replace_matrix(3G)

NAME

replace_matrix2d, replace_matrix3d, intreplace_matrix2d − replace current transformation matrix with a specified matrix

SYNOPSIS

C Syntax:

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

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

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

FORTRAN77 Syntax:

See Language Dependencies Below

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

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

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

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 intreplace_matrix2d(fildes:integer;var xform2:int2d_xform;
radix,raw:integer);

procedure replace_matrix2d(fildes:integer;xform2:two_d_xform);

procedure replace_matrix3d(fildes:integer;var xform3:three_d_xform);

DESCRIPTION

Input Parameter

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

xform2 A 3x2 (2-dimensional) matrix.

xform3 A 4x4 (3-dimensional) matrix.

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

raw If set 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 (top of matrix stack) is replaced by the specified matrix, xform2 or xform3. The matrix is concatenated with the current viewing transformation matrix before the replacement is made. If the graphics device has not been opened in MODEL_XFORM mode, the matrix is concatenated with the current viewing transformation matrix before the replacement is made. The current transformation matrix is used to transform subsequent output primitives.

The vdc-to-device units-transformation matrix cannot be replaced using replace_matrix2d, intreplace_matrix2d, or replace_matrix3d. It can be changed using intvdc_extent, vdc_extent, vdc_justification, set_p1_p2, or mapping_mode. Likewise, the viewing transformation matrix cannot be replaced using these functions. It can be changed using intview_matrix2d, intview_port, intview_window, view_camera, view_port, view_matrix, view_volume, or view_window. If there are no matrices in the matrix stack, replace_matrix generates a warning.

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

1. It is assumed that user points are defined in modelling coordinates. These points are transformed into world coordinates using a matrix called the modelling transformation matrix (provided a matrix has been pushed on the stack). World coordinates are used to perform any rendering calculations needed. Use replace_matrix to place modelling transformations on the matrix stack.

2. World coordinates are then 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 consists of the vdc-to-device coordinate transformation matrix. Viewing functions can be used to define further viewing transformations such as perspective. When a device is opened the viewing transformation matrix is simply the vdc-to-device coordinated transformation matrix. Intview_window, intview_port, intview_matrix2d, view_window, view_port, view_matrix, view_camera, and view_volume can be used to define further viewing transformations.

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. For this reason, the modelling transformation cannot be combined with the viewing transformation. Thus, matrices pushed on the stack are left as is and 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 then the modelling and viewing transformations may be combined; thus the current viewing transformation matrix is post-concatenated to modelling matrices placed on the matrix stack and subsequent output primitives are transformed by the top matrix on the matrix stack only.

Starbase maintains all internal floating point matrices in 3-dimensional (4x4) form, so replace_matrix2d must expand the matrix xform2.

Perspective transformations (as well as any other non-linear or viewing transformation) should not appear in modelling matrices since this will distort surface normals, invalidating 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:
A transposition of array rows and columns is required 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