The Raster is a platform-dependent representation of bitmaps. Raster formats are largely dictated by the underlying hardware and are not even guaranteed to use the RGB color model - some platforms may even use compressed formats.
Rasters need to be locked if you need to access or edit their contents and should be unlocked after processing.
It is possible to tell RenderWare Graphics that you only wish to read data, or access structures like palettes, so that unlocking does not impact too much on performance.
These hints are used to determine whether RenderWare needs to perform conversions on the data before and/or after unlocking.
Rasters are closely connected with
|
|
RwRasterFlipMode represents raster flip modes |
|
|
RwRasterFormat is a set of values and flags which may be combined to specify a raster format. The format chosen for a particular raster depends on the hardware device and the raster type specified at creation time (see API function RwRasterCreate). The format may be retrieved using API function RwRasterGetFormat. The raster format is a packed set of bits which contains the following four pieces of information (these may be combined with bitwise OR):-
|
|
|
RwRasterLockMode represents the options available for locking a raster so that it may be modified (see API function RwRasterLock). An application may wish to write to the raster, read from the raster or simultaneously write and read a raster (rwRASTERLOCKWRITE | rwRASTERLOCKREAD).
|
|
|
RwRasterType This type represents the options available for creating a new raster (se API function RwRasterCreate) |
|
|
RwRasterClear is used to clear the entire area of the current render target to the given device specific pixel value. The current render target is the raster at the top of the context stack.
|
|
||||||||||||
|
RwRasterClearRect is used to clear the specified rectangular sub-region of the current render target to the given device specific pixel value. The current render target is the raster on top of the context stack. The sub-region must be wholly contained within the bounds of the destination raster.
|
|
||||||||||||||||||||
|
RwRasterCreate is used to create a new raster of the specified type with the given width, height and depth. The width and height are specified in pixels, the depth is the number of bits per pixel, and the flags indicate the type, and possibly the format, of the raster to create. Specifying zero for the depth indicates that the device default value should be used.
|
|
|
RwRasterDestroy is used to destroy the specified raster and free any resources it may have used.
|
|
|
RwRasterGetCurrentContext is used to determine which, if any, raster is the current target for raster rendering and clearing. The current raster is only defined between calls to RwRasterPushContext and RwRasterPopContext.
|
|
|
RwRasterGetDepth is used to retrieve the depth of the specified raster in bits per pixel. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
|
RwRasterGetFormat is used to retrieve the RwRasterFormat of the specified raster. This describes the pixel color format, and where applicable, the palette depth and mipmap settings. These are set when the raster is created. For example, a raster created on a 16-bit device with type rwRASTERTYPECAMERA may have a format rwRASTERFORMAT565. This indicates that it stores color information at 16-bits per pixel with 5-bits allocated to the red channel, 6-bits to the green and 5-bits to the blue. See RwRasterFormat for more information. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
|
RwRasterGetHeight is used to retrieve the height of the specified raster in pixels. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
|
RwRasterGetNumLevels is used to retrieve the number of mipmap levels in a specified raster (usually of type rwRASTERTYPETEXTURE). This can depend on platform and raster size.
|
|
||||||||||||||||
|
RwRasterGetOffset is used to retrieve the x- and y-offset of the specified raster relative to the top-level parent raster i.e. the raster that holds the pixel data. If the specified raster is not a sub-raster the offsets are zero.
|
|
|
RwRasterGetParent is used to retrieve the raster that the specified sub-raster references for its pixel data. If the given raster is not a sub-raster it references its own pixels and is self-parenting.
|
|
|
RwRasterGetPluginOffset is used to get the offset of a previously registered raster plugin.
|
|
|
RwRasterGetStride is used to retrieve the stride of the specified raster. The stride is measured in bytes per raster line and is the number of bytes that separate two vertically adjacent pixels. If the specified raster is a sub-raster this function will return the stride of its parent. Note that the stride is only defined when the raster is locked. Calling RwRasterGetStride when the raster has not been locked will produce undefined results. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
|
RwRasterGetType is used to retrieve the RwRasterType of the specified raster. This describes the type of the raster, such as whether it is a texture raster (rwRASTERTYPETEXTURE), a camera raster (rwRASTERTYPECAMERA) and so on. The type of a raster is set when it is created. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
|
RwRasterGetWidth is used to retrieve the width of the specified raster in pixels. Note that this function is used for debug purposes only and, for efficiency, is available as a macro for final release versions of an application.
|
|
||||||||||||||||
|
RwRasterLock is used to lock the specified raster for direct pixel access according to the given lock mode. The lock prevents the device changing the raster's data while it is under the control of the application. This function also puts a valid stride in the raster for retrieval. If the specified raster is a sub-raster, this function returns a pointer to the first sub- raster pixel. The stride of the sub-raster, however, is equal to that of the parent raster and must be used for accessing successive scan lines in the sub-raster. The raster must be unlocked when the application has finished updating the pixel data so that the device is made aware of the changes.
|
|
||||||||||||
|
RwRasterLockPalette is used to lock the specified raster for direct palette access according to the given lock mode. The lock prevents the device changing the palettes data while it is under the control of the application. The palette must be unlocked when the application has finished updating the palette data so that the device is made aware of the changes.
|
|
|
RwRasterPopContext is used to indicate that the raster on the top of the context stack is no longer to be targeted with subsequent clears and blits. This function cannot be used between RwCameraBeginUpdate and RwCameraEndUpdate.
|
|
|
RwRasterPushContext is used to indicate that the specified raster is to be the target of subsequent clears and blits. Whenever any 2D rendering is performed the graphical output is stored in the raster on the top of the context stack. This function therefore selects the raster that will be rendered to. This function cannot be used between RwCameraBeginUpdate and RwCameraEndUpdate.
|
|
|
RwRasterRead is used to read an image from a disk file and convert it into a raster. If the file name is not an absolute path name the current search path is used to determine in which directory the image file can be found. The types of image files that are supported are determined by the format modules which have been registered using RwImageRegisterImageFormat. Note that the filename must include the file's extension, as this identifies the images type for dispatch to the correct loader module. The raster is created as type rwRASTERTYPENORMAL and with the default depth. Gamma correction is not applied to the rasters image
|
|
||||||||||||
|
RwRasterReadMaskedRaster is used to read two images from disk files, apply the mask contained in the second to the first and convert the result to a raster. If the file names are not absolute path names the current search path is used to determine in which directory the image files can be found. The types of image files that are supported are determined by the format modules which have been registered using RwImageRegisterImageFormat. Note that the filename must include the file's extension, as this identifies the images type for dispatch to the correct loader module. The raster is created as type rwRASTERTYPENORMAL and with the default depth. Gamma correction is not applied to the rasters image.
|
|
||||||||||||||||||||||||
|
RwRasterRegisterPlugin is used to register a plugin and reserve some space within a raster. This must happen after the engine has been initialized but before the engine is opened.
|
|
||||||||||||||||
|
RwRasterRender is used to render the specified raster to the currently selected render target. The current render target is the raster on top of the context stack. The rendering takes place such that the upper-left corner of the raster falls at the specified position in the destination raster and if the raster has a mask defining transparency in its alpha- channel this is taken into account. No Z-buffering of the raster with its destination is considered - this function only performs a simple blit operation. Areas of the raster which fall outside the destination are clipped before rendering takes place. The raster itself is not changed in any way. Use the API function RwRasterPushContext to set the current raster.
|
|
||||||||||||||||
|
RwRasterRenderFast is used to render the specified raster to the currently selected render target. The current render target is the raster on top of the context stack. Unlike RwRasterRender, transparency information in the raster, if any, is not considered in the rendering, making this function considerably faster. The rendering takes place such that the upper-left corner of the raster falls at the specified position in the destination raster. No Z-buffering of the raster with its destination is considered - this function only performs a simple blit operation. Areas of the raster which fall outside the destination are clipped before rendering takes place. The raster itself is not changed in any way. Use the API function RwRasterPushContext to set the current raster.
|
|
||||||||||||
|
RwRasterRenderScaled is used to render the specified raster to the given rectangular region in the currently selected render target. The current render target is the raster on top of the context stack. If the raster has a mask defining transparency in its alpha-channel this is taken into account. No Z-buffering of the raster with its destination is considered - this function only performs a simple blit operation. The size of the specified rectangle determines the area in the destination raster where rendering takes place. The raster is scaled to fit this region, using pixel replication or averaging, as appropriate. Areas of the raster (after scaling) which fall outside the destination are clipped before rendering takes place. The raster itself is not changed in any way. Use the API function RwRasterPushContext to set the current raster.
|
|
||||||||||||
|
RwRasterSetFreeListCreateParams allows the developer to specify how many RwRaster s to preallocate space for. Call before RwEngineOpen.
|
|
||||||||||||
|
RwRasterSetFromImage is used to change the pixels of the specified raster to those of the given image. The width and height of the image must be equal to those of the raster. If the raster is locked before calling this function then the pixel data is put into the currently locked mip level of the raster, and the lock is not released afterwards. Otherwise the raster is locked at mip level 0 in order to set the pixel data and then unlocked afterwards.
|
|
||||||||||||||||
|
RwRasterShowRaster is used to copy the specified raster to the display device. The raster must be of type rwRASTERTYPECAMERA.
|
|
||||||||||||||||
|
RwRasterSubRaster is used to define a raster that references a rectangular sub-region in another raster. The sub-region must be wholly contained within the bounds of the raster it references. It is necessary that the sub-raster is created with zero width and height so that no memory is actually allocated for the raster's pixel data (which would become unused). Hence, the sub-raster acts as a place-holder whose pixel pointer references the pixel data in another raster covered by the specified rectangle.
|
|
|
RwRasterUnlock is used to unlock the specified raster, following a call to RwRasterLock, allowing it to be used by the device again.
|
|
|
RwRasterUnlockPalette is used to unlock the specified rasters palette, following a call to RwRasterLockPalette, allowing it to be used by the device again.
|
|
|
RwRasterValidatePlugins is used to validate the plugin memory allocated within the specified raster. This function is useful for determining where memory trampling may be occurring within an application. This function only returns a meaningful response under a debug library.
|
© 1993-2003 Criterion Software Limited. All
rights reserved. Built Tue Apr 22 12:46:15 2003. Send Feedback
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |