A pixmap is an off-screen rendering target.
The information and state variables associated with each pixmap is stored in memory allocated when the pixmap is created with screen_create_pixmap(). The composited windowing system keeps track of pixmaps that are allocated to ensure resources are released when the application terminates.
Before a pixmap can be used for rendering, a buffer must be created with screen_create_pixmap_buffer() or attached with screen_attach_pixmap_buffer(). Provided that the usage flags are set appropriately before creating or attaching the pixmap buffer, the contents of pixmaps can then be updated using various rendering APIs. The rendering can be made visible by copying parts of the pixmap to a window using screen_blit().
Pixmaps are restricted to a single buffer. If the pixmap's buffer size hasn't been set explicitly, the buffer size will default to the size of the first display of the pixmap. Trying to change the buffer size or the usage once a buffer has already been allocated will result in an error. Additionally, trying to change the pixel format once the buffer has been added will also result in an error - unless the depth is identical, e.g. changing between RGBA8888 and RGBX8888 is acceptable. Note that buffers cannot be detached from pixmaps.