.\" @(#)intro.3 3.13 94/06/07 SMI;
.so man3/xgl.macs
.TH intro 3 "August 1994" "XGL Graphics Library" "XGL Graphics Library"
.SH NAME
intro \- introduces the \s-1XGL\s0 graphics library
.SH DESCRIPTION
.\" indexing
.IX Introduction
.LP
These Reference Manual pages describe the syntax for using
the operators (functions) and attributes in the 
\s-1XGL\s0 Graphics Library.
Special sections immediately following this introduction describe
the \s-1XGL\s0 enumerated types, \s-1XGL\s0 macro values,
\s-1XGL\s0 point list structures, and \s-1XGL\s0 data structures.
The next two sections describe, in alphabetical order, the
\s-1XGL\s0 attributes and operators. 
.LP
The \s-1XGL\s0 programming paradigm is built around 
\fIobjects\fP, which are instances of abstract data types.
The application can create an object and apply operators to it.
The application cannot, however, extend the definition of an object
or modify the behavior of operators.
Therefore, \s-1XGL\s0 is not an object-oriented programming system,
although its design does incorporate some object-oriented concepts.
.LP
The \s-1XGL\s0 operators are standard C language
library calls and are documented as such.
Note that some operators can take a variable
number of parameters.
For example, the operator xgl_object_set is described this way:
.LP
.nr F1 \w'<attribute-list>     'u
.nr F2 \w'attributes );     'u
.ta .25i +\n(F1u +\n(F2u
.B "#include\ <xgl/xgl.h>"
.LP
.nf
.IP \fBvoid\fP 5
.B xgl_object_set (
.B	Xgl_object	obj,
.B	<attribute-list>	attributes );
.fi
.LP
The first parameter is of the type \fBXgl_object\fP,
which is a handle to the \s-1XGL\s0 object data.
The next argument, whose type is shown as \fB<attribute-list>\fP,
is a \fIvariable length\fP list of attribute-value pairs.
A zero (\s-2ASCII NULL\s0 character) is used to mark
the end of the list.
.LP
Each \s-1XGL\s0 object has a set of attributes associated with it.
An attribute is a named field inside the object.
The application can set an attribute's value,
or it can retrieve its value, or both. 
The documentation for the \s-1XGL\s0 attributes specifies
the C data type needed for setting the attribute and the C
data type needed for getting (retrieving) its value.
The following example describes how to set and
get the attribute 
.BR \s-2XGL_\%CTX_\%LINE_\%WIDTH_\%SCALE_\%FACTOR (3)\s0 ,
which controls the width of lines in the Context object.
.LP
.nf
.B "#include\ <xgl/xgl.h>"
.LP
.B "Xgl_ctx             ctx;"
.LP
.Bs "xgl_object_set(ctx, " XGL_CTX_LINE_WIDTH_SCALE_FACTOR ", float, 0);"
.Bs "xgl_object_get(ctx, " XGL_CTX_LINE_WIDTH_SCALE_FACTOR ", float *);"
.fi
.LP
This notation indicates that to set the attribute value,
the application passes a \fIfloat\fP, and to get the value,
the application passes a \fIpointer\fP to a \fIfloat\fP,
which is overwritten with a new value.
.SS "Naming Scheme"
The \s-1XGL\s0 library defines symbols that start with 
\fIXGL\fP, \fIXgl\fP, \fIxgl\fP, \fIXGLI\fP, \fIXgli\fP,
and \fIxgli\fP.
The application program should not define any symbols
(type names, enumerated values, cpp definitions, function names,
and so on) beginning with these prefixes.
.LP
.SS "Printed Manual vs. On-line Manual"
Most attributes and operators are discussed on their own separate manual page.
In some cases, however, several related attributes are discussed
together on a single manual page.
In the printed reference manual, only the page where they are
discussed is printed, but for the on-line manual, you can use
\fBman\fP (1) for any of the topics discussed on that page. 
.LP
For example, both
.BR \s-2XGL_\%3D_\%CTX_\%SURF_\%BACK_\%AMBIENT (3)\s0
and
.BR \s-2XGL_\%3D_\%CTX_\%SURF_\%FRONT_\%AMBIENT (3)\s0
are discussed on the page for 
.BR \s-2XGL_\%3D_\%CTX_\%SURF_\%FRONT_\%AMBIENT (3)\s0 .
In the printed reference manual, you will find only the page for
.BR \s-2XGL_\%3D_\%CTX_\%SURF_\%FRONT_\%AMBIENT (3)\s0
printed.
You can look up 
.BR \s-2XGL_\%3D_\%CTX_\%SURF_\%BACK_\%AMBIENT (3)\s0
in the index to see where it is discussed.
You can issue either of the following commands
for the on-line version, however:
.sp .4
.in +5
.nf
man \s-2XGL_3D_CTX_SURF_BACK_AMBIENT\s0
.sp .5v
man \s-2XGL_3D_CTX_SURF_FRONT_AMBIENT\s0
.in -5
.fi
.LP
You can also access the following descriptions of other aspects of
\s-1XGL\s0:
.IP "Data Structures"
described in
.BR xgl_\%struct (3)
.IP "Enumerated Types"
described in
.BR xgl_\%enum_\%types (3)
.IP "Macro Values"
described in
.BR xgl_\%macro_\%values (3)
.IP "Point Lists"
described in
.BR xgl_\%pt_\%list (3)
.IP "Object Types"
described on their individual man pages
.nf
.\" .BR \s-2XGL_\%OBJ (3)\s0
.BR \s-2XGL_\%2D_\%CTX (3)\s0
.BR \s-2XGL_\%3D_\%CTX (3)\s0
.BR \s-2XGL_\%CGM_\%DEV (3)\s0
.BR \s-2XGL_\%CMAP (3)\s0
.BR \s-2XGL_\%DMAP_\%TEXTURE (3)\s0
.BR \s-2XGL_\%GCACHE (3)\s0
.BR \s-2XGL_\%LIGHT (3)\s0
.BR \s-2XGL_\%LPAT (3)\s0
.BR \s-2XGL_\%MARKER (3)\s0
.BR \s-2XGL_\%MEM_\%RAS (3)\s0
.BR \s-2XGL_\%MIPMAP_\%TEXTURE (3)\s0
.BR \s-2XGL_\%PCACHE (3)\s0
.BR \s-2XGL_\%SFONT (3)\s0
.BR \s-2XGL_\%STREAM (3)\s0
.BR \s-2XGL_\%SYS_\%STATE (3)\s0
.BR \s-2XGL_\%TMAP (3)\s0
.BR \s-2XGL_\%TRANS (3)\s0
.BR \s-2XGL_\%WIN_\%RAS (3)\s0
.fi