1 /* 2 Copyright (c) 2012, Broadcom Europe Ltd 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions are met: 7 * Redistributions of source code must retain the above copyright 8 notice, this list of conditions and the following disclaimer. 9 * Redistributions in binary form must reproduce the above copyright 10 notice, this list of conditions and the following disclaimer in the 11 documentation and/or other materials provided with the distribution. 12 * Neither the name of the copyright holder nor the 13 names of its contributors may be used to endorse or promote products 14 derived from this software without specific prior written permission. 15 16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY 20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef MMAL_COMPONENT_H 29 #define MMAL_COMPONENT_H 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** \defgroup MmalComponent Components 36 * Definition of a MMAL component and its associated API. A component will always expose ports 37 * which it uses to send and receive data in the form of buffer headers 38 * (\ref MMAL_BUFFER_HEADER_T) */ 39 /* @{ */ 40 41 #include "mmal_types.h" 42 #include "mmal_port.h" 43 44 struct MMAL_COMPONENT_PRIVATE_T; 45 typedef struct MMAL_COMPONENT_PRIVATE_T MMAL_COMPONENT_PRIVATE_T; 46 47 /** Definition of a component. */ 48 typedef struct MMAL_COMPONENT_T 49 { 50 /** Pointer to the private data of the module in use */ 51 struct MMAL_COMPONENT_PRIVATE_T *priv; 52 53 /** Pointer to private data of the client */ 54 struct MMAL_COMPONENT_USERDATA_T *userdata; 55 56 /** Component name */ 57 const char *name; 58 59 /** Specifies whether the component is enabled or not */ 60 uint32_t is_enabled; 61 62 /** All components expose a control port. 63 * The control port is used by clients to set / get parameters that are global to the 64 * component. It is also used to receive events, which again are global to the component. 65 * To be able to receive events, the client needs to enable and register a callback on the 66 * control port. */ 67 MMAL_PORT_T *control; 68 69 uint32_t input_num; /**< Number of input ports */ 70 MMAL_PORT_T **input; /**< Array of input ports */ 71 72 uint32_t output_num; /**< Number of output ports */ 73 MMAL_PORT_T **output; /**< Array of output ports */ 74 75 uint32_t clock_num; /**< Number of clock ports */ 76 MMAL_PORT_T **clock; /**< Array of clock ports */ 77 78 uint32_t port_num; /**< Total number of ports */ 79 MMAL_PORT_T **port; /**< Array of all the ports (control/input/output/clock) */ 80 81 /** Uniquely identifies the component's instance within the MMAL 82 * context / process. For debugging. */ 83 uint32_t id; 84 85 } MMAL_COMPONENT_T; 86 87 /** Create an instance of a component. 88 * The newly created component will expose ports to the client. All the exposed ports are 89 * disabled by default. 90 * Note that components are reference counted and creating a component automatically 91 * acquires a reference to it (released when \ref mmal_component_destroy is called). 92 * 93 * @param name name of the component to create, e.g. "video_decode" 94 * @param component returned component 95 * @return MMAL_SUCCESS on success 96 */ 97 MMAL_STATUS_T mmal_component_create(const char *name, 98 MMAL_COMPONENT_T **component); 99 100 /** Acquire a reference on a component. 101 * Acquiring a reference on a component will prevent a component from being destroyed until 102 * the acquired reference is released (by a call to \ref mmal_component_destroy). 103 * References are internally counted so all acquired references need a matching call to 104 * release them. 105 * 106 * @param component component to acquire 107 */ 108 void mmal_component_acquire(MMAL_COMPONENT_T *component); 109 110 /** Release a reference on a component 111 * Release an acquired reference on a component. Triggers the destruction of the component when 112 * the last reference is being released. 113 * \note This is in fact an alias of \ref mmal_component_destroy which is added to make client 114 * code clearer. 115 * 116 * @param component component to release 117 * @return MMAL_SUCCESS on success 118 */ 119 MMAL_STATUS_T mmal_component_release(MMAL_COMPONENT_T *component); 120 121 /** Destroy a previously created component 122 * Release an acquired reference on a component. Only actually destroys the component when 123 * the last reference is being released. 124 * 125 * @param component component to destroy 126 * @return MMAL_SUCCESS on success 127 */ 128 MMAL_STATUS_T mmal_component_destroy(MMAL_COMPONENT_T *component); 129 130 /** Enable processing on a component 131 * @param component component to enable 132 * @return MMAL_SUCCESS on success 133 */ 134 MMAL_STATUS_T mmal_component_enable(MMAL_COMPONENT_T *component); 135 136 /** Disable processing on a component 137 * @param component component to disable 138 * @return MMAL_SUCCESS on success 139 */ 140 MMAL_STATUS_T mmal_component_disable(MMAL_COMPONENT_T *component); 141 142 /* @} */ 143 144 #ifdef __cplusplus 145 } 146 #endif 147 148 #endif /* MMAL_COMPONENT_H */ 149