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

