AT&T Home | AT&T Labs | Research

# The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
Matrix typedict

A Matrix is an object that represents an affine transformation, which is a 2D coordinate transformation that preserves parallel lines. Matrices are commonly used to transform points that a Yoix program works with into points that describe a physical location in an object, like a Canvas, Frame, Image, or JFrame, that can be drawn on your screen, and in that context we often say the matrix maps "user space" into "device space". A Matrix defines the numbers that describe the affine transformation and a collection of built-ins, many with names borrowed from PostScript, that use or modify the matrix. The fields in a Matrix are:
 concat A Builtin that multiplies this matrix by another matrix and replaces this matrix by the result. concatmatrix A Builtin that multiplies this matrix by another matrix and returns the result. currentmatrix A Builtin that returns a writable copy of this matrix. dividematrix A Builtin that divides this matrix by another matrix and returns the result. dtransform A Builtin that transforms a displacement using this matrix and returns the result. identmatrix A Builtin that replaces this matrix with the identity matrix. idtransform A Builtin that transforms a displacement using the inverse of this matrix and returns the result. initmatrix A Builtin that changes this matrix so it represents the default Yoix coordinate system. invertmatrix A Builtin that returns the inverse of this matrix. itransform A Builtin that transforms a point using the inverse of this matrix and returns the result. maptopixel A Builtin that returns a point in user space close to a given point that also maps directly to a pixel in device space. rotate A Builtin that changes this matrix so it applies a rotation about the origin to transformed points. scale A Builtin that changes this matrix so it applies horizontal and vertical scaling to transformed points. setmatrix A Builtin that replaces this matrix with a copy of another matrix. shear A Builtin that changes this matrix so it applies horizontal and vertical shearing to transformed points. shx A double that represents the horizontal shearing associated with this matrix, which is `0` by default. shy A double that represents the vertical shearing associated with this matrix, which is `0` by default. sx A double that represents the horizontal scaling associated with this matrix, which is `1` by default. sy A double that represents the vertical scaling associated with this matrix, which is `1` by default. transform A Builtin that transforms a point using this matrix and returns the result. translate A Builtin that changes this matrix so it applies horizontal and vertical translation to transformed points. tx A double that represents the horizontal translation associated with this matrix, which is `0` by default. ty A double that represents a vertical translation associated with this matrix, which is `0` by default.
Several permanent fields have not been documented and should not be used in Yoix applications. In addition, we should point out that most applications make changes to a matrix using built-ins, like rotate, scale, and translate, rather than by explicitly setting individual components.

The read-only matrix `VM.screen.defaultmatrix` describes the default Yoix coordinate system, which has its origin in the upper left corner of an object (e.g., a Canvas, Frame, Image, JFrame, or your entire screen), positive x to the right, positive y down, and a resolution of 72 dots per inch. It is a consistent coordinate system that is used to describe the position and size of components that appear on your screen, the location of mouse events, the initial coordinate system associated with Graphics objects, and much more. In other words, ask for a frame that has a width of 720 and your program gets a 10 inch wide frame no matter where it runs. Add a mousePressed event handler to the frame and the location of mouse pressed events in the frame are reported in the default Yoix coordinate system.

The default values assigned to sx, sy, shx, shy, tx, and ty mean that a new matrix created without an initializer starts out as the identity matrix. However the matrix stored in the CTM field associated with a Graphics or Path object, or the one created by the declaration

```Matrix mtx = VM.screen.defaultmatrix.currentmatrix(); ```
start out as writable copies of `VM.screen.defaultmatrix`.
 Example: The program, ```import yoix.*.*; Triangle(Graphics graphics, double sx, double sy) { Matrix mtx; graphics { // "named block" mtx = currentmatrix(); scale(sx, sy); moveto(72, 72); rlineto(72, 0); rlineto(0, 72); closepath(); setmatrix(mtx); fill(); } } JFrame f = { Color background = Color.white; paint(Rectangle rect) { Triangle(graphics, 2, 1); Triangle(graphics, 1, 3); } }; f.visible = TRUE; ```defines a simple function that draws triangles that vary in shape and position based on arguments that are used to scale the matrix that is controlling the drawing. We used currentmatrix and setmatrix to save and restore the original matrix, which is changed by scale, to illustrate their use and to emphasize, by the placement of setmatrix, that the scaled matrix is automatically used as components, like lines, are added to the path but it is not used when fill is called to draw the path. This is a simple example, but there is plenty to learn, so experiment by moving setmatrix, removing closepath, replacing fill with stroke (pay close attention to the width of lines), and using gsave and grestore instead of currentmatrix and setmatrix. Pay careful attention to line widths when you try stroke instead of fill, because the matrix will make a subtle difference. See Also: Font, Graphics, Path

Yoix is a registered trademark of AT&T Inc.