'\"!  tbl | mmdoc
.if n .pH arch.intro @(#)intro	40.1
.ig
imaged dc 8/30/89
docformat -c -s4 -dqm4 fn
..
.ds  Lb Shapes
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.ds S) Shapes
.BK "Shapes Internal Architecture"
.CH "Introduction" "1"
.H 1 "Introduction" 
\*(S) is the lowest-level device-independent
protocol for graphics.
It replaces the existing PIXRECT layer and
provides graphics support for the X11/NeWS merge.
Some low-level functionality typically associated
with graphics libraries
(such as color-map management and text display)
are not part of \*(S) because they are handled
either directly by the window system or by the
window system in conjunction with \*(S).
.P
The interface between X11/NeWS and \*(S) consists
of C-language macros that access the \*(S) data.
There is no communication protocol between the
window system and the graphics library.
\*(S) is compiled as part of X11/NeWS and
is accessible only through the merge.
.P
\*(S) takes advantage of accelerator
transformation hardware during path construction
(if possible).
While \*(S) provides some support for all
graphics accelerators,
its use of accelerators is heavily slanted
towards operations common to X11/NeWS
incorporating the following considerations:
.BL
.LI
X11 operates in device coordinate space,
and \*(S) optimizes the case where no coordinate
transforms are requested.
.LI
NeWS uses the P\s-2OST\s+2S\s-2CRIPT\s+2 imaging
model permitting a single 2D transform and always
creating a path.
\*(S) internally optimizes 2D operations and has
a configurable transformation pipeline.
.LI
NeWS does all transforms on coordinates during
path construction rather than at rendering,
which is not particularly efficient for
highly pipelined accelerators.
Most accelerators derive their speed from
parallel steps of the graphics pipeline,
in particular by overlapping transformation and rendering.
.LE
.H 2 "SH_SMALL"
The source code for \*(S) is configurable to
accommodate several purposes.
Different versions can be created when you
compile the code.
As you read through the code,
you will see a wide variety of compile flags.
Many of flags compile out code that X11/NeWS does not need
but that is used by another product that works
from the same source tree.
This document only discusses code that pertains
to X11/NeWS and does not discuss variables not used
by X11/NeWS.
.\" begin new page
.P
SH_SMALL is the all-purpose compile directive
that means ``compile for X11/NeWS.''
When SH_SMALL is enabled,
the following flags are enabled as well.
When you encounter an `ifndef' that uses these variables,
ignore the code that follows,
because it won't be compiled in when you build X11/NeWS.
.SK
.TB "SH_SMALL Flags"
.TS
box tab(/);
cf4I | cf4I
l | l.
Name/Meaning
=
NO_VIEW_CLIP/No view clipping
NO_CLOSE_MOVE/No closing of a bound on move
NO_PATH_IMM/No immediate display
NO_PATH_ANALYSIS/No path analysis
NO_RTM/No rendering matrix
NO_COL_DIR/No direct color
NO_MODEL/No model transform
NO_VDC/No view transform
NO_3D_TRANS/No 3D transformations
.TE
.TT
.H 2 "The Objects"
.P
\*(S) objects are allocated from main memory,
and their attributes are accessible through
macros or subroutine calls.
The external objects have internal operators and
attributes that are not user-accessible.
All operators and attributes of internal objects
are inaccessible to the user.
.TB "External Objects"
.TS
box tab(;);
cf4I | cf4I | cf4I
l  | l | l.
Object;Name;Description
=
CLASS;Class;Collection of objects with the same operators
;;and attributes
_
CTX;Context;Graphics state information
_
CMAP;Color Map;Device-dependent index of RGB values
_
CURS;Cursor;Bit-mapped cursor description
_
GLYPH;Glyph;A small bitmap, usually representing
;;a text character
_
PATH;Path;A simple, unbranched display list
_
PAT;Pattern;Line-style description
_
RAS;Raster;An arbitrarily shaped output or screen
;;area which can be dynamically
;;repositioned or resized
_
TRANS;Transform;4 \(mu 4 transformation matrix
.TE
.TT
.P
Points and color are not true objects because
they are not allocated memory;
they are statically allocated in the calling
program and populated by macros.
.TB "External Structures"
.TS
box tab(;);
lf4I | lf4I | lf4I
l | l | l.
Object;Name;Description
=
COLOR;Color;Color data structure
_
FRACT;Fract;Method of designating numbers in which
;;the significant digits can be on the left
;;or right side of the decimal point
_
POINT;Point;Geometric position data structure
.TE
.TT
.TB "Internal Objects"
.TS
box tab(@);
lf4I | lf4I | lf4I
l | l | l.
Object@Name@Description
=
ET@Edge Table@Facilitates the rendering of polygons
_
SHAPE@Shape@A 2D area description representing
@@line, curve, area, raster, or glyph
_
SCREEN@Screen@Display device description
.TE
.TT
.H 2 "The Generic Object Structure"
Most \*(S) objects are represented as C structures.
An object handle is a pointer to such a C structure.
Typically, object structures have three parts:
.P
The first part is a fixed-format object header describing
which class the object belongs to,
which device that class is implemented for,
and what the functions are for each operator of that class.
The object handle points
\f2after\f1
the object header.
Thus, negative offsets must be used to access these fields.
The
\f2Shapes Reference Manual\f1
describes how to access the generic object attributes and operators.
They are defined in include/sh_class.h.
The object header looks like:
.PC
.nf
struct obj_hdr
  {
   unsigned int obj_flags : 8; /* object flags */
   unsigned int obj_size : 24; /* object size (bytes) */
   CLASS        obj_class;     /* class of object */
   Unsgn16      obj_use;       /* object use count */
   CLASS_OPER   *obj_func;     /* object operator dispatch table */
  };
.fi
.SF
Following the object header are fields containing the values for
the external attributes of the class.
This is the part of the structure to which the object handle points.
The names of these structure fields are the same as the names of
the \*(S) attributes they represent.
The layout of this part of the structure will be
different for each class,
but objects of the same class all use the same structure.
.P
The last part of a class structure is optional.
It defines internal attributes, flags, state information, etc.,
that is used in the implementation of the class.
.H 2 "Object Header Files"
.P
The table below contains the \*(S) user-level objects,
their internal structure names,
and the filenames of their headers.
(Unless otherwise specified,
the header files reside in the include/ directory.)
.P
.SK
.TB "User-Level Objects"
.TS
box tab(%);
cf4I | cf4I | cf4I
l | l |  l .
Object%Structure%Header Files
=
%CLASS% sh_class.h
%CLASS_DEF
%struct class
%struct obj_hdr
_
CMAP%class_CMAP%sh_CMAP.h
%%sh_CMAP.ah
%%di/cmap.h
_
CONTEXT%class_CTX%shapes.h
%%sh_CTX.h
%%sh_CTX.ah
%%di/fb_ctx.h
_
CURSOR%class_CURS%sh_CURS.ah
%%sh_CURS.h
_
GLYPH%%sh_glyph.h
_
RASTER%class_RAS%sh_RAS.h
%%sh_RAS.ah
%%di/ras.h
_
PATH%class_PATH%sh_PATH.h
%%sh_PATH.ah
_
PATTERN%class_PAT%sh_PAT.h
%%sh_PAT.ah
_
TRANSFORM%class_TRANS%sh_TRANS.h
%%sh_TRANS.ah
%%di/trans.h
.TE
.TT
.TB "User-Level Structures"
.TS
box tab(%);
cf4I |  cf4I
l |  l .
Structures%Header Files
=
COLOR%sh_color.h
_
DRAW%sh_draw.h
_
POINT%sh_point.h
.TE
.TT
.\" begin new page
.H 2 "Directory Descriptions"
.P
Each level of the directory hierarchy is
described in this section.
.P
/src
.P
Contains Makefile (used by install),
and Makefile.cfg (root Makefiles,
including default compile values).
These files are used to build the Shapes
system during the install process.
The installation process sets up user-definable
directories for the header files containing the
public routines and the library files containing
the executable code.
.P
/src/di
.P
Contains the device-independent source code library.
These files contain the routines that operate
independently of the framebuffer or other display
device in use.
The library libShapes.a is created from these files.
.P
/src/dd
.P
Contains the device dependent source code library.
These files contain the low-level,
generic rendering code common to different
devices and supported framebuffers.
The library sh_libShFB.a is created from these files.
.P
src/dd/mem32
.P
Contains the low-level, non-accelerated glyph, fill style,
and raster copy rendering code common to 32-bit frame buffers.
These routines handle memory rasters and screens
that are addressed as memory.
.P
src/dd/mem8
.P
Contains the low-level, non-accelerated  glyph, fill style,
and raster copy rendering code common to 8-bit frame buffers.
These routines handle memory rasters and screens
that are addressed as memory.
.P
src/dd/vga
.P
Contains the low-level glyph, fill style, and raster copy
rendering code for 4-bit deep VGA display
controllers.
These functions work on both screen and memory rasters, so there is no
mem4 directory.
.P
src/dd/mem1
.P
Contains the low-level, non-accelerated glyph, fill style,
and raster copy rendering code common to 1-bit frame buffers.
These routines handle memory rasters and screens
that are addressed as memory.
.P
src/dd/mem
.P
Contains the source code that supports common raster operations,
such as vector copy, solid fill, texture, etc.
Included are the files required to support
cross-depth rendering operations.
.P
src/dd/cg2
.P
Contains the source code specific and header
files to the raster-op,
plane-enable support of cg2 hardware device.
This code writes directly to the internal
registers of the cg2.
.\" begin new page
.P
src/dd/cg6
.P
Contains the source code and header files
specific to the low-level rendering support of
cg6 hardware device.
It also contains the transformation pipeline and
can directly render solid, thin lines, triangles,
and quadrilaterals clipped to rectangles.
This code writes directly to the internal
registers of the cg6.
.P
src/dd/cg5
.P
Contains the source code and header files
specific to the low-level rendering support of
cg5 hardware device.
This code writes directly to the internal
registers of the cg5.
.P
/src/include
.P
Contains the header files that help define
Shapes to the user.
These public files contain various system constants,
structure definitions, and attribute lists.
.P
/src/include/vga
.P
Contains header files specific to the
port of Shapes to the VGA.
.P
/src/include/di
.P
Contains the framebuffer independent public header files.
These files contains code that is used internally by Shapes
in conjunction with the various routines contained
in the /src/di directory.
.H 2 "File and Procedure Naming"
.P
All files in the /dd directory and its
subdirectories use the following file naming
convention:

             device | function | source | target

.TB "Device Prefixes"
.TS
box tab(/);
cf4I | cf4I
l | l.
Prefix/Device
=
mem/common memory raster code
m1/1 bit per pixel memory raster code
m8/8 bits per pixel memory raster code
m32/32 bits per pixel memory raster code
bw2/bw2 framebuffer code
cg2/cg2 framebuffer code
cg4/cg4 framebuffer code
cg5/cg5 framebuffer code
cg6/cg6 framebuffer code
cg8/cg8 framebuffer code
vga/VGA cards in a 4 bit deep code
.TE
.TT
.P
.TB "Function Prefixes"
.TS
box;
cf4I | cf4I
l | l.
Prefix	Function
=
Pt	point
Vc	vector
Cp	copy raster
Fl	solid fill raster
Tx	texture raster
Os	opaque stipple raster
St	stipple raster
FlGl	solid fill glyph(s)
TxGl	texture glyph(s)
OsGl	opaque stipple glyph(s)
StGl	stipple glyph(s)
FlArea	solid fill complex area
Im	image
DspTab	dispatch tables
PthRas	prepare raster for path rendering
Ras	general raster specific code
Cursor	cursor support
Curve	curve rendering
PthAnal	analyzed path rendering
PthTrns	path transformation
PiArea	area pipelines
PiClAr	area clipping pipelines
PiClVc	vector clipping pipelines
PiHol	hollow pipelines
PiVc	vector pipelines
Rop	rop conversion tables
Trns	general transformation support
.TE
.TT
.TB "Source Prefixes"
.TS
box;
cf4I | cf4I
l | l.
Prefix	Device
=
1	1 bit per pixel
4	4 bits per pixel
8	8 bits per pixel
.TE
.TT
.TB "Target Prefixes"
.TS
box;
cf4I | cf4I
l | l.
Prefix	Device
=
S	shape (multiple rectangles) or polyglyph
R	single rectangle
P	code provides plane enable support
D	CTX_ROP_DRAW special cased
G	non special cased rop support
.TE
.TT
.P
In addition, all externally referenceable
procedures begin with the sh_ prefix.
