'\"!  tbl | mmdoc
.if n .pH arch.context @(#)context	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
..
.ds S) Shapes
.BK "Shapes Internal Architecture"
.CH "The CONTEXT Object" "3"
.H 1 "The CONTEXT Object" 
.H 2 "Introduction"
The context objects contains the graphics state
that specifies precisely how \*(S) will draw an image.
This information is used to dispatch
to device-dependent rendering routines.
.P
Although much of the context implementation is
shared among all framebuffer ports
(attribute setting, handling the current path,
attaching to a raster),
some operations can be device dependent.
.H 2 "The Context Header" Ctx_Hdr
.P
The external context attributes are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the internal attributes that are
used in the implementation of the context object.
All context attributes are defined in include/sh_CTX.ah;
and their values are defined in include/sh_CTX.h
and include/di/fb_ctx.h.
For clarity, we have omitted fields that are not
included in the SH_SMALL compilation.
.PC
.nf
RASTER           CTX_RASTER;
Unsgn8           CTX_ERROR;
Unsgn8           CTX_TYPE;
CTX_shade        CTX_SHADE;
CTX_pipeline     CTX_PIPELINE;
CTX_area_style   CTX_AREA_STYLE;
CTX_fill_style   CTX_FILL_STYLE;
CTX_rop          CTX_ROP;
CTX_line_cap     CTX_LINE_CAP;
CTX_line_join    CTX_LINE_JOIN;
CTX_line_style   CTX_LINE_STYLE;
CTX_plane_enable CTX_PLANE_ENABLE;
fract            CTX_LINE_SIZE;
fract            CTX_MITER_LIMIT;
PATTERN          CTX_LINE_PATTERN;
COLOR            CTX_COLOR;
COLOR            CTX_BACK_COLOR;
TRANSFORM        CTX_VIEW_TRANSFORM;
RASTER           CTX_FILL_RASTER;
POINT_B2D        CTX_FILL_ORG;
PATH             CTX_PATH;
PATH             CTX_CLIP_PATH;
POINT            CTX_RASTER_PEN;
Unsgn32          CTX_FLATNESS;
OBJ_KEY          ctx_clip_key;
PATH_POINT       *ctx_buf_top;
PATH_POINT       *ctx_buf_ptr;
PATH_POINT       *ctx_buf_end;
TRANSFORM        ctx_ctm;
unsigned int     ctx_curve_form : 4;
unsigned int     ctx_curve_order : 4;
Unsgn8           ctx_pipe_type;
Unsgn8           ctx_pipe_disp;
Unsgn8           ctx_draw_disp;
unsigned int     ctx_pipe_flags : 3;
.fi
.SF
.H 2 ctx_clip_key
.P
Helps determine if the raster/context clip shape needs to be recomputed.
When the raster/context clip shape is established,
a copy of ctx_clip_key is saved in the raster (as ras_clip_key).
Whenever CTX_CLIP_PATH is updated, ctx_clip_key is changed.
Similarly, updating RAS_CLIP_PATH causes ras_clip_key to be changed.
Each time something is rendered to a raster,
ctx_clip_key is compared to ras_clip_key.
If they are different, the raster/context clip is recomputed.
.H 2 "ctx_buf_top, ctx_buf_end, ctx_buf_ptr"
.P
Maintain pointers to the top and end of the path data area,
and the next available position in the current path.
These pointers are used and updated by the drawing operators
(Draw_XXX, Color, Close, CloseSub, Curve)
to facilitate path construction.
They are initialized when a path
becomes associated with a context
and are updated if the path is extended by reallocation.
Corresponding offsets (path_data, path_end, path_cur)
exist within each path object.
Any path that belongs to a context
also has a reference to the context.
This reference is used to update the internal
path pointers from their context copies whenever
the path is accessed directly
(rather than via the context).
Path construction is documented more fully in
Chapter 7.
.H 2 ctx_curve_form
.P
Specifies the curve form used to interpret curve control points.
See the Curve() macro in the reference manual.
.H 2 ctx_curve_order
.P
Specifies the curve order used to interpret curve control points.
Options are of order three or four.
.H 2 ctx_ctm
.P
TRANSFORM object that represents the current viewing pipeline transform.
If transforms are not enabled,
it is set to an identity transform.
If only one of the viewing transforms is selected,
ctx_ctm is set to that transform.
In any case,
this transform always exists and is initialized appropriately.
Although it is may contain an object handle,
ctx_ctm is not reference counted.
See Chapter
6 for a more
complete description of how the viewing
pipeline is handled.
.H 2 ctx_pipe_type
.P
These flags select which type of path rendering pipeline
is used to render a path (vector, area, outline, and hollow).
.TB "Pipeline Selection Flags"
.TS
box tab(@);
cf4I cf4I
l | l.
Flag@Description
=
FB_PIPE_AREA@Filled areas (polygons, curve bounded regions)
FB_PIPE_OUTLINE@Thick, patterned, and/or hollow outlines
FB_PIPE_VEC@Thin, solid, fast vectors & curves
FB_PIPE_HOL@Thin, solid vectors & curves with closure
.TE
.TT
.P
For each of the path rendering pipelines,
there are two types of tables:\ \&
path transformation, and low-level rendering.
The path transformation function is
selected by ctx_pipe_type and ctx_pipe_disp.
The low-level rendering
function is selected by ctx_draw_disp.
.H 2 ctx_pipe_disp
.P
These flags determine which function is selected to transform
and render a path.
They are combined with the TRANSFORM type flags in
TRANS_TYPE to select a specific function used to parse the path.
This function applies the coordinate transformations and calls
lower-level drawing functions (selected by ctx_draw_disp, see below)
to render individual primitives.
.TB "Pipeline Dispatch Flags"
.TS
box tab(@);
cf4I cf4I
l | l.
Flag@Description
=
FB_PIPE_SHAPE@non-rectangular clip
FB_PIPE_3D@3D enabled
FB_PIPE_CLIP@view clipping enabled
FB_PIPE_CM@close on move enabled
.TE
.TT
.H 2 ctx_draw_disp
.P
Selects a set of low-level rendering functions by setting global
dispatch vectors that are called by
the path transformation functions (see above).
The details of this selection are described more fully in
Chapters  7 and 13.
.TB "Drawing Dispatch Flags"
.TS
box tab(@);
cf4I cf4I
l | l.
Flag@Description
=
FB_DRAW_PLANES@bit planes selected
FB_ROP_FIELD@raster op
FB_DRAW_AREA_STYLE@fill style
.TE
.TT
One or more of the following global pointers are set
up to reference a specific rendering routine.
Which pointers are set up depends on which path rendering
pipeline is selected by ctx_pipe_type.
.TB "Global Pointers"
.TS
box tab (@);
cf4I | cf4I
l | l.
Pointer@Description
=
RND_Shape@Fill shape with color or texture
RND_Line@Draw vector or linear edge
RND_Curve@Draw curve segment or curved edge
RND_Pgon@Render polygon edge table
RND_Curve_Pipe@Curve transformation
.TE
.TT
.H 2 ctx_pipe_flags
.P
The graphics viewing pipeline has three separate components:\ \&
transformation (model, view), clipping to view volume,
and VDC to raster mapping.
If an context attribute pertaining to the pipeline changes,
the part of the pipeline it affects is invalidated by
setting a designated flag in ctx_pipe_flags.
For example,
whenever any of the transforms selected by CTX_PIPELINE is changed,
the CTX_TRANS_CHANGED flag is set.
When the pipeline is applied to a path, ctx_pipe_flags is examined.
If it is non-zero, the viewing pipeline is recomputed.
Chapter 6 discusses
the operation of the viewing pipeline in more detail.
.TB "Pipeline Validation Flags"
.TS
box tab (@);
cf4I | cf4I
l | l.
Flag@Description
=
CTX_TRANS_CHANGED@current transform changed
CTX_CLIP_CHANGED@view clip changed
CTX_VDC_CHANGED@VDC mapping changed
.TE
.TT
.H 2 "Context Operators"
.P
The calling conventions of the external context 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 context operators that are used by \*(S)
but not intended to be user-callable.
All context operators are defined in include/sh_CTX.h.
.H 2 Get_Context
.P
All of the context attributes are inquired via macros.
The name of the attribute is used to generate a specific macro to
return the structure field associated with the attribute.
Macros for attributes that require computation generate calls
to the internal Get_Context operator.
Currently, only CTX_PEN, CTX_RASTER_PEN,
CTX_PATH_PEN, CTX_PATH_RASTER_PEN,
and CTX_ERROR require a subroutine call.
.P
The following section of code shows the macro definitions for
two context attributes to illustrate the two different methods:
.PC
.nf
#define Get_Context(c,a)  CAT(a,get)((CONTEXT)(c))
#define CTX_SHADEget(v)   ((v)->CTX_SHADE)
#define CTX_PENget(v) ((POINT *)
                      GetOper_Obj(v, CTX_OP_Get)(v,CTX_PEN))
.fi
.SF
.H 2 Set_Context
.P
As with Get_Context, Set_Context is implemented as a macro that
uses the attribute name to generate a unique macro to set
each attribute.
Unlike Get_Context, almost all attributes are ultimately set
via subroutine call.
Very few are done with in-line code because setting
most attributes can have side effects that are
possibly device-dependent.
.P
Since many Set_Context calls result in setting
the attribute to the same value,
we optimize for this case by having macros for
frequently used attributes check the value
against the current value before they call the subroutine.
Note that there are two internal subroutines that
set attributes:\ \&
one handles integer and pointer attributes,
and the other takes care of attributes whose
values are floating point.
\*(S) assumes that integers and pointers are the same size.
.PC
.nf
#define Set_Context(c,a,v)     CAT(a,set)((CONTEXT) (c),a,v)
#define CTX_CALL_SET_I(c,a,v)  GetOper_Obj(c, CTX_OP_Set_I)
                                          (c,a,v)
#define CTX_CHK_N_SET_I(c,a,v) (Get_Context(c,a) != v) ?
                                CTX_CALL_SET_I(c,a,v) : 0
#define CTX_SHADEset(a,b,c)    CTX_CHK_N_SET_I(a,b,c)
#define CTX_PENset(a,b,c)      CTX_CALL_SET_I(a,b,c)
.fi
.SF
.H 2 Copy_Context
.P
Because it is used by NeWS to implement the PostScript
gsave and grestore operations,
Copy_Context is optimized at the expense of clarity.
It has internal knowledge of the transform and path objects.
For this reason, Copy_Context may need to be device-dependent
if either the transform or the path object has a different
data format than the generic implementation.
.H 2 Clear_Context
.P
Clear_Context is implemented as a macro that calls the
device-dependent Clear_Raster operator
(see Chapter 4).
.H 2 "Display_Context, Display_Path"
.P
Display_Context and its companion operator, Display_Path,
are both implemented as macros that call an internal
raster operator (Path_Raster).
This scheme permits generic context code to be used while
allowing rendering to be completely device-dependent.
The operation of Path_Raster is described in
Chapter 4.
.H 2 Winview_Context
.P
Computes the appropriate VDC transformation to map the clip volume
onto the raster coordinate space.
The operation of Winview_Context depends on the
VDC mapping chosen (CTX_VDC_MAP).
It is called when the viewing pipeline is validated if the
CTX_VDC_CHANGED flag is set in ctx_pipe_flags.
See Chapter 6
for a thorough description of the viewing pipeline.
.H 2 Pipeline_Context
.P
Recalculates the viewing pipeline.
It is called whenever CTX_PIPELINE is set or when one of the
transforms in the viewing pipeline is changed.
This operator is usually device-dependent on accelerators
that have transformation hardware.
See Chapter 6
for a better description of Pipeline_Context.
.H 2 Extend_Context(ctx)
.P
Extends the current path by a fixed amount.
This operator is used by the path construction macros
(in include/sh_draw.h)
when the current path is not large enough to accommodate another element.
Extend_Context updates both the context pointers
(ctx_buf_top, ctx_buf_end, ctx_buf_ptr) and their counterparts
in the path header (path_data, path_end, path_cur).
Chapter 7
describes the implementation of the current path in detail.
.H 2 "Attach_Raster(ras, ctx)"
.P
Attach_Raster associates a different raster with the current context.
When a context is bound to a raster,
that context takes on the same class type as the raster.
Switching the class type (OBJ_CLASS_TYPE)
selects a new dispatch vector for the context operators.
This may change the implementation of some operations,
selecting device-specific functions for things like Pipeline_Context.
The class type of the current viewing transformation, ctx_ctm,
is also set to the raster class type,
allowing device-dependent transformation operations as well.
.H 2 "Rendering Pipelines" Ctx_Rendr
.P
\*(S) currently supports several types of pipelines.
Which of these pipeline types is chosen depends on certain bit fields in
the pipeline selector, ctx_pipe_type.
This selection is done by the Path_Raster operator
when a request is made to render a path
(via to Display_Context or Display_Path).
.BL
.LI
The Vector pipeline transforms, clips, and renders solid color,
single pixel width vectors, and curve segments.
It is optimized for paths that contain only vector endpoints,
no closure.
.LI
The Hollow pipeline transforms, clips, and renders solid color,
single pixel width vectors, and curve segments.
It also handles Close and CloseSub.
.LI
The Area pipeline transforms, clips, and renders filled areas
(which may be polygons or curve-bounded regions).
The path coordinates are converted to a polygon edge list.
.LI
The Outline pipeline transforms,
clips, and renders patterned, textured,
thick vectors, and curve segments.
It inputs a source path containing the original line endpoints and outputs
a path describing these lines in wide dashed form.
For thin, dashed vectors, the output path contains vectors, one for each dash.
For wide vectors (dashed or not), the output path contains polygons.
Unless round endcaps and joins are selected, the output path for wide lines
is usually composed of quadrilaterals and triangles.
The output path is then rendered using the appropriate vector or area pipeline.
.LE
.P
Each of the pipeline types above actually represent a set of pipelines
that traverse the path object.
They differ in that each is optimized for a special case.
The exact pipeline chosen to render the path is determined by
characteristics of the path rendering transform and selected.
.P
When a request is made to render a path,
the pipeline selection flags in ctx_pipe_disp are
combined with the transformation flags in trans_type,
and the result is used to index into a dispatch table
of path-rendering pipeline functions SCR_PATH_FUN
table from the SCREEN object for the device/raster.
.P
If a path contains closure information,
the coordinates of the most recent MOVE must be maintained.
If a path contains only vector endpoints (no closure),
it can be more optimally rendered in some cases.
A flag is maintained in the path flags field which is
set whenever Close() or CloseSub() is invoked to indicate
the path contains closure information.
If this flag is set when a path is rendered as vectors,
the more general hollow pipeline is selected.
Otherwise, the more optimal vector pipeline is used.
.P
The table below enumerates the entire set of path rendering pipelines
currently available in the \*(S).
Note that more cases are optimized via separate pipelines
for vectors than for areas.
.TB "Path Rendering Pipelines (sh_fb_pipe_fun)"
.TS
box tab(@);
cf4I | cf4I  | cf4I
l | l | l .
Type@Function@Description
=
Vector@vec_pipe_tr_b2d@fract 2D translation only
@vec_pipe_sc_b2d@Fract 2D scaling and translation only
@vec_pipe_xf_b2d@Fract 2D general transform
@vec_pipe_sc_f2d@Float 2D scaling and translation only
@vec_pipe_xf_f2d@Float 2D general transform
_
Area@area_pipe_sc_b2d@Fract 2D translation only
@area_pipe_xf_b2d@Fract 2D general transform
@area_pipe_sc_f2d@Float 2D scaling and translation only
@area_pipe_xf_f2d@Float 2D general transform
_
@hol_pipe_sc_b2d@Fract 2D scaling and translation only
@hol_pipe_xf_b2d@Fract 2D general transform
@hol_pipe_sc_f2d@Float 2D scaling and translation only
@hol_pipe_xf_f2d@Float 2D general transform
.TE
.TT
