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


 * pixels
 * width
 * height
 * pitch
 * format
 * capacity


 * PixelPtr
 * Window
 * Copy
 * Paste
 * Convert
 * ReadPixel
 * WritePixel
 * ClearPixels


 * Create
 * CreateStatic

TPixmap: Fields
Field pixels:Byte Ptr

Description: A byte pointer to the pixmap's pixels

Field width

Description: The width, in pixels, of the pixmap

Field height

Description: The height, in pixels, of the pixmap

Field pitch

Description: The pitch, in bytes, of the pixmap

Field format

Description: The pixel format of the pixmap

Field capacity

Description: The capacity, in bytes, of the pixmap, or -1 for a static pixmap

TPixmap: Methods
Method PixelPtr:Byte Ptr( x,y )

Description: Get memory address of a pixel

Returns: A byte pointer to the pixel at coordinates x, y

Method Window:TPixmap( x,y,width,height )

Description: Create a virtual window into a pixmap

Returns: A static pixmap that references the specified rectangle.

Method Copy:TPixmap

Description: Duplicate a pixmap

Returns: A new TPixmap object.

Method Paste( source:TPixmap,x,y )

Description: Paste a pixmap

Method Convert:TPixmap( format )

Description: Convert a pixmap

Returns: A new TPixmap object in the specified format

Method ReadPixel( x,y )

Description: Read a pixel from a pixmap

Returns: The pixel at the specified coordinates packed into an integer

Method WritePixel( x,y,argb )

Description: Write a pixel to a pixmap

Method ClearPixels( argb )

Description: Clear a pixmap

TPixmap: Functions
Function Create:TPixmap( width,height,format,align=4 )

Description: Create a pixmap

Returns: A new TPixmap object

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.


 * LoadPixmap

TPixmapLoader: Methods
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:

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:

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:

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: