.if n .pH port.chap1 @(#)chap1	40.1
.ig
imagen dc 8/31/89
docformat -c -s4 -dqm4 -p1 chap1
..
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.BK "Shapes Porting Guide"
.CH "Introduction" "1"
.H 1 "Introduction"
.P
.nh
This document contains topics you should consider
if you are porting Shapes to devices that are
not supported by Shapes code.
It is assumed that you are a
C programmer familiar with UNIX.
In addition, you should be well acquainted with Shapes,
especially the screen object and low-level rendering.
.P
This manual discusses the following topics:
.BL
.LI
The Porting Process
.in +3P
.P
An overview of dispatch tables
.br
Directory structure
.br
Compile considerations
.br
Simplifying the port by setting vector line draw to shape
.in -3P
.LI
Porting at the screen object level
.LE
.H 2 "Getting Started"
.P
If you already have existing rendering code similar
to that needed to support X11 rendering primitives,
you may want to consider porting at the screen object level.
.P
To achieve highest performance,
the memory raster rendering implementation must resemble
(as closely as possible) the memory arrangement
of the most commonly used framebuffer.
There are very few places where
raster data is imported or exported from Shapes,
and any necessary bit/byte order conversions
generally occur at a higher level.
.P
For example, if access to framebuffer pixels is by
planar methods only,
memory rasters should also be implemented in planes,
with a bit/byte order corresponding to that of the framebuffer.
We recommend using the highest scanline padding and
alignment values that the CPU can easily deal with
and that do not waste significant amounts of unused memory.
Matching the scanline alignment of the framebuffer
is always preferred whenever possible.
.P
If your framebuffer looks like Sun memory or the Sun
framebuffer structure,
you probably can inherit via the class mechanism,
or at least work off of the existing raster
memory code,
which is held in the directories dd/mem, dd/mem1/, and dd/mem8.
If not, you will have to choose from two
unpalatable possibilities:
.BL
.LI
Rewriting the code in dd/mem and at least dd/mem1
to match the structure of your framebuffer.
This approach is taken for the color VGA in dd/vga.
Though perhaps painful, this offers the best possibility
for maximum performance from your device.
.LI
Find ways at a lower level to twist the memory from
the Sun structure to the structure of your framebuffer.
Though perhaps easier,
you will need to have a great deal of performance
savvy to get X/NeWS running acceptably via this approach.
.LE
.P
The following steps are recommended as a reasonable way to begin
porting Shapes.
By using these steps,
you will get a great deal of Shapes functionality
up very quickly,
and thus have a platform on which to get a better
sense of the porting strategies that would be
optimal for your device.
.AL
.LI
Install your device into Shapes.
.LI
Port or write from scratch code to do the solid fill of a SHAPE.
.LI
Port thin vector line drawing code.
.LI
Port raster to raster copy code.
.LI
Expand upon fill SHAPE code to include fill styles.
You may want to special case fill styles,
Boolean raster operations, and plane enables.
.LI
Port the glyph code.
Again, you may want to special case on fill styles,
Boolean raster operations, plane enables,
and glyph size and alignment.
.LE
.H 2 "Existing Ports Within Shapes"
.P
This section describes four examples of ports within
the Shapes hierarchy that inherit functionality from
the memory framebuffer code.
As you come across questions in porting Shapes code,
you may find it helpful
to scroll through these ports in order to get an
idea of how the Shapes engineers solved similar problems.
The brief descriptions of these ports proceed from
the simplest to most complex.
.H 2 "BW2"
.P
This is the simplest port because bw2 inherits all of
its functionality from the memory 1 (MEM1) implementation.
Only two files were created or changed
on account of the Bw2.
.AL
.LI
di/init.c \- the device was hooked into Shapes in this file
.LI
dd/bw2Ras.c \- Bw2 initialization code here.
Also demonstrates Mem1 inheritance
mechanism.
.LE
.H 2 "CG4"
.P
The cg4 can inherit most of the MEM8 functionality.
In addition, the cg4 demonstrates how a device can be
invoked through many \f2virtual\fP names, such as:
.BL
.LI
/dev/cgfourX_over
.LI
/dev/cgfourX_ovl
.LI
/dev/cgfourX
.LE
.P
When the cg4 device is type \f2over\fP or \f2ovl\fP,
the physical SCREEN device is SCR_DEV_CG4,
but the virtual SCREEN device is SCR_DEV_BW2.
.P
The great advantage of a cg4 is that its overlay plane
can be used for cursor implementation.
The Shapes port of the cg4 takes advantage of this fact
by writing new code for the CURSOR object to put it
in the overlay plane.
.P
Additional changes that the cg4 demonstrates are:
.AL
.LI
Change to CMAP Installation implementation \- The Cg4
inherits all cmap functionality save the Install_Cmap operator.
Check out how this is rewritten in dd/cg4Ras.c
.LI
Changes to CURSOR implementation \- Cursor object is
nearly totally rewritten in dd /cg4Ras.
Again, the use of the inheritance mechanism should be your
main item of interest.
.LE
.H 2 "CG2"
.P
The port to the cg2 is a full-fledged port,
requiring rewriting of substantial amounts of lower-level
rendering code.
The new code takes advantage of the cg2's hardware support for ROPS,
plane enables, and multipixel fill and copy functionality.
As with the other ports,
you must integrate the cg2 into Shapes via its own init function,
sh_init_cg2.
.P
Most of the work of the port is rewriting the stroke,
fill, copy, and glyph functions.
However, before you can write those functions,
you must create the cg2 dispatch tables so that Shapes
will find them when they are needed.
The cg2 dispatch tables
(at the top of file cg2/cg2Ras.c)
are just a renaming of the functions used in the mem8
dispatch tables (see file dd/M8Ras.c).
In
fact, if you compare them,
you will see their forms are exactly the same,
even though the function names in various slots are different.
When beginning a framebuffer port,
copying the dispatch tables from another framebuffer
is often a good first step.
.P
The cg2 also provides a new implementation of some portions
of CMAP and RASTER objects.
Colormap code is redone to maintain a color map in both
hardware and software.
Rasters are redone to take advantage of the more efficient
functionality for the following operators:
.SS
Write_Raster
Display_Raster
Store_Raster
Path_Raster (called by Display_Context)
Color_Raster
Clear_Raster
Dispatch_Raster
.ft1
.SE
.P
The most significant change \(em replacing the mem8 low-level
rendering with a cg2 version \(em requires new dispatch
tables that are hooked into the screen object.
The following code in dd/cg2/cg2Ras.c assigns the screen
function dispatch tables through the commands:
.PC
	scr->SCR_STROKE_FUN = cg2_stroke_fun;
	scr->SCR_FILL_FUN = cg2_fill_fun;
	scr->SCR_COPY_FUN = cg2_copy_fun;
	scr->SCR_GLYPH_FUN = cg2_glyph_fun;
.ft1
.SF
.H 2 "VGA"
The hierarchy also includes an unsupported port to a
VGA display controller in a 16 color, 4 bit deep mode.
Like the CG2 port, the VGA port replaces the low-level rendering code
with functions optimized for the VGA.
These functions are defined in dd/vga.
The dispatch tables have been replaced in di/vgaRas.c
to refer to the vga specific functions.
The rendering functions work on both memory and screen rasters.
Note that the format of memory rasters is different from the
format used in dd/mem1.
.P
The VGA also provides new implementation of some
portions of the CMAP and RASTER objects.
New colormap code loads the colors into the
palette registers of the VGA.
The modifications to the RASTER object account for the differences
in raster formats.
.P
The VGA implementation is designed to work within the
virtual terminal mechanism of UNIX System V/36.
The code for handling virtual terminal switching requests is in di/vgaVt.c.
.P
A monochrome VGA port is also included in the hierarchy.
This port uses all the code in dd/mem and dd/mem1,
making it very similar in nature to the BW2 port.
The major difference is that several byte-ordering dependencies
have been corrected for this port.
