mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
232 lines
11 KiB
232 lines
11 KiB
/* |
|
Copyright (c) 2012, Broadcom Europe Ltd |
|
All rights reserved. |
|
|
|
Redistribution and use in source and binary forms, with or without |
|
modification, are permitted provided that the following conditions are met: |
|
* Redistributions of source code must retain the above copyright |
|
notice, this list of conditions and the following disclaimer. |
|
* Redistributions in binary form must reproduce the above copyright |
|
notice, this list of conditions and the following disclaimer in the |
|
documentation and/or other materials provided with the distribution. |
|
* Neither the name of the copyright holder nor the |
|
names of its contributors may be used to endorse or promote products |
|
derived from this software without specific prior written permission. |
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY |
|
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
*/ |
|
|
|
#ifndef MMAL_CONNECTION_H |
|
#define MMAL_CONNECTION_H |
|
|
|
/** \defgroup MmalConnectionUtility Port connection utility |
|
* \ingroup MmalUtilities |
|
* The port connection utility functions can be used in place of common sequences |
|
* of calls to the MMAL API in order to process buffers being passed between two |
|
* ports. |
|
* |
|
* \section ProcessingConnectionBufferHeaders Processing connection buffer headers |
|
* Either in response to the client callback function being called, or simply on a |
|
* timer, the client will need to process the buffer headers of the connection |
|
* (unless tunneling is used). |
|
* |
|
* Buffer headers that are in the pool queue will need to be sent to the output port, |
|
* while buffer headers in the connection queue are sent to the input port. The |
|
* buffer headers in the connection queue may contain pixel data (the cmd field is |
|
* zero) or an event (the cmd field is non-zero). In general, pixel data buffer |
|
* headers need to be passed on, while event buffer headers are released. In the |
|
* case of the format changed event, mmal_connection_event_format_changed() can be |
|
* called before the event is released. |
|
* |
|
* Other, specialized use cases may also be implemented, such as getting and |
|
* immediately releasing buffer headers from the connection queue in order to |
|
* prevent their propagation. This could be used to drop out video, for example. |
|
* |
|
* \section TunnellingConnections Tunnelling connections |
|
* If the \ref MMAL_CONNECTION_FLAG_TUNNELLING flag is set when the connection is |
|
* created, MMAL tunneling will be used. This automates the passing of the buffer |
|
* headers between the output port and input port, and back again. It will also do |
|
* this as efficiently as possible, avoiding trips between the ARM and the VideoCore |
|
* if both components are implemented on the VideoCore. The consequence of this is |
|
* that there is no client callback made as buffer headers get transferred. |
|
* |
|
* The client can still monitor the control port of a component (usually a sink |
|
* component, such as video_render) for the end of stream, in order to know when to |
|
* dismantle the connection. |
|
* |
|
* \section ConnectionClientCallback Client callback |
|
* When not using tunnelling, the client callback function is called each time a |
|
* buffer arrives from a port (either input or output). |
|
* |
|
* \note The callback is made on a different thread from the one used by the |
|
* client to set up the connection, so care must be taken with thread safety. |
|
* One option is to raise a signal to the main client thread that queue processing |
|
* needs to be done, another is for the callback to perform the queue processing |
|
* itself. |
|
* |
|
* The client can also store an opaque pointer in the connection object, which is |
|
* never used by the MMAL code and is only meaningful to the client. |
|
* |
|
* @{ |
|
*/ |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
/** \name Connection flags |
|
* \anchor connectionflags |
|
* The following flags describe the properties of the connection. */ |
|
/* @{ */ |
|
/** The connection is tunnelled. Buffer headers do not transit via the client but |
|
* directly from the output port to the input port. */ |
|
#define MMAL_CONNECTION_FLAG_TUNNELLING 0x1 |
|
/** Force the pool of buffer headers used by the connection to be allocated on the input port. */ |
|
#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_INPUT 0x2 |
|
/** Force the pool of buffer headers used by the connection to be allocated on the output port. */ |
|
#define MMAL_CONNECTION_FLAG_ALLOCATION_ON_OUTPUT 0x4 |
|
/** Specify that the connection should not modify the buffer requirements. */ |
|
#define MMAL_CONNECTION_FLAG_KEEP_BUFFER_REQUIREMENTS 0x8 |
|
/** The connection is flagged as direct. This doesn't change the behaviour of |
|
* the connection itself but is used by the the graph utility to specify that |
|
* the buffer should be sent to the input port from with the port callback. */ |
|
#define MMAL_CONNECTION_FLAG_DIRECT 0x10 |
|
/** Specify that the connection should not modify the port formats. */ |
|
#define MMAL_CONNECTION_FLAG_KEEP_PORT_FORMATS 0x20 |
|
/* @} */ |
|
|
|
/** Forward type definition for a connection */ |
|
typedef struct MMAL_CONNECTION_T MMAL_CONNECTION_T; |
|
|
|
/** Definition of the callback used by a connection to signal back to the client |
|
* that a buffer header is available either in the pool or in the output queue. |
|
* |
|
* @param connection Pointer to the connection |
|
*/ |
|
typedef void (*MMAL_CONNECTION_CALLBACK_T)(MMAL_CONNECTION_T *connection); |
|
|
|
/** Structure describing a connection between 2 ports (1 output and 1 input port) */ |
|
struct MMAL_CONNECTION_T { |
|
|
|
void *user_data; /**< Field reserved for use by the client. */ |
|
MMAL_CONNECTION_CALLBACK_T callback; /**< Callback set by the client. */ |
|
|
|
uint32_t is_enabled; /**< Specifies whether the connection is enabled or not (Read Only). */ |
|
|
|
uint32_t flags; /**< Flags passed during the create call (Read Only). A bitwise |
|
* combination of \ref connectionflags "Connection flags" values. |
|
*/ |
|
MMAL_PORT_T *in; /**< Input port used for the connection (Read Only). */ |
|
MMAL_PORT_T *out; /**< Output port used for the connection (Read Only). */ |
|
|
|
MMAL_POOL_T *pool; /**< Pool of buffer headers used by the output port (Read Only). */ |
|
MMAL_QUEUE_T *queue; /**< Queue for the buffer headers produced by the output port (Read Only). */ |
|
|
|
const char *name; /**< Connection name (Read Only). Used for debugging purposes. */ |
|
|
|
/* Used for debug / statistics */ |
|
int64_t time_setup; /**< Time in microseconds taken to setup the connection. */ |
|
int64_t time_enable; /**< Time in microseconds taken to enable the connection. */ |
|
int64_t time_disable; /**< Time in microseconds taken to disable the connection. */ |
|
}; |
|
|
|
/** Create a connection between two ports. |
|
* The connection shall include a pool of buffer headers suitable for the current format of |
|
* the output port. The format of the input port shall have been set to the same as that of |
|
* the input port. |
|
* Note that connections are reference counted and creating a connection automatically |
|
* acquires a reference to it (released when \ref mmal_connection_destroy is called). |
|
* |
|
* @param connection The address of a connection pointer that will be set to point to the created |
|
* connection. |
|
* @param out The output port to use for the connection. |
|
* @param in The input port to use for the connection. |
|
* @param flags The flags specifying which type of connection should be created. |
|
* A bitwise combination of \ref connectionflags "Connection flags" values. |
|
* @return MMAL_SUCCESS on success. |
|
*/ |
|
MMAL_STATUS_T mmal_connection_create(MMAL_CONNECTION_T **connection, |
|
MMAL_PORT_T *out, MMAL_PORT_T *in, uint32_t flags); |
|
|
|
/** Acquire a reference on a connection. |
|
* Acquiring a reference on a connection will prevent a connection from being destroyed until |
|
* the acquired reference is released (by a call to \ref mmal_connection_destroy). |
|
* References are internally counted so all acquired references need a matching call to |
|
* release them. |
|
* |
|
* @param connection connection to acquire |
|
*/ |
|
void mmal_connection_acquire(MMAL_CONNECTION_T *connection); |
|
|
|
/** Release a reference on a connection |
|
* Release an acquired reference on a connection. Triggers the destruction of the connection when |
|
* the last reference is being released. |
|
* \note This is in fact an alias of \ref mmal_connection_destroy which is added to make client |
|
* code clearer. |
|
* |
|
* @param connection connection to release |
|
* @return MMAL_SUCCESS on success |
|
*/ |
|
MMAL_STATUS_T mmal_connection_release(MMAL_CONNECTION_T *connection); |
|
|
|
/** Destroy a connection. |
|
* Release an acquired reference on a connection. Only actually destroys the connection when |
|
* the last reference is being released. |
|
* The actual destruction of the connection will start by disabling it, if necessary. |
|
* Any pool, queue, and so on owned by the connection shall then be destroyed. |
|
* |
|
* @param connection The connection to be destroyed. |
|
* @return MMAL_SUCCESS on success. |
|
*/ |
|
MMAL_STATUS_T mmal_connection_destroy(MMAL_CONNECTION_T *connection); |
|
|
|
/** Enable a connection. |
|
* The format of the two ports must have been committed before calling this function, |
|
* although note that on creation, the connection automatically copies and commits the |
|
* output port's format to the input port. |
|
* |
|
* The MMAL_CONNECTION_T::callback field must have been set if the \ref MMAL_CONNECTION_FLAG_TUNNELLING |
|
* flag was not specified on creation. The client may also set the MMAL_CONNECTION_T::user_data |
|
* in order to get a pointer passed, via the connection, to the callback. |
|
* |
|
* @param connection The connection to be enabled. |
|
* @return MMAL_SUCCESS on success. |
|
*/ |
|
MMAL_STATUS_T mmal_connection_enable(MMAL_CONNECTION_T *connection); |
|
|
|
/** Disable a connection. |
|
* |
|
* @param connection The connection to be disabled. |
|
* @return MMAL_SUCCESS on success. |
|
*/ |
|
MMAL_STATUS_T mmal_connection_disable(MMAL_CONNECTION_T *connection); |
|
|
|
/** Apply a format changed event to the connection. |
|
* This function can be used when the client is processing buffer headers and receives |
|
* a format changed event (\ref MMAL_EVENT_FORMAT_CHANGED). The connection is |
|
* reconfigured, changing the format of the ports, the number of buffer headers and |
|
* the size of the payload buffers as necessary. |
|
* |
|
* @param connection The connection to which the event shall be applied. |
|
* @param buffer The buffer containing a format changed event. |
|
* @return MMAL_SUCCESS on success. |
|
*/ |
|
MMAL_STATUS_T mmal_connection_event_format_changed(MMAL_CONNECTION_T *connection, |
|
MMAL_BUFFER_HEADER_T *buffer); |
|
|
|
#ifdef __cplusplus |
|
} |
|
#endif |
|
|
|
/** @} */ |
|
|
|
#endif /* MMAL_CONNECTION_H */
|
|
|