Generic Docs
This is just the documentation for all the stuff in GMESCAPI.
All functions that are prefixed with __ should not be used, and as such will not be explained.
count = gm_escapi_count();
Returns the amount of currently connected devices.
max_count = gm_escapi_max_count();
Returns the maximum amount of supported webcams. (as of now it's 16)
ver = gm_escapi_version();
Returns the ESCAPI version. (as of now it's 0x300 or $300 if you prefer 1.4 HEX syntax)
err = gm_escapi_last_error();
Returns the last error message, or an empty string if there were none so far.
name = gm_escapi_get_camera_name(0);
Returns the name of the camera for the device index.
gm_escapi_set_focus_frames(30);
Sets the amount of focus frames (see Home for more info).
This will set how many frames the camera should take before returning you the end result.
That will help the camera to gain focus and the image won't be blurry.
A value between 20 and 40 is usually enough.
f = gm_escapi_get_focus_frames();
Gets the amount of focus frames (see Home for more info).
gm_escapi_set_capture_prop(device, CAPTURE_HUE, 1, false, false);
Sets the camera setting, please note that your changes will be applied only after you capture a frame, or use gm_escapi_set_sys_capture_props to force an Apply (the camera LED will still turn on!).
If you don't want to touch the setting at all, set the last argument (ignore) to true
The auto argument is not supported by all properties, it means if the camera should try to autodetect the comfortable value for the setting.
The value is always a float between 0 and 1.
Keep in mind that the settings you set will be changed in the system, as such it's good practice to restore the setting after you're done.
val = gm_escapi_get_capture_prop(device, CAPTURE_HUE);
Gets the camera setting's value. It is always a float between 0 and 1, and is a percentage value. To get the percentage simply multiply the returned value by 100.
If the value is less than zero, it means that the property is not supported by the webcam's driver.
if (gm_escapi_is_capture_prop_auto(device, CAPTURE_HUE)) { // ...
Returns true if the camera setting is set to auto, or false if otherwise.
Keep in mind that even if you set auto to true, it may not be supported by the camera, which will only break things.
if (gm_escapi_is_capture_prop_ignore(device, CAPTURE_HUE)) { // ...
Returns true if the camera setting is ignored, or false if otherwise.
If you don't want to touch a certain camera setting, you may set the last argument in gm_escapi_set_capture_prop which will stop it from changing.
By default when you start the game, all properties are set to ignore, so nothing will overwrite, since when you set the properties, you're changing them in the system.
gm_escapi_reset_capture_props(device);
Resets all capture properties for a device index to 0, sets auto to false, and ignore to true.
You can also pass -1 as the device index to reset properties for all cameras.
gm_escapi_get_sys_capture_props(device);
Gets the current system's capture properties.
When you run the game, all properties are set to 0, but with this function you can get the current values stored in the system.
Keep in mind that the camera LED will turn on for a very short period of time.
You can also pass -1 to get properties for all cameras.
Then use the gm_escapi_get_capture_prop to get the camera settings.
This function is very useful if you want to save the current system settings, and restore them later.
gm_escapi_set_sys_capture_props(device);
Usually the camera settings are written to the system when you make a frame, but this function can be used to force-apply the settings without taking a picture (the camera LED will still turn on, for a very short period of time).
This function is very useful if you just want to restore the system properties and you don't need to take any pictures.
size = gm_escapi_offset(width, height, frames);
buffer_seek(buf, buffer_seek_relative, gm_escapi_offset(width, height, i));
This is a little helper function which you can use to either calculate the size needed to store n-frames, or an offset where the n-th frame is stored.
str = gm_escapi_prop_reflection(CAPTURE_HUE);
Turns the macro CAPTURE_ into a string, for example, for CAPTURE_HUE this will return a string CAPTURE_HUE.
Useful if you want to print all current values and you want to include the names in the log.
async_id = gm_escapi_capture_async(device, width, height, buf, 0);
Starts the asynchronous capture operation for a camera.
You need to pass in the device index, width, height, buffer, and the offset.
If you don't want to offset anything, just pass 0 for the offset.
It returns -1 if some of the arguments are wrong/make no sense, and an asynchronous id if all is fine.
After that, wait for the Async - Social event.
async_id = gm_escapi_capture_async_ext(device, width, height, buf, 0, frames);
Like gm_escapi_capture_async, but you can also set how many frames you want to store in a buffer.
Keep in mind that the buffer must be large enough to store multiple frames.
Also the focus frame setting is not ignored, every frame will be captured focus frames-many times, and then written to the buffer.
You can set focus frames to 1 if you don't wish to do any focus stuff and just want a sequence of frames.
status = gm_escapi_capture(device, width, height, buf, 0);
Not recommended, this is the synchronous variant of gm_escapi_capture_async, meaning the buffer will contain the frame right after the function returns.
But since capturing is a somewhat long process, the game will hang for a few seconds.
Since it's a synchronous function you don't need to wait for an Async - Social event, as such it doesn't return an async id, but rather, an error code.
-1 - error, use gm_escapi_last_error to get the last error.
0 - something's weird
1 - all good
Every Async - Social event from GMESCAPI will contain an event_type key, this is how you identify a certain event.
That's how I'm going to explain them, by the event_type key.
This is the event made by the gm_escapi_capture_async function.
Here are the keys that will be in the async_load map:
escapi_async_id - your asynchronous id returned by the function.
escapi_capture_result - -1 for an error, 0 if something's weird, and 1 for true.
escapi_focus_frames - focus frames setting that was used by the function.
escapi_device_id - device id that you requested the image for.
This is the event made by the gm_escapi_capture_async_ext function.
Here are the keys that will be in the async_load map:
escapi_async_id - your asynchronous id returned by the function.
escapi_capture_result_ext - -1 for an error, 0 if something's weird, and 1 for true.
escapi_focus_frames - focus frames setting that was used by the function.
escapi_device_id - device id that you requested the image for.
escapi_frames - the amount of frames you requested (not focus frames!).
There are also macroses that start from CAPTURE_, they should be used in the camera properties functions as the prop argument.
They're pretty self explanatory, just keep in mind that CAPTURE_PROP_MAX is not a valid camera property, rather, it's just the length of all the properties, so you can make a for loop such as:
for (var i = 0; i < CAPTURE_PROP_MAX; i++) { // ...
You can ask me on Discord nik#5351 if you didn't get something.