Static controls for shared screen capture during the current macro run.
Syntax
ScreenCapture
This class cannot be constructed directly.
Parameters
None
Returns
—
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Serialized
Parallel execution: Conditional
Cache controls update shared policy without waiting for a frame or the requested duration. The next capture consumes that policy. A cache change affects every flow in the Run; these controls do not request capture permission.
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()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Pin the next real screen-capture frame and reuse it until ScreenCapture.cache_off() is called.
Syntax
ScreenCapture.cache_on()
Parameters
None
Returns
None — No return value.
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Serialized
Parallel execution: Conditional
Cache controls update shared policy without waiting for a frame or the requested duration. The next capture consumes that policy. A cache change affects every flow in the Run; these controls do not request capture permission.
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)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Unpin the screen-capture frame without changing automatic-cache settings.
Syntax
ScreenCapture.cache_off()
Parameters
None
Returns
None — No return value.
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Serialized
Parallel execution: Conditional
Cache controls update shared policy without waiting for a frame or the requested duration. The next capture consumes that policy. A cache change affects every flow in the Run; these controls do not request capture permission.
Example
# Remove explicit pinning before the next scan
ScreenCapture.cache_off()
region = Region(100, 200, 300, 400)
print(region.find("start", 0).found)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
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.
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.
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Serialized
Parallel execution: Conditional
Cache controls update shared policy without waiting for a frame or the requested duration. The next capture consumes that policy. A cache change affects every flow in the Run; these controls do not request capture permission.
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()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Restore normal automatic frame caching immediately and cancel any timed or indefinite disable period.
Syntax
ScreenCapture.auto_cache_on()
Parameters
None
Returns
None — No return value.
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Serialized
Parallel execution: Conditional
Cache controls update shared policy without waiting for a frame or the requested duration. The next capture consumes that policy. A cache change affects every flow in the Run; these controls do not request capture permission.
Example
# Restore normal automatic frame reuse
ScreenCapture.auto_cache_on()
region = Region(100, 200, 300, 400)
print(region.find("start", 0).found)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
