SetDrawBuffer
Sets a display buffer as the active drawing buffer.
Declaration
N_int32 NAPI GA_2DStateFuncs::SetDrawBuffer(
GA_buffer *drawBuf)
Prototype In
snap/graphics.h
Parameters
drawBuf |
Buffer to make the active drawing buffer. |
Return Value
0 on success, -1 on failure
Description
This function allows the application to make a display memory buffer the active rendering buffer for all subsequent drawing commands. The display memory drawing buffer may be a region of memory with non-conforming dimensions compared to the main display mode (ie: a 320x240 offscreen buffer with an 800x600 display mode). However if the hardware cannot support non-conforming regions, this function will fail. It may also fail if you request a drawing buffer where the offset is not aligned on a scanline boundary for hardware that does not support rendering to arbitrary offscreen buffers.
Note also that some hardware has restrictions on the alignment of both the starting offset in display memory and the pitch in display memory. The BitmapStartAlign and BitmapStridePad fields of the GA_modeInfo structure indicate the alignment requirements, so you must ensure that the Offset and Stride members of the GA_buffer structure are correctly aligned based on these values (if not this function will fail). Some hardware may also require the use of the AlignLinearBuffer command as well.
In order to avoid the complexity of managing offscreen memory, application programmers and shell driver programmers should use the buffer manager functions instead (GA_bufferFuncs). These functions provide a more abstract interface to offscreen video memory, and will automatically take care of managing all the details of surface allocation for you.
Note: This function should never fail if the starting address is aligned to a scanline boundary and the scanline width is the same as the logical display pitch for the display mode.
See Also
Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com