Package pyglet.image

Image load, capture and high-level texture functions.

Only basic functionality is described here; for full reference see the accompanying documentation.

To load an image:

from pyglet import image
pic = image.load('picture.png')

The supported image file types include PNG, BMP, GIF, JPG, and many more, somewhat depending on the operating system. To load an image from a file-like object instead of a filename:

pic = image.load('hint.jpg', file=fileobj)

The hint helps the module locate an appropriate decoder to use based on the file extension. It is optional.

Once loaded, images can be used directly by most other modules of pyglet. All images have a width and height you can access:

width, height = pic.width, pic.height

You can extract a region of an image (this keeps the original image intact; the memory is shared efficiently):

subimage = pic.get_region(x, y, width, height)

Remember that y-coordinates are always increasing upwards.

Drawing images

To draw an image at some point on the screen:

pic.blit(x, y, z)

This assumes an appropriate view transform and projection have been applied.

Some images have an intrinsic "anchor point": this is the point which will be aligned to the x and y coordinates when the image is drawn. By default the anchor point is the lower-left corner of the image. You can use the anchor point to center an image at a given point, for example:

pic.anchor_x = pic.width // 2
pic.anchor_y = pic.height // 2
pic.blit(x, y, z)

Texture access

If you are using OpenGL directly, you can access the image as a texture:

texture = pic.get_texture()

(This is the most efficient way to obtain a texture; some images are immediately loaded as textures, whereas others go through an intermediate form). To use a texture with pyglet.gl:

from pyglet.gl import *
glEnable(texture.target)        # typically target is GL_TEXTURE_2D
glBindTexture(texture.target, texture.id)
# ... draw with the texture

Pixel access

To access raw pixel data of an image:

rawimage = pic.get_image_data()

(If the image has just been loaded this will be a very quick operation; however if the image is a texture a relatively expensive readback operation will occur). The pixels can be accessed as a string:

format = 'RGBA'
pitch = rawimage.width * len(format)
pixels = rawimage.get_data(format, pitch)

"format" strings consist of characters that give the byte order of each color component. For example, if rawimage.format is 'RGBA', there are four color components: red, green, blue and alpha, in that order. Other common format strings are 'RGB', 'LA' (luminance, alpha) and 'I' (intensity).

The "pitch" of an image is the number of bytes in a row (this may validly be more than the number required to make up the width of the image, it is common to see this for word alignment). If "pitch" is negative the rows of the image are ordered from top to bottom, otherwise they are ordered from bottom to top.

Retrieving data with the format and pitch given in ImageData.format and ImageData.pitch avoids the need for data conversion (assuming you can make use of the data in this arbitrary format).

Submodules

pyglet.image.atlas

Group multiple small images into larger textures.

Classes

	ImageException
	ImagePattern Abstract image creation class.
	SolidColorImagePattern Creates an image filled with a solid color.
	CheckerImagePattern Create an image with a tileable checker image.
	AbstractImage Abstract class representing an image.
	AbstractImageSequence Abstract sequence of images.
	TextureSequence Interface for a sequence of textures.
	UniformTextureSequence Interface for a sequence of textures, each with the same dimensions.
	ImageData An image represented as a string of unsigned bytes.
	ImageDataRegion
	CompressedImageData Image representing some compressed data suitable for direct uploading to driver.
	Texture An image loaded into video memory that can be efficiently drawn to the framebuffer.
	TextureRegion A rectangular region of a texture, presented as if it were a separate texture.
	Texture3D A texture with more than one image slice.
	TileableTexture A texture that can be tiled efficiently.
	DepthTexture A texture with depth samples (typically 24-bit).
	BufferManager Manages the set of framebuffers for a context.
	BufferImage An abstract framebuffer.
	ColorBufferImage A color framebuffer.
	DepthBufferImage The depth buffer.
	BufferImageMask A single bit of the stencil buffer.
	ImageGrid An imaginary grid placed over an image allowing easy access to regular regions of that image.
	TextureGrid A texture containing a regular grid of texture regions.
	Animation Sequence of images with timing information.
	AnimationFrame A single frame of an animation.

Functions

AbstractImage	load(filename, file=None, decoder=None) Load an image from a file.
AbstractImage	create(width, height, pattern=None) Create an image optionally filled with the given pattern.
BufferManager	get_buffer_manager() Get the buffer manager for the current OpenGL context.
Animation	load_animation(filename, file=None, decoder=None) Load an animation from a file.

Variables

__package__ = 'pyglet.image'

Function Details

load

load(filename, file=None, decoder=None)

Load an image from a file.

Parameters:

filename : str: Used to guess the image format, and to load the file if file is unspecified.
file : file-like object or None: Source of image data in any supported format.
decoder : ImageDecoder or None: If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.

Returns: AbstractImage

Note: You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but decoders are free to return any subclass of AbstractImage.

create

create(width, height, pattern=None)

Create an image optionally filled with the given pattern.

Parameters:

width : int: Width of image to create
height : int: Height of image to create
pattern : ImagePattern or None: Pattern to fill image with. If unspecified, the image will initially be transparent.

Returns: AbstractImage

Note: You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but patterns are free to return any subclass of AbstractImage.

load_animation

load_animation(filename, file=None, decoder=None)

Load an animation from a file.

Currently, the only supported format is GIF.

Parameters:

filename : str: Used to guess the animation format, and to load the file if file is unspecified.
file : file-like object or None: File object containing the animation stream.
decoder : ImageDecoder or None: If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.

Returns: Animation