Name

cgMapBuffer - map buffer into application's address space

Synopsis

#include <Cg/cg.h>

void * cgMapBuffer( CGbuffer buffer,
                    CGbufferaccess access );

Parameters

buffer

The buffer which will be mapped into the application's address space.

access

An enumerant indicating the operations the client may perform on the data store through the pointer while the buffer data is mapped.

The following enumerants are allowed:

CG_MAP_READ

The application can read but not write through the data pointer.

CG_MAP_WRITE

The application can write but not read through the data pointer.

CG_MAP_READ_WRITE

The application can read and write through the data pointer.

CG_MAP_WRITE_DISCARD

Same as CG_MAP_READ_WRITE if using a GL buffer.

CG_MAP_WRITE_NO_OVERWRITE

Same as CG_MAP_READ_WRITE if using a GL buffer.

Return Values

Returns a pointer through which the application can read or write the buffer's data store.

Returns NULL if an error occurs.

Description

cgMapBuffer maps a buffer into the application's address space for memory-mapped updating of the buffer's data. The application should call cgUnmapBuffer|cgUnmapBuffer when it's done updating or querying the buffer.

Examples

unsigned char *bufferPtr = cgMapBuffer( myBuffer, CG_MAP_READ_WRITE );
memcpy( ptr, bufferPtr, size );
cgUnmapBuffer( myBuffer );

Errors

CG_INVALID_BUFFER_HANDLE_ERROR is generated if buffer is not a valid buffer.

CG_INVALID_ENUMERANT_ERROR is generated if access is not CG_MAP_READ, CG_MAP_WRITE, CG_MAP_READ_WRITE, CG_MAP_WRITE_DISCARD or CG_MAP_WRITE_NO_OVERWRITE.

CG_BUFFER_ALREADY_MAPPED_ERROR is generated if buffer is already mapped.

History

cgMapBuffer was introduced in Cg 2.0.

See Also

cgUnmapBuffer, cgSetBufferData, cgSetBufferSubData, cgSetParameter