This reference covers the entire JavaScript API (application programming interface) available in Conduit 2.0.
Although significant portions of this API are shared with modern web browsers like Firefox and Safari, there are also fundamental differences. For example the DOM (document object model) and its associated object types are only applicable to a web browser environment. Conduit's user interface layer is represented in JavaScript using Presenter objects, which are quite different from HTML elements.
Conduit uses a JSON-compatible text format for defining Presenter user interfaces separately from code. This concept is largely similar to XML UI formats on some other platforms. Conduit uses JSON because it's less verbose than XML and maps directly into JavaScript types. This PresenterJSON user interface definition format is documented separately [TBD].
Conduit Live 2 offers some additional JavaScript objects that allow direct access to its video capture/playback environment. Please refer to the Conduit Live documentation for more information.
Many of the objects in this reference are constructors: you can create new instances of these classes within your script using JavaScript's regular new operator. Examples of these constructable objects are Color, Canvas and MutableByteBuffer. Other objects are opaque classes: they are owned by Conduit and can't be constructed directly within a script, but instead are always obtained through API methods. Examples of opaque classes are Surface and Presenter. Opaque classes are indicated with an italicized title.
Table of contents:
These objects are part of the JavaScript standard. They are constructors except Math, which provides useful math constants (like Math.PI) and functions (like Math.sin()).
Refer to e.g. Mozilla's JavaScript 1.5 reference for the full specification.
A blob of binary data. Typically a ByteBuffer object represents the contents of a file. The file might have been loaded from disk (using the API available in the sys global) or received from a server over the network.
The data can be accessed as raw byte values. If you know the data contains text (and you know the text encoding), you can use the asString method to convert the data into a regular String object.
This class can't be constructed. (To create binary data objects in JavaScript, see MutableByteBuffer.)
| length | Number | read-only | |
| isMutable | Boolean | read-only |
Interprets the binary data as text according to the specified encoding. Valid values for encoding are: "utf-8", "utf-16", "ascii".
This method is a shorthand for getUnsignedByte.
Gets the byte value at the specified index in the buffer, interpreting the byte as a signed value.
Gets the byte value at the specified index in the buffer, interpreting the byte as an unsigned value.
Finds the first occurrence of the given byte value in the buffer.
The mutable subclass of ByteBuffer. All properties and methods of ByteBuffer are valid for this class.
Sets the byte value at the specified index in the buffer, converting value to an integer in range [-128, 127].
Sets the byte value at the specified index in the buffer, converting value to an integer in range [0, 255].
A color value. The color consists of four components: red, green, blue and alpha. Component values can be any floating-point numbers.
| red | Number | read/write | |
| green | Number | read/write | |
| blue | Number | read/write | |
| alpha | Number | read/write |
A collection of curve segments that can form a path or other graphical object.
| length | Number | read-only | |
| closed | Boolean | read/write |
Adds an arc or circle to the curve list. xc and yc define the center of the arc. angle1 and angle2 define (in radians) the extent of the angle. (To draw a full circle, use values 0 and 2*Math.PI for angle1 and angle2 respectively.)
Appends a curve to the curve list. The new curve starts at the end point of the last existing curve in the curve list and extends to (x, y). If there are no curves in the curve list, this method does nothing.
Valid values for curveTypeId are: "linear", "bezier", "catmull-rom".
Linear and Catmull-Rom curves do not require any additional control points. For Bézier curves, you should specify four extra arguments: the first control point's x and y coordinates, and the second control point's x and y coordinates.
Inserts a curve into the curve list. The curve starts at (x1, y1) and extends to (x2, y2).
Valid values for curveTypeId are: "linear", "bezier", "catmull-rom".
Linear and Catmull-Rom curves do not require any additional control points. For Bézier curves, you should specify four extra arguments: the first control point's x and y coordinates, and the second control point's x and y coordinates.
The last argument can optionally be an index to specify at which position the curve should be inserted in the curve list. (E.g. to insert at the start of the list, use 0 as the index.)
A reference to an image. This class can't be constructed; you can only obtain Image objects through API methods.
| width | Number | read-only | |
| height | Number | read-only |
This global object provides utility methods for converting JavaScript objects to the JSON string format and back.
This object complies to the "native JSON" standard as implemented in Firefox 3.5 and other new browsers.
(See e.g. Using native JSON in Firefox)
Returns an Object or Array which is the JavaScript representation of the JSON string if the conversion is successful.
Returns a String which is the JSON representation of the object if the conversion is successful.
This global object is available for scripts that are executed within the context of a Conduit node. It gives access to the node's parameters and assets. Parameters are the interface that is primarily visible to the user: sliders, buttons, and so on.
Assets are a way of storing persistent data within a node. They are stored in a list which is visible in the Assets tab for a scripted node in Conduit Editor. Assets can be text (String object), data (ByteBuffer object), images (Image object) or Conduit effects (ConduitEffect object). They can be dynamically set during a script's execution. This is the recommended way of storing data that needs to persist when a node is saved to disk.
| name | String | read-only | |
| parameterCount | Number | read-only | |
| assetCount | Number | read-only |
Gets the asset at the specified index in the node's assets list. Note that the indexes begin at 1.
Stores an object as an asset at the specified index in the node's assets list. Note that the indexes begin at 1.
Gets the value of the node's parameter with the specified index. Note that the indexes begin at 1.
Sets the value for the node's parameter with the specified index. Note that the indexes begin at 1.
Informs Conduit that a parameter's state has been modified. This is only necessary for custom parameters like tables whose contents are dependent on your script's internal state. Calling this method ensures that the parameter UI is updated.
Rendering using a Conduit effect is a potentially complex operation. A renderer object manages all the necessary state. This call gets a renderer that is compatible with the given conduit effect.
The renderer must not be retained by your script, but instead always fetched through this call for each render operation.
LIMITED AVAILABILITY: This method is only available within a Supernode.
The returned surface is a temporary surface suitable for rendering in the current script context. If the width and height arguments are omitted, the surface will match the size of the main rendering surface.
The surface must not be retained by your script, but instead always fetched through this call for each render operation.
LIMITED AVAILABILITY: This method is only available within a Supernode.
This global object allows JavaScript code to interact with the system. Methods are provided for printing strings to the system log and into Conduit's "trace window". An important system-level functionality is loading files from the local file system (this ability may be restricted for security reasons).
| hostID | String | read-only | Identifies the host application. |
Prints the string to the system log. On Mac OS X, the log can be viewed using the Console application (in Applications / Utilities).
Prints the string into Conduit's floating "trace window". The string may be trimmed to fit into the window.
Reads the contents of the file at the given path in the local file system. The path string should use slashes to separate components (on Windows, Conduit will convert slashes to backslashes internally).
For security reasons, files can't be read from operating system locations. Conduit will also prevent too large files from being loaded into memory.
A Canvas object allows for drawing high-quality 2D graphics.
The Canvas API in Conduit follows the HTML 5 draft standard, and is thus compatible with Firefox, Safari and other modern browsers that implement Canvas. More information and tutorials can be found at Mozilla's Canvas developer center.
| width | Number | read-only | |
| height | Number | read-only |
Provides access to the Canvas object's 2D graphics context, which allows drawing operations to be performed onto the canvas. The only supported value for contextId is "2d".
This method is a Conduit extension. It allows the contents of a Canvas object to be used as a texture when drawing accelerated graphics using Conduit's Surface API.
surface must be a valid Surface object.
The 2D rendering context provides all the methods and properties necessary for drawing graphics into a Canvas.
This API is too large to be documented here. Please refer to the HTML 5 draft standard for the full specification.
You can also find more information and tutorials at Mozilla's Canvas developer center.
Represents a color gradient that can be used as a fill or stroke style when rendering graphics into a Canvas.
You can obtain a CanvasGradient object using the createLinearGradient or createRadialGradient methods of the CanvasRenderingContext2D object.
Please refer to the HTML 5 draft standard for the full specification.
Represents a pattern that can be used as a fill or stroke style when rendering graphics into a Canvas.
You can obtain a CanvasPattern object using the createPattern method of the CanvasRenderingContext2D object.
Please refer to the HTML 5 draft standard for the full specification.
The Surface object is similar in principle to Canvas. It also represents an image that can be drawn into, but there are some important differences: Surface supports 3D rendering and is fully accelerated in hardware on the GPU (graphics processing unit).
Surface is designed for real-time rendering. When rendering graphics in Conduit you should first consider whether Surface can be used for the purpose, and only resort to Canvas as necessary. Often the best strategy is to use Canvas for static elements like fixed graphics and text, and Surface for the "heavy lifting" — rendering that needs to be performed on every frame.
All the drawing state is encapsulated in the drawingContext property. You can set the drawing context's properties to e.g. change the textures, shader or transform that affect the outcome of the rendering.
To use a Surface as a source image when drawing into another Surface, access the texture property and set the destination surface's drawing context's textureArray property to an array containing the texture. (This is as easy as: destSurface.drawingContext.textureArray = [ sourceSurface.texture ]; )
| width | Number | read-only | |
| height | Number | read-only | |
| drawingContext | SurfaceDrawingContext | read-only | |
| texture | Texture | read-only |
Clears the surface. If no color is specified, the surface is cleared with transparent black, i.e. RGBA == [0, 0, 0, 0].
The x/y/w/h arguments can be used to clear only a specified region of the surface.
Draws a quad (= rectangle) that fills the entire surface. The surface's drawingContext determines how the quad is rendered: e.g. if a texture is set, this method effectively copies the contents of the source texture into the surface.
Draws a quad (= rectangle) that has its top-left corner at coordinates (0, 0) and bottom-right corner at (1, 1).
Draws the curves contained in curveList as primitives of type primitiveTypeId.
Valid values for primitiveTypeId are: "points", "quads", "line-strip", "line-loop", "triangle-fan", "triangle-strip".
Draws the vertices contained in vertexArray as primitives of type primitiveTypeId. The vertices can't contain Z values for this call.
Valid values for primitiveTypeId are: "points", "quads", "line-strip", "line-loop", "triangle-fan", "triangle-strip".
Vertices given in the array are expected to be regular JavaScript objects that specify coordinates, e.g.: { "x": 0.3, "y": 0.3, "u": 0, "v": 0 }. Valid coordinate names are x/y for on-surface coordinates and u/v for texture coordinates.
Draws the vertices contained in vertexArray as primitives of type primitiveTypeId.
Valid values for primitiveTypeId are: "points", "quads", "line-strip", "line-loop", "triangle-fan", "triangle-strip".
Vertices given in the array are expected to be regular JavaScript objects that specify coordinates, e.g.: { "x": 0.3, "y": 0.3, "z", -1.5, "u": 0, "v": 0 }. Valid coordinate names are x/y/z/w for coordinates in surface's 3D space, and u/v for texture coordinates.
Performs the same operation as drawUnitQuad(), but instead of replacing the existing pixels in the surface, composites the newly rendered graphics into the surface using the "over" operation. (Rendered color values are expected to be premultiplied with alpha; non-premultiplied (aka "straight") alpha is not supported.)
Performs the same operation as draw2DVertices(), but instead of replacing the existing pixels in the surface, composites the newly rendered graphics into the surface using the "over" operation. (Rendered color values are expected to be premultiplied with alpha; non-premultiplied (aka "straight") alpha is not supported.)
The drawing context contains all the properties that affect the rendered output of a drawing operation performed onto a Surface.
| modelViewTransform | Transform3D | read/write | |
| renderStyle | String | read/write | Valid values: { "default", "onScreenControls" } |
| shader | Shader | read/write | |
| textureArray | Array | read/write | |
| useFragmentAntialiasing | Boolean | read/write | This setting enables hardware antialiasing, but may limit rendering to a subset of functionality (depending on GPU capabilities). |
Sets parameter values that will be passed to the shader when rendering. index is an integer starting at zero. (The maximum valid index depends on the shader). value can be either an array of Numbers, a single Number, or a Color object.
The default shader simply renders with a solid color using the first shader parameter's value. Thus, to set the color to a bright yellow with full opacity, you could call surface.drawingContext.setShaderParam(0, [1, 1, 0, 1]);.
A shader is a program that determines the final color value for each rendered pixel. Shaders are executed on the GPU, which places very specific restrictions on the program's contents. (For example, the GPU does not support arbitrary loops.)
The default shader for a surface's drawing context fills pixels with a solid color. This shader can be created using the constant "solid-color". Other shaders can be created by passing a valid shader program as a string.
Instead of writing shaders manually, consider using Conduit's node-based interface to design an effect, and then accessing the effect as a shader using API methods in your script. For typical tasks, this is much easier than learning the shader programming language.
The constructor argument can be a templateId. Currently the only supported value is "solid-color". Calling the constructor with no argument is equal to calling with "solid-color".
If the constructor argument is a String that can't be interpreted as a templateId, it is assumed to be a shader program. Currently the only shader language supported is OpenGL's "ARB fragment program" assembly (this format is supported by Conduit on both Windows and Mac OS X).
A texture is an image that has been made accessible to the GPU and can be used as a source when drawing into a surface. To specify a texture for drawing, use the textureArray property on the surface's drawing context.
| width | Number | read-only | |
| height | Number | read-only | |
| samplingMode | String | read/write | Accepted values are "nearest" and "linear". |
This object represents a transformation in 3D space. Its scale and translate methods are similar to the equivalent methods in the Canvas API; however, remember to pass the third (Z) component even if you're only rendering in 2D space. (If you don't want to modify Z, you should always set it to 1 when scaling, and 0 when translating.)
Rotation behaves somewhat differently in 3D than in 2D. To rotate "2D-style", rotate around the Z axis only.
Internally, the transformation is stored in a 4*4 matrix. You can modify the matrix directly using the matrixArray property.
| matrixArray | Array (16 Numbers) | read/write |
Translates in 3D space.
Scales in 3D space.
Rotates in 3D space. angle is given in radians, and it is multiplied by the three components to produce the actual rotation. To rotate around a single axis, pass 1 for the wanted axis and 0 for the two others.
This basic style of rotation may not be sufficient for advanced animation. Quaternion math could be used to implement rotations that are more suitable to be animated. Conduit doesn't currently provide a native API for quaternion rotations, but it's possible to do the math in JavaScript.
A presenter manages user interface display objects such as buttons and text boxes. Some presenters are simple and may control only a simple view; others manage complex objects like tables or scrollable lists, and may act as containers which have other presenters nested inside them.
Presenters are created in Conduit using the JSON-based interface definition format ("PresenterJSON"). Typically you'll only need to access these objects in JavaScript when responding to events.
| id | String | read-only | |
| title | String | read-only | |
| isContainer | Boolean | read-only | |
| label | String | read/write | The label displayed to the user (if any). |
| enabled | Boolean | read/write | Whether the presenter accepts clicks or other events. |
| text | String | read/write | Text content. |
| numberValue | Number | read/write | Numeric content (e.g. a slider's position). |
This object represents a custom table parameter in Conduit's user interface. (The table was usually created from a PresenterJSON user interface definition script.)
The detailView property can be used to access the presenter that contains the detail view associated with this table.
| detailView | Presenter | read-only |
An OSCEvent object is passed to a Conduit node's event scripts (e.g. "onMouseClick") when a mouse or keyboard event occurs.
| type | String | read-only | |
| imageWidth | Number | read-only | |
| imageHeight | Number | read-only | |
| imageX | Number | read-only | |
| imageY | Number | read-only | |
| imageToViewTransform | Transform3D | read-only | |
| viewSurface | Surface | read-only |
Converts a point specified in image coordinates to the view's coordinates (i.e. the coordinate space in which on-screen controls are drawn).
A Conduit effect is a graph of nodes that can be manipulated visually in the Conduit Editor user interface. (Conduit effects are also called simply "conduits" when the disambiguation from the application's name is clear enough.)
| name | String | read-only | |
| nodeCount | Number | read-only | |
| isShaderizable | Boolean | read-only |
A Conduit renderer takes a set of input textures, applies a Conduit effect to them, and outputs the resulting image into a Surface. The renderer has a params property that can be used to set slider and color picker values for the Conduit effect.
You can't directly set the Conduit effect associated with the renderer, but instead must obtain a renderer from the Conduit API to match a specific Conduit effect. (See node.getRendererForConduit() method.)
| name | String | read-only | |
| params | Object | read/write | This object contains slider values in format 'Slider N' and picker values in format 'Color Picker N', where N is an integer. |
Renders into the given surface. The textures used as inputs to this renderer's Conduit effect
are obtained from surface's drawing context's texture array.
I.e. to set the input textures before calling this method, use:
surface.drawingContext.textureArray = [ tex1, tex2, tex3 .. ];