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_FORMAT_H
29#define MMAL_FORMAT_H
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** \defgroup MmalFormat Elementary stream format
36 * Definition of an elementary stream format and its associated API */
37/* @{ */
38
39#include "mmal_types.h"
40#include "mmal_encodings.h"
41
42/** Enumeration of the different types of elementary streams.
43 * This divides elementary streams into 4 big categories, plus an invalid type. */
44typedef enum {
45 MMAL_ES_TYPE_UNKNOWN, /**< Unknown elementary stream type */
46 MMAL_ES_TYPE_CONTROL, /**< Elementary stream of control commands */
47 MMAL_ES_TYPE_AUDIO, /**< Audio elementary stream */
48 MMAL_ES_TYPE_VIDEO, /**< Video elementary stream */
49 MMAL_ES_TYPE_SUBPICTURE /**< Sub-picture elementary stream (e.g. subtitles, overlays) */
50} MMAL_ES_TYPE_T;
51
52/** Definition of a video format.
53 * This describes the properties specific to a video stream */
54typedef struct
55{
56 uint32_t width; /**< Width of frame in pixels */
57 uint32_t height; /**< Height of frame in rows of pixels */
58 MMAL_RECT_T crop; /**< Visible region of the frame */
59 MMAL_RATIONAL_T frame_rate; /**< Frame rate */
60 MMAL_RATIONAL_T par; /**< Pixel aspect ratio */
61
62 MMAL_FOURCC_T color_space; /**< FourCC specifying the color space of the
63 * video stream. See the \ref MmalColorSpace
64 * "pre-defined color spaces" for some examples.
65 */
66
67} MMAL_VIDEO_FORMAT_T;
68
69/** Definition of an audio format.
70 * This describes the properties specific to an audio stream */
71typedef struct MMAL_AUDIO_FORMAT_T
72{
73 uint32_t channels; /**< Number of audio channels */
74 uint32_t sample_rate; /**< Sample rate */
75
76 uint32_t bits_per_sample; /**< Bits per sample */
77 uint32_t block_align; /**< Size of a block of data */
78
79 /** \todo add channel mapping, gapless and replay-gain support */
80
81} MMAL_AUDIO_FORMAT_T;
82
83/** Definition of a subpicture format.
84 * This describes the properties specific to a subpicture stream */
85typedef struct
86{
87 uint32_t x_offset; /**< Width offset to the start of the subpicture */
88 uint32_t y_offset; /**< Height offset to the start of the subpicture */
89
90 /** \todo surely more things are needed here */
91
92} MMAL_SUBPICTURE_FORMAT_T;
93
94/** Definition of the type specific format.
95 * This describes the type specific information of the elementary stream. */
96typedef union
97{
98 MMAL_AUDIO_FORMAT_T audio; /**< Audio specific information */
99 MMAL_VIDEO_FORMAT_T video; /**< Video specific information */
100 MMAL_SUBPICTURE_FORMAT_T subpicture; /**< Subpicture specific information */
101} MMAL_ES_SPECIFIC_FORMAT_T;
102
103/** \name Elementary stream flags
104 * \anchor elementarystreamflags
105 * The following flags describe properties of an elementary stream */
106/* @{ */
107#define MMAL_ES_FORMAT_FLAG_FRAMED 0x1 /**< The elementary stream will already be framed */
108/* @} */
109
110/** \name Undefined encoding value.
111 * This value indicates an unknown encoding
112 */
113/* @{ */
114#define MMAL_ENCODING_UNKNOWN 0
115/* @} */
116
117/** \name Default encoding variant value.
118 * This value indicates the default encoding variant is used
119 */
120/* @{ */
121#define MMAL_ENCODING_VARIANT_DEFAULT 0
122/* @} */
123
124/** Definition of an elementary stream format */
125typedef struct MMAL_ES_FORMAT_T
126{
127 MMAL_ES_TYPE_T type; /**< Type of the elementary stream */
128
129 MMAL_FOURCC_T encoding; /**< FourCC specifying the encoding of the elementary stream.
130 * See the \ref MmalEncodings "pre-defined encodings" for some
131 * examples.
132 */
133 MMAL_FOURCC_T encoding_variant;/**< FourCC specifying the specific encoding variant of
134 * the elementary stream. See the \ref MmalEncodingVariants
135 * "pre-defined encoding variants" for some examples.
136 */
137
138 MMAL_ES_SPECIFIC_FORMAT_T *es; /**< Type specific information for the elementary stream */
139
140 uint32_t bitrate; /**< Bitrate in bits per second */
141 uint32_t flags; /**< Flags describing properties of the elementary stream.
142 * See \ref elementarystreamflags "Elementary stream flags".
143 */
144
145 uint32_t extradata_size; /**< Size of the codec specific data */
146 uint8_t *extradata; /**< Codec specific data */
147
148} MMAL_ES_FORMAT_T;
149
150/** Allocate and initialise a \ref MMAL_ES_FORMAT_T structure.
151 *
152 * @return a \ref MMAL_ES_FORMAT_T structure
153 */
154MMAL_ES_FORMAT_T *mmal_format_alloc(void);
155
156/** Free a \ref MMAL_ES_FORMAT_T structure allocated by \ref mmal_format_alloc.
157 *
158 * @param format the \ref MMAL_ES_FORMAT_T structure to free
159 */
160void mmal_format_free(MMAL_ES_FORMAT_T *format);
161
162/** Allocate the extradata buffer in \ref MMAL_ES_FORMAT_T.
163 * This buffer will be freed automatically when the format is destroyed or
164 * another allocation is done.
165 *
166 * @param format format structure for which the extradata buffer will be allocated
167 * @param size size of the extradata buffer to allocate
168 * @return MMAL_SUCCESS on success
169 */
170MMAL_STATUS_T mmal_format_extradata_alloc(MMAL_ES_FORMAT_T *format, unsigned int size);
171
172/** Shallow copy a format structure.
173 * It is worth noting that the extradata buffer will not be copied in the new format.
174 *
175 * @param format_dest destination \ref MMAL_ES_FORMAT_T for the copy
176 * @param format_src source \ref MMAL_ES_FORMAT_T for the copy
177 */
178void mmal_format_copy(MMAL_ES_FORMAT_T *format_dest, MMAL_ES_FORMAT_T *format_src);
179
180/** Fully copy a format structure, including the extradata buffer.
181 *
182 * @param format_dest destination \ref MMAL_ES_FORMAT_T for the copy
183 * @param format_src source \ref MMAL_ES_FORMAT_T for the copy
184 * @return MMAL_SUCCESS on success
185 */
186MMAL_STATUS_T mmal_format_full_copy(MMAL_ES_FORMAT_T *format_dest, MMAL_ES_FORMAT_T *format_src);
187
188/** \name Comparison flags
189 * \anchor comparisonflags
190 * The following flags describe the differences between 2 format structures */
191/* @{ */
192#define MMAL_ES_FORMAT_COMPARE_FLAG_TYPE 0x01 /**< The type is different */
193#define MMAL_ES_FORMAT_COMPARE_FLAG_ENCODING 0x02 /**< The encoding is different */
194#define MMAL_ES_FORMAT_COMPARE_FLAG_BITRATE 0x04 /**< The bitrate is different */
195#define MMAL_ES_FORMAT_COMPARE_FLAG_FLAGS 0x08 /**< The flags are different */
196#define MMAL_ES_FORMAT_COMPARE_FLAG_EXTRADATA 0x10 /**< The extradata is different */
197
198#define MMAL_ES_FORMAT_COMPARE_FLAG_VIDEO_RESOLUTION 0x0100 /**< The video resolution is different */
199#define MMAL_ES_FORMAT_COMPARE_FLAG_VIDEO_CROPPING 0x0200 /**< The video cropping is different */
200#define MMAL_ES_FORMAT_COMPARE_FLAG_VIDEO_FRAME_RATE 0x0400 /**< The video frame rate is different */
201#define MMAL_ES_FORMAT_COMPARE_FLAG_VIDEO_ASPECT_RATIO 0x0800 /**< The video aspect ratio is different */
202#define MMAL_ES_FORMAT_COMPARE_FLAG_VIDEO_COLOR_SPACE 0x1000 /**< The video color space is different */
203
204#define MMAL_ES_FORMAT_COMPARE_FLAG_ES_OTHER 0x10000000 /**< Other ES specific parameters are different */
205/* @} */
206
207/** Compare 2 format structures and returns a set of flags describing the differences.
208 * The result will be zero if the structures are the same, or a combination of
209 * one or more of the \ref comparisonflags "Comparison flags" if different.
210 *
211 * @param format_1 first \ref MMAL_ES_FORMAT_T to compare
212 * @param format_2 second \ref MMAL_ES_FORMAT_T to compare
213 * @return set of flags describing the differences
214 */
215uint32_t mmal_format_compare(MMAL_ES_FORMAT_T *format_1, MMAL_ES_FORMAT_T *format_2);
216
217/* @} */
218
219#ifdef __cplusplus
220}
221#endif
222
223#endif /* MMAL_FORMAT_H */
224