'\"!  tbl | mmdoc
.if n .pH port.chap2 @(#)chap2	40.1
.ig
imagen dc 8/31/89
docformat -c -s4 -dqm4 -p1 chap2
..
.BK "Shapes Porting Guide"
.CH "The Porting Process" "2"
.H 1 "The Porting Process"
.H 2 "Init linkage"
.P
Currently, adding a new framebuffer device type is not
as simple as we eventually hope it to be.
It is still necessary to edit and recompile raster.c
in the \f2di\fP directory of Shapes to add a new device
with a new pixel depth.
.P
A good place to start is by adding one or more SCR_DEV_XXX
device numbers to the file include/sh_scr_dev.h.
As many device numbers can be added as there are variations
of devices of a particular device type.
.P
Next, the device name should be added to the sh_Scr_Dev[]
table currently declared in di/init.c,
along with the function name to be called to open
the device.
Also, any virtual device names should
be added to the sh_Scr_Virt[] table.
For example Shapes supports the Sun cg4 framebuffer
device under the four following names:\ \&
\f2/dev/cgfourX , /dev/cgfourX_ove , /dev/cgfourX_ovl ,\f1
and
\f2/dev/cgfourX_clr ,\f1
where X is the Unix device number.
Shapes determines what portion of the framebuffer
to open based on the virtual device name it receives.
.P
For example, device \f2/dev/cgfourX\fP defaults to the
color planes,
while the other names specify overlay plane,
overlay enable plane, or color planes exactly.
The operating system, however,
recognizes only \f2/dev/cgfourX\fP as a physical device.
Shapes knows that the others are virtual device names
because of their existence in the virtual device table,
and maps each one into memory slightly differently.
Shapes associates the virtual device name,
with the physical device name and uses the
physical device name when opening the device.
If it finds a match,
it creates a screen device object for the device name
and attaches the screen object to the raster it is trying
to create.
Files /dd/scrRas.c and /di/screen.c contain most
of the code involved here.
.P
The open function in file xxxRas.c
(e.g., dd/bw2Ras.c) for any framebuffer should
open the device,
map it into memory,
create and initialize a ras_screen object associated
with the device,
and call a routine to perform any default
initialization of the device.
This file must also contain a device-specific raster
class table for the new device,
and a device-specific color map class table for
the device.
The raster class table is loaded with the address of
the raster operator table and color map operator table
for the particular device.
This file should also contain any device-specific code
necessary for closing the device,
and any device-specific code necessary to install
color maps on the device.
The header files describing the screen object are
include/di/sh_SCR.ah and include/di/sh_SCR.h\|.
The remaining device-specific code needed to add
a new framebuffer is all related to rendering.
.P
.H 2 "Path Raster"
.P
The Path_Raster call (e.g., dd/pathRas.c) is the nexus
where Shapes evaluates the state of the context and
decides where to dispatch for rendering.
As such, it determines how to interpret
the many arrays of the dispatch table,
and it also initiates the device-dependent setup
before rendering.
.P
The path raster code has been written so that you should
only need to create a header file \f2pathMac.h\fP
(e.g., dd/cg2/pathMac.h) that provides a format for defining
how your device differs from other devices.
.P
.H 2 "Dispatch Tables"
.P
This section describes the dispatching tables from the
point of view of the 8-bit memory implementation.
It describes the routines you will find in the dispatching
tables and how you might test them.
Since it is the most complicated dispatching scheme,
we hope you will be able to extrapolate the information
provided to other dispatch tables.
We also hope that this table gives you an idea
of the amount of work you may need to do.
.P
Shapes has two dispatch tables \-
the path raster dispatch table,
and the memory dispatch table.
In certain cases, the former dispatches
on down to the later.
We will cover the two tables separately.
.P
.H 2 "Path Raster Dispatch Table"
.P
The path raster dispatch table is found in the xxxRas.c file
(e.g. dd/M8Ras.c).
.P
The format for this section is as follows:
.br
        Routine:
.br
	File:
.br
	Description:
.br
	Test By:
.br
	Amorfus Test:
.br
	Comments:
.AB N
Amorfus Test is not applicable to the AT&T VGA board.
.AC
.P
\f3sh_fb_A2Ds\f1
.TS
l lw(3.5i).
File:	di/areaShape.c
Description:	Convert paths to shapes.
Test:	T{
No need to port \(em Device independent,
as its  rendering needs based on to RenderShape
(the macro dispatch for rendering a shape).
T}
Comments:	
.TE
.P
\f3sh_fb_Area_Shape\f1
.TS
l lw(3.5i).
File:	di/areaShape.c
Description:	T{
Converts edge tables to shapes.
T}
Test:	T{
No need to port,
as it renders through RenderShape macro.
T}
Comments:	
.TE
.P
\f3sh_fb_L2Ds\f1
.TS
l lw(3.5i).
File:	di/vecShape.c
Description:	Turn a vector into a shape
Test:	No need to port.
Comments:	
.TE
\f3sh_fb_Vect\f1
.TS
l lw(3.5i).	
File:	di/mem/memVec.ace
T{
Description:
T}	T{
Renders single pixel vectors in 1-, 8-, and
32-bit memory framebuffers.
T}
.sp
T{
Test By:
T}	T{
Set_Context(ctx, LINE_SIZE, 0);
.br
Set_Context(ctx, CTX_SHADE, CTX_SHADE_OFF);
.br
<draw a path>
T}
.sp
T{
Amorfus Test:
T}	T{
All Amorfus tests that begin with LineRel, Line, MoveRel, Move,
and whose data type part is
.UI not
3D.
For example, tests MoveRel_B2D_001.c an
Line_B2D_001.c should work.
Test Line_B3D will
.UI not
work since there's no 3D in Shapes).
T}
.sp
T{
Testall Test:
T}	T{
Drawing lines with left-button mouse click.
T}
Comments:
.TE
.P
\f3sh_fb_curve_2d\f1
.TS
l l w(3.5i).
File:	di/pipeCurve.c
Description:	T{
Renders 2D curves by converting curve descriptions to Shapes.
T}
Test:	No need to port.
Comments:	
.TE
.P
\f3sh_mem8_FLGLs\f1
.TS
l lw(3.5i).
File:	dd/mem8/m8FlGlS.ace
Description:	T{
Renders solid filled glyphs,
handling all variations of rop and
plane enable.
T}
Test By:	T{
Set_Context(ctx, CTX_SHADE, CTX_SHADE_SOLID);
T}
Poly_Glyph();
Amorfus Test:	Poly_Glyph_*.c
Testall Test:	T{
Switching to text mode and adding text.
T}
Comments:	
.TE
.P	
\f3sh_mem_CPs\f1
.TS
l lw(3.5i).
File:	dd/mem/memCpS.c
Description:	T{
Copy from one raster to another, clipped by a shape.
The source and destination raster may be one and the same
(which causes problems for copying that this routine resolves).
By using the dispatch tables in dd/mem/memDspTab.c,
this routine handles all variations of plane enable and
ROP.
T}
Test By:	T{
Display_Raster(),
.br
Read_Raster()
.br
or Write_Raster()
.br
Store_Raster()
T}
Amorfus Test:	T{
Write_Raster_*.c  Since all Amorfus programs test to
see whether the programs have completed successfully
by using Read_Raster(),
any Amorfus program where you know that the graphics
displayed are correct can server as a test of the copy Raster.
T}
Testall Test:	Through scroll text.
Comments:	T{
You may or may not find it necessary to re-write this routine,
depending on how you have structured your lower level
raster-to-raster copies.
Initially, you may find it easier to draw to work the
lower level functions within this scheme.
T}
.TE
.P
\f3sh_mem_OSTs\f1
.TS
l lw(3.5i).
File:	dd/mem/memOsS.c
Description:	T{
Used to render shapes with the fill style set to opaque stipple.
T}
Test By:	T{
Set_Context(ctx, CTX_FILL_STYLE, CTX_FILL_OPAQUE_STIPPLE);
Display_Context(ctx, CTX_RENDER_FLUSH);
T}
Amorfus Test:	
Comments:	
.TE
.P
\f3sh_mem_STGLs\f1
.TS
l lw(3.5i).
File:	dd/mem/memStGlS.c
Description:	T{
Used to render polyglyphs with fill style set to stipple.
T}
Test By:	T{
Set_Context(ctx, CTX_FILL_STYLE, CTX_FILL_OPAQUE_STIPPLE); PolyGlyph();
T}
Amorfus Test:
Testall Test:
Comments:
.TE
.P
\f3sh_mem_STPLs\f1
.TS
l lw(3.5i).
File:	dd/mem/memStS.c
T{
Description:
T}	T{
Used to render shapes with the fill style set to stipple.
T}
.sp
T{
Test By:
T}	T{
Set_Context(ctx, CTX_FILL_STYLE, CTX_FILL_STIPPLE);
Display_Context(ctx, CTX_RENDER_FLUSH);	
T}
Amorfus Test:
Comments:
.TE
.P
\f3sh_mem_TEXs\f1
.TS
l lw(3.5i).	
File:	dd/mem/memTxS.c	
Description:	T{
Used to render shapes with the fill style set to texturing.
T}
Test By:	T{
Set_Context(ctx, CTX_FILL_STYLE, CTX_FILL_TEXTURED);
.br
Display_Context(ctx, CTX_RENDER_FLUSH);	
T}
Amorfus Test:	
Comments:	
.TE
.P
\f3sh_mem_TXGLs\f1
.TS
l lw(3.5i).
File:	dd/mem/memTxGlS.c
Description:	Used to render polyglyphs with fill style set to texture.
Test By:	T{
Set_Context(ctx, CTX_FILL_STYLE, CTX_FILL_TEXTURED);
.br
PolyGlyph();	
T}
Amorfus Test:	
Comments:	
.TE
.P
\f3sh_mem_fill_shape\f1
.TS
l lw(3.5i).
File:	dd/mem/memFlS.ace
Description:	T{
Used to perform a solid fill of a shape on any memory
depth for all ROPs and plane enables.
T}
Test By:	T{
Clear_Context()  Drawing wide line vectors any width
curves filled polygons where
.br
CTX_SHADE <= CTX_SHADE_SOLID
.br
CTX_FILL_STYLE <= CTX_FILL_SOLID
T}
Amorfus Test:	T{
Any of the wide line test or curve tests.
T}
Testall Test:	T{
Any solid-filled wide line or curve test.
T}
Comments:	T{
As you can tell by the wide variety of primitives drawn
through this primitive,
performance of the routine is critical.
T}
.TE
.H 2 "Memory Dispatch Table"
.P
The memory dispatch table provides the framework for
describing to Shapes how to handle raster to raster
rendering and copying across varying depths.
The routines listed below are not used for VGA color.
.P
In trying to understand what the routines listed below do,
keep in mind the following:
.BL
.LI
The first number is the depth of the source raster.
.LI
The second number is the depth of the destination raster.
.LI
The letter \f2p\fP indicates that the routine looks
at the plane-enable bit of the destination raster.
.LI
The letter \f2d\fP indicates that the routine is used
for the ROP draw only.
.LI
The letter \f2g\fP (for generic) indicates that the
routine handles all ROPs.
.LI
The phrase \f2o16\fP indicates that the routine is optimized
for glyphs between 8 and 16 bits long.
.LI
The phrase \f2o32\fP indicates that the routine is optimized
for glyphs between 16 and 32 bits long.
.LI
The phrase \f2o8\fP indicates that the routine is
optimized for glyphs between 0 and 8 bits long.
.LE
.P
In the mem8 directory, the variations of a file,
for instance sh_mem_CPRS,
are all derived from one source file through compile flags.
.P
You should probably endeavor to change the dispatch
tables to a general routine,
write the most general routines,
and get it working.
Once you've gotten that far,
you can decide whether it's worth the effort to expand
the code size and achieve a performance gain.
(If you have gotten this far,
the probable answer is \f2yes\fP.)
.P
The additional, low-level rendering routines required
by the 8-bit memory port,
as found in the file dd/mem/memDspTab.c are:
.PC
.nf
sh_mem_CPRS_18pd();
sh_mem_CPRS_18pg();
sh_mem_CPRS_88_d();
sh_mem_CPRS_88_g();
sh_mem_CPRS_88pd();
sh_mem_CPRS_88pg();
sh_mem_FLGLo8_18pg();
sh_mem_OSRS_88_d();
sh_mem_OSRS_88_g();
sh_mem_OSRS_88pd();
sh_mem_OSRS_88pg();
sh_mem_STRS_18pd();
sh_mem_STRS_18pg();
sh_mem_TXGL_188_d();
sh_mem_TXGL_188_g();
sh_mem_TXGL_188pd();
sh_mem_TXGL_188pg();
sh_mem_TXRS_18pd();
sh_mem_TXRS_18pg();
sh_mem_TXRS_88_d();
sh_mem_TXRS_88_g();
sh_mem_TXRS_88pd();
sh_mem_TXRS_88pg();
.fi
.SF
.H 2 "Using the Makefile to Create Special Cases for Rendering."
.P
In the current implementation of Shapes,
the Makefile in the low-level rendering directories
can create from a single source file many different
routines special cased for combinations of raster operations
and plane enables;
compile flags determine what special cases are compiled
in or excluded.
.P
For example, the following texturing routine is compiled
in the most generic way possible for all ROPs and using
plane enable masks.
.PC
cc -02 -fsingle -DSH_SMALL -DWINDOWGRABBER -DSH_NO_DEPTH32 -DSH_NO_CG5 \e
-I/home/shapes3/bmac/sun4/shapes/usr/include \e
-I../../include ../../include/fr-sun4.il \e
-DROP_GENERIC -DBIT_PLANE \e
-DCg2_Tex_Raster_1_8=sh_cg2_TXRS_18pg \e
-DCg2_Tex_Raster_Opt_1_8=sh_cg2_TXRSol8pg \e
-DCg2_Tex_Raster_8_8=sh_cg2_TXRS_88pg -sun4 -c cg2TxR.c
.SF
