ScreenCapture

Class

Control whether screen recognition reuses captured images during the current macro run. Normally, a captured image can be reused for up to 100 ms. Call these methods directly on ScreenCapture; do not create an instance.

Syntax

ScreenCapture

This class cannot be constructed directly.

Returns

—

Example

# Reuse one captured frame for several screen checks
ScreenCapture.cache_on()
color = Color.get(Point(500, 900))
hit = Region.full_screen().find("enemy", timeout=0)
ScreenCapture.cache_off()

# Prefer the freshest available frame for a short recognition burst
ScreenCapture.auto_cache_off(duration_ms=1000)
hit = Region.full_screen().find("enemy", timeout=800, rate=30)

# Disable without a timer, then restore automatic caching explicitly
ScreenCapture.auto_cache_off()
hit = Region.full_screen().find("enemy", timeout=2000, rate=30)
ScreenCapture.auto_cache_on()

Methods

4 methods

ScreenCapture.cache_on

Static Method

Keep one captured screen image for repeated checks until cache_off() or the macro run ends. Use the next available image, or the latest valid image if no new one is ready. This takes priority over automatic reuse settings and does not request screen-capture permission.

Syntax

ScreenCapture.cache_on()

Returns

None — No return value.

Example

# Pin one shared frame for two recognition passes
ScreenCapture.cache_on()
region = Region(100, 200, 300, 400)
first = region.find("start", 0)
second = region.find("confirm", 0)
ScreenCapture.cache_off()
print(first.found, second.found)

ScreenCapture.cache_off

Static Method

Stop keeping the image selected by cache_on(). Automatic reuse settings stay unchanged, so a recent image may still be reused. Also call auto_cache_off() when each check needs the newest available image.

Syntax

ScreenCapture.cache_off()

Returns

None — No return value.

Example

# Remove explicit pinning before the next scan
ScreenCapture.cache_off()
region = Region(100, 200, 300, 400)
print(region.find("start", 0).found)

ScreenCapture.auto_cache_off

Static Method

Turn off automatic image reuse so capture requests seek the newest available image. Return immediately; a duration starts at this call, and calling again replaces it. Applies to bitmap, raw-image, TFLite, and pixel capture. This can increase processing and battery use without making execution faster or forcing Android to draw new pixels; waiting for an image remains limited. It does not cancel cache_on() or request capture permission.

Syntax

ScreenCapture.auto_cache_off(duration_ms=None)

Parameters

Name	Description
`duration_msNumber \| None`	Duration in positive whole milliseconds (100 and 100.0 are valid). Omit or use None to stay off until auto_cache_on() or the macro run ends. Zero, negative, fractional, string, boolean, and overflowing values raise an error. Optional · Positional or named Default: `None`

Returns

None — No return value.

Example

# Temporarily bypass automatic cache; explicit pinning is separate
ScreenCapture.cache_off()
ScreenCapture.auto_cache_off(1000)
region = Region(100, 200, 300, 400)
print(region.find("start", 500).found)
ScreenCapture.auto_cache_on()

ScreenCapture.auto_cache_on

Static Method

Allow automatic image reuse again immediately, canceling any previous off period. The macro also restores this when its run ends. This does not cancel cache_on(), request capture permission, or wait.

Syntax

ScreenCapture.auto_cache_on()

Returns

None — No return value.

Example

# Restore normal automatic frame reuse
ScreenCapture.auto_cache_on()
region = Region(100, 200, 300, 400)
print(region.find("start", 0).found)