JavaScript Patch API
Patch
new Patch() constructor
Creates a new patch object. You should create exactly one of these objects, set its properties.
Patch.inputs array
An array of PatchInput objects that define the input ports to the patch. This property may only be defined at the top-level; you may not update it later during patch execution.
Patch.outputs array
An array of PatchOutput objects that define the output ports to the patch. This property may only be defined at the top-level; you may not update it later during patch execution.
Patch.loopAware boolean (default: false)
Set this property to true if this patch is capable of processing values in an Origami loop. Use PatchInput.values array to access values from loops.
If you don’t set this property to true, then multiple copies of the patch’s JavaScript environment will be created to process each value in a loop.
Patch.alwaysNeedsToEvaluate boolean (default: false)
Set this property to true if you need the the patch to be evaluated on every frame. In most cases this is not needed and will only affect performance negatively. Avoid setting this to true.
Patch.evaluate() function
Define the patch logic in this function. It will be called when needed based on the Engine run loop or every single frame when Patch.alwaysNeedsToEvaluate is set to true.
PatchInput
new PatchInput(name, type, [defaultValue]) constructor
Use this constructor to create a new input port for the patch. You must give the port a name (which may be the empty string) and a type (from the types enum). You may also give the input a default value; if you don’t supply one, the default default value for the type you selected will be used.
PatchInput.name string
The name of the input port, which is displayed next to the port in the Patch Graph.
PatchInput.type
The type of the input port. Must be one of the values from the types enum.
PatchInput.value read-only
The current value being passed into the input port.
PatchInput.values array, read-only
If the patch.loopAware property is set to true and the input port is receiving a loop as input, then this property is an array of the values in the loop. Otherwise, this property is an array containing a single value equal to PatchInput.value.
PatchInput.defaultValue
The default value for the input port.
PatchInput.isDirty() function
Returns true if the input port’s value has changed since the last time it was evaluated, or false otherwise.
PatchInput.readRising() function
Returns true if the input port has just changed to a nonzero/“truthy” value, or false otherwise. Useful when dealing with Pulses (see State & Pulses)
PatchInput.readFalling() function
Returns true if the input port has just changed to a zero/“falsey” value, or false otherwise. Useful when dealing with Pulses (see State & Pulses)
PatchOutput
new PatchOutput(name, type, [defaultValue]) constructor
Use this constructor to create a new output port for the patch. You must give the port a name (which may be the empty string) and a type (from the types enum). You may also give the input a default value; if you don’t supply one, the default default value for the type you selected will be used.
PatchOutput.name string
The name of the output port, which is displayed next to the port in the Patch Graph.
PatchOutput.type
The type of the output port. Must be one of the values from the types enum.
PatchOutput.value read-only
The current value being passed into the output port.
PatchOutput.values array, read-only
If the patch.loopAware property is set to true, you may set this property to output a loop of values from the port. The property must be an array, and the type of each element of the array must match the type of the port.
PatchOutput.defaultValue
The default value for the output port.
PatchOutput.pulse() function
If this ouput’s type is PULSE, you may call this function to send a pulse on this output port.
Image
new Image(arrayBuffer, width, height) constructor
Use this constructor to create a new Image from an ArrayBuffer. The Array Buffer is expected to be as RGBA with each component being a value from 0-255. You also need to provide the width and height of the image and those dimensions must match the size of the Array Buffer.
new Image(image, size) constructor
Use this constructor to create a new Image from an existing one. The second parameter must be a SIZE object which allows you to resize the original image.
new Image(size) constructor
Use this constructor to create an empty Image. You must provide a SIZE object to create the buffer for the image. Later you can use setPixelAt(x, y, color) method to update the pixel values.
Image.width number
The Image width in pixels.
Image.height number
The Image height in pixels.
Image.format string
The Image format, can be something like “JPG”, “PNG”, “GIF”, etc.
Image.getPixelAt(x, y) function
Returns a Color object for the specified pixel position provided by x and y.
Image.setPixelAt(x, y, color) function
Sets the Color object at the pixel position provided by x and y. This can only used on images created within the JS context. Images being passed from patches are read-only.
Types
JavaScript patch does not support all the available data types in Origami, for example Sounds and Videos are not supported. Here’s the list of types that should be used for PatchInput and PatchOutput.
NUMBER
Default type for most Patches in Origami. It’s a 64-bit floating value that can be used generically.
PROGRESS
It’s an alias of NUMBER type. However can provide a semantic meaning that the intention for this number is to be normalized between 0-1 (see Progress)
POSITION
A vector type with 2 floating value components x and y For example: console.log('point:',point.x, point.y) (see Point)
SIZE
A vector type with 2 components like POSITION. The difference is the UI in the patch graph will treat the port as Size, but on the JavaScript side it should access its components with x representing the width and y representing the height.
ANCHOR
A vector type with 2 components like POSITION. The difference is the UI in the patch graph will treat the port as Anchor, but on the JavaScript side it should access its components with x and y values are expected to be in the range from 0-1.
POINT3D
A vector type with 3 floating value components x, y and z. For example: console.log('point:',point.x, point.y, point.z) (see Point3D)
POINT4D
A vector type with 4 floating value components x, y, z and w. For example: console.log('point:',point.x, point.y, point.z) (see Vec4)
COLOR
A vector type with 4 components like POINT4D. Those components need to be accessed with x, y, z and w Those components represent a color in the format of RGBA x being red, y being green, z being blue and w corresponds to the alpha channel. All values are normalized from 0-1 (see Color to RGB)
BOOLEAN
A type that can be true or false (see State & Pulses)
PULSE
Similar to BOOLEAN it can only hold a true or false but it is a transient value that is not persisted over time (see State & Pulses)
INTEGER
A numeric value that is not a fraction.
ENUM
The UI in the patch graph will display this as a list of values, but from the JavaScript perspective this is an INTEGER where the value represents the index of the element in the list.
STRING
This type represents a Text
JSON
This type represents a JSON Object (see JSON Object)
IMAGE
This type represents an Image Object (see Image Object)