gavl: Video frames

# Video frames
[Video]

Container for video images. More...

## Data Structures
struct | gavl_video_frame_t
## Functions
gavl_video_frame_t * | gavl_video_frame_create (const gavl_video_format_t *format)
| Create video frame.
gavl_video_frame_t * | gavl_video_frame_create_nopad (const gavl_video_format_t *format)
| Create video frame without padding.
void | gavl_video_frame_destroy (gavl_video_frame_t *frame)
| Destroy a video frame.
void | gavl_video_frame_null (gavl_video_frame_t *frame)
| Zero all pointers in the video frame.
void | gavl_video_frame_clear (gavl_video_frame_t *frame, const gavl_video_format_t *format)
| Fill the frame with black color.
void | gavl_video_frame_fill (gavl_video_frame_t *frame, const gavl_video_format_t *format, float *color)
| Fill the frame with a user spefified color.
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.
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.
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.
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.
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.
void | gavl_video_frame_get_subframe (gavl_pixelformat_t pixelformat, const gavl_video_frame_t *src, gavl_video_frame_t *dst, gavl_rectangle_i_t *src_rect)
| Get a subframe of another frame.
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.
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.

## 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 intervalls 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_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_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.

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.

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.

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

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

Fill the frame with a user spefified 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

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.

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

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

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

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

void gavl_video_frame_get_subframe | ( | gavl_pixelformat_t | pixelformat,
|  | const gavl_video_frame_t * | src,
|  | gavl_video_frame_t * | dst,
|  | 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 speficied 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.

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 speficied 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.

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