This object represents a platform-neutral bitmap.
Images are intended for loading and processing of bitmap data. They cannot be rendered directly by RenderWare Graphics and must be converted into raster ( RwRaster) objects prior to rendering.
The image object also supports file handling extensions that are completely separate from the RenderWare Binary Stream (see RwStream) system. This allows it to read and write known bitmap file formats, such as .BMP, .RAS and .PNG. By default, no such support is provided. You must link and register the appropriate Toolkits to support these extensions, or write your own.
|
|
RwImageCallBackRead is the function registered with RwImageRegisterImageFormat that is used, for example by RwImageRead and RwImageReadMaskedImage, to read images of a specific format from a disk file.
|
|
|
RwImageCallBackWrite is the function registered with RwImageRegisterImageFormat that is used, for example by RwImageWrite, to write images of a specific format to a disk file.
|
|
|
RwImageAllocatePixels is used to allocate memory for pixels for the specified image. This function can be used following a call to RwImageCreate to allocate memory for a data array which will hold the pixel values of the image. If the image depth is 4 or 8-bits per pixel then memory is also allocated to hold the data for the image's palette. Note that calling RwImageDestroy on the specified image will also free the memory allocated using this function. The pixel memory can also be freed using RwImageFreePixels, without destroying the image structure.
|
|
||||||||||||
|
RwImageApplyMask applies an image's alpha mask to another image. Masking an image has the effect of copying the alpha channel (that part of the image controlling transparency) from the mask image to the destination image. Both image and mask must have the same dimensions. If the input image has 8 bits per pixel, the result of applying the mask is to convert the image to 32 bits per pixel, which allocates its own pixel array. Therefore, if the pixel data was previously registered using RwImageSetPixels, the original pixel data is not freed and should be destroyed by the application if necessary. This also means that the pointer returned by RwImageGetPixels will have changed after applying the mask.
|
|
||||||||||||
|
RwImageCopy is used to copy the contents of one image to another. The source and destination images must have the same pixel resolution but they can have different depths. The only currently supported depth conversions are from 4 or 8- to 32-bits per pixels and it is an error to copy a 32-bit image to an 8 or 4-bit image. Note that the destination images must have memory allocated for its pixel data.
|
|
||||||||||||||||
|
RwImageCreate creates an image with the specified size and depth. Only images with depths 4, 8 and 32-bits per pixel are currently supported. For the former, pixel values are indices into a color look-up table or palette. For the latter, pixel values are true colors in red-green-blue-alpha format. Note that this function does not create space for the pixels or the palette, which can be allocated separately using RwImageAllocatePixels. However, API functions exist which can attach pre-existing pixel and palette data to the image, if required. If RwImageAllocatePixels has been used, then the image stride is automatically calculated, otherwise it must be explicitly determined and set.
|
|
||||||||||||||||
|
RwImageCreateResample re-samples the specified image to a different size according to the width and height input arguments. This function creates a new image of the required size and with a depth of 32-bits per pixel, though the input image can have 8- or 32-bits per pixel. If the re-sampled image is smaller than the original, new pixels are calculated by averaging groups of pixels in the source image. If the re-sampling results in a larger image, pixel replication is used to determine new pixels in the output image. The source image is not altered in any way.
|
|
|
RwImageDestroy destroys the specified image. If the pixel and palette data arrays have been allocated using RwImageAllocatePixels this function frees the space allocated for them too.
|
|
|
RwImageFindFileType is used to search for an image of the specified name, conforming to one of the registered types. It returns an image extension identifying the type of image found, which when appended to the image name will permit loading of the image using RwImageRead or RwImageReadMaskedImage.
RtBMP, RtPNG, RtRAS and RtTIFF. |
|
||||||||||||||||||||||||||||
|
RwImageFindRasterFormat is used to determine a suitable raster format for a given image and the current target. Passing in the image to be considered, and a raster type flag containing type and mipmap format (not pixel format) will return a size, depth and format that can be used to create a suitable target raster for the image.
|
|
||||||||||||
|
RwImageFormatSetFreeListCreateParams allows the developer to specify how many RwImage s to preallocate space for. Call before RwEngineInit.
|
|
|
RwImageFreePixels is used to free memory previously allocated by RwImageAllocatePixels. This includes the pixel data and also the palette data array, where appropriate. It is an error to use this function if the pixel and palette data has been initialized using pre-existing data arrays via the functions RwImageSetPixels and RwImageSetPalette.
|
|
|
RwImageGammaCorrect is used to apply gamma correction to the specified image according to the currently set gamma correction value. The gamma value is specified using the function RwImageSetGamma.
|
|
|
RwImageGetDepth is used to determine the number of bits per pixel of the specified image. Currently, only images with 8- and 32-bits per pixels are supported. 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.
|
|
|
RwImageGetGamma is used to retrieve the current gamma correction value.
|
|
|
RwImageGetHeight is used to determine the height of the specified image 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.
|
|
|
RwImageGetPalette is used to retrieve the specified image's palette data. This function is only relevant for images with 4 or 8-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.
|
|
|
RwImageGetPath is used in conjunction with image, raster and texture reading API functions, the search path is defined as the directory or directories in which the image files can be found. If more than one directory is specified, these must be separated using a semi-colon. The search path can be considered to be either absolute or relative. In the latter case the search path is relative to the directory from which the application executable is running (the current directory). If no search path is specified (empty string) only the current directory is used.
|
|
|
RwImageGetPixels is used to retrieve the specified image's pixel data. 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.
|
|
|
RwImageGetPluginOffset is used to get the offset of a previously registered plugin.
|
|
|
RwImageGetStride is used to determine the stride of the specified image. The stride is the number of bytes between the beginning of one scan-line of the image and the beginning of the next, taking account of padding such that each new scan-line falls on a 8-bit boundary. 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.
|
|
|
RwImageGetWidth is used to determine the width of the specified image 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.
|
|
|
RwImageMakeMask generates an alpha channel for the specified image based on it's pixel color values. The alpha channel is that part of the image controlling transparency and its value for each pixel is calculated here from the color channel values as follows: max(red, green, blue).
|
|
|
RwImageRead is used to read an image from a disk file. The image file name can either be absolute or relative. In the latter case RwImageRead will use the current search path to determine in which directory the image file can be found. The format modules which have been registered using RwImageRegisterImageFormat, determine the types of files that are supported. Note that the filename must include the file's extension, as this identifies the images type for dispatch to the correct loader module. No gamma correction is applied to the image.
|
|
||||||||||||
|
RwImageReadMaskedImage is used to read an image from a disk file. Unlike RwImageRead this function also reads a second file that is used to create a transparency map in the first image. If the image file names are not absolute the current search path is used to determine in which directory the files can be found. The format modules, which have been registered using RwImageRegisterImageFormat , determine the types of image files that are supported. Note that the filename must include the file's extension, as this identifies the images type for dispatch to the correct loader module. No gamma correction is applied to the images.
|
|
||||||||||||||||
|
RwImageRegisterImageFormat is used to register a new image format with RenderWare. This will allow loading and saving of the supplied image format if suitable callbacks are supplied. RenderWare Graphics is supplied with a number of Toolkits containing such callbacks. These Toolkits can be used to add support for the following image formats:
These Toolkits replace the functionality found in previous releases. As a result, the following functions are now considered obsolete and will be deleted in a later release:
RwImage * (*RwImageCallBackRead)(const RwChar *imageName); RwImage *(*RwImageCallBackWrite)(RwImage *image, const RwChar *imageName); An example of writing your own file format parser is provided in the ".../examples/imgformt/" folder. Note that as a default there are no image formats registered with RenderWare. Also, image formats must be registered for reading textures and rasters from image files as these rely on the RwImage functionality. This function must be used after the RenderWare engine has been started. Sample Usage: To enable reading and writing of Sun raster image files together with reading Windows Bitmap files, we must first make sure we are linking against the appropriate libraries, "rtras.lib" and "rtbmp.lib". Next, we include the header files, "rtras.h" and "rtbmp.h". At this point, we can add the following lines to our code after the call to RwEngineOpen():
RwImageRegisterImageFormat("ras", RtRASImageRead, RtRASImageWrite);
RwImageRegisterImageFormat("bmp", RtBMPImageRead,NULL);
|
|
||||||||||||||||||||||||
|
RwImageRegisterPlugin is used to register a plugin and reserve some space within a image. This must happen after the engine has been initialized but before the engine is opened.
|
|
||||||||||||
|
RwImageResample re-samples the specified source image to a different size. The re-sampled size is that specified by the destination image which will receive the new image data. Both the source and destination images must be in 32-bit format. If the destination image is smaller than the source, new pixels in the destination are calculated by averaging groups of pixels in the source image. If the re-sampling results in a larger image, pixel replication is used to determine new pixels in the destination image. Note that the source and destination image pointers must not refer to the same image.
|
|
||||||||||||||||
|
RwImageResize resizes the specified source image to a different size. If the image already has pixels allocated and the resized image is smaller than the original then pixel data will be clipped out as necessary. If pixels have already been allocated to the image and the resized image is larger than the original then the new pixels will return garbage. For example, if an image 275x120 is resized to 256x256 the image size is changed to 256x120 and the extra pixels are filled with garbage.
|
|
||||||||||||
|
RwImageSetFreeListCreateParams allows the developer to specify how many RwImage s to preallocate space for. Call before RwEngineInit.
|
|
||||||||||||
|
RwImageSetFromRaster is used to convert the specified (device dependent) raster into an equivalent (device independent) image. The image and raster dimensions should be the same and it is recommended that the image be created with a depth be 32-bits per pixel. The image must have pixels allocated for it before calling this function. If the raster is locked before calling this function then the pixel data is taken from 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 extract the pixel data and then unlocked afterwards.
To grab and save the camera's image raster to a disk file:
RwRaster *raster;
RwImage *image;
RwInt32 x, y;
RwChar *filename;
raster = RwCameraGetRaster(camera);
if( raster )
{
x = RwRasterGetWidth(raster);
y = RwRasterGetHeight(raster);
image = RwImageCreate(x, y, 32);
if( image )
{
RwImageAllocatePixels(image);
RwImageSetFromRaster(image, raster);
RwImageWrite(image, filename);
RwImageDestroy(image);
}
}
|
|
|
RwImageSetGamma is used to specify the current gamma correction value. Gamma values greater than 1.0 will lighten an image while values less than 1.0 will darken an image. Typically, used to adjust an image prior to display on a monitor whose gamma value differs from unity. The default gamma value is ( RwReal)((1.0)).
|
|
||||||||||||
|
RwImageSetPalette is used to attach a pre-existing palette data array to the specified image. The palette data pointer references an array of allocated bytes large enough to accommodate all of the palette data (conforming with the image's depth). This function is typically used following a call to RwImageCreate to set the palette of an image when the palette data already exists in the required form. This function should only be used for images which have 4 or 8-bits per pixel and have had their pixels allocated using RwImageSetPixels. 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.
|
|
|
RwImageSetPath is used to specify the current search path for reading images from the file system. Used in conjunction with image, raster and texture reading API functions, the search path is defined as the directory or directories in which the image files can be found. If more than one directory is specified, these must be separated using a semi-colon. The search path can be considered to be either absolute or relative. In the latter case the search path is relative to the directory from which the application executable is running (the current directory). If no search path is specified (empty string) only the current directory is used. Always include a trailing path separator in the directory name when setting the search path.
|
|
||||||||||||
|
RwImageSetPixels is used to attach a pre-existing pixel data array to the specified image. The pixel data pointer references an array of allocated bytes large enough to accommodate all of the image data (conforming with the image's width, height, depth and stride). This function is typically used following a call to RwImageCreate to set the pixels of an image when the image data already exists in the required form. The image stride should also be explicitly calculated and set at the same time. If the image data has 8 bits per pixel then a palette is also required, which can be attached to the image using RwImageSetPalette.
|
|
||||||||||||
|
RwImageSetStride is used to specify the stride for the given image. The stride is the number of bytes between the beginning of one scan-line of the image and the beginning of the next, taking account of padding so that each new scan-line falls on an 8-bit boundary. For the currently supported image depths (8- and 32-bits per pixel) the stride is simply the image width multiplied by the number of bits per pixel. This function should be used if pixels are not set using RwImageAllocatePixels which automatically determines and sets the stride. 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.
|
|
|
RwImageStreamGetSize is used to determine the size in bytes of the binary representation of the given image. This value is used in the binary chunk header to indicate the size of the chunk. The size does not include the size of the chunk header.
|
|
|
RwImageStreamRead is used to read an image from the specified binary stream. Note that prior to this function call a binary image chunk must be found in the stream using the RwStreamFindChunk API function. The sequence to locate and read an image from a binary stream connected to a disk file is as follows RwStream *stream; RwImage *newImage; stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx"); if( stream ) { if( RwStreamFindChunk(stream, rwID_IMAGE, NULL, NULL) ) { newImage = RwImageStreamRead(stream); } RwStreamClose(stream, NULL); }
|
|
||||||||||||
|
RwImageStreamWrite is used to write the specified image to the given binary stream. Note that the stream will have been opened prior to this function call.
|
|
|
RwImageValidatePlugins is used to validate the plugin memory allocated within the specified image. 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.
|
|
||||||||||||
|
RwImageWrite is used to write an image to a disk file. The image file name must be absolute and include the extension. The extension determines the type of file written, and must correspond to one of the registered image formats (registered with RwImageRegisterImageFormat). Note that if the image has been gamma corrected using RwImageGammaCorrect, the gamma correction is removed from the image before writing it to disk. Inverse gamma correction is performed using the current gamma correction value.
RtBMP, RtPNG, RtRAS and RtTIFF. |
© 1993-2003 Criterion Software Limited. All
rights reserved. Built Tue Apr 22 12:46:14 2003. Send Feedback
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |