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

from import *
glEnable(        # typically target is GL_TEXTURE_2D
# ... 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).


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.



  • event
  • gl
  • glext_arb
  • glu
  • graphics
  • key
  • lib
  • lib_glx
  • mouse
  • pprint
  • pyglet
  • re
  • sys
  • util
  • warnings
  • weakref

Table Of Contents

Previous topic

vertex_list_indexed Function

Next topic