Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (c) 2010 The WebM project authors. All Rights Reserved. |
| 3 | * |
| 4 | * Use of this source code is governed by a BSD-style license |
| 5 | * that can be found in the LICENSE file in the root of the source |
| 6 | * tree. An additional intellectual property rights grant can be found |
| 7 | * in the file PATENTS. All contributing project authors may |
| 8 | * be found in the AUTHORS file in the root of the source tree. |
| 9 | */ |
| 10 | |
| 11 | |
| 12 | /*!\file |
| 13 | * \brief Describes the vpx image descriptor and associated operations |
| 14 | * |
| 15 | */ |
Vignesh Venkatasubramanian | b08e2e2 | 2014-03-10 09:50:31 -0700 | [diff] [blame] | 16 | #ifndef VPX_VPX_IMAGE_H_ |
| 17 | #define VPX_VPX_IMAGE_H_ |
| 18 | |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 19 | #ifdef __cplusplus |
| 20 | extern "C" { |
| 21 | #endif |
| 22 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 23 | /*!\brief Current ABI version number |
| 24 | * |
| 25 | * \internal |
| 26 | * If this file is altered in any way that changes the ABI, this value |
| 27 | * must be bumped. Examples include, but are not limited to, changing |
| 28 | * types, removing or reassigning enums, adding/removing/rearranging |
| 29 | * fields to structures |
| 30 | */ |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 31 | #define VPX_IMAGE_ABI_VERSION (3) /**<\hideinitializer*/ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 32 | |
| 33 | |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 34 | #define VPX_IMG_FMT_PLANAR 0x100 /**< Image is a planar format. */ |
| 35 | #define VPX_IMG_FMT_UV_FLIP 0x200 /**< V plane precedes U in memory. */ |
| 36 | #define VPX_IMG_FMT_HAS_ALPHA 0x400 /**< Image has an alpha channel. */ |
| 37 | #define VPX_IMG_FMT_HIGHBITDEPTH 0x800 /**< Image uses 16bit framebuffer. */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 38 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 39 | /*!\brief List of supported image formats */ |
| 40 | typedef enum vpx_img_fmt { |
| 41 | VPX_IMG_FMT_NONE, |
| 42 | VPX_IMG_FMT_RGB24, /**< 24 bit per pixel packed RGB */ |
| 43 | VPX_IMG_FMT_RGB32, /**< 32 bit per pixel packed 0RGB */ |
| 44 | VPX_IMG_FMT_RGB565, /**< 16 bit per pixel, 565 */ |
| 45 | VPX_IMG_FMT_RGB555, /**< 16 bit per pixel, 555 */ |
| 46 | VPX_IMG_FMT_UYVY, /**< UYVY packed YUV */ |
| 47 | VPX_IMG_FMT_YUY2, /**< YUYV packed YUV */ |
| 48 | VPX_IMG_FMT_YVYU, /**< YVYU packed YUV */ |
| 49 | VPX_IMG_FMT_BGR24, /**< 24 bit per pixel packed BGR */ |
| 50 | VPX_IMG_FMT_RGB32_LE, /**< 32 bit packed BGR0 */ |
| 51 | VPX_IMG_FMT_ARGB, /**< 32 bit packed ARGB, alpha=255 */ |
| 52 | VPX_IMG_FMT_ARGB_LE, /**< 32 bit packed BGRA, alpha=255 */ |
| 53 | VPX_IMG_FMT_RGB565_LE, /**< 16 bit per pixel, gggbbbbb rrrrrggg */ |
| 54 | VPX_IMG_FMT_RGB555_LE, /**< 16 bit per pixel, gggbbbbb 0rrrrrgg */ |
| 55 | VPX_IMG_FMT_YV12 = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_UV_FLIP | 1, /**< planar YVU */ |
| 56 | VPX_IMG_FMT_I420 = VPX_IMG_FMT_PLANAR | 2, |
| 57 | VPX_IMG_FMT_VPXYV12 = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_UV_FLIP | 3, /** < planar 4:2:0 format with vpx color space */ |
| 58 | VPX_IMG_FMT_VPXI420 = VPX_IMG_FMT_PLANAR | 4, |
| 59 | VPX_IMG_FMT_I422 = VPX_IMG_FMT_PLANAR | 5, |
| 60 | VPX_IMG_FMT_I444 = VPX_IMG_FMT_PLANAR | 6, |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 61 | VPX_IMG_FMT_I440 = VPX_IMG_FMT_PLANAR | 7, |
| 62 | VPX_IMG_FMT_444A = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_HAS_ALPHA | 6, |
| 63 | VPX_IMG_FMT_I42016 = VPX_IMG_FMT_I420 | VPX_IMG_FMT_HIGHBITDEPTH, |
| 64 | VPX_IMG_FMT_I42216 = VPX_IMG_FMT_I422 | VPX_IMG_FMT_HIGHBITDEPTH, |
| 65 | VPX_IMG_FMT_I44416 = VPX_IMG_FMT_I444 | VPX_IMG_FMT_HIGHBITDEPTH, |
| 66 | VPX_IMG_FMT_I44016 = VPX_IMG_FMT_I440 | VPX_IMG_FMT_HIGHBITDEPTH |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 67 | } vpx_img_fmt_t; /**< alias for enum vpx_img_fmt */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 68 | |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 69 | /*!\brief List of supported color spaces */ |
| 70 | typedef enum vpx_color_space { |
| 71 | VPX_CS_UNKNOWN = 0, /**< Unknown */ |
| 72 | VPX_CS_BT_601 = 1, /**< BT.601 */ |
| 73 | VPX_CS_BT_709 = 2, /**< BT.709 */ |
| 74 | VPX_CS_SMPTE_170 = 3, /**< SMPTE.170 */ |
| 75 | VPX_CS_SMPTE_240 = 4, /**< SMPTE.240 */ |
| 76 | VPX_CS_BT_2020 = 5, /**< BT.2020 */ |
| 77 | VPX_CS_RESERVED = 6, /**< Reserved */ |
| 78 | VPX_CS_SRGB = 7 /**< sRGB */ |
| 79 | } vpx_color_space_t; /**< alias for enum vpx_color_space */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 80 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 81 | /**\brief Image Descriptor */ |
| 82 | typedef struct vpx_image { |
| 83 | vpx_img_fmt_t fmt; /**< Image Format */ |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 84 | vpx_color_space_t cs; /**< Color Space */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 85 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 86 | /* Image storage dimensions */ |
Vignesh Venkatasubramanian | 5a9753f | 2016-01-19 11:05:09 -0800 | [diff] [blame^] | 87 | unsigned int w; /**< Stored image width */ |
| 88 | unsigned int h; /**< Stored image height */ |
| 89 | unsigned int bit_depth; /**< Stored image bit-depth */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 90 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 91 | /* Image display dimensions */ |
| 92 | unsigned int d_w; /**< Displayed image width */ |
| 93 | unsigned int d_h; /**< Displayed image height */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 94 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 95 | /* Chroma subsampling info */ |
| 96 | unsigned int x_chroma_shift; /**< subsampling order, X */ |
| 97 | unsigned int y_chroma_shift; /**< subsampling order, Y */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 98 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 99 | /* Image data pointers. */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 100 | #define VPX_PLANE_PACKED 0 /**< To be used for all packed formats */ |
| 101 | #define VPX_PLANE_Y 0 /**< Y (Luminance) plane */ |
| 102 | #define VPX_PLANE_U 1 /**< U (Chroma) plane */ |
| 103 | #define VPX_PLANE_V 2 /**< V (Chroma) plane */ |
| 104 | #define VPX_PLANE_ALPHA 3 /**< A (Transparency) plane */ |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 105 | unsigned char *planes[4]; /**< pointer to the top left pixel for each plane */ |
| 106 | int stride[4]; /**< stride between rows for each plane */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 107 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 108 | int bps; /**< bits per sample (for packed formats) */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 109 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 110 | /* The following member may be set by the application to associate data |
| 111 | * with this image. |
| 112 | */ |
| 113 | void *user_priv; /**< may be set by the application to associate data |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 114 | * with this image. */ |
| 115 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 116 | /* The following members should be treated as private. */ |
| 117 | unsigned char *img_data; /**< private */ |
| 118 | int img_data_owner; /**< private */ |
| 119 | int self_allocd; /**< private */ |
Vignesh Venkatasubramanian | b08e2e2 | 2014-03-10 09:50:31 -0700 | [diff] [blame] | 120 | |
| 121 | void *fb_priv; /**< Frame buffer data associated with the image. */ |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 122 | } vpx_image_t; /**< alias for struct vpx_image */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 123 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 124 | /**\brief Representation of a rectangle on a surface */ |
| 125 | typedef struct vpx_image_rect { |
| 126 | unsigned int x; /**< leftmost column */ |
| 127 | unsigned int y; /**< topmost row */ |
| 128 | unsigned int w; /**< width */ |
| 129 | unsigned int h; /**< height */ |
| 130 | } vpx_image_rect_t; /**< alias for struct vpx_image_rect */ |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 131 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 132 | /*!\brief Open a descriptor, allocating storage for the underlying image |
| 133 | * |
| 134 | * Returns a descriptor for storing an image of the given format. The |
| 135 | * storage for the descriptor is allocated on the heap. |
| 136 | * |
| 137 | * \param[in] img Pointer to storage for descriptor. If this parameter |
| 138 | * is NULL, the storage for the descriptor will be |
| 139 | * allocated on the heap. |
| 140 | * \param[in] fmt Format for the image |
| 141 | * \param[in] d_w Width of the image |
| 142 | * \param[in] d_h Height of the image |
| 143 | * \param[in] align Alignment, in bytes, of the image buffer and |
| 144 | * each row in the image(stride). |
| 145 | * |
| 146 | * \return Returns a pointer to the initialized image descriptor. If the img |
| 147 | * parameter is non-null, the value of the img parameter will be |
| 148 | * returned. |
| 149 | */ |
| 150 | vpx_image_t *vpx_img_alloc(vpx_image_t *img, |
| 151 | vpx_img_fmt_t fmt, |
| 152 | unsigned int d_w, |
| 153 | unsigned int d_h, |
| 154 | unsigned int align); |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 155 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 156 | /*!\brief Open a descriptor, using existing storage for the underlying image |
| 157 | * |
| 158 | * Returns a descriptor for storing an image of the given format. The |
| 159 | * storage for descriptor has been allocated elsewhere, and a descriptor is |
| 160 | * desired to "wrap" that storage. |
| 161 | * |
| 162 | * \param[in] img Pointer to storage for descriptor. If this parameter |
| 163 | * is NULL, the storage for the descriptor will be |
| 164 | * allocated on the heap. |
| 165 | * \param[in] fmt Format for the image |
| 166 | * \param[in] d_w Width of the image |
| 167 | * \param[in] d_h Height of the image |
| 168 | * \param[in] align Alignment, in bytes, of each row in the image. |
| 169 | * \param[in] img_data Storage to use for the image |
| 170 | * |
| 171 | * \return Returns a pointer to the initialized image descriptor. If the img |
| 172 | * parameter is non-null, the value of the img parameter will be |
| 173 | * returned. |
| 174 | */ |
| 175 | vpx_image_t *vpx_img_wrap(vpx_image_t *img, |
| 176 | vpx_img_fmt_t fmt, |
| 177 | unsigned int d_w, |
| 178 | unsigned int d_h, |
| 179 | unsigned int align, |
| 180 | unsigned char *img_data); |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 181 | |
| 182 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 183 | /*!\brief Set the rectangle identifying the displayed portion of the image |
| 184 | * |
| 185 | * Updates the displayed rectangle (aka viewport) on the image surface to |
| 186 | * match the specified coordinates and size. |
| 187 | * |
| 188 | * \param[in] img Image descriptor |
| 189 | * \param[in] x leftmost column |
| 190 | * \param[in] y topmost row |
| 191 | * \param[in] w width |
| 192 | * \param[in] h height |
| 193 | * |
| 194 | * \return 0 if the requested rectangle is valid, nonzero otherwise. |
| 195 | */ |
| 196 | int vpx_img_set_rect(vpx_image_t *img, |
| 197 | unsigned int x, |
| 198 | unsigned int y, |
| 199 | unsigned int w, |
| 200 | unsigned int h); |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 201 | |
| 202 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 203 | /*!\brief Flip the image vertically (top for bottom) |
| 204 | * |
| 205 | * Adjusts the image descriptor's pointers and strides to make the image |
| 206 | * be referenced upside-down. |
| 207 | * |
| 208 | * \param[in] img Image descriptor |
| 209 | */ |
| 210 | void vpx_img_flip(vpx_image_t *img); |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 211 | |
hkuang | ba164df | 2013-06-19 15:33:45 -0700 | [diff] [blame] | 212 | /*!\brief Close an image descriptor |
| 213 | * |
| 214 | * Frees all allocated storage associated with an image descriptor. |
| 215 | * |
| 216 | * \param[in] img Image descriptor |
| 217 | */ |
| 218 | void vpx_img_free(vpx_image_t *img); |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 219 | |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 220 | #ifdef __cplusplus |
Vignesh Venkatasubramanian | b08e2e2 | 2014-03-10 09:50:31 -0700 | [diff] [blame] | 221 | } // extern "C" |
Johann | 1b362b1 | 2012-10-10 11:46:26 -0700 | [diff] [blame] | 222 | #endif |
Vignesh Venkatasubramanian | b08e2e2 | 2014-03-10 09:50:31 -0700 | [diff] [blame] | 223 | |
| 224 | #endif // VPX_VPX_IMAGE_H_ |