SoCpuBufferObject Class Reference
[CPU device]

CPU buffer object class More...

#include <Inventor/devices/SoCpuBufferObject.h>

Inheritance diagram for SoCpuBufferObject:

Public Member Functions
	SoCpuBufferObject ()
	SoCpuBufferObject (void *buffer, size_t size)
virtual void	map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void	unmap (SoBufferObject *bufferObject)
virtual void *	map (AccessMode accessMode)
virtual void	unmap ()
virtual void	memcpy (SoBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
virtual void	memset (void *value, size_t valueSize=1, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
virtual bool	setSize (size_t size)
virtual SoBufferObject *	createInstance () const
virtual void	clearInstance ()
void	setBuffer (void *buffer, size_t size)
virtual void	map (SoCpuBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void	unmap (SoCpuBufferObject *bufferObject)
virtual void	memcpy (SoCpuBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
virtual void	memcpy (SoGLBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
virtual void	map (SoGLBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void	unmap (SoGLBufferObject *bufferObject)
Friends
class	SoGLBufferObject

Detailed Description

CPU buffer object class

This class provides management functions for CPU memory buffers.

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

   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

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

Constructor & Destructor Documentation

SoCpuBufferObject::SoCpuBufferObject ( )

Default constructor.

The contents of the buffer are initially empty.

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

virtual void SoCpuBufferObject::clearInstance ( ) [virtual]

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

Implements SoBufferObject.

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.

virtual void SoCpuBufferObject::map	(	SoGLBufferObject *	targetBufferObject,
		AccessMode	accessMode,
		size_t	startPosition = `0`,
		size_t	mappingSize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Map the current buffer object into the specified GL buffer object.

This is an optimized implementation. See the general map() method for more information.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::map	(	SoCpuBufferObject *	targetBufferObject,
		AccessMode	accessMode,
		size_t	startPosition = `0`,
		size_t	mappingSize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Map the current buffer object into the specified CPU buffer object.

This is an optimized implementation. See the general map() method for more information.

Implements SoBufferObject.

virtual void* SoCpuBufferObject::map ( AccessMode accessMode ) [virtual]

Map the buffer to a system memory address.

Returns:: a pointer to the memory managed by this cpu buffer. Returns NULL if empty.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::map	(	SoBufferObject *	targetBufferObject,
		AccessMode	accessMode,
		size_t	startPosition = `0`,
		size_t	mappingSize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Map the current "source" buffer object into the specified "target" buffer object.

This is useful in order to use a buffer in multiple contexts (e.g. OpenGL and CUDA). 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.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::memcpy	(	SoGLBufferObject *	sourceBufferObject,
		size_t	destOffset = `0`,
		size_t	sourceOffset = `0`,
		size_t	copySize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Copy data from the specified GL buffer object into this buffer object.

This is an optimized implementation. See the general memcpy method for more information.

virtual void SoCpuBufferObject::memcpy	(	SoCpuBufferObject *	sourceBufferObject,
		size_t	destOffset = `0`,
		size_t	sourceOffset = `0`,
		size_t	copySize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Copy data from the specified CPU buffer object into this buffer object.

This is an optimized implementation. See the general memcpy method for more information.

Implements SoBufferObject.

virtual void SoCpuBufferObject::memcpy	(	SoBufferObject *	sourceBufferObject,
		size_t	destOffset = `0`,
		size_t	sourceOffset = `0`,
		size_t	copySize = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

Copy 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.

Source and destination overlaping is supported if both are of type SoCpuBufferObject.

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).

Reimplemented in SoCpuBufferBitSet, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::memset	(	void *	value,
		size_t	valueSize = `1`,
		size_t	offset = `0`,
		size_t	count = `SO_BUFFER_SIZE_ALL`
	)			`[virtual]`

This function sets the contents of (or a portion of) this buffer object to the specified value. The valueSize parameter provides a way to do a memset with float, short, byte, etc values. The number of bytes set in this buffer object is exactly valueSize*count. The first byte changed in this buffer is given by the offset argument.

Parameters:

	value	is a pointer to the value to set in the buffer.
	valueSize	The size in bytes of the value. Default is 1 byte.
	offset	The offset in bytes (where to start setting values). Default is 0.
	count	The number of values to set. Default is number of bytes in buffer.

EXAMPLE

   unsigned char memset_value = 0;
   buffer->memset( &memset_value );

Implements SoBufferObject.

Reimplemented in SoCpuBufferBitSet, and SoCpuBufferUniform.

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 (ie. SSE/Altivec computing, CUDA memory mapping, etc).

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

virtual bool SoCpuBufferObject::setSize ( size_t size ) [virtual]

Sets the size in bytes of the buffer object.

In other words, a request to allocate size bytes of CPU memory. Returns true if the allocation succeeded. The memory is owned by the buffer object and will be freed when the buffer object is destroyed.

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. By default memory allocations have the maximum possible alignment to allow use with (for example) SSE instructions.

By default 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).

Parameters:

size

The size in bytes of the memory to allocate.

Returns:: True if allocation succeeded.

Reimplemented from SoBufferObject.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::unmap ( SoGLBufferObject * bufferObject ) [virtual]

Unmap the specified GL buffer object.

This is an optimized implementation. See the general unmap function for more information.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::unmap ( SoCpuBufferObject * bufferObject ) [virtual]

Unmap the specified CPU buffer object.

This is an optimized implementation. See the general unmap function for more information.

Implements SoBufferObject.

virtual void SoCpuBufferObject::unmap ( ) [virtual]

Unmap a buffer mapped to a system memory address.

No error is reported if the buffer was not mapped.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoCpuBufferObject::unmap ( SoBufferObject * bufferObject ) [virtual]

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.

Reimplemented in SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

Friends And Related Function Documentation

friend class SoGLBufferObject [friend]

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

Inventor/devices/SoCpuBufferObject.h

SoCpuBufferObject Class Reference [CPU device]

Public Member Functions

Friends

Detailed Description

EXAMPLE

EXAMPLE

SEE ALSO

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

SoCpuBufferObject Class Reference
[CPU device]