Video Frame functions in Automation 4

This file describes the interface used for reading frames from loaded videos.

---

Get a specific frame from the currently loaded video on which multiple other
functions are defined.

function aegisub.get_frame(frame_number, withSubtitles)

@frame_number (number)
  Number of frame to retrieve.

@withSubtitles (boolean)
  Optional. Whether to load with subtitles drawn on to the frame.

Returns: frame (userdata)
  The frame object defines multiple other functions. See below.

---

Get width of frame object.

function frame:width()

Returns: number
  Width in pixels.

---

Get height of frame object.

function frame:height()

Returns: number
  Height in pixels.

---

Get RGB pixel value at a certain position of frame object.

function frame:getPixel(x, y)

@x (number)
  Pixel to retrieve on the x-axis

@y (number)
  Pixel to retrieve on the y-axis

Returns: 3 values, all numbers
  1. R value of the pixel
  2. G value of the pixel
  3. B value of the pixel

---

Get ASS formated pixel value at a certain position of frame object.

function frame:getPixelFormatted(x, y)

@x (number)
  Pixel to retrieve on the x-axis

@y (number)
  Pixel to retrieve on the y-axis

Returns: string
  String in ASS format representing the pixel value. e.g. "&H0073FF&"

---

Get raw BGRA (alpha being irrelevant) data of frame object, whose pixel values
can then be accessed via LuaJIT's FFI.

The frame data is valid until the frame object is garbage-collected.

Example usage (which does not account for flipped frames for simplicity)

data, pitch = frame:data()
buf = require("ffi").cast("unsigned char *", data)
-- Get the R value of the pixel at coordinates (42, 34)
pix_val = buf[34 * pitch + 4 * 42 + 2]

function frame:data()

Returns: 3 values - a lightuserdata, a number, and a boolean
  1. Lightuserdata object which can be cast to "unsigned char *" via ffi.cast, a pointer
     to the raw frame data.
  2. The pitch of the frame data.
  3. Whether the frame is flipped upside-down.

---