SoBufferObject

java.lang.Object
- com.openinventor.inventor.Inventor
- - com.openinventor.inventor.devices.SoBufferObject

All Implemented Interfaces:

SafeDisposable

Direct Known Subclasses:

SoCpuBufferObject, SoGLBufferObject
```
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.
- SoGLBufferObject: A buffer in GPU memory managed through the OpenGL API.
- SoCudaBufferObject: A buffer in GPU memory managed through Nvidia's CUDA API.
- SoOpenCLBufferObject: A buffer (usually) in GPU memory managed through the OpenCL 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. For example if computation is done using CUDA when available, but using the CPU when a CUDA device is not available.
Since version 8.0, some Open Inventor classes take or return data using an SoBufferObject (or derived class). For example texture images (see SoSFImage), geometry data (see SoBufferedShape) and tiles of volume data (see SoLDMDataAccess).
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 an OpenGL buffer object SoGLBufferObject) you can bind the viewer's context using methods in the view class or you can use the class SoGLContext. See the example on the SoGLBuffer 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 calling setSize(), memcpy(), memset(), etc. Allocating memory in a buffer object:

Use the 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 the memcpy() method or a direct reference . Memory is automatically allocated, if necessary, when a buffer object is mapped into another buffer object. Loading data and retrieving data:
- 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 using memcpy() or map().
- 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 the map() 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 the unmap() 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 the unmap() call. If necessary, Open Inventor will automatically do an inter-device data transfer.
See also:
SoCpuBufferObject, SoGLBufferObject, SoCudaBufferObject, SoOpenCLBufferObject
SoCpuDevice, SoCudaDevice, SoGLDevice, SoOpenCLDevice

Nested Class Summary

Nested Classes
Modifier and Type Class and 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

Nested Classes
Modifier and Type	Class and Description
`static class`	`SoBufferObject.AccessModes` This enum provides the possible access modes for a mapped buffer object.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`READ_ONLY` Deprecated. Use `SoBufferObject.AccessModes.READ_ONLY` instead.
`static int`	`READ_WRITE` Deprecated. Use `SoBufferObject.AccessModes.READ_WRITE` instead.
`static int`	`SET` Deprecated. Use `SoBufferObject.AccessModes.SET` instead.
`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 and 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`	`getMappingAccessMode()` Returns the access mode used for the buffer mapping.
`long`	`getMappingSize()` Returns the size of the mapped area in bytes.
`long`	`getMappingStartPosition()` Returns the position in the source buffer mapped in this buffer.
`long`	`getSize()` Returns the size, in bytes, of the buffer object.
`boolean`	`isDisposable()` Returns a boolean flag which indicates if it is safe to call `SafeDisposable.dispose()` on the object.
`void`	`lockBuffer()` Locks the buffer against concurrent calls from different threads.
`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`	`map(SoCpuBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode)` Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).
`void`	`map(SoCpuBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition)` Calls map(targetBufferObject, accessMode, startPosition, (long)SO_BUFFER_SIZE_ALL).
`void`	`map(SoCpuBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition, long mappingSize)` Maps the current buffer object into the specified CPU 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.
`void`	`memcpy(SoCpuBufferObject sourceBufferObject)` Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).
`void`	`memcpy(SoCpuBufferObject sourceBufferObject, long destOffset)` Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).
`void`	`memcpy(SoCpuBufferObject sourceBufferObject, long destOffset, long sourceOffset)` Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (long)SO_BUFFER_SIZE_ALL).
`void`	`memcpy(SoCpuBufferObject sourceBufferObject, long destOffset, long sourceOffset, long copySize)` Copies data from the specified CPU buffer object into this buffer object.
`void`	`setMappedBufferObject(SoBufferObject bufferObject)` This function is used when the instance of buffer object is used to map a buffer.
`void`	`setMappingAccessMode(SoBufferObject.AccessModes accessMode)` Sets the mapping mode used for the mapping of a buffer object.
`void`	`setMappingZoneInformation(long startPosition, long size)` Stores information about the mapping in order to know the subset of the data mapped in the buffer.
`boolean`	`setSize(long size)` Sets the size in bytes of the buffer object.
`void`	`unlockBuffer()` Unlocks the buffer object.
`void`	`unmap(SoBufferObject bufferObject)` Remove the specified bufferObject from the list of buffers which map the current buffer.
`void`	`unmap(SoCpuBufferObject bufferObject)` Unmap the specified CPU buffer.

Methods inherited from class com.openinventor.inventor.Inventor
getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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
  - READ_ONLY
```
@Deprecated
public static final int READ_ONLY
```
    Deprecated. Use SoBufferObject.AccessModes.READ_ONLY instead.
  - SET
```
@Deprecated
public static final int SET
```
    Deprecated. Use SoBufferObject.AccessModes.SET instead.
  - READ_WRITE
```
@Deprecated
public static final int READ_WRITE
```
    Deprecated. Use SoBufferObject.AccessModes.READ_WRITE instead.
- Method Detail
  - memcpy
```
public void memcpy(SoCpuBufferObject sourceBufferObject,
                   long destOffset,
                   long sourceOffset)
```
    Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (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).
  - map
```
public void map(SoCpuBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode,
                long startPosition)
```
    Calls map(targetBufferObject, accessMode, startPosition, (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 call SafeDisposable.dispose() on the object.
    
    Specified by:
    
    isDisposable in interface SafeDisposable
    
    Returns:
    
    true if the object can be disposed in a safe manner
  - 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 interface SafeDisposable
    
    Overrides:
    
    dispose in class Inventor
    
    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.
  - memcpy
```
public void memcpy(SoBufferObject sourceBufferObject,
                   long destOffset)
```
    Calls memcpy(sourceBufferObject, destOffset, (long)0, (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).
  - memcpy
```
public void memcpy(SoCpuBufferObject sourceBufferObject)
```
    Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).
  - memcpy
```
public void memcpy(SoBufferObject sourceBufferObject)
```
    Calls memcpy(sourceBufferObject, (long)0, (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).
  - map
```
public void map(SoCpuBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode)
```
    Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).
  - memcpy
```
public void memcpy(SoCpuBufferObject sourceBufferObject,
                   long destOffset)
```
    Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).
  - setMappingZoneInformation
```
public void setMappingZoneInformation(long startPosition,
                                      long size)
```
    Stores information about the mapping in order to know the subset of the data mapped in the buffer.
  - 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.
  - getMappingStartPosition
```
public long getMappingStartPosition()
```
    Returns the position in the source buffer mapped in this buffer.
    
    Returns:
    
    Returns a position in bytes.
  - memcpy
```
public void memcpy(SoCpuBufferObject sourceBufferObject,
                   long destOffset,
                   long sourceOffset,
                   long copySize)
```
    Copies data from the specified CPU buffer object into this buffer object.
    
    See the general memcpy method for more information.
  - getContext
```
public SoDeviceContext getContext()
```
    Returns the device context where this buffer is valid.
    
    Returns:
    
    A device context.
  - setMappedBufferObject
```
public void setMappedBufferObject(SoBufferObject bufferObject)
```
    This function is used when the instance of buffer object is used to map a buffer. It stores the pointer on the buffer which is mapped by *this*.
    
    Parameters:
    
    bufferObject - The buffer object which is mapped.
  - getMappedBufferObject
```
public SoBufferObject getMappedBufferObject()
```
    Returns a pointer to the buffer object which is mapped by the actual object.
  - getMappingAccessMode
```
public SoBufferObject.AccessModes getMappingAccessMode()
```
    Returns the access mode used for the buffer mapping.
  - clearInstance
```
public void clearInstance()
```
    Free the memory allocated by the buffer object.
  - setMappingAccessMode
```
public void setMappingAccessMode(SoBufferObject.AccessModes accessMode)
```
    Sets the mapping mode used for the mapping of a buffer object.
    
    Parameters:
    
    accessMode - The accessMode used for the mapping.
  - map
```
public void map(SoCpuBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode,
                long startPosition,
                long mappingSize)
```
    Maps the current buffer object into the specified CPU buffer object.
    
    See the general map method for more information.
  - map
```
public void map(SoBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode,
                long startPosition,
                long mappingSize)
```
    Maps the current buffer object into the specified buffer object.
    It is useful in order to use a buffer in multiple contexts (e.g. OpenGL and CUDA).
    
    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 source buffer to map from (default is start of buffer).
    
    mappingSize - Number of bytes from the startPosition to map (default is SO_BUFFER_SIZE_ALL meaning the whole buffer is mapped.
  - unmap
```
public void unmap(SoBufferObject bufferObject)
```
    Remove the specified bufferObject from the list of buffers which map the current buffer. If the access mode supports writing the specified buffer is sync'd with the buffer.
    
    Parameters:
    
    bufferObject - Buffer to be unmapped.
  - unmap
```
public void unmap(SoCpuBufferObject bufferObject)
```
    Unmap the specified CPU buffer.
    
    See the general unmap method for more information.
  - getBufferObjectCache
```
public static SoCpuBufferObjectCache getBufferObjectCache()
```
    Returns the cache manager object. This object manages a cache of SoCpuBufferObject objects. SoBufferObject creates an instance of this class that is primarily used for the LDM tile cache (see SoLDMGlobalResourceParameters for more information). The buffer object cache can be accessed using the SoBufferObject static method getBufferObjectCache. Default size is 50 or the value of OIV_BUFFER_OBJECT_CACHE_SIZE.
  - getSize
```
public long getSize()
```
    Returns the size, in bytes, of the buffer object.
    
    Returns:
    
    The size in bytes of the buffer object.
  - 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).
  - getMappingSize
```
public long getMappingSize()
```
    Returns the size of the mapped area in bytes.
    
    Returns:
    
    The size of the mapped area.
  - 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.
  - setSize
```
public boolean setSize(long size)
```
    Sets the size in bytes of the buffer object.
    
    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 calls lockBuffer() then it must call unlockBuffer() to allow other threads to lock the buffer.

Class SoBufferObject

Nested Class Summary

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Field Summary

Fields inherited from class com.openinventor.inventor.Inventor

Method Summary

Methods inherited from class com.openinventor.inventor.Inventor

Methods inherited from class java.lang.Object

Field Detail

SO_BUFFER_SIZE_ALL

READ_ONLY

SET

READ_WRITE

Method Detail

memcpy

map

map

isDisposable

dispose

memcpy

memcpy

memcpy

memcpy

map

map

memcpy

setMappingZoneInformation

createInstance

getMappingStartPosition

memcpy

getContext

setMappedBufferObject

getMappedBufferObject

getMappingAccessMode

clearInstance

setMappingAccessMode

map

map

unmap

unmap

getBufferObjectCache

getSize

memcpy

getMappingSize

lockBuffer

setSize

unlockBuffer