Class SoBufferObject
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.devices.SoBufferObject
-
- All Implemented Interfaces:
SafeDisposable
- Direct Known Subclasses:
SoCpuBufferObject
,SoGpuBufferObject
,SoInteropBufferObject
public abstract class SoBufferObject extends Inventor implements SafeDisposable
Abstract base class for buffer object management. This class provides generic functions to manage buffer objects.There are specific implementations of this class for buffer objects on each type of device:
SoCpuBufferObject
: A buffer in CPU system memory.SoGpuBufferObject
: A buffer in GPU memory.SoGLBufferObject
: A buffer in GPU memory managed through the OpenGL API.
In many cases the abstract
SoBufferObject
methods allow the application to handle buffer objects without knowing the specific type of the buffer. This is very convenient when computation is implemented on multiple devices.Since version 8.0, some Open Inventor classes take or return data using an
SoBufferObject
(or derived class). For example texture images (seeSoSFImage
), geometry data (seeSoBufferedShape
) and tiles of volume data (seeSoLDMDataAccess
).Creating a buffer object
Before creating a non-CPU buffer object you must bind (then unbind) a valid context for the target device. For example, to create a GPU buffer object (
Allocating memory in a buffer object:SoGpuBufferObject
) you can bind the viewer's context using methods in the view class or you can use the classSoGLContext
. See the example on the SoGpuBuffer page. For an existing buffer object you can use the buffer's bind()/unbind() methods or get a valid context to bind using thegetContext() method. Binding this context is necessary before changing buffer properties or callingsetSize()
,memcpy()
, memset(), etc.
Use the
Loading data and retrieving data:setSize()
method to allocate memory in a buffer object. (Note that you must bind a valid context before calling this method on non-CPU buffer objects.) Generally buffer objects have zero size when created. However some buffer object classes have a constructor that takes an existing block of memory as a parameter. In that case the initial size is non-zero. You must allocate memory before copying data into a buffer object using either thememcpy()
method or a direct reference . Memory is automatically allocated, if necessary, when a buffer object is mapped into another buffer object.
- Some buffer objects, e.g.
SoCpuBufferObject
, have a constructor that takes an existing block of memory as a parameter. In this case the buffer object is automatically set to the necessary size to contain the specified data. Creating an SoCpuBufferObect that "wraps" the existing data is usually the first step in loading data into a non-CPU buffer usingmemcpy()
ormap()
. - The
memcpy()
methods copy data into a buffer object from another buffer object. For example to copy data into an OpenGL buffer from a CPU buffer. Before using these methods on a non-CPU buffer object, you must bind (then unbind) a valid context for the target device. The buffer object must be large enough (have enough memory allocated) to hold the data. See the allocating memory topic above. - The memset() methods fill a buffer object with a specified value. Before using these methods on a non-CPU buffer object, you must bind (then unbind) a valid context for the target device. The buffer object must be large enough (have enough memory allocated) to hold the data. See the allocating memory topic above.
- The
map()
methods that have a buffer object parameter "map" one buffer object into another, usually to allow the data to be accessed on a different device. When the access mode is READ_ONLY or READ_WRITE, the contents of the source buffer are available through the target buffer object after themap()
call. If necessary, Open Inventor will automatically do an inter-device transfer of the data. When the access mode is SET or READ_WRITE, the contents of the modified target buffer object are available through the source buffer object after theunmap()
call. If necessary, Open Inventor will automatically do an inter-device data transfer. - Some buffer object classes provide a
map()
method that maps the buffer's data into CPU memory and returns a reference. If necessary, Open Inventor will automatically do an inter-device transfer of the data. While the buffer is mapped the application can directly modify its data using the returned reference. If the access mode is SET or READ_WRITE, the modified data will be available through the buffer object after theunmap()
call. If necessary, Open Inventor will automatically do an inter-device data transfer.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SoBufferObject.AccessModes
This enum provides the possible access modes for a mapped buffer object.-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
-
Field Summary
Fields Modifier and Type Field Description static long
SO_BUFFER_SIZE_ALL
Used to indicate that we want to use the whole buffer.-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clearInstance()
Free the memory allocated by the buffer object.SoBufferObject
createInstance()
Create a new buffer with the same properties as the current one.boolean
dispose()
Explicitly call this method to force object to dispose its unmanaged resources.static SoCpuBufferObjectCache
getBufferObjectCache()
Returns the cache manager object.SoDeviceContext
getContext()
Returns the device context where this buffer is valid.SoBufferObject
getMappedBufferObject()
Returns a pointer to the buffer object which is mapped by the actual object.SoBufferObject.AccessModes
getMappedBufferObjectAccessMode()
Returns the access mode used for the buffer mapping.long
getMappedBufferObjectPosition()
Returns the position in the source buffer mapped in this buffer.long
getMappedBufferObjectSize()
Returns the size of the mapped area in bytes.long
getSize()
Returns the size, in bytes, of the buffer object.boolean
isDisposable()
Returns a boolean flag which indicates if it is safe to callSafeDisposable.dispose()
on the object.void
lockBuffer()
Locks the buffer against concurrent calls from different threads.java.nio.ByteBuffer
map(SoBufferObject.AccessModes accessMode)
Calls map(accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).java.nio.ByteBuffer
map(SoBufferObject.AccessModes accessMode, long offset)
Calls map(accessMode, offset, (long)SO_BUFFER_SIZE_ALL).java.nio.ByteBuffer
map(SoBufferObject.AccessModes accessMode, long offset, long count)
Map the buffer to a system memory address and allows the mapping of a sub part of the buffer object into CPU memory.void
map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode)
Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).void
map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition)
Calls map(targetBufferObject, accessMode, startPosition, (long)SO_BUFFER_SIZE_ALL).void
map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition, long mappingSize)
Maps the current buffer object into the specified buffer object.void
memcpy(SoBufferObject sourceBufferObject)
Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).void
memcpy(SoBufferObject sourceBufferObject, long destOffset)
Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).void
memcpy(SoBufferObject sourceBufferObject, long destOffset, long sourceOffset)
Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (long)SO_BUFFER_SIZE_ALL).void
memcpy(SoBufferObject sourceBufferObject, long destOffset, long sourceOffset, long copySize)
Copies data from the specified buffer object into this buffer object.boolean
setSize(long size)
Sets the size in bytes of the buffer object.void
unlockBuffer()
Unlocks the buffer object.void
unmap()
Unmaps the buffer from CPU address space.void
unmap(SoBufferObject bufferObject)
Unmap this buffer from the specified buffer object.-
Methods inherited from class com.openinventor.inventor.Inventor
getNativeResourceHandle
-
-
-
-
Field Detail
-
SO_BUFFER_SIZE_ALL
public static final long SO_BUFFER_SIZE_ALL
Used to indicate that we want to use the whole buffer.- See Also:
- Constant Field Values
-
-
Method Detail
-
map
public java.nio.ByteBuffer map(SoBufferObject.AccessModes accessMode, long offset)
Calls map(accessMode, offset, (long)SO_BUFFER_SIZE_ALL).
-
map
public void map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode)
Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).
-
dispose
public boolean dispose()
Description copied from class:Inventor
Explicitly call this method to force object to dispose its unmanaged resources. The object may not be reused in the application code after this call.- Specified by:
dispose
in interfaceSafeDisposable
- Overrides:
dispose
in classInventor
- Returns:
true
if this object native resources were successfully disposed;false
if it was already disposed or no native resources has been registered for this object.
-
map
public java.nio.ByteBuffer map(SoBufferObject.AccessModes accessMode)
Calls map(accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).
-
map
public void map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition)
Calls map(targetBufferObject, accessMode, startPosition, (long)SO_BUFFER_SIZE_ALL).
-
memcpy
public void memcpy(SoBufferObject sourceBufferObject, long destOffset, long sourceOffset)
Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (long)SO_BUFFER_SIZE_ALL).
-
isDisposable
public boolean isDisposable()
Description copied from interface:SafeDisposable
Returns a boolean flag which indicates if it is safe to callSafeDisposable.dispose()
on the object.- Specified by:
isDisposable
in interfaceSafeDisposable
- Returns:
true
if the object can be disposed in a safe manner
-
memcpy
public void memcpy(SoBufferObject sourceBufferObject)
Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).
-
memcpy
public void memcpy(SoBufferObject sourceBufferObject, long destOffset)
Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).
-
map
public java.nio.ByteBuffer map(SoBufferObject.AccessModes accessMode, long offset, long count)
Map the buffer to a system memory address and allows the mapping of a sub part of the buffer object into CPU memory. Notes:- The
unmap()
method must be called before using the buffer.
- Returns:
- Reference to data in the mapped region of the buffer memory.
- The
-
unmap
public void unmap()
Unmaps the buffer from CPU address space.
-
map
public void map(SoBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition, long mappingSize)
Maps the current buffer object into the specified buffer object.
This is useful in order to use a buffer in multiple contexts. The default is to map the entire contents of this buffer, but it is also possible to map a subset of this buffer's memory using the startPosition and mappingSize parameters.A source buffer may be mapped into multiple target buffers. However a target buffer can only be mapped from one source buffer at a time. If a different source buffer is currently mapped into the target buffer, it is automatically unmapped and may be left in an undefined state.
Note: If the current buffer is empty or startPosition is beyond the end of the managed memory, the buffer is not mapped (and an error message is issued in debug builds).
- Parameters:
targetBufferObject
- The buffer object which will be the mapped version of this buffer.accessMode
- The access mode used for the mapping.startPosition
- Offset (in bytes) in source buffer to map from (default is start of buffer).mappingSize
- Size (in bytes) from the startPosition, if SO_BUFFER_SIZE_ALL then the whole buffer is mapped.
-
getSize
public long getSize()
Returns the size, in bytes, of the buffer object.- Returns:
- The size in bytes of the buffer object.
-
lockBuffer
public void lockBuffer()
Locks the buffer against concurrent calls from different threads.
This is a blocking call. In other words it will not return immediately if another thread currently has the buffer locked.
-
getBufferObjectCache
public static SoCpuBufferObjectCache getBufferObjectCache()
Returns the cache manager object. This object manages a cache ofSoCpuBufferObject
objects.SoBufferObject
creates an instance of this class that is primarily used for the LDM tile cache (seeSoLDMGlobalResourceParameters
for more information). The buffer object cache can be accessed using theSoBufferObject
static method getBufferObjectCache. Default size is 50 or the value of OIV_BUFFER_OBJECT_CACHE_SIZE.
-
setSize
public boolean setSize(long size)
Sets the size in bytes of the buffer object.
If the requested size is the same as the current size, this method does nothing and returns true. If there is existing memory that is owned by the buffer object, that memory is released. If the requested size is zero, the buffer object is now empty.
- Parameters:
size
- The requested size in bytes.- Returns:
- true if the operation was successful.
-
unlockBuffer
public void unlockBuffer()
Unlocks the buffer object.
If a thread callslockBuffer()
then it must callunlockBuffer()
to allow other threads to lock the buffer.
-
unmap
public void unmap(SoBufferObject bufferObject)
Unmap this buffer from the specified buffer object.
In other words, remove the specified target buffer from the list of buffers which this buffer is mapped to. If the access mode supports writing, the specified buffer is sync'd with the current buffer. An error is reported (in debug builds) if the buffer is not mapped to the specified buffer- Parameters:
bufferObject
- Buffer to be unmapped.
-
getMappedBufferObjectAccessMode
public SoBufferObject.AccessModes getMappedBufferObjectAccessMode()
Returns the access mode used for the buffer mapping.
-
getMappedBufferObject
public SoBufferObject getMappedBufferObject()
Returns a pointer to the buffer object which is mapped by the actual object.
-
getMappedBufferObjectSize
public long getMappedBufferObjectSize()
Returns the size of the mapped area in bytes.- Returns:
- The size of the mapped area.
-
getMappedBufferObjectPosition
public long getMappedBufferObjectPosition()
Returns the position in the source buffer mapped in this buffer.- Returns:
- Returns a position in bytes.
-
createInstance
public SoBufferObject createInstance()
Create a new buffer with the same properties as the current one.
The new instance will have the same context or device properties, but no memory is allocated.
-
memcpy
public void memcpy(SoBufferObject sourceBufferObject, long destOffset, long sourceOffset, long copySize)
Copies data from the specified buffer object into this buffer object.
If the size or the offset are not valid an error is reported (SoDebugError
). This buffer is not resized, if it is too small an error is reported.Warning Source and destination overlaping support is implementation dependent, if not supported an error is reported.
- Parameters:
sourceBufferObject
- The buffer object to be copied.destOffset
- The starting offset in the destination buffer object, useful for data subsets.sourceOffset
- The starting offset in the source buffer object, useful for data subsets.copySize
- The number of bytes to copy from the source buffer object (SO_BUFFER_SIZE_ALL means all).
-
getContext
public SoDeviceContext getContext()
Returns the device context where this buffer is valid.- Returns:
- A device context.
-
clearInstance
public void clearInstance()
Free the memory allocated by the buffer object.
-
-