The Sketch Object

The Sketch Object

Every instance of jsui has an instance of Sketch bound to the variable "sketch". This is often the only instance of Sketch you will need to use. However, if you want to do things like render sprites, have multiple layers of images, or use drawing commands to create alpha channels for images, then you can create additional instances to render in. By default, when any function in your jsui object has been called the context is already set for the instance of Sketch bound to the variable "sketch".

Sketch Constructor


var mysketch = new Sketch(); // create a new instance of Sketch with default width and height
var mysketch = new Sketch(width,height); // create a new instance of sketch with specified width and height
size[0] is width size[1] is height. Turns on/off full scene antialiasing.

Sketch Simple Line and Polygon Methods

move

Arguments

delta_x [Number]
delta_y [Number]
delta_z [Number]

Moves the drawing position to the location specified by the sum of the current drawing position and the delta x, y, and z arguments.

moveto

Arguments

x [Number]
y [Number]
z [Number]

Moves the drawing position to the location specified by the x, y, and z arguments.

point

Arguments

x [Number]
y [Number]
z [Number]

Draws a point at the location specified by the x, y, and z arguments. After this method has been called, the drawing position is updated to the location specified by the x, y, and z arguments.

line

Arguments

delta_x [Number]
delta_y [Number]
delta_z [Number]

Draws a line from the current drawing position to the location specified the sum of the current drawing position and the delta x, y, and z arguments. After this method has been called, the drawing position is updated to the location specified by the sum of the current drawing position and the delta x, y, and z arguments.

lineto

Arguments

x [Number]
y [Number]
z [Number]

Draws a line from the current drawing position to the location specified by the x, y, and z arguments. After this method has been called, the drawing position is updated to the location specified by the x, y, and z arguments.

linesegment

Arguments

x1 [Number]
y1 [Number]
z1 [Number]
x2 [Number]
y2 [Number]
z2 [Number]

Draws a line from the location specified by the x1, y1, and z1 arguments to the location specified by the x2, y2, and z2 arguments. After this method has been called, the drawing position is updated to the location specified by the x2, y2, and z2 arguments.

tri

Arguments

x1 [Number]
y1 [Number]
z1 [Number]
x2 [Number]
y2 [Number]
z2 [Number]
x3 [Number]
y3 [Number]
z3 [Number]

Draws a filled triangle with three corners specified by the x1, y1, z1, x2, y2, z2, x3, y3, and z3 arguments. After this method has been called, the drawing position is updated to the location specified by the x3, y3, and z3 arguments.

frametri

Arguments

x1 [Number]
y1 [Number]
z1 [Number]
x2 [Number]
y2 [Number]
z2 [Number]
x3 [Number]
y3 [Number]
z3 [Number]

Draws a framed triangle with three corners specified by the x1, y1, z1, x2, y2, z2, x3, y3, and z3 arguments. After this method has been called, the drawing position is updated to the location specified by the x3, y3, and z3 arguments.

quad

Arguments

x1 [Number]
y1 [Number]
z1 [Number]
x2 [Number]
y2 [Number]
z2 [Number]
x3 [Number]
y3 [Number]
z3 [Number]
x4 [Number]
y4 [Number]
z4 [Number]

Draws a filled quadrilateral with four corners specified by the x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, and z4 arguments. After this method has been called, the drawing position is updated to the location specified by the x4, y4, and z4 arguments.

framequad

Arguments

x1 [Number]
y1 [Number]
z1 [Number]
x2 [Number]
y2 [Number]
z2 [Number]
x3 [Number]
y3 [Number]
z3 [Number]
x4 [Number]
y4 [Number]
z4 [Number]

Draws a framed quadrilateral with four corners specified by the x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, and z4 arguments. After this method has been called, the drawing position is updated to the location specified by the x4, y4, and z4 arguments.

Shape Methods

circle

Arguments

radius [Number]
theta_start [Number]
theta_end [Number]

Draws a filled circle with radius specified by the radius argument. If theta_start and theta_end are specified, then an arc will be drawn instead of a full circle. The theta_start and theta_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

cube

Arguments

scale_x [Number]
scale_y [Number]
scale_z [Number]

Draws a cube with width 2*scale_x, height 2*scale_y, depth 2*scale_z, and center point at the current drawing position. If the scale_y and scale_z arguments are not specified, they will assume the same value as scale_x. The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

cylinder

Arguments

radius1 [Number]
radius2 [Number]
mag [Number]
theta_start [Number]
theta_end [Number]

Draws a cylinder with top radius specified by the radius1 argument, bottom radius specified by the radius2 argument, length specified by the mag argument, and center point at the current drawing position. If the theta_start and theta_end arguments are specified, then a patch will be drawn instead of a full cylinder. The theta_start and theta_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

ellipse

Arguments

radius1 [Number]
radius2 [Number]
theta_start [Number]
theta_end [Number]

Draws a filled ellipse with radii specified by the radius1 and radius2 arguments. If theta_start and theta_end are specified, then an arc will be drawn instead of a full ellipse. The theta_start and theta_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

framecircle

Arguments

radius [Number]
theta_start [Number]
theta_end [Number]

Draws a framed circle with radius specified by the radius argument. If theta_start and theta_end are specified, then an arc will be drawn instead of a full circle. The theta_start and theta_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

frameellipse

Arguments

radius1 [Number]
radius2 [Number]
theta_start [Number]
theta_end [Number]

Draws a framed ellipse with radii specified by the radius1 and radius2 arguments. If theta_start and theta_end are specified, then an arc will be drawn instead of a full ellipse. The theta_start and theta_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

plane

Arguments

scale_x1 [Number]
scale_y1 [Number]
scale_x2 [Number]
scale_y2 [Number]

Draws a plane with top width 2*scale_x1, left height 2*scale_y1, bottom width 2*scale_x2, right height 2*scale_y2, and center point at the current drawing position. If scale_y1 is not specified, it will assume the same value as scale_x1. If scale_x2 and scale_y2 are not specified, they will assume the same values as scale_x1 and scale_y1 respectively. The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

roundedplane

Arguments

round_amount [Number]
scale_x [Number]
scale_y [Number]

Draws a rounded plane with width 2*scale_x, and height 2*scale_y and center point at the current drawing position. The size of the rounded portion of the plane is determined by the round_amount argument. If scale_y is not specified, it will assume the same value as scale_x. The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

sphere

Arguments

radius [Number]
theta1_start [Number]
theta1_end [Number]
theta2_start [Number]
theta2_end [Number]

Draws a sphere with radius specified by the radius argument and center point at the current drawing position. If the theta1_start, theta1_end, theta2_start, and theta2_end arguments are specified, then a patch will be drawn instead of a full sphere. The theta1_start, theta1_end, theta2_start, and theta2_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

torus

Arguments

radius1 [Number]
radius2 [Number]
theta1_start [Number]
theta1_end [Number]
theta2_start [Number]
theta2_end [Number]

Draws a torus with major radius specified by the radius1 argument, minor radius specified by the radius2 argument, and center point at the current drawing position. If theta1_start, theta1_end, theta2_start, and theta2_end are specified, then a patch will be drawn instead of a full torus. The theta1_start, theta1_end, theta2_start, and theta2_end arguments are in terms of degrees(0-360). The current shapeorient, shapeslice, and shapeprim values will also affect the drawing.

Sketch Shape Attribute Methods

shapeorient

Arguments

rotation_x [Number]
rotation_y [Number]
rotation_z [Number]

Sets the rotation for drawing internal to any of the "shape" drawing methods to the rotation specified by the x_rot, y_rot, and rotation_x, rotation_y, and rotation_z arguments. Its use internal to a given shape method such as torus(0.1) would essentially be equivalent to the following set of OpenGL calls.


					with (sketch) {
					    glmatrixmode("modelview");
					    glpushmatrix();
					    glrotate(rotation_x,1.,0.,0.);
					    glrotate(rotation_y,1.,1.,0.);
					    glrotate(rotation_z,0.,0.,1.);
					    torus(0.5,0.2);
					    glpopmatrix();
					}
				

shapeslice

Arguments

slice_a, slice_b [Number]
slice_b [Number]

Sets the number of slices to use when rendering any of the "shape" drawing methods. Increasing the slice_a and slice_b arguments will increase the quality at which the shape is rendered, while decreasing these values will improve performance.

shapeprim

Arguments

draw_prim [String]

Sets the OpenGL drawing primitive to use within any of the "shape" drawing methods. Acceptable values for the draw_prim argument are the following strings: lines, line_loop, line_strip, points, polygon, quads, quad_grid, quad_strip, triangles, tri_grid, tri_fan, tri_strip.

Sketch Text Methods

font

Arguments

fontname [String]

Sets the current font to the fontname specified by the fontname argument.

fontsize

Arguments

points [Number]

Sets the fontsize to the size specified by the points argument. Note that this size is an absolute, rather than relative value.

gettextinfo

Arguments

string [String]

Returns an array containing the width and height of the given string in absolute screen coordinates, taking into account the current font and fontsize.

text

Arguments

string [String]

Draws the text specified by the string argument at the current drawing position, taking into account the current font, fontsize, and text alignment. Text is strictly 2D, and does not take into account any world transformations. After calling the text method, if the x axis text alignment is set to "left", the current drawing position will be updated to reflect the world position associated with the end of the string. If the x axis text alignment is set to "right", the current drawing position will be updated to reflect the world position associated with the end of the string. If the x axis text alignment is set to "center", the current drawing position will remain unchanged.

textalign

Arguments

align_x [String]
align_y [String]

Sets the alignment of text to be drawn with respect to the current drawing position. Acceptable values for the x axis alignment are: "left", "right", or "center". Acceptable values for the y axis alignment are: "bottom", "top", or "center". The default alignment is "left", "bottom".

Sketch Pixel Methods Methods

copypixels

Arguments

source_object [String]
destination_x [Number]
destination_y [Number]
source_x [Number]
source_y [Number]
width [Number]
height [Number]

Copies pixels from the source object to the location specified by the destination_x and destination_y arguments. The initial x and y offset into the source and size of the rectangle copied can be speified by the source_x, source_y, width and height arguments. If these are not present an x and y offset of zero and width and height equal to the source image is assumed. No scaling of pixels is supported. The source object can either be an instance of Image, or Sketch. If blending is enabled in the destination sketch object, alpha blending will be performed and the current alpha color will also be applied globally. The copypixels method is much faster than obtaining the equivalent result using glbindtexture() to texture a plane, and is the recommended means of drawing images when scaling and rotation is not required.

depthatpixel

Arguments

x [Number]
y [Number]

Returns the depth value associated with the currently rendered pixel at a given absolute screen coordinate.

freepeer

Frees the image data from the native c peer, which is not considered by the JavaScript garbage collector, and may consume lots of memory until the garbage collector decides to run based on JS allocated memory. Once called, the Sketch object is not available for any other use.

getpixel

Arguments

x [Number]
y [Number]

Returns an array containing the pixel value at the specified location. This array is ordered RGBA, i.e. array element 0 is red, 1, green, 2, blue, 3 alpha. Color values are floating point numbers in the range 0.-1.

setpixel

Arguments

x [Number]
y [Number]
red [Number]
green [Number]
blue [Number]
alpha [Number]

Sets the pixel value at the specified location. Color values are floating point numbers in the range 0.-1.

screentoworld

Arguments

x [Number]
y [Number]

Returns an array containing the x, y, and z world coordinates associated with a given screen pixel using the same the depth from the camera as 0,0,0. Optionally a third depth arg may be specified, which may be useful for hit detection and other applications. The depth value is typically specified in the range 0.-1. where 0 is the near clipping plane, and 1. is the far clipping plane. The worldtoscreen method can be used to determine the depth value of a given world coordinate, and the depthatpixel method can be used to determine the depth value associated with the currently rendered pixel at a given absolute screen coordinate.

worldtoscreen

Arguments

x [Number]
y [Number]
z [Number]

Returns an array containing the x, y, and depth screen coordinates associated with a given world coordinate. The depth value is typically specified in the range 0.-1. where 0 is the near clipping plane, and 1. is the far clipping plane.

Sketch Stroke Methods

beginstroke

Arguments

stroke_style [String]

Begin definition of a stroked path of the style specified by the stroke_style argument. Currently supported stroke styles are "basic2d" and "line".

endstroke

End definition of a stroked path, and render the path.

strokeparam

Arguments

parameter_name [String]
parameter_values [Anything]
arguments [Anything]

Set the current value of the parameter specified by the parameter_name argument to be the value specified by parameter_values argument(s). Some parameters are global for the extent of a stroked path definition, while others may vary on a point by point basis.

strokepoint

Arguments

x [Number]
y [Number]
z [Number]

Defines an anchor point at the location specified by the x, y, and z arguments. Some stroke styles such as "basic2d" will ignore the z coordinate.

Basic 2D Stroke Style Parameters


  alpha

May vary point to point. Value is specified as an alpha value. Useful if alpha is the only color channel which will vary throughout the path.


  color

May vary point to point. Values are specified as red, green, blue, and alpha values.


  order

global. Value is specified as interpolation order. The default order is 3, or bi-cubic interpolation.


  outline

global. Value is specified as on/off (0/1). The default is 1.


  outcolor

May vary point to point. Values are specified as red, green, blue, and alpha values. If no outcolor has been specified, then the current color is assumed.


  scale

May vary point to point. Value is specified as an width value. This value controls how wide the stroked path is.


  slices

global. Value is specified as number of slices per curve section. The default is 20.

Line Stroke Style Parameters


  alpha

May vary point to point. Value is specified as an alpha value. Useful if alpha is the only color channel which will vary throughout the path.


  color

May vary point to point. Values are specified as red, green, blue, and alpha values.


  order

global. Value is specified as interpolation order. The default order is 3, or bi-cubic interpolation.


  slices

global. Value is specified as number of slices per curve section. The default is 20.

Sketch Setup Methods

default2d

The default2d method is a simple way to set the graphics state to default properties useful for 2D graphics. It is called everytime your object is resized if default2d() has been called more recently than default3d(). It is essentially equivalent to the following set of calls:


				  with (sketch) {
				    glpolygonmode("front_and_back","fill");
				    glpointsize(1.);
				    gllinewidth(1.);
				    gldisable("depth_test");
				    gldisable("fog");
				    glcolor(0.,0.,0.,1.);
				    glshademodel("smooth");
				    gldisable("lighting");
				    gldisable("normalize");
				    gldisable("texture");
				    glmatrixmode("projection");
				    glloadidentity();
				    glortho(-aspect, aspect, -1, 1, -1,100.);
				    glmatrixmode("modelview");
				    glloadidentity();
				    glulookat(0.,0.,2.,0.,0.,0.,0.,0.,1.);
				    glclearcolor(1., 1., 1., 1.);
				    glclear();
				    glenable("blend");
				    glblendfunc("src_alpha","one_minus_src_alpha");
				  }
				

default3d

The default3d method is a simple way to set the graphics state to default properties useful for 3D graphics. It is called everytime the jsui object is resized if default3d() has been called more recently than default2d().

It is essentially equivalent to the following set of calls:


				  with (sketch) {
				    glpolygonmode("front_and_back","fill");
				    glpointsize(1.);
				    gllinewidth(1.);
				    glenable("depth_test");
				    glenable("fog");
				    glcolor(0.,0.,0.,1.);
				    glshademodel("smooth");
				    gllightmodel("two_side", "true");
				    glenable("lighting");
				    glenable("light0");
				    glenable("normalize");
				    gldisable("texture");
				    glmatrixmode("projection");
				    glloadidentity();
				    gluperspective(default_lens_angle, aspect, 0.1, 100.);
				    glmatrixmode("modelview");
				    glloadidentity();
				    glulookat(0.,0.,2.,0.,0.,0.,0.,0.,1.);
				    glclearcolor(1., 1., 1., 1.);
				    glclear();
				    glenable("blend");
				    glblendfunc("src_alpha","one_minus_src_alpha");
				  }
				

ortho3d

Arguments

[]

The orth3d method is a simple way to set the graphics state to default properties useful for 3D graphics, using an orthographic projection (i.e. object scale is not affected by distance from the camera). It is called every time the jsui object is resized if ortho3d() has been called more recently than default2d(), or default3d().

It is essentially equivalent to the following set of calls:


				  with (sketch) {
				    glpolygonmode("front_and_back","fill");
				    glpointsize(1.);
				    gllinewidth(1.);
				    glenable("depth_test");
				    glenable("fog");
				    glcolor(0.,0.,0.,1.);
				    glshademodel("smooth");
				    gllightmodel("two_side", "true");
				    glenable("lighting");
				    glenable("light0");
				    glenable("normalize");
				    gldisable("texture");
				    glmatrixmode("projection");
				    glloadidentity();
				    glortho(-aspect, aspect, -1, 1, -1,100.);
				    glmatrixmode("modelview");
				    glloadidentity();
				    glulookat(0.,0.,2.,0.,0.,0.,0.,0.,1.);
				    glclearcolor(1., 1., 1., 1.);
				    glclear();
				    glenable("blend");
				    glblendfunc("src_alpha","one_minus_src_alpha");
				  }
				

Sketch OpenGL Methods

glbegin

Arguments

draw_prim []

glbindtexture

Arguments

image_object [String]

Note: this method also calls glenable(texture)

glblendfunc

Arguments

src_function [String]
dst_function [String]

glclear

glclearcolor

Arguments

red [Number]
green [Number]
blue [Number]
alpha [Number]

glcleardepth

Arguments

depth [Number]

glclipplane

Arguments

plane [Number]
coeff1 [Number]
coeff2 [Number]
coeff3 [Number]
coeff4 [Number]

glcolor

Arguments

red [Number]
green [Number]
blue [Number]
alpha [Number]

glcolormask

Arguments

red [Number]
green [Number]
blue [Number]
alpha [Number]

glcolormaterial

Arguments

face [Number]
mode []

glcullface

Arguments

face [Number]

gldepthmask

Arguments

on [Number]

gldepthrange

Arguments

near [Number]
far [Number]

gldisable

Arguments

capability [Number]

gldrawpixels

Arguments

image [String]

gledgeflag

Arguments

on [Number]

glenable

Arguments

capability [Number]

glend

glfinish

glflush

glfog

Arguments

parameter_name, value [String]
value [Number]

glfrustum

Arguments

left [Number]
right [Number]
bottom [Number]
top [Number]
near [Number]
far [Number]

glhint

Arguments

target [String]
mode [Number]

gllight

Arguments

light [String]
parameter_name [String]
value [Number]

gllightmodel

Arguments

parameter_name [String]
value [Number]

gllinestipple

Arguments

factor []
bit-pattern []

gllinewidth

Arguments

width [Number]

glloadidentity

glloadmatrix

Arguments

matrix_array [Array]

gllogicop

Arguments

opcode []

glmaterial

glmatrixmode

Arguments

mode [String]

glmultmatrix

Arguments

matrix_array [Array]

glnormal

Arguments

x [Number]
y [Number]
z [Number]

glortho

Arguments

left [Number]
right [Number]
bottom [Number]
top [Number]
near [Number]
far [Number]

glpointsize

Arguments

size [Number]

glpolygonmode

Arguments

face [Number]
mode [Number]

glpolygonoffset

Arguments

factor [Number]
units [Number]

glpopattrib

glpopmatrix

glpushattrib

glpushmatrix

glrect

Arguments

x1 [Number]
y1 [Number]
x2 [Number]
y2 [Number]

glrotate

Arguments

angle [Number]
x [Number]
y [Number]
z [Number]

glscale

Arguments

x_scale [Number]
y_scale [Number]
z_scale [Number]

glscissor

Arguments

x [Number]
y [Number]
width [Number]
height [Number]

glshademodel

Arguments

mode []

gltexcoord

Arguments

s []
t []

gltexenv

Arguments

parameter_name [String]
val1 [String]
val2 [String]
val3 [String]
val4 [String]

gltexgen

Arguments

coord [Array]
parameter_name [String]
val1 [String]
val2 [String]
val3 [String]
val4 [String]

gltexparameter

Arguments

parameter_name [String]
val1 [String]
val2 [String]
val3 [String]
val4 [String]

gltranslate

Arguments

delta_x [Number]
delta_y [Number]
delta_z [Number]

glulookat

Arguments

eye_x [Number]
eye_y [Number]
eye_z [Number]
center_x [Number]
center_y [Number]
center_z [Number]
up_x [Number]
up_y [Number]
up_z [Number]

gluortho2d

Arguments

left [Number]
right [Number]
bottom [Number]
top [Number]

gluperspective

Arguments

fovy []
aspect [Number]
near [Number]
far [Number]

glvertex

Arguments

x [Number]
y [Number]
z [Number]

glviewport

Arguments

x [Number]
y [Number]
width [Number]
height [Number]