'\"!  tbl | mmdoc
.if n .pH arch.render @(#)render	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 "Low Level Rendering" "14"
.H 1 "Low Level Rendering" 
.H 2 "Introduction"
.P
.nh
This section describes the internal operation of
the low level rendering routines.
They are enumerated in
Table 14-1.
.P
\*(S) rendering supports fill styles, plane enables,
and Boolean raster operations.
Plane write enable masks are supported on
destination pixels for all types of rendering
operations.
In addition, X11 copy-plane functionality is
provided by supporting plane-read enable masks
for source pixels in a special form of opaque stippling.
The Boolean raster operators (ROPS) that are
supported by \*(S) are listed in the table below.
.TB "Shapes Raster Operators"
.TS
box tab (;);
cf2 | cf2
l | l.
Context Raster Operator;Boolean Raster Operator
=
CTX_ROP_AND;src AND dst
CTX_ROP_CLEAR;0
CTX_ROP_DRAW;src
CTX_ROP_DRAW_INVERTED;NOT src
CTX_ROP_EQUIVALENT;(NOT src) XOR dst
CTX_ROP_ERASE;(NOT src) AND dst
CTX_ROP_ERASE_REVERSED;src AND (NOT dst)
CTX_ROP_INVERT;NOT dst
CTX_ROP_NAND;(NOT src) OR (NOT dst)
CTX_ROP_NO_OP;dst
CTX_ROP_NOR;(NOT src) AND (NOT dst)
CTX_ROP_PAINT_INVERTED;(NOT src) OR dst
CTX_ROP_PAINT_REVERSED;src OR (NOT dst)
CTX_ROP_SET;(NOT 0)
CTX_ROP_XOR;src XOR dst
.TE
.P
For most dumb framebuffers,
only CTX_ROP_DRAW is special-cased for high performance.
The rendering of all other ROPS follows a generic
routine.
.H 2 "RenderLine, RenderCurve, RenderPgon"
.P
The RenderLine function directly renders thin, solid lines.
RenderCurve converts a thin, solid curve into a
shape object.
RenderPgon makes a shape from a polygon edge table.
In the latter two cases,
RenderShape is called to do the actual rendering
of the primitive.
Thick or dashed lines and curves are
decomposed into thin vectors or polygons.
.H 2 "RenderShape"
.P
The RenderShape pipeline must support
shape-rendering for all fill styles.
Shapes are generated as a series of rectangles
ranging from a single pixel to larger than full screen.
Shape rendering routines are optimized for
dealing with rectangles.
\*(S) presents these rectangles as a series of
y-spans from minimum to maximum y.
Each y-span may again be subdivided into multiple x-spans
(also from minimum to maximum).
For all types of rendering operations,
the right-most pixel of each scanline within a rectangle
and the last scanline of each rectangle are not rendered.
This technique prevents the overlapping of adjacent shapes.
.P
Porting \*(S) to new devices at the rectangle
rendering level is recommended for highest
performance.
Porting at lower rendering levels may be
possible for frame buffers similar to Sun's but
is not recommended as a long term solution.
.H 2 "Solid Fill"
.P
\*(S) provides four fill styles:\ \&
solid, textured, opaque stippled, and stippled.
Solid fill renders the shape in the current
foreground color and ignores the fill raster.
All other fill styles use the fill raster as a source.
The fill origin positions the fill raster
relative to the origin of the destination raster.
.P
For dumb frame buffers,
rendering with fill rasters is optimized when
fill raster widths are integer multiples of 32
pixels wide.
Rasters of 8, 16, and in some cases 32 pixels in width
(if less than 32 scanlines high)
are automatically replicated when necessary into
a temporary storage area to allow the optimized
rendering code to be used whenever possible.
.H 2 "Texture"
.P
Texture is accomplished by copying the fill
raster into the destination raster,
wrapping around the fill raster as needed so it
completely fills the required area within the
destination raster.
Texturing is similar to copying in that the bits
from each source pixel are used directly.
.P
\*(S) provides three types of texture:
.BL
.LI
Monochrome-to-monochrome\(emuses the source
pixels directly and does not map the ones and
zeros through a color map before copying them.
.LI
Monochrome-to-color\(emthe zero pixels in the
monochrome fill raster are mapped into the
current background color and the ones are mapped
to the current foreground color.
.LI
Color-to-color\(emthe pixel depth of the fill
raster must be the same as that of the
destination raster and fill raster pixels are
used directly as source pixels.
.LE
.H 2 "Opaque Stippling"
.P
Opaque stippling always uses a one-bit deep fill
raster to opaque stipple the destination raster.
\*(S) opaque stippling supports monochrome-to-monochrome
and monochrome-to-color.
Unlike texturing, monochrome-to-monochrome opaque
stippling maps the ones and zeros of the fill
raster through the current foreground and
background colors as the fill occurs.
This mapping is actually implemented through
converting the requested ROP
(or fill style) to give the desired effect.
In this way, monochrome opaque stippling can be
written more simply to just use the fill raster
pixels as they exist,
letting the ROP control color mapping.
.P
Monochrome-to-color opaque stippling is
identical to monochrome-to-color texturing.
.P
X11 copy plane functionality is provided as a
special form of color-to-color opaque stippling.
In this case, the raster RAS_PLANE_ENABLE
mask is applied to the fill raster pixels before
using them.
After applying the mask,
if the result is non-zero,
the source pixel is replaced by the current
foreground color.
If the result is zero,
the source pixel is replaced by the current
background color as the destination is opaque
stippled.
Thus, one or more fill raster planes can be used
to opaque stipple the destination.
.P
When one plane is used from both the fillraster
and the CTX_PLANE_ENABLE,
limiting the destination raster plane enable to one plane,
the equivalent of copy plane occurs.
It is not necessary to support the case where
both the fill raster and the destination raster
are the same raster and the source plane is
included as one of the destination planes.
(This case is detected by the X11/NeWS server and
is handled at a higher level through other operations).
As in texturing,
the fill raster may be required to
wrap around to completely fill the
destination.
.H 2 "Stippling"
.P
Stippling uses a one-bit deep fill raster to
stipple the destination raster.
The fill raster is an additional 2D clip mask
where the one pixels are rendered as the current
foreground color into the destination raster.
Where the fill raster contains zero pixels,
the corresponding pixel in the destination raster
remains unaltered.
\*(S) supports monochrome-to-monochrome and
monochrome-to-color stippling only.
Fill rasters may also be required to wrap around
here to completely fill the destination area.
.H 2 "RenderCopy"
.P
The RenderCopy pipeline is used for high performance,
multidirectional copying of pixels from a source
to destination raster.
RenderCopy differs from textured filling.
When the source and destination raster are the same and overlap,
RenderRaster changes the copy direction to avoid
destroying the source pixels as they are copied
to the destination area.
.P
RenderCopy supports the following copy directions:
.BL
.LI
Top-to-Bottom/ Left-to-Right
.LI
Top-to-Bottom/ Right-to-Left
.LI
Bottom-to Top/Left-to-Right
.LI
Bottom-to-Top/Right-to-Left
.LE
.P
This routine does not support wrapping of the
source raster;
therefore, it has a higher performance
implementation than textured fill.
The CTX_RASTER_PEN position determines the
position of the source raster relative to the
destination raster.
.P
\*(S) supports monochrome-to-monochrome,
monochrome-to-color, and color- to-color copying.
As in texturing,
monochrome source pixels are used
exactly as they exist and are generally not
mapped before using.
Applications can  force color mapping of
monochrome source pixels before rendering them
into destination monochrome rasters by calling
RenderCopy with the CTX_FILL_OPAQUE_STIPPLED fill style.
Internally, the monochrome color mapping is
accomplished by manipulating the ROP.
.P
The RenderCopy routine is used by the following functions.:
.BL
.LI
Display_Raster()
.LI
Read_Raster()
.LI
Write_Raster()
.LI
Store_Raster()
.LE
.H 2 "RenderGlyph"
.P
The RenderGlyph routine renders polyglyphs and
supports all fill styles.
A \f2glyph\fP is a 2D bitmask that is used as an
additional clip mask when rendering into the
destination raster.
Only destination pixels that correspond to the
ones in the glyph are altered when rendering glyphs;
the destination pixels that correspond to the
zeros in the glyph remain unaltered as glyphs are
rendered.
.P
\*(S) supports the X11 image text functionality,
in which a Poly_Glyph bounding box can be cleared to
the background color before rendering the glyphs
within the polyglyph.
.BL
.LI
Solid glyphs are rendered using the current foreground
color to fill the glyph in the destination raster.
.LI
Textured glyphs are rendered identically to textured
rasters,
using the glyphs as additional clip masks.
.LI
Opaque stippled and stippled glyphs use a series
of raster rendering operations,
are device independent,
and can be ported from one frame
buffer implementation to another with little or
no alteration.
.LE
.H 2 "Global Framebuffer Attributes"
.P
Each low-level rendering routine is
completely context-independent.
This is accomplished by passing a small set of
rendering attributes in the structure FBATTR.
These variables are derived from the
appropriate raster and context attributes.
.P
Globally available macros for gaining access to
this attribute cache are referenced by using FB_*\ ,
where `*' represents the particular attribute.
These are found in include/di/fb_render.h.
See Chapter \f2CH_Disp\fP
for a more thorough description of FBATTR.
.P
.PC
typedef struct
  {
   Unsgn32   col;          /* foreground color */
   Unsgn32   bcol;         /* background color */
   CTX_rop   rop;          /* raster op */
   Unsgn32   disp;         /* context dispatch value */
   Unsgn32   plane_enable; /* plane enable mask */
   Unsgn32   fill_style;   /* fill style */
   RASTER    fill_raster;  /* fill raster */
   POINT_B2D fill_origin;  /* fill origin */
  } FBATTR;
.SF
.P
Most primitives can be completely rendered
with one call to a low-level function.
In this situation,
using the context attributes directly causes no problems.
.P
Separating low-level rendering from the context
allows complex primitives to be rendered via
calls to the lowest levels of several
simpler functions,
using them to build the primitives in stages.
Doing this may require changing rendering
attributes along the way.
These functions dispatch differently
depending on the rendering attributes to be used.
For example, the best method for producing
monochrome opaque stippling is to examine the
foreground and background colors of the context
and then call RenderCopy with a new set of ROPs.
.P
This is where the FBATTR structure becomes useful.
When a complex primitive is rendered,
a global FBATTR structure, sh_fb_attr,
is initialized from the context attributes.
These global attributes may subsequently be changed
(leaving the context attributes alone),
or another FBATTR structure with different
attributes may be used.
The Dispatch_Raster function is used to reset
the global dispatch vectors based on the new attributes.
.P
For example, consider the many combinations of
raster-op and plane enable.
Typically only a few combinations are highly optimized.
Others can be handled by generic code because
they are rarely used.
.P
The FB_disp attribute is initially extracted from
the context ctx_draw_disp attribute and
represents an index derived from the plane enable
mask and ROP.
This value will be odd if it is necessary
to use the plane enable mask when rendering.
The ROP portion of the field is determined by:
.PC
#include "di/fb_ctx.h"
extern	int	sh_FB_ROP_TRANS[];

	      FB_disp |= sh_FB_ROP_TRANS [(int)rop] << FB_ROP_SHIFT;
.SF
.P
This code fragment converts the 16 ROPs supported
by \*(S) into a smaller subset used later as a
dispatching index.
It provides the ability to make rendering
function calls based on the few ROP and
plane-enable-cases one wants to implemented as
high performance.
Some devices may need these special-cased,
high-performance functions,
and others may not,
depending on what hardware support is available.
