cgMapBuffer(3)

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_READ_ONLY, CG_WRITE_ONLY, or CG_READ_WRITE.

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