| Home
| Previous
| Next
| Up

MGL_bufferFlagsType

Declaration

typedef enum {
MGL_BUF_SYSMEM = 0x00000001,
MGL_BUF_CACHED = 0x00000002,
MGL_BUF_MOVEABLE = 0x00000004,
MGL_BUF_PAGEABLE = 0x00000008,
MGL_BUF_PRIORITY = 0x00000010,
MGL_BUF_NOSYSMEM = 0x00000020
} MGL_bufferFlagsType

Prototype In

mgraph.h

Description

Defines the flags passed to MGL_createBuffer. The flags define how the buffer is allocated by the MGL, and the type of buffer.

The MGL_BUF_SYSMEM flag indicates that the buffer is currently located in system memory only. It is possible for a buffer that was allocated with the MGL_BUF_PAGEABLE and MGL_BUF_CACHED flags to initially be in video memory but then get paged out to system memory to make space for higher priority buffers. You can also set this flag when you allocate a buffer to cause the buffer to be allocated in system memory instead of video memory.

The MGL_BUF_CACHED flag indicates that the buffer should have a system memory cache allocated for it, so that it can be swapped in and out of video memory as necessary. Sometimes it may be useful to have buffers cached in system memory, but not have them pageable. Thus the system memory cache can be used to refresh the video memory as necessary if the video memory contents were lost (ie: on a focus switch etc). Note that the system memory cache is not maintained automaticaly by MGL, but rather it is up to the application code to maintain the contents of the system memory cache if they need to be kept in sync. You can use the MGL_updateBufferCache and MGL_updateFromBufferCache functions to keep the system memory cache in sync as necessary. Note also that some of the buffer manager drawing functions will draw from the buffer cache if it is present and the hardware cannot accelerate the operation within video memory. Hence it is important that the application keep the buffer cache coherent with the contents of the video memory buffer or some drawing operations may come out incorrect.

The MGL_BUF_MOVEABLE flag indicates that the buffer should be allocated on the moveable buffer heap, so that the buffer can be moved around as necessary to compact the heap if it becomes fragmented. For buffers that should never move in video memory, this flag should not be set and the buffers will be allocated in the non-moveable or fixed heap.

The MGL_BUF_PAGEABLE flag indicates that the buffer is a low priority buffer and can be paged to system memory in order to make room for higher priority buffers. Setting MGL_BUF_PAGEABLE flag will automatically set the MGL_BUF_CACHED flag so that there is a system memory cache for the buffer. Pageable buffers will be paged back into video memory when the heap becomes free of all non-pageable buffers. Hence shell drivers using the buffer manager to cache bitmaps etc should make those bitmaps all pageable, so that they will get pages to system memory if applications need more offscreen memory (ie: 2D or 3D graphics intensive apps). When the graphics intensive app exits, the pageable buffers will get pages back into video memory as all non-pageable buffers will have been freed.

The MGL_BUF_PRIORITY flag indicates that the buffer is a high priority buffer. As long as there are any high priority buffers still allocated, the buffer manager will not attempt to page back in pageable buffers from system memory.

The MGL_BUF_NOSYSMEM flag is used to indicate that the surface being created should only ever be allocated in video memory. If there is no video memory available, the buffer allocation function will fail (normally it will attempt to allocate the buffer in system memory if the MGL_BUF_CACHED or MGL_BUF_PAGEABLE flags are set).

Members

MGL_BUF_SYSMEM | Buffer is currently located in system memory
MGL_BUF_CACHED | Buffer is cached in system memory
MGL_BUF_MOVEABLE | Buffer can be moved around to compact buffer heap
MGL_BUF_PAGEABLE | Buffer can be paged to system memory
MGL_BUF_PRIORITY | Buffer is a high priority bitmap
MGL_BUF_NOSYSMEM | Buffer should never be allocated in system memory

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com