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 | edit source]TPixmap
[edit | edit source]The Pixmap type
- pixels
- width
- height
- pitch
- format
- capacity
- PixelPtr
- Window
- Copy
- Paste
- Convert
- ReadPixel
- WritePixel
- ClearPixels
- Create
- CreateStatic
TPixmap: Fields
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]Method LoadPixmap:TPixmap( stream:TStream )
Description: Load a pixmap
Information: This method must be implemented by extending types.
Functions
[edit | edit source]CreatePixmap
[edit | edit source]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 | edit source]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 | edit source]Function CopyPixmap:TPixmap( pixmap:TPixmap )
Description: Copy a pixmap
Returns: A new pixmap object
ConvertPixmap
[edit | edit source]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 | edit source]Function PixmapWidth( pixmap:TPixmap )
Description: Get pixmap width
Returns: The width, in pixels, of pixmap
PixmapHeight
[edit | edit source]Function PixmapHeight( pixmap:TPixmap )
Description: Get pixmap width
Returns: The height, in pixels, of pixmap
PixmapPitch
[edit | edit source]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 | edit source]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 | edit source]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 | edit source]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 | edit source]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 | edit source]Function XFlipPixmap:TPixmap( pixmap:TPixmap )
Description: Flip a pixmap horizontally
Returns: A new pixmap object
YFlipPixmap
[edit | edit source]Function YFlipPixmap:TPixmap( pixmap:TPixmap )
Description: Flip a pixmap vertically
Returns: A new pixmap object
ResizePixmap
[edit | edit source]Function ResizePixmap:TPixmap( pixmap:TPixmap,width,height )
Description: Resize a pixmap
Returns: A new pixmap object of the specified width and height
LoadPixmap
[edit | edit source]Function LoadPixmap:TPixmap( url:Object )
Description: Load a pixmap
Returns: A pixmap object
ReadPixel
[edit | edit source]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 | edit source]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 | edit source]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 |