Aegisub/automation/v4-docs/get-frame.txt
arch1t3cht f52b699493 lua: Add function to get raw frame data
This can be useful when scripts want to read the entire frame
and pass it on somewhere else (say, write it to a file or use some
library function on it).
2024-02-20 15:02:59 +01:00

93 lines
2 KiB
Text

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