'\"!  tbl | mmdoc
.if n .pH ref.glyph @(#)glyph	40.1

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 glyph
..
.SO mstr.hdr
.ds Lb Shapes 
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.nh
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.BK "Shapes Reference Manual"
.CH "Glyph Object" "9"
.H 1 "Glyph Object"
.H 2 "Introduction"
.P
Shapes does not directly support text fonts.
However, it does support bitmap descriptions of
text characters,
known as \f2glyphs\fP,
which applications can use to build sophisticated
font management systems.
.P
The glyph object is a small,
low-overhead bitmap that represents a single text
character.
A series of bitmaps are linked together using the
GLYPH_REF structure to name the glyph and its
position so that they can be rendered through the
Poly_Glyph command.
To learn about the glyph object,
begin reading about the Poly_Glyph command.
.P
Keep in mind that a glyph defines a CPU- or
framebuffer-dependent bitmap.
It is not device-independent.
.IX "glyph object"
.H 4 "NAME"
.P
Create_Glyph \- Creates a glyph of the specified type, width, and height.
.IX "Create_Glyph"
.tm .CE U 3 "Create_Glyph" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Glyph\f2(type, width, height)\f1
.br
RAS_data_type type;
.br
int width;
.br
int height;
.H 4 "DESCRIPTION"
.P
Creates a glyph of the specified type, width, and height.
.P
\f2type\f1
Specifies the type of glyph, as described in the table below.
.TB "Glyph Types"
.TS
box, tab(/);
cf4I | cf4I
l | l .
Type/Description
=
RAS_ALIGN_16/User data has 16-bit alignment.
RAS_ALIGN_32/User data has 32-bit alignment.
RAS_DEPTH_1/User data is 1-bit per pixel.
.TE
.TT
.P
\f2width\f1
Integer, specifying the pixel-width of the glyph.
.P
\f2height\f1
Integer, specifying the pixel-height of the glyph.
.H 4 "RETURNED VALUE"
.P
GLYPH
.H 4 "SEE ALSO"
.P
Set_Glyph
.br
Poly_Glyph
.br
Create_Raster
.H 4 "NAME"
.P
Destroy_Glyph  \- Destroys the specified glyph
and releases the resources associated with it.
.IX "Destroy_Glyph"
.tm .CE U 3 "Destroy_Glyph" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Glyph\f2(glyph)\f1
.br
GLYPH glyph;
.H 4 "DESCRIPTION"
.P
Destroys the specified glyph and releases the
associated resources.
.P
.UI "Note" :\ \&
This object is the only object that
is not reference counted;
therefore, the glyph will be destroyed even if
there are references to it.
.P
\f2glyph\f1
Specifies the glyph to be destroyed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Create_Glyph

.H 4 "NAME"
.P
Get_Glyph \- Returns the setting of the specified glyph attribute.
.IX "Get_Glyph"
.tm .CE U 3 "Get_Glyph" \n(PN
.H 4 "SYNOPSIS
.P
\f3Get_Glyph\f2(glyph, attr)\f1
.br
GLYPH glyph;
.br
GLYPH_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the setting of the specified glyph attribute.
.P
\f2glyph\f1
The glyph from which the attribute setting is to be returned.
.P
\f2attr\f1
The attribute for which the setting is to be returned.
.H 4 "RETURNED VALUE"
.P
Attribute Value
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
Set_Glyph \- Specifies the data used in the glyph
created with Create_Glyph.
.IX "Set_Glyph"
.tm .CE U 3 "Set_Glyph" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Set_Glyph\f2(glyph, data_source, source)\f1
.br
GLYPH glyph;
.br
<data_source> data_source;
.br
RASTER source;
.H 4 "DESCRIPTION"
.P
Sets the data for the glyph created by
Create_Glyph, using the same pixel-width and
pixel-height.
.P
\f2glyph\f1
Specifies the glyph in which to set the data.
.P
\f2data_source\f1
Specifies the source of the data.
.TB "Glyph Types"
.TS
box tab(/);
cf4I | cf4I
l | l.
Type/Description
=
GYLPH_RASTER/T{
Copies the data from a raster object.
T}
GLYPH_DATA/T{
Copies the data from a user array,
using the raster alignment and depth specified at
the time you created the glyph object.
T}
.TE
.TT
.P
\f2source\f1
Specifies the raster or data array from which to
retrieve the data.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
GLYPH_DATA
.br
GLYPH_RASTER
.H 4 "NAME"
.P
Poly_Glyph \- Render a series of glyphs into a raster.
.IX "Poly_Glyph"
.tm .CE U 3 "Poly_Glyph" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Poly_Glyph\f2(ctx, gr, n, org, dim, opt)\f1
.br
CONTEXT ctx;
.br
GLYPH_REF * gr;
.br
int n;
.br
POINT_2BD * org;
.br
POINT_B2D * dim;
.br
int opt;
.H 4 "DESCRIPTION"
.P
Renders a series of glyphs, as represented by an
array of GLYPH_REF structures,
into the raster associated with the specified context.
Glyphs are positioned in raster coordinates and
ignore all transformations.
.P
Glyphs serve as one-bit clip masks for rendering
text characters.
Typically, CTX_FILL_STYLE is set to CTX_FILL_SOLID,
the pixels where the glyph has bits at zero are unaffected,
and pixels where the glyph has bits at one are
set to the current color.
.P
Other fill styles add greater complexity to the
text rendering operation and involve the
context's fill raster as a source raster.
As before, pixels where the glyph has bits at
zero are unaffected,
and pixels where the glyph has bits of one are rendered.
For the pixels rendered,
the filling rules described in the section on
CTX_FILL_STYLE apply.
.P
\f2ctx\f1
Context used for rendering attributes.
The following attributes affect glyph
rendering:

.br
CTX_BACK_COLOR
.br
CTX_CLIP_PATH
.br
CTX_COLOR
.br
CTX_FILL_STYLE
.br
CTX_FILL_ORG
.br
CTX_FILL_RASTER
.br
CTX_PLANE_ENABLE
.br
CTX_RASTER
.br
CTX_ROP
.br

No context attributes,
including the current point attributes,
are affected by glyph rendering.
.P
\f2gr\f1
.P
Pointer to an array of GLYPH_REF structures.
The GLYPH_REF has the following structure definition:
.PC
typedef	struct
  {
   GLYPH	gr_glyph;	/* glyph to display */
   short	gr_x, gr_y;	/* position of glyph upper left corner */
  } GLYPH_REF;
.ft1
.SF
.P
\f2n\f1
Number of GLYPH_REFs in the array of GLYPH_REF structures.
.P
\f2org\f1
Specifies the upper-left corner of a bounding box
for the glyph references.
You must ensure that this bounding box contains
the glyph references.
.P
\f2dim\f1
Specifies the dimensions of a bounding box for
the glyph references.
You must ensure that this bounding box contains
the glyph references.
.P
\f2opt\f1
Specifies the options available for rendering the
designated structure:
.TB "Glyph Options"
.TS
box, tab(/);
cf4I | cf4I
l | l .
Option/Comment
=
GLYPH_OPT_ABSOLUTE/T{
Ignores RAS_ORG for glyph positioning
T}
_
GLYPH_OPT_MONOTONIC/T{
The widths of all glyphs are equal and
the signs of all heights are the same
T}
_
GLYPH_OPT_FIXED/T{
All the glyphs have the same width and height
T}
_
GLYPH_OPT_LEFT_TO_RIGHT/T{
The position of each glyph is to the right of the
previous glyphs rather than top-to-bottom
or left-to-right
T}
_
GLYPH_OPT_CLEAR/T{
Clears bounding box to the background color and
overrides the context's current raster operation
to use CTX_ROP_DRAW for rendering
T}
.TE
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_ANTIALIAS
.br
CTX_BACK_COLOR
.br
CTX_CLIP_PATH
.br
CTX_COLOR
.br
CTX_FILL_STYLE
.br
CTX_FILL_ORG
.br
CTX_FILL_RASTER
.br
CTX_PLANE_ENABLE
.br
CTX_RASTER
.br
CTX_ROP
.br
Display_Raster
.H 2 "Glyph Attributes"

.H 4 "NAME"
.P
GLYPH_DATA
.IX "GLYPH_DATA"
.tm .CE U 3 "GLYPH_DATA" \n(PN
.H 4 "DESCRIPTION"
.P
Set this value in order to copy a glyph clip mask
into the glyph object.
The data is assumed to be an array of the type
specified by the alignment parameter of the
Create_Glyph call.
The format of this array is CPU dependent.
See Write_Raster for more details.
.H 4 "RETURNED VALUE"
.P
char *
.H 4 "SEE ALSO"
.P
Read_Raster
.br
Write_Raster
.br
GLYPH_SIZE

.H 4 "NAME"
.P
GLYPH_HEIGHT
.IX "GLYPH_HEIGHT"
.tm .CE U 3 "GLYPH_HEIGHT" \n(PN
.H 4 "DESCRIPTION"
.P
Height of glyph in pixels,
as specified when you created the glyph.
Since glyphs are always 1-bit clip masks,
this is also the same as the height of the
glyph in bits.
You may only query this attribute.
.H 4 "RETURNED VALUE"
.P
integer
.H 4 "SEE ALSO"
.P
Create_Glyph
.br
Glyph_Width


.H 4 "NAME"
.P
GLYPH_RASTER
.IX "GLYPH_RASTER"
.tm .CE U 3 "GLYPH_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
Set this attribute to the handle of a raster
object in order to copy raster data into the
glyph object.
The raster must be of depth one.
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO"
.P
Create_Raster
.br
Set_Glyph
.br
GLYPH_DATA

.H 4 "NAME"
.P
GLYPH_SIZE
.IX "GLYPH_SIZE"
.tm .CE U 3 "GLYPH_SIZE" \n(PN
.H 4 "DESCRIPTION"
.P
Number of bytes used for the glyph.
You may only query this value.
The raster alignment specified when creating the
glyph affects this value.
.P
This attribute provides a way to write the glyph
data out to a file.
Get the pointer to the beginning of the data from
the attribute GLYPH_DATA.
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
GLYPH_HEIGHT
.br
GLYPH_WIDTH
.br
Create_Glyph


.H 4 "NAME"
.P
GLYPH_TYPE
.IX "GLYPH_TYPE"
.tm .CE U 3 "GLYPH_TYPE" \n(PN
.H 4 "DESCRIPTION"
.P
Returns the alignment and depth of the glyph as
specified when you created the glyph.
You may only query this attribute.
.H 4 "RETURNED VALUE"
.P
RAS_data_type
.H 4 "SEE ALSO"
.P
Create_Glyph


.H 4 "NAME"
.P
GLYPH_WIDTH
.IX "GLYPH_WIDTH"
.tm .CE U 3 "GLYPH_WIDTH" \n(PN
.H 4 "DESCRIPTION"
.P
Width of glyph in pixels,
as specified when you created the glyph.
Since glyphs are always 1-bit clip masks,
this is also the same as the width of the glyph,
in bits.
You may only query this attribute.
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
Create_Glyph
.br
GLYPH_WIDTH
.br \}
.\"  ENDIF SHAPES------------------------------------------------
