BlitzMax/Modules/Graphics/Pixmaps

Pixmaps provide storage for rectangular regions of pixels. You can create a new pixmap using the CreatePixmap command, or load a pixmap using LoadPixmap. Pixmaps have 5 properties: width, height, a byte pointer to the pixmap's pixels, pitch and format. You can retrieve a pointer to a pixmap's pixels using the PixmapPixelPtr command. A pixmap's pitch refers to the number of bytes between one row of pixels in the pixmap and the next. To retrieve a pixmap's pitch, use the PixmapPitch command. A pixmap's pixel format determines how the pixels within a pixmap are stored in memory. This must be taken into account if you want to access pixels directly via a pixmap's pixel pointer. You can retrieve the format of a pixmap using the PixmapFormat command, and convert pixmaps from one format to another using ConvertPixmap. You can also use ResizePixmap to resize a pixmap and flip a pixmap horizontally or vertically with XFlipPixmap and YFlipPixmap. Types TPixmap The Pixmap type Fields pixels width height pitch format capacity Methods PixelPtr Window Copy Paste Convert ReadPixel WritePixel ClearPixels Functions Create CreateStatic TPixmap: Fields pixels Field pixels:Byte Ptr Description: A byte pointer to the pixmap's pixels width Field width Description: The width, in pixels, of the pixmap height Field height Description: The height, in pixels, of the pixmap pitch Field pitch Description: The pitch, in bytes, of the pixmap format Field format Description: The pixel format of the pixmap capacity Field capacity Description: The capacity, in bytes, of the pixmap, or -1 for a static pixmap TPixmap: Methods PixelPtr Method PixelPtr:Byte Ptr( x,y ) Description: Get memory address of a pixel Returns: A byte pointer to the pixel at coordinates x, y Window Method Window:TPixmap( x,y,width,height ) Description: Create a virtual window into a pixmap Returns: A static pixmap that references the specified rectangle. Copy Method Copy:TPixmap() Description: Duplicate a pixmap Returns: A new TPixmap object. Paste Method Paste( source:TPixmap,x,y ) Description: Paste a pixmap Convert Method Convert:TPixmap( format ) Description: Convert a pixmap Returns: A new TPixmap object in the specified format ReadPixel Method ReadPixel( x,y ) Description: Read a pixel from a pixmap Returns: The pixel at the specified coordinates packed into an integer WritePixel Method WritePixel( x,y,argb ) Description: Write a pixel to a pixmap ClearPixels Method ClearPixels( argb ) Description: Clear a pixmap TPixmap: Functions Create Function Create:TPixmap( width,height,format,align=4 ) Description: Create a pixmap Returns: A new TPixmap object CreateStatic Function CreateStatic:TPixmap( pixels:Byte Ptr,width,height,pitch,format ) Description: Create a static pixmap Returns: A new TPixmap object TPixmapLoader Abstract base type for pixmap loaders To create a new pixmap loader, you should extend TPixmapLoader and implement the LoadPixmap method. To install your pixmap loader, simply create an instance of it using New. Methods LoadPixmap TPixmapLoader: Methods LoadPixmap Method LoadPixmap:TPixmap( stream:TStream ) Description: Load a pixmap Information: This method must be implemented by extending types. Functions CreatePixmap Function CreatePixmap:TPixmap( width,height,format,align_bytes=4 ) Description: Create a pixmap Returns: A new pixmap object of the specified width and height Information: format should be one of the following: Format Description PF_A8 8 bit alpha PF_I8 8 bit intensity PF_RGB888 24 bit big endian RGB PF_BGR888 24 bit little endian RGB PF_RGBA8888 32 bit big endian RGB with alpha PF_BGRA8888 32 bit little endian RGB with alpha Note that the newly created pixmap will contain random data. ClearPixels can be used to set all pixels to a known value prior to use. CreateStaticPixmap Function CreateStaticPixmap:TPixmap( pixels:Byte Ptr,width,height,pitch,format ) Description: Create a pixmap with existing pixel data Returns: A new pixmap object that references an existing block of memory Information: The memory referenced by a static pixmap is not released when the pixmap is deleted. See CreatePixmap for valid pixmap formats. CopyPixmap Function CopyPixmap:TPixmap( pixmap:TPixmap ) Description: Copy a pixmap Returns: A new pixmap object ConvertPixmap Function ConvertPixmap:TPixmap( pixmap:TPixmap,format ) Description: Convert pixel format of a pixmap Returns: A new pixmap object with the specified pixel format Information: See CreatePixmap for valid pixmap formats. PixmapWidth Function PixmapWidth( pixmap:TPixmap ) Description: Get pixmap width Returns: The width, in pixels, of pixmap PixmapHeight Function PixmapHeight( pixmap:TPixmap ) Description: Get pixmap width Returns: The height, in pixels, of pixmap PixmapPitch Function PixmapPitch( pixmap:TPixmap ) Description: Get pixmap pitch Returns: The pitch, in bytes, of pixmap Information: Pitch refers to the difference, in bytes, between the start of one row of pixels and the start of the next row. PixmapFormat Function PixmapFormat( pixmap:TPixmap ) Description: Get pixmap format Returns: The format of the pixels stored in pixmap Information: See CreatePixmap for supported formats. PixmapPixelPtr Function PixmapPixelPtr:Byte Ptr( pixmap:TPixmap,x=0,y=0 ) Description: Get pixmap pixels Returns: A byte pointer to the pixels stored in pixmap PixmapWindow Function PixmapWindow:TPixmap( pixmap:TPixmap,x,y,width,height ) Description: Create a pixmap window Returns: A new pixmap object Information: PixmapWindow creates a 'virtual' window into pixmap. MaskPixmap Function MaskPixmap:TPixmap( pixmap:TPixmap,mask_red,mask_green,mask_blue ) Description: Mask a pixmap Returns: A new pixmap object Information: MaskPixmap builds a new pixmap with alpha components set to '0' wherever the pixel colors in the original pixmap match mask_red, mask_green and mask_blue. mask_red, mask_green and mask_blue should be in the range 0 to 255. XFlipPixmap Function XFlipPixmap:TPixmap( pixmap:TPixmap ) Description: Flip a pixmap horizontally Returns: A new pixmap object YFlipPixmap Function YFlipPixmap:TPixmap( pixmap:TPixmap ) Description: Flip a pixmap vertically Returns: A new pixmap object ResizePixmap Function ResizePixmap:TPixmap( pixmap:TPixmap,width,height ) Description: Resize a pixmap Returns: A new pixmap object of the specified width and height LoadPixmap Function LoadPixmap:TPixmap( url:Object ) Description: Load a pixmap Returns: A pixmap object ReadPixel Function ReadPixel( pixmap:TPixmap,x,y ) Description: Read a pixel from a pixmap Returns: A 32 bit pixel value Information: The returned 32 bit value contains the following components: bits 24-31 pixel alpha bits 16-23 pixel red bits 8-15 pixel green bits 0-7 pixel blue WritePixel Function WritePixel( pixmap:TPixmap,x,y,argb ) Description: Write a pixel to a pixmap Information: The 32 bit argb value contains the following components: bits 24-31 pixel alpha bits 16-23 pixel red bits 8-15 pixel green bits 0-7 pixel blue ClearPixels Function ClearPixels( pixmap:TPixmap,argb=0 ) Description: Clear a pixmap Information: Sets all pixels in a pixmap to a 32 bit pixel value. The 32 bit argb value contains the following components: bits 24-31 pixel alpha bits 16-23 pixel red bits 8-15 pixel green bits 0-7 pixel blue