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 edit

TPixmap edit

The Pixmap type

Fields
  • pixels
  • width
  • height
  • pitch
  • format
  • capacity
Methods
  • PixelPtr
  • Window
  • Copy
  • Paste
  • Convert
  • ReadPixel
  • WritePixel
  • ClearPixels
Functions
  • Create
  • CreateStatic

TPixmap: Fields edit

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 edit

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 edit

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 edit

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 edit

LoadPixmap

Method LoadPixmap:TPixmap( stream:TStream )

Description: Load a pixmap

Information: This method must be implemented by extending types.

Functions edit

CreatePixmap edit

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 edit

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 edit

Function CopyPixmap:TPixmap( pixmap:TPixmap )

Description: Copy a pixmap

Returns: A new pixmap object

ConvertPixmap edit

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 edit

Function PixmapWidth( pixmap:TPixmap )

Description: Get pixmap width

Returns: The width, in pixels, of pixmap

PixmapHeight edit

Function PixmapHeight( pixmap:TPixmap )

Description: Get pixmap width

Returns: The height, in pixels, of pixmap

PixmapPitch edit

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 edit

Function PixmapFormat( pixmap:TPixmap )

Description: Get pixmap format

Returns: The format of the pixels stored in pixmap

Information: See CreatePixmap for supported formats.

PixmapPixelPtr edit

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 edit

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 edit

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 edit

Function XFlipPixmap:TPixmap( pixmap:TPixmap )

Description: Flip a pixmap horizontally

Returns: A new pixmap object

YFlipPixmap edit

Function YFlipPixmap:TPixmap( pixmap:TPixmap )

Description: Flip a pixmap vertically

Returns: A new pixmap object

ResizePixmap edit

Function ResizePixmap:TPixmap( pixmap:TPixmap,width,height )

Description: Resize a pixmap

Returns: A new pixmap object of the specified width and height

LoadPixmap edit

Function LoadPixmap:TPixmap( url:Object )

Description: Load a pixmap

Returns: A pixmap object

ReadPixel edit

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 edit

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 edit

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