The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/docs/pmv3base.inf

OS/2 Help File | 1994-03-07 | 1.1 MB | 21,294 lines

ΓòÉΓòÉΓòÉ 1. Introduction to the Graphics Programming Interface ΓòÉΓòÉΓòÉ

The OS/2* 2.0 Presentation Manager* (PM) Graphics Programming Interface (GPI)
provides more than 200 functions.  These functions enable a user to create,
display, and print graphic images in a PC-based environment, using a variety of
techniques, media, and formats.

The major advantage of the GPI is device-independence, which is achieved
through the linking of presentation spaces with device contexts, and the use of
a wide selection of graphics primitives.

This chapter describes the parts of the operating system that enable you to
write PM applications, using presentation space-device context associations to
circumvent having to communicate directly with device drivers.  An overview of
the following topics is presented:

o Presentation spaces and device contexts
o Graphics primitives

   - Line and arc primitives
   - Area primitives and polygons
   - Character string primitives and fonts
   - Marker primitives

o Color and mix attributes
o Bit maps and metafiles
o Paths and regions
o Retained and nonretained graphics
o Correlation
o Clipping and boundary determination
o Coordinate spaces and transformation operations and functions
o Print job submission and manipulation.

Subsequent chapters offer in-depth descriptions of the GPI-its components,
capabilities, and advantages-to provide the information you need to write
applications that can prepare graphical output for display and printing.


ΓòÉΓòÉΓòÉ 1.1. About the GPI ΓòÉΓòÉΓòÉ

In a PM application, you use the graphics functions (most of which are prefixed
Gpi) to program the desired graphics output.  Many of the GPI functions are
described in this book.  For a complete alphabetic listing of the GPI
functions, along with their syntax and parameters, refer to the Presentation
Manager Programming Reference. Virtually all of the GPI calls conform to the
IBM Systems Application Architecture* (SAA*).

The applications you write probably will receive window messages about the
images to be created; your task, then, is to write how to process this input
into output.  Refer to the OS/2 Programming Guide, Volume II, for details about
the window messages, the visual parts of the PM user interface, and the
programming functions for creating and using windows, so that you can produce
window-based graphics applications.


ΓòÉΓòÉΓòÉ 1.1.1. Presentation Spaces and Device Contexts ΓòÉΓòÉΓòÉ

A presentation space is a data structure-the programming equivalent of a blank
piece of paper on which graphic images are created before being sent to an
output device.  An output device can be, for example, a printer or plotter,
memory bit map, display screen, or even a facsimile card.  A PM application
must direct all drawing to a presentation space.

The graphics engine and device drivers are responsible for getting output from
a presentation space to an output or hardcopy device.  The mapping from the
presentation space to the hardcopy device is handled by a device context that
is associated (linked) with the presentation space.

A device context also is a data structure-its purpose is to translate graphics
commands made to its associated presentation space into commands that the
physical device can convert to displayed information. The following figure
illustrates how an application's graphics commands flow through a presentation
space, to a device context, and on to the physical device.

The Flow of an Application's Graphics Commands


ΓòÉΓòÉΓòÉ 1.1.2. Graphics Primitives ΓòÉΓòÉΓòÉ

Graphics primitives are building blocks provided by the PM programming
interface from which to construct pictures.  There are several types of
primitives:

o Line and arc
o Area and polygon
o Character string
o Marker.


ΓòÉΓòÉΓòÉ 1.1.2.1. Primitive Attributes ΓòÉΓòÉΓòÉ


Each graphic primitive has a set of properties that further defines its
appearance.  A line, for example, can be drawn in different colors and
different widths; it can be dotted, solid, or even invisible.  Such properties
are called primitive attributes.

In general, primitive attributes are set for the type of primitive rather than
for a single instance of the primitive.  If you set the line-type attribute to
LINETYPE_DOT, for example, all lines subsequently drawn appear as dotted lines.

All primitive attributes have default settings that apply when a presentation
space is first created and continue to apply until you change them.  When an
attribute value is set, it is called the current attribute value, and remains
in effect until changed.


ΓòÉΓòÉΓòÉ 1.1.2.2. Line and Arc Primitives ΓòÉΓòÉΓòÉ


Simple drawing applications, such as pie and bar charts and graphs, use line
and arc primitives as their drawing tools.  Computer-aided design (CAD)
applications combine the numerous styles and forms of straight and curved lines
that compose line and arc primitives to draw more complex pictures.

Line and arc primitive attributes are stored in the LINEBUNDLE data structure.
Their relative attributes include width, type, color, and mix.

See Line and Arc Primitives for detailed information about line and arc
primitives and their use in PM applications.


ΓòÉΓòÉΓòÉ 1.1.2.3. Area Primitives ΓòÉΓòÉΓòÉ


An area is a closed shape that can be defined with line and arc primitives;
area primitives are produced by functions that can define and draw an area.

Area primitives are contained in the AREABUNDLE data structure.  Area primitive
attributes include pattern symbol and reference point, pattern set, foreground
and background colors, and foreground and background mix modes.

Areas are also referred to as area brackets because the functions that create
and define an area always are bracketed by the functions GpiBeginArea and
GpiEndArea.  The power of area brackets is their complete flexibility to draw
any combination of curved or straight lines and combine the results into a
closed figure.


ΓòÉΓòÉΓòÉ 1.1.2.4. Polygon Primitives ΓòÉΓòÉΓòÉ


A polygon is a closed plane figure bounded by straight lines.  A polygon
primitive is any set of polygons with specified vertices that can be filled or
filled and outlined.

The GPI has a function (GpiPolygons) that allows you to draw multiple
straight-lined closed areas outside of an area bracket; but like areas, they
can be adjacent, intersecting, or completely separate.

See Area and Polygon Primitives for guidance on how and when to use area
primitives and polygons in PM applications.


ΓòÉΓòÉΓòÉ 1.1.2.5. Character String Primitives and Fonts ΓòÉΓòÉΓòÉ


A character string primitive is used to create text.  A font is a collection of
character string primitives that share a common height, line weight, and
appearance.

Both character string primitive functions and font functions are used to
ascertain the available fonts, select a font for text output, draw a string of
the selected characters, and modify a character string.

Character string primitives are stored in the CHARBUNDLE data structure.
Attributes of the character string primitives include set, precision, cell,
angle, direction, text alignment, color, and mix.

See Character String Primitives for details about character string primitives,
and Fonts for details about fonts, and how to use both in PM applications.


ΓòÉΓòÉΓòÉ 1.1.2.6. Marker Primitives ΓòÉΓòÉΓòÉ


Marker primitives are graphics objects, used, for example, to indicate the
peaks and valleys on a line graph.  The GPI has a base marker set that includes
visible marker symbols, such as squares, diamonds, stars, circles, and crosses.

Marker primitives are contained in the MARKERBUNDLE data structure.  Marker
primitive attributes consist of marker symbols, marker box, the aforementioned
marker set, colors, and mix modes.

See Marker Primitives for detailed information about marker primitives and how
to use them in PM applications.


ΓòÉΓòÉΓòÉ 1.1.3. Color and Mix Attributes ΓòÉΓòÉΓòÉ

Color and Mix are two attributes that apply to primitives.  The color attribute
describes the color of a line, arc, character, area, or image.  The mix
attribute controls how each primitive is combined with an existing drawing and
affects, among other things, the resulting color when primitives of different
colors overlap.

Some primitives have foreground and background color attributes.  For example,
the character primitive has a foreground color attribute that specifies the
color of the character and a background color attribute that specifies the
color surrounding the character.  Primitives that have foreground and
background color attributes also have foreground and background mix attributes.

See Color and Mix Attributes for details about color implementation using the
GPI.


ΓòÉΓòÉΓòÉ 1.1.4. Bit Maps ΓòÉΓòÉΓòÉ

A bit map is a graphic image stored in memory.  Bit maps can be created using
the Icon Editor or hard-coded using GPI functions.  The bit maps can be stored
in a memory device context or in disk files.  PM supports both monochrome and
color bit maps.

Applications can use bit maps for the following:

o To store and display scanned images, icons, and pointers
o To create fill patterns for area primitives and paths.
o To animate graphics for multimedia displays.

See Bit Maps for more information about bit maps, icons, and pointers, and how
to make them available to the PM-application user.


ΓòÉΓòÉΓòÉ 1.1.5. Metafiles ΓòÉΓòÉΓòÉ

Metafiles are files that contain low-level graphics commands that describe a
picture.

The OS/2 operating system supports long-term retention ofgraphic so that
pictures can be saved for use by any PM application, or even by non-PM
applications that support the Mixed Object Document Content Architecture
(MO:DCA) interchange standard.  Graphics data that is to be exchanged among PM
and non-PM applications is transferred to those applications in a metafile.

See Metafiles for complete details about metafiles and their use in both PM and
non-PM applications.


ΓòÉΓòÉΓòÉ 1.1.6. Paths ΓòÉΓòÉΓòÉ

A path is an object defined by a sequence of graphic primitive and attribute
functions issued between GpiBeginPath and GpiEndPath.  A path can be used for
defining a filled area, a complex clipping shape, an outline, and for drawing
geometric (wide) lines.  As a matter of fact, paths are the only means of
drawing lines with a geometric (scalable) width, and clipping to circular,
elliptical, or other nonrectangular figures, as well as being an efficient way
of producing text in an outline font.

See Paths to learn how to define and use paths with several different drawing
techniques.


ΓòÉΓòÉΓòÉ 1.1.7. Regions ΓòÉΓòÉΓòÉ

Regions are rectangular graphics objects in an application's device space that
can be used to clip output, draw one or more discrete filled rectangles, or
draw a filled polygon consisting of intersecting rectangles.  Regions also are
used to repaint the client area of a window or part of an object in a picture.

Regions are device-dependent and are defined in device coordinates.  Each
region is created for a device that is currently associated with a presentation
space.  The system implements regions as part of a device context.

See Regions for more information on how to use regions in PM applications.


ΓòÉΓòÉΓòÉ 1.1.8. Retained Graphics ΓòÉΓòÉΓòÉ

There are two types of graphics output in the OS/2 operating system: retained
and nonretained. Retained graphics is a presentation space model in which an
entire graphics picture is stored for subsequent display and editing.

An application draws nonretained graphics output using a graphics function.
The output appears immediately on the output device, such as a window.  If part
of the picture is erased or has to be repeated, the application must issue the
same function as many times as necessary; this is the primary drawback of
nonretained graphics.

Retained graphics provide many advantages such as convenience, flexibility,
editing capability, more powerful and useful graphics, and better organization.
A possible disadvantage of retained graphics is the additional memory required
to store the data.

PM applications store graphics in segments. Primarily, a graphics segment is a
means of grouping and storing graphics primitives and their attributes.
Although usually graphics segments are related in some way, they do not have to
be.

See Creating and Drawing Retained Graphics for detailed information on how to
create and replay retained graphics.  See Editing Retained Graphics and
Graphics Segments for information on how to edit retained graphics and graphics
segments.


ΓòÉΓòÉΓòÉ 1.1.9. Correlation ΓòÉΓòÉΓòÉ

Correlation is the process of determining which primitives or primitive group
in a picture are at a given position on the display.  Correlation, most
commonly, is used in graphics applications; for instance, to identify a
primitive or primitive group selected by the user.  It should be noted,
however, that correlation also can be used in non-graphic applications; for
example, if your application models the operation of a calculator and allows a
user to select numbers for mathematical operations.

See Correlation for low-level information about the correlation process.


ΓòÉΓòÉΓòÉ 1.1.10. Clipping and Boundary Determination ΓòÉΓòÉΓòÉ

Clipping is a process by which all output outside the defined clip boundary of
a picture is discarded (clipped), and only the parts inside the clip boundary
(clipping area) are displayed.

Most often, clipping boundaries are defined by the application.  The PM
interface performs some clipping automatically when, for example, the
application's graphic output is clipped to fit a client area (user work area)
or the device output area for a hard-copy device.

Boundary determination is an operation to compute the size of the smallest
rectangle that encloses a graphics object on the screen, for the purpose of
updating only the affected parts of the screen when that graphics object is
moved or changed.

See Clipping and Boundary Determination for comprehensive information about
clipping and boundary determination for PM applications.


ΓòÉΓòÉΓòÉ 1.1.11. Coordinate Spaces and Transformation Operations and Functions ΓòÉΓòÉΓòÉ

Transformations (also called transforms) enable an application to control the
size and orientation of graphic output on any output device.  The GPI transform
functions provide for scaling, translation, rotation, and shear in both
graphics pictures and text.  Almost all of these GPI functions draw their
output in a conceptual area called a world coordinate space.

The following table describes the five kinds of coordinate spaces used in GPI
transformations:

Types of Coordinate Spaces

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéName                    ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWorld coordinate space  ΓöéA space where an application        Γöé
Γöé                        Γöéspecifies its coordinates for       Γöé
Γöé                        Γöédrawing.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéModel space             ΓöéA conceptual space in which a       Γöé
Γöé                        Γöépicture is constructed by the outputΓöé
Γöé                        Γöéof the model transform matrix.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDefault page coordinate ΓöéA space representing a picture      Γöé
Γöéspace                   Γöédefined in page coordinates without Γöé
Γöé                        Γöéany scaling or scrolling.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPage coordinate space   ΓöéA conceptual space in which a       Γöé
Γöé                        Γöépicture is constructed by the outputΓöé
Γöé                        Γöéof the default viewing transform    Γöé
Γöé                        Γöématrix.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevice coordinate space ΓöéThe coordinate space of a device.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

See Coordinate Spaces and Transformations for information on all the available
transforms and functions for GPI graphics transformations.


ΓòÉΓòÉΓòÉ 1.1.12. Print Job Submission and Manipulation ΓòÉΓòÉΓòÉ

Printing is the process of producing hardcopy output. An application can submit
the job using the spooler, which will direct the job to the appropriate
printer. Alternatively, an application can submit the job directly to the
printer. Direct submission can halt all user input to an application until
printing is complete.

If you choose to use the spooler, you can manipulate the job while it is in a
spool queue. A common example of manipulation is increasing the number of
copies to be printed or deleting the job entirely.

See Print Job Submission and Manipulation for more information on how to print
jobs or manipulate them once inside a queue.


ΓòÉΓòÉΓòÉ 1.1.13. Program Execution ΓòÉΓòÉΓòÉ

Graphics programming is influenced by the underlying execution of the operating
system.  While the OS/2 2.0 Programming Guide, Volume I, will familiarize you
with the concepts of operating system execution, following are some of the
concepts that you will be concerned with when programming for the GPI:

A session is one or more processes with its own virtual console.  A virtual
console is a virtual screen-either a character-based full screen or a PM
window-and buffers for keyboard and mouse input.

A process is the application's code, data, and other resources-such as file
handles, semaphores, pipes, queues, and so forth-in memory.  The operating
system considers every application it loads to be a process.

A thread is a dispatchable unit of execution that consists of a set of
instructions, related CPU register values, and a stack.  Every process has at
least one thread and can have many threads running at the same time.  The
application runs when the operating system turns over control to a thread in
the process.  A thread is the basic unit of execution scheduling.

Graphics output can be slow, so it is wise to perform lengthy drawing
operations on an asynchronous thread.  As a result, the main thread is free to
process its message queue and remain responsive to user input.  User input goes
to only the main thread, so good communication between the main thread and the
drawing thread is very important if you are to achieve rapid response to user
requests.

For example, if a user changes or deletes graphics, the main thread must be
able to interrupt the processing of the asychronous thread to pass on the
revised instructions.  The main thread issues GpiSetStopDraw, with the value
SDW_ON-this suspends all drawing to the graphics presentation space named in
GpiSetStopDraw and establishes the stop draw condition.

Drawing to other presentation spaces in the same process and in different
processes is unaffected by this stop-draw condition.  But no drawing can begin
from another thread to the named presentation space while the stop-draw
condition is in effect.  Any drawing operations to the same presentation space
that are in progress on other threads of the same process when you issue this
function are terminated with a warning.  When the main thread receives an
acknowledgment from the drawing thread, it can clear the suspension by issuing
GpiSetStopDraw with the value SDW_OFF.


ΓòÉΓòÉΓòÉ 1.2. Summary ΓòÉΓòÉΓòÉ

Following is a summary of some of the GPI's frequently-used functions.

GPI Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute Functions           Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMove                       ΓöéMoves the current position to Γöé
Γöé                              Γöéthe specified point.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryAttrs                 ΓöéReturns current attributes forΓöé
Γöé                              Γöéthe specified primitive type. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharSet               ΓöéReturns the character-set     Γöé
Γöé                              Γöélocal identifier (ICID) as setΓöé
Γöé                              Γöéby GpiSetCharSet.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCurrentPosition       ΓöéReturns the value of current  Γöé
Γöé                              Γöéposition.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLineType              ΓöéReturns the current cosmetic  Γöé
Γöé                              Γöéline-type attribute as set by Γöé
Γöé                              ΓöéGpiSetLineType.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLineWidth             ΓöéReturns the current value of  Γöé
Γöé                              Γöéthe cosmetic line-width       Γöé
Γöé                              Γöéattribute as set by           Γöé
Γöé                              ΓöéGpiSetLineWidth.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMix                   ΓöéReturns the current value of  Γöé
Γöé                              Γöéthe (character) foreground    Γöé
Γöé                              Γöécolor-mixing mode as set by   Γöé
Γöé                              ΓöéGpiSetMix.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPatternSet            ΓöéReturns the current value of  Γöé
Γöé                              Γöéthe pattern-set identifier as Γöé
Γöé                              Γöéset by GpiSetPatternSet.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetArcParams               ΓöéSets the current arc          Γöé
Γöé                              Γöéparameters.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetAttrs                   ΓöéSets the attributes for the   Γöé
Γöé                              Γöéspecified primitive type.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharBox                 ΓöéSets the current character-boxΓöé
Γöé                              Γöéattribute to the specified    Γöé
Γöé                              Γöévalue.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCurrentPosition         ΓöéSets the current position to  Γöé
Γöé                              Γöéthe specified point.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineType                ΓöéSets the current cosmetic     Γöé
Γöé                              Γöéline-type attribute.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineWidth               ΓöéSets the current cosmetic     Γöé
Γöé                              Γöéline-width attribute.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMix                     ΓöéSets the current background   Γöé
Γöé                              Γöémix attribute for each        Γöé
Γöé                              Γöéindividual primitive type.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPattern                 ΓöéSets the current value of the Γöé
Γöé                              Γöépattern-symbol attribute.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBit Map Functions             Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateBitmap               ΓöéCreates a bit map and returns Γöé
Γöé                              Γöéthe bit-map handle.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteBitmap               ΓöéDeletes a bit map.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapBits            ΓöéTransfer data from a bit map  Γöé
Γöé                              Γöéto application storage.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapHandle          ΓöéReturns the handle of the bit Γöé
Γöé                              Γöémap currently tagged with the Γöé
Γöé                              Γöéspecified local identifier.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapParameters      ΓöéReturns information about a   Γöé
Γöé                              Γöébit map identified by the     Γöé
Γöé                              Γöébit-map handle.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDeviceBitmapFormats   ΓöéReturns the formats of bit    Γöé
Γöé                              Γöémaps supported internally by  Γöé
Γöé                              Γöéthe device driver.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmap                  ΓöéSets a bit map as the         Γöé
Γöé                              Γöécurrently selected bit map in Γöé
Γöé                              Γöéa memory device context.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmapid                ΓöéTags a bit map with a local   Γöé
Γöé                              Γöéidentifier so that it can be  Γöé
Γöé                              Γöéused as a pattern set         Γöé
Γöé                              Γöécontaining a single member.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevice Functions              Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevCloseDC                    ΓöéCloses a device context.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevEscape                     ΓöéEnables applications to accessΓöé
Γöé                              Γöéfacilities of a device not    Γöé
Γöé                              Γöéotherwise available through   Γöé
Γöé                              Γöéthe API.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevOpenDC                     ΓöéCreates a device context.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevPostDeviceModes            ΓöéReturns and, optionally, sets Γöé
Γöé                              Γöéjob properties.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevQueryCaps                  ΓöéQueries the device            Γöé
Γöé                              Γöécharacteristics.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevQueryDeviceNames           ΓöéQueries the presentation      Γöé
Γöé                              Γöédriver to return the names,   Γöé
Γöé                              Γöédescriptions, and data types  Γöé
Γöé                              Γöéof the devices it support.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevQueryHardcopyCaps          ΓöéQueries the hard-copy         Γöé
Γöé                              Γöécapabilities of a device.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDrawing Functions             Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginArea                  ΓöéBegins the construction of an Γöé
Γöé                              Γöéarea.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginPath                  ΓöéSpecifies the start of a path.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBitBlt                     ΓöéCopies a rectangle of bit-map Γöé
Γöé                              Γöéimage data.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharString                 ΓöéDraws a character string      Γöé
Γöé                              Γöéstarting at the current       Γöé
Γöé                              Γöéposition.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndArea                    ΓöéEnds construction of a shaded Γöé
Γöé                              Γöéarea.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndPath                    ΓöéEnds the specification of a   Γöé
Γöé                              Γöépath started by GpiBeginPath. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiErase                      ΓöéClears the output display of  Γöé
Γöé                              Γöéthe device context associated Γöé
Γöé                              Γöéwith the specified            Γöé
Γöé                              Γöépresentation space to the     Γöé
Γöé                              Γöéreset color.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiIntersectClipRectangle     ΓöéSets the new clip region to   Γöé
Γöé                              Γöéthe intersection of the       Γöé
Γöé                              Γöécurrent clip region and the   Γöé
Γöé                              Γöéspecified rectangle.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLine                       ΓöéDraws a straight line from theΓöé
Γöé                              Γöécurrent position to the       Γöé
Γöé                              Γöéspecified end point.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPaintRegion                ΓöéPaints a region into a        Γöé
Γöé                              Γöépresentation space using the  Γöé
Γöé                              Γöécurrent pattern attributes.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolyLine                   ΓöéDraws a series of straight    Γöé
Γöé                              Γöélines starting at the current Γöé
Γöé                              Γöéposition and connecting the   Γöé
Γöé                              Γöépoints specified.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolySpline                 ΓöéCreates a succession of BezierΓöé
Γöé                              Γöésplines.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharStringPos         ΓöéProcesses a string as if it isΓöé
Γöé                              Γöébeing drawn under the current Γöé
Γöé                              Γöécharacter attributes using    Γöé
Γöé                              ΓöéGpiCharStringPos, and returns Γöé
Γöé                              Γöéthe positions in the string atΓöé
Γöé                              Γöéwhich each character would be Γöé
Γöé                              Γöédrawn.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryClipBox               ΓöéReturns the dimensions of the Γöé
Γöé                              Γöétightest rectangle that       Γöé
Γöé                              Γöécompletely encloses the       Γöé
Γöé                              Γöéintersection of all the       Γöé
Γöé                              Γöéclipping definitions.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPel                   ΓöéReturns the color of a pel at Γöé
Γöé                              Γöéa position specified in world Γöé
Γöé                              Γöécoordinates.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRectVisible                ΓöéDetermines whether any part ofΓöé
Γöé                              Γöéa rectangle lies within the   Γöé
Γöé                              Γöéclipping region of the device Γöé
Γöé                              Γöéassociated with the specified Γöé
Γöé                              Γöépresentation space.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRestorePS                  ΓöéRestores the state of the     Γöé
Γöé                              Γöépresentation space to the one Γöé
Γöé                              Γöéthat exists when the          Γöé
Γöé                              Γöécorresponding GpiSavePS is    Γöé
Γöé                              Γöéissued.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSavePS                     ΓöéSaves information about the   Γöé
Γöé                              Γöépresentation space on a LIFO  Γöé
Γöé                              Γöéstack.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetClipRegion              ΓöéDefines the region to be used Γöé
Γöé                              Γöéfor clipping when any drawing Γöé
Γöé                              Γöétakes place through the       Γöé
Γöé                              Γöéspecified presentation space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPel                     ΓöéSets a pel at a position      Γöé
Γöé                              Γöéspecified in world coordinatesΓöé
Γöé                              Γöéusing the current (line) colorΓöé
Γöé                              Γöéand mix.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiWCBitBlt                   ΓöéCopies a rectangle of bit-map Γöé
Γöé                              Γöéimage data.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFont Functions                Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateLogFont              ΓöéProvides the logical          Γöé
Γöé                              Γöédefinition of a font.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteSetId                ΓöéDeletes a logical font or     Γöé
Γöé                              Γöébit-map tag.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLoadFonts                  ΓöéLoads one or more fonts from  Γöé
Γöé                              Γöéthe specified resource file.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFontMetrics           ΓöéReturns a record providing    Γöé
Γöé                              Γöédetails of the font metrics   Γöé
Γöé                              Γöéfor the logical font that is  Γöé
Γöé                              Γöécurrently selected.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFonts                 ΓöéReturns a record providing    Γöé
Γöé                              Γöédetails of the fonts that     Γöé
Γöé                              Γöématch the specified           Γöé
Γöé                              ΓöépszFacename.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryNumberSetIds          ΓöéReturns the number of local   Γöé
Γöé                              Γöéidentifiers currently in use, Γöé
Γöé                              Γöéreferring to fonts or bit     Γöé
Γöé                              Γöémaps.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryWidthTable            ΓöéReturns width table           Γöé
Γöé                              Γöéinformation for the logical   Γöé
Γöé                              Γöéfont identified by the value  Γöé
Γöé                              Γöéof the character-set          Γöé
Γöé                              Γöéattribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCP                      ΓöéSets the default graphics codeΓöé
Γöé                              Γöépage.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiUnloadFonts                ΓöéUnloads any fonts previously  Γöé
Γöé                              Γöéloaded from the resource file Γöé
Γöé                              Γöéby GpiLoadFonts.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPresentation Space Functions  Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS                   ΓöéCreates a presentation space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDestroyPS                  ΓöéDeletes a presentation space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDevice                ΓöéReturns the handle of the     Γöé
Γöé                              Γöécurrently associated device   Γöé
Γöé                              Γöécontext.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiResetPS                    ΓöéResets the presentation space.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPS                      ΓöéSets the presentation space   Γöé
Γöé                              Γöésize, unit, and format.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRegion Functions              Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCombineRegion              ΓöéCombines two regions.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateRegion               ΓöéCreates a region for a        Γöé
Γöé                              Γöéparticular class of device    Γöé
Γöé                              Γöéusing a series of rectangles. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryRegionBox             ΓöéReturns the dimensions of the Γöé
Γöé                              Γöésmallest rectangle able to    Γöé
Γöé                              Γöébound the region.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetRegion                  ΓöéChanges a region to be the    Γöé
Γöé                              Γöélogical OR of a set of        Γöé
Γöé                              Γöérectangles.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTransform Functions           Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiConvert                    ΓöéConverts an array of          Γöé
Γöé                              Γöécoordinate pairs from one     Γöé
Γöé                              Γöécoordinate space to another.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryModelTransformMatrix  ΓöéReturns the current model     Γöé
Γöé                              Γöétransform.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetModelTransformMatrix    ΓöéSets the model transform      Γöé
Γöé                              Γöématrix for subsequent         Γöé
Γöé                              Γöéprimitives.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPageViewport            ΓöéSets the page viewport within Γöé
Γöé                              Γöédevice space.                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 2. Presentation Spaces and Device Contexts ΓòÉΓòÉΓòÉ

A presentation space is a data structure maintained by the operating system in
which information relevant to the graphic output is stored.  The information is
related to both the subsequent drawings (such as colors or line styles) and the
presentation space resources (such as color tables or fonts).

The first task in a graphics application is to define a presentation space,
because so many of the GPI functions must operate within them.  A presentation
space is required for each output device currently in use by your application,
including each separate window on the display screen.  In almost all cases, the
presentation space is set up to be device-independent, because the requirements
of each possible output device are so different.

Note:  In some cases, it is possible to disassociate a presentation space from
       one device and associate it with another, thereby allowing the
       presentation space to be shared.

To facilitate the device independence of the PM programming interface, all
device-specific information is held in a device context.  A device context is a
data structure that identifies a particular instance of an output device and
contains all the device-specific information, such as the logical name of the
device and the presentation driver name.  Each separate instance of an output
device that you intend to use must be described in a device context.  For
example, if a single application uses more than one window, each of those
windows must have its own window device context.

The applicable device context, then, must be associated with the presentation
space in order to send  graphics data to that output device.  See Associating
Presentation Spaces with Device Contexts for details about how to create these
associations.

This chapter describes presentation spaces and device contexts. The following
topics are related to the information in this chapter:

o Graphics primitives
o Coordinate spaces
o Transformations
o Graphics segments.


ΓòÉΓòÉΓòÉ 2.1. About Presentation Spaces ΓòÉΓòÉΓòÉ

There are three types of presentation spaces:

o Standard Micro
o Cached Micro
o Normal.


ΓòÉΓòÉΓòÉ 2.1.1. Micro Presentation Spaces ΓòÉΓòÉΓòÉ

You need a micro presentation space if your application creates a separate
presentation space for each output device instance and if its output is a
simple drawing.

Although run time memory requirements vary according to the graphics function
an application uses, a typical micro presentation space graphical application
uses 315KB of GPI, engine, and display memory resource (code and data).  A
micro presentation space cannot be reassociated with a different device.


ΓòÉΓòÉΓòÉ 2.1.1.1. Standard Micro Presentation Space ΓòÉΓòÉΓòÉ

Use a standard micro presentation space for drawing on any type of output
device, provided the presentation space is not in retain mode or retain and
draw mode.

There are two different functions you can use to access a standard micro
presentation space. The following table lists both functions and their
considerations.

Functions that Create Standard Micro Presentation Spaces

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name  ΓöéUsage                         ΓöéClosing        Γöé
Γöé               Γöé                              ΓöéFunction       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS    ΓöéAccepts an anchor handle, a   ΓöéGpiDestroyPS   Γöé
Γöé               Γöédevice-context handle, and a  Γöédestroys a     Γöé
Γöé               Γöépresentation space size as    Γöépresentation   Γöé
Γöé               Γöéparameters. Creates both      Γöéspace and      Γöé
Γöé               Γöénormal presentation spaces andΓöéreleases all   Γöé
Γöé               Γöémicro presentation spaces.    Γöéresources ownedΓöé
Γöé               Γöé                              Γöéby the         Γöé
Γöé               Γöé                              Γöépresentation   Γöé
Γöé               Γöé                              Γöéspace.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetScreenPS ΓöéThe presentation space        ΓöéWinReleasePS   Γöé
Γöé               Γöérepresents the entire display Γöé               Γöé
Γöé               Γöéscreen. Warning:  Exercise    Γöé               Γöé
Γöé               Γöécaution when using this       Γöé               Γöé
Γöé               Γöéfunction as the graphic outputΓöé               Γöé
Γöé               Γöécan overlap individual        Γöé               Γöé
Γöé               Γöéwindows.                      Γöé               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 2.1.1.2. Cached Micro Presentation Space ΓòÉΓòÉΓòÉ

The window manager maintains a cache of micro presentation spaces for windows
on a display screen.  The cache is provided for applications that use a large
number of windows, and where each window requires a temporary presentation
space-device context pair for a short sequence of output operations.  These
presentation spaces belong to the system rather than to your application, and
are allocated only on a temporary basis.

Cached micro presentation spaces are provided by the window system rather than
by the GPI; their use is synchronized with other window activities.  For
example, you need not associate a cached micro presentation space with the
display screen; the window manager does this for you.

Cached micro presentation spaces offer the best system performance because,
unlike normal presentation spaces and standard micro presentation spaces, they
are not permanently allocated to an application. The PM programming interface
is a model interface, however, cached micro presentation spaces can be
cumbersome to use because all the attributes must be initialized continually.

Use a cached micro presentation space to send output only to a window on the
display device. There are three different functions you can use to access a
cached micro presentation space, each with its own considerations. These
functions are listed in the following table.

Functions that Obtain Cached Micro Presentation Spaces

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name  ΓöéUsage                         ΓöéClosing        Γöé
Γöé               Γöé                              ΓöéFunction       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinBeginPaint  ΓöéAccepts a NULL presentation   ΓöéWinEndPaint    Γöé
Γöé               Γöéspace handle for a cached     Γöéautomatically  Γöé
Γöé               Γöémicro presentation space.  TheΓöéreleases the   Γöé
Γöé               Γöépresentation space created by Γöépresentation   Γöé
Γöé               Γöéthis function is already      Γöéspace, no      Γöé
Γöé               Γöépreassociated with the window Γöématter what    Γöé
Γöé               Γöédevice context, making this   Γöétype.          Γöé
Γöé               Γöéthe easiest function to use.  Γöé               Γöé
Γöé               ΓöéUsually this type of creation Γöé               Γöé
Γöé               Γöéis in response to a WM_PAINT  Γöé               Γöé
Γöé               Γöémessage.                      Γöé               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetScreenPS ΓöéThe presentation space        ΓöéWinReleasePS   Γöé
Γöé               Γöérepresents the entire display Γöé               Γöé
Γöé               Γöéscreen.                       Γöé               Γöé
Γöé               ΓöéWarning:  Exercise caution    Γöé               Γöé
Γöé               Γöéwhen using this function as   Γöé               Γöé
Γöé               Γöéthe graphic output can overlapΓöé               Γöé
Γöé               Γöéindividual windows.           Γöé               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetPS       ΓöéThe presentation space can    ΓöéWinReleasePS   Γöé
Γöé               Γöérepresent the entire desktop, Γöé               Γöé
Γöé               Γöéor any other window.          Γöé               Γöé
Γöé               ΓöéThe presentation space can be Γöé               Γöé
Γöé               Γöéused to process any message,  Γöé               Γöé
Γöé               Γöébut it must be returned to theΓöé               Γöé
Γöé               Γöécache when message processing Γöé               Γöé
Γöé               Γöéis complete.                  Γöé               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

In general, use a cached micro presentation space to process a single paint
message when no presentation space information needs to be remembered between
messages.  The presentation space must be both obtained and released during the
processing of that message.  All application information stored in a cached
micro presentation space is lost as soon as it is released to the cache.

You must provide a window handle on input to WinBeginPaint and WinGetPS.  The
resulting presentation space is defined specifically for that window, and
cannot be reassociated.

The cached micro presentation space always is:

o Defined in pels-although you can change the units using GpiSetPS
o Formatted GPIF_LONG
o Given a suitable size by the system.

When you finish using a cached micro presentation space, you do not have to
disassociate it from the window device context because WinReleasePS or
WinEndPaint performs the disassociation.  This makes the cached micro
presentation space available for use in other windows.  The presentation space
itself cannot be deleted.

Cached micro presentation spaces are used serially.  The next time you need a
cached presentation space, access a new 1 using the appropriate function.  Each
time you get a cached micro presentation space, graphics attributes are reset
to their default values.


ΓòÉΓòÉΓòÉ 2.1.2. Normal Presentation Spaces ΓòÉΓòÉΓòÉ

You must use a normal presentation space if you require your application to use
the same presentation space to send output to multiple devices (a display
screen and printer, for example), or if it uses the segment and
retained-drawing functions to generate complex drawings.

There is only one function you can use to create a normal presentation space:

Functions that Create Normal Presentation Spaces

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name  ΓöéUsage                         ΓöéClosing        Γöé
Γöé               Γöé                              ΓöéFunction       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS    ΓöéAccepts an anchor handle, a   ΓöéGpiDestroyPS   Γöé
Γöé               Γöédevice-context handle, and a  Γöédestroys a     Γöé
Γöé               Γöépresentation space size as    Γöépresentation   Γöé
Γöé               Γöéparameters. Creates both      Γöéspace and      Γöé
Γöé               Γöénormal presentation spaces andΓöéreleases       Γöé
Γöé               Γöémicro presentation spaces.    Γöé               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

If a normal presentation space is used, or if metafiling is carried out, more
run time memory is used than if a micro presentation spaces was used.  A normal
presentation space requires 114KB more than a micro presentation space.


ΓòÉΓòÉΓòÉ 2.1.3. Modal Graphic Systems ΓòÉΓòÉΓòÉ

The graphic output sent to the presentation space is created by graphic
primitives, such as straight or curved lines. How those primitives appear
depends in part on the mode of the presentation space.

In modal systems, certain information that modifies a graphic primitive is
established before you issue the instruction to draw the primitive. For
example, The following figure is an example of a red, solid line being drawn
from (4,3) to (9,7).  With PM's modal interface, the only value you need to
supply to the GpiLine function is the end point (9,7).

Line Drawn with the GpiLine Function.

The line is drawn automatically with the current color, red, in the current
line type, solid, and starting from the current position, (4,3).  There are
separate functions for specifying the current color, line type, and position.

In nonmodal graphics systems, you supply information relevant to an instruction
when you issue that instruction.  For example, you could issue a line-drawing
instruction in which you would specify that the line is to be green, dotted,
and drawn from point a to point b.  Those values or attributes are bound to a
particular drawing instruction, and affect no other.  If you are going to
continue the line from point b to point c, you must again specify "green",
"dotted", "point b", and finally, "point c".

For the PM programming interface, the default values for the graphics
primitives (or current values if the defaults have been modified) are stored in
the presentation space along with the current position.  While at first it
might seem like many functions are necessary to perform 1 step, that is, to
draw the line, a modal graphics system actually saves resources.  After you
perform the first line draw, chances are that if you draw a second or third
line, the line attributes are not likely to change, that is, the mode of the
presentation space remains the same.  Thus, the constant repetition of
attributes in a nonmodal graphics system actually uses more resources if the
desired output requires more than 1 or 2 graphic functions.

It is possible to define graphics, and store their definitions, without sending
them to a screen or a printer.  In these situations, the concept of attribute
currentness becomes relevant.  The color of a line on a screen, for example, is
the color that was current when you defined the line.  This is not always the
color that is current when the line is drawn.


ΓòÉΓòÉΓòÉ 2.1.4. Current Position ΓòÉΓòÉΓòÉ

The current position is the world-coordinate space position at which the next
drawing request begins; it is part of the data stored in the presentation
space.  When you create or obtain a presentation space, the current position is
set to the origin (0,0).  The current position also is reset to (0,0) whenever
a presentation space is associated with a different device context.

Most drawing requests update the current position.  If you draw a line from the
origin to (3,5), for example, the current position is updated to (3,5).  The
current position also can be updated explicitly by GpiSetCurrentPosition or
GpiMove.  If you do not want the first drawing in a presentation space to start
at (0,0), call GpiSetCurrentPosition first.


ΓòÉΓòÉΓòÉ 2.1.5. Primitive Attributes ΓòÉΓòÉΓòÉ

The graphics primitives and the functions that draw them are discussed in Line
and Arc Primitives through Fonts. The primitive's function allows the
attributes of the primitive to be set for all subsequent issuance of that
primitive.  The attributes are stored in data structures called bundles.  There
are functions that allow you to set the attributes of the primitives before the
drawing of any primitive is performed.  GpiSetAttrs allows you to not only
specify the primitive for which the attributes are going to be set, but also,
the settings for the specific attributes. GpiQueryAttrs returns the current
values of specified attributes for specified primitives.

Two other functions, GpiSetAttrMode and GpiQueryAttrMode, enable you to define
or query the attribute mode settings, AM_PRESERVE and AM_NOPRESERVE.  The
AM_PRESERVE setting preserves the value of an attribute any time that attribute
is changed.  The previous value can be recovered easily if, for example, you
need 6 dotted lines, 1 solid line, then 6 more dotted lines.  The AM_NOPRESERVE
setting discards the previous value of an attribute once the value is changed.
The values of the attributes are presentation space resources.


ΓòÉΓòÉΓòÉ 2.2. Using Presentation Spaces ΓòÉΓòÉΓòÉ

You can use presentation-space functions to:

o Create a normal, micro, or cached micro presentation space
o Delete, save, or restore a presentation space
o Define or determine the presentation space attributes.


ΓòÉΓòÉΓòÉ 2.2.1. Obtaining and Creating a Presentation Space ΓòÉΓòÉΓòÉ

Refer to the OS/2 2.0 Programming Guide, Volume II  for details and sample code
on how to obtain and create presentation spaces.


ΓòÉΓòÉΓòÉ 2.2.2. Deleting a Presentation Space ΓòÉΓòÉΓòÉ

A presentation space consumes a considerable amount of memory; you should
delete it when your application no longer requires it.  Delete either a normal
or micro presentation space with GpiDestroyPS.

When you finish using a cached micro presentation space that you accessed with
WinGetPS, release it with WinReleasePS.  You need not delete a presentation
space that you accessed with WinBeginPaint.  PM does this for you when you call
WinEndPaint.


ΓòÉΓòÉΓòÉ 2.2.3. Saving and Restoring a Presentation Space ΓòÉΓòÉΓòÉ

You can save certain attributes and resources of a presentation space, modify
its fields, draw in the modified presentation space, then restore it with
GpiSavePS and GpiRestorePS.  When you call GpiSavePS, the graphics engine
copies the following items from the current presentation space onto a special
stack:

o Primitive attributes
o Transformation matrixes
o Viewing limit
o Clip path
o Clip region
o Current position
o Loaded logical color table
o Loaded logical font.

You can push the contents of a presentation space on the stack as many times as
is necessary.  GpiRestorePS pops the contents of a presentation space off the
stack.


ΓòÉΓòÉΓòÉ 2.2.4. Presentation Spaces Review ΓòÉΓòÉΓòÉ

The following table summarizes the features and restrictions of each type of
presentation space.

Presentation Space Features and Restrictions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFeature/Restriction ΓöéNormal       ΓöéStandard     ΓöéCached Micro  Γöé
Γöé                    Γöé             ΓöéMicro        Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevice types        ΓöéAny device   ΓöéAny device   ΓöéVideo-display Γöé
Γöésupported           Γöé             Γöé             Γöéwindow only   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNumber of supported ΓöéMultiple     ΓöéOne          ΓöéOne           Γöé
Γöédevices             Γöé             Γöé             Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAssociation         ΓöéAssociate andΓöéAssociate at ΓöéN/A.          Γöé
Γöé                    Γöédisassociate Γöécreation;    Γöé              Γöé
Γöé                    Γöéas required. Γöécannot       Γöé              Γöé
Γöé                    Γöé             Γöédisassociate.Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetained graphics   ΓöéYes          ΓöéNo           ΓöéNo            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAvailable GPI       ΓöéAll functionsΓöéAll except   ΓöéAll except    Γöé
Γöéfunctions           Γöé             Γöésegment      Γöésegment       Γöé
Γöé                    Γöé             Γöéfunctions    Γöéfunctions     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMemory              ΓöéHighest      ΓöéMedium memoryΓöéQuickest      Γöé
Γöéconsiderations      Γöémemory usage Γöéusage        Γöéallocation    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 2.3. About Device Contexts ΓòÉΓòÉΓòÉ

Device contexts link presentation spaces to devices by converting
device-independent presentation space information into device-dependent
information.  This conversion occurs in the presentation driver, a low-level
program that is transparent to the application.  A presentation driver is a
device-driver code that converts the application commands into output commands
specific for each output device.

After creating a device context, it must be associated with a presentation
space before the drawing (or primitives) can be printed or displayed.  When a
presentation space and a device context are associated with each other, any
output you direct to the presentation space is directed automatically at the
device context and displayed on the physical device. For example, before you
can draw a picture in a display window, the picture's graphics presentation
space must be associated with the window's device context.

Device contexts also give applications access to important device information
such as screen dimensions or printer capabilities.

As with presentation spaces, there are three types of device contexts:

o Cached
o Window
o Normal.


ΓòÉΓòÉΓòÉ 2.3.1. Cached Device Contexts ΓòÉΓòÉΓòÉ

A cached device context is 1 that already is associated with a cached
presentation space when that space is obtained from the cache.


ΓòÉΓòÉΓòÉ 2.3.2. Window Device Contexts ΓòÉΓòÉΓòÉ

Window device contexts are a special type, in that they are the only device
contexts obtained with WinOpenWindowDC.  As their name implies, the output
device they represent is a display window.  WinOpenWindowDC accepts a window
handle as input, and returns the window device context handle.  The window
device context handle can then be associated with a standard micro presentation
space or a normal presentation space.

The window device context is closed automatically when its associated window is
deleted.


ΓòÉΓòÉΓòÉ 2.3.3. Normal Device Contexts ΓòÉΓòÉΓòÉ

A normal device context (also called a standard or noncached device context)
links a presentation space with any nonwindow output device.  Use DevOpenDC to
obtain a device context handle to 1 of 6 normal device contexts listed in the
following table. Each of the 6 normal device contexts must be closed by
DevCloseDC before your application is closed.

Normal Device Contexts

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDC Type             ΓöéPurpose             ΓöéUsage               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéQueued              ΓöéLinks a presentationΓöéApplications use    Γöé
Γöé                    Γöéspace with a printerΓöéqueued device       Γöé
Γöé                    Γöéor plotter shared byΓöécontexts to offload Γöé
Γöé                    Γöémultiple            Γöéprinting control    Γöé
Γöé                    Γöéapplications sendingΓöéfrom the            Γöé
Γöé                    Γöéspooled print jobs  Γöéapplication.        Γöé
Γöé                    Γöéto the print queue. Γöé                    Γöé
Γöé                    ΓöéQueued device       Γöé                    Γöé
Γöé                    Γöécontexts store printΓöé                    Γöé
Γöé                    Γöéjobs by using a     Γöé                    Γöé
Γöé                    Γöéprogram called printΓöé                    Γöé
Γöé                    Γöéspooler, which keepsΓöé                    Γöé
Γöé                    Γöétrack of the order  Γöé                    Γöé
Γöé                    Γöéin which the jobs   Γöé                    Γöé
Γöé                    Γöéarrive at the       Γöé                    Γöé
Γöé                    Γöéprinter and in whichΓöé                    Γöé
Γöé                    Γöéthey are printed.   Γöé                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDirect              ΓöéLinks a presentationΓöéApplications        Γöé
Γöé                    Γöéspace with a printerΓöénormally do not use Γöé
Γöé                    Γöéor plotter, directlyΓöédirect device       Γöé
Γöé                    Γöébypassing the       Γöécontexts, unless    Γöé
Γöé                    Γöéspooler and print   Γöéthey are avoiding   Γöé
Γöé                    Γöéqueue.  A direct    Γöéthe queue (for      Γöé
Γöé                    Γöédevice context is   Γöésecurity reasons) orΓöé
Γöé                    Γöéused by the spooler Γöégoing directly to a Γöé
Γöé                    Γöéto process jobs as  Γöédedicated machine.  Γöé
Γöé                    Γöéthey are removed    Γöé                    Γöé
Γöé                    Γöéfrom the print      Γöé                    Γöé
Γöé                    Γöéqueue.              Γöé                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInformation         ΓöéLinks a presentationΓöéAn application can  Γöé
Γöé                    Γöéspace with a printerΓöéuse an information  Γöé
Γöé                    Γöéor plotter, directlyΓöédevice context with Γöé
Γöé                    Γöéenabling device     Γöélower memory        Γöé
Γöé                    Γöéinformation to be   Γöéoverhead, rather    Γöé
Γöé                    Γöéqueried, but        Γöéthan use a direct   Γöé
Γöé                    Γöéproducing no output Γöédevice context,     Γöé
Γöé                    Γöéon the device.      Γöéwhich could provide Γöé
Γöé                    Γöé                    Γöéthe same            Γöé
Γöé                    Γöé                    Γöéinformation.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMemory              ΓöéLinks a presentationΓöéApplications use    Γöé
Γöé                    Γöéspace with a bit    Γöémemory device       Γöé
Γöé                    Γöémap.                Γöécontexts for drawingΓöé
Γöé                    Γöé                    Γöéto the bit map and  Γöé
Γöé                    Γöé                    Γöéusing it as a sourceΓöé
Γöé                    Γöé                    Γöéor target of BitBlt Γöé
Γöé                    Γöé                    Γöéoperations.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetafile            ΓöéA special device    ΓöéOnly applications   Γöé
Γöé                    Γöécontext that enablesΓöéthat use metafiles  Γöé
Γöé                    Γöéa picture output to Γöéuse metafile device Γöé
Γöé                    Γöéits associated      Γöécontexts.           Γöé
Γöé                    Γöépresentation space  Γöé                    Γöé
Γöé                    Γöéto be recorded in a Γöé                    Γöé
Γöé                    Γöémetafile for        Γöé                    Γöé
Γöé                    Γöéinterchange for     Γöé                    Γöé
Γöé                    Γöéfuture use.         Γöé                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetafile_NoQuery    ΓöéFunctionally        ΓöéIf attributes of theΓöé
Γöé                    Γöéidentical to        Γöépresentation space  Γöé
Γöé                    Γöémetafile; however,  Γöéare not to be       Γöé
Γöé                    Γöéquerying of         Γöéqueried, this deviceΓöé
Γöé                    Γöépresentation space  Γöécontext offers      Γöé
Γöé                    Γöéattributes is not   Γöéimproved performanceΓöé
Γöé                    Γöéallowed.            Γöéover metafile.      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 2.4. Using Device Contexts ΓòÉΓòÉΓòÉ

In addition to associating or disassociating presentation spaces with device
contexts, you can use device context functions to:

o Obtain or create a device context
o Associate a device context with a presentation space
o Close a device context
o Retrieve information about a device's capabilities.

See Associating a Presentation Space for details on associating and
disassociating device contexts and presentation spaces.


ΓòÉΓòÉΓòÉ 2.4.1. Creating a Device Context ΓòÉΓòÉΓòÉ

You can create a normal device context by calling DevOpenDC.  This function
requires that you specify 1 of the 5 normal types.  It also requires that you
pass certain device-initialization data, including a logical address, the
device-driver name, device-driver data, a description of the device type, and
information about the queue (if the device is a queued device).  The
device-initialization data is passed in a DEVOPENSTRUC structure.

The following figure is an example of this structure.

    typedef struct _DEVOPENSTRUC {   /* dop                          */
        PSZ      pszLogAddress       /* Logical-device address       */
        PSZ      pszDriverName       /* Device-driver name           */
        PDRIVDATA  pdriv             /* Pointer to extra driver data */
        PSZ      pszDataType         /* Type of queued data          */
        PSZ      pszComment          /* Optional spooler info        */
        PSZ      pszQueueProcName    /* Queue-processor name         */
        PSZ      pszQueueProcParams  /* Queue-processor arguments    */
        PSZ      pszSpoolerParams    /* Spooler arguments            */
        PSZ      pszNetworkParams    /* Network arguments            */
    } DEVOPENSTRUC;

DEVOPENSTRUC Structure

The last four fields in this structure apply only to queued devices.

The following figure shows how to create a nondisplay device context for a
printer.


    HDC hdcPrinter;                     /* Handle of printer device context    */
    HAB hab;                            /* Anchor-block handle                 */
    DEVOPENSTRUC dop;                   /* Device information                  */

    dop.pszLogAddress = "lpt1";         /* Logical-device address              */
    dop.pszDriverName = "EPSON";        /* Device-driver name                  */
    dop.pdriv = (PDRIVDATA) NULL;       /* Pointer to driver data              */
    dop.pszDataType = "PM_Q_STD";       /* Standard queued data                */

    hdcPrinter = DevOpenDC(hab,
                           OD_DIRECT,   /* Direct device type                  */
                           "*",         /* No data in OS2.INI                  */
                           4,           /* Use first 4 fields in dop structure */
                           (PDEVOPENDATA) &dop,
                           (HDC) NULL);

Creating a Printer Device Context

The following figure is an example of how to create a standard device context
for a metafile.


    HDC hdcMeta;                                 /* Handles of metafile       */
                                                 /*    and window DCs         */
    HAB hab;                                     /* Anchor-block handle       */
    DEVOPENSTRUC dop;                            /* Device information        */

    dop.pszLogAddress = NULL;                    /* Logical-device address    */
    dop.pszDriverName = "DISPLAY";               /* Device-driver name        */

    hdcMeta = DevOpenDC(hab,
                        OD_METAFILE,             /* Metafile DC               */
                        "*",                     /* No data in OS2.INI        */
                        2,                       /* Use first 2 fields in dop */
                        (PDEVOPENDATA) &dop,     /* Structure for system info */
                        NULL)                    /* Compatible with screen    */

Creating a Metafile Device Context


ΓòÉΓòÉΓòÉ 2.4.2. Associating Presentation Spaces with Device Contexts ΓòÉΓòÉΓòÉ

Drawing graphic objects requires a presentation space and a device context to
direct output to a specific instance of an output device, such as a display
window or a printer. This association enables the device context to identify
the output device for that presentation space. Further, the device context
identifies the particular instance of the output device, such as a printer or
display window.

A presentation space can be associated with only one device context at a time;
the reverse is also true:  a device context can be associated with only one
presentation space at a time.

The following figure shows how a presentation space is associated with a window
device context. It is then disassociated from the window device context and
associated with a printer device context. It cannot be associated with both
device contexts simultaneously.

    WM_Create:
         hdcScreen = WinOpenWindowsDC (hwnd);
         phs = GpiCreatePS (...GPIA.Assoc);
          .
          .
          .

    WM_COMMAD:

      Case IDM_File PRINT:                       /* Device selection        */
         hdcPrinter = DevOpenDC (...);
         GpiAssociate (hps, NULL);               /* Disconnect from screen  */
         GpiAssociate (hps, hdcPrinter);         /* Connect to printer      */
          .
          .                                      /* Output                  */
          .
         GpiAssociate (hps, NULL);               /* Disconnect from print   */
         GpiAssociate (hps, hdcScreen);          /* Reconnect to screen     */
          .
          .
          .

    WM_PAINT:
         WinBeginPaint (hwnd, hps, NULL);
          .
          .                                      /* Output                  */
          .


Associating, Disassociating, and Reassociating a Presentation Space

The following figure shows how to open a window device context and associate it
with a normal presentation space.

    HDC hdcWin;            /* Window device-context handle     */
    HPS hpsWin;            /* Normal-presentation-space handle */
    HWND hwndClient;       /* Client-window handle             */
    HAB hab;               /* Anchor-block handle              */
    SIZEL sizlPage;        /* Presentation page                */

    hdcWin = WinOpenWindowDC(hwndClient);
    hpsWin = GpiCreatePS(hab, hdcWin, &sizlPage,
                         PU_LOENGLISH | GPIA_ASSOC);


Associating a Cached Device Context with a Normal Presentation Space

Note:  This type of code is used when the device context is defined before the
       presentation space.

WinOpenWindowDC can be called only once for a particular window and returns an
error if called a second time. WinQueryWindowDC can be used to obtain a window
device context previously allocated using WinOpenWindowDC. The following figure
shows how to create a presentation space with page units of 0.01 inch
(PU_LOENGLISH) and associate it with a printer device context. As input to
GpiCreatePS, you supply the height and width of the presentation page.


    HAB hab;          /* Anchor-block handle         */
    HPS hpsPrinter;   /* Presentation-space handle   */
    HDC hdcPrinter;   /* Device-context handle       */
    SIZEL sizlPage;   /* Page structure              */
    .
    .
    .
    hpsPrinter = GpiCreatePS(hab, hdcPrinter, &sizlPage,
       PU_LOENGLISH | GPIA_ASSOC);


Creating a Normal Presentation Space


ΓòÉΓòÉΓòÉ 2.4.3. Closing a Device Context ΓòÉΓòÉΓòÉ

To close a device context that your application opened with DevOpenDC, call
DevCloseDC.  However, you should not try to close a device context that you
opened with WinOpenWindowDC. The operating system does automatically when the
associated window is deleted.


ΓòÉΓòÉΓòÉ 2.4.4. Determining Device Capabilities ΓòÉΓòÉΓòÉ

Once you have created a device context for a particular output device, you can
determine the capabilities of that device by calling DevQueryCaps. This
function retrieves the following information:

o Device technology (whether the device is a raster or vector device)
o Maximized window dimensions (if the device is a video display)
o Page dimensions (if the device is a printer or plotter)
o Character-box dimensions
o Marker-box dimensions
o Pel resolution
o Color capabilities
o Mix-mode capabilities.

You can use this information, for example, to select fonts, set up the
presentation page, or create a new logical color table.


ΓòÉΓòÉΓòÉ 2.5. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the presentation spaces and device contexts
functions.

Presentation Space and Device Context Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevCloseDC              ΓöéCloses a device context that was    Γöé
Γöé                        Γöéopened by DevOpenDC.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevOpenDC               ΓöéCreates a nondisplay device context.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevQueryCaps            ΓöéDetermines the capabilities of an   Γöé
Γöé                        Γöéoutput device.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevQueryHardcopyCaps    ΓöéDetermines the form (or paper size) Γöé
Γöé                        Γöéand related information of printers Γöé
Γöé                        Γöéand plotters.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiAssociate            ΓöéAssociates the current presentation Γöé
Γöé                        Γöéspace with a device context.        Γöé
Γöé                        ΓöéDisassociates the current           Γöé
Γöé                        Γöépresentation space by passing a nullΓöé
Γöé                        Γöédevice context.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS             ΓöéCreates the specified type of       Γöé
Γöé                        Γöépresentation space.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDestroyPS            ΓöéDeletes a normal presentation space Γöé
Γöé                        Γöéor standard micro presentation spaceΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMove                 ΓöéExplicitly sets the current         Γöé
Γöé                        Γöéposition.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPS              ΓöéDetermines the size, units, and     Γöé
Γöé                        Γöéother options of a presentation     Γöé
Γöé                        Γöéspace.                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiResetPS              ΓöéResets the presentation space.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRestorePS            ΓöéPops the contents of a saved        Γöé
Γöé                        Γöépresentation space off a stack.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSavePS               ΓöéSaves items from the current        Γöé
Γöé                        Γöépresentation space onto an          Γöé
Γöé                        Γöéaccessible stack.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCurrentPosition   ΓöéExplicitly updates the current      Γöé
Γöé                        Γöéposition.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPS                ΓöéSets the presentation page size,    Γöé
Γöé                        Γöéunits, and format.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinBeginPaint           ΓöéAllocates a cached micro            Γöé
Γöé                        Γöépresentation space for WM_PAINT     Γöé
Γöé                        Γöéprocessing (if an existing          Γöé
Γöé                        Γöépresentation space is not being     Γöé
Γöé                        Γöéused) and establishes the update    Γöé
Γöé                        Γöéregion for the paint.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinEndPaint             ΓöéReturns any cached micro            Γöé
Γöé                        Γöépresentation space to the cache, andΓöé
Γöé                        Γöésignals completion of the WM_PAINT  Γöé
Γöé                        Γöéprocessing.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetPS                ΓöéAllocates a cached micro            Γöé
Γöé                        Γöépresentation space from the cache.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinGetScreenPS          ΓöéAllocates a cached micro            Γöé
Γöé                        Γöépresentation space from the cache   Γöé
Γöé                        Γöéfor the entire display screen.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinOpenWindowDC         ΓöéCreates a device context for a      Γöé
Γöé                        Γöédisplay window.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinQuerySysValue        ΓöéCopies the size of the client area  Γöé
Γöé                        Γöéof the desktop window to the        Γöé
Γöé                        Γöépresentation page.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinQueryWindowDC        ΓöéDetermines the device context for a Γöé
Γöé                        Γöédisplay window when WinOpenWindowDC Γöé
Γöé                        Γöéhas been called previously.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinReleasePS            ΓöéReturns a cached micro presentation Γöé
Γöé                        Γöéspace to the cache.                 Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the presentation
space and device context functions.

Presentation Space and Device Context Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDEVOPENSTRUC            ΓöéContains device-initializing data   Γöé
Γöé                        Γöéfor non-display device contexts.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSIZEL                   ΓöéSpecifies the dimensions of the     Γöé
Γöé                        Γöépresentation space's presentation   Γöé
Γöé                        Γöépage.                               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3. Line and Arc Primitives ΓòÉΓòÉΓòÉ

Line and arc primitives are graphics building blocks for creating pictures that
consist of objects such as polygons, circles, fillets, ellipses, and other
geometric figures.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Color and mix attributes
o Area primitives.


ΓòÉΓòÉΓòÉ 3.1. About Line and Arc Primitives ΓòÉΓòÉΓòÉ

Simple drawing applications use line and arc primitives as drawing tools; they
are useful, for example, in spreadsheet applications for constructing pie
charts, bar charts, and graphs, as shown in the following figure.

Sample Pie Chart Created with Line and Arc Primitives

Following are more illustrations that were drawn using line and arc primitives.

Sample Bar Graph Created with Line and Arc Primitives

Computer-aided-design (CAD) applications combine line and arc primitives to
draw such complex pictures as schematic diagrams for electrical wiring,
blueprints for building sites, and cross-sectional views of machinery.

Sample Blueprint Created with Line and Arc Primitives

Line and arc primitives are actually two families of primitives that contain
many variations of straight lines and curved lines, respectively.  They are
presented together in this chapter because all the variations are governed by
the attributes found in the data structure LINEBUNDLE.

An application draws the line and arc primitives by first issuing GpiMove or
GpiSetCurrentPosition, either of which sets the current position to a specified
starting point.  GpiMove ignores the AM_PRESERVE mode; whereas
GpiSetCurrentPosition saves the current position if the AM_PRESERVE mode is
set.  The more sophisticated function, GpiPolyLineDisjoint, contains its own
starting point and does not need to be preceded by GpiMove or
GpiSetCurrentPosition.

Prior to calling a line or arc function, the current position can be determined
with GpiQueryCurrentPosition.


ΓòÉΓòÉΓòÉ 3.1.1. Attributes of Line and Arc Primitives ΓòÉΓòÉΓòÉ

The attributes of the line and arc primitives contained in LINEBUNDLE are:

o Line width
o Geometric width
o Line type
o Line end
o Line join
o Line color
o Line mix.

The line end and line join attributes apply only to lines drawn in a primitive
called a path. These attributes and paths themselves are explained in Paths.

When an application creates a presentation space, the line and arc attributes
are set to the default values shown in the following table.

Line Attribute Default Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute      ΓöéDefault Value ΓöéFunction that Redefines        Γöé
Γöé               Γöé              ΓöéAttribute                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWidth          Γöé1.0           ΓöéGpiSetLineWidth                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGeometric widthΓöéNone          ΓöéGpiSetLineWidthGeom            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéType           ΓöéLINETYPE_SOLIDΓöéGpiSetLineType                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéColor          ΓöéCLR_NEUTRAL   ΓöéGpiSetAttrs (LBB_COLOR)        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMix attribute  ΓöéFM_OVERPAINT  ΓöéGpiSetAttrs (LBB_MIX_MODE)     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3.1.2. Line Width and Geometric Width ΓòÉΓòÉΓòÉ

The operating system defines two types of lines:  cosmetic and geometric,
representing two separate concepts.

Cosmetic lines represent the mathematical ideal of a line being an entity with
only one dimension-length.  When cosmetic lines are drawn, they usually are
only one pel wide.

The line width attribute provides a visual method of distinguishing different
types of lines. For example, on a map, roads might be drawn thicker than
railroad tracks. The line width attribute defines a multiplier to be applied to
the normal (or default) line width. Your application can determine the cosmetic
line width by calling GpiQueryLineWidth.

There are certain devices that do not define the thickness of cosmetic lines in
terms of a number of pels.  The PM interface interprets the specified width for
these devices as shown in the following table:

Line-Width Attributes as Interpreted by PM

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIdentifer               ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_DEFAULT       ΓöéThe default width for the device.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_NORMAL        ΓöéThe line width equivalent to a      Γöé
Γöé                        Γöémultiplier of 1.  Identical to      Γöé
Γöé                        ΓöéLINEWIDTH_DEFAULT unless changed    Γöé
Γöé                        Γöéwith GpiSetDefAttrs.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEWIDTH_THICK         ΓöéThe line width equivalent to a      Γöé
Γöé                        Γöémultiplier greater than 1.          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Your application can set the cosmetic line width with either a multiplier or an
identifier value using GpiSetLineWidth.  Since the line represents a widthless
ideal, the actual drawn width is a fixed value.  The line width remains
unchanged when you increase the size of, or zoom in on, a graphics object.  The
cosmetic line width is not subject to transformations.

In contrast, geometric lines represent an area whose thickness is equal to the
specified line width.  Geometric lines are subject to changes in scale through
transformations, in the same manner as geometric figures.

The width of a geometric line does not have a default value.  Width is treated
as a line attribute for programming convenience, but it actually is a geometric
property.  A line width is set with GpiSetLineWidthGeom; if a width is already
specified, that width can be determined with GpiQueryLineWidthGeom.

To use geometric line width, the lines are assembled into a path. When you use
a path to define wide lines, you can specify the following:

o Geometric width for the lines, using the geometric line width attribute,
o Style of the line ends, using the line end attribute
o Style of the junctions of the lines, using the line join attribute.

These three attributes apply only to geometric lines drawn using paths.


ΓòÉΓòÉΓòÉ 3.1.3. Line Types ΓòÉΓòÉΓòÉ

Line type, also called line style, defines the way a line or arc is drawn:  as
a solid line, a series of dashes, a series of dots, or a combination of dashes
and dots.

The line type for all subsequent line primitives is selected using
GpiSetLineType.  If you want to change the line type to LINETYPE_DOT, for
example, any line or arc primitive subsequently drawn is drawn as a dotted
line. The following table illustrates the nine standard line types provided by
PM.

Note:  You cannot define other line types for PM applications.

Standard Line Types

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType                    ΓöéIdentifer               ΓöéLong Value  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDotted line             ΓöéLINETYPE_DOT            Γöé1L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéShort-dashed line       ΓöéLINETYPE_SHORTDASH      Γöé2L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDash-dot line           ΓöéLINETYPE_DASHDOT        Γöé3L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDouble-dotted line      ΓöéLINETYPE_DOUBLEDOT      Γöé4L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLong-dashed line        ΓöéLINETYPE_LONGDASH       Γöé5L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDash-double-dot line    ΓöéLINETYPE_DASHDOUBLEDOT  Γöé6L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid line              ΓöéLINETYPE_SOLID          Γöé7L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInvisible line          ΓöéLINETYPE_INVISIBLE      Γöé8L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAlternate pels on       ΓöéLINETYPE_ALTERNATE      Γöé9L          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The default line type (LINETYPE_DEFAULT) is identical to the LINETYPE_SOLID
type, and has a long value of 0L.  The error line type (LINETYPE_ERROR) has a
long value of -1L. The following figure illustrates the nine line types. Your
application can determine the current line type using GpiQueryLineType.

The Nine Line Types


ΓòÉΓòÉΓòÉ 3.1.4. Line Color and Mix Attributes ΓòÉΓòÉΓòÉ

The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface. Both attributes also are described in Color and Mix Attributes.

The line color defines the color used to draw the output from any of the
operating system's line functions. When a presentation space is created, the
line color initial default is black. Unlike certain other primitives, the line
and arc primitives do not have a background color. The current color of the
drawing surface automatically plays a greater role in the appearance of line
and arc primitives than in those primitives that do have a background color.
Specifically, when an application draws a dotted or dashed line, the color that
appears between the dots or dashes is the current drawing-surface color, as
shown in the following figure.

Line and Arc Primitives

Line and arc primitives have only a color attribute for the actual line. The
mix attribute controls the combination of line color with drawing surface
color.

When a presentation space is created, the line mix attribute initial default is
FM_OVERPAINT. The overpaint mix attribute specifies that the line color is not
modified by the color of the drawing surface. If the line mix attribute is
changed, the line color is mixed with colors that are already on the drawing
surface.

To specify a new color or mix attribute issue GpiSetAttrs. This function
accepts as input the type of primitive, for example PRIM_LINE, a list of
attributes that are to be changed, a list of attributes that are to be set to
their default values, and the values for the attributes that are to be changed.
GpiSetAttrs is useful for specify colors and mix attributes just for a specific
data structure, for example the LINEBUNDLE structure. GpiSetAttrs also provides
some protection against invalid colors as described in Presentation Manager
Programming Reference.

To determine the current line color and mix attribute issue GpiQueryAttrs. This
function accepts as input the primitive type and the attributes in question. It
returns as output an array of values for the specifically queried attributes.

To reset the default line color and mix attribute, just as with any other
attribute specified in the LINEBUNDLE data structure, issue GpiSetDefAttrs.
This function accepts as input the type of primitive, for example PRIM_LINE,
the attributes to be changed, and the values that will become the new default
values. The changing of default values is important when working with segments,
described in Creating and Drawing Retained Graphics and Editing Retained
Graphics and Graphics Segments. Changing the default values during a series of
drawing functions is not recommended.

The line color and mix attribute also can be specified with GpiSetColor and
GpiSetMix, respectively. However, those two functions have the disadvantage of
specifying the color and mix attribute for all primitive xxxBUNDLE data
structures that have a component for foreground color and foreground mix
attribute. The queries, GpiQueryColor and GpiQueryMix, determine the color and
mix attribute as specified by GpiSetColor and GpiSetMix. If the line color or
mix attribute is specified individually, the aforementioned queries can return
a value inconsistent with the current line color or mix attribute.


ΓòÉΓòÉΓòÉ 3.1.5. Line Primitive Family ΓòÉΓòÉΓòÉ

The following table describes the three variants of the basic line primitive
and the functions that draw them.

Functions that Draw Straight Lines

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants    ΓöéFunction                ΓöéDescription                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines       ΓöéGpiLine                 ΓöéDraws a single line from the      Γöé
Γöé            Γöé                        Γöécurrent position to a specified   Γöé
Γöé            Γöé                        Γöépoint.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPolylines   ΓöéGpiPolyLine             ΓöéDraws a series of connected lines,Γöé
Γöé            Γöé                        Γöéfrom the current position through Γöé
Γöé            Γöé                        Γöésuccessive points.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(series of  ΓöéGpiPolyLineDisjoint     ΓöéDraws a series of unconnected     Γöé
Γöélines)      Γöé                        Γöélines.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBoxes       ΓöéGpiBox                  ΓöéDraws a rectangular box with one  Γöé
Γöé            Γöé                        Γöécorner at the current position.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

When the operating system draws a line, it includes the pels at the starting
and ending points of the line.  The algorithm used to draw the rest of the line
depends on the device driver.  For example, a driver for a raster device might
use a modified Bresenham algorithm to draw a line; but a driver for a vector
device, such as a plotter, simply would connect the starting and ending points
of the line.  In all cases, the result is a line primitive that looks the same
from device to device.


ΓòÉΓòÉΓòÉ 3.1.5.1. Lines ΓòÉΓòÉΓòÉ

GpiLine draws a line from the current position to a specified end point, as
shown in the following figure. After drawing the line, the current position is
at the end point specified by GpiLine.

GpiLine

The current position is (4,3), and the specified end point of GpiLine is (9,7).
When the line has been drawn, (9,7) becomes the current position.

To draw a single point, you can issue GpiLine, with an end point identical to
the current position, as shown in the following figure. The current position
can be determined using GpiQueryCurrentPosition.

GpiLine Used to Draw a Single Point


ΓòÉΓòÉΓòÉ 3.1.5.2. Polylines ΓòÉΓòÉΓòÉ

GpiPolyLine draws a sequence of connected lines, starting at the current
position and passing through a series of specified coordinate positions as
shown in the following figure. After drawing the series of lines, the current
position is at the end point of the last line specified by GpiPolyLine.

If you are drawing a graph that has five connected lines, you can issue
GpiPolyLine once rather than GpiLine five times.  GpiPolyLine accepts as input
a number of points and an array of point coordinates.

GpiPolyLine

The starting position is (2,2), and the polyline is drawn through (4,4), (6,4),
(8,6), and (10,3).  The new current position is (10,3).

GpiPolyLineDisjoint is a new function that eliminates having to use a series of
GpiMove and GpiLine functions to draw multiple lines that are not connected.
GpiPolyLineDisjoint accepts as input an even number, the number of points, and
an array of point coordinates.  The first point in a point-pair is the starting
point; the second, the end point of that line segment.  Upon completion, the
end point of the final line becomes the current position. The following figure
shows the results of a GpiPolyLineDisjoint call.

GpiPolylineDisjoint

A graph with discontinuities.


ΓòÉΓòÉΓòÉ 3.1.5.3. Boxes ΓòÉΓòÉΓòÉ

At its simplest, GpiBox draws a rectangular box with one corner at the current
position and the diagonally-opposite corner at a position that you specify.
The sides of the box are parallel to the x- and y-axes.  Like GpiPolyLine,
GpiBox lets you draw a number of connected lines using a single function rather
than four separate GpiLine functions.  The current position is unchanged by
GpiBox.

Note:  The start and end position of any closed shape are always the same;
       therefore, the current position is unchanged after drawing a closed
       figure.

The GpiBox primitive is shown in the following figure.

The Box

The current position is (3,2) and the corner position is at (8,6).  When the
box has been drawn, the current position remains at (3,2).

In addition to the corner position, GpiBox accepts as input an option for
rounded corners and for filled interior.  The PM programming interface rounds
the corners of a box by drawing an elliptical section in place of the square
corner.  Two long values, IHRound and IVRound, represent the horizontal and
vertical length of the full axis of the ellipse used to round each corner.  If
the two values are equal, a quarter-circle is used for the rounding.  If the
two values are 0, no rounding is performed. The following figure shows an
example of rounding corners using a quarter-circle.

Quarter-Circle Box-Corner Rounding

The current position is (20,20).  GpiBox is issued with a corner position of
(65,60) and an identical vertical and horizontal rounding value of 26.

The following figure shows the complete result. The intermediate steps are not
visible to the user of your application.

Box with Rounded Corners

All four corners are rounded with identical values.

Since GpiBox can be used to define a closed figure, it also accepts as input a
long value signifying a filled interior.  The long value, IControl can be any
of the following:

Value               Description

DRO_OUTLINE         Draw the box only.

DRO_FILL            Fill the box interior only.

DRO_OUTLINEFILL     Draw the box and fill its interior.

The pattern that fills the interior and other drawing options are controlled by
the data structure AREABUNDLE.  Areas are described in Area and Polygon
Primitives. GpiFullArc is the only other line and arc primitive that can be
used to define a closed figure.


ΓòÉΓòÉΓòÉ 3.1.6. Attributes of Arc Primitives ΓòÉΓòÉΓòÉ

The arc primitive shares width, type, and color and mix attributes with line
primitives.  For example, if you issue GpiSetLineType to change the line type
to LINETYPE_DASHDOT, all subsequent arcs are drawn with a dash-dot line.  In
addition to the line attributes defined in the LINEBUNDLE data structure, arc
primitives in the simple-arc family are influenced by the values in the
ARCPARAMS data structure.  Arc primitives in the multiple-arc family have a
different method of construction and are not influenced by ARCPARAMS.

In terms of geometrical pictures, the simple arcs contain full or partial:

Circles        Closed curves whose center is equidistant from every point on
               the curve.

Ellipses       Closed curves defined by two fixed points such that the sum of
               the distances from any point on the curve to the two fixed
               points is constant.

Multiple arcs contain:

Fillets        Curves that are tangential to the two lines defined by three
               control points.

Splines        Curves that, given four control points, are tangent to the first
               and last of three intersecting lines.

There are three simple arc operations that begin with a unit circle that lies
at the origin of world coordinate space.  This unit circle defines the current
arc on which subsequent full, partial, and 3-point arcs are based.  Your
application can define the following attributes of the current arc with
GpiSetArcParams:

o Shape
o Orientation
o Size
o Drawing direction.

GpiSetArcParams accepts as input a ARCPARAMS data structure that has four
parameters (p, q, r, and s). Of the four:

o p scales in the x-direction
o q scales in the y-direction
o r and s are shear components

The mathematical origins of the parameters are illustrated in the following
figure.

The ARCPARAMS Values in World Coordinates

The values were derived from the major and minor axis of an ellipse.

An application can determine the current arc parameters with GpiQueryArcParams,
which copies the current arc parameters to their corresponding fields in the
supplied ARCPARAMS structure.  The application can set the arc parameters with
GpiSetArcParams.  This function accepts as input a copy of the ARCPARAMS
structure that contains the new arc parameters.  The default values of p, q, r,
and s, unless changed by GpiSetDefArcParams, define a unit circle:

o p and q are 1
o r and s are 0.

The arc parameters define a transformation that is applied to each point on the
perimeter of the unit circle.  For any point (x,y) on the perimeter of the unit
circle, there exists a new point (x',y'), as determined by the following two
linear equations:

x' = p x x + r x y
y' = s x x + q x y

These parameters form a 2-by-2 matrix,


Γöî      ΓöÉ
Γöé p  r Γöé
Γöé s  q Γöé
Γöö      Γöÿ

that scales and shears simple arcs.

Note:  This transformation matrix is not related to the general transformation
       functions that move objects through coordinate spaces.  It is a special
       purpose matrix that transforms the shape and size of the imaginary unit
       circle.  The transformed unit circle, also called the current arc, is
       then used to define the shape and size of the simple arc functions in
       world coordinates.

After an arc has been described in world coordinates, it can be transformed
with the transformation functions, just as any other primitive can.

For detailed information about transformations and their use, see Coordinate
Spaces and Transformations.

A transformation is orthogonal when:

(p x r) + (s x q) = 0

If orthogonal, the line from the origin (0,0) to the point (p,s) is either:

o The radius of a circle
o Half the major or minor axis of an ellipse;

and, the line from the origin to the point (r,q) is either:

o The radius of a circle
o Half the minor or major axis of an ellipse.

An orthogonal transformation does not guarantee that the shape of an object as
defined by an application will be the same as the shape of the object on the
output device.  For example, if the page units in the application are PU_PELS,
and the pels on the device are rectangular (but not square), calling GpiFullArc
produces an ellipse-not a circle- even when the arc parameters are set to their
default values.

The product of the 2-by-2 matrix multiplication influences the direction of any
arc based on the current arc, except a 3-point arc. The following table
illustrates this directional influence.

Direction of the Arc

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf...                         ΓöéGpiFullArc and                Γöé
Γöé                              ΓöéGpiPartialArc...              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) is greater than (r x  ΓöéDraw the ellipse              Γöé
Γöés)                            Γöécounterclockwise.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) is less than (r x s)  ΓöéDraw the ellipse clockwise.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(p x q) equals (r x s)        ΓöéDraw a straight line rather   Γöé
Γöé                              Γöéthan an ellipse.              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3.1.7. Simple-Arc Primitive Family ΓòÉΓòÉΓòÉ

The following table describes the three variants of a simple-arc primitive and
the functions that draw them. All are defined, to some extent, by the current
arc parameters. As with line primitives, an application draws simple-arcs by
first issuing GpiMove or GpiSetCurrentPosition to set the current position.

Functions that Draw Simple Arcs

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants    ΓöéFunction      ΓöéDescription                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFull arcs   ΓöéGpiFullArc    ΓöéDraws a circle or an ellipse.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPartial arcsΓöéGpiPartialArc ΓöéDraws a straight line followed by Γöé
Γöé            Γöé              Γöéa section of a circle or ellipse. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé3-point arcsΓöéGpiPointArc   ΓöéDraws an arc through three points.Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3.1.7.1. Full Arcs ΓòÉΓòÉΓòÉ

GpiFullArc draws a complete circle or ellipse with its center at the current
position.  The current position remains unchanged.  Whether GpiFullArc draws a
circle or an ellipse depends on the current arc parameters.  When the current
arc is a circle, GpiFullArc draws a circle; when it is an ellipse, GpiFullArc
draws an ellipse.


ΓòÉΓòÉΓòÉ 3.1.7.1.1. Defining an Ellipse ΓòÉΓòÉΓòÉ


To define an ellipse as the current arc, issue GpiSetArcParams on which the
values (p,s) and (r,q) are the world coordinates of the end points of the major
and minor axes of the ellipse.  For example, current arc parameters of (18,0)
and (0,10) define an ellipse with a major axis of 36 coordinate units and a
minor axis of 20 coordinate units. The resultant ellipse is shown in the
following figure.

The Ellipse

For maximum accuracy, create the axes of an ellipse so that they are at
right-angles to each other.  You can check this by ensuring that the following
equation is always true:

p x r + s x q = 0

So, to check the above example:

0 x 18 + 10 x 0 = 0

You also can define a tilted ellipse as the current arc. None of the current
arc parameters for a tilted ellipse will be 0, though you should still ensure
that the axes of the ellipse are at right-angles to each other. The following
figure shows a tilted ellipse defined with current arc parameters of (8,6) and
(-3,4).

Tilted Ellipse


ΓòÉΓòÉΓòÉ 3.1.7.1.2. Defining a Circle ΓòÉΓòÉΓòÉ


To define a circle as the current arc, (r,q) and (p,s) can be any such value
that they lie on a circle.  For example, if (r,q) and (p,s) are set to (-4, 3)
(3,4), the current arc is a circle with a radius of 5 coordinate units.  For
simplicity, a circle can be defined by specifying current arc parameters where
p is the radius of the circle, and p = q, r = 0, and s = 0. For example, to
define a circle centered on the origin and with a radius of 10 world-coordinate
units, issue GpiSetArcParams with the values (0,10) (10,0).

The default values of the current arc parameters are (0,1) (1,0), which define
a circle with a radius of one world-coordinate unit (a unit circle).


ΓòÉΓòÉΓòÉ 3.1.7.1.3. GpiFullArc Input Parameters ΓòÉΓòÉΓòÉ


GpiFullArc accepts as input a multiplier value, so that the size of the full
arc is increased or decreased in relation to the current arc.  For example, if
the current arc parameters define an ellipse whose major axis is 20 coordinate
units and whose minor axis is 8 coordinate units, a multiplier of 2 in
GpiFullArc creates an ellipse whose major axis is 40 coordinate units and whose
minor axis is 16 coordinate units.

Because the arc parameters are integers when a fraction is required, for
example when rotating an ellipse, greater precision can be obtained by scaling
up the required arc parameter values as much as possible, then using a
multiplier smaller than 1 to scale the ellipse back down to the required size.

With the default arc parameters defining a circle of 1 world coordinate unit,
you can draw a circle of any size by allowing the arc parameters to default,
then specifying the radius of the circle with the GpiFullArc multiplier.  For
example, to draw a circle with a radius of 12 coordinate units, issue
GpiFullArc with a multiplier of 12 and allow the GpiSetArcParams to default.
Since GpiFullArc, like GpiBox, can be used to define a closed figure, it also
accepts as input a long value signifying a filled interior.  The long value,
IControl can be:

Value               Description

DRO_OUTLINE         Draw the arc only.

DRO_FILL            Fill the arc interior only.

DRO_OUTLINEFILL     Draw the arc and fill its interior.

The pattern that fills the interior and other drawing options are controlled by
the data structure AREABUNDLE.  See Area and Polygon Primitives for detailed
information on using areas.

The Full Arc

(a) is a tilted ellipse that is defined by the current arc parameters.  (b) is
drawn using GpiFullArc with:

o A multiplier value that reduces the size of the arc relative to the current
  arc
o An IControl value filling the interior with the current area-fill pattern,
  but not drawing the arc's outline.


ΓòÉΓòÉΓòÉ 3.1.7.2. Partial Arcs ΓòÉΓòÉΓòÉ

A partial arc is a section of a full arc defined by the current arc parameters.
To draw a partial arc, use GpiPartialArc, which draws two separate figures.
The first figure is a straight line from the current position to the starting
point of a partial arc, and the second figure is the partial arc itself.  When
the arc has been drawn, the new current position is at the end point of the
partial arc.

GpiPartialArc accepts as input the center of the current full arc, of which the
partial arc is a part, specified in world coordinates. You also can specify a
multiplier value to increase or decrease the size of the partial arc in
relation to the current full arc.

You also must specify two positive fixed values: a start angle and a sweep
angle.  If the current full arc is a circle, the start angle is measured
counterclockwise from the x-axis of the circle.  The intersection of the start
angle with the full arc, adjusted by the multiplier value, defines the starting
point of the partial arc.

The sweep angle continues the counterclockwise measurement, beginning where the
start angle left off.  The intersection of the sweep angle with the full arc,
adjusted by the multiplier value, defines the partial arc.

If the current arc is not a circle, the start and sweep angle are skewed to the
same degree that the ellipse is a skewed circle. The following figure shows how
the partial arc is constructed.

The Partial Arc

A is the start angle; B, the sweep angle.  C is the center point; D, the
current position.  Arc.EF is the partial arc.  F is the new current position.

The inner circle in the previous figure is the arc defined by the current arc
parameters.  A multiplier has been specified with GpiPartialArc, so the partial
arc is based on the full arc described by the outer circle.  Point C is the
center point specified on GpiPartialArc.  Angle A is the start angle, and angle
B is the sweep angle.  GpiPartialArc therefore, draws a line from the current
position (point D) to the start of the partial arc (point E). It also draws arc
EF. Point F is the new current position.  The arc is drawn counterclockwise
because the current arc parameters define a counterclockwise circle.  You can
join points F and D with GpiLine.  This line is drawn automatically if you
define the partial arc within a GpiBeginArea and GpiEndArea bracket.


ΓòÉΓòÉΓòÉ 3.1.7.3. 3-Point Arcs ΓòÉΓòÉΓòÉ

GpiPointArc draws an arc from the current position through an intermediate
point to an end point.  When the arc is drawn, the current position is at the
end point of the arc.  You specify both the intermediate point and the end
point, and these values determine both the size of the arc and the direction in
which it is drawn.  The shape and the orientation of a 3-point arc are
determined by the current arc parameters. The following figure shows how a
3-point arc is constructed.

If the current arc parameters define an ellipse, that ellipse is scaled up or
down to fit the 3 points of the arc.

When you want the 3 points of the arc to be points on a circle, allow the
current arc parameters to default so they define a unit circle.  You do not
need to use the values p and q to specify the radius of the circle, because the
radius is determined by the relative positions of the 3 points of the arc.


ΓòÉΓòÉΓòÉ 3.1.8. Multiple-Arc Primitive Family ΓòÉΓòÉΓòÉ

The following table describes the three variants of the simple-arc primitive
and the functions that draw them. As with line primitives, an application draws
simple arcs by first issuing GpiMove or GpiSetCurrentPosition to set the
current position.  The multiple arcs are the most sophisticated of the arc
primitives and their construction does not depend on the current arc
parameters.

Functions that Draw Multiple-Arcs

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariants    ΓöéFunction                ΓöéDescription                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFillets     ΓöéGpiPolyFillet           ΓöéDraws one or more fillets.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé            ΓöéGpiPolyFilletSharp      ΓöéDraws one or more fillets with    Γöé
Γöé            Γöé                        Γöévarying degrees of sharpness.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSplines     ΓöéGpiPolySpline           ΓöéDraws one or more splines.        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 3.1.8.1. Fillets ΓòÉΓòÉΓòÉ

GpiPolyFillet constructs a fillet (a curved line) made up of one or more arcs,
each of which touches a different straight line.  You specify the end points of
these straight lines with GpiPolyFillet.  The lines are not drawn but are used
to construct the curve.

The fillet starts at the current position and finishes at the end point of the
last line. On the way from the start point to the end point, the fillet is
tangential to all intermediate lines at their midpoints.  When the fillet is
drawn, the current position is at the end point of the last construction line.
The following figure is an example of how a fillet is constructed.

The Fillet

The fillet starts at (2,6) and ends at (5,1).  The fillet is tangential to the
midpoints of the lines from (2,8) to (6,9), from (6,9) to (9,5), and from (9,5)
to (5,3).

When you supply only two points, the construction lines of the fillet are drawn
from the current position to the first point, and from the first point to the
second point.  The fillet is drawn from the current position to the second
point, and is tangential to the construction lines at those same points.

GpiPolyFilletSharp creates a fillet on a series of connected construction
lines.  The first fillet in the series is built using two construction lines:
one drawn from the current position to point 1 (the control point), and one
drawn from point 1 to point 2 (the end point).  The fillet is drawn from the
current position to the end point, and is tangential to the two construction
lines at those points.

GpiPolyFilletSharp also accepts as input a sharpness value. Sharpness is a
measure of the distance between the fillet and the control point, and is
calculated as shown in the following figure.

Fillet with Sharpness Specified

Point A is the current position, point B is the control point, and point C is
the end point.  W is the midpoint of the notional line AC.  D is the point at
which the fillet crosses the notional line WB.

The sharpness of the fillet is the value WD / DB.  The line WD is 10 coordinate
units, and the line DB is 5 coordinate units; therefore the sharpness value is
2. The sharpness value defines the type of arc, as shown in the following
table.

Fillet Sharpness Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéA sharpness value of...       ΓöéDefines...                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGreater than 1.0              ΓöéA hyperbola                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEqual to 1.0                  ΓöéA parabola                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLess than 1.0                 ΓöéAn ellipse                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Subsequent fillets start from the end point of the previous fillet, and are
constructed using the next two lines in the sequence in exactly the same way.
Thus, for each fillet you define one control point, one end point, and one
sharpness value.  Upon completion, the current position is at the end point of
the final construction line in the sequence.

There might be discontinuity of gradient between multiple fillets drawn with
GpiPolyFilletSharp.  To avoid this, ensure that points B and C of one fillet
are on the same construction line as points A and B of the next fillet in the
sequence. This concept is illustrated in connection with the spline primitive
in the figure that follows the next figure. Discontinuity of gradient between
fillets does not occur when the fillets are drawn with GpiPolyFillet.


ΓòÉΓòÉΓòÉ 3.1.8.2. Splines ΓòÉΓòÉΓòÉ

GpiPolySpline creates a succession of one or more Bezier splines.  The spline
also is a curve, but its construction method is different from that of the
fillet.  As input to this function, you supply three construction points for
each spline.  The first spline starts from the current position and ends at the
third specified point.  The two intermediate points are control points for the
curve.  Subsequent splines start at the end point of the previous spline, have
two intermediary control points, and end at the third control point. The
following figure shows the construction method for the spline.

The Spline

Points (1) and (2) are the control points of the spline, and point (3) is the
end point.

To avoid discontinuity of gradient between the end of one spline and the start
of the next, ensure that the last two construction points of the first spline
and the first two construction points of the second spline are positioned along
a single construction line. This concept is shown in the following figure.

Spline with No Discontinuity of Gradient

 The last two points of the first spline (points 2 and 3) are positioned along
the same construction line as the first two points (current position and point
1) of the second spline.


ΓòÉΓòÉΓòÉ 3.2. Using Line and Arc Primitives ΓòÉΓòÉΓòÉ

This section explains how to:

o Draw a straight line
o Create a "rubber-banding" effect with straight lines or arcs
o Draw a circle, ellipse, fillet, or spline.


ΓòÉΓòÉΓòÉ 3.2.1. Drawing a Straight Line ΓòÉΓòÉΓòÉ

To draw a straight line, set the current position with GpiMove or
GpiSetCurrentPosition.  Set the end point of the line by filling in a POINTL
structure, then draw the line with GpiLine. The following figure shows how to
draw a straight line in a PM application.


#include <os2.h>

    BOOL DrawLine(HPS hps, LONG xStart, LONG yStart, LONG xEnd, LONG yEnd){
        POINTL ptl;                       /* Point structure              */

        ptl.x = xStart;                   /* Loads starting x-coordinate  */
        ptl.y = yStart;                   /* Loads starting y-coordinate  */
        GpiMove(hps, &ptl);               /* Sets current position        */
        ptl.x = xEnd;                     /* Loads ending x-coordinate    */
        ptl.y = yEnd;                     /* Loads ending y-coordinate    */
        if (GpiLine(hps, &ptl) == GPI_OK){
            return TRUE;                  /* Draw Line.                   */
        } /* if */
        else return FALSE;
    } /* DrawLine */


Drawing a Straight Line

The second argument of GpiMove is the address of a POINTL structure that
contains coordinates of the line's starting point.  The second argument of
GpiLine is the address of another POINTL structure that contains the
coordinates of the last point on the line.


ΓòÉΓòÉΓòÉ 3.2.2. Creating a Rubber-Banding Effect with a Straight Line ΓòÉΓòÉΓòÉ

When lines are drawn with a rubber-banding effect, two things happen: the
original line (if one exists) is erased; and a new line is drawn in its place.
This process typically takes place each time the mouse is dragged and continues
until the mouse button is released.  The quickest way to erase the original
line (having ensured that it was drawn using mix attribute FM_XOR) is to redraw
it using mix attribute FM_XOR. The following figure shows how to create this
effect.

#define INCL_WININPUT
#define INCL_GPITRANSFORMS
#define INCL_GPIPRIMITIVES
#include <os2.h>
    HPS hps;                            /* Presentation-space handle  */
    LONG curr_color;

MRESULT EXPENTRY wpGeneric(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
    static POINTL ptlStart;             /* Starting point of line     */
    static POINTL ptlNew;               /* Ending point of line       */
    static POINTL ptlPrev;              /* Previous end point of line */
    static BOOL fDraw;                  /* Line-drawing flag          */

    switch (msg) {
        case WM_BUTTON1DOWN:            /* User begins drawing        */
           GpiSetColor(hps, CLR_GREEN);
           ptlStart.x = (LONG) (LOUSHORT(mp1));
           ptlStart.y = (LONG) (HIUSHORT(mp1));
           GpiConvert(hps, CVTC_DEVICE, CVTC_WORLD, 1L,
                    &ptlStart);
           ptlPrev.x = ptlStart.x;
           ptlPrev.y = ptlStart.y;
           GpiMove(hps, &ptlStart);
           fDraw = TRUE;
           return ((MRESULT) TRUE);

        case WM_MOUSEMOVE:              /* User draws line             */
            if (fDraw) {
                ptlNew.x = (LONG) (LOUSHORT(mp1));
                ptlNew.y = (LONG) (HIUSHORT(mp1));
                GpiConvert(hps, CVTC_DEVICE, CVTC_WORLD, 1L,  &ptlNew);
                curr_color = GpiQueryColor(hps);
                GpiSetMix(hps, FM_XOR);
                if ((ptlStart.x != ptlPrev.x)
                || (ptlStart.y != ptlPrev.y)) {
                    GpiMove(hps, &ptlStart);
                    GpiLine(hps, &ptlPrev);
                } /* if */
                if ((ptlStart.x != ptlNew.x)
                || (ptlStart.y != ptlNew.y)) {
                    GpiMove(hps, &ptlStart);
                    GpiLine(hps, &ptlNew);
                    ptlPrev.x = ptlNew.x;
                    ptlPrev.y = ptlNew.y;
                } /* if */
                GpiSetMix(hps, FM_OVERPAINT);
            } /* if */
            return ((MRESULT) TRUE);

         case WM_BUTTON1UP:              /* User stops drawing          */
            fDraw = FALSE;
            return ((MRESULT) TRUE);
    } /* switch */
} /* wpGeneric */


Rubber-Banding a Straight Line


ΓòÉΓòÉΓòÉ 3.2.3. Drawing a Circle ΓòÉΓòÉΓòÉ

When drawing a circle, all the transformations between the world, model, page,
and device spaces must maintain square units. This means that your application
should select metric, English, or arbitrary page units instead of pels.  On
most devices, pels are rectangular, but not necessarily square.  This also
means that the Sx and Sy scaling factors should be equal.  If the
transformations maintain square units and the arc parameters are set to their
default values, GpiFullArc produces a circle.

In the example shown in the following figure, if the page units are
PU_LOENGLISH and the default transformations are set, a circle with a radius of
1/2 inch is drawn.


#define INCL_GPIPRIMITIVES
#include <os2.h>
    HPS hps;                                  /* Presentation-space handle      */

MRESULT EXPENTRY wpClient (HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
    ARCPARAMS arcp;                           /* Structure for arc parameters   */
    POINTL ptlPos;                            /* Structure for current position */
    FIXED fxMult;                             /* Multiplier for circle          */

    arcp.lP = 1;
    arcp.lQ = 1;
    arcp.lR = 0;
    arcp.lS = 0;
    GpiSetArcParams(hps, &arcp);               /* Sets parameters to default    */
    ptlPos.x = 100;                            /* Loads x-coordinate            */
    ptlPos.y = 100;                            /* Loads y-coordinate            */
    GpiMove(hps, &ptlPos);                     /* Sets current position         */
    fxMult = MAKEFIXED(50, 0);                 /* Sets multiplier               */
    GpiFullArc(hps, DRO_OUTLINE, fxMult);      /* Draws circle                  */
} /* wpClient */


Drawing a Circle

The second argument to GpiFullArc, DRO_OUTLINE, specifies that the operating
system should draw only the outline of the circle-rather than filling the
interior with the current fill pattern.  The third argument, fxMult, specifies
that the operating system should multiply the size of the circle by 50 units.
Because the page units are PU_LOENGLISH and the default transformations are
set, 50 units is equivalent to 1/2 inch.


ΓòÉΓòÉΓòÉ 3.2.4. Drawing an Ellipse ΓòÉΓòÉΓòÉ

If you set the world, model, page, and device transformations so that they
maintain square units, you can use the arc parameters to transform the shape of
the unit circle to an ellipse, and draw this with GpiFullArc.  The example in
the following figure alters the arc parameter, p, by doubling its value, making
the ellipse twice as wide horizontally as it is vertically.

In the example shown in the following figure, if the page units are
PU_LOENGLISH and the default transformations are set, an ellipse with a 2-inch
major axis (parallel to the x-axis) and a 1-inch minor axis (parallel to the
y-axis) is drawn.


#define INCL_GPIPRIMITIVES
#include <os2.h>
    HPS hps;                              /* Presentation-space handle      */

MRESULT EXPENTRY wpClient (HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
    POINTL ptlPos;                        /* Structure for current position */
    FIXED fxMult;                         /* Multiplier for ellipse         */
    ARCPARAMS arcp;                       /* Structure for arc parameters   */

    arcp.lP = 2;
    arcp.lQ = 1;
    arcp.lR = 0;
    arcp.lS = 0;
    GpiSetArcParams(hps, &arcp);           /* Sets parameters to default */
    ptlPos.x = 200;                        /* Loads x-coordinate         */
    ptlPos.y = 100;                        /* Loads y-coordinate         */
    GpiMove(hps, &ptlPos);                 /* Sets current position      */
    fxMult = MAKEFIXED(50, 0);             /* Sets multiplier            */
    GpiFullArc(hps, DRO_OUTLINE, fxMult);  /* Draws circle               */
} /* wpClient */


Drawing an Ellipse

Because the arc-parameter fields, lP and lQ, are set to 2 and 1, the operating
system creates an ellipse with a major axis that is twice as long as the minor
axis.


ΓòÉΓòÉΓòÉ 3.2.5. Drawing a Pie Slice ΓòÉΓòÉΓòÉ

The following steps describe how to use GpiPartialArc to draw a closed shape
bounded by a chord and an arc:

 1. Set the current line type to LINETYPE_INVISIBLE with GpiSetLineType.

 2. Issue GpiPartialArc with the start angle equal to angle B, and the sweep
    angle equal to 0.  This effectively moves the current position to a point
    on the current arc, and thereby defines one end of the chord.

 3. Select a visible line type with GpiSetLineType.

 4. Issue GpiPartialArc, with the start angle equal to angle A, and the sweep
    angle equal to angle B - angle A.  Angle B must be greater than angle A.
    The center point is the same on both GpiPartialArc calls.

To fill this partial arc with the current area-fill pattern, you can bracket
the GpiPartialArc call of step 4 with the GpiBeginArea and GpiEndArea
functions.  You should not issue GpiBeginArea before step 2.

The effect of this sequence is shown in the following figure.

Closed Figure Bounded by Chord and Arc

The circle in the following figure is defined by the current arc parameters.
Point F is the current position, and point C is the center of the arc as
specified with the first GpiPartialArc call.  The first GpiPartialArc call-with
the line type set to LINETYPE_INVISIBLE-moves the current position to point D.
The second GpiPartialArc call-with the line type set to LINETYPE_SOLID- draws
the chord from the current position (point D) to the start point of the arc
(point E), and draws arc ED. The partial arc has been defined within an area
and has been filled with the current area-fill pattern.

The following figure shows how to draw a "pie slice" like the one drawn in the
previous figure.


#define INCL_GPIPRIMITIVES
#include <os2.h>

void Figure_516(){
   HPS hps;
   POINTL ptlCenter = {2L, 2L};       /*  Coordinates of the center point  */
   FIXED fxAngleA = 20L;              /*  Angle A in degrees               */
   FIXED fxAngleB = 130L;             /*  Angle B in degrees               */

   GpiSetLineType(hps, LINETYPE_INVISIBLE);
                    /*  Set position to start drawing the arc at angle B.  */
   GpiPartialArc(hps, &ptlCenter, MAKEFIXED(1, 0), fxAngleB, 0L);
   GpiSetLineType(hps, LINETYPE_ID);
   GpiBeginArea(hps, BA_BOUNDARY | BA_ALTERNATE);      /*  Fill the area   */
   GpiPartialArc(hps, &ptlCenter, MAKEFIXED(1, 0), fxAngleA, fxAngleB-fxAngleA);
   GpiEndArea(hps);                                    /* Cancel area-fill */
}


Drawing a Pie Slice


ΓòÉΓòÉΓòÉ 3.2.6. Drawing a Fillet ΓòÉΓòÉΓòÉ

 A fillet is tangential to two lines.  The curve of the fillet is always
tangential to a line drawn between its start and control points and a line
drawn between its end and control points.

The following figure shows an example of how to draw a single curve, using the
current position and two control points.


#include <os2.h>
    HPS hps;                                 /* Presentation-space handle    */

MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
    POINTL aptl[2];                /* Structure for control points           */

        aptl[0].x = 50;            /* Loads x-coord. of first control point  */
        aptl[0].y = 50;            /* Loads y-coord. of first control point  */
        GpiMove(hps, aptl);                  /* Sets current position        */
        aptl[0].x = 75;            /* Loads x-coord. of second control point */
        aptl[0].y = 75;            /* Loads y-coord. of second control point */
        aptl[1].x = 100;           /* Loads x-coord. of third control point  */
        aptl[1].y = 50;            /* Loads y-coord. of third control point  */
        GpiPolyFillet(hps, 2, aptl); /* Draws fillet                         */
} /* wpClient */


Drawing a Fillet

When you draw a sharp fillet, the sharpness value controls the shape of the
curve, as shown in a previous table.

The following figure shows an example of using a sharpness value of 3, which
creates a hyperbolic curve.


#include <os2.h>
    HPS hps;                        /* Presentation-space handle             */

MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
        POINTL aptl[2];            /* Structure for control points           */
        FIXED fxSharpness;         /* Sharpness value                        */

        aptl[0].x = 50;            /* Loads x-coord. of first control point  */
        aptl[0].y = 50;            /* Loads y-coord. of first control point  */
        GpiMove(hps, aptl);        /* Sets current position                  */
        aptl[0].x = 75;            /* Loads x-coord. of second control point */
        aptl[0].y = 75;            /* Loads y-coord. of second control point */
        aptl[1].x = 100;           /* Loads x-coord. of third control point  */
        aptl[1].y = 50;            /* Loads y-coord. of third control point  */
        fxSharpness = MAKEFIXED(3, 0);   /* Sets sharpness value             */
        GpiPolyFilletSharp(hps,    /* Draws fillet                           */
            2L, aptl, &fxSharpness);
} /* wpClient */


Drawing a Hyperbolic Curve


ΓòÉΓòÉΓòÉ 3.2.7. Drawing a Spline ΓòÉΓòÉΓòÉ

When you use GpiPolySpline to draw a spline, each curve is tangential to the
first and last of three connected lines. The following figure shows how to draw
a spline.


#include <os2.h>
    HPS hps;                        /* Presentation-space handle              */

MRESULT EXPENTRY wpClient(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2){
        POINTL aptl[3];             /* Structure for control points           */

        aptl[0].x = 50;             /* Loads x-coord. of first control point  */
        aptl[0].y = 100;            /* Loads y-coord. of first control point  */
        GpiMove(hps, aptl);         /* Sets current position                  */
        aptl[0].x = 75;             /* Loads x-coord. of second control point */
        aptl[0].y = 200;            /* Loads y-coord. of second control point */
        aptl[1].x = 100;            /* Loads x-coord. of third control point  */
        aptl[1].y = 0;              /* Loads y-coord. of third control point  */
        aptl[2].x = 125;            /* Loads x-coord. of fourth control point */
        aptl[2].y = 100;            /* Loads y-coord. of fourth control point */
        GpiPolySpline(hps, 3L, aptl);   /* Draws spline                       */
} /* wpClient */


Drawing a Spline


ΓòÉΓòÉΓòÉ 3.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the line and arc primitive functions.

Line and Arc Primitive Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBox                  ΓöéStarting at the current position,   Γöé
Γöé                        Γöédraws a rectangular or rounded      Γöé
Γöé                        Γöécorner box that, optionally, can be Γöé
Γöé                        Γöéfilled.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiFullArc              ΓöéDraws an ellipse or a circle that,  Γöé
Γöé                        Γöéoptionally, can be filled.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLine                 ΓöéDraws a straight line from the      Γöé
Γöé                        Γöécurrent position.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMove                 ΓöéSets the current position.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPartialArc           ΓöéDraws a straight line, followed by aΓöé
Γöé                        Γöésection of a circle or ellipse.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPointArc             ΓöéDraws an arc through 3 points.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolyFillet           ΓöéDraws 1 or more fillets.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolyFilletSharp      ΓöéDraws 1 or more fillets with varyingΓöé
Γöé                        Γöédegrees of sharpness.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolyLine             ΓöéDraws straight lines from the       Γöé
Γöé                        Γöécurrent position to connect a seriesΓöé
Γöé                        Γöéof vertices.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolySpline           ΓöéDraws 1 or more Bezier splines.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryArcParams       ΓöéDetermines the current arc          Γöé
Γöé                        Γöéparameters.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryAttrs           ΓöéCopies the current line attributes  Γöé
Γöé                        Γöéto a LINEBUNDLE structure.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCurrentPosition ΓöéDetermines the x- and y-coordinates Γöé
Γöé                        Γöéof the current position.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLineType        ΓöéDetermines the current line type.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLineWidth       ΓöéDetermines the current line width.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetArcParams         ΓöéDefines the current arc parameters. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetAttrs             ΓöéDefines the current line attributes.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetColor             ΓöéDefines the current line color.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCurrentPosition   ΓöéDefines the current position and canΓöé
Γöé                        Γöéretain the previous current         Γöé
Γöé                        Γöéposition.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineType          ΓöéDefines the current line style.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineWidth         ΓöéDefines the current line width.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMix               ΓöéDefines the current line mix        Γöé
Γöé                        Γöéattribute.                          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the line and arc
primitive functions.

Line and Arc Primitive Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure               ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéARCPARAMS               ΓöéContains the current arc parameters.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEBUNDLE              ΓöéContains the current line           Γöé
Γöé                        Γöéparameters.                         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 4. Marker Primitives ΓòÉΓòÉΓòÉ

Marker primitives are graphics objects-such as stars, dots, or crosses-that are
used, for example, to indicate the plotted points on a line graph. The
following topics are related to the information in this chapter:

o Presentation spaces
o Line and arc primitives
o Color and mix attributes
o Fonts.


ΓòÉΓòÉΓòÉ 4.1. About Marker Primitives ΓòÉΓòÉΓòÉ

Marker primitives always are drawn centered over a point. In a designated
presentation space, the GpiMarker function draws a single marker primitive of
the current marker symbol, with its center at a specified position. This
position becomes the new current position when the marker is drawn.

Another marker function, GpiPolyMarker, draws multiple marker primitives in the
designated presentation space. Each marker primitive is centered over a
position specified in an input array to GpiPolyMarker. All marker primitives
drawn by a single call to GpiPolyMarker use the same (current) marker symbol.
When a series of marker primitives is drawn, the current position is the center
point of the last marker in the series. The following figure shows the use of
marker primitives in a line graph.

Marker Primitives

This example shows a sequence of diamond-shaped marker primitives drawn on a
line graph at (1,2), (3,4), (4,3), (7,5), (8,4), (9,8), (10,6), and (11,6). The
new current position is at (11,6). The marker portion of this example could
have been drawn with a single issuance of GpiPolyMarker or with 8 separate
GpiMarker calls.


ΓòÉΓòÉΓòÉ 4.1.1. Attributes of Marker Primitives ΓòÉΓòÉΓòÉ

Marker primitive attributes are contained in a data structure called
MARKERBUNDLE. Following is a list of these attributes:

o Marker symbol
o Marker box
o Marker set
o Foreground color
o Background color
o Foreground mix attribute
o Background mix attribute.

When an application creates a presentation space, the marker attributes are set
to the default values shown in the following table.

Marker Attribute Default Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute       ΓöéDefault Value     ΓöéFunction that Redefines   Γöé
Γöé                Γöé                  ΓöéAttribute                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker symbol   ΓöéCross             ΓöéGpiSetMarker              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker box      ΓöéDevice dependent; ΓöéGpiSetMarkerBox           Γöé
Γöé                Γöéequal to the size Γöé                          Γöé
Γöé                Γöéof one character  Γöé                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMarker set      ΓöéLCID_DEFAULT      ΓöéGpiSetMarkerSet           Γöé
Γöé                Γöé                  ΓöéNote:  If this default is Γöé
Γöé                Γöé                  Γöéchanged, the base marker  Γöé
Γöé                Γöé                  Γöéset cannot be reselected  Γöé
Γöé                Γöé                  Γöéwith GpiSetMarkerSet.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground colorΓöéBlack             ΓöéGpiSetAttrs (MBB_COLOR)   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground colorΓöéClear             ΓöéGpiSetAttrs               Γöé
Γöé                Γöé                  Γöé(MBB_BACK_COLOR)          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mix  ΓöéOverpaint         ΓöéGpiSetAttrs (MBB_MIX_MODE)Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mix  ΓöéLeave alone       ΓöéGpiSetAttrs               Γöé
Γöé                Γöé                  Γöé(MBB_BACK_MIX_MODE)       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 4.1.2. Marker Symbols ΓòÉΓòÉΓòÉ

The current marker symbol is selected from the current marker set using
GpiSetMarker. The marker symbol selected for the specified presentation space
is used for all subsequent GpiMarker and GpiPolyMarker calls until a new symbol
is selected.

The following table describes the marker symbols provided by the PM programming
interface in a base marker set. These symbols are not necessarily available
from other marker sets.

The Base Marker Set

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSymbol            ΓöéIdentifier                      ΓöéLong ValueΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCross             ΓöéMARKSYM_CROSS                   Γöé1L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPlus sign         ΓöéMARKSYM_PLUS                    Γöé2L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDiamond           ΓöéMARKSYM_DIAMOND                 Γöé3L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSquare            ΓöéMARKSYM_SQUARE                  Γöé4L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSix-point star    ΓöéMARKSYM_SIXPOINTSTAR            Γöé5L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEight-point star  ΓöéMARKSYM_EIGHTPOINTSTAR          Γöé6L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid diamond     ΓöéMARKSYM_SOLIDDIAMOND            Γöé7L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid square      ΓöéMARKSYM_SOLIDSQUARE             Γöé8L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDot               ΓöéMARKSYM_DOT                     Γöé9L        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSmall circle      ΓöéMARKSYM_SMALLCIRCLE             Γöé10L       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlank, (Often     ΓöéMARKSYM_BLANK                   Γöé64L       Γöé
Γöécalled the        Γöé                                Γöé          Γöé
Γöéinvisible marker) Γöé                                Γöé          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default marker symbol (MARKSYM_DEFAULT) is identical to the MARKSYM_CROSS
symbol and has a long value of 0L. The error marker symbol (MARKSYN_ERROR) has
a long value of -1L.

The following figure shows the visible marker symbols from the base marker set.
Your application can determine the marker set with GpiQueryMarkerSet.

The Base Marker Set


ΓòÉΓòÉΓòÉ 4.1.3. Marker Box ΓòÉΓòÉΓòÉ

The marker box is a rectangular boundary that defines the horizontal and
vertical space occupied by the marker symbol. The marker box is used to center
the current marker symbol.

If the current marker set contains vector marker primitives (characters
outlined by using line and arc functions), changing the size of the marker box
changes the size of the marker primitives also. When you change the size of the
marker box, a vector marker symbol is scaled up or down automatically to fit
the box. Image marker primitives, however, cannot be scaled. If the current
marker set contains image characters, the marker box dimensions are fixed,
because you cannot alter the size of image markers.

You can use GpiSetMarkerBox to change the size of the marker box for a
particular presentation space. Set the value of the appropriate PSIZEF
structure to the required size. The new size is expressed in world coordinates
and should not contain any fractional values.

The default size of the marker box can be determined using DevQueryCaps. The
values, CAPS_MARKER_WIDTH and CAPS_MARKER_HEIGHT, depend on the currently
associated device and the presentation page. Marker box values set with
GpiSetMarkerBox can be determined using GpiQueryMarkerBox.

GpiSetAttrs also can be used to change the size of the marker box;
GpiSetDefAttrs can be used to change the default size of the marker box.


ΓòÉΓòÉΓòÉ 4.1.4. Marker Set ΓòÉΓòÉΓòÉ

When you create a presentation space, the current marker set, along with other
marker attributes, are set to default. The current marker symbol (the cross
described earlier) is specified from the supplied marker set. The supplied set
of marker primitives contains only image, or raster, marker primitives.

The marker primitives in the default marker set are drawn by setting the color
of the pels in the marker box. Within the marker box, the color of the set pels
defines the foreground color. The default foreground color is neutral- black on
the display screen and on printers.

The color of the pels that are not set defines the background color. The
default background color is the background color on the device-white on the
display screen, and the loaded paper color on printers. The default background
mix is LEAVE_ALONE, or transparent, which means the background color is
irrelevant.

If the default set is changed using GpiSetDefAttrs, its markers are not
accessible. The markers from the default set can be recovered by calling
GpiSetDefAttrs and specifying the value LCID_DEFAULT, (0).

Customizing Marker Sets
If the current marker set does not contain a symbol that suits your
application, you can load a new marker set and select a marker symbol from that
set. The only way to see the current marker set is to display it on the screen
or view a hardcopy of the symbols. You load a new marker set for a specified
presentation space by creating a logical font. Then, you select the font as a
marker set by specifying the logical font identifer (lcid) as an input
parameter to GpiSetMarkerSet. lcids and their values are described in Selecting
the New Current Font. After selecting the marker set, call GpiSetMarker to
select a marker from the set. You can set both values simultaneously, with
GpiSetAttrs.

You can use any font's character set as a marker set and any character within
that marker set as a marker. To determine the value that identifies the current
marker set, call GpiQueryMarkerSet. To determine the value that identifies the
current marker character, call GpiQueryMarker. You can retrieve both values
simultaneously with GpiQueryAttrs. You also can create image marker symbols
using the Font Editor.


ΓòÉΓòÉΓòÉ 4.1.5. Marker Color and Mix Attributes ΓòÉΓòÉΓòÉ

The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface. Both attributes also are described in Color and Mix Attributes.

The marker color defines the color used to draw the output from any of the OS/2
operating system marker functions. When a presentation space is created, the
marker color initial default is black. Markers are one of the primitives that
have a foreground and background color, as shown in the following figure.

For image markers, the colors are determined by the setting of pels. For vector
markers, the foreground consists of the arcs and lines that define the marker.
The background color appears between the foreground lines. The marker can be
solid, or filled, in which case the background color does not appear between
the foreground lines.

Marker Primitives

Marker primitives have both a color and background color attribute. The mix
attribute controls the combination of marker color with drawing-surface color,
while the background mix attribute controls the combination of the marker box
color with the drawing-surface color.

When a presentation space is created, the marker mix attribute initial default
is FM_OVERPAINT. The overpaint mix attribute specifies that the marker color is
not to be modified by the color of the drawing surface. If the marker mix
attribute is changed, the marker color is mixed with colors that are already on
the drawing surface.

The marker background color initial default is CLR_BACKGROUND. Usually this is
defined by the application to the same color as the drawing surface. The marker
background mix attribute initial default is BM_LEAVEALONE. The leave-alone mix
background attribute specifies that the marker background color is not drawn.
The box that effectively surrounds the marker appears only if the marker
background mix attribute is changed.

To specify a new color or mix attribute call GpiSetAttrs. This function accepts
as input the type of primitive, for example PRIM_MARKER, a list of attributes
that are to be changed, a list of attributes that are to be set to their
default values, and the values for the attributes that are to be changed.
GpiSetAttrs is useful to specify colors and mix attributes just for a specific
data structure, for example the MARKERBUNDLE. GpiSetAttrs also provides some
protection against invalid colors as described in Presentation Manager
Programming Reference.

To determine the current marker color and mix attribute call GpiQueryAttrs.
This function accepts as input the primitive type and the attributes in
question. It returns as output an array of values for the specifically queried
attributes.

To reset the default marker color and mix attribute, just as with any other
attribute specified in the MARKERBUNDLE data structure, call GpiSetDefAttrs.
This function accepts as input the type of primitive, for example PRIM_MARKER,
the attributes to be changed, and the values that will become the new default
values. The changing of default values is important when working with segments,
described in Creating and Drawing Retained Graphics and Editing Retained
Graphics and Graphics Segments. Changing the default values during a series of
drawing functions is not recommended.

The marker color and mix attribute also can be specified with:

o GpiSetColor
o GpiSetMix
o GpiSetBackColor
o GpiSetBackMix.

However, these functions have the disadvantage of specifying the foreground and
background color or mix attribute for all primitive xxxBUNDLE data structures
that have the respective component.

There are four querys that determine the color and mix attribute as specified
by GpiSetxxx functions:

o GpiQueryColor
o GpiQueryMix
o GpiQueryBackColor
o GpiQueryBackMix.

If the marker color, marker background color, mix attribute, or background mix
attribute were specified individually, the aforementioned queries can return a
value inconsistent with the current marker attribute.


ΓòÉΓòÉΓòÉ 4.2. Using Marker Primitives ΓòÉΓòÉΓòÉ

You can use marker functions to:

o Draw a single marker or a series of markers

o Set or determine (query) any combination of the marker bundle attributes
  including:

   - Determining the lcid for the current marker set
   - Selecting a character set as the new marker set
   - Determining the value that identifies the current marker
   - Selecting a character as the new marker
   - Setting or changing the size of the marker box
   - Setting or changing the color of a marker.


ΓòÉΓòÉΓòÉ 4.2.1. Drawing Marker Primitives ΓòÉΓòÉΓòÉ

You can draw either a single marker or a series of markers using the current
marker symbol. To draw a single marker, set the fields in a POINTL structure to
correspond to the desired position in world coordinates. Then call GpiMarker,
passing it the address of the POINTL structure as the second argument.

To draw a series of markers, set the fields in an array of POINTL structures to
correspond to the desired positions in world coordinates. Then call
GpiPolyMarker, passing it the number of points in the array as the second
argument and the name of the array as the third argument.

The following figure shows how to draw a graph with GpiPolyLine and
GpiPolyMarker.


#include <os2.h>
void fncMARK01(void){
    HPS hps;                                  /* Presentation-space handle */
    POINTL aptl[6];                           /* Array of points           */

    aptl[0].x = 10; aptl[0].y = 15;           /* Assigns points            */
    aptl[1].x = 150; aptl[1].y = 30;
    aptl[2].x = 200; aptl[2].y = 32;
    aptl[3].x = 250; aptl[3].y = 70;
    aptl[4].x = 360; aptl[4].y = 120;
    aptl[5].x = 380; aptl[5].y = 98;
    GpiPolyMarker(hps, sizeof(aptl) / sizeof(POINTL),aptl);
                                              /* Plots points              */
    GpiMove(hps, aptl);                       /* Sets current position     */
    GpiPolyLine(hps, sizeof(aptl) / sizeof(POINTL),aptl);
                                              /* Draws lines               */
} /* fncMARK01 */


Drawing a Graph


ΓòÉΓòÉΓòÉ 4.2.2. Selecting a New Marker ΓòÉΓòÉΓòÉ

The following figure shows how to check whether the default marker primitive
from the default marker set is being used currently; and if so, how to replace
the cross with the six-pointed star.

#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK02(void){
    HPS hps;

    if ((GpiQueryMarker(hps) == MARKSYM_DEFAULT) &&
        (GpiQueryMarkerSet(hps) == LCID_DEFAULT))
    GpiSetMarker(hps, MARKSYM_SIXPOINTSTAR);


Selecting a New Marker


ΓòÉΓòÉΓòÉ 4.2.3. Selecting a New Marker Set ΓòÉΓòÉΓòÉ

The followiing figure is an example of how to load a Helvetica** vector font,
select it as the new marker set, and select the uppercase A as the new marker
primitive.


#define INCL_GPILCIDS
#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK03(void){
    LONG cHelvFonts, cFonts, lcid, i, j;
    HPS hps;
    FATTRS fattrs;
    FONTMETRICS afm[80];
    MARKERBUNDLE mbnd;

    cHelvFonts = GpiQueryFonts(hps, QF_PUBLIC, "Helv",
   &cFonts, sizeof(FONTMETRICS), (PFONTMETRICS) NULL);
                                 /* Queries the number of Helvetica fonts.      */

    GpiQueryFonts(hps, QF_PUBLIC, "Helv", &cHelvFonts,
       sizeof(FONTMETRICS), afm);
                                 /* Loads the array of FONTMETRICS structures.  */

    for (i = 0; !(afm[i].fsDefn & FM_DEFN_OUTLINE)
                                   && i < cHelvFonts; i++);
                                 /* Finds outline font                          */

    fattrs.usRecordLength = sizeof(FATTRS);
    fattrs.fsSelection = 0;
    fattrs.lMatch = afm[i].lMatch;         /* Uses Helvetica outline font       */
    for (j = 0; j <= sizeof(afm[i].szFacename); j++)
    fattrs.szFacename[j] = afm[i].szFacename[j];
    fattrs.idRegistry = 0;
    fattrs.usCodePage = 850;     /* Uses international code page                */
    fattrs.lMaxBaselineExt = 0;
    fattrs.lAveCharWidth = 0;
    fattrs.fsType = 0;
    fattrs.fsFontUse = FATTR_FONTUSE_TRANSFORMABLE;

    GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fattrs);
    mbnd.usSet = lcid;           /* Uses font as marker set                     */
    mbnd.usSymbol = 'A';         /* Uses capital A as primitive                 */
    GpiSetAttrs(hps, PRIM_MARKER, MBB_SYMBOL | MBB_SET, 0, &mbnd);
} /* fncMARK03 */


Selecting a New Marker Set


ΓòÉΓòÉΓòÉ 4.2.4. Changing the Marker Color ΓòÉΓòÉΓòÉ

The following figure shows how to set the marker foreground color to green.


#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncMARK04(void){
    HPS hps;
    MARKERBUNDLE mbnd;

    mbnd.lColor = CLR_GREEN;
    GpiSetAttrs(hps, PRIM_MARKER, MBB_COLOR, 0L, &mbnd);
} /* fncMARK04 */


Changing the Marker Color


ΓòÉΓòÉΓòÉ 4.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the marker primitive functions.

Marker Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMarker               ΓöéDraws the current marker primitive  Γöé
Γöé                        Γöéat a specified position.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolyMarker           ΓöéDraws a series of the current markerΓöé
Γöé                        Γöéprimitive at a specified position.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryAttrs           ΓöéDetermines the current marker bundleΓöé
Γöé                        Γöéattributes.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMarker          ΓöéDetermines the current marker symbolΓöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMarkerBox       ΓöéDetermines the size of the current  Γöé
Γöé                        Γöémarker box.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMarkerSet       ΓöéDetermines the value of the current Γöé
Γöé                        Γöémarker set attribute.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetAttrs             ΓöéSets the marker bundle attributes.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMarker            ΓöéSets the attribute of the marker    Γöé
Γöé                        Γöésymbol.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMarkerBox         ΓöéSets the dimensions of the marker   Γöé
Γöé                        Γöébox. (This function influences      Γöé
Γöé                        Γöévector markers only. The width and  Γöé
Γöé                        Γöéheight of raster marker primitives  Γöé
Γöé                        Γöéare fixed.)                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMarkerSet         ΓöéSets the attribute of the marker    Γöé
Γöé                        Γöéset.                                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following table summarizes the data structures used by the marker primitive
functions.

Marker Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPOINTL                  ΓöéA structure specifying the values ofΓöé
Γöé                        Γöéa single pair of x- and y-          Γöé
Γöé                        Γöécoordinates.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPSIZEF                  ΓöéA structure specifying the size of  Γöé
Γöé                        Γöéthe marker box.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMARKERBUNDLE            ΓöéA structure of marker primitive     Γöé
Γöé                        Γöéattributes.                         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 5. Area and Polygon Primitives ΓòÉΓòÉΓòÉ

An area is one or more closed figures that can be drawn filled, outlined, or
filled and outlined.  If an area includes more than one figure, those figures
can be separate or intersecting.

A polygon, too, is one or more closed figures that can be drawn filled,
outlined, or filled and outlined.  Polygons, unlike areas, are limited to
figures with straight edges.  Polygons also can be separate or intersecting.

The following topics are related to the information in this chapter:

o Presentation spaces
o Line and arc primitives
o Color and mix attributes
o Fonts
o Bit maps
o Paths.


ΓòÉΓòÉΓòÉ 5.1. About Area Primitives ΓòÉΓòÉΓòÉ

Applications can create, outline, and fill areas and can create custom-fill
patterns from bit maps or font symbols.  Some graphics functions are not valid
within an area definition.  For example, you cannot include marker, image, or
character-string primitives in an area definition. The following figure is an
example of an area.

An Area

This area comprises two hexagons, one completely enclosed by the other. The
area is filled with the current area-fill pattern.


ΓòÉΓòÉΓòÉ 5.1.1. Attributes of Area Primitives ΓòÉΓòÉΓòÉ

The attributes of the area primitive are contained in a data structure called
AREABUNDLE.  These attributes are:

o Pattern symbol
o Pattern reference point
o Pattern set
o Foreground color
o Background color
o Foreground mix attribute
o Background mix mode.

When an application creates a presentation space, the area attributes are set
to the default values shown in the following table.

Area Attribute Default Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute         ΓöéDefault     ΓöéFunction that Redefines       Γöé
Γöé                  ΓöéValue       ΓöéAttribute                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern symbol    Γöésolid       ΓöéGpiSetPattern                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern reference Γöé(0,0)       ΓöéGpiSetPatternRefPoint         Γöé
Γöépoint             Γöé            Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern set       ΓöéLCID_DEFAULTΓöéGpiSetPatternSet              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground color  ΓöéBlack       ΓöéGpiSetAttrs (ABB_COLOR)       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground color  ΓöéClear       ΓöéGpiSetAttrs (ABB_BACK_COLOR)  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mix    ΓöéOverpaint   ΓöéGpiSetAttrs (ABB_MIX_MODE)    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mix    ΓöéLeave alone ΓöéGpiSetAttrs                   Γöé
Γöé                  Γöé            Γöé(ABB_BACK_MIX_MODE)           Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  If the default (LCID_DEFAULT) for pattern set is changed, the base
pattern set cannot be reselected with GpiSetPatternSet.


ΓòÉΓòÉΓòÉ 5.1.2. Pattern Symbol Attribute ΓòÉΓòÉΓòÉ

The current pattern symbol, also called the symbol point code, is selected from
the current pattern set with GpiSetPattern.  The pattern symbol selected for
the specified presentation space is used as the subsequent fill pattern until a
new symbol is selected. Applications must not call GpiSetPattern while in an
area or a path.  If the current pattern set specifies a bit map, this attribute
is ignored.

The following table describes the pattern symbols provided by the PM
programming interface in a base pattern set.  These symbols are not necessarily
available from other pattern sets.

The Base Pattern Set

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSymbol                                    ΓöéIdentifier            ΓöéLong Γöé
Γöé                                          Γöé                      ΓöéValueΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid shading decreasing in dots per inch ΓöéPATSYM_DENSE1 through Γöé1L - Γöé
Γöé                                          ΓöéPATSYM_DENSE8         Γöé8L   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVertical lines                            ΓöéPATSYM_VERT           Γöé9L   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHorizontal lines                          ΓöéPATSYM_HORIZ          Γöé10L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines bottom left to top right            ΓöéPATSYM_DIAG1          Γöé11L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines bottom left to middle right         ΓöéPATSYM_DIAG2          Γöé12L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines top left to bottom right            ΓöéPATSYM_DIAG3          Γöé13L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLines top left to middle right            ΓöéPATSYM_DIAG4          Γöé14L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNo shading                                ΓöéPATSYM_NOSHADE        Γöé15L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSolid shading                             ΓöéPATSYM_SOLID          Γöé16L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAlternate pels                            ΓöéPATSYM_HALFTONE       Γöé17L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCartesian grid                            ΓöéPATSYM_HATCH          Γöé18L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDiagonal crosshatch                       ΓöéPATSYM_DIAGHATCH      Γöé19L  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlank (often called the clear pattern)    ΓöéPATSYM_BLANK          Γöé64L  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The default pattern symbol (PATSYM_DEFAULT) is identical to the PATSYM_SOLID
symbol, and has a long value of 0L.  The error pattern symbol (PATSYN_ERROR)
has a long value of -1L.

The following figure shows the patterns from the base pattern symbol set.
Applications can determine the the current pattern set by issuing
GpiQueryPattern.

The Base Pattern Symbol set.


ΓòÉΓòÉΓòÉ 5.1.3. Pattern Reference Point Attribute ΓòÉΓòÉΓòÉ

The pattern reference point is the point from which the area's fill-pattern
spreads horizontally and vertically.  The lower-left corner of the pattern is
aligned on this point.  The pattern reference point has a default value of
(0,0), and is expressed in world coordinates.  Applications can determine the
pattern reference point with GpiQueryPatternRefPoint.  Applications can specify
the pattern reference point with GpiSetPatternRefPoint; however, this should
not be done inside an area.  The pattern reference point does not have to be
within the boundary of the area. The following figure shows an area that was
filled using the default pattern reference point.

The Pattern Reference Point

The pattern of diagonal lines is aligned with the pattern reference point
(0,0).  When the picture is displayed or printed, only the hexagon will be
filled.

Use of the default reference point causes the diagonal lines of the pattern to
intersect the area boundary at specific points.  If you change the reference
point to (0,4), for example, the pattern shifts upward, and the points of
intersection with the area boundary are different.  Although the reference
point is outside the area, when an application displays or prints the picture,
only the area is filled.


ΓòÉΓòÉΓòÉ 5.1.4. Pattern Set Attribute ΓòÉΓòÉΓòÉ

When you create a presentation space, the current pattern set and other area
attributes are set to the default.  The current pattern-a black solid, as
described earlier- is specified from the supplied pattern set.  (The supplied
set of pattern symbols contains image or raster patterns only.)  An area
primitive is filled by repeating this pattern vertically and horizontally
within the area boundary.


ΓòÉΓòÉΓòÉ 5.1.4.1. Default Pattern Set ΓòÉΓòÉΓòÉ

The standard pattern set contains patterns of solid shading with decreasing
intensity, and patterns of vertical, horizontal, and diagonal lines. If the
default pattern set is changed with GpiSetDefAttrs, its patterns are not
accessible.  The patterns from the default set can be recovered by specifying
GpiSetDefAttrs with the value LCID_DEFAULT, (0).


ΓòÉΓòÉΓòÉ 5.1.4.2. Customizing Pattern Sets ΓòÉΓòÉΓòÉ

An application can create custom patterns by using bit maps or characters and
symbols from an image font.  When designing custom patterns, consider that the
operating system uses only the first 8 bits in the first 8 rows, starting with
the lower-left corner of the bit map.  The cell size of an image font used as a
fill pattern might be too large to include the complete character or symbol.

An application can change the appearance of a fill pattern by changing its
alignment in an area primitive with GpiSetPatternRefPoint. When the default
reference point is set, the operating system aligns the lower-left corner of
the fill pattern with the point (0,0) in the application's world space and
begins filling the area. If an application adjusts the pattern reference point
to (3,2), The operating system aligns the lower-left corner of the fill pattern
with the point (3,2) in the application's world space and begins filling the
area. By moving the reference point from (0,0) to (3,2), the fill pattern
appears shifted up 2 pels and to the right 3 pels.


ΓòÉΓòÉΓòÉ 5.1.4.2.1. Custom Fill Patterns from a Bit Map ΓòÉΓòÉΓòÉ

To create a custom pattern from a hard-coded bit map, an application must use
the following steps:

 1. Create or load a bit map to obtain a bit-map handle, for example, use
    GpiLoadBitmap.

 2. Call GpiSetBitmapId (ID) to tag the bit map with a local identifier (lcid)
    from 1 to 254.

 3. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET) to set the current fill
    pattern.

The application can now draw the area.


ΓòÉΓòÉΓòÉ 5.1.4.2.2. Custom Fill Patterns from a Font Symbol ΓòÉΓòÉΓòÉ

To create a custom pattern from a character or a symbol in a font:

 1. Create a logical image font and assign it an ID, for example use
    GpiCreateLogFont.

 2. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET), passing it the local
    identifier for the font.

 3. Call GpiSetPattern, passing the value of the code point for a character or
    symbol in the font.

The application can now draw the area.


ΓòÉΓòÉΓòÉ 5.1.5. Area Colors and Mix Attributes ΓòÉΓòÉΓòÉ

The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface. Both attributes also are described in Color and Mix Attributes.

The area color defines the color used to fill the output from any of the OS/2
operating system area functions, when necessary. The area primitive is the only
primitive in which the color can be changed during the drawing of the area;
therefore, this attribute, more than the other area attributes, depends on the
current value as described in Attribute Currentness.

When a presentation space is created, the area color initial default is black.
The pattern symbol initial default, explained previously, is solid. Areas are
one of the primitives that have a foreground and background color, as shown in
the following figure; however, the appearance of the area also depends on the
pattern symbol.

Area Primitives

Area primitives have both a color and background color attribute. The
background color does not appear if the pattern symbol is solid, and the
background color is undefined if the pattern symbol is a customized,
multi-colored bit map.

When a presentation space is created, the area mix attribute initial default is
FM_OVERPAINT. The overpaint mix attribute specifies that the area color is not
to be modified by the color of the drawing surface. If the area mix attribute
is changed, the area color is mixed with colors that are already on the drawing
surface.

When the pattern symbol is solid, the color that fills the area, if necessary,
is the current area foreground color. If the pattern symbol is changed to be a
pattern of vertical lines, for example, the color of those lines is the current
area foreground color. Inside of the area bracket, there can be other colors if
these colors are the current color for primitives such as lines or arcs, that
are drawn within the area bracket. These colors are not specifically defined or
influenced by the area foreground color.

The area background color initial default is CLR_BACKGROUND. Usually this is
defined by the application to the same color as the drawing surface. If the
pattern symbol is solid, the area background color does not appear. If the
pattern symbol is changed to be a pattern of vertical lines, for example, the
color in between those lines is the current area background color.

The area background mix attribute initial default is BM_LEAVEALONE. The
leave-alone background mix attribute specifies that the area background color
is not drawn. This means that for a nonsolid pattern symbol, the
drawing-surface color or the color of an object, not created by the area
bracket, but on the drawing surface, shows through the nonsolid pattern. The
area background color, for nonsolid pattern symbols, appears only if the
background mix attribute is changed to overpaint, BM_OVERPAINT.

If you have customized the pattern symbol with a bit map, the color definitions
of the area primitive change. The foreground color corresponds to the color of
the pels that are specified ON in the fill-pattern bit map. The background
color corresponds to the color of the pels that are specified OFF in the
fill-pattern bit map. The foreground and background mix attribute do not
change.

Note:  Background color and mix attribute only apply to monochrome (2-color)
       fill patterns. The bit set to 0 is defined as the background and the bit
       set to 1 is defined as the foreground.

A multi-colored bit map is unaffected by the background color and mix
attributes.

To specify a new color or mix attribute call GpiSetAttrs. This function accepts
as input the type of primitive, for example PRIM_AREA, a list of attributes
that are to be changed, a list of attributes that are to be set to their
default values, and the values for the attributes that are to be changed.
GpiSetAttrs is useful to specify colors and mix attributes just for a specific
data structure, for example the AREABUNDLE. GpiSetAttrs also provides some
protection against invalid colors as described in Presentation Manager
Programming Reference.

To determine the current area color and mix attribute, call GpiQueryAttrs. This
function accepts as input the primitive type and the attributes in question. It
returns as output an array of values for the specifically queried attributes.

To reset the default area color and mix attribute, just as with any other
attribute specified in the AREABUNDLE data structure, call GpiSetDefAttrs. This
function accepts as input the type of primitive, for example PRIM_AREA, the
attributes to be changed, and the values that will become the new default
values. The changing of default values is important when working with segments,
described in Creating and Drawing Retained Graphics and Editing Retained
Graphics and Graphics Segments. Changing the default values during a series of
drawing functions is not recommended.

The area color and mix attribute also can be specified with:

o GpiSetColor
o GpiSetMix
o GpiSetBackColor
o GpiSetBackMix.

However, these functions have the disadvantage of specifying the foreground and
background color or mix attribute for all primitive xxxBUNDLE data structures
that have the respective component.

There are four queries that determine the color and mix attribute as specified
by GpiSetxxx functions:

o GpiQueryColor
o GpiQueryMix
o GpiQueryBackColor
o GpiQueryBackMix.

If the area color, area background color, mix attribute, or background mix
attribute were specified individually, the aforementioned queries can return a
value inconsistent with the current area attribute.


ΓòÉΓòÉΓòÉ 5.1.6. Area Brackets ΓòÉΓòÉΓòÉ

Areas also are referred to as area brackets, because the functions that create
and define the area always are "bracketed" by the two functions, GpiBeginArea
and GpiEndArea.  Only one area is defined between these two functions.
However, within the area, there can be any number of adjacent, intersecting, or
completely separate area primitives.

GpiBeginArea signals the start of a group of primitives that define the
boundary of the area.  The current position is not changed by GpiBeginArea,
although it is updated by any drawing instructions that follow.

If you call GpiSetCurrentPosition or GpiMove within an area definition, the
current figure is closed automatically, and a new figure is started at the
current position by the next line or curve.  A figure in the area, whose start
and end points are not the same, is closed by drawing a straight line from the
current position to the start position of the figure.

GpiEndArea signals the end of an area definition and tells the operating system
to draw the area.  If an application does not close a figure before issuing
GpiEndArea, the figure is closed automatically by drawing a straight line from
the end point of the last line or curve to the start point of the current
figure.  The current position is always updated to the end point of the last
line drawn.

The functional sequence to draw the area in the following figure could be:


#include <os2.h>
void fncAREA01(void){

#if 0

GpiBeginArea                /* Starts the area bracket          */

GpiSetCurrentPosition       /* Set the start point of the       */
                            /* outer hexagon.                   */
GpiPolyLine                 /* Draw the outer hexagon.          */
GpiSetCurrentPosition       /* Set the start point of the inner */
                            /*  hexagon.                        */
GpiPolyLine                 /* Draw the inner hexagon.          */

GpiEndArea                  /* End the area definition.         */

#endif

}


Defining an Area Primitive

An area bracket contains the functions that define an area. Only one area can
be defined between "bracket" functions.

Following the beginning of an area bracket, an application can define the shape
and location of the area in world space by using the following line and arc
functions:

o GpiBox
o GpiFullArc
o GpiLine
o GpiPartialArc
o GpiPointArc
o GpiPolyFillet
o GpiPolyFilletSharp
o GpiPolyLine
o GpiPolySpline

Note:  If an application calls either GpiBox or GpiFullArc inside an area, it
       must use the DRO_OUTLINE option.

In addition to the drawing functions, an application also can use the following
specification functions inside an area bracket:

o GpiBeginElement
o GpiCallSegmentMatrix
o GpiComment
o GpiElement
o GpiEndArea
o GpiEndElement
o GpiGetData
o GpiLabel
o GpiMove
o GpiOffsetElementPointer
o GpiPop
o GpiPutData
o GpiSetArcParams
o GpiSetAttrMode
o GpiSetAttrs
o GpiSetColor
o GpiSetCurrentPosition
o GpiSetEditMode
o GpiSetElementPointer
o GpiSetElementPointerAtLabel
o GpiSetLineEnd
o GpiSetLineJoin
o GpiSetLineType
o GpiSetLineWidth
o GpiSetMix
o GpiSetModelTransformMatrix
o GpiSetSegmentTransformMatrix

An application also can use the following query functions inside an area
bracket:

o GpiQueryArcParams
o GpiQueryAttrMode
o GpiQueryAttrs
o GpiQueryBackColor
o GpiQueryBackMix
o GpiQueryBoundaryData
o GpiQueryCharAngle
o GpiQueryCharBox
o GpiQueryCharDirection
o GpiQueryCharMode
o GpiQueryCharSet
o GpiQueryCharShear
o GpiQueryCharStringPos
o GpiQueryCharStringPosAt
o GpiQueryClipBox
o GpiQueryClipRegion
o GpiQueryColor
o GpiQueryColorData
o GpiQueryColorIndex
o GpiQueryCp
o GpiQueryCurrentPosition
o GpiQueryDefaultViewMatrix
o GpiQueryDefCharBox
o GpiQueryDevice
o GpiQueryDeviceBitmapFormats
o GpiQueryEditMode
o GpiQueryFontFileDescriptions
o GpiQueryFontMetrics
o GpiQueryFonts
o GpiQueryGraphicsField
o GpiQueryInitialSegmentAttrs
o GpiQueryKerningPairs
o GpiQueryLineEnd
o GpiQueryLineJoin
o GpiQueryLineType
o GpiQueryLineWidth
o GpiQueryLineWidthGeom
o GpiQueryLogColorTable
o GpiQueryMarker
o GpiQueryMarkerBox
o GpiQueryMarkerSet
o GpiQueryMix
o GpiQueryModelTransformMatrix
o GpiQueryNearestColor
o GpiQueryNumberSetIds
o GpiQueryPageViewport
o GpiQueryPattern
o GpiQueryPatternRefPoint
o GpiQueryPatternSet
o GpiQueryPel
o GpiQueryPickAperturePosition
o GpiQueryPickApertureSize
o GpiQueryRealColors
o GpiQueryRegionBox
o GpiQueryRegionRects
o GpiQueryRGBColor
o GpiQuerySegmentAttrs
o GpiQuerySegmentNames
o GpiQuerySegmentPriority
o GpiQuerySegmentTransformMatrix
o GpiQuerySetIds
o GpiQueryStopDraw
o GpiQueryTag
o GpiQueryViewingLimits
o GpiQueryViewingTransformMatrix
o GpiQueryWidth


ΓòÉΓòÉΓòÉ 5.1.7. Area Bracket Attributes ΓòÉΓòÉΓòÉ

In addition to the attributes controlled by the AREABUNDLE data structure,
there are two attributes that can be specified for each individual area
bracket:

o Area boundary
o Area construction.
These bracket attributes affect how the area primitives inside the bracket are
drawn.

The concept of attribute currentness, first described in Line and Arc
Primitives, is especially important to areas and paths that contain multiple
figures.


ΓòÉΓòÉΓòÉ 5.1.8. Area Boundaries ΓòÉΓòÉΓòÉ

An application specifies the area boundary when it calls GpiBeginArea.  There
are two options:

o BA_BOUNDARY (the default)
o BA_NOBOUNDARY.

The BA_BOUNDARY value tells the programming interface to draw all outlines of
the area primitives within the area bracket, using a line that conforms to the
current LINEBUNDLE attributes.  If the line attributes have not been changed,
the default outline color is black on most displays and printers, and the
default line style is solid.  An application can change the line color and line
styles within the area bracket.  The interior of the area primitive is filled
with the current pattern.

To prevent the interface from outlining an area, an application can use the
BA_NOBOUNDARY flag when issuing GpiBeginArea.  Only the interior fill pattern
is visible.  This value most often is used when an area contains many
overlapping figures, and the interior lines are not desired.

You could think of this option in terms similar to the outline and fill options
discussed with boxes and full arcs in Line and Arc Primitives.  The BA_BOUNDARY
value corresponds to DRO_OUTLINEFILL; and BA_NOBOUNDARY, to DRO_FILL.  There is
no distinct boundary value that corresponds to DRO_OUTLINE, the simple outline.
To simulate this effect, OR the BA_NOBOUNDARY value with the appropriate area
construction value when issuing GpiBeginArea.


ΓòÉΓòÉΓòÉ 5.1.9. Area Construction ΓòÉΓòÉΓòÉ

An application specifies the area construction when it calls GpiBeginArea.
There are two options:

o BA_ALTERNATE  (the default)
o BA_WINDING.
Construction modes also are called area-fill modes; they provide different ways
of determining whether a given point is included in the filled area.  Normally,
the construction mode you use is a matter of personal preference.


ΓòÉΓòÉΓòÉ 5.1.9.1. Alternate Mode ΓòÉΓòÉΓòÉ

In alternate mode, the following occurs:

o A point is included in the filled area if you have to cross an odd number of
  lines in the area when drawing a line from that point to infinity.

o A point is not included in the filled area if you have to cross an even
  number of lines in the area when drawing a line from that point to infinity.
In the example in the following figure, the inner hexagon is not shaded,
because to draw a line from any point in the hexagon to infinity, you must
cross two boundary lines.  The remainder of the area is shaded, because to move
outside the area, you need to cross only one boundary line.

Calculating Filled Areas Constructed in Alternate Mode


ΓòÉΓòÉΓòÉ 5.1.9.2. Winding Mode ΓòÉΓòÉΓòÉ

In winding mode, the direction in which the boundary lines in the area are
drawn determines whether a given point is included in the filled area.  The
direction of a line depends on both the graphics functions used to draw it and
the world coordinates that define it.  For example, if the current position of
a presentation space is (c,c), and GpiBox is called with the
diagonally-opposite corner of the box specified as (d,d), GpiBox always draws
the box in the following order:

 1. (xc.,yc.) to
 2. (xd.,yc.) to
 3. (xd.,yd.) to
 4. (xc.,yd.) and returning to
 5. (xc.,yc.).

As illustrated in the following figure, in some cases the box is drawn in a
counterclockwise direction. When either xd. is less than xc., or yd. is less
than yc., but not both, a box is drawn clockwise.

The Box

The current position is (3,2) and the specified corner is at (8,6).  The box is
drawn from (3,2) to (8,2) to (8,6) to (3,8) to (3,2).

For the polyline primitive, the direction in which a line is drawn depends on
the relative values of the end points of each line, so you can choose whether
to draw in a clockwise or counterclockwise direction.

To determine if a given point is included in the filled area, count the number
of lines to be crossed to move from that point to infinity.  For each boundary
line drawn in one direction, add one to the tally.  For each line drawn in the
opposite direction, subtract one from the tally.  A point is within the area if
the result is nonzero.

If two figures-for example, the hexagons in the following figure- are drawn in
different directions, the tally for the inner hexagon is 0 and the area will
look exactly as it does in alternate mode.

Area Constructed in Different Directions in Winding Mode

If the two hexagons are drawn in the same direction, the result is 2, and the
inner hexagon is shaded as shown in the following figure.

Area Constructed in the Same Direction in Winding Mode

The boundary lines of the area in the previous figure have been drawn and are
visible through the area-fill pattern. The boundary lines of an area primitive
do not have to be drawn; but if they are, they are drawn according to the
current line attributes.

To vary the appearance of different parts of the boundary line, you can change
the current line attributes during area definition.

The boundary lines of an area are considered a part of the area's interior.
Therefore, when you draw an area without boundary lines (BA_NOBOUNDARY), the
area-fill pattern extends to include the boundaries of the area, and the area
is the same size it would be if the boundary lines had been drawn.


ΓòÉΓòÉΓòÉ 5.1.10. Attribute Currentness ΓòÉΓòÉΓòÉ

Graphics functions that change attributes are valid within the area bracket.
There are misconceptions, however, about which attributes are used when the
figures are displayed in a window or drawn to the printer.

Review the following functional sequence:

Function       Effect

GpiColor       Sets color to red.

GpiBeginArea   Opens area bracket.

GpiLine        Draws a straight line.

GpiColor       Sets color to green.

GpiPolyLine    Draws two additional lines to form a triangle.

GpiEndArea     Ends the area bracket and displays a picture.

If you are displaying on a color monitor, the image appears as follows:

The triangle has one red line, drawn with GpiLine, and two green lines, drawn
with GpiPolyLine.  The interior of the triangle, if drawn, is red.  Red is the
color that was current when the area was defined and, therefore, is the current
color for the area interior.  In terms of the interior area, green is only the
color that was current when the function that initiates drawing was called.

If the application immediately opened a new area bracket, the interior of that
bracket, if drawn, would be green. The color attribute for the second
AREABUNDLE, is not "inherited" from the last AREABUNDLE drawn.


ΓòÉΓòÉΓòÉ 5.2. About Polygon Primitives ΓòÉΓòÉΓòÉ

Area brackets have the flexibility to draw any combination of curved or
straight lines and combine the results into a closed figure.  An advantage that
polygons sometimes have over area brackets, however, is that they require fewer
time-consuming calculations to provide that kind of flexibility.

The operating system provides a function that enables you to draw multiple
straight-line closed areas outside of an area bracket; and like
bracket-generated areas, they can be adjacent, intersecting, or completely
separate.

The function is GpiPolygons, and the set of objects it draws are called polygon
primitives. A polygon primitive is any set of polygons with specified vertices
that can be filled or filled and outlined. This function accepts as input the
desired number of polygons, the POLYGON data structure for each polygon, and a
boundary and construction option similar to those of the GpiBeginArea function.

The purpose of GpiPolygons is to enable you to specify an area in such a way as
to pass all of the area boundaries at once.  This improves performance
significantly because the operating system cannot process the accumulated
primitives inside an area bracket until it reaches the GpiEndArea function.
GpiPolygons is not valid inside an area bracket because the figures it defines
are areas already.

Although GpiPolygons is limited to straight line figures, it retains a great
deal of flexibility.  The polygon data structure (POLYGON) contains the number
of vertices; and the vertices, themselves, are in world coordinates. The
collection of POLYGON structures accepted in a single GpiPolygons function is
not limited to one type of polygon.

The drawing of the first polygon begins at the current position. For all
subsequent polygons, all vertices must be explicitly defined. If the individual
polygons are not completely defined, they are closed with a straight line drawn
from the last defined vertex to the first.

After the application has defined the polygons, they may be transformed and
manipulated just as other primitives are.


ΓòÉΓòÉΓòÉ 5.2.1. Polygon Boundaries ΓòÉΓòÉΓòÉ

Applications have two options when specifying the polygon boundary:

o POLYGON_BOUNDARY (the default)
o POLYGON_NOBOUNDARY.

The POLYGON_BOUNDARY value tells the PM programming interface to draw all
outlines of the polygon primitives using a line that conforms to the current
LINEBUNDLE attributes. If the line attributes have not been changed, the
default outline color is black on most display devices and printers, and the
default line style is solid. As the attributes cannot be changed within the
context of GpiPolygons, all polygons are drawn with the same line. The interior
of the polygons are filled with the pattern that conforms to the current
AREABUNDLE attributes.

To prevent PM from outlining an area, an application can use the
POLYGON_NOBOUNDARY flag when issuing GpiPolygons. Only the interior fill
pattern is visible. This value is used most often when there are many
overlapping polygons, and the interior lines are not desired.

You might think of this option in terms similar to the outline and fill options
discussed with boxes and full arcs in Line and Arc Primitives. The
POLYGON_BOUNDARY value corresponds to the DRO_OUTLINEFILL value; and
POLYGON_NOBOUNDARY, to the DRO_FILL. There is no distinct boundary value that
corresponds to DRO_OUTLINE, the simple outline.

To simulate this effect, OR the POLYGON_NOBOUNDARY value with the appropriate
polygon construction value, described below, when issuing GpiPolygons.


ΓòÉΓòÉΓòÉ 5.2.2. Polygon Construction ΓòÉΓòÉΓòÉ

An application specifies the area construction when it calls GpiBeginArea.
There are two options:

o POLYGON_ALTERNATE (the default)
o POLYGON_WINDING.

As with area construction, in alternate mode:

o A point is included in the filled polygon if you have to cross an odd number
  of lines in the set of polygons when drawing a line from that point to
  infinity.

o A point is not included in the filled polygon if you have to cross an even
  number of lines in the set of polygons when drawing a line from that point to
  infinity.

Also as with area construction, in winding mode, the direction in which the
boundary lines of the polygons are drawn determines whether a given point is
included in the filled polygon. Since the individual polygons drawn with
GpiPolygons are generated by independent structures, the direction in which a
polygon is drawn depends only on the vertices of that polygon.

To determine if a given point is included in the filled polygon, count the
number of lines to be crossed to move from that point to infinity. For each
boundary line drawn in one direction add one to the tally. For each line drawn
in the opposite direction, subtract one from the tally. A point is within the
polygon if the result is nonzero.


ΓòÉΓòÉΓòÉ 5.2.3. Polygon Overlap ΓòÉΓòÉΓòÉ

An application specifies which pels are drawn when it calls GpiPolygons. There
are two options:

o POLYGON_INCL (the default)
o POLYGON_EXCL.

When the overlap value is POLYGON_INCL, the bottom right is included in the
polygon. The value POLYGON_EXCL, the exclusive value, indicates that the bottom
right is excluded from the polygon. This value acts in conjunction with the mix
attribute in determining the appearance of a polygon, which is especially
important for a group of overlapping or adjacent polygons.

For example, GpiPolygons specifies a number of polygons. Two of the polygons
share the vertex pair (6,7) and (9,7). When the polygons are drawn, if the
overlap value was POLYGON_INCL, there are two distinct lines to be drawn from
(6,7) to (9,7). A mix attribute other than FM_OVERPAINT could cause undesirable
results as the line and drawing-surface colors mix.

As with the polygon boundary and construction values, the overlap value can be
ORed when issuing GpiPolygons to create a specific effect.


ΓòÉΓòÉΓòÉ 5.3. Using Area and Polygon Primitives ΓòÉΓòÉΓòÉ

You can use area functions to:

o Draw one or more closed figures
o Create a custom fill pattern from a bit map
o Create a custom fill pattern from a font character.


ΓòÉΓòÉΓòÉ 5.3.1. Drawing a Single, Closed Figure ΓòÉΓòÉΓòÉ

The following figure shows an example of how to use area functions to draw a
single closed figure that is filled with a vertical pattern using the alternate
mode. The closed figure in this example is a 5-pointed star.

#define INCL_GPI
#include <os2.h>
void fncAREA02(void){
   POINTL aptl[5];               /* Structure for current position */
   HPS hps;

    /* Initialize the array of points for the 5-pointed star.       */
    aptl[0].x = 400; aptl[0].y = 195;
    aptl[1].x = 40;  aptl[1].y = 320;
    aptl[2].x = 260; aptl[2].y = 10;
    aptl[3].x = 260; aptl[3].y = 390;
    aptl[4].x = 37;  aptl[4].y = 82;

    GpiSetPattern(hps, PATSYM_VERT);/* Set pattern outside bracket */

    /* Draw the star. */
    GpiBeginArea(hps, BA_ALTERNATE);
    GpiMove(hps, &aptl[4]);         /* First and last point of star */
    GpiPolyLine(hps, 5L, aptl);
    GpiEndArea(hps);
} /* fncAREA02 */


Drawing a Closed Figure


ΓòÉΓòÉΓòÉ 5.3.2. Drawing Multiple, Intersecting, Closed Figures ΓòÉΓòÉΓòÉ

The following figure is an example of how to use area functions to draw two
intersecting boxes, filled, using the winding mode.

#define INCL_GPI
#include <os2.h>
void fncAREA03(void){
    POINTL ptl;            /* Structure for current position */
    HPS    hps;

    GpiBeginArea(hps, BA_WINDING);
    ptl.x = 100;
    ptl.y = 50;
    GpiMove(hps, &ptl);
    ptl.x = 300;
    ptl.y = 250;
    GpiBox(hps, DRO_OUTLINE, &ptl, 0, 0);
    ptl.x = 180;
    ptl.y = 120;
    GpiMove(hps, &ptl);
    ptl.x = 380;
    ptl.y = 320;
    GpiBox(hps, DRO_OUTLINE, &ptl, 0, 0);
    GpiEndArea(hps);
} /* fncAREA03 */


Drawing Multiple Intersecting Closed Figures


ΓòÉΓòÉΓòÉ 5.3.3. Creating a Custom Fill Pattern from a Bit Map ΓòÉΓòÉΓòÉ

The following figure is an example of how to create a custom fill pattern by
using a hard-coded bit map. In this example, the bit map creates a pattern of
arrows.

#define INCL_DOS
#define INCL_GPI
#define INCL_WIN
#include <os2.h>
   LONG lcidCustom;                  /* Bit map tag                           */
   HPS  hps;

   VOID CreatePattern(VOID);

   VOID MyFunction(VOID){
       CreatePattern();
       GpiSetPatternSet(hps, lcidCustom);
        .
        .
        .
   } /* func */

   VOID CreatePattern(VOID){
        HBITMAP hbm;               /* Bit map handle                          */
        BITMAPINFOHEADER2 bmp2;    /* Structure for bit map information       */
        PBITMAPINFO2 pbmi2;        /* Pointer to structure for bit map data   */
        PRGB2 prgb2;               /* Structure for color data                */
        ULONG cbBitmapInfo, cColors;

        BYTE abPattern[] = { 0xFF, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xC3, 0xFF,
                             0xC3, 0xFF, 0x81, 0xFF,
                             0x81, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xFF, 0xFF
   };


        lcidCustom = 1;            /* Bit map tag                             */

        bmp2.cbFix = (ULONG) sizeof(BITMAPINFOHEADER2);
        bmp2.cx = 8;               /* Bit map is 8 pels wide                  */
        bmp2.cy = 8;               /* Bit map is 8 pels high                  */
        bmp2.cPlanes = 1;          /* One bit plane                           */
        bmp2.cBitCount = 1;        /* One bit per pel                         */

        /* Use default values for the remainder of the structure.             */

        bmp2.ulCompression = 0;
        bmp2.cbImage = 0;
        bmp2.cxResolution = 0;
        bmp2.cyResolution = 0;
        bmp2.cclrUsed = 0;
        bmp2.cclrImportant = 0;
        bmp2.usUnits = 0;
        bmp2.usReserved = 0;
        bmp2.usRecording = 0;
        bmp2.usRendering = 0;
        bmp2.cSize1 = 0;
        bmp2.cSize2 = 0;
        bmp2.ulColorEncoding = 0;
        bmp2.ulIdentifier = 0;

        cColors = 1 << (bmp2.cBitCount * bmp2.cPlanes);

        cbBitmapInfo = sizeof(BITMAPINFO2) + (sizeof(RGB2) * cColors);

        DosAllocMem((PVOID)&pbmi2, cbBitmapInfo,
                    PAG_COMMIT | PAG_READ | PAG_WRITE);

        pbmi2->cbFix = bmp2.cbFix;
        pbmi2->cx = bmp2.cx;
        pbmi2->cy = bmp2.cy;
        pbmi2->cPlanes = bmp2.cPlanes;
        pbmi2->cBitCount = bmp2.cBitCount;

        /* Use default values for the remainder of the structure.             */

        pbmi2->ulCompression = 0;
        pbmi2->cbImage = 0;
        pbmi2->cxResolution = 0;
        pbmi2->cyResolution = 0;
        pbmi2->cclrUsed = 0;
        pbmi2->cclrImportant = 0;
        pbmi2->usUnits = 0;
        pbmi2->usReserved = 0;
        pbmi2->usRecording = 0;
        pbmi2->usRendering = 0;
        pbmi2->cSize1 = 0;
        pbmi2->cSize2 = 0;
        pbmi2->ulColorEncoding = 0;
        pbmi2->ulIdentifier = 0;

        prgb2 = (PRGB2) (pbmi2 + 1);  /* Set address to follow bmp2           */

        /* Set bit map colors to black and white.                             */
        prgb2[0].bBlue = 0;                               /* Color[0] = black */
        prgb2[0].bGreen = 0;                              /* Color[0] = black */
        prgb2[0].bRed = 0;                                /* Color[0] = black */
        prgb2[0].fcOptions = 0;
        prgb2[1].bBlue = 255;                             /* Color[1] = white */
        prgb2[1].bGreen = 255;                            /* Color[1] = white */
        prgb2[1].bRed = 255;                              /* Color[1] = white */
        prgb2[1].fcOptions = 0;

        /* Create a bit map and retrieve its handle.                          */
        hbm = GpiCreateBitmap(hps,
            &bmp2,
            CBM_INIT,
            (PBYTE) abPattern,                            /* Array of bits    */
            pbmi2);

        /* Tag the bit map just created with a custom identifier (lcid).      */
        GpiSetBitmapId(hps, hbm, lcidCustom);
   } /* CreatePattern */


Creating a Custom Fill Pattern from a Bit Map


ΓòÉΓòÉΓòÉ 5.3.4. Creating a Custom Fill Pattern from a Font Character ΓòÉΓòÉΓòÉ

The following figure is an example of how to create a custom fill pattern by
using a character from a font. The fill pattern can be only an 8-by-8 bit map;
as a result, not all of the character is used.

#define INCL_GPI
#define INCL_WIN
#include <os2.h>
   HPS hps;                      /* Presentation-space handle */
   LONG lcidCustom;              /* Font identifier           */
   FONTMETRICS afm[80];
   FATTRS fat;

   VOID LoadFont(VOID);

   void fncAREA05(void){

figseg fit=11.
        LoadFont();
GpiSetPatternSet(hps, lcidCustom);
GpiSetPattern(hps, 'o');         /* Use lowercase 'o' as fill */
    .
    .
    .
   } /* fncAREA05 */

   VOID LoadFont(VOID){
      LONG cFonts = 0;
      LONG cPublicFonts, i;

      lcidCustom = 1;

/* Determine the number of loaded public fonts.               */
cPublicFonts = GpiQueryFonts(hps, QF_PUBLIC, NULL, (PLONG) &cFonts,
    (LONG) (sizeof(FONTMETRICS)), NULL);

/* Load the metrics for all public fonts into afm.            */
GpiQueryFonts(hps, QF_PUBLIC, NULL, (PLONG) &cPublicFonts,
    (LONG) (sizeof(FONTMETRICS)), afm);

/* Get the first image font with a point size larger than 8.  */
for (i = 0; ((afm[i].fsDefn & FM_DEFN_OUTLINE) ||
     afm[i].lEmHeight <= 8) && i < cPublicFonts; i++);

/* Load the FATTRS structure with the required metrics.       */
fat.usRecordLength = sizeof(fat);
fat.fsSelection = 0;
fat.lMatch = afm[i].lMatch;
StringCopy(fat.szFacename, afm[i].szFacename);
fat.idRegistry = 0;
fat.usCodePage = 0;
fat.lMaxBaselineExt = 0;
fat.lAveCharWidth = 0;
fat.fsType = 0;
fat.fsFontUse = 0;

/* Select this font and assign it a custom lcid.              */
GpiCreateLogFont(hps, NULL, lcidCustom, &fat);
GpiSetCharSet(hps, lcidCustom);
} /* LoadFont */

Creating a Custom Fill Pattern from a Font Character


ΓòÉΓòÉΓòÉ 5.4. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the area and polygon primitive functions.

Area-Primitive Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginArea            ΓöéStarts the area bracket and sets theΓöé
Γöé                        Γöéoutline option and fill mode.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndArea              ΓöéEnds the area bracket and draws the Γöé
Γöé                        Γöéarea.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPolygons             ΓöéDraws a series of closed,           Γöé
Γöé                        Γöéstraight-line figures.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPattern         ΓöéDetermines the current bit map fill Γöé
Γöé                        Γöépattern.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPatternRefPoint ΓöéDetermines the fill-pattern         Γöé
Γöé                        Γöéreference point in world            Γöé
Γöé                        Γöécoordinates.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPatternSet      ΓöéDetermines the local identifier of aΓöé
Γöé                        Γöébit map or font.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPattern           ΓöéDefines the fill pattern from the   Γöé
Γöé                        Γöésupplied patterns or from a code    Γöé
Γöé                        Γöépoint for a character or symbol in aΓöé
Γöé                        Γöéfont.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPatternRefPoint   ΓöéDefines the fill-pattern reference  Γöé
Γöé                        Γöépoint in world coordinates.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPatternSet        ΓöéDefines the fill-pattern attribute  Γöé
Γöé                        Γöéto a local identifier of a bit map  Γöé
Γöé                        Γöéor font.                            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following table summarizes the data structures used by the area and polygon
primitive functions.

Area-Primitive Structure

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAREABUNDLE              ΓöéA structure of area primitive       Γöé
Γöé                        Γöéattributes.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEBUNDLE              ΓöéA structure of line primitive       Γöé
Γöé                        Γöéattributes, which controls the      Γöé
Γöé                        Γöéoutline of the area primitives.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPOINTL                  ΓöéA structure specifying the values a Γöé
Γöé                        Γöésingle pair of x- and y-coordinates.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPOLYGON                 ΓöéA structure that describes a        Γöé
Γöé                        Γöéstraight line polygon. It contains aΓöé
Γöé                        Γöécount of the vertices, and an array Γöé
Γöé                        Γöéof POINTL structures to describe theΓöé
Γöé                        Γöécoordinates of each vertex.         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 6. Character String Primitives ΓòÉΓòÉΓòÉ

Character string primitives are printed or displayed text limited to a length
of 256 characters by the PM programming interface.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Color and mix attributes
o Fonts
o Coordinate spaces
o Transformations.


ΓòÉΓòÉΓòÉ 6.1. About Character String Primitives ΓòÉΓòÉΓòÉ

A PM application must make certain choices about fonts in preparation for text
display or printing. Often these choices are driven by selections from a user.
After the selections are made, as discussed in Fonts, the application can make
additional decisions about the appearance of the individual characters within
the font by setting attributes in the CHARBUNDLE data structure. CHARBUNDLE is
the lowest of three levels of data structures that define the appearance of
displayed or printed text. The other two, FONTMETRICS and FATTRS, are described
in Fonts.

A font family-for instance, Helvetica** or Courier-is a collection of fonts.
Fonts within the same family share certain attributes such as stroke width and
serif characteristics. However, the individual fonts differ from each other in
the following ways:

o Height
o Line weight
o Appearance.

Stroke width refers to the width of lines used to draw characters and symbols
from a font. A serif is a short crossline drawn at the ends of the main strokes
that form a character or symbol. Height refers to the point size of a font. A
common example of line weight is boldface. A common example of appearance is
italic.

The most important factor that affects the CHARBUNDLE attributes is whether the
current font is an image or an outline font. The following figure shows an
example of the difference.

Image and Outline Fonts

Outline fonts are composed of characters drawn with straight and curved lines.
Image fonts, also called bit map fonts, are composed of pels arranged in
certain shapes.


ΓòÉΓòÉΓòÉ 6.1.1. Attributes of Character String Primitives ΓòÉΓòÉΓòÉ

Attributes of the character string primitives contained in CHARBUNDLE are as
follows:

o Character set
o Character mode
o Character cell
o Character angle
o Character shear
o Character direction
o Character text alignment
o Character extra
o Character break extra
o Foreground color
o Background color
o Foreground mix
o Background mix.

When an application creates a presentation space, the character string
attributes are set to the default values shown in the following table.

Character String Attribute Default Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute   ΓöéDefault Value           ΓöéFunction that Redefines Attribute Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSet         ΓöéLCID_DEFAULT            ΓöéGpiSetCharSet                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMode        ΓöéCM_MODE1                ΓöéGpiSetCharMode                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCell        ΓöéOutline font - Defined  ΓöéGpiSetCharBox                     Γöé
Γöé            Γöéby device               Γöé                                  Γöé
Γöé            ΓöéImage font - Defined by Γöé                                  Γöé
Γöé            Γöéfont                    Γöé                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAngle       Γöé(1,0)                   ΓöéGpiSetCharAngle                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéShear       Γöé(0,1)                   ΓöéGpiSetCharShear                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDirection   ΓöéLeft to right           ΓöéGpiSetCharDirection               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéText        ΓöéLeft                    ΓöéGpiSetTextAlignment               Γöé
Γöéalignment   Γöé                        Γöé                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéExtra       Γöé0                       ΓöéGpiSetCharExtra                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBreak extra Γöé0                       ΓöéGpiSetCharBreakExtra              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground  ΓöéBlack                   ΓöéGpiSetAttrs (CBB_COLOR)           Γöé
Γöécolor       Γöé                        Γöé                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground  ΓöéClear                   ΓöéGpiSetAttrs (CBB_BACK_COLOR)      Γöé
Γöécolor       Γöé                        Γöé                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground  ΓöéOverpaint               ΓöéGpiSetAttrs (CBB_MIX_MODE)        Γöé
Γöémix         Γöé                        Γöé                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground  ΓöéLeave alone             ΓöéGpiSetAttrs (CBB_BACK_MIX_MODE)   Γöé
Γöémix         Γöé                        Γöé                                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Current character attributes take effect when you send graphics characters to
an output device; they have no effect at the time you define a logical font.


ΓòÉΓòÉΓòÉ 6.1.2. Character Set ΓòÉΓòÉΓòÉ

Character set defines the local identifier, lcid, of the current font. The font
lcid is set using GpiSetCharSet. GpiCreateLogFont, described in Fonts,
associates the font with an lcid.

The value of the current lcid is determined using GpiQueryCharSet.


ΓòÉΓòÉΓòÉ 6.1.3. Character Mode ΓòÉΓòÉΓòÉ

Every presentation space has a current character mode, which determines the
extent to which a font can be affected by the attributes defined in CHARBUNDLE.
The mode affects compatibility issues that are invisible to both the user and
the programmer. The following table describes the character modes and their
influences on the current font.

An application selects a character mode using GpiSetCharMode. When a mode is
selected, it applies to any font (including the system font) used while the
mode is current. The character mode takes effect when you draw character
strings; it has no effect at the time you define a logical font.

Character Mode Effects on Character Attributes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCharacter ΓöéIf Image Font...            ΓöéIf Outline Font...    Γöé
ΓöéMode      Γöé                            Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCM_MODE1  ΓöéIgnores all current         ΓöéAffected by all       Γöé
Γöé          Γöécharacter attributes, exceptΓöécurrent character     Γöé
Γöé          Γöécharacter direction.        Γöéattributes.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCM_MODE2  ΓöéUses the character shear,   ΓöéAffected by all       Γöé
Γöé          Γöébox, angle, and direction   Γöécurrent character     Γöé
Γöé          Γöéattributes to position the  Γöéattributes.           Γöé
Γöé          Γöécharacter cell, but the     Γöé                      Γöé
Γöé          Γöécharacters themselves are   Γöé                      Γöé
Γöé          Γöénot sheared, rotated,       Γöé                      Γöé
Γöé          Γöéscaled, or reversed.        Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCM_MODE3  ΓöéRaises an error if you try  ΓöéAffected by all       Γöé
Γöé          Γöéto draw a character string. Γöécurrent character     Γöé
Γöé          ΓöéNote:  Any font used when   Γöéattributes.           Γöé
Γöé          Γöéthe current character mode  Γöé                      Γöé
Γöé          Γöéis CM_MODE3 must be an      Γöé                      Γöé
Γöé          Γöéoutline font.               Γöé                      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The default character mode (CM_DEFAULT) is identical to CM_MODE1.


ΓòÉΓòÉΓòÉ 6.1.4. Character Cell ΓòÉΓòÉΓòÉ

A character cell is an imaginary rectangular boundary that defines the
horizontal and vertical space occupied by a single character from an outline
character set.

The PM programming interface calculates character cell width and height from
the point size. The width value for the character cell is the nominal width of
the lowercase characters in the character set. In a monospace font, the width
of all character cells is identical. In a proportional font, the width of the
character cells depends on the character.

In an image font, the height of the character cell is the number of pels in the
font. In an outline font, the height of the character cell is the point size of
the font.

The characters in a character string are positioned one character per cell. The
spacing between adjacent characters in a string is affected by the character
cell attribute, except for image characters in CM_MODE1.

Cell width determines the spacing of consecutive characters along the baseline,
as illustrated in the following figure.

Character Cell Measurements

Current cell size is specified using GpiSetCharBox. As input, this function
accepts the desired height and width of the character cell in world
coordinates. These values are related to certain dimensions in the FONTMETRICS
structure that controls font attributes. Heights or widths of 0 are valid input
and cause the outline character to be drawn as a point or straight line.
Heights or widths of negative values cause certain special effects, for
example, reversed lettering.

The character cell value affects both the size and position of characters drawn
from an outline font, regardless of the current character mode. Each character
is scaled up or down to fit the cell size, as shown in the following figure.

Effect of the Character Cell on an Outline Font

The character cell value is ignored if the current font is an image font and
the current character mode is CM_MODE1, as shown in the following figure.

Note:  It is essential to code the character cell correctly, even if you
       anticipate using image fonts. In case of a font match failure, an
       outline font can be substituted for a image font.

Effect of the Character Cell on an Image Font in CM_MODE1

Although the character cell has been both increased and decreased, the
character string is unaltered.

The character cell value controls the positioning of image-font characters when
the current character mode is CM_MODE2; but it cannot cause the characters to
be scaled to fit the cell. This effect is shown in the following figure.

Effect of the Character Cell on an Image Font in CM_MODE2

If you increase the character cell size for an image font in CM_MODE2, the
characters are more widely spaced, but their size is not changed. If you
decrease character cell size, the space between the characters is reduced, and
because the characters themselves cannot be scaled, they can overlap.


ΓòÉΓòÉΓòÉ 6.1.4.1. Default Character Cell ΓòÉΓòÉΓòÉ

The default character-cell size is a device-dependent value. You do not need to
know this value unless you want to switch back to the initial default value
after having specified another value. It is recommended that you save initial
default values using GpiSavePS.

The default character cell, like other default attributes, can be set using
GpiSetDefAttrs (CBB_BOX). If necessary, you can query the current default value
using GpiQueryDefAttrs.


ΓòÉΓòÉΓòÉ 6.1.4.2. Coding a Character Cell ΓòÉΓòÉΓòÉ

The dimensions that an application passes to GpiSetCharBox and that
GpiQueryCharBox returns are fixed-point values. A fixed value is a 32-bit value
whose high-order 16 bits contain the integral part of the floating-point number
and whose low-order 16 bits contain the fractional part. The fractional part is
the numerator of a fraction whose denominator is fixed at 65536. The MAKEFIXED
macro provides a method for producing fixed values. If, for example, one of the
character cell dimensions were 7.635 world units, an application could obtain
the corresponding fixed value by using the MAKEFIXED macro, passing 7 as the
first argument and 41615 as the second.

The purpose of the character cell is to assist other font metrics, described in
Fonts, to define text lines. For example, if you planned to have an average
text line of 60 characters, dividing your output width by 60 would provide your
character cell width.

DevQueryCaps can be used to provide information about suitable character cell
values. DevQueryCaps returns two sets of values that can influence the
character cell:

o Default cell values

   - CAPS_GRAPHICS_CHAR_WIDTH
   - CAPS_GRAPHICS_CHAR_HEIGHT.

o Device resolution

   - CAPS_HORIZONTAL_FONT_RES
   - CAPS_VERTICAL_FONT_RES.

The default cell values return the size of the default character cell in pels.
Convert the device resolution into character cell values by multiplying it by
the desired point size, then dividing by 72 (72.2818).


ΓòÉΓòÉΓòÉ 6.1.5. Character Angle ΓòÉΓòÉΓòÉ

The character angle is defined by the x-axis and a vector drawn through the
origin to a specified point in a Cartesian coordinate system. Neither (0,0) nor
the specified point need have any relation to the current position. The
operating system then aligns the baseline with this vector.

An application can retrieve the point that defines the character angle vector
using GpiQueryCharAngle. An application can set the character angle using
GpiSetCharAngle. This function accepts as input the x- and y-coordinates of a
point that defines the new vector. When you specify an angle, it becomes the
current setting. To reset the character angle vector to its default value
(parallel to the x-axis), call GpiSetCharAngle with both x and y equal to 0.

The effects of the current character angle vary depending on the current
character mode and the current font type. When the current font is an outline
font, the current character angle determines the angle of both the whole string
and the individual characters in the string, regardless of the current
character mode. The baseline of each character cell is drawn parallel to the
new baseline, as shown in the following figure.

Effect of the Character Angle on an Outline Font

The character string is drawn parallel to the vector drawn from the origin to
(10,7). The baseline of each of the character cells also is drawn parallel to
this vector.

The character angle value is ignored if the current font is an image font and
the current character mode is CM_MODE1, as shown in the following figure.

Effect of the Character Angle on an Image Font in CM_MODE1

The angle of the character string is unaltered by GpiSetCharAngle.

When the current font is an image font and the current character mode is
CM_MODE2, the current character angle determines the angle of the whole string
but does not affect the individual characters in the string. The character
reference point, which is the point at which the character baseline intersects
the left edge of the character cell, is placed on a line parallel to the new
baseline. The baseline of each character cell remains parallel to the x-axis,
as shown in the following figure.

Effect of the Character Angle on an Image Font in CM_MODE2

The character string is drawn parallel to the vector from (0,0) to (10,7).

Each of the characters in the string in the previous figure is drawn with the
vertical sides of its character cell parallel to the y-axis, and with the
horizontal sides of its character box parallel to the x-axis.


ΓòÉΓòÉΓòÉ 6.1.6. Character Shear ΓòÉΓòÉΓòÉ

Character shear is the angle defined by the x-axis and a vector drawn through
the origin to a specified point in a Cartesian coordinate system. Neither (0,0)
nor the specified point need have any relation to the current position. The
operating system then aligns the vertical sides of the character cell. If the
font is an outline font, the operating system also aligns the vertical strokes
of the characters with the vector, regardless of the current character mode, as
shown in the following figure.

An application can retrieve the point that defines the character shear vector
using GpiQueryCharShear. An application can set the character shear using
GpiSetCharShear, which accepts as input the x- and y-coordinates of a point
that defines the new vector in a POINTL structure.

The shear of a character is the angle formed by the vertical lines of the
character cell, and it can affect both the positioning and shape of characters
in the character string. By default, the vertical lines of a character cell are
parallel to the y-axis of the presentation page. As input to GpiCharShear,
supply the coordinates of the end point of a vector drawn from the origin
(0,0). The effects of the current character shear value vary, depending on the
current character mode and font type.

Effect of Character Shear on an Outline Font

The character cell is drawn with its vertical lines parallel to the vector from
the origin to (5,6). The character is sheared to the same degree.

The character-shear value is ignored if the current font is an image font and
the current character mode is CM_MODE1, as shown in the following figure.

Effect of Character Shear on an Image Font in CM_MODE1

The character string is unaffected by the character-shear value.

The character-shear value affects the positioning of the characters from an
image font in CM_MODE2 only if character direction is CHDIRN_TOPBOTTOM or
CHDIRN_BOTTOMTOP. That is, characters drawn vertically do not appear in a
vertical line for nonzero shear angle from the vertical. The characters
themselves cannot be sheared, as shown in the following figure.

Effect of Character Shear on an Image Font in CM_MODE2

The character cell is sheared; and it controls the positioning of the
characters, but the characters themselves are unchanged.

If the x- and y-coordinate values you specify in GpiSetCharShear are both
positive and negative, the characters slant from lower left to upper right. If
you supply one negative and one positive value, the characters slant from upper
left to lower right, as illustrated in the following figure.

Effect of X- and Y-Values on Character Shear

Character shear, like other attributes, has a default value that can be changed
using GpiSetDefAttrs (CBB_SHEAR). To reset the character shear to its default
effect of drawing the vertical lines of the character cell parallel to the
y-axis, supply a coordinate value of (0,1) on GpiSetCharShear.


ΓòÉΓòÉΓòÉ 6.1.7. Character Direction ΓòÉΓòÉΓòÉ

Character direction is the direction in which the characters in a string are
drawn in relation to the baseline. By default, the characters are drawn from
left to right. An application can change the direction using
GpiSetCharDirection. GpiSetCharDirection accepts as input 1 of the 4 values
illustrated in the following figure. The value CHDIRN_DEFAULT is identical to
CHDIRN_LEFTRIGHT.


ΓöîΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÉ            ΓöîΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÉ
Γöé A Γöé B Γöé C Γöé            Γöé C Γöé B Γöé A Γöé
ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÿ            ΓööΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÿ
                                  
start       end          end         start

CHDIRN_LEFTRIGHT         CHDIRN_RIGHTLEFT


start                    end
                          
ΓöîΓöÇΓöÇΓöÇΓöÉ                    ΓöîΓöÇΓöÇΓöÇΓöÉ
Γöé A Γöé                    Γöé C Γöé
Γö£ΓöÇΓöÇΓöÇΓöñ                    Γö£ΓöÇΓöÇΓöÇΓöñ
Γöé B Γöé                    Γöé B Γöé
Γö£ΓöÇΓöÇΓöÇΓöñ                    Γö£ΓöÇΓöÇΓöÇΓöñ
Γöé C Γöé                    Γöé A Γöé
ΓööΓöÇΓöÇΓöÇΓöÿ                    ΓööΓöÇΓöÇΓöÇΓöÿ
                          
end                      start

CHDIRN_TOPBOTTOM         CHDIRN_BOTTOMTOP


Effect of Character Direction on an Image Font or Outline Font

An application can determine the current character direction using
GpiQueryCharDirection.


ΓòÉΓòÉΓòÉ 6.1.8. Character Text Alignment ΓòÉΓòÉΓòÉ

Character text alignment is the attribute that describes how the character
strings are drawn with respect to the boundary of the output, either the
current position or the starting position of the string, if a
GpiCharStringxxxAt function draws the string. The alignment is set using
GpiSetTextAlignment, which accepts as input a long value for horizontal and
vertical alignment.

The acceptable values for GpiSetTextAlignment depend on the direction of the
current coordinate system, as follows:

Value          Corresponds to the direction of...

Left           The lowest x-coordinate value

Right          The highest x-coordinate value

Top            The highest y-coordinate value

Bottom         The lowest y-coordinate value

Internally, the PM programming interface determines a reference point within a
character string that is to be positioned over the starting point specified for
the string.

If an application draws the string with either GpiCharString or
GpiCharStringPos, the starting point specified for the string is the current
position. If the application draws the string with either GpiCharStringAt or
GpiCharStringPosAt, the starting point specified for the string is accepted as
input by the function.


ΓòÉΓòÉΓòÉ 6.1.8.1. Horizontal Alignment of a Character String ΓòÉΓòÉΓòÉ

When a horizontal character string does not fill the width of the output area,
it can be positioned in 1 of the 3 ways shown in the following figure. All of
these options can be set directly with the lHorizontal option of
GpiSetTextAlignment.

Horizontal Positioning of Text Strings

Text justification requires an application to perform both queries and
coordinate calculations. The following flags are used to specify types of
horizontal alignment:

Horizontal Alignment Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIdentifier              ΓöéAlignment                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_LEFT                 ΓöéOn the left edge of the leftmost    Γöé
Γöé                        Γöécharacter in the string             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_RIGHT                ΓöéOn the right edge of the rightmost  Γöé
Γöé                        Γöécharacter in the string             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_CENTER               ΓöéOn the arithmetic mean of the       Γöé
Γöé                        Γöéleftmost and rightmost characters inΓöé
Γöé                        Γöéthe string                          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The Presentation Manager Programming Reference describes two sets of default
values for the lHorizontal option.  They are provided for compatibility and map
into the horizontal alignment values described above.

GpiQueryGraphicsField, GpiQueryPageViewport, and GpiQueryViewingLimit all
provide methods of determining the width of the output area so your application
can specify coordinates properly for the current position.


ΓòÉΓòÉΓòÉ 6.1.8.2. Vertical Alignment of a Character String ΓòÉΓòÉΓòÉ

When a character string is to be displayed vertically, it can be positioned in
1 of the 4 ways illustrated in the following figure. The vertical options all
can be set directly using the lVertical option of GpiSetTextAlignment.

Vertical Positioning of Text Strings

The following flags are used to specify types of vertical alignment:

Vertical Alignment Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIdentifier              ΓöéAlignment                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_TOP                  ΓöéOn the top edge of the topmost      Γöé
Γöé                        Γöécharacter in the string             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_HALF                 ΓöéOn the arithmetic mean of the       Γöé
Γöé                        Γöétopmost and bottommost characters inΓöé
Γöé                        Γöéthe string                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_BASE                 ΓöéOn the baseline of the bottommost   Γöé
Γöé                        Γöécharacter in the string             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTA_BOTTOM               ΓöéOn the bottom edge of the bottommostΓöé
Γöé                        Γöécharacter in the string             Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The Presentation Manager Programming Reference also describes 2 sets of default
values for the lVertical option.  They are provided for compatibility and map
into the vertical alignment values described above.


ΓòÉΓòÉΓòÉ 6.1.9. Character Extra and Break Extra ΓòÉΓòÉΓòÉ

Certain output devices permit you to specify extra space between character
cells by using the character extra attribute. Sometimes the space between words
also can be expanded by increasing the size of the break character, usually
defined as the space character, by using the break extra attribute. If this
adjustment to either attribute is permitted, the result will be in addition to
the sizing effects caused by the following parameters:

o Font kerning
o Font proportional spacing
o Width vectors.

The break values you can specify create different effects, as follows:

Break Values and Their Effects

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue                   ΓöéEffect                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPositive                ΓöéForces characters apart.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0                       ΓöéResumes the default spacing created Γöé
Γöé                        Γöéby other parameters.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNegative                ΓöéForces characters together, even    Γöé
Γöé                        Γöéoverlapped characters.              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

These effects are illustrated in the following figure.

The Cumulative Effect of Break Values

The above are fixed integer values specified in world coordinates. Both the
character extra and break extra attributes have initial default values of 0,
which can be changed using GpiSetDefAttrs (CBB_EXTRA) and (CBB_BREAK_EXTRA).
These values can be changed using GpiSetCharExtra or GpiSetCharBreakExtra,
respectively; and the values can be queried using GpiQueryCharExtra and
GpiQueryCharBreakExtra.


ΓòÉΓòÉΓòÉ 6.1.10. Character Color and Mix ΓòÉΓòÉΓòÉ

The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface or any other objects on the
surface. Both of these attributes are described in detail in Color and Mix
Attributes.

The character-string color defines the color used to draw the output from any
of the draw-character-string functions. When a presentation space is created,
the character-string color default is black. Character strings are one of the
primitives that have both a foreground and a background color, as shown in the
following figure.

For image characters, colors are determined by setting pels. For outline
characters, the foreground consists of arcs and lines that define the
character; the background color appears between the foreground lines. The
character can be solid or filled, in which cases the background color does not
appear between the foreground lines.

Character string primitives have a color attribute for both the actual
character and its character cell, which surrounds the character. The
character-cell color is the background color.

The foreground mix attribute controls the combination of character-string color
and drawing-surface color, while the background mix attribute controls the
combination of the character-cell color and the drawing-surface color, as
illustrated in the following figure.

Character String Primitives

When a presentation space is created, the character string mix attribute
default is FM_OVERPAINT. The overpaint mix attribute specifies that the
character-string color is not to be modified by the color of the drawing
surface. If the character string mix attribute is changed, the character-string
color is mixed with colors that are already on the drawing surface.

The character string background color default is CLR_BACKGROUND, usually
defined by the application as the same color as the drawing surface. The
character string background mix attribute default is BM_LEAVEALONE. The
leave-alone background mix attribute specifies that the character string
background color not be drawn. The cell that surrounds the character string
appears only if the background character-string color and mix attributes are
changed.

Use GpiSetAttrs to specify a new color or mix attribute. As input, this
function accepts the following:

o Type of primitive, for example, PRIM_CHAR
o List of attributes to be changed
o List of attributes to be set to their default values
o Values for the attributes to be changed.

GpiSetAttrs also is useful to specify color and mix attributes for a specific
data structure, for example, CHARBUNDLE. GpiSetAttrs provides some protection
against invalid colors, as described in the Presentation Manager Programming
Reference.

To determine the current character-string color and mix attributes, call
GpiQueryAttrs, which accepts as input the primitive type and the attributes in
question. GpiQueryAttrs returns an array of values for the queried attributes.

To reset the default character-string color and mix attributes, as with all
attributes specified in CHARBUNDLE, call GpiSetDefAttrs, which accepts as input
the type of primitive, attributes to be changed, and values that will become
the new default values. Changing default values is especially important when
working with segments, described in Creating and Drawing Retained Graphics and
Editing Retained Graphics and Graphics Segments. Changing the default values
during a series of drawing functions is not recommended.

The character color and mix attributes also can be specified using the
following functions:

o GpiSetColor
o GpiSetMix
o GpiSetBackColor
o GpiSetBackMix.

If the character color, character background color, mix, or background mix
attributes are specified individually, the following queries can return a value
inconsistent with the current character attributes:

o GpiQueryColor
o GpiQueryMix
o GpiQueryBackColor
o GpiQueryBackMix.


ΓòÉΓòÉΓòÉ 6.2. Using Character String Primitives ΓòÉΓòÉΓòÉ

You can use the character string primitive functions to perform the following
tasks:

o Draw a string of characters using the selected font.

o Modify the string by using one or more of the following operations:

   Scaling
   Shearing
   Rotating
   Transforming
   Changing the angle of the baseline.

o Aligning Text.


ΓòÉΓòÉΓòÉ 6.2.1. Drawing Text ΓòÉΓòÉΓòÉ

The following figure shows how to select a Helvetica outline font, set the size
of the character box, change the foreground color to red, set the character
angle, and move the cursor to a specified location. Then, GpiCharString is used
to write a string of characters with the specified size, color, angle, and
location.

#define INCL_GPIPRIMITIVES
#define INCL_GPILCIDS
#include <os2.h>
void fncFONT09(void){

    POINTL ptl = { 100, 50 };
    GRADIENTL grad = { 4, 1 };
    SIZEF sizfx;
    FATTRS fat;
    CHARBUNDLE cbnd;
    FONTMETRICS afm[80];
    HPS hps;
    HDC hdc;
    LONG cHelvFonts, i;
    LONG cFonts = 0;
    LONG lcid = 1;
    LONG devRes[2];               /* Horizontal, vertical font resolutions */

    cHelvFonts = GpiQueryFonts(hps, QF_PUBLIC, "Helv",
        &cFonts, sizeof(FONTMETRICS), NULL);

    GpiQueryFonts(hps, QF_PUBLIC, "Helv", &cHelvFonts,
        sizeof(FONTMETRICS), afm);
                                  /* Find an outline Helvetica font.       */

    for (i = 0; (!(afm[i].fsDefn & FM_DEFN_OUTLINE)) &&
               i < cHelvFonts; i++)    ;

    fat.usRecordLength = sizeof(FATTRS);
    fat.fsSelection = 0;
    fat.lMatch = afm[i].lMatch;
    StringCopy(fat.szFacename, afm[i].szFacename);
    fat.idRegistry = 0;
    fat.usCodePage = 0;
    fat.lMaxBaselineExt = 0;
    fat.lAveCharWidth = 0;
    fat.fsType = 0;
    fat.fsFontUse = FATTR_FONTUSE_OUTLINE;

    GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fat);
    GpiSetCharSet(hps, lcid);

    DevQueryCaps(hdc, CAPS_HORIZONTAL_FONT_RES, 2L, devRes);
    sizfx.cx = MAKEFIXED((afm[i].sNominalPointSize * devRes[0])/ 720, 0);
    sizfx.cy = MAKEFIXED((afm[i].sNominalPointSize * devRes[1])/ 720, 0);
    GpiSetCharBox(hps, &sizfx);

    cbnd.lColor = CLR_RED;
    GpiSetAttrs(hps, PRIM_CHAR, CBB_COLOR, NULLHANDLE, &cbnd);
    GpiSetCharAngle(hps, &grad);
    GpiMove(hps, &ptl);
    GpiCharString(hps, 11, "Vector Text");
} /* fncFONT09 */


Drawing Text

Certain parameters in the above example are explained in Fonts.


ΓòÉΓòÉΓòÉ 6.2.2. Formatting Text ΓòÉΓòÉΓòÉ

Graphics text, like all other graphics objects, has to be positioned correctly
in the output area, which usually consists of one of the following:

o Entire client area of a PM window
o Part of a PM window
o Addressable area of a printer.

Unlike other graphics objects, however, text is governed by well-established
readability and usability rules. These rules apply generally to text output,
whatever its method of production.  Following are some recommendations:

o Lines of text from fonts with large point sizes must be more widely spaced
  for maximum readability.

o The longer the line of text, the greater the space between lines must be to
  ensure that the lines do not appear to merge.

o Very small text must be split into multiple columns rather than continued
  across the page.

Some of these considerations are taken care of by the font designer. The PM
programming interface enables you to control both the horizontal and vertical
positioning of text.


ΓòÉΓòÉΓòÉ 6.2.3. Positioning Text in World Coordinates ΓòÉΓòÉΓòÉ

When considering text alignment, take the versatility of the coordinate systems
into account. The following definitions depend on the current coordinate
system:

World Coordinate Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue          ΓöéCorresponds to the direction of...           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLeft           ΓöéThe lowest x-coordinate value                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRight          ΓöéThe highest x-coordinate value               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTop            ΓöéThe highest y-coordinate value               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBottom         ΓöéThe lowest y-coordinate value                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

To position a character string horizontally, you must know the width of the
output area and the length of the character string. The PM programming
interface provides three different functions for determining the width of the
output:

Functions for Determining Width of Character String Primitives

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryGraphicsField   ΓöéReturns the bottom-left and         Γöé
Γöé                        Γöétop-right corners of the graphics   Γöé
Γöé                        Γöéfield in presentation page units.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryViewingLimits   ΓöéReturns the viewing limit.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPageViewport    ΓöéReturns the page viewport in device Γöé
Γöé                        Γöéunits.                              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

All three functions are described in the Presentation Manager Programming
Reference.

The GpiConvert function changes coordinates into world coordinates. To
calculate the width of the output area, subtract its left from its right. For
example, if the left is 30, and right is 600, the width of the output area is
570 world coordinates.

The PM programming interface provides three different functions for determining
the length of the character string primitive:

o GpiQueryTextBox
o GpiQueryCharStringPos
o GpiQueryCharStringPosAt.

GPiQueryTextBox returns the relative coordinates of a parallelogram that
surrounds the character string. By subtracting the x-coordinate of
TXTBOX_BOTTOMRIGHT from the x-coordinate of TXTBOX_BOTTOMLEFT, an application
can determine the length of the string.

GpiQueryCharStringPos returns an array of points, in which the world coordinate
position of each character in the string is recorded. The last value in the
array becomes the new current position if the string is drawn using
GpiCharStringPos. By subtracting this position from the current position
(obtained using GpiQueryCurrentPosition) the length of the string can be
determined.

GpiQueryCharStringPosAt also returns an array of points, in which the world
coordinate position of each character in the string is recorded. The last value
of the array becomes the new current position if the string is drawn using
GpiCharStringPosAt. This function accepts a specified starting position for the
character string. By specifying a starting position of (0,0) for example, an
application can determine the length of the string without subtraction.

The current position actually is not updated by either GpiQueryCharStringPos or
GpiQueryCharStringPosAt. All three functions are described also in the
Presentation Manager Programming Reference.

When a character string does not fill the width of the output area, it can be
positioned in 1 of the four ways illustrated in the following figure.

Horizontal Positioning of Text Strings

To left-align the text, set the x-coordinate of the current position to the
left of the output area before drawing the character string.
GpiSetCurrentPosition must be used to set the current position if your
application draws the string using either GpiCharString or GpiCharStringPos.
Both GpiCharStringAt and GpiCharStringPosAt accept a starting position as
input.

To right-align the text, subtract the length of the character string from the
width of the output area, then add the difference to the x-coordinate of the
current position before drawing the character string. If the output area is 570
world coordinates wide, for example, and the character string is 436 world
coordinates long, add 134 to the x-coordinate of the current position before
drawing the text.

To center the text, subtract the length of the character string from the width
of the output area, then divide the difference by 2 before adding it to the
x-coordinate of the current position. If the difference is 134, for example,
you add 67 to the x-coordinate of the current position.

To justify the text, so that the text string fills the width of the output
area, distribute the surplus space throughout the character string.  For
example, you could add the extra space to the break characters only, or you
could share it equally among all characters in the string. Text justification
requires the individual positioning each character in the string using either
of the following calls:

o GpiCharStringPos-draws at the current position and permits you to position
  every character after the first.

o GpiCharStringPosAt-permits you to position every character, including the
  first.

Both functions enable you to specify a different character increment for each
character in the string. Distance is measured from the character reference
point of one character to the character reference point of the next character.
The values you specify apply only to the character string supplied at input;
they do not become current attribute values.

If you are formatting a block of text, the string might be wider than the
output area, or longer than 256 characters. In either case, your application
must separate the string into smaller groups of characters so that it fits
either criteria. A good starting point is to determine the number of characters
planned for each line. Dividing the output width by the character cell width
can provide a first estimate as to where to separate a character string. An
application can use this estimate to work through the string looking for
spaces. Each time you find a space, compare the length of the string (up to the
space) with the width of the output area. When the string is longer than the
output area, work back to the previous space and display or print that part of
the string. You can format the entire block of text for the output area in this
way.

When you are formatting a block instead of a single line of text, an
application must specify the vertical placement of each line. If you are using
an image font, you have the assurance that each character is the same height.
However, you do not have that assurance with an outline font, nor that the text
block is written in the same font. Therefore, when calculating the separation
of lines, avoid using complex combinations of font metrics values. Instead, it
is recommended that you multiply the desired point size, or em-height metric,
of the text by 1.2.


ΓòÉΓòÉΓòÉ 6.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the character string primitive functions.

Character String Primitive Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharString           ΓöéDraws a character string using the  Γöé
Γöé                        Γöécurrent font from the current       Γöé
Γöé                        Γöéposition.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringAt         ΓöéDraws a character string using the  Γöé
Γöé                        Γöécurrent font from a specified       Γöé
Γöé                        Γöéposition.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringPos        ΓöéDraws a character string using the  Γöé
Γöé                        Γöécurrent font with the first         Γöé
Γöé                        Γöécharacter at the current position,  Γöé
Γöé                        Γöéthen allows positioning of every    Γöé
Γöé                        Γöéfollowing character.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringPosAt      ΓöéDraws a character string in the     Γöé
Γöé                        Γöécurrent font and allows positioning Γöé
Γöé                        Γöéfor the first and every following   Γöé
Γöé                        Γöécharacter.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharAngle       ΓöéDetermines the current character    Γöé
Γöé                        Γöéangle attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharBox         ΓöéDetermines the current character boxΓöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharBreakExtra  ΓöéDetermines the current character    Γöé
Γöé                        Γöébreak extra attribute.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharDirection   ΓöéDetermines the current character    Γöé
Γöé                        Γöédirection attribute.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharExtra       ΓöéDetermines the current character    Γöé
Γöé                        Γöéextra attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharMode        ΓöéDetermines the current mode         Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharSet         ΓöéDetermines the current character setΓöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharShear       ΓöéDetermines the current character    Γöé
Γöé                        Γöéshear attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharStringPos   ΓöéDetermines the position of each     Γöé
Γöé                        Γöécharacter for an equivalent         Γöé
Γöé                        ΓöéGpiCharStringPos function without   Γöé
Γöé                        Γöéactually drawing any characters.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharStringPosAt ΓöéDetermines the position at which    Γöé
Γöé                        Γöéeach character will appear if an    Γöé
Γöé                        Γöéequivalent GpiCharStringPosAt       Γöé
Γöé                        Γöéfunction is used.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDefCharBox      ΓöéDetermines the size of the default  Γöé
Γöé                        Γöécharacter box.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryTextBox         ΓöéDetermines the coordinates of the   Γöé
Γöé                        Γöécorners of a text box for an        Γöé
Γöé                        Γöéequivalent GpiCharStringPos functionΓöé
Γöé                        Γöéwithout actually drawing any        Γöé
Γöé                        Γöécharacters.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharAngle         ΓöéSets the current character angle    Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharBox           ΓöéSets the current character box      Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharBreakExtra    ΓöéSets the current character break    Γöé
Γöé                        Γöéextra attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharDirection     ΓöéSets the current character directionΓöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharExtra         ΓöéSets the current character extra    Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharMode          ΓöéSets the current character mode     Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharSet           ΓöéSets the current character set      Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharShear         ΓöéSets the current character shear    Γöé
Γöé                        Γöéattribute.                          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the character string
primitive functions.

Character String Primitive Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCHARBUNDLE              ΓöéContains the character attributes.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFATTRS                  ΓöéContains the attributes of the font Γöé
Γöé                        Γöéspecified using GpiCreateLogFont.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFONTMETRICS             ΓöéContains all the font metrics       Γöé
Γöé                        Γöéreturned by the system to describe aΓöé
Γöé                        Γöéparticular font.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPOINTL                  ΓöéSpecifies the values of a single    Γöé
Γöé                        Γöépair of x- and y-coordinates.       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 7. Color and Mix Attributes ΓòÉΓòÉΓòÉ

This chapter describes color and mix attributes and their use in OS/2
applications. The following topics are related to the information in this
chapter:

o Presentation spaces
o Device contexts
o Line and arc primitives
o Marker primitives
o Area primitives
o Character string primitives
o Bit maps and images primitives.


ΓòÉΓòÉΓòÉ 7.1. About Color and Mix Attributes ΓòÉΓòÉΓòÉ

Color and mix are 2 attributes of graphics primitives. They can be specified by
an application in a number of ways; and are specified in the xxxBUNDLE data
structure associated with the 5 graphics primitives and in bit maps. Bit maps
and some of the primitives have both foreground and background color
attributes. For example, a character string primitive has a foreground color
attribute that specifies the color of the character and a background color
attribute that specifies the color of the character cell surrounding the
character.

The mix attribute controls how each primitive is combined with the existing
drawing. Among other things, it affects the color that results when primitives
of different colors overlap. Primitives with foreground and background color
attributes also have foreground and background mix attributes.


ΓòÉΓòÉΓòÉ 7.2. Color Implementation ΓòÉΓòÉΓòÉ

Understanding how colors are implemented can assist in understanding how the
color and mix attributes work.

The pel is the smallest element of the display screen that can be addressed.
For monochrome displays, pels are either turned off or turned on. For color
displays, each pel contains a red, green, and blue section, each of which is
called a phosphor.

The display has color guns of red, blue, and green light that illuminate the
phosphors in a single pel. By switching these color guns on and off in
different combinations, 8 standard colors can be produced. By varying the
intensities of the color guns, additional colors can be produced. The following
table shows the 8 standard colors that can be generated from the 3 color guns.

Eight Standard Colors

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPel appears... ΓöéRed            ΓöéGreen          ΓöéBlue           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRed            ΓöéON             ΓöéOFF            ΓöéOFF            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGreen          ΓöéOFF            ΓöéON             ΓöéOFF            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlue           ΓöéOFF            ΓöéOFF            ΓöéON             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWhite          ΓöéON             ΓöéON             ΓöéON             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlack          ΓöéOFF            ΓöéOFF            ΓöéOFF            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCyan           ΓöéOFF            ΓöéON             ΓöéON             Γöé
Γöé(Turquoise)    Γöé               Γöé               Γöé               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPink           ΓöéON             ΓöéOFF            ΓöéON             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéYellow         ΓöéON             ΓöéON             ΓöéOFF            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Each pel is described internally by a number of bits of storage. In a
monochrome display, only 1 bit per pel is required, and that bit is either on
or off. In an 8-color system, 3 bits per pel are necessary. Each of those 3
bits records the on or off setting of 1 color gun.

To be able to control the intensity of a color and obtain more than 8 colors,
more than 3 bits per pel are needed. For example, 6 bits per pel provide 32
different combinations.

The wider the range of available colors, the more bits per pel required for
each color. This storage issue is resolved by keeping a wide choice of colors
but restricting the number of colors available at any given time. Applications
define the colors that they want to use in a logical color table. Selecting a
color defined in the logical color table produces the nearest available color
in the hardware palette.


ΓòÉΓòÉΓòÉ 7.2.1. RGB Color Encoding ΓòÉΓòÉΓòÉ

The red, green, and blue (RGB) components of a color are stored in either an
RGB or RGB2 data structure, or as a long integer (32-bit) value. The color
fields in the RGB2 structure and in the long integer follow the same rules.

If stored as a long integer, the RGB value has the first 8 bits reserved for a
flag value and the remaining 24 bits reserved for color intensity. The flag
byte must be set to 0. Each of the last 3 bytes specifies a color intensity, in
the range 0 through 255, for a single primary color.

If a byte contains 0, the corresponding primary color is not present. As the
value in the byte increases, the intensity of the primary color increases. For
example, if the byte contains 128, the primary color is pale; if the byte
contains 255, the primary color is as intense as the device permits.

The RGB value is determined by the following equation:

    RGB Value = (R * 65536) + (G * 256) + B

    Where:
        R is the red intensity
        G is the green intensity
        B is the blue intensity

If all 3 bytes are set to 0, the resulting color is black; if they all are set
to 255, the resulting color is white. The RGB value associated with each of the
standard 8 colors is in the following table.

RGB Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéColor               ΓöéRGB value           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlack               Γöé0x00000000          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRed                 Γöé0x00FF0000          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGreen               Γöé0x0000FF00          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBlue                Γöé0x000000FF          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPink                Γöé0x00FF00FF          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCyan                Γöé0x0000FFFF          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéYellow              Γöé0x00FFFF00          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWhite               Γöé0x00FFFFFF          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 7.2.2. Color Tables ΓòÉΓòÉΓòÉ

A color table is an array of RGB values. There are 2 kinds of color tables:
logical and physical. The logical color table is a list of colors specific to a
presentation space. An application typically uses a logical color table to
define colors specific to that application.

The physical color table specifies colors the device can generate currently.
These device colors are shared by every application on the system. Because some
display adapters cannot generate every possible device color at the same time,
the physical color table can be a subset of the full range of possible device
colors. The operating system maps the RGB values specified in the logical color
table to device colors in the physical color table.


ΓòÉΓòÉΓòÉ 7.2.3. Logical Color Table ΓòÉΓòÉΓòÉ

A logical color table contains a variable number of entries, each of which
describes a different RGB (Red, Green, Blue) combination that produces a color.
The principle of the color table is illustrated in the following figure.

Logical Color Table

This simplified example demonstrates that to produce yellow on the computer
screen, red and green are mixed in equal intensities, and no blue is used at
all. In this example, yellow is addressed in the color table by index 21.
Notice that this is not the same index number used in the default logical color
table, which indicates that this color table has been changed by the
application.

A logical color table is stored in a presentation space and is specific to that
presentation space. A logical color table enables applications to specify
colors as indexes rather than explicit RGB values.

The colors displayed are likely to vary from 1 output device to another so the
definitions in the color table can be fine-tuned to get the best results. Any
color can be made more or less intense by altering its definition in the
logical color table.


ΓòÉΓòÉΓòÉ 7.2.3.1. Default Logical Color Table ΓòÉΓòÉΓòÉ

The PM programming interface provides a default logical color table, which
defines the colors and the indexes that retrieve them, as shown in the
following table.

Default Logical Color Table

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéColor Index     ΓöéIndeΓöéEffect                                  Γöé
Γöé                ΓöéNumbΓöé                                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_FALSE       Γöé-5  ΓöéAll bits are set to 0.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_TRUE        Γöé-4  ΓöéAll bits are set to 1.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DEFAULT     Γöé-3  ΓöéDefault value                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_WHITE       Γöé-2  ΓöéWhite                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_BLACK       Γöé-1  ΓöéBlack                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_BACKGROUND  Γöé0   ΓöéNatural background color for the device Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_BLUE        Γöé1   ΓöéBlue                                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_RED         Γöé2   ΓöéRed                                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_PINK        Γöé3   ΓöéPink                                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_GREEN       Γöé4   ΓöéGreen                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_CYAN        Γöé5   ΓöéCyan                                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_YELLOW      Γöé6   ΓöéYellow                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_NEUTRAL     Γöé7   ΓöéNeutral - The contrasting color to      Γöé
Γöé                Γöé    ΓöéCLR_BACKGROUND                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKGRAY    Γöé8   ΓöéDark gray                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKBLUE    Γöé9   ΓöéDark blue                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKRED     Γöé10  ΓöéDark red                                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKPINK    Γöé11  ΓöéDark pink                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKGREEN   Γöé12  ΓöéDark green                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DARKCYAN    Γöé13  ΓöéDark cyan                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_BROWN       Γöé14  ΓöéBrown                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_PALEGRAY    Γöé15  ΓöéPale gray                               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  Entries after CLR_PALEGRAY have device-dependent defaults.

PM maps the color index name to the index number (shown in the second column of
the previous table), then uses that number to address the appropriate color.


ΓòÉΓòÉΓòÉ 7.2.3.2. Device-Independent Color Indexing ΓòÉΓòÉΓòÉ

Three of the index names provide a level of device independence in choosing
colors:  CLR_DEFAULT, CLR_BACKGROUND, and CLR_NEUTRAL. These indexes enable an
application to select colors according to their purpose, and thus build device
independence into your applications. The purpose of a color does not vary from
1 device to another, although the actual color used to implement that purpose
might. The following table describes these indexes and the purpose of each:

Device Independent Color Indexes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIndex                         ΓöéPurpose                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_BACKGROUND                ΓöéThe natural background color  Γöé
Γöé                              Γöéfor the device. This is the   Γöé
Γöé                              Γöécolor of the paper on a       Γöé
Γöé                              Γöéprinter, and the window       Γöé
Γöé                              Γöébackground color (white, by   Γöé
Γöé                              Γöédefault) on a display.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_NEUTRAL                   ΓöéThe contrast color to         Γöé
Γöé                              ΓöéCLR_BACKGROUND. This is       Γöé
Γöé                              Γöéusually black on a printer,   Γöé
Γöé                              Γöéand the default window text   Γöé
Γöé                              Γöécolor (black, by default) on aΓöé
Γöé                              Γöédisplay.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCLR_DEFAULT                   ΓöéUnless redefined, this has theΓöé
Γöé                              Γöésame effect as CLR_NEUTRAL.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The colors produced by CLR_DEFAULT, CLR_BACKGROUND, and CLR_NEUTRAL in the
default logical color table depend on the output device. For example,
CLR_NEUTRAL could produce black on a device with a white background or white on
a device with a black background.


ΓòÉΓòÉΓòÉ 7.2.4. Defining a Logical Color Table ΓòÉΓòÉΓòÉ

To change the values in the default logical color table (that is, to load a new
logical color table), use GpiCreateLogColorTable. Using this function, an
application can do the following:

o Replace part or all of the default color table.
o Add color definitions to the default color table.
o Reset the logical color table to its default values.

There are 2 methods of making changes:

 1. To add to a table or change some of its  contents, rather than replace the
    table completely, supply an array of color indexes and their associated RGB
    values.

 2. To load a consecutive sequence of index values, supply only an array of RGB
    values without index values.


ΓòÉΓòÉΓòÉ 7.2.4.1. Color Tables in Index Mode ΓòÉΓòÉΓòÉ

The default logical color table is defined as an array of color indexes and
their associated RGB values. A table in this format is in index mode.

To alter a logical color table in index mode, specify either LCOLF_INDRGB or
LCOLF_CONSECRGB as the format value in GpiCreateLogColorTable. If an
application uses the color index names to address the contents of a loaded
color table in index mode, the color identified by the associated index number
is retrieved. For example, CLR_NEUTRAL produces the color addressed by index
number 7. If CLR_NEUTRAL must be blue, the application must define the color
table so that index number 7 addresses the RGB definition of the appropriate
shade of blue.

If an application uses the format LCOLF_INDRGB when calling
GpiCreateLogColorTable, the application supplies an array of index and RGB
pairs to update the table. These values do not have to be consecutive. An
application can change the contents of an existing table and add entries to the
end of the table.

If an application calls GpiCreateLogColorTable using the LCOLF_CONSECRGB
format, the application supplies an array of RGB values and a starting index.
When using this format, the RGB values must be consecutive; you cannot use a
single call to GpiCreateLogColorTable to redefine CLR_BLUE and CLR_PINK without
also specifying an RGB value for CLR_RED. As with LCOLF_INDRGB, this format can
be used to change the contents of the existing table and to add entries to the
end of the table.

When an application calls GpiSetAttrs to put a value into the color field of a
graphics primitive attribute structure, the value is an index into the logical
color table. When the operating system draws the primitive, it uses this index
to determine the RGB value specified in the logical color table by the
application; then it searches the physical color table for the color closest to
this RGB value. The operating system then draws the primitive, using the color
from the physical color table. How closely the drawn colors match the colors in
the logical color table depends on the device colors in the physical color
table.


ΓòÉΓòÉΓòÉ 7.2.4.2. Color Tables in RGB Mode ΓòÉΓòÉΓòÉ

The color values specified with GpiSetAttrs and GpiSetColor also can be
specified directly as RGB values rather than as indexes. To enable this, the
logical color table must be switched into RGB mode by calling
GpiCreateLogColorTable, specifying a format of LCOLF_RGB. (No color array is
passed.)

If the color table is in RGB mode, it can be switched back to index mode and
reset to its original default values by specifying either LCOLF_INGRGB or
LCOLF_CONSECRGB in GpiCreateLogColorTable.


ΓòÉΓòÉΓòÉ 7.2.5. Querying the Available Colors ΓòÉΓòÉΓòÉ

Several query functions are provided for applications to get information about
the current logical and physical color tables before defining a logical color
table.

Applications use GpiQueryColorData to determine whether the default logical
color table is in effect. If it is not, the following information about the
loaded logical color table is returned:

o Format of the current logical color table

o Smallest and largest color indexes (if the table is in index mode) supported
  in this color table. The smallest color index is always 0, and the largest
  color index is never less than 15, because deleting entries from the default
  logical color table is not permitted.

GpiQueryRealColors returns the RGB values of each of the distinct colors
defined in the physical color table of the current device. It also can return
the index in the current logical color table that references each of the colors
in the physical table.

To determine the available colors nearest to a specified color on a particular
device, call GpiQueryNearestColor, which accepts as input the RGB value of the
desired color. The function returns the RGB value of the nearest available
color in the physical color table of the associated device.

Applications can use GpiQueryRGBColor to determine the RGB value of a
particular color. GpiQueryRGBColor accepts as input the index to the logical
color table entry of the color in question. Output from this function is the
RGB value that the index would reference in the physical color table. If a
logical color table is loaded in RGB mode, GpiQueryRGBColor returns the same
results as GpiQueryNearestColor.

Conversely, to determine the index value that references a given RGB color (or
the closest match to that color) in the physical color table, an application
uses GpiQueryColorIndex. The application can determine which colors are in the
current logical color table by calling GpiQueryLogColorTable. To determine
which colors are in the physical color table, call GpiQueryRealColors.


ΓòÉΓòÉΓòÉ 7.2.6. Physical Color Table ΓòÉΓòÉΓòÉ

Each output device has its own physical color table, which is organized like a
logical color table. The physical color table contains the RGB color
definitions of the distinct colors that the device can produce, while a logical
color table contains the definitions of the colors as chosen by an application.
When an application draws on an output device, the PM programming interface
maps the index value that addresses the current color in the logical color
table to the index that retrieves the closest match for the current color in
the physical color table.

Because this substitution occurs when the graphics are drawn, the presentation
space can be associated with a number of different device contexts without
invalidating the logical color definitions. For example, an application can
create a picture on the screen using a wide range of colors, then direct that
drawing to an 8-pen vector plotter. The drawing is reproduced without having to
be re-created. Although the picture, as drawn by the plotter, does not have the
variety of colors displayed on the screen, the substitution process selects the
nearest match for each color on the screen from the 8 available colors on the
plotter.


ΓòÉΓòÉΓòÉ 7.2.7. Palette Manager ΓòÉΓòÉΓòÉ

Applications can use GpiCreatePalette to change the physical color palette by
creating a new palette. This function is used if the application has specific
color needs and must ensure that the color is part of the physical color
palette. GpiCreatePalette also enables an application to prevent dithering of
the 16 default colors by setting the flag parameter to LCOL_PURECOLOR (for
information on dithering, see Dithering). If the full 256 colors in the palette
are needed, the application can set the flag to LCOL_OVERRIDE_DEFAULT_COLORS.
It is recommended that the Palette Manager functions be used only when really
necessary because the operating system cannot guarantee consistent colors in
other windows and the ability to change the physical palette is device
dependent.

After the palette is created, an application can set or change any of the
values in the palette by calling GpiSetPaletteEntries. To delete the palette,
applications use GpiDeletePalette, passing the handle of the palette to be
deleted. (The handle is returned by GpiCreatePalette when the palette is
created.)

GpiQueryPalette enables applications to determine the palette currently
selected for a given presentation space. A palette can be used by more than 1
presentation space at the same time. The operating system maintains a count of
the number of presentation spaces using a specific palette. Complete
information on the current palette can be accessed by GpiQueryPaletteInfo.

Palettes also can be shared by using a palette handle.

When coding an application, color table functions and color palette functions
must not be mixed. The application can call DevQueryCaps to determine whether
the hardware supports palettes, then call the appropriate functions.


ΓòÉΓòÉΓòÉ 7.2.7.1. Realizing a Color Palette ΓòÉΓòÉΓòÉ

WinRealizePalette maps the colors requested by the application into the color
palette for the system. When the application's window is activated, the palette
changes are transferred, or realized, into the physical palette for the system.

When a palette is realized, there might not be enough empty palette entries to
accommodate the additional palette changes (a maximum of 256 entries). For
example, it is possible that some of the colors changed in the physical palette
are being used by another application. In this situation, a WM_REALIZEPALETTE
message is posted to all the applications running on the desktop.

On receiving the WM_REALIZEPALETTE message, applications using Palette Manager
functions must repaint their screens. The original application colors are
mapped to the closest matching color in the new palette. Applications that do
not use Palette Manager functions normally perform default processing within
their applications causing a repaint of their windows with the closest match
from the palette. If there are no changes, just additions, to the physical
palette, no message is sent.

Note:  The Palette Manager maps a window's colors to the closest available
       value in the palette when the physical palette has to be changed, but
       this does not guarantee that the color will be a close match to the
       original color used.

As the focus changes from window to window, the physical palette changes
according to the activated window. Notification messages are sent as necessary
to other applications.

If the physical color values in the palette have to change to accommodate the
number of palette entries passed from the application when a palette is
realized, the number of altered entries in the physical palette is returned by
WinRealizePalette.

Color palette realization is available only to systems that have a minimum of
256 colors.


ΓòÉΓòÉΓòÉ 7.2.8. Color Attribute ΓòÉΓòÉΓòÉ

The PM graphic interface uses a variety of colors. These colors are referred to
as the system colors, and they are defined in the system color table, which is
separate from an application's logical color table. To find out the RGB values
of the system colors, call WinQuerySysColor.

The colors of graphic primitives are specified separately from the system
colors. Every primitive has a foreground color; some also have a background
color.


ΓòÉΓòÉΓòÉ 7.2.8.1. Primitive Foreground ΓòÉΓòÉΓòÉ

The foreground of a primitive is the primitive itself. For example, the
foreground of a full arc primitive is the full arc, as shown in the following
figure.

Foreground of a Primitive

The full arc primitive is drawn in a different color from the window
background.

By default, the foreground color of all primitives is the color addressed by
the index CLR_DEFAULT. In the default color table, this produces black on a
graphics display. If the application replaces the default logical color table,
CLR_DEFAULT produces the color addressed by index number 7 (CLR_NEUTRAL).


ΓòÉΓòÉΓòÉ 7.2.8.2. Primitive Background ΓòÉΓòÉΓòÉ

The following primitives have a background:

o Areas
o Character strings
o Images
o Markers.

The background of any character or marker primitive, whether the primitive is
from an image or an outline font, is the entire character or marker box. First
the background is drawn, then the foreground is drawn on top of it. Similarly,
the background of an area primitive is the entire area to be filled. The
background of an image primitive, however, is that part of the primitive in
which the pels are not set. The following figure shows the background of a
primitive.

Background of a Primitive

The background of this character-string primitive is the entire character box.

The index to the default background color is CLR_BACKGROUND, which provides a
background color appropriate for the device. On a printer, CLR_BACKGROUND is
the color of the paper. On a display screen, CLR_BACKGROUND is the default
window background color.


ΓòÉΓòÉΓòÉ 7.2.8.3. Changing the Foreground and Background Colors of Primitives ΓòÉΓòÉΓòÉ

To change the current foreground color, use GpiSetColor; as input, the
application supplies either the index to the required color in the current
logical color table or the RGB value of the color, depending on the mode of the
table. Color indexes higher than those supplied in the default color table must
be loaded explicitly before they can be used.

It is possible to specify one of the system colors (for example,
SYSCLR_ACTIVEBORDER) as the current foreground (or background) color of a
primitive. The color appears as defined in the system color table, and the
logical color table is not used.

The specified color becomes the current color, and the foreground of any
primitive drawn subsequently is drawn in that color. The current foreground
color for a particular primitive type is set by calling GpiSetAttrs. For
example, if an application sets the current foreground color to CLR_RED by
calling GpiSetColor, and sets the current foreground color for marker
primitives to CLR_CYAN by calling GpiSetAttrs, all subsequent markers are cyan,
and all other primitives are red.

To change the current primitive background color, call GpiSetBackColor. To
ensure that this color is different from the background color of the output
area (so that the entire primitive background is visible), the current window
background color must not be the same as the current primitive background
color. Also, select an appropriate background mix attribute.

GpiQueryBackColor returns the current background color setting for a character
primitive; to learn the current foreground color setting, use GpiQueryColor.
GpiQueryAttrs can be used to determine the current foreground and background
color values for a single primitive type.


ΓòÉΓòÉΓòÉ 7.2.9. Color Output and Mix Attributes ΓòÉΓòÉΓòÉ

A mix attribute is a bitwise operation on the color indexes in a device's
logical color table. Mix attributes enable colors to be specified in relation
to other colors. When an application draws a graphics primitive, the operating
system uses a mix attribute to determine the color that appears on the output
device.

For example, instead of specifying that a line should be black and, therefore,
invisible if the background also is black, an application can use a mix
attribute of FM_XOR to specify that the line always should be drawn the inverse
of the background color.

Suppose an application has set the lColor field in the LINEBUNDLE structure to
CLR_RED and the usMixMode field in the same structure to FM_OR. The current
color of the drawing surface is CLR_GREEN. To determine the color of a line,
the operating system performs a bitwise OR operation on the indexes of these
colors, as follows:

          0010  (the default index for red)
          0100  (the default index for green)
         ------
          0110  (result of bitwise OR)

In this case, the result is 6-the index for yellow. This means that even though
the application specified CLR_RED in the LINEBUNDLE structure, a yellow line
appears when the application calls any of the functions that draw a line
primitive.


ΓòÉΓòÉΓòÉ 7.2.10. Mix Attribute ΓòÉΓòÉΓòÉ

The mix attribute determines how each primitive an application draws is
combined with any existing drawing. In color applications, the mix attribute
determines the color that results when one primitive is drawn on top of
another. There are two forms of the mix attribute:  foreground mix and
background mix.

The foreground mix attribute governs how the foreground of a primitive is
combined with the existing drawing, and it applies to all primitive types. The
background mix attribute governs how the background of a primitive is combined
with the existing drawing, and it is applicable only to those primitives that
have a background. Primitives that can be affected by the background mix
attribute are areas, character strings, images, and markers. The primitive
attribute data structures contain fields for both foreground and background
color and mix attributes.

There are 17 foreground mix attributes. For each mix attribute, the indexes of
the foreground and current drawing-surface colors are combined by using 1 of
the bitwise operators. The available foreground mix settings are listed in the
following table.

Foreground Mix Attributes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéMix Attribute  ΓöéEffect         ΓöéDescription                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_DEFAULT     ΓöéDefault        ΓöéDefault foreground mix        Γöé
Γöé               Γöé               Γöéattribute (overpaint).        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_OR          ΓöéOR             ΓöéIndex value of the final colorΓöé
Γöé               Γöé               Γöéis determined by a bitwise OR Γöé
Γöé               Γöé               Γöéoperation on the index of the Γöé
Γöé               Γöé               Γöéforeground color and the indexΓöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_OVERPAINT   ΓöéOverpaint      ΓöéIndex value of the final colorΓöé
Γöé               Γöé               Γöéis that of the foreground     Γöé
Γöé               Γöé               Γöécolor. This is the default    Γöé
Γöé               Γöé               Γöéforeground mix attribute.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_XOR         ΓöéExclusive-OR   ΓöéIndex value of the final colorΓöé
Γöé               Γöé(XOR)          Γöéis determined by a bitwise XORΓöé
Γöé               Γöé               Γöéoperation on the index of the Γöé
Γöé               Γöé               Γöéforeground color and the indexΓöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_LEAVEALONE  ΓöéLeave-alone    ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Invisible)    Γöéis that of the index of the   Γöé
Γöé               Γöé               Γöécolor of the drawing surface. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_AND         ΓöéAND            ΓöéIndex value of the final colorΓöé
Γöé               Γöé               Γöéis determined by a bitwise ANDΓöé
Γöé               Γöé               Γöéoperation on the index of the Γöé
Γöé               Γöé               Γöéforeground color and the indexΓöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_SUBTRACT    Γöé(Inverse       ΓöéIndex value of the final colorΓöé
Γöé               ΓöéSource) AND    Γöéis determined by inverting theΓöé
Γöé               ΓöéDestination    Γöéindex of the foreground color Γöé
Γöé               Γöé               Γöéand performing a bitwise AND  Γöé
Γöé               Γöé               Γöéoperation on this value and   Γöé
Γöé               Γöé               Γöéthe index of the color of the Γöé
Γöé               Γöé               Γöédrawing surface.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_MASKSRCNOT  ΓöéSource AND     ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Inverse       Γöéis determined by inverting theΓöé
Γöé               ΓöéDestination)   Γöéindex value of the            Γöé
Γöé               Γöé               Γöédrawing-surface color and     Γöé
Γöé               Γöé               Γöéperforming a bitwise AND      Γöé
Γöé               Γöé               Γöéoperation on this value and   Γöé
Γöé               Γöé               Γöéthe index value of the        Γöé
Γöé               Γöé               Γöéforeground color.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_ZERO        ΓöéAll zeros      ΓöéRGB value of the final color'sΓöé
Γöé               Γöé               Γöéis always 0x00000000.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_NOTMERGESRC ΓöéInverse (SourceΓöéIndex value of the final colorΓöé
Γöé               ΓöéOR Destination)Γöéis always the inverse of the  Γöé
Γöé               Γöé               ΓöéFM_OR result.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_NOTXORSRC   ΓöéInverse (SourceΓöéIndex value of the final colorΓöé
Γöé               ΓöéXOR            Γöéis always the inverse of the  Γöé
Γöé               ΓöéDestination)   ΓöéFM_XOR result.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_INVERT      ΓöéInverse        ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Destination)  Γöéis always the inverse of the  Γöé
Γöé               Γöé               Γöéindex of the color of the     Γöé
Γöé               Γöé               Γöédrawing surface.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_MERGESRCNOT ΓöéSource OR      ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Inverse       Γöéis determined by performing a Γöé
Γöé               ΓöéDestination)   Γöébitwise OR operation on the   Γöé
Γöé               Γöé               Γöéindex of the foreground color Γöé
Γöé               Γöé               Γöéand the inverse of the index  Γöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_NOTCOPYSRC  ΓöéInverse        ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Source)       Γöéis the inverse of the index ofΓöé
Γöé               Γöé               Γöéthe foreground color.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_MERGENOTSRC Γöé(Inverse       ΓöéIndex value of the final colorΓöé
Γöé               ΓöéSource) OR     Γöéis determined by performing a Γöé
Γöé               ΓöéDestination    Γöébitwise AND operation on the  Γöé
Γöé               Γöé               Γöéindex of the drawing surface'sΓöé
Γöé               Γöé               Γöécolor and the inverse of the  Γöé
Γöé               Γöé               Γöéindex of the foreground color.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_NOTMASKSRC  ΓöéInverse (SourceΓöéIndex value of the final colorΓöé
Γöé               ΓöéAND            Γöéis the inverse of the FM_AND  Γöé
Γöé               ΓöéDestination)   Γöéresult.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFM_ONE         ΓöéAll 1's.       ΓöéRGB value of the final color  Γöé
Γöé               Γöé               Γöéis always 0x00FFFFFF.         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

There are four background mix attributes. For each mix attribute, the index
value for the background color and the current drawing-surface color (in the
device's physical color table) are combined using one of the bitwise operators.

The RGB values are those from the physical color table. When the result of the
mix attribute's bitwise operation defines a color different from that of both
the drawing surface and the drawing attribute, the resulting index accesses an
RGB color in the physical table. The color, therefore, is unpredictable unless
the logical color table has been realized (using the Palette Manager).

The first five of the foreground mix attributes also are available as
background mix attributes. The background mix attributes are listed in the
following table.

Background Mix Attributes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéMix Attribute  ΓöéEffect         ΓöéDescription                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBM_DEFAULT     ΓöéDefault        ΓöéDefault background mix        Γöé
Γöé               Γöé               Γöéattribute (Leave-alone).      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBM_OR          ΓöéOR             ΓöéIndex value of the final colorΓöé
Γöé               Γöé               Γöéis determined by a bitwise OR Γöé
Γöé               Γöé               Γöéoperation on the index of the Γöé
Γöé               Γöé               Γöébackground color and the indexΓöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBM_OVERPAINT   ΓöéOverpaint      ΓöéIndex value of the final colorΓöé
Γöé               Γöé               Γöéis that of the background     Γöé
Γöé               Γöé               Γöécolor.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBM_XOR         ΓöéExclusive-OR   ΓöéIndex value of the final colorΓöé
Γöé               Γöé(XOR)          Γöéis determined by a bitwise XORΓöé
Γöé               Γöé               Γöéoperation on the index of the Γöé
Γöé               Γöé               Γöébackground color and the indexΓöé
Γöé               Γöé               Γöéof the color of the drawing   Γöé
Γöé               Γöé               Γöésurface.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBM_LEAVEALONE  ΓöéLeave-alone    ΓöéIndex value of the final colorΓöé
Γöé               Γöé(Invisible)    Γöéis that of the drawing-surfaceΓöé
Γöé               Γöé               Γöécolor.                        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The most frequently used foreground mix attributes are FM_OVERPAINT, which is
the default value, FM_OR, and FM_XOR. The most frequently used background mix
attributes are BM_LEAVEALONE, which is the default value, and BM_OVERPAINT.


ΓòÉΓòÉΓòÉ 7.2.10.1. Overpaint Mix Attribute ΓòÉΓòÉΓòÉ

When using FM_OVERPAINT, the foreground of the primitive replaces any existing
drawing in the same area of the presentation page. If the existing drawing is
yellow, for example, and the new drawing is red, the drawing is red at the
points of overlap. (This is the default foreground mix attribute.) Because 1
color is replacing another and no color mixing is being performed, the effects
of the overpaint mix attribute are entirely predictable, as shown in the
following figure.

Overpaint Foreground Mix Attribute

The circle is drawn on top of the square. At the points of overlap, the output
is the color of the circle.

When using BM_OVERPAINT, the primitive background replaces the existing
drawing, as shown in the following figure.

Overpaint Background Mix Attribute

Using BM_OVERPAINT, the background of the primitive is apparent only if it is
drawn in a different color from the output-area background. Notice that, in
this example, the foreground mix attribute is FM_OVERPAINT.


ΓòÉΓòÉΓòÉ 7.2.10.2. OR Mix Attribute ΓòÉΓòÉΓòÉ

When using FM_OR, the foreground of the new primitive is merged with the
existing drawing at the points of overlap. This is effected by ORing the
indexes of the overlapping colors to produce a third color. The resulting color
is unpredictable if the logical color table has not been realized (using the
Palette Manager). The OR mix attribute is useful for making the common points
of 2 graphics distinct from the points belonging to 1 of the graphics only, as
shown in the following figure.

OR Mix Attribute

The circle is drawn on top of the square. At the points of overlap, indexes are
OR'd to produce a new index referencing a new RGB color in the physical color
table.

When using the BM_OR attribute, the background of the primitive is merged with
the existing drawing according to the same rules that apply to the FM_OR
attribute.


ΓòÉΓòÉΓòÉ 7.2.10.3. Exclusive-OR (XOR) Mix Attribute ΓòÉΓòÉΓòÉ

The FM_XOR attribute enables objects to be drawn in such a way that they can be
removed easily by simply drawing them a second time using the FM_XOR attribute.
The FM_XOR attribute is available on display devices only and is useful for
graphics animation when an application must move an individual graphic and
completely restore the graphics that it originally overlapped. Typically, an
application would do the following:

 1. Draw the graphics object using the FM_XOR attribute.

 2. Calculate the object's next position.

 3. Draw the object again in its current position, still using the FM_XOR
    attribute. This effectively erases it from its current position without
    destroying the graphics with which it overlaps.

 4. Draw the object in its new position using the FM_XOR mix attribute.

For retained graphics, this sequence can be automated to some extent by
defining specific graphics segments as dynamic. Dynamic graphics always are
drawn using the FM_XOR attribute, regardless of the current mix attributes.

The effects of the FM_XOR attribute are shown in the following figure.

Exclusive-OR (XOR) Mix Attribute

The circle is drawn on top of the square. At the points of overlap, graphics
are not drawn if the 2 overlapping figures are an identical color.

When using the BM_XOR attribute, the background of the primitive is merged with
the existing picture according to the same rules that apply to the FM_XOR
attribute.


ΓòÉΓòÉΓòÉ 7.2.10.4. Leave-Alone Mix Attribute ΓòÉΓòÉΓòÉ

The leave-alone mix attribute most often is used as a background mix attribute.
When using the FM_LEAVEALONE attribute, the foreground of the primitive is not
drawn. When using the BM_LEAVEALONE attribute, the background of the primitive
is not drawn, as shown in the following figure.

Leave-Alone Background Mix Attribute

This is the background mix attribute that most often is used for character
strings and marker primitives. It is generally used with a foreground mix value
of FM_OVERPAINT.


ΓòÉΓòÉΓòÉ 7.2.10.5. Specifying Foreground and Background Mix Attributes ΓòÉΓòÉΓòÉ

Specify the current foreground mix value for all primitives using GpiSetMix. To
learn the current foreground mix setting, use GpiQueryMix, which returns the
current foreground mix setting for a character string primitive. GpiQueryAttrs
can be used to determine the current foreground and background mix values for a
single primitive type.

To specify a background mix value for all primitives, use GpiSetBackMix.
GpiQueryBackMix returns the current background mix value for a character-string
primitive. To specify the current foreground and background mix values for a
single primitive type, call GpiSetAttrs.

Note:  Not all devices support all of the background and foreground mix
       attributes described. When a device does not support the mix attribute
       chosen by an application, the default mix attribute is used; no error
       condition is raised. DevQueryCaps can be used to determine whether a mix
       attribute is supported on a specific device.


ΓòÉΓòÉΓòÉ 7.2.11. Color on Advanced Display Devices ΓòÉΓòÉΓòÉ

Some devices can display simultaneously a fixed number of colors (typically
156), chosen from a much larger number of colors (often more than 256000). An
application can use the Palette Manager functions to take advantage of the
extra capabilities of these devices. These functions enable an application to
change the colors in a device's physical color table and the displayed colors
rapidly without explicitly redrawing the screen.

An application can use the CAPS_ADDITIONAL_GRAPHICS option of DevQueryCaps to
determine whether the display device supports palette functions.


ΓòÉΓòÉΓòÉ 7.2.12. Dithering ΓòÉΓòÉΓòÉ

If an application requests a color not available in the physical color table,
the operating system can approximate the color by a process called dithering.
For example, if the physical color table does not contain a light green color
but does contain a yellow and a green, the operating system can create what
appears to be light green by mixing yellow pels and green pels. Dithering is a
variation on the way red, green, and blue color guns illuminate the phosphors
in a single pel to produce a color that is not pure red, green, or blue (for
example, yellow).

The dithering process takes advantage of the way the human eye interprets
color. If every other pel is set to one color, and all the intermediate pels to
a different color, together they produce the effect of a third color at normal
viewing distances.

The checkerboard effect is just one of the ways in which dithering can be
implemented. Dithering works only when producing a solid mass of color, such as
an area fill pattern. It does not have the desired effect on line primitives.

Dithering is especially important on monochrome devices. By combining various
combinations of black pels with white pels, the operating system can create
numerous shades of gray.

To use only the pure colors defined in the physical color table, that is, to
prevent color dithering, set LCOL_PURECOLOR in GpiCreateLogColorTable. When
LCOL_PURECOLOR is set, the nearest available color to the 1 selected is used.


ΓòÉΓòÉΓòÉ 7.2.13. Considerations When Using Monochrome Displays ΓòÉΓòÉΓòÉ

When a graphic primitive that is drawn in color is displayed on a monochrome
display, the operating system maps the colors that the application uses to the
colors supported by the monochrome display.


ΓòÉΓòÉΓòÉ 7.2.13.1. Drawing Color Graphics on Monochrome Devices ΓòÉΓòÉΓòÉ

When mapping color graphics to a monochrome device (screen, printer, or bit
map), the monochrome device has a reset color and a contrast color. The reset
color is the color GpiErase clears to and is either black or white. If the
reset color is black, the contrast color is white; and if the reset color is
white, the contrast color is black.

To determine whether the reset color is to be black or white, the color
retrieved by the index CLR_BACKGROUND from the current logical color table is
examined. If a logical color table has not been loaded, CLR_BACKGROUND is
either the paper color on a printer or SYSCLR_WINDOW on a display. If a logical
color table has been loaded, CLR_BACKGROUND is the color addressed by color
index 0 on any device.

If the color retrieved by CLR_BACKGROUND is either white or black, that color
becomes the reset color. For example, if an application is drawing to a screen,
has not loaded a color table, and the system colors have not been altered, the
background color is white, because SYSCLR_WINDOW produces a white background by
default. In this instance, the contrast color is black.

If the color retrieved by CLR_BACKGROUND is neither white nor black, the color
translates to whichever of black and white it is nearest to. As a rule, dark
colors produce a black background, and pale colors produce a white background.
For example, if an application is using a loaded color table, or if the color
retrieved by SYSCLR_WINDOW has been altered (either interactively or by
WinSetSysColors), CLR_BACKGROUND could be dark gray. In this instance, the
reset color would be black, and the contrast color would be white.

When the reset color has been established, the PM programming interface applies
the following rules when mapping color graphics to a monochrome device:

o Any color graphics drawn in CLR_BACKGROUND, and any graphics defined in the
  actual reset color (which is either black or white), are drawn in the reset
  color. Any other graphics are drawn in the contrast color.

o The index CLR_WHITE produces white, and the index CLR_BLACK produces black,
  regardless of whether the reset color is black or white.

o If no color table is loaded and CLR_DEFAULT or CLR_NEUTRAL are used as the
  foreground color, they produce the contrast color. If they are used as the
  background color, they produce the reset color.

o If an application calls GpiQueryNearestColor for a monochrome device, one of
  the following occurs:

   - If the color supplied on input is the reset color, the reset color is
     returned.
   - If the color supplied on input is not the reset color, the contrast color
     is returned.


ΓòÉΓòÉΓòÉ 7.2.13.2. Drawing Color Area Fill Patterns on Monochrome Devices ΓòÉΓòÉΓòÉ

An area primitive is drawn according to the current foreground and background
mix attributes and in the current area foreground and area background colors.

When an application draws a monochrome pattern on a color device, the bits of
the pattern set to 1 translate to the current area foreground color, and the 0
bits translate to the current area background color. When the application draws
a color pattern on a monochrome device, and if the current pattern is anything
other than PATSYM_DEFAULT or PATSYM_SOLID from the default pattern set, the
color closest to white is translated into 1 bits. For example, if a pattern of
diagonal lines is being drawn in which the foreground color is red and the
background color is cyan, the cyan is translated to white (1 bits) because cyan
is closer than red is to white. Red, therefore is translated to black (0 bits).
The effect of translating this color pattern to a monochrome surface is
summarized as follows:

Pattern      As 1s and     Color       Monochrome
                0s        Surface       Surface

\   \        10001000     RcccRccc     01110111
 \   \       01000100     cRcccRcc     10111011
  \   \      00100010     ccRcccRc     11011101
   \   \     00010001     cccRcccR     11101110
\   \        10001000     RcccRccc     01110111
 \   \       01000100     cRcccRcc     10111011
  \   \      00100010     ccRcccRc     11011101
   \   \     00010001     cccRcccR     11101110

The original pattern of 1's and 0's is used, however, when deciding which part
of the pattern is the background and which part is the foreground. Thus, if the
background mix attribute is BM_LEAVEALONE, the following occurs:

Pattern      As 1s and     Color      Monochrome
                0s        Surface      Surface

\   \        10001000     R...R...     0...0...
 \   \       01000100     .R...R..     .0...0..
  \   \      00100010     ..R...R.     ..0...0.
   \   \     00010001     ...R...R     ...0...0
\   \        10001000     R...R...     0...0...
 \   \       01000100     .R...R..     .0...0..
  \   \      00100010     ..R...R.     ..0...0.
   \   \     00010001     ...R...R     ...0...0

The 1 bits on the monochrome surface still are interpreted as the background of
the primitive and are not drawn when the BM_LEAVEALONE attribute is specified.

When a bit map is used as an area fill pattern, any bit drawn in the current
area background color is set to 0, and all other bits are set to 1 on a
monochrome surface. Thus, if the current area background color is blue, all
blue bits in the bit map are set to 0, and all other bits are set to 1. The 0
bits constitute the background of the primitive.

If the pattern is solid (PATSYM_DEFAULT or PATSYM_SOLID in the supplied pattern
set), the following occurs:

o If color dithering is switched off, and the application is drawing a color
  pattern to a color surface, the color nearest the color specified is used.

o If color dithering is switched on, and the application is drawing a color
  pattern to a color surface, a combination of colors can be used to achieve
  the effect of the requested color. For example, if the application chooses
  pink on a surface where pink is not available, a combination of red and white
  pels can be used to achieve the effect of the color.

o If color dithering is switched on, and the application is drawing a color
  pattern to a monochrome surface, sufficient pels are set to suggest the
  intensity of the requested color.

Dithering can be enabled and disabled using LCOL_PURECOLOR in
GpiCreateLogColorTable.


ΓòÉΓòÉΓòÉ 7.3. Using Color and Mix Attributes ΓòÉΓòÉΓòÉ

The color- and mix-attribute functions can be used to perform the following
tasks:

o Create a logical color table.

o Determine the format and the starting and ending index values of the current
  logical color table.

o Determine the index value for an entry in the logical color table that is the
  closest match to an RGB value.

o Determine the RGB value associated with a particular entry in the logical
  color table.

o Determine and set the current foreground and background colors.

o Determine and set the current foreground and background mix attributes.


ΓòÉΓòÉΓòÉ 7.3.1. Creating a Logical Color Table ΓòÉΓòÉΓòÉ

To create a logical color table, the application creates an array of RGB values
that replace the existing logical color table, then calls
GpiCreateLogColorTable, using the LCOL_RESET and LCOLF_CONSECRGB flags. The
following figure demonstrates this process.

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR01(void){
    HPS hps;
    LONG alTable[] = {
        0xFFFFFF,        /* White */
        0xFF88FF,
        0xFF8800,
        0xFF8888,
        0xFF0088,
        0x880088,
        0x008888,
        0x00FF88,
        0x00F800,
        0x008800,
        0x000088,
        0x0000F8,
        0x0800F8,
        0x888888,
        0x080808,
        0x000000 };      /* Black */

    GpiCreateLogColorTable(hps,
       LCOL_RESET,                      /* Start with the default      */
       LCOLF_CONSECRGB,                 /* Consecutive RGB values      */
       0,                               /* Starting index in table     */
       sizeof(alTable) / sizeof(LONG),  /* Number of elements in table */
       alTable);
} /* fncCOLR01 */


Creating a Logical Color Table


ΓòÉΓòÉΓòÉ 7.3.2. Determining the Color-Table Format and Index Values ΓòÉΓòÉΓòÉ

To determine the format and the starting and ending index values of the current
logical color table, applications call GpiQueryColorData. The following figure
is an example of using GpiQueryColorData to determine whether the default
logical color table is loaded. If so, the code fragment loads a new table.

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR02(void){
    HPS hps;
    LONG        aClrData[3];
    LONG alTable[16];

    GpiQueryColorData(hps, 3, aClrData);

    if (aClrData[QCD_LCT_FORMAT] == LCOLF_DEFAULT)
        GpiCreateLogColorTable(hps,
           LCOL_RESET,                      /* Start with the default      */
           LCOLF_CONSECRGB,                 /* Consecutive RGB values      */
           0,                               /* Starting index in table     */
           sizeof(alTable) / sizeof(LONG),  /* Number of elements in table */
           alTable);
} /* fncCOLR02 */


Determining Color-Table Format and Index Values


ΓòÉΓòÉΓòÉ 7.3.3. Determining the Index Value of an RGB Value ΓòÉΓòÉΓòÉ

Applications call GpiQueryColorIndex to find the closest match in a logical
color table to an RGB value. This function finds the closest match for this RGB
value in the physical color table, then finds the color in the logical color
table closest to the color in the physical color table. The function returns
the index value of that entry in the logical color table. The followiing figure
is an example of how to determine which index value in the logical color table
matches the RGB value for pink (0x00FF00FF), then uses that index entry to set
the foreground color to pink for each of the primitive attributes.

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR03(void){
    LONG lIndex;                             /* Logical-color-table index */
    HPS hps;

    lIndex = GpiQueryColorIndex(hps, LCOLOPT_REALIZED, 0x00FF00FF);

    if ((lIndex >= 0) && (lIndex <= 15))     /* Check for valid index     */
        GpiSetColor(hps, lIndex);
} /* fncCOLR03 */


Determining the Index Value of an RGB Value


ΓòÉΓòÉΓòÉ 7.3.4. Setting the Primitive Color Attributes ΓòÉΓòÉΓòÉ

To set the color attributes for 1 type of graphics primitive, an application
uses GpiSetAttrs. To set the color attributes for each type of primitive in a
presentation space, use GpiSetColor and GpiSetBackColor. The following figure
shows how to use GpiSetAttrs to set the color attribute of line primitives to
dark gray.

#define INCL_GPIPRIMITIVES
#include <os2.h>

void fncCOLR04(void){
    LINEBUNDLE lbnd;     /* Line-primitive attribute structure */
    HPS hps;

    lbnd.lColor = CLR_DARKGRAY;

    GpiSetAttrs(hps, PRIM_LINE, LBB_COLOR, 0, &lbnd);
} /* fncCOLR04 */


Setting Primitive Color Attributes

The following figure is an example of how to use GpiSetColor to set the
foreground color attribute to dark gray in all of the primitives.

#include <os2.h>

void fncCOLR05(void){
    HPS hps;

    GpiSetColor(hps, CLR_DARKGRAY);
} /* fncCOLR05 */


Setting Foreground Color Attributes


ΓòÉΓòÉΓòÉ 7.3.5. Creating a Palette ΓòÉΓòÉΓòÉ

To create a palette, an application must first call DevQueryCaps with the
CAPS_ADDITIONAL_GRAPHICS option to determine whether the device supports
palette functions. Next the application creates an array of RGB values or an
array of RGB2 structures, then calls GpiCreatePalette. Next the applications
calls GpiSelectPalette to select the palette for the presentation space, and
calls WinRealizePalette to map the RGB values to device colors for subsequent
drawing. When the application is finished drawing, it calls GpiSelectPalette to
disassociate the presentation space and the palette; then it deletes the
palette by calling GpiDeletePalette.

The following figure demonstrates these steps.

#define INCL_GPILOGCOLORTABLE
#define INCL_GPIBITMAPS
#include <os2.h>
void fncCOLR06(void){
    COLOR clrCurrent;
    HPAL hpal;
    HDC hdc;
    HPS hps;
    HAB hab;
    HWND hwnd;
    POINTL aptl[2], ptl;
    LONG cSimulColors, lPalSupport;
    SHORT j;
    RGB2 *prgb2ColorData;

    /* Determine how many colors the device can display at once.              */
    DevQueryCaps(hdc, CAPS_COLORS, 1, &cSimulColors);

    /* Determine if the device supports Palette Manager functions.            */
    DevQueryCaps(hdc, CAPS_ADDITIONAL_GRAPHICS, 1, &lPalSupport);

    /* Allocate space for the array of RGB2 structures.                       */
    DosAllocMem((PPVOID)&prgb2ColorData, cSimulColors * sizeof(RGB2), fALLOC);

    /* Fill the array of RGB2 structures with as many different               */
    /*    shades of blue as the device will support.                          */

    clrCurrent = 0x000000FF;
    for (j = 0; j < cSimulColors; j++) {
        prgb2ColorData[j].bRed = 0;
        prgb2ColorData[j].bGreen = 0;
        prgb2ColorData[j].bBlue = clrCurrent;
        prgb2ColorData[j].fcOptions = 0;
        clrCurrent = clrCurrent > 0 ? --clrCurrent : 0x000000FF;
    }

    if (lPalSupport & CAPS_PALETTE_MANAGER) {
        hpal = GpiCreatePalette(hab,       /* Create palette                  */
               0L,
               LCOLF_CONSECRGB,            /* Format of color table entries   */
               cSimulColors,               /* Number of entries in table      */
               (PULONG) prgb2ColorData);   /* Pointer to color table          */
    }

    GpiSelectPalette(hps, hpal);
    WinRealizePalette(hwnd, hps);
    GpiSelectPalette(hps, NULLHANDLE);     /* Restore default physical colors */
    GpiDeletePalette(hpal);                /* Delete palette                  */
} /* fncCOLR06 */


Creating a Palette


ΓòÉΓòÉΓòÉ 7.4. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the color and mix attribute functions.

Color and Mix Attribute Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiAnimatePalette       ΓöéChanges the color values of         Γöé
Γöé                        Γöéanimating indexes in a palette.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateLogColorTable  ΓöéLoads a new logical color table.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePalette        ΓöéCreates and initializes a color     Γöé
Γöé                        Γöépalette.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeletePalette        ΓöéDeletes a color palette.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBackColor       ΓöéDetermines the current background   Γöé
Γöé                        Γöécolor from the character string     Γöé
Γöé                        Γöébundle attributes.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBackMix         ΓöéDetermines the current background   Γöé
Γöé                        Γöémix attribute from the character    Γöé
Γöé                        Γöéstring bundle attributes.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryColor           ΓöéDetermines the current foreground   Γöé
Γöé                        Γöécolor from the character string     Γöé
Γöé                        Γöébundle attributes.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryColorData       ΓöéDetermines information about the    Γöé
Γöé                        Γöécurrent logical color table.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryColorIndex      ΓöéDetermines the index value for the  Γöé
Γöé                        Γöélogical color table entry closest toΓöé
Γöé                        Γöéa specified RGB value.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLogColorTable   ΓöéDetermines the current logical colorΓöé
Γöé                        Γöétable contents.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMix             ΓöéDetermines the current foreground   Γöé
Γöé                        Γöémix attribute from the character    Γöé
Γöé                        Γöéstring bundle attributes.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryNearestColor    ΓöéDetermines the RGB value available  Γöé
Γöé                        Γöéon an output device, closest to a   Γöé
Γöé                        Γöédesired RGB value.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPalette         ΓöéDetermines the palette currently    Γöé
Γöé                        Γöéselected in a presentation space.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPaletteInfo     ΓöéDetermines the RGB, the index       Γöé
Γöé                        Γöévalues, or both, for the currently  Γöé
Γöé                        Γöéloaded colors.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryRealColors      ΓöéDetermines the RGB values for actualΓöé
Γöé                        Γöécolors in the device color table.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryRGBColor        ΓöéDetermines the RGB value paired withΓöé
Γöé                        Γöéa logical color table index.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRealizeColorTable    ΓöéMaps the logical color table into   Γöé
Γöé                        Γöéthe physical color table.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSelectPalette        ΓöéSelects a new palette for the       Γöé
Γöé                        Γöépresentation space.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBackColor         ΓöéSets the background color for       Γöé
Γöé                        Γöécharacter strings, markers, areas,  Γöé
Γöé                        Γöéimages, and bit maps.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBackMix           ΓöéSets the background mix attribute   Γöé
Γöé                        Γöéfor character strings, markers,     Γöé
Γöé                        Γöéareas, images, and bit maps.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetColor             ΓöéSets the foreground color for arcs, Γöé
Γöé                        Γöélines, character strings, markers,  Γöé
Γöé                        Γöéareas, images, and bit maps.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMix               ΓöéSets the foreground mix attribute   Γöé
Γöé                        Γöéfor arcs, lines, character strings, Γöé
Γöé                        Γöémarkers, areas, images, and bit     Γöé
Γöé                        Γöémaps.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPaletteEntries    ΓöéChanges entries in a logical        Γöé
Γöé                        Γöépalette.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiUnrealizeColorTable  ΓöéDisassociates the mapped logical    Γöé
Γöé                        Γöécolor table from the physical color Γöé
Γöé                        Γöétable.                              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the color and mix
attribute functions.

Color and Mix Attribute Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAREABUNDLE              ΓöéArea primitive attributes.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCHARBUNDLE              ΓöéCharacter primitive attributes.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéIMAGEBUNDLE             ΓöéImage primitive attributes.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEBUNDLE              ΓöéLine primitive attributes.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMARKERBUNDLE            ΓöéMarker primitive attributes.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRGB                     ΓöéRed, green and byte color values.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRGB2                    ΓöéSame as RGB with the addition of an Γöé
Γöé                        Γöéoption-flag.                        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 8. Bit Maps ΓòÉΓòÉΓòÉ

Raster output devices, such as display screens, are made up of a number of
picture elements, called pixels or pels. By setting the color of the pels, you
can create an image on the screen. The screen image can be represented
internally by a graphics object called a bit map.  The bit map contains a
number of bits that describe the appearance of each pel on the screen.

This chapter describes bit maps, their creation, uses, and functions. The
following topics are related to the information in this chapter:

o Presentation spaces and device contexts
o Coordinate spaces
o Color and mix modes
o Area primitives
o Paths.


ΓòÉΓòÉΓòÉ 8.1. About Bit Maps ΓòÉΓòÉΓòÉ

Applications can use bit maps to:

o Store and display scanned images, icons, and symbols
o Create fill patterns for area primitives and paths.

An application can display a bit-map image on any raster output device.  A
raster is a rectangular matrix of pels on a video display or dot matrix
printer.  A raster output device displays an image by setting pels in its
matrix to colors specified in a corresponding bit map.  An image created in
this way is called a "bit-map image".  Bit maps cannot be sent to vector output
devices such as plotters.

A bit map is drawn to an output device row-by-row. Each horizontal line of pels
is known as a scan line.

There is a 1-to-1 correspondence between the number of rows of pels in a
bit-map image and the rows of bits in a bit map.  The first pel in a bit-map
image is in the lower-left corner, and the last pel is in the upper-right
corner.  The pels are in left-to-right order inside each row of the image. The
following figure shows this relationship between bit map and image.

Bits and Pels in a Bit-Map Image

When an application creates a bit map by calling GpiCreateBitmap, it specifies
the bit-map width and height in terms of pels in the bit-map image.  The width
is the number of pels within a row; the height is the number of rows.  The
application must store these dimensions in the BITMAPINFO2 and
BITMAPINFOHEADER2 structures and pass their addresses to GpiCreateBitmap.


ΓòÉΓòÉΓòÉ 8.1.1. System Implementation ΓòÉΓòÉΓòÉ

Bit maps are most useful when rapid and frequent movement is required, such as
with icons and pointers. They are especially useful for restoring the contents
of a window-for example, when an overlying window is removed. If you save the
contents of a window in a bit map, you can restore the window contents simply
by redisplaying the bit map when the window needs to be redrawn.

Using bit maps is also an effective method of erasing some of the screen
contents.  For example, you can save the image of the screen in a bit map at
any time while drawing on the screen.  If you continue drawing after saving the
screen image, you can "erase" any drawing done since you saved the screen image
by redisplaying the bit map.

Bit maps are not, however, the recommended way to store graphics that are going
to be changed.  Most changes to the bit-map contents mean that you have to
re-create the bit map.

Bit-map images are device-dependent.  Their appearance is affected by the shape
of the device's pels and the device's color capabilities.  For example, if the
pels on one display measure 0.05 mm by 0.1 mm, but 0.1 mm by 0.3 mm on a second
display, a circular bit-map pie chart drawn on the first display appears
elliptical on the second. The following figure shows how a bit map appears on
two types of displays.

Bit Map Shown on Two Types of Displays

Bit maps, particularly color bit maps, can also occupy large amounts of memory.
The actual amount of memory occupied by a bit map is determined by both the
size of the bit map and the number of bits used to describe each pel.


ΓòÉΓòÉΓòÉ 8.1.2. Bit Map Functions ΓòÉΓòÉΓòÉ

OS/2 2.0 provides a set of functions that allow you to:

o Create bit maps
o Create and load custom bit maps
o Store color information on a bit map
o Draw bit maps
o Transfer bit maps
o Change the size of a bit map
o Specify the mix values for a bit map
o Convert between monochrome and color data
o Manipulate single pels
o Copy images from a display into a bit map
o Save a bit map
o Delete a bit map
o Make a bit map available to other processes.


ΓòÉΓòÉΓòÉ 8.1.2.1. Creating a Bit Map ΓòÉΓòÉΓòÉ

A bit map can be created by an application, or by using the PM Icon Editor.


ΓòÉΓòÉΓòÉ 8.1.2.1.1. By an Application ΓòÉΓòÉΓòÉ

To enable an application to create a bit map:

 1. Create a memory device context.

    A memory device context enables an application to treat a bit map in memory
    as though it were a device.  For example, an application can copy color
    information from another bit map, or copy pels on the display, into a bit
    map associated with a memory device context.

    To create the memory device context, call DevOpenDC with:

   o A device type of OD_MEMORY (second argument)

   o A handle to a compatible device context (such as the device context of a
     device with which the bit map is to be compatible).

     Note:  The device device-context handle ideally should be the handle of
            the actual device to which you will be directing the bit map;
            otherwise, it will be necessary to change ownership to the
            appropriate device driver before the BitBlt operation (which copies
            the bit map from one presentation space to one associated with a
            screen device context).  As a consequence, the image may appear
            distorted.

    If you omit the handle of the compatible device context by specifying NULL,
    screen compatibility is assumed.

 2. Create a graphics presentation space and associate it with the memory
    device context.

    The operating system requires this association before the application can
    perform many of the bit map operations.  The handle of this graphics
    presentation space is required as input to subsequent bit-map-creation and
    manipulation functions.

 3. Create the bit map.

    When an application creates a bit map, the handle of the presentation space
    that you have associated with the memory device context causes the bit map
    to be created in a format that is compatible with the memory device
    context.

    The application also passes two structures: the bit-map information header
    and the bit-map information table. These structures contain a great deal of
    information about the bit map.

    To create the bit map, call GpiCreateBitmap with:

   o The handle of the presentation space (first argument)
   o The bit-map information header, BITMAPINFOHEADER2 (second argument).

    The bit-map information header data structure is defined in the header
    files in the OS/2 2.0 Toolkit. The bit-map information table contains
    similar information, with the addition of the RGB2 array structure.

    GpiCreateBitmap returns a handle to the bit map, which is used to identify
    the bit map.

    To determine which bit-map formats are supported on a particular device,
    call GpiQueryDeviceBitmapFormats. This returns every format supported on a
    named device.  The data is returned as an array of bit-map plane and
    bit-count pairs.  The first pair of values in the array is the one most
    suitable for the device.

    You can think of the bit map at this stage as a rectangular area of memory
    containing random data.  You can initialize the bit map at this stage by
    providing GpiCreateBitmap with the address in application storage of some
    initialization data and by setting the CBM_INIT option.  This is a useful
    function if, for example, your application always starts by displaying the
    same image.

 4. Select the bit map.

    Before selecting the bit map, you can disassociate the presentation space
    from the original memory device context and associate it with a different
    memory device context.  However, the bit-map format must be convertible to
    a format that is supported by the new device. If you have selected one of
    the four standard bit-map formats, this compatibility is guaranteed and the
    conversion is automatic.

    Note:  When a presentation space is associated with a memory device
           context, a bit map must be selected into the device context before
           you can draw in the presentation space.

    To select the bit map, call GpiSetBitmap with:

   o The presentation-space handle (first parameter)
   o The bit map-handle (second parameter).

The following figure shows the sequence of events when you create and display a
bit map.

Creating and Displaying Bit Maps

The application:

 1. Calls DevOpenDC to create the memory device context.

 2. Creates a graphics presentation space.  This is associated with the memory
    device context.

 3. Calls GpiCreateBitmap to define a bit map.

 4. Calls GpiSetBitmap to designate the bit map as the one currently selected
    in the memory device context.

 5. Calls drawing instructions to the Presentation Space to draw to the bit
    map.

    Note:  If the bit map is initialized when it is created, this step does not
           normally exist.  Alternately, this step can be a GpiSetBitmapBits
           call.

 6. Calls GpiBitBlt to copy the bit map from Presentation Space 1 to
    Presentation Space 2 (associated with a screen device context). The bit map
    is transferred directly to the screen.


ΓòÉΓòÉΓòÉ 8.1.2.1.2. Using the Icon Editor ΓòÉΓòÉΓòÉ

Using the Icon Editor, you can create monochrome or color bit maps that have a
static appearance.  This means that the bit maps can be created in advance and
then used without change while the application is running.

When you use the Icon Editor to create a bit map, the bit map is saved in a
resource file that can be loaded whenever it is needed. To load a bit-map file,
call GpiLoadBitmap, with the identifier of the resource file that contains the
bit map, as the second parameter.  If you allow this value to default, the
application's .EXE file is assumed to contain the bit map.

GpiLoadBitmap lets you specify the x- and y-dimensions (in pels) of the bit
map.  The loaded bit map is stretched or compressed accordingly. If you supply
a 0 value for one of these dimensions, the bit map is sized in the other
dimension only, which is likely to cause distortion of the image.  If the bit
map is to be produced in its original size, specify 0 for both its width and
its height.

Output from the call to this function is the bit-map handle.  To display the
loaded bit map on the screen, follow the sequence of steps described in
Creating a Bit Map, omitting steps 3 (defining the bit map) and 5 (issuing
drawing instructions to the presentation space).

A bit map created by the Icon Editor is saved in a device-independent format.
This format generates an array of bit maps with formats (bits per pel) matching
each of the supported display devices.


ΓòÉΓòÉΓòÉ 8.1.2.2. Creating and Loading a Custom Bit Map ΓòÉΓòÉΓòÉ

An application can create a custom bit map by setting the bits in an array and
passing the array to GpiCreateBitmap, or by running the Icon Editor and loading
the bit map with GpiLoadBitmap.

To create a custom bit map with an array, an application:

 1. Defines an array of bytes that will set pels in an image to the appropriate
    colors.  This array of bytes typically represents the output of a scanned
    image.

 2. Sets the fields in the BITMAPINFOHEADER2 structure to their appropriate
    values.

 3. Sets the fields in the BITMAPINFO2 structure to their appropriate values.

 4. Calls GpiCreateBitmap, passes it the addresses of the structures and the
    array of bytes that the application has already defined, and sets the
    flOptions parameter to CBM_INIT.

If the application is to use this bit map as a fill pattern, it assigns the bit
map a local identifier by calling GpiSetBitmapId.

To load a custom bit map that was created with the Icon Editor:

 1. Copy the bit map file to the directory in which you compile your
    application.

 2. Create a BITMAP entry in your application's resource file, assigning a
    unique integer identifier to the bit map.

 3. Call GpiLoadBitmap, passing it the identifier that you assigned to the bit
    map in the resource file.

An application can use GpiLoadBitmap to load any bit map from a file that
conforms to any of the standard OS/2 bit-map formats or to a device-specific
format supported by the device concerned. This means that an application can
load a bit map created by another application, if that application created the
correct bit-map header and stored the bit-map bits correctly.


ΓòÉΓòÉΓòÉ 8.1.2.3. Storing Color Information in a Bit Map ΓòÉΓòÉΓòÉ

Graphics systems use one of two formats for storing color information in bit
maps.  The first format uses a single plane and a multiple bit count. The
second format uses multiple color planes.


ΓòÉΓòÉΓòÉ 8.1.2.3.1. Color Planes ΓòÉΓòÉΓòÉ

Bit maps are arranged in one or more color planes.  A color plane is an array
of bit-map bits that contains color information.

The bit maps in each of the previous illustrations use the single bit-map plane
format, which is the standard format for bit maps in OS/2 applications.  In
this format, a specified number of adjacent bit-map bits contains indexes to
either a special color table of RGB values or actual RGB2 structures.  Whether
the application maps bits into an RGB or RGB2 structure depends on the bit-map
format.  All of the color information resides in a single plane.

The second color format uses more than one color plane. A common multiplane
bit-map format is the 3-plane format, in which one plane corresponds to the red
pels, another to the green pels, and a third to the blue pels.  Multiplane
bit-map formats are rare in PM applications.  Most bit maps are stored
externally in a single-plane format, although the device driver (such as VGA)
may internally convert them to the multiplane format.

The single-plane format can be converted internally to any multiplane format
used by a device.  You also can use a nonstandard number of bits to describe
each pel, if supported by your output device. If you write your own
presentation driver, it must be able to convert the standard bit-map formats to
its own internal format.

An application can determine which color-plane format a device supports by
calling GpiQueryDeviceBitmapFormats.


ΓòÉΓòÉΓòÉ 8.1.2.3.2. Standard Bit-Map Formats ΓòÉΓòÉΓòÉ

On a monochrome device, you need only 1 bit to describe a single pel, and that
bit is switched on or off.  Color devices require more bits.  For example, an
8-color picture requires 3 bits to describe a single pel, because each
component of the RGB mix (red, green, blue) that gives a pel its color must be
described.

A bit count is a value that specifies how many adjacent bit-map bits correspond
to each pel in a bit-map image.  There are four standard bit-map formats, each
with a different bit count.  The formats are shown in the following table.

Standard Bit-Map Formats

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFormat              ΓöéBits per pel        ΓöéSize of 640 x 480   Γöé
Γöé                    Γöé                    Γöéimage in bytes      Γöé
Γöé                    Γöé                    Γöé(uncompressed)      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMonochrome          Γöé1                   Γöé38 400              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé16 color            Γöé4                   Γöé153 600             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé256 color           Γöé8                   Γöé307 200             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé16.7 million color  Γöé24                  Γöé921 600             Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  The bits are stored consecutively in the bit-map plane. If you have 4
bits for each pel, the 4 bits for pel 1 are followed by the 4 bits for pel 2,
and so on.  The bits that describe pel 1 are stored beginning in the
most-significant bits of the first byte.  The data for each scan line is packed
together, and the bottom scan line appears first in memory with the leftmost
pel first.  Each scan line, however, is padded at the end so that each line
begins on a ULONG (32-bit) boundary.

If the device supports a bit count of 1 bit per pel, the color table contains 2
entries.  A device that supports a bit count of n bits per pel, has a
corresponding color table with 2n entries. However, a bit count of 24 bits per
pel indicates that there is no color table, because each pel is a direct RGB
value.

The following figure shows a bit map using a bit count of 4 bits per pel and an
associated color table:

A Bit Map and Its Associated Color Table

If a device uses a bit count of 1, 4, or 8 bits per pel, the bit-map bits
contain index values for a bit-map color table.  If the device supports a bit
count of 24 bits per pel, the bit-map bits contain the bRed, bGreen, and bBlue
fields of RGB2 structures.  No color table is associated with a bit map on a
device that supports a format of 24 bits per pel-such a device can support over
16 million colors. Instead of using a color table, the BITMAPINFO2 structure
consists of only the header, and the red, green, and blue color values are
provided directly by the bit-map data.

An application can determine the bit-count format that a device supports by
calling GpiQueryDeviceBitmapFormats.


ΓòÉΓòÉΓòÉ 8.1.2.4. Drawing Bit Maps ΓòÉΓòÉΓòÉ

An application can draw bit-map images on a raster printer or display screen,
or into metafiles associated with a raster device. Any GPI drawing requests
(including those that produce graphics text), issued to a presentation space
associated with a memory DC containing a selected bit map, cause the bit map to
receive raster images of your drawings. The following table describes the bit
map drawing functions:

Bit-Map Drawing Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction            ΓöéInput               ΓöéOutput              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinDrawBitmap       ΓöéThe handle of a bit ΓöéA bit-map image on aΓöé
Γöé                    Γöémap.                Γöéraster display.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiImage            ΓöéA buffer containing ΓöéA special monochromeΓöé
Γöé                    Γöébit map image data. Γöébit-map image on a  Γöé
Γöé                    Γöé                    Γöéraster display or   Γöé
Γöé                    Γöé                    Γöéprinter.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawBits         ΓöéA buffer containing ΓöéA bit-map image on aΓöé
Γöé                    Γöébit map image data. Γöéraster display or   Γöé
Γöé                    Γöé                    Γöéprinter.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBitBlt           ΓöéThe handle of a     ΓöéA bit-map image on aΓöé
Γöé                    Γöépresentation space  Γöéraster display or   Γöé
Γöé                    Γöécontaining a bit    Γöéprinter, or a       Γöé
Γöé                    Γöémap.                Γöébit-map image into aΓöé
Γöé                    Γöé                    Γöémetafile (albeit in Γöé
Γöé                    Γöé                    Γöéan escape order).   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiWCBitBlt         ΓöéThe handle of a bit ΓöéA bit-map image on aΓöé
Γöé                    Γöémap.                Γöéraster display or   Γöé
Γöé                    Γöé                    Γöéprinter, or a       Γöé
Γöé                    Γöé                    Γöébit-map image into aΓöé
Γöé                    Γöé                    Γöémetafile.           Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 8.1.2.4.1. WinDrawBitmap ΓòÉΓòÉΓòÉ

WinDrawBitmap draws a bit-map image by copying it into a window linked to a
target presentation space.  A call to this function is valid only in draw mode
(DM_DRAW), and only for a screen device context. This function does not require
an application to select a bit map into a presentation space before the
application draws the corresponding image.  An application can use
WinDrawBitmap to scale bit maps by specifying DBM_STRETCH as the last argument,
and the address of a RECTL structure as the fourth argument.  The coordinates
in this structure are always device coordinates.

WinDrawBitmap draws both color and monochrome bit maps.  Color bit maps require
no color conversion.  Monochrome bit maps can be drawn in any two colors which
can be explicitly specified as parameters to the call or taken from the image
bundle.  These parameters will be color table indexes or RGB values, depending
on the color table mode of the target presentation space.  The current image
bundle mix modes are used and, for certain mix values, will affect color.

You can call WinDrawBitmap in retain mode, but the bit-map image will only be
drawn and not recorded in the segments.

Note:  An application can determine the current colors and their corresponding
       mix modes by calling GpiQueryAttrs. The application can set them by
       calling GpiSetAttrs.

An inverted bit map is a bit map in which the colors have been inverted; white
becomes black and black becomes white.  An application can draw inverted bit
maps by calling WinDrawBitmap and passing it DBM_INVERT as the last argument.
An application can draw halftone bit maps by calling WinDrawBitmap and passing
it DBM_HALFTONE as the last argument.  Before drawing the bit map, clear the
presentation space to CLR_BACKGROUND using GpiErase.


ΓòÉΓòÉΓòÉ 8.1.2.4.2. GpiImage ΓòÉΓòÉΓòÉ

GpiImage draws a nonstandard, monochrome (two-color) bit map called an image
primitive.  The bit-map bits in an image are stored in the opposite order from
the bits in a standard bit map-the first bit in the bit map corresponds to the
pel in the upper-left corner of the bit-map image, and the last bit in the bit
map corresponds to the pel in the lower-right corner of the bit-map image. The
following figure shows the correspondence between the bits in an image
primitive and the pels in the drawing produced by GpiImage.

Image-Primitive Bits and Pels

A call to GpiImage also is valid only in draw mode (DM_DRAW), but can provide
output to a screen or printer.  An application cannot scale bit-map images by
using GpiImage.


ΓòÉΓòÉΓòÉ 8.1.2.5. Transferring Bit Maps ΓòÉΓòÉΓòÉ

The three remaining bit-map drawing functions operate in very similar ways.
GpiDrawBits copies a bit-map image from application memory to a device or a
device context; GpiBitBlt directs bit maps to devices other than the screen;
GpiWCBitBlt enables you to retain the bit-map data in the segment store of the
target presentation space.

The similarities are discussed first.  Their differences are discussed in the
sections that follow.

An application should use GpiDrawBits, GpiBitBlt, or GpiWCBitBlt to draw bit
maps that use a color table or RGB2 structures color formats of 1, 4, 8, or 24
bits per pel.

An application can draw inverted bit maps for any of these three functions by
calling the function and passing ROP_NOTSRCCOPY as the raster operation.


ΓòÉΓòÉΓòÉ 8.1.2.5.1. GpiDrawBits ΓòÉΓòÉΓòÉ

GpiDrawBits copies bit map image data from storage into a bit map that has been
selected into a device context associated with a presentation space.  It can
also copy bit-map image data to a device. An application can use this function
to draw a bit map without first selecting the bit map into a presentation
space.

This function is valid in all draw modes.  Set the draw mode to DM_RETAIN or
DM_DRAWANDRETAIN to create retained segments; otherwise, the default mode,
DM_DRAW, is selected.


ΓòÉΓòÉΓòÉ 8.1.2.5.2. GpiBitBlt ΓòÉΓòÉΓòÉ

GpiBitBlt requires an application to use device coordinates for the dimensions
of the source and target rectangles.  GpiBitBlt allows you to direct bit maps
to devices other than the screen.  It is independent of the drawing mode, but
it operates as if in draw mode.

At its simplest, GpiBitBlt copies a whole bit map, unaltered, from a device or
bit map source to a device or bit map target. At its most powerful, GpiBitBlt
can take a part of or a whole bit map, and alter both its size and appearance
in the process of copying it to another device context. A bit map can be
copied:

o From one memory device context to another memory device context

o From a memory device context to the device context of an output device
  (screen window or printer) that supports raster operations

o From the device context of an output device to a memory device context

o From the device context of an output device to another device context of the
  same output device.  In both cases, the screen device can be a PM window.

A memory device context (whether it is the source or the target of the
GpiBitBlt operation) must have a bit map selected when GpiBitBlt is called.

GpiBitBlt has a number of input parameters, two of which are the handles of two
presentation spaces:  the source presentation space and the target presentation
space.  Both of these presentation spaces must be associated with an
appropriate device context. Unless the associated device is a banded printer, a
single presentation space can be both source and target.  This allows you to
copy a bit map within a single PM window, or to update the bit map. The source
and target rectangles are specified in device coordinates in GpiBitBlt.
GpiBitBlt, consequently, is very device-dependent, and should be avoided when
creating data for interchange.


ΓòÉΓòÉΓòÉ 8.1.2.5.3. GpiWCBitBlt ΓòÉΓòÉΓòÉ

GpiWCBitBlt enables you to retain the bit-map data in the segment store of the
target presentation space.  It is a valid in all three drawing modes:

o DM_DRAW-display, printer, or into metafile
o DM_RETAIN-into metafile or segment
o DM_DRAWANDRETAIN-display, printer, then into associated segment or metafile.

Most of the bit-map drawing operations occur in an application's device space;
GpiWCBitBlt, however, lets an application draw in its world space, but requires
that you use device coordinates for the source rectangle, and world coordinates
for the target rectangle.

An application can use GpiWCBitBlt to draw a bit map with consistent dimensions
on devices with different aspect ratios. The aspect ratio is the ratio of a
pel's width to its height.

When creating data for interchange, use GpiWCBitBlt. GpiWCBitBlt provides the
same function as GpiBitBlt, with the following exceptions:

o The target rectangle is specified in world coordinates, and all four
  coordinates (the two source-rectangle coordinates and the two
  target-rectangle coordinates) must be specified.

o The source handle must be a bit-map handle. It must not be the handle of a
  source presentation space. The bit map identified by the source handle must
  not be selected into a memory device context when you call GpiWCBitBlt.

o GpiWCBitBlt conforms to the current drawing mode in the target presentation
  space.  If the drawing mode is retain or draw-and-retain, the bit map is
  retained in segment store.


ΓòÉΓòÉΓòÉ 8.1.2.6. Changing the Size of the Bit Map ΓòÉΓòÉΓòÉ

You can specify the sizes of the rectangular bit blocks in both the source and
the target presentation spaces.  To do this, provide an array of up to four
device-coordinate positions as input to the call.  The first two positions
define the lower-left and upper-right corners of the target rectangle;  the
second two define the same two corners of the source rectangle.

If you want the two rectangles to be of equal size, do not specify the device
coordinates of the upper-right corner of the source rectangle. The correct
amount of data is automatically transferred to fill the target rectangle. The
following figure shows the points count for bit-block transfers.

Points Count for Bit-Block Transfers

Equal-size rectangles can be built much faster than rectangles that need
stretching or compressing.  Compression options (flOptions) are ignored if the
rectangles are to be of equal size.

If the rectangles are not to be of equal size, you must specify all four
coordinate points.  The bit-map data is stretched, if the target rectangle is
larger than the source rectangle, or compressed, if the target rectangle is
smaller, to fit the target rectangle. The bit map is stretched by duplicating
rows and columns of data, an action that might cause distortion of the image.
If the data is to be compressed, you can specify one of three compression
options as shown in the following table.

Bit-map Data Compression Rules

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOption              ΓöéCompression Rules                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBBO_OR              ΓöéCompresses the bit map data as          Γöé
Γöé                    Γöénecessary, using a logical OR operation Γöé
Γöé                    Γöéon the eliminated rows and columns. ThisΓöé
Γöé                    Γöéis useful for preserving the foreground Γöé
Γöé                    Γöéwhen foreground pels are "1" and the    Γöé
Γöé                    Γöébackground pels are "0".                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBBO_AND             ΓöéCompresses the bit map data as          Γöé
Γöé                    Γöénecessary, using a logical AND operationΓöé
Γöé                    Γöéon the eliminated rows and columns.     Γöé
Γöé                    ΓöéThis is useful for preserving the       Γöé
Γöé                    Γöéforeground when foreground pels are "0" Γöé
Γöé                    Γöéand the background pels are "1".        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBBO_IGNORE          ΓöéCompresses the bit map data as          Γöé
Γöé                    Γöénecessary, but ignores any eliminated   Γöé
Γöé                    Γöérows or columns. This is most useful forΓöé
Γöé                    Γöécolor bit maps, where the results of    Γöé
Γöé                    Γöécombining pels of different colors are  Γöé
Γöé                    Γöéunpredictable.                          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 8.1.2.7. Specifying Mix Values ΓòÉΓòÉΓòÉ

When you draw a graphics primitive into a presentation space, it is affected by
the current foreground-mix value, and possibly by the current background-mix
value, in that presentation space. However, when you copy a bit map into a
target presentation space, the current foreground- and background-mix values in
the target presentation space are ignored.  Instead, you specify a mix-mode
value, also known as the raster-operation (ROP) value.  This value determines:

o How the bit map is affected by any data that might already be in the target
  presentation space

o The color of each pel in the bit map.

Each pel in the bit map of the target presentation space has, potentially,
three color settings:

o The setting of that pel in the source rectangle

o The initial setting of that pel in the target rectangle

o The setting of that pel in the current area-fill pattern in the target
  presentation space.

The (boolean) values of each of these settings can be combined using boolean
operations to produce the final value of each pel in the target presentation
space.  For a color target, the target must be regarded as consisting of
multiple one-bit per pel planes, with the mixing applied to each plane
separately to produce the final color index into the physical color table.
Because the final color index is an index into the physical palette, the
results of any color mixing are therefore unpredictable.  For example, if you
ORed together two numeric index values, the color indexed by the result is
unlikely to have any direct relation to the colors indexed by the two values
you ORed together.  It depends on the order of the colors in the physical
table.

As input to the functions, you supply an actual mix value. The ROP mix value
required to achieve any given result can be determined from the following
table. The final value of each bit in every pel depends on the values of the
corresponding bits in the pattern (P), source (S), and the original target
value (T initial).  Each row of the table shows one of the eight possible
combinations of these values.  For each combination, mark the desired final
target value in the last column. The eight bits in this column then show the
value of the least significant byte of the ROP value required to achieve this
mixing function.  For example, if the required mixing function is to copy the
source to the target, then the Target (final) column will be the same as the S
column, and the ROP value will have the binary value 11001100, or the
hexadecimal value 00CC.

Possible Settings for the Index Bits

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPatternΓöéSource ΓöéTarget (initial)Γöé              ΓöéTarget (final)  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0      Γöé0      Γöé0               Γöé              ΓöéIndex bit 0     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0      Γöé0      Γöé1               Γöé              ΓöéIndex bit 1     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0      Γöé1      Γöé0               Γöé              ΓöéIndex bit 2     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0      Γöé1      Γöé1               Γöé              ΓöéIndex bit 3     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      Γöé0      Γöé0               Γöé              ΓöéIndex bit 4     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      Γöé0      Γöé1               Γöé              ΓöéIndex bit 5     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      Γöé1      Γöé0               Γöé              ΓöéIndex bit 6     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      Γöé1      Γöé1               Γöé              ΓöéIndex bit 7     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

If you want the pattern to have no effect on the target rectangle, the four
low-order bits of the index must be the same as the four high-order bits.

A monochrome bit map consists only of Source settings of 1s and 0s, where a 1
or 0 represents each pel.  It also has a two entry color table with index 0
specifying what color a 0 pel represents and index 1 representing what color a
1 pel represents.  In a monochrome bit map, this color table is not used during
BitBlt operations (but is used when drawing to the bit map and moving the bit
map between devices). The preceding table defines how any combination of
pattern, source and target original (1 and 0) values define the target final (1
or 0) value.  A color bit map has an index (in the case of 4 bits, 0-15) for
each pel which, serves as index into the bit map color table (16 entries for 4
bits per pel) to define the color of each pel. Unlike monochrome bit maps, this
table is used during BitBlt operations (instead of target image bundle
attributes) to provide the color of the target output.

The following table represents a selection of the most commonly used mixes with
predefined symbolic names (but there are many other possible mixes).

Mix Value Names

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéMix Name          ΓöéEffect                                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_SRCCOPY       ΓöéSource                                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_SRCPAINT      ΓöéSource OR Target                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_SRCAND        ΓöéSource AND Target                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_SRCINVERT     ΓöéSource XOR Target                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_SRCERASE      ΓöéSource AND NOT (Target)                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_NOTSRCCOPY    ΓöéNOT (Source)                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_NOTSRCERASE   ΓöéNOT (Source) AND NOT (Target)             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_MERGECOPY     ΓöéSource AND Pattern                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_MERGEPAINT    ΓöéNOT (Source) OR Target                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_PATCOPY       ΓöéPattern                                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_PATPAINT      ΓöéNOT (Source) OR Pattern OR Target         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_PATINVERT     ΓöéTarget XOR Pattern                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_DSTINVERT     ΓöéNOT (Target)                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_ZERO          Γöé0                                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_ONE           Γöé1                                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéROP_GRAY          ΓöéGray pattern background                   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

ROP_SRCCOPY is the most often used value.  It simply copies the bit map to the
target presentation space without performing any color mixing. Because most of
the remaining mixes involve some degree of color mixing, they result in an
image that is quite different from the original.


ΓòÉΓòÉΓòÉ 8.1.2.8. Converting between Monochrome and Color Data Bit Maps ΓòÉΓòÉΓòÉ

It is possible to copy a monochrome bit map to a color bit map or device, and
to copy a color bit map to a monochrome bit map or device.  PM handles these
conversions automatically according to the following rules:

o If you are copying a monochrome bit map to a color bit map or to a color or
  monochrome device surface, a Source setting of 1 adopts the current
  image-foreground color of the target presentation space, and a Source setting
  of 0 adopts the current image-background color of the target presentation
  space.  For example, if the image foreground color is blue and the image
  background color is yellow in the target presentation space, a monochrome bit
  map is converted to a blue foreground on a yellow background.

o If you are copying from a monochrome pattern to a color bit map or device, a
  Source setting of 1 adopts the current area-foreground color of the target
  device and a Source setting of 0 adopts the current area-background color of
  the target device.  Note that if image bundle attributes do not exist for the
  source bit map, as is the case when using GpiWCBitBlt (which uses a bit map
  handle as the source), then zero source pixels adopt the image background
  color and nonzero source pixels adopt the image-foreground color of the
  presentation space.

o If you are copying a color bit map to a monochrome bit map or device, those
  pels that have the same color as the current image-background color in the
  source presentation space adopt the image background color of the target
  presentation space. For example, if the current image-background color in the
  source presentation space is blue, all blue pels in the bit map take on the
  color of the current image background in the target presentation space.

  All other pels in the color bit map adopt the current image-foreground color
  of the target presentation space.


ΓòÉΓòÉΓòÉ 8.1.2.9. Manipulating Single Pels ΓòÉΓòÉΓòÉ

You can manipulate single pels in a bit map by using the GpiSetPel and
GpiQueryPel functions. GpiSetPel sets the pel at the specified point (in world
coordinates) to the current line color.  This function is independent of the
current drawing mode, and its effect is immediate.  It is, however, a
device-dependent function.  The CAPS_RASTER_CAPS option of the DevQueryCaps
function indicates if GpiSetPel is supported on the current device.


ΓòÉΓòÉΓòÉ 8.1.2.10. Copying Images from a Display into a Bit Map ΓòÉΓòÉΓòÉ

An application can copy an image from a raster display screen to a bit map by
calling GpiBitBlt or GpiWCBitBlt.  Before copying the bit map, the application
must call DevOpenDC to create a memory device context.  This device context
allows an application to treat a bit map in memory as though it were a
device-the application can copy color information from pels on the display to
the bit map.

Once an application creates a memory device context, associates it with a
presentation space, and selects a bit map into the presentation space, the
application can use the presentation-space handle as the first argument to
GpiBitBlt or GpiWCBitBlt.  If the application will be drawing the image on
devices with different aspect ratios, the application should use GpiWCBitBlt to
preserve the original dimensions of the bit map.


ΓòÉΓòÉΓòÉ 8.1.2.11. Saving a Bit Map ΓòÉΓòÉΓòÉ

You have two ways to save a bit map that has been created by an application:

o Store the bit map in a metafile, by calling GpiWCBitBlt.

  Metafiles are covered in detail later.

o Use the OS/2 operating system file-handling functions, in conjunction with
  GpiQueryBitmapBits and GpiSetBitmapBits.

  An application can save a bit map in a file by calling GpiQueryBitmapBits,
  DosOpen, DosWrite, and DosClose.

GpiQueryBitmapBits copies bit-map data from a memory device context (that has a
standard-format bit map selected into it) to a buffer. The bit map you copy can
be newly created or have been loaded from a resource file.

You must supply the address in application storage of a bit-map information
table. The bit-map information table has the same structure as the bit map
information header, except for an additional entry, the colors field. As input
to GpiQueryBitmapBits, you supply a bit-count value and a plane value.  These
must both be standard bit-map format values, so the plane value is always 1,
and the bit-count value is 1, 4, 8, or 24. If any conversion of the bit-map
data is necessary, it is done automatically.  You also must provide the address
of the application storage into which the bit-map data is to be loaded.  You
probably will need to find out how large the bit map is before you can do this.
The GpiQueryBitmapParameters function returns the width, height, plane count,
and bit count of a named bit map.

You also must supply the size of the fixed portion of the header (as well as
bit count, and so on).  Nonstandard formats supported by the device that owns
the bit map will also be valid for GpiQueryBitmapBits.

You must ensure that you allocate sufficient storage at the end of the bit map
information table for the returned color table which, if the number of planes
is 1, will have 2n entries, where n is the number of bits per pel.

On return from GpiQueryBitmapBits, the system supplies the width, height, and
bit-map color table in the bit-map information table. You can retrieve a part
of a bit map by specifying the number of the scan line from which the transfer
is to start, and the number of scan lines you want.

When you have copied a bit map into application storage, you can save the bit
map externally, and reload it later, by using OS/2 file-handling functions.
After the application creates a file by calling DosOpen, it can call DosWrite
to copy the buffer containing the bit-map bits into the file.  The application
then closes the file by calling DosClose.

If an application needs to use a bit map it has stored on disk, it can copy the
file's contents into a buffer by calling DosRead, and then copy information
about the image to the bit map by calling GpiSetBitmapBits.  The application
must select the bit map into a memory device context before it sets the bits.
As with GpiQueryBitmapBits, you can transfer a part of the bit map rather than
the whole.  GpiSetBitmapBits can be used to transfer standard-format bit maps
only, and only to a bit map selected into a memory device context. If
necessary, bit-map data is automatically converted from one standard format to
another. Nonstandard formats supported by the device owning the bit map will
also be valid for GpiSetBitmapBits.

If an application creates bit maps another application might use, it should
create them by using the standard OS/2 operating system bit-map file format.


ΓòÉΓòÉΓòÉ 8.1.2.12. Deleting a Bit Map ΓòÉΓòÉΓòÉ

It is good practice always to delete a bit map from memory when you have
finished using it.  To delete a bit map, use GpiDeleteBitmap. If you have
loaded a bit map from a resource file, GpiDeleteBitmap deletes only its memory
version.  If the bit map has not been deleted when the owning process ends, it
is deleted automatically by the system.


ΓòÉΓòÉΓòÉ 8.1.2.13. Making Bit Maps Available to Other Processes ΓòÉΓòÉΓòÉ

When an application creates a bit map or loads one from a resource file, it can
make the bit map available to other processes by placing the bit-map handle in
the clipboard.


ΓòÉΓòÉΓòÉ 8.2. Using Bit Maps ΓòÉΓòÉΓòÉ

An application can use bit-map functions to:

o Copy an image from a raster device (such as a display screen) to a bit map
o Copy an image from a raster device (such as a display screen) to the same
  device
o Copy an image from a bit map to a raster device
o Copy an image from a bit map to another bit map
o Copy an image from application memory to a bit map
o Copy an image from application memory to a raster device
o Scale bit-map images
o Create custom fill patterns for area primitives and paths
o Load a bit map created with the Icon Editor
o Draw bit-map images
o Store bit maps in a metafile or application memory.


ΓòÉΓòÉΓòÉ 8.2.1. Copying an Image from a Display Screen to a Bit Map ΓòÉΓòÉΓòÉ

To copy an image from a display screen to a bit map:

 1. Associate the memory device context with a presentation space.

 2. Create a bit map.

 3. Select the bit map into the memory device context by calling GpiSetBitmap.

 4. Determine the location (in device coordinates) of the image.

 5. Call GpiBitBlt and copy the image to the bit map.

The following figure demonstrates these steps.


    HDC hdcMem;
    PSZ pszData[4] = { "Display", NULL, NULL, NULL };
    HPS hpsMem, hps;
    HAB hab;
    SIZEL sizlPage = {0, 0};
    BITMAPINFOHEADER2 bmp;
    PBITMAPINFO2 pbmi;
    HBITMAP hbm;
    SHORT sWidth = 128, sHeight = 128;
    POINTL aptl[3];
    LONG alData[2];

    /*
     * Create the memory device context and presentation space so they
     * are compatible with the screen device context and presentation space.
     */

    hdcMem = DevOpenDC(hab, OD_MEMORY, "*", 4,
        (PDEVOPENDATA) pszData, NULLHANDLE);

    hpsMem = GpiCreatePS(hab, hdcMem, &sizlPage,
        PU_PELS | GPIA_ASSOC | GPIT_MICRO);

    /* Determine the device's plane/bit-count format. */

    GpiQueryDeviceBitmapFormats(hpsMem, 2, alData);

    /*
     * Load the BITMAPINFOHEADER2 and BITMAPINFO2 structures. The sWidth and
     * sHeight fields specify the width and height of the destination
     * rectangle.
     */

    bmp.cbFix = (ULONG) sizeof(BITMAPINFOHEADER2);
    bmp.cx = sWidth;
    bmp.cy = sHeight;
    bmp.cPlanes = alData[0];
    bmp.cBitCount = alData[1];
    bmp.ulCompression = BCA_UNCOMP;
    bmp.cbImage = (((sWidth *
        (1 << bmp.cPlanes) * (1 << bmp.cBitCount)) + 31) / 32) * sHeight;
    bmp.cxResolution = 70;
    bmp.cyResolution = 70;
    bmp.cclrUsed = 2;
    bmp.cclrImportant = 0;
    bmp.usUnits = BRU_METRIC;
    bmp.usReserved = 0;
    bmp.usRecording = BRA_BOTTOMUP;
    bmp.usRendering = BRH_NOTHALFTONED;
    bmp.cSize1 = 0;
    bmp.cSize2 = 0;
    bmp.ulColorEncoding = BCE_RGB;
    bmp.ulIdentifier = 0;


    DosAllocMem((PPVOID)&pbmi, sizeof(BITMAPINFO2) +
        (sizeof(RGB2) * (1 << bmp.cPlanes) * (1 << bmp.cBitCount)),
        PAG_COMMIT | PAG_READ | PAG_WRITE);

    pbmi->cbFix = bmp.cbFix;
    pbmi->cx = bmp.cx;
    pbmi->cy = bmp.cy;
    pbmi->cPlanes = bmp.cPlanes;
    pbmi->cBitCount = bmp.cBitCount;
    pbmi->ulCompression = BCA_UNCOMP;
    pbmi->cbImage = ((sWidth+31)/32) * sHeight;
    pbmi->cxResolution = 70;
    pbmi->cyResolution = 70;
    pbmi->cclrUsed = 2;
    pbmi->cclrImportant = 0;
    pbmi->usUnits = BRU_METRIC;
    pbmi->usReserved = 0;
    pbmi->usRecording = BRA_BOTTOMUP;
    pbmi->usRendering = BRH_NOTHALFTONED;
    pbmi->cSize1 = 0;
    pbmi->cSize2 = 0;
    pbmi->ulColorEncoding = BCE_RGB;
    pbmi->ulIdentifier = 0;

    /* Create a bit map that is compatible with the display.            */

    hbm = GpiCreateBitmap(hpsMem, &bmp, FALSE, NULL, pbmi);

    /* Associate the bit map and the memory presentation space.         */

    GpiSetBitmap(hpsMem, hbm);

    /* Copy the screen to the bit map.                                  */

    aptl[0].x = 0;       /* Lower-left corner of destination rectangle  */
    aptl[0].y = 0;       /* Lower-left corner of destination rectangle  */
    aptl[1].x = sWidth;  /* Upper-right corner of destination rectangle */
    aptl[1].y = sHeight; /* Upper-right corner of destination rectangle */
    aptl[2].x = 0;       /* Lower-left corner of source rectangle       */
    aptl[2].y = 0;       /* Lower-left corner of source rectangle       */

    hps = WinGetScreenPS(HWND_DESKTOP);

    GpiBitBlt(hpsMem, hps,
        sizeof(aptl) / sizeof(POINTL), /* Number of points in aptl      */
        aptl, ROP_SRCCOPY, BBO_IGNORE);

    WinReleasePS(hps);


Copying a Display-Screen Image to a Bit Map


ΓòÉΓòÉΓòÉ 8.2.2. Scaling and Drawing a Bit-Map Image ΓòÉΓòÉΓòÉ

You can scale a bit map by calling GpiBitBlt or GpiWCBitBlt and altering the
dimensions of the target rectangle. The following figure shows how to shrink
the screen copied in the first example to half its original size, and then
redraw it by calling GpiBitBlt.

    POINTL aptl[3];
    HPS hpsMem, hps;
    HWND hwnd;
    SHORT sWidth = 128, sHeight = 128;
    /* Target-rectangle dimensions (in device coordinates)              */
    aptl[0].x = 0;
    aptl[0].y = 0;
    aptl[1].x = sWidth / 2;
    aptl[1].y = sHeight / 2;

    /* Source-rectangle dimensions (in device coordinates)              */
    aptl[2].x = 0;
    aptl[2].y = 0;
    aptl[3].x = sWidth;
    aptl[3].y = sHeight;

    hps = WinGetPS(hwnd);

    GpiBitBlt(hps, hpsMem,
        sizeof(aptl) / sizeof(POINTL),      /* Number of points in aptl */
        aptl, ROP_SRCCOPY, BBO_IGNORE);

    WinReleasePS(hps);

Scaling and Drawing a Bit-Map Image


ΓòÉΓòÉΓòÉ 8.2.3. Creating a Custom Fill Pattern ΓòÉΓòÉΓòÉ

To create a custom fill pattern that the operating system will use to fill area
primitives and paths:

 1. Set an array of bits for a bit map that measures 8-bits-by-8-bits (remember
    that the operating system pads the bit-map bits on a ULONG (32-bit)
    boundary).

 2. Create a bit map in a screen presentation space by calling GpiCreateBitmap
    and passing it the address of the array of bits from Step 1.

 3. Assign a local identifier (lcid) to the bit map by calling GpiSetBitmapId.

 4. Set the attribute of the pattern set in the AREABUNDLE structure by calling
    GpiSetPattern.

The following figure shows how to create the pattern.

    /* Define an array of bytes;  this array creates a grid pattern. */

    BYTE abPattern5[] = {
        0xFF, 0xFF, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00,
        0x80, 0x00, 0x00, 0x00 };

        LONG lcidCustom = 1;
    HPS hps;
    PBITMAPINFO2 pbmi;
    BITMAPINFOHEADER2 bmp;
    HBITMAP hbm;
    PRGB2 prgb2;

    /* Create the bit map, passing the address of the array of bytes. */
    hbm = GpiCreateBitmap(hps, &bmp, CBM_INIT, (PBYTE) abPattern5, pbmi);

    /* Assign a local identifier to the bit map.                      */
    GpiSetBitmapId(hps, hbm, lcidCustom);

    /* Set the pattern-set attribute in the AREABUNDLE structure.     */
    GpiSetPatternSet(hps, lcidCustom);


Creating a Custom Fill Pattern


ΓòÉΓòÉΓòÉ 8.2.4. Loading a Bit Map from a File ΓòÉΓòÉΓòÉ

You can load a bit map from a file if the format of the file corresponds to the
standard OS/2 operating system bit-map file format. (Any bit map that you
create with the Icon Editor is automatically stored in this format.)  To load a
bit map:

 1. Copy the bit-map file to the directory that contains your application's
    resource file and source code.

 2. Create an entry in your application's resource file, assigning a unique
    integer identifier to the bit map.

 3. Call GpiLoadBitmap in your application's source code, passing it the
    integer identifier that you assigned to the bit map in your application's
    resource file.

You can actually include your bit map in the application's .EXE file or in a
separate resource file.  If the bit map is included in a separate resource
file, you must specify both the resource ID and the ID of the bit map within
the resource file on GpiLoadBitmap.  If bit map is to be included in the
application's .EXE file, the resource ID is specified as NULL and only the ID
of the bit map is required by GpiLoadBitmap.

Following is an example of code from an application's resource file that
assigns the integer value, 200, to a bit-map file called CUSTOM.BMP.

    BITMAP  200 CUSTOM.BMP

The following figure is an example of code from the application that shows how
to retrieve a bit-map handle by calling GpiLoadBitmap, use the handle to tag
the bit map by calling GpiSetBitmapId, and then use the local identifier
supplied by GpiSetBitmapId to set the bit map as the current fill pattern,
using GpiSetPatternSet.

    HPS hps;
    HBITMAP hbm;
    LONG lcidCustom = 1;
    POINTL ptl;

    hbm = GpiLoadBitmap(hps,  /* Presentation-space handle        */
        NULLHANDLE,           /* Resource in application's module */
        IDB_PATTERN,          /* Bit-map ID                       */
        16,                   /* Bit-map width                    */
        16);                  /* Bit-map height                   */

    /* Assign a local identifier to the bit map.                  */
    GpiSetBitmapId(hps, hbm, lcidCustom);

    /* Set the pattern-set attribute in the AREABUNDLE structure. */
    GpiSetPatternSet(hps, lcidCustom);

    ptl.x = 100;
    ptl.y = 100;
    GpiMove(hps, &ptl);
    ptl.x = 200;
    ptl.y = 200;
    GpiBox(hps, DRO_OUTLINEFILL, &ptl, 0, 0);

Loading a Bit Map from a File


ΓòÉΓòÉΓòÉ 8.2.5. Storing a Bit Map in a Metafile ΓòÉΓòÉΓòÉ

You can draw bit maps in a metafile or segment by calling GpiWCBitBlt. The
operating system converts this function to a drawing order.  The
target-rectangle dimensions that you pass to GpiWCBitBlt are in world
coordinates, not device coordinates. The following figure shows how to draw a
bit map in a metafile, and then play the metafile.

    DEVOPENSTRUC dop;
    HDC hdcMeta;
    HPS hps, hpsMeta;
    SIZEL sizlPage;
    HMF hmf;
    HBITMAP hbm;
    HAB hab;
    HWND hwnd;
    POINTL aptl[4];

    dop.pszLogAddress = NULL;
    dop.pszDriverName = "DISPLAY";
    dop.pdriv = NULL;
    dop.pszDataType = NULL;

    hdcMeta = DevOpenDC(hab, OD_METAFILE, "*", 4L,
                  (PDEVOPENDATA) &dop, NULLHANDLE);
    hpsMeta = GpiCreatePS(hab, hdcMeta, &sizlPage, PU_PELS | GPIA_ASSOC);

    hbm = GpiLoadBitmap(hpsMeta, NULLHANDLE, IDB_PATTERN, 16L, 16L);

    aptl[0].x = aptl[0].y = 0;  /* Lower-left corner target rectangle        */
    aptl[1].x = 150;            /* X coordinate upper-right target rectangle */
    aptl[1].y = 300;            /* Y coordinate upper-right target rectangle */
    aptl[2].x = aptl[2].y = 0;  /* Lower-left corner source rectangle        */
    aptl[3].x = aptl[3].y = 16; /* Upper-right corner source rectangle       */

    GpiWCBitBlt(hpsMeta, hbm, 4L, aptl, ROP_SRCCOPY, BBO_IGNORE);

    GpiAssociate(hpsMeta, NULLHANDLE);
    hmf = DevCloseDC(hdcMeta);

    hps = WinGetPS(hwnd);

    GpiPlayMetaFile(hps, hmf, 0L, NULL, NULL, 0L, NULL);

    WinReleasePS(hps);

Storing a Bit Map in a Metafile

You can also store a bit map in a metafile by calling GpiBitBlt.  In this case,
however, the bit map will be stored inside an escape order.


ΓòÉΓòÉΓòÉ 8.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes bit-map object functions.

Bit-Map Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name               ΓöéDescription                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateBitmap             ΓöéCreates a bit map that is       Γöé
Γöé                            Γöécompatible with a device        Γöé
Γöé                            Γöéassociated with a presentation  Γöé
Γöé                            Γöéspace.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawBits                 ΓöéCopies bit-map image data from  Γöé
Γöé                            Γöéstorage to a bit map that has   Γöé
Γöé                            Γöébeen selected into a device     Γöé
Γöé                            Γöécontext.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiImage                    ΓöéDraws an image primitive.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLoadBitmap               ΓöéLoads a bit map from a resource Γöé
Γöé                            Γöéfile or application EXE file.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapBits          ΓöéTransfers data from a bit map toΓöé
Γöé                            Γöéapplication storage.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapDimension     ΓöéDetermines the width and height Γöé
Γöé                            Γöéof a bit map, in units of 0.1   Γöé
Γöé                            Γöémm.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapHandle        ΓöéDetermines the handle of a bit  Γöé
Γöé                            Γöémap with a specific local ID.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapInfoHeader    ΓöéDetermines information about a  Γöé
Γöé                            Γöéparticular bit map, then        Γöé
Γöé                            Γöétransfers the information to theΓöé
Γöé                            ΓöéBITMAPINFOHEADER structure.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBitmapParameters    ΓöéDetermines information about a  Γöé
Γöé                            Γöéparticular bit map, then        Γöé
Γöé                            Γöétransfers the information to theΓöé
Γöé                            ΓöéBITMAPINFOHEADER structure. Use Γöé
Γöé                            ΓöéGpiQueryBitmapInfoHeader        Γöé
Γöé                            Γöéwhenever possible.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDeviceBitmapFormats ΓöéDetermines the device bit map   Γöé
Γöé                            Γöéformats (number of planes and   Γöé
Γöé                            Γöénumber of bits per pel)         Γöé
Γöé                            Γöésupported by the device, with   Γöé
Γöé                            Γöéthe format that most closely    Γöé
Γöé                            Γöématches the device returned     Γöé
Γöé                            Γöéfirst.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPel                 ΓöéDetermines the color index or   Γöé
Γöé                            ΓöéRGB value for a specific pel,   Γöé
Γöé                            Γöéwhose location is specified in  Γöé
Γöé                            Γöéworld coordinates.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmap                ΓöéSelects a bit map into a memory Γöé
Γöé                            Γöédevice context.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmapBits            ΓöéTransfers standard-format bit   Γöé
Γöé                            Γöémaps from a buffer into a bit   Γöé
Γöé                            Γöémap, associated with a memory   Γöé
Γöé                            Γöédevice context.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmapDimension       ΓöéDefines the height and width of Γöé
Γöé                            Γöéa bit map, in units of 0.1 mm.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetBitmapID              ΓöéAssigns a local identifier to a Γöé
Γöé                            Γöébit map.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPel                   ΓöéDraws a pel using the current   Γöé
Γöé                            Γöéline bundle color and mix       Γöé
Γöé                            Γöéattributes at a specified       Γöé
Γöé                            Γöéposition in world coordinates.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWinDrawBitmap               ΓöéDraws a bit map in a display    Γöé
Γöé                            Γöéwindow.                         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the bit-map object
functions.

Bit-Map Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name    ΓöéDescription                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBITMAPINFO2       ΓöéContains 20 fields that specify the       Γöé
Γöé                  Γöéattributes of the bit map, such as the    Γöé
Γöé                  Γöébit-map width, height, number of color    Γöé
Γöé                  Γöéplanes, bit count, RGB array structure,   Γöé
Γöé                  Γöéinformation header size, and so on.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBITMAPINFOHEADER2 ΓöéContains 19 fields that specify the       Γöé
Γöé                  Γöébit-map header information, such as the   Γöé
Γöé                  Γöébit map width, height, number of color    Γöé
Γöé                  Γöéplanes, bit count, information header     Γöé
Γöé                  Γöésize, and so on.                          Γöé
Γöé                  ΓöéThis record contains the same fields as   Γöé
Γöé                  ΓöéBITMAPINFO2, with the exception of the    Γöé
Γöé                  Γöélast field, argbColorY1.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRGB2              ΓöéA 4-byte structure containing 1 byte blue,Γöé
Γöé                  Γöégreen, and red color component values.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 9. Fonts ΓòÉΓòÉΓòÉ

In typography, a font is a collection of characters that share a common height,
line weight, and appearance. In presentation manager, fonts are an lcid
identified resource, like bit maps, and are used in conjunction with the
character string primitive data structures to define the appearance of
displayed and printed text. The primary role of the PM programming interface
with regard to fonts is to evaluate whether a particular font is appropriate
for a given situation.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Character string primitives
o Coordinate spaces
o Transformations
o Color and mix attributes.


ΓòÉΓòÉΓòÉ 9.1. About Fonts ΓòÉΓòÉΓòÉ

Font height is specified in printer's points, referred to in this volume as
just points. A point equals approximately 1/72 of an inch. The line weight and
appearance of a font are specified by the categories listed in the following
table.

Examples of Line Weight and Font Appearance Categories

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute   ΓöéCategory    ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLine Weight ΓöéNormal      ΓöéCharacters drawn with a normal line Γöé
Γöé            Γöé            Γöéweight.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé            ΓöéBold        ΓöéCharacters drawn with a heavier lineΓöé
Γöé            Γöé            Γöéweight.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAppearance  ΓöéCondensed   ΓöéCharacters drawn with half the      Γöé
Γöé            Γöé            Γöéaverage character width.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé            ΓöéExpanded    ΓöéCharacters drawn with twice the     Γöé
Γöé            Γöé            Γöéaverage character width.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé            ΓöéItalic      ΓöéCharacters drawn with a normal line Γöé
Γöé            Γöé            Γöéweight and sloped to the right.     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

A font family is a collection of fonts that share common design characteristics
such as stroke width and serif.  Stroke width refers to the width of lines used
to draw the characters and symbols of a font. A serif is a short cross-line
drawn at the ends of the main strokes forming a character or symbol.

Text output is drawn with the characters and symbols of a font. The operating
system stores fonts either in memory or on devices. Applications can access
fonts through a device context associated with the current presentation space.
When an application creates a presentation space, using GpiCreatePS or
WinGetPS, the operating system assigns the presentation space a default font
from one of the available fonts. An application can retrieve information about
the default font using GpiQueryFontMetrics.


ΓòÉΓòÉΓòÉ 9.1.1. Image Font and Outline Font Implementation ΓòÉΓòÉΓòÉ

The operating system can define and implement the characters of a font as
either images or outlines.

Each of the characters in an image font (sometimes called a raster font) is
created by alternating the ON and OFF settings of pels to produce the image.
The image characters are stored as a bit map; sometimes image fonts are even
referred to as bit-map fonts.

The characters in an image font must be drawn in a fixed size-you cannot rotate
or scale them, for example-but usually they are of good quality; they are
displayed faster than outline characters; and frequently, they look better at
low resolutions.

The characters in an outline font, on the other hand, are drawn using a
sequence of lines and arcs; then the characters are filled if so requested. The
outline characters are stored as a collection of line, fillet, and spline
functions. Outline fonts are transformable because the outline characters can
be scaled, rotated, and sheared. Outline fonts can be implemented as vectors,
drawn by a series of small, straight lines; if that is the case, they can be
referred to correctly as vector fonts.  Vector fonts can be drawn much faster
than fonts requiring the inclusion of actual curves and arcs.

A major advantage of outline fonts is their device independence; unlike image
fonts, whose appearance depends on the device's pel definition.

The following figure is an example of a character in both an image font and an
outline font.

Image and Outline Characters

The image character is produced by manipulating pels. The outline character is
produced by drawing a sequence of lines and arcs.  (The resultant shape of an
outline character can be filled if desired.)

Note:  Most of the functions and data structures described in this chapter
       relate only to outline fonts.


ΓòÉΓòÉΓòÉ 9.1.2. PM-Supplied Fonts ΓòÉΓòÉΓòÉ

The PM programming interface provides a number of both image and outline
typographic-quality character fonts. On some devices, image fonts in small font
sizes have a better appearance than their outline-font equivalents.

Type size is measured in points. There are approximately 72 points to an inch,
so each character in a 24-point font, for example, is 1/3-inch high. Each
incremental unit of a presentation page in PU_TWIPS format is 1/20 of a
printer's point (1/1440 inch).

The following image fonts are available on all OS/2-supported display adapters:

Available Image Fonts

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFont Family Name        ΓöéPoint Sizes Available               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTms Rmn                 Γöé8, 10, 12, 14, 18, 24               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHelv                    Γöé8, 10, 12, 14, 18, 24               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCourier (monospace)     Γöé8, 10, 12                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSystem Monospace        Γöé10                                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

In addition, a default system font is used in window components such as title
bars and menus; it is a proportionally spaced Swiss font.

The outline fonts provided by the PM programming interface are Adobe** Type 1.
The appearance and performance characteristics of these fonts are more flexible
than for image fonts.

The following table lists the outline fonts available with the operating system
and their equivalent fonts from earlier versions of OS/2.

Available Outline Fonts

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOutline Font      ΓöéOS/2 2.0 Fonts Available    ΓöéEquivalent    Γöé
ΓöéFamily Name       Γöé                            ΓöéName          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTimes New Roman** ΓöéTimes New Roman             ΓöéTms Rmn       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéTimes New Roman Bold        ΓöéTms Rmn Bold  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéTimes New Roman Bold Italic ΓöéTms Rmn Bold  Γöé
Γöé                  Γöé                            ΓöéItalic        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéTimes New Roman Italic      ΓöéTms Rmn ItalicΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHelvetica**       ΓöéHelvetica                   ΓöéHelv          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéHelvetica Bold              ΓöéHelv Bold     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéHelvetica Bold Italic       ΓöéHelv Bold     Γöé
Γöé                  Γöé                            ΓöéItalic        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéHelvetica Italic.           ΓöéHelv Italic   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCourier           ΓöéCourier                     ΓöéCourier       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéCourier Bold                ΓöéCourier Bold  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéCourier Bold Italic         ΓöéCourier Bold  Γöé
Γöé                  Γöé                            ΓöéItalic        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                  ΓöéCourier Italic              ΓöéCourier ItalicΓöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSymbol            ΓöéSymbol                      ΓöéNone          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéThe outline font names provided with earlier versions of OS/2 Γöé
Γöéare still supported, but the corresponding new fonts are      Γöé
Γöéobtained when the previous font names are selected.           Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 9.1.3. Availability of Additional Fonts ΓòÉΓòÉΓòÉ

Over 600 Adobe Type 1 fonts are available from font vendors, and user systems
could have a large number of these installed. Applications must be capable of
functioning properly with whatever font the user selects.

An application can examine the font metrics to see what a font looks like or
display different font characters from which the user can choose.  When dealing
with an interactive or user-driven application, the recommended method of
choosing a font is to call WinFontDlg, which displays an example of the font in
a dialog box.

Additional Adobe Type 1 fonts can be used just like other outline fonts.
Notice, however, that some of those fonts are more stylized, that is, the fonts
have a greater variation in the widths of different characters within the same
font, which is provided by kerning. Kerning is described and illustrated in
Kerning.

Adobe Type 1 fonts, provided with and for a particular application, can be
loaded with GpiLoadFonts, provided that the following rules are observed:

o The .AFM file of the font must be specified as the font file.
o The .PFB file must be in the same directory as the .AFM file.


ΓòÉΓòÉΓòÉ 9.1.4. Font Data Structures and Attributes ΓòÉΓòÉΓòÉ

The attributes of fonts are contained in the FONTMETRICS data structure. The
appearance of the actual text is influenced also by the attributes of the
individual characters, which can be found in the CHARBUNDLE data structure. The
character string primitives are described in Character String Primitives.

An application can determine whether to use a particular font by examining its
font metrics, which are the measurements that define the features of that font.
The measurements are decided on by a font designer, whose most important
criteria might be ensuring that the font is pleasing to the eye.

Unlike the attributes of a character string primitive, the individual font
metrics attributes cannot be changed using specific GPI functions. Your
application can determine the values of the current logical font attributes by
calling GpiQueryFontMetrics, which accepts as input the amount of data to be
returned as well as a pointer to the data area. Unlike other GPI calls,
GpiQueryFontMetrics does not return the size necessary for all font metrics
data. Querying with a sizeof operator, instead of calling the query twice,
returns the size data.

The following table and text defines and explains the uses of the various font
metric attributes.

Font Metric Attributes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute                     ΓöéDescription                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFace name                     ΓöéThe full typeface name of a   Γöé
Γöé                              Γöéfont, such as Courier Bold    Γöé
Γöé                              ΓöéItalic.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFamily name                   ΓöéA broader equivalent of the   Γöé
Γöé                              Γöéface name (e.g.Courier).      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCode page                     ΓöéThe mapping between a set of  Γöé
Γöé                              Γöécodepoints and a set of       Γöé
Γöé                              Γöégraphic characters.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell                ΓöéControls the height and width Γöé
Γöé                              Γöéof outline font characters.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell ascent         ΓöéDistance between the baseline Γöé
Γöé                              Γöéto the top of the character   Γöé
Γöé                              Γöécell.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter cell descent        ΓöéDistance between the baseline Γöé
Γöé                              Γöéand the bottom of the         Γöé
Γöé                              Γöécharacter cell.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum baseline extent       ΓöéMaximum vertical extent of    Γöé
Γöé                              Γöéfont characters in world      Γöé
Γöé                              Γöécoordinates.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum ascender              ΓöéMaximum distance a font       Γöé
Γöé                              Γöécharacter ascends above the   Γöé
Γöé                              Γöébaseline.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximum descender             ΓöéMaximum distance a font       Γöé
Γöé                              Γöécharter descends below the    Γöé
Γöé                              Γöébaseline.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInternal leading              ΓöéVertical distance equal to theΓöé
Γöé                              Γöédifference between the maximumΓöé
Γöé                              Γöébaseline extent and the em    Γöé
Γöé                              Γöéheight.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEm height                     ΓöéEquivalent to the character   Γöé
Γöé                              Γöécell height.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEm width                      ΓöéEquivalent to the character   Γöé
Γöé                              Γöécell width.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéX height                      ΓöéHeight above the baseline of  Γöé
Γöé                              Γöéany lowercase character.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLowercase ascent              ΓöéMaximum distance of a         Γöé
Γöé                              Γöélowercase character above the Γöé
Γöé                              Γöébaseline.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLowercase descent             ΓöéMaximum distance of a         Γöé
Γöé                              Γöélowercase character below the Γöé
Γöé                              Γöébaseline.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéExternal leading              ΓöéMaximum vertical font spacing Γöé
Γöé                              Γöéthat can be added without     Γöé
Γöé                              Γöéadversely affecting the       Γöé
Γöé                              Γöéappearance of the text.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAverage character width       ΓöéAverage width of font         Γöé
Γöé                              Γöécharacters in world           Γöé
Γöé                              Γöécoordinates                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCharacter slope               ΓöéInitial slope of a character  Γöé
Γöé                              Γöéwith respect to a vertical    Γöé
Γöé                              Γöéline.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInline direction              ΓöéCharacter angle measured with Γöé
Γöé                              Γöérespect to a horizontal line. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWeight class                  ΓöéSpecifies the thickness of    Γöé
Γöé                              Γöéeach stroke of a font         Γöé
Γöé                              Γöécharacter.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFirst, last, default, and     ΓöéSee Glyphs, Code Pages, and   Γöé
Γöébreak characters              ΓöéCode Points.                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The face name attribute is the typeface name by which a particular font design
is known. Two examples are Times New Roman Bold and Times New Roman Italic.
Roman is the family name of these fonts. You always should provide a face name
because most outline fonts are known by it.

The code page to be associated with the font is identified by this metric. Some
fonts are specific to a particular code page and should be used with only that
code page. Other fonts are universal and can be used with any supported code
page.  Code pages are described in Glyphs, Code Pages, and Code Points.

Every character in a font is drawn within a rectangular region called a
character cell. The character-cell height is the distance from the bottom of
the character cell to its top. The width of the character cell is the distance
from one side to the other.

An imaginary horizontal line, called a baseline, is drawn through the lower
portion of the character cell. The operating system uses the baseline to
position characters. All uppercase and most lowercase letters in a given font
rest approximately on the baseline. Some lowercase letters, such as g and y,
descend below the baseline.

The distance from the baseline to the top of the character cell is the
character-cell ascent. Similarly, the character-cell descent is the distance
from the baseline to the bottom of the character cell.

The following figure illustrates characters drawn along a baseline inside their
character cells. Various font metrics also are illustrated.

Some Font Metrics

The maximum baseline extent is the sum of the maximum ascender and the maximum
descender values. The internal leading is the space allowed for diacritics
above capital letters. When an application draws a string of text, the
operating system positions the leftmost point of the baseline over a
predetermined point for each character in the string.

A font's Em height is a measure of its visual height. This measurement was
given its name because, historically, the height of an uppercase letter M
usually was equal to the average height of all uppercase characters in the
font. However, this is no longer the case.

The value of Em height represents the font point size in world coordinates and
is the same as the character cell height. For an outline font, this can be set
by the character cell height attribute. The value of Em Width is the equivalent
horizontal dimension and is the same as the character cell width. For an
outline font this also can be set by the character cell width attribute. These
are, in fact, the dimensions of the em square (a typographic term) and, like
point size, cannot be defined in terms of any measurable characteristic of a
visible character of the font.

The average distance from the baseline to the top of any lowercase character is
called a font's x height. This measurement was given its name because the
height of a lowercase x usually is equal to the average height of all lowercase
characters in the font.

The maximum ascender is the height of the tallest character in a font. The
maximum descender is the depth (below the baseline) of the lowest character in
a font.

The lowercase ascent is the height of the tallest lowercase character in a
font. The lowercase descent is the depth (below the baseline) of the lowest
lowercase character in a font.

Many fonts reserve part of the space in the top of each character cell for
accent marks. This reserved space is called internal leading. Some fonts
require a certain amount of space to be left between rows of text. This space,
called external leading, is not included in the character-cell height or ascent
measurements. The external leading is the recommended space to leave between
rows of text to preserve its pleasing appearance.

The average character width is stored in the lAveCharWidth field in the
FONTMETRICS structure. The average character width is a measure of character
width based on the normal frequency of lowercase letter usage in the English
language. You can use this value to approximate the average width of a
character in string length calculations.

The maximum baseline extent for a font is the sum of the maximum ascender and
the maximum descender. Maximum baseline extent is not equal to cell height for
outline fonts, but is for image fonts.

The character slope is an angle measured clockwise with respect to a typical
vertical line. The slope of a normal font is 0; the slope of an italic font is
other than 0. The character slope in the FONTMETRICS data structure can be
thought of as the initial slope, since the slope can be changed in the
CHARBUNDLE data structure.

The inline direction is an angle measured clockwise with respect to a
horizontal line. The inline direction for a Swiss, Helvetica, or Roman font is
normally 0-exactly horizontal. The inline direction for a Hebrew font is
normally 180, because Hebrew text is oriented right to left.

The character-rotation angle is an angle measured counterclockwise with respect
to a horizontal line. The baselines of characters are aligned with the vector
drawn at the angle of rotation.

The weight class specifies the thickness of each stroke that forms part of each
character in a font.

The first, last, default, and break character all are associated with glyphs
for UGL fonts and code pages and are described in Glyphs, Code Pages, and Code
Points.

A superscript is a character drawn immediately above and to the right of a
normal character in a string of text. Superscripts are identified by a width
and height and by vertical and horizontal offsets.

A subscript is a character drawn immediately below and to the right of a normal
character in a string of text. Subscripts are identified by a width and height
and by vertical and horizontal offsets.

Kerning pairs are described in Kerning.


ΓòÉΓòÉΓòÉ 9.1.5. Glyphs, Code Pages, and Code Points ΓòÉΓòÉΓòÉ

The image or picture that you associate with each character or symbol in a font
is called a glyph. The mapping between a set of glyphs and their code points is
called a code page.

For a single byte character set (SBCS), each code page contains up to 256 code
points. Normally these are 8-bit integers in the range 0 through 255, with 1
code point identifying 1 glyph in that code page. The code pages can be either
ASCII or EBCDIC. Because a code point repeats on a new code page, you need both
the code page and code point to uniquely identify a glyph.

There usually is 1 code page per font; however, double byte character sets
(DBCS) are sometimes used for Asian languages with large character sets. Fonts
are a set of glyph definitions and a default code page mapping. The same set of
font glyph definitions is remapped for different code pages.

Each font contains 4 special glyph points:

o First glyph
o Last glyph
o Default glyph
o Break glyph.

First and last glyph points are of more interest to the font designers than
application programmers because they apply to the set of font glyph definitions
rather than a particular code page. The last character is the maximum code
point of the font that has a glyph associated with it and may be bigger than
256.

The default glyph appears in text when an application specifies a glyph point
that does not exist in the font.

The break glyph usually is the space character and often has the same code
point as the default character.

Actually a font can have more or less than 256 definitions, but any particular
code page may have less than 256 but no more. There may be a translation
between the code point in the code page and the code point (between the first
and last glyphs) that references the glyph in the font.

The operating system assigns unique identifiers to each of its code pages.
Common code pages are 437-the United States code page, and 850-the multilingual
code page. The default code page is 850.

An application can determine the current code page by calling GpiQueryCp, or it
can assign a new code page using GpiSetCp. If you default the code page in the
FATTRS structure when calling GpiCreateLogFont, you get the current code page
as specified by GpiSetCp (or returned by GpiQueryCp). You can specify any one
of the code page identifiers returned to you from the WinQueryCpList function.

When using a font other than the system font, you specify the required code
page in the FATTRS structure of GpiCreateLogFont. You can determine the code
page for that font (if it is the current logical font) by using
GpiQueryFontMetrics. The available code pages are described in the Presentation
Manager Programming Reference.


ΓòÉΓòÉΓòÉ 9.1.6. Proportional and Monospace Fonts ΓòÉΓòÉΓòÉ

When text is drawn, the operating system aligns each character by positioning
its character cell next to that of the previous character.

A monospace font provides the same amount of space for each character, whatever
its shape. These fonts also are called fixed fonts. Courier and System
Monospaced are monospace fonts. Monospace fonts, in fact, are essential for
some purposes, for example program listings, where vertical alignment is
important.

A proportionally-spaced font is one in which some characters are allotted less
space than others, so that each character occupies the proportion of space that
is correct for its shape. For example, a lowercase letter l does not need the
same space as a lowercase letter m. Many graphics fonts supplied by the PM
programming interface, including the system font, support proportional spacing.

The font metrics value maxcharinc specifies the width of the widest character
in the font, and the value avecharwidth specifies an average width of the
characters in the font.

You can retrieve information about the widths of the characters in the current
font by calling GpiQueryWidthTable. You provide the code point of the first
character you are interested in and the number of characters for which you want
width-table information. Refer to the Presentation Manager Programming
Reference for information on how character-width information is computed.


ΓòÉΓòÉΓòÉ 9.1.7. Kerning ΓòÉΓòÉΓòÉ

Kerning, like proportional spacing, is a type of letter spacing. In a kerned
font, some characters are allowed to overhang others and, therefore, occupy an
area that is less than each character's increment for that font. Usually this
feature is restricted to pairs of characters whose appearance might benefit
from greater proximity. The 5 character pairs that most commonly benefit from
kerning are Yo, We, To Tr, and Ta.

Kerning is not available in the system-provided image fonts. The Helvetica and
Times New Roman outline fonts provided with the system do include kerning
information. You can specify kerning as a requirement on the GpiCreateLogFont.
Selecting a kerned font lets a kerning take place whenever it is defined.

The a-space is the area of the character cell before the character; the b-space
is the area of the character cell occupied by the character; and the c-space is
the area of the character cell after the character. The a-space and c-space are
shown in the following figure.

a-Space, b-Space, and c-Space

The best way to implement kerning is to use a kerning-pair table. The kerning
table will exist only for certain pairs of characters for which adjustments are
desirable.

Each of the entries in a kerning-pair table contains the code points of a pair
of kerned characters and an adjustment that should be applied to the character
width of the first character of the pair. A negative value means that the space
is decreased, and a positive value means it is increased, whenever the 2
characters in a kerning pair are produced together. A kerning-pair table might
be provided with a purchased font. If so, it will be recorded in the font
header.

If kerning is specified on a character-pair basis (that is, if the font has a
kerning-pair table), the font has a specific number of kerned pairs.
GpiQueryKerningPairs returns kerning-pair information from the current logical
font. For each pair of kerned characters, you are given the characters
themselves and an adjustment in world coordinates that must be applied to the
character width of the first character of the pair.

When you specify negative a- and c-space values, the values affect any
character paired with the kerned character. Because this form of kerning cannot
be applied selectively, you have to choose the kerned characters carefully. For
example, an italic letter f ( Я ) is a good candidate for this sort of kerning,
because it can overhang most of the characters that precede and follow it.

An application can adjust the amount of space between all characters in a font
with GpiSetCharExtra. Any extra space is added to font kerning values. An
application also can adjust the width of a font's break character (space)  with
GpiSetCharBreakExtra. These functions are described in Character String
Primitives.

Kerning is not available on all devices. On devices that support kerning,
kerning is enabled by default. When kerning is not supported on a device,
kerning support is switched off by default. When kerning support is switched
off, the kerning information supplied with a font is ignored. To determine
whether a device supports kerning, use DevQueryCaps.

The kerning information can be implemented by your application when a character
string primitive is written to an output device; this is called rendering the
text. The functions GpiCharStringPos and GpiCharStringPosAt, both described in
Character String Primitives, permit specification of the starting position for
each character. The entire character string can be searched for character pairs
that also are kerning pairs for the kerning information to be applied.


ΓòÉΓòÉΓòÉ 9.1.8. FATTRS Data Structure ΓòÉΓòÉΓòÉ

The FATTRS structure is used to identify the characteristics of a requested
font. Certain attributes of a font that govern many individual character string
primitives are contained in FATTRS, as follows:

o Record length
o Selection indicators
o Match value
o Face name
o Registry identifier
o Code page
o Maximum baseline extent
o Average character width
o Type indicator
o Font use indicator.


ΓòÉΓòÉΓòÉ 9.1.8.1. Record Length ΓòÉΓòÉΓòÉ

Record length determines the length of the FATTRS structure. An application
normally specifies this with the sizeof operator.


ΓòÉΓòÉΓòÉ 9.1.8.2. Selection Indicators ΓòÉΓòÉΓòÉ

There are 5 selection indicators:

Indicator                   If set ON, selects...

FATTR_SEL_ITALIC            A font with an italic appearance. This is intended
                            for use with an image font and results in a
                            simulation of an italic font.

FATTR_SEL_BOLD              A boldface version of the font. This is intended
                            for use with an image font and results in a
                            simulation of a boldface font.

FATTR_SEL_OUTLINE           Hollow characters when using an outline font. This
                            only can be used with outline fonts.

                            This indicator is less important than the others
                            because improved performance is now available (from
                            Adobe Type Manager) on filled outline fonts than
                            was originally available when this option
                            (FATTR_SEL_OUTLINE) was introduced.

FATTR_SEL_STRIKEOUT         A font in which the characters are struck through.
                            This option also might be selected on the character
                            string primitive.

FATTR_SEL_UNDERSCORE        A font in which the characters are underscored.
                            This option also might be selected on the character
                            string primitive.

Any combination of these indicators can be set. When set, they cause a
simulation of the selected feature. For example, if you require a bold,
italicized version of a PM image font, PM simulates that feature because bold,
italic image fonts are not supplied.


ΓòÉΓòÉΓòÉ 9.1.8.3. Match Value ΓòÉΓòÉΓòÉ

The match value is a number that identifies a physical font; it is allocated to
the font when the font is loaded. If the match value is less than 0, the font
is a device font; and, if the match value is greater than 0, the font is a
generic font.

A device font is exclusive to the device with which it is associated, and its
match number is guaranteed to be unique only within the device driver. If an
application prints on a different printer, the application cannot guarantee
that the font will be identical just by specifying the match value. A generic
font is available on more than one device. The PM-supplied fonts, for example,
are generic fonts. Printer fonts always are device fonts, but you also can and
should use generic fonts with printers.

You can choose whether or not to use the match value to specify the font when
calling GpiCreateLogFont. Specifying the match value is easier but less
flexible than the alternative, which is to specify the font name and outline
characteristics. For an image font, the alternative is to specify the maximum
baseline extent and average character width of the required font.


ΓòÉΓòÉΓòÉ 9.1.8.4. Face Name ΓòÉΓòÉΓòÉ

The face name value in the FATTRS data structure is identical to the face name
of the FONTMETRICS data structure when describing a specific font.


ΓòÉΓòÉΓòÉ 9.1.8.5. Registry Identifier ΓòÉΓòÉΓòÉ

The registry identifier is a unique number by which the font is registered with
IBM. The registry identifier of a particular font can be retrieved by calling
GpiQueryFonts. If you do not have a registry number, set this value to 0.


ΓòÉΓòÉΓòÉ 9.1.8.6. Code Page ΓòÉΓòÉΓòÉ

The code page is the identifier of the code page to be associated with the
font. You can default the code page in GpiCreateLogFont by specifying 0. Like
the face name, the code page in the FATTRS data structure is identical to the
code page in the FONTMETRICS data structure when describing a specific font.


ΓòÉΓòÉΓòÉ 9.1.8.7. Maximum Baseline Extent ΓòÉΓòÉΓòÉ

The maximum baseline extent is the vertical space occupied by characters in the
font. If you are setting the font-use indicator FATTR_FONTUSE_OUTLINE,
described on page Font-Use Indicators, you should set the maximum baseline
extent to 0. Outline fonts take an equivalent value from the character cell
attribute that is current when text is written to an output device.

The maximum baseline extent value is required to select an image font and must
be specified in world coordinates. For image fonts, this is the vertical height
in world coordinates of character images in the font. This field must be
specified when requesting an image font with GpiCreateLogFont.

The maximum baseline extent measurement is shown in a previous figure. The
maximum baseline extent in the FATTRS data structure is used for programming,
unlike the maximum baseline extent in the FONTMETRICS data structure, which is
only measurement as recommended by the font's designer.


ΓòÉΓòÉΓòÉ 9.1.8.8. Average Character Width ΓòÉΓòÉΓòÉ

The average character width of a font is the average character increment in
world coordinates. The character increment is the sum of the a-space, b-space,
and c-space of a character, which is shown in the previous figure. If you are
setting the font-use indicator FATTR_FONTUSE_OUTLINE, you can set the average
character width to 0 because the outline fonts take an equivalent value from
the character cell attribute that is current when text is written to an output
device.

This field should be specified when requesting an image font using
GpiCreateLogFont; it must be specified in world coordinates.


ΓòÉΓòÉΓòÉ 9.1.8.9. Type Indicator ΓòÉΓòÉΓòÉ

PM provides a type indicator to allow the further specification of font most
appropriate to your application. The type indicators found in the FATTR data
structure are not interchangeable with the type indicators in the FONTMETRICS
data structure.

The most commonly used type indicator, FATTR_TYPE_KERNING, causes kerning to
take effect for those fonts that contain kerning-pair information.
FATTR_TYPE_KERNING is supported only for PostScript** devices.

There are three other type indicators provided:

Indicator                   When...
FATTR_TYPE_ANTIALIASED      An anti-aliased font is required
FATTR_TYPE_MBCS             A mixed single- or double-byte code page is
                            required
FATTR_TYPE_DBCS             A double-byte code page is required.

Refer to the Presentation Manager Programming Reference for details about these
type indicators.


ΓòÉΓòÉΓòÉ 9.1.8.10. Font-Use Indicators ΓòÉΓòÉΓòÉ

The font-use indicators tell the PM programming interface what you intend to do
with the font, and determine whether you get an image font or an outline font.
There are three font-use indicators:

Indicator                   If set ON...

FATTR_FONTUSE_OUTLINE       Forces selection of an outline font. This value
                            must be set if you intend to use graphics
                            characters in a path definition.

FATTR_FONTUSE_TRANSFORMABLE Allows the scaling, rotating, or shearing of font
                            characters. Set this value ON if the current
                            character mode is CM_MODE3.

FATTR_FONTUSE_NOMIX         Allows the PM programming interface to ignore
                            current mix-mode values. Set this value ON if the
                            graphics text is not going to be written over or
                            underneath other graphics, because it improves the
                            performance of text drawing.

FATTR_FONTUSE_TRANSFORMABLE and FATTR_FONTUSE_OUTLINE normally are both
specified to select an outline font. Specify neither if you want to select an
image font.


ΓòÉΓòÉΓòÉ 9.1.9. Public and Private Fonts ΓòÉΓòÉΓòÉ

The fonts supplied by PM are loaded automatically when the system is started
and are available to any application at any time. They are said to be public
fonts. Any font that you define locally has to be loaded before you can use it.
If you load a locally defined font using the Install option of the Workplace
Font Palette, that font is available to any application in the system, and,
therefore is a public font. Some devices provide their own fonts. All device
fonts are public fonts.

Any font loaded using GpiLoadFonts from within an application is a private
font. A private font is available only to the application that loads it. The
file in which you store a locally created font definition can contain more than
one font definition. GpiLoadFonts loads a named font file and, therefore, loads
all fonts defined in that file. GpiQueryFontFileDescriptions provides the
family name and the face name of each font in a locally defined font file; use
this function to determine if a particular file contains the font you want to
use before you load it.

To unload a previously loaded private font file, call GpiUnloadFonts. You
cannot unload public fonts with this function.

You cannot use private fonts in a document that you want to print using the
spooler. If you want to print the document from a printer server, using the
PM_Q_STD format, all the fonts used in the document must be installed as public
fonts on the server.

You can use either public or private fonts if you specify the data format
PM_Q_RAW or if you want to print without the spooler.


ΓòÉΓòÉΓòÉ 9.1.10. Drawing a Character String Primitive ΓòÉΓòÉΓòÉ

To draw a string of one or more graphics characters from the current font, call
GpiCharString. The string starts at the current position and, when it has been
drawn, the new current position is the point at which the next character would
be, had there been one.

To draw the string starting at a position other than the current position, call
GpiCharStringAt. This is equivalent to calling GpiSetCurrentPosition or
GpiMove, followed by GpiCharString. You supply the text of the character string
as a parameter to the appropriate GPI function.

Note:  You also can call WinDrawText, which draws text to the screen a line at
       a time. WinDrawText differs from the GpiCharStringxxx functions in that
       WinDrawText ignores the DM_RETAIN drawing mode and can only be used to
       draw to a window device context.

The following figure shows some examples of a character string primitive.

The Character String Primitive

This example shows the string Presentation Manager drawn from different logical
fonts.


ΓòÉΓòÉΓòÉ 9.1.11. Font Files and Dynamic-Link Libraries ΓòÉΓòÉΓòÉ

You can use the Font Editor to alter and customize image-font files. Files
created with Font Editor have a .FNT extension. After you create a custom font,
put it into a dynamic-link library (DLL) that the application can load. Once
the application loads this library, it can use any of the custom fonts the
library contains.

DLLs that contain fonts are unique; they contain data segments and empty (or
useless) code segments. They are unique because they contain no executable
code, unlike normal DLLs. Also you are able to install the font file as a
public font if desired; GpiLoadFonts will make it available only as a private
font. The operating system naming convention for a DLL that contains font
information end with a .FON extension.

To create a DLL, you must use an assembler, a linker, and the operating system
Resource Compiler. For this example, assume that your custom font file is named
NEWFONT.FNT.

After creating your custom font file, you need to create a special assembler
language file with your editor. Call this file MYFONT.ASM, for example. The
following figure shows an example of the source code for this file.


   code segment word      ;Makes dummy code segment aligned on word boundary
   db "empty_segment"     ;Initializes a string in dummy segment
   code ends              ;Dummy segment ends here
   end                    ;Terminates source file

Creating a Custom Font

After you have created MYFONT.ASM, assemble it by using the following command:

    masm myfont

After assembling the MYFONT.ASM file, create a module-definition file. Call
this file MYFONT.DEF, for example. It should contain the statements in the
following figure.


    LIBRARY myfont
    SEGMENTS CODE MOVEABLE

Module Definition File for Custom Font File

The first statement tells the linker that you are creating a library with the
module name, MYFONT. The second statement tells the linker that the segments in
this library are movable code segments.

After creating MYFONT.DEF, start the linker with the command in the following
figure.

    link myfont,,,,myfont.def

Linking a Custom Font File

This command creates an empty executable file called MYFONT.EXE.

After creating the empty executable file, which is the template for a DLL,
create a resource file and call it MYFONT.RC. For example, if your font file is
called NEWFONT.FNT, you would place the statement in the following figure in
MYFONT.RC.

    FONT    200     NEWFONT.FNT

Resource for Custom Font File

This statement assigns the identifier, 200, to the font resource NEWFONT.FNT.

Finally, use the Resource Compiler to add the font file (NEWFONT.FNT) to the
empty DLL as in the following figure.

    rc  myfont.rc

Creating the Resource File for a Custom Font File

The executable file, MYFONT.EXE, now contains your custom fonts. After you have
renamed this file, MYFONT.FON, you can load the fonts into your application
using GpiLoadFonts and pass it a pointer to the path and library name as the
second argument-for example, c:\os2\dll\myfont.fon.


ΓòÉΓòÉΓòÉ 9.2. Using Fonts ΓòÉΓòÉΓòÉ

You can use the font functions to:

o Determine the characteristics of available fonts
o Select a font for text output
o Delete or unload a font when finished
o Create a font
o Create marker sets and pattern sets
o Use a bit map as a fill pattern
o Use a clip path as a fill pattern.


ΓòÉΓòÉΓòÉ 9.2.1. Selecting a Font ΓòÉΓòÉΓòÉ

Every presentation space has a current font, and graphics characters must be
drawn in that font. By default, the current font is the system font. Before an
application can use any font other than the system font, it has to identify the
other font as the new current font.

There are 2 distinct ways to identify the other font:

o Call GpiQueryFonts to request information about the available physical fonts,
  and then explicitly select one of those fonts by supplying its identifier as
  input to GpiCreateLogFont.

  This process has 11 steps and is described in Explicit Font Selection. This
  method of selecting a font is most useful for selecting image fonts.

  If you must have an image font, you are urged to use this "explicit
  selection"method, because you need to specify a maximum baseline extent and
  an average character width in the FATTRS structure. These values can be
  determined only by calling GpiQueryFonts. If you specify values that are not
  valid, you are likely to be given an outline font.

o Use GpiCreateLogFont to specify the features you require in a font, and
  permit the PM programming interface to make an appropriate font available to
  you.

  This process has 2 steps and is detailed in Closest-Matching Font Selection.


ΓòÉΓòÉΓòÉ 9.2.1.1. Explicit Font Selection ΓòÉΓòÉΓòÉ

An application can select either a public or a private font with
GpiCreateLogFont.  A public font is available to all applications. A private
font is loaded by an application for its exclusive use.

Use the PM Control Panel to load a public font. Four DLLs contain the Times
Roman, Helvetica, Courier, and System Monospaced image fonts. The names of
these libraries are:

o TIMES.FON
o HELV.FON
o COURIER.FON
o SYSMONO.FON.

Unlike most DLLs, font libraries typically use the file name extension .FON. If
the user loads all four libraries, a total of 76 public fonts are available.
An application can use both outline and image formats of these fonts.
Characters in the image format are available in sizes ranging from 8 to 24
points.  Characters in the outline format can be any size.

Call GpiLoadFont to load a private font.  Pass the function the path and name
of the DLL that contains the font.  After the application loads the DLL of
fonts, it can determine the characteristics of the fonts in that library by
calling GpiQueryFonts.

To select a public font from all of the available public fonts, do the
following:

 1. Call GpiQueryFonts, passing the QF_PUBLIC flag, a NULL pointer to the
    font's face name, and a count of 0 to determine the number of available
    public fonts, as shown in the following figure.

        #define INCL_GPILCIDS
        #include <os2.h>
        void fncFONT06(void){

            FONTMETRICS fm, afm[80];
            LONG cFonts = 0, cPublicFonts;
            HPS hps;

            cPublicFonts = GpiQueryFonts(hps,      /* Queries all public fonts */
            QF_PUBLIC,
            (PSZ) NULL,
            &cFonts,
            sizeof(fm),
            (PFONTMETRICS) NULL);
        } /* fncFONT06 */

    Determining the Number of Public Fonts Loaded

    Note:  To load and use a private font, follow the same procedure, but
           specify QF_PRIVATE, instead of QF_PUBLIC, in the calls to
           GpiQueryFonts.

 2. Copy the value returned by GpiQueryFonts into a LONG integer variable.

 3. Allocate memory for the FONTMETRICS data structures.

 4. Call GpiQueryFonts again, passing the QF_PUBLIC flag, a NULL pointer to the
    font's face name, the count returned by the previous call, and the address
    of an array of FONTMETRICS structures.

    GpiQueryFonts returns the font metrics of every font available the array of
    FONTMETRICS structures.  The font metrics define in detail the physical
    characteristics of a font and are described in the Presentation Manager
    Programming Reference.

    Because the font metrics are so detailed, the amount of information
    returned to you from GpiQueryFonts can be extensive.  You can restrict the
    amount of information returned by this function by:

   o Specifying an absolute number of fonts about which you require information
   o Asking for information about fonts of a specific face name only
   o Limiting the length of the font-metrics buffer.

    If you request information for more fonts than are available on the system,
    GpiQueryFonts returns all the information about the available fonts and a
    value indicating how many fonts it has returned.

    If you request information for fewer fonts than are available on the system
    (that match the specified face name, and so forth), GpiQueryFonts returns a
    value indicating the number of fonts that it was unable to return.

    The following figure is an example of this technique of selecting a font.

        #define INCL_GPILCIDS
        #include <os2.h>

        PFONTMETRICS fncFONT07 (HPS hps, PLONG pcPublicFonts) {
           PFONTMETRICS afm = NULL;
           LONG         fonts = 1000;

           *pcPublicFonts = GpiQueryFonts(hps,
                                          QF_PUBLIC,
                                          (PSZ) NULL,
                                          &fonts,
                                          sizeof(*afm),
                                          (PFONTMETRICS) NULL);

           if (!DosAllocMem(&afm,
                            sizeof(*afm)*(*pcPublicFonts),
                            PAG_COMMIT | PAGWRITE )) {
               GpiQueryFonts(hps,
                            QF_PUBLIC,
                            (PSZ) NULL,
                            pcPublicFonts,
                            sizeof(*afm),
                            afm);
           } /* endif */
           return afm;
        }

    Selecting a Font

 5. Examine the array of FONTMETRICS structures.

    a. For an outline font, examine the face name and other attributes of the
       font your application requires.

    b. For an image font, examine the device resolution fields. These fields
       are the ones that determine if a particular font and its metrics match
       the device with which you wish to use it.

    Note:  If your application is interactive, organize the face names and
           other information relevant to those fonts (such as point sizes) in a
           menu. When the operator has selected a font, supply the relevant
           information from the font metrics of that font in the FATTRS
           structure of GpiCreateLogFont.

 6. After determining which font to use, your application must fill in the
    fields of the FATTRS structure.  Some of the data for these fields will be
    copied (explicitly) from the FONTMETRICS structure. Then call
    GpiCreateLogFont.

    If you do not supply a face name, the default font is used.  If you supply
    a face name, and the presentation driver cannot find a matching font, a
    default font is selected.

    The FATTRS structure describes a logical font. An application can have up
    to 254 logical fonts defined at any one time in a single presentation
    space.

    Note:  A logical font is a list of font attributes, whereas a physical font
           is the bit-map or vector information that the system uses to draw
           characters.

 7. The fonts supplied by the PM programming interface, the fonts you load
    using the Control Panel, and any fonts you load with GpiLoadFonts are all
    physical fonts.

    Copying the entries in the FATTRS structure ensures that, if a particular
    font is unavailable, an attempt is made to find the most suitable
    substitute.  Without the FATTRS information, PM is less likely to locate a
    suitable font.

 8. Initialize a local identifier (lcid) for the new font.

 9. Call GpiCreateLogFont and pass as input parameters:

   o The lcid for the font

   o The address of an 8-character array containing the name you want to give
     to the logical font, (or, if you do not want to specify a name, the value
     NULL)

   o The address of the FATTRS structure.

10. Examine the return value from GpiCreateLogFont. The value will be 2 if the
    function is successful; 1, if the default font was used.

11. Pass the lcid to GpiSetCharSet, assigning the font to your application's
    presentation space. Then the application can use it for text output. (This
    step identifies a logical font as the current font.)

The following figure shows how to select an image font at least 14 device
coordinate units high.

#define INCL_GPILCIDS
#include <os2.h>

LONG fncFONT08(HPS hps, LONG lcid, LONG xres, LONG yres) {
   FATTRS       fat;
   PFONTMETRICS afm;
   LONG         cFonts;
   LONG         i;
   LONG         rc = 0;

   afm = fncFONT07(hps, &cfonts);
   if (amf) {
      for (i=0; 1<cfonts; i++) {
         if (!(afm[i].fsDefn & FM_DEFN_OUTLINE)
            afm[i].sXDeviceRes == xres &&
            afm[i].sYDeviceRes == yres &&
            afm[i].lMaxBaselineExt >= 14)  {
           fat.usRecordLength = sizeof(fat);
           fat.fsSelection = 0;
           fat.lMatch = 0;
           strcpy(fat.szFacename, afm[i].szFacename);
           fat.idRegistry = afm[i].idRegistry;
           fat.usCodePage = 0;
           fat.lMaxBaselineExt = afm[i].lMaxBaselineExt;
           fat.lAveCharWidth = afm[i].lAveCharWidth;
           fat.fsType = 0;
           fat.fsFontUse = 0;

           rc = GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fat);
           if (rc) {
              GpiSetCharSet(hps, lcid);
           } /* endif */
        } /* endfor */

     } /* endif */

     return rc;
}

Selecting an Image Font

GpiQueryFonts returns device coordinates for image fonts. For outline fonts, it
returns notional coordinates. Notional coordinates are the coordinate in which
the font was defined.  Usually outline fonts are defined over a 1000-by-1000
matrix, with the unit of the matrix a 1/1000 of the em height.


ΓòÉΓòÉΓòÉ 9.2.1.2. Reassociating the Presentation Space ΓòÉΓòÉΓòÉ

The match value of any device font is guaranteed to be unique only for the
current device. If you associate the presentation space with a different device
context, any logical fonts that also are device fonts are no longer available.
On the new device, the match number could identify a different device font
(which may not be suitable) or no font at all. Therefore, you should redefine a
logical font and select it as the current font if you reassociate the
presentation space when the current font is a device font. Otherwise, the
default font is used.

If you do not intend to use the font on the new device, however, you need not
redefine it. You will be able to continue using the font if you reassociate the
presentation space with the original device context.

Any generic fonts can continue to be used after the presentation space is
reassociated if they are suitable for the new device. An image font, for
example, can be used only on devices that are all-points addressable.


ΓòÉΓòÉΓòÉ 9.2.1.3. Font Resolution ΓòÉΓòÉΓòÉ

Device fonts, particularly printer fonts, usually are designed for a specific
resolution, namely the resolution of the device on which they are to be used.
By contrast, generic outline fonts are not device-specific. Generic image fonts
are designed for a particular resolution value and, therefore, are really
applicable only to devices with a matching resolution value.

The horizontal and vertical font resolution values for the device are returned
by DevQueryCaps. The desired horizontal and vertical device resolution values
in the font metrics of the font concerned are returned by GpiQueryFonts.
Compare these the device and the desired resolution values only for an image
font. If they are identical then this image font is designed for use with this
device (for example, the point size in the font metrics will be accurate for
this device). To select a font, do the following:

 1. Query the available fonts using GpiQueryFonts.

 2. If you want an outline font, search the metrics of fonts returned by
    GpiQueryFonts for a font that is an outline font and that has the required
    face name.

 3. If you want an image font, search the metrics of the fonts returned by
    GpiQueryFonts for a font that is an image font and that has the following:

   o Required face name
   o Required point size
   o Horizontal device resolution font metric that matches the horizontal
     resolution for the device
   o Vertical device resolution font metric that matches the vertical
     resolution for the device.

 4. As an alternative to the above for an image font, search the metrics of the
    fonts returned by GpiQueryFonts for a font that is an image font and that
    has the following:

   o Required face name
   o Required em height in world coordinates.

Before you define a logical font, determine the resolution of the current
device by using DevQueryCaps with the CAPS_VERTICAL_FONT_RES and
CAPS_HORIZONTAL_FONT_RES parameters.

Compare the values returned from this function with the xDeviceRes and
yDeviceRes values in the font metrics of the available fonts. These 2 values
contain the resolution of the device for which the font was designed. All
measurements are in pels per inch. By comparing the font resolution with the
device resolution, you can identify the image font best suited to the current
device.


ΓòÉΓòÉΓòÉ 9.2.1.4. Closest-Matching Font Selection ΓòÉΓòÉΓòÉ

The alternative to selecting a specific font is to set the match value to 0.
To have the PM programming interface select the closest-matching font
available, do the following:

 1. Define a logical font with GpiCreateLogFont. This function establishes a
    link between the calling application and an appropriate physical font.
    GpiCreateLogFont accepts a number of options as input, including the font
    attributes, which describe the physical features and capabilities of the
    font.

 2. Complete the FATTRS structure of GpiCreateLogFont. The FATTRS structure
    describes a logical font, which the system uses to find the closest
    matching physical font.  Depending on whether you are selecting a font
    using a match number, fill in the FATTRS structure, observing the rules
    listed in the following table.

    Filling in the FATTRS Structure

        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
        ΓöéIf using a match number       ΓöéIf not using a match number   Γöé
        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
        ΓöéSet the match number to the   ΓöéSet the match number to zero. Γöé
        Γöérequired FONTMETRICS value.   Γöé                              Γöé
        ΓöéThe FONTMETRICS value is the  ΓöéIf your font is an image font:Γöé
        Γöévalue in the FONTMETRICS      Γöé                              Γöé
        Γöéstructure for the required    ΓöéSet the maximum baseline      Γöé
        Γöéfont returned by              Γöéextent to the required        Γöé
        ΓöéGpiQueryFonts.                ΓöéFONTMETRICS value.            Γöé
        Γöé                              Γöé                              Γöé
        ΓöéSet the maximum baseline      ΓöéSet the average character     Γöé
        Γöéextent to zero.               Γöéwidth to the required         Γöé
        Γöé                              ΓöéFONTMETRICS value.            Γöé
        ΓöéSet the average character     Γöé                              Γöé
        Γöéwidth to zero.                Γöé                              Γöé
        Γöé                              Γöé                              Γöé
        ΓöéNote:  A negative lMatch is   Γöé                              Γöé
        Γöéonly unique for a device. A   Γöé                              Γöé
        Γöépositive lMatch is only uniqueΓöé                              Γöé
        Γöéon a particular system at a   Γöé                              Γöé
        Γöéparticular time.              Γöé                              Γöé
        ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

    Also observe the rules concerning the font-use indicator that are listed in
    the following table.

    Font-Use Indicator Considerations

        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
        ΓöéIf you have not set the       ΓöéIf you have set the           Γöé
        ΓöéFATTR_FONTUSE_OUTLINE         ΓöéFATTR_FONTUSE_OUTLINE         Γöé
        Γöéindicator:                    Γöéindicator:                    Γöé
        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
        ΓöéPM looks for an image font    ΓöéPM looks for a suitable       Γöé
        Γöéthat has the required         Γöéoutline font whose selection  Γöé
        Γöéselection indicators and whoseΓöéindicators match those you    Γöé
        Γöémaximum baseline extent and   Γöéhave specified.               Γöé
        Γöéaverage character width match Γöé                              Γöé
        Γöéthose you have specified.     ΓöéIf no suitable outline font isΓöé
        Γöé                              Γöéfound, the default font is    Γöé
        ΓöéIf no suitable image font is  Γöéused. No attempt is made to   Γöé
        Γöéfound, PM looks for an outlineΓöésubstitute an image font.     Γöé
        Γöéfont with the required face   Γöé                              Γöé
        Γöéname and selection indicators.Γöé                              Γöé
        Γöé                              Γöé                              Γöé
        ΓöéIf no suitable outline font isΓöé                              Γöé
        Γöéfound, the default font is    Γöé                              Γöé
        Γöémade available to you.        Γöé                              Γöé
        ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Outline fonts are affected by the current character attributes (for example,
character box, shear, and angle).  Because an outline font might be made
available to you, even when you requested an image font, call
GpiQueryFontMetrics to determine whether the font is an image font or an
outline font.  GpiQueryFontMetrics returns the metrics of the current logical
font in world coordinates.

The settings of the definition indicator, field defn in the font metrics, tell
you whether the font is either an image or outline font, or a device or generic
font. If the font is an outline font, specify values for the character
attributes before using the font.  Outline fonts are unaffected by the maximum
baseline extent and average character width values specified in
GpiCreateLogFont.

If the default font provided is an image font, and you also have specified
FATTR_FONTUSE_TRANSFORMABLE, any attempt to draw graphics characters in
CM_MODE3 raises an error condition. This is an exception to the general rule
that a FATTR_FONTUSE_TRANSFORMABLE font must be used in CM_MODE3 only.


ΓòÉΓòÉΓòÉ 9.2.2. Selecting the New Current Font ΓòÉΓòÉΓòÉ

In addition to completing the FATTRS structure, you must supply as input to
GpiCreateLogFont a unique lcid for the font.  The identifier is a number in the
range of 1 through 254. Because you can have more than one logical font
definition in a presentation space, you must select the current font by
supplying the font's lcid as input to GpiSetCharSet.

You do not have to call GpiSetCharSet to use the default font. When you want to
reset the current font to its default value, however, call GpiSetCharSet with
the value LCID_DEFAULT. The current font, like other modal attributes, reverts
automatically to its default value when specific GPI functions are called.


ΓòÉΓòÉΓòÉ 9.2.3. Deleting Logical Fonts and Unloading Physical Fonts ΓòÉΓòÉΓòÉ

A logical font can be used only by the application that defines it. The logical
font definition is stored in the presentation space and is saved on the LIFO
stack with its lcid when GpiSavePS is called. Unlike a physical font
definition, a logical font definition is temporary and is lost when the
presentation space is deleted.

To specifically delete a logical font, call GpiDeleteSetId, which deletes the
logical font, and makes its lcid available for reuse. Sometimes this is
necessary because there are only 255 lcids available. The logical font must not
be the current font when you call GpiDeleteSetId.

Logical fonts are deleted to release the lcid and free memory. Unload private
fonts using GpiUnloadFonts to free memory and to make them no longer available.
Uninstall public fonts using the Control Panel to free memory and to make them
no longer available.

You must end the association between physical and logical fonts before calling
GpiUnloadFonts.

If you call GpiUnloadFonts to unload a private font file, you must end the
association between the physical fonts in that file and the logical fonts
defined by the application. Do the following:

o Call GpiSetCharSet to select a current font (such as the default font) that
  is not linked to the physical fonts you are unloading

o Call GpiDeleteSetId to delete each logical font that refers to any of the
  physical fonts in the font resource-file. If you fail to do this, an error is
  returned to your application from GpiUnloadFonts.


ΓòÉΓòÉΓòÉ 9.2.4. Creating Fonts ΓòÉΓòÉΓòÉ

You cannot edit the definitions of any of the PM-provided fonts, although you
can create and edit image-font files using the Font Editor. A font file
contains a header, that describes the font in general terms and a section
containing bit maps of the characters themselves. The font definition is stored
in a resource file. A full description of the font-file format is provided in
the Presentation Manager Programming Reference.


ΓòÉΓòÉΓòÉ 9.2.5. Creating Marker Sets and Pattern Sets ΓòÉΓòÉΓòÉ

Like character sets, marker sets and pattern sets are defined in fonts. For
both marker sets and pattern sets, there are system-provided defaults. You also
can create your own image markers or patterns, but not outline markers or
patterns, using the Font Editor. The font definition containing the image or
pattern can be loaded either as a public font (using the Install selection from
the Control Panel) or as a private font (using GpiLoadFonts). The current
character mode has no effect on marker sets and pattern sets. Any character
from a font can be used as a marker or as an area-fill pattern.

Before you can use a locally defined marker set or pattern set, you must call
GpiCreateLogFont to define a logical font and to give it an lcid, just as you
would for a character font. Most of the values you can specify with
GpiCreateLogFont are not applicable to marker sets and pattern sets.
Furthermore, in the instance of marker sets and pattern sets, you usually know
that you want to use a particular font.

To select a locally defined marker set or pattern set:

 1. Call GpiQueryFonts to obtain a match value for the font.

 2. Call GpiCreateLogFont, specifying the face name, match value, and lcid for
    the font.

 3. Select the logical font as the current marker set or pattern set by calling
    GpiSetMarkerSet or GpiSetPatternSet, as appropriate.

To revert to using the default pattern or marker sets, call GpiSetPatternSet or
GpiSetMarkerSet with the value LCID_DEFAULT.


ΓòÉΓòÉΓòÉ 9.2.6. Using Bit Maps as Area-Fill Patterns ΓòÉΓòÉΓòÉ

An alternative to using the Font Editor to create your own pattern sets is to
use a bit map as an area-fill pattern. You must call GpiSetBitmapId to give the
bit map an lcid, and then call GpiSetPatternSet, specifying the lcid of the bit
map. The bit map becomes a pattern set containing one pattern, and the current
pattern-symbol attribute is ignored. GpiQueryBitmapHandle returns the handle of
the bit map currently known by the lcid that you supply as input.

PM cannot distinguish among the lcids associated with a particular presentation
space. Any lcid can identify a character set, marker set, pattern set, or bit
map (that is being used as an area-fill pattern). For example, if you call
GpiQueryNumberSetIds to determine how many lcids are currently assigned in the
presentation space, the number returned to you includes all logical fonts
defined for this presentation space. You also can use GpiDeleteSetId to remove
lcids associated with the non-font entities. If you call this function to
delete a bit map that is being used as an area-fill pattern, the bit map itself
is not deleted; however, it is disassociated from its lcid, and the lcid can be
reused.


ΓòÉΓòÉΓòÉ 9.2.7. Using Paths with Fill Patterns ΓòÉΓòÉΓòÉ

Using paths lets you fill a character string with a complicated or nonrepeating
pattern. The following sequence is recommended:

o Select the required outline font, and set the required character attributes.
o Create a path by calling GpiBeginPath, GpiCharString, and GpiEndPath.
o Set the required pattern symbol and other AREABUNDLE pattern attributes.
o Fill the path using GpiFillPath.

The following figure provides an example of using paths with fill patterns to
create characters.

Using Clip Paths to Create Characters


ΓòÉΓòÉΓòÉ 9.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the font functions.

Font Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Names          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharString           ΓöéDraws a character graphics string   Γöé
Γöé                        Γöéfrom the current font from the      Γöé
Γöé                        Γöécurrent position.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringAt         ΓöéDraws a character graphics string   Γöé
Γöé                        Γöéfrom the current font from a        Γöé
Γöé                        Γöéspecified position.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringPos        ΓöéDraws a character string with the   Γöé
Γöé                        Γöéfirst character at the current      Γöé
Γöé                        Γöéposition and permits positioning of Γöé
Γöé                        Γöéevery following character.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharStringPosAt      ΓöéDraws a character string and permitsΓöé
Γöé                        Γöépositioning for the first and every Γöé
Γöé                        Γöéfollowing character.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateLogFont        ΓöéDefines a logical font with         Γöé
Γöé                        Γöéspecified font attributes.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteSetId          ΓöéDeletes a logical font.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLoadFonts            ΓöéLoads a dynamic-link library        Γöé
Γöé                        Γöécontaining font resources and makes Γöé
Γöé                        Γöéthese available as private fonts.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharBreakExtra  ΓöéDetermines the current character    Γöé
Γöé                        Γöébreak extra attribute.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharExtra       ΓöéDetermines the current character    Γöé
Γöé                        Γöéextra attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharSet         ΓöéDetermines the current character setΓöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharStringPos   ΓöéDetermines the position of each     Γöé
Γöé                        Γöécharacter for an equivalent         Γöé
Γöé                        ΓöéGpiCharStringPos without actually   Γöé
Γöé                        Γöédrawing any characters.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCharStringPosAt ΓöéDetermines the position at which    Γöé
Γöé                        Γöéeach character for an equivalent    Γöé
Γöé                        ΓöéGpiCharStringPosAt without actually Γöé
Γöé                        Γöédrawing any characters.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryCp              ΓöéDetermines the current code page.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFaceString      ΓöéGenerates a compound face name for aΓöé
Γöé                        Γöéfont.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFontAction      ΓöéDetermines if available fonts have  Γöé
Γöé                        Γöébeen affected since the last time   Γöé
Γöé                        Γöéthe function was called.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFontFileDescriptΓöéDetermines the family name and face Γöé
Γöé                        Γöéname of each font in the locally    Γöé
Γöé                        Γöédefined font file.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFontMetrics     ΓöéDetermines the metric values of the Γöé
Γöé                        Γöécurrent font.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryFonts           ΓöéDetermines the font metrics of everyΓöé
Γöé                        Γöéfont available with a specified faceΓöé
Γöé                        Γöéname.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryKerningPairs    ΓöéDetermines kerning-pair information Γöé
Γöé                        Γöéfrom the current logical font.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryLogicalFont     ΓöéDetermines the font attributes      Γöé
Γöé                        Γöé(FATTRS) of the specified or currentΓöé
Γöé                        Γöélogical font.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryNumberSetIds    ΓöéDetermines the number of lcids that Γöé
Γöé                        Γöéare currently assigned in the       Γöé
Γöé                        Γöépresentation space.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySetIds          ΓöéDetermines the lcids currently      Γöé
Γöé                        Γöéassigned to logical fonts in the    Γöé
Γöé                        Γöéspecified presentation space.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryTextBox         ΓöéDetermines the coordinates of the   Γöé
Γöé                        Γöécorners of a text box for an        Γöé
Γöé                        Γöéequivalent GpiCharStringPos without Γöé
Γöé                        Γöéactually drawing any characters.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryWidthTable      ΓöéDetermines the width of all         Γöé
Γöé                        Γöécharacters in the current font.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharBreakExtra    ΓöéSets the current character break    Γöé
Γöé                        Γöéextra attribute.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharExtra         ΓöéSets the current character extra    Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCharSet           ΓöéSets the current character set      Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetCp                ΓöéAssigns a new code page.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiUnloadFonts          ΓöéUnloads a font file (private fonts).Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the font functions.

Font Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure               ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCHARBUNDLE              ΓöéContains the character attributes.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFATTRS                  ΓöéContains the font attributes of the Γöé
Γöé                        Γöéspecified font named in             Γöé
Γöé                        ΓöéGpiCreateLogFont.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFONTMETRICS             ΓöéContains all the font metrics       Γöé
Γöé                        Γöéreturned by the system to describe aΓöé
Γöé                        Γöéparticular font.                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 10. Paths ΓòÉΓòÉΓòÉ

A path is a graphics object composed of one or more figures drawn with graphic
primitives.  A path can be used for defining a filled area, a complex clipping
shape, an outline, and for drawing geometric wide lines.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Line and arc primitives
o Area primitives
o Color and mix attributes
o Regions
o Clipping.


ΓòÉΓòÉΓòÉ 10.1. About Paths ΓòÉΓòÉΓòÉ

Paths provide several useful drawing techniques including:

o An alternate means of generating filled or outlined irregular figures and
  nonrectangular shapes.

o An efficient means of producing hollow text in an outline font.

o The only means of clipping (restricting the area of interest of a picture) to
  circular, elliptical, or other nonrectangular figures.

o The only means of drawing lines with a thickness that can be transformed.
These techniques are respectively illustrated in the following figure.

Drawing Techniques Achieved with Paths

A path is similar to an area, but there are fundamental differences between the
two. The following table describes their similarities and contrasts.

Comparison of Paths and Areas

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPaths                         ΓöéAreas                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFunctions that define a path  ΓöéFunctions that define an area Γöé
Γöéare bracketed by GpiBeginPath Γöéare bracketed by GpiBeginArea Γöé
Γöéand GpiEndPath.               Γöéand GpiEndArea.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths are defined in world    ΓöéAreas are defined in world    Γöé
Γöécoordinates.                  Γöécoordinates.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be modified before  ΓöéAreas are displayed           Γöé
Γöébeing displayed or used for   Γöéimmediately on completion.    Γöé
Γöéclipping.                     Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be used by          ΓöéAreas cannot be used as       Γöé
Γöéapplications to perform       Γöéclipping regions.             Γöé
Γöéclipping.                     Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPaths can be converted into   ΓöéAreas cannot be converted intoΓöé
Γöégraphics objects called       Γöéregions.                      Γöé
Γöéregions.                      Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSix operations can be         ΓöéOnly two operations can be    Γöé
Γöéperformed on paths, each      Γöéperformed on areas (specified Γöé
Γöérequiring a separate function:Γöéwith options when creating theΓöé
Γöé                              Γöéarea):                        Γöé
ΓöéOutline                       Γöé                              Γöé
ΓöéFill                          ΓöéOutline                       Γöé
ΓöéModify                        ΓöéFill                          Γöé
ΓöéStroke                        Γöé                              Γöé
ΓöéConvert to clip path          Γöé                              Γöé
ΓöéConvert to region             Γöé                              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 10.1.1. Path Attributes ΓòÉΓòÉΓòÉ

Paths do not have a separate xxxBUNDLE data structure associated with them;
their attributes are defined by LINEBUNDLE and AREABUNDLE.  As described in
Attributes of Line and Arc Primitives however, there are certain line
attributes that apply only to geometric lines, or lines created with some path
operations. Depending on the purpose of a path, only certain path attributes
are in effect. These and the other path attributes are described in this
chapter.

When an application creates a presentation space, the path attributes are set
to the default values shown in the following table.

Path Attribute Default Values

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute       ΓöéDefault Value   ΓöéFunction that Redefines     Γöé
Γöé                Γöé                ΓöéAttribute                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGeometric width ΓöéNone            ΓöéGpiSetLineWidthGeom         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéEnd             ΓöéLINEEND_FLAT    ΓöéGpiSetLineEnd               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéJoin            ΓöéLINEJOIN_BEVEL  ΓöéGpiSetLineJoin              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéWidth           Γöé1.0             ΓöéGpiSetLineWidth             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéType            ΓöéLINETYPE_SOLID  ΓöéGpiSetLineType              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéColor           ΓöéCLR_NEUTRAL     ΓöéGpiSetAttrs (LBB_COLOR)     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMix mode        ΓöéFM_OVERPAINT    ΓöéGpiSetAttrs (LBB_MIX_MODE)  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern symbol  ΓöéSolid           ΓöéGpiSetPattern               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPattern set     ΓöéLCID_DEFAULT    ΓöéGpiSetPatternSet            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéReference point Γöé(0,0)           ΓöéGpiSetPatternRefPoint       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground colorΓöéCLR_NEUTRAL     ΓöéGpiSetAttrs (ABB_COLOR)     Γöé
Γöé                Γöé(black on most  Γöé                            Γöé
Γöé                Γöédevices)        Γöé                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground colorΓöéCLR_BACKGROUND  ΓöéGpiSetAttrs (ABB_BACK_COLOR)Γöé
Γöé                Γöé(white on most  Γöé                            Γöé
Γöé                Γöédevices)        Γöé                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéForeground mix  ΓöéFM_OVERPAINT    ΓöéGpiSetAttrs (ABB_MIX_MODE)  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBackground mix  ΓöéBM_LEAVEALONE   ΓöéGpiSetAttrs                 Γöé
Γöé                Γöé                Γöé(ABB_BACK_MIX_MODE)         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  Geometric width, End, and Join take effect only when a path is converted
       to a geometric wide line using GpiStrokePath or GpiModifyPath.

Width, Type, Color, and Mix mode take effect only when a path is outlined using
GpiOutlinePath.

Pattern symbol, Pattern set, and Reference point take effect only when a path
is filled using GpiFillPath or GpiStrokePath.


ΓòÉΓòÉΓòÉ 10.1.2. Line Width and Geometric Width for Paths ΓòÉΓòÉΓòÉ

Cosmetic lines represent the mathematical ideal of a 1-dimensional line; the
width attribute associated with them is provided only for ease of drawing these
lines larger than 1 pel.

In contrast, geometric line width is not an attribute; it is a geometric
property. To set the width of a geometric line, an application can use
GpiSetLineWidthGeom. This geometric width takes effect only when a path is
converted to a geometric wide line using GpiStrokePath or GpiModifyPath.

If a geometric line is drawn before the geometric width is specified, the drawn
line is defined by the cosmetic line width-usually 1-which results in the
thinnest possible line for the currently associated device. A geometric line
width has no default in the same way that the sides of a box, drawn with
GpiBox, have no length until specified by the function.

The value specified with GpiSetLineWidthGeom is the thickness of the line in
world coordinates, and it is subject to scaling by the current transformations
in effect at the time GpiModifyPath or GpiStrokePath is issued. For example, if
you apply a transform with a scaling factor of 0.5, for an object whose current
geometric line width is 4 world coordinates, the width of the displayed line
will be halved.

In the floor plan shown in the following figure, the outer walls were drawn
using geometric lines.  All of the other objects were drawn using normal lines.

Geometric Lines and Normal Lines

Your application can determine the current geometric width by issuing
GpiQueryLineWidthGeom.


ΓòÉΓòÉΓòÉ 10.1.3. Line End ΓòÉΓòÉΓòÉ

The line end attribute specifies the shape of the unattached end of a geometric
line. Lines whose shapes are partially defined by a geometric width have to be
closed, unlike cosmetic lines that simply end. An application can draw
geometric lines with square, flat, or round ends.

Note:  The end attribute takes effect only when a path is converted to a
       geometric width line using GpiStrokePath or GpiModifyPath.

Set the current geometric line end attribute with GpiSetLineEnd. The attribute
applies to all subsequent unattached lines within the path bracket. The
following table describes the three standard line ends provided by the PM
programming interface; you cannot define your own end types.

Standard Geometric Line End Types

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType                            ΓöéIdentifier      ΓöéLong Value  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFlat, flush with line end       ΓöéLINEEND_FLAT    Γöé1L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRound, past line end            ΓöéLINEEND_ROUND   Γöé2L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFlat, but extends past line end ΓöéLINEEND_SQUARE  Γöé3L          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The default line end type (LINEEND_DEFAULT) is identical to the LINEEND_FLAT
type, and has a long value of 0L. The error linetype (LINEEND_ERROR) has a long
value of -1L.

The following figure illustrates these three types of line ends. Your
application can determine the current geometric line end by issuing
GpiQueryLineEnd.

Closing Unattached Geometric Lines

A square line end extends the line by a distance that is half the width of the
line.  For example, if the line is 6 coordinate units wide, a square line end
extends it by 3 coordinate units.

A round line end is constructed by drawing a circle whose radius is half the
width of the line.


ΓòÉΓòÉΓòÉ 10.1.4. Line Join ΓòÉΓòÉΓòÉ

The line join attribute specifies the shape formed by two intersecting
geometric lines. Where one wide line joins another, the nature of the join must
be defined. An application can select a beveled, rounded, or mitred line-join
style.

Note:  The join attribute takes effect only when a path is converted to a
       geometric wide line using GpiStrokePath or GpiModifyPath.

Set the current geometric line-join attribute with GpiSetLineJoin. The
attribute applies to all subsequent intersection of lines within the path
bracket. The following table describes the three standard line joins provided
by the PM programming interface. You cannot define your own join types.

Standard Geometric Line Join Types

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéType                            ΓöéIdentifier      ΓöéLong Value  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDiagonal corner                 ΓöéLINEJOIN_BEVEL  Γöé1L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRounded corner                  ΓöéLINEJOIN_ROUND  Γöé2L          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé90┬░ angled corner               ΓöéLINEJOIN_MITRE  Γöé3L          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The default join type (LINEJOIN_DEFAULT) is identical to the LINEJOIN_BEVEL
type, and has a long value of 0L. The error linetype (LINEJOIN_ERROR) has a
long value of -1L. The following figure illustrates these three types of line
joins. Your application can determine the current geometric line join using
GpiQueryLineJoin.

Joining Wide Lines


ΓòÉΓòÉΓòÉ 10.1.5. Cosmetic Line Attributes for Paths ΓòÉΓòÉΓòÉ

When a path is drawn as a cosmetic line with GpiOutlinePath, the following
attributes are defined by the LINEBUNDLE data structure:

o Line width
o Line type
o Line color
o Line mix.

These attributes are described in Attributes of Line and Arc Primitives.

These attributes follow the current definitions and appear just as line
primitives do. Since the line primitive has only a foreground color and mix
attribute, the current color of the drawing surface affects the appearance of
these paths more than it does the appearance of paths that define geometric
lines. Those paths follow the area attributes and are affected by background
color and background mix attributes as well.


ΓòÉΓòÉΓòÉ 10.1.6. Area Attributes for Paths ΓòÉΓòÉΓòÉ

When a path is drawn as a geometric line with GpiStrokePath or GpiModifyPath,
the following attributes are defined by the AREABUNDLE data structure:

o Pattern symbol
o Pattern set
o Pattern reference point
o Area foreground color
o Area background color
o Area foreground mix
o Area background mix.

These attributes are discussed in Attributes of Area Primitives.

Area attributes follow the current definitions and appear just as area
primitives do.  The operating system uses the pattern symbol to fill the
interior of the path that defines the geometric line.  Any alterations to the
fill pattern or reference point affect the appearance of a geometric line just
as it does an area.


ΓòÉΓòÉΓòÉ 10.1.7. Path Color and Mix Attributes ΓòÉΓòÉΓòÉ

The color attribute defines the color used to draw a primitive or an object.
The mix attribute determines how the color of a primitive or an object is
combined with the color of the drawing surface, or any other objects on the
surface. Both attributes also are described in Color and Mix Attributes. Unlike
the color and mix attributes for primitives, and certain other objects, the
path color is defined by different attributes in different situations as
illustrated in the following figure.

Path Objects

Path colors are determined by the area color, area background color, area mix,
and area background mix attributes if the path is stroked into a wide line. The
cosmetic line path color is determined by the line color and mix attributes.

The line color defines the color used to draw the output from any of the OS/2
operating system line functions issued within the path. The line colors can
change within the path bracket, just as they can within area brackets. The
interaction of the line with the drawing-surface color is controlled by the
line mix attribute, which also can vary within the path bracket.

After the path is closed, the path can be stroked into a geometric (or wide)
line. Depending on the construction options, described in Path Fill, the
geometric line can be filled. The appearance of the pattern symbol used to fill
the path depends on the area attributes. The definitions of the area color and
background color depend on the pattern symbol as described in Area Colors and
Mix Attributes.

To specify a new color or mix attribute refer to the instructions in Line Color
and Mix Attributes for lines, or in Area Colors and Mix Attributes for areas.


ΓòÉΓòÉΓòÉ 10.1.8. Path Brackets ΓòÉΓòÉΓòÉ

The functions that create and define the path always are bracketed by the
GpiBeginPath and GpiEndPath functions. Only one path can be defined between
these two functions. However, within the path, there can be any number of
figures.

GpiBeginPath signals the start of a path definition. Each path you define
becomes the current path and replaces any existing path in the presentation
space. The current position is not changed by GpiBeginPath, although it is
updated by any drawing instructions that follow.

GpiBeginPath accepts as input only a path identifier of 1; this identifier is
used by the functions performing path operations to identify the path.

Due to the number of different operations that can be performed on paths, the
path definition can contain both open and closed figures.  If a figure does not
start and end at the same coordinate point, it is classified as an open figure.
Unlike an area bracket, if you issue GpiSetCurrentPosition or GpiMove within a
path definition, the current figure is not automatically closed.  Other
functions that merely separate figures within a path definition are listed in
the Presentation Manager Programming Reference.

The PM programming interface provides a method of closing figures within a
path.  The function GpiCloseFigure (valid only in path brackets) closes a
figure in the path, whose start and end points are not the same, by drawing a
straight line from the current position to the start position of the figure.
Use GpiCloseFigure if you want the line join attribute to be applied between
the start and end point of a figure.  Do not use it if you want the line end
attributes to be employed as the start and end points for a geometric wide
line.

If the path definition contains full arc or box primitives, however, you must
not close them using GpiCloseFigure.  GpiBox and GpiFullArc generate completely
closed figures and must not be used within another figure definition.

To signal the end of the current path definition, issue GpiEndPath. The path
definition is constructed in the currently associated presentation space. The
current position always is updated to the end point of the last line drawn.

The functions that generate a path are enclosed in a path bracket. Applications
can use the functions in the following list within a path bracket.

o GpiBeginElement
o GpiBox
o GpiCallSegmentMatrix
o GpiCharString
o GpiCharStringAt
o GpiCharStringPos
o GpiCharStringPosAt
o GpiCloseFigure
o GpiComment
o GpiCreateLogFont
o GpiDeleteSetId
o GpiElement
o GpiEndElement
o GpiEndPath
o GpiFullArc
o GpiGetData
o GpiLabel
o GpiLine
o GpiMarker
o GpiMove
o GpiOffsetElementPointer
o GpiPartialArc
o GpiPointArc
o GpiPolyFillet
o GpiPolyFilletSharp
o GpiPolyLine
o GpiPolyMarker
o GpiPolySpline
o GpiPop
o GpiPutData
o GpiQueryArcParams
o GpiQueryAttrMode
o GpiQueryCurrentPosition
o GpiSetArcParams
o GpiSetAttrMode
o GpiSetAttrs
o GpiSetCharAngle
o GpiSetCharBox
o GpiSetCharDirection
o GpiSetCharMode
o GpiSetCharSet
o GpiSetCharShear
o GpiSetColor
o GpiSetCp
o GpiSetCurrentPosition
o GpiSetEditMode
o GpiSetLineEnd
o GpiSetLineJoin
o GpiSetLineType
o GpiSetLineWidth
o GpiSetMarker
o GpiSetMarkerBox
o GpiSetMarkerSet
o GpiSetMix
o GpiSetModelTransformMatrix

Warning: Some GPI functions cannot be issued while an open path definition
exists. In particular, you cannot include image or area primitives in a path
definition.


ΓòÉΓòÉΓòÉ 10.1.9. Path Operations ΓòÉΓòÉΓòÉ

The operations performed on a path determine which of the path attributes
become applicable. Unlike specifying area brackets, the variety of operations
also calls for separate functions instead of specifying options with
GpiBeginPath. Specifically, the following six operations can be performed on a
path:

o Outline
o Fill
o Modify
o Stroke
o Convert to clip path
o Convert to region.

There are other graphics operations provided by the PM programming interface,
for example, transformations; however, they can apply to entities other than
paths.

Upon completion, the GpiFillPath, GpiOutlinePath, GpiStrokePath, and
GpiPathToRegion functions delete the current path definition. This path is not
available for any subsequent operations.

GpiModifyPath does not delete the current path definition. An application can
modify a path before issuing one of the aforementioned functions.

The first time your application issues GpiSetClipPath, the current path
definition is converted into the current clip path. GpiSetClipPath deletes the
path definition upon completion but not the clip path definition.

A path definition can be stored in a graphics segment; and, if that segment is
retained, the path can be re-created as required. Segments are discussed in
Creating and Drawing Retained Graphics.


ΓòÉΓòÉΓòÉ 10.1.10. Path Outline ΓòÉΓòÉΓòÉ

To draw the outline of the current path, issue GpiOutlinePath. This function
accepts a path identifier (which must be 1) as input. GpiOutlinePath does not
create a geometric line; therefore, the cosmetic line attributes are used.

GpiOutlinePath normally has the same effect as though the lines and arcs used
to create the path were drawn without actually being part of the path. Any open
figures within the path are not closed automatically. If the path contains
character strings that use an outline font, the characters are not filled.

The following functional sequence is recommended for drawing outline text or
outline figures:

Functional Sequence for Drawing Outline Text and Figures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéEffect                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginPath            ΓöéStarts the path definition.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiMove                 ΓöéMoves to the starting point of the  Γöé
Γöé                        Γöéfirst figure.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCharString,GpiFullArcΓöéUses an outline font to specify textΓöé
Γöé                        Γöéor define the lines in a figure.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndPath              ΓöéEnds the path.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOutlinePath          ΓöéDraws the text or figure outlines.  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

If you are drawing a complex path, consisting of several character strings that
use an outline font, it can take quite some time to produce.  If you want to
create a only rough draft, you might find it quicker to draw an outline instead
of the filled path. This improves performance and might be acceptable for small
characters. When they are small enough, hollow characters can look like filled
characters.

You can create hollow characters in either of two ways:

o Outside a path, issue GpiCreateLogFont.

  This enables you to define an outline font that uses hollow characters.

o Inside a path, draw the characters, then display the path with
  GpiOutlinePath.

  Only the character outlines contribute to the path definition even if the
  font is not hollow.  (This might cause ambiguous results.)

Using outlined paths to create character outlines also can be used to define a
clip path in the shape of a letter or word.


ΓòÉΓòÉΓòÉ 10.1.11. Path Fill ΓòÉΓòÉΓòÉ

To draw the current path and fill its interior using the current pattern
symbol, issue GpiFillPath.  The path is deleted after the interior is filled.
The boundary lines are considered part of the path interior and are drawn with
this function.  Any open figures in the path definition are closed
automatically by GpiFillPath.

This function accepts the path identifier (which must be 1) as input, and
either of two construction options:

o FPATH_ALTERNATE (the default)
o FPATH_WINDING (must be selected if the path has been modified).

Paths, like area primitives, can be filled in alternate mode or winding mode.
If the path consists of multiple, intersecting figures, the path-fill mode
affects the final appearance of the path.

The following figure shows two identical paths that were filled, each using one
of the two modes. Each path consists of a triangle drawn within a rectangle.
The path on the left was filled using the alternate mode.  The path on the
right was filled using the winding mode.

Alternate and Winding Fill Modes


ΓòÉΓòÉΓòÉ 10.1.11.1. Paths in Alternate Mode ΓòÉΓòÉΓòÉ

For paths drawn in alternate mode (as with area primitives), the following is
true:

o If you have to cross an odd number of boundaries in the path when drawing an
  imaginary line parallel to the x-axis, a point is included in the filled path
  from that point to positive infinity.

o If you have to cross an even number of boundaries in the path when drawing an
  imaginary line parallel to the x-axis, a point is not included in the filled
  path from that point to positive infinity.

The following figure shows how the operating system determines the filled
portion for the path shown in the previous figure. The path outside the
triangle, but inside the rectangle, is filled, because the imaginary lines
drawn from those points in the positive x-direction intersect the path
boundaries an odd number of times.

Calculating Filled Paths Constructed in Alternate Mode

Parts of the path with odd tallys are filled; parts with even tallys are not
filled.


ΓòÉΓòÉΓòÉ 10.1.11.2. Paths in Winding Mode ΓòÉΓòÉΓòÉ

For paths drawn in winding mode (also like area primitives), the direction the
boundaries in the path are drawn in determines whether a given point is
included in the filled path.  The drawn direction of a boundary line depends on
both the graphics functions used to draw it and the world coordinates that
define it.

For box primitives, for example, if the specified diagonal corner is to the
right, to the top, or both, of the current position, the box is drawn
counterclockwise.  If the specified diagonal corner is to the left, to the
bottom, but not both, the box is drawn clockwise.

For a polyline primitive, the direction of the boundary depends on the relative
values of the start and end points of each line.  For a polygon primitive, the
direction of the boundary depends on the relative values of the specified
vertices.

To determine whether a given point is included in the filled path, count the
number of boundary lines to be crossed to move from that point to infinity.
For each boundary line drawn in one direction add one to the tally.  For each
boundary line drawn in the opposite direction, subtract one from the tally.  A
point is within the area if the result is nonzero.  As with the alternate mode,
the imaginary determining line is drawn in the positive x-direction from the
point in question toward infinity.

The following figure shows how the operating system determines the filled
portion for the path shown in the figure before the previous one. Assume that
both the rectangle and triangle were drawn in the same direction, whether
clockwise or counterclockwise is immaterial.  Both figures are filled, because
the number of times the imaginary lines drawn from those points in the positive
x-direction intersect the path boundaries is continuously summed.  There is
never a subtraction of a boundary tally to reduce the total to 0.

Paths Constructed in the Same Direction in Winding Mode

Parts of the path with nonzero tallys are filled; parts with zero tallys are
not filled.

If two figures, for example in the following figure, are drawn in different
directions, the tally for the inner triangle is 0 and the area looks exactly as
it does in alternate mode.

Paths Constructed in Different Directions in Winding Mode

Parts of the path with nonzero tallys are filled; parts with zero tallys are
not filled.


ΓòÉΓòÉΓòÉ 10.1.12. Path Modification ΓòÉΓòÉΓòÉ

To convert the current path to one that describes the envelope of a geometric
wide line, issue GpiModifyPath.  The current geometric line attributes are then
applied to the figures within the path. The line end, line join, and geometric
line width attributes all must be set before modify-path or stroke-path
operations begin, because it is during those times that the attributes are
applied. Cosmetic line attributes of width and type have no effect on geometric
lines.

GpiModifyPath accepts the path identifier (which must be 1) and the
modification option MPATH_STROKE as input.

Subsequently, the modified path can be filled to display the geometric wide
line, but only in winding mode.  Alternatively, the modified path can be
converted into a clip path, but again, only in winding mode.

Open figures within the path are not closed automatically. Figures not
explicitly closed with GpiCloseFigure are drawn with line ends rather than line
joins at their start and end points.  If the figures within the path overlap,
the geometric width envelope compensates so that the overlap portion is not
drawn blank in XOR or exclusive-OR mode.

Now the geometric lines can be scaled.

Note:  The current transforms are applied to the primitives inside a path
       bracket when the path is defined.  This binds the path definition in
       device coordinates at that time. The path is unaffected by subsequent
       transformations, except for those (such as scaling) that affect the
       width of geometric (wide) lines.  Since the geometric line width
       attribute is not applied until the path is converted into a wide line by
       GpiModifyPath or GpiStrokePath, the width of geometric lines is
       unaffected by earlier transformations directed at the path definition.

After creating a path bracket, geometric wide lines can be constructed by
either:

o Stroking the path (GpiStrokePath)
o Modifying the path (GpiModifyPath), then filling the path (GpiFillPath).

GpiStrokePath is slightly more efficient, but GpiModifyPath and GpiFillPath
offer more flexibility (by way of the fill options). After drawing the lines no
alterations can be made.


ΓòÉΓòÉΓòÉ 10.1.13. Path-Stroking ΓòÉΓòÉΓòÉ

To modify and fill the current path in a single operation, issue GpiStrokePath.
Then the path is drawn immediately to the output device, with the current
geometric line attributes applied to the figures within the path.  Certain
device drivers can use this function to optimize storage.

GpiStrokePath automatically fills the path in winding mode with the current
area pattern symbol. When GpiStrokePath is complete, the path definition is
deleted from the device context.

GpiStrokePath is subject to the same constraints as functions that perform
simple line modification:

o The line end, line join, and geometric line width attributes all must be set
  before stroke operations.
o Cosmetic line attributes of width and type have no effect.
o Any open figures within the path are not closed automatically.
o If figures are not explicitly closed with GpiCloseFigure, they are drawn with
  line ends rather than line joins at their start and end points.
o If the figures within the path overlap, the geometric width envelope
  compensates so that the overlap portion is not drawn blank when drawn in XOR
  (exclusive-OR) mode.

This function accepts as input both the path identifier (which must be 1) and
the stroke option (which must be 0L).

When the operating system strokes a path, it draws a geometric line of
specified width along the original figure that defined the path; then, fills
the wide line.  If the original figure is not a closed shape, the operating
system does not automatically close it before filling the path. The following
figure shows the effects of GpiStrokePath on a box originally defined with
normal (cosmetic) lines.

Defining Lines with a Geometric Width

The broken line is the figure defined within the path. The solid lines show the
path after it has been converted. Each line has a geometric width of n
coordinate units, and the line joins have been defined as beveled.

After setting these attributes, the application can draw the line with
GpiStrokePath. After the lines are drawn, an application can scale stroked
paths with a scaling transformation.

As an alternative to the GpiStrokePath, you can convert the path using
GpiModifyPath, which does not draw the path on the current output device. To
draw a modified path, issue GpiFillPath, which draws the path and fills it with
the current area-fill pattern in winding mode. A modified path cannot be filled
in alternate mode.

On some devices, it might be that the GpiStrokePath method works better than
GpiModifyPath, followed by GpiFillPath.


ΓòÉΓòÉΓòÉ 10.1.14. Path Conversion to Clip Path ΓòÉΓòÉΓòÉ

Clipping is the process an application uses to limit graphics output to a
specific area (called the clipping area) of the display or page.  Clipping is
described further in Clipping and Boundary Determination.

There are several clipping functions provided by the PM programming interface;
however, if your application requires an irregular complex shape for a clipping
area, it must define the shape with a path. To convert the path into a clipping
boundary, issue GpiSetClipPath. The clip path, as defined by this operation,
becomes the current clip path for all subsequent drawing.

This function accepts a path identifier and one of two construction options as
input:

o SCP_ALTERNATE (default)
o SCP_WINDING (must be selected if the path has been modified).

Unlike the path operations described previously, GpiSetClipPath accepts two
different path identifiers:

o 1
o 0 (default).

The default path identifier of 0, called SCP_RESET, resets the clip path to
infinity, which displays the picture without clipping.  If this value is
selected, the current clip path definition is discarded instead of stored.

A path identifier of 1 is called SCP_AND.  For GpiSetClipPath, a path
identifier of 1 causes the clip path to be redefined as the mathematical
intersection of the stored clip path and the current path definition.  For all
other path operations, an identifier of 1 specifies the current path as the
recipient of the operation.  The only method of specifying the clip path as the
current path, after GpiSetClipPath has been issued, is to issue GpiSetClipPath
again:  the first issuance with a path identifier of 0; the second, with a path
identifier of 1.  The path identifiers and the construction mode can be ORed
together for certain effects.

Any open figures within a path are closed automatically.  The boundaries of the
path are considered part of the interior, so any point on the boundary is not
clipped. The following figure shows the result of clipping text with a
triangular clip path.

Triangular Clip Path


ΓòÉΓòÉΓòÉ 10.1.15. Path Conversion to Region ΓòÉΓòÉΓòÉ

To convert the current path to a region, issue GpiPathToRegion. Then, the new
region can be modified using any of the region functions that allow the
creation of irregular shaped regions.  For detailed information about regions,
see Regions.

Any open figures in the path definition are closed automatically by
GpiPathToRegion. Upon conversion, the current path definition is discarded just
like it is when being converted to a clip path. When GpiPathToRegion is
complete, the path definition is deleted automatically.

This function accepts the path identifier (which must be 1) and one of two
construction options as input:

o FPATH_ALTERNATE (default)
o FPATH_WINDING (must be selected if the path has been modified).


ΓòÉΓòÉΓòÉ 10.2. Using Paths ΓòÉΓòÉΓòÉ

You can use path functions to:

o Draw geometric lines and filled polygons
o Draw outline text
o Create a triangular clip path.


ΓòÉΓòÉΓòÉ 10.2.1. Drawing a Geometric (Wide) Line ΓòÉΓòÉΓòÉ

The following figure is an example of how to draw a straight line, 10 units
wide with rounded ends.

#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncPATH01(void){
    POINTL ptl;
    HPS hps;

    GpiSetLineWidthGeom(hps, 10L);       /* Sets line width to ten              */
    GpiSetLineEnd(hps, LINEEND_ROUND);   /* Sets line end to round              */
    GpiBeginPath(hps, 1L);               /* Begins path                         */
    ptl.x = 7;
    ptl.y = 15;
    GpiMove(hps, &ptl);                  /* Sets current position               */
    ptl.x = 450;
    ptl.y = 15;
    GpiLine(hps, &ptl);                  /* Draws line                          */
    GpiEndPath(hps);                     /* Ends path                           */
    GpiStrokePath(hps, 1L, 0L);          /* Draws geometric line                */
} /* fncPATH01 */


Drawing a Wide Line


ΓòÉΓòÉΓòÉ 10.2.2. Drawing Filled Polygons ΓòÉΓòÉΓòÉ

The following figure is an example of how to draw an empty triangle within a
solid rectangle.

#define INCL_GPIPATHS
#include <os2.h>
void fncPATH02(void){
    HPS hps;
    POINTL aptl1[4] = {       /*  Array of points for triangle   */
        50,  50,
        100, 100,
        150, 50,
        50,  50  };

    POINTL aptl2[5] = {       /* Array of points for rectangle   */
 25,  25,
 25, 200,
200, 200,
200,  25,
 25,  25 };

    GpiBeginPath(hps, 1L);                 /* Begins path                  */
    GpiMove(hps, aptl1);                   /* Sets current position        */
    GpiPolyLine(hps, 4L, aptl1);           /* Plots points for triangle    */
    GpiMove(hps, aptl2);                   /* Sets current position        */
    GpiPolyLine(hps, 5L, aptl2);           /* Plots points for rectangle   */
    GpiEndPath(hps);                       /* Ends path                    */
    GpiFillPath(hps, 1L, FPATH_ALTERNATE); /* Draws triangle and rectangle */
} /* fncPATH02 */


Drawing Filled Polygons


ΓòÉΓòÉΓòÉ 10.2.3. Drawing Outline Text ΓòÉΓòÉΓòÉ

The following figure shows an example of how to draw text from an outline font
with GpiOutlinePath.

#define INCL_GPIPRIMITIVES
#include <os2.h>
void fncPATH03(void){
    LONG lcid = 1;                            /* Identifier for font           */
    FATTRS fattrs;                            /* Structure for font attributes */
    SIZEF sizfx;                              /* Structure for character box   */
    POINTL ptl;                               /* Structure for starting point  */
    HPS hpsWin;

    fattrs.usRecordLength = sizeof(FATTRS);
    fattrs.fsSelection = FATTR_SEL_OUTLINE;   /* Specifies outline font        */
    fattrs.lMatch = 0;                        /* System determines font        */
    fattrs.szFacename[0] = 0;
    fattrs.idRegistry = 0;
    fattrs.usCodePage = 0;
    fattrs.lMaxBaselineExt = 0;
    fattrs.lAveCharWidth = 0;
    fattrs.fsType = 0;
    fattrs.fsFontUse = FATTR_FONTUSE_OUTLINE; /* Specifies outline font        */

    GpiCreateLogFont(hpsWin,(PSTR8) NULL, lcid, &fattrs);
    GpiSetCharSet(hpsWin, lcid);              /* Sets logical font             */

    sizfx.cx = MAKEFIXED(30, 0);              /* Width of character box        */
    sizfx.cy = MAKEFIXED(30, 0);              /* Height of character box       */
    GpiSetCharBox(hpsWin, &sizfx)             /* Sets size of character box    */

    GpiBeginPath(hpsWin, 1L);                 /* Begins path                   */
    ptl.x = 100;
    ptl.y = 200;
    GpiMove(hpsWin, &ptl);                    /* Sets current position         */
    GpiCharString(hpsWin, 7L, "Outline");     /* Establishes char. string      */
    GpiEndPath(hpsWin);                       /* Ends path                     */
    GpiOutlinePath(hpsWin, 1L, 0L);           /* Draws character string        */
} /* fncPATH03 */


Drawing Outline Text


ΓòÉΓòÉΓòÉ 10.2.4. Creating a Triangular Clip Path ΓòÉΓòÉΓòÉ

The following figure shows an example of how to create a triangular clip path;
then, write text into it.

#define INCL_GPIPATHS
#include <os2.h>
void fncPATH04(void){
    POINTL ptlStart;
    HPS hps;
    LONG i;

    POINTL aptl[4] = {             /* Array of points for triangle     */
           35,  45,
          100, 100,
          200,  45,
           35,  45 };

    GpiBeginPath(hps, 1L);         /* Begins path bracket              */
    GpiMove(hps, aptl);            /* Sets current position            */
    GpiPolyLine(hps, 4L, aptl);    /* Plots points for triangle        */
    GpiEndPath(hps)                /* Ends path bracket                */

    GpiSetClipPath(hps, 1L, SCP_ALTERNATE | SCP_AND);

    /* Write a block of text.                                          */

    ptlStart.x = 50;
    for (i = 50L; i < 110L; i += 10L) {
        ptlStart.y = i;
        GpiCharStringAt(hps, &ptlStart, 18L, "String of text!");
    } /* for */
} /* fncPATH04 */

Creating a Triangular Clip Path


ΓòÉΓòÉΓòÉ 10.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the path object functions.

Path Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginPath            ΓöéBegins a path definition.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCloseFigure          ΓöéDraws a line within the path        Γöé
Γöé                        Γöédefinition from the current positionΓöé
Γöé                        Γöéto the starting position of the     Γöé
Γöé                        Γöéfigure.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndPath              ΓöéTerminates a path.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiFillPath             ΓöéDraws the path, fills it with the   Γöé
Γöé                        Γöécurrent AREABUNDLE attributes, then Γöé
Γöé                        Γöédeletes the path. The fill can be inΓöé
Γöé                        Γöéeither winding or alternate mode.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiModifyPath           ΓöéModifies a path to describe the     Γöé
Γöé                        Γöéenvelope of a geometric wide line byΓöé
Γöé                        Γöéapplying line end, line join, and   Γöé
Γöé                        Γöégeometric line width attributes.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOutlinePath          ΓöéDraws only the borders of a path.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPathToRegion         ΓöéConverts a path to a region.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetClipPath          ΓöéConverts the created path into a    Γöé
Γöé                        Γöéclip path. The original path is     Γöé
Γöé                        Γöédeleted.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineEnd           ΓöéDefines the line end attribute.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineJoin          ΓöéDefines the line join attribute.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetLineWidthGeom     ΓöéDefines the geometric line width    Γöé
Γöé                        Γöéattribute.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiStrokePath           ΓöéConverts a path to the envelope of aΓöé
Γöé                        Γöégeometric wide line using the line  Γöé
Γöé                        Γöéend, line join and geometric line   Γöé
Γöé                        Γöéwidth attributes fills the path     Γöé
Γöé                        Γöéusing area bundle attributes and    Γöé
Γöé                        Γöéthen deletes the path.              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the path object
functions.

Path Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéAREABUNDLE              ΓöéData structure of area primitive    Γöé
Γöé                        Γöéattributes.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLINEBUNDLE              ΓöéData structure of line primitive    Γöé
Γöé                        Γöéattributes.                         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 11. Regions ΓòÉΓòÉΓòÉ

A region is a graphics object usually composed of one or more rectangles.
Converted to clip regions, they are used mainly to define a clipping boundary,
in device coordinates, for multiple intersecting rectangles.  Clip regions
provide the required clipping in an update region during WM_PAINT processing
when it is necessary to repaint part of a window. Regions also can be used for
area fill.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Area primitives
o Color and mix modes
o Coordinate spaces
o Transformations
o Clipping.


ΓòÉΓòÉΓòÉ 11.1. About Regions ΓòÉΓòÉΓòÉ

A region consists of one or more overlapping or separate rectangles in an
application's device space. The sides of the rectangles are parallel to the x-
and y-axes in the device coordinate space. An irregular, nonrectangular path
can be converted into a region, as explained in Paths.  However, unless
otherwise specified, the assumption of this chapter is that a region is
rectangular.

If a region consists of intersecting rectangles, the intersecting sides are
always perpendicular. If the rectangles have no common elements, the region is
defined as separate rectangles.

Unlike areas and paths, which are defined in world coordinates, regions are
device-dependent and, so, are defined in device coordinates.  The device
coordinates are inclusive (inside the rectangle) at the bottom and left
coordinate boundaries, and exclusive (outside the rectangle and clipped) at the
top and right boundaries.

Each region is created for the device that currently is associated with a
presentation space.  Also, after creation, regions are available for various
operations; a region handle identifies the region for subsequent operations.

The following figure shows a region that consists of two intersecting
rectangles.  An application defined the region by passing an array, containing
the coordinates for the two rectangles, to the GpiCreateRegion function.  The
application then drew the region with GpiPaintRegion.

Defining a Region

This region comprises two overlapping rectangles.


ΓòÉΓòÉΓòÉ 11.1.1. System Implementation ΓòÉΓòÉΓòÉ

Regions are device-dependent objects and, therefore, are associated with a
particular device.  For this reason, when an application specifies a
presentation space as input to one of the region functions, that presentation
space must be associated with a device context. The associated device context
serves to identify the device. Because a region is specific to the device for
which it was created, a region should not be created for one device and then
used for another.

If the device is a printer, a metafile can be used to store region functions as
escapes, and the resulting metafile can be displayed on any device.  The
appearance of the result of any region function is affected by differences in
the pel:aspect ratio and device resolution on different printers.

Most of the region-oriented functions use the RECTL structure to define the
device-space coordinates of the rectangle. When an application creates a
rectangle in a device space and passes its coordinates to a region function,
the operating system excludes the top and rightmost edges of the rectangle.
This means that an application must add 1 to the values in the xRight and yTop
fields of the RECTL structure to obtain the desired dimensions. For example, if
an application requires a region that measures 100-by-100 device units, with a
lower-left corner at (10,10), xRight and yTop should be set to 111 instead of
110.


ΓòÉΓòÉΓòÉ 11.1.2. Region Attributes ΓòÉΓòÉΓòÉ

Regions do not have a distinct xxxBUNDLE data structure associated with them.
Unlike primitives or even paths, the purpose of regions is to provide a
definition for an operation-not visual output. However, there are two functions
that present the region as a visible entity.

GpiPaintRegion paints a region in the presentation space. This function accepts
only the region handle as input. GpiPaintRegion does not cause graphics orders
to be added to the current segment. Therefore, in retain or draw-and-retain
modes, you are advised to use paths or areas rather than regions to ensure the
desired effect.

GpiFrameRegion draws a frame around a region by tracing the inner perimeter
with a rectangle of a specified size. This function accepts the region handle
and the desired frame thickness as input.

A region's visible output is controlled by the following AREABUNDLE attributes:

o Pattern symbol
o Pattern set
o Pattern reference point
o Area foreground color
o Area background color
o Area foreground mix.

These attributes follow the current definitions and appear just as area
primitives do.  The operating system uses the pattern symbol to fill the
interior of the region. Any alterations to the fill pattern or reference point
affects the appearance of a region, just as it does in an area.

Because neither the painted region nor the region frame have boundary lines, no
LINEBUNDLE attributes influence the appearance of a region resulting from the
GpiPaintRegion or GpiFrameRegion functions.


ΓòÉΓòÉΓòÉ 11.1.3. Region Creation ΓòÉΓòÉΓòÉ

Areas and paths are created and defined within a bracket; regions are defined
by a single function, GpiCreateRegion. As input to GpiCreateRegion, supply the
total number of, and the coordinates for, each rectangle that contributes to
the region. The following applies to region coordinates:

o They define the bottom left and top right coordinates of each rectangle that
  makes up the region.

o They must be in the range -32768 through +32767.

o They always are device coordinates, because regions always are created and
  drawn in an application's device space.

The output from GpiCreateRegion is the region handle, which identifies the
region for subsequent operations. Because each region can be distinctly
identified, the region functions allow applications to work with more than one
region at a time.

For example, an application can combine two regions with GpiCombineRegion or
compare two regions with GpiEqualRegion. GpiQueryRegionRects retrieves the
coordinates of the rectangles that make up a region, enabling an application to
create a copy of that region. To create the copy, you supply, as input to a new
GpiCreateRegion function, the exact rectangles returned from
GpiQueryRegionRects.


ΓòÉΓòÉΓòÉ 11.1.4. Region Operations ΓòÉΓòÉΓòÉ

The following operations can be performed on a region:

o Creating Regions
o Drawing Regions
o Moving Regions
o Determining Region Characteristics
o Converting a Path to a Region
o Converting a Region to a Clip Region
o Deleting Regions.


ΓòÉΓòÉΓòÉ 11.1.4.1. Creating Regions ΓòÉΓòÉΓòÉ

To create a rectangular region, call GpiCreateRegion. This function accepts, as
input, the number of rectangles to be ORed into a single region and the
coordinates of those rectangles. If the number of rectangles is 0, an empty
region is created.

To create a new region from regions that already exist, call GpiCombineRegion.
This function accepts, as input, a region handle for the target region, a
region handle for each of the two source regions, and an options flag that
specifies the way the two source regions are combined.

Note:  The destination region can be either of the two source regions; in which
       case, that region is replaced by the new region.

The rectangles are differentiated by one region's being distinctly "the first
source rectangle" and the other region labeled "the second source rectangle".
The order of the source rectangles affects the way GpiCombineRegion combines
them. You can use GpiCombineRegion an indefinite number of times to form
complex polygons; however, the function is limited to combining only two
regions each time it is called.  The two source regions must be created for the
same type of device.

Following are the five ways in which two regions can be combined:

Option         Result

CRGN_OR        Union of the two source regions.

CRGN_XOR       Symmetric difference of the two source regions.

CRGN_COPY      Source region 1 only; source region 2 is ignored.

CRGN_AND       Intersection of the two source regions.

CRGN_DIFF      Source region 1 minus source region 2.

The effects of these different combining operations on overlapping regions are
shown in the following figure. Their effects on separate regions are shown in
the figure after the following figure.

Combining Overlapping Regions

The source regions are two overlapping rectangles. The regions that result from
the various combine operations are shown as shaded areas.

Output from GpiCombineRegion tells you whether the resulting region is a NULL
region, rectangular region, or complex region. A complex region is any region
defined by two or more rectangles.

To change the definition of a region while keeping the same region handle, call
GpiSetRegion. This function accepts, as input, the number and dimensions of the
rectangles that now define the region, just as GpiCreateRegion does. However,
GpiSetRegion also accepts the handle of the region to be updated.
GpiSetRegion, like GpiCreateRegion, takes a region definition to be the union
of a sequence of rectangles (that are effectively ORed together).  In the case
of GpiCreateRegion, a new region is created and its handle returned. In the
case of GpiSetRegion, the previous definition is discarded and replaced by the
new definition that is associated with the existing region handle.

Combining Disjoint Regions

The two source regions do not overlap. The regions that result from the various
combine operations are shown as shaded areas. The result from a CRGN_AND
combining of separate regions is a NULL region.


ΓòÉΓòÉΓòÉ 11.1.4.2. Moving a Region ΓòÉΓòÉΓòÉ

To move a region, call GpiOffsetRegion. This function accepts, as input, the
region handle and an offset value that is added to every coordinate point of
the region.

GpiOffsetRegion moves a region by a specific number of device coordinates. By
specifying positive or negative x- and y-values an application can move a
region in any direction, relative to its current position.


ΓòÉΓòÉΓòÉ 11.1.4.3. Determining Region Characteristics ΓòÉΓòÉΓòÉ

Regions are used in many operations. There are several functions that determine
the characteristics of regions because these characteristics influence the
outcome of the operation being performed.

To determine whether two regions are identical, call GpiEqualRegion. This
function accepts, as input, the two region handles. Regions are identical if
the only difference between them is an empty region. For example, a rectangular
region whose lower-left corner is at 10,10 is not identical to a region whose
lower-left corner is at 50,50, even if the regions have exactly the same
dimensions. The two regions also must be of the same device class to be
considered identical.

To determine the rectangles that compose a region, call GpiQueryRegionRects,
which retrieves the coordinates of a series of rectangles that, when  ORed
together, define the shape of the regions.

Note:  The individual regions returned may differ in size and number from those
       originally used to specify the region

GpiQueryRegionRects accepts, as input, the region handle and the maximum number
of rectangles that can be returned. The division of the region into multiple
rectangles is handled automatically by the PM programming interface.

It is not necessary for an application to retrieve all the rectangles in a
single function. Your application can call GpiQueryRegionRects any number of
times.  Therefore, the application must specify the maximum number of
rectangles and the rectangle number to start from in each function.

No assumptions can be made about the number and coordinates of rectangles
returned except that they will define the specified region precisely. The
purpose of specifying the number of rectangles in the query is to ensure that
the system does not return more coordinates than can fit in the RECTL array.

To determine whether a point is inside the borders of a region, call
GpiPtInRegion. This function is especially useful in applications that must
determine whether the mouse pointer is over a region. The particular point must
be expressed in device coordinates.

To determine whether any part of a specified rectangle lies within a region,
call GpiRectInRegion. This function accepts, as input, the region handle and
the rectangle as specified in device coordinates.

To determine the coordinates of the smallest rectangle that encloses a region,
call GpiQueryRegionBox. This function accepts the region handle as input. The
output from this function tells you whether the bounding region is rectangular,
NULL, or complex.


ΓòÉΓòÉΓòÉ 11.1.4.4. Converting a Region to a Clip Region ΓòÉΓòÉΓòÉ

Clipping is the process an application uses to limit graphics output to a
specific area (called the clipping area) of the display or page. Clipping is
discussed in Clipping and Boundary Determination.

There are several clipping functions provided by the PM programming interface.
However, if your application requires a clipping boundary in device
coordinates, it must define the boundary with a region. To convert the region
into a clipping boundary, call GpiSetClipRegion. The clip region, as defined by
this operation, becomes the current clip region of all subsequent drawing
operations.

GpiSetClipRegion accepts, as input, the region handle. A NULL region handle
sets the clip region to infinity, effectively performing no clipping.

Unlike clip paths, the region that is no longer the current clip region is not
deleted. It retains the effects of any changes made to it while it was a clip
region; and it can be used with the other region functions, including being
reselected as the clip region with GpiSetClipRegion.

You do not have to deselect the current clip region before selecting another.
Each selected clip region automatically replaces the one before it. If there is
an existing clip region when you call GpiSetClipRegion, it reverts to a normal
region, and its handle is returned.

Note:  Clip regions and clip paths share the same low-level implementation. Use
       paths when you want to define your shape in world coordinates using
       drawing primitives, and regions when you want to define it in device
       coordinates (or world coordinates) using rectangles. Regions are
       generally faster to define.

When you have selected the current clip region, none of the region functions
described thus far can be used for that region. The following functions can be
used with the current clip region:

o GpiQueryClipBox
o GpiIntersectClipRectangle
o GpiExcludeClipRectangle
o GpiOffsetClipRegion
o GpiPtVisible
o GpiRectVisible.

These functions are described in Clipping and Boundary Determination. All of
these functions work in world coordinates, rather than device coordinates, and
therefore, are subject to current transformations.

GpiPtVisible and GpiRectVisible do not apply exclusively to clip regions.

When the screen contents are altered (for example, when a window is sized), you
have to be able to repair the part of the screen image affected by the change.
The following figure illustrates the necessary region. dup.

Repairing the Screen with Clip Regions

To improve performance of the drawing operation, you can restrict the redrawing
and repair work to the affected parts of the screen.

Use WinQueryUpdateRegion to determine whether graphics objects are totally
outside the update region and need not be drawn at all. Graphics objects that
are within, or are partly outside, the update region should be drawn, and the
system will perform the required clipping automatically.

Define a clipping region using the dimensions of the update region.  Then call
an appropriate GPI drawing request, such as GpiDrawChain, to redraw the screen
contents. Any drawing that would occur outside the clip region is discarded
according to the standard clipping rules. Only those graphics within the clip
region are redrawn.


ΓòÉΓòÉΓòÉ 11.1.4.5. Deleting a Region ΓòÉΓòÉΓòÉ

To delete a region, call GpiDestroyRegion. This function accepts, as input, the
region handle. If the region is the current clip region, it cannot be deleted.
To delete a current clip region, first call GpiSetClipRegion and specify a NULL
region handle.  The region is no longer the current clip region and can be
deleted.


ΓòÉΓòÉΓòÉ 11.2. Using Regions ΓòÉΓòÉΓòÉ

You can use the region functions to:

o Create or delete a region
o Combine regions
o Compare regions
o Move a region
o Paint and frame a region
o Locate a point with respect to a region
o Determine the coordinates of region rectangles.


ΓòÉΓòÉΓòÉ 11.2.1. Creating and Deleting a Region ΓòÉΓòÉΓòÉ

To create a region:

 1. Create an array of RECTL structures containing the dimensions of the
    rectangles that will compose the region.

 2. Call GpiCreateRegion to create the region. (This function returns a handle
    that identifies the region.)

To delete a region, pass the handle returned by the GpiCreateRegion function to
GpiDestroyRegion.

The following figure shows how to create and delete a region.

#include <os2.h>
void fncREGN01(void){
    HPS  hps;                            /* Presentation-space handle    */
    HRGN hrgn;                           /* Region handle                */
    RECTL arcl[] = {
         25,  50,                        /* Rectangle 1                  */
         75, 100,
         50,  75,                        /* Rectangle 2                  */
        100, 150,
         75, 125,                        /* Rectangle 3                  */
        200, 175,
        150,  75,                        /* Rectangle 4                  */
        250, 150 };

    hrgn = GpiCreateRegion(hps,        /* Creates region                 */
        sizeof(arcl) / sizeof (RECTL), /* Number of rectangles in region */
        arcl);                         /* Array of rectangle structures  */
        .
        . /* Work with the region here.                                  */
        .
    GpiDestroyRegion(hps, hrgn);   /* Destroys region identified by hrgn */
} /* fncREGN01 */


Creating and Deleting a Region


ΓòÉΓòÉΓòÉ 11.2.2. Combining Regions ΓòÉΓòÉΓòÉ

To combine two regions:

 1. Create a region that the operating system can use as the destination region
    when it combines the source regions.
 2. Determine which of the 5 combining methods to use.
 3. Call GpiCombineRegion.

The following figure shows how to combine 2 regions by using the OR operation:

#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN02(void){
    HPS  hps;
    HRGN hrgn1, hrgn2, hrgn3;          /* Region handles                    */
    RECTL rcl1, rcl2;

    rcl1.xLeft = 50; rcl1.yBottom = 100;
    rcl1.xRight = 200; rcl1.yTop = 175;
    hrgn1 = GpiCreateRegion(hps, 1L, &rcl1);        /* First source region  */

    rcl2.xLeft = 125; rcl2.yBottom = 150;
    rcl2.xRight = 225; rcl2.yTop = 200;
    hrgn2 = GpiCreateRegion(hps, 1L, &rcl2);        /* Second source region */

    hrgn3 = GpiCreateRegion(hps, 0L, (PRECTL) NULL); /* Destination region  */

    /* Combine the regions. */
    GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
} /* fncREGN02 */


Combining Regions


ΓòÉΓòÉΓòÉ 11.2.3. Comparing Regions ΓòÉΓòÉΓòÉ

GpiEqualRegion determines whether two regions are identical. The following
figure shows how to compare regions.

#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN03(void){
    HPS hps;                    /* Presentation-space handle         */
    HRGN hrgn1, hrgn2;          /* Region handles                    */
    LONG lEqual;                /* Return value for GpiEqualRegion   */
    RECTL rcl1, rcl2;           /* Structures for region coordinates */

    rcl1.xLeft = 50; rcl1.yBottom = 100;
    rcl1.xRight = 200; rcl1.yTop = 175;
    hrgn1 = GpiCreateRegion(hps, 1, &rcl1);    /* Creates first region  */

    rcl2.xLeft = 125; rcl2.yBottom = 150;
    rcl2.xRight = 225; rcl2.yTop = 200;
    hrgn2 = GpiCreateRegion(hps, 1, &rcl2);    /* Creates second region */

    lEqual = GpiEqualRegion(hps, hrgn1, hrgn2); /* Compares regions     */
    if (lEqual == EQRGN_EQUAL)
    {
        .
        .   /* Regions are equal.     */
        .
    }
    else if (lEqual == EQRGN_NOTEQUAL)
    {
        .
        .   /* Regions are not equal. */
        .
    }
    else if (lEqual == EQRGN_ERROR)
    {
        .
        .   /* An error occurred.     */
        .
    }
} /* fncREGN03 */


Comparing Regions


ΓòÉΓòÉΓòÉ 11.2.4. Offsetting a Region ΓòÉΓòÉΓòÉ

GpiOffsetRegion moves a region, by a specified offset, from its current
position (in world space). This function must be called with the address of a
POINTL structure that contains an x and a y translation factor. The following
figure shows how to offset a region.

} /* fncREGN04 */
    POINTL ptlNewPos;             /* Structure for offset value  */

    ptlNewPos.x = 200;            /* Sets x offset               */
    ptlNewPos.y = 10;             /* Sets y offset               */

    GpiOffsetRegion(hps, hrgn, &ptlNewPos);    /* Offsets region */


Offsetting a Region


ΓòÉΓòÉΓòÉ 11.2.5. Painting a Region ΓòÉΓòÉΓòÉ

GpiPaintRegion fills a region with the current fill pattern, using the colors
and mix mode that appear in the current AREABUNDLE structure.  GpiFrameRegion
draws a frame around a region by tracing the perimeter of the region with a
rectangle of a specified size. The following figure shows how to change the
fill-pattern color to green, paint a region, and draw a frame around the
region.

    SIZEL sizl;                        /* Structure for size of frame */
    HPS  hps;                          /* Presentation-space handle   */
    HRGN hrgn;                         /* Region handle               */

    GpiSetColor(hps, CLR_DARKPINK);
    GpiPaintRegion(hps, hrgn);         /* Paint region dark pink      */
    GpiSetColor(hps, CLR_BLACK);
    sizl.cx = 5;
    sizl.cy = 5;
    GpiFrameRegion(hps, hrgn, &sizl);   /* 5-by-5 black frame         */


Painting a Region


ΓòÉΓòÉΓòÉ 11.2.6. Locating a Point with Respect to a Region ΓòÉΓòÉΓòÉ

To determine whether the mouse pointer lies within a region:

 1. Retrieve the mouse-pointer coordinates and store them in a POINTL
    structure.

 2. Call GpiPtInRegion, passing it a handle that identifies the appropriate
    region and the address of the POINTL structure from Step 1.

 3. Examine the value that GpiPtInRegion returns to determine whether the point
    lies within the region.

The following figure shows how to locate the mouse pointer with respect to a
region.

#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN04(void){
    POINTL ptlCurPos;      /* Mouse coordinates              */
    HPS hps;               /* Presentation-space handle      */
    HRGN hrgn;             /* Region handle                  */
    LONG lPosition;        /* Return value for GpiPtInRegion */

    /* Determine mouse coordinates and store in ptlCurPos.   */
    lPosition = GpiPtInRegion(hps, hrgn, &ptlCurPos);
    if (lPosition == PRGN_INSIDE) {
        .
        . /* Point lies within region.  */
        .
    } /* if */
    else if (lPosition == PRGN_OUTSIDE) {
        .
        . /* Point lies outside region. */
        .
    } /* else-if */


Locating a Point in a Region


ΓòÉΓòÉΓòÉ 11.2.7. Determining Coordinates of Rectangles in a Region ΓòÉΓòÉΓòÉ

If a region consists of more than one rectangle, you can call
GpiQueryRegionRects to retrieve the coordinates of the lower-left and
upper-right corners of each rectangle.

If you use GpiQueryRegionRects to retrieve every rectangle requested to define
a region, the function retrieves the coordinates of as many contiguous
rectangles as required. GpiQueryRegionRects returns the coordinates of the
rectangles that define a region to an array of RECTL structures, and returns
the number of rectangles that were requested for the definition to the
crcReturned field of the RGNRECT structure.  Your RECTL array may not be large
enough to hold all of the rectangles.  Specify the maximum it can accept and
request the remainder in subsequent functions if necessary.

To determine the coordinates of the rectangles that form a region, follow these
steps:

 1. Create an array of RECTL structures that will receive the rectangle
    coordinates.  More rectangles may be required to define the region than
    were required to create it.

 2. Fill in the ircStart, crc, and usDirection fields of the RGNRECT structure.
    The crc field can specify more rectangles than will be returned by
    GpiQueryRegionRects.

 3. Call GpiQueryRegionRects to retrieve the coordinates.

The following figure shows how to determine the number of rectangles that
define a region, the coordinates of the rectangles in that region, and how to
create a new region using those coordinates.

#define INCL_GPIREGIONS
#include <os2.h>
void fncREGN05(void){
    RGNRECT rgnrc;               /* Structure for region rectangles       */
    RECTL arcl1[5];              /* Array for determining rectangle count */
    PRECTL parcl;                /* Array for rectangle coordinates       */
    ULONG cRects = 0;            /* Total number of rectangles in region  */
    HPS hps;
    HRGN hrgn3;

    rgnrc.ircStart = 1;          /* Rectangle to start with               */
    rgnrc.crc = 5;               /* Number of rectangles to query         */
    rgnrc.ulDirection = RECTDIR_LFRT_BOTTOP;      /* Direction to query   */

    /**********************************************************************/
    /*  Determine the total number of rectangles in the region by         */
    /*  repeatedly calling GpiQueryRegionRects with an array of 5 RECTL   */
    /*  structures. The loop terminates when the function retrieves less  */
    /*  than 5 rectangles.                                                */
    /**********************************************************************/
    do {
        GpiQueryRegionRects(hps, /* Handle of presentation space          */
            hrgn3,               /* Region to query                       */
            (PRECTL) NULL,       /* Gets all rectangles in region         */
            &rgnrc,              /* Structure with rectangle data         */
            arcl1);              /* Array of structures for coordinates   */

        cRects += rgnrc.crcReturned;
    } while (rgnrc.crcReturned == rgnrc.crc); /* While 5 rects retrieved  */

    //cRects = rgnrc.crcReturned + (rgnrc.ircStart - 1);

    rgnrc.ircStart = 0;                  /* Rectangle to start with       */
    rgnrc.crc = cRects;                  /* Number of rectangles to query */

    /* Allocate enough memory for all RECTL structures.                   */
    parcl = (PRECTL) malloc(cRects * sizeof(RECTL));

    /* Fill array with coordinates of all rectangles.                     */
    GpiQueryRegionRects(hps,     /* Handle of presentation space          */
        hrgn3,                   /* Region to query                       */
        (PRECTL) NULL,           /* Gets all rectangles in region         */
        &rgnrc,                  /* Structure with rectangle data         */
        parcl);                  /* Array of structures for coordinates   */
} /* fncREGN05 */


Determining Rectangle Coordinates in a Region


ΓòÉΓòÉΓòÉ 11.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the region object functions.

Region Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCombineRegion        ΓöéCombines 2 regions in any of 5 ways.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreateRegion         ΓöéCreates a region from 1 or more     Γöé
Γöé                        Γöérectangles. If there are 2 or more  Γöé
Γöé                        Γöérectangles, they are combined with  Γöé
Γöé                        Γöéan OR operation.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDestroyRegion        ΓöéDeletes a region and frees the      Γöé
Γöé                        Γöémemory associated with it.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEqualRegion          ΓöéDetermines whether 2 regions are    Γöé
Γöé                        Γöéequal.                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiFrameRegion          ΓöéDraws a frame around a region by    Γöé
Γöé                        Γöétracing the perimeter.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOffsetRegion         ΓöéMoves a region, other than a clip   Γöé
Γöé                        Γöéregion, in any direction by the     Γöé
Γöé                        Γöéspecified amount.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPaintRegion          ΓöéFills a region, other than a clip   Γöé
Γöé                        Γöéregion, with the current fill       Γöé
Γöé                        Γöépattern.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPtInRegion           ΓöéDetermines if a point lies within a Γöé
Γöé                        Γöégiven region, other than a clip     Γöé
Γöé                        Γöéregion.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryRegionBox       ΓöéDetermines the dimensions of the    Γöé
Γöé                        Γöésmallest rectangle that surrounds   Γöé
Γöé                        Γöéthe entire region.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryRegionRects     ΓöéDetermines the coordinates of       Γöé
Γöé                        Γöéindividual rectangles that compose aΓöé
Γöé                        Γöéregion.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRectInRegion         ΓöéDetermines if all or part of a      Γöé
Γöé                        Γöérectangle lies within a region.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetRegion            ΓöéReplaces the definition of an       Γöé
Γöé                        Γöéexisting region with a new          Γöé
Γöé                        Γöédefinition described by one or more Γöé
Γöé                        Γöérectangles.                         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used by the region object
functions.

Region Structures

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRECTL                   ΓöéA structure specifying the values ofΓöé
Γöé                        Γöé2 (x,y) coordinate pairs defining   Γöé
Γöé                        Γöéthe bottom-left and top-right       Γöé
Γöé                        Γöécoordinates of a rectangle.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRGNRECT                 ΓöéA structure specifying a start      Γöé
Γöé                        Γöérectangle number, a count of the    Γöé
Γöé                        Γöémaximum number of rectangles to be  Γöé
Γöé                        Γöéreturned and a field to be updated  Γöé
Γöé                        Γöéwith the number of region rectanglesΓöé
Γöé                        Γöéreturned by GpiQueryRegionRects.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 12. Creating and Drawing Retained Graphics ΓòÉΓòÉΓòÉ

There are two types of graphics output in the OS/2 operating system:  retained
and nonretained. This chapter describes creating and replaying retained
graphics.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Coordinate spaces and transformations
o Editing graphic segments.


ΓòÉΓòÉΓòÉ 12.1. About Creating and Drawing Retained Graphics ΓòÉΓòÉΓòÉ

An application draws by calling graphics functions. Applications store retained
graphics in segments, which can be edited.  This means that the retained image
can be modified without having to re-create the unmodified portion using
multiple GPI functions.

When using nonretained graphics, the output appears on the output device (for
example, a window) immediately.  However, if part of the picture is erased or
must be repeated, the application must call the same graphics function a
second, or even a third time.

There are many other advantages to using retained graphics, including:

o Convenience-An application can draw retained graphics with a single function
  that accesses the storage area containing all the individual functions
  necessary for the object.

o Flexibility-An application can redraw graphics retained in the segment store
  to any number of device contexts.

o Editing-An application can modify an object without having to call all the
  functions necessary to re-create the picture.  Individual segments can be
  moved, scaled, or rotated; then, redrawn.

  Editing the graphics within a segment is described in Editing Retained
  Graphics and Graphics Segments.

o Power-An application can access the more powerful and useful graphics
  functions only when graphics are stored in segments.

o Organization-An application can use segments to store the components that
  will be assembled into the final picture.

Primarily, a graphics segment is a means of grouping and storing graphics
primitives and their attributes. Although the graphics within a segment usually
are related in some way, they do not have to be. A segment might contain a
number of unrelated GPI functions that you want to keep and execute at specific
times.

Retained graphics do affect application performance, however, in that a normal
presentation space requires 114KB of main memory more than a micro presentation
space; and using the drawing mode DM_RETAIN adds an additional 46KB.

Note:

Your application can have up to 16K (16378) segments in the segment store of a
single presentation space. The size of an individual segment is limited only by
the amount of storage available to you.

Do not confuse a graphic segment with a memory segment.


ΓòÉΓòÉΓòÉ 12.1.1. Drawing Modes ΓòÉΓòÉΓòÉ

When you create a presentation space, the drawing mode is set to draw. Your
application can change this mode using GpiSetDrawingMode. The two additional
drawing modes provided by the PM programming interface are retain (DM_RETAIN)
and draw-and-retain (DM_DRAWANDRETAIN). Your application can determine which
drawing mode is set using GpiQueryDrawingMode.

The drawing mode that you select becomes current for the presentation space,
and it can be changed any number of times. Select the appropriate drawing mode
before creating a segment. The drawing mode effects the segment type.


ΓòÉΓòÉΓòÉ 12.1.1.1. Draw Mode ΓòÉΓòÉΓòÉ

In draw mode, graphics output is provided immediately to the currently
associated device and is not retained in a segment store.  When the graphics
have been drawn, they cannot be used again unless they are re-created. For
example, when a window containing draw mode graphics is moved or sized, the
graphics have to be re-created by the application.

Draw mode graphics are suitable if an application is creating fairly simple
graphics quickly or is maintaining its own graphics database.  In the latter
case, there is nothing to gain by retaining graphics.

A segment created when the drawing mode is DM_DRAW, is called a nonretained
segment. While it might sound contradictory, nonretained segments have certain
advantages that are described in Nonretained Graphic Segments.


ΓòÉΓòÉΓòÉ 12.1.1.2. Retain Mode ΓòÉΓòÉΓòÉ

In retain mode, graphics are retained in the segment store only; they are not
directed to the current device as they are created.

In retain mode, the presentation space does not have to be associated with a
device context when graphics are being defined. It is possible to define
graphics and store their definitions without sending them to a display screen
or printer. The concept of attribute currentness, however, is relevant only
when you are drawing graphics to an output device. For example, the color, or
other attribute, that is current when you define a primitive is the color in
which the line is drawn. That color, or other attribute might not be the color
that is current when you you actually draw the primitive. This is described in
Attribute Currentness.

Many of the GPI queries that return current attribute values are invalid in
retain mode because current attribute values have no effect when graphics are
not sent to an output device.


ΓòÉΓòÉΓòÉ 12.1.1.3. Draw-and-Retain Mode ΓòÉΓòÉΓòÉ

In draw-and-retain mode, graphics are both drawn on the current device as they
are created and stored for later use.  The GPI queries that return current
attribute values are valid in draw-and-retain mode.


ΓòÉΓòÉΓòÉ 12.1.2. Creating a Graphics Segment ΓòÉΓòÉΓòÉ

Your application signals the start of a graphics segment using GpiOpenSegment,
which is valid only in a normal presentation space. The following figure is an
example of 2 segments in a presentation space.


                            Presentation Space
                          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                          Γöé                                     Γöé
                          Γöé   Graphics Segment 1                Γöé
                          Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                    Γöé
                          Γöé   Γöé            Γöé                    Γöé
GpiOpenSegment (hps,1L);  Γöé   Γöé            Γöé                    Γöé
GpiSetXXX (hps,...);    ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ     Γöé                    Γöé
GpiLine (hps,...);      ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ         Γöé                    Γöé
GpiCloseSegment (hps);    Γöé   Γöé            Γöé  Graphics Segment 2Γöé
                          Γöé   Γöé            Γöé  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé
                          Γöé   Γöé            Γöé  Γöé            Γöé    Γöé
                          Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé            Γöé    Γöé
                          Γöé                   Γöé            Γöé    Γöé
GpiOpenSegment (hps,2L);  Γöé                   Γöé            Γöé    Γöé
GpiSetXXX (hps,...);    ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇ      Γöé    Γöé
GpiLine (hps,...);      ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ         Γöé    Γöé
GpiCloseSegment (hps);    Γöé                   Γöé            Γöé    Γöé
                          Γöé                   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    Γöé
                          Γöé                                     Γöé
                          Γöé                                     Γöé
                          ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Graphics Segments in a Presentation Space

GpiOpenSegment accepts, as input, the presentation space handle and a long
integer value, which names each segment.

OS/2 applications identify segments with long integer values. If you want to
refer to the segment individually in later graphics operations (for example, to
edit the segment) the identifier you supply must be greater than 0 and unique
within the presentation space.

If you do not want to refer to the segment individually after it is created,
you can give the segment an identifier of 0. You might do this when you are
creating nonretained segments, for example.  Any number of segments can have
the 0 identifier; they are referred to throughout this guide as zero segments.

To determine which names already have been used in a presentation space, use
GpiQuerySegmentNames. This function returns an array of segment names for all
retained segments, excluding zero segments, within a specified name range.

Segments do not have to be named in consecutive order (although it is
recommended for organizational purposes) because the segment order can be
changed using GpiSetSegmentPriority.


ΓòÉΓòÉΓòÉ 12.1.3. Filling a Graphics Segment ΓòÉΓòÉΓòÉ

After a graphic segment is opened, the GPI functions that follow become a part
of a retained segment and are executed every time the segment, itself, is
drawn.

The typical GPI functions that would be called are those that:

o Create graphics primitives-such as lines or markers
o Assign attributes to those primitives-such as color or line type.

However, there are a few GPI functions that you cannot call while there is an
open segment, for example a second GpiOpenSegment. These functions are
identified in GPI Functions.

A presentation space can contain many segments. Each time you open a new
segment, many attributes reset themselves to default values. Therefore, the
current position and attribute values that apply before you call GpiOpenSegment
cannot be guaranteed to be in effect after you call the function. Beginning
each segment with a number of attribute-setting requests and, possibly, with
GpiSetCurrentPosition, is recommended. Your application also might take
advantage of GpiSetDefAttrs, for example, to minimize the number of attributes
that must dealt with upon opening a new segment.


ΓòÉΓòÉΓòÉ 12.1.4. Closing a Graphics Segment ΓòÉΓòÉΓòÉ

When you have finished creating a graphics segment, close it using
GpiCloseSegment. There can be only one open segment at a time in a single
graphics presentation space, so you must close one segment before going on to
the next.

There is some degree of clean-up processing associated with using
GpiCloseSegment, known as close-segment processing, that can make current
attribute values unreliable. For more information about the effects of
GpiOpenSegment and GpiCloseSegment on current attributes, see Graphics
Attributes.


ΓòÉΓòÉΓòÉ 12.1.5. Segment Attributes ΓòÉΓòÉΓòÉ

Each segment, whether retained or nonretained, has a number of characteristics,
called attributes that you can set in accordance with your application's
requirements. The attributes of a segment are quite different from those of a
graphics primitive in that segment attributes have ON and OFF settings. There
are 7 segment attributes; however, only 2 are described in this chapter:
chained (ATTR_CHAINED) and fast-chained (ATTR_FASTCHAIN).

When an application creates a segment in a presentation space, the operating
system assigns initial attributes to it. By default, 5 of the attributes will
be set ON and 2 will be set OFF. The chained and fast-chained attributes are
set ON. Your application can alter these values using
GpiSetInitialSegmentAttrs, or retrieve the values of the current initial
attributes using GpiQueryInitialSegmentAttrs.

The chain attribute tells the operating system to add each new segment in your
application's presentation space to the segment chain. The fast-chained
attribute tells the operating system to prevent the resetting of the primitive
attributes to their default values before drawing the segment chain.


ΓòÉΓòÉΓòÉ 12.1.5.1. Chained Attribute ΓòÉΓòÉΓòÉ

When you define a segment with the chained attribute switched ON, that segment
becomes a part of the segment chain and is called a chained segment. The
segment chain is composed of all chained segments defined in a single
presentation space. The following figure illustrates the segment chain concept.
Segments can be chained together so that they can be drawn as a group. By
default, each new segment is chained to the previous segment.

There can be only one segment chain at a time in a single presentation space,
and all chained segments are chained to each other in the order in which you
created them. Zero segments must have the chained attribute.

Usually, a logical relationship exists between the segments in a segment chain,
although this is not a requirement. The whole segment chain can be drawn using
GpiDrawChain. Each segment in the chain is called a root segment. Root segments
are affected by those GPI functions that act on the segment chain, but they
also can be manipulated independently of the chain.

Segments that are defined with the chained attribute switched OFF are called
unchained segments. Your application can switch off the chain attribute using
GpiSetInitialSegmentAttrs (hps, ATTR_CHAIN, ATTR_OFF). Unchained segments
always are retained when they are created, regardless of the current
drawing-mode parameter. An unchained segment must have a unique name.

There are a number of reasons for defining a segment as unchained. For example,
a particular segment might not belong to the picture that is defined by the
segment chain. You also are likely to define as unchained any segment that
belongs to the picture but that has no single, fixed place in the segment
chain. A car wheel, for example, could be defined once but drawn four times in
a picture of a car. It would have no single, fixed place in the segment chain,
but would be included four times in the picture by being called from one or
more root segments.

A segment is called from another segment by including GpiCallSegmentMatrix in
the calling segment. A segment and the segments it calls logically are one
object. An important point about called segments is that they assume the
primitive attribute settings of the calling segment. Of course, you can change
the attribute settings within the called segment if the inherited values are
inappropriate.

A closed, unchained segment can be called from any other segment. Chained
segments, however, cannot be called from other segments.


ΓòÉΓòÉΓòÉ 12.1.5.2. Fast-Chained Attribute ΓòÉΓòÉΓòÉ

The fast-chained attribute applies only to chained segments. It prevents
primitive attributes from being reset to their default values at the beginning
of the segment, an aid to performance. There is unnecessary overhead in
resetting attributes to their defaults if either of the following is true:

o You are going to change the default values of the attributes at the start of
  the segment.

o You know that attributes have not been altered previously from their default
  values.

The fast-chained attribute is switched ON by default, and you should leave it
on unless you specifically want attributes to be set to their default values.
To turn off the fast-chained attribute, call GpiSetInitialSegmentAttrs (hps,
ATTR_FASTCHAIN, ATTR_OFF).


ΓòÉΓòÉΓòÉ 12.1.6. Actual Drawing Mode ΓòÉΓòÉΓòÉ

The drawing mode, as defined by GpiSetDrawingMode, works in conjunction with
the segment status to produce the actual drawing mode. It is the actual drawing
mode that determines whether graphics are:

o Drawn directly to the output device
o Retained in the segment store
o Both drawn and retained.

The actual drawing mode is summarized in the following table.

The Current Drawing Mode

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé                 Γöé               ΓöéContext       Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDrawingModeΓöéChained SegmentΓöéUnchained     ΓöéOutside of anyΓöé
Γöéparameter        Γöé               ΓöéSegment       Γöésegment       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAWANDRETAIN Γöédraw-and-retainΓöéretain        Γöédraw          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_RETAIN        Γöéretain         Γöéretain        Γöédraw          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAW          Γöédraw           Γöéretain        Γöédraw          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

As you can see in the prceding tabke, graphics within chained segments always
conform to the current drawing mode parameter. That is, they are drawn in
DM_DRAW mode, retained in DM_RETAIN mode, and both drawn and retained in
DM_DRAWANDRETAIN mode.

Graphics in unchained segments always are retained, regardless of the current
drawing-mode parameter. You cannot retain segments created when the current
drawing-mode parameter is DM_DRAW, unless they are unchained segments.

Similarly, graphics outside segments always are drawn without being retained.
You cannot retain primitives outside segments, regardless of the current
drawing mode.

Note:  A micro presentation space has no segment store. Therefore, you cannot
       create graphics segments in a micro presentation space, nor can you
       change the drawing mode, which is always DM_DRAW.


ΓòÉΓòÉΓòÉ 12.1.7. Drawing a Retained Graphic ΓòÉΓòÉΓòÉ

Your application can draw a complete segment chain with GpiDrawChain. The
segments are drawn in the order in which they appear in the chain. For example,
the segments in the following figure are drawn in the following order:

 1. Root segment 1
 2. Unchained segment A
 3. Unchained segment B
 4. Root segment 2
 5. Unchained segment B
 6. Root segment 3.

Chained and Called Segments

Segment A is called by root segment 1, and segment B is called by both segment
A and root segment 2. Segment C calls segment D. Both C and D are unchained
segments that are not called from the segment chain, and consequently, are not
part of the segment chain.

GpiSetSegmentPriority changes the position of a root segment (which must not be
a zero segment) in the chain. As input to this function, you supply the name of
the segment you want to reorder and the name of a reference segment. The
reference segment is the segment that either will be immediately before, or
immediately after, the reordered segment's new position in the chain.

If the segment you are moving is to come after the reference segment in the
chain, it is said to have a higher priority (HIGHER_PRI). If it is to come
before the reference segment, it is said to have a lower priority (LOWER_PRI).
The nearer a segment is to the end of the chain, the higher its priority.

If you supply the name of an unchained segment as input to
GpiSetSegmentPriority, the segment is added to the chain in the position you
specify. To learn the position of a segment in the chain, use
GpiQuerySegmentPriority.

If your application called the following functions:

GpiSetSegmentPriority (hps, C, 2, LOWER_PRI)
GpiSetSegmentPriority (hps, 3, 0, HIGHER_PRI)
GpiSetSegmentPriority (hps, B, 0, LOWER_PRI)

the segment chain in the previous figure would appear as in the following
figure; and GpiDrawChain would draw the segments in the following order.

 1. Root segment 3
 2. Root segment 1
 3. Unchained segment A
 4. Unchained segment B
 5. Segment C
 6. Unchained segment D.
 7. Root segment 2
 8. Unchained segment B.
 9. Segment B


ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé   Root   Γö£ΓöÇΓöÇΓöÇΓöÇΓöñ   Root   Γö£ΓöÇΓöÇΓöÇΓöÇΓöñ          Γö£ΓöÇΓöÇΓöÇΓöÇΓöñ   Root   Γö£ΓöÇΓöÇΓöÇΓöÇΓöñ          Γöé
ΓöéSegment 3 Γöé    ΓöéSegment 1 Γöé    ΓöéSegment C Γöé    ΓöéSegment 2 Γöé    ΓöéSegment B Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                     Γöé               Γöé               Γöé
                     Γöé               Γöé               Γöé
                ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                ΓöéUnchained Γöé    ΓöéUnchained Γöé    ΓöéUnchained Γöé
                ΓöéSegment A Γöé    ΓöéSegment D Γöé    ΓöéSegment B Γöé
                ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                     Γöé
                     Γöé
                ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                ΓöéUnchained Γöé
                ΓöéSegment B Γöé
                ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Chained and Called Segments Reordered Using GpiSetSegmentPriority


ΓòÉΓòÉΓòÉ 12.1.7.1. Segment Priority ΓòÉΓòÉΓòÉ

The priority of a segment, in conjunction with the current foreground and
background mix attributes, affects how the picture is presented to the user.
The segment with the highest priority is drawn last, and appears on top of the
previously drawn primitives. Picture components in segments with low priorities
risk being drawn over and never seen by the user. The mix attributes affect the
graphics functions within each segment.


ΓòÉΓòÉΓòÉ 12.1.7.2. GpiDrawSegment ΓòÉΓòÉΓòÉ

In the figure before the previous figure, Unchained Segment C and its called
segment Unchained Segment D are not part of the segment chain and, therefore,
are not drawn by GpiDrawChain. Both segments can be drawn using GpiDrawSegment
(hps, C).

The function GpiDrawSegment accepts as input any segment name greater than
zero. GpiDrawSegment can draw individual segments both inside and outside the
segment chain. Any segment that is called from the GpiDrawSegment-named segment
also is drawn.


ΓòÉΓòÉΓòÉ 12.1.7.3. GpiDrawFrom ΓòÉΓòÉΓòÉ

You can draw a smaller portion of the entire segment chain (but a larger
portion than a single segment) using GpiDrawFrom. GpiDrawFrom accepts, as
input, a presentation space handle and 2 nonzero segment names, the first of
which must be part of the segment chain. GpiDrawFrom then draws the segments,
starting with the first and ending with the last, including all chained and
called segments. The order in which the segments are drawn is identical to that
of the figure before the previous figure- a root segment, its first-to-last
called segments, then the next root segment.

If the second named segment does not appear between the first segment and the
end of the chain, the drawing begins with the first and continues through the
end of the chain, including all chained and called segments, again with the
drawing order as described in the figure before the previous figure.


ΓòÉΓòÉΓòÉ 12.1.8. Attribute Modes ΓòÉΓòÉΓòÉ

You can change primitive-attribute settings at any time; the new values you
specify replace the existing values. For example, if the current foreground
color is green and you change it to red, red replaces green as the foreground
color attribute.

When you set primitive attributes within a retained or nonretained segment, you
can save the existing attribute values on a last-in-first-out (LIFO) stack,
from where they can later be retrieved and made current again. You do this by
selecting either of the 2 attribute modes:

o AM_PRESERVE mode-Also known as push-and-set mode
o AM_NOPRESERVE mode-Also known as set mode.

In AM_NOPRESERVE mode, which is the default setting, existing attribute values
are replaced by any new attribute values that you supply. In AM_PRESERVE mode,
the existing attribute values are stored on a LIFO stack; then, the new values
that you specify take effect. AM_PRESERVE mode also causes the current position
to be saved if the position was specified using GpiSetCurrentPosition. If you
use GpiMove to set the current position, the position is not saved, regardless
of the attribute mode. Those attributes that are affected by the current
attribute mode are listed in the Presentation Manager Programming Reference.

To select a current attribute mode, use GpiSetAttrMode. The current attribute
mode affects subsequent attribute-setting requests in the presentation space.
Attribute modes are not applicable to micro presentation spaces, because
graphics segments can be created only in normal presentation spaces.

To retrieve an attribute value from the LIFO stack, use GpiPop, which pulls
back the attribute that was stored most recently on the stack.  You can
retrieve more than one attribute value by supplying a number as an input
parameter of this function. For example, if you specify 4, GpiPop retrieves the
4 attributes that were most recently stored on the stack. If each of the values
retrieved applies the same type of attribute to the same primitive (for
example, if all four are line-type settings), the last one to be retrieved
(and, therefore, the first one on the stack) becomes the current setting.

If you save attribute values from any segment called from another segment, and
do not retrieve the values using GpiPop, the values are restored automatically
when the end of the segment is reached. If you save attribute values from any
segment that is not called from another segment, and do not explicitly restore
those values using GpiPop, they are lost at the end of the segment.

The AM_PRESERVE mode is useful when you do not want attributes in calling
segments to be overwritten by attributes specified in the called segments. This
overwritting happens because a calling segment and the segments it calls are
logically one object. Attribute changes within a called segment remain current
upon return to the calling segment. If you set some attribute values at the
start of a called segment, and the current attribute mode is AM_PRESERVE, the
attribute values of the calling segment are stored on the LIFO stack. At the
end of the called segment, the values on the stack are retrieved automatically
so that the calling segment continues with its own attribute values.


ΓòÉΓòÉΓòÉ 12.1.9. Reusing the Presentation Space ΓòÉΓòÉΓòÉ

A normal presentation space with segments retained in the segment store can be
costly in terms of storage. Therefore, delete any presentation space that you
no longer need, using GpiDestroyPS. If for example, your application is using a
series of presentation spaces, each with a different format, the creation and
deletion activity also can be costly. The PM programming interface provides the
following functions that let you reuse or redefine an existing presentation
space; so you can create a presentation space once, and use it any number of
times.

o GpiSavePS
o GpiRestorePS
o GpiResetPS
o GpiSetPS.


ΓòÉΓòÉΓòÉ 12.1.9.1. GpiSavePS ΓòÉΓòÉΓòÉ

GpiSavePS saves presentation space information (such as current primitive
attributes and the current position) on a dedicated LIFO stack. The
presentation space itself is unchanged; that is, it still exists, has the same
presentation space handle, and the presentation page dimensions and format are
the same.

Output from GpiSavePS is a number that identifies the saved information on the
LIFO stack. An output of 3, for example, tells you that this is the third lot
of presentation space data on the stack.


ΓòÉΓòÉΓòÉ 12.1.9.2. GpiRestorePS ΓòÉΓòÉΓòÉ

GpiRestorePS retrieves the saved information from the LIFO stack and reapplies
it to the presentation space. Input to this function can be either the
identifier returned to you from GpiSavePS or a relative value. A relative value
of -1, for example, retrieves the information most recently stored on the
stack. You do not have to restore the information that was most recently saved;
however, any data that you skip over is discarded.

A LIFO Stack with Four Items

For example, if there are four items of data on the stack, as shown in the
previous figure, and you request the restoration of item 2, items 3 and 4 are
discarded. Item 1 is the only item remaining on the stack.

You can restore item 2 by specifying either an absolute value of 2, or a
relative value of -3. The relative value depends on the number of items
currently in the stack.  The contents of the LIFO stack are purged whenever
GpiAssociate is called.


ΓòÉΓòÉΓòÉ 12.1.9.3. GpiResetPS ΓòÉΓòÉΓòÉ

When a presentation space is first created, it is in a neutral state. Current
attributes are set to their initial default values; the current position is
(0,0); the segment store contains no segments; and, there are no
application-defined resources, such as logical color tables.  You can return an
existing presentation space to this state using GpiResetPS.  GpiResetPS has 3
levels of reset activity, each more powerful than the last. These are:

 1. GRES_ATTRS, which is equivalent to the processing done by GpiCloseSegment.

 2. GRES_SEGMENTS, which is equivalent to creating a new presentation space,
    but without deleting any logical resources. All retained segments are
    deleted from the segment store.

 3. GRES_ALL, which is equivalent to creating a new presentation space.

GpiResetPS does not alter the size or format of the presentation page.


ΓòÉΓòÉΓòÉ 12.1.9.4. GpiSetPS ΓòÉΓòÉΓòÉ

GpiSetPS redefines the size and format of the presentation page. The processing
performed when you call GpiSetPS is similar to that performed by GpiCreatePS,
except that the presentation space already exists. The presentation space is
returned to a neutral state (which is the equivalent of requesting GRES_ALL
using GpiResetPS), and the presentation page is redefined. For example, you can
change a presentation page defined in 0.01mm units to one defined in pels.
Essentially, this lets you work with an new presentation space without having
to delete one and create another.

You also can use GpiSetPS to change the current mapping mode of a presentation
space. To do this, use the PS_NORESET flag, which is the equivalent of
requesting GRES_SEGMENTS using GpiResetPS. This feature is particularly useful
if you are designing an application that deals with page layout and drafting,
or if you want the screen size to correspond to the page size for the printed
output.


ΓòÉΓòÉΓòÉ 12.1.10. Nonretained Graphic Segments ΓòÉΓòÉΓòÉ

It is valid segment construction to create a segment bracket while the drawing
mode is DM_DRAW. The GPI functions contained within the bracket are drawn
immediately rather than being retained for future use; thus, this type of
segment is called a nonretained segment.

Because the usual reason for constructing segments is to take advantage of
retained graphics, nonretained segments might appear as a contradiction in
terms at first. However, there are four  particular advantages in their use:

o If ATTR_FASTCHAIN is set to OFF, the GpiOpenSegment implicitly resets all
  attributes to their defaults.

o The GpiOpenSegment and GpiCloseSegment initialize and reset the viewing
  transform matrix, just as they do for retained segments.

o Nonretained segments can be recorded in a metafile, just as a retained
  segment can.

o A graphic in a nonretained segment, with a unique name, can be converted
  easily to a retained graphic for future use.


ΓòÉΓòÉΓòÉ 12.2. Using Segment Creating and Drawing Functions ΓòÉΓòÉΓòÉ

You can use retained-drawing and segment functions to:

o Create a chained or called segment
o Draw the picture associated with one or more segments.


ΓòÉΓòÉΓòÉ 12.2.1. Creating a Chained Segment ΓòÉΓòÉΓòÉ

To create a chained segment, you must:

 1. Set the drawing mode to DM_RETAIN.

 2. Check to see if the chained attribute is one of the initial segment
    attributes using GpiQueryInitialSegmentAttrs.

 3. Set the chained attribute, if necessary, with GpiSetInitialSegmentAttrs.

 4. Open the segment using GpiOpenSegment.

 5. Perform the necessary drawing operations.

 6. Close the segment using GpiCloseSegment.

The following figure is an example of a segment containing a box primitive and
calling another segment using GpiCallSegmentMatrix.

#define INCL_GPISEGMENTS
#define INCL_GPITRANSFORMS
#include <os2.h>
void fncSEGS01(void){
    POINTL ptl;
    HPS hps;
    LONG idSegment    = 1;
    LONG idNonChained = 2;
    MATRIXLF matlfTransform = { MAKEFIXED(2,0), MAKEFIXED(0,0), 0,
                                MAKEFIXED(0,0), MAKEFIXED(1,0), 0,
                                0, 0, 1 };

    /************************************************************************/
    /* Turns chaining on. Adds the new segment to the segment chain.        */
    /* Segment idNonChained is called, whether chained or not.              */
    /************************************************************************/

    if (ATTR_OFF == GpiQueryInitialSegmentAttrs(hps, ATTR_CHAINED)
        GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_ON);
    GpiOpenSegment(hps, idSegment);
    ptl.x = 150; ptl.y = 150;
    GpiMove(hps, &ptl);
    ptl.x = 225; ptl.y = 225;
    GpiBox(hps, DRO_FILL, &ptl, 0L, 0L);
    GpiCallSegmentMatrix(hps, idNonChained, 9L, &matlfTransform,
        TRANSFORM_REPLACE);
    GpiCloseSegment(hps);
} /* fncSEGS01 */


Creating a Chained Graphics Segment


ΓòÉΓòÉΓòÉ 12.2.2. Creating a Called Segment ΓòÉΓòÉΓòÉ

To create a called segment, you must:

 1. Set the drawing mode to DM_RETAIN.

 2. Check to see whether the chained attribute is one of the initial segment
    attributes using GpiQueryInitialSegmentAttrs.

 3. Set the chained attribute, if necessary, with GpiSetInitialSegmentAttrs.

 4. Open the segment using GpiOpenSegment.

 5. Perform the necessary drawing operations.

 6. Close the segment using GpiCloseSegment.

The following figure shows an example of how to draw a box in a called segment.

#define INCL_GPISEGMENTS
#define INCL_GPICONTROL
#include <os2.h>
void fncSEGS02(void){
    POINTL ptl;
    HPS hps;
    LONG idNonChained = 2;

    GpiSetDrawingMode(hps, DM_RETAIN);

    /* Creates a non-chained segment. */

    if (ATTR_ON == GpiQueryInitialSegmentAttrs(hps, ATTR_CHAINED))
        GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_OFF);
    GpiOpenSegment(hps, idNonChained);
    ptl.x = 100;
    ptl.y = 100;
    GpiMove(hps, &ptl);
    ptl.x = 200;
    ptl.y = 200;
    GpiLine(hps, &ptl);
    GpiCloseSegment(hps);
} /* fncSEGS02 */


Creating a Called Graphics Segment


ΓòÉΓòÉΓòÉ 12.2.3. Drawing a Segment Chain ΓòÉΓòÉΓòÉ

The following figure shows an example of how to draw a segment chain using the
GpiDrawChain function.

#define INCL_GPICONTROL
#include <os2.h>
void fncSEGS03(void){
    HPS hps;

    if (DM_DRAW != GpiQueryDrawingMode(hps))
        GpiSetDrawingMode(hps, DM_DRAW);
    GpiDrawChain(hps);
} /* fncSEGS03 */


Drawing a Segment Chain


ΓòÉΓòÉΓòÉ 12.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the functions used to create and draw retained
graphics and segments.

Retained Graphics and Segment Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name               ΓöéDescription                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCallSegmentMatrix        ΓöéConcatenates the contents of an Γöé
Γöé                            Γöéunchained segment bracket onto  Γöé
Γöé                            Γöéanother chained or unchained    Γöé
Γöé                            Γöésegment bracket.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCloseSegment             ΓöéDefines the end of a segment    Γöé
Γöé                            Γöébracket.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawChain                ΓöéDraws the subpictures stored in Γöé
Γöé                            Γöéa presentation space segment    Γöé
Γöé                            Γöéchain.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawFrom                 ΓöéDraws the subpictures from a    Γöé
Γöé                            Γöéspecified range of segments in  Γöé
Γöé                            Γöéthe segment chain.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawSegment              ΓöéDraws a subpicture from a singleΓöé
Γöé                            Γöésegment.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOpenSegment              ΓöéDefines the beginning of a      Γöé
Γöé                            Γöésegment bracket.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryInitialSegmentAttrs ΓöéRetrieves the setting of 1 of   Γöé
Γöé                            Γöéthe 7 initial segment           Γöé
Γöé                            Γöéattributes.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentAttrs        ΓöéRetrieves the setting of 1 of   Γöé
Γöé                            Γöéthe 7 segment attributes.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentNames        ΓöéRetrieves a list of existing    Γöé
Γöé                            Γöésegment identifiers within a    Γöé
Γöé                            Γöéspecified range.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentPriority     ΓöéReturns the identifier for a    Γöé
Γöé                            Γöésegment that precedes or followsΓöé
Γöé                            Γöéa segment in the segment chain. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDrawingMode           ΓöéSets the drawing mode in your   Γöé
Γöé                            Γöépresentation space to 1 of 3    Γöé
Γöé                            Γöépossible modes: draw, retain, orΓöé
Γöé                            Γöédraw-and-retain.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetInitialSegmentAttrs   ΓöéSets the default segment        Γöé
Γöé                            Γöéattributes.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetSegmentAttrs          ΓöéSets 1 of the 7 segment         Γöé
Γöé                            Γöéattributes.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetSegmentPriority       ΓöéAlters the order in which the   Γöé
Γöé                            Γöéoperating system draws and      Γöé
Γöé                            Γöédetects segments in the segment Γöé
Γöé                            Γöéchain.                          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 13. Editing Retained Graphics and Graphics Segments ΓòÉΓòÉΓòÉ

This chapter describes editing retained graphics and graphics segments. The
following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Coordinate spaces
o Transformations
o Creating segments.


ΓòÉΓòÉΓòÉ 13.1. About Editing Retained Graphics and Graphics Segments ΓòÉΓòÉΓòÉ

In the OS/2 operating system, applications store retained graphics in segments.
One of the advantages of using graphics segments is that segments can be
edited, which allows the retained image to be modified without having to
re-create the unmodified portion with multiple GPI functions.

Creating and Drawing Retained Graphics described how to create a segment, and
store GPI functions within the segment bracket. To understand how to edit a
segment, the underlying structure of a segment is described here in greater
detail.

The GPI functions are not inserted directly into a segment bracket. Instead,
the operating system converts the GPI functions into graphics orders; then
stores these orders in the GpiOpenSegment-GpiCloseSegment bracket.

Generally, each of the GPI functions within the segment bracket generates one
element of the segment. An element is the smallest portion of a segment that
can be edited and is made up of one or more orders. A graphics order, also
known as a drawing order, is the smallest, complete portion of a segment. The
following figure illustrates the levels of graphic segment construction.


GpiOpenSegment (...);    Graphic Segment
                        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ              element
GpiLine (...);          Γöé line order            Γöé element 0   pointer
                        Γöé                       Γöé
GpiBeginElement (...);  Γöé begin element order   Γöé element 1
                        Γöé                       Γöé
   GpiBox (...);        Γöé       box order       Γöé
   GpiPolyline (...);   Γöé       polyline order  Γöé
                        Γöé                       Γöé
GpiCloseElement (...);  Γöé end element order     Γöé
                        Γöé                       Γöé
GpiLabel (...);         Γöé label order           Γöé element 2
                        Γöé                       Γöé
GpiSetColor (...);      Γöé set-color order       Γöé element 3
                        ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
GpiEndSegment (...);

Structure of a Graphics Segment

Elements 0, 2, and 3 are each composed of a single order. Element 1 is composed
of two orders bracketed by GpiBeginElement and GpiEndElement.


ΓòÉΓòÉΓòÉ 13.1.1. Graphics Orders ΓòÉΓòÉΓòÉ

A graphics order is a low-level graphics command that corresponds to a
primitive function or attribute. In addition to code and data requirements,
each graphics order uses approximately 11 bytes of storage. An application that
uses 2000 graphics drawing orders will use around 22KB of memory to store them.
The following table describes the four sizes of graphics orders.

Graphics Orders

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéGraphics Order Size     ΓöéContent                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1 byte                  ΓöéA hexadecimal identifier            Γöé
Γöé                        Γöécorresponding to a drawing function Γöé
Γöé                        Γöéor attribute function. This         Γöé
Γöé                        Γöéidentifier is also known as the     Γöé
Γöé                        Γöéorder code.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé2 byte                  ΓöéThe order code is in the first byte,Γöé
Γöé                        Γöéand data is in the second byte.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLong                    ΓöéThe order code is in the first byte.Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéThe length value of the actual data,Γöé
Γöé                        Γöéin bytes, is in the second byte.    Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéThe actual data (up to 255 bytes).  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVery long               ΓöéA hexadecimal identifier            Γöé
Γöé(maximum length of 64KB)Γöéspecifically for extended orders, isΓöé
Γöé                        Γöéin the first byte.                  Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéThe order code is in the second     Γöé
Γöé                        Γöébyte.                               Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéA length value that specifies how   Γöé
Γöé                        Γöémany bytes are used by the          Γöé
Γöé                        Γöégraphics-order arguments, (high     Γöé
Γöé                        Γöéorder) is in the third byte.        Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéA length value that specifies how   Γöé
Γöé                        Γöémany bytes are used by the          Γöé
Γöé                        Γöégraphics-order arguments, (low      Γöé
Γöé                        Γöéorder) is in the fourth byte.       Γöé
Γöé                        Γöé                                    Γöé
Γöé                        ΓöéThe actual data.                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following example shows a long graphics order that corresponds to the
GpiLine function:

    81 8 100 0 0 0 100 0 0 0

The first number, 81, is the hexadecimal identifier that corresponds to
GpiLine. The second number, 8, is the length value that specifies how many
bytes are used by the graphics-order arguments. The next 8 bytes contain the
arguments for GpiLine. In this case, the arguments specify the line's end point
at (100,100).



                               Graphics
                               Segment
                                      Γöé
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  ΓöîΓöÇΓöÇ  0x21  Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ order # ΓöÇΓöÇΓöÉ
Γöé                      Γöé  Γöé     0x08  Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ length    Γöé
Γöé ptl.x = 100L;        Γöé  Γöé     0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ               Γöé
Γöé ptl.y = 100L;        Γöé  Γöé     0x00  Γöé     Γö£ΓöÇΓöÇ      x      Γöé
Γöé GpiMove (hps, &ptl); Γö╝ΓöÇΓöÇΓöÿ     0x10  Γöé     Γöé               Γö£ΓöÇΓöÇ  element
Γöé ptl.x = 200L;        Γöé        0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ               Γöé
Γöé ptl.y = 400L;        Γöé        0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ               Γöé
Γöé GpiMove (hps, &ptl); Γö╝ΓöÇΓöÇΓöÉ     0x00  Γöé     Γö£ΓöÇΓöÇ      y      Γöé
Γöé                      Γöé  Γöé     0x20  Γöé     Γöé               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé     0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ             ΓöÇΓöÇΓöÿ
                          ΓööΓöÇΓöÇ  0x81  Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ order # ΓöÇΓöÇΓöÉ
                                0x08  Γö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ length    Γöé
                                0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ               Γöé
                                0x00  Γöé     Γö£ΓöÇΓöÇ      x      Γöé
                                0x30  Γöé     Γöé               Γö£ΓöÇΓöÇ  element
                                0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ               Γöé
                                0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÉ               Γöé
                                0x00  Γöé     Γö£ΓöÇΓöÇ      y      Γöé
                                0x40  Γöé     Γöé               Γöé
                                0x00  Γöé ΓöÇΓöÇΓöÇΓöÇΓöÿ             ΓöÇΓöÇΓöÿ
                                      Γöé


Graphics Orders

The encoding that appears in the Graphics Segments column is a hexadecimal
version of the order, length, and parameter information. The GPIs and their
corresponding graphics orders are listed in Presentation Manager Programming
Reference.

In most cases, graphics orders in a segment correspond to a subpicture, which
is part of a complete, more complex picture. Your application would combine the
individual segments to form the complete picture.

Three drawing modes affect how the operating system stores graphics orders in
segments. These modes are described in the following table. The default drawing
mode is draw. To specify another as the current drawing mode, use
GpiSetDrawingMode.

The actual drawing mode is a combination of the drawing mode as set using
GpiSetDrawingMode, and the segment status-chained, unchained, or outside of the
segment. A previos table describes the actual drawing mode. The actual drawing
mode does not effect the storing of orders in segments.

Segment Graphics Drawing Modes

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode      ΓöéGpiSetDrawingMode ΓöéWhen this mode is set...Γöé
Γöé                  ΓöéValue             Γöé                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw              ΓöéDM_DRAW           Γöéit is not possible to   Γöé
Γöé                  Γöé                  Γöéstore graphics orders inΓöé
Γöé                  Γöé                  Γöéa chained segment.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetain            ΓöéDM_RETAIN         Γöéyour application can    Γöé
Γöé                  Γöé                  Γöéstore graphics orders inΓöé
Γöé                  Γöé                  Γöéchained and unchained   Γöé
Γöé                  Γöé                  Γöésegments.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-and-retain   ΓöéDM_DRAWANDRETAIN  Γöéyour application can    Γöé
Γöé                  Γöé                  Γöéstore graphics orders inΓöé
Γöé                  Γöé                  Γöéchained and unchained   Γöé
Γöé                  Γöé                  Γöésegments.  In this mode,Γöé
Γöé                  Γöé                  Γöéoutput intended for a   Γöé
Γöé                  Γöé                  Γöéchained segment is both Γöé
Γöé                  Γöé                  Γöédrawn on the device and Γöé
Γöé                  Γöé                  Γöéstored in a segment.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 13.1.2. Graphics Elements ΓòÉΓòÉΓòÉ

Graphics elements are composed of either a single graphics order, or a series
of graphic orders that are bracketed by an opening and closing element
function.

The purpose of this element bracket is to allow the addition of a single
element, that comprises more than one graphics order, to a segment. This is
most useful when you know that you will want to retrieve those orders at a
later time, and manipulate them as a group rather than as individual functions.

Note:  There is no reason for enclosing a single GPI function within a
       GpiBeginElement-GpiEndElement bracket, although it is a valid
       construction.

Element brackets also are valid when drawing graphics directly to the output
device, but again, they serve no purpose unless converted to a retained segment
at a later time.

Elements cannot be nested, so two elements cannot begin in succession without
an intervening GpiEndElement request. Certain GPI functions cannot be called
between GpiBeginElement and GpiEndElement.

Element construction is valid only within segments.


ΓòÉΓòÉΓòÉ 13.1.2.1. Adding Elements to a New Segment ΓòÉΓòÉΓòÉ

There are four ways of adding elements to a newly created segment:

o Call one or more GPI functions. Each function generates one element of the
  segment. This is the simplest way of supplying graphics data to a segment.

o Call GpiBeginElement, and follow it with one or more GPI functions. Close the
  element using GpiEndElement. All the GPI functions enclosed within the
  bracket, and the GpiBeginElement, and GpiEndElement functions generate a
  single element of the segment, and therefore occupy a single element-pointer
  position. Subsequently, the graphics orders cannot be accessed individually
  with the element pointer, although the orders can be accessed directly, for
  example, using GpiGetData.

o Call GpiElement. As input, you supply the graphics orders themselves, rather
  than the GPI functions that generate them. No matter how much data you supply
  on this request, it is considered a single element of the segment.

  Multiple orders added to a segment in this way cannot be accessed
  individually using the element pointer, but they can be accessed directly,
  for example, using GpiGetData.

  GpiElement cannot be included within a GpiBeginElement-GpiEndElement bracket.
  The data passed by GpiElement must not include GpiBeginElement and
  GpiEndElement.

o Call GpiPutData. As with GpiElement, supply graphics orders as input. You can
  even include GpiBeginElement and GpiEndElement orders in this data, and thus
  add more than one element to the segment. GpiPutData is useful when there is
  a large amount of data to add to a segment.

  GpiPutData cannot be used if the segment editing mode is set to
  SEGEM_REPLACE. When the segment editing mode is SEGEM_INSERT, the element
  pointer must point to the last element in the current segment.

  GpiPutData is most often used in conjunction with GpiGetData, which copies
  data as a list of drawing orders from a segment to application storage.


ΓòÉΓòÉΓòÉ 13.1.2.2. Element Types ΓòÉΓòÉΓòÉ

Each element that results from a single GPI function has an associated element
type.

The element type is generally the graphics-order code associated with the
graphics order generated by the GPI function, and is supplied by the system.
For example, GpiLine has the element type, OCODE_GCLINE, which identifies it as
a line-drawing request. Your application can determine the current
classification of an element using GpiQueryElementType.

The specific element type for each of the GPI functions are documented in the
Presentation Manager Programming Reference. These types are equivalent to the
graphic order values.

When using GpiElement or GpiBeginElement, you can simultaneously add several
graphics orders to a segment. Those orders become one element of the segment.
You can supply your own classification for these compound elements by supplying
a value for the type parameter of GpiElement or GpiBeginElement in the range of
0x81000000 through 0XFFFFFFFF.

For example, the orders passed by a single GpiElement function could change the
line type to dotted, set the current color to blue, and draw a line. You could
classify this element with a type value that identifies it as a blue dotted
line.

Note:  Element types are used only for classification. They are not used as
       location markers or correlation tags.


ΓòÉΓòÉΓòÉ 13.1.2.3. The Element Pointer ΓòÉΓòÉΓòÉ

Use the element pointer to change the contents of an existing segment.  When
calling GpiOpenSegment, the element pointer is set to 0. The first element that
you add to a newly created segment causes the pointer to be set to 1, and each
subsequent element causes the pointer to be incremented by 1. When a segment is
closed, the element pointer is always reset to 0.

Your application can move the element pointer to a specified value using
GpiSetElementPointer. For example, to address the sixth element in a segment,
set the element pointer to 6.

Your application also can move the element pointer by a specific number, rather
than to a specific number, using GpiOffsetElementPointer. For example, if the
element pointer currently addresses element 3, to move it to element 8, code an
offset of 5 in GpiOffsetElementPointer. The pointer moves backward rather than
forward through the segment. The offset value can be a positive or negative
number.

If the sum of the offset and the current pointer position is less than 0, the
operating system sets the pointer so that it points to position 0. Position 0
precedes the first element in the segment. If the sum of the offset and the
current pointer position is greater than the number of elements in the segment,
the operating system sets the pointer so that it points to the last element in
the segment.

You can determine the current location of the element pointer using
GpiQueryElementPointer. To request the contents of a part of or all of the
elements at the current pointer position, use GpiQueryElement.


ΓòÉΓòÉΓòÉ 13.1.2.4. Labels ΓòÉΓòÉΓòÉ

You can include labels in a segment to make locating particular elements of the
segment easier. If you label an element that is likely to be edited, you can
access that element when necessary, regardless of whether the actual position
of the label-element pair within the segment has changed.

Warning: When editing segments, do not inadvertently insert elements between a
label and the element that follows. Your application will no longer be able to
use certain GPIs correctly. Their default locations and offsets will be
invalid.

A label is only a place-holder or reference point, and is itself an element of
the segment. Labels are long integer values. To include a label in a segment,
use GpiLabel. The following example includes the label 5 in the current
segment, whose segment id is 4.

GpiOpenSegment(hps, 4L);
GpiLabel(hps, 5L);
 .
 .
 .
Your application can set the element pointer to the label position using
GpiSetElementPointerAtLabel, then increment the pointer position to the element
itself using GpiOffsetElementPointer with an offset of 1.

Note:  This example of GPI cannot work properly if your application has allowed
       the insertion of elements between a label and the element that follows
       it.

Labels do not have to be unique. If you do not use unique labels,
GpiSetElementPointerAtLabel positions the element pointer at the first
occurrence of the label, starting from the current pointer position. If the
label is not found between the current pointer position and the end of the
segment, an error condition is raised. Using labels as a navigation aid might
be quicker than scanning the segment for a particular element.

If you do not use labels, you must locate an element before you can change it.
To locate a specific element in a segment, you must repeatedly move the element
pointer using GpiSetElementPointer, then read the contents of the element using
GpiQueryElement. This can be quite a lengthy procedure depending upon the
number of elements in the segment.


ΓòÉΓòÉΓòÉ 13.1.3. Graphics Segments ΓòÉΓòÉΓòÉ

Segments are made up of elements, which are in turn made up of one or more
graphic orders. The previous sections have discussed the properties and
functions for orders and elements. The following sections discuss the
attributes and functions that apply to segments as a whole.

The segment attributes are encoded in a segment prior to the graphics orders
that correspond to GPIs and attributes.


ΓòÉΓòÉΓòÉ 13.1.3.1. Initial Segment Attributes ΓòÉΓòÉΓòÉ

Each segment has a number of characteristics, called attributes that you can
set in accordance with your application's requirements. The attributes of a
segment are quite different from those of a graphics primitive, in that segment
attributes have ON and OFF settings. There are seven segment attributes, each
described in the following table.

Graphic Segment Attributes and Initial Settings

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéAttribute         ΓöéValue               ΓöéIf set...     ΓöéDefault Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéChained           ΓöéATTR_CHAINED        Γöéthe operating ΓöéON      Γöé
Γöé                  Γöé                    Γöésystem adds   Γöé        Γöé
Γöé                  Γöé                    Γöéeach new      Γöé        Γöé
Γöé                  Γöé                    Γöésegment in    Γöé        Γöé
Γöé                  Γöé                    Γöéyour          Γöé        Γöé
Γöé                  Γöé                    Γöéapplication's Γöé        Γöé
Γöé                  Γöé                    Γöépresentation  Γöé        Γöé
Γöé                  Γöé                    Γöéspace to the  Γöé        Γöé
Γöé                  Γöé                    Γöésegment chain.Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFast chain        ΓöéATTR_FASTCHAIN      Γöéthe operating ΓöéON      Γöé
Γöé                  Γöé                    Γöésystem        Γöé        Γöé
Γöé                  Γöé                    Γöéprevents the  Γöé        Γöé
Γöé                  Γöé                    Γöéresetting of  Γöé        Γöé
Γöé                  Γöé                    Γöéprimitive     Γöé        Γöé
Γöé                  Γöé                    Γöéattributes to Γöé        Γöé
Γöé                  Γöé                    Γöétheir default Γöé        Γöé
Γöé                  Γöé                    Γöévalues before Γöé        Γöé
Γöé                  Γöé                    Γöédrawing the   Γöé        Γöé
Γöé                  Γöé                    Γöésegment chain.Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDynamic           ΓöéATTR_DYNAMIC        Γöéthe operating ΓöéOFF     Γöé
Γöé                  Γöé                    Γöésystem draws  Γöé        Γöé
Γöé                  Γöé                    Γöésegment outputΓöé        Γöé
Γöé                  Γöé                    Γöéby using the  Γöé        Γöé
Γöé                  Γöé                    ΓöéXOR raster    Γöé        Γöé
Γöé                  Γöé                    Γöéoperation.    Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDetectable        ΓöéATTR_DETECTABLE     Γöéyour          ΓöéOFF     Γöé
Γöé                  Γöé                    Γöéapplication   Γöé        Γöé
Γöé                  Γöé                    Γöécan perform   Γöé        Γöé
Γöé                  Γöé                    Γöécorrelation   Γöé        Γöé
Γöé                  Γöé                    Γöéoperations on Γöé        Γöé
Γöé                  Γöé                    Γöésegments      Γöé        Γöé
Γöé                  Γöé                    Γöécreated in    Γöé        Γöé
Γöé                  Γöé                    Γöéthis          Γöé        Γöé
Γöé                  Γöé                    Γöépresentation  Γöé        Γöé
Γöé                  Γöé                    Γöéspace.        Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPropagate         ΓöéATTR_PROP_DETECTABLEΓöéthe detectableΓöéON      Γöé
Γöédetectable        Γöé                    Γöéattribute willΓöé        Γöé
Γöé                  Γöé                    Γöébe set in eachΓöé        Γöé
Γöé                  Γöé                    Γöésegment calledΓöé        Γöé
Γöé                  Γöé                    Γöéby a chained  Γöé        Γöé
Γöé                  Γöé                    Γöésegment.      Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVisible           ΓöéATTR_VISIBLE        ΓöéGpiDrawChain, ΓöéON      Γöé
Γöé                  Γöé                    ΓöéGpiDrawFrom,  Γöé        Γöé
Γöé                  Γöé                    Γöéand           Γöé        Γöé
Γöé                  Γöé                    ΓöéGpiDrawSegmentΓöé        Γöé
Γöé                  Γöé                    Γöéwill generate Γöé        Γöé
Γöé                  Γöé                    Γöéoutput on a   Γöé        Γöé
Γöé                  Γöé                    Γöédevice.       Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPropagate visible ΓöéATTR_PROP_VISIBLE   ΓöéThe visible   ΓöéON      Γöé
Γöé                  Γöé                    Γöéattribute willΓöé        Γöé
Γöé                  Γöé                    Γöébe set in eachΓöé        Γöé
Γöé                  Γöé                    Γöésegment calledΓöé        Γöé
Γöé                  Γöé                    Γöéby a chained  Γöé        Γöé
Γöé                  Γöé                    Γöésegment.      Γöé        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

When an application creates a segment in a presentation space, the operating
system assigns initial attributes to it. By default, five of the attributes
will be set ON and two will be set OFF. Your application can override the
defaults for all subsequently created segments within the presentation space
using GpiSetInitialSegmentAttrs.

Use GpiQueryInitialSegmentAttrs, to retrieve the values of the current initial
attributes.

Note:  The chained and fast-chained attributes are discussed in Chained
       Attribute and Fast-Chained Attribute.


ΓòÉΓòÉΓòÉ 13.1.3.2. The Dynamic Attribute ΓòÉΓòÉΓòÉ

Dynamic segments are graphics segments that can be moved from where they were
drawn on the screen to a different coordinate position, or altered in some
other way, without affecting the remaining part of the picture. The new
position of a dynamic segment can be provided with an input device, such as a
mouse, or it can be application-generated.

The dynamic attribute is set to OFF by default. The setting is always inherited
by called segments from the setting of their callers. Thus, if a calling
segment is nondynamic, any segments called by it are also nondynamic,
regardless of how they have been defined. If the calling segment is dynamic,
all segments called by it are also dynamic. Any segment explicitly defined as
dynamic must have a unique name, and it cannot be created when the current
drawing-mode parameter is DM_DRAW or DM_DRAWANDRETAIN. Although no error
condition is raised if you define an unchained segment as dynamic, it is not
treated as dynamic unless the segment is called from a dynamic root segment.

Graphics objects to be moved without disturbing the remaining contents of the
display are drawn in exclusive-OR mode. Segments that you define as dynamic
always are drawn in exclusive-OR mode, regardless of the current mix attribute
settings and any GpiSetMix functions the segment itself might contain.

For performance reasons, dynamic segments are to be grouped at the start of the
picture chain. There are GPI functions that handle dynamic segments as a group,
so it is more efficient if the entire segment chain does not have to be scanned
to locate them.

When the entire picture chain is drawn, however, dynamic segments are to be
drawn after all other segments in the chain to ensure that the effects of
drawing in exclusive-OR mode are not adversely affected by drawings in other
mix modes. Also, you must ensure that no nondynamic drawing overlays the
dynamic segments after they have been drawn. The PM programming interface
ensures that dynamic segments are always drawn on top of other graphics.


ΓòÉΓòÉΓòÉ 13.1.3.3. The Detectability Attribute ΓòÉΓòÉΓòÉ

The detectability attribute of a segment determines if that segment can be
selected with an input device, such as a mouse. A segment with this attribute
is said to be selectable. Selectable segments can be selected for correlation
operations. The detectability attribute is set OFF by default. All detectable
segments must have unique names. If you define a zero segment as detectable, it
is created as nondetectable.


ΓòÉΓòÉΓòÉ 13.1.3.4. The Propagate-Detectability Attribute ΓòÉΓòÉΓòÉ

This attribute controls whether the detectability attribute of a calling
segment is inherited by any segments called from it. The
propagate-detectability attribute is set ON by default. This value overrides
the detectability setting of the called segment. For example, if you set the
detectability attribute of a calling segment to OFF, all segments called from
it are nondetectable, regardless of how they have been defined.


ΓòÉΓòÉΓòÉ 13.1.3.5. The Visibility Attribute ΓòÉΓòÉΓòÉ

The visibility attribute controls whether a segment is to be visible on an
output device. The contents of a segment that is not defined with the
visibility attribute set ON are still executed whenever the segment is drawn.
This can cause changes to the current position and to current attribute values,
even though the primitives themselves are not visible on the output device. The
visibility attribute is set ON by default.


ΓòÉΓòÉΓòÉ 13.1.3.6. The Propagate-Visibility Attribute ΓòÉΓòÉΓòÉ

This attribute controls whether the visibility attribute of a calling segment
is inherited by any segments called from it. The propagate-visibility attribute
is set ON by default. This value overrides the visibility setting of the called
segment. For example, if the visibility attribute of a calling segment is set
to OFF, all segments called from it are invisible, regardless of how they have
been defined.


ΓòÉΓòÉΓòÉ 13.1.4. Changing the Attributes of a Segment ΓòÉΓòÉΓòÉ

After you create a segment, you might need to alter its attributes. For
example, if you created a segment using the default attributes and you want to
perform a correlation operation on the subpicture in that segment, you will
need to set the detectable attribute using GpiSetSegmentAttrs. You can retrieve
the values of the attributes for any segment using GpiQuerySegmentAttrs.

You can change the default segment-attribute settings globally for a single
presentation space using GpiSetInitialSegmentAttrs. The attribute setting that
you specify in this function applies to all segments created subsequently in
that presentation space, except that a nonretained segment can never have the
dynamic attribute. For example, if you want all segments to be detectable, you
can call this function to change the setting for all of them before you create
them. GpiSetInitialSegmentAttrs cannot be used to change the attributes of
existing segments.

You also can change the attributes of any single retained segment, but not
those created subsequently, using GpiSetSegmentAttrs. This is useful if, for
example, you want most of the segments in a picture chain to be detectable. You
can change the attribute setting to detectable for the entire chain, before
creating it, using GpiSetInitialSegmentAttrs; then, change the attribute to
nondetectable for each of the segment exceptions using GpiSetSegmentAttrs. You
can also use GpiSetSegmentAttrs, for example, to make a visible segment
invisible when an erase request is received from the operator, or to take a
segment out of the chain by redefining it as unchained. If you change an
unchained segment to chained, it is added to the end of the segment chain.  If
you want the newly chained segment to be positioned elsewhere in the chain, use
GpiSetSegmentPriority rather than GpiSetSegmentAttrs.

Some of these segment attributes apply equally to primitives that are outside
of segments, although their default settings cannot be changed. Primitives
outside of segments are always detectable and visible. They cannot be dynamic,
because the dynamic attribute applies only to retained graphics. The chained
and fast-chaining attributes do not apply to primitives outside of segments.


ΓòÉΓòÉΓòÉ 13.1.5. Editing a Segment ΓòÉΓòÉΓòÉ

The operating system provides segment editing functions for writing
applications that allow users to edit segments or elements in a segment. For
example, after performing a correlation operation using your application, a
user might need to alter the elements that intersected the pick aperture.
Correlation and the pick aperture are explained in Correlation.

You can edit the contents of any retained segment that has a unique name. You
also can edit the contents of a retained zero segment that has not yet been
closed. Zero segments cannot be edited after they have been closed, because you
cannot refer to a zero segment when it is no longer the current open segment.

Before you can begin editing, you must set the current drawing-mode parameter
to DM_RETAIN. You cannot edit a segment if the current drawing-mode parameter
is DM_DRAWANDRETAIN or DM_DRAW. To begin editing, call GpiOpenSegment and
specify the name of the segment you want to edit. When you are finished editing
a segment, close it using GpiCloseSegment.

The operating system has two edit modes: insert mode and replace mode. You can
set the edit modes using GpiSetEditMode. You can determine which mode is
currently set using GpiQueryEditMode.

The current edit mode applies to all segments in the presentation space until
you change it. The edit mode is not an attribute of a particular segment and
can be changed at any time. The default edit mode, which is set when you create
a presentation space, is insert mode. When you create a graphics segment, you
are actually editing it in insert mode.

If the edit mode is set to insert (SEGEM_INSERT) you can insert an element at
the current location of the element pointer. The operating system shifts the
element that was previously at that location into the next slot, and so on,
until the last element is shifted into a new, final slot. The following figure
shows a segment before and after a new element is inserted at position 0, the
beginning of the segment.

            Original Segment                         New Segment
                                Element Pointer
            ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ     Γöé             Γöé      ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Position 0  Γöé             ΓöéΓöÇΓöÇΓöÇΓöÇΓöÿ             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöé             Γöé
            Γöé             Γöé                          Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 1  Γöé  Element 1  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ      Γöé New element Γöé
            Γöé             Γöé                   Γöé      Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                   Γöé      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 2  Γöé  Element 2  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇΓöé  Element 1  Γöé
            Γöé             Γöé                 Γöé        Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                 Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 3  Γöé  Element 3  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 2  Γöé
            Γöé             Γöé               Γöé          Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ               Γöé          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 4  Γöé  Element 4  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 3  Γöé
            Γöé             Γöé             Γöé            Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ             Γöé            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 5  Γöé  Element 5  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 4  Γöé
            Γöé             Γöé           Γöé              Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ           Γöé              Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 6  Γöé  Element 6  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 5  Γöé
            Γöé             Γöé         Γöé                Γöé             Γöé
            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ         Γöé                Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 7  Γöé  Element 7  ΓöéΓöÇ ΓöÇ ΓöÇ ΓöÇΓöÉ ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 6  Γöé
            Γöé             Γöé       Γöé                  Γöé             Γöé
            ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ       Γöé                  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                                  ΓööΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇ ΓöÇΓöé  Element 7  Γöé
                                                     Γöé             Γöé
                                                     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

segments, inserting new elements

The new element is inserted after the current element; then, the element
pointer is set to the new element.

If replace mode is set (SEGEM_REPLACE) you can replace the element at the
current pointer location with a new element. The following figure shows a
segment before and after the third element was replaced.


           Original Segment                         New Segment
           ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Position 0 Γöé             Γöé                          Γöé             Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 1 Γöé  Element 1  Γöé                          Γöé  Element 1  Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 2 Γöé  Element 2  Γöé                          Γöé  Element 2  Γöé
           Γöé             Γöé     Element pointer      Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ     Γöé             Γöé      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 3 Γöé  Element 3  ΓöéΓöÇΓöÇΓöÇΓöÇΓöÿ             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöé  Element 3  Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 4 Γöé  Element 4  Γöé                          Γöé  Element 4  Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 5 Γöé  Element 5  Γöé                          Γöé  Element 5  Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 6 Γöé  Element 6  Γöé                          Γöé  Element 6  Γöé
           Γöé             Γöé                          Γöé             Γöé
           Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ                          Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Position 7 Γöé  Element 7  Γöé                          Γöé  Element 7  Γöé
           Γöé             Γöé                          Γöé             Γöé
           ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ                          ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Replacing an Element with a New Element

The new element overwrites the previous element; the element pointer does not
change.

Replacing elements is the recommended technique for redrawing identical
primitives with different attributes, for example, color.

You can insert or replace data in an existing segment using any of the
functions described in Adding Elements to a New Segment. As mentioned
previously, GpiPutData is valid only in insert mode; and, only when the element
pointer is addressing the final element in the segment. That is, when you are
editing, you can use GpiPutData only to add data to the end of a segment.

A replace request is not valid when the element pointer is set to 0. If you
call GpiOpenSegment to create a new segment without first ensuring that the
current edit mode is insert, your first attempt to add an element to the
segment might cause an error condition to be raised.


ΓòÉΓòÉΓòÉ 13.1.5.1. Deleting a Graphics Element ΓòÉΓòÉΓòÉ

The PM programming interface has three different functions that allow you to
delete elements within the currently opened segment.

Function                 Description

GpiDeleteElement         Deletes a single element at the current element
                         pointer location.

GpiDeleteElementRange    Deletes a range of elements in a segment.

GpiDeleteElementsBetweenLabels Deletes a series of elements between two labels.

When you remove an element from a segment, the element pointer addresses the
element immediately before the one you deleted. As with other editing
functions, the current drawing mode parameter must be DM_RETAIN when you are
deleting elements. The current editing mode (insert or replace) has no effect
on the delete functions.


ΓòÉΓòÉΓòÉ 13.1.5.2. Deleting Graphics Segments ΓòÉΓòÉΓòÉ

When you have finished drawing the subpicture associated with a segment, you
should delete the segment. The PM programming interface has two different
functions that allow you to delete segments.

Function                 Description

GpiDeleteSegment         Deletes a retained segment

GpiDeleteSegments        Deletes a range of retained segments.

Your application can only delete segments that have unique names; because, you
use the segment identifiers to identify the segment or range of segments for
deletion. Retained zero segments cannot be deleted. They disappear only when
their associated presentation space is deleted or reset. The presentation space
can be reset either by GpiResetPS with the GRES_SEGMENTS flag or the GRES_ALL
flag set, or by GpiSetPS. Resetting the presentation space is described in
Reusing the Presentation Space.

If GpiDeleteSement occurs within a segment bracket and the segment identified
is the currently open segment, the operating system deletes the segment and
ignores the remainder of the functions up to, and including, GpiCloseSegment.
If GpiDeleteSegment occurs within a segment bracket and the identifier for a
segment other than the currently open segment, the operating system deletes the
segment, then continues processing the remaining functions in the segment
bracket. If GpiDeleteSegment occurs outside of a segment and references a
segment in the segment chain, the operating system removes the segment from the
chain and links the two adjacent segments, if such segments exist.

If the range of segments deleted by GpiDeleteSegments were in the segment
chain, the operating system "repairs" the chain by linking the segments
immediately preceding and following the deleted segments, if such segments
exist.


ΓòÉΓòÉΓòÉ 13.1.5.3. Copying a Single Graphics Element ΓòÉΓòÉΓòÉ

Your application can copy the graphics orders from a single element using the
GpiQueryElement and GpiElement functions. GpiQueryElement copies the graphics
orders (or part of the orders, depending on allocated size) from an element
into an array of bytes. GpiQueryElement is not valid within an element bracket,
nor if the drawing mode is other than DM_RETAIN.

GpiElement copies the data from the array back into the current segment. The
data may not contain any begin or end element orders. GpiElement is not valid
within an element bracket. The element is retained if the drawing mode is
DM_RETAIN; and drawn if the mode is either DM_DRAW, or DM_DRAWANDRETAIN.


ΓòÉΓòÉΓòÉ 13.1.5.4. Copying Multiple Graphics Elements ΓòÉΓòÉΓòÉ

Your application can use GpiGetData and GpiPutData to:

o Copy elements from one segment to another

o Copy elements from one position in a segment to another position in the same
  segment.

GpiGetData copies a buffer of graphics orders from a named segment, into an
area of application storage, whose byte size you specify on input. Only the
named segment must not be open when you call this function. The named segment
is also known as the source segment.

The first time GpiGetData is called, data retrieval has to start at the
beginning of the segment. This is done by declaring an element offset of 0.

Output from GpiGetData depends on whether the area of application storage is
large enough to hold the entire buffer of graphics orders. If so, the buffer is
returned along with a count of the number of bytes of data returned to you from
the segment. If not, the application storage is filled, and the count is set to
the size of the application storage.  The offset of the element where
GpiGetData stopped copying, and the count are returned. Your application can
then determine if a subsequent GpiGetData needs to be called, by checking that
the count is less than the size (length) of the application storage.

On subsequent GpiGetData functions, the element offset can be 0, or it can be
the offset value that was returned from the previous function. In this manner,
if your application calls GpiGetData more than once to copy an entire segment,
it can "pick up where it left off", rather than recopying the segment from the
beginning each time.

You can copy the data from the application storage to a new location in a
segment using GpiPutData. This receiving segment is also known as the
destination segment. The segment into which you are copying the data can be
open when you call GpiPutData.

If GpiGetData does not retrieve a complete segment, the data it does retrieve
can be written out to the second segment using GpiPutData, even if the last
order copied is incomplete.

The current drawing mode determines whether the graphics orders are executed,
stored in the segment, or both. When you call GpiPutData, the current edit mode
must be SEGEM_INSERT and, if there is already data in the destination segment,
the element pointer must address the last element of the segment.

Because the PM programming interface does not support explicit renaming of
segments, GpiGetData-GpiPutData is the method you use to rename a segment. That
is, create a second segment with the desired name, copy the contents of the
first segment to it, then delete the original segment.


ΓòÉΓòÉΓòÉ 13.1.6. Drawing Retained Graphics ΓòÉΓòÉΓòÉ

Nonretained graphics segments and primitives outside of graphics segment are
always drawn immediately to the current output device. Segments that have been
retained in segment store, however, can be drawn any number of times to any
number of device contexts. The PM programming interface has three different
functions that allow you to draw segments:

Function                 Description

GpiDrawSegment           Draws a single segment in the chain.

GpiDrawFrom              Draws a group of segments in the chain.

GpiDrawChain             Draws the entire chain.

GpiDrawSegment draws a single, named segment, which can be chained or
unchained. You supply the segment name as input to this function.
GpiDrawSegment can draw a dynamic segment in some circumstances. These are
described in Drawing Dynamic Segments.

GpiDrawFrom draws one or more root segments from the segment chain. You supply
the names of two root segments as input. The drawing process starts at the
first named segment and draws all chained and called segments, excluding
dynamic segments, up to and including the second named segment.

The order in which you specify the segment names is to reflect their relative
positions in the segment chain. If the second-named segment appears in the
segment chain before the first-named segment, no error is raised, but drawing
starts from the first named segment and continues to the end of the chain. This
also happens if the second segment is an unchained segment rather than a root
segment. If the drawing control, DCTL_DYNAMIC is set, any dynamic segments
already drawn on the display are removed before GpiDrawFrom begins to draw
nondynamic segments; then, they are redrawn after GpiDrawFrom ends.

GpiDrawChain draws all nondynamic chained segments in a named presentation
space, as well as any unchained segments called by those chained segments. It
does not draw dynamic segments. You supply only the presentation space handle
as input to this function. If the drawing control, DCTL_DYNAMIC is set, any
dynamic segments already drawn on the display are removed before GpiDrawFrom
begins to draw nondynamic segments; then, they are redrawn after GpiDrawFrom
completes.

You can call any of these functions while a segment is open. The open segment
is not modified by these functions, although any of them can result in the
current attribute values and current position being modified. For more
information about the attribute-resetting process, see Graphics Attributes.

The current drawing mode determines whether the segments identified in the
drawing functions are executed, stored in the segment, or both. The current
drawing mode does not effect which segments are drawn, or the priority in which
they are drawn for any of these three GPI drawing functions.

If an error occurs during the drawing process, you can determine where the
error occurred using GpiErrorSegmentData. This function returns information
about the last error that occurred during a segment-drawing operation. It
returns a pointer to the segment identifier and a pointer to one of three
constants that indicate when the error occurred.

Constant                 Error occurred...

GPIE_SEGMENT             While drawing the segment.

GPIE_ELEMENT             While calling GpiElement.

GPIE_DATA                While calling GpiPutData.


ΓòÉΓòÉΓòÉ 13.1.7. Drawing Dynamic Segments ΓòÉΓòÉΓòÉ

A dynamic segment is a chained segment that possesses special properties.
Dynamic segments are those that can be moved or changed in some other way
without disturbing the remaining parts of the picture. To draw dynamic segments
on the display screen for the first time, use GpiDrawDynamics. GpiDrawDynamics
draws every dynamic segment in the segment chain.

When they have been drawn on the display, dynamic segments can be updated. For
example, to move one or more dynamic segments to another part of the display
screen, remove them from their current position using GpiRemoveDynamics. You
can restrict the scope of this function by supplying the names of a start
segment and a finish segment. The start segment and finish segment can be the
same. Dynamic segments outside of this range are not removed from the display
screen.

If you intend to re-associate the presentation space, call GpiRemoveDynamics
first; otherwise, GpiRemoveDynamics cannot remove the dynamic segments after
the presentation space has been re-associated. The dynamic segments effectively
cease to be dynamic.

After removing the appropriate dynamic segments from the display screen, you
can redraw them elsewhere, again using GpiDrawDynamics. If you specify a range
of dynamic segments in GpiRemoveDynamics, the redrawing is restricted to that
range. Note that, when dynamic segments have been drawn on the display screen,
you must not edit their definitions in segment store.

Dynamic segments are treated like nondynamic segments when you are directing
output to a hardcopy device. GpiRemoveDynamics and GpiDrawDynamics raise an
error condition if the current output device is not a display window.


ΓòÉΓòÉΓòÉ 13.1.8. The Drawing Controls ΓòÉΓòÉΓòÉ

GpiErase clears the output display of the currently associated device to
CLR_BACKGROUND, which is the normal background color for the device. If you are
using the default color table, this value clears the window background to
white. This is a once-only request and must be issued each time you want the
display screen cleared before drawing a new picture. You can use this function
for either a micro presentation space or a normal presentation space.

To get this effect for more than one drawing request, you can use
GpiSetDrawControl. This function establishes current values for five drawing
controls, which remain in effect until they are reset. The following table
describes the five drawing controls.

Drawing Controls

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéControl                 ΓöéValue           ΓöéIf set, the         Γöé
Γöé                        Γöé                Γöéoperating system... Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBoundary data           ΓöéDCTL_BOUNDARY   Γöécomputes the        Γöé
Γöéaccumulation            Γöé                Γöédimensions of the   Γöé
Γöé                        Γöé                Γöésmallest rectangle  Γöé
Γöé                        Γöé                Γöéthat would          Γöé
Γöé                        Γöé                Γöécompletely surround Γöé
Γöé                        Γöé                Γöéthe retained-drawingΓöé
Γöé                        Γöé                Γöéoutput.             Γöé
Γöé                        Γöé                ΓöéThis control is     Γöé
Γöé                        Γöé                Γöédescribed in        Γöé
Γöé                        Γöé                ΓöéClipping and        Γöé
Γöé                        Γöé                ΓöéBoundary            Γöé
Γöé                        Γöé                ΓöéDetermination.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCorrelation             ΓöéDCTL_CORRELATE  Γöéperforms correlationΓöé
Γöé                        Γöé                Γöéoperations on any   Γöé
Γöé                        Γöé                Γöéprimitives or any   Γöé
Γöé                        Γöé                Γöéoutput associated   Γöé
Γöé                        Γöé                Γöéwith GpiPutData or  Γöé
Γöé                        Γöé                ΓöéGpiElement.         Γöé
Γöé                        Γöé                ΓöéThis control is     Γöé
Γöé                        Γöé                Γöédescribed in        Γöé
Γöé                        Γöé                ΓöéCorrelation.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDisplay control         ΓöéDCTL_DISPLAY    Γöédraws retained      Γöé
Γöé                        Γöé                Γöéoutput on the deviceΓöé
Γöé                        Γöé                Γöéidentified by the   Γöé
Γöé                        Γöé                Γöécurrent device      Γöé
Γöé                        Γöé                Γöécontext. If this    Γöé
Γöé                        Γöé                Γöécontrol is not set, Γöé
Γöé                        Γöé                Γöéno retained output  Γöé
Γöé                        Γöé                Γöéwill appear on the  Γöé
Γöé                        Γöé                Γöédevice.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-dynamic-segments   ΓöéDCTL_DYNAMIC    Γöécalls               Γöé
Γöé                        Γöé                ΓöéGpiRemoveDynamics   Γöé
Γöé                        Γöé                Γöébefore drawing any  Γöé
Γöé                        Γöé                Γöéretained output and Γöé
Γöé                        Γöé                Γöéthen, after drawing Γöé
Γöé                        Γöé                Γöéthe retained output,Γöé
Γöé                        Γöé                Γöéit calls            Γöé
Γöé                        Γöé                ΓöéGpiDrawDynamics to  Γöé
Γöé                        Γöé                Γöédraw output stored  Γöé
Γöé                        Γöé                Γöéin dynamic segments.Γöé
Γöé                        Γöé                ΓöéThis automatically  Γöé
Γöé                        Γöé                Γöéremoves all dynamic Γöé
Γöé                        Γöé                Γöésegments from the   Γöé
Γöé                        Γöé                Γöédisplay screen      Γöé
Γöé                        Γöé                Γöébefore a            Γöé
Γöé                        Γöé                ΓöéGpiDrawxxxxx requestΓöé
Γöé                        Γöé                Γöéis issued, then     Γöé
Γöé                        Γöé                Γöélater redraws the   Γöé
Γöé                        Γöé                Γöésegments. This      Γöé
Γöé                        Γöé                Γöéensures that dynamicΓöé
Γöé                        Γöé                Γöésegments are always Γöé
Γöé                        Γöé                Γöédrawn on top of     Γöé
Γöé                        Γöé                Γöénondynamic segments Γöé
Γöé                        Γöé                Γöéand primitives.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéErase-before-draw       ΓöéDCTL_ERASE      Γöécalls GpiErase      Γöé
Γöé                        Γöé                Γöébefore drawing any  Γöé
Γöé                        Γöé                Γöéretained output.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

GpiSetDrawControl can be called in either a micro or a normal presentation
space, although not all of the controls are valid in a micro presentation
space. For details, see the Presentation Manager Programming Reference.
GpiDrawSegment can be used to draw a dynamic segment in some circumstances. Its
effects are as follows:

o If the named segment is both chained and dynamic, and the DCTL_DYNAMIC
  drawing control is set, all dynamic segments in the chain, including the
  named segment, are drawn as dynamic.

o If the named segment is both chained and dynamic, and the DCTL_DYNAMIC
  control is not set, the named segment is not drawn.

o If the named segment is unchained and dynamic, it is drawn as a nondynamic
  segment, regardless of the setting of the DCTL_DYNAMIC control.

If you called GpiRemoveDynamics prior to calling GpiDrawDynamics and you
specified a range of dynamic segments, the operating system draws only that
range. If you set the DCTL_DYNAMIC control using GpiSetDrawControl, the
operating system calls GpiRemoveDynamics before drawing the subpictures from
the dynamic segments.

The DCTL_DISPLAY control is the only control set to DCTL_ON by default. All
other controls are set to DCTL_OFF when you create a presentation space.


ΓòÉΓòÉΓòÉ 13.2. Using Segment Editing Functions ΓòÉΓòÉΓòÉ

You can use editing functions to:

o Create a chained-dynamic segment
o Delete a segment
o Edit the contents of a segment.

The following figure shows an example of how to edit the contents of a segment.
In the example, three elements are inserted. The steps required for this task
are as follows:

 1. Set the segment edit mode to insert or replace using GpiSetEditMode.

 2. Set the drawing mode to retain.

 3. Open the segment using GpiOpenSegment, passing it the segment identifier
    from a previous correlation operation.

 4. Set the element pointer so that it points to the position at which you will
    replace or insert an element using GpiSetElementPointer,
    GpiSetElementPointerAtLabel, or GpiOffsetElementPointer.

 5. Insert the new primitives using any of the Gpi primitive functions.

 6. Delete any unnecessary primitives using GpiDeleteElement or
    GpiDeleteElementRange.

 7. Close the segment using GpiCloseSegment.

The first element inserted contains the graphics order that sets the color to
yellow; the second element moves the current position; and the third element
draws an outlined box with rounded corners. After the three elements are
inserted, the code deletes the element at position 5 in the segment (this
element was previously at positions 1 and 2).

#define INCL_GPISEGEDITING
#define INCL_GPICONTROL
#include <os2.h>
void fncESEG01(void){
    HPS hps;
    LONG idNonChained;
    POINTL ptl;

    GpiSetEditMode(hps, SEGEM_INSERT);

    GpiSetDrawingMode(hps, DM_RETAIN);

    GpiOpenSegment(hps, idNonChained);

    GpiSetElementPointer(hps, 0L);

    GpiSetColor(hps, CLR_YELLOW);

    ptl.x = 100; ptl.y = 100;

    GpiMove(hps, &ptl);

    ptl.x = 150; ptl.y = 150;

    GpiBox(hps, DRO_OUTLINE, &ptl, 40L, 40L);

    ptl.x = 30; ptl.y = 30;

    GpiMove(hps, &ptl);

    GpiSetElementPointer(hps, 5L);

    GpiDeleteElement(hps);

    GpiCloseSegment(hps);

} /* fncESEG01 */


Editing the Contents of a Graphics Segment


ΓòÉΓòÉΓòÉ 13.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the functions used to edit retained graphics and
segments.

Editing Graphics and Segment Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name                 ΓöéDescription                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiBeginElement               ΓöéDefines the beginning of an   Γöé
Γöé                              Γöéelement bracket.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCloseSegment               ΓöéDefines the end of a segment  Γöé
Γöé                              Γöébracket.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteElement              ΓöéDeletes the element at the    Γöé
Γöé                              Γöéelement pointer, then sets theΓöé
Γöé                              Γöéelement pointer to the        Γöé
Γöé                              Γöéprevious element.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteElementRange         ΓöéDeletes a specified range of  Γöé
Γöé                              Γöéelements from a segment.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteElementsBetweenLabelsΓöéDeletes all of the elements inΓöé
Γöé                              Γöéa segment that appear between Γöé
Γöé                              Γöétwo labels.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteSegment              ΓöéDeletes a segment.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteSegments             ΓöéDeletes a specified range of  Γöé
Γöé                              Γöésegments.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawChain                  ΓöéDraws the subpictures stored  Γöé
Γöé                              Γöéin a presentation space's     Γöé
Γöé                              Γöésegment chain.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawDynamics               ΓöéRedraws dynamic segments.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawFrom                   ΓöéDraws the subpictures from a  Γöé
Γöé                              Γöéspecified range of segments inΓöé
Γöé                              Γöéthe segment chain.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDrawSegment                ΓöéDraws a subpicture from a     Γöé
Γöé                              Γöésingle segment.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiErase                      ΓöéClears a window identified by Γöé
Γöé                              Γöéa screen device context and   Γöé
Γöé                              Γöépaints the window, using the  Γöé
Γöé                              Γöécolor identified by index 0 inΓöé
Γöé                              Γöéyour presentation space's     Γöé
Γöé                              Γöécolor table.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiElement                    ΓöéCreates an element from       Γöé
Γöé                              Γöégraphics orders that you storeΓöé
Γöé                              Γöéin a buffer and pass to the   Γöé
Γöé                              Γöéfunction.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiEndElement                 ΓöéDefines the end of an element Γöé
Γöé                              Γöébracket.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiErrorSegmentData           ΓöéProvides information about theΓöé
Γöé                              Γöélast error that occurred      Γöé
Γöé                              Γöéduring a retained-drawing     Γöé
Γöé                              Γöéoperation.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiGetData                    ΓöéCopies graphics orders from a Γöé
Γöé                              Γöésegment into a buffer.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLabel                      ΓöéGenerates a special element   Γöé
Γöé                              Γöécalled a label.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOffsetElementPointer       ΓöéMoves the element pointer in aΓöé
Γöé                              Γöésegment by a specified offset.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOpenSegment                ΓöéDefines the beginning of a    Γöé
Γöé                              Γöésegment bracket.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPutData                    ΓöéCopies graphics orders from a Γöé
Γöé                              Γöébuffer into a segment.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDrawControl           ΓöéDetermines whether one of the Γöé
Γöé                              Γöéfive drawing controls is set. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDrawingMode           ΓöéDetermines which of the three Γöé
Γöé                              Γöédrawing modes is set.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryEditMode              ΓöéDetermines which of the two   Γöé
Γöé                              Γöésegment-editing modes is      Γöé
Γöé                              Γöécurrently set.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryElement               ΓöéRetrieves the graphics orders Γöé
Γöé                              Γöéfrom the element at the       Γöé
Γöé                              Γöécurrent position of the       Γöé
Γöé                              Γöéelement pointer and copies theΓöé
Γöé                              Γöéorders into a buffer of bytes.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryElementPointer        ΓöéRetrieves the location of the Γöé
Γöé                              Γöéelement pointer.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryElementType           ΓöéRetrieves the type of the     Γöé
Γöé                              Γöéelement at the current        Γöé
Γöé                              Γöélocation of the element       Γöé
Γöé                              Γöépointer.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryInitialSegmentAttrs   ΓöéRetrieves the setting of one  Γöé
Γöé                              Γöéof the seven initial segment  Γöé
Γöé                              Γöéattributes.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentAttrs          ΓöéRetrieves the setting of one  Γöé
Γöé                              Γöéof the seven segment          Γöé
Γöé                              Γöéattributes.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentNames          ΓöéRetrieves a list of existing  Γöé
Γöé                              Γöésegment identifiers within a  Γöé
Γöé                              Γöéspecified range.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentPriority       ΓöéReturns the identifier for a  Γöé
Γöé                              Γöésegment that precedes or      Γöé
Γöé                              Γöéfollows a segment in the      Γöé
Γöé                              Γöésegment chain.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryStopDraw              ΓöéDetermines whether the        Γöé
Γöé                              Γöéstop-draw condition is set.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRemoveDynamics             ΓöéRemoves parts of a picture    Γöé
Γöé                              Γöéthat were drawn by dynamic    Γöé
Γöé                              Γöésegments in the segment chain.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDrawControl             ΓöéSets one of the five drawing  Γöé
Γöé                              Γöécontrols.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDrawingMode             ΓöéSets the drawing mode in your Γöé
Γöé                              Γöépresentation space to one of  Γöé
Γöé                              Γöéthree possible modes: draw,   Γöé
Γöé                              Γöéretain, or draw-and-retain.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetEditMode                ΓöéDefines which of the two      Γöé
Γöé                              Γöésegment-editing modes is      Γöé
Γöé                              Γöécurrently set.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetElementPointer          ΓöéSets the element pointer so   Γöé
Γöé                              Γöéthat it points at the nth     Γöé
Γöé                              Γöéelement in a segment.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetElementPointerAtLabel   ΓöéSets the element pointer to   Γöé
Γöé                              Γöéthe element identified by a   Γöé
Γöé                              Γöéparticular label.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetInitialSegmentAttrs     ΓöéSets the default segment      Γöé
Γöé                              Γöéattributes.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetSegmentAttrs            ΓöéSets one of the seven segment Γöé
Γöé                              Γöéattributes.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetSegmentPriority         ΓöéAlters the order in which the Γöé
Γöé                              Γöéoperating system draws and    Γöé
Γöé                              Γöédetects segments in the       Γöé
Γöé                              Γöésegment chain.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetStopDraw                ΓöéSets the stop-draw condition. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 14. Correlation ΓòÉΓòÉΓòÉ

Correlation is the process of determining which primitives, if any, are
contained in an area of interest.  The process for nonretained graphics is very
different from the process for retained graphics. The following topics are
related to the information in this chapter:

o Presentation spaces
o Coordinate spaces and transformations
o Segments.


ΓòÉΓòÉΓòÉ 14.1. About Correlation ΓòÉΓòÉΓòÉ

When you want to select an area of interest on the screen, you usually move the
pointer to the applicable point and signal (by clicking a mouse, for example)
that this is the object you want. This selection process most commonly is used
for graphic applications. For example, your application could permit a user to
select an object, then change its color.  Correlation, however, also can be
used in nongraphic applications.  For example, your application models the
operation of a calculator and permits a user to select numbers for mathematical
operations.

The area of interest is defined by the operating system as a small rectangle,
centered on the (x,y) coordinate position, that has been sent to the
application.  The virtual rectangle the application generates is known as the
pick aperture. The following figure shows an example of a pick aperture.

The Pick Aperture

The process of determining what lies in the pick aperture differs between
nonretained and retained graphics.  For nonretained graphics, the presentation
space must be put in a state that supports correlation before the primitives
are drawn; then, correlation is performed while the primitives are being drawn.
For retained graphics, the segments that contain the graphics can be replayed,
permitting correlation after the primitives are drawn.

Note:  The necessity to correlate graphics usually can be predicted; therefore,
       you can plan for it when designing applications. However, this does not
       mean that you have to create retained (rather than nonretained) graphic
       segments. The decision to retain graphics is dependent on several
       considerations of which correlation is only one.


ΓòÉΓòÉΓòÉ 14.1.1. Correlating Nonretained Graphics ΓòÉΓòÉΓòÉ

For the purposes of correlation, nonretained graphics are those graphics that
are being correlated during the drawing process.  Nonretained graphics can
exist in nonretained graphic segments or completely outside any segment
structure. Primitives outside segments are detectable when the applicable draw
control is set.

Nonretained graphics, inside a segment bracket, can be created in either draw
or draw-and-retain modes. If created in draw-and-retain mode, a segment, at
first, is considered nonretained while the primitives in the segment are being
drawn; then, it is considered retained. To be correlated, nonretained segments
must have unique, nonzero identifiers, and must be defined as detectable. The
primitives within these segments can be tagged just as primitives in retained
segments are; however, the tags do not influence the correlation process for
nonretained graphics.

To get correlation data from the drawing of nonretained graphics, 3 steps must
be performed- after creation of the presentation space but before drawing the
primitives:

 1. Call GpiSetDrawControl to switch on the correlation flag (DCTL_CORRELATE,
    DCTL_ON).

 2. Call GpiSetPickApertureSize, if necessary, to change the size of the pick
    aperture.

 3. Call GpiSetPickAperturePosition, if necessary, to explicitly position the
    aperture.  As input to this function, you provide the coordinate position
    on which the pick aperture is to be centered, using presentation page
    coordinates.

Correlation is performed for the following functions:

o Individual primitive-drawing requests, for example, GpiBox
o GpiPutData
o GpiElement
o GpiPlayMetaFile.

Correlation is never performed for GpiErase.

You detect correlation hits by examining the returned values from the GPI
functions.  If GpiLine, for example, draws a line that intersects the pick
aperture, it returns a value of GPI_HITS to indicate a correlation hit. If the
line does not intersect the pick aperture, GpiLine returns a value of GPI_OK,
to indicate the successful drawing of a line without a correlation hit. GpiLine
returns a value of GPI_ERROR if an error is detected.

If the line intersects the pick aperture, a correlation hit is returned even if
the line style is LINETYPE_INVISIBLE. For other primitives, if the object is
drawn in outline mode, a correlation hit is returned only if the pick aperture
intersects the boundary.  If the object is in fill mode, a correlation hit is
returned if the pick aperture intersects or lies within the boundary.

The following figure is an example of primitives intersecting the pick
aperture.

Correlating Nonretained Graphics

Each GPI function whose output intersects the pick aperture returns a hit
(GPI_HIT). GpiBox, whose output does not intersect the pick aperture, returns
GPI_OK.


ΓòÉΓòÉΓòÉ 14.1.2. Correlating Retained Graphics ΓòÉΓòÉΓòÉ

The information in a retained graphic segment can be redrawn; therefore,
setting up an environment for correlation is not necessary. Correlation on
retained segments is processed through segment IDs and tags throughout the
segments.

For any retained segment to be a candidate for correlation, the following must
be done:

 1. Call GpiOpenSegment with a unique, nonzero identifier.

 2. Call GpiSetSegmentAttrs with the following settings:

    a. ATTR_DETECTABLE switched ON
    b. ATTR_DYNAMIC left OFF (default),
       unless the segment is unchained and, therefore, drawn non-dynamically.
    c. ATTR_PROP_DETECTABLE left ON (default),
       in any segment that calls the candidate segment.

 3. Call GpiSetTag at appropriate locations within the segment

Note:  The preceding is the recommended method.  However, an application still
       can receive correlation data about invisible segments, as explained in
       The lType Input Parameter.


ΓòÉΓòÉΓòÉ 14.1.2.1. Tagging Primitives within a Segment ΓòÉΓòÉΓòÉ

The GpiSetTag function inserts a long integer value, called a tag, at the
current element pointer position. The tag becomes a segment element, which
serves as an identifier for the primitives that follow until the next tag is
issued. Tags also are called pick tags or pick identifiers.  Typically,
applications assign tags only to elements that correspond to primitives. You
can determine the value of the last tag assigned to an element using
GpiQueryTag.

Note:  Tags are used only in correlation; they are not used in the chaining or
       calling of segments, nor do they cause or modify output.

The long integer value of the tag is 0 by default. However, a 0 value makes the
subsequent primitives undetectable. An application can use this effect to make
some parts of a segment detectable and other parts of it non-detectable. If you
know that this capability is unnecessary, you can change the default tag value
using GpiSetDefTag.

The tag you specify becomes the current tag, and it applies to all subsequent
primitives until you next call GpiSetTag. The tag can be considered one of the
attributes of the primitive, and, therefore, affected by the current attribute
mode. In AM_PRESERVE mode, it is stored on the LIFO stack and can be recalled
with GpiPop. Tags cannot be inserted between a GpiBeginArea and GpiEndArea area
bracket; therefore, all primitives within an area have the same tag.

A tag value greater than 0 enables correlation on the subsequent primitives,
but only if the segment ID is greater than 0 as well. The data returned from
each correlation consists of a set of segment-tag pairs. The reason for this
pairing is that a single segment can draw objects in several locations. By
adding identifiers within the segment, an application has a more exact
description of what has intersected the pick aperture.

For simple chained segments, each unique segment-tag pair within the pick
aperture is known as a hit. If two or more primitives in the pick aperture have
the same tag, they are considered a single hit. Hits for called segments differ
slightly and are described in The lMaxDepth Input Parameter.


ΓòÉΓòÉΓòÉ 14.1.2.2. Correlation Functions for Retained Graphics ΓòÉΓòÉΓòÉ

The PM programming interface has 3 different functions that enable you to
correlate a uniquely identified retained segment.

Function                 Description

GpiCorrelateSegment      Permits correlation on a single segment.

GpiCorrelateFrom         Permits correlation on a range of segments from a
                         segment chain.

GpiCorrelateChain        Permits correlation on the entire segment chain.

For nonretained graphics, the correlation hits are returned by the actual
drawing commands.  For retained graphics, the correlation hits are returned by
the 3 correlation functions, listed above.

The size of the pick aperture is set using GpiSetPickApertureSize, just as with
nonretained graphics. However, the coordinate position on which the pick
aperture is centered usually is obtained from operator input, for example, from
a WM_BUTTON1DOWN message, instead of from GpiSetPickAperturePosition.

After the graphics orders that create pictures are stored in retained segments,
the pictures can be re-created by your application with the various GpiDrawxxx
functions.  Then the user can view the pictures, if the output is directed to a
screen for example. After the user selects an area of interest, a
GpiCorrelatexxx function redraws the picture internally to determine just what
intersects the pick aperture. The user does not see the re-creation. A standard
order of functions within your application would be:

o GpiDrawxxx
o GpiSetPickApertureSize
o GpiCorrelatexxx.


ΓòÉΓòÉΓòÉ 14.1.2.3. The Correlation Input Parameters ΓòÉΓòÉΓòÉ

There is only one segment chain per presentation space; therefore,
GpiCorrelateChain needs the presentation space handle as input. The segment
correlation functions need both the presentation space handle and the segment
IDs.

All three correlation functions require the following as input:

o Correlation attribute type
o Maximum number of hits
o Number of segment-tag pairs to be returned for a single hit, called the pair
  depth.


ΓòÉΓòÉΓòÉ 14.1.2.3.1. The lType Input Parameter ΓòÉΓòÉΓòÉ

The two classifications of segments upon which you can request correlation are
the following:

o Segments that have been defined as both detectable and visible
o All nonzero segments, regardless of their detectability and visibility
  attributes.


ΓòÉΓòÉΓòÉ 14.1.2.3.2. The lMaxHits Input Parameter ΓòÉΓòÉΓòÉ

The correlation functions return the number of hits made on the retained
segments. The following figure is an example of a line intersecting the pick
aperture.

Retained Segment Correlation with One Hit

The intersection of a unique segment-identified and -tagged primitive with the
pick aperture (pa) produces one hit.  If the pick aperture size were increased,
there still would be only 1 hit. The triangle produces no hit because its tag
is 0.

The following figure is an example of multiple primitives intersecting the pick
aperture.

Retained Segment Correlation with Multiple Hits

Four separate primitives intersect the pick aperture; however, since 2
primitives share the same tag, and 1 primitive has a segment ID of 0, there are
only 2 hits.

Your application can set a limit on the number of hits to return from a
correlation function. The maximum-number-of-hits parameter influences the size
of the array created to handle the segment-tag pair returned for each hit.  By
comparing the maximum number desired to the actual number of hits, your
application can determine whether all hits are accounted for. The following
figure shows an example of the alSegTag data structure that contains the
segment-tag pairs for the previous figure.

alSegTag Data Structure

As shown in the previous figure, the identifier-tag pairs are returned to the
application in the reverse order of their occurrence on the segment chain. That
is, the highest priority segment is returned first. Therefore, the application
can identify the topmost segment, which is the segment most likely to have been
picked.


ΓòÉΓòÉΓòÉ 14.1.2.3.3. The lMaxDepth Input Parameter ΓòÉΓòÉΓòÉ

When a called segment is picked, correlation data is returned also for all
segments above it in the hierarchy, up to and including the root segment. The
following figure is an example of a picture drawn from a complex segment chain
with called segments.


                   Correlation on Retained Segments

                          Presentation Space          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                                                      Γöé             id=222Γöé
                                                ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇGpi Set Tag (...,6)Γöé
                                                Γöé     Γöé                   Γöé
                                                Γöé     Γöé       (Draws moon)Γöé
                                                Γöé     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                 Γöé Γöé                 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                 Γöé Γöé                 Γöé             id=220Γöé
                 Γöé Γöé               ΓöîΓöÇGpi Set Tag (...,4)Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                 Γöé Γöé               Γöé ΓöéGpi ...            Γöé ΓöîΓöÇ      id=223Γöé
                 Γöé Γöé               Γöé Γöé     (Draws planet)Γöé Γöé Γöé(draws moon)Γöé
                 Γöé Γöé               Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                 Γöé Γöé    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   Γöé          Γöé
                 Γöé Γöé    Γöé             id=200Γöé   Γöé          Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                 Γöé Γöé  ΓöîΓöÇGpi Set Tag (...,2)Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ      id=224Γöé
                 Γöé Γöé  Γöé ΓöéGpi ...            Γöé              Γöé Γöé(draws moon)Γöé
                 Γöé Γöé  Γöé Γöé        (Draws sun)Γöé              Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                 Γöé Γöé  Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ              Γöé
          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓö┤ΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 chained Γöé Γöé             id=100Γöé   Γöé Γöé             id=230Γöé ΓööΓöÇ      id=225Γöé
segments Γöé ΓöéGpi Set Tag (...,1)Γöé   ΓööΓöÇ                   Γöé   Γöé(draws moon)Γöé
         Γöé ΓöéGpi ...            Γöé     Γöé                   Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
         Γöé Γöé       Root SegmentΓöé     Γöé     (Draws planet)Γöé
          ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                 Γöé Γöé  Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                 Γöé Γöé  Γöé Γöé             id=300Γöé
                 Γöé Γöé  Γö£ΓöÇGpi Set Tag (..,12)Γöé
                 Γöé Γöé  Γöé ΓöéGpi ...            Γöé
                 Γöé Γöé  Γöé Γöé     (Draws course)Γöé
                 Γöé Γöé  Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                 Γöé Γöé  Γöé
                 Γöé Γöé  Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                 Γöé Γöé  Γöé Γöé             id=400Γöé
                 Γöé Γöé  ΓööΓöÇGpi Set Tag (..,22)Γöé
                 Γöé Γöé    ΓöéGpi ...            Γöé
                 Γöé Γöé    Γöé     (Draws rocket)Γöé
                 Γöé Γöé    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
                           called segment
                         ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Multiple Hits from a Called Segment

Two separate items, called from different portions of the segment chain,
intersect the pick aperture.  Each has a unique segment identifier and tag, so
there are two hits.

For called segments, the group of segment-tag pairs constitutes a single hit.
You can limit the number of segment and tag pairs returned for each hit using
the maximum depth parameter, just as you can limit the total number of hits
returned to you using the maximum number of hits parameter. The following
figure shows two examples of the alSegTag data structure from the previous
figure, for two different lMaxDepth values.

          ΓöîΓöÇ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöÇΓöÇΓöÉ            ΓöîΓöÇΓöÇΓöÇ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöÇΓöÇΓöÉ
          Γöé  Γöéid = 300Γöé  0Γöé            Γöé    Γöéid = 300Γöé  0Γöé
          Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
          Γöé  Γöétag = 12Γöé  1Γöé            Γöé    Γöétag = 12Γöé  1Γöé
    ΓöîΓöÇ ΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
    Γöé     Γöé  Γöéid = 100Γöé  2Γöé            Γöé    Γöéid = 100Γöé  2Γöé
    Γöé     Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
    Γöé     Γöé  Γöétag = 1 Γöé  3Γöé  2 actual  Γöé    Γöétag = 1 Γöé  3Γöé
    Γöé     Γò₧ΓòÉ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇΓöÇ  hits  ΓöÇΓöÇΓöñ    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇ ΓöÇΓöÉ
    Γöé     Γöé  Γöéid = 222Γöé  4Γöé  returned  Γöé    Γöé    0   Γöé  4Γöé    Γöé
    Γöé     Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
 IMax     Γöé  Γöétag = 6 Γöé  5Γöé            Γöé    Γöé    0   Γöé  5Γöé    Γöé
 hitsΓöÇ ΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
 = 3      Γöé  Γöéid = 220Γöé  6Γöé            Γöé    Γöé    0   Γöé  6Γöé    Γöé
    Γöé     Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
    Γöé     Γöé  Γöétag = 4 Γöé  7Γöé            Γöé    Γöé    0   Γöé  7Γöé    Γöé
    Γöé     Γò₧ΓòÉ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí            Γöé ΓöîΓöÇ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí    Γöé
    Γöé     Γöé  Γöé    ?   Γöé  8Γöé            Γöé Γöé  Γöéid = 222Γöé  8Γöé    Γöé
    Γöé     Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
    Γöé     Γöé  Γöé    ?   Γöé  9Γöé  IMax      Γöé Γöé  Γöétag = 6 Γöé  9Γöé    Γöé
    ΓööΓöÇ ΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇ Depth     Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
          Γöé  Γöé    ?   Γöé 10Γöé  = 2       Γöé Γöé  Γöéid = 220Γöé 10Γöé    Γöé
          Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé            Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
          Γöé  Γöé    ?   Γöé 11Γöé       IMax Γöé Γöé  Γöétag = 4 Γöé 11Γöé  IMax
          ΓööΓöÇ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ       DepthΓöéΓöÇΓöñ  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇ hits
                                  = 4  Γöé Γöé  Γöéid = 200Γöé 12Γöé  = 3
                                       Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                       Γöé Γöé  Γöétag = 2 Γöé 13Γöé    Γöé
                                       Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                       Γöé Γöé  Γöéid = 100Γöé 14Γöé    Γöé
                                       Γöé Γöé  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                       Γöé Γöé  Γöétag = 1 Γöé 15Γöé    Γöé
                                       ΓööΓöÇΓööΓöÇ Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓòÉΓòÉΓòí    Γöé
                                            Γöé    ?   Γöé 16Γöé    Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                            Γöé    ?   Γöé 17Γöé    Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                            Γöé    ?   Γöé 18Γöé    Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé    Γöé
                                            Γöé    ?   Γöé 19Γöé    Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇ ΓöÇΓöÿ
                                            Γöé    ?   Γöé 20Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
                                            Γöé    ?   Γöé 21Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
                                            Γöé    ?   Γöé 22Γöé
                                            Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γöé
                                            Γöé    ?   Γöé 23Γöé
                                            ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöÇΓöÇΓöÿ

alSegTag Data Structure for Different lMaxDepth Values

Unused segment-tag pairs for actual hits are set to 0 in the alSegTag array.

There are two major reasons for the PM programming interface to provide this
capacity. The first is the consideration of application storage. If your
application is a graphics package, for example, providing extensive design
capabilities to an end user, the user's drawing may be very complex with 10 or
more levels of segment calling. The data returned from a single hit could
require an alSegTag array so large the data overruns the application storage
you had reserved. By setting a maximum calling depth, your application can
reserve the correct amount of storage.

The second consideration is the knowledge that your application's user is
interested only in a certain level of calling depth. Many users will be
interested only in the topmost called segment, because it usually is the
segment containing the functions that performs the actual drawing.


ΓòÉΓòÉΓòÉ 14.1.3. Pick Aperture ΓòÉΓòÉΓòÉ

Your application determines the size of the pick aperture using
GpiQueryPickApertureSize, and determines the page space coordinates of the
center of the aperture with GpiQueryPickAperturePosition.

Because your objective is to retrieve a single detectable object for each
correlation operation, you have to obtain a balance between the number of
detectable objects in a picture and the size of the pick aperture. The more
detectable objects you define, the smaller the pick aperture must be to return
a manageable amount of information to the application. However, the pick
aperture usually is not a 1 pel-by-1 pel rectangle. A larger rectangle makes
better sense because the pick aperture can be difficult to hit with a single
pel; but a larger sampling area, for example 4 pels-by-4 pels, increases the
probability of an intersection between a lighted pel and the pick aperture.

The pick aperture can be specified in any of the units available to the
presentation space.  However, the type of unit must be identical to the type
specified for the presentation page. The default size of the pick aperture is
square, with sides equal to the default character cell height.


ΓòÉΓòÉΓòÉ 14.2. Using Correlation ΓòÉΓòÉΓòÉ

This section explains how to perform correlation on the graphics associated
with a segment.

The following figure shows how to set the pick aperture size with
GpiSetPickAperture, and correlate the segment chain with GpiCorrelateChain,
passing it the pick-aperture position as the third argument. The functions use
the psizlPick and pptlPick arguments to set the aperture size and position the
aperture center. The correlation is performed on visible and detectable
segments only (PICKSEL_VISIBLE). GpiCorrelateChain copies any segment-tag pairs
to the buffer pointed to by alSegTag and returns the count of hits detected.

#define INCL_GPICORRELATION
#include <os2.h>
LONG fncCORL01  (HPS hps, PSIZEL psizlPick, PPOINTL pptlPick,
                  LONG lMaxHits, LONG lMaxDepth, PLONG alSegTag)
    {
        LONG cHits;

        GpiSetPickApertureSize(hps, PICKAP_REC, psizlPick);
                                                     /* Set the pick aperture. */

        cHits = GpiCorrelateChain(hps, PICKSEL_VISIBLE, pptlPick,
                    lMaxHits, lMaxDepth, alSegTag);
                                                     /* Correlate the hits.    */

        return (cHits);                              /* Return count of hits.  */

} /* fncCORL01 */


Performing a Correlation Operation


ΓòÉΓòÉΓòÉ 14.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the functions used to correlate both retained
and nonretained graphics and segments.

Correlation Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name                 ΓöéDescription                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCorrelateChain             ΓöéDetermines whether correlationΓöé
Γöé                              Γöéhits occurred at the current  Γöé
Γöé                              Γöépick-aperture location for anyΓöé
Γöé                              Γöésegment either actually in theΓöé
Γöé                              Γöésegment chain or called by a  Γöé
Γöé                              Γöésegment in the chain.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCorrelateFrom              ΓöéDetermines whether correlationΓöé
Γöé                              Γöéhits occurred at the current  Γöé
Γöé                              Γöépick-aperture location for anyΓöé
Γöé                              Γöésegment in a range of chained Γöé
Γöé                              Γöésegments.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCorrelateSegment           ΓöéDetermines whether correlationΓöé
Γöé                              Γöéhits occurred at the current  Γöé
Γöé                              Γöépick-aperture location for a  Γöé
Γöé                              Γöégiven segment.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiErase                      ΓöéClears a window identified by Γöé
Γöé                              Γöéa screen device context, and  Γöé
Γöé                              Γöépaints the window, using the  Γöé
Γöé                              Γöécolor identified by index 0 inΓöé
Γöé                              Γöéthe presentation space color  Γöé
Γöé                              Γöétable.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryBoundaryData          ΓöéRetrieves the size of the     Γöé
Γöé                              Γöésmallest rectangle that       Γöé
Γöé                              Γöécompletely surrounds the      Γöé
Γöé                              Γöécurrent segment output, if theΓöé
Γöé                              Γöédrawing control DCTL_BOUNDARY Γöé
Γöé                              Γöéhas been set by calling       Γöé
Γöé                              ΓöéGpiSetDrawControl.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPickAperturePosition  ΓöéRetrieves the location of the Γöé
Γöé                              Γöécenter of the pick aperture inΓöé
Γöé                              Γöéthe application's page space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPickApertureSize      ΓöéRetrieves the dimensions of   Γöé
Γöé                              Γöéthe pick aperture in          Γöé
Γöé                              Γöépresentation page coordinates.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryTag                   ΓöéRetrieves the value of the    Γöé
Γöé                              Γöélast tag set by calling       Γöé
Γöé                              ΓöéGpiSetTag.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiResetBoundaryData          ΓöéResets the boundary data to   Γöé
Γöé                              ΓöéNULL.                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDrawControl             ΓöéSets one of the five drawing  Γöé
Γöé                              Γöécontrols. These controls are  Γöé
Γöé                              Γöédescribed in a previous table.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPickAperturePosition    ΓöéSets the location of the      Γöé
Γöé                              Γöécenter of the pick aperture inΓöé
Γöé                              Γöéthe application's page space. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPickApertureSize        ΓöéSets the dimensions of the    Γöé
Γöé                              Γöépick aperture in presentation Γöé
Γöé                              Γöépage coordinates.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetTag                     ΓöéAssigns a tag to an element inΓöé
Γöé                              Γöéa segment.                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15. Metafiles ΓòÉΓòÉΓòÉ

A metafile is a graphics object that, like a segment, contains the GPI
instructions that contribute to the final version of a picture. Unlike a
segment, a metafile also contains a header, with state information, and all
resources necessary to identically create the picture. Because pictures that
are displayed when a graphics application is executed are lost when the
application finishes, metafiles provide a method of retaining pictures beyond a
single execution of an application.

The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Line primitives
o Marker primitives
o Area primitives
o Character string primitives
o Color and mix attributes
o Paths
o Regions
o Fonts
o Printing
o Segments
o Bit maps
o Coordinate spaces and transformations.


ΓòÉΓòÉΓòÉ 15.1. About Metafiles ΓòÉΓòÉΓòÉ

Metafiles can exist in three distinct forms.  A metafile that has just been
created is called a memory metafile because it exists in memory managed by the
Presentation Manager on behalf of the application that created it. A metafile
that is transferred to disk storage as a file with the default extension of
.MET is called a disk metafile.  A metafile that is loaded into an
application's memory is editable by the application.

Metafiles save resources in the following ways:

o Metafiles can be created and used in draw mode by a single application.
  Therefore, an application that is not retaining segments in a segment store
  can retain graphics in a metafile.

o Metafiles remain available while the owning application is running,
  regardless of the number of presentation spaces the application obtains or
  defines.

o Given the same starting conditions in each presentation space, you can
  produce an identical picture each time the metafile contents are executed.

o Different threads or processes within an application can display a picture
  stored as a metafile without each having to own the metafile.

o If your organization has common graphical resources, such as a company logo,
  those resources can be stored in a metafile. This avoids the overhead of
  re-creating the resources each time they are needed.

o Because the metafile is a device-independent format, it is useful for
  transferring pictures that are to be printed when the printer-type is
  unknown.

o PM applications can exchange graphical information by using metafiles, either
  by using the clipboard or by transferring them over a network.

o Your application can also exchange graphics data with non-PM applications
  that support the Mixed Object Document Content Architecture (MO:DCA)
  interchange standard.


Unlike bit-maps, metafiles offer some device-independence. Bit maps store
picture information on a pel-by-pel basis.  Metafiles store picture information
in the form of low-level graphics commands that the operating system uses to
construct the pictures.

Note:  Metafiles can contain bit maps or other graphics information that is in
       device-dependent format.

The graphics commands, called "graphics orders", represent graphics functions
that create a picture. These include drawing instructions, as well as
attribute-setting instructions (for example, color tables and logical fonts)
and anything that describes the structure of the picture.  The contents of a
metafile, therefore, are similar to those of the graphics presentation space in
which the picture is drawn.  The Presentation Manager automatically records the
environmental detail of the presentation space in which a picture is drawn in
the metafile.

Note:  A metafile can contain data generated from GPI functions only.  Any
       non-graphical data included in a metafile is ignored.

An application can re-create a picture from a metafile and display it in a
window on the screen or print it by "playing" the metafile. When an application
displays the contents of a metafile, it can use the color table, font, fill
pattern, and transformations that are stored in the metafile, or it can use the
logical color table, logical font, fill pattern, and transformations that are
set for the current presentation space.  The appearance of the picture stored
in the metafile can, therefore, be changed by editing the current presentation
space before playing the metafile.

An application can save metafiles to a disk to be loaded later by any
application that chooses to access the metafile.  Disk metafiles loaded into
application memory can also be edited in the same manner as elements in
graphics segments are edited.


ΓòÉΓòÉΓòÉ 15.1.1. Contents of a Metafile ΓòÉΓòÉΓòÉ

Every graphic function can be represented by one or more graphics orders. The
operating system defines graphics orders for:

o Areas
o Bit maps (for fill patterns) and pattern-reference points
o Character output and attribute
o Colors and mix modes (foreground and background)
o Lines and arcs and line and arc attributes (including GpiBox)
o Paths (including clip paths)
o Position (for example, GpiMove)
o Saving and resetting attributes (including GpiPop)
o Transformations (in model space)
o Viewing Limits.

Editing Retained Graphics and Graphics Segments also describes orders and how
to edit them.

When a picture is drawn in a presentation space associated with a metafile
device context, the operating system converts the primitive attributes and
drawing functions into graphics orders and stores them in the metafile.

The operating system stores the effects of region and other operations that are
not permitted as escape orders in the metafile. When an application finishes
playing a metafile, the system restores any regions that were defined for the
presentation space prior to calling GpiPlayMetaFile.

An application can use any of the query functions while creating a metafile,
but the system will not store those query functions in the metafile.
Similarly, an application can set a value by using a mathematical operator, but
the system will store only the result of the operation in the metafile.  For
example, if an application determines the end point of a line by subtracting
100 from the x- and y-coordinates of the upper-right corner of a window, the
system records the end point, not the relative distance, in the metafile.

Because the output of bit map functions is dependent upon the capabilities of
the output device, Gpi bit map functions might produce unexpected results when
they are used in a metafile.  If the pel dimensions of the output device are
different from the pel dimensions of the device on which the metafile was
created, the bit map will be distorted.  If the output device is a plotter, the
bit map functions will not work at all.

Most of the escape functions used by the DevEscape function can be used in
metafiles.  The escape functions that the system does not save in metafiles are
DEVESC_QUERYESCSUPPORT and DEVESC_GETSCALINGFACTOR.


ΓòÉΓòÉΓòÉ 15.1.1.1. Metafile Content Restrictions ΓòÉΓòÉΓòÉ

Like areas and paths, not all functions and attributes can be represented in a
metafile. Metafile content is mainly dependent upon the drawing mode in which
the metafile is to be played. If the metafile is to be played when the current
drawing-mode parameter is DM_DRAW (and in no other drawing mode), the metafile
content is restricted as shown in Draw-Mode Restrictions. If the metafile is to
be played when the current drawing-mode parameter is DM_RETAIN or
DM_DRAWANDRETAIN, or if the file is to conform to SAA* guidelines, the metafile
content is restricted as shown in Creating Metafiles for Interchange.

Metafile restrictions are also described in Appendix G in Presentation Manager
Programming Reference Volume III.


ΓòÉΓòÉΓòÉ 15.1.1.1.1. Draw-Mode Restrictions ΓòÉΓòÉΓòÉ

The following restrictions apply if the metafile is to be played when the
current drawing mode parameter is DM_DRAW:

o If the DCTL_DISPLAY flag of GpiSetDrawControl is OFF when you are sending
  graphics to a metafile, the graphics will not be visible when the metafile is
  played.  Their effects on the current position and on current attribute
  settings are recorded.

o Region functions are not recorded in a metafile. The effects of the following
  functions, however, are recorded:

   - GpiSetClipRegion
   - GpiIntersectClipRegion
   - GpiExcludeClipRegion
   - GpiOffsetClipRegion
   - GpiPaintRegion.

  When the metafile is played into a presentation space, temporary regions are
  created.  Upon completion of GpiPlayMetaFile, these temporary regions are
  automatically deleted and the clipping region that was current before the
  metafile was played, is restored.

o In general, escape functions identified by reserved escape codes (that is,
  escape codes in the range of 0 through 32767) are recorded in a metafile.
  However, the DevEscape functions DEVESC_QUERYESCSUPPORT (escape code 0) and
  DEVESC_GETSCALINGFACTOR (escape code 1) are not stored in the metafile.

o The effect GpiErase, including close-segment processing, is recorded in a
  metafile.

o The following functions can produce unexpected effects if the metafile
  contents are displayed on a different device from the one they were created
  for:

   - GpiBitBlt
   - GpiSetPel
   - GpiSetClipRegion
   - GpiOffsetClipRegion
   - GpiPaintRegion
   - GpiIntersectClipRectangle
   - GpiExcludeClipRectangle.

  The reason for the unexpected effects is because the pel resolutions of the
  devices might differ.  Raster operations (for example, GpiBitBlt) do not work
  on plotters.

o You can associate the metafile device context with a different presentation
  space while creating the metafile, but the new presentation space must have
  the same format as the original.


ΓòÉΓòÉΓòÉ 15.1.1.1.2. Creating Metafiles for Interchange ΓòÉΓòÉΓòÉ

The following restrictions apply if the metafile is to be played when the
current drawing-mode parameter is DM_DRAWANDRETAIN or DM_RETAIN, or if the
metafile is to conform to SAA guidelines:

o Before you issue the first drawing instruction to a graphics presentation
  space that has been associated with a metafile device context, you must
  establish (or default) the following:

   - The graphics field (use GpiSetGraphicsField)

   - The color table (use GpiCreateLogColorTable)

   - The code page for the default character set (use GpiSetCp)

   - The default viewing transformation (use GpiSetDefaultViewMatrix)

   - The settings of the drawing controls (use GpiSetDrawControl; DCTL_DISPLAY
     must be set on)

   - The default values of attributes (use GpiSetDefAttrs)

   - The default viewing limits (use GpiSetDefViewingLimits)

   - The primitive tag (use GpiSetDefTag)

   - The default arc parameters (use GpiSetDefArcParams).

  You must not specify a graphics field if the metafile is to conform to SAA
  guidelines.  If a graphics field is specified, you can play the metafile in
  DM_RETAIN or DM_DRAWANDRETAIN mode, but the graphics field must be specified
  before the first drawing instruction is issued to the metafile. The effect of
  the graphics field in the target presentation space when playing the metafile
  is controlled by the PMF_LOADTYPE option of GpiPlayMetafile.

o You can define logical fonts and identify bit maps to be used as area-fill
  patterns at any time.  You must not, however, issue GpiDeleteSetId against
  these resources after they have been established. Once assigned, therefore,
  lcids cannot be reused.

o The size of the logical-color-table data must not exceed 31KB.

o You must not use clipping regions.  Therefore, none of the following
  functions is supported:

   - GpiSetClipRegion
   - GpiExcludeClipRectangle
   - GpiIntersectClipRectangle
   - GpiOffsetClipRegion.

o You must not reassociate the metafile device context.

o When you use a bit map as the source of a GpiWCBitBlt operation or as an
  area-fill pattern, it must not be modified.

o Only the following foreground mixes can be used:

   - FM_DEFAULT
   - FM_OR
   - FM_OVERPAINT
   - FM_LEAVEALONE.

o Only the following background mixes can be used:

   - BM_DEFAULT
   - BM_OVERPAINT
   - BM_LEAVEALONE.

o The following functions are not supported:

   - GpiBitBlt
   - GpiSetPel
   - GpiSetPS
   - GpiResetPS
   - GpiErase
   - GpiPaintRegion
   - DevEscape.


ΓòÉΓòÉΓòÉ 15.1.1.1.3. Micro Presentation Space Restrictions ΓòÉΓòÉΓòÉ

When you create a metafile from a micro presentation space, or play the
metafile through a micro presentation space, the contents of the metafile are
restricted to those GPI functions that are valid in a micro presentation space.
In this case, the application must use GpiDestroyPS instead of GpiAssociate
before issuing DevCloseDC.  GpiAssociate is not permitted in a micro
presentation space.


ΓòÉΓòÉΓòÉ 15.1.1.1.4. Query Restrictions ΓòÉΓòÉΓòÉ

Query functions can be issued, with the usual restrictions, unless the metafile
device context was created using the no query option, OD_METAFILE_NOQUERY.


ΓòÉΓòÉΓòÉ 15.1.1.1.5. Segment Restrictions ΓòÉΓòÉΓòÉ

Chained and unchained segments invoked by any GpiDraw command are written to
the metafile.  Primitives outside segments are recorded automatically as zero
segments.  If the metafile is subsequently played in DM_RETAIN mode, all
graphics are directed to the segment store.

Chained dynamic segments cannot be recorded in a metafile. GpiRemoveDynamics
and GpiDrawDynamics cause an error condition to be raised when the presentation
space is associated with a metafile device context. Unchained dynamic segments
are recorded as zero segments.  To draw an unchained dynamic segment, use
GpiDrawSegment.


ΓòÉΓòÉΓòÉ 15.1.1.1.6. Asynchronous Drawing Thread Restrictions ΓòÉΓòÉΓòÉ

If the metafile is being created on an asynchronous drawing thread and the
thread is suspended by GpiSetStopDraw, an unusable metafile results.


ΓòÉΓòÉΓòÉ 15.1.2. Metafile Functions ΓòÉΓòÉΓòÉ

OS/2 2.0 provides a set of functions that allow you to:

o Create a metafile
o Store pictures in a metafile
o Play a metafile
o Save a metafile
o Load a metafile
o Edit a metafile
o Copy a metafile
o Delete a metafile.

How these functions are used to create and manipulate metafiles in relationship
to applications and components of the operating system is illustrated in the
following figure.

Metafile Functions


ΓòÉΓòÉΓòÉ 15.1.2.1. Creating a Metafile ΓòÉΓòÉΓòÉ

Pictures are drawn in presentation spaces associated with device contexts. PM
considers a metafile to be an output device or destination, in the same manner
as a window or printer. This means that to record a picture in a metafile, a
metafile device context must be created and associated with a presentation
space.

A metafile device context is created by calling DevOpenDC and specifying the
type of device context as:

o OD_METAFILE
o OD_METAFILE_NOQUERY.

OD_METAFILE is generally used to specify a metafile device context, although
OD_METAFILE_NOQUERY provides better recording performance. OD_METAFILE_NOQUERY
does not support attribute queries, for example, GpiQueryCurrentPosition, or
GpiQueryColor.

The device driver for the device that the metafile device context is associated
with is specified in the DEVOPENSTRUC data structure required for DevOpenDC.
DEVOPENSTRUC is described in Print Job Submission and Manipulation.

A metafile device context can be associated with a newly-created presentation
space by calling GpiCreatePS and specifying the handle to the metafile device
context returned from the call to DevOpenDC. A metafile device context can also
be associated with an existing, normal presentation space by calling
GpiAssociate and specifying the handle to the metafile device context returned
from the call to DevOpenDC.


ΓòÉΓòÉΓòÉ 15.1.2.2. Storing Pictures in a Metafile ΓòÉΓòÉΓòÉ

When a metafile device context is associated with a presentation space,
presentation space resources (such as the current logical color table ) and
environmental settings (such as the presentation-page format) are copied
automatically into the metafile. These items must be established before the
presentation space is associated with the metafile device context.

Loading of additional resources (such as fonts) and adjustments to the
environment (such as modifying the default viewing transform) should be made
before you begin drawing. Attribute settings, segment-creation requests, and
primitive-drawing requests that contribute to the picture are directed to the
metafile after its device context has been associated with a presentation
space.

If an application calls GpiSetDrawControl, specifying DCTL_DISPLAY and
DCTL_OFF, before drawing graphics into a metafile, the graphics are not visible
when the metafile is played.  However, the metafile records any changes made to
the current position or presentation-space attributes.

When the metafile device context has been associated with a graphics
presentation space, the metafile is ready to receive graphical data. Just as
with any other output destination, whether the picture is sent directly to the
metafile is controlled by the current drawing mode, as shown in the following
table.

Drawing Mode Dependencies When Recording Metafiles

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode          ΓöéEffect                                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw mode             ΓöéGraphics go directly to the metafile. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRetain mode           ΓöéGraphics go to the segment store of   Γöé
Γöé                      Γöéthe presentation space. They are not  Γöé
Γöé                      Γöédirected to the metafile until the    Γöé
Γöé                      Γöéapplication issues an appropriate     Γöé
Γöé                      ΓöéGpiDraw request (GpiDrawChain,        Γöé
Γöé                      ΓöéGpiDrawFrom, GpiDrawSegment).         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDraw-and-retain mode  ΓöéGraphics go directly to the metafile, Γöé
Γöé                      Γöéand also to the segment store of the  Γöé
Γöé                      Γöépresentation space.                   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The drawing mode can be changed at any time while the metafile device context
remains open by calling GpiSetDrawingMode.

As long as the metafile device context remains open, you can continue drawing.
A metafile can only contain data generated from GPI functions. Any nongraphical
data included in a metafile is ignored. The following list describes items
found in a metafile:

o Picture
o Logical color table
o Logical font
o Fill pattern
o Viewing transformation
o Page units
o Page dimensions.

When an application finishes drawing in a metafile, it must disassociate the
metafile device context from the presentation space by calling GpiAssociate. If
the metafile is associated with or through a micro presentation space, call
GpiDestroyPS to perform an implicit disassociation.

When you have finished drawing in the metafile, and the presentation space has
been disassociated, the application can close the metafile device context and
obtain a handle to the metafile by calling DevCloseDC. A closed metafile cannot
be reopened; therefore, additional drawing in the metafile is not possible.  A
closed metafile can be referenced by the metafile handle. The metafile handle
is used to reference the metafile for subsequent operations on the metafile.
Use the metafile handle to:

o Transfer a metafile to application memory
o Transfer a metafile from application memory
o Save a metafile on disk
o Play a metafile into presentation space
o Edit a metafile
o Copy a metafile
o Delete a metafile.

Because each metafile can be distinctly identified, your application can work
with more than one metafile at a time. However, because metafiles can be very
large files, you must make maximum use of the metafile handles to avoid
duplicating the actual metafiles in memory.


ΓòÉΓòÉΓòÉ 15.1.2.3. Playing a Metafile ΓòÉΓòÉΓòÉ

An application can redraw a picture stored in a metafile by executing the
contents of metafile. This is known as playing a metafile into a graphics
presentation space. How a picture is redrawn (that is, how the metafile is
replayed) depends on the current drawing-mode of the target presentation space.
The following table describes these dependencies.

Drawing Mode Dependencies When Playing Metafiles

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDrawing Mode      ΓöéResult               ΓöéIf the metafile      Γöé
Γöé                  Γöé                     Γöécontains a segment   Γöé
Γöé                  Γöé                     Γöéchain...             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAW           ΓöéThe metafile contentsΓöéThe contents of the  Γöé
Γöé                  Γöéare executed, and theΓöésegments in the chainΓöé
Γöé                  Γöépicture is directed  Γöérepresent the pictureΓöé
Γöé                  Γöéto the current outputΓöéoutput that is       Γöé
Γöé                  Γöédevice.              Γöédirected at the      Γöé
Γöé                  Γöé                     Γöétarget output device.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_RETAIN         ΓöéThe metafile contentsΓöéThe chain is added toΓöé
Γöé                  Γöéare retained in the  Γöéthe end of any chain Γöé
Γöé                  Γöéapplication's segmentΓöéthat may already be  Γöé
Γöé                  Γöéstore. The picture   Γöéin the segment store.Γöé
Γöé                  Γöédefined in the       ΓöéIf any segment in theΓöé
Γöé                  Γöémetafile is not      Γöémetafile has the sameΓöé
Γöé                  Γöédirected to an outputΓöénonzero name as a    Γöé
Γöé                  Γöédevice until the     Γöésegment already in   Γöé
Γöé                  Γöéapplication issues anΓöéthe segment store of Γöé
Γöé                  Γöéappropriate GpiDraw. Γöéthe presentation     Γöé
Γöé                  Γöé                     Γöéspace, an error      Γöé
Γöé                  Γöé                     Γöécondition is raised. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDM_DRAWANDRETAIN  ΓöéThe metafile contentsΓöéSee above.           Γöé
Γöé                  Γöéare both stored and  Γöé                     Γöé
Γöé                  Γöéexecuted.            Γöé                     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  Unchained segments in the metafile are always retained, regardless of
the current drawing-mode parameter.

When the contents of a metafile are retained in the segment store of the target
presentation space, they can be manipulated by the application as if the
application had created them. For example, the segments can be edited, drawn,
correlated, and deleted.

A metafile is "played" by calling GpiPlayMetaFile.  A metafile cannot, however,
be "played" within a segment bracket. GpiPlayMetaFile requires a metafile
handle, an option count, an options array, a byte count of a descriptive
record, and the descriptive record.

The GpiPlayMetaFile descriptive record is a natural-language description of the
picture contents. For example, its value might be A House. This description is
provided on input to the DevOpenDC function that defines the metafile device
context.  It can be used, for example, in a list box from which a user can
select a picture.

The GpiPlayMetaFile options array specifies how the operating system alters
your application's presentation space before playing the metafile. The options
array determines the display attributes of the metafile. The array fields and
their respective attributes, as numbered consecutively in the array, are shown
in the following table.

GpiPlayMetaFile Options

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOption                        ΓöéAttribute                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_SEGBASE                   ΓöéReserved, must be 0.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_LOADTYPE                  ΓöéViewing transform, graphics.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_RESOLVE                   ΓöéReserved, must be 0.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_LCIDS                     ΓöéFont and local bit map local  Γöé
Γöé                              Γöéidentifiers.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_RESET                     ΓöéDrawing attributes.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_SUPPRESS                  ΓöéActual playing of the         Γöé
Γöé                              Γöémetafile.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_COLORTABLES               ΓöéColor tables, color palettes. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_COLORREALIZABLE           ΓöéRealization of metafile color Γöé
Γöé                              Γöétable.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPMF_DEFAULTS                  ΓöéDrawing defaults values.      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.1.2.3.1. PMF_RESET Option ΓòÉΓòÉΓòÉ

The PMF_RESET option, more so than the other array options, controls the
effects of other array options. This option allows a total reset of the
presentation space and provides further control of the following presentation
space environmental attributes:

o Page units (device transform)
o Page dimensions
o Default viewing transform.

Warning: If the metafile page units, page dimensions and page coordinate format
do not match those in the presentation space, playing the metafile will cause
an error.

The PMF_RESET option can have one of the values shown in the following table.

PMF_RESET Options for GpiPlayMetaFile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue           ΓöéDescription                                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRES_RESET       ΓöéAllows the presentation space to be         Γöé
Γöé                Γöécompletely reset, just as if it were newly  Γöé
Γöé                Γöécreated, and the values of the              Γöé
Γöé                Γöéaforementioned environmental attributes to  Γöé
Γöé                Γöébe specified from the metafile into the     Γöé
Γöé                Γöépresentation space.                         Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéThis option is equivalent to specifying     Γöé
Γöé                ΓöéGRES_ALL on GpiResetPS. If this option is   Γöé
Γöé                Γöéused, the target presentation page is       Γöé
Γöé                Γöéredefined so that it is the same size, and  Γöé
Γöé                Γöédefined in the same units, as the metafile. Γöé
Γöé                ΓöéIt also ensures that the physical size of   Γöé
Γöé                Γöéthe metafile picture is preserved if the    Γöé
Γöé                Γöépresentation page is defined in units other Γöé
Γöé                Γöéthan pels, or arbitrary units.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRES_NORESET     ΓöéPrevents resetting of the presentation      Γöé
ΓöéRES_DEFAULT     Γöéspace. The existing presentation space      Γöé
Γöé                Γöévalues of the environmental attributes will Γöé
Γöé                Γöébe preserved, and their values in the       Γöé
Γöé                Γöémetafile will be discarded.                 Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéIf this option is used, ensure that the     Γöé
Γöé                Γöépresentation-page units of the target       Γöé
Γöé                Γöépresentation space are the same as those    Γöé
Γöé                Γöéwith which the metafile was generated,      Γöé
Γöé                Γöébefore you play a metafile into the         Γöé
Γöé                Γöépresentation space. For example, if the     Γöé
Γöé                Γöéoriginal presentation page is defined in    Γöé
Γöé                Γöéincrements of 0.1 mm, the target            Γöé
Γöé                Γöépresentation page must be defined in the    Γöé
Γöé                Γöésame way.                                   Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéTo change the format of the target          Γöé
Γöé                Γöépresentation page, if the presentation-page Γöé
Γöé                Γöéformats do not match, issue GpiSetPS, but   Γöé
Γöé                Γöéonly if you know the metafile               Γöé
Γöé                Γöépresentation-page units.                    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

If you are certain that the settings of the current presentation space are
appropriate for the metafile, then you can play the metafile with the NO_RESET
option. To reset some or all of the current values in the target presentation
space, without redefining the presentation page, call:

 1. GpiResetPS, with the GRES_ATTRS or GRES_SEGMENTS option
 2. GpiPlayMetaFile, with the NO_RESET option.

The PMF_LCID option may be used to append or replace fonts from the metafile to
the fonts in the presentation space. The PMF_COLORTABLES option may be used to
append or replace color table entries in the presentation space from the
metafile. Other options (PMF_LOADTYPE, PMF_DEFAULTS, and so on) can be used to
selectively replace settings in the presentation space from the metafile.

Like the PMF_RESET option, other options, except for PMF_SUPPRESS, either:

o Allow the values in the presentation space to be preserved and those in the
  metafile to be discarded, or

o Allow the presentation space to be loaded using the values in the metafile.

If the first choice is used with RES_RESET, then the items controlled by the
PMF_options will be left set to their default reset state, otherwise it will
occur as described in the first choice above.

If the second choice is used with RES_RESET, then the items controlled by the
PMF_options are as described above. If it is used with RES_NORESET, then the
fonts and color tables in the metafile can append to the existing color tables
and fonts in the presentation space. Existing presentation space color table
entries and fonts, such as viewing transform will be replaced if respecified in
the metafile.

Note:  If your application uses the attributes from the metafile, the
       attributes that were specified in the presentation space before the
       metafile was played are overwritten.


ΓòÉΓòÉΓòÉ 15.1.2.3.2. PMF_SUPPRESS Option ΓòÉΓòÉΓòÉ

The PMF_SUPPRESS option allows you to control the playing of the metafile. The
PMF_SUPPRESS option can have one of the values shown in the following table.

PMF_SUPPRESS Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue           ΓöéDescription                                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSUP_SUPPRESS    ΓöéThe operating system does not draw the      Γöé
Γöé                Γöémetafile on the device associated with the  Γöé
Γöé                Γöépresentation space. This option is useful ifΓöé
Γöé                Γöéyou need to alter the presentation space    Γöé
Γöé                Γöébefore drawing it on an output device.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSUP_NOSUPPRESS  ΓöéThe operating system draws the metafile on  Γöé
ΓöéSUP_DEFAULT     Γöéthe device associated with the presentation Γöé
Γöé                Γöéspace.                                      Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

You can use the RES_RESET option to reinitialize the presentation space and
modify certain resources or presentation space environmental attributes from
the application before playing the remainder of the metafile by:

 1. Saving the current state of the presentation space by calling GpiSavePS.

    Use this function only if you wish to restore the previous state of the
    presentation space after playing the metafile.

 2. Calling GpiPlayMetaFile and specifying:

   o The PMF_RESET option with the value RES_RESET
   o The PMF_SUPPRESS option with the value SUP_SUPPRESS.

    This causes GpiPlayMetaFile to set the presentation space to the
    specifications recorded in the metafile but not to play the picture in the
    metafile.

 3. Making any required changes to the presentation space.

 4. Calling GpiPlayMetaFile and specifying:

   o The PMF_RESET option with the value RES_NORESET.
   o The PMF_SUPPRESS option with the value SUP_NOSUPPRESS.

    This causes the picture to play.

 5. Restoring the state of the presentation space after playing the metafile by
    calling GpiRestorePS.


ΓòÉΓòÉΓòÉ 15.1.2.3.3. PMF_LOADTYPE Option ΓòÉΓòÉΓòÉ

The PMF_LOADTYPE option of GpiPlayMetaFile determines which viewing
transformations and graphics fields affect the metafile picture. The
PMF_LOADTYPE option can have one of the values shown in the following table.

PMF_LOADTYPE Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue           ΓöéDescription                                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLT_ORIGINALVIEW ΓöéViewing transformations recorded in the     Γöé
Γöé                Γöémetafile are used in the target presentationΓöé
Γöé                Γöéspace.                                      Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéIf changes to the graphics field are        Γöé
Γöé                Γöérecorded in the metafile, the graphics fieldΓöé
Γöé                Γöéin the target presentation space is updated,Γöé
Γöé                Γöéand the picture is clipped to that graphics Γöé
Γöé                Γöéfield.                                      Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéChanges to the default viewing              Γöé
Γöé                Γöétransformation recorded in the metafile are Γöé
Γöé                Γöéused to update the default viewing          Γöé
Γöé                Γöétransformation in the target presentation   Γöé
Γöé                Γöéspace.                                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLT_NOMODIFY     ΓöéAny viewing transformations recorded in the Γöé
ΓöéLT_DEFAULT      Γöémetafile are ignored. The metafile contents Γöé
Γöé                Γöéare drawn in accordance with the current    Γöé
Γöé                Γöéviewing transformation in the target        Γöé
Γöé                Γöépresentation space. (Note that, if you also Γöé
Γöé                Γöéspecify RES_RESET, the current viewing      Γöé
Γöé                Γöétransformation is reset to its default      Γöé
Γöé                Γöévalue.)                                     Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéThe picture is clipped to any graphics fieldΓöé
Γöé                Γöédefined in the target presentation space,   Γöé
Γöé                Γöéand any graphics field recorded in the      Γöé
Γöé                Γöémetafile is ignored.                        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The PMF_RESET option RES_RESET changes values in the target presentation space.
Therefore, the effect of the PMF_LOADTYPE option should always be considered in
conjunction with the PMF_RESET option. For example, if you specify both
RES_RESET and LT_NOMODIFY, the default viewing transformation in the target
presentation space is updated with that from the metafile, even though
LT_NOMODIFY means that such values should be ignored.


ΓòÉΓòÉΓòÉ 15.1.2.3.4. PMF_LCIDS Option ΓòÉΓòÉΓòÉ

The PMF_LCIDS option of GpiPlayMetaFile controls whether logical resources
referenced by a local identifier (lcid) are loaded from the metafile. Logical
resources include logical fonts and bit maps used as area-fill patterns. The
PMF_LCIDS option can have one of the values shown in the following table.

PMF_LCIDS Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue           ΓöéDescription                                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLC_LOADDISC     ΓöéLoads lcid-referenced resources from the    Γöé
Γöé                Γöémetafile.                                   Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéIf the lcids of those resources are already Γöé
Γöé                Γöéin use in the target presentation space, theΓöé
Γöé                Γöéresources currently identified by those     Γöé
Γöé                Γöélcids are deleted and their lcids are freed Γöé
Γöé                Γöébefore the metafile contents are loaded. TheΓöé
Γöé                Γöénew fonts and bit maps replace the existing Γöé
Γöé                Γöéones in the presentation space. (If the     Γöé
Γöé                Γöéoperating system uses a local identifier    Γöé
Γöé                Γöéthat the application has already defined,   Γöé
Γöé                ΓöéGpiPlayMetaFile deletes the existing        Γöé
Γöé                Γöéidentifier before using it for the metafile Γöé
Γöé                Γöéresource.)                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéLC_NOLOAD       ΓöéThe operating system uses the presentation  Γöé
ΓöéLC_DEFAULTS     Γöéspace's logical font and custom fill        Γöé
Γöé                Γöépattern; it will ignore any logical font or Γöé
Γöé                Γöécustom fill pattern in the metafile.        Γöé
Γöé                Γöé                                            Γöé
Γöé                ΓöéAn application can use the GpiSavePS and    Γöé
Γöé                ΓöéGpiRestorePS functions to maintain the localΓöé
Γöé                Γöéidentifiers it has already defined.         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.1.2.3.5. PMF_COLORTABLE Option ΓòÉΓòÉΓòÉ

The PMF_COLORTABLES option may be used to append or replace color table entries
in the presentation space from the metafile. The PMF_COLORTABLES option can
have one of the values shown in the following table.

PMF_COLORTABLES Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue               ΓöéDescription                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_REPLACE        ΓöéReplaces the logical color table in the Γöé
Γöé                    Γöépresentation space with the color table Γöé
Γöé                    Γöéin the metafile.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_REPLACEPALETTE ΓöéReplaces the current palette, if it     Γöé
Γöé                    Γöéexists, in the presentation space with  Γöé
Γöé                    Γöéthe palette in the metafile.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCTAB_NOMODIFY       ΓöéMaintains the logical color table in theΓöé
ΓöéCTAB_DEFAULT        Γöépresentation space.                     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.1.2.3.6. PMF_COLORREALIZABLE Option ΓòÉΓòÉΓòÉ

The PMF_COLORREALIZABLE option may be used to select whether color table from
the metafile is realized upon loading. The PMF_COLORREALIZEABLE option can have
one of the values shown in the following table.

PMF_COLORREALIZABLE Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue               ΓöéDescription                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCREA_DOREALIZE      ΓöéSets the realizable option when loading Γöé
Γöé                    Γöéthe color table.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCREA_NOREALIZE      ΓöéDoes not set the realizable option when Γöé
ΓöéCREA_DEFAULT        Γöéloading the color table.                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.1.2.3.7. PMF_DEFAULTS Option ΓòÉΓòÉΓòÉ

The PMF_DEFAULTS option can have one of the values shown in the following
table.

PMF_DEFAULTS Options for GpiPlayMetafile

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéValue               ΓöéDescription                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDDEF_LOADDISC       ΓöéReplaces the default attributes, defaultΓöé
Γöé                    Γöéviewing limits, and default arc         Γöé
Γöé                    Γöéparameters in the presentation space    Γöé
Γöé                    Γöéwith the values specified in the        Γöé
Γöé                    Γöémetafile.                               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDDEF_IGNORE         ΓöéMaintains the default attributes,       Γöé
ΓöéDDEF_DEFAULTS       Γöédefault viewing limits, and default arc Γöé
Γöé                    Γöéparameters in the presentation space.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.1.2.4. Saving a Metafile ΓòÉΓòÉΓòÉ

A metafile is not a permanent object and, unless it is explicitly saved,
disappears when the application that creates it ends.  Metafiles are saved in
disk files by calling GpiSaveMetaFile.

This function accepts as input the metafile handle and the name of the disk
file in which the metafile is to be saved.  As the disk file is created by this
function, an error condition is raised if a file with this name already exists.
When you call GpiSaveMetaFile, the memory version of the metafile is deleted.
Its handle is no longer valid, until the file is reloaded from disk.


ΓòÉΓòÉΓòÉ 15.1.2.5. Loading a Metafile ΓòÉΓòÉΓòÉ

A metafile saved on disk has to be reloaded before it can be used. Any
application with access to the disk file can transfer the file from disk
storage to application storage by calling GpiLoadMetaFile. GpiLoadMetaFile
returns a metafile handle, which identifies the metafile after it has been
loaded.


ΓòÉΓòÉΓòÉ 15.1.2.6. Editing a Metafile ΓòÉΓòÉΓòÉ

Metafiles can be edited in a manner similar to editing graphics segments. To
edit graphics orders in a metafile, an application transfers them into
application storage (an array of bytes) by calling the GpiQueryMetaFileBits
function. The number of graphics orders copied depends on the size of the array
that the application supplies.  The application can determine the size of the
metafile (in bytes) by calling the GpiQueryMetaFileLength function.  When the
application has finished editing the graphics orders, it can copy them back
into the metafile by calling the GpiSetMetaFileBits function.

Edited versions of metafiles can be saved by calling GpiSaveMetaFile. The disk
file that contains the edited version of the metafile cannot have the same name
as the file from which the metafile was originally loaded. GpiSaveMetaFile
raises an error condition if the disk file already exists.


ΓòÉΓòÉΓòÉ 15.1.2.7. Copying a Metafile ΓòÉΓòÉΓòÉ

A copy of a memory metafile can be made by calling GpiCopyMetaFile. PM makes a
copy of the metafile and returns a new handle to the new metafile.


ΓòÉΓòÉΓòÉ 15.1.2.8. Deleting a Metafile ΓòÉΓòÉΓòÉ

A memory metafile is deleted by calling GpiDeleteMetaFile. After the operation
is complete, the handle to the metafile no longer points to a usable object. A
disk file containing the metafile remains untouched by this operation. A disk
metafile is deleted by using operating system commands that delete any other
type of file.


ΓòÉΓòÉΓòÉ 15.1.3. Metafiles and the System Clipboard ΓòÉΓòÉΓòÉ

A metafile that you have created or loaded can be made available to other
applications at the same workstation by placing the handle to the metafile in
the system clipboard. When a resource is passed to the clipboard, it  becomes
the property of the system, and is not deleted when the owning application
ends. Any application that can access the clipboard can retrieve the handle to
the metafile.  Using the handle to the metafile, the application should copy
the metafile by calling GpiCopyMetaFile before closing the clipboard.  The
application can then perform any metafile operation on the metafile.

For more information on the system clipboard, see the Programming Guide Volume
II.


ΓòÉΓòÉΓòÉ 15.2. Using Metafiles ΓòÉΓòÉΓòÉ

Use metafile functions to:

o Create a metafile
o Draw into a metafile
o Load a metafile to disk
o Load a metafile from disk into an application
o Play a metafile
o Edit a metafile
o Copy a metafile
o Transfer metafile contents to application memory
o Transfer metafile contents from application memory.


ΓòÉΓòÉΓòÉ 15.2.1. Creating and Drawing into a Metafile ΓòÉΓòÉΓòÉ

To create a metafile, you must:

 1. Create a metafile device context with DevOpenDC.

 2. Create a presentation space with GpiCreatePS function, and associate the
    presentation space with the metafile device context.

 3. Draw into the metafile with various Gpi drawing functions.

 4. Disassociate the metafile device context from the presentation space with
    GpiAssociate.

 5. Close the metafile device context with DevCloseDC.

The following figure shows how to create a simple metafile that draws text
within the borders of a three-color box.

#include <os2.h>
void fncMETA01(void){
    DEVOPENSTRUC dop;
    HDC hdcMeta;
    HPS hpsMeta;
    HMF hmf;
    HAB hab;
    SIZEL sizlPage;
    POINTL ptl;

    dop.pszLogAddress = (PSZ) NULL;
    dop.pszDriverName = "DISPLAY";

    hdcMeta = DevOpenDC(hab,
        OD_METAFILE,                 /* Metafile device context             */
        "*",                         /* Ignores OS2.INI                     */
        2L,                          /* Uses first two fields               */
        (PDEVOPENDATA) &dop,         /* Device information                  */
        (HDC) NULLHANDLE);           /* Compatible device context           */

    hpsMeta = GpiCreatePS(hab,
        hdcMeta,                     /* Metafile device context             */
        &sizlPage,                   /* Page viewport                       */
        PU_PELS | GPIA_ASSOC);       /* Device units and associated context */

    /* Draw a box in a metafile. */

    GpiSetColor(hpsMeta, CLR_CYAN);

    ptl.x = 150; ptl.y = 200;
    GpiMove(hpsMeta, &ptl);


    ptl.x = 300; ptl.y = 275;
    GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);

    GpiSetColor(hpsMeta, CLR_GREEN);

    ptl.x = 300; ptl.y = 200;
    GpiMove(hpsMeta, &ptl);

    ptl.x = 390; ptl.y = 275;
    GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);


    GpiSetColor(hpsMeta, CLR_YELLOW);

    ptl.x = 390; ptl.y = 200;
    GpiMove(hpsMeta, &ptl);

    ptl.x = 530; ptl.y = 275;
    GpiBox(hpsMeta, DRO_FILL, &ptl, 0L, 0L);

    ptl.x = 175; ptl.y = 230;
    GpiMove(hpsMeta, &ptl);


    GpiSetColor(hpsMeta, CLR_PINK);

    GpiCharString(hpsMeta, 41,
        "METAFILE COPY METAFILE COPY METAFILE COPY");

    GpiAssociate(hpsMeta, (HDC) NULLHANDLE);
    hmf = DevCloseDC(hdcMeta);
} /* fncMETA01 */

Creating a Metafile


ΓòÉΓòÉΓòÉ 15.2.2. Drawing into a Metafile in Retain Mode ΓòÉΓòÉΓòÉ

To draw into a metafile, set the drawing mode to the appropriate value for your
application and then perform the drawing operations. The following figure shows
an example of how to copy the contents of a segment into a metafile.

#define INCL_GPIMETAFILES
#define INCL_GPICONTROL
#include <os2.h>
void fncMETA02(void){
    HDC hdcMeta, hdc;
    POINTL ptl;
    HMF hmf;
    LONG alOpt[10];
    HPS hps;

    /*
     * Open a segment, assign it an identifier of 10,
     * and draw some text into it.
     */

    GpiSetDrawingMode(hps, DM_RETAIN);
    GpiOpenSegment(hps, 10L);
    ptl.x = 175; ptl.y = 230;
    GpiMove(hps, &ptl);
    GpiSetColor(hps, CLR_PINK);
    GpiCharString(hps, 41,
        "METAFILE COPY METAFILE COPY METAFILE COPY");
    GpiCloseSegment(hps);

    GpiAssociate(hps, NULLHANDLE);   /* Disassociates PS and screen DC */
    GpiAssociate(hps, hdcMeta);      /* Associates PS and meta DC      */
    GpiDrawSegment(hps, 10L);        /* Draws segment into metafile    */
    GpiAssociate(hps, NULLHANDLE);   /* Disassociates PS and meta DC   */
    hmf = DevCloseDC(hdcMeta);       /* Closes metafile                */

    GpiAssociate(hps, hdc);          /* Associates PS and screen DC    */
    GpiSetDrawingMode(hps, DM_DRAW); /* Sets drawing mode to DM_DRAW   */

    /*
     * Load the array of options for GpiPlayMetaFile
     * with default values.
     */

    alOpt[PMF_SEGBASE]  = 0;                   /* Reserved                */
    alOpt[PMF_LOADTYPE] = LT_DEFAULT;          /* Default transformations */
    alOpt[PMF_RESOLVE]  = 0;                   /* Reserved                */
    alOpt[PMF_LCIDS]    = LC_DEFAULT;          /* Uses default lcids      */
    alOpt[PMF_RESET]    = RES_DEFAULT;         /* Uses default            */
    alOpt[PMF_SUPPRESS] = SUP_DEFAULT;         /* Uses default            */
    alOpt[PMF_COLORTABLES] = CTAB_DEFAULT;     /* Uses default            */
    alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT; /* Uses default            */

    GpiPlayMetaFile(hps,                  /* Plays metafile onto screen   */
        hmf, 8L, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA02 */


Copying a Graphic Segment to a Metafile

If you want to create a simple drawing in a metafile for repeated display, you
can set the drawing mode to DM_DRAW and draw directly into the metafile. The
code in the first code fragment shows an example of how to do this. You can
store named segments in the metafile that you are recording in DM_DRAW mode by
bracketing your output primitive functions between GpiOpenSegment and
GpiCloseSegment.


ΓòÉΓòÉΓòÉ 15.2.3. Copying a Metafile to Disk ΓòÉΓòÉΓòÉ

You can copy a metafile to disk using GpiSaveMetaFile function, and you can
load the file back into your application using GpiLoadMetaFile function. The
following figure shows an example of how to copy a metafile to a file named
META.MET, then load the same file back into the application and play it.

#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA03(void){
    HMF hmf;
    HAB hab;
    HPS hps;
    LONG alOpt[10];

    GpiSaveMetaFile(hmf, "meta.met");           /* Saves metafile on disk  */

    hmf = GpiLoadMetaFile(hab, "meta.met");     /* Loads metafile          */

    alOpt[PMF_SEGBASE]  = 0;                    /* Reserved                */
    alOpt[PMF_LOADTYPE] = LT_DEFAULT;           /* Default transformations */
    alOpt[PMF_RESOLVE]  = 0;                    /* Reserved                */
    alOpt[PMF_LCIDS]    = LC_DEFAULT;           /* Uses default lcids      */
    alOpt[PMF_RESET]    = RES_DEFAULT;          /* Uses default            */
    alOpt[PMF_SUPPRESS] = SUP_DEFAULT;          /* Uses default            */
    alOpt[PMF_COLORTABLES]     = CTAB_DEFAULT;  /* Uses default            */
    alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT;  /* Uses default            */

    GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA03 */


Copying a Metafile to Disk


ΓòÉΓòÉΓòÉ 15.2.4. Playing a Metafile ΓòÉΓòÉΓòÉ

The following figure shows an example of how to play the metafile using the
font, color table, and fill-pattern descriptions in your application's
presentation space.

#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA04(void){
    HPS hps;
    HMF hmf;
    LONG alOpt[10];

    alOpt[PMF_SEGBASE]  = 0;               /* Reserved                        */
    alOpt[PMF_LOADTYPE] = LT_DEFAULT;      /* Viewing transformation in PS    */
    alOpt[PMF_RESOLVE]  = RS_DEFAULT;      /* Reserved                        */
    alOpt[PMF_LCIDS]    = LC_DEFAULT;      /* Font and fill pattern in PS     */
    alOpt[PMF_RESET]    = RES_DEFAULT;     /* Page units and dimensions in PS */
    alOpt[PMF_SUPPRESS] = SUP_DEFAULT;     /* Draws metafile into PS          */
    alOpt[PMF_COLORTABLES]     = CTAB_DEFAULT;    /* Color table in PS        */
    alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT;    /* Sets realizable option   */

    GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA04 */


Playing a Metafile

The following figure shows an example of how to play a metafile using the font,
color table, and fill-pattern descriptions in the metafile.

#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA05(void){
    HPS hps;
    HMF hmf;
    LONG alOpt[10];

    alOpt[PMF_SEGBASE]  = 0;             /* Reserved                          */
    alOpt[PMF_LOADTYPE] = LT_DEFAULT;    /* Viewing transformation in PS      */
    alOpt[PMF_RESOLVE]  = RS_DEFAULT;    /* Reserved                          */
    alOpt[PMF_LCIDS]    = LC_LOADDISC;   /* Font and fill pattern in metafile */
    alOpt[PMF_RESET]    = RES_DEFAULT;   /* Page units and dimensions in PS   */
    alOpt[PMF_SUPPRESS] = SUP_DEFAULT;   /* Draws metafile into PS            */
    alOpt[PMF_COLORTABLES]     = CTAB_REPLACE;    /* Color table in metafile  */
    alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT;    /* Sets realizable option   */

    GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA05 */


Playing a Metafile Using Font, Color, and Fill-Pattern Descriptions

The following figure shows an example of how to play a metafile using the
viewing transformation, page units, and presentation-page dimensions specified
in the metafile.

#define INCL_GPIMETAFILES
#include <os2.h>
void fncMETA06(void){
    HPS hps;
    HMF hmf;
    LONG alOpt[10];

    alOpt[PMF_SEGBASE]  = 0;                    /* Reserved                    */
    alOpt[PMF_LOADTYPE] = LT_ORIGINALVIEW;      /* Viewing transformation      */
    alOpt[PMF_RESOLVE]  = RS_DEFAULT;           /* Reserved                    */
    alOpt[PMF_LCIDS]    = LC_DEFAULT;           /* Font and fill pattern in PS */
    alOpt[PMF_RESET]    = RES_RESET;            /* Page units/dimensions       */
    alOpt[PMF_SUPPRESS] = SUP_DEFAULT;          /* Draws metafile into PS      */
    alOpt[PMF_COLORTABLES]     = CTAB_DEFAULT;  /* Uses color table in PS      */
    alOpt[PMF_COLORREALIZABLE] = CREA_DEFAULT;  /* Sets realizable option      */

    GpiPlayMetaFile(hps, hmf, 8, alOpt, (PLONG) NULL, 0L, (PSZ) NULL);
} /* fncMETA06 */

Playing a Metafile Using Transformation and Page Units


ΓòÉΓòÉΓòÉ 15.3. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the metafile object functions.

Metafile Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name           ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevCloseDC              ΓöéCloses a metafile device context andΓöé
Γöé                        Γöéreturns a handle that identifies a  Γöé
Γöé                        Γöémetafile.                           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDevOpenDC               ΓöéCreates a metafile device context   Γöé
Γöé                        Γöéwhen you pass it the OD_METAFILE    Γöé
Γöé                        Γöéconstant as the second argument.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCopyMetaFile         ΓöéCreates a copy of a metafile.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiDeleteMetaFile       ΓöéDeletes a metafile.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiLoadMetaFile         ΓöéLoads data from disk storage into a Γöé
Γöé                        Γöémetafile and returns a handle that  Γöé
Γöé                        Γöéidentifies the metafile.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPlayMetaFile         ΓöéPlays the contents of a metafile    Γöé
Γöé                        Γöéinto a presentation space.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMetaFileBits    ΓöéCopies the contents of a metafile   Γöé
Γöé                        Γöé(such as drawing orders, color-tableΓöé
Γöé                        Γöédescription, and page units) into anΓöé
Γöé                        Γöéarray of bytes. The number of bytes Γöé
Γöé                        Γöécopied depends on the size of the   Γöé
Γöé                        Γöéarray.                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryMetaFileLength  ΓöéRetrieves the size of a metafile in Γöé
Γöé                        Γöébytes. You use this function to     Γöé
Γöé                        Γöédetermine the size of the array you Γöé
Γöé                        Γöéwill need when you issue the        Γöé
Γöé                        ΓöéGpiQueryMetaFileBits function.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSaveMetaFile         ΓöéCopies a metafile to a disk and thenΓöé
Γöé                        Γöéremoves it from your application's  Γöé
Γöé                        Γöémemory.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetMetaFileBits      ΓöéCopies drawing orders from an array Γöé
Γöé                        Γöéof bytes to a metafile. You use thisΓöé
Γöé                        Γöéfunction to copy drawing orders backΓöé
Γöé                        Γöéinto a metafile from application    Γöé
Γöé                        Γöémemory.                             Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 16. Clipping and Boundary Determination ΓòÉΓòÉΓòÉ

Both Clipping and boundary determination are graphics operations concerned with
limiting the amount of graphics information passed between different coordinate
spaces. The following topics are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Coordinate spaces
o Transformations
o Regions
o Paths.


ΓòÉΓòÉΓòÉ 16.1. About Clipping ΓòÉΓòÉΓòÉ

Clipping enables the PM programming interface to discard parts of a picture
that lie outside a specified clipping boundary.  The parts of the picture
enclosed by the boundary are said to be inside the clipping area.  A clipping
area might be a single rectangle or a complex shape, depending on the method
used to define it.

Note:  In this chapter, the word area does not refer to an area primitive; it
       describes the shape or shapes used for clipping graphics output.

If an application attempts to draw outside of a clipping area, the operating
system ensures that the output does not appear on the drawing surface of the
output device. For example, if an application defined a triangular clipping
area before drawing text output, all text outside of the triangle would be
discarded, even though an entire page of text was defined. The following figure
illustrates the result.

Triangular Clip Path

Clipping boundaries are defined by the application. The PM programming
interface performs some clipping automatically when, for example, your
application's graphic output is clipped to fit a client window area or the
device's output area for a hardcopy device.


ΓòÉΓòÉΓòÉ 16.1.1. Types of Clipping Areas ΓòÉΓòÉΓòÉ

Clipping can occur at each stage in the viewing pipeline. The viewing pipeline
is described and illustrated in Coordinate Spaces and Transformations. Objects
in world coordinate, model, page, or device space can be clipped. When an
application defines clipping areas in several coordinate spaces, the final
result is similar to combining all the areas into a single clipping area. This
single area is defined by the intersection of the areas in each coordinate
space.

Clipping in different coordinate spaces, however, is a means of conceptualizing
the process to aid in its understanding. Clipping, like transformations,
actually happens in one operation, with all the different types of clipping
being performed on all primitives in the device space at once.

The following table describes the different types of clipping areas associated
with the different coordinate spaces.

Clipping Areas and Coordinate Space Summary

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéClipping Area   ΓöéCoordinate SpaceΓöéDescription                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéClip path       ΓöéWorld space     ΓöéAlways inclusive/inclusive  Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéClipping area can have      Γöé
Γöé                Γöé                Γöécurved edges                Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéClipping area can be        Γöé
Γöé                Γöé                Γöérotated.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéViewing limit   ΓöéModel space     ΓöéAlways a rectangular        Γöé
Γöé                Γöé                Γöéclipping boundary           Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéAlways inclusive/inclusive  Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéRotating clipping area      Γöé
Γöé                Γöé                Γöéresults in larger rectangle.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGraphics field  ΓöéPage space      ΓöéAlways a rectangular        Γöé
Γöé                Γöé                Γöéclipping boundary           Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéAlways inclusive/inclusive  Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéRotating clipping area      Γöé
Γöé                Γöé                Γöéimpossible. Cannot specify aΓöé
Γöé                Γöé                Γöédevice transform with       Γöé
Γöé                Γöé                Γöérotation.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéClip region     ΓöéDevice space    ΓöéCan be a single rectangle orΓöé
Γöé                Γöé                Γöémultiple rectangles that    Γöé
Γöé                Γöé                Γöéoverlap or remain separate  Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéAlways inclusive/exclusive  Γöé
Γöé                Γöé                Γöé                            Γöé
Γöé                Γöé                ΓöéRotating the clipping area  Γöé
Γöé                Γöé                Γöéis impossible.              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  Inclusive/inclusive means that the operating system includes the bottom
and leftmost edges of the rectangle in the clipping area as well as the top and
rightmost edges. Inclusive/exclusive means that the operating system includes
the bottom and leftmost edges but excludes the top and rightmost edges. This
concept is illustrated in the following figure.

The followingfigure illustrates the differences between inclusive-inclusive and
inclusive-exclusive clipping. dup.

Inclusive/Inclusive and Inclusive/Exclusive Clipping


ΓòÉΓòÉΓòÉ 16.1.1.1. The Clip Path ΓòÉΓòÉΓòÉ

The clip path defines the clipping boundary in world coordinate space. Paths
are graphic objects that serve many purposes, only one of which is to be used
as a clipping mechanism. Paths are described in Paths. The recommended
functional sequence for creating a clip path is as follows:

Function                 Effect

GpiBeginPath             Begins the path definition.

Line and arc GPIs        Gives the path shape.

GpiEndPath               Ends the path definition.

GpiModifyPath            An optional step explained below.

GpiSetClipPath           Converts the path to a clip path.

Before converting to a clip path, the path can be modified using GpiModifyPath.
If modified, the path is converted to a geometric (wide) line using the current
geometric width, line join, and line end attributes. The shape defined by the
geometric line then is used for the clip path. The clip path can be a simple
unmodified path.

GpiSetClipPath accepts two different path identifiers as input:

o 1
o 0 (default).

The default path identifier of 0, called SCP_RESET, resets the clip path to
infinity, which displays the picture without clipping. If this value is
selected, the current clip path definition is discarded instead of stored.

A path identifier of 1 is called SCP_AND and specifies that the clip path be
redefined as the mathematical intersection of the stored clip path and the
current path definition. The only method of specifying the clip path to the
current path, after GpiSetClipPath has been issued, is to issue GpiSetClipPath
twice:  the first issuance with a path identifier of 0; the second, a path
identifier of 1.

The following figure shows a triangle shape that has been defined within a path
bracket and selected as the current clip path. The filled box shape is drawn
subsequently, and, therefore, is clipped to the triangle.

The Clipping Path

The broken lines show the area of the box that has been clipped.

Clip paths are most useful when you want to use an irregular clipping boundary,
or when the clipping boundary itself is an integral part of the picture. Both
are true of the clip path in the previous figure.

GpiSetClipPath also accepts 1 of 2 construction options as input:

o SCP_ALTERNATE (default)
o SCP_WINDING (must be selected if path has been modified).

Any drawing that is clipped to the current clip path must follow the alternate
or the winding rules as to whether that portion of a picture is included in the
clip area. The alternate and winding modes are described for paths in Paths in
Alternate Mode and Paths in Winding Mode. Any point on the boundary of the path
is considered within the path and is not clipped.

To end clipping to the current clip path, issue GpiSetClipPath with an
identifier of 0. This function deselects the current clip path by setting it to
infinity. In some circumstances, the current clip path is deselected
automatically.

A path definition can be stored in a graphics segment; and, if that segment is
retained, the path can be re-created as required when the segment is redrawn.
Clip path definitions can be stored in a retained segment also and redrawn when
required. In draw-and-retain mode, the initial path or clip path is created as
the segment is constructed. If the current drawing mode is retain, however, the
path or clip path is not created until the first time the segment is drawn.


ΓòÉΓòÉΓòÉ 16.1.1.2. The Viewing Window ΓòÉΓòÉΓòÉ

The viewing window defines a rectangular clipping boundary in model space.  It
is defined with GpiSetViewingLimits. As input to this function, you supply the
model coordinates of the lower-left and upper-right corners of the viewing
window.

When a drawing primitive, such as a line, intersects a viewing window, any part
of that line outside of the viewing window is clipped. Any point on the
boundary of the viewing window is considered within the window, and is not
clipped. By default, the viewing window performs no clipping. In this case, all
graphics output in the model space is transformed. The following figure shows
how the viewing window outlines a part of model space.

The Viewing Window

This example shows how a presentation page is constructed. The viewing window
outlines the tail of the aircraft, which is scaled and translated when drawn in
presentation-page space.  The rest of the aircraft is clipped away during the
drawing process.


ΓòÉΓòÉΓòÉ 16.1.1.3. The Graphics Field ΓòÉΓòÉΓòÉ

The graphics field defines a rectangular clipping area in the presentation
page.  It is defined in GpiSetGraphicsField.

Note:  If this clipping area is to be used, it must be defined before any
       drawing begins.

Specify the size of the graphics field in presentation page coordinates as
input to GpiSetGraphicsField.

Only the graphic output contained in this clipping boundary is visible when the
presentation page is transformed to device space. By default, the graphics
field is infinitely large and, therefore, performs no clipping. If you do
specify a graphics field, however, any point on its boundary is considered
within the graphics field and is not clipped. When a drawing primitive, such as
a line, intersects a graphic field, any part of the line outside the graphics
field is clipped. The following figure shows how a graphics field could be
defined for a presentation page.

The Graphics Field

The broken line shows an arbitrary graphics field that is smaller than the
presentation page. The aircraft tail, a separate object in the presentation
page, is outside the graphics field and is clipped away as it is drawn.

The picture assembled in the graphics field is the picture that is displayed or
printed. If you do not define a graphics field, the picture assembled in the
presentation page is the picture that is displayed or printed. The presentation
page is not a clipping boundary, and graphics in page coordinate space that are
outside the presentation page boundary, therefore, might be visible.


ΓòÉΓòÉΓòÉ 16.1.1.4. The Current Clipping Region ΓòÉΓòÉΓòÉ

Clipping regions are clipping areas defined (as regions) by one or more
rectangles in device coordinates. Because they are defined in device
coordinates, clipping regions do not suffer from the rounding errors associated
with other types of clipping. Therefore, they are ideally suited to redraw part
of the picture without boundary discontinuities, for example, after a BitBlt
operation has been used to scroll a picture in a window.

Regions are not available automatically for clipping. To select an existing
region as the current clipping region, use GpiSetClipRegion. By default, the
clipping region is the same size as the drawing surface. Only one clipping
region can exist in the presentation space at one time.  To end clipping to the
current clipping region, deselect it by issuing GpiSetClipRegion with a NULL
region handle. A deselected clipping region retains the effects of any changes
made to it while it was a clipping region and can be reselected.

You do not have to deselect the current clipping region before selecting
another.  Each selected clipping region automatically replaces the one before
it. If a clipping region exists when you issue GpiSetClipRegion, the existing
clipping region reverts to being a normal region, and its handle is returned.

Clip paths and clip regions share a common implementation, but clip regions are
faster to create than clip paths. This might be a performance factor when
designing your application for repairing the screen, or redrawing the picture
in a client window after the display has changed. The following figure
illustrates this use of regions.

Screen Repairing

Note:  GpiSetClipRegion does not cause graphics orders to be added to the
       current segment. Therefore, variations in the clip region must not be
       used to construct the picture. The clip region is intended to define a
       fixed clipping area for the entire picture.

When you select the current clipping region, none of the region-related GPI
functions can be used for that region. The PM programming interface provides a
series of functions that mirror the region-related functions.  However, all of
these functions work in world coordinates rather than device coordinates, and,
therefore, are subject to current transformations.

Any of the following functions can be used to get information about or to
redefine the current clipping region.

o GpiQueryClipBox

  You can request the dimensions of the smallest rectangle that encloses all
  current clipping boundaries by issuing GpiQueryClipBox. The following
  boundaries are included in this calculation:

   - Current clip path
   - Current viewing window
   - Current graphics field
   - Current clipping region
   - Visible region of the window.

o GpiIntersectClipRectangle

  GpiIntersectClipRectangle redefines the current clipping region to the
  intersection of the existing clipping region with the rectangle whose
  dimensions you supply in this function. This has the same effect as CRGN_AND
  in GpiCombineRegion.

o GpiExcludeClipRectangle

  You also can redefine the current clipping region using
  GpiExcludeClipRectangle.  This function excludes a specified rectangle from
  the current region, and has the same effect as CRGN_DIFF on GpiCombineRegion.

o GpiOffsetClipRegion

  The current clipping region can be moved from its current position using
  GpiOffsetClipRegion.

o GpiPtVisible

  GpiPtVisible tells you whether a point, expressed in world coordinates, is
  visible on the screen. A point is visible if it is within all current
  clipping boundaries and is in the visible region of the window.

o GpiRectVisible

  GpiRectVisible tells you whether any part or the whole of a rectangle, whose
  dimensions you supply in world coordinates, is visible on the screen. The
  rectangle is visible if it intersects both the visible region of the window
  and all current clipping boundaries.


ΓòÉΓòÉΓòÉ 16.1.2. How Clipping Is Implemented ΓòÉΓòÉΓòÉ

The rules by which the PM programming interface implements clipping are as
follows:

o Any primitive completely outside the clipping boundary is discarded.

  When a primitive crosses a clipping boundary, any part outside the boundary
  is discarded.

o Any primitive completely within the clipping boundary is retained.

  When a primitive crosses a clipping boundary, any part within the boundary is
  retained.

o When the clipping boundary is a clip path, viewing window, or graphics field,
  any point that falls on the boundary is considered within the clipping
  boundary.

  When the clipping boundary is a clipping region, any point on the top or
  right boundaries of a rectangle is discarded; and any point on the bottom or
  left boundaries of a rectangle, that is not on the right or top boundaries
  also, is included in the region.


ΓòÉΓòÉΓòÉ 16.1.3. Redrawing Nondynamic Graphics ΓòÉΓòÉΓòÉ

An interactive graphics application usually permits changes to the displayed
picture, for example, an object can be moved or sized; and you can plan for
this by defining particular segments as dynamic.  Dynamic segments are
described in Editing Retained Graphics and Graphics Segments.

If dynamic segments are inappropriate (when you are using nonretained graphics,
for example), you can repair the picture using a clipping region, for example,
a picture of a hexagon and a circle as shown in the following figure.

A Hexagon and Circle

If the circle is moved to another screen position by the use of an input
device, you must repair its original location, and redraw it in its new
location. The following figure shows this sequence of events. Following are the
steps required to do this:

 1. Determine the size of the smallest rectangle that contains the circle in
    its current position using a process called boundary determination.

 2. Switch off the DCTL_DISPLAY flag of GpiSetDrawControl, apply a translation
    transformation to the circle, and redraw it in its new position.

 3. Determine the size of the smallest rectangle that contains the circle in
    its new position using boundary determination.

 4. Use GpiConvert to convert the model-space coordinates provided by the
    boundary-determination process to device-space coordinates.

 5. Use the device-space coordinates of the two rectangles to create a region,
    and select it as the current clipping region.

 6. Switch on the DCTL_DISPLAY flag of GpiSetDrawControl.

 7. Issue GpiErase (or set the erase-before-draw control) to erase the current
    contents of the clipping region.

 8. Redraw the picture with the circle in its new position. Any part of the
    picture within the clipping region is redrawn. That part of the hexagon
    that is outside the clipping region is unaffected by the change and does
    not have to be redrawn.

Defining a Clipping Region

The broken circle shows the position to which the circle is to be moved.  The
two bounding rectangles overlap, and produce a complex region.  If the circle
were to be moved much farther away from its start position, the region would
comprise two disjoint rectangles.


ΓòÉΓòÉΓòÉ 16.2. About Boundary Determination ΓòÉΓòÉΓòÉ

Boundary determination is an operation to compute the size of the smallest
rectangle that encloses a graphics output in model space.  One use of boundary
determination is to enable you to repair only the affected parts of the screen,
when a graphics object is moved, for example, or when a graphics object is
changed some other way. Dynamic segments are not included in
boundary-determination operations.

Boundary determination can be performed on both retained and nonretained
graphics.  In both instances, you request boundary data to be calculated by
setting the boundary data flag (DCTL_BOUNDARY) in GpiSetDrawControl. If you do
not set this flag (for example, if you do not want to collect boundary data
unnecessarily) and later find that you need boundary data for a particular
object, you can do the following:

 1. Switch on the boundary-data flag, and switch off the display flag, using
    GpiSetDrawControl.

 2. Redraw the object in its current location. Boundary data is collected, but
    the object is unaltered.

If you are drawing retained graphics, each drawing request (GpiDrawSegment,
GpiDrawFrom, and GpiDrawChain) causes the boundary data resulting from the
drawing to be made available. The application must request this data explicitly
by issuing GpiQueryBoundaryData after each drawing request for which it wants
to examine boundary data. Boundary data is returned to the application in model
space coordinates. The boundary data is reset before each retained drawing
operation, so there is no risk of accumulating data from separate operations.

If you are drawing nonretained graphics, boundary data is accumulated for each
GpiPutData and for each individual primitive-drawing function. The application
can request the accumulated boundary data at any time by issuing
GpiQueryBoundaryData. Data continues to accumulate unless you issue the
GpiResetBoundaryData; it is not reset automatically.

The boundary data returned to you is in the form of 4 model-space coordinates,
which are the lowest (x,y) positions and the highest (x,y) positions of the
bounding rectangle in model space, as illustrated in the following figure.

The Bounding Rectangle


ΓòÉΓòÉΓòÉ 16.3. Using Clipping and Boundary Determination ΓòÉΓòÉΓòÉ

This section explains how to use clipping functions to:

o Create a clip path or clip region
o Exclude a rectangular area from a clip region
o Add a rectangular area to a clip region
o Set the clip region to the intersection of the current clip region and a
  specified rectangle
o Determine the size of the smallest rectangle that will surround the
  intersection of the current clipping areas completely.


ΓòÉΓòÉΓòÉ 16.3.1. Creating a Clip Path ΓòÉΓòÉΓòÉ

A drawing and computer-aided-design (CAD) application may require the ability
to clip to curved edges.  If so, it must use a clip path to define a curved
clipping area in world coordinates.  Because clip paths (especially ones that
clip to curved edges) require considerable memory and processing time, use them
only when necessary; whenever possible, your application must use a clip
region, graphics field, or viewing limit.

To create a clip path, do the following:

 1. Determine the clip path's shape and size (in world coordinates).

 2. Issue GpiBeginPath to begin defining the path.

 3. Create the path.

 4. Close the path definition with GpiEndPath.

 5. Create a clip path from the path definition with GpiSetClipPath.

The following figure uses this procedure to create an elliptical clip path.

#define INCL_GPIPATHS
#include <os2.h>
void fncCLIP01(void){
    HPS    hps;                      /* Presentation-space handle */
    POINTL ptl1;                     /* Point structure           */
    FIXED  fxArc;                    /* Multiplier for arc        */
    LONG idPath;                     /* Path identifier           */
        .
        .           /* Load ptl1 with coordinates of clip path.   */
        .
    idPath = 1;
    GpiBeginPath(hps, idPath);       /* Begins path               */
    GpiMove(hps, &ptl1);             /* Sets current position     */
    fxArc  = MAKEFIXED(50, 0);       /* Sets arc multiplier       */
    GpiFullArc(hps, DRO_OUTLINE, fxArc);  /* Defines ellipse      */
    GpiEndPath(hps);                 /* Ends path                 */
    GpiSetClipPath(hps, idPath, SCP_ALTERNATE | SCP_AND);
} /* fncCLIP01 */


Creating a Clip Path


ΓòÉΓòÉΓòÉ 16.3.2. Creating a Clip Region ΓòÉΓòÉΓòÉ

To create a clip region, first determine its size and shape (in device
coordinates).  Load the coordinates for the rectangles that define the clip
region into an array of RECTL structures. Then create the region and set it to
a clip region with GpiCreateRegion and GpiSetClipRegion respectively.

The following figure shows how to create a clip region.

#include <os2.h>
void fncCLIP02(void){
    HPS  hps;
    HRGN hrgn;
    RECTL arcl[3];
        .
        .  /* Load array of RECTL structures with coordinates.       */
        .
    hrgn = GpiCreateRegion(hps, sizeof(arcl) / sizeof(RECTL), arcl);
    GpiSetClipRegion(hps, hrgn, NULL);
} /* fncCLIP02 */


Creating a Clip Region


ΓòÉΓòÉΓòÉ 16.3.3. Excluding a Rectangular Area from a Clip Region ΓòÉΓòÉΓòÉ

Some applications let you prepare output in multiple stages. For example, a
word-processing application might permit you to prepare your text first and
then add bit maps that enhance and support the text. These applications can use
GpiExcludeClipRectangle to exclude an area from a clip region, preventing the
user from deleting output that already exists.

To exclude an area from a clip region, first determine the dimensions (in
device coordinates) of the smallest rectangle that completely surrounds the
area to exclude from the clip region. Then, issue GpiExcludeClipRectangle,
including, as input, the dimensions of the area to exclude. The following
figure illustrates these steps.

#include <os2.h>
void fncCLIP03(void){
    HPS   hps;
    RECTL rcl;
        .
        .  /* Set rectangle coordinates here. */
        .
    GpiExcludeClipRectangle(hps, &rcl);
} /* fncCLIP03 */


Excluding a Rectangular Area from a Clip Region


ΓòÉΓòÉΓòÉ 16.3.4. Adding a Rectangular Area to a Clip Region ΓòÉΓòÉΓòÉ

Some applications might need to increase the size of a clip region. For
example, a user might request that a desktop-publishing application extend a
column of text on a page.

To add a rectangular area to a clip region, follow these steps:

 1. Determine the dimensions (in device coordinates) of the rectangular area to
    add to the current clip region.

 2. Release the current clip region using GpiSetClipRegion. GpiCombineRegion
    cannot combine regions if either of the regions is a clip region.

 3. Issue GpiCreateRegion and pass it the dimensions of the rectangle that you
    defined in Step 1. This creates a second region that you can combine with
    the first.

 4. Reissue GpiCreateRegion and create a third region that will be the final
    destination region.

 5. Issue GpiCombineRegion to create a region that combines the original region
    and the region you created in Step 2. It is not essential to create a third
    region because GpiCombineRegion can use one of the 2 source regions being
    combined for a target region.

 6. Issue GpiSetClipRegion and pass it the handle returned by GpiCombineRegion.

The following figure illustrates these steps.

#define INCL_GPIREGIONS
#include <os2.h>
void fncCLIP04(void){
    HPS   hps;
    RECTL rcl1, rcl2, rcl3;
    HRGN  hrgn1, hrgn2, hrgn3;

    hrgn1 = GpiCreateRegion(hps, sizeof(rcl1) / sizeof(RECTL), &rcl1);
    GpiSetClipRegion(hps, hrgn1, NULL);       /* Creates first clipping region */
        .
        .  /* Compute coordinates of second region here.                       */
        .
    GpiSetClipRegion(hps, NULLHANDLE, NULL);  /* Releases first clipping region*/
    hrgn2 = GpiCreateRegion(hps, sizeof(rcl2) / Sizeof(RECTL), &rcl2);
    hrgn3 = GpiCreateRegion(hps, sizeof(rcl3) / Sizeof(RECTL), &rcl3);
    GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
    GpiSetClipRegion(hps, hrgn3, NULL);       /* Creates second clipping region*/
} /* fncCLIP04 */


Adding a Rectangular Area to a Clip Region

This operation also could be performed with GpiIntersectClipRectangle.


ΓòÉΓòÉΓòÉ 16.3.5. Setting the Clip Region to a Region Intersection ΓòÉΓòÉΓòÉ

Your application might require the ability to set the clip region to the
intersection of the current clip region and another region.  Do this with
GpiIntersectClipRectangle, as shown in the following figure.

#include <os2.h>
void fncCLIP05(void){
    RECTL rcl;
    HPS hps;
        .
        . /* Load rcl with coordinates of rectangle to intersect. */
        .
    GpiIntersectClipRectangle(hps, &rcl);
} /* fncCLIP05 */


Setting the Clip Region to a Region Intersection


ΓòÉΓòÉΓòÉ 16.3.6. Determining the Size of a Clipping Area ΓòÉΓòÉΓòÉ

If an application is able to specify a clip path in world space, a viewing
limit in model space, a graphics field in page space, and a clip region in
device space, it might be necessary for your application to determine the size
of the clipping area formed by the intersection of the four. GpiQueryClipBox
returns the dimensions (in world coordinates) of the smallest rectangle that
completely surrounds the intersection of all the defined clipping areas,
including the visible region.

The following figure shows how to use GpiQueryClipBox to fill a RECTL structure
with the desired coordinates.

#include <os2.h>
void fncCLIP06(void){
    HPS   hps;
    RECTL rclClip;
    GpiQueryClipBox(hps, &rclClip);
} /* fncCLIP06 */


Determining the Size of a Clipping Area


ΓòÉΓòÉΓòÉ 16.4. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the functions used to perform clipping.

Clipping Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name             ΓöéDescription                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiExcludeClipRectangle   ΓöéExcludes a specified rectangle    Γöé
Γöé                          Γöéfrom the current clipping region. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiIntersectClipRectangle ΓöéCombines a rectangle with the     Γöé
Γöé                          Γöécurrent clipping region to form a Γöé
Γöé                          Γöénew clipping region.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiOffsetClipRegion       ΓöéMoves the clipping region by a    Γöé
Γöé                          Γöéspecified amount.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPtVisible              ΓöéDetermines whether a point, given Γöé
Γöé                          Γöéin world coordinates, is within   Γöé
Γöé                          Γöéall current clipping boundaries.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryClipBox           ΓöéDetermines the smallest rectangle Γöé
Γöé                          Γöéthat encloses all current clippingΓöé
Γöé                          Γöéboundaries.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryClipRegion        ΓöéDetermines the handle of the      Γöé
Γöé                          Γöécurrently selected clip region.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryGraphicsField     ΓöéDetermines the location, in page  Γöé
Γöé                          Γöécoordinates, of the lower-left andΓöé
Γöé                          Γöéupper-right corners of the currentΓöé
Γöé                          Γöégraphics field rectangle.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryViewingLimits     ΓöéDetermines the location, in model Γöé
Γöé                          Γöécoordinates, of the lower-left andΓöé
Γöé                          Γöéupper-right corners of the currentΓöé
Γöé                          Γöéviewing limits rectangle.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRectVisible            ΓöéDetermines whether any part or theΓöé
Γöé                          Γöéwhole of a rectangle, given in    Γöé
Γöé                          Γöéworld coordinates, is within all  Γöé
Γöé                          Γöécurrent clipping boundaries.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetClipPath            ΓöéDefines the current path as a clipΓöé
Γöé                          Γöépath.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetClipRegion          ΓöéDefines the current region as a   Γöé
Γöé                          Γöéclip region.                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetGraphicsField       ΓöéDefines the rectangle in          Γöé
Γöé                          Γöépresentation-page space as the    Γöé
Γöé                          Γöégraphics field clipping boundary. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetViewingLimits       ΓöéDefines the rectangle in model    Γöé
Γöé                          Γöéspace as the viewing limits       Γöé
Γöé                          Γöéclipping boundary.                Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structure used by the functions that
perform clipping.

Clipping Structure

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRECTL                   ΓöéA structure specifying the values ofΓöé
Γöé                        Γöétwo (x,y) coordinate pairs, definingΓöé
Γöé                        Γöéthe bottom-left and top-right       Γöé
Γöé                        Γöécoordinates of a rectangle.         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 17. Coordinate Spaces and Transformations ΓòÉΓòÉΓòÉ

A transformation is an operation performed on a graphic object that changes the
object in one of four ways:  translation, rotation, scaling and shearing.
Transformations enable an application to control the location, orientation,
size, and shape of graphics output on any output device.

The transformation of graphic output can be conceptually divided into a series
of distinct transformations applied from 1 logical stopping point to another.
Coordinate spaces are used as a method of conceptualizing these logical
stopping points. The coordinate spaces are concepts used to explain and
manipulate the transformation process.

A graphic primitive in an intermediate coordinate space cannot be displayed on
an output device and a transformation cannot be interrupted at one of the
distinct stages. The entire series of transformation steps, is applied all at
once.

This chapter describes the transformation design process. The following topics
are related to the information in this chapter:

o Presentation spaces
o Device contexts
o Segments and retained graphics
o Clipping.


ΓòÉΓòÉΓòÉ 17.1. About Coordinate Spaces ΓòÉΓòÉΓòÉ

Most of the GPI functions draw their output in a conceptual area called the
world coordinate space. If you picture the presentation space as a blank canvas
on which to draw, the world coordinate space is a Cartesian grid that provides
a reference of scale for what is being drawn.

The components of a picture defined in a world coordinate space are often
defined to a scale convenient only to that component. Applications also can
define each component, or subpicture, starting at the origin (0,0). This
enables applications to define the scale of a subpicture and the location of
the subpicture separately. The ability to define all subpictures at the origin
means there is not always 1-to-1 correspondence between a presentation space
and a world coordinate space. Frequently a separate world coordinate space
exists for every subpicture.

After subpictures are defined in the world coordinate space, they undergo a
process called transformation then appear on an output device. If an
application has not specifically applied a transformation to its subpictures,
by default the PM programming interface applies the identity transformation,
which, in effect, makes no changes to the subpicture.

All graphics systems, not just the PM programming interface, use at least 1
coordinate space to generate output. The simplest graphics systems use a single
coordinate space, whose points are the pels on the display. These are sometimes
called single-space systems.

The PM programming interface creates multiple coordinate spaces and uses
transformations to move subpictures between the coordinate spaces. The PM
programming interface assembles the application's graphic output in a process
that can use up to 5 coordinate spaces, known collectively as the viewing
pipeline. The PM programming interface coordinate spaces are:

o World Coordinate Space
o Model Space
o Page Space
o Device Space
o Media Space.
For those who are more familiar with a graphics system that uses a
single-coordinate space, the following table lists the differences to expect
when using PM's multi-coordinate space.

Single-Coordinate vs. Multi-Coordinate Space Systems

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéSingle-Coordinate Space       ΓöéPM Multi-Coordinate System    Γöé
ΓöéSystems                       Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDistances and locations       ΓöéSeven units of measurement,   Γöé
Γöéspecified in pels.            Γöéincluding pels, are available.Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéBecause the shape, or aspect  ΓöéThe output is device          Γöé
Γöératio, and size of pels can   Γöéindependent.                  Γöé
Γöévary on different devices, theΓöé                              Γöé
Γöégraphic primitives on 1 deviceΓöé                              Γöé
Γöémight look different on       Γöé                              Γöé
Γöéanother.                      Γöé                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCoordinates entered must      ΓöéCoordinates are made device   Γöé
Γöéalready be device coordinates.Γöécompatible through the PM     Γöé
Γöé                              Γöéprogramming interface.        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Additionally, a single-space system requires that applications keep track of:

o The scaling between the subpictures. Often this is accomplished by forcing
  the definition of objects to the scale of the picture, instead of to the
  scale of the subpicture.

o The scaling between the creation space and output space. Often this is
  accomplished by forcing the definition of objects to the scale of the paper
  or window, instead of to the scale of the subpicture.

o All aspects of other transformations.


ΓòÉΓòÉΓòÉ 17.1.1. World Coordinate Space ΓòÉΓòÉΓòÉ

The world coordinate space is where most drawing coordinates are specified.
Each primitive in a world coordinate space is defined using the coordinate
positions in the primitive's definition. For example, if an application draws a
line from (8,4) to (20,75), the coordinate values (8,4) and (20,75) are world
coordinates.

The world coordinate space is specified when the presentation space is created
with GpiCreatePS. The PS_FORMAT option supports 2 sizes of world coordinate
spaces:  short and long. If the size is short (GPIF_SHORT), the world
coordinate space is a rectangular Cartesian space with maximum coordinates of
(32767, 32767) and minimum coordinates of (-32768, -32768). If the world
coordinate space is short, it is the application's responsibility to ensure
that the coordinates defining the subpicture fall within this range.

The second size, long (GPIF_LONG), is the default for the world coordinate
space. Most GPI functions that direct their output to the world coordinate
space, for example GpiLine, accept 32-bit integers as parameters. A 32-bit
integer is equivalent to a rectangular Cartesian space with maximum coordinates
of (134217727, 134217727) and minimum coordinates of (-134217728, -134217728).

World coordinates do not have to be within the range of the presentation page.
A graphic image that requires a high degree of detail and precision might use
most or all of the available coordinate range. A transformation is used to
scale the graphic image down to an appropriate size. The actual presentation
page size is unimportant in most cases. It is used with the page viewport to
redefine the device transform if GpiSetPageViewport is called.

An application can use a clip path clipping area to define the part of the
world space to place in the next coordinate space (the model space). A clip
path is the only clipping region that can be nonrectangular. Its edges can
include arcs, curves, and straight lines. The coordinates that define the
dimensions and shape of a clip path are always world coordinates. (Clipping is
further described in Clipping and Boundary Determination.)

In a world-coordinate space, there can be several graphic primitives. If,
however, an application uses the DM_RETAIN drawing mode to store output in
graphic segments, the operating system assigns a new world space to each
segment. There is also a world space for the drawings outside of segments.


ΓòÉΓòÉΓòÉ 17.1.2. Model Space ΓòÉΓòÉΓòÉ

Model space is the conceptual area where the separate components of a picture,
defined in world space, are brought together. To assemble one or more
primitives from world spaces to model space the application specifies the
transformations to occur, then the PM programming interface applies them to
each of the components. Model transformations convert world coordinates to
model-space coordinates. For example, an octagon and the word STOP, defined
individually in separate world-coordinate spaces, can be assembled into a stop
sign in model space.

Graphics applications can have more than one model space. If there is more than
one model space, the picture components are assembled in page space. If an
application has each model space in a different segment, the model transforms
are reset for each segment.

An application can use a viewing limit clipping area to define the part of a
model space to place in the next coordinate space (the page space). A viewing
limit is always rectangular, and the coordinates that define its location and
dimensions are always model coordinates.


ΓòÉΓòÉΓòÉ 17.1.3. Page Space ΓòÉΓòÉΓòÉ

The page space is where a complete picture is assembled for viewing on a
display screen, or for printing or plotting on a piece of paper. Page
coordinate units can be increments of an inch, a meter, pels, or some arbitrary
value. An application uses GpiCreatePS to specify the units used for page
coordinates.

If the application uses retained-drawing mode, the picture in page space
contains parts of models (or pictures) from each of the model spaces that have
not been clipped. The picture also contains any additional unclipped
graphics-primitive output that the application generated in nonretained-drawing
mode. If the application uses nonretained-drawing mode, the picture in page
space contains all the graphics-primitive output that has not been clipped.

In the page space, an application can use a rectangular clipping area called a
graphics field to define the part of the page space to place in the next
coordinate space (the device space). The coordinates that define the location
and dimensions of the graphics field are always page coordinates.

The page space contains the presentation page whose size and units are defined
when creating the presentation space with GpiCreatePS. The presentation page is
a rectangle in page space.


ΓòÉΓòÉΓòÉ 17.1.4. Device Space ΓòÉΓòÉΓòÉ

The device space is the coordinate space in which a picture is drawn before it
appears in a display screen window or on the printer or plotter.

Device space is defined in device-specific units. Depending on the page unit
used, device-coordinate units can be pels, increments of an inch, increments of
a meter, or arbitrary. For example, if the page unit is pels, the
device-coordinate unit is pels; if the page units are arbitrary, the
device-coordinate units are arbitrary.


ΓòÉΓòÉΓòÉ 17.1.5. Media Space ΓòÉΓòÉΓòÉ

The media space is used only with windows. When an application draws a
primitive at a specified location in a window, it is not actually drawing in
the device space, as the device is the entire terminal screen.

Drawing in a window involves a shifting transformation which moves a drawing
from the given (unitless) position, to position in the specified window.


ΓòÉΓòÉΓòÉ 17.2. About Transformations ΓòÉΓòÉΓòÉ

The coordinate spaces are connected by different transformation functions. In
reality, the input coordinates of the world coordinate space are transformed
directly into device coordinates in a single operation. The intermediate
coordinate spaces exist only to provide a useful model to assist in the
understanding of how to define the different transformation matrixes.

Transformation of graphic primitives occur when a transformation matrix is
applied to those primitives. The individual transformations introduced here, do
not actually transform the primitives, but rather define portions of the
transformation matrix. After all portions of the matrix are identified, the
actual operation is performed in a single step.

The transformation functions manipulate graphics primitives as they move from
one coordinate space to the next. Transformation functions usually begin with
the letters Gpi. Most of the function names have a transformation type that
identifies the entities on which it operates. For example, a model
transformation is the transformation type that transforms graphics primitives
between a world coordinate space and a model space. There is a 1-to-1
correspondence between these transformation types and the actual functions. The
transformation matrix data structure is called MATRIXLF.

The following figure lists the sequence of coordinate spaces and the
transformation types between the coordinate spaces. Internally, all
transformations are combined, and the resulting values are held in the same
format as the individual components. By default, there is no viewing window and
no graphics field. The application can use the default page viewport. Clipping
regions for each coordinate space are also shown.

Viewing Pipeline


ΓòÉΓòÉΓòÉ 17.2.1. Identity Transformation ΓòÉΓòÉΓòÉ

The identity transformation is the default transformation between all
coordinate spaces. The identity transformation, makes no change to the original
coordinates of an object. This transformation is also referred to as the unity
transformation, because of the mathematical matrix used to make this
transformation.

The identity matrix looks like this:


     Γöî         ΓöÉ
     Γöé 1  0  0 Γöé
     Γöé 0  1  0 Γöé
     Γöé 0  0  1 Γöé
     Γöö         Γöÿ

(Transformations are accomplished with matrix multiplication; and 1, not 0, is
the multiplication identity.)

If a transformation is not explicitly specified, the identity transformation is
used to create that portion of the transformation matrix. Most transformations
applied to a primitive can be in addition to, or instead of, the current
transformation.


ΓòÉΓòÉΓòÉ 17.2.2. Moving through Coordinate Spaces Using the Identity Transformation ΓòÉΓòÉΓòÉ

The effects of transformation can be minimized by defaulting to the identity
transformation. This means that no deliberate action is requested by the
application.

Graphic primitives are drawn in their own coordinate scale in world coordinate
space. The primitives are then combined in model space. Neither the world
coordinate space or the model space have "real world" units associated with
them. This means that if an application draws a line on the x-axis from -300000
to +300000, the line exists as a line 600000 Cartesian units long in both world
coordinate and model space.

Page space is the first of the coordinate spaces to be associated with units
such as millimeters or inches. These units are set with the GpiCreatePS option
PS_UNITS. If the application specifies the option PS_UNITS with the value
PU_ARBITRARY, the page space remains unitless; units are applied when the
output is drawn in device space.

As an example, assume that the units PU_LOMETRIC, (0.1 mm) have been chosen.
Again, assuming the identity transformation between model and page space, the
primitive appears in the page space as a line that extends

300000 * 0.1mm to the right of the origin
300000 * 0.1mm to the left of the origin

A presentation page, a rectangle in page space, has its size defined when a
presentation space is created with GpiCreatePS. The presentation page format is
defined with the GpiCreatePS option, PS_FORMAT. The three choices for that
option are:

o GPIF_DEFAULT-32-bit integers or 2GB
o GPIF_LONG-32-bit integers
o GPIF_SHORT-16-bit integers or 32KB.

PS_FORMAT effects the number of units permitted along the coordinate axes of
the presentation page. If the choice was GPIF_LONG or GPIF_DEFAULT, and, for
example, PS_UNITS remains PU_LOMETRIC, the presentation page axes could range
from 0 to 134217727 0.1mm. If the choice was GPIF_SHORT, the coordinate axes
could range only from 0 to 32767 0.1mm. These limits are the maximum number of
units, presentation pages are usually much smaller.

The presentation page does not effect the primitive in presentation space, it
determines what parts of the primitive are visible. With no transformation to
scale down the primitive from the model to the page space, the presentation
page acts like a sheet of cardboard with a rectangular hole. Only the part of
the page space behind the "hole" is visible in page space. The view of
everything else is blocked by the "cardboard." Only what is visible in the page
space is drawn to the next coordinate space.

Continuing with the example of the 600000 units line above, if GPIF_LONG (or
GPIF_DEFAULT) is selected, the 600000 unit line could easily be viewed in the
presentation page. If GPIF_SHORT is selected, the maximum presentation page
size is 65534 * 0.1 mm units long. In the case, much of the 600000 unit line
would not be drawn into the next coordinate space.

The device space is not affected by the PS_FORMAT option. Whether GPIF_LONG, or
GPIF_SHORT, the device space is a rectangle with maximum coordinates of (32767,
32767) and minimum coordinates of (-32768, -32768). Note that not all of this
rectangle is visible, since real devices aren't that big. The device space
relates to the physical device.

The transformation between the page and device space is handled automatically
by the PM programming interface. The presentation page is mapped into a
rectangle in the device space called the page viewport. This transformation is
based on the parameters and options of the GpiCreatePS function.

Confusion can arise because the effects of the presentation page and the page
viewport appear to be a clipping of the primitives in page and device space.
While the action taken is identical, the term clipping is reserved for the
activity deliberately designated by the application with clipping functions.


ΓòÉΓòÉΓòÉ 17.2.3. Applying Transformations Other Than the Identity Transformation ΓòÉΓòÉΓòÉ

To better understand the workings of transformations other than the identity
transformation, an example of the picture assembly process is illustrated in
the following figure, and a detailed explanation follows.

Picture Assembly Process

In the world space of the following figure four segments are drawn, each
containing a different subpicture. The units of the subpictures can be
different (for example, the building might be measured in feet, while the
window might be measured in inches), because each subpicture is converted to
the scale of the completed picture when it is transformed into the completed
picture. All of the subpictures in the previous figure are defined at "real
world" scales in their own (Cartesian) world coordinate space.

The difference between applying and not applying transformations can be seen in
the model space in the previous figure. Without transformations, the
subpictures would be drawn at exactly the coordinates given in the world space
and thus all four subpictures would overlap. With transformations, the
subpictures can be scaled and translated to the scale of the final picture. The
window subpicture, Segment id=200 has been scaled, rotated, and translated.

The model space contains the model of what the application is trying to draw.
There can be more than one model space for very complex drawings, but this is
not a recommended style of programming.

The building also resides in the page space, and is prepared in the device
space for printing on an 8 and a half by 11 sheet of paper. This is shown in
the following figure. Most often the page space to device space transformation
(the device transformation) is the identity transformation.

Different Spaces

The transformation process in the previous figure is acting on segments. To
draw the composite picture in model space, create a segment chain that plays
all 4 segments associated with the building. The purpose of the world to model
space transformation is to transform the graphic segments into a composite
picture.

Having built the composite picture, the next step is to map the composite into
the page space. Usually, the model-to-page space transformation is the identity
transformation. The different coordinate spaces are shown in the previous
figure.

The user might want an exploded diagram as well as the composite picture. This
is illustrated in the following figure. To create the exploded diagram, the
application must draw the segment chain again, with a slight translation down,
and scaled up (enlarged) with a very large scaling factor.

Again, while it is possible to create several complex images in different model
spaces that must be assembled in the page space, the most frequent use of the
page space is to prepare a view of the model-from-model space with the first
application of "real world" units such as inches or millimeters. As shown in
the previous figures, both world and model space share unitless Cartesian
coordinates.

The usual purpose of the page space is to show multiple views of the image
residing in the model space, as shown in the following figure.

Different Spaces with an Exploded View

The enlarged image on the right side of the page space is drawn after the image
on the left. It therefore has a higher priority, and therefore would be drawn
on top of the left side image. To obtain a multi-viewed page space image, the
application defines a clipping region, and applies this region to the second
(enlarged image) playback of the segment chain. The clipping region permits the
enlarged image to appear only on the right side of the page space.

The same building also resides in this model space; but, it resides in the page
space, along with an exploded view of the uppermost right side window. The view
is enlarged to such a magnitude that the details of the window are once again
evident. If the images in world coordinate space are not able to be drawn in
the amount of detail now supported by the PM programming interface, then
drawing details, such as an exploded view, would reveal the barrenness of the
image.

Subpictures can be drawn in world coordinate space without being drawn inside a
graphics segment.


ΓòÉΓòÉΓòÉ 17.2.4. Combining Transformations Between a Coordinate Space Pair ΓòÉΓòÉΓòÉ

There are more than one transformation between the world coordinate and model
spaces, and between the model and page spaces. Depending on the desired output,
the transformations can be combined in different ways.

Between the world coordinate and model space, there are five ways of combining
the three transformations.

World Coordinate to Model Space Transformation Combinations

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Function       ΓöéEffect          ΓöéTransformationΓöé
Γöé                              Γöé                ΓöéType Sequence Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCallSegMatrix              ΓöéADD             ΓöéM   I   S     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                              ΓöéPREEMPT         ΓöéI   M   S     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé                              ΓöéREPLACE         Γöé    I   S     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiPlaySegment (Call Segment) ΓöéDrawing outside Γöé    M   S     Γöé
Γöé                              Γöéof an instance  Γöé              Γöé
Γöé                              Γöédrawing         Γöé              Γöé
Γöé                              Γöéprimitive but   Γöé              Γöé
Γöé                              Γöéinside a        Γöé              Γöé
Γöé                              Γöésegment.        Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNo specific function          ΓöéDrawing outside Γöé        M     Γöé
Γöé                              Γöéof segments     Γöé              Γöé
Γöé                              Γöéaltogether.     Γöé              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Abbreviations:  I - Instance Transformation, M - Model Transformation, S -
Segment Transformation

Between the model and page space pair are two transformations and they also can
be combined in different ways.

Model to Page Space Transformation Combinations

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Function       ΓöéEffect          ΓöéTransformationΓöé
Γöé                              Γöé                ΓöéType Sequence Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPageViewport            ΓöéDrawing inside  ΓöéV   D         Γöé
Γöé                              Γöéof and outside  Γöé              Γöé
Γöé                              Γöéof segments.    Γöé              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDefaultViewMatrix       ΓöéDrawing outside Γöé    D         Γöé
Γöé                              Γöéof segments.    Γöé              Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Abbreviations:  V - Viewing Transformation, D - Default Viewing Transformation


ΓòÉΓòÉΓòÉ 17.2.5. Transformation Mathematics ΓòÉΓòÉΓòÉ

The transformation of a picture can be represented in general terms by two
linear equations that define how the (x,y) coordinates of each point in the
picture are changed.

 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 Γöé  The general form of these equations is:  Γöé  where                                  Γöé
 Γöé                                           Γöé                                         Γöé
 Γöé  x' = Ax + Cy + E                         Γöé    (x,y) defines the original point     Γöé
 Γöé                                           Γöé    (x',y') is the transformed point     Γöé
 Γöé  y' = Bx + Dy + F                         Γöé    A, B, C, D, E, and F are constants.  Γöé
 Γöé                                           Γöé                                         Γöé
 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The transformations that result from these equations depend on the values of
the constants, which in turn vary according to the type of transformation being
applied.

The operating system handles transformations by using matrix mathematics. In
the matrix mathematics,

o Translation is an addition operation
o Scaling, reflecting, rotation, and shear are multiplication operations.

If all the transformations were multiplication operations, different types of
transformation could be applied with a single transformation operation.
Therefore, to facilitate the combining of calls, translation in the OS/2
operating system is performed as a multiplication operation, rather than an
addition operation.

This requires that the vector representing a point, [ x   y ]
be extended by a third component, w: [ x   y   w ]
This enables all the transformations to be handled in a uniform manner.

This is called a homogeneous coordinate system. The value, w, is a multiplier,
so that the point represented is: (wx, wy).

Note:  The PM programming interface does not support a 3-dimensional
       presentation space. The 3-dimensional matrix is created to effect matrix
       multiplication.

In this notation, the point (x, y) is represented as [ x   y   1 ]. To be able
to operate on such three-element vectors, and to combine translation with the
multiplication operations, the 2-by-2 matrix has to be extended to a 3-by-3
matrix, with the third column being:


       0
       0
       1

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé  The linear equations:         Γöé  become the matrix equations:           Γöé
  Γöé                                Γöé                            Γöî         ΓöÉ  Γöé
  Γöé  x' = Ax + Cy + E              Γöé                            Γöé A  B  0 Γöé  Γöé
  Γöé                                Γöé  [ x' y' 1 ] = [ x y 1 ] * Γöé C  D  0 Γöé  Γöé
  Γöé  y' = Bx + Dy + F              Γöé                            Γöé E  F  1 Γöé  Γöé
  Γöé                                Γöé                            Γöö         Γöÿ  Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

In standard matrix notation, you have:


                            Γöî                      ΓöÉ
                            Γöé Msub11 Msub12 Msub13 Γöé
  [ x' y' 1 ] = [ x y 1 ] * Γöé Msub21 Msub22 Msub23 Γöé
                            Γöé Msub31 Msub32 Msub33 Γöé
                            Γöö                      Γöÿ


ΓòÉΓòÉΓòÉ 17.2.6. Model for Building the Transformation Matrix ΓòÉΓòÉΓòÉ

The transformation matrix shown above can be set equal to an entity as complex
as:

M*I*S*V*D

where * symbolizes matrix multiplication. As mentioned earlier, all the
transformation types might not have a distinct value at all times. One, or all,
could simply be the identity transformation.

These intermediate space and step-wise transformations are not actually how the
operating system performs transformations. The reason for this relates to the
way the PM programming interface stores transformation information. The
transformation matrix data structure MATRIXLF, undergoes continuous
modification during the drawing process, and it can be influenced by more than
one transformation function from the application responding, for example, to
what a user wants the drawing to look like.

For example, after creating the model of a building from drawing primitives,
the user might want to see 2 identical buildings side-by-side. The application
has already applied a series of transformations to the 2 segments in world
coordinate space to create the model of the building. If the application,
rather than the PM programming interface, had to perform the entire
transformation over again from start to finish, it would have to keep track of
much more detail. The PM programming interface enables applications to process
a smaller portion of the MATRIXLF structure, in this example the "V" or "V and
D" component, to enable the user to see 2 buildings side-by-side.


ΓòÉΓòÉΓòÉ 17.2.7. MATRIXLF, the Transformation Matrix ΓòÉΓòÉΓòÉ

For all the transformation functions, the 3-by-3 transformation matrix is
specified as a one-dimensional array in the following order:

(M11, M12, 0, M21, M22, 0, M31, M32, 1)

This one-dimensional array corresponds to the data structure, MATRIXLF. The
elements in the data structure correspond to the matrix multiplication
constants, as shown in the following table.

Transformation Factors in the MATRIXLF Data Structure.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation Type           ΓöéMatrix Values                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéScaling, Reflection           ΓöéM11 and M22                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRotation                      ΓöéM11, M12, M21, M22            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTranslation                   ΓöéM31 and M32                   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

All nine elements do not have to be specified for every transformation
function. However, those specified are interpreted as the first n of the nine.
If the third, sixth, and ninth elements are specified, they must be 0, 0, and 1
respectively.


ΓòÉΓòÉΓòÉ 17.2.7.1. MATRIXLF Structure ΓòÉΓòÉΓòÉ

Of the nine fields in MATRIXLF, four are special 32-bit FIXED variables. The
remaining 5 are 32-bit long integer variables.

The scaling, reflecting, and rotation constants, M11,M12,M21, M22, are the
32-bit, signed, FIXED variables, with an implied binary point between the
second and third bytes. The translation constants, M31 and M32, and the 3
third-column variables, are 32-bit long integers.

A FIXED variable is a binary representation of a floating-point number. A FIXED
variable has 2 parts:

o The high-order 16-bits which contain a signed integer in the range -32768
  through 32767

o The low-order 16-bits which contain the numerator of a fraction in the range
  0 through 65535. The denominator for this fraction is 65536.

For example, to store the cosine of 60┬░ (0.5) in a FIXED variable, an
application would multiply 65536 by 0.5. The result, 32768, would be the value
to assign to a field in the MATRIXLF structure.

To store a scaling factor of 3 in a FIXED variable, the application would
multiply 65536 by 3. Again, the result, 196608, would be the value to assign to
a field in the MATRIXLF structure.


ΓòÉΓòÉΓòÉ 17.2.7.2. MAKEFIXED Macro ΓòÉΓòÉΓòÉ

The MAKEFIXED macro provides a quick and convenient method for setting the
value of FIXED variables. This macro requires 2 arguments:  the first is the
integer part of the FIXED value, and the second is the fraction part of the
FIXED value. In the following example, MAKEFIXED is used to assign the FIXED
value equivalent of 1 1/8 to the matrix component M11.

    matlf.fxM11 = MAKEFIXED(1, 8192)


Determining a FIXED Equivalent

The first argument, 1, is the integer part of the FIXED value. The second
argument, 8192, is the result of multiplying 65536 by 1/8.

If it is necessary for an application to scale or rotate an object, the
application can avoid most of these mathematics by using the helper functions,
GpiRotate and GpiScale. GpiRotate accepts a rotation in degrees and converts
this value into the appropriate fields in the MATRIXLF structure. Similarly,
GpiScale accepts a scaling factor and fills in the MATRIXLF structure with the
appropriate values.


ΓòÉΓòÉΓòÉ 17.3. About Transformation Operations ΓòÉΓòÉΓòÉ

The available transformations are listed in the following table.

Transformations

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéOperation       ΓöéResult                                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéScaling         ΓöéShrinks or enlarges the object              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéReflection      ΓöéCreates a mirror image of an object with    Γöé
Γöé                Γöérespect to the x- or y- axis                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRotation        ΓöéRotates the object                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTranslation     ΓöéShifts the object with respect to the originΓöé
Γöé                Γöéof the coordinate system                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéShear           ΓöéRotates either all the vertical or all the  Γöé
Γöé                Γöéhorizontal lines in an object               Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

These basic operations can be combined.

The PM programming interface provides special functions to perform scaling,
rotation, and translation and also enables applications to specify the
transformation matrix directly. Applications can specify values for more than
one type of transformation on a single transformation call.

Transformations are used to manipulate graphic objects as they are being moved
from 1 coordinate space to another. These operations are performed by functions
called transformation functions. There are also functions that help perform the
transformations called helper functions.

The scaling, reflection, rotation, translation, and shear transformations are
best demonstrated by applying them to a picture. The following figure shows the
image of a flag before any transformations have been applied. The flag is
defined by 5 points. Their (x,y) coordinates are (0,0), (0,4), (0,6), (2,6),
and (2,4).

Flag Before Transformation

In the next several sections, where the transformations are described in
detail, the effect of the transformation on the flag is illustrated.


ΓòÉΓòÉΓòÉ 17.3.1. Scaling and Reflection Transformations ΓòÉΓòÉΓòÉ

Applications can scale an object by using GpiScale or by modifying the MATRIXLF
structure directly. A scaling transformation reduces or increases the size of a
graphics object. A reflecting transformation creates a mirror image of an
object with respect to the x- or y-axis.

A scaling factor of:

o greater than 1 causes an increase in size

o greater than 0 but less than 1 causes a reduction in size,

o less than 0 causes a reflection about that axis. That is, a negative x
  scaling factor causes reflection in the x direction.

Note:  If an application specifies a scaling factor of greater than 1, the
       graphics presentation space must be defined with the coordinate format
       GPIF_LONG. This is because 32-bit matrix elements are required to store
       these values in retained segment and metafile orders.

The equations to scale by factors Sx and Sy are obtained from the general
equations (with M11 = Sx and M22 = Sy) and can be written:

x' = xSx

y' = ySy

A scaling transformation reduces or increases all the coordinates of an object
by the scaling factor. Any object not aligned on the x- and y-axes is therefore
moved nearer to the origin by a reduction in size, and away from the origin by
an increase in size. For example, if an application applies a scaling factor of
0.5 to a simple box with its corners at (4,4), (10,4), (10,10), and (4,10), the
four corners moves to (2,2), (5,2), (5,5), and (2,5).

To scale an object about a point without causing it to move, the following
sequence of transformations is required:

 1. Translate the scaling point of the object to the origin.

 2. Scale the object at the origin.

 3. Translate the scaling point of the object back to its original position.


ΓòÉΓòÉΓòÉ 17.3.1.1. Scaling a Graphics Object ΓòÉΓòÉΓòÉ

An application can scale the flag by 0.5, by applying:

x' = 0.5x

y' = 0.5y

The original 5 points of the flag are transformed:

(0,0) ΓöÇ (0,0)
(0,4) ΓöÇ (0,2)
(0,6) ΓöÇ (0,3)
(2,4) ΓöÇ (1,2)
(2,6) ΓöÇ (1,3)
The following figure shows the effect of the scaling.

Scaling by 0.5

This scaling preserves the shape and orientation of the object, because the
scaling factors in both directions are the same. However, scaling equations
permit different scaling factors to be applied to x and y, which can cause
distortion of the original shape of the object.


ΓòÉΓòÉΓòÉ 17.3.1.2. Reflecting a Graphics Object ΓòÉΓòÉΓòÉ

A negative scaling factor causes a reflection of the object to be drawn. A
scaling factor of -1, for example, causes a mirror image of the object to be
drawn in the appropriate direction.

The following figure shows the flag reflected by applying a negative y scaling
factor.

Reflection


ΓòÉΓòÉΓòÉ 17.3.1.3. MATRIXLF Structure for Scaling and Reflecting ΓòÉΓòÉΓòÉ

When an application scales an object by using the scaling transformation, the
matrix element M11 contains the horizontal scaling component (Sx), and the
matrix element M22 contains the vertical scaling component (Sy).


                          Γöî         ΓöÉ
                          Γöé Sx 0  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé 0  Sy 0 Γöé
                          Γöé 0  0  1 Γöé
                          Γöö         Γöÿ

If the matrix element M11 contains a negative horizontal reflection component
(-Sx), it causes reflection about the y-axis. If the matrix element M22
contains a negative vertical reflection component (-Sy) it causes reflection
about the x-axis.


ΓòÉΓòÉΓòÉ 17.3.2. Rotation Transformations ΓòÉΓòÉΓòÉ

The application can rotate an object either using GpiRotate or by modifying the
MATRIXLF structure directly.

The operating system applies a transformation to all points in the source
coordinate space. This means that unless an object is drawn about the origin of
the source coordinate space, translation occurs when the object is rotated or
scaled. GpiRotate enables an application to specify a point, relative to the
origin, that is, the center of rotation.

The equations for the rotation of an object about the origin (0,0) through an
angle (theta), can be written:

x' = x cos (theta) - y sin (theta)

y' = x sin (theta) + y cos (theta)

A negative (theta) value rotates the object clockwise. For clockwise rotation,
the rotation equations are:

x' = x cos (theta) + y sin (theta)

y' = -x sin (theta) + y cos (theta)

To rotate an object about some other point (p,q), the following sequence of
transformations is required:

 1. Translate the object by (-p,-q) to move the point of rotation to the
    origin.

 2. Rotate the object around the origin.

 3. Translate the object by (p,q) to move it back to its original position.

Rotation preserves the shape and size of the object.


ΓòÉΓòÉΓòÉ 17.3.2.1. Rotating a Graphics Object ΓòÉΓòÉΓòÉ

An application can rotate the flag counterclockwise through 90┬░, by applying:

x' = x cos 90 - y sin 90

y' = x sin 90 + y cos 90

Because cos 90 = 0 and sin 90 = 1, these equations become:

x' = - y

y' = x

The original 5 points are transformed:

(0,0) ΓöÇ (0,0)
(0,4) ΓöÇ (-4,0)
(0,6) ΓöÇ (-6,0)
(2,4) ΓöÇ (-4,2)
(2,6) ΓöÇ (-6,2)

The following figure shows the effect of rotating the flag 90┬░.

Rotation Counterclockwise through 90┬░


ΓòÉΓòÉΓòÉ 17.3.2.2. MATRIXLF Structure for Rotating ΓòÉΓòÉΓòÉ

For counterclockwise rotation:


                          Γöî                              ΓöÉ
                          Γöé  cos (theta)  sin (theta)  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé -sin (theta)  cos (theta)  0 Γöé
                          Γöé   0            0           1 Γöé
                          Γöö                              Γöÿ

For clockwise rotation:


                          Γöî                              ΓöÉ
                          Γöé  cos (theta) -sin (theta)  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé  sin (theta)  cos (theta)  0 Γöé
                          Γöé   0            0           1 Γöé
                          Γöö                              Γöÿ


ΓòÉΓòÉΓòÉ 17.3.3. Translation Transformations ΓòÉΓòÉΓòÉ

The application can translate an object either using GpiTranslate or by
modifying the MATRIXLF structure directly.

To move a graphics object by an absolute number of coordinate units, a
translation equation is applied. The equations for translation by Tx and Ty are
obtained from the general equations (with E = Tx, and F = Ty) and can be
written:

x' = x + Tx

y' = y + Ty

Translation preserves the shape, size, and orientation of the object. A
negative Tx value causes movement to the left. A negative Ty value causes
movement downward.


ΓòÉΓòÉΓòÉ 17.3.3.1. Translating a Graphics Object ΓòÉΓòÉΓòÉ

If Tx is equal to 8 and Ty is equal to 5, then:

x' = x + 8

y' = y + 5

The original 5 points are transformed:

(0,0) ΓöÇ (8,5)
(0,4) ΓöÇ (8,9)
(0,6) ΓöÇ (8,11)
(2,4) ΓöÇ (10,9)
(2,6) ΓöÇ (10,11)

The following figure shows the effect of translating the flag by (8,5).

Translation by (8,5)


ΓòÉΓòÉΓòÉ 17.3.3.2. MATRIXLF Structure for Translating ΓòÉΓòÉΓòÉ

When an application translates an object by using the translation
transformation, the matrix element M31 contains the horizontal translation
component, and the matrix element M32 contains the vertical translation
component, as follows:


                          Γöî         ΓöÉ
                          Γöé 1  0  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé 0  1  0 Γöé
                          Γöé Tx Ty 1 Γöé
                          Γöö         Γöÿ


ΓòÉΓòÉΓòÉ 17.3.4. Shearing Transformations ΓòÉΓòÉΓòÉ

There are 2 shear transformations:  vertical and horizontal. The vertical shear
transformation affects only the y-component of the coordinates of points in an
object; the horizontal shear transformation affects only the x-component.

If an application shears an object that contains 2 orthogonal vectors (2
perpendicular lines), the vectors are no longer orthogonal.

A shearing transformation alters the shape of an object by translating its
x-coordinates relative to its y-coordinates, or its y-coordinates relative to
its x-coordinates. The amount by which the coordinates are translated is
determined by the angle of the shear.

The equation for shearing an object to the left along the x axis by angle
(theta) is:

x' = x - y tan (theta)

y' = y

To shear an object along the y-axis, the tangent of the angle of the shear is
represented by constant B in the general equation.


ΓòÉΓòÉΓòÉ 17.3.4.1. Shearing a Graphics Object ΓòÉΓòÉΓòÉ

The following figure shows the flag sheared to the left along the x-axis.

Shearing Along the X-Axis


ΓòÉΓòÉΓòÉ 17.3.4.2. MATRIXLF Structure for Shearing ΓòÉΓòÉΓòÉ

For vertical shear transformation, the matrix element M11 contains the
horizontal shear component, and the element M21 contains the vertical shear
component, as follows:


                          Γöî                    ΓöÉ
                          Γöé   1           0  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé -tan (theta)  1  0 Γöé
                          Γöé   0           0  1 Γöé
                          Γöö                    Γöÿ

For horizontal shear transformation, the matrix element M21 contains the
horizontal shear component, and the matrix element M22 contains the vertical
shear component, as follows:


                          Γöî                    ΓöÉ
                          Γöé +tan (theta)  0  0 Γöé
[ x' y' 1 ] = [ x y 1 ] * Γöé   1           1  0 Γöé
                          Γöé   0           0  1 Γöé
                          Γöö                    Γöÿ


ΓòÉΓòÉΓòÉ 17.4. About Transformation Functions ΓòÉΓòÉΓòÉ

Transformation functions manipulate objects between coordinate spaces by
applying transformations. Transformation functions require 2 coordinate spaces:
a source coordinate space, and a target coordinate space. Which transformation
function an application should use is determined by the 2 coordinate spaces and
by the transformation effect desired.

The world-to-model space, model-to-page space, and page-to-device space
transformations are all actually performed as a single operation. The different
coordinate spaces are conceptual in nature, rather than explicitly defined
entities. Describing them separately is meant to help explain the levels of
activity during transformations.

All transformation functions share certain parameters, although the values and
defaults of those parameters might not be identical.


ΓòÉΓòÉΓòÉ 17.4.1. Current Transformation ΓòÉΓòÉΓòÉ

Every graphics object, whether in world, model, page, or device space, has a
current transformation value, even if that value is simply the identity
transformation.

The default current model transformation is the concatenation of any instance,
segment, and model transformations from the root segment downward. The default
current viewing transformation is the 1 most recently specified. The device
transformation, which is set by the page viewport and the presentation page,
should not be changed while drawing is in progress.


ΓòÉΓòÉΓòÉ 17.4.2. Accumulating Transformations ΓòÉΓòÉΓòÉ

Each time one of the transformation functions is called by an application, the
application can set the function's option parameter to control how the function
combines the transformation with existing transformations and in what order the
transformations are applied.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf the application uses this flag...ΓöéThen the operating      Γöé
Γöé                                    Γöésystem...               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_REPLACE                   ΓöéReplaces any existing   Γöé
Γöé                                    Γöétransformations with theΓöé
Γöé                                    Γöénew transformation. The Γöé
Γöé                                    Γöéexisting value of the   Γöé
Γöé                                    Γöématrix is discarded and Γöé
Γöé                                    Γöéreplaced by straight    Γöé
Γöé                                    Γöésubstitution.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_PREEMPT                   ΓöéApplies the new         Γöé
Γöé                                    Γöétransformation before   Γöé
Γöé                                    Γöéapplying the existing   Γöé
Γöé                                    Γöétransformation.         Γöé
Γöé                                    ΓöéThe transformation      Γöé
Γöé                                    Γöématrix of the new       Γöé
Γöé                                    Γöétransformation is       Γöé
Γöé                                    Γöépre-multiplied with the Γöé
Γöé                                    Γöétransformation matrix ofΓöé
Γöé                                    Γöéthe current             Γöé
Γöé                                    Γöétransformation.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTRANSFORM_ADD                       ΓöéApplies the new         Γöé
Γöé                                    Γöétransformation after    Γöé
Γöé                                    Γöéapplying the existing   Γöé
Γöé                                    Γöétransformation.         Γöé
Γöé                                    ΓöéThe transformation      Γöé
Γöé                                    Γöématrix of the new       Γöé
Γöé                                    Γöétransformation is       Γöé
Γöé                                    Γöépost-multiplied with theΓöé
Γöé                                    Γöétransformation matrix ofΓöé
Γöé                                    Γöéthe current             Γöé
Γöé                                    Γöétransformation.         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The order in which transformations are applied affects the appearance of the
picture. For example, suppose that a box primitive has been defined, with its
lower-left corner at (4,2) and its upper-right corner at (8,8), and that you
want both to scale the box by 0.5 and to translate it by (-10,-10).

If the box is translated before scaling it, the transformed box is as shown in
the following figure.

If the box is scaled before translating it, the transformed box is as shown in
the figure after the following figure.

When an application is drawing a picture in which there are called segments,
and in which transformations are applied to the root segments, the root-segment
transformations should usually be applied to any segments they call. For
example, if a segment that is translated to the left of the picture (by
changing its segment transformation) calls a second segment, that leftward
transformation should also be applied to the called segment. In this instance,
the application would specify TRANSFORM_ADD in the call to GpiCallSegmentMatrix
to add the instance transformation to the calling segments' segment
transformation. Instance transformations are automatically reset on return to
the calling segment.

Translating before Scaling

The translated box has its lower-left corner at (-6,-8), and its upper-right
corner at (-2,-2). Each of its coordinates is then scaled by 0.5, and the
transformed box has its corners at (-3,-1), (-1,-1), (-3,-4), and (-1,-4).

Scaling before Translating

The scaled box has its lower-left corner at (2,1), and its upper-right corner
at (4,4). The box is then translated by (-10,-10), and the transformed box has
its corners at (-8,-6), (-6,-6), (-6,-9), and (-8,-9).


ΓòÉΓòÉΓòÉ 17.4.3. Concatenating Transformations ΓòÉΓòÉΓòÉ

When an application applies more than one transformation, it can concatenate
the individual transformations to produce a final result. To concatenate
transformations, multiply the individual transformation matrixes. The product
of this multiplication is the concatenated transformation.

There are four ways the final matrix can be concatenated:

 1. Hard code the matrix values into the application, then call the
    transformation functions.

 2. Multiply the individual matrixes, then call the transformation functions.

 3. Use the helper functions with the TRANSFORM_ADD option, then call the
    transformation functions.

 4. Alternately apply transformation operations directly to the transformation
    matrix, then apply a transformation function.

Concatenating before calling provides better performance.


ΓòÉΓòÉΓòÉ 17.4.3.1. Hard Coding Values for a Concatenated Matrix ΓòÉΓòÉΓòÉ

Pre-calculating the concatenated matrix values, then hard coding the values
into the application, gives the fastest performance. However, this is rarely
practical as the actual transformations to be performed are often variable.

If an application is, for example, performing interactive graphics, and one of
the options offered to the user is a menu choice of rotate by 90┬░, and enlarge
by 4, then the rotational and scaling factors would not change, and the matrix
values could be hard coded into the application.


ΓòÉΓòÉΓòÉ 17.4.3.2. Multiplying Matrix Values ΓòÉΓòÉΓòÉ

Multiplying transformation matrix values directly offers the second fastest
performance, yet can still respond to a variety of desired transformations. As
many transformation matrixes as needed can be multiplied together. If the
application is concatenating the matrixes itself, it is responsible for
preventing the accumulated transformation side effects.

For example, to rotate an object counterclockwise about the point (p,q) using a
single transformation call requires 3 transformations to be concatenated. When
the application is specifying each transformation, step-by-step, the sequence
of actions would be:

 1. Translate the object by (-p,-q) to move the point of rotation to the
    origin.

 2. Rotate the object about the origin.

 3. Translate the object by (p,q) to move it back to its original position.

The individual matrixes are:


Γöî           ΓöÉ Γöî                              ΓöÉ Γöî         ΓöÉ
Γöé  1   0  0 Γöé Γöé  cos (theta)  sin (theta)  0 Γöé Γöé 1  0  0 Γöé
Γöé  0   1  0 Γöé Γöé -sin (theta)  cos (theta)  0 Γöé Γöé 0  1  0 Γöé
Γöé -Tx -Ty 1 Γöé Γöé   0            0           1 Γöé Γöé Tx Ty 1 Γöé
Γöö           Γöÿ Γöö                              Γöÿ Γöö         Γöÿ

The matrix for the concatenated transformation is produced incrementally. That
is, 2 adjacent matrixes are multiplied to produce a single matrix, which is
then multiplied with the third matrix. You can begin by multiplying either the
first 2 matrixes or the second 2 matrixes. If you start by multiplying matrixes
2 and 3 together, the resulting matrix is:


          Γöî                              ΓöÉ
          Γöé  cos (theta)  sin (theta)  0 Γöé
          Γöé -sin (theta)  cos (theta)  0 Γöé
          Γöé   Tx           Ty          1 Γöé
          Γöö                              Γöÿ

This matrix is multiplied with the first matrix to produce the matrix for
rotating an object at the point (p,q):


          Γöî                              ΓöÉ
          Γöé  cos (theta)  sin (theta)  0 Γöé
          Γöé -sin (theta)  cos (theta)  0 Γöé
          Γöé   a            b           1 Γöé
          Γöö                              Γöÿ

where:

a = (-Txcos (theta) + Ty sin (theta) + Tx)

and

b = (-Txsin (theta) - Ty cos (theta) + Ty)

If an application were performing the concatenation for a scaling operation,
again it would have to specify the transformation step-by-step. The sequence of
actions would be:

 1. Translate the object's scaling point to the origin.

 2. Scale the object at the origin.

 3. Translate the object back to its original position.

Here are the 3 matrixes required to obtain this effect:


Γöî           ΓöÉ Γöî            ΓöÉ Γöî         ΓöÉ
Γöé  1   0  0 Γöé Γöé  Sx  0   0 Γöé Γöé 1  0  0 Γöé
Γöé  0   1  0 Γöé Γöé  0   Sy  0 Γöé Γöé 0  1  0 Γöé
Γöé -Tx -Ty 1 Γöé Γöé  0   0   1 Γöé Γöé Tx Ty 1 Γöé
Γöö           Γöÿ Γöö            Γöÿ Γöö         Γöÿ

The matrix of the concatenated transformation is:


   Γöî                           ΓöÉ
   Γöé     Sx          0       0 Γöé
   Γöé     1           Sy      0 Γöé
   Γöé (-TxSx+Tx)  (-TySy+Ty)  1 Γöé
   Γöö                           Γöÿ


ΓòÉΓòÉΓòÉ 17.4.3.3. Transformation Helper Functions ΓòÉΓòÉΓòÉ

Three helper functions, are provided to perform the matrix math required to
concatenate transformations:

o GpiTranslate
o GpiRotate
o GpiScale.

Any of these three functions can be used with the TRANSFORM_ADD option to
concatenate the new matrix with an existing matrix. This method builds up the
matrix in application storage in a sequence of steps before issuing a single
transform function.

While this is slower than hard coding the matrix, it is faster than alternating
between applying transformation operations directly to the matrix then applying
a transformation function.

The helper functions merely calculate the appropriate matrix. The
transformation is not applied until the array containing the matrix values is
passed to the appropriate transformation function.

Applications use GpiTranslate to change the position of an object. The
application specifies the coordinates of the point to which to move the object
and the name of the transform matrix to use as input to GpiTranslate. The
transformation matrix must be in the form of a one-dimensional array. The
application also can specify whether this transformation is to replace the
value for a previous transformation, or whether it is to be added to it.

Applications use GpiRotate to rotate an object. The application specifies the
angle of rotation, the coordinates of the point around which the object is to
rotate, and the transformation matrix. The transformation matrix must be in the
form of a 1 dimensional array. The application also can specify whether this
transformation is to replace the value for a previous transformation, or
whether it is to be added to it.

To scale an object at a point without also moving the object, applications use
GpiScale. When using GpiScale, the application specifies the scaling factor,
the coordinates of the center point, and the transformation matrix. The
transformation matrix must be in the form of a one-dimensional array. The
application also can specify whether this transformation is to replace the
value for a previous transformation, or whether it is to be added to it.


ΓòÉΓòÉΓòÉ 17.4.3.4. Applying Transformation Operations Directly to the Transformation Matrix and Using Transformation Functions ΓòÉΓòÉΓòÉ

An application could alternate between applying transformation operations
directly to the transformation matrix, then applying a transformation function
with the TRANSFORM_ADD option set. This would build up the matrix in the
presentation space. This method has the slowest performance of the four
concatenation methods.


ΓòÉΓòÉΓòÉ 17.4.4. Round-Off Error ΓòÉΓòÉΓòÉ

Whenever an application uses transformations, it should handle any round-off
error that occurs after multiple scaling, rotation, shear, or reflection
transformations. The rounding error increases because a transformation is
incrementally updated by the amount of the error with, for example, the
TRANSFORM_ADD option. For the rotation to remain accurate, the application
should recalculate the transformation, rather that accumulate many small
changes.

For example, if an application uses a rotation transformation to rotate the
hands of a clock, the accuracy of the clock diminishes due to rounding off
after the transformation. The rounding error should be periodically removed by
using the TRANSFORM_REPLACE option at known points, for example, every 90┬░ or
every complete revolution of the clock.


ΓòÉΓòÉΓòÉ 17.4.5. World Space-to-Model Space Transformations ΓòÉΓòÉΓòÉ

The model transformation drawing attribute operates between world and model
space. This attribute can be updated by one of the three following
transformation functions:

o GpiSetModelTransformMatrix
o GpiSetSegmentTransformationsMatrix
o GpiCallSegmentMatrix.

If the model transformation drawing attribute has never been updated, the
attribute defaults to the identity transformation. If the drawing attribute has
been updated, the existing transformation is the concatenation of any instance,
segment, or model transformations from the root segment downwards. Each time a
new segment is opened (using GpiOpenSegment), the model transformation drawing
attribute is reset to its default value.

The three transformations that operate between world space and model space are:

o Model transformations
o Segment transformations
o Instance transformations.

The transformations that occur between world-coordinate and model spaces depend
on the drawing mode and the possible segment type of the drawing primitive.

The drawing mode can be either nonretain or retain. Nonretain mode is also
called draw mode, as the graphics are immediately displayed. In retain mode,
the graphics orders are stored in chained and unchained segments. A series of
segments are shown in the following figure.

Segments

A model transformation effects objects in any of these segments. A segment
transformation effects the 6 chained segments, on the left and must be issued
before Root Segment 1 is accessed. An instance transformation can be applied
only to Segment B, or Segment D; and must be issued from Segment A or Segment
2, or Segment C. The instance transformation is reset on return to the calling
segment.


ΓòÉΓòÉΓòÉ 17.4.5.1. Model Transformations ΓòÉΓòÉΓòÉ

Model transformations also can be applied to objects both inside and outside of
segments. Model transformations also can be applied to objects created under
retained or nonretained drawing mode. This means model transformations affect
the output from:

o GpiDrawChain
o GpiDrawFrom
o GpiDrawSegment
o Any GPI functions that occur outside of a retained-drawing segment.

Applications can change the model transformation any number of times in a
single segment. Changing the model transformation changes the transformation
applied to any drawing primitives issued subsequently.

An application can determine the values for the current model transformation by
calling GpiQueryModelTransformMatrix, which returns the model transformation's
scaling, rotation, and translation values in a one-dimensional array
representing elements in the MATRIXLF structure.

GpiSetModelTransformMatrix specifies the model transformation's scaling,
rotation, and translation values applied to subsequent primitives in the
segment. As this function does not require the name a segment, it also can be
used to apply transformations to primitives outside of segments.

For example, in the building example earlier in the chapter, if the window is
stored in a retained segment, an application could draw several identical
windows on the house by setting a new translation component in the model
transformation before calling GpiBox.


ΓòÉΓòÉΓòÉ 17.4.5.2. Segment Transformations ΓòÉΓòÉΓòÉ

The segment transformation provides a way of defining the model transformation
drawing attribute at the start of a retained segment. The attribute can
subsequently be updated by the model transform orders within the segment. A
segment transformation can be applied only to a retained segment.

Segment transformations alter retained-drawing output. Unlike a model
transformation, which can be set and reset within a segment bracket, a segment
transformation must be set outside of a segment bracket.

An application can determine the values for the current segment transformation
by calling GpiQuerySegmentTransformMatrix, which returns the model
transformation's scaling, rotation, and translation values in a one-dimensional
array representing elements in the MATRIXLF structure.

To apply a segment transformation, applications use
GpiSetSegmentTransformMatrix. GpiSetSegmentTransformMatrix can be used to apply
any sort of transformation to a segment. For example, it can be used to
translate a dynamic segment from one screen position to another, when movement
is requested by the user. The application could perform the following steps,
for example, on receipt of a WM_MOUSEMOVE message:

 1. Use the new mouse position to calculate the required displacement from the
    current position.
 2. Call GpiRemoveDynamics to remove the dynamic segment from its current
    position.
 3. Call GpiSetSegmentTransformMatrix to translate the segment coordinates by
    the required amount.
 4. Call GpiDrawDynamics to redraw the segment in its new position.


ΓòÉΓòÉΓòÉ 17.4.5.3. Instance Transformations ΓòÉΓòÉΓòÉ

Instance transformations provide a way of defining the model transformation
drawing attribute for the duration of a called segment.

Instance transformations alter the retained-drawing output from special
segments referred to as called segments. A called segment usually contains a
subpicture duplicated several times in other subpictures. The instance
transformation positions, sizes, and rotates the subpicture each time the
segment is duplicated, because the transformation is set each time the segment
is called. An instance transformation applies only to the called segment, and
is reset on return to the calling segment. There is no query function
associated with the transformation as it must be explicitly set for each called
segment.

To apply an instance transformation, applications call GpiCallSegmentMatrix
from the calling segment. GpiCallSegmentMatrix calls the segment and also
applies the model transformation's scaling, rotation, and translation values in
a one-dimensional array representing elements in the MATRIXLF structure and
passes a segment identifier.


ΓòÉΓòÉΓòÉ 17.4.5.4. World Space-to-Model Space Transformation Summary ΓòÉΓòÉΓòÉ

The following table summarizes the choices available during world-coordinate
space to model space transformations.

World to Model Space Transformation Summary

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTransformation ΓöéTransformation Function           ΓöéApplies    Γöé
ΓöéType           Γöé                                  Γöéto...      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéModel          ΓöéGpiSetModelTransformMatrix        ΓöéPrimitives Γöé
ΓöétransformationsΓöé                                  Γöéboth insideΓöé
Γöé               Γöé                                  Γöéand outsideΓöé
Γöé               Γöé                                  Γöéa segment. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSegment        ΓöéGpiSetSegmentTransformationsMatrixΓöéA retained Γöé
ΓöétransformationsΓöé                                  Γöésegment,   Γöé
Γöé               Γöé                                  Γöéissued at  Γöé
Γöé               Γöé                                  Γöéthe first  Γöé
Γöé               Γöé                                  Γöéelement of Γöé
Γöé               Γöé                                  Γöéthe        Γöé
Γöé               Γöé                                  Γöésegment.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInstance       ΓöéGpiCallSegmentMatrix              ΓöéOnly the   Γöé
ΓöétransformationsΓöé                                  Γöécalled     Γöé
Γöé               Γöé                                  Γöésegment.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  The effect of GpiSetModelTransformMatrix and GpiCallSegmentMatrix on the
model transformation drawing attribute can be duplicated by an equivalent
drawing order in a drawn retained segment.


ΓòÉΓòÉΓòÉ 17.4.6. Model Space-to-Page Space Transformations ΓòÉΓòÉΓòÉ

There are two transformations that operate between the model space and the page
space:

o Viewing transformations
o Default viewing transformations

All three model transformation types and the viewing transformations can be
considered a part of the picture. The default viewing transformation is part of
the environment, and must not be used for picture construction.

Viewing transformations only apply in retained or nonretained segments. The
viewing transformation attribute is set to the presentation space viewing
transformation matrix value at the start of each drawn root segment and remains
constant for that segment. If GpiSetViewingTransformMatrix is called, the new
value is not used until the next segment is opened. The matrix drawing
attribute is reset to identity at the end of the segment. Each change in a
viewing transformation is equivalent to defining a new model space.

The default viewing transformation is a presentation space attribute, and
should not normally be modified in the middle of a picture. This attribute can
be updated by the transformation function GpiSetDefaultViewMatrix.

A picture is normally constructed in the presentation page with an identity
default viewing transformation. The default viewing transformation can then be
used to scale and scroll the entire picture in the presentation page.


ΓòÉΓòÉΓòÉ 17.4.6.1. Viewing Transformations ΓòÉΓòÉΓòÉ

More than one copy of an entire model space can be drawn in page coordinate
space, and each copy can be transformed as required. Parts of the model space
also can be transformed to the presentation page. For example, an enlarged view
of the tail of an aircraft can be shown with a reduced view of the complete
aircraft in 1 corner. This is shown in the following figure. In this example,
the picture assembled in the presentation page is derived from a single model
space.

Presentation-Page Space

The entire model space (the aircraft) and a part of the model space (the tail
of the aircraft) are drawn to a single page coordinate space. In each instance,
scaling and translation transformations have been applied.

Alternatively, the displayed picture can be made up of several subpictures with
no common graphical elements. For example, the aircraft can be drawn in one
part of the display, and a map of an airport in another part of the display. In
this instance, the final picture would be derived from different model spaces.

Whether multiple views are derived from a single model space or from different
model spaces, there are two items to address for each instance of a model space
incorporated into the presentation page:

 1. The part of the model space to be displayed must be identified by defining
    a viewing window for the model space.

 2. To position and size the contents of the model space in page coordinate
    space, a viewing transformation must be specified.

To get views of one or more model spaces on the screen simultaneously, each
model space is drawn the required number of times. Before each drawing request,
the viewing window is defined and a viewing transformation is specified.


ΓòÉΓòÉΓòÉ 17.4.6.2. Defining the Viewing Window ΓòÉΓòÉΓòÉ

The viewing window is a conceptual boundary around a part of the model space.
To produce the picture in the previous figure, the aircraft is drawn twice. The
first time, the viewing window is on only the tail of the aircraft, and the
second time, the viewing window is on the entire aircraft. Only those parts of
the model space within the viewing window are visible in the picture assembled
in presentation-page space. GpiSetViewingLimits is used to define the viewing
window.


ΓòÉΓòÉΓòÉ 17.4.6.3. Graphics Field ΓòÉΓòÉΓòÉ

Applications also can specify a type of viewing window for the presentation
page smaller than the page. This window is known as the graphics field. To
define a graphics field use GpiSetGraphicsField. By default, no graphics field
is specified. If a graphics field is defined, the picture assembled within it
is the picture that is visible on the output device.

An application can determine the current values for the viewing transformation
by calling GpiQueryViewingTransformMatrix, which returns the transformation
values in a one-dimensional array representing elements in the MATRIXLF
structure. The application can set the values by calling
GpiSetViewingTransformMatrix, and passing the transformation values in a
one-dimensional array representing elements in the MATRIXLF structure.


ΓòÉΓòÉΓòÉ 17.4.6.4. Default Viewing Transformations ΓòÉΓòÉΓòÉ

The default viewing window is the same size as the model space. Therefore, to
display 1 or more entire model spaces, draw the picture the required number of
times and let the viewing window default each time.

Default viewing transformations scroll or zoom pictures in a window on a
display screen. An application can determine the current values for the default
viewing transformation by calling GpiQueryDefaultViewMatrix, which returns the
default-viewing-transformation values in a one-dimensional array representing
elements in the MATRIXLF structure. The application can set these values by
calling GpiSetDefaultViewMatrix and passing the transformation values in a
one-dimensional array representing elements in the MATRIXLF structure.

A default viewing transformation is applied when the screen contents are zoomed
or scrolled by user interaction. A picture is zoomed when the user wants to
increase or decrease the size of an area of interest. A picture is usually
scrolled when there is more in the presentation page than can be displayed in a
single page of output. Anything lying off the screen, but within the range of
the presentation page, can be scrolled into view. The default viewing
transformation applies to the entire page coordinate space, and can be added
to, or can replace, the current default viewing transformation. The PM
programming interface applies it after any viewing transformations.

When a presentation page is created, the default viewing transformation is set
to identity. For example, if the presentation-page contents are scrolled:

o Erase the screen contents.

o Call GpiSetDefaultViewMatrix to translate the presentation-page picture by
  the required amount.

o Draw the picture again.

The following figure shows the airplane presentation-page contents scrolled to
the left.

Scrolling the Presentation Page

Every presentation-page coordinate is translated to the left by the same
amount.

Zooming is implemented in the same way, except that the default viewing
transformation is used to scale the picture up or down as required.

If you want to display only one view of a single picture, and if you do not
want scrolling and zooming capabilities, you can let the viewing and default
viewing transformations default. When both transformations are permitted to
default, page coordinate space is effectively the same as model space.


ΓòÉΓòÉΓòÉ 17.4.7. Page Space-to-Device Space Transformations ΓòÉΓòÉΓòÉ

There is only one transformation between the page coordinate space and the
device space, the device transformation. The device transformation enables
applications to work in any presentation-page units regardless of the target
device. Unlike the transformations previously described, the device
transformation:

o Only scales and translates objects
o Is defined by 2 rectangles.

The first rectangle is called the presentation page. Its location is the bottom
left origin and its dimensions are fixed. The second is called the page
viewport. Its location is the bottom left origin and its dimensions can be
varied.

The device transformation, which maps the picture in presentation-page space to
device space, happens automatically. The device transformation is established
when the presentation space is created, and ensures that graphics are displayed
in the correct size and, where possible, that their aspect ratio is preserved.
The rules by which the device transformation is implemented are described in
Mapping the Presentation Page to the Device.

To modify the device transformation, applications use GpiSetPageViewport. Input
for this function is the device coordinates of the lower-left and upper-right
corners of the page viewport. Applications should modify the default device
transformation only when it is necessary to use nonstandard page units.


ΓòÉΓòÉΓòÉ 17.4.7.1. Presentation Pages ΓòÉΓòÉΓòÉ

A presentation page is a rectangle in a page space. Its lower-left corner is
always positioned at the origin of the page space.

An application can determine the dimensions of the presentation page by calling
GpiQueryPS. It returns a pointer to a SIZEL structure that contains the page
dimensions. If an application specifies arbitrary page units when creating a
presentation space with GpiCreatePS, the page viewport is constructed such that
the origin of the page rectangle maps to the origin of the default device
rectangle and either the right or top edge maps to the corresponding edge.
Thus, the aspect ratio of the graphic is preserved.

If either the height or width of the presentation page is set to 0 (using
GpiCreatePS), the application must set GPIA_ASSOC to set the default
presentation page size to the default device rectangle size.


ΓòÉΓòÉΓòÉ 17.4.7.2. Page Viewports ΓòÉΓòÉΓòÉ

A page viewport is a rectangle in device space, whose origin and size can be
varied. The operating system uses the presentation-page rectangle and the
page-viewport rectangle to define the device transformation.

An application can determine the current dimensions of the page viewport by
calling GpiQueryPageViewport, which returns a pointer to a RECTL structure that
contains the coordinates of the viewport. The application can set the location
and dimensions of the page viewport by calling GpiSetPageViewport and passing
it a pointer to a RECTL structure that contains the new values.

The ratio of the page width to the page-viewport width defines a horizontal
scaling factor. The ratio of the page height to the viewport height defines a
vertical scaling factor. Applications can use DevQueryCaps to obtain the
horizontal and vertical resolution of a device in pels per meter. The
dimensions of a pel can vary from one device to another, but they usually fall
in the range of 0.25 to 0.50 mm.

The page viewport can be shifted in the device space by a translation
transformation.


ΓòÉΓòÉΓòÉ 17.4.7.3. Mapping the Presentation Page to the Device ΓòÉΓòÉΓòÉ

When an application associates a presentation space with a device context, a
default device transformation is set. A page viewport is defined according to
the rules in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéPresentation-page ΓöéPage viewport size  ΓöéUsage.                Γöé
Γöéspecification     Γöé                    Γöé                      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPels              ΓöéThe same size as theΓöéThe lower-left corner Γöé
Γöé                  Γöépresentation page.  Γöéof the presentation   Γöé
Γöé                  Γöé                    Γöépage maps to the      Γöé
Γöé                  Γöé                    Γöélower-left corner of  Γöé
Γöé                  Γöé                    Γöéthe device space. For Γöé
Γöé                  Γöé                    Γöéexample, if an        Γöé
Γöé                  Γöé                    Γöéapplication defines a Γöé
Γöé                  Γöé                    Γöépresentation page of  Γöé
Γöé                  Γöé                    Γöé300 coordinates       Γöé
Γöé                  Γöé                    Γöé(x-axis)-by-200       Γöé
Γöé                  Γöé                    Γöécoordinates (y-axis), Γöé
Γöé                  Γöé                    Γöéthen the picture is   Γöé
Γöé                  Γöé                    Γöétransformed to a      Γöé
Γöé                  Γöé                    Γöéscreen area of the    Γöé
Γöé                  Γöé                    Γöésame size.            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMetric units      ΓöéThe coordinates thatΓöéThe lower-left corner Γöé
Γöé                  Γöéproduce the correct Γöéof the presentation   Γöé
Γöé                  Γöématrix for the      Γöépage maps to the      Γöé
Γöé                  Γöéphysical spacing of Γöélower-left corner of  Γöé
Γöé                  Γöéthe pels.           Γöéthe device space.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéArbitrary units   ΓöéThe default size forΓöéThe page viewport is  Γöé
Γöé                  Γöéthe device is used. Γöéconstructed such that Γöé
Γöé                  ΓöéFor a plotter or    Γöéthe presentation-page Γöé
Γöé                  Γöéprinter, this is theΓöécoordinates give equalΓöé
Γöé                  Γöémaximum accessible  Γöéx- and y-spacing. The Γöé
Γöé                  Γöéarea of the paper,  Γöélower-left corner of  Γöé
Γöé                  Γöéand for a screen, itΓöéthe presentation page Γöé
Γöé                  Γöéis the maximized    Γöémaps to the lower-leftΓöé
Γöé                  Γöéwindow size.        Γöécorner of the device  Γöé
Γöé                  Γöé                    Γöéspace, and either the Γöé
Γöé                  Γöé                    Γöéright or the top edgesΓöé
Γöé                  Γöé                    Γöémap, such that the    Γöé
Γöé                  Γöé                    Γöépicture is contained  Γöé
Γöé                  Γöé                    Γöéwithin the device     Γöé
Γöé                  Γöé                    Γöérectangle and its     Γöé
Γöé                  Γöé                    Γöéaspect ratio is       Γöé
Γöé                  Γöé                    Γöépreserved.            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The following figure shows mapping from the presentation page to the device.

The device transformation can be explicitly specified using GpiSetPageViewport.

Mapping a Picture from the Presentation Page to the Device

In this example, a map of the world has been drawn in a presentation page,
defined in arbitrary units, that is much larger than the device space. The
device transformation scales the picture to fit the maximized window size and
preserves its aspect ratio.


ΓòÉΓòÉΓòÉ 17.4.7.4. Coding the Device Transformation ΓòÉΓòÉΓòÉ

The PM programming interface automatically transforms the presentation-page
contents to the area of the device space within the page viewport. The drawing
is not clipped to the page viewport because this is a scaling transformation
only. The entire picture is displayed, regardless of the size of the page
viewport specified. The following figure shows the airplane presentation-page
contents scaled to fit the page viewport.

Device Space

A page viewport smaller than the presentation page has been defined. The
picture assembled in the presentation page is therefore scaled to fit the page
viewport.

After transformation to device space, graphics coordinates must be in the range
-32768 through +32767, even if the presentation page is defined in GPIF_LONG
format. An attempt to address a coordinate outside this range results in a
coordinate-overflow error. To determine if a graphics object will give an
error, applications can do the following:

o If the application is not rotating or shearing a graphics object, it calls
  GpiConvert to convert the device-space limits to world-coordinate-space
  limits, then uses these limits when creating the graphics object.

o If the application is rotating or shearing a graphics object, it uses
  GpiConvert to convert the device-space limits back to model space, and
  ensures that the picture boundary is inside these limits. Note that this
  method only applies if all rotational and shearing is performed using 1 of
  the model transformation types.

Remember that world-coordinate space has its own limits:

o -32768 through +32767 for a GPIF_SHORT-format presentation page

o -134217728 through [phone] for a GPIF_LONG-format presentation page.

Although applications can specify a page viewport of any size, the presentation
page can be mapped only to an area equal to, or less than, the available device
space. If an application specifies a viewport larger than the available device
space, part of the presentation page contents are displayed outside the visible
device output area. To find out the dimensions of the page viewport for the
currently associated device, use GpiQueryPageViewport. Applications can store
the dimensions of the current page viewport before changing them, and restore
them later.


ΓòÉΓòÉΓòÉ 17.4.7.5. Device-Transformation Matrix ΓòÉΓòÉΓòÉ

To directly manipulate the device-transformation matrix it is necessary for
applications to know the following values:

X1   the x-coordinate of the lower-left corner of the page viewport

Y1   the y-coordinate of the lower-left corner of the page viewport

X2   the x-coordinate of the upper-right corner of the page viewport

Y2   the y-coordinate of the upper-right corner of the page viewport

XPS  the presentation-space width -1

YPS  the presentation-space height -1.

The device-transformation matrix is defined as:

  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé  The device-transformation matrix: Γöé  where:                      Γöé
  Γöé  Γöî                 ΓöÉ               Γöé                              Γöé
  Γöé  Γöé Msub11  0     0 Γöé               Γöé a = (Xsub2-Xsub1)/(Xps+1)    Γöé
  Γöé  Γöé  0     Msub22 0 Γöé               Γöé                              Γöé
  Γöé  Γöé Msub31 Msub32 1 Γöé               Γöé b = (Ysub2-Ysub1)/(Yps+1)    Γöé
  Γöé  Γöö                 Γöÿ               Γöé                              Γöé
  Γöé                                    Γöé c = Xsub1+(a-1)/2            Γöé
  Γöé                                    Γöé                              Γöé
  Γöé                                    Γöé d = Ysub1+(b-1)/2            Γöé
  Γöé                                    Γöé                              Γöé
  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 17.4.8. Windowing-System Transformation ΓòÉΓòÉΓòÉ

There is 1 transformation, the windowing-system transformation, performed
automatically by the PM programming interface. The windowing-system
transformation, which is a translation transformation only, maps the
coordinates of the picture in device space to the coordinates of the screen
window or printer page. This happens when a picture is first drawn, and
whenever the display window in which the picture has been drawn is moved.


ΓòÉΓòÉΓòÉ 17.4.9. Transforming Bit-Map Data ΓòÉΓòÉΓòÉ

In general, graphics defined in device coordinates (bit maps and image
primitives) cannot be transformed. For example, the size of an image primitive
is specified in device coordinates, and cannot be altered. The size, therefore,
remains unaltered down the viewing pipeline. The position of an image
primitive, however, is specified in world coordinates. The image is therefore
subject to translation transformations. Note, however, that GpiWCBitBlt permits
the target rectangle to be specified in world coordinates, which are
transformed.

Because the position of the image primitive is specified in world coordinates
and its width is specified in device coordinates, positioning 2 images together
on the screen causes special difficulties. The second image cannot be
positioned without knowing the width, in world coordinates, of the first image.
To get the width of the first image:

 1. Identify 2 coordinate positions, 1 on the image's left edge, and 1 on its
    right edge. For example, the 2 positions could be (10,80) and (150,80).
    These positions are in device coordinates.

 2. Convert these device coordinates to world coordinates using GpiConvert.
    GpiConvert converts an array of (x,y) coordinates that apply in 1
    coordinate space to their corresponding values in another coordinate space.

 3. Subtract the lower x-coordinate from the higher x-coordinate. In the above
    example, the width of the image is the difference between the
    world-coordinate equivalents of 150 and 10.

When you have the width of the first image in world coordinates, you can
calculate the start position of the second image.

Paths, although defined in world coordinates, are device-dependent and are
bound in device coordinates when they are defined. Subsequent transformations
(other than the windowing-system transformation) have no effect on paths.
However, if a path is used to create a wide line, the width of the line is
scaled as required.


ΓòÉΓòÉΓòÉ 17.5. Using Coordinate Spaces and Transformations ΓòÉΓòÉΓòÉ

This section explains how to:

o Set an application's drawing units to convenient units
o Translate, rotate, and scale a picture
o Shear a picture.


ΓòÉΓòÉΓòÉ 17.5.1. Setting Drawing Units ΓòÉΓòÉΓòÉ

Applications can use GpiCreatePS to set the device transformation so that it
uses page units that might be more convenient than pels; for example,
centimeters. If the output device is a screen, the application first opens a
device context by calling WinOpenWindowDC. If the output device is a printer or
plotter, the application opens a printer or plotter device context by calling
DevOpenDC. The application then creates a presentation space by calling
GpiCreatePS, specifying low-metric page units and associating the device
context with the presentation space. The following figure is an example of how
to set drawing units.


    HWND hwnd;                    /* Client-window handle         */
    HAB hab;                      /* Anchor-block handle          */
    HPS hps;                      /* Presentation-space handle    */
    HDC hdc;                      /* Device-context handle        */
    SIZEL sizlPage;               /* Presentation-page rectangle  */

    hdc = WinOpenWindowDC(hwnd);
    sizlPage.cx = 0;
    sizlPage.cy = 0;
    hps = GpiCreatePS(hab,        /* Anchor-block handle          */
          hdc,                    /* Device-context handle        */
          &sizlPage,              /* Address of SIZEL structure   */
          PU_LOMETRIC             /* Centimeters as page units    */
          | GPIA_ASSOC);          /* Associates window DC with PS */


Setting Drawing Units


ΓòÉΓòÉΓòÉ 17.5.2. Translating, Rotating, and Scaling a Picture ΓòÉΓòÉΓòÉ

GpiTranslate, GpiRotate, and GpiScale provide a convenient method for
transforming objects in a picture. The following figure shows how to use these
functions to translate, rotate, and scale a triangle.

    MATRIXLF matlfTransform;
    POINTL ptlStart, ptlTrans, ptlRotate, ptlScale;
    FIXED fxAngle, afxScale[2];
    POINTL aptlTriangle[] = { 575, 300, 575, 500, 500, 300 };

    ptlStart.x = 500;                      /* Starting point x direction   */
    ptlStart.y = 300;                      /* Starting point y direction   */
    GpiMove(hps, &ptlStart);
    GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);

    ptlTrans.x = 75;                       /* x coordinate for translation */
    ptlTrans.y = 75;                       /* y coordinate for translation */

    GpiTranslate(hps,                      /* Presentation-space handle    */
        &matlfTransform,                   /* Address of matrix            */
        TRANSFORM_REPLACE,                 /* Replace old matrix with new  */
        &ptlTrans);                        /* Coordinates for translation  */

    GpiSetModelTransformMatrix(hps,        /* Presentation-space handle    */
        9,                                 /* Number of points in matrix   */
        &matlfTransform,                   /* Address of matrix            */
        TRANSFORM_REPLACE);                /* Replace old matrix with new  */

    GpiMove(hps, &ptlStart);               /* Move to starting point       */
    GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);

    fxAngle = MAKEFIXED(-45, 0);           /* Rotate 45 degrees clockwise  */
    ptlRotate.x = 550;                     /* x coordinate rotation origin */
    ptlRotate.y = 350;                     /* y coordinate rotation origin */

    GpiRotate(hps,                         /* Presentation-space handle    */
        &matlfTransform,                   /* Address of matrix            */
        TRANSFORM_REPLACE,                 /* Replace old matrix with new  */
        fxAngle,                           /* Rotation angle               */
        &ptlRotate);                       /* Origin of rotation           */

    GpiSetModelTransformMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);

    GpiMove(hps, &ptlStart);               /* Move to starting point       */
    GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);

    ptlScale.x = 550;                      /* x coordinate scale origin    */
    ptlScale.y = 350;                      /* y coordinate scale origin    */
    afxScale[0] = MAKEFIXED(2, 0);         /* Scaling factor on x axis     */
    afxScale[1] = MAKEFIXED(2, 0);         /* Scaling factor on y axis     */

    GpiScale(hps,                          /* Presentation-space handle    */
        &matlfTransform,                   /* Address of matrix            */
        TRANSFORM_REPLACE,                 /* Replace old matrix with new  */
        &afxScale[0],                      /* Scaling factor               */
        &ptlScale);                        /* Origin of scaling operation  */

    GpiSetModelTransformMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);

    GpiMove(hps, &ptlStart);               /* Move to starting point       */
    GpiPolyLine(hps, sizeof(aptlTriangle) / sizeof(POINTL), aptlTriangle);

Translating, Rotating, and Scaling a Triangle


ΓòÉΓòÉΓòÉ 17.5.3. Shearing a Picture ΓòÉΓòÉΓòÉ

The following figure is an example of shearing a picture by modifying the
transformation matrix directly.


   MATRIXLF matlfTransform;
   POINTL ptlStart, ptlEnd;

   ptlStart.x = 500;          /* x coordinate, lower-left corner of box   */
   ptlStart.y = 300;          /* y coordinate, lower-left corner of box   */
   GpiMove(hps, &ptlStart);
   ptlEnd.x = 700;      ;     /* x coordinate, upper-right corner of box  */
   ptlEnd.y = 500;      ;     /* y coordinate, upper-right corner of box  */
   GpiBox(hps, DRO_OUTLINE, &ptlEnd, 0, 0);  /* Draw first box            */

    matlfTransform.fxM11 = MAKEFIXED(1, 0);
    matlfTransform.fxM12 = MAKEFIXED(0, 0);
    matlfTransform.lM13 = 0;
    matlfTransform.fxM21 = MAKEFIXED(0, 65536 / 2);  /* Shear factor .5   */
    matlfTransform.fxM22 = MAKEFIXED(1, 0);
    matlfTransform.lM23 = 0;
    matlfTransform.lM31 = 200;               /* Translate 200 units right */
    matlfTransform.lM32 = 0;
    matlfTransform.lM33 = 1;
    GpiSetDefaultViewMatrix(hps, 9, &matlfTransform, TRANSFORM_REPLACE);

    GpiMove(hps, &ptlStart);
    GpiBox(hps, DRO_OUTLINE, &ptlEnd, 0, 0); /* Draw sheared box          */


Shearing a Picture


ΓòÉΓòÉΓòÉ 17.5.4. Using World to Model Space Transformations ΓòÉΓòÉΓòÉ

The following is an example of a sequence of calls in which segment, model, and
instance transformations are applied to graphics objects.

GpiSetDrawingMode (DM_RETAIN)   /* Sets the current drawing mode        */
                                /* to DM_RETAIN                         */

GpiOpenSegment (segment 1)      /* Creates a chained segment            */

GpiCloseSegment
GpiSetSegmentAttrs              /* Make segment 1 an unchained segment  */

GpiOpenSegment (segment 2)      /* Creates a retained, chained segment  */

GpiSetModelTransformMatrix (TRANSFORM_ADD)
                                /* Specifies a transformation to        */
                                /* apply to subsequent primitives.      */
                                /* This is in addition to the current   */
                                /* model transformation.                */

GpiCallSegmentMatrix (1, TRANSFORM_ADD)
                                /* Calls segment 1 and applies a        */
                                /* transformation to it.                */
                                /* This transformation is in addition   */
                                /* to the current model transformation, */
                                /* and applies only to the called       */
                                /* segment.                             */
   .
   .
GpiSetCurrentArcParams
GpiPointArc                     /* The 3-point arc is not subject       */
                                /* to the transformation specified      */
                                /* on the call to GpiCallSegmentMatrix. */
                                /* The transformation that was          */
                                /* current before segment 1 was called  */
                                /* is applied to the remainder of       */
                                /* segment 2.                           */

GpiCloseSegment
GpiSetSegmentTransformMatrix (segment 2)
                                /* Specifies a segment transformation   */
                                /* for segment 2                        */

GpiDrawSegment                  /* Draws segment 2                      */


Using World-to-Model Transformations


ΓòÉΓòÉΓòÉ 17.5.5. Viewing Transformation ΓòÉΓòÉΓòÉ

Each time an application draws the model space, it specifies a different
viewing transformation to transfer a view of the picture-to-page coordinate
space. GpiSetViewingTransformMatrix is used to apply a viewing transformation.
There is one viewing transformation for each part or whole model space to be
incorporated in page-coordinate space.

GpiSetViewingTransformMatrix cannot be called while there is an open segment,
and it has no effect on primitives outside segments. When it has been
specified, the viewing transformation applies to all subsequently created
segments until it is next changed. The viewing transformation that is current
when a segment is created is a fixed part of the segment. Once specified, the
viewing transformation cannot be queried, nor can it be altered, unless you
re-create the segment. This is inconvenient when several versions of the same
picture are being drawn. The problem can be solved by:

o Defining the picture in one or more unchained segments.

o Creating a segment chain and calling the unchained segments from each root
  segment.

o Setting the viewing transformation before each root segment.

Each time the segment chain is drawn, multiple views of the same picture are
produced. This sequence is illustrated in the following example, where the
segment chain comprises 3 root segments, each of which calls a single unchained
segment.

GpiSetInitialSegmentAttrs      /* Switches off the chained attribute   */

GpiOpenSegment                 /* Creates an unchained segment         */
                               /* containing the picture definition    */

GpiCloseSegment
GpiSetInitialSegmentAttrs      /* Switches on the chained attribute    */

GpiSetViewingTransformMatrix   /* Sets the viewing transformation      */
                               /* for segment 1                        */

GpiOpenSegment (segment 1)
GpiCallSegmentMatrix           /* Calls the unchained segment          */

GpiCloseSegment
GpiSetViewingTransformMatrix   /* Sets the viewing transformation      */
                               /* for segment 2                        */

GpiOpenSegment (segment 2)
GpiSetViewingLimits            /* Specifies the area of interest       */
                               /* in the model space.                  */

GpiCallSegmentMatrix           /* Calls the unchained segment          */

GpiCloseSegment
GpiSetViewingTransformMatrix   /* Sets the viewing transformation      */
                               /* for segment 3                        */

GpiOpenSegment (segment 3)
GpiCallSegmentMatrix           /* Calls the unchained segment          */
GpiCloseSegment


Using Viewing Transformations

When a segment chain has been created using this method, an application cannot
change the viewing transformation unless it re-creates the segment chain. The
viewing transformation of a segment is permanently recorded and cannot be
edited. The application would not, however, have to re-create the picture
definition in the unchained segment.

If the picture definition comprises a number of unchained segments, an
application must create an intermediate segment to contain the
GpiCallSegmentMatrix calls for those segments. Each root segment would then
call the intermediate segment.

The viewing transformation applies to the entire root segment and cannot be
overridden from within the segment. It is particularly useful for positioning
and scaling 1 or more segments of a subpicture within the presentation page
when a segment transformation cannot be used. A segment transformation can be
overridden by any model or instance transformations within the segment. A
typical example of its use is when importing a subpicture using GpiPutData or
GpiPlayMetaFile.

Note:  The viewing transformation must be set to its default value before an
       application defines an unchained segment to be called from another
       segment.


ΓòÉΓòÉΓòÉ 17.6. Summary ΓòÉΓòÉΓòÉ

The following table summarizes the functions used with coordinate spaces and
transformations.

Coordinate-Space and Transformation Functions

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFunction Name                   ΓöéDescription                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCallSegmentMatrix            ΓöéApplies an instance         Γöé
Γöé                                Γöétransformation.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiConvert                      ΓöéTransforms an array of      Γöé
Γöé                                Γöépoints from one coordinate  Γöé
Γöé                                Γöéspace to another.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiConvertWithMatrix            ΓöéTransforms an array of      Γöé
Γöé                                Γöépoints using a specified setΓöé
Γöé                                Γöéof transformation matrix    Γöé
Γöé                                Γöévalues.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiCreatePS                     ΓöéDefines presentation page   Γöé
Γöé                                Γöésize and initial page       Γöé
Γöé                                Γöéviewport.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryDefaultViewMatrix       ΓöéDetermines the current      Γöé
Γöé                                Γöévalues for the default      Γöé
Γöé                                Γöéviewing transformation.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryModelTransformMatrix    ΓöéDetermines the values for   Γöé
Γöé                                Γöéthe current model           Γöé
Γöé                                Γöétransformation.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryPageViewport            ΓöéDetermines the coordinates  Γöé
Γöé                                Γöéof the current page         Γöé
Γöé                                Γöéviewport.                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQuerySegmentTransformMatrix  ΓöéDetermines the values for   Γöé
Γöé                                Γöéthe current segment         Γöé
Γöé                                Γöétransformation.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiQueryViewingTransformMatrix  ΓöéDetermines the current      Γöé
Γöé                                Γöévalues for the viewing      Γöé
Γöé                                Γöétransformation.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiRotate                       ΓöéGenerates a transformation  Γöé
Γöé                                Γöématrix to perform rotation  Γöé
Γöé                                Γöéby a given number of        Γöé
Γöé                                Γöédegrees.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiScale                        ΓöéGenerates a transformation  Γöé
Γöé                                Γöématrix to scale by a given  Γöé
Γöé                                Γöéscaling factor.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetDefaultViewMatrix         ΓöéDefines the default viewing Γöé
Γöé                                Γöétransformation values.      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetModelTransformMatrix      ΓöéDefines the model           Γöé
Γöé                                Γöétransformation attribute    Γöé
Γöé                                Γöévalues, the values to be    Γöé
Γöé                                Γöéstored in a retained        Γöé
Γöé                                Γöésegment, or both.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetPageViewport              ΓöéSets page viewport size and Γöé
Γöé                                Γöéorigin.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetSegmentTransformMatrix    ΓöéDefines the segment         Γöé
Γöé                                Γöétransformation values to be Γöé
Γöé                                Γöéstored in a specified       Γöé
Γöé                                Γöéretained segment.           Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetViewingLimits             ΓöéDefines the viewing window. Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiSetViewingTransformMatrix    ΓöéDefines the values of the   Γöé
Γöé                                Γöéviewing transformation      Γöé
Γöé                                Γöématrix.                     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéGpiTranslate                    ΓöéGenerates a transformation  Γöé
Γöé                                Γöématrix to translate by a    Γöé
Γöé                                Γöégiven horizontal value,     Γöé
Γöé                                Γöévertical value, or both.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The following table summarizes the data structures used to manipluate
coordinate spaces and transformations.

Coordinate-Space and Transformation Structure

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéStructure Name          ΓöéDescription                         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMATRIXLF                ΓöéThe values of the transformation    Γöé
Γöé                        Γöématrix.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéRECTL                   ΓöéThe values of the page viewport.    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSIZEL                   ΓöéThe presentation page dimensions.   Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 18. Print Job Submission and Manipulation ΓòÉΓòÉΓòÉ

The print subsystem of the OS/2 operating system provides a flexible,
high-level interface between your application and an output device.  Because
most of the internal workings of the subsystem are shielded from both user and
programmer, this chapter concentrates on the programming process required to
produce hardcopy output.  Querying of printer resources, working under a
specific user's environment, designing for application-specific requirements,
and manipulation of print jobs also are described.


ΓòÉΓòÉΓòÉ 18.1. About the Print Subsystem Components ΓòÉΓòÉΓòÉ

The print subsystem comprises the following software components of the
operating system:

o Spooler
o Print subsystem user interface
o Queue drivers (queue processors)
o Printer drivers
o File system
o Kernel device drivers.


ΓòÉΓòÉΓòÉ 18.1.1. Spooler ΓòÉΓòÉΓòÉ

The spooler is the central coordinating process for the print subsystem.  It
gives the user flexibility in organizing and optimizing the use of the system's
printers. The spooler has a global view of the system's printing resources,
particularly in a server environment; and, therefore, is able to make the best
use of those resources, as follows:

o Print output from two separately executing applications cannot be intermixed
  on the printer.  As an optional optimization, the spooler can start a
  printing job before it is completely queued.  Any successive jobs are queued
  normally.

o The spooler can print a job in the background while the user continues to use
  the application.  Other single-tasking operating systems, such as DOS,
  require the user to wait until the print output is sent completely to the
  printer.

o The spooler can send jobs from PM applications, across a network, to a remote
  server, without the application's knowledge.

  Note:  The file system handles print jobs from non-PM applications.

o Queues within the spooler can be used for various purposes.  For example, one
  queue can be used for large print jobs that are printed at times when print
  demand is low.  Or a queue can be configured to print jobs using a special
  size paper; print jobs on this queue would be held until the correct paper is
  loaded into the printer.

o The spooler can support a number of printers simultaneously.  It can be
  configured so that jobs on a single queue can be shared among all the
  printers.  This load balancing, which is particularly important in server
  environments, can be achieved without the application's knowledge.

o Jobs can be prioritized while in the queue. For example, an urgent job can be
  given a higher priority than ordinary jobs.

The spooler consists of one or more print queues; one for each printer object
defined by the user.  Jobs are created by applications and placed in a queue,
waiting to print.  When the previous job is completed, the next job in the
queue is sent to the printer.


ΓòÉΓòÉΓòÉ 18.1.1.1. Print Job Formats ΓòÉΓòÉΓòÉ

The print jobs held in a spooler queue are known as spool files.  Spool files
contain the following:

o Parameters submitted with the print job
o Print job data.

Print job data is in one of two formats:

PM_Q_STD       Standard output data, PM_Q_STD, is spooled as a PM metafile;
               that is, as a series of graphics orders stored in a packed
               binary format.  PM_Q_STD print jobs are created through the GPI.

               An advantage of the PM_Q_STD format is that the files are
               smaller than PM_Q_RAW format files.  The smaller size saves disk
               space for jobs in the spooler queue and reduces network traffic
               when transmitting the data to a network server.

               The content of PM_Q_STD jobs can be viewed using the PICVIEW
               application.  This is achieved using the job-content menu on a
               print job in the printer object.  The multi-page spool file can
               be shown in a device-independent manner so that the content of
               the job can be recognized easily.

               After a job is spooled and ready to print, the spooler sends the
               PM_Q_STD job to the queue driver. The queue driver replays the
               metafile, through the GPI, to the appropriate printer driver.
               The driver, in turn, converts the data to printer-specific
               commands, that is, a printer-specific format.

               There are some restrictions on the content of PM_Q_STD jobs that
               are related to the restrictions for PM metafiles.  For details,
               refer to the Presentation Manager Programming Reference, Volume
               III, Appendix G.  PM applications that cannot deal with these
               restrictions should enqueue print jobs using PM_Q_RAW, but there
               is an increase in required disk space and, possibly, network
               traffic.

               Print jobs sent to network servers that do not support PM are
               converted automatically to the PM_Q_RAW format by the system.
               The application still can continue specifying PM_Q_STD.

               Note:  The effect of converting all PM_Q_STD print jobs to
                      PM_Q_RAW can be turned on by the user's selecting
                      Printer-specific format in a printer object settings
                      page.

PM_Q_RAW       Raw data, PM_Q_RAW, is the actual printer command to print the
               job.  For example, raw data created for an HP** LaserJet**
               printer contains Printer Command Language (PCL) commands; and
               raw data created for a PostScript** printer contains PostScript
               commands.

               The content of PM_Q_RAW jobs can be viewed with the system
               editor.  This is achieved using the job content menu on a print
               job in the printer object.  However, it is not always easy to
               recognize the content of a job.  For example PostScript is very
               hard to understand and get a visual idea of the actual output.

               Print jobs are created by the file system as a result of
               printing directly to the physical port using either INT 17 or
               INT 21 under DOS or the OS/2 DosOpen API.  These print jobs
               always are queued using PM_Q_RAW.  The actual queue chosen
               depends on the port used and the configuration of the print
               subsystem.  See Submitting a Non-Presentation Manager (Base)
               Print Job for more information.

               PM applications also can use the PM_Q_RAW format, but the
               overall print-job creation process normally is slower because
               the printer driver has to perform more work to create the
               printer-specific format.

               If the Print while spooling printer object setting is turned on,
               the user can perceive a faster response.  In particular for a
               multi-page document, the first page starts printing as soon as
               the printer driver has