jsui, Sketch and OpenGL

Javascript files loaded by the jsui object have access to the Sketch object, which may be used for drawing graphics. We will refer to the Sketch object and the methods it exposes as the Sketch API. The Sketch API is built upon the cross platform OpenGL API, and can be divided into two categories: "OpenGL Methods" and "High Level Methods". The "OpenGL Methods" are a direct binding for a large portion of the low level OpenGL API, and the "High Level Methods" are extensions built upon lower level OpenGL calls.

An example of a high level method would be sketch.sphere(0.1) which calculates all of the geometry and associated information for lighting and color, and based on the current state of the sketch object, issues many OpenGL calls to render a sphere. The sketch.sphere() method is much simpler to use than the underlying OpenGL calls it makes use of. We consider "high level" to be that which isolates the programmer from the intricate details of OpenGL.

OpenGL Conventions and Differences

All OpenGL methods begin with prefix, "gl". While we will provide a listing of supported OpenGL methods in this document, for more in-depth coverage of OpenGL we recommend that you consult either online or printed documentation concerning the OpenGL API. The www.opengl.org website is the official online resource for OpenGL, and is a good starting point for online documentation, tutorials, links, news and other information pertaining to OpenGL. There are a few important differences between the OpenGL API, and the methods which the Sketch object exposes:

• The Sketch methods are all lowercase, and only exist within the context of a sketch object. For example, this means that glBegin() will be sketch.glbegin(), and glClearColor() will be sketch.glclearcolor(). Javascript's "with" statement may be used to avoid having to type "sketch." for every method call.
• All symbolic constants are lowercase Javascript strings, and have no "GL_" prefix. For example the constant GL_LIGHTING will be the Javascript string "lighting", and GL_LINE_STRIP is replaced with "line_strip".
• There are no special versions of vector calls. Only floating point values are supported, and sketch will fill in extra values with defaults. For example glColorv4fv(), glColorv3fv(), etc. will simply be sketch.glcolor().
• Sketch supports passing Javascript arrays in place of individual arguments. So glColor3f(0.,0.,1.) can be replaced with either sketch.glcolor(0.,0.,1.), or sketch.glcolor(frgb), where frgb is the array [0.,0.,1.].

Colors and Coordinates

As is the convention in OpenGL, color values should be specified with each component as a floating point number in the range of 0.-1., as opposed to an integer in the range 0-255. For example red would be (1.,0.,0.), rather than (255,0,0). OpenGL also supports the use of an alpha channel for transparency and other types of blending modes. Colors with alpha channel values may be specified as RGBA, for example, green with 25% opacity would be (0.,1.,0.,0.25). If there is no alpha channel value present, it is assumed to be 1.--i.e. 100% opaque. By default, alpha blending is enabled. To turn off blending, use sketch.gldisable("blend"). When working in 3D, depth buffering is turned on by default, and will typically interfere with attempts to blend transparent objects. To turn off depth buffering, use sketch.gldisable("depth_test").

Unlike some graphics APIs, the OpenGL API does not distinguish between 2D and 3D drawing. Conventional 2D drawing is simply a subset of 3D drawing calls with specific graphics state--e.g. no lighting, no depth testing, orthorgraphic projection, et cetera. High level utility methods are provided as a convenience to setup up the OpenGL graphics state to something typically used for 2D or 3D graphics. If assuming 2D drawing conventions, one can ordinarily use z coordinates of zero for all methods that require them.

Coordinates in OpenGL are also given in terms of floating point relative world coordinates, rather than absolute pixel coordinates. The scale of these world coordinates will change depending on the current graphics transformation--i.e. translation, rotation, scaling, projection mode, viewport, etc. However, our default mapping is that Y coordinates are in the range -1. to 1 from bottom to top, and X coordinates are in the range -aspect to aspect from left to right, where aspect is equal to the ratio of width/height. In the default case, (0,0) will be center of your object, (-aspect,1.) will be the upper left corner, and (aspect,-1.) will be the lower right corner.

Note that user events are typically provided in terms of absolute screen coordinates. Please see the sketch.screentoworld() and sketch.worldtoscreen() methods for converting between absolute screen coordinates and relative world coordinates.