'\"!  tbl | mmdoc
.if n .pH arch.transform @(#)transform	40.1

.ig
imaged dc 8/30/89
docformat -c -s4 -p1 -dqm4 fn
..
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.nh
.ds S) Shapes
.BK "Shapes Internal Architecture"
.CH "The TRANSFORM Object" "6"
.H 1 "The TRANSFORM Object"
.H 2 "Introduction"
Transform objects are used to describe
transformations that can be done on coordinates
such as translation, rotation, and scaling.
Internally, such transformations are represented
in terms of a 4\|\(mu\|4 matrix.
.P
Because many accelerators provide hardware for transformation,
some of the transform operators are
device-dependent on such devices.
Mul_Transform and Path_Transform are the most
likely to be device specific.
.P
The external transform attributes are documented in the
\f2Shapes Reference Manual\f1
This section discusses the internal attributes
that are used in the implementation of the
transform object.
All transform attributes are defined in
include/sh_TRANS.ah;
their values are defined in include/sh_TRANS.h
and include/di/trans.h.
.PC
OBJ_KEY      trans_key;
Unsgn8       TRANS_TYPE;
Unsgn8       trans_flags;
unsigned int trans_mode : 3;
unsigned int trans_select : 5;
CONTEXT      trans_ctx;
void         (*trans_val_func)();
MTX_FLT      trans_data;
.SF
.H 2 TRANS_TYPE
.P
This variable defines the dimension (2D or 3D),
data type (float or fract),
and matrix complexity
(identity, scaling, translation, or rotation).
It is the only user-accessible transform attribute.
Type is used to optimize multiplication of
transforms with other transforms or points,
as well as to select rendering pipelines.
.P
You can use type information to speed up calculations:
.BL
.LI
Use 2D rather than 3D matrices whenever possible.
.LI
Specify floating point calculations whenever
accuracy is critical and fract calculations at
other times.
.LI
Shapes coordinates the calculation process
according to the complexity of the function \(em
identity through translation, scaling, and rotation.
.LE
.SK
.TB "Transform Type"
.TS
box tab(%);
cf4I | cf4I
l | l.
Flag%Description
=
TRANS_3D%3D matrix
TRANS_2D%2D matrix
_
TRANS_FLT%floating point
TRANS_BIN%fract
_
TRANS_TRANSLATE%translation
TRANS_SCALE%scaling
TRANS_ROTATE%rotation
TRANS_IDENTITY%identity matrix
.TE
.TT
.H 2 trans_data
.P
The transformation data variable defines the 4\|\(mu\|4
matrix data associated with the transform.
The trans_data definition of a floating point
transform is MTX_FLT;
it is MTX_BIN for a fixed point binary (fract) transform.
In either case,
the matrix contains sixteen 32-bit numbers.
.H 2 trans_inv
.P
The transformation inverse contains the 4\|\(mu\|4 matrix
data associated with the inverse of the transform.
This matrix is not always valid.
The TRANS_FLAGS_IVAL bit in the trans_flags
indicates that trans_inv is the valid inverse.
.H 2 trans_flags
.P
The transform flags variable defines the state of
the matrix.
Currently there is only one flag, TRANS_FLAGS_IVAL,
that indicates that the inverse of the matrix has
been computed and is stored in trans_inv.
.H 2 trans_key
.P
The transform key changes whenever the transform
is updated.
It can be used by other objects to determine if
the transform has changed between operations.
.P
.H 2 "Transform Operators"
The calling conventions of the external transform
operators are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the implementation of
these operators,
assuming the reader is familiar with their behavior.
We also describe internal transform operators
that are used by \*(S) but not intended to be user-callable.
All transform operators are defined in include/sh_TRANS.h.
.H 2 Scale_Transform
.P
Pre-concatenates a scale transform onto the given transform.
Scale_Transform optimizes the case where the
original transform is also a scale transform.
It will multiply the x, y, z components of the
input point with the scale factors of the
transform rather than do a full matrix multiplication.
.H 2 Translate_Transform
.P
Pre-concatenates a translation transform onto the
given transform.
Translation_Transform optimizes the case where
the original transform is an identity or
translation transform.
It will add the x, y, z components of the input
point to the translation factors of the transform
rather than do a full matrix multiplication.
.H 2 Rotate_Transform
.P
Pre-concatenates a rotation transform onto the
given transform.
Rotate_Transform optimizes the case where the
rotation angle is given in fract degrees by using
the frsincosd routine to calculate the rotation factors.
.H 2 Write_Transform
.P
Allows the user to import a 4\|\(mu\|4 matrix.
If the user does not specify TRANS_TYPE flags,
Write_Transform will inspect the contents of the
matrix and try to determine how to set TRANS_TYPE.
.H 2 Transpose_Transform
.P
Stores the transpose of a source transform into a
destination transform.
Transpose_Transform detects the case where the
transpose and the original matrix are the same
and uses Copy_Transform.
.H 2 Invert_Transform
.P
Stores the inverse of a source transform into a
destination transform.
When the inverse is computed,
it is saved in the trans_inv attribute and the
TRANS_IVAL flag is set in trans_flags.
.P
Several optimizations are done when computing the inverse:
.BL
.LI
The inverse of a scale transform is taken by
computing the reciprocals of the scale factors.
.LI
The inverse of a translation transform is taken
by computing the negatives of the translation factors.
.LI
The inverse of a rotation transform is taken by
transposing the rotation matrix.A
.LI
The inverse of an identity is noted to be an identity.
.LI
The inverse of a 2D matrix is done by expanding
the equations.
.LI
All other cases are handled by Gaussian elimination.
This is slow,
which is why we do all the above optimizations.
.LE
.H 2 Mul_Transform
.P
Multiplies two arbitrary transforms and stores
the result in a third.
Mul_Transforms optimizes for fract and 2D and
notes when one of the operands is an identity matrix.
.H 2 "Point_Transform, InversePoint_Transform"
.P
These routines transform a coordinate by the
input transform or its inverse respectively.
They are heavily optimized for various
combinations of the transform type and the point type.
Note that both Point_Transform and
InversePoint_Transform depend on the bits in the
transform type and point type for their internal dispatching.
Changes to any of the TRANS_xxx or PT_xxx bits
could break these routines.
The routines used by Point_Transform are also
called by the path transformation pipelines to
transform coordinates.
.H 2 "The Viewing Pipeline"
.P
The graphics viewing pipeline has 3 separate components:\ \&
transformation (model, view),
clipping to view volume,
and VDC to raster mapping.
Individual parts of the viewing pipeline can be
enabled or disabled by the CTX_PIPELINE attribute.
All or none of the three context transforms,
CTX_MODEL_TRANSFORM, CTX_VIEW_TRANSFORM,
or CTX_VDC_TRANSFORM, may be enabled.
If more than one these is selected,
the viewing transformation applied to coordinates
is the concatenation of the selected transformations.
Internally, view clipping is done in raster space.
Whenever the viewing transformation changes,
internal representations of the view volume
must also be updated.
.P
Instead of performing these calculations
whenever anything in the viewing pipeline changes,
\*(S) maintains flags in the context indicating
which part of the viewing pipeline is no longer valid.
Whenever a context attribute pertaining to the
pipeline changes,
the part of the pipeline it affects is flagged.
At the point where the viewing pipeline is actually used,
when a path is transformed or rendered,
these flags are checked to decide whether the
pipeline must be validated and which parts need
to be recomputed.
.P
Until a transform is selected,
it may not be allocated memory.
If CTX_PIPELINE has never enabled CTX_APPLY_MODEL,
the value of the CTX_MODEL_TRANSFORM attribute
(and that of ctx_trans_mv) may be NULL.
.H 2 INVALIDATE_PIPELINE
.P
Invalidates the given part of the viewing pipeline by setting
one of the bits in ctx_pipe_flags.
For example,
INVALIDATE_PIPELINE(ctx,TRANS) is called whenever one of the
pipeline transforms is changed.
It sets the CTX_TRANS_CHANGED bit in ctx_pipe_flags.
If context attributes which affect the pipeline
(clip origin, dimensions, VDC mapping) are changed,
INVALIDATE_PIPELINE sets CLIP or VDC flags.
.H 2 VALIDATE_PIPELINE
.P
When the pipeline is applied to a path,
VALIDATE_PIPELINE is called.
It examines ctx_pipe_flags.
If it is non-zero,
Validate_Transform is called to recalculate ctx_ctm.
.H 2 "Context Transforms"
.P
If the transform is used as a part of the
graphics pipeline of a context,
it contributes to the \f2current transform\fP.
The attributes and macros that follow apply only
to transforms that are part of the context's
viewing pipeline.
Only transforms that are referenced by CTX_MODEL_TRANSFORM,
CTX_VIEW_TRANSFORM, CTX_VDC_TRANSFORM,
or ctx_trans_mv use the internal fields below.
.H 2 trans_ctx
.P
Associates this transform with a specific context
as model, view, VDC,
or concatenated product (ctx_trans_mv).
A transform can only be associated with one context at a time.
Although it contains an object handle,
trans_ctx is not reference counted.
.H 2 trans_mode
.P
Indicates whether the transform is used as either
a construction or rendering transform and whether
it is the viewing pipeline transformation.
.TB "Tranform Mode"
.TS
box tab(%);
cf4I | cf4I
l | l.
Flag%Description
=
NULL%not used in pipeline	
CTM_CONSTRUCT%used in path construction
CTM_RENDER%used in rendering
CTM_PIPELINE%is the pipeline transform
.TE
.TT
.H 2 trans_select
.P
This variable indicates what part of the viewing
pipeline this transform represents.
It may represent just one transform,
or it may OR together to represent a
concatenation of transforms.
.P
.TB "Transform Select"
.TS
box tab(%);
cf4I | cf4I
l | l.
Flag%Description
=
NULL%not a context transform
CTX_APPLY_VIEW%incorporates view transform
CTX_APPLY_MODEL%incorporates model transform
CTX_APPLY_VDC%incorporates VDC transform
.TE
.TT
.H 2 trans_val_func
.P
Pointer to the viewing pipeline validation function.
This is set by Pipeline_Context and is called by
Validate_Transform whenever the viewing pipeline
needs to be recomputed.
.H 2 CTX_MODEL_TRANSFORM
.P
Context attribute that references the current
model transform.
The trans_select value is always CTX_APPLY_MODEL.
If NULL, no model transform exists.
.H 2 CTX_VIEW_TRANSFORM
.P
Context attribute that references the current view transform.
The trans_select value is always CTX_APPLY_VIEW.
If NULL, no view transform exists.
.H 2 CTX_VDC_TRANSFORM
.P
Context attribute that references the current VDC transform.
The trans_select value is always CTX_APPLY_VDC.
If NULL, no VDC transform exists.
.H 2 ctx_trans_mv
.P
Internal context field that represents the
viewing pipeline transform if more than one
transformation is selected by CTX_PIPELINE.
This is where the concatenated product is stored.
The trans_select value is always CTX_APPLY_MODEL |
CTX_APPLY_VIEW | CTX_APPLY_VDC.
If NULL, no concatenation is required.
.H 2 ctx_ctm
.P
Internal context field that represents the
current viewing pipeline transform.
It may be one of sh_fb_identity_bin,
CTX_MODEL_TRANSFORM, CTX_VIEW_TRANSFORM,
CTX_VDC_TRANSFORM, or ctx_trans_mv.
It is not referenced counted and is never NULL.
.H 2 ctx_trans_render
.P
Internal context field that represents the
current render transform.
If CTX_PIPELINE does not enable CTX_APPLY_RENDER,
it is set to sh_fb_identity_bin.
Otherwise, it is the same as ctx_ctm and is not
reference counted.
.H 2 Update
.P
If the transformation belongs to the viewing pipeline
(that is, trans_mode has CTM_RENDER or CTM_CONSTRUCT set),
changing its value has side effects.
If it is the current construction transformation (CTM_CONSTRUCT),
it is applied to the pending path points before
it is changed.
If it is the render transform (CTM_RENDER)
and we are in immediate mode,
any operations accumulated in the current path
must be rendered.
In either case,
the transformation part of viewing pipeline must
be invalidated.
Any transform operator that changes the contents
of the trans_data field must call Update before
returning.
.H 2 Validate_Transform
.P
Invokes the current transform validation function, trans_val_func,
to compute the viewing pipeline transformation.
Typically, Validate_Transform is only invoked
from the pipeline validation macro
VALIDATE_PIPELINE and only if the pipeline
validation flags have been set.
See the description of ctx_pipe_flags in Chapter 3.
.H 2 "Pipeline_Context(ctx, trans)"
.P
Called when one of the pipeline transforms is set
to a new value.
In this capacity,
Pipeline_Context disassociates the old
transform from the viewing pipeline and attaches
the new one.
.BL
.LI
transform current path (Update_Path) by old transform
.LI
select validation function for new transform
.LI
invalidate viewing pipeline (TRANS & CLIP)
.LI
set trans_ctx to the current context
.LI
set CTM_RENDER or CTM_CONSTRUCT in trans_mode
.LI
set trans_select to one of CTX_APPLY_MODEL,VIEW,VDC
.LI
clear trans_ctx, trans_mode,
trans_select of old transform
.LE
.H 2 "Pipeline_Context(ctx, NULL)"
.P
Called when the CTX_PIPELINE attribute is changed.
In this case,
Pipeline_Context establishes a new viewing pipeline.
.BL
.LI
clear trans_mode for model, view, VDC (deselecting them)
.LI
invalidate viewing pipeline
.LI
set ctx_ctm to identity, model, view, VDC or ctx_trans_mv
based on CTX_PIPELINE value (see table below)
.LI
select trans_val_func to the appropriate function
to validate the viewing pipeline when
Validate_Transform is invoked
.LI
set CTM_PIPELINE and CTM_RENDER or CTM_CONSTRUCT
in trans_mode
.LE
.P
.TB "Pipeline Transform Selection"
.TS
center box tab(@);
cf4I |cf4I
l | l .
Pipeline@Transform Selected
=
NULL@sh_identity_trans_bin
_
CTX_APPLY_VDC@CTX_VDC_TRANSFORM
_
CTX_APPLY_VIEW@CTX_VIEW_TRANSFORM
_
CTX_APPLY_MODEL@CTX_MODEL_TRANSFORM
_
CTX_APPLY_MODEL@ctx_trans_mv
CTX_APPLY_VIEW@
_
CTX_APPLY_MODEL@ctx_trans_mv
CTX_APPLY_VDC@
_
CTX_APPLY_VIEW@ctx_trans_mv
CTX_APPLY_VDC@
_
CTX_APPLY_MODEL@ctx_trans_mv
CTX_APPLY_VIEW@
CTX_APPLY_VDC@
.TE
.TT
