.if n .pH arch.raster @(#)raster	40.2
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.nh
.ds S) Shapes
.SO BP.HEADER
.BK "Shapes Internal Architecture"
.CH "The RASTER object" "4"
.H 1 "The RASTER object"
.H 2 "Introduction"
A raster represents a drawing surface on the
screen or in off-screen memory.
It is composed of two parts:\ \&
a pixel array containing the image,
and a list of rectangles defining a region to
which the image is clipped.
.H 2 "Raster Attributes"
The external raster attributes are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the internal attributes
that are used in the implementation of the
raster object.
All raster attributes are defined in
include/sh_RAS.ah;
their values are defined in include/sh_RAS.h.
.P
.PC
Unsgn8        RAS_DEPTH;
Unsgn8        RAS_AREA_STYLE;
unsigned int  RAS_CURSOR_OVERLAP : 1;
unsigned int  RAS_ANTI_ALIAS : 1;
unsigned int  ras_type_index : 2;
unsigned int  ras_depth_index : 2;
unsigned int  ras_shape_clip : 1;
unsigned int  ras_private : 1;
RAS_type      RAS_TYPE;
Unsgn32       RAS_PLANE_ENABLE;
CMAP          RAS_CMAP;
POINT_B2D     RAS_ORG;
POINT_B2D     RAS_DIM;
PATH          RAS_CLIP_PATH;
unsigned char *RAS_DATA;
Unsgn32       RAS_LINEBYTES;
RASTER        ras_parent;
SCREEN        ras_screen;
COORD_2D      ras_base;
CONTEXT       ras_ctx;
SHAPE         ras_shape;
SHAPE         ras_clip_shape;
OBJ_KEY       ras_clip_key;
Unsgn32       *ras_lock;
Unsgn32       *ras_infop;
.SF
.H 2 ras_parent
.P
Parent of the given raster.
This field is NULL unless this raster is a child raster
(created with type RAS_TYPE_CHILD).
A child raster inherits the attributes of its
parent and shares the same memory or screen
area.
The dimensions and origin of a child may be
different than its parent,
but most of the other attributes
(like depth, color map, etc.)
must be the same.
When the raster is created,
ras_parent is set and never changed.
Parent rasters are reference counted so that a
parent raster's resources will not disappear
until all of its children have been removed.
.H 2 ras_screen
.P
Screen object from which this raster was derived.
A screen represents a single display open device
(framebuffer or accelerator).
There is also a screen for each different depth
of memory raster (1, 8, 32).
When a memory raster is created,
its depth is used to select which screen object
it is derived from.
The screen object for a screen raster is
determined from its device name.
Child rasters inherit the screen from their parent.
.P
The screen contains information on
device-dependent raster characteristics such as alignment,
maximum pixel resolution, device register locations,
file descriptor of open device:\ \&
anything that is common to all rasters of a given
depth or device type.
It is created when the device is opened,
usually when the first screen raster is made for
that device.
A screen object is removed when the last screen
raster using the device is destroyed.
.P
The ras_screen variable is used internally within
device-dependent code to access device-specific fields.
It is set once when the raster is created and
never changed.
The file descriptor for the device is stored in
the SCREEN,
so any OS ioctl calls on the device need to go
thru ras_screen.
.P
The screen object is documented fully in
Chapter 10.
.H 2 ras_base
.P
Contains the device coordinate values for the
first existing pixel in the physical memory
allocated for the raster.
For screen rasters,
this value is always 0,0
regardless of the RAS_ORG value.
For memory rasters,
ras_base is always equal to RAS_ORG.
On a child raster, the ras_base is the same as the
raster origin position, as seen by its parent raster.
For all rasters,
RAS_ORG minus ras_bas always equals the offset
needed to reference the first pixel in the raster.
.H 2 ras_type_index
.P
.TB "Numeric Index of Raster Types"
.TS
box tab (;);
cf2 | cf2 | cf2
l | l | l.
Index;Raster type;Description
=
1;RAS_MEM;memory raster
2;RAS_SCR;screen raster
3;RAS_CHLD_MEM;child of memory raster
4;RAS_CHLD_SCR;child of screen raster
.TE
.TT
.P
RAS_TYPE points to a function and cannot be used
inside of a C ``switch'' statement,
whereas ras_type_index is in a more convenient
form for internal use and distinguishes between
memory and screen child rasters
(which RAS_TYPE does not).
.H 2 ras_depth_index
.P
.TB "Raster Depth Index"
.TS
box tab (;);
cf2 | cf2
l | l.
Index;Number of Bits
=
0;depth 1
1;depth 4
2;depth 8
3;depth 32
.TE
.TT
.P
The raster depth index is used when indexing into
internal dispatch tables based on raster depth.
.H 2 ras_shape_clip
.P
Sets a bit flag to indicate whether the raster
clip shape is a rectangle or not.
The bit is set if the clip shape is an arbitrary
shape and clear if it is a rectangle.
This variable gives the status of the combined
raster/context clip shape in ras_clip_shape
(not the shape described by RAS_CLIP_PATH).
It is computed every time ras_clip_shape is validated.
.H 2 ras_private
.P
Sets the bit flag if the raster data area
(RAS_DATA) is provided by the user
(rather than allocated by \*(S)).
Once the user provides the data area,
\*(S) never attempts to re-size or free it.
.H 2 ras_ctx
.P
Provides the context associated with a raster.
The ras_ctx variable is highly volatile and is
only valid during the rendering of a single item,
such as within Display_Path, Display_Context, or Display_Raster.
It is
\f2not\f1
valid across \*(S) calls.
It exists so that lower level rendering code
can access the context being used with this
raster without explicitly having to pass its handle.
It is typically set at the start of a display operation,
after the raster/context clip shape is validated.
.H 2 ras_shape
.P
SHAPE object describing the clip shape of the raster.
If RAS_CLIP_PATH is set,
ras_shape is the SHAPE describing its area.
If RAS_CLIP_PATH is NULL,
ras_shape is a SHAPE object describing the raster
bounding box.
This variable is set when the raster clip shape
is validated
(by Shape_Raster or Clip_Raster, see ras_clip_key).
It is cleared if RAS_CLIP_PATH is set to NULL or
if RAS_CLIP_PATH is already NULL and the raster
bounding box changes
(RAS_ORG or RAS_DIM).
.H 2 ras_clip_shape
.P
SHAPE object describing the clip shape of the
current raster/context pair.
A raster may be associated with more than one
context at a time,
and a context may be switched between more than
one raster.
ras_shape attempts to remember the intersection
of the raster clip path and the clip path of the
context this raster was last used with.
It optimizes the case where a raster is
associated with a single context and used many
times by reducing the frequency of costly shape
intersection operations.
.\" begin new page
.P
When CTX_CLIP_PATH is set,
a SHAPE object is created that describes the
area enclosed by this path.
Similarly, a SHAPE object describing the raster
clip path (see ras_shape) is created whenever
this changes.
ras_clip_shape is the intersection of these two
SHAPE objects.
.H 2 ras_clip_key
.P
OBJ_KEY holding a validation key indicating the
status of the raster/context clip (ras_clip_shape).
Every time the raster clip shape changes (ras_shape),
ras_clip_key is given a different value.
Every time the context clip shape changes (CTX_CLIP_PATH),
a corresponding key in the context, ctx_clip_key,
also gets a different value.
.P
\*(S) determines whether to re-compute the
raster/context clip shape by comparing whether
ras_clip_key and ctx_clip_key are equal.
If they are not equal,
the raster/context clip shape is recomputed,
and ctx_clip_key is copied into ras_clip_key.
As long as the raster and context clip shapes
remain the same,
neither key will change,
and ras_clip_shape will not be recomputed.
When either of these changes,
or when the raster is used with a different context,
the keys will be different.
.H 2 "ras_lock, ras_infop"
.P
Window grabber status fields.
.H 2 "Internal Raster Operators"
.P
The calling conventions of the external raster
operators are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the implementation of
these operators,
assuming the reader is familiar with their
behavior.
We also describe internal raster operators that
are used by \*(S) but not intended to be user-callable.
All raster operators are defined in include/sh_RAS.h.
.P
Many of the raster operators are implemented as
front-ends that set up global dispatch
vectors to select one or more device-specific
rendering routines to do that actual drawing.
This process is described in detail in
Chapters 13 and 14.
.H 2 "Get_Raster, Set_Raster"
.P
All of the raster attributes are inquired via macros.
The name of the attribute is used to generate a
specific macro to return the structure field
associated with the attribute.
Macros for attributes which require computation
generate calls to the internal Get_Raster operator.
Raster attributes are always set with a subroutine call.
.P
The following section of code shows the macro
definitions for some raster attributes to
illustrate the different methods:
.PC
#define Get_Raster(r,a) CAT(a,get)((RASTER)(r))
#define RAS_TYPEget(r)  ((r)->RAS_TYPE)
#define RAS_VSYNCget(r) ((int) GetOper_Obj(r, RAS_OP_Get)
                                          (r,RAS_VSYNC))
#define Set_Raster(r,a,v)
        ((void) GetOper_Obj(r,RAS_OP_Set)((RASTER)(r), a, v))
.SF
.H 2 "Read_Raster, Write_Raster"
.P
Read_Raster and Write_Raster allow the user to
import or export raster data into a \*(S) raster object.
.H 2 "Display_Raster, Store_Raster"
.P
These routines copy raster data to and from a
raster associated with a context.
They are typically implemented with
device-dependent front ends that
setup and call generic subroutines
(sh_Display_Raster and sh_Store_Raster)
to do intermediate computation.
Ultimately, the device-dependent RenderCopy
routine is used to do that actual raster copy.
.H 2 Image_Raster
.P
Performs image transformations on raster data.
This is a stand-alone routine and does not
currently use any of the \*(S) RenderXXX routines.
.H 2 Points_Raster
.P
Displays a list of points on a raster (used by X11).
Like Image_Raster, it is stand-alone.
.H 2 Clear_Raster
.P
Clears the display area defined by the raster
clip path to the background color.
This is an internal operator called by the
Clear_Context macro.
It is usually device-dependent and uses
the RenderShape macro to fill the shape
associated with the clip path with a color.
.H 2 Color_Raster
.P
Sets the device-dependent value of the current
color based on a \*(S) COLOR.
It is called by the path transformation pipelines
when a COL_INDEX, COL_RGB, or COL_HSV path item
is encountered.
Some accelerators can cache the current color in
a device register.
And some implementations
(monochrome framebuffers, for example)
may change the set of lower level rendering
routines depending on the current color.
This operator exists to allow device-independent
transformation pipelines to process color changes
in a device-dependent way.
.H 2 "Shape_Raster, sh_Shape_Raster"
.P
Internal raster routine
(not an object operator, a subroutine)
that validates the raster clip shape (ras_shape).
If ras_shape is NULL,
it is recomputed based on the raster bounding box.
If ras_shape is not NULL,
no validation is done because it is assumed that,
either it reflects the current SHAPE
for RAS_CLIP_PATH or the bounding box has not changed.
Note that, in either case,
ras_clip_key is left alone.
.H 2 "Clip_Raster, sh_Clip_Raster"
.P
Internal raster routine
(not an object operator, a subroutine)
that validates the raster/context clip shape (ras_shape).
If ras_clip_key and ctx_clip_key are equal,
no validation is done.
Otherwise, the raster clip shape is validated
(by Shape_Raster) and intersected with the
context clip shape.
ctx_clip_key is copied into ras_clip_key.
.P
Clip_Raster is called at the start of any \*(S)
call that displays something on a raster.
The key comparison is done outside the subroutine call,
in the macro.
.H 2 Dispatch_Raster
.P
Dispatch_Raster allows one to set up the
low-level rendering dispatch vectors FB_rnd_shape,
FB_rnd_copy, and FB_rnd_glyph for any raster.
Dispatch_Raster will also execute any device
specific setup-code for that raster.
This may be useful when the source raster needs
device specific setup.
(Since raster code dispatches off the destination
raster in any operation,
it may sometimes be necessary to take special
heed of the source raster.)
See Chapter 13 for
details about how this dispatching is organized.
.H 2 Glyph_Raster
.P
Renders a glyph list on the given raster.
It is called by the Poly_Glyph macro.
Glyph_Raster is implemented with a
device-dependent front ends
that does dispatching setup.
Glyph_Raster uses the RenderGlyph routine to
display the glyph list.
.H 2 Path_Raster
.P
Renders a path on the given raster.
Called by the Display_Context and Display_Path macros.
This routine is highly device dependent:\ \&
it initializes device registers and selects
device specific implementations for
transformation and rendering routines.
All framebuffer implementations of Path_Raster
are derived from a generic prototype in dd/pathRas.c.
It uses macros in pathMac.h,
which are redefined for each device.
This function is where all the flags we set in
the raster, context, and transform are combined
to select specific transformation and
rendering from the SCREEN object associated with
the raster on which we are drawing.
See Chapter 13
for a description of the dispatch tables
Path_Raster works with.
.BL
.LI
process path according to type
(empty, immediate mode, current)
.LI
validate clip shape
(use ctx_clip_key, ras_clip_key)
.LI
for current path,
apply transform to coordinates if necessary
.LI
validate viewing pipeline transform
(use ctx_pipe_flags)
.LI
initialize rendering attributes
(FB_xxx and device registers)
.LI
select path rendering pipeline
(combine ctx_pipe_type and ras_shape_clip)
.LI
select path transformation function
(combine ctx_pipe_disp and TRANS_TYPE to select a
function from SCR_PATH_FUN)
.LI
select raster drawing primitives for the pipeline
(initialize FB_rnd_xxx as needed by combining
context attributes and ctx_draw_disp to select a
function from SCR_STROKE_FUN or SCR_FILL_FUN).
.LI
call path transformation and rendering function
to render the path.
.\" begin new page
.LE
.P
.FG "Path Rendering Process" FG_Path_Rend
.DS
.BP PSART/ps.pth_rnd2 3.75i 0 "" 0.75 0.75 0
.DE
