Struct CGImage

Source

pub struct CGImage { /* private fields */ }

Expand description

CGImage wrapper for screenshots

Represents a Core Graphics image returned from screenshot capture.

§Examples

let content = SCShareableContent::get()?;
let display = &content.displays()[0];
let filter = SCContentFilter::create().with_display(display).with_excluding_windows(&[]).build();
let config = SCStreamConfiguration::new()
    .with_width(1920)
    .with_height(1080);

let image = SCScreenshotManager::capture_image(&filter, &config)?;
println!("Screenshot size: {}x{}", image.width(), image.height());

Implementations§

Source §

impl CGImage

Source

pub fn width(&self) -> usize

Get image width in pixels

§Examples

let image = SCScreenshotManager::capture_image(&filter, &config)?;
let width = image.width();
println!("Width: {}", width);

Source

pub fn height(&self) -> usize

Get image height in pixels

Source

pub fn as_ptr(&self) -> *const c_void

Source

pub fn rgba_data(&self) -> Result<Vec<u8>, SCError>

Get raw RGBA pixel data

Returns a vector containing RGBA bytes (4 bytes per pixel). The data is in row-major order.

Performance note: every ScreenCaptureKit-produced CGImage is natively in BGRA. Forcing RGBA here makes CGContext.draw perform a per-pixel channel swap that costs ~20 ms on a 4K image. If your consumer accepts BGRA (Metal / wgpu / ffmpeg / most GPU pipelines), prefer bgra_data which skips the conversion.

Allocation note: this allocates a fresh Vec<u8> of width*height*4 bytes per call (~33 MB for 4K). For sustained screenshot loops, prefer rgba_data_into which writes into a caller-supplied buffer and lets you reuse the allocation across calls.

§Errors

Returns an error if the pixel data cannot be extracted

Source

pub fn bgra_data(&self) -> Result<Vec<u8>, SCError>

Get raw BGRA pixel data — the native ScreenCaptureKit pixel layout.

Returns a vector containing BGRA bytes (4 bytes per pixel) in row-major order. Each pixel is stored as [B, G, R, A].

This skips the BGRA → RGBA channel-swap that rgba_data performs inside CGContext.draw, saving roughly 20 ms on a 4K screenshot. Use this when the downstream consumer accepts BGRA natively — that includes Metal (MTLPixelFormat::BGRA8Unorm), wgpu (Bgra8Unorm), ffmpeg (AV_PIX_FMT_BGRA), and any direct upload to a kCVPixelFormatType_32BGRA pixel buffer.

For sustained capture loops, see bgra_data_into which writes into a caller-supplied buffer.

§Errors

Returns an error if the pixel data cannot be extracted.

Source

pub fn rgba_data_into(&self, dest: &mut [u8]) -> Result<usize, SCError>

Render the image’s RGBA bytes into a caller-supplied buffer.

dest must hold at least width * height * 4 bytes. Returns the number of bytes written on success. Use this for sustained screenshot loops to amortise the per-call ~33 MB-at-4K allocation across many frames — pre-allocate one Vec<u8>::with_capacity(...) (or set dest.len() = capacity once after the first call) and reuse it.

§Errors

Returns SCError::InternalError if dest is too small or the CGContext draw fails.

§Examples

// Pre-allocate once, reuse across many screenshots.
let mut buffer: Vec<u8> = vec![0; 1920 * 1080 * 4];
for _ in 0..100 {
    let img = SCScreenshotManager::capture_image(&filter, &config)?;
    img.rgba_data_into(&mut buffer)?;
    // process `buffer`...
}

Source

pub fn bgra_data_into(&self, dest: &mut [u8]) -> Result<usize, SCError>

Render the image’s BGRA bytes into a caller-supplied buffer.

Same shape as rgba_data_into but in the native source pixel layout — saves the per-pixel R↔B swap rgba_data_into performs. Combine with a reusable buffer for the fastest possible sustained-capture loop.

§Errors

Returns SCError::InternalError if dest is too small or the CGContext draw fails.

Source

pub fn save_png(&self, path: &str) -> Result<(), SCError>

Save the image to a PNG file

§Arguments

path - The file path to save the PNG to

§Errors

Returns an error if the image cannot be saved

§Examples

let image = SCScreenshotManager::capture_image(&filter, &config)?;
image.save_png("/tmp/screenshot.png")?;

Source

pub fn save(&self, path: &str, format: ImageFormat) -> Result<(), SCError>

Save the image to a file in the specified format

§Arguments

path - The file path to save the image to
format - The output format (PNG, JPEG, TIFF, GIF, BMP, or HEIC)

§Errors

Returns an error if the image cannot be saved

§Examples

let image = SCScreenshotManager::capture_image(&filter, &config)?;

// Save as PNG (lossless)
image.save("/tmp/screenshot.png", ImageFormat::Png)?;

// Save as JPEG with 85% quality
image.save("/tmp/screenshot.jpg", ImageFormat::Jpeg(0.85))?;

// Save as HEIC with 90% quality (smaller file size)
image.save("/tmp/screenshot.heic", ImageFormat::Heic(0.9))?;