gavl: Video frames

gavl

Data Structures | Functions
Video frames
Video

Container for video images. More...

## Data Structures
struct | gavl_video_frame_s

## Functions
GAVL_PUBLIC gavl_video_frame_t * | gavl_video_frame_create (const gavl_video_format_t *format)
| Create video frame.
GAVL_PUBLIC gavl_video_frame_t * | gavl_video_frame_create_nopad (const gavl_video_format_t *format)
| Create video frame without padding.
GAVL_PUBLIC void | gavl_video_frame_destroy (gavl_video_frame_t *frame)
| Destroy a video frame.
GAVL_PUBLIC void | gavl_video_frame_null (gavl_video_frame_t *frame)
| Zero all pointers in the video frame.
GAVL_PUBLIC void | gavl_video_frame_clear (gavl_video_frame_t *frame, const gavl_video_format_t *format)
| Fill the frame with black color.
GAVL_PUBLIC void | gavl_video_frame_fill (gavl_video_frame_t *frame, const gavl_video_format_t *format, const float *color)
| Fill the frame with a user specified color.
GAVL_PUBLIC void | gavl_video_frame_absdiff (gavl_video_frame_t *dst, const gavl_video_frame_t *src1, const gavl_video_frame_t *src2, const gavl_video_format_t *format)
| Fill the frame with the absolute difference of 2 source frames.
GAVL_PUBLIC void | gavl_video_frame_psnr (double *psnr, const gavl_video_frame_t *src1, const gavl_video_frame_t *src2, const gavl_video_format_t *format)
| Calculate the PSNR of 2 source frames.
GAVL_PUBLIC int | gavl_video_frame_ssim (const gavl_video_frame_t *src1, const gavl_video_frame_t *src2, gavl_video_frame_t *dst, const gavl_video_format_t *format)
| Calculate the SSIM of 2 source frames.
GAVL_PUBLIC void | gavl_video_frame_copy (const gavl_video_format_t *format, gavl_video_frame_t *dst, const gavl_video_frame_t *src)
| Copy one video frame to another.
GAVL_PUBLIC void | gavl_video_frame_copy_plane (const gavl_video_format_t *format, gavl_video_frame_t *dst, const gavl_video_frame_t *src, int plane)
| Copy a single plane from one video frame to another.
GAVL_PUBLIC void | gavl_video_frame_copy_flip_x (const gavl_video_format_t *format, gavl_video_frame_t *dst, const gavl_video_frame_t *src)
| Copy one video frame to another with horizontal flipping.
GAVL_PUBLIC void | gavl_video_frame_copy_flip_y (const gavl_video_format_t *format, gavl_video_frame_t *dst, const gavl_video_frame_t *src)
| Copy one video frame to another with vertical flipping.
GAVL_PUBLIC void | gavl_video_frame_copy_flip_xy (const gavl_video_format_t *format, gavl_video_frame_t *dst, const gavl_video_frame_t *src)
| Copy one video frame to another with horizontal and vertical flipping.
GAVL_PUBLIC void | gavl_video_frame_copy_metadata (gavl_video_frame_t *dst, const gavl_video_frame_t *src)
| Copy metadata of one video frame to another.
GAVL_PUBLIC void | gavl_video_frame_get_subframe (gavl_pixelformat_t pixelformat, const gavl_video_frame_t *src, gavl_video_frame_t *dst, const gavl_rectangle_i_t *src_rect)
| Get a subframe of another frame.
GAVL_PUBLIC void | gavl_video_frame_get_field (gavl_pixelformat_t pixelformat, const gavl_video_frame_t *src, gavl_video_frame_t *dst, int field)
| Get a field from a frame.
GAVL_PUBLIC void | gavl_video_frame_dump (gavl_video_frame_t *frame, const gavl_video_format_t *format, const char *namebase)
| Dump a video frame to files.
GAVL_PUBLIC void | gavl_video_frame_dump_metadata (const gavl_video_format_t *format, const gavl_video_frame_t *frame)
| Dump a metadata of a video frame.
GAVL_PUBLIC void | gavl_video_frame_set_strides (gavl_video_frame_t *frame, const gavl_video_format_t *format)
| Set the strides according to the format.
GAVL_PUBLIC void | gavl_video_frame_set_planes (gavl_video_frame_t *frame, const gavl_video_format_t *format, uint8_t *buffer)
| Set the frames according to the format.
GAVL_PUBLIC int | gavl_video_frame_continuous (const gavl_video_format_t *format, const gavl_video_frame_t *frame)
| Check if a video frame uses a continuous memory block.
GAVL_PUBLIC int | gavl_video_frame_extract_channel (const gavl_video_format_t *format, gavl_color_channel_t ch, const gavl_video_frame_t *src, gavl_video_frame_t *dst)
| Extract one channel of a video frame into a grayscale image.
GAVL_PUBLIC int | gavl_video_frame_insert_channel (const gavl_video_format_t *format, gavl_color_channel_t ch, const gavl_video_frame_t *src, gavl_video_frame_t *dst)
| Insert one channel from a grayscale image into a video frame.
GAVL_PUBLIC int | gavl_video_frames_equal (const gavl_video_format_t *format, const gavl_video_frame_t *f1, const gavl_video_frame_t *f2)
| Check if 2 video frames are bit-identical.

## Detailed Description

Container for video images.

This is the standardized method of storing one frame with video data. For planar formats, the first scanline starts at planes[0], subsequent scanlines start in intervals of strides[0] bytes. For planar formats, planes[0] will contain the luminance channel, planes[1] contains Cb (aka U), planes[2] contains Cr (aka V).

Video frames are created with gavl_video_frame_create and destroyed with gavl_video_frame_destroy. The memory can either be allocated by gavl (with memory aligned scanlines) or by the caller.

Gavl video frames are always oriented top->bottom left->right. If you must flip frames, use the functions gavl_video_frame_copy_flip_x, gavl_video_frame_copy_flip_y or gavl_video_frame_copy_flip_xy .

## Function Documentation

## ◆ gavl_video_frame_create()

GAVL_PUBLIC gavl_video_frame_t * gavl_video_frame_create | ( | const gavl_video_format_t * | format | ) |

Create video frame.

Parameters

  format | Format of the data to be stored in this frame or NULL

Creates a video frame for a given format and allocates buffers for the scanlines. To create a video frame from your custom memory, pass NULL for the format and you'll get an empty frame in which you can set the pointers manually. If scanlines are allocated, they are padded to that scanlines start at certain byte boundaries (currently 8).

## ◆ gavl_video_frame_create_nopad()

GAVL_PUBLIC gavl_video_frame_t * gavl_video_frame_create_nopad | ( | const gavl_video_format_t * | format | ) |

Create video frame without padding.

Parameters

  format | Format of the data to be stored in this frame or NULL

Same as gavl_video_frame_create but omits padding, so scanlines will always be adjacent in memory.

## ◆ gavl_video_frame_destroy()

GAVL_PUBLIC void gavl_video_frame_destroy | ( | gavl_video_frame_t * | frame | ) |

Destroy a video frame.

Parameters

  frame | A video frame

Destroys a video frame and frees all associated memory. If you used your custom memory to allocate the frame, call gavl_video_frame_null before.

## ◆ gavl_video_frame_null()

GAVL_PUBLIC void gavl_video_frame_null | ( | gavl_video_frame_t * | frame | ) |

Zero all pointers in the video frame.

Parameters

  frame | A video frame

Zero all pointers, so gavl_video_frame_destroy won't free them. Call this for video frames, which were created with a NULL format before destroying them.

## ◆ gavl_video_frame_clear()

GAVL_PUBLIC void gavl_video_frame_clear | ( | gavl_video_frame_t * | frame,
|  | const gavl_video_format_t * | format )

Fill the frame with black color.

Parameters

  frame | A video frame
  format | Format of the data in the frame

## ◆ gavl_video_frame_fill()

GAVL_PUBLIC void gavl_video_frame_fill | ( | gavl_video_frame_t * | frame,
|  | const gavl_video_format_t * | format,
|  | const float * | color )

Fill the frame with a user specified color.

Parameters

  frame | A video frame
  format | Format of the data in the frame
  color | Color components in RGBA format scaled 0.0 .. 1.0

## ◆ gavl_video_frame_absdiff()

GAVL_PUBLIC void gavl_video_frame_absdiff | ( | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src1,
|  | const gavl_video_frame_t * | src2,
|  | const gavl_video_format_t * | format )

Fill the frame with the absolute difference of 2 source frames.

Parameters

  format | Format of the data in the frame
  dst | A video frame
  src1 | First source frame
  src2 | Second source frame

Since 1.1.1

## ◆ gavl_video_frame_psnr()

GAVL_PUBLIC void gavl_video_frame_psnr | ( | double * | psnr,
|  | const gavl_video_frame_t * | src1,
|  | const gavl_video_frame_t * | src2,
|  | const gavl_video_format_t * | format )

Calculate the PSNR of 2 source frames.

Parameters

  psnr | Returns PSNR for all components (maximum 4)
  src1 | First source frame
  src2 | Second source frame
  format | Format of the data in the frame

Since 1.1.1

## ◆ gavl_video_frame_ssim()

GAVL_PUBLIC int gavl_video_frame_ssim | ( | const gavl_video_frame_t * | src1,
|  | const gavl_video_frame_t * | src2,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_format_t * | format )

Calculate the SSIM of 2 source frames.

Parameters

  src1 | First source frame
  src2 | Second source frame
  dst | Will contain the SSIM index for each pixel
  format | Format of the data in the frame

Returns
  1 if the SSIM could be computed, 0 else

This calculates the SSIM indices of each pixel for 2 source frames and stores them into dst. The source frames must have the pixelformat GAVL_GRAY_FLOAT implying that only the luminance component is considered. The destination also has the pixelformat GAVL_GRAY_FLOAT. If other pixelformats are passed to this function it will return 0 and nothing is done.

The SSIM algorithm is taken from the paper "Image Quality Assessment: From Error Visibility to Structural Similarity" by Z. Want et. al. published in IEEE Transactions on image processing, VOL. 13, NO. 4, APRIL 2004. Homepage of the author: http://www.ece.uwaterloo.ca/~z70wang/research/ssim/

Since 1.1.2

## ◆ gavl_video_frame_copy()

GAVL_PUBLIC void gavl_video_frame_copy | ( | const gavl_video_format_t * | format,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src )

Copy one video frame to another.

Parameters

  format | The format of the frames
  dst | Destination
  src | Source

The source and destination formats must be identical, as this routine does no format conversion. The scanlines however can be padded differently in the source and destination. This function only copies the image data. For copying the metadata (timestamp etc.) use# gavl_video_frame_copy_metadata.

## ◆ gavl_video_frame_copy_plane()

GAVL_PUBLIC void gavl_video_frame_copy_plane | ( | const gavl_video_format_t * | format,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src,
|  | int | plane )

Copy a single plane from one video frame to another.

Parameters

  format | The format of the frames
  dst | Destination
  src | Source
  plane | The plane to copy

Like gavl_video_frame_copy but copies only a single plane

## ◆ gavl_video_frame_copy_flip_x()

GAVL_PUBLIC void gavl_video_frame_copy_flip_x | ( | const gavl_video_format_t * | format,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src )

Copy one video frame to another with horizontal flipping.

Parameters

  format | The format of the frames
  dst | Destination
  src | Source

Like gavl_video_frame_copy but flips the image horizontally

## ◆ gavl_video_frame_copy_flip_y()

GAVL_PUBLIC void gavl_video_frame_copy_flip_y | ( | const gavl_video_format_t * | format,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src )

Copy one video frame to another with vertical flipping.

Parameters

  format | The format of the frames
  dst | Destination
  src | Source

Like gavl_video_frame_copy but flips the image vertically

## ◆ gavl_video_frame_copy_flip_xy()

GAVL_PUBLIC void gavl_video_frame_copy_flip_xy | ( | const gavl_video_format_t * | format,
|  | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src )

Copy one video frame to another with horizontal and vertical flipping.

Parameters

  format | The format of the frames
  dst | Destination
  src | Source

Like gavl_video_frame_copy but flips the image both horizontally and vertically

## ◆ gavl_video_frame_copy_metadata()

GAVL_PUBLIC void gavl_video_frame_copy_metadata | ( | gavl_video_frame_t * | dst,
|  | const gavl_video_frame_t * | src )

Copy metadata of one video frame to another.

Parameters

  dst | Destination
  src | Source

This function only copies the metadata (timestamp, duration, timecode). For copying the image data use gavl_video_frame_copy.

Since 1.1.0.

## ◆ gavl_video_frame_get_subframe()

GAVL_PUBLIC void gavl_video_frame_get_subframe | ( | gavl_pixelformat_t | pixelformat,
|  | const gavl_video_frame_t * | src,
|  | gavl_video_frame_t * | dst,
|  | const gavl_rectangle_i_t * | src_rect )

Get a subframe of another frame.

Parameters

  pixelformat | Pixelformat of the frames
  dst | Destination
  src | Source
  src_rect | Rectangular area in the source, which will be in the destination frame

This fills the pointers of dst from src such that the dst will represent the specified rectangular area. Note that no data are copied here. This means that dst must be created with NULL as the format argument and gavl_video_frame_null must be called before destroying dst.

When dealing with chroma subsampled pixelformats, you must call gavl_rectangle_i_align on src_rect before.

## ◆ gavl_video_frame_get_field()

GAVL_PUBLIC void gavl_video_frame_get_field | ( | gavl_pixelformat_t | pixelformat,
|  | const gavl_video_frame_t * | src,
|  | gavl_video_frame_t * | dst,
|  | int | field )

Get a field from a frame.

Parameters

  pixelformat | Pixelformat of the frames
  dst | Destination
  src | Source
  field | Field index (0 = top field, 1 = bottom field)

This fills the pointers and strides of the destination frame such that it will represent the specified field of the source frame. Note that no data are copied here. This means that dst must be created with NULL as the format argument and gavl_video_frame_null must be called before destroying dst.

## ◆ gavl_video_frame_dump()

GAVL_PUBLIC void gavl_video_frame_dump | ( | gavl_video_frame_t * | frame,
|  | const gavl_video_format_t * | format,
|  | const char * | namebase )

Dump a video frame to files.

Parameters

  frame | Video frame to dump
  format | Format of the video data in the frame
  namebase | Base for the output filenames

This is purely for debugging purposes: It dumps each plane of the frame into files <namebase>.p1, <namebase>.p2 etc

## ◆ gavl_video_frame_dump_metadata()

GAVL_PUBLIC void gavl_video_frame_dump_metadata | ( | const gavl_video_format_t * | format,
|  | const gavl_video_frame_t * | frame )

Dump a metadata of a video frame.

Parameters

  frame | Video frame

Metadata (= everything except the image data) are written to stderr for debugging purposes

## ◆ gavl_video_frame_set_strides()

GAVL_PUBLIC void gavl_video_frame_set_strides | ( | gavl_video_frame_t * | frame,
|  | const gavl_video_format_t * | format )

Set the strides according to the format.

Parameters

  frame | Video frame
  format | Format of the video data in the frame

This sets the strides array according to the format under the assumption, that no padding is done.

## ◆ gavl_video_frame_set_planes()

GAVL_PUBLIC void gavl_video_frame_set_planes | ( | gavl_video_frame_t * | frame,
|  | const gavl_video_format_t * | format,
|  | uint8_t * | buffer )

Set the frames according to the format.

Parameters

  frame | Video frame
  format | Format of the video data in the frame
  buffer | Start of the first scanline of the first plane

This sets the planes array from a raw buffer. If frame->strides[0] is zero, gavl_video_frame_set_strides is called before.

## ◆ gavl_video_frame_continuous()

GAVL_PUBLIC int gavl_video_frame_continuous | ( | const gavl_video_format_t * | format,
|  | const gavl_video_frame_t * | frame )

Check if a video frame uses a continuous memory block.

Parameters

  format | Format of the video data in the frame
  frame | Video frame

Returns
  1 if the planes are consecutive in memory and no padding is used, 0 else

Use this to check if a frame can be directly serialized or not.

## ◆ gavl_video_frame_extract_channel()

GAVL_PUBLIC int gavl_video_frame_extract_channel | ( | const gavl_video_format_t * | format,
|  | gavl_color_channel_t | ch,
|  | const gavl_video_frame_t * | src,
|  | gavl_video_frame_t * | dst )

Extract one channel of a video frame into a grayscale image.

Parameters

  format | Format of the source frame
  ch | Channel to extract
  src | Source frame
  dst | Destination where the extracted channel will be copied

This extracts one color channel into a grayscale image for separate processing. Use gavl_get_color_channel_format to obtain the format for the destination frame.

## ◆ gavl_video_frame_insert_channel()

GAVL_PUBLIC int gavl_video_frame_insert_channel | ( | const gavl_video_format_t * | format,
|  | gavl_color_channel_t | ch,
|  | const gavl_video_frame_t * | src,
|  | gavl_video_frame_t * | dst )

Insert one channel from a grayscale image into a video frame.

Parameters

  format | Format of the source frame
  ch | Channel to merge
  src | Source frame (grayscale image containing one channel)
  dst | Destination

This inserts one color channel from a grayscale image into a video frame (overwriting the previous contents of that channel). Use gavl_get_color_channel_format to obtain the format for the source grayscale frame.

## ◆ gavl_video_frames_equal()

GAVL_PUBLIC int gavl_video_frames_equal | ( | const gavl_video_format_t * | format,
|  | const gavl_video_frame_t * | f1,
|  | const gavl_video_frame_t * | f2 )

Check if 2 video frames are bit-identical.

Parameters

  format | Format
  f1 | First frame
  f2 | Second frame

Returns
  1 if the frames are equal, 0 else

Since 1.2.0