'\"!  eqn | tbl | mmdoc
'\"macro stdmacro
.if n .pH ref.raster @(#)raster	40.1 of 11/1/89

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 raster
..
.SO mstr.hdr
.ds Lb Shapes
.BK "Shapes Reference Manual"
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.EQ
delim $$
.EN
.CH "Raster Object" "14"
.H 1 "Raster Object"
.H 2 "Introduction"
.P
.IX "raster"
.nh
A raster is an area on which images are drawn.
The raster may be an area in memory or a region
of a display device.
A single raster may have one or more contexts
associated with it.
.P
Rasters have the following characteristics:
.BL
.LI
Clip path
.LI
Pixel data read back
.LI
Redefinable origin and dimensions
.LI
Display color map rendering
.LE
.P
The following raster attributes can be changed
with Set_Raster and queried with Get_Raster:
.BL
.LI
Dimensions of the image rectangle \- width,
height and depth (bits-per-sample)
.LI
Mapping of the image color or gray scale to the
apparent color or gray scale of the output device
.LI
Clipping path defining the available part of the raster
.LE
.H 4 "NAME"
.P
Create_Raster \- Creates a raster of the specified type.
.IX "Create_Raster"
.tm .CE U 3 "Create_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Raster\f2(type, root)\f1
.br
RAS_type type;
.br
char *root;
.br
RASTER root;
.H 4 "DESCRIPTION"
.P
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
Creates a drawing surface that is accessible
through raster operators.
You can draw into the raster through the Display_Context,
Display_Path, Display_Raster, and Poly_Glyph operators.
.br \}
.\"  ENDIF SHAPES------------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
Creates a drawing surface that is accessible
through raster operators.
You can draw into the raster through the Display_Context,
Display_Path, and Display_Raster operators.
.br \}
.\"  ENDIF Paint------------------------------------------------
.P
The newly-created raster object has a reference
count of one.
To remove the resources associated with this object,
it must be explicitly destroyed.
When a raster is created,
a color map object, RAS_CMAP,
is associated with it.
.P
A memory raster object renders directly into a
rectangular area of memory rather than to a
display device.
.P
\f2type\f1
Specifies the type of raster.
The table below describes the raster types:
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.TB "Raster Types"
.TS
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Type/Description
=
RAS_SCREEN/T{
Rectangular raster with the origin at 0,0 and
pixel dimensions of the full screen.
RAS_DEPTH reflects the depth of the device;
RAS_ORG is (0,0),
and RAS_DIM represents the width and height of
the screen.
The root argument to Create_Raster() specifies
the screen device as a character string.
T}
_
RAS_MEMORY/T{
Raster pixel data in memory and not visible on
the screen.
You must set RAS_DEPTH and RAS_DIM
(in that order) after creating the raster.
The root is ignored.
T}
_
RAS_CHILD /T{
Raster pixel data on the same device and, generally,
the same area as that of the parent raster.
X11/NeWS uses child rasters as individual window canvases.
RAS_ORG specifies the child's position on the parent raster.
RAS_DIM specifies the pixel dimensions of the rectangle.
The root argument specifies the object ID of the parent raster,
which cannot be RAS_CHILD.
T}
.TE
.TT
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.TS
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Type/Description
=
RAS_MEMORY/T{
Raster pixel data in memory and not visible on
the screen.
You must set RAS_DEPTH and RAS_DIM
(in that order) after creating the raster.
The root is ignored.
T}
_
RAS_SUNWINDOWS /T{
Raster is a canvas under SunWindows.
The root provides a pointer to the pixwin structure,
which defines the boundaries of the raster.
RAS_DEPTH reflects the depth of the screen device;
RAS_ORG is (0,0),
and RAS_DIM reflects the width and height of the window.
RAS_DIM is updated when the user resizes the window.
T}
.TE
.br \}
.\"  ENDIF Paint-----------------------------------------------
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
Generally, a child raster occupies some or all of
the same image memory associated with its parent;
operations on its image memory will also affect
the image memory of all ancestors.
The coordinates of a child raster need not lie
within the boundaries of its parent raster,
but the memory must be within the parent's memory
bounds.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.P
\f2root\f1
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.TB "Root Types"
.TS
box tab(@);
cf4I | cf4I | cf4I
l | l | l.
Type@Type@Description
=
Screen rasters@char *@T{
Device name,
such as
.PC "/dev/cgtwo0"
used with VGA.
T}
_
Memory rasters@NULL@T{
Used with VGA.
T}
_
Child rasters@RASTER@T{
Handle to existing object.
T}
.TE
.TT
.br \}
.\"  ENDIF SHAPES----------------------------------------------

.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.TS
box tab(?);
cf4I | cf4I | cf4I
l | l | l.
Type?Type?Description
=
SunWindows rasters?struct pixwin *?T{
Pointer the a pixwin canvas where the raster will exist.
T}
_
Memory rasters?Null
.TE
.br \}
.\"  ENDIF Paint-----------------------------------------------
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
With X11/NeWS you may create a memory raster with
root RAS_PRIVATEDATA,
so that the software layer,
rather than Shapes,
takes responsibility for the allocation and
destruction of raster memory.
You must set the internal variable RAS_DATA to
indicate the location of raster memory.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO"
.P
Create_Cmap
.br
CMAP Object
.br
RAS_CMAP
.br
Destroy_Raster
.br
RAS_DEPTH
.br
RAS_DIM
.H 4 "NAME"
.P
Destroy_Raster \- Destroys the specified raster
and frees its resources if no other object
references it.
.IX "Destroy_Raster"
.tm .CE U 3 "Destroy_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Raster\f2(raster)\f1
.br
RASTER raster;
.H 4 "DESCRIPTION"
.P
Destroys the specified raster and frees its
resources if no other object references it.
If another object references the raster,
its resources are not freed until all references
are removed.
.P
\f2raster\f1
Specifies the raster to be destroyed.
It is an error to reference a raster handle after
it has been destroyed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Create_Raster
.br
Temp_Raster
.br
Destroy_Obj
.H 4 "NAME"
.P
Display_Raster \- Displays the raster using the
attributes of the specified context.
.IX "Display_Raster"
.tm .CE U 3 "Display_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Display_Raster\f2(raster, ctx, src_clip_path)\f1
.br
RASTER raster;
.br
CTX ctx;
.br
PATH src_clip_path;
.H 4 "DESCRIPTION"
.P
Copies the specified raster into the specified
context's raster using the attributes of the
context.
If neither raster has a non-zero raster origin,
the upper-left corner of the source raster is
placed at the current pen position within the
destination context,
and the entire raster is copied over,
subject to the destination's clip path and the
source clip path parameter.
No viewing transformations apply.
.P
If either or both rasters have raster origins,
the following formula designates the destination
of the upper-left corner of the source raster:

CTX_RASTER_PEN + dstras.RAS_ORG \(mi srcras.RAS_ORG = Destination Origin
.P
If the destination raster is a child raster,
the above formula provides the location in the
destination raster's parent raster.
.P
The destination raster's clip area is limited to
the intersection between the context's clip path
and the destination raster's clip path.
A source clip may also apply
(see path argument below).
.P
The following rendering attributes affect Display_Raster:
.sp
CTX_ROP
.br
CTX_PLANE_ENABLE
.br
CTX_FILL_STYLE
.br
CTX_CLIP_PATH
.br
RAS_CLIP_PATH
.br
RAS_PLANE_ENABLE
.br
RAS_ORG
.br
RAS_DIM
.P
Copying between the various raster depth
combinations is described in the following table:
.P
.TB "Raster Depth Mapping"
.TS H
box tab(/);
cf4I | cf4I
c | lw(4.5i).
Raster Depth/Copy Operation
=
.TH
1:1 /T{
The source is copied directly into the
destination unless CTX_FILL_STYLE is set to opaque stippled.
In this case,
source 1 produces CTX_COLOR and
source 0 produces CTX_BACK_COLOR.
T}
_
1:4 /T{
If any source pixel is 1,
CTX_COLOR is copied in the destination raster.
If any source pixel is 0,
CTX_BACK_COLOR is copied in the destination pixel.
T}
_
4:4 /T{
Direct copy from source to destination.
T}
_
.TE
.TT
.P
Other source and destination raster depth copies
are not supported and will return an error.
.P
\f2raster\f1
Specifies the source raster for the copy.
.P
\f2ctx\f1
Specifies destination raster of the copy,
as well as the raster operation,
pen position, the plane enable,
and a clip path.
.P
\f2src_clip_path\f1
Specifies a clip path in source raster coordinates.
This argument is useful for limiting access to
the source raster when the origin of a child
raster may have placed the raster in a region
that does not exist.
If path is null,
Display_Raster clips to the bounding box of the
source raster.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_RASTER_PEN
.br
CTX_CLIP_PATH
.br
RAS_CLIP_PATH
.br
CTX_ROP
.br
CTX_PLANE_ENABLE
.br
Store_Raster
.H 4 "NAME"
.P
Get_Raster \- Returns the setting of the
specified raster attribute.
.IX "Get_Raster"
.tm .CE U 3 "Get_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Get_Raster\f2(raster, attr)\f1
.br
RASTER raster;
.br
RAS_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the setting of the specified raster
attribute.
.P
\f2raster\f1
Specifies the raster from which the attribute
setting is to be returned.
.P
\f2attr\f1
Specifies the attribute from which the setting is
to be returned.
.H 4 "RETURNED VALUE"
.P
Attribute setting
.H 4 "SEE ALSO"
.P
Set_Raster
.H 4 "NAME"
.P
Read_Raster \- Transfers image data from a raster
into an application program data area.
.IX "Read_Raster"
.tm .CE U 3 "Read_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Read_Raster\f2(raster, data, format)\f1
.br
RASTER raster;
.br
char *data;
.br
int format;
.H 4 "DESCRIPTION"
.P
Transfers image data from a raster into an
application program data area.
The arguments are interpreted in the same way as
Write_Raster.
No programmer-specified ROPS or plane enables apply.
.P
\f2raster\f1
Source raster for the copy.
.P
\f2format\f1
Specifies depth and alignment of the user data.
.TB "Format Arguments"
.TS
box, tab(/);
cf4I | cf4I
l | l.
Type/Description
=
RAS_ALIGN_8/Data has 8-bit alignment
RAS_ALIGN_16/Data has 16-bit alignment
RAS_ALIGN_32/Data has 32-bit alignment
RAS_DEPTH_1/Data is 1-bit per pixel
RAS_DEPTH_8/Data is 1-byte per pixel
RAS_DEPTH_4/Data is 4 bits per pixel
.TE
.TT
.P
\f2data\f1
User data area.
Prior to the Read_Raster call,
you must allocate a character data area:
.DS
     Data Area = RAS_DIM.x * RAS_DIM.y * RAS_DEPTH
.DE
The user must allocate sufficient data, taking into
account the dimensions and depth of the raster
and the alignment of the data.
The format of the data is device dependent.
.P
The data is structured from the most significant
to least significant:\ \&
raster-y scan line to raster-x location.
Therefore, to determine whether or not the pixel value
(x,y) is turned on for a 1-bit framebuffer,
you should look at the byte in the user data:
.DS
     y * RAS_DIM.x * RAS_DEPTH + (x>>3)
.DE
Then, in order to get the correct bit,
use a bit mask dependent on the memory structure
of the CPU.
The pixel ordering of memory follows the natural
ordering of the CPU and is the same as that for
Sun framebuffers for that CPU.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Write_Raster
.H 4 "NAME"
.P
Set_Raster \- Sets the specified raster attribute.
.IX "Set_Raster"
.tm .CE U 3 "Set_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Set_Raster\f2(raster, attr, setting)\f1
.br
RASTER raster;
.br
RAS_attr attr;
.br
<attribute type> setting;
.H 4 "DESCRIPTION"
.P
Sets the specified attribute.
.P
\f2raster\f1
Specifies the raster for which the attribute is
to be set.
.P
\f2attr\f1
Specifies the attribute that is to be set.
.P
\f2setting\f1
Specifies the setting for the specified attribute.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Get_Raster
.H 4 "NAME"
.P
Store_Raster \- Copies all or part of the raster
associated with the context into the specified raster.
.IX "Store_Raster"
.tm .CE U 3 "Store_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Store_Raster\f2(raster, ctx)\f1
.br
RASTER raster;
.br
CONTEXT cxt;
.H 4 "DESCRIPTION"
.P
Copies all or part of the the raster associated
with the context into the specified raster object.
The current draw point, CTX_RASTER_PEN,
indicates the  upper-left corner in the source
raster of the rectangular area to copy.
The copy maps into the upper-left corner of the
destination raster.
The intersection of the context and raster clip
paths for the source context are used to crop the
area to be copied
(only pixels within this area will be transferred
to the destination raster.)
.P
The context's ROP applies,
but no plane enables are used.
The table below describes depth-to-depth mappings
and the effect of the CTX_FILL_STYLE attribute.
.TB "Raster Depth Mapping"
.TS H
box tab(/);
cf4I | cf4I
l | lw(4.5i).
Raster Depth/Copy Operation
=
.TH
1:1 /T{
The source is copied directly into the
destination unless CTX_FILL_STYLE is set to
opaque stippled.
In this case,
source 1 produces CTX_COLOR and a source 0
produces CTX_BACK_COLOR.
T}
_
1:4 /T{
If any source pixel is 1,
CTX_COLOR is copied in the destination raster.
If any source pixel is 0,
CTX_BACK_COLOR is copied in the destination pixel.
T}
_
4:4 /T{
Direct copy from source to destination.
T}
.TE
.TT
.P
The following rendering attributes affect Store_Raster:
.P
CTX_ROP
.br
CTX_FILL_STYLE
.br
CTX_CLIP_PATH
.br
RAS_CLIP_PATH
.br
RAS_PLANE_ENABLE
.br
RAS_ORG, RAS_DIM
.P
If either or both rasters have raster origins,
the following formula yields the point in the
destination raster at which the copying is to begin:
.DS
dst_ras.RAS_ORG \(mi (CTX_RASTER_PEN + srcras.RAS_ORG) = Destination Origin
.DE
The upper-left corner of the source raster maps
to this position.
.P
\f2raster\f1
Destination raster for the copy.
.P
\f2ctx\f1
Source raster for the copy.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Display_Raster
.br
CTX_RASTER_PEN
.br
CTX_FILL_STYLE
.br
CTX_ROP
.br
RAS_ORG
.H 4 "NAME"
.P
Temp_Raster \- Creates a raster which has no
initial references.
.IX "Temp_Raster"
.tm .CE U 3 "Temp_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Temp_Raster\f2(type, root)\f1
.br
RAS_type type;
.br
OBJID root;
.H 4 "DESCRIPTION"
.P
Creates a raster that has no initial reference count.
The resources associated with this object will be
freed if its reference count is zero and the
object you associate it with is destroyed.
A temporary raster is useful for passing the
raster as the argument to another operator.
.P
\f2type\f1
Specifies the type of raster.
See Create_Raster for a description of the parameter.
.P
\f2root\f1
.P
See Create_Raster for a description of the
\f2root\f1 parameter.
.H 4 "RETURNED VALUE"
.P
RASTER \- a handle to the new raster object.
.H 4 "SEE ALSO"
.P
Create_Raster
.H 4 "NAME"
.P
Write_Raster \- Copies all or part of the raster
object into the raster associated with the
specified context.
.IX "Write_Raster"
.tm .CE U 3 "Write_Raster" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Write_Raster\f2(raster, data, format)\f1
.br
RASTER raster;
.br
char *data;
.br
int format;
.H 4 "DESCRIPTION"
.P
Transfers image data from an application data
area into a raster by using write images in one
of several fixed formats.
The format argument determines how the sample
data is interpreted.
.P
No user-specified plane enables,
ROPS, or color mappings apply.
For 1- to 4-bit writes,
the foreground color is index 1 and the
background color is index 0.
.P
\f2raster\f1
Raster to write user data into.
\f2format\f1
Specifies the alignment and the depth of the data.
Alignment indicates the granularity that pointers
to the data must be able to handle.
CPU architectures work most efficiently with
the 32-bit alignment.
.P
.TB "Format Arguments"
.TS
box, tab(/);
cf4I | cf4I
l | l.
Type/Description
=
RAS_ALIGN_8/Data has 8-bit alignment
RAS_ALIGN_16/Data has 16-bit alignment
RAS_ALIGN_32/Data has 32-bit alignment
RAS_DEPTH_1/Data is 1-bit per pixel
RAS_DEPTH_8/Data is 1-byte per pixel
RAS_DEPTH_4/Data is 4-bits per pixel
.TE
.TT
\f2data\f1
User data area.
.DS
     Data Area Size = RAS_DIM.x * RAS_DIM.y * RAS_DEPTH
.DE
The user must allocate sufficient data, taking into account
the dimensions and depth of the raster and the alignment
of the data.
The format of the data is device dependent.
.P
The data is structured from the most significant
to least significant:\ \&
raster-y scan-line to raster-x location.
Therefore, to determine whether or not the pixel value
(x,y) is turned on for a 1-bit framebuffer,
you should look first to the byte in the user
data:
.DS
     y * RAS_DIM.x * RAS_DEPTH + (x>>3)
.DE
Then, in order to get the correct bit,
use a bit mask dependent on the memory structure
of the CPU.
The pixel ordering of memory follows the natural
ordering of the CPU and is the same as that for
Sun framebuffers for that CPU.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Read_Raster
.br
.H 2 "Raster Attributes"
.IX "raster attributes"
.H 4 "NAME"
.P
RAS_AREA_STYLE
.IX "RAS_AREA_STYLE "
.tm .CE U 3 "RAS_AREA_STYLE" \n(PN
.H 4 "DESCRIPTION"
.P
Describes the conversion of the raster clip path
geometry into a path area that is useful for
clipping.
See the description of CTX_AREA_STYLE for a full
explanation.
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.br

Choose one of:
.br
CTX_CLOSE_OFF
.br
CTX_CLOSE_MOVE
.br

Choose one of:
.br
CTX_FILL_NONZERO
.br
CTX_FILL_EVENODD
.br \}
.\"  ENDIF Paint------------------------------------------------
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
In addition to CTX_CLOSE_OFF choose one of:
.br \}
.\"  ENDIF SHAPES------------------------------------------------
CTX_FILL_NONZERO
.br
CTX_FILL_EVENODD
.H 4 "RETURNED VALUE"
.P
RAS_area_style
.H 4 "SEE ALSO"
.P
CTX_AREA_STYLE
.br
RAS_CLIP_PATH
.H 4 "NAME"
.P
RAS_CLIP_PATH
.IX "RAS_CLIP_PATH "
.tm .CE U 3 "RAS_CLIP_PATH " \n(PN
.H 4 "DESCRIPTION"
.P
Raster clip path.
All operations that use the raster as a
destination limit the display region to the
raster clip path.
The raster clip path is expressed in raster coordinates,
as offset by the raster origin.
In X11/NeWS,
the raster clip path is used as the outline of
the unobscured part of the window.
.P
Memory and child rasters can query and set this attribute.
Screen rasters can only query.
.P
If the raster clip path is NULL,
a default clip path of the raster's bounding box
is used.
.P
.H 4 "RETURNED VALUE"
.P
PATH
.H 4 "SEE ALSO"
.P
RAS_AREA_STYLE
.br
CTX_CLIP_PATH
.br
Area_Path
.H 4 "NAME"
.P
RAS_CMAP
.IX "RAS_CMAP "
.tm .CE U 3 "RAS_CMAP " \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the CMAP object associated with the raster.
Manipulation of this object determines how color
is handled.
For a description of its initial values,
see the section on the CMAP object.
.P
For each device or memory raster depth,
one default color map of monochrome,
indexed color is created.
As you create more rasters on the same device,
they all share the same color map unless you
explicitly assign a freshly-created
color map.
Thus, changing the default RAS_CMAP for one raster
changes it for all the other rasters sharing the
color map.
.P
Setting RAS_CMAP causes the hardware color map to
be loaded
(for screen rasters only).
It also may cause the color mapping function
(CMAP_FUNC) to be invoked.
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
.P
Setting the attribute RAS_CMAP to null causes the
color information to be interpreted according to
the direct color model.
The introduction to the color map section
explains direct color.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "RETURNED VALUE"
.P
CMAP
.H 4 "SEE ALSO"
.P
CMAP OBJECT
.br
Create_Cmap
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.H 4 "NAME"
.P
RAS_CURSOR_OVERLAP
.IX "RAS_CURSOR_OVERLAP "
.tm .CE U 3 "RAS_CURSOR_OVERLAP " \n(PN
.H 4 "DESCRIPTION"
.P
Set this value if a cursor overlapping this
raster cannot be supported transparently through
hardware.
The cursor attribute CURS_NEEDS_CUE lets you know
whether your current cursor can be supported
through hardware alone.
You must query CURS_NEEDS_CUE
(and possibly reset RAS_CURSOR_OVERLAP)
every time you change cursor shape and size or
the raster associated with the cursor.
.P
If you enable RAS_CURSOR_OVERLAP,
pixels obscured by a cursor are retained and restored.
If you disable it,
you are indicating no hardware handling of the
cursor (or no cursor).
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
CURS_NEEDS_CUES
.br
CURS_RASTER
.br
CURSOR Object
.br
.H 4 "NAME"
.P
RAS_DATA
.IX "RAS_DATA "
.tm .CE U 3 "RAS_DATA " \n(PN
.H 4 "DESCRIPTION"
.P
For memory rasters,
RAS_DATA is a pointer to the first memory word
of the raster pixel array.
This typically references the pixels in the upper left corner.
For screen rasters,
RAS_DATA points to the first memory word of the framebuffer,
and is independent of the placement of the raster
within that framebuffer.
.P
RAS_DATA is most useful in conjunction with the RAS_PRIVATEDATA
option on Create_Raster.
Create_Raster(RAS_MEMORY, RAS_PRIVATEDATA)
causes a memory raster to be created without a data area.
Setting the RAS_DATA attribute for such a raster allows the data
area to reside in the user program.
.H 4 "RETURNED VALUE"
.P
unsigned int *
.H 4 "SEE ALSO"
.P
RAS_LINEBYTES
.br
Create_Raster
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.H 4 "NAME"
.P
RAS_DEPTH
.IX "RAS_DEPTH "
.tm .CE U 3 "RAS_DEPTH " \n(PN
.H 4 "DESCRIPTION"
.P
Specifies raster depth.
Memory rasters can both read and write the attribute,
while screen rasters can only read it.
You must set this attribute immediately after
creating a memory raster.
Once set, however,
you cannot change the value of the raster depth.
.P
The range of samples in the raster image is $2 sup n-1$,
where \f2n\fP is the depth of the raster.
.P
Currently,
only depths of 1- and 4-bits are allowed.
.P
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
Create_Raster
.br
CTX_PLANE_ENABLE
.H 4 "NAME"
.P
RAS_DIM
.IX "RAS_DIM "
.tm .CE U 3 "RAS_DIM " \n(PN
.H 4 "DESCRIPTION"
.P
Specifies raster dimensions, in pixels.
Memory rasters can both read and write this attribute,
while screen rasters can only read it.
.P
To resize a memory raster,
you must change this attribute.
Since resizing causes a reallocation of raster memory,
the previous contents of the memory raster are obliterated,
and no assurances are made as to the new values.
A call to Clear_Context() is advised to ensure a
known base of values.
.P
The RAS_DIM in conjunction with the RAS_ORG may
be used as a default view clipping region.
For more information,
read about the context attribute CTX_VDC_MAP.
.H 4 "RETURNED VALUE"
.P
POINT_B2D *
.H 4 "SEE ALSO"
.P
RAS_ORG
.br
RAS_DEPTH
.br
Create_Raster
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.H 4 "NAME"
.P
RAS_LINEBYTES
.IX "RAS_LINEBYTES "
.tm .CE U 3 "RAS_LINEBYTES " \n(PN
.H 4 "DESCRIPTION"
.P
Gives the number of bytes in a single scan line of the raster.
RAS_LINEBYTES allows a user program to determine the layout of
a raster so that it can write pixels independently of Shapes.
The internal format of a raster is completely characterized by
RAS_DEPTH, RAS_LINEBYTES, and RAS_DATA.
.H 4 "RETURNED VALUE"
.P
unsigned int
.H 4 "SEE ALSO"
.P
RAS_DATA
.br
RAS_DEPTH
.br
Create_Raster
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.H 4 "NAME"
.P
RAS_ORG
.IX "RAS_ORG "
.tm .CE U 3 "RAS_ORG " \n(PN
.H 4 "DESCRIPTION"
.P
Origin of the upper-left corner of the raster.
Memory rasters can both read and write this attribute,
while screen rasters can only read it.
.P
The RAS_ORG, in conjunction with the RAS_DIM,
may be used as a default view clipping region.
For more information,
read about the context attribute CTX_VDC_MAP.
.P
The interpretation of RAS_ORG varies with the
type of screen raster.
The effects of the RAS_ORG are as follows:
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
RAS_SCREEN \-  Screen rasters ignore the effect
of the raster origin.
\f2Its use with screen rasters,
though not an error,
is undefined and should be avoided.\fP
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
RAS_SUNWINDOWS \- SunWindows rasters ignore the
effect of the raster origin.
It use with SunWindows rasters, though not an error,
is undefined and should be avoided.
.br \}
.\"  ENDIF Paint-----------------------------------------------
.P
RAS_MEMORY \- Display_Context will interpret the
first memory location as representing the raster
origin coordinate.
Therefore, if the origin is set to (x,y),
and if Display_Context would touch the pixel
(x,y) on a screen raster
(assuming the same context set to different rasters),
it will touch the first memory location in the
memory raster as well.
The Display_Raster command works similarly,
providing the RAS_ORG of the source raster is zero.
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.P
RAS_CHILD \- Setting the raster origin provides a
means for changing the offset of where the raster
appears on the parent raster.
For example, assume the RAS_CHILD origin is set to (x,y).
A Display_Context call that touches the
upper-left corner of the raster will effect
location (0,0).
Because of the parent/child relationship,
this location appears as (x,y) on the parent raster.
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.P
The raster origin affects the interpretation of
all raster copy commands such as Store_Raster
and Display_Raster.
.H 4 "RETURNED VALUE"
.P
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
POINT_B2D *
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
POINT *
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "SEE ALSO"
.P
Display_Context
.br
Store_Raster
.br
Display_Raster
.br
Copy_Raster
.br
RAS_DIM
.H 4 "NAME"
.P
RAS_PLANE_ENABLE
.IX "RAS_PLANE_ENABLE "
.tm .CE U 3 "RAS_PLANE_ENABLE " \n(PN
.H 4 "DESCRIPTION"
.P
This attribute has only one purpose:\ \&
as the bit-plane enable mask for X11 copy source mask.
X11 copy source occurs when the CTX_FILL_STYLE is
set to CTX_FILL_OPAQUE_STIPPLE,
and you execute either a Display_Raster call or
use a fill raster to fill a bounded region.
.P
RAS_PLANE_ENABLE is meaningful only on 4:4 and 8:8 bit copies.
.P
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
CTX_PLANE_ENABLE
.br
CTX_FILL_STYLE (CTX_FILL_OPAQUE_STIPPLING)
.H 4 "NAME"
.P
RAS_TYPE
.IX "RAS_TYPE "
.tm .CE U 3 "RAS_TYPE " \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the type of raster.
The available types are as follows:
.\" BEGIN SHAPES-----------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
RAS_CHILD
.br
RAS_MEMORY
.br
RAS_SCREEN
.br \}
.\"  ENDIF SHAPES----------------------------------------------
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
RAS_SUNWINDOWS
.br
RAS_MEMORY
.br
.br \}
.\"  ENDIF Paint-----------------------------------------------
.H 4 "RETURNED VALUE"
.P
RAS_type
.H 4 "SEE ALSO"
.P
Create_Raster
