pop_matrix(3G)

NAME

intpop_matrix2d, pop_matrix, pop_matrix2d, pop_matrix3d − remove matrix from top of matrix stack

SYNOPSIS

C Syntax:

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

void pop_matrix(fildes);
int fildes;

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

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

FORTRAN77 Syntax:

See Language Dependencies Below

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

subroutine pop_matrix(fildes)
integer*4 fildes

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

subroutine pop_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 intpop_matrix2d(fildes:integer;var xform2:int2d_xform;
var radix:integer;raw:integer);

procedure pop_matrix(fildes:integer);

procedure pop_matrix2d(fildes:integer;var xform:two_d_xform);

procedure pop_matrix3d(fildes:integer;var xform:three_d_xform);

DESCRIPTION

Input Parameters

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

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.

Output Parameters

xform2 3x2 (2-Dimensional) matrix.

xform3 4x4 (3-Dimensional) matrix.

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

Discussion

The top matrix on the matrix stack is called the current transformation matrix.

The pop_matrix procedure removes the top matrix from the matrix stack and throws it away.

The pop_matrix2d , intpop_matrix2d , and pop_matrix3d procedures are used to remove the top matrix from the matrix stack and return it in either xform2 or xform3. If in MODEL_XFORM mode (see gopen), the matrix is returned as is. Otherwise, the popped matrix is concatenated with the inverse of the current viewing transformation. This inverse calculation is numerically intensive and will be done the first time a Starbase function needs the inverse of the viewing matrix after changing the viewing matrix. After calling one of these functions, the new current transformation matrix is the next matrix on the matrix stack.

The vdc-to-device unit transformation matrix and the viewing transformation matrix cannot be popped or replaced using matrix functions. The vdc matrix can be changed using intvdc_extent, vdc_extent, vdc_justification, set_p1_p2, or mapping_mode. The viewing matrix can be changed using intview_matrix2d, intview_port, intview_window, view_camera, view_matrix, view_volume, or view_window. If the matrix stack is empty, pop_matrix generates a warning.

Starbase maintains all internal floating point matrices in three-dimensional (4x4) form, so pop_matrix2d must shrink the current transformation matrix down before returning it.

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.

If matrices need to be read back without popping them off the matrix stack, use read_matrices.

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 unit transformation matrix.

Museum

Related Articles