# 11. API - Renderers¶

Renderers are used by the camera to provide preview and overlay functionality on the Pi’s display. Users will rarely need to construct instances of these classes directly (start_preview() and add_overlay() are generally used instead) but may find the attribute references for them useful.

## 11.1. PiRenderer¶

class picamera.PiRenderer(parent, layer=0, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False)[source]

Wraps MMALRenderer for use by PiCamera.

The parent parameter specifies the PiCamera instance that has constructed this renderer. The layer parameter specifies the layer that the renderer will inhabit. Higher numbered layers obscure lower numbered layers (unless they are partially transparent). The initial opacity of the renderer is specified by the alpha parameter (which defaults to 255, meaning completely opaque). The fullscreen parameter which defaults to True indicates whether the renderer should occupy the entire display. Finally, the window parameter (which only has meaning when fullscreen is False) is a four-tuple of (x, y, width, height) which gives the screen coordinates that the renderer should occupy when it isn’t full-screen.

This base class isn’t directly used by PiCamera, but the two derivatives defined below, PiOverlayRenderer and PiPreviewRenderer, are used to produce overlays and the camera preview respectively.

close()[source]

Finalizes the renderer and deallocates all structures.

This method is called by the camera prior to destroying the renderer (or more precisely, letting it go out of scope to permit the garbage collector to destroy it at some future time).

alpha

Retrieves or sets the opacity of the renderer.

When queried, the alpha property returns a value between 0 and 255 indicating the opacity of the renderer, where 0 is completely transparent and 255 is completely opaque. The default value is 255. The property can be set while recordings or previews are in progress.

Note

If the renderer is being fed RGBA data (as in partially transparent overlays), the alpha property will be ignored.

crop

Retrieves or sets the area to read from the source.

The crop property specifies the rectangular area that the renderer will read from the source as a 4-tuple of (x, y, width, height). The special value (0, 0, 0, 0) (which is also the default) means to read entire area of the source. The property can be set while recordings or previews are active.

For example, if the camera’s resolution is currently configured as 1280x720, setting this attribute to (160, 160, 640, 400) will crop the preview to the center 640x400 pixels of the input. Note that this property does not affect the size of the output rectangle, which is controlled with fullscreen and window.

Note

This property only affects the renderer; it has no bearing on image captures or recordings (unlike the zoom property of the PiCamera class).

fullscreen

Retrieves or sets whether the renderer appears full-screen.

The fullscreen property is a bool which controls whether the renderer takes up the entire display or not. When set to False, the window property can be used to control the precise size of the renderer display. The property can be set while recordings or previews are active.

hflip

Retrieves or sets whether the renderer’s output is horizontally flipped.

When queried, the vflip property returns a boolean indicating whether or not the renderer’s output is horizontally flipped. The property can be set while recordings or previews are in progress. The default is False.

Note

This property only affects the renderer; it has no bearing on image captures or recordings (unlike the hflip property of the PiCamera class).

layer

Retrieves or sets the layer of the renderer.

The layer property is an integer which controls the layer that the renderer occupies. Higher valued layers obscure lower valued layers (with 0 being the “bottom” layer). The default value is 2. The property can be set while recordings or previews are in progress.

rotation

Retrieves or sets the current rotation of the renderer.

When queried, the rotation property returns the rotation applied to the renderer. Valid values are 0, 90, 180, and 270.

When set, the property changes the rotation applied to the renderer’s output. The property can be set while recordings or previews are active. The default is 0.

Note

This property only affects the renderer; it has no bearing on image captures or recordings (unlike the rotation property of the PiCamera class).

vflip

Retrieves or sets whether the renderer’s output is vertically flipped.

When queried, the vflip property returns a boolean indicating whether or not the renderer’s output is vertically flipped. The property can be set while recordings or previews are in progress. The default is False.

Note

This property only affects the renderer; it has no bearing on image captures or recordings (unlike the vflip property of the PiCamera class).

window

Retrieves or sets the size of the renderer.

When the fullscreen property is set to False, the window property specifies the size and position of the renderer on the display. The property is a 4-tuple consisting of (x, y, width, height). The property can be set while recordings or previews are active.

## 11.2. PiOverlayRenderer¶

class picamera.PiOverlayRenderer(parent, source, resolution=None, format=None, layer=0, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False)[source]

Represents an MMALRenderer with a static source for overlays.

This class descends from PiRenderer and adds a static source for the MMALRenderer. The source must be an object that supports the buffer protocol in one of the supported formats.

The optional resolution parameter specifies the size of the source as a (width, height) tuple. If this is omitted or None then the resolution is assumed to be the same as the parent camera’s current resolution. The optional format parameter specifies the encoding of the source. This can be one of the unencoded formats: 'yuv', 'rgb', 'rgba', 'bgr', or 'bgra'. If omitted or None, format will be guessed based on the size of source (assuming 3 bytes for RGB, and 4 bytes for RGBA).

The length of source must take into account that widths are rounded up to the nearest multiple of 32, and heights to the nearest multiple of 16. For example, if resolution is (1280, 720), and format is 'rgb' then source must be a buffer with length 1280 x 720 x 3 bytes, or 2,764,800 bytes (because 1280 is a multiple of 32, and 720 is a multiple of 16 no extra rounding is required). However, if resolution is (97, 57), and format is 'rgb' then source must be a buffer with length 128 x 64 x 3 bytes, or 24,576 bytes (pixels beyond column 97 and row 57 in the source will be ignored).

The layer, alpha, fullscreen, and window parameters are the same as in PiRenderer.

Changed in version 1.13: Added format parameter

update(source)[source]

Update the overlay with a new source of data.

The new source buffer must have the same size as the original buffer used to create the overlay. There is currently no method for changing the size of an existing overlay (remove and recreate the overlay if you require this).

Note

If you repeatedly update an overlay renderer, you must make sure that you do so at a rate equal to, or slower than, the camera’s framerate. Going faster will rapidly starve the renderer’s pool of buffers leading to a runtime error.

## 11.3. PiPreviewRenderer¶

class picamera.PiPreviewRenderer(parent, source, resolution=None, layer=2, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False)[source]

Represents an MMALRenderer which uses the camera’s preview as a source.

This class descends from PiRenderer and adds an MMALConnection to connect the renderer to an MMAL port. The source parameter specifies the MMALPort to connect to the renderer.

The layer, alpha, fullscreen, and window parameters are the same as in PiRenderer.

resolution

Retrieves or sets the resolution of the preview renderer.

By default, the preview’s resolution matches the camera’s resolution. However, particularly high resolutions (such as the maximum resolution of the V2 camera module) can cause issues. In this case, you may wish to set a lower resolution for the preview that the camera’s resolution.

When queried, the resolution property returns None if the preview’s resolution is derived from the camera’s. In this case, changing the camera’s resolution will also cause the preview’s resolution to change. Otherwise, it returns the current preview resolution as a tuple.

Note

The preview resolution cannot be greater than the camera’s resolution (in either access). If you set a preview resolution, then change the camera’s resolution below the preview’s resolution, this property will silently revert to None, meaning the preview’s resolution will follow the camera’s resolution.

When set, the property reconfigures the preview renderer with the new resolution. As a special case, setting the property to None will cause the preview to follow the camera’s resolution once more. The property can be set while recordings are in progress. The default is None.

Note

This property only affects the renderer; it has no bearing on image captures or recordings (unlike the resolution property of the PiCamera class).

New in version 1.11.

## 11.4. PiNullSink¶

class picamera.PiNullSink(parent, source)[source]

Implements an MMALNullSink which can be used in place of a renderer.

The parent parameter specifies the PiCamera instance which constructed this MMALNullSink. The source parameter specifies the MMALPort which the null-sink should connect to its input.

The null-sink can act as a drop-in replacement for PiRenderer in most cases, but obviously doesn’t implement attributes like alpha, layer, etc. as it simply dumps any incoming frames. This is also the reason that this class doesn’t derive from PiRenderer like all other classes in this module.

close()[source]

Finalizes the null-sink and deallocates all structures.

This method is called by the camera prior to destroying the null-sink (or more precisely, letting it go out of scope to permit the garbage collector to destroy it at some future time).