'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH ref.context @(#)context	40.2 of 11/9/89

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 context
..
.SO mstr.hdr
.SO BP.HEADER
.ds Lb Shapes
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.BK "Shapes Reference Manual"
.CH "Context Object" "4"
.H 1 "Context Object"
.H 2 "Introduction"
.P
.nh
The context object sets the graphics state that
specifies precisely how Shapes will draw.
For example, one attribute, the CTX_SHADE,
determines whether to draw outlined polygons
rather than filled polygons.
Others determine clipping regions, line drawing style,
line ending and line cap style, colors, etc.
This chapter describes the context attributes.
.P
Perhaps the most important context attribute is
its associated raster, CTX_RASTER,
which specifies the drawing surface.
Each context has but one raster;
however, any raster can be the drawing surface
for an unlimited number of contexts.
.P
Another conceptually vital context attribute is
the path attribute, CTX_PATH,
which stores geometric information.
When you create and attach a path to the context object,
all drawing primitives accumulate in the path object,
enabling them to be rendered and re-rendered with
the same of differing context attributes.
.P
Some of the context attributes relate closely to
operators and concepts set forth in the
\f2P\s-2OST\s+2S\s-2CRIPT\s+2 Language Reference Manual.*\f1
You may want to turn there for another
description of line styles, joins,
mitre limits, and caps,
as well as a discussion of arbitrary clip paths,
curve geometry, and coordinate transformations.
.H 4 "NAME"
.P
Clear_Context \- Clears the display memory of the
raster associated with the context.
.IX "Clear_Context"
.tm .CE U 3 "Clear_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Clear_Context\f2(ctx)\f1
.br
CONTEXT ctx;
.H 4 "DESCRIPTION"
.P
Clears the entire raster associated with the
specified context to the background color,
ignoring the context clip path and ROPs.
CTX_PLANE_ENABLE is not ignored so that plane
enable masks remain functional.
.P
\f2ctx\f1
The context associated with the raster to be cleared.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_BACK_COLOR
.br
CTX_RASTER
.H 4 "NAME"
.P
Copy_Context \- Copies the attributes of the
source context into a new or existing context.
.sp
\s-2* Adobe Systems Incorporated:
.UI "P\s-2OST\s+2S\s-2CRIPT\s+2 Language Reference Manual" :
Addison-Wesley Publishing Company,
Reading, Massachusetts, 1985.\s+2
.IX "Copy_Context"
.tm .CE U 3 "Copy_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Copy_Context\f2(src, dst)\f1
.br
CONTEXT src;
.br
CONTEXT dst;
.H 4 "DESCRIPTION"
.P
Copies the source context into the destination context.
Shapes makes a full copy for the following context attributes,
which reference other objects:
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
CTX_MODEL_TRANSFORM
.br
CTX_VDC_TRANSFORM
.br
CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF Paint-----------------------------------------------
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF SHAPES----------------------------------------------
CTX_PATH
.P
A copy by
\f2references\f1
is made for the following objects,
and the reference count for each attribute is increased by one.
CTX_CLIP_PATH
.br
CTX_FILL_RASTER
.br
CTX_LINE_PATTERN
.br
CTX_RASTER
.P
\f2src\f1
The context from which the attributes are to be copied.
.P
\f2dst\f1
The context into which the attributes are to be copied.
If the destination is designated as NULL,
the context is duplicated,
and a pointer is issued to a new context.
The new context, like those created with Create_Context,
has a reference count of one.
.H 4 "RETURNED VALUE"
.P
CONTEXT
.P
NULL is returned if the copy cannot be made.
.H 4 "SEE ALSO"
.P
Create_Context
.H 4 "NAME"
.P
Create_Context \- Creates a new context.
.IX "Create_Context"
.tm .CE U 3 "Create_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Context\f2(type, raster)\f1
.br
CTX_type type;
.br
RASTER raster;
.H 4 "DESCRIPTION"
.P
Creates a new context and associates it with the
specified raster.
The context object begins with a reference count
of 1 and therefore requires Destroy_Context to
free its resources.
The attributes of a context can be read and
altered with Set_Context and Get_Context.
.P
Create_Context creates a path object associated with CTX_PATH.
You may query and manipulate this path object.
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.P
You must set CTX_PIPELINE to enable the transform
or transforms before you can get that transform
and use its object handle.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.P
You must set CTX_PIPELINE before you can acquire
and use the object handle for CTX_VIEW_TRANSFORM.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.P
The defaults for the other attributes are
described on their attribute page.
.P
\f2type\f1
.P
Specifies the type of context to create for rendering.
CTX_GENERIC is the only predefined context type.
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
However, this parameter makes additions possible.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.P
\f2raster\f1
Determines the drawing surface associated with the context.
The attribute CTX_RASTER is a reference to this raster,
and a call to Display_Context will direct primitives to it.
Although Shapes works for all Sun device types,
performance can be greatly enhanced by a graphics accelerator.
.H 4 "RETURNED VALUE"
.P
CONTEXT
.P
NULL is returned if the context cannot be created.
.H 4 "SEE ALSO"
.P
Path Objects
.br
Transform Objects
.br
Create_Raster
.H 4 "NAME"
.P
Destroy_Context \- Destroys the specified context.
.IX "Destroy_Context"
.tm .CE U 3 "Destroy_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Context\f2(ctx)\f1
.br
CONTEXT ctx;
.H 4 "DESCRIPTION"
.P
Destroys the specified context and frees the
resources associated with it.
If other objects refer to the context,
the resources are not freed until all references
are removed.
.P
Unless you have created and assigned these objects to the context,
as you did CTX_RASTER,
the resources of the following objects will also be freed:
.P
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
CTX_CLIP_PATH
.br
CTX_FILL_RASTER
.br
CTX_LINE_PATTERN
.br
CTX_MODEL_TRANSFORM
.br
CTX_PATH
.br
CTX_VDC_TRANSFORM
.br
CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF Paint-----------------------------------------------
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
CTX_CLIP_PATH
.br
CTX_FILL_RASTER
.br
CTX_LINE_PATTERN
.br
CTX_PATH
.br \}
.\"  ENDIF Paint-----------------------------------------------
.P
\f2ctx\f1
.P
The context to be destroyed.
.P
NOTE: After it has been destroyed,
it is an error to use this context handle unless
it is reassigned to another context.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Create_Context
.H 4 "NAME"
.P
Display_Context \- Renders the geometry in the
current path to the current raster.
.IX "Display_Context"
.tm .CE U 3 "Display_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Display_Context\f2 (ctx, post_time)\f1
.br
CONTEXT ctx;
.br
int post_time;
.H 4 "DESCRIPTION"
.P
Renders the current path into the current raster,
displaying an area of the raster equal to the
intersection of the raster clip path and the
context clip path.
Rendering a path will update the values of
CTX_PEN and CTX_RASTER_PEN.
Also, depending on the contents of the path,
it may change the values of CTX_COLOR.
See the Color() drawing macro.
.P
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
If the path associated with the context is of
type PATH_IMMEDIATE,
the contents of the path will be cleared after
the path is rendered.
The default path created by Create_Context is of
type PATH_IMMEDIATE.
.P
.br \}
.\"  ENDIF Paint-----------------------------------------------
The rendering style, geometry,
and transformations applied are dependent on the
context attribute values.
.P
The time when the hardware displays the image
depends on the setting of post_time argument for
a context whose raster is associated with a
graphics accelerator.
.P
\f2ctx\f1
The context to be displayed.
.P
\f2post_time\f1
Specifies whether the hardware is flushed and
when the current path is rendered.
.TB "Display_Context Posting Arguments"
.TS
box, tab(/);
cf4I | cf4I
l | lw(4.5i).
Arguments/Description
=
CTX_RENDER/T{
Causes the contents of the current path to be rendered.
If the underlying hardware buffers information,
CTX_FLUSH may be required to make the entire image visible.
T}
_
CTX_FLUSH/T{
Flushs from CPU to the hardware buffer making
buffered information visible.
On hardware that has no graphics buffer,
using only this enumeration has no effect.
T}
_
CTX_RENDER_FLUSH/T{
Renders the current path directly on through to
the display.
T}
.TE
.TT
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_PEN
.br
CTX_RASTER_PEN
.br
PATH object
.br
Color()
.H 4 "NAME"
.P
Get_Context \- Returns the current setting of the
specified context attribute.
.IX "Get_Context"
.tm .CE U 3 "Get_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Get_Context\f2(ctx, attr)\f1
.br
CONTEXT ctx;
.br
CTX_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the current setting of the specified
context attribute as illustrated by the code sample below:
.SS
POINT_B2D *p;

p =Get_Context(ctx, CTX_PATH_PEN));
printf("Location of last point: %f, %f\\\\n",
       floatfr(p->x), floatfr(p->y));
.ft1
.SE
.P
You can use Get_Context to obtain object handles
of objects like CTX_VIEW_TRANSFORM,
and then use the object handles to
manipulate the contents of the context's objects.
.P
\f2ctx\f1
The context from which the attribute setting is
to be returned.
.P
\f2attr \f1
The attribute setting to be returned.
.H 4 "RETURNED VALUE"
.P
Attribute type
.H 4 "SEE ALSO"
.P
Set_Context
.br
Context Attributes
.H 4 "NAME"
.P
Set_Context \- Sets the context attribute.
.IX "Set_Context"
.tm .CE U 3 "Set_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Set_Context\f2(ctx, attr, setting)\f1
.br
CONTEXT ctx;
.br
CTX_attr attr;
.br
<attribute type> setting;
.H 4 "DESCRIPTION"
.P
Sets the context attribute to the specified setting.
This may lead to changes in the values of other
context attributes.
.P
\f2ctx\f1
The context for which the attribute type is to be set.
.P
\f2attr\f1
The attribute for which the type is to be set.
.P
\f2setting\f1
The setting for the specified attribute.
The type varies according to the
attribute.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Get_Context
.H 4 "NAME"
.P
Temp_Context
.IX "Temp_Context"
.tm .CE U 3 "Temp_Context" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Temp_Context\f2(type, raster)\f1
.br
CTX_type type;
.br
RASTER raster;
.H 4 "DESCRIPTION"
.P
Creates a new context that has no initial reference count.
This operator works exactly like Create_Context
except that it does not have to be explicitly destroyed.
It is useful for passing the context as an
argument to another operator.
.P
\f2type\f1
.P
Specifies the type of context to create for rendering.
Currently, CTX_GENERIC is the only predefined context type,
but this parameter makes additions possible.
.P
\f2raster\f1
.P
Determines the drawing surface associated with the context.
The attribute CTX_RASTER is a reference to this raster,
and a call to Display_Context will direct primitives to it.
Although Shapes works for all Sun device types,
performance can be greatly enhanced by a graphics accelerator.
.H 4 "RETURNED VALUE"
.P
CONTEXT
.P
NULL is returned if the context cannot be created.
.H 4 "SEE ALSO"
.P
Create_Context
.br
Path Objects
.br
Transform Objects
.br
Create_Raster
.br
.H 2 "Context Attributes"
.H 4 "NAME"
.P
CTX_AREA_STYLE
.IX "CTX_AREA_STYLE"
.tm .CE U 3 "CTX_AREA_STYLE" \n(PN
.H 4 "DESCRIPTION"
.P
Controls area closure and fill behavior.
To set this attribute,
choose one setting for CTX_CLOSE and one setting
for CTX_FILL and OR them together.
CTX_AREA_STYLE accepts the following:
.IX "non-zero winding number rule"
.IX "rule" "non-zero winding number"
.IX "even-odd rule"
.IX "rule" "even-odd"
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.TB "CTS_AREA_STYLE Types"
.TS
center box;
cf4I | cf4I
l | lw(4.5i).
Value 	Description
=
CTX_CLOSE_OFF	T{
The area is closed only when a close primitive or
the end of the path is encounted.
This is the default.
T}
_
CTX_FILL_NONZERO	T{
The non-zero winding rule is used to determine
which parts of the area are to be filled.
This is the default.
T}
_
CTX_FILL_EVENODD	T{
The even-odd rule is used to fill the area.
T}
.TE
.TT
.br \}
.\"  ENDIF SHAPES------------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.TS
center box;
cf4I | cf4I
l | lw(4.5i).
Value 	Description
=
CTX_CLOSE_OFF	T{
If CTX_CLOSE_MOVE is not set,
the area is closed only when a close primitive or
the end of the path is encounted.
This is the default.
T}
_
CTX_CLOSE_MOVE	T{
PT_MOVE operations close the current area and
start a new area.
T}
_
CTX_FILL_NONZERO	T{
The non-zero winding rule is used to determine
which parts of the area are to be filled.
This is the default.
T}
_
CTX_FILL_EVENODD	T{
The even-odd rule is used to fill the area.
T}
.TE
.br \}
.\"  ENDIF PAINT------------------------------------------------
.P
The following describes the two rules that
determine whether or not a closed region within a
polygon is filled:
.P
\f2Non-Zero Winding Rule \fP
.BL
.LI
Pick any point inside the region.
.LI
Draw a ray from the point in any direction;
the ray should intersect the bounds \- it should not graze,
touch, or run coincident to a bound.
.LI
Start at the point with a count of zero and move along the ray.
At each bound the ray intersects,
add one if the ray crosses a bound going left-to-right,
and subtract one if the ray crosses a bound going right-to-left.
.P
If the total along the ray is non-zero,
the region is filled;
otherwise, it stays unfilled.
.P
\f2Even-Odd Rule\fP
.LI
Create a ray in the same way as for the non-zero
winding rule above.
.LI
Starting at the point with a count of zero,
add one for each bound the ray crosses.
.LI
If the total number of bounds crossed is odd,
the region is filled;
otherwise, it stays unfilled.
.LE
.P
The following code and illustrations demonstrates
the filling rules:
.PC
Color (black)
PT_MOVE,0,0
PT_LINEREL,50,0
PT_LINEREL,0,50
PT_LINEREL,-50,0
Color (grey)
PT_LINEREL,0,-50
PT_MOVE,25,25
PT_LINEREL,50,0
PT_LINEREL,0,50
PT_LINEREL,-50,0
PT_LINEREL,0,-50
.ft1
.SF
.FG "Fill Rules"
.DS
.BP PSART/ps.evenodd 5i
.EP
.DE
.H 4 "RETURNED VALUE"
.P
CTX_area_style
.H 4 "SEE ALSO"
.P
Close
.br
CloseSubpath
.br
PT_MOVE
.br
RAS_AREA_STYLE
.H 4 "NAME"
.P
CTX_BACK_COLOR
.IX "CTX_BACK_COLOR"
.tm .CE U 3 "CTX_BACK_COLOR" \n(PN
.H 4 "DESCRIPTION"
.P
Used during clear operations, stippling,
and for the even dashes of double-dashed lines and curves.
Also used during certain raster fill operations
to draw the destination raster's pixel when the
source raster's pixel has a value of zero.
.P
.H 4 "RETURNED VALUE"
.P
COLOR *
.H 4 "SEE ALSO"
.P
Clear_Context
.br
Display_Raster
.br
Store_Raster
.br
CTX_COLOR
.br
CTX_FILL_STYLE
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_CLIP_DIM
.IX "CTX_CLIP_DIM"
.tm .CE U 3 "CTX_CLIP_DIM" \n(PN
.H 4 "DESCRIPTION"
.P
A point specifying view clipping area dimensions
during path rendering.
The clipping dimension serves as a measure
analogous to that of the radius of a circle:\ \&
it is the distance from the origin to an edge of
the clipping area along the x- and y-axis.
No view clipping occurs during path construction.
You define the coordinate space for the clipping
area through the mapping defined by the viewing
transforms CTX_MODEL_TRANSFORM and CTX_VIEW_TRANSFORM.
.P
In order for view clipping to occur,
you must first enable it by setting the
CTX_PIPELINE attribute to include CTX_APPLY_CLIP
and the application of the transforms you deem appropriate.
The default clip coordinate area is the the
dimension (1,1).
.P
Clipping to the raster clip path and the context
clip path occurs after view clipping.
.P
If the CTX_VDC_MAP attribute is set to
CTX_MAP_RASTER and the VDC transform is enabled,
Shapes will control the values of CTX_CLIP_DIM;
you may only query this attribute.
CTX_MAP_RASTER is the default setting for CTX_VDC_MAP.
.H 4 "RETURNED VALUE"
.P
POINT *
.H 4 "SEE ALSO"
.P
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_VDC_MAP
.br
CTX_PIPELINE
.br
CTX_VIEW_TRANSFORM
.br
CTX_VDC_TRANSFORM
.H 4 "NAME"
.P
CTX_CLIP_ORG
.IX "CTX_CLIP_ORG"
.tm .CE U 3 "CTX_CLIP_ORG" \n(PN
.H 4 "DESCRIPTION"
.P
A point specifying the clipping area center point.
You define the coordinate space for this point by
the mapping defined by the viewing transforms
CTX_MODEL_TRANSFORM and CTX_VIEW_TRANSFORM.
.P
If the CTX_VDC_MAP attribute is set to CTX_MAP_RASTER,
Shapes will control the values of CTX_CLIP_DIM;
you may then only query this attribute.
CTX_MAP_RASTER is the default setting for CTX_VDC_MAP.
.H 4 "RETURNED VALUE"
.P
POINT *
.H 4 "SEE ALSO"
.P
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_PIPELINE
.br
CTX_VIEW_TRANSFORM
.br
CTX_VDC_TRANSFORM
.br \}
.\"  ENDIF Paint------------------------------------------------
.H 4 "NAME"
.P
CTX_CLIP_PATH
.IX "CTX_CLIP_PATH"
.tm .CE U 3 "CTX_CLIP_PATH" \n(PN
.H 4 "DESCRIPTION"
.P
A path defining the current boundary against
which all output is clipped before being rendered into the raster.
.P
The raster has its own clip path,
so the effective clip path is the intersection
between the raster's clip path and the clip path
of the context.
When creating an effective clipping region at display time,
only the path area is used to describe the clipping region.
.P
When you call Set_Context to set the clip path,
if a path has geometry,
it is converted to a path area.
If the path has area and no geometry,
the path area is unchanged and used for the clip region.
Finally, if the path has neither area nor geometry,
a rectangular path area is created,
based on the PATH_ORG and PATH_DIM.
(This sequence of rules is described more
completely by the Area_Path operator.)
.P
A NULL clip path value indicates no context clip
path and that only the raster's clip path is used.
.FG "Raster Clipping"
.DS
.BP PSART/ps.rstr_clip 3.75i 0
.EP
.DE
.H 4 "RETURNED VALUE"
.P
PATH
.H 4 "SEE ALSO"
.P
Area_Path
.br
Differ_Path
.br
Intersect_Path
.br
Union_Path
.br
RAS_CLIP_PATH
.br
CTX_AREA_STYLE
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_CLIP_PLANES
.IX "CTX_CLIP_PLANES"
.tm .CE U 3 "CTX_CLIP_PLANES" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the active view area clip planes.
Logically or the following attributes together to
select your combination.
.P
Since clipping uses a left-handed coordinate system
(x increases going left-to-right,
y increases going bottom-to-top),
the clip planes are at the following coordinates:
.P
.br
CTX_CLIP_LEFT \- clip to the line defined by two points:
.br
     (CLIP_ORG.x - CLIP_DIM.x,CLIP_ORG.y - CLIP_DIM.y)
.br
     (CLIP_ORG.x - CLIP_DIM.x, CLIP_ORG.y + CLIP_DIM.y)
.P
CTX_CLIP_RIGHT \- clip to line defined by the two points:
.br
     (CLIP_ORG.x + CLIP_DIM.x,CLIP_ORG.y - CLIP_DIM.y)
.br
     (CLIP_ORG.x + CLIP_DIM.x,CLIP_ORG.y + CLIP_DIM.y)
.P
CTX_CLIP_TOP \- clip to the line defined by the two points:
.br
     (CLIP_ORG.x - CLIP_DIM.x,CLIP_ORG.y + CLIP_DIM.y)
.br
     (CLIP_ORG.x + CLIP_DIM.x,CLIP_ORG.y + CLIP_DIM.y)
.P
CTX_CLIP_BOTTOM \- clip to the line defined by the two points:
.br
     (CLIP_ORG.x - CLIP_DIM.x,CLIP_ORG.y - CLIP_DIM.y)
.br
     (CLIP_ORG.x + CLIP_DIM.x,CLIP_ORG.y - CLIP_DIM.y)
.br
CTX_CLIP_X \- same as CTX_CLIP_LEFT | CTX_CLIP_RIGHT
.br
CTX_CLIP_Y \- same as CTX_CLIP_TOP | CTX_CLIP_BOTTOM
.br
CTX_CLIP_ALL \ - same as CTX_CLIP_X | CTX_CLIP_Y
.br
CTX_CLIP_NONE \- Disable all clip planes.
This is the default.
.P
.H 4 "RETURNED VALUE"
.P
CTX_clip_planes
.H 4 "SEE ALSO"
.P
CTX_CLIP_ORG
.br
CTX_CLIP_DIM
.br
CTX_VDC_TRANSFORM
.br
CTX_VDC_MAP
.br \}
.\"  ENDIF Paint------------------------------------------------
.H 4 "NAME"
.P
CTX_COLOR
.IX "CTX_COLOR"
.tm .CE U 3 "CTX_COLOR" \n(PN
.H 4 "DESCRIPTION"
.P
Used to determine the color used for draw and
solid fill operations.
Also used for certain raster fills to set the
destination raster pixel to CTX_COLOR when the
source raster pixel is one.
.P
You can embed changes to the CTX_COLOR attribute
in the path using the Color() macro.
When a color change is encountered in a path during rendering,
it changes the CTX_COLOR attribute in the context.
.H 4 "RETURNED VALUE"
.P
COLOR *
.H 4 "SEE ALSO"
.P
Drawing Macro \- Color()
.br
Display_Raster
.br
Store_Raster
.br
CTX_FILL_STYLE
.H 4 "NAME"
.P
CTX_ERROR
.IX "CTX_ERROR"
.tm .CE U 3 "CTX_ERROR" \n(PN
.H 4 "DESCRIPTION"
.P
Number of last error that occurred that involved
the current context.
A non-zero number implies that an error has
occurred since the last inquiry of this value.
NULL means no error has occurred.
CTX_ERROR is reset to zero after being queried.
.P
If multiple errors occur between inquiry,
the first error is the one returned.
.P
.H 4 "RETURNED VALUE"
.P
CTX_error
.H 4 "SEE ALSO"
.P
Get_Error
.H 4 "NAME"
.P
CTX_FILL_ORG
.IX "CTX_FILL_ORG"
.tm .CE U 3 "CTX_FILL_ORG" \n(PN
.H 4 "DESCRIPTION"
.P
This attribute defines placement of the
CTX_FILL_RASTER relative to the origin of the
raster being filled.
Default is (0, 0).
Since fill rasters can wrap around,
this attribute provides a way to control how a
wrap-around maps into the destination raster of
the fill
.P
When picturing how fills work,
think of the tiles of the fill raster been laid
down inside the space of the destination raster,
filling the whole raster with many squares.
The first tile is laid down at destination
raster's origin plus the CTX_FILL_ORG.
Keep in mind, of course,
that these tiles are only visible where the
current path specifies an area to be drawn.
.P
.H 4 "RETURNED VALUE"
.P
POINT *
.H 4 "SEE ALSO"
.P
CTX_FILL_RASTER
.br
CTX_FILL_STYLE
.H 4 "NAME"
.P
CTX_FILL_RASTER
.IX "CTX_FILL_RASTER"
.tm .CE U 3 "CTX_FILL_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
Used as a texture or stipple mask for filling
areas when the CTX_FILL_STYLE is set to something
other than CTX_FILL_SOLID.
Think of it as laying out the fill raster pattern
inside the area being filled.
.P
The only supported source-to-depth raster fills
are 1:1, 1:4, and 4:4.
It is an error to use a fill and destination
raster combination that is not supported.
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO"
.P
CTX_FILL_STYLE
.br
CTX_FILL_ORG
.H 4 "NAME"
.P
CTX_FILL_STYLE
.IX "CTX_FILL_STYLE"
.tm .CE U 3 "CTX_FILL_STYLE" \n(PN
.H 4 "DESCRIPTION"
.P
Determines, in part, the pixel-by-pixel logical
operations that take place when an area is filled
or when one raster is copied into another using
Display_Raster.
The various fill styles provide a means for
creating stipples, textures,
or patterns in raster and the polygonal areas
drawn within rasters.
.P
When used through Display_Context and when the
fill style is not set to CTX_FILL_SOLID,
Shapes uses the CTX_FILL_RASTER as a source raster
for the filling.
In other words, the fill raster provides the
pattern or the texture for the fill area,
and the fill raster can wrap over and over again
within the polygon defined by the current path or geometry.
In contrast, when executing the Display_Raster operator,
which also pays attention to the fill style,
the source raster does not wrap around in the
destination raster,
and the raster is copied (or stippled) only once.
.P
These context attributes may determine how the fill occurs:
.br
CTX_COLOR
.br
CTX_BACK_COLOR
.br
CTX_PLANE_ENABLE  (effects destination raster only)
.br
CTX_FILL_RASTER (and its RAS_PLANE_ENABLE and RAS_DIM attributes)
.br
CTX_FILL_ORIGIN
.br
CTX_RASTER (often referred to as the destination raster)
.br
CTX_ROP
.br
.P
CTX_FILL_STYLE many have the following settings:

\f3CTX_FILL_SOLID\fP
.P
1- or 4-bit rasters are filled with the context's
current color, CTX_COLOR.
CTX_FILL_SOLID ignores CTX_PLANE_ENABLE in the 1-bit case.
.P
\f3CTX_FILL_STIPPLED\fP
.P
Stippling works only for 1-bit source rasters.
Each pixel in the fill raster is examined.
If the source pixel is a 1,
the corresponding pixel in the destination raster
is set to the current color.
If the source pixel is not set,
the corresponding pixel in the destination is unchanged.
Only those planes enabled by CTX_PLANE_ENABLE are
modified in the destination raster.
The destination raster is the CTX_RASTER
attribute of the current context.
.br
.br
.TB "Stippling Action"
.TS
box tab(/);
cf4I | cf4I
c | l.
Source Pixel/Action
=
1/CTX_COLOR to destination raster
_
0/Destination is unchanged
.TE
.TT
Dependent on:
.P
CTX_FILL_RASTER
.br
CTX_PLANE_ENABLE
.P
Ignores:
.P
RAS_PLANE_ENABLE
.P
\f3CTX_FILL_OPAQUE_STIPPLED\fP
.P
Enabled pixels are set to the current color.
Unenabled pixels are set to the background color.
Each pixel in the fill raster is examined.
If the source depth is greater than 1 and the source pixel is one,
the corresponding pixel in the destination raster
is set to the current color;
otherwise, it is set to the current background color.
.TB "Opaque Stipple Action"
.TS
box tab(/);
cf4I | cf4I | cf4I
c | c | lw(4.5i).
Source Depth/Source Pixel/Action
=
1/1/CTX_COLOR to destination raster
_
1/0/CTX_BACK_COLOR to destination raster
_
>1/non-zero/T{
CTX_COLOR to destination if the source is non-zero.
However, source raster's pixels are first ANDed
with the RAS_PLANE_ENABLE field.
X11 calls this operation a \f2copy plane\f1
when the source raster is greater than 1 bit deep
and has its RAS_PLANE_ENABLE attribute set with
only 1 plane enabled.
T}
_
>1/0/CTX_BACK_COLOR to destination
.TE
.TT
Dependent on:
.P
CTX_FILL_RASTER
.br
CTX_PLANE_ENABLE
.br
RAS_PLANE_ENABLE
.P
\f3CTX_FILL_TEXTURED\fP
.P
Source pattern and color are replicated in the
destination raster.
X11 calls this a \f2tiling\fP operation.
When invoked via a Display_Context call,
it differs from a raster copy via Display_Raster
in that it wraps the source raster in the
destination raster.
.P
In 1:4 bit copies, however,
the following holds:
.br
.TB "Texture Fill Action"
.TS
box tab(/);
cf4I | cf4I
c | l.
Source Pixel/Action
=
1/CTX_COLOR to destination
_
0/CTX_BACK_COLOR to destination
.TE
.TT

Dependent on:
.P
CTX_FILL_RASTER
.br
CTX_PLANE_ENABLE
.br

Ignores:
.P
RAS_PLANE_ENABLE
.H 4 "RETURNED VALUE"
.P
CTX_fill_style
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
CTX_LINE_CAP
.IX "CTX_LINE_CAP"
.tm .CE U 3 "CTX_LINE_CAP" \n(PN
.H 4 "DESCRIPTION"
.P
Defines the shape of the endpoints of a series of
vectors and curves.
Vectors and curves of line width 0
(1 pixel wide) ignore this attribute.
.P
The cap is a projection beyond the endpoint of the line.
The amount of the projection is dependent on line width.
.TB "LINE_CAP Types"
.TS
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Type/Description
=
CTX_CAP_BUTT/T{
Butt cap.
The line is squared off at the end with no projection.
This is the default.
T}
_
CTX_CAP_SQUARE/T{
Square ends.
The end of the line is extended a distance half
the line width.
T}
_
CTX_CAP_ROUND/T{
Rounded ends.
A semicircle with the diameter equal to the line
width is appended to the end of the line.
T}
_
CTX_CAP_NOTLAST/T{
Butt ends without drawing the last point.
Useful for creating smooth line joints.
T}
.TE
.TT
.FG "Line Caps"
.DS
.BP PSART/ps.line_cap
.EP
.DE
.H 4 "RETURNED VALUE"
.P
CTX_line_cap
.H 4 "SEE ALSO"
.P
CTX_LINE_SIZE
.br
CTX_MITER_LIMIT
.br
CTX_LINE_STYLE
.P
.H 4 "NAME"
.P
CTX_LINE_JOIN
.IX "CTX_LINE_JOIN"
.tm .CE U 3 "CTX_LINE_JOIN" \n(PN
.H 4 "DESCRIPTION"
.P
Defines the shape of joints between wide line
(line size greater than zero) and curve segments.
.P
The joint is projection beyond the two wide lines
that, mathematically, takes its point of
emanation from the intersection of the two wide
line's center-lines.
.TB "CTX_LINE_JOIN Types"
.TS
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Type/Description
=
CTX_JOIN_BEVEL/T{
Each line is fitted with a butt end cap.
The notch between the two end caps is filled in
with a triangle.
T}
_
CTX_JOIN_MITER/T{
Mitered corners created from the extending line
segments until the outside edges of each of the
wide lines intersect.
However, if the angle between the two wide lines is very acute,
the line join projection is truncated to a beveled join.
The attribute CTX_MITER_LIMIT controls when the
truncation occurs.
This is the default.
T}
_
CTX_JOIN_ROUND/T{
Rounded corners produced by an arc the diameter
of which equals the line width.
The center of the arc is at the point where the
two lines intersect
T}
.TE
.TT
.FG "Line Joins"
.DS
.BP PSART/ps.line_join
.EP
.DE
.H 4 "RETURNED VALUE"
.P
CTX_line_join
.H 4 "SEE ALSO"
.P
CTX_LINE_SIZE
.br
CTX_LINE_CAP
.br
CTX_MITER_LIMIT
.H 4 "NAME"
.P
CTX_LINE_PATTERN
.IX "CTX_LINE_PATTERN"
.tm .CE U 3 "CTX_LINE_PATTERN" \n(PN
.H 4 "DESCRIPTION"
.P
The pattern object used when rendering vectors or curves.
Used in conjunction with CTX_LINE_STYLE and is
used only when CTX_LINE_STYLE is dashed or
double-dashed.
The default is NULL for solid vectors or curves.
Patterns are specified via the pattern object as
an array of numbers specifying which coordinates
are on and off.
These off and on segments are measured in user coordinates,
not in pixels.
.P
The pattern wraps around over and over again
along curves and around corners until the end of
the line is reached.
.H 4 "RETURNED VALUE"
.P
PATTERN
.H 4 "SEE ALSO"
.P
CTX_LINE_STYLE
.br
Pattern Object
.H 4 "NAME"
.P
CTX_LINE_SIZE
.IX "CTX_LINE_SIZE"
.tm .CE U 3 "CTX_LINE_SIZE" \n(PN
.H 4 "DESCRIPTION"
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
Line or curve thickness, in user-coordinate units
.P
If the path construction transform is enabled,
the view transform matrix determines the line's
pixel-width on the raster.
Observe that if the view transform has different
x and y scaling factors,
the line or curve's width will be skewed.
Also keep in mind that the line size is a
parameter for the construction of line joins and caps.
.P
The default thickness is 0,
which produces 1-pixel wide vectors or curves.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
Line and curve thickness.
Thickness is measured in user-coordinate units
when the path construction transform is enabled,
and in pixels when the path render transform is enabled.
.P
If the path construction transform is enabled,
your view transform matrix determines the line's
pixel-width on the raster.
(Caution: The concatenation of your transforms
must be invertible for wide lines to work.)
Observe that if the view transform has different
x and y scaling factors,
the line or curve width will be skewed.
Also keep in mind that the line size is a
parameter for the construction of line joins and caps.
.P
The default thickness is 0,
which produces 1-pixel wide vectors or curves.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "RETURNED VALUE"
.P
float
.H 4 "SEE ALSO"
.P
CTX_LINE_CAP
.br
CTX_LINE_JOIN
.br
CTX_MITER_LIMIT
.H 4 "NAME"
.P
CTX_LINE_STYLE
.IX "CTX_LINE_STYLE"
.tm .CE U 3 "CTX_LINE_STYLE" \n(PN
.H 4 "DESCRIPTION"
.P
The line-style that defines which sections of a
line or curve are drawn.
.TB "CTX_LINE_STYLE Types"
.TS
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Type/Description
=
CTX_LINE_DASHED/On-off dashed line
_
CTX_LINE_DOUBLE_DASHED/T{
Double dashed line with odd dashes filled with
CTX_COLOR and even dashes filled with CTX_BACK_COLOR.
T}
_
CTX_LINE_SOLID/Solid line.
This is the default.
.TE
.TT
.P
If a dashed or double-dashed line is specified,
then CTX_LINE_PATTERN specifies the line pattern.
.H 4 "RETURNED VALUE"
.P
CTX_line_style
.H 4 "SEE ALSO"
.P
CTX_LINE_PATTERN
.H 4 "NAME"
.P
CTX_MITER_LIMIT
.IX "CTX_MITER_LIMIT"
.tm .CE U 3 "CTX_MITER_LIMIT" \n(PN
.H 4 "DESCRIPTION"
.P
Sets the limit that determines the treatment of
mitered corners.
The limit must be greater than zero.
The miter length is the distance between the
inside intersection of the two wide lines and the
outside intersection.
If the ratio of the miter length to the line
width exceeds the miter limit,
the lines will receive a beveled line join.
The default miter limit is 10.
.P
To understand why the miter limit is necessary,
imagine two wide lines that are not parallel and
that should end with a miter join.
The miter join would, if not constrained by the miter limit,
shoot off the past the intersection of the two
lines and dwarf the length of the two lines it
was supposed to be joining.
.H 4 "RETURNED VALUE"
.P
Float
.H 4 "SEE ALSO"
.P
CTX_LINE_JOIN
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_MODEL_TRANSFORM
.IX "CTX_MODEL_TRANSFORM"
.tm .CE U 3 "CTX_MODEL_TRANSFORM" \n(PN
.H 4 "DESCRIPTION"
.P
The model transform matrix.
In order to force creation of the transform
object associated with this attribute,
you must enable CTX_APPLY_MODEL via the CTX_PIPELINE attribute.
Once created, you may query this attribute to
obtain a handle to the model transform.
You can change the model transform by passing
this handle to the transform operators
.P
The model transform is intended for mapping from
a local coordinate space into a world coordinate space.
You may define the local coordinate space as
the coordinate system that most naturally defines
the object you are trying to represent with the path.
For example, the most natural coordinate system
for a circle is to have its center at (0,0).
You use the model transformation to place the
path containing the circle in its proper position
in the world,
which in many scenarios would not be at (0,0).
See the section on CTX_VIEW_TRANSFORM for more
detail about world coordinates.
.P
.H 4 "RETURNED VALUE"
.P
TRANSFORM
.H 4 "SEE ALSO"
.P
CTX_CLIP_DIM
.br
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_PIPELINE
.br
CTX_VDC_MAP
.br
CTX_VDC_TRANSFORM
.br
CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "NAME"
.P
CTX_PATH
.IX "CTX_PATH"
.tm .CE U 3 "CTX_PATH" \n(PN
.H 4 "DESCRIPTION"
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
Specifies the current path.
The path is the store for the current geometry.
.P
When a context is created,
a default path is also created whose handle you
can query with Get_Context.
You can use all path operators on the path
referred to by this handle.
.P
If you set this attribute to NULL,
the path is created for you.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
Specifies the current path.
The current path stores the succession of pen moves.
To re-render the same sequence of pen moves,
just re-issue the Display_Context command.
The binding between the pen moves in the
path and the context attributes occurs when the Display_Context
operator is issued.
To reset the path to having no pen moves,
use the Clear_Path operator.
.P
When the path is set to null
(which is the default),
PATH_IMMEDIATE path is automatically created.
In such a case, Shapes is in \f2immediate mode.\fP
In immediate mode, all drawing primitives
(e.g., Draw_F2D) act as if they drawn at the
moment the primitive is issued.
The binding between the pen and the context
occurs when the drawing primitive is issued.
Furthermore, the drawing primitives are discarded
after they are drawn and do not accumulate in the path object.
Because certain Shapes implementations buffer graphics primitives,
the moment when immediate mode data makes it onto
the screen is hardware-dependent;
to ensure display,
issue a Display_Context command.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "RETURNED VALUE"
.P
PATH
.H 4 "SEE ALSO"
.P
PATH Operators and Attributes
.br
Display_Context
.br
CTX_PATH_PEN
.br
Draw_Xxx
.H 4 "NAME"
.P
CTX_PATH_PEN
.IX "CTX_PATH_PEN"
.tm .CE U 3 "CTX_PATH_PEN" \n(PN
.H 4 "DESCRIPTION"
.P
Last coordinate added to the path in user space.
This attribute can only be queried.
When you ask for this value,
Shapes examines the end of the path to see if it
can reduce consecutive move operations to a
single move before returning the last coordinate
in the path.
If the structure of your application causes the
creation of many consecutive move operations,
you may be able to speed up path rendering
performance by first querying this attribute.
The default for queries is (0,0).
.H 4 "RETURNED VALUE"
.P
POINT *
.P
The point returned may describe points that are
floats (PT_FLT2D) or fracts (PT_BIN2D).
The point types, however,
will always be absolute
(e.g., PT_LINE_F2D,
but never PT_LINEREL_F2D).
.H 4 "SEE ALSO"
.P
CTX_PATH
.H 4 "NAME"
.P
CTX_PATH_RASTER_PEN
.IX "CTX_PATH_RASTER_PEN"
.tm .CE U 3 "CTX_PATH_RASTER_PEN" \n(PN
.H 4 "DESCRIPTION"
.P
When queried, this attribute setting represents
the last coordinate added to the path in raster space.
.P
This attribute may be set to add a point to the
path that is not subject to any transformations.
This also affects the value of CTX_PATH_PEN.
The default for inquiries is (0,0).
.H 4 "RETURNED VALUE"
.P
POINT_B2D *
.P
The point returned is always an absolute fract coordinate.
The point types, however,
will always be absolute
(e.g., PT_LINE_B2D,
but never PT_LINEREL_B2D).
.H 4 "SEE ALSO"
.P
CTX_PATH_PEN
.H 4 "NAME"
.P
CTX_PEN
.IX "CTX_PEN"
.tm .CE U 3 "CTX_PEN" \n(PN
.H 4 "DESCRIPTION"
.P
When queried, this attribute returns the position of
the last point rendered in model space.
The default is (0,0).
.P
When set, it represents the point where rendering begins.
It also changes the value of CTX_RASTER_PEN
by applying the rendering transformation to CTX_PEN.
Thus, you may use CTX_PEN to set the starting
point of a Display_Raster command.
.P
Bear in mind that a point is not rendered with
certainty until a Display_Context is posted with at
least CTX_FLUSH or CTX_RENDER_FLUSH.
The CTX_PEN is only updated after a point is rendered.
.H 4 "RETURNED VALUE"
.P
POINT *
.P
This attribute returns an arbitrary point that
may be absolute or relative, fract or float.
.H 4 "SEE ALSO"
.P
CTX_RASTER_PEN
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_PIPELINE
.IX "CTX_PIPELINE"
.tm .CE U 3 "CTX_PIPELINE" \n(PN
.H 4 "DESCRIPTION"
.P
Determines whether a transform is used during
path construction.
The transforms\ selected by CTX_PIPELINE is
applied to each point in the path before it is
stored in the path structure.
.P
To enable the coordinate transform,
choose CTX_APPLY_VIEW.
To disable the transform, choose NULL.
.H 4 "RETURNED VALUE"
.P
CTX_pipeline
.H 4 "SEE ALSO"
.P
CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_PIPELINE
.IX "CTX_PIPELINE"
.tm .CE U 3 "CTX_PIPELINE" \n(PN
.H 4 "DESCRIPTION"
.P
Determines the transforms used for the viewing pipeline,
whether clipping is enabled,
and the time of application for transforms.
Do this by ORing together enumerations that deal
with each of the three categories.
.P
You may selectively enable none, all,
or any combination of the path transforms.
.P
CTX_APPLY_VIEW \- Enable the viewing transform.
.br
CTX_APPLY_MODEL \- Enable the modeling transform.
.br
CTX_APPLY_VDC \- Enable the VDC transform.
.P
When enabling a transform,
you must also select whether that transform is
to be applied at the time of path construction or
when the path is rendered.
Transforms applied at path construction transform
the point of the path before they are stored into
the path structure.
Transform applied at path rendering do not alter
the path but transform the path points as part of
the viewing pipeline.
If left unspecified,
Shapes defaults to the path construction transforms.
.P
CTX_APPLY_RENDER  \- Apply the path transforms at
path render time.
.br
CTX_APPLY_CONSTRUCT \- Apply the path transforms
at path construct time.
.P
Finally, if you have enabled CTX_APPLY_RENDER,
you also have the option of enabling view clipping.
Do this by ORing the enumeration CTX_APPLY_CLIP
as well.
.P
CTX_APPLY_CLIP \- Apply view clipping at the time
of path rendering.
Be sure to enable clipping planes with the
CTX_CLIP_PLANES attribute,
which defaults to CTX_CLIP_NONE,
or no clipping will occur.
.P
.H 4 "EXAMPLE"
.SS
/*
 * Apply view transform, clip, then apply the vdc transform at
 * the time of path rendering
 */
Set_Context(ctx, CTX_PIPELINE, CTX_APPLY_CLIP | CTX_APPLY_RENDER |
		CTX_APPLY_VIEW | CTX_APPLY_VDC);
.ft1
.SE
.H 4 "RETURNED VALUE"
.P
CTX_pipeline
.H 4 "SEE ALSO"
.P
CTX_CLIP_DIM
.br
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_MODEL_TRANSFORM
.br
CTX_VIEW_TRANSFOR
.br
 CTX_VDC_TRANSFORM
.br
CTX_PIPELINES
.br
CTX_VDC_MAP
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "NAME"
.P
CTX_PLANE_ENABLE
.IX "CTX_PLANE_ENABLE"
.tm .CE U 3 "CTX_PLANE_ENABLE" \n(PN
.H 4 "DESCRIPTION"
.P
The CTX_PLANE_ENABLE attribute determines the
planes of the display surface to which access is
allowed during drawing operations.
It is used as a bit mask on the display pixels,
determining which bits of the pixel are modified.
Each bit of the display pixel can be constructed
as a separate plane.
.P
For each bit of the plane enable,
a 1 allows the bit to be written to and a 0
protects the bit.
Plane enable is only sensible for the numbers
that are less than the size of your color map.
For example, if you have a color map of four,
use plane enables for 0, 1, 2, or 3 but not for 5.
In this case, setting the plane enable to 5 will
yield unpredictable results.
.FG "Plane Enable"
.DS
.BP PSART/ps.pl_enable
.EP
.DE
.H 4 "RETURNED VALUE"
.P
CTX_plane_enable
.H 4 "SEE ALSO"
.P
CTX_FILL_STYLE,
.br
Display_Raster
.H 4 "NAME"
.P
CTX_RASTER
.IX "CTX_RASTER"
.tm .CE U 3 "CTX_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the raster associated with the context.
This raster defines the drawing surface for the
Display_Context operator.
.P
There is no restriction on switching this
attribute back and forth between rasters running
in memory or on varying devices.
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO
.P
Create_Raster
.br
Create_Context
.H 4 "NAME"
.P
CTX_RASTER_PEN
.IX "CTX_RASTER_PEN"
.tm .CE U 3 "CTX_RASTER_PEN" \n(PN
.H 4 "DESCRIPTION"
.P
When queried, this attribute represents the
coordinates of the last point rendered in
the raster space.
The default is (0, 0, 0).
.P
For paths with area and no geometry,
it is the first vertex of the area that is not
necessarily the last pixel rendered.
.P
When you set this attribute,
it moves the position of the drawing pen in
raster space.
As with CTX_PEN, this facilitates Display_Raster.
It also affects CTX_PEN;
CTX_PEN is set to the same value as CTX_RASTER_PEN.
.FG "Raster Space"
.DS
.sp 3v
.BP PSART/ps.rstr_spc
.EP
.DE
.H 4 "RETURNED VALUE"
.P
POINT *
.P
The returned point is the absolute fract
coordinates of the pen position in the raster
coordinate system.
.H 4 "SEE ALSO"
.P
CTX_RASTER_PEN
.H 4 "NAME"
.P
CTX_ROP
.IX "CTX_ROP"
.tm .CE U 3 "CTX_ROP" \n(PN
.H 4 "DESCRIPTION"
.P
The CTX_ROP attribute defines the raster
operation for the context.
Graphics primitives are to be rendered using this
raster operation to combine the source and destination.
.P
Bear in mind that a point is not rendered with
certainty until a Display_Context is posted with at
least CTX_FLUSH or CTX_RENDER_FLUSH.
The CTX_PEN is only updated after a point is
rendered.
.br
.TB "CTX_ROP Values"
.TS H
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Value/Description
=
.TH
CTX_ROP_AND/\AND source and destination
_
CTX_ROP_CLEAR/Clear destination
_
CTX_ROP_DRAW/Copy source to destination
_
CTX_ROP_DRAW_INVERTED/T{
Copy 1's complement of the source to destination
T}
_
CTX_ROP_EQUIVALENT/T{
For each bit in source and destination that are equivalent,
set the bit in the destination.
For those that are not equivalent,
clear the destination.
T}
_
CTX_ROP_ERASE/T{
For each bit set in the source,
erase destination.
T}
_
CTX_ROP_ERASE_REVERSED/T{
For each bit set in the destination,
clear the source and write the source to the
destination
T}
_
CTX_ROP_INVERT/1's complement of the destination
_
CTX_ROP_NAND/NAND source with destination
_
CTX_ROP_NO_OP/Do nothing
_
CTX_ROP_NOR/NOR source with destination
_
CTX_ROP_PAINT/OR source with destination
_
CTX_ROP_PAINT_INVERTED/T{
OR the destination with the 1's complement of the source
T}
_
CTX_ROP_PAINT_REVERSED/T{
Replace the destination with the or of the source
and the 1's complement of the destination
T}
_
CTX_ROP_SET/Set destination
_
CTX_ROP_XOR/Exclusive OR source with destination
.TE
.TT
.H 4 "RETURNED VALUE"
.P
CTX_rop
.H 4 "SEE ALSO"
.P
Display_Raster
.br
Display_Context
.H 4 "NAME"
.P
CTX_SHADE
.IX "CTX_SHADE"
.tm .CE U 3 "CTX_SHADE" \n(PN
.H 4 "DESCRIPTION"
.P
If CTX_SHADE_OFF is set,
the path is rendered as a series of vector outlines,
and additional vectors that close areas
are added where needed.
The close operation can either be an explicit close,
or an implicit one through a move or an attribute change,
depending on CTX_AREA_STYLE.
.P
CTX_SHADE_SOLID causes moves and draws to define
an area according to the particular fill rule.
.FG "CTX_SHADE"
.DS
.BP PSART/ps.shade
.EP
.DE
.H 4 "RETURNED VALUE"
.P
CTX_shade
.H 4 "SEE ALSO"
.P
CTX_AREA_STYLE
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_VDC_MAP
.IX "CTX_VDC_MAP"
.tm .CE U 3 "CTX_VDC_MAP" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies how to map the clip area onto the raster.
Depending on its setting CTX_VDC_MAP will either
take control of the VDC transform or relinquish
control of it to the programmer.
Certain of the VDC remappings also change the
contents of the clipping area attributes,
CTX_CLIP_ORG, CTX_CLIP_DIM.
The VDC mappings are only operative if the VDC
transform has been enabled.
.P
Applications need control over the VDC transform
without knowing the actual dimensions of the
raster because the raster dimensions are
controlled by the user of the window system and
can change at any time.
The CTX_VDC_MAP attribute provides enumerations
that remap automatically the clipping area onto
the raster when the raster changes size or aspect ratio.
.P
For mappings where Shapes changes the VDC
transform to a non-identity transform,
you must enable the VDC transform via the
CTX_PIPELINE attribute for the expected VDC
mapping to occur.
For mappings where Shapes changes the clipping
area parameters,
you must enable clipping via the
CTX_PIPELINE attribute for view clipping to take
place.
.P
.P
CTX_MAP_OFF \- The programmer specifies the VDC
mapping by manipulating the CTX_VDC_TRANSFORM object.
Shapes alters neither the clipping area nor the
VDC transform.
This is the default.
.P
CTX_MAP_ALL \- Shapes scales the VDC transform in
X and Y so that the clipping area maps exactly
onto the raster.
The origin of the clipping area,
CTX_CLIP_ORG maps into the center point of the raster.
.P
CTX_MAP_ASPECT \- Like CTX_MAP_ALL, except that
the aspect ratio established by the clipping area
is preserved when project onto the raster.
Shapes scales the VDC transform in either X and Y
so that for the lesser dimension of the raster,
the clip area maps exactly onto the raster.
The greater dimension of the raster
(in either x or y) use the same VDC scaling
factor as the lesser.
Finally, the VDC transform has a translation
factor such that the clipping area origin maps
into the center of the raster.
.P
CTX_MAP_RASTER \- If enabled,
sets the VDC transform to identity,
and the clipping region to:
.br
CLIP_ORG =(RAS_DIM.x/2.0,  RAS_DIM.y/2.0)
.br
CLIP_DIM =(RAS_DIM.x/2.0, - RAS_DIM.y/2.0)
.br
In words, this puts the upper-left corner of the
clip region at the upper-left corner of the raster,
(0,0), and the lower-right corner of the clip
region at the lower-right corner of the raster,
(RAS_DIM.x, RAS_DIM.y).
.H 4 "RETURNED VALUE"
.P
CTX_vdc_map
.H 4 "SEE ALSO"
.P
CTX_CLIP_DIM
.br
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_PIPELINE
.br
CTX_MODEL_TRANSFORM
.br
CTX_VIEW_TRANSFORM
.br
CTX_VDC_TRANSFORM
.br \}
.\"  ENDIF Paint-----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
CTX_VDC_TRANSFORM
.IX "CTX_VDC_TRANSFORM"
.tm .CE U 3 "CTX_VDC_TRANSFORM" \n(PN
.H 4 "DESCRIPTION"
.P
The VDC transform matrix.
In order to force creation of the transform
object associated with this attribute,
you must enable CTX_APPLY_VDC via the
CTX_PIPELINE attribute.
Once created, you may query this attribute to
obtain a handle to the VDC transform.
Pass this handle to transform operators
in order to change the VDC transform.
.P
The VDC transform is intended for mapping from
the virtual coordinate space to the raster.
The virtual coordinate space is defined by clipping area
(see CTX_VIEW_TRANSFORM).
Raster coordinates are defined by the pixel width
and height of the raster.
.P
The easiest way to program this transform is to
let Shapes handle it.
This is especially convenient since the raster is
typically a window that the user can resize.
Read about CTX_VDC_MAP to adopt this approach.
If any of the VDC mappings other than CTX_MAP_OFF
are enabled,
it is an error to alter the VDC transform.
.P
If you wish to program the VDC transform yourself,
you will need to define a mapping from the
clipping area to the raster coordinates.
This transformation may only include translations
and scaling factors.
Rotations in the VDC transform are ignored.
.P
If the the VDC transform is identity or unenabled,
for example, it will just map the clip area
through into raster coordinates.
.H 4 "RETURNED VALUE"
.P
TRANSFORM
.H 4 "SEE ALSO"
.P
CTX_CLIP_DIM
.br
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_PIPELINE
.br
CTX_VDC_MAP
.br
CTX_MODEL_TRANSFORM, CTX_VIEW_TRANSFORM
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "NAME"
.P
CTX_VIEW_TRANSFORM
.IX "CTX_VIEW_TRANSFORM"
.tm .CE U 3 "CTX_VIEW_TRANSFORM" \n(PN
.H 4 "DESCRIPTION"
.P
The viewing transform matrix.
In order to force creation of the transform
object associated with this attribute,
you must enable CTX_APPLY_VIEW via the
CTX_PIPELINE attribute.
Once created, you may query this attribute to
obtain a handle to the viewing transform.
Then you can pass this handle to transform
operators in order to change the viewing transform.
.P
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
The view transform is intended for mapping from a
world coordinate space into a virtual device
coordinate space.
Define the world coordinate space as the
coordinate system that most naturally defines the
viewing world.
You can also think of it as the coordinate system
that exists after the model transformation and
prior to the viewing transformation.
.P
Virtual device coordinates are defined as the
coordinate system where view clipping occurs.
The clipping area is centered at the CTX_CLIP_ORG
and has dimensions defined by CTX_CLIP_DIM.
If you enable clipping,
the viewing pipeline will transform primitives by
the viewing transform,
and then clip away and discard all portions of
primitives that lie outside the viewing area.
.P
If primitives have only two-dimensional
information and require view clipping,
the viewing transformation should map the
rectangle in the world space that you wish to
expose to the rectangle in virtual device
coordinates centered at CTX_CLIP_ORG and having a
dimension CTX_CLIP_DIM.
.P
For ideas on how to map from virtual device
coordinates into the raster,
read about CTX_VDC_MAP and CTX_VDC_TRANSFORM.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "RETURNED VALUE"
.P
TRANSFORM
.H 4 "SEE ALSO"
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.P
CTX_CLIP_DIM
.br
CTX_CLIP_ORG
.br
CTX_CLIP_PLANES
.br
CTX_MODEL_TRANSFORM
.br
CTX_VDC_TRANSFORM
.br
CTX_PIPELINE
.br
CTX_VDC_MAP
.br \}
.\"  ENDIF Paint-----------------------------------------------
.TB "Context Attribute Default Settings"
.TS H
box tab(/);
cf4I | cf4I | cf4I
l | l | l.
Attribute/Default Condition/Description
=
.TH
CTX_AREA_STYLE/CTX_CLOSE_OFF/Area closure and fill behavior:
/CTX_FILL_NONZERO/CTX_CLOSE_OFF
//CTX_CLOSE_MOVE
//CTX_FILL_NONZERO
//CTX_FILL_EVENODD
_
CTX_BACK_COLOR/Black/Background color for clear operations
_
CTX_CLIP_PATH/None/Current clipping path
_
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
CTX_CLIP_DIM/(1,1)/Clip area dimensions
_
CTX_CLIP_ORG/(0,0)/Clip area origin
_
CTX_CLIP_PLANES/None/Clip planes
_
.br \}
.\"  ENDIF Paint------------------------------------------------
CTX_COLOR/White/Current color
_
CTX_FILL_ORG/(0,0)/For area texturing,
//Stippling raster reference origin
_
CTX_FILL_STYLE/CTX_FILL_SOLID/Area fill style:
//CTX_FILL_SOLID
//CTX_FILL_TEXTURED
//CTX_FILL_OPAQUE_STIPPLED
//CTX_FILL_STIPPLED
_
CTX_LINE_CAP/CTX_CAP_BUTT/Line cap:
//CTX_CAP_BUTT
//CTX_CAP_ROUND
//CTX_CAP_SQUARE
//CTX_CAP_NOTLAST
_
CTX_LINE_JOIN/CTX_JOIN_MITER/Line join:
//CTX_JOIN_MITER
//CTX_JOIN_ROUND
//CTX_JOIN_BEVEL
_
CTX_LINE_PATTERN/Solid/Current line pattern
_
CTX_LINE_SIZE/0 (thin line)/Line width
_
CTX_LINE_STYLE/CTX_LINE_SOLID/Current line style:
//CTX_LINE_SOLID
//CTX_LINE_DASHED
//CTX_LINE_DOUBLE_DASHED
_
CTX_MITER_LIMIT/10/Miter join limit.
_
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
CTX_MODEL_TRANSFORM/Identity/T{
Model transformation matrix
T}
_
.br \}
.\"  ENDIF Paint------------------------------------------------
CTX_PATH/None/Current path
_
CTX_PATH_PEN/(0,0)/T{
Untransformed coordinate of last point in path
T}
_
CTX_PATH_RASTER_PEN/(0,0)/T{
Coordinate of last point in path in raster space
T}
_
CTX_PEN/(0,0)/Last point rendered in user coordinate
_
CTX_PIPELINE/0/Viewing pipeline configuration:
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
//CTX_APPLY_MODEL
//CTX_APPLY_VIEW
//CTX_APPLY_VDC
//CTX_APPLY_CLIP
//CTX_APPLY_CONSTRUCT
//CTX_APPLY_RENDER
_
.br \}
.\" ENDIF PAINT
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
//CTX_APPLY_CONSTRUCT
//CTX_APPLY_VIEW
_
.br \}
.\"  ENDIF SHAPES------------------------------------------------
CTX_PLANE_ENABLE/void/T{
Specifies which planes are accessible.
T}
_
CTX_RASTER/void/Raster associated with the context
_
CTX_RASTER_PEN/(0,0)/Last point rendered in raster coordinate
_
CTX_ROP/CTX_ROP_DRAW/Raster operators:
//CTX_ROP_AND
//CTX_ROP_CLEAR
//CTX_ROP_DRAW
//CTX_ROP_DRAW_INVERTED
//CTX_ROP_EQUIVALENT
//CTX_ROP_ERASE
//CTX_ROP_ERASE_REVERSED
//CTX_ROP_INVERT
//CTX_ROP_NAND
//CTX_ROP_NOR
//CTX_ROP_NO_OP
//CTX_ROP_PAINT
//CTX_ROP_PAINT_INVERTED
//CTX_ROP_PAINT_REVERSED
//CTX_ROP_SET
//CTX_ROP_XOR
_
CTX_SHADE/CTX_SHADE_OFF/Shading model
//CTX_SHADE_OFF
//CTX_SHADE_SOLID
_
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
CTX_VDC_MAP/CTX_MAP_RASTER/T{
VDC mapping characteristics:
T}
//CTX_MAP_OFF
//CTX_MAP_ALL
//CTX_MAP_ASPECT
//CTX_MAP_RASTER
_
CTX_VDC_TRANSFORM/Identity/T{
VDC transformation matrix
T}
_
.br \}
.\"  ENDIF Paint------------------------------------------------
CTX_VIEW_TRANSFORM/Identity/T{
View transformation matrix
T}
.TE
.TT
