ExCubecl.Video (ExCubecl v0.4.0)

Video-specific GPU operations: overlay, mix, scale, crop, convert.

All operations run on GPU-resident frame buffers and return new frame buffers.

Examples

result = ExCubecl.Video.overlay(base_frame, overlay_frame, x: 100, y: 50, alpha: 0.8)
result = ExCubecl.Video.mix(frame_a, frame_b, mode: :dissolve, ratio: 0.5)
result = ExCubecl.Video.scale(frame, width: 1280, height: 720)
rgb = ExCubecl.Video.convert(frame, :yuv420p, :rgb24)
cropped = ExCubecl.Video.crop(frame, x: 0, y: 0, width: 640, height: 360)

Summary

Types

blend_mode()

frame()

pixel_format()

Functions

convert(frame, from_format, arg3)

Converts a video frame between pixel formats on the GPU.

crop(frame, opts)

Crops a video frame to the specified rectangle.

mix(frame_a, frame_b, opts \\ [])

Blends two video frames using the specified blend mode.

overlay(base, overlay, opts \\ [])

Alpha-composites overlay onto base at position (x, y) with opacity alpha.

scale(frame, opts)

Scales a video frame to the specified dimensions using GPU-accelerated resampling.

snapshot(video_frame, path)

Saves a snapshot of the frame to a PNG file.

Types

blend_mode()

@type blend_mode() :: :dissolve | :add | :multiply

frame()

@type frame() :: ExCubecl.VideoFrame.t()

pixel_format()

@type pixel_format() :: :yuv420p | :rgb24 | :rgba | :nv12

Functions

convert(frame, from_format, arg3)

@spec convert(frame(), pixel_format(), pixel_format()) ::
  {:ok, frame()} | {:error, term()}

Converts a video frame between pixel formats on the GPU.

Examples

rgb = ExCubecl.Video.convert(frame, :yuv420p, :rgb24)

crop(frame, opts)

@spec crop(
  frame(),
  keyword()
) :: {:ok, frame()} | {:error, term()}

Crops a video frame to the specified rectangle.

Options

:x — left edge (default 0)
:y — top edge (default 0)
:width — crop width
:height — crop height

mix(frame_a, frame_b, opts \\ [])

@spec mix(frame(), frame(), keyword()) :: {:ok, frame()} | {:error, term()}

Blends two video frames using the specified blend mode.

Options

:mode — blend mode: :dissolve (default), :add, or :multiply
:ratio — blend ratio 0.0 (all A) to 1.0 (all B), default 0.5

overlay(base, overlay, opts \\ [])

@spec overlay(frame(), frame(), keyword()) :: {:ok, frame()} | {:error, term()}

Alpha-composites overlay onto base at position (x, y) with opacity alpha.

Uses Porter-Duff Over compositing on the GPU.

Options

:x — horizontal offset (default 0)
:y — vertical offset (default 0)
:alpha — opacity 0.0–1.0 (default 1.0)

scale(frame, opts)

@spec scale(
  frame(),
  keyword()
) :: {:ok, frame()} | {:error, term()}

Scales a video frame to the specified dimensions using GPU-accelerated resampling.

Options

:width — target width in pixels
:height — target height in pixels

snapshot(video_frame, path)

@spec snapshot(frame(), String.t()) :: :ok | {:error, term()}

Saves a snapshot of the frame to a PNG file.

Note: This triggers a GPU→CPU readback, so it should be used sparingly.