1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, 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
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON 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
25SOFTWARE, 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
32extern "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
44struct MMAL_COMPONENT_PRIVATE_T;
45typedef struct MMAL_COMPONENT_PRIVATE_T MMAL_COMPONENT_PRIVATE_T;
46
47/** Definition of a component. */
48typedef 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 */
97MMAL_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 */
108void 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 */
119MMAL_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 */
128MMAL_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 */
134MMAL_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 */
140MMAL_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