'\"!  tbl | mmdoc
.if n .pH arch.dispatch @(#)dispatch	40.1
.ig
imaged dc 8/30/89
docformat -c -s4 -dqm4 fn
..
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.ds S) Shapes
.BK "Shapes Internal Architecture"
.CH "Dispatching" "13"
.H 1 "Dispatching" 
.H 2 "Introduction"
.P
.nh
Dispatching allows a core of code to request a
common set of rendering primitives that are
independent of the device-dependent methods used
to render those primitives.
In other words,
you can have device-dependent methods for each
rendering primitive.
.P
Much of the power of \*(S) comes from its
structural framework,
which supports built-in replacement functionality.
Replacement ranges from complete replacement of
entire classes of rendering operations to
replacement of individual operations that vary
from each other by as little as a single
rendering attribute.
\*(S) contains distinct levels,
which are downwardly accessible via indirect
function calls through dispatch vectors.
.H 2 "Global Dispatch Vectors"
.P
The global dispatch vectors at the uppermost
levels include the general class of primitives
that must be supported on all devices.
They are part of the global rendering context discussed
later in this chapter.
The rendering macros and their corresponding
dispatch vectors are listed below.
These primitives require support on all devices.
.TB "Global Rendering Macros"
.TS
box tab (;);
cf2 | cf2 | cf2
l | l | l.
Macro;Primitive;Function
=
RenderPath;RND_path;Renders a path
RenderLine;RND_line;Renders a line
RenderCurve;RND_curve;Renders a curve
RenderShape;RND_shape;Fills a shape
RenderPgon;RND_pgon;Fills a polygon
RenderCopy;RND_copy;Copies source raster
;;to destination raster
RenderGlyph;RND_glyph;Renders a polyglyph
.TE
At lower levels of rendering,
the functional variations become more device specific.
Many devices support another internal level of dispatching.
This generally differentiates a few cases optimized
for high-performance from the more generic cases
that must also be supported.
.P
The global dispatch vectors are set and used by Path_Raster,
Display_Raster, Store_Raster, Glyph_Raster,
Read_Raster, and Write_Raster.
They are updated by the above functions before
anything is rendered to the raster.
The update is based primarily on the set of
rendering functions available for the destination
raster and the current state of the context
attributes that will be used for primitive rendering.
The following table includes the factors that
contribute to the dispatch vector variations.
.TB "Top-level Dispatch Dependencies"
.TS
box tab (@);
cf4I | cf4I
l | l.
Variable@Possibilities
=
DEVICE@MEM1, MEM8, MEM32, CG2, CG4, VGA
@CG6 ... <your device>
RENDERING PIPELINE@line, curve, polygon, area, copy, glyph
SHADING@on, off
PRIMITIVE WIDTH@thin, fat
PATTERN@on, off
2D CLIP SHAPE@rectangle, complex
FILLSTYLE@solid, textured, opaque stipple, stippled,
RASTER PIXEL DEPTH@1, 4, 8, 32
PLANE ENABLE@on, off
ROP@clear, nor, erase, draw_inverted, erase_reversed,
@invert, xor, nand, and, equivalent, no_op,
@paint_inverted, draw, paint_reversed, paint, set
.TE
.H 2 "Top Level Dispatch Tables"
.P
The repertoire of rendering functions needed for specific
primitives differs widely between devices.
To minimize size and complexity,
the dispatch tables are organized into hierarchical layers.
Only top-level dispatch vector setup is done by the
raster rendering routines (XXX_Raster).
Subsequent dispatching is done in the individual routines
if needed.
.H 2 "Table Organization"
.P
The screen object for a device contains the
set of dispatch tables for that device.
These top-level dispatch tables are organized in
approximately the same way for each device.
This organization allows you to use similar
macros for top-level dispatch vector setup for all devices.
The following table shows the dispatch tables
available on all devices.
.TB "Top Level Dispatch Tables"
.TS
box tab (;);
cf2 | cf2 | cf2
l | l | l.
Table;screen attribute;Description
=
xxx_path_func;SCR_PATH_FUN;Path rendering functions
;thin, hollow, outline
xxx_stroke_func;SCR_STROKE_FUN;Stroke rendering functions
;line, curve, polygon, area
xxx_fill_func;SCR_FILL_FUN;Filling functions
;line, curve, shape
xxx_copy_func;SCR_COPY_FUN;Raster copying functions
xxx_glyph_func;SCR_GLYPH_FUN;Glyph rendering functions
.TE
.P
The stroke and fill dispatch tables have
duplicate sets of entries.
One set clips to a simple 2D rectangular clip shape,
and the other set handles more complex 2D clip shapes.
The other dispatch tables do not differentiate
based on clip shape,
and both complex and simple clipping are
supported by their rendering functions.
Figure 2-5
gives an example of the organization of the 8-bit memory dispatch tables.
.H 2 "Indexing"
.P
Each entry may be a direct function or a
reference to another table.
Secondary tables usually differentiate fill styles,
but sometimes use raster-op and plane enable as well.
Usually the secondary tables for different devices use
the same indexing schemes even if the device
does not distinguish all the cases.
This scheme allows device-independent code to be shared
by dispatching internally to device dependent code.
.H 2 "Dispatch Setup"
.P
There are several major rendering threads running
through \*(S).
Each thread contains its own dispatching
mechanism to the rendering functions that support
that thread.
The major threads include path, fill, copy, and glyph.
An overview of these threads is given in
Chapter 2.
.P
.H 2 "Path Rendering"
Dispatching for path rendering is set up by Path_Raster.
A prototype of the Path_Raster function can be
found in dd/pathRas.c.
This file is used in conjunction with a
device-dependent set of macros in pathMac.h.
Together, these define a version of Path_Raster for
a specific device.
See Figure 4-1 in Chapter 4.
.P
Path_Raster has two levels of dispatching.
It first selects the path transformation function from the
set of functions in SCR_PATH_FUN.
This function will use the global dispatch vectors to
render specific primitives.
The global dispatch vectors RND_xxx are selected from the
table of functions in SCR_STROKE_FUN or SCR_FILL_FUN.
This level of dispatching is supported for all devices.
The dispatch tables referenced by SCR_PATH_FUN,
SCR_STROKE_FUN, and SCR_FILL_FUN
are found in the xxxRas.c file for the corresponding device.
.P
For many devices, there is also a lower,
more device specific level of dispatching.
This is not true for color VGA.
If the lower level dispatching is supported  for
a particular device,
the dispatch tables for this level are found in
the xxxDisTab.c file for the particular device.
.P
.TB "Macros Used in Path Rendering"
.TS
box;
cBI cBI cBI
l | l | l.
Macro	Dispatch Vector	Table
=
RenderPath		SCR_PATH_FUN
RenderLine	RND_line	SCR_STROKE_FUN
RenderCurve	RND_curve	SCR_STROKE_FUN
RenderPgon	RND_pgon	SCR_FILL_FUN
RenderShape	RND_shape	SCR_STROKE_FUN, SCR_FILL_FUN
.TE
.H 2 "Raster and Glyph Rendering"
.P
Raster and Glyph rendering is simpler than path
rendering because only one level of dispatching
is used.
The Glyph_Raster operator uses the RenderGlyph macro,
which calls a function selected from the
SCR_GLYPH_FUN table in the screen object.
Raster copy operations all invoke the RenderCopy macro,
which selects a function from SCR_COPY_FUN.
.TB "Macros Used in Raster and Glyph Rendering"
.TS
box;
cBI cBI cBI cBI
l | l | l | l.
Operator	Macro	Dispatch Vector	Table
=
Glyph_Raster	RenderGlyph	RND_glyph	SCR_GLYPH_FUN
Display_Raster	RenderCopy	RND_copy	SCR_COPY_FUN
Store_Raster	RenderCopy	RND_copy	SCR_COPY_FUN
Read_Raster	RenderCopy	RND_copy	SCR_COPY_FUN
Write_Raster	RenderCopy	RND_copy	SCR_COPY_FUN
.TE
.H 2 "Dispatching Within Primitives"
.P
The RenderPath macro calls functions that
process paths and curves.
These functions eventually use the RenderLine, RenderCurve,
RenderPgon, or RenderShape macros to actually
render their primatives.
.P
The RenderCopy macro directly references the function
that does the raster copy.
All raster copy functions follow roughly the same structure.
.AL
.LI
Update the destination raster clip shape.
.LI
Set up the global rendering attributes and
lower level dispatch vector.
.LI
Call the lower level rendering routine,
which does hardware setup based on the rendering
attributes it receives,
renders, cleans up, and returns.
.LE
.P
RenderShape and RenderGlyph support fill styles fully.
After initial setup,
they make a common device-dependent call to a
function to accomplish the following:
.AL
.LI
Set up hardware (when necessary)
and clip the fill raster (when present)
to usable rectangular boundaries.
Thus, only the addressable area of the fill
raster is referenced when filling begins.
.LI
Set up the lowest level rendering function
dispatch vector based on such things as fill
raster/destination raster pixel depth combination,
ROP, plane enable, fill raster width, glyph width, etc.
.LI
For each rectangle in the destination clip shape,
call the lowest level rendering function to
draw the glyph / fill the rectangle.
.LE
.P
The source files for these mid-level functions are given below.
.P
.TB "Low Level Rendering Files"
.TS
box;
cBI cBI cBI cBI
l | l | l | l.
Fill Style	RenderShape	RenderGlyph	RenderCopy
=
CTX_FILL_SOLID	xxxFlS.c	xxxFlGS.c	xxxCpS.c
CTX_FILL_TEXTURE	xxxTxS.c	xxxTxGlS.c	xxxCpS.c
CTX_FILL_OPAQUE_STIPPLE	xxxOsS.c	xxxOsGls.c	xxxCpS.c
CTX_FILL_STIPPLE	xxxStS.c	xxxStGlS.c	xxxCpS.c
.TE
.P
These functions may render primitives directly using macros,
or may make function calls to render the
primitives using the lowest level of dispatching.
To minimize the overhead of passing parameters
between function levels,
one of two rendering structures is set up,
and only a single reference to this rendering
structure is passed on to the actual rendering
function.
This is also the transition point between
relatively device-independent and very
device-dependent functions.
.P
The following files contain the macros that are
used to transition between device-independent and
device-dependent code except for color VGA.
.TB "Rendering Header Files"
.TS
box tab (;);
cf2 | cf2
l | l.
Filename;Description
=
ras_typ.h;Raster rendering structure definitions
gly_typ.h;Glyph rendering structure definitions
ras_mac.h;Raster macros
mac_mac.h;Glyph macros
rop.h;Rendering macros
.TE
.P
Since these are device-dependent structures,
these files exist for each major device
implementation in the device-dependent include directory.
For simple frame buffer ports,
only the header files and the lowest level
rendering functions that these files call need
to be changed.
.H 2 "The Global Rendering Context"
.P
The global rendering context contains the
minimum state required for rendering
with the generic frame buffer code.
It is defined in include/di/fb_render.h.
While more state may be required for certain graphics accelerators,
these data structures are always a subset of the
complete graphics context at any point in time.
Most of the variables in this context are initialized
each time rendering begins,
using the context attributes of the context
associated with the destination raster.
.H 2 FBREND
There are two primary components to the global
rendering context:\ \&
FBREND and FBATTR.
FBREND is a cache of miscellaneous temporary
rendering information primarily used by the
rendering pipelines.
It is truly global in the sense that there is
only one copy of it for all of \*(S).
It is declared in dd/init.c as sh_fb_rend_glob,
but macros are defined that allow the fields of
this structure to be accessed by the field names
with the prefix ``FB_''.
Thus, sh_fb_rend_glob.hol_move is called
FB_hol_move throughout the \*(S) code and
documentation.
.PC
typedef struct
  {
   Static_Obj(et, struct class_ET);
   CONTEXT	ctx;
   Unsgn8	curve_form, curve_order;
   fract	xorg, yorg, zorg;
   POINT_B3H	pen;
   POINT_B3D	hol_move;
   Unsgn8	hol_close;
   Unsgn8	pipe_disp;
   union { float f; fract b; }
	clip_xmin, clip_xmax,
   	clip_ymin, clip_ymax,
   	clip_zmin, clip_zmax;
   CTX_clip_planes clip_planes;
   RND_FUNC	rnd_line;
   RND_FUNC	rnd_curve;
   RND_FUNC	rnd_pgon;
   RND_FUNC	rnd_shape;
   RND_FUNC	rnd_copy;
   RND_FUNC	rnd_glyph;
   POINT	p;
  } FBREND;
.SF
.H 2 FB_et
.P
\*(S) contains a single global polygon edge table
that is defined and declared in this data structure.
Since immediate mode is simulated through paths,
two contexts will never have two polygons open
simultaneously and only one global edge table is needed.
It is only used when rendering a filled region from a path.
It grows but never shrinks and is never garbage collected. 
The edge table is documented more completely in
Chapter 12.
.H 2 "curve_form, curve_order"
These cache the curve form and curve order during curve rendering.
.H 2 "FB_xorg, FB_yorg"
.P
Contain the raster offset (RAS_ORG) of the raster being
rendered to.
They are not valid across \*(S) calls.
.P "FB_pen"
The current pen position in screen coordinates.
The raster pen is maintained in raster coordinates within the
graphics context (as CTX_RASTER_PEN).
A path is rendered
(this is done at the start of Path_Raster).
The path pipelines use FB_pen internally to keep track of the
pen position in screen coordinates.
After the path has been rendered,
Path_Raster subtracts FB_xorg, FB_yorg from FB_pen to get
the new value of CTX_RASTER_PEN.
.H 2 FB_hol_move
.P
Contains the screen coordinates of the last move encountered.
It is used in the hollow pipelines to implement PATH_CLOSE
and PATH_CLOSESUB.
FB_hol_move is set up in Path_Raster when it is determined
that the hollow pipelines must be used.
It is initialized to the raster pen in screen coordinates
(same as FB_pen).
.H 2 FB_hol_close
.P
Hollow pipeline closure status.
Used only by hollow pipelines, FB_hol_close is composed of
the following bits.
.TB "Hollow Closure Status FB_hol_close"
.TS
box;
cBI cBI
l | l.
Option	Description
=
HOL_ON	Enables hollow pipeline
HOL_MV	Indicates move encountered
HOL_CM	Indicates close-on-move enabled
.TE
FB_hol_move is initialized in Path_Raster;
it is set to either HOL_ON or (HOL_ON | HOL_CM),
depending on whether the CTX_CLOSE_MOVE option is
enable in CTX_AREA_STYLE.
.P
When a MOVE operation is encountered in the
hollow pipelines,
and the HOL_MV or HOL_CM bits are set,
a vector is drawn between the current pen position (FB_pen)
and the last move (FB_hol_close).
HOL_MV is set to indicate a move was seen.
.P
When a PATH_CLOSE or PATH_CLOSESUB is found,
a vector is drawn between FB_pen and FB_hol_mv if HOL_MV is set.
HOL_MV is then cleared.
.H 2 FB_clip_xxx
.P
Defines the view clipping volume in screen coordinates as
floating point or fract.
The view volume is derived by transforming the context
clip volume defined by CTX_CLIP_ORG and CTX_CLIP_DIM by
the viewing pipeline.
It is done during pipeline validation.
.H 2 FB_clip_planes
.P
Indicate which clipping planes are enabled.
One or more of the following bits are enabled.
These values are defined in include/di/clip.h.
.TB "Clip Planes"
.TS
box;
cBI cBI
l | l.
Option	Description
=
CLIP_LEFT	Clip against left plane (xmin)
CLIP_RIGHT	Clip against right plane (xmax)
CLIP_TOP	Clip against top plane (ymin)
CLIP_BOTTOM	Clip against bottom plane (ymax)
CLIP_BACK	Clip against back plane (zmin)
CLIP_FRONT	Clip against front plane (zmax)
.TE
FB_clip_planes is initialized from the CTX_CLIP_PLANES
attribute when the viewing pipeline is validated.
.H 2 FB_p
.P
Used internally by point transformation routines to cache the
transformed point before perspective divide.
This point is needed for view clipping of rational curves.
.H 2 "Global Rendering Dispatch Vectors"
.P
The global rendering dispatch vectors point to the actual
rendering functions that are invoked by the RenderXXX macros.
They are initialized by most raster rendering functions
(like Display_Raster, Path_Raster, etc.)
before any drawing is done on the raster.
Table 13-1
gives the rendering macros and
the names of their dispatch vectors.
.P
Only those that which could possibly be
needed during the current rendering pass are valid at any point in time.
Several rendering operators within \*(S) use multiple passes
through the lowest level rendering code to complete their operations.
Those operators may change one or more of
these dispatch vectors during their operation.
.H 2 FBATTR
.P
FBATTR defines a small set of attributes used by almost
all of the low-level rendering routines.
This structure is what allows the low-level
rendering routine to be independent of the graphics context.
.P
Like FBREND,
the values in FBATTR are derived from the
appropriate raster and context attributes.
A global FBATTR structure called sh_fb_attrs
is declared in dd/init.c,
and macros exist that allow the fields of this structure
to be accessed by the field names with the prefix ``FB_''.
For example, sh_fb_attrs.col is called FB_col.
.P
The global sh_fb_attrs structure is not the only
instance of FBATTR used by \*(S).
FBATTR is used whenever a rendering routine wishes to call
another rendering routine that needs the attributes
set up a different way.
This is described more fully in
Chapter 14.
.PC
typedef struct
  {
   Unsgn32   col;          /* foreground color (device dependent) */
   Unsgn32   bcol;         /* background color (device dependent) */
   CTX_rop   rop;          /* raster op */
   Unsgn32   disp;         /* raster specific context dispatch value */
   Unsgn32   plane_enable; /* raster specific plane enable mask */
   Unsgn32   fill_style;   /* requested fill style */
   RASTER    fill_raster;  /* requested fill raster */
   POINT_B2D fill_origin;  /* requested fill origin */
  } FBATTR;
.SF
.P
.H 2 FB_col
.P
Foreground color in device-dependent format.
It is derived from the CTX_COLOR attribute by
calling Apply_Cmap.
FB_col is computed each time rendering is requested.
.H 2 FB_bcol
.P
Background color in device-dependent format.
It is derived from the CTX_BACK_COLOR attribute
by calling Apply_Cmap.
It is only computed for rendering operations in
which it is used
(like opaque stippling, texturing).
.H 2 FB_rop
.P
Raster-op, derived directly from CTX_ROP,
and always computed for all rendering operations.
.H 2 FB_plane_enable
.P
Plane enable mask,
derived directly from the CTX_PLANE ENABLE
attribute at the start of rendering.
.H 2 FB_fill_style
.P
Fill style, derived directly from the
CTX_FILL_STYLE attribute for all rendering operations.
.H 2 FB_fill_raster
.P
Fill raster, derived directly from the
CTX_FILL_RASTER attribute.
Only computed for rendering operations that fill
with a texture.
.H 2 FB_fill_origin
.P
Fill raster origin, derived directly from the
CTX_FILL_ORG attribute.
Only computed for rendering operations that fill
with a texture.
.H 2 FB_disp
.P
Device-specific function dispatch index.
This is computed at the start of rendering.
