STATE_bitmap_set_pixel

 

 


   *** 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()
  

 

 

Go to page 1      Select API

 

Copyright © 2007 3DSTATE Corporation. www.3dstate.com