org.lwjgl.util.mapped
Class MappedObject

java.lang.Object
  org.lwjgl.util.mapped.MappedObject

public abstract class MappedObject
extends java.lang.Object

Base superclass of all mapped objects. Classes that require data mapping should extend this class and registered with MappedObjectTransformer.register(Class).

Subclasses may only specify the default constructor. Any code inside that constructor is optional, but will not run when the view is instantiated, see runViewConstructor().

Bounds checking may be enabled through a JVM system property: org.lwjgl.util.mapped.Checks=true

Author:

Riven

Field Summary

long	baseAddress The mapped object base memory address, in bytes.
static int	SIZEOF Holds the value of sizeof of the sub-type of this MappedObject The behavior of this (transformed) method does not follow the normal Java behavior. Vec2.SIZEOF will yield 8 (2 floats) Vec3.SIZEOF will yield 12 (3 floats) This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access"). Using Java 5.0's static-import on this method will break functionality.
int	view The mapped object view offset, in elements.
long	viewAddress The mapped object view memory address, in bytes.

Constructor Summary

protected

MappedObject()

Method Summary

<T extends MappedObject> T[]	asArray()
java.nio.ByteBuffer	backingByteBuffer() Returns the ByteBuffer that backs this mapped object.
int	capacity() Returns the number of mapped objects that fit in the mapped buffer.
<T extends MappedObject> void	copyRange(T target, int instances) Copies and amount of SIZEOF * instances bytes, from the current mapped object, to the specified mapped object.
<T extends MappedObject> void	copyTo(T target) Copies and amount of SIZEOF - padding bytes, from the current mapped object, to the specified mapped object.
<T extends MappedObject> T	dup() Creates an identical new MappedObject instance, comparable to the contract of ByteBuffer.duplicate().
static <T extends MappedObject> java.lang.Iterable<T>	foreach(T mapped) Creates an Iterable that will step through capacity() views, leaving the view at the last valid value. For convenience you are encouraged to static-import this specific method: import static org.lwjgl.util.mapped.MappedObject.foreach;
static <T extends MappedObject> java.lang.Iterable<T>	foreach(T mapped, int elementCount) Creates an Iterable that will step through elementCount views, leaving the view at the last valid value. For convenience you are encouraged to static-import this specific method: import static org.lwjgl.util.mapped.MappedObject.foreach;
int	getAlign() Returns the mapped object memory alignment, in bytes.
int	getSizeof() Returns the mapped object memory sizeof, in bytes.
protected long	getViewAddress(int view)
static <T extends MappedObject> T	malloc(int elementCount) Creates a MappedObject instance, mapping the memory region of an allocated direct ByteBuffer with a capacity of elementCount*SIZEOF The behavior of this (transformed) method does not follow the normal Java behavior. Vec2.malloc(int) will return a mapped Vec2 instance. Vec3.malloc(int) will return a mapped Vec3 instance. This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access"). Using Java 5.0's static-import on this method will break functionality.
static <T extends MappedObject> T	map(java.nio.ByteBuffer bb) Creates a MappedObject instance, mapping the memory region of the specified direct ByteBuffer.
static <T extends MappedObject> T	map(long address, int capacity) Creates a MappedObject instance, mapping the memory region specified.
void	next() Moves the current view to the next element.
void	runViewConstructor() Any code in the default constructor will not run automatically.
void	setViewAddress(long address)
<T extends MappedObject> T	slice() Creates a new MappedObject instance, with a base offset equal to the offset of the current view, comparable to the contract of ByteBuffer.slice().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

baseAddress

public long baseAddress

The mapped object base memory address, in bytes. Read-only.

viewAddress

public long viewAddress

The mapped object view memory address, in bytes. Read-only.

SIZEOF

public static int SIZEOF

Holds the value of sizeof of the sub-type of this MappedObject

The behavior of this (transformed) method does not follow the normal Java behavior.
Vec2.SIZEOF will yield 8 (2 floats)
Vec3.SIZEOF will yield 12 (3 floats)
This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access").
Using Java 5.0's static-import on this method will break functionality.

view

public int view

The mapped object view offset, in elements. Read/write. This is a virtual field, used as a convenient getter/setter for viewAddress.

Constructor Detail

MappedObject

protected MappedObject()

Method Detail

getViewAddress

protected final long getViewAddress(int view)

setViewAddress

public final void setViewAddress(long address)

getAlign

public final int getAlign()

Returns the mapped object memory alignment, in bytes.

Returns:

the memory alignment

getSizeof

public final int getSizeof()

Returns the mapped object memory sizeof, in bytes.

Returns:

the sizeof value

capacity

public final int capacity()

Returns the number of mapped objects that fit in the mapped buffer.

Returns:

the mapped object capacity

map

public static <T extends MappedObject> T map(java.nio.ByteBuffer bb)

Creates a MappedObject instance, mapping the memory region of the specified direct ByteBuffer.

The behavior of this (transformed) method does not follow the normal Java behavior.
Vec2.map(buffer) will return a mapped Vec2 instance.
Vec3.map(buffer) will return a mapped Vec3 instance.
This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access").
Using Java 5.0's static-import on this method will break functionality.

map

public static <T extends MappedObject> T map(long address,
                                             int capacity)

Creates a MappedObject instance, mapping the memory region specified. This is useful for mapping arbitrary regions in memory, e.g. OpenCL CLMem objects, without creating a ByteBuffer first.

The behavior of this (transformed) method does not follow the normal Java behavior.
Vec2.map(buffer) will return a mapped Vec2 instance.
Vec3.map(buffer) will return a mapped Vec3 instance.
This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access").
Using Java 5.0's static-import on this method will break functionality.

malloc

public static <T extends MappedObject> T malloc(int elementCount)

Creates a MappedObject instance, mapping the memory region of an allocated direct ByteBuffer with a capacity of elementCount*SIZEOF

The behavior of this (transformed) method does not follow the normal Java behavior.
Vec2.malloc(int) will return a mapped Vec2 instance.
Vec3.malloc(int) will return a mapped Vec3 instance.
This (required) notation might cause compiler warnings, which can be suppressed with @SuppressWarnings("static-access").
Using Java 5.0's static-import on this method will break functionality.

dup

public final <T extends MappedObject> T dup()

Creates an identical new MappedObject instance, comparable to the contract of ByteBuffer.duplicate(). This is useful when more than one views of the mapped object are required at the same time, e.g. in multithreaded access.

slice

public final <T extends MappedObject> T slice()

Creates a new MappedObject instance, with a base offset equal to the offset of the current view, comparable to the contract of ByteBuffer.slice().

runViewConstructor

public final void runViewConstructor()

Any code in the default constructor will not run automatically. This method can be used to execute that code on the current view.

next

public final void next()

Moves the current view to the next element.

copyTo

public final <T extends MappedObject> void copyTo(T target)

Copies and amount of SIZEOF - padding bytes, from the current mapped object, to the specified mapped object.

copyRange

public final <T extends MappedObject> void copyRange(T target,
                                                     int instances)

Copies and amount of SIZEOF * instances bytes, from the current mapped object, to the specified mapped object. Note that this includes any padding bytes that are part of SIZEOF.

foreach

public static <T extends MappedObject> java.lang.Iterable<T> foreach(T mapped)

Creates an Iterable that will step through capacity() views, leaving the view at the last valid value.

For convenience you are encouraged to static-import this specific method: import static org.lwjgl.util.mapped.MappedObject.foreach;

foreach

public static <T extends MappedObject> java.lang.Iterable<T> foreach(T mapped,
                                                                     int elementCount)

Creates an Iterable that will step through elementCount views, leaving the view at the last valid value.

For convenience you are encouraged to static-import this specific method: import static org.lwjgl.util.mapped.MappedObject.foreach;

asArray

public final <T extends MappedObject> T[] asArray()

backingByteBuffer

public final java.nio.ByteBuffer backingByteBuffer()

Returns the ByteBuffer that backs this mapped object.

Returns:

the backing buffer