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.
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)
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
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).
|atlas||Group multiple small images into larger textures.|
|codecs||Collection of image encoders and decoders.|
|AbstractImage||Abstract class representing an image.|
|AbstractImageSequence||Abstract sequence of images.|
|Animation||Sequence of images with timing information.|
|AnimationFrame||A single frame of an animation.|
|BufferImage||An abstract framebuffer.|
|BufferImageMask||A single bit of the stencil buffer.|
|BufferManager||Manages the set of framebuffers for a context.|
|CheckerImagePattern||Create an image with a tileable checker image.|
|ColorBufferImage||A color framebuffer.|
|CompressedImageData||Image representing some compressed data suitable for direct uploading|
|DepthBufferImage||The depth buffer.|
|DepthTexture||A texture with depth samples (typically 24-bit).|
|ImageData||An image represented as a string of unsigned bytes.|
|ImageGrid||An imaginary grid placed over an image allowing easy access to regular regions of that image.|
|ImagePattern||Abstract image creation class.|
|SolidColorImagePattern||Creates an image filled with a solid color.|
|Texture||An image loaded into video memory that can be efficiently drawn to the framebuffer.|
|Texture3D||A texture with more than one image slice.|
|TextureGrid||A texture containing a regular grid of texture regions.|
|TextureRegion||A rectangular region of a texture, presented as if it were|
|TextureSequence||Interface for a sequence of textures.|
|TileableTexture||A texture that can be tiled efficiently.|
|UniformTextureSequence||Interface for a sequence of textures, each with the same dimensions.|
|create(width, height[, pattern])||Create an image optionally filled with the given pattern.|
|get_buffer_manager()||Get the buffer manager for the current OpenGL context.|
|load(filename[, file, decoder])||Load an image from a file.|
|load_animation(filename[, file, decoder])||Load an animation from a file.|