15. API - mmalobj¶
This module provides an object-oriented interface to libmmal
which is the
library underlying picamera, raspistill
, and raspivid
. It is provided
to ease the usage of libmmal
to Python coders unfamiliar with C and also
works around some of the idiosyncracies in libmmal
.
15.1. Components¶
-
class
picamera.mmalobj.
MMALComponent
[source]¶ Represents a generic MMAL component. Class attributes are read to determine the component type, and the OPAQUE sub-formats of each connectable port.
-
close
()[source]¶ Close the component and release all its resources. After this is called, most methods will raise exceptions if called.
-
control
¶ The
MMALControlPort
control port of the component which can be used to configure most aspects of the component’s behaviour.
-
enabled
¶ Retrieves or sets whether the component is currently enabled. When a component is disabled it does not produce or consume data. Components may be implicitly enabled by downstream components.
-
-
class
picamera.mmalobj.
MMALCamera
[source]¶ Bases:
picamera.mmalobj.MMALComponent
Represents the MMAL camera component.
The intended use of the output ports (which in turn determines the behaviour of those ports) is as follows:
- Port 0 is intended for preview renderers
- Port 1 is intended for video recording
- Port 2 is intended for still image capture
-
annotate_rev
¶ The annotation capabilities of the firmware have evolved over time and several structures are available for querying and setting video annotations. By default the
MMALCamera
class will pick the latest annotation structure supported by the current firmware but you can select older revisions withannotate_rev
for other purposes (e.g. testing).
-
class
picamera.mmalobj.
MMALCameraInfo
[source]¶ Bases:
picamera.mmalobj.MMALComponent
Represents the MMAL camera-info component.
-
info_rev
¶ The camera information capabilities of the firmware have evolved over time and several structures are available for querying camera information. When initialized,
MMALCameraInfo
will attempt to discover which structure is in use by the extant firmware. This property can be used to discover the structure version and to modify the version in use for other purposes (e.g. testing).
-
-
class
picamera.mmalobj.
MMALDownstreamComponent
[source]¶ Bases:
picamera.mmalobj.MMALComponent
Represents an MMAL component that acts as a filter of some sort, with a single input that connects to an upstream source port. This is an asbtract base class.
-
class
picamera.mmalobj.
MMALSplitter
[source]¶ Bases:
picamera.mmalobj.MMALDownstreamComponent
Represents the MMAL splitter component.
-
class
picamera.mmalobj.
MMALResizer
[source]¶ Bases:
picamera.mmalobj.MMALDownstreamComponent
Represents the MMAL resizer component.
-
class
picamera.mmalobj.
MMALEncoder
[source]¶ Bases:
picamera.mmalobj.MMALDownstreamComponent
Represents a generic MMAL encoder. This is an abstract base class.
-
class
picamera.mmalobj.
MMALVideoEncoder
[source]¶ Bases:
picamera.mmalobj.MMALEncoder
Represents the MMAL video encoder component.
-
class
picamera.mmalobj.
MMALImageEncoder
[source]¶ Bases:
picamera.mmalobj.MMALEncoder
Represents the MMAL image encoder component.
-
class
picamera.mmalobj.
MMALRenderer
[source]¶ Bases:
picamera.mmalobj.MMALDownstreamComponent
Represents the MMAL preview renderer component.
-
class
picamera.mmalobj.
MMALNullSink
[source]¶ Bases:
picamera.mmalobj.MMALDownstreamComponent
Represents the MMAL null-sink component.
15.2. Ports¶
-
class
picamera.mmalobj.
MMALControlPort
(port)[source]¶ Represents an MMAL port with properties to configure the port’s parameters.
-
enable
(callback=None)[source]¶ Enable the port with the specified callback function (this must be
None
for connected ports, and a callable for disconnected ports).The callback function must accept two parameters which will be this
MMALControlPort
(or descendent) and anMMALBuffer
instance. Any return value will be ignored.
-
send_buffer
(buf)[source]¶ Send
MMALBuffer
buf to the port.
-
enabled
¶ Returns a
bool
indicating whether the port is currently enabled. Unlike other classes, this is a read-only property. Useenable()
anddisable()
to modify the value.
-
index
¶ Returns an integer indicating the port’s position within its owning list (inputs, outputs, etc.)
-
params
¶ The configurable parameters for the port. This is presented as a mutable mapping of parameter numbers to values, implemented by the
MMALPortParams
class.
-
-
class
picamera.mmalobj.
MMALPort
(port, opaque_subformat='OPQV')[source]¶ Bases:
picamera.mmalobj.MMALControlPort
Represents an MMAL port with properties to configure and update the port’s format. This is the base class of
MMALVideoPort
,MMALAudioPort
, andMMALSubPicturePort
.-
commit
()[source]¶ Commits the port’s configuration and automatically updates the number and size of associated buffers. This is typically called after adjusting the port’s format and/or associated settings (like width and height for video ports).
-
copy_from
(source)[source]¶ Copies the port’s
format
from the sourceMMALControlPort
.
-
enable
(callback=None)[source]¶ Enable the port with the specified callback function (this must be
None
for connected ports, and a callable for disconnected ports).The callback function must accept two parameters which will be this
MMALControlPort
(or descendent) and anMMALBuffer
instance. The callback should returnTrue
when processing is complete and no further calls are expected (e.g. at frame-end for an image encoder), andFalse
otherwise.
-
bitrate
¶ Retrieves or sets the bitrate limit for the port’s format.
-
format
¶ Retrieves or sets the encoding format of the port. Setting this attribute implicitly sets the encoding variant to a sensible value (I420 in the case of OPAQUE).
After setting this attribute, call
commit()
to make the changes effective.
-
opaque_subformat
¶ Retrieves or sets the opaque sub-format that the port speaks. While most formats (I420, RGBA, etc.) mean one thing, the opaque format is special; different ports produce different sorts of data when configured for OPQV format. This property stores a string which uniquely identifies what the associated port means for OPQV format.
If the port does not support opaque format at all, set this property to
None
.MMALConnection
uses this information when negotiating formats for a connection between two ports.
-
supported_formats
¶ Retrieves a sequence of supported encodings on this port.
Warning
This property does not work on the camera’s still port (
MMALCamera.outputs[2]
) due to an underlying firmware bug.
-
-
class
picamera.mmalobj.
MMALVideoPort
(port, opaque_subformat='OPQV')[source]¶ Bases:
picamera.mmalobj.MMALPort
Represents an MMAL port used to pass video data.
-
class
picamera.mmalobj.
MMALSubPicturePort
(port, opaque_subformat='OPQV')[source]¶ Bases:
picamera.mmalobj.MMALPort
Represents an MMAL port used to pass sub-picture (caption) data.
-
class
picamera.mmalobj.
MMALAudioPort
(port, opaque_subformat='OPQV')[source]¶ Bases:
picamera.mmalobj.MMALPort
Represents an MMAL port used to pass audio data.
-
class
picamera.mmalobj.
MMALPortParams
(port)[source]¶ Represents the parameters of an MMAL port. This class implements the
MMALControlPort.params
attribute.Internally, the class understands how to convert certain structures to more common Python data-types. For example, parameters that expect an MMAL_RATIONAL_T type will return and accept Python’s
Fraction
class (or any other numeric types), while parameters that expect an MMAL_BOOL_T type will treat anything as a truthy value. Parameters that expect the MMAL_PARAMETER_STRING_T structure will be treated as plain strings, and likewise MMAL_PARAMETER_INT32_T and similar structures will be treated as plain ints.Parameters that expect more complex structures will return and expect those structures verbatim.
15.3. Connections¶
-
class
picamera.mmalobj.
MMALConnection
(source, target)[source]¶ Represents an MMAL internal connection between two components. The constructor accepts arguments providing the source
MMALPort
and targetMMALPort
.The connection will automatically negotiate the most efficient format supported by both ports (implicitly handling the incompatibility of some OPAQUE sub-formats). See Under the Hood for more information.
15.4. Buffers¶
-
class
picamera.mmalobj.
MMALBuffer
(buf)[source]¶ Represents an MMAL buffer header. This is usually constructed from the buffer header pointer and is largely supplied simply to make working with the buffer’s data a bit simpler; accessing the
data
attribute implicitly locks the buffer’s memory and returns the data as a bytes string.-
copy
(data=None)[source]¶ Return a copy of this buffer header, optionally replacing the
data
attribute with data which must be an object supporting the buffer protocol.
-
update
(data)[source]¶ Overwrites the
data
in the buffer. The data parameter is an object supporting the buffer protocol which contains up tosize
bytes.Warning
Some buffer objects cannot be modified without consequence (for example, buffers returned by an encoder’s output port).
-
command
¶ Returns the command set in the buffer’s meta-data. This is usually 0 for buffers returned by an encoder; typically this is only used by buffers sent to the callback of a control port.
-
dts
¶ Returns the decoding timestamp (DTS) of the buffer.
-
flags
¶ Returns the flags set in the buffer’s meta-data.
-
length
¶ Returns the length of data held in the buffer. This is equal to calling
len()
ondata
but faster (as retrieving the buffer’s data requires memory locks in certain cases).
-
pts
¶ Returns the presentation timestamp (PTS) of the buffer.
-
-
class
picamera.mmalobj.
MMALPool
(pool)[source]¶ Construct an MMAL pool containing num buffer headers of size bytes.
15.5. Debugging¶
The following functions are useful for quickly dumping the state of a given MMAL pipeline:
-
picamera.mmalobj.
debug_pipeline
(port)[source]¶ Given an
MMALVideoPort
port, this traces all objects in the pipeline feeding it (including components and connections) and yields each object in turn. Hence the generator typically yields something like:MMALVideoPort
(the specified output port)MMALEncoder
(the encoder which owns the output port)MMALVideoPort
(the encoder’s input port)MMALConnection
(the connection between the splitter and encoder)MMALVideoPort
(the splitter’s output port)MMALSplitter
(the splitter on the camera’s video port)MMALVideoPort
(the splitter’s input port)MMALConnection
(the connection between the splitter and camera)MMALVideoPort
(the camera’s video port)MMALCamera
(the camera component)
-
picamera.mmalobj.
print_pipeline
(port)[source]¶ Prints a human readable representation of the pipeline feeding the specified
MMALVideoPort
port.
Note
It is also worth noting that most classes, in particular
MMALVideoPort
and MMALBuffer
have useful repr()
outputs which can be extremely useful with simple print()
calls for
debugging.