Capture

class pixel_forge.Capture

Capture class to capture frames from a monitor or a window.

The idea is to get either a Monitor or a Window as target, create a Capture object, and then start a capture thread that will update the internal frame of the Capture object whenever a new frame is available. Frames are only materialized, converted to NumPy arrays and passed over to Python when the user requests it to avoid unnecessary copies.

property active

True if the capture thread is running, False otherwise.

frame()

Convert the latest frame to an array and return it.

Returns:

The frame as a 3D NumPy array with dimensions [h w 4] (height x width x RGBA).

Raises:

RuntimeError – If the capture thread has not yet picked up a frame.

start(capture_target: Monitor | Window, await_first_frame: bool = True)

Start the capture.

This registeres an event handler that automatically updates the latest frame whenever a new frame is available. The frame can be accessed using frame(). Since the event handler runs in a separate thread, the first frame might not be available immediately. To ensure a frame is available before continuing, set await_first_frame to True. This will block the main thread until the first frame is available.

Parameters:

• capture_target – The monitor or window to capture.

• await_first_frame – Waits for the first frame to arrive if True.

stop()

Stop the capture thread, wait for it to join and invalidate the last frame.

This method is also called automatically when the object is garbage collected.