cgMapBuffer
Keywords: cgMapBuffer, NVIDIA, NVIDIA Cg Toolkit, Cg Toolkit, Shader, Shader Programming, GPU Shader Programming, GPU Program

> ## 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