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_FORMAT_H 29 #define MMAL_FORMAT_H 30 31 #ifdef __cplusplus 32 extern "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. */ 44 typedef 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 */ 54 typedef 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 */ 71 typedef 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 */ 85 typedef 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. */ 96 typedef 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 */ 125 typedef 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 */ 154 MMAL_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 */ 160 void 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 */ 170 MMAL_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 */ 178 void 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 */ 186 MMAL_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 */ 215 uint32_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