Back to main page

Overview

Commands are sent by Camlet to plug-ins whenever something interesting happens. A list of all the commands and their response formats is given below. Commands beginning with _ do not have a response (and so camlet will go on without waiting for one).

_camera_connected command

Sent to plug-ins when a new camera is connected.

Arguments

• name - Human-readable name of the camera.
• hardware_id - Opaque string which stays the same for this physical camera.
  Stays the same even when it’s unplugged and reconnected, etc. However, it’s possible, though very unlikely, for two cameras to have the same hardware_id (e.g. if manufacturer does not give a serial number, and the names and supported formats of the devices are the same, etc.).
• device_path - Unique identifier for currently-connected cameras.
  May change if a camera is unplugged and reconnected, but guaranteed to be unique for two cameras that are connected at the same time.

_camera_disconnected command

Sent to plug-ins when a camera was disconnected.

Arguments

• device_path - Path to the device file, previously sent via the _camera_connected command.

frame command

Sent to plug-ins every time a frame is rendered.

Arguments

• menu_open - Provided with an empty value if a menu is open.
• camera_width/camera_height - width/height of the image produced by the camera.
• picture_width/picture_height - width/height of the displayed camera feed.
  This is different from camera_width/camera_height, since the picture is scaled to match the size of the window. Does not include any letterboxing added by camlet.
• window_width/window_height - width/height of the camlet window.
  This includes letterboxing (black bars), if there is any.
• new_camera_frame - Provided with an empty value if the camera has captured a new frame.
• active_camera - The device path of the currently-selected camera.
  This is not passed if no camera is connected.
• mode - The current mode of camlet.
  Currently this is always either photo or video, but more modes may be added in future major or minor versions.
• window_mouse_x/y - Position of the mouse relative to the top-left of the window.
• picture_mouse_x/y - Position of the mouse relative to the top-left of the displayed camera feed.
  May be negative, or greater than the picture width/height if the mouse is in the letterboxing.
• timer - Current number of seconds left for photo countdown timer.

Response

• camera_shader - GLSL shader code which the camera feed will pass through.
  If not provided, the current shader will be kept. If provided with an empty value, the current shader will be removed. camlet checks to see if the shader code you provided has actually changed when deciding whether to recompile, so it’s okay to pass this always.
• camera_uniforms - Uniform values to pass to camera_shader.
  If a uniform is not specified here, it will keeps its previous value. All uniforms are cleared when a new camera_shader is set. The format is described in the section Uniform Syntax.
• camera_bound_textures - Textures to bind for camera_shader.
  This is a comma-separated list of texture_slot:texture. Each texture must have been grabbed by some other command and not yet released. If this is not passed, the current textures are kept. If passed with an empty value, all current textures are cleared.
• overlay_shader - GLSL shader which the camera feed and letterboxing will pass through.
  These are always applied after camera shaders. These are not applied to photos or video recordings. If not provided, the current shader will be kept. If provided with an empty value, the current shader will be removed. camlet checks to see if the shader code you provided has actually changed when deciding whether to recompile, so it’s okay to pass this always.
• overlay_uniforms - Uniform values to pass to overlay_shader.
  If a uniform is not specified here, it will keeps its previous value. All uniforms are cleared when a new overlay_shader is set. The format is described in the section Uniform Syntax.
• overlay_bound_textures - Textures to bind for overlay_shader.
  This is a comma-separated list of texture_slot:texture. Each texture must have been grabbed by some other command and not yet released. If this is not passed, the current textures are kept. If passed with an empty value, all current textures are cleared.
• grab_camera - Provide to grab texture from unprocessed camera feed.
  Value must be empty.
• grab_processed - Provide to grab texture from camera feed, after passing it through all camera shaders.
  Value must be empty.
• release - Comma-separated list of textures to release.
  These will not actually be released until the frame is done rendering, so it’s okay to still use the textures one last time in camera_bound_textures, etc.
• stop_video - If provided, the current video recording (if any) will stop.
  The value must be empty.
• start_video - If provided, a new video recording will start.
  The value must be empty. Note that you will get a video_start and _video_started command as usual. If both this and stop_video are provided (possibly by different plug-ins), they are both respected; the current video recording will be stopped and a new one will be started. This does nothing if the menu is open.
• take_photo - If provided, a photo will be taken.
  The value must be empty. Note that you will get a photo and _photo_ok/_photo_error command as usual.
• set_mode - If set to photo, camlet will enter photo mode; if set to video, camlet will enter video mode.
  If different values are set from different plug-ins, an arbitrary winner is chosen. If any plug-in specifies start_video, this will always be ignored and camlet will enter video mode.
• switch_camera - Set to a camera’s device_path as given by _camera_connected to switch to that camera.
  If different values are set from different plug-ins, an arbitrary winner is chosen. Currently camlet stops the current video recording when the camera is switched, although this may change in a future major or minor version.
• upload_texture - Upload a texture from a file.
  The value is the path of the texture. It will be automatically detected as either PNG, JPEG, or the “raw” format of 4-byte little-endian width, 4-byte little-endian height, 1-byte number of channels (must be 1, 2, 3, or 4) followed by width × height × channels bytes of 8-bit-per-channel data. The texture ID will be given in a _grabbed command.
• download_texture - Download a texture to a file.
  The value must be structured as <texture>,<format>;<path>. <format> can be one of jpg,<quality>, png, or raw (4-byte little-endian width, 4-byte little-endian height, 1-byte channel count which is currently always 3, followed by width × height × 3 bytes of RGB888 data). Currently only one download per frame is supported.
• render_text - Text to render to a texture.
  The texture ID will be given in a _grabbed command.
• cancel_timer - Cancel the photo countdown timer.

_grabbed command

Sent to a plug-in to indicate that a texture was grabbed successfully. When you’re done with the texture in question, you should provide it in the release argument to the frame command, otherwise it will stay around in video memory forever.

NOTE: You may get the same texture twice from this command. For example, if there are no camera shaders, then the “unprocessed” frame is the same as the “processed” frame, so the same texture will be given for both. So make sure you don’t end up releasing the same texture twice.

Arguments

• texture - The texture that was grabbed.
  If at any point you don’t need this texture anymore, release it to free up GPU memory.
• source - The originator of the grab.
  This will be camera if the grab is due to grab_camera from a frame response, processed if the grab is due to grab_processed from a frame response, upload if the grab is due to upload_texture from a frame response, or text if the grab is due to render_text from a frame response.
• text_dimensions - Dimensions of text.
  Only passed if source = text. This is a newline-separated list of <x>,<y>,<width>,<height> (in 0-1 texture coordinates) for each line of text that was rendered.

init command

Sent to a plug-in when it is enabled.

Arguments

• version_major - Major version of camlet.
  This will be incremented any time a backwards-incompatible change is made to camlet. If the value is not one that the plug-in expects, the plug-in should respond with an error value.
• version_minor - Minor version of camlet.
  This will be incremented any time a backwards-compatible change is made to camlet. If the value is less than what the plug-in needs, the plug-in should respond with an error value.
• version_patch - Patch version of camlet.
  Can be ignored in practically all cases.

Response

Exactly one of ok or error must be provided.

• ok - Indicates that the plug-in was successfully initialized.
  Value must be empty.
• error - Indicates that the plug-in was not successfully initialized.
  Value should be a human-readable string that describes the error.
• setting_<ID> - Defines a setting for the plug-in.
  ID is a non-empty string which identifies the setting even if it is renamed; it must be 1-30 bytes long and may not start with _ or contain spaces. The value must have the format <type>;<name>;<default value>. Where <type> is one of number,<min>,<max>,<step>, select;<option1>,<option2>,<etc.> (allows the user to select between any of the optionN strings) with options being at most 63 bytes long, file, directory, or keyboard (allows the user to select a keyboard shortcut); <name> is a human-readable name of the setting; and <default value> is the default value for the setting. If any settings are defined, a _settings command will be sent immediately after the init command.

_key_down command

Sent when a key was pressed.

Arguments

• key - Number identifying the key.
• name - Human-readable name of the key.
  It’s okay to use this for comparisons (“did the user press the Left Shift key?”), but best not to use it for text input.
• scancode - Number identifying the physical location of the key on the keyboard.
  In almost all cases, you want key instead.
• repeat - Passed if this is a repeated key press from holding down the key.
• modifiers - A (possibly empty) string containing some of the letters of acgsACGS.
  Lowercase = left, uppercase = right, a/A = Alt, c/C = Ctrl, g/G = GUI (“Windows®” key), s/S = Shift.
• combo - A string which can be compared to the value of keyboard settings.

_key_up command

Sent when a key was released.

Arguments

• key - Number identifying the key.
  See https://wiki.libsdl.org/SDL3/SDL_Keycode for a list of numbers.
• name - Human-readable name of the key.
• scancode - Number identifying the physical location of the key on the keyboard.
  See https://wiki.libsdl.org/SDL3/SDL_Scancode for a list of numbers.

_mouse_down command

Sent when a mouse button was pressed.

Arguments

• window_x/y - Position of the mouse relative to the top-left of the window.
• picture_x/y - Position of the mouse relative to the top-left of the displayed camera feed.
  May be negative, or greater than the picture width/height if the mouse is in the letterboxing.
• button - Character identifying the mouse button.
  L = left, M = middle, R = right, X = X1, Y = X2.
• clicks - Number of clicks of the button (1 = single-click, 2 = double-click, etc.)

_mouse_scroll command

Sent when the mouse was scrolled.

Arguments

• physical_x/y - The horizontal/vertical movement of the mouse wheel, in a physical sense.
  Negative = left/up, positive = right/down. Ignores the user’s preferences about using “flipped”/“natural” scrolling.
• logical_x/y - The horizontal/vertical movement of the mouse wheel, in a logical sense.
  Negative = move the content left/up, positive = move the content right/down. If the user likes “flipped”/“natural” scrolling then this will be the negative of physical_x/y, otherwise it will be equal.
• window_x/y - Position of the mouse relative to the top-left of the window.
• picture_x/y - Position of the mouse relative to the top-left of the displayed camera feed.
  May be negative, or greater than the picture width/height if the mouse is in the letterboxing.

_mouse_up command

Sent when a mouse button was released.

Arguments

• window_x/y - Position of the mouse relative to the top-left of the window.
• picture_x/y - Position of the mouse relative to the top-left of the displayed camera feed.
  May be negative, or greater than the picture width/height if the mouse is in the letterboxing.
• button - Character identifying the mouse button.
  L = left, M = middle, R = right, X = X1, Y = X2.

photo command

Sent when a photo is about to be taken.

Arguments

• path - The absolute file path where the image will be saved.
• format - The image format to be used (one of png or jpg currently, but more may be added in the future).
• width/height - The width/height of the image that will be saved, in pixels.
• quality - The quality of the image.
  For format = jpg, this is the JPEG quality from 1 to 100. For format = png, this is not passed.

Response

• cancel - If provided, the photo will not be taken, but a flash will still be displayed (unless no_flash is also provided).
  Value must be empty.
• no_flash - If provided, no flash will be displayed.
  Value must be empty.
• camera_shader - GLSL shader which the photo (and subsequent camera feed) will pass through.
  If you only want to set it for the photo, just set it back to its previous value in your response to the next frame command. If not provided, the current shader will be kept. If provided with an empty value, the current shader will be removed.
• camera_uniforms - Uniform values to pass to camera_shader.
  If a uniform is not specified here, it will keeps its previous value. All uniforms are cleared when a new camera_shader is set. The format is described in the section Uniform Syntax.
• camera_bound_textures - Textures to bind for camera_shader.
  This is a comma-separated list of texture_slot:texture. Each texture must have been grabbed by some other command and not yet released. If this is not passed, the current textures are kept. If passed with an empty value, all current textures are cleared.

_photo_error command

Sent when photo saving fails, including due to being cancelled by a plug-in. To get information about the photo that would have been taken, refer to the preceding photo command.

_photo_ok command

Sent after a photo is saved to disk. To get information about the photo, refer to the preceding photo command.

_quit command

Sent when camlet quits. Note camlet will hang until the plug-in exits after sending this. After receiving this, exit as soon as possible.

_setting command

Sent once for each setting after init, then again whenever the user changes a setting.

Arguments

• id - The ID of the setting.
• value - The new value for the setting.
• done - If passed, indicates that this is the last setting.
  This is only ever passed during initialization, not when the user changes a setting through the menu.

video_start command

Sent when a video recording is about to start. This doesn’t mean the video recording will actually start, since a plug-in may cancel it. For that, listen out for the _video_started command.

Arguments

• path - The path where the video.
• width/height - The resolution of the video.
• framerate - The framerate of the video, in frames per second (this is not necessarily an integer).
• quality - The quality of the video, from 1 to 100.

Response

• cancel - If provided, the video will not be started.
  Value must be empty.

_video_started command

Sent when a video is started. To get information about the video, refer to the preceding video_start command.

_video_stop command

Sent when a video is stopped. To get information about the video, refer to the preceding video_start command.

Built-in shader variables

Some variables are automatically passed in to your shaders by camlet.

All shaders are provided with the in vec2 camlet_pos; input which is the coordinate of the pixel being rendered in convenient 0-to-1 coordinates, with (0,0) being the bottom-left of the camera feed (in the case of camera shaders) or window (in the case of overlay shaders). There is also the uniform sampler2D camlet_frame; which is the current frame to be processed. Lastly, out vec4 camlet_color; is the place where you should output the pixel color. So then a simple fragment shader which does nothing is given by

#version 130
in vec2 camlet_pos;
uniform sampler2D camlet_frame;
out vec4 camlet_color;

void main() {
    camlet_color = texture(camlet_frame, camlet_pos);
}

Identifiers starting with camlet_ are reserved for camlet and should not be used in your shaders except for the purposes described here.

Uniform syntax

This section describes the syntax of the camera_uniforms / overlay_uniforms argument.

Scalar values must be encoded in decimal. If the number contains any of .eE then it is treated as a floating-point uniform (e.g. 1e5, 3.5e+6, 0.0). Otherwise, if the number has the suffix u then it is treated as an unsigned integer (e.g. 0u). Otherwise, it is treated as a signed integer (e.g. 35, -36).

Vector values are encoded as a comma-separated list of scalar values, matrix values are encoded as a semicolon-separated list of vector values representing the columns of the matrix, array values are encoded as a pipe-separated lists of scalar/vector/matrix values. Trailing commas, semicolons, and pipes are allowed.