Introduction & Table of contents

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:

Array Boolean Date Function
Math Number Object RegExp
String ByteBuffer MutableByteBuffer Color
CurveList Image JSON node
sys Canvas CanvasRenderingContext2D CanvasGradient
CanvasPattern Surface SurfaceDrawingContext Shader
Texture Transform3D Presenter TableCustomParam
OSCEvent ConduitEffect ConduitRenderer

JavaScript standard objects

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.

Array

Boolean

Date

Function

Math

Number

Object

RegExp

String

Conduit base classes

ByteBuffer

Description

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.)

Properties

length Number read-only  
isMutable Boolean read-only  

Methods

asString(encoding[, startIndex, length])
Returns a String if the data is valid for the specified encoding.

Interprets the binary data as text according to the specified encoding. Valid values for encoding are: "utf-8", "utf-16", "ascii".

at(index)
Returns a Number in range [0, 255].

This method is a shorthand for getUnsignedByte.

getSignedByte(index)
Returns a Number in range [-128, 127].

Gets the byte value at the specified index in the buffer, interpreting the byte as a signed value.

getUnsignedByte(index)
Returns a Number in range [0, 255].

Gets the byte value at the specified index in the buffer, interpreting the byte as an unsigned value.

indexOfByte(value[, startIndex, length])
Returns a Number which is a valid index if the byte value was found, or -1 otherwise.

Finds the first occurrence of the given byte value in the buffer.

MutableByteBuffer

Description

The mutable subclass of ByteBuffer. All properties and methods of ByteBuffer are valid for this class.

Constructors

new MutableByteBuffer(length:Number)
new MutableByteBuffer(objectToCopy:ByteBuffer)

Methods

setSignedByte(index, value)

Sets the byte value at the specified index in the buffer, converting value to an integer in range [-128, 127].

setUnsignedByte(index, value)

Sets the byte value at the specified index in the buffer, converting value to an integer in range [0, 255].

Color

Description

A color value. The color consists of four components: red, green, blue and alpha. Component values can be any floating-point numbers.

Constructors

new Color(r, g, b, a)
new Color(htmlStyleColor:String)
new Color(objectToCopy:Color)

Properties

red Number read/write  
green Number read/write  
blue Number read/write  
alpha Number read/write  

Methods

toString()
Returns a String which describes the color. The string's format is the same as used by the HTML and CSS standards.

CurveList

Description

A collection of curve segments that can form a path or other graphical object.

Constructors

new CurveList()
new CurveList(objectToCopy:CurveList)

Properties

length Number read-only  
closed Boolean read/write  

Methods

addArc(xc, yc, radius, angle1, angle2[, anticlockwise])

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.)

appendCurveToPoint(curveTypeId, x, y[, (...additional control point coords...)])

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.

insertCurve(curveTypeId, x1, y1, x2, y2[, (...additional control point coords...), insertionIndex])

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.)

Image

Description

A reference to an image. This class can't be constructed; you can only obtain Image objects through API methods.

Properties

width Number read-only  
height Number read-only  

Global objects in Conduit

JSON

Description

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)

Methods

parse(string)

Returns an Object or Array which is the JavaScript representation of the JSON string if the conversion is successful.

stringify(object)

Returns a String which is the JSON representation of the object if the conversion is successful.

node

Description

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.

Properties

name String read-only  
parameterCount Number read-only  
assetCount Number read-only  

Methods

getAsset(index)
Returns the asset object (a String, ByteBuffer, Image or ConduitEffect).

Gets the asset at the specified index in the node's assets list. Note that the indexes begin at 1.

setAsset(index, object)

Stores an object as an asset at the specified index in the node's assets list. Note that the indexes begin at 1.

getParam(index)
Returns the parameter's value (typically a Number, Boolean or String).

Gets the value of the node's parameter with the specified index. Note that the indexes begin at 1.

setParam(index, value)

Sets the value for the node's parameter with the specified index. Note that the indexes begin at 1.

refreshParam(index)

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.

getRendererForConduit(conduit:ConduitEffect)
Returns a Conduit renderer that can be used with the given effect.

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.

getTempSurface([width, height])
Returns a Surface.

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.

sys

Description

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).

Properties

hostID String read-only Identifies the host application.

Methods

log(string)

Prints the string to the system log. On Mac OS X, the log can be viewed using the Console application (in Applications / Utilities).

trace(string)

Prints the string into Conduit's floating "trace window". The string may be trimmed to fit into the window.

readLocalFile(path)
Returns a ByteBuffer object if the file was successfully read.

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.

Canvas (2D graphics)

Canvas

Description

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.

Constructors

new Canvas(width, height)

Properties

width Number read-only  
height Number read-only  

Methods

getContext(contextId)
Returns a CanvasRenderingContext2D object.

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".

getTextureForSurface(surface:Surface)
Returns a Texture object that is compatible with the given surface.

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.

CanvasRenderingContext2D

Description

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.

CanvasGradient

Description

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.

CanvasPattern

Description

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.

Surface (2D and 3D accelerated graphics)

Surface

Description

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 ]; )

Properties

width Number read-only  
height Number read-only  
drawingContext SurfaceDrawingContext read-only  
texture Texture read-only  

Methods

clear([color:Color], [x, y, w, h])

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.

drawWithinBounds()

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.

drawUnitQuad()

Draws a quad (= rectangle) that has its top-left corner at coordinates (0, 0) and bottom-right corner at (1, 1).

draw2DCurveList(primitiveTypeId:String, curveList:CurveList)

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".

draw2DVertices(primitiveTypeId:String, vertexArray:Array)

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.

draw3DVertices(primitiveTypeId:String, vertexArray:Array)

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.

compositeUnitQuad()

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.)

composite2DVertices(primitiveTypeId:String, vertexArray:Array)

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.)

SurfaceDrawingContext

Description

The drawing context contains all the properties that affect the rendered output of a drawing operation performed onto a Surface.

Properties

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).

Methods

setShaderParam(index, value)

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]);.

Shader

Description

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.

Constructors

new Shader()
new Shader(templateId:String)
new Shader(shaderProgram:String)
new Shader(objectToCopy:Shader)

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).

Texture

Description

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.

Properties

width Number read-only  
height Number read-only  
samplingMode String read/write Accepted values are "nearest" and "linear".

Transform3D

Description

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.

Constructors

new Transform3D()
new Transform3D(objectToCopy:Transform3D)

Properties

matrixArray Array (16 Numbers) read/write  

Methods

translate(x, y, z)

Translates in 3D space.

scale(x, y, z)

Scales in 3D space.

rotate(angle, x, y, z)

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.

Conduit user interface

Presenter

Description

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.

Properties

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).

Methods

getChildById(id:String)
Returns a Presenter which is a child of this object and has the given id.

TableCustomParam

Description

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.

Properties

detailView Presenter read-only  

OSCEvent

Description

An OSCEvent object is passed to a Conduit node's event scripts (e.g. "onMouseClick") when a mouse or keyboard event occurs.

Properties

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  

Methods

convertImagePointToView(x, y)
Returns a JavaScript object with x and y properties, if the conversion was successful.

Converts a point specified in image coordinates to the view's coordinates (i.e. the coordinate space in which on-screen controls are drawn).

Conduit effects

ConduitEffect

Description

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.)

Properties

name String read-only  
nodeCount Number read-only  
isShaderizable Boolean read-only  

Methods

asShader()
Returns a Shader object representing the effect, if the effect can be represented as a single shader. (You can check this beforehand using the isShaderizable property.)

ConduitRenderer

Description

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.)

Properties

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.

Methods

renderInSurface(surface:Surface)

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 .. ];