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 toTrue
indicates whether the renderer should occupy the entire display. Finally, the window parameter (which only has meaning when fullscreen isFalse
) 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
andPiPreviewRenderer
, 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 withfullscreen
andwindow
.
-
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 toFalse
, thewindow
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 isFalse
.
-
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.
-
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 isFalse
.
-
window
¶ Retrieves or sets the size of the renderer.
When the
fullscreen
property is set toFalse
, thewindow
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 theMMALRenderer
. 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 orNone
then the resolution is assumed to be the same as the parent camera’s currentresolution
. 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 orNone
, 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 anMMALConnection
to connect the renderer to an MMAL port. The source parameter specifies theMMALPort
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 returnsNone
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 isNone
.Note
This property only affects the renderer; it has no bearing on image captures or recordings (unlike the
resolution
property of thePiCamera
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 thisMMALNullSink
. The source parameter specifies theMMALPort
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 likealpha
,layer
, etc. as it simply dumps any incoming frames. This is also the reason that this class doesn’t derive fromPiRenderer
like all other classes in this module.