Canvas Library

Position Specification

Various taccgl™-Methods (e.g. position, from, to, clip) receive coordinates in 2D or in 3D space. 3D coordinates usually refer to the 3D model while 2D coordinates are often used for textures (e.g. map) or refer to pixel coordinates of the underlying HTML page. Coordinates can be given either directly using 2 or 3 numerical parameters as described with the individual methods or using a position specification. A position specification is a javaScript object usually written using curley brackets as {positioning options}.

If a position specification is passed to a taccgl™ method, it is evaluated when starting the method. Evaluation leads to the actual coordinates, which are then used just as numerical parameters would.

Examples for simple position specifications are {x:50,y:100,z:0} which gives all coordinates explicitly and {oy:100} which specifies an offset of 100 pixels in y direction.

Position calculation is based on a transition t, which displays or animates e.g. an HTML element or a 3D object. Per default the transition object is used, whose method was called. So for example relative coordinates such as ox,oy,oz or rx,ry,rz use the position of the base transition t as starting point.

If the base transtion t describes a motion i.e. if the position moves over time, using pt the desired point in time can be specified. pt=0 stands for the begin of the transition and pt=1. pt=0 is the default, i.e. per default the base for relative coordinates is the from value.

option Meaning
x:number, y:number, z:number Specifies absolute coordinate values directly in pixels.
ox:number, oy:number, oz:number Specifies coordinate offsets that are added to the coordinates at the end in pixels.
rx:number, ry:number, rz:number Specifies relative coordinates within the coordinate system of the current transition. This is similar to ox,oz,oy but the values are not given in pixels. Instead a value of rx=1 means the width of the current transition. So {rx:1,ry:0,rz:0} refers to the top right corner; {rx:0,ry:1,rz:0} to the bottom left corner, {rx:0.5,ry:0.5,rz:0.5} to the point in the center.
el:id, ex:number, ey:number id must be the id of an HTML element (or a DOM node). The coordinates ex, eyspecify relative coordinates within the coordinate system of the specified HTML element. So {ex:1,ey:0} refers to the top right corner; {ex:0,ey:1} to the bottom left corner, {ex:0.5,ey:0.5} to the point in the center.
t:transition Makes position calculation based on the specified transition.
pt:number Usually the base point for relative coordinates is the from value of the base transition t. For pt:1 calculation is based on the to value. In general it is based on from*(1-pt) + to*pt .
rt:number For some specifications, e.g. rx, ry, rz the size of the transition is relevant. If this is a resizing transition, i.e. the height, width, or, depth changes over time, then rt can be used to select this point in time. rt:1 means to take the destination size as basis for the calculation. In general from_size*(1-rt) + to_size*pt is used as size.
hx:number, hy:number, The coordinates hx and hy are relative to the home position of the base transition. This is the position of the HTML element given in the a or actor method, possibly modified by clipping. hx:0, hy:0 refers to the top left corner of the HTML element, hx:1, hy:1 to the bottom right corner.
rel:id, rex:number, rey:number rel, rex, rey specify a position under the same rules as el, ex, ey. This position is then added to the position defined by other positioning options.
mel:id, mex:number, mey:number mel, mex, mey specify a position under the same rules as el, ex, ey. This position is then subtracted from the position defined by other positioning options.
Tx:number, Ty:number Tx, Ty specify coordinates relative to the texture space assigne to the transition. If the transition has a moving or resizing texture pt and rt are honored accordingly.
M:transition, mx:number, my:number, mz:number, Mx:number, My:number, Mz:number M must be a transition displaying an external 3D object. Then mx, my, mz define a point in coordinates of the external 3D model. Alternatively Mx, My, Mz can be given. These coordinates are scaled according to the actual size of the 3D model.


  • Normally just one of
    • x, y, z,
    • e, ex, ey,
    • hx, hy,
    • Tx, Ty, or
    • M, mx, my, mz, Mx, My, Mz
    should be given. These define a base point. Other positioning options
    • ox, oy, oz
    • rx, ry, rz
    • rel, rex, rey
    • mel, mex, mey
    then result in values that a added to (or subtracted from) this base point.
  • As an exception to the above rule, it is possible to combine one or two of the x, y, z - options with other options. Then the one or two specified values are taken while the remain coordintates are calculated according to the above rules.
Next Page:Lighting
Previous Page: Animations and Transitions