|
*** useful for doing some special effects and advanced stuff
Set a pixel in the given bitmap
Parameters:
bitmap_handle [IN]:
The bitmap handle.
x,y [IN]:
the specific pixel. 0,0 it the top left corner of the bitmap
(width-1, height-1) is mapped is the bottom right corner.
To get the width and height of the bitmap use STATE_bitmap_get_height()
and STATE_bitmap_get_width()
mipmap_level [IN]:
Zero based index. If there are 8 mipmaps level then 0-7 are legal mipmap levels
When bitmapss are loaded into the engine, the engine automatically creates
different version of the bitmap. For example if the bitmap loaded is 256x256
then the engine will create additional bitmaps in the size of 128x128, 64x64, 32x32, ... 1x1
This is a known technique that improves graphic quality significantly.
When rendering a polygon that uses this bitmap the most suitable mipmap levels are selected
and blended together.
This is done automaticall and internally so you shouldn't concern about it at all
except when using STATE_bitmap_set_pixel(). Using this function you can
access each mipmap level.
Except for doing some special effects this is usually not
very useful so you might want to set just mipmao 0 (the heighest detailed mipmap)
and cancel mipmapping for all the polygons using this bitmap using STATE_polygon_use_mipmap(polygon, NO)
Note that if you don't cancel mipmapping for the relevant polygon and you just modify
one mipmap level, the changes will only be noticeable when the modified mipmap
is used. For example if you write pixel to mipmap 0 then only when the viewer (the camera)
is close to the polygon with the bitmap, the high level mipmap level (mipmap 0) will be used
and only then the changes to the bitmap will be evident.
RGBA [IN]:
returns the color and alpha value of the pixel.
RGBA[0] is red
RGBA[1] is green
RGBA[2] is blue
RGBA[3] is the alpha value
Note that the engine will automatically convert the give RGBA to the proper format used by the bitmap
Important notes:
1. The function can only be called after at least one render was done.
2. The function support the following bitmap formats
D3DFMT_A8R8G8B8, D3DFMT_X8R8G8B8, D3DFMT_A4R4G4B4, D3DFMT_A1R5G5B5
Note that the engine default bitmap format is BITMAP_FORMAT_DXT1 (which is a compressed format)
This means that if you plan to use the STATE_bitmap_get_pixel() or STATE_bitmap_set_pixel()
You need to call STATE_bitmap_set_default_format(BITMAP_FORMAT_A8R8G8B8); (or any other supported formats)
at the beginning of the program (or at least before the first render ).
3. Note that the changes to the bitmap will be lost when the screen resolution is changed.
4. Unless you know what you are doing, we recommend that you write only to mipmap 0 and cancel
mipmapping to all polygons using the modified bitmap (by calling STATE_polygon_use_mipmap(polygon, NO) )
Return Value:
Return OK or VR_ERROR. VR_ERROR is returned if the function is called before the first render or when x,y are out of range.
See also STATE_bitmap_get_number_of_mipmaps()
|