push_matrix(3G)

NAME

push_matrix2d, push_matrix3d, intpush_matrix2d − push matrix onto top of matrix stack

SYNOPSIS

C Syntax:

void push_matrix2d(fildes,xform2);
int fildes;
float xform2[3][2];

void push_matrix3d(fildes,xform3);
int fildes;
float xform3[4][4];

void intpush_matrix2d(fildes,xform2,radix,raw);
int fildes,xform2[3][2],radix,raw;

FORTRAN77 Syntax:

See Language Dependencies Below

subroutine push_matrix2d(fildes,xform2)
integer*4 fildes
real xform2(2,3)

subroutine push_matrix3d(fildes,xform3)
integer*4 fildes
real xform3(4,4)

subroutine intpush_matrix2d(fildes,xform2,radix,raw)
integer*4 fildes,xform2(2,3),radix,raw

Pascal Syntax:

type
int2d_xform = array [1..3][1..2] of integer;
two_d_xform = array [1..3][1..2] of real;
three_d_xform = array [1..4][1..4] of real;

procedure push_matrix2d(fildes:integer;
var xform2:two_d_xform);

procedure push_matrix3d(fildes:integer;
var xform2:three_d_xform);

procedure intpush_matrix2d(fildes:integer;
var xform2:int2d_xform;
radix,raw:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

xform2 3x2 (2-Dimensional) matrix.

xform3 4x4 (3-Dimensional) matrix.

radix is the radix factor for the 3x2 integer matrix.

raw If set to TRUE(1), integer matrices will be in internal (raw) format (i.e. translation values are not scaled).
If set to FALSE(0), all integer matrix values are scaled.

Discussion

The current transformation matrix (on top of matrix stack) is pushed to the second matrix position on the matrix stack. If the graphics device has been opened in MODEL_XFORM mode, the matrix parameter, xform2 or xform3, is placed on the top of the matrix stack. If the device is not in MODEL_XFORM mode, the matrix parameter is concatenated with the current viewing transformation matrix and the result is placed on the top of the matrix stack. The new transformation matrix is used to transform subsequent output primitives.

The coordinate systems used by Starbase can be conceptually defined as follows:

1. User points are assumed to be defined in modelling coordinates. These points are transformed into world coordinates using a matrix called the modelling transformation matrix (if any matrices have been pushed on the stack). World coordinates are used to perform any necessary rendering calculations. Use push_matrix to place modelling transformations on the matrix stack after defining the viewing transformation.

2. World coordinates are transformed to device coordinates by the viewing transformation matrix which is usually the concatenation of user-defined viewing transformations and the vdc-to-device transformation matrix. When a device is opened, the viewing transformation matrix is simply the vdc-to-device coordinate transformation matrix. The user can define further viewing transformations (such as perspective) with intview_window, intview_port, intview_matrix2d view_camera, view_matrix, view_port, view_volume, or view_window.

If a graphics device has been opened in MODEL_XFORM mode, special rendering calculations such as shading may be needed after the modelling-to-world-coordinate transformation. Therefore the modelling transformation cannot be combined with the viewing transformation. Thus, matrices pushed on the stack are left as is; all transformations from modelling coordinates to device coordinates occur in two steps: modelling-to-world-coordinates, followed by world-to-device-coordinates.

If a graphics device is not in MODEL_XFORM mode, the modelling and viewing transformations can be combined: The current viewing transformation matrix is post-concatenated to modelling matrices placed on the matrix stack, while subsequent output primitives are transformed using only the top matrix on the matrix stack.

Starbase maintains all internal floating point matrices in 3D (4x4) form, so push_matrix2d must expand the 2d matrix xform2.

Perspective transformations (as well as any other non-linear or viewing transformation) should not appear in modelling matrices because they distort surface normals and invalidate lighting calculations. Rather, they should appear in the viewing transformation which is set with view_matrix. When performing perspective transformations, a perspective model where the eye is at origin of perspective space is recommended. Any other model can easily be modified by a single translation step.

Integer transformation matrices are scaled to allow a fractional portion for rotating objects. The radix factor indicates the number of bits to the right of the decimal point. Legal limits are 0 to 30. Once a coordinate has been transformed, it is divided by 2**radix to return to an integer value.

When using raw mode with an integer matrix, positions (3,1) and (3,2) have an implied radix factor of 0(no scaling). This allows large translation ranges along with accurate rotations.

Integer operations are only available when using the INT_XFORM gopen mode. When in INT_XFORM mode, floating point operations are not available for that fildes. Floating point operations are the default, or can be specified with FLOAT_XFORM mode. For a list of integer operations, floating point operations and common operations see the starbase.3g manual page.

LANGUAGE DEPENDENCIES

FORTRAN77: FORTRAN requires a transposition of array rows and columns due to the manner in which FORTRAN77 stores arrays.

DEFAULTS

After gopen, the current transformation matrix is the vdc-to-device units transformation matrix.

Museum

Related Articles