gavl: Rectangles

# Rectangles
[Video]

## Data Structures
struct | gavl_rectangle_i_t
struct | gavl_rectangle_f_t
## Functions
void | gavl_rectangle_i_crop_to_format (gavl_rectangle_i_t *r, const gavl_video_format_t *format)
| Crop an integer rectangle so it fits into the image size of a video format.
void | gavl_rectangle_f_crop_to_format (gavl_rectangle_f_t *r, const gavl_video_format_t *format)
| Crop a floating point rectangle so it fits into the image size of a video format.
void | gavl_rectangle_crop_to_format_noscale (gavl_rectangle_i_t *src_rect, gavl_rectangle_i_t *dst_rect, const gavl_video_format_t *src_format, const gavl_video_format_t *dst_format)
| Set 2 rectangles as source and destination when no scaling is available.
void | gavl_rectangle_crop_to_format_scale (gavl_rectangle_f_t *src_rect, gavl_rectangle_i_t *dst_rect, const gavl_video_format_t *src_format, const gavl_video_format_t *dst_format)
| Crop 2 rectangles to their formats when scaling is available.
void | gavl_rectangle_i_set_all (gavl_rectangle_i_t *r, const gavl_video_format_t *format)
| Let an integer rectangle span the whole image size of a video format.
void | gavl_rectangle_f_set_all (gavl_rectangle_f_t *r, const gavl_video_format_t *format)
| Let a float rectangle span the whole image size of a video format.
void | gavl_rectangle_i_crop_left (gavl_rectangle_i_t *r, int num_pixels)
| Crop an integer rectangle by some pixels from the left border.
void | gavl_rectangle_i_crop_right (gavl_rectangle_i_t *r, int num_pixels)
| Crop an integer rectangle by some pixels from the right border.
void | gavl_rectangle_i_crop_top (gavl_rectangle_i_t *r, int num_pixels)
| Crop an integer rectangle by some pixels from the top border.
void | gavl_rectangle_i_crop_bottom (gavl_rectangle_i_t *r, int num_pixels)
| Crop an integer rectangle by some pixels from the bottom border.
void | gavl_rectangle_f_crop_left (gavl_rectangle_f_t *r, double num_pixels)
| Crop a float rectangle by some pixels from the left border.
void | gavl_rectangle_f_crop_right (gavl_rectangle_f_t *r, double num_pixels)
| Crop a float rectangle by some pixels from the right border.
void | gavl_rectangle_f_crop_top (gavl_rectangle_f_t *r, double num_pixels)
| Crop a float rectangle by some pixels from the top border.
void | gavl_rectangle_f_crop_bottom (gavl_rectangle_f_t *r, double num_pixels)
| Crop a float rectangle by some pixels from the bottom border.
void | gavl_rectangle_i_align (gavl_rectangle_i_t *r, int h_align, int v_align)
| Align a rectangle.
void | gavl_rectangle_i_align_to_format (gavl_rectangle_i_t *r, const gavl_video_format_t *format)
| Align a rectangle to a format.
void | gavl_rectangle_i_copy (gavl_rectangle_i_t *dst, const gavl_rectangle_i_t *src)
| Copy an integer rectangle.
void | gavl_rectangle_f_copy (gavl_rectangle_f_t *dst, const gavl_rectangle_f_t *src)
| Copy a float rectangle.
void | gavl_rectangle_i_to_f (gavl_rectangle_f_t *dst, const gavl_rectangle_i_t *src)
| Convert an integer rectangle to a floating point rectangle.
void | gavl_rectangle_f_to_i (gavl_rectangle_i_t *dst, const gavl_rectangle_f_t *src)
| Convert a floating point rectangle to an integer rectangle.
int | gavl_rectangle_i_is_empty (const gavl_rectangle_i_t *r)
| Check if an integer rectangle is empty.
int | gavl_rectangle_f_is_empty (const gavl_rectangle_f_t *r)
| Check if a float rectangle is empty.
void | gavl_rectangle_fit_aspect (gavl_rectangle_i_t *dst_rect, const gavl_video_format_t *src_format, const gavl_rectangle_f_t *src_rect, const gavl_video_format_t *dst_format, float zoom, float squeeze)
| Calculate a destination rectangle for scaling.
void | gavl_rectangle_i_dump (const gavl_rectangle_i_t *r)
| Dump a rectangle to stderr.
void | gavl_rectangle_f_dump (const gavl_rectangle_f_t *r)
| Dump a floating point rectangle to stderr.

## Detailed Description

Define rectangular areas in a video frame

## Function Documentation

void gavl_rectangle_i_crop_to_format | ( | gavl_rectangle_i_t * | r,
|  | const gavl_video_format_t * | format |
| ) |  |  |

Crop an integer rectangle so it fits into the image size of a video format.

Parameters:

  | r | An integer rectangle
  | format | The video format into which the rectangle must fit

void gavl_rectangle_f_crop_to_format | ( | gavl_rectangle_f_t * | r,
|  | const gavl_video_format_t * | format |
| ) |  |  |

Crop a floating point rectangle so it fits into the image size of a video format.

Parameters:

  | r | A floating point rectangle
  | format | The video format into which the rectangle must fit

void gavl_rectangle_crop_to_format_noscale | ( | gavl_rectangle_i_t * | src_rect,
|  | gavl_rectangle_i_t * | dst_rect,
|  | const gavl_video_format_t * | src_format,
|  | const gavl_video_format_t * | dst_format |
| ) |  |  |

Set 2 rectangles as source and destination when no scaling is available.

Parameters:

  | src_rect | Source rectangle
  | dst_rect | Destination rectangle
  | src_format | Source format
  | dst_format | Destination format

This shrinks src_rect and dest_rect that neither is outside the image boundaries of the format. Both rectangles will have the same dimensions.

This function can be used for fitting a video image into a window for the case, that no scaling is available.

void gavl_rectangle_crop_to_format_scale | ( | gavl_rectangle_f_t * | src_rect,
|  | gavl_rectangle_i_t * | dst_rect,
|  | const gavl_video_format_t * | src_format,
|  | const gavl_video_format_t * | dst_format |
| ) |  |  |

Crop 2 rectangles to their formats when scaling is available.

Parameters:

  | src_rect | Source rectangle
  | dst_rect | Destination rectangle
  | src_format | Source format
  | dst_format | Destination format

This shrinks src_rect and dest_rect that neither is outside the image boundaries of the format.

void gavl_rectangle_i_set_all | ( | gavl_rectangle_i_t * | r,
|  | const gavl_video_format_t * | format |
| ) |  |  |

Let an integer rectangle span the whole image size of a video format.

Parameters:

  | r | An integer rectangle
  | format | The video format into which the rectangle must fit

void gavl_rectangle_f_set_all | ( | gavl_rectangle_f_t * | r,
|  | const gavl_video_format_t * | format |
| ) |  |  |

Let a float rectangle span the whole image size of a video format.

Parameters:

  | r | A float rectangle
  | format | The video format into which the rectangle must fit

void gavl_rectangle_i_crop_left | ( | gavl_rectangle_i_t * | r,
|  | int | num_pixels |
| ) |  |  |

Crop an integer rectangle by some pixels from the left border.

Parameters:

  | r | An integer rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_i_crop_right | ( | gavl_rectangle_i_t * | r,
|  | int | num_pixels |
| ) |  |  |

Crop an integer rectangle by some pixels from the right border.

Parameters:

  | r | An integer rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_i_crop_top | ( | gavl_rectangle_i_t * | r,
|  | int | num_pixels |
| ) |  |  |

Crop an integer rectangle by some pixels from the top border.

Parameters:

  | r | An integer rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_i_crop_bottom | ( | gavl_rectangle_i_t * | r,
|  | int | num_pixels |
| ) |  |  |

Crop an integer rectangle by some pixels from the bottom border.

Parameters:

  | r | An integer rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_f_crop_left | ( | gavl_rectangle_f_t * | r,
|  | double | num_pixels |
| ) |  |  |

Crop a float rectangle by some pixels from the left border.

Parameters:

  | r | A float rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_f_crop_right | ( | gavl_rectangle_f_t * | r,
|  | double | num_pixels |
| ) |  |  |

Crop a float rectangle by some pixels from the right border.

Parameters:

  | r | A float rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_f_crop_top | ( | gavl_rectangle_f_t * | r,
|  | double | num_pixels |
| ) |  |  |

Crop a float rectangle by some pixels from the top border.

Parameters:

  | r | A float rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_f_crop_bottom | ( | gavl_rectangle_f_t * | r,
|  | double | num_pixels |
| ) |  |  |

Crop a float rectangle by some pixels from the bottom border.

Parameters:

  | r | A float rectangle
  | num_pixels | The number of pixels by which the rectangle gets smaller

void gavl_rectangle_i_align | ( | gavl_rectangle_i_t * | r,
|  | int | h_align,
|  | int | v_align |
| ) |  |  |

Align a rectangle.

Parameters:

  | r | An integer rectangle
  | h_align | Horizontal alignment
  | v_align | Vertical alignment

This aligns a rectangle such that the horizontal and vertical coordinates are multiples of h_align and v_align respectively. When dealing with chroma subsampled formats, you must call this function with the return values of gavl_pixelformat_chroma_sub before taking subframes from video frames.

void gavl_rectangle_i_align_to_format | ( | gavl_rectangle_i_t * | r,
|  | const gavl_video_format_t * | format |
| ) |  |  |

Align a rectangle to a format.

Parameters:

  | r | An integer rectangle
  | format | A video format

The convenience function does the same as gavl_rectangle_i_align but takes a format as argument.

void gavl_rectangle_i_copy | ( | gavl_rectangle_i_t * | dst,
|  | const gavl_rectangle_i_t * | src |
| ) |  |  |

Copy an integer rectangle.

Parameters:

  | dst | Destination rectangle
  | src | Source rectangle

void gavl_rectangle_f_copy | ( | gavl_rectangle_f_t * | dst,
|  | const gavl_rectangle_f_t * | src |
| ) |  |  |

Copy a float rectangle.

Parameters:

  | dst | Destination rectangle
  | src | Source rectangle

void gavl_rectangle_i_to_f | ( | gavl_rectangle_f_t * | dst,
|  | const gavl_rectangle_i_t * | src |
| ) |  |  |

Convert an integer rectangle to a floating point rectangle.

Parameters:

  | dst | Destination rectangle
  | src | Source rectangle

void gavl_rectangle_f_to_i | ( | gavl_rectangle_i_t * | dst,
|  | const gavl_rectangle_f_t * | src |
| ) |  |  |

Convert a floating point rectangle to an integer rectangle.

Parameters:

  | dst | Destination rectangle
  | src | Source rectangle

int gavl_rectangle_i_is_empty | ( | const gavl_rectangle_i_t * | r | ) |

Check if an integer rectangle is empty.

Parameters:

  | r | Rectangle

Returns:
  1 if the rectangle is empty, 0 else.

A rectangle is considered to be empty if the width or height are <= 0.

int gavl_rectangle_f_is_empty | ( | const gavl_rectangle_f_t * | r | ) |

Check if a float rectangle is empty.

Parameters:

  | r | Rectangle

Returns:
  1 if the rectangle is empty, 0 else.

A rectangle is considered to be empty if the width or height are <= 0.

void gavl_rectangle_fit_aspect | ( | gavl_rectangle_i_t * | dst_rect,
|  | const gavl_video_format_t * | src_format,
|  | const gavl_rectangle_f_t * | src_rect,
|  | const gavl_video_format_t * | dst_format,
|  | float | zoom,
|  | float | squeeze |
| ) |  |  |

Calculate a destination rectangle for scaling.

Parameters:

  | dst_rect | Destination rectangle
  | src_format | Source format
  | src_rect | Source rectangle
  | dst_format | Destination format
  | zoom | Zoom factor
  | squeeze | Squeeze factor

Assuming we take src_rect from a frame in src_format, calculate the optimal dst_rect in dst_format. The source and destination display aspect ratio will be preserved unless it is changed with the squeeze parameter.

Zoom is a zoom factor (1.0 = 100 %). Squeeze is a value between -1.0 and 1.0, which changes the apsect ratio in both directions. 0.0 means unchanged.

Note that dst_rect might be outside the image dimensions of dst_format. If you don't like this, call gavl_rectangle_crop_to_format_scale afterwards.

Furthermore, the chroma subsampling is ignored by this function. If you you use the rectangles to fire up a gavl_video_scaler_t, this is no problem (the scaler will align the rectangles internally). You can align the destination rectangle manually using gavl_rectangle_i_align or gavl_rectangle_i_align_to_format.

void gavl_rectangle_i_dump | ( | const gavl_rectangle_i_t * | r | ) |

Dump a rectangle to stderr.

Parameters:

  | r | Rectangle

void gavl_rectangle_f_dump | ( | const gavl_rectangle_f_t * | r | ) |

Dump a floating point rectangle to stderr.

Parameters:

  | r | Floating point rectangle