vpx_image.h 10.5 KB
Newer Older
John Koleszar's avatar
John Koleszar committed
1
/*
2
 *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
John Koleszar's avatar
John Koleszar committed
3
 *
4
 *  Use of this source code is governed by a BSD-style license
5
6
 *  that can be found in the LICENSE file in the root of the source
 *  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.
John Koleszar's avatar
John Koleszar committed
9
10
11
 */


James Zern's avatar
James Zern committed
12
/*!\file
John Koleszar's avatar
John Koleszar committed
13
14
15
 * \brief Describes the vpx image descriptor and associated operations
 *
 */
James Zern's avatar
James Zern committed
16
17
18
#ifndef VPX_VPX_IMAGE_H_
#define VPX_VPX_IMAGE_H_

John Koleszar's avatar
John Koleszar committed
19
20
21
22
#ifdef __cplusplus
extern "C" {
#endif

John Koleszar's avatar
John Koleszar committed
23
24
25
26
27
28
29
30
  /*!\brief Current ABI version number
   *
   * \internal
   * If this file is altered in any way that changes the ABI, this value
   * must be bumped.  Examples include, but are not limited to, changing
   * types, removing or reassigning enums, adding/removing/rearranging
   * fields to structures
   */
John Koleszar's avatar
John Koleszar committed
31
32
33
#define VPX_IMAGE_ABI_VERSION (1) /**<\hideinitializer*/


James Zern's avatar
James Zern committed
34
35
#define VPX_IMG_FMT_PLANAR     0x100  /**< Image is a planar format */
#define VPX_IMG_FMT_UV_FLIP    0x200  /**< V plane precedes U plane in memory */
James Zern's avatar
James Zern committed
36
#define VPX_IMG_FMT_HAS_ALPHA  0x400  /**< Image has an alpha channel component */
John Koleszar's avatar
John Koleszar committed
37
38


John Koleszar's avatar
John Koleszar committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
  /*!\brief List of supported image formats */
  typedef enum vpx_img_fmt {
    VPX_IMG_FMT_NONE,
    VPX_IMG_FMT_RGB24,   /**< 24 bit per pixel packed RGB */
    VPX_IMG_FMT_RGB32,   /**< 32 bit per pixel packed 0RGB */
    VPX_IMG_FMT_RGB565,  /**< 16 bit per pixel, 565 */
    VPX_IMG_FMT_RGB555,  /**< 16 bit per pixel, 555 */
    VPX_IMG_FMT_UYVY,    /**< UYVY packed YUV */
    VPX_IMG_FMT_YUY2,    /**< YUYV packed YUV */
    VPX_IMG_FMT_YVYU,    /**< YVYU packed YUV */
    VPX_IMG_FMT_BGR24,   /**< 24 bit per pixel packed BGR */
    VPX_IMG_FMT_RGB32_LE, /**< 32 bit packed BGR0 */
    VPX_IMG_FMT_ARGB,     /**< 32 bit packed ARGB, alpha=255 */
    VPX_IMG_FMT_ARGB_LE,  /**< 32 bit packed BGRA, alpha=255 */
    VPX_IMG_FMT_RGB565_LE,  /**< 16 bit per pixel, gggbbbbb rrrrrggg */
    VPX_IMG_FMT_RGB555_LE,  /**< 16 bit per pixel, gggbbbbb 0rrrrrgg */
    VPX_IMG_FMT_YV12    = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_UV_FLIP | 1, /**< planar YVU */
    VPX_IMG_FMT_I420    = VPX_IMG_FMT_PLANAR | 2,
    VPX_IMG_FMT_VPXYV12 = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_UV_FLIP | 3, /** < planar 4:2:0 format with vpx color space */
58
59
60
61
62
    VPX_IMG_FMT_VPXI420 = VPX_IMG_FMT_PLANAR | 4,
    VPX_IMG_FMT_I422    = VPX_IMG_FMT_PLANAR | 5,
    VPX_IMG_FMT_I444    = VPX_IMG_FMT_PLANAR | 6,
    VPX_IMG_FMT_444A    = VPX_IMG_FMT_PLANAR | VPX_IMG_FMT_HAS_ALPHA | 7
  } vpx_img_fmt_t; /**< alias for enum vpx_img_fmt */
John Koleszar's avatar
John Koleszar committed
63

James Zern's avatar
James Zern committed
64
65
66
67
68
#if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
#define IMG_FMT_PLANAR         VPX_IMG_FMT_PLANAR     /**< \deprecated Use #VPX_IMG_FMT_PLANAR */
#define IMG_FMT_UV_FLIP        VPX_IMG_FMT_UV_FLIP    /**< \deprecated Use #VPX_IMG_FMT_UV_FLIP */
#define IMG_FMT_HAS_ALPHA      VPX_IMG_FMT_HAS_ALPHA  /**< \deprecated Use #VPX_IMG_FMT_HAS_ALPHA */

John Koleszar's avatar
John Koleszar committed
69
70
71
  /*!\brief Deprecated list of supported image formats
   * \deprecated New code should use #vpx_img_fmt
   */
James Zern's avatar
James Zern committed
72
#define img_fmt   vpx_img_fmt
John Koleszar's avatar
John Koleszar committed
73
74
75
  /*!\brief alias for enum img_fmt.
   * \deprecated New code should use #vpx_img_fmt_t
   */
James Zern's avatar
James Zern committed
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
#define img_fmt_t vpx_img_fmt_t

#define IMG_FMT_NONE       VPX_IMG_FMT_NONE       /**< \deprecated Use #VPX_IMG_FMT_NONE */
#define IMG_FMT_RGB24      VPX_IMG_FMT_RGB24      /**< \deprecated Use #VPX_IMG_FMT_RGB24 */
#define IMG_FMT_RGB32      VPX_IMG_FMT_RGB32      /**< \deprecated Use #VPX_IMG_FMT_RGB32 */
#define IMG_FMT_RGB565     VPX_IMG_FMT_RGB565     /**< \deprecated Use #VPX_IMG_FMT_RGB565 */
#define IMG_FMT_RGB555     VPX_IMG_FMT_RGB555     /**< \deprecated Use #VPX_IMG_FMT_RGB555 */
#define IMG_FMT_UYVY       VPX_IMG_FMT_UYVY       /**< \deprecated Use #VPX_IMG_FMT_UYVY */
#define IMG_FMT_YUY2       VPX_IMG_FMT_YUY2       /**< \deprecated Use #VPX_IMG_FMT_YUY2 */
#define IMG_FMT_YVYU       VPX_IMG_FMT_YVYU       /**< \deprecated Use #VPX_IMG_FMT_YVYU */
#define IMG_FMT_BGR24      VPX_IMG_FMT_BGR24      /**< \deprecated Use #VPX_IMG_FMT_BGR24 */
#define IMG_FMT_RGB32_LE   VPX_IMG_FMT_RGB32_LE   /**< \deprecated Use #VPX_IMG_FMT_RGB32_LE */
#define IMG_FMT_ARGB       VPX_IMG_FMT_ARGB       /**< \deprecated Use #VPX_IMG_FMT_ARGB */
#define IMG_FMT_ARGB_LE    VPX_IMG_FMT_ARGB_LE    /**< \deprecated Use #VPX_IMG_FMT_ARGB_LE */
#define IMG_FMT_RGB565_LE  VPX_IMG_FMT_RGB565_LE  /**< \deprecated Use #VPX_IMG_FMT_RGB565_LE */
#define IMG_FMT_RGB555_LE  VPX_IMG_FMT_RGB555_LE  /**< \deprecated Use #VPX_IMG_FMT_RGB555_LE */
#define IMG_FMT_YV12       VPX_IMG_FMT_YV12       /**< \deprecated Use #VPX_IMG_FMT_YV12 */
#define IMG_FMT_I420       VPX_IMG_FMT_I420       /**< \deprecated Use #VPX_IMG_FMT_I420 */
#define IMG_FMT_VPXYV12    VPX_IMG_FMT_VPXYV12    /**< \deprecated Use #VPX_IMG_FMT_VPXYV12 */
#define IMG_FMT_VPXI420    VPX_IMG_FMT_VPXI420    /**< \deprecated Use #VPX_IMG_FMT_VPXI420 */
#endif /* VPX_CODEC_DISABLE_COMPAT */
John Koleszar's avatar
John Koleszar committed
97

John Koleszar's avatar
John Koleszar committed
98
99
100
  /**\brief Image Descriptor */
  typedef struct vpx_image {
    vpx_img_fmt_t fmt; /**< Image Format */
John Koleszar's avatar
John Koleszar committed
101

John Koleszar's avatar
John Koleszar committed
102
103
104
    /* Image storage dimensions */
    unsigned int  w;   /**< Stored image width */
    unsigned int  h;   /**< Stored image height */
John Koleszar's avatar
John Koleszar committed
105

John Koleszar's avatar
John Koleszar committed
106
107
108
    /* Image display dimensions */
    unsigned int  d_w;   /**< Displayed image width */
    unsigned int  d_h;   /**< Displayed image height */
John Koleszar's avatar
John Koleszar committed
109

John Koleszar's avatar
John Koleszar committed
110
111
112
    /* Chroma subsampling info */
    unsigned int  x_chroma_shift;   /**< subsampling order, X */
    unsigned int  y_chroma_shift;   /**< subsampling order, Y */
John Koleszar's avatar
John Koleszar committed
113

John Koleszar's avatar
John Koleszar committed
114
    /* Image data pointers. */
115
116
117
118
#define VPX_PLANE_PACKED 0   /**< To be used for all packed formats */
#define VPX_PLANE_Y      0   /**< Y (Luminance) plane */
#define VPX_PLANE_U      1   /**< U (Chroma) plane */
#define VPX_PLANE_V      2   /**< V (Chroma) plane */
James Zern's avatar
James Zern committed
119
#define VPX_PLANE_ALPHA  3   /**< A (Transparency) plane */
120
#if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
121
#define PLANE_PACKED     VPX_PLANE_PACKED
122
123
124
#define PLANE_Y          VPX_PLANE_Y
#define PLANE_U          VPX_PLANE_U
#define PLANE_V          VPX_PLANE_V
125
#define PLANE_ALPHA      VPX_PLANE_ALPHA
126
#endif
John Koleszar's avatar
John Koleszar committed
127
128
    unsigned char *planes[4];  /**< pointer to the top left pixel for each plane */
    int      stride[4];  /**< stride between rows for each plane */
John Koleszar's avatar
John Koleszar committed
129

John Koleszar's avatar
John Koleszar committed
130
    int     bps; /**< bits per sample (for packed formats) */
John Koleszar's avatar
John Koleszar committed
131

John Koleszar's avatar
John Koleszar committed
132
133
    /* The following member may be set by the application to associate data
     * with this image.
John Koleszar's avatar
John Koleszar committed
134
     */
John Koleszar's avatar
John Koleszar committed
135
136
    void    *user_priv; /**< may be set by the application to associate data
                         *   with this image. */
John Koleszar's avatar
John Koleszar committed
137

John Koleszar's avatar
John Koleszar committed
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
    /* The following members should be treated as private. */
    unsigned char *img_data;       /**< private */
    int      img_data_owner; /**< private */
    int      self_allocd;    /**< private */
  } vpx_image_t; /**< alias for struct vpx_image */

  /**\brief Representation of a rectangle on a surface */
  typedef struct vpx_image_rect {
    unsigned int x; /**< leftmost column */
    unsigned int y; /**< topmost row */
    unsigned int w; /**< width */
    unsigned int h; /**< height */
  } vpx_image_rect_t; /**< alias for struct vpx_image_rect */

  /*!\brief Open a descriptor, allocating storage for the underlying image
   *
   * Returns a descriptor for storing an image of the given format. The
   * storage for the descriptor is allocated on the heap.
   *
   * \param[in]    img       Pointer to storage for descriptor. If this parameter
   *                         is NULL, the storage for the descriptor will be
   *                         allocated on the heap.
   * \param[in]    fmt       Format for the image
   * \param[in]    d_w       Width of the image
   * \param[in]    d_h       Height of the image
John Koleszar's avatar
John Koleszar committed
163
164
   * \param[in]    align     Alignment, in bytes, of the image buffer and
   *                         each row in the image(stride).
John Koleszar's avatar
John Koleszar committed
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
   *
   * \return Returns a pointer to the initialized image descriptor. If the img
   *         parameter is non-null, the value of the img parameter will be
   *         returned.
   */
  vpx_image_t *vpx_img_alloc(vpx_image_t  *img,
                             vpx_img_fmt_t fmt,
                             unsigned int d_w,
                             unsigned int d_h,
                             unsigned int align);

  /*!\brief Open a descriptor, using existing storage for the underlying image
   *
   * Returns a descriptor for storing an image of the given format. The
   * storage for descriptor has been allocated elsewhere, and a descriptor is
   * desired to "wrap" that storage.
   *
   * \param[in]    img       Pointer to storage for descriptor. If this parameter
   *                         is NULL, the storage for the descriptor will be
   *                         allocated on the heap.
   * \param[in]    fmt       Format for the image
   * \param[in]    d_w       Width of the image
   * \param[in]    d_h       Height of the image
   * \param[in]    align     Alignment, in bytes, of each row in the image.
   * \param[in]    img_data  Storage to use for the image
   *
   * \return Returns a pointer to the initialized image descriptor. If the img
   *         parameter is non-null, the value of the img parameter will be
   *         returned.
   */
  vpx_image_t *vpx_img_wrap(vpx_image_t  *img,
                            vpx_img_fmt_t fmt,
                            unsigned int d_w,
                            unsigned int d_h,
                            unsigned int align,
                            unsigned char      *img_data);


  /*!\brief Set the rectangle identifying the displayed portion of the image
   *
   * Updates the displayed rectangle (aka viewport) on the image surface to
   * match the specified coordinates and size.
   *
   * \param[in]    img       Image descriptor
   * \param[in]    x         leftmost column
   * \param[in]    y         topmost row
   * \param[in]    w         width
   * \param[in]    h         height
   *
   * \return 0 if the requested rectangle is valid, nonzero otherwise.
   */
  int vpx_img_set_rect(vpx_image_t  *img,
                       unsigned int  x,
                       unsigned int  y,
                       unsigned int  w,
                       unsigned int  h);


  /*!\brief Flip the image vertically (top for bottom)
   *
   * Adjusts the image descriptor's pointers and strides to make the image
   * be referenced upside-down.
   *
   * \param[in]    img       Image descriptor
   */
  void vpx_img_flip(vpx_image_t *img);

  /*!\brief Close an image descriptor
   *
   * Frees all allocated storage associated with an image descriptor.
   *
   * \param[in]    img       Image descriptor
   */
  void vpx_img_free(vpx_image_t *img);
John Koleszar's avatar
John Koleszar committed
239
240

#ifdef __cplusplus
James Zern's avatar
James Zern committed
241
242
243
}  // extern "C"
#endif

James Zern's avatar
James Zern committed
244
#endif  // VPX_VPX_IMAGE_H_