13. API - picamera.renderers Module

The renderers module defines the renderer classes used by the camera to provide preview and overlay output 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.

Note

All classes in this module are available from the picamera namespace without having to import picamera.renderers directly.

The following classes are defined in the module:

13.1. PiRenderer

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

Base implementation of an MMAL video renderer 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.

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 of 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 of 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 of 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 of 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.

13.2. PiOverlayRenderer

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

Represents an MMAL renderer with a static source for overlays.

This class descends from PiRenderer and adds a static source for the MMAL renderer. The optional size parameter specifies the size of the source image as a (width, height) tuple. If this is omitted or None then the size is assumed to be the same as the parent camera’s current resolution.

The source must be an object that supports the buffer protocol which has the same length as an image in RGB format (colors represented as interleaved unsigned bytes) with the specified size after the width has been rounded up to the nearest multiple of 32, and the height has been rounded up to the nearest multiple of 16.

For example, if size is (1280, 720), 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 size is (97, 57), 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.

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).

13.3. PiPreviewRenderer

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

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

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

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

13.4. PiNullSink

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

Implements an MMAL null-sink which can be used in place of a renderer.

The parent parameter specifies the PiCamera instance which constructed this null-sink. The source parameter specifies the MMAL port 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).