# 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:
| 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 |