ScreenCapture

Class

Static controls for shared screen capture during the current macro run. Automatic caching normally reuses frames for up to 100 ms to reduce capture work. For rapid recognition that needs the freshest available frame, use auto_cache_off(); this increases processing and battery use and does not guarantee faster execution or newly rendered pixels. Explicit cache_on() pins a frame separately and takes priority over automatic-cache settings.

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

Pin the next real screen-capture frame and reuse it until ScreenCapture.cache_off() is called. If no new buffer is queued yet, the latest valid frame from the current capture reader is pinned instead. This 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

Unpin the screen-capture frame without changing automatic-cache settings. A recent frame can still be reused while automatic caching is enabled. Use auto_cache_off() as well when recognition needs the freshest available frame.

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

Disable intentional automatic frame reuse for duration_ms milliseconds from this call, or until auto_cache_on() or the macro run ends when omitted or None. Calling again replaces the previous duration. Applies to shared bitmap, raw-frame, TFLite, and pixel capture; bypasses TTL reuse but still uses bounded frame acquisition and cannot force Android to render new pixels. Does not unpin cache_on(), request capture permission, or wait for the duration to pass.

Syntax

ScreenCapture.auto_cache_off(duration_ms=None)

Parameters

Name	Description
`duration_msNumber \| None`	Positive whole-number milliseconds (100 and 100.0 are both valid), or None for no time limit within this macro run. Zero, negative, fractional, string, boolean, and overflowing values are rejected. 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

Restore normal automatic frame caching immediately and cancel any timed or indefinite disable period. Does not unpin cache_on(), request capture permission, or wait. Automatic caching is also restored when the macro run ends.

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)