WebM Codec SDK: vpx/vpx_image.h File Reference

WebM Codec SDK

Data Structures | Macros | Typedefs | Enumerations | Functions
vpx_image.h File Reference

Describes the vpx image descriptor and associated operations. More...

Go to the source code of this file.

## Data Structures
struct | vpx_image
| Image Descriptor. More...
struct | vpx_image_rect
| Representation of a rectangle on a surface. More...

## Macros
#define | VPX_IMAGE_ABI_VERSION
| Current ABI version number.
#define | VPX_IMG_FMT_PLANAR 0x100
#define | VPX_IMG_FMT_UV_FLIP 0x200
#define | VPX_IMG_FMT_HAS_ALPHA 0x400
#define | VPX_IMG_FMT_HIGHBITDEPTH 0x800
#define | VPX_PLANE_PACKED 0
#define | VPX_PLANE_Y 0
#define | VPX_PLANE_U 1
#define | VPX_PLANE_V 2
#define | VPX_PLANE_ALPHA 3

## Typedefs
typedef enum vpx_img_fmt | vpx_img_fmt_t
| List of supported image formats.
typedef enum vpx_color_space | vpx_color_space_t
| List of supported color spaces.
typedef enum vpx_color_range | vpx_color_range_t
| List of supported color range.
typedef struct vpx_image | vpx_image_t
| Image Descriptor.
typedef struct vpx_image_rect | vpx_image_rect_t
| Representation of a rectangle on a surface.

## Enumerations
enum | vpx_img_fmt { VPX_IMG_FMT_NONE , VPX_IMG_FMT_YV12 , VPX_IMG_FMT_I420 = 0x100 | 2 , VPX_IMG_FMT_I422 = 0x100 | 5 , VPX_IMG_FMT_I444 = 0x100 | 6 , VPX_IMG_FMT_I440 = 0x100 | 7 , VPX_IMG_FMT_NV12 = 0x100 | 9 , VPX_IMG_FMT_I42016 = VPX_IMG_FMT_I420 | 0x800 , VPX_IMG_FMT_I42216 = VPX_IMG_FMT_I422 | 0x800 , VPX_IMG_FMT_I44416 = VPX_IMG_FMT_I444 | 0x800 , VPX_IMG_FMT_I44016 = VPX_IMG_FMT_I440 | 0x800 }
| List of supported image formats. More...
enum | vpx_color_space { VPX_CS_UNKNOWN = 0 , VPX_CS_BT_601 = 1 , VPX_CS_BT_709 = 2 , VPX_CS_SMPTE_170 = 3 , VPX_CS_SMPTE_240 = 4 , VPX_CS_BT_2020 = 5 , VPX_CS_RESERVED = 6 , VPX_CS_SRGB = 7 }
| List of supported color spaces. More...
enum | vpx_color_range { VPX_CR_STUDIO_RANGE = 0 , VPX_CR_FULL_RANGE = 1 }
| List of supported color range. More...

## Functions
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)
| Open a descriptor, allocating storage for the underlying image.
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 stride_align, unsigned char *img_data)
| Open a descriptor, using existing storage for the underlying image.
int | vpx_img_set_rect (vpx_image_t *img, unsigned int x, unsigned int y, unsigned int w, unsigned int h)
| Set the rectangle identifying the displayed portion of the image.
void | vpx_img_flip (vpx_image_t *img)
| Flip the image vertically (top for bottom).
void | vpx_img_free (vpx_image_t *img)
| Close an image descriptor.

## Detailed Description

Describes the vpx image descriptor and associated operations.

## Macro Definition Documentation

## ◆ VPX_IMG_FMT_PLANAR

#define VPX_IMG_FMT_PLANAR 0x100

Image is a planar format.

## ◆ VPX_IMG_FMT_UV_FLIP

#define VPX_IMG_FMT_UV_FLIP 0x200

V plane precedes U in memory.

## ◆ VPX_IMG_FMT_HAS_ALPHA

#define VPX_IMG_FMT_HAS_ALPHA 0x400

Image has an alpha channel.

## ◆ VPX_IMG_FMT_HIGHBITDEPTH

#define VPX_IMG_FMT_HIGHBITDEPTH 0x800

Image uses 16bit framebuffer.

## ◆ VPX_PLANE_PACKED

#define VPX_PLANE_PACKED 0

To be used for all packed formats

## ◆ VPX_PLANE_Y

#define VPX_PLANE_Y 0

Y (Luminance) plane

## ◆ VPX_PLANE_U

#define VPX_PLANE_U 1

U (Chroma) plane

## ◆ VPX_PLANE_V

#define VPX_PLANE_V 2

V (Chroma) plane

## ◆ VPX_PLANE_ALPHA

#define VPX_PLANE_ALPHA 3

A (Transparency) plane

## Typedef Documentation

## ◆ vpx_img_fmt_t

typedef enum vpx_img_fmt vpx_img_fmt_t

List of supported image formats.

alias for enum vpx_img_fmt

## ◆ vpx_color_space_t

typedef enum vpx_color_space vpx_color_space_t

List of supported color spaces.

alias for enum vpx_color_space

## ◆ vpx_color_range_t

typedef enum vpx_color_range vpx_color_range_t

List of supported color range.

alias for enum vpx_color_range

## ◆ vpx_image_t

typedef struct vpx_image vpx_image_t

Image Descriptor.

alias for struct vpx_image

## ◆ vpx_image_rect_t

typedef struct vpx_image_rect vpx_image_rect_t

Representation of a rectangle on a surface.

alias for struct vpx_image_rect

## Enumeration Type Documentation

## ◆ vpx_img_fmt

enum vpx_img_fmt

List of supported image formats.

Enumerator
VPX_IMG_FMT_YV12 | Image is a planar format. V plane precedes U in memory. planar YVU
VPX_IMG_FMT_I420 | Image is a planar format.
VPX_IMG_FMT_I422 | Image is a planar format.
VPX_IMG_FMT_I444 | Image is a planar format.
VPX_IMG_FMT_I440 | Image is a planar format.
VPX_IMG_FMT_NV12 | Image is a planar format.
VPX_IMG_FMT_I42016 | Image uses 16bit framebuffer.
VPX_IMG_FMT_I42216 | Image uses 16bit framebuffer.
VPX_IMG_FMT_I44416 | Image uses 16bit framebuffer.
VPX_IMG_FMT_I44016 | Image uses 16bit framebuffer.

## ◆ vpx_color_space

enum vpx_color_space

List of supported color spaces.

Enumerator
VPX_CS_UNKNOWN | Unknown
VPX_CS_BT_601 | BT.601
VPX_CS_BT_709 | BT.709
VPX_CS_SMPTE_170 | SMPTE.170
VPX_CS_SMPTE_240 | SMPTE.240
VPX_CS_BT_2020 | BT.2020
VPX_CS_RESERVED | Reserved
VPX_CS_SRGB | sRGB

## ◆ vpx_color_range

enum vpx_color_range

List of supported color range.

Enumerator
VPX_CR_STUDIO_RANGE | Y [16..235], UV [16..240] (bit depth 8) Y [64..940], UV [64..960] (bit depth 10) Y [256..3760], UV [256..3840] (bit depth 12)
VPX_CR_FULL_RANGE | YUV/RGB [0..255] (bit depth 8) YUV/RGB [0..1023] (bit depth 10) YUV/RGB [0..4095] (bit depth 12)

## Function Documentation

## ◆ vpx_img_alloc()

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 )

Open a descriptor, allocating storage for the underlying image.

Returns a descriptor for storing an image of the given format. The storage for the image is allocated on the heap.

Parameters

  [in] | img | Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
  [in] | fmt | Format for the image
  [in] | d_w | Width of the image. Must not exceed 0x08000000 (2^27).
  [in] | d_h | Height of the image. Must not exceed 0x08000000 (2^27).
  [in] | align | Alignment, in bytes, of the image buffer and each row in the image (stride). Must not exceed 65536.

Returns
  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_img_wrap()

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 | stride_align,
|  | unsigned char * | img_data )

Open a descriptor, using existing storage for the underlying image.

Returns a descriptor for storing an image of the given format. The storage for the image has been allocated elsewhere, and a descriptor is desired to "wrap" that storage.

Parameters

  [in] | img | Pointer to storage for descriptor. If this parameter is NULL, the storage for the descriptor will be allocated on the heap.
  [in] | fmt | Format for the image
  [in] | d_w | Width of the image. Must not exceed 0x08000000 (2^27).
  [in] | d_h | Height of the image. Must not exceed 0x08000000 (2^27).
  [in] | stride_align | Alignment, in bytes, of each row in the image (stride). Must not exceed 65536.
  [in] | img_data | Storage to use for the image. The storage must outlive the returned image descriptor; it can be disposed of after calling vpx_img_free().

Returns
  Returns a pointer to the initialized image descriptor. If the img parameter is non-null, the value of the img parameter will be returned.

Note
  img_data is required to have a minimum allocation size that satisfies the requirements of the fmt, d_w, d_h and stride_align parameters. This size can be calculated as follows (see `img_alloc_helper` in the vpx_image.c file in the libvpx source tree for more detail):
  align = (1 << x_chroma_shift) - 1;
  w = (d_w + align) & ~align;
  align = (1 << y_chroma_shift) - 1;
  h = (d_h + align) & ~align;
  s = (fmt & VPX_IMG_FMT_PLANAR) ? w : (uint64_t)bps * w / 8;
  s = (fmt & VPX_IMG_FMT_HIGHBITDEPTH) ? s * 2 : s;
  s = (s + stride_align - 1) & ~((uint64_t)stride_align - 1);
  s = (fmt & VPX_IMG_FMT_HIGHBITDEPTH) ? s / 2 : s;
  alloc_size = (fmt & VPX_IMG_FMT_PLANAR) ? (uint64_t)h * s * bps / 8
  : (uint64_t)h * s;
  VPX_IMG_FMT_HIGHBITDEPTH
  #define VPX_IMG_FMT_HIGHBITDEPTH
  Definition vpx_image.h:35
  VPX_IMG_FMT_PLANAR
  #define VPX_IMG_FMT_PLANAR
  Definition vpx_image.h:32
  x_chroma_shift, y_chroma_shift and bps can be obtained by calling vpx_img_wrap with a non-`NULL` img_data parameter. The `vpx_image_t` pointer should not be used in other API calls until after a successful call to vpx_img_wrap with a valid image buffer. For example:
  vpx_img_wrap(img, fmt, d_w, d_h, stride_align, (unsigned char *)1);
  ... calculate buffer size and allocate buffer as described earlier
  vpx_img_wrap(img, fmt, d_w, d_h, stride_align, img_data);
  vpx_img_wrap
  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 stride_align, unsigned char *img_data)
  Open a descriptor, using existing storage for the underlying image.

## ◆ vpx_img_set_rect()

int vpx_img_set_rect | ( | vpx_image_t * | img,
|  | unsigned int | x,
|  | unsigned int | y,
|  | unsigned int | w,
|  | unsigned int | h )

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. Specifically, sets img->d_w, img->d_h, and elements of the img->planes[] array.

Parameters

  [in] | img | Image descriptor
  [in] | x | leftmost column
  [in] | y | topmost row
  [in] | w | width
  [in] | h | height

Returns
  0 if the requested rectangle is valid, nonzero (-1) otherwise.

## ◆ vpx_img_flip()

void vpx_img_flip | ( | vpx_image_t * | img | ) |

Flip the image vertically (top for bottom).

Adjusts the image descriptor's pointers and strides to make the image be referenced upside-down.

Parameters

  [in] | img | Image descriptor

## ◆ vpx_img_free()

void vpx_img_free | ( | vpx_image_t * | img | ) |

Close an image descriptor.

Frees all allocated storage associated with an image descriptor.

Parameters

  [in] | img | Image descriptor