SoCpuBufferObject Class Reference

CPU buffer object class More...

#include <Inventor/devices/SoCpuBufferObject.h>

Inheritance diagram for SoCpuBufferObject:

Public Member Functions
	SoCpuBufferObject ()
	Default constructor.
	SoCpuBufferObject (void *buffer, size_t size)
	Constructor that takes an existing block of CPU memory.
void	setBuffer (void *buffer, size_t size)
	Request that the buffer object manage an existing block of memory.
virtual SoBufferObject *	createInstance () const
	Create a new buffer with the same properties as the current one.
virtual void	clearInstance ()
	This function clears the content of the buffer, it frees the memory if the mode was COPY.
Public Member Functions inherited from SoBufferObject
void	lockBuffer ()
	Locks the buffer against concurrent calls from different threads.
void	unlockBuffer ()
	Unlocks the buffer object.
virtual bool	setSize (size_t size)
	Sets the size in bytes of the buffer object.
virtual size_t	getSize () const
	Returns the size, in bytes, of the buffer object.
virtual void *	map (AccessMode accessMode, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
	Map the buffer to a system memory address and allows the mapping of a sub part of the buffer object into CPU memory.
virtual void	unmap ()
	Unmaps the buffer from CPU address space.
virtual void	map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
	Maps the current buffer object into the specified buffer object.
virtual void	unmap (SoBufferObject *bufferObject)
	Unmap this buffer from the specified buffer object.
virtual void	memcpy (SoBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
	Copies data from the specified buffer object into this buffer object.
virtual void	memset (void *value, size_t valueSize=1, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
	This function sets the contents of (or a portion of) this buffer object to the specified value.
SoDeviceContext *	getContext () const
	Returns the device context where this buffer is valid.
SoBufferObject *	getMappedBufferObject () const
	Returns a pointer to the buffer object which is mapped by the actual object.
AccessMode	getMappedBufferObjectAccessMode ()
	Returns the access mode used for the buffer mapping.
size_t	getMappedBufferObjectPosition () const
	Returns the position in the source buffer mapped in this buffer.
size_t	getMappedBufferObjectSize () const
	Returns the size of the mapped area in bytes.
Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.
void	unref () const
	Removes a reference from an instance.
void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
int	getRefCount () const
	Returns current reference count.
void	lock () const
	lock this instance.
void	unlock () const
	unlock this instance.
Public Member Functions inherited from SoTypedObject
virtual SoType	getTypeId () const =0
	Returns the type identifier for a specific instance.
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.
template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Additional Inherited Members
Public Types inherited from SoBufferObject
enum	AccessMode {   READ_ONLY ,   SET ,   READ_WRITE }
	This enum provides the possible access modes for a mapped buffer object. More...
Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
Related Symbols inherited from SoBufferObject
#define	SO_BUFFER_SIZE_ALL   ((std::numeric_limits<size_t>::max)())
	Used to indicate that we want to use the whole buffer.

Detailed Description

CPU buffer object class

This class provides management functions for CPU memory buffers.

By default memory allocations have the maximum possible alignment to allow use with (for example) SSE instructions.

Memory is managed using the new/delete operators. On Microsoft Windows platforms it is possible to use VirtualAlloc/VirtualFree instead by setting OIV_BUFFER_USE_VIRTUAL_ALLOC (see SoPreferences).

See SoBufferObject for general information about buffer objects.

See SoBufferedShape for an example of storing vertices in a CPU buffer.

NOTE:
SoBufferObject classes are reference counted objects (just like nodes, paths, etc). Therefore you cannot create an SoBufferObject on the stack. And to delete an SoBufferObject you must ref and unref the object. The SoRef smart pointer is a safe and convenient way to create buffer objects. See examples in SoBufferObject.

EXAMPLE

Load data into a buffer object from an array in memory:

const float vertices[][3] = {
     1,0.5,0, 0,1,0, -1,0.5,0,
    -1,-1,0, 1,-1,0, 1,0,0, -1,0,0,
    -1,-1.5,0, 1,-1.5,0
};
const int NUM_COORDS = sizeof(vertices) / sizeof(SbVec3f);

Wrap coordinate array in a CPU buffer object:

SoRef<SoCpuBufferObject> vertBuf = 
    new SoCpuBufferObject( (void*)vertices, NUM_COORDS * sizeof(SbVec3f) );

Or allocate memory and copy data into buffer:

SoRef<SoCpuBufferObject> vertBuf = new SoCpuBufferObject();
vertBuf->setSize( NUM_COORDS * sizeof(SbVec3f) );
SbVec3f* vertPtr = (SbVec3f*)vertBuf->map( SoBufferObject::SET );
    memcpy( vertPtr, vertices, NUM_COORDS * sizeof(SbVec3f) );
vertBuf->unmap();

EXAMPLE

Access data stored in a buffer object.

unsigned char* data  = (unsigned char*)cpuBuffer->map( SoBufferObject::READ_ONLY );
unsigned char  value = data[0];
    . . .
cpuBuffer->unmap();

SEE ALSO

SoGLBufferObject

Definition at line 150 of file SoCpuBufferObject.h.

Constructor & Destructor Documentation

SoCpuBufferObject() [1/2]

SoCpuBufferObject::SoCpuBufferObject

(

)

Default constructor.

The contents of the buffer are initially empty.

SoCpuBufferObject() [2/2]

SoCpuBufferObject::SoCpuBufferObject	(	void *	buffer,
		size_t	size
	)

Constructor that takes an existing block of CPU memory.

This memory is owned, and should be freed by, the application.

Parameters

buffer	Pointer to the buffer to manage.
size	Size of buffer in bytes.

Member Function Documentation

clearInstance()

virtual void SoCpuBufferObject::clearInstance ( )

virtual

This function clears the content of the buffer, it frees the memory if the mode was COPY.

Implements SoBufferObject.

createInstance()

virtual SoBufferObject * SoCpuBufferObject::createInstance ( ) const

virtual

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.

Implements SoBufferObject.

Reimplemented in SoCpuBufferBitSet.

setBuffer()

void SoCpuBufferObject::setBuffer	(	void *	buffer,
		size_t	size
	)

Request that the buffer object manage an existing block of memory.

The application still owns this memory and is responsible for releasing the memory (when no SoCpuBufferObjects have a reference on it).

We recommend to use the most aligned memory pointer possible to enable optimized algorithm usage.

NOTE: If another buffer object is currently mapped into another buffer, the other buffer is automatically unmapped and its contents are undefined.

---

The documentation for this class was generated from the following file:

• Inventor/devices/SoCpuBufferObject.h