MGL_createBuffer

Creates a new MGL memory buffer for storing bitmaps

Declaration

MGLBUF * MGLAPI MGL_createBuffer(
    MGLDC *dc,
    int width,
    int height,
    M_uint32 flags)

Prototype In

mgraph.h

Parameters

dc

MGL display or windowed device context to allocate buffer from

width

Width of the buffer in pixels

height

Height of the buffer in scanlines

flags

Flags to use when creating the buffer

 

Return Value

Pointer to the allocated buffer, NULL on failure.

Description

This function allocates a new lightweight bitmap buffer in offscreen display memory. Lighweight bitmap buffers are used to store bitmap and sprite information in the offscreen display memory in the hardware, but are not full device contexts. Hence buffers have much less memory overhead than a full offscreen device context. Buffers can only be used for storing bitmaps and blitting them around on the screen. You can copy the contents to a MGL device context using the MGL_putBuffer, MGL_stretchBuffer and MGL_putBufferSrcTrans functions. You can also copy the contents of an MGL device context to a buffer using the MGL_copyToBuffer function.

If you need to draw on a buffer in offscreen memory, create a full offscreen device context instead. Then you can call any of the standard MGL drawing functions and BitBlt operations for the offscreen memory buffer. The primary disadvantage of doing this is that a full offscreen device context has a lot more memory overhead involved in maintaining the device context state information than a simple offscreen buffer.

If you flag the MGL_BUF_CACHED flag, MGL will always keep a cached copy of the surface memory for the buffer in system memory. If your offscreen buffers get lost (ie: on a fullscreen mode switch), they can be automatically be restored when the application regains the active focus. This also allows the MGL to compact the offscreen memory heap when necessary. If you don't set the cacheIt parameter to true, then it is your applications responsibility to reload the bitmaps when the focus is lost and regained. Note however that the MGL is not responsible for maintaining the contents of the buffer cache memory, so if you draw directly on the buffer surface you should ensure that the cache is kept up to date if you wish for your buffers to be cached. Note that the MGL_copyToBuffer and MGL_copyBitmapToBuffer functions will ensure that both the buffer cache and video memory buffer contents are updated if the buffer is cached. Hence if you are only using the buffers to store static sprite information, you can use MGL_copyToBuffer() or MGL_copyBitmapToBuffer() and never have to worry about keeping the buffer cache in sync.

Note:    The MGL automatically manages offscreen display memory, and if you run out of offscreen display memory it will place the buffer surfaces in system memory (unless you pass the MGL_BUF_NOSYSMEM flag). Hence you should allocate your important buffers first, to ensure they end up in offscreen memory for speedy drawing.

Note:    This function is only valid for display device contexts, and will fail if you call it for a different device context type with an error code of grInvalidDC.

See Also

MGL_createBuffer, MGL_lockBuffer, MGL_unlockBuffer, MGL_destroyBuffer, MGL_createOffscreenDC, MGL_putBuffer, MGL_stretchBuffer, MGL_putBufferSrcTrans, MGL_putBufferDstTrans, MGL_copyToBuffer, MGL_copyBitmapToBuffer, MGL_updateBufferCache, MGL_updateFromBufferCache

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