• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
3  *
4  * This source code is subject to the terms of the BSD 2 Clause License and
5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
6  * was not distributed with this source code in the LICENSE file, you can
7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
8  * Media Patent License 1.0 was not distributed with this source code in the
9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
10  */
11 
12 /*!\file
13  * \brief Describes the aom image descriptor and associated operations
14  *
15  */
16 #ifndef AOM_AOM_AOM_IMAGE_H_
17 #define AOM_AOM_AOM_IMAGE_H_
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 #include "aom/aom_integer.h"
24 
25 /*!\brief Current ABI version number
26  *
27  * \internal
28  * If this file is altered in any way that changes the ABI, this value
29  * must be bumped.  Examples include, but are not limited to, changing
30  * types, removing or reassigning enums, adding/removing/rearranging
31  * fields to structures
32  */
33 #define AOM_IMAGE_ABI_VERSION (5) /**<\hideinitializer*/
34 
35 #define AOM_IMG_FMT_PLANAR 0x100  /**< Image is a planar format. */
36 #define AOM_IMG_FMT_UV_FLIP 0x200 /**< V plane precedes U in memory. */
37 /** 0x400 used to signal alpha channel, skipping for backwards compatibility. */
38 #define AOM_IMG_FMT_HIGHBITDEPTH 0x800 /**< Image uses 16bit framebuffer. */
39 
40 /*!\brief List of supported image formats */
41 typedef enum aom_img_fmt {
42   AOM_IMG_FMT_NONE,
43   AOM_IMG_FMT_YV12 =
44       AOM_IMG_FMT_PLANAR | AOM_IMG_FMT_UV_FLIP | 1, /**< planar YVU */
45   AOM_IMG_FMT_I420 = AOM_IMG_FMT_PLANAR | 2,
46   AOM_IMG_FMT_AOMYV12 = AOM_IMG_FMT_PLANAR | AOM_IMG_FMT_UV_FLIP |
47                         3, /** < planar 4:2:0 format with aom color space */
48   AOM_IMG_FMT_AOMI420 = AOM_IMG_FMT_PLANAR | 4,
49   AOM_IMG_FMT_I422 = AOM_IMG_FMT_PLANAR | 5,
50   AOM_IMG_FMT_I444 = AOM_IMG_FMT_PLANAR | 6,
51   AOM_IMG_FMT_I42016 = AOM_IMG_FMT_I420 | AOM_IMG_FMT_HIGHBITDEPTH,
52   AOM_IMG_FMT_YV1216 = AOM_IMG_FMT_YV12 | AOM_IMG_FMT_HIGHBITDEPTH,
53   AOM_IMG_FMT_I42216 = AOM_IMG_FMT_I422 | AOM_IMG_FMT_HIGHBITDEPTH,
54   AOM_IMG_FMT_I44416 = AOM_IMG_FMT_I444 | AOM_IMG_FMT_HIGHBITDEPTH,
55 } aom_img_fmt_t; /**< alias for enum aom_img_fmt */
56 
57 /*!\brief List of supported color primaries */
58 typedef enum aom_color_primaries {
59   AOM_CICP_CP_RESERVED_0 = 0,  /**< For future use */
60   AOM_CICP_CP_BT_709 = 1,      /**< BT.709 */
61   AOM_CICP_CP_UNSPECIFIED = 2, /**< Unspecified */
62   AOM_CICP_CP_RESERVED_3 = 3,  /**< For future use */
63   AOM_CICP_CP_BT_470_M = 4,    /**< BT.470 System M (historical) */
64   AOM_CICP_CP_BT_470_B_G = 5,  /**< BT.470 System B, G (historical) */
65   AOM_CICP_CP_BT_601 = 6,      /**< BT.601 */
66   AOM_CICP_CP_SMPTE_240 = 7,   /**< SMPTE 240 */
67   AOM_CICP_CP_GENERIC_FILM =
68       8, /**< Generic film (color filters using illuminant C) */
69   AOM_CICP_CP_BT_2020 = 9,      /**< BT.2020, BT.2100 */
70   AOM_CICP_CP_XYZ = 10,         /**< SMPTE 428 (CIE 1921 XYZ) */
71   AOM_CICP_CP_SMPTE_431 = 11,   /**< SMPTE RP 431-2 */
72   AOM_CICP_CP_SMPTE_432 = 12,   /**< SMPTE EG 432-1  */
73   AOM_CICP_CP_RESERVED_13 = 13, /**< For future use (values 13 - 21)  */
74   AOM_CICP_CP_EBU_3213 = 22,    /**< EBU Tech. 3213-E  */
75   AOM_CICP_CP_RESERVED_23 = 23  /**< For future use (values 23 - 255)  */
76 } aom_color_primaries_t;        /**< alias for enum aom_color_primaries */
77 
78 /*!\brief List of supported transfer functions */
79 typedef enum aom_transfer_characteristics {
80   AOM_CICP_TC_RESERVED_0 = 0,  /**< For future use */
81   AOM_CICP_TC_BT_709 = 1,      /**< BT.709 */
82   AOM_CICP_TC_UNSPECIFIED = 2, /**< Unspecified */
83   AOM_CICP_TC_RESERVED_3 = 3,  /**< For future use */
84   AOM_CICP_TC_BT_470_M = 4,    /**< BT.470 System M (historical)  */
85   AOM_CICP_TC_BT_470_B_G = 5,  /**< BT.470 System B, G (historical) */
86   AOM_CICP_TC_BT_601 = 6,      /**< BT.601 */
87   AOM_CICP_TC_SMPTE_240 = 7,   /**< SMPTE 240 M */
88   AOM_CICP_TC_LINEAR = 8,      /**< Linear */
89   AOM_CICP_TC_LOG_100 = 9,     /**< Logarithmic (100 : 1 range) */
90   AOM_CICP_TC_LOG_100_SQRT10 =
91       10,                     /**< Logarithmic (100 * Sqrt(10) : 1 range) */
92   AOM_CICP_TC_IEC_61966 = 11, /**< IEC 61966-2-4 */
93   AOM_CICP_TC_BT_1361 = 12,   /**< BT.1361 */
94   AOM_CICP_TC_SRGB = 13,      /**< sRGB or sYCC*/
95   AOM_CICP_TC_BT_2020_10_BIT = 14, /**< BT.2020 10-bit systems */
96   AOM_CICP_TC_BT_2020_12_BIT = 15, /**< BT.2020 12-bit systems */
97   AOM_CICP_TC_SMPTE_2084 = 16,     /**< SMPTE ST 2084, ITU BT.2100 PQ */
98   AOM_CICP_TC_SMPTE_428 = 17,      /**< SMPTE ST 428 */
99   AOM_CICP_TC_HLG = 18,            /**< BT.2100 HLG, ARIB STD-B67 */
100   AOM_CICP_TC_RESERVED_19 = 19     /**< For future use (values 19-255) */
101 } aom_transfer_characteristics_t;  /**< alias for enum aom_transfer_function */
102 
103 /*!\brief List of supported matrix coefficients */
104 typedef enum aom_matrix_coefficients {
105   AOM_CICP_MC_IDENTITY = 0,    /**< Identity matrix */
106   AOM_CICP_MC_BT_709 = 1,      /**< BT.709 */
107   AOM_CICP_MC_UNSPECIFIED = 2, /**< Unspecified */
108   AOM_CICP_MC_RESERVED_3 = 3,  /**< For future use */
109   AOM_CICP_MC_FCC = 4,         /**< US FCC 73.628 */
110   AOM_CICP_MC_BT_470_B_G = 5,  /**< BT.470 System B, G (historical) */
111   AOM_CICP_MC_BT_601 = 6,      /**< BT.601 */
112   AOM_CICP_MC_SMPTE_240 = 7,   /**< SMPTE 240 M */
113   AOM_CICP_MC_SMPTE_YCGCO = 8, /**< YCgCo */
114   AOM_CICP_MC_BT_2020_NCL =
115       9, /**< BT.2020 non-constant luminance, BT.2100 YCbCr  */
116   AOM_CICP_MC_BT_2020_CL = 10, /**< BT.2020 constant luminance */
117   AOM_CICP_MC_SMPTE_2085 = 11, /**< SMPTE ST 2085 YDzDx */
118   AOM_CICP_MC_CHROMAT_NCL =
119       12, /**< Chromaticity-derived non-constant luminance */
120   AOM_CICP_MC_CHROMAT_CL = 13, /**< Chromaticity-derived constant luminance */
121   AOM_CICP_MC_ICTCP = 14,      /**< BT.2100 ICtCp */
122   AOM_CICP_MC_RESERVED_15 = 15 /**< For future use (values 15-255)  */
123 } aom_matrix_coefficients_t;
124 
125 /*!\brief List of supported color range */
126 typedef enum aom_color_range {
127   AOM_CR_STUDIO_RANGE = 0, /**< Y [16..235], UV [16..240] */
128   AOM_CR_FULL_RANGE = 1    /**< YUV/RGB [0..255] */
129 } aom_color_range_t;       /**< alias for enum aom_color_range */
130 
131 /*!\brief List of chroma sample positions */
132 typedef enum aom_chroma_sample_position {
133   AOM_CSP_UNKNOWN = 0,          /**< Unknown */
134   AOM_CSP_VERTICAL = 1,         /**< Horizontally co-located with luma(0, 0)*/
135                                 /**< sample, between two vertical samples */
136   AOM_CSP_COLOCATED = 2,        /**< Co-located with luma(0, 0) sample */
137   AOM_CSP_RESERVED = 3          /**< Reserved value */
138 } aom_chroma_sample_position_t; /**< alias for enum aom_transfer_function */
139 
140 /**\brief Image Descriptor */
141 typedef struct aom_image {
142   aom_img_fmt_t fmt;                 /**< Image Format */
143   aom_color_primaries_t cp;          /**< CICP Color Primaries */
144   aom_transfer_characteristics_t tc; /**< CICP Transfer Characteristics */
145   aom_matrix_coefficients_t mc;      /**< CICP Matrix Coefficients */
146   int monochrome;                    /**< Whether image is monochrome */
147   aom_chroma_sample_position_t csp;  /**< chroma sample position */
148   aom_color_range_t range;           /**< Color Range */
149 
150   /* Image storage dimensions */
151   unsigned int w;         /**< Stored image width */
152   unsigned int h;         /**< Stored image height */
153   unsigned int bit_depth; /**< Stored image bit-depth */
154 
155   /* Image display dimensions */
156   unsigned int d_w; /**< Displayed image width */
157   unsigned int d_h; /**< Displayed image height */
158 
159   /* Image intended rendering dimensions */
160   unsigned int r_w; /**< Intended rendering image width */
161   unsigned int r_h; /**< Intended rendering image height */
162 
163   /* Chroma subsampling info */
164   unsigned int x_chroma_shift; /**< subsampling order, X */
165   unsigned int y_chroma_shift; /**< subsampling order, Y */
166 
167 /* Image data pointers. */
168 #define AOM_PLANE_PACKED 0  /**< To be used for all packed formats */
169 #define AOM_PLANE_Y 0       /**< Y (Luminance) plane */
170 #define AOM_PLANE_U 1       /**< U (Chroma) plane */
171 #define AOM_PLANE_V 2       /**< V (Chroma) plane */
172   unsigned char *planes[3]; /**< pointer to the top left pixel for each plane */
173   int stride[3];            /**< stride between rows for each plane */
174   size_t sz;                /**< data size */
175 
176   int bps; /**< bits per sample (for packed formats) */
177 
178   int temporal_id; /**< Temporal layer Id of image */
179   int spatial_id;  /**< Spatial layer Id of image */
180 
181   /*!\brief The following member may be set by the application to associate
182    * data with this image.
183    */
184   void *user_priv;
185 
186   /* The following members should be treated as private. */
187   unsigned char *img_data; /**< private */
188   int img_data_owner;      /**< private */
189   int self_allocd;         /**< private */
190 
191   void *fb_priv; /**< Frame buffer data associated with the image. */
192 } aom_image_t;   /**< alias for struct aom_image */
193 
194 /**\brief Representation of a rectangle on a surface */
195 typedef struct aom_image_rect {
196   unsigned int x;   /**< leftmost column */
197   unsigned int y;   /**< topmost row */
198   unsigned int w;   /**< width */
199   unsigned int h;   /**< height */
200 } aom_image_rect_t; /**< alias for struct aom_image_rect */
201 
202 /*!\brief Open a descriptor, allocating storage for the underlying image
203  *
204  * Returns a descriptor for storing an image of the given format. The
205  * storage for the descriptor is allocated on the heap.
206  *
207  * \param[in]    img       Pointer to storage for descriptor. If this parameter
208  *                         is NULL, the storage for the descriptor will be
209  *                         allocated on the heap.
210  * \param[in]    fmt       Format for the image
211  * \param[in]    d_w       Width of the image
212  * \param[in]    d_h       Height of the image
213  * \param[in]    align     Alignment, in bytes, of the image buffer and
214  *                         each row in the image(stride).
215  *
216  * \return Returns a pointer to the initialized image descriptor. If the img
217  *         parameter is non-null, the value of the img parameter will be
218  *         returned.
219  */
220 aom_image_t *aom_img_alloc(aom_image_t *img, aom_img_fmt_t fmt,
221                            unsigned int d_w, unsigned int d_h,
222                            unsigned int align);
223 
224 /*!\brief Open a descriptor, using existing storage for the underlying image
225  *
226  * Returns a descriptor for storing an image of the given format. The
227  * storage for descriptor has been allocated elsewhere, and a descriptor is
228  * desired to "wrap" that storage.
229  *
230  * \param[in]    img       Pointer to storage for descriptor. If this parameter
231  *                         is NULL, the storage for the descriptor will be
232  *                         allocated on the heap.
233  * \param[in]    fmt       Format for the image
234  * \param[in]    d_w       Width of the image
235  * \param[in]    d_h       Height of the image
236  * \param[in]    align     Alignment, in bytes, of each row in the image.
237  * \param[in]    img_data  Storage to use for the image
238  *
239  * \return Returns a pointer to the initialized image descriptor. If the img
240  *         parameter is non-null, the value of the img parameter will be
241  *         returned.
242  */
243 aom_image_t *aom_img_wrap(aom_image_t *img, aom_img_fmt_t fmt, unsigned int d_w,
244                           unsigned int d_h, unsigned int align,
245                           unsigned char *img_data);
246 
247 /*!\brief Open a descriptor, allocating storage for the underlying image with a
248  * border
249  *
250  * Returns a descriptor for storing an image of the given format and its
251  * borders. The storage for the descriptor is allocated on the heap.
252  *
253  * \param[in]    img        Pointer to storage for descriptor. If this parameter
254  *                          is NULL, the storage for the descriptor will be
255  *                          allocated on the heap.
256  * \param[in]    fmt        Format for the image
257  * \param[in]    d_w        Width of the image
258  * \param[in]    d_h        Height of the image
259  * \param[in]    align      Alignment, in bytes, of the image buffer and
260  *                          each row in the image(stride).
261  * \param[in]    size_align Alignment, in bytes, of the image width and height.
262  * \param[in]    border     A border that is padded on four sides of the image.
263  *
264  * \return Returns a pointer to the initialized image descriptor. If the img
265  *         parameter is non-null, the value of the img parameter will be
266  *         returned.
267  */
268 aom_image_t *aom_img_alloc_with_border(aom_image_t *img, aom_img_fmt_t fmt,
269                                        unsigned int d_w, unsigned int d_h,
270                                        unsigned int align,
271                                        unsigned int size_align,
272                                        unsigned int border);
273 
274 /*!\brief Set the rectangle identifying the displayed portion of the image
275  *
276  * Updates the displayed rectangle (aka viewport) on the image surface to
277  * match the specified coordinates and size.
278  *
279  * \param[in]    img       Image descriptor
280  * \param[in]    x         leftmost column
281  * \param[in]    y         topmost row
282  * \param[in]    w         width
283  * \param[in]    h         height
284  * \param[in]    border    A border that is padded on four sides of the image.
285  *
286  * \return 0 if the requested rectangle is valid, nonzero otherwise.
287  */
288 int aom_img_set_rect(aom_image_t *img, unsigned int x, unsigned int y,
289                      unsigned int w, unsigned int h, unsigned int border);
290 
291 /*!\brief Flip the image vertically (top for bottom)
292  *
293  * Adjusts the image descriptor's pointers and strides to make the image
294  * be referenced upside-down.
295  *
296  * \param[in]    img       Image descriptor
297  */
298 void aom_img_flip(aom_image_t *img);
299 
300 /*!\brief Close an image descriptor
301  *
302  * Frees all allocated storage associated with an image descriptor.
303  *
304  * \param[in]    img       Image descriptor
305  */
306 void aom_img_free(aom_image_t *img);
307 
308 /*!\brief Get the width of a plane
309  *
310  * Get the width of a plane of an image
311  *
312  * \param[in]    img       Image descriptor
313  * \param[in]    plane     Plane index
314  */
315 int aom_img_plane_width(const aom_image_t *img, int plane);
316 
317 /*!\brief Get the height of a plane
318  *
319  * Get the height of a plane of an image
320  *
321  * \param[in]    img       Image descriptor
322  * \param[in]    plane     Plane index
323  */
324 int aom_img_plane_height(const aom_image_t *img, int plane);
325 
326 #ifdef __cplusplus
327 }  // extern "C"
328 #endif
329 
330 #endif  // AOM_AOM_AOM_IMAGE_H_
331