gfx_break interface facilitates management of graphical
breakpoints. It is implemented by the graphics console.
A graphical breakpoint is defined by an image patch and a location on the screen, stored in a file using a bespoke format. Such a file can be created using the store method.
A breakpoint can then be activated using the add method. The console will check if the breakpoint matches the screen data every interval seconds in virtual time, using the clock that is associated to the console. Graphical breakpoints are therefore deterministic.
Note that the coordinates of the image patch is stored in the graphical breakpoint, and the breakpoint will only match on those coordinates.
The store method stores the specified rectangle on the screen in
the given file. It returns false if the rectangle is invalid or on
I/O error.
The add method activates a previously stored graphical
breakpoint, and returns a breakpoint ID, which is also passed to
cb when the breakpoint matches. The parameter name is
the breakpoint name that will appear in log messages. If name is
NULL then the file name is used. If oneshot is true, the
breakpoint will be removed automatically after the first match. The
interval parameter specifies how often the breakpoint is tested,
in seconds of simulated time. If cb is not NULL, then
this function will be called on breakpoint match, otherwise a match stops
the simulation. If the breakpoint file cannot be loaded, the method returns
-1.
The remove method deactivates a previously activated breakpoint.
The match method determines if a stored graphical breakpoint matches the current screen. It returns -1 if the breakpoint could not be loaded, 1 on match or 0 otherwise.
The info method returns the header of a stored graphical breakpoint, including the image patch coordinates. If the given file cannot be read or has invalid data, then a header containing all 0's is returned.
The export_png method converts the image data in a graphical breakpoint file to PNG format.
The add_bytes method behaves as add but reads the breakpoint data from memory instead of a file.
SIM_INTERFACE(gfx_break) {
bool (*store)(conf_object_t *NOTNULL obj,
const char *file,
int minx, int miny, int maxx, int maxy);
int64 (*add)(conf_object_t *NOTNULL obj,
const char *file, const char *name,
bool oneshot, double interval,
gfx_break_cb_t cb, lang_void *arg);
bool (*remove)(conf_object_t *NOTNULL obj, int64 break_id);
int (*match)(conf_object_t *NOTNULL obj, const char *file);
gbp_header_t (*info)(conf_object_t *NOTNULL obj, const char *file);
bool (*export_png)(conf_object_t *NOTNULL obj, const char *file,
const char *png_file);
int64 (*add_bytes)(conf_object_t *NOTNULL obj,
bytes_t data, const char *name,
bool oneshot, double interval,
gfx_break_cb_t cb, lang_void *arg);
};
#define GFX_BREAK_INTERFACE "gfx_break"