Window Capture Functions

class autocv.core.window_capture.WindowCapture(hwnd: int = -1)

Base class for discovering Win32 windows and capturing their contents.

This class stores a target Win32 handle (hwnd) and offers helper methods for:

• enumerating visible windows (top-level) and child windows,

• resolving handles by title/class substring,

• capturing window pixels via a GDI BitBlt into a BGR numpy.ndarray.

property is_attached: bool

Return whether a handle value has been configured.

This property only checks the sentinel -1 value; it does not validate the handle with the OS.

property last_frame: ndarray[tuple[int, ...], dtype[uint8]] | None

Return the latest frame cached by capture_frame when persist is True.

attach(hwnd: int) → None

Attach to a new window handle and clear cached state.

detach() → None

Detach from any window handle and clear cached state.

invalidate_cache() → None

Reset cached bounds and the last captured frame.

get_window_bounds(*, use_cache: bool = False) → tuple[int, int, int, int]

Return the window bounds.

Parameters:

use_cache – When True, reuse cached bounds if available.

Returns:

Tuple of (left, top, right, bottom).

Return type:

Bounds

Raises:

InvalidHandleError – If no window handle is attached.

get_window_size(*, use_cache: bool = False) → tuple[int, int]

Return the window size.

Parameters:

use_cache – When True, reuse cached bounds if available.

Returns:

Tuple of (width, height).

Return type:

Size

Raises:

InvalidHandleError – If no window handle is attached.

static bounds_to_rect(bounds: tuple[int, int, int, int]) → tuple[int, int, int, int]

Convert absolute bounds into a window-relative rectangle.

Parameters:

bounds – Absolute screen-space bounds.

Returns:

Rectangle expressed as (x, y, width, height).

Return type:

Rect

get_windows_with_hwnds() → list[tuple[int, str]]

Return all visible top-level windows with non-empty titles.

get_hwnd_by_title(title: str, *, case_insensitive: bool = True) → int | None

Find the first window whose title contains the provided text.

Parameters:

• title – Title substring to search for.

• case_insensitive – When True, perform case-insensitive matching.

Returns:

Matching handle or None.

Return type:

WindowHandle | None

get_child_windows(hwnd: int | None = None) → list[tuple[int, str]]

Return child windows for the provided or current handle.

Parameters:

hwnd – Optional target handle; defaults to the current attachment.

Returns:

Child handles and class names.

Return type:

list[ChildWindowEntry]

Raises:

InvalidHandleError – If the instance is not attached to a valid handle (validated by the decorator).

set_hwnd_by_title(title: str, *, case_insensitive: bool = False) → bool

Update hwnd when a matching window title is discovered.

Parameters:

• title – Title substring to search for.

• case_insensitive – When True, perform case-insensitive matching.

Returns:

True when the handle was updated.

Return type:

bool

set_inner_hwnd_by_title(class_name: str) → bool

Update hwnd to the first child window whose class matches.

Parameters:

class_name – Substring of the child window class to match (case-insensitive).

Returns:

True when the handle was updated.

Return type:

bool

Raises:

InvalidHandleError – If no window handle is attached when enumerating child windows.

capture_frame(region: tuple[int, int, int, int] | None = None, *, persist: bool = True, use_cache: bool = False) → ndarray[tuple[int, ...], dtype[uint8]]

Capture the current window region into a contiguous BGR image.

Parameters:

• region – Optional capture region specified as (x, y, width, height) in window coordinates. Defaults to the full window when omitted.

• persist – When True, store the frame in last_frame for reuse.

• use_cache – When True, reuse cached window bounds when clamping the capture region.

Returns:

Captured frame in BGR channel order.

Return type:

NDArrayUint8

Raises:

• InvalidHandleError – If no window handle is attached.

• ValueError – If region falls completely outside the window bounds or has non-positive dimensions.