XGL Reference Manual
Total Page:16
File Type:pdf, Size:1020Kb
XGL Reference Manual Sun Microsystems, Inc. 2550 Garcia Avenue Mountain View, CA 94043 U.S.A. A Sun Microsystems, Inc. Business 1997 Sun Microsystems, Inc., 2550 Garcia Avenue, Mountain View, California 94043-1100 USA. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, SunSoft, SunDocs, SunExpress, XGL, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and Sun(TM) Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227- 14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-3(a). DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. XGL Graphics Library Intro ( 3 ) NAME intro − introduces the XGL graphics library DESCRIPTION These Reference Manual pages describe the syntax for using the operators (functions) and attributes in the XGL Graphics Library. Special sections immediately following this introduction describe the XGL enumerated types, XGL macro values, XGL point list struc- tures, and XGL data structures. The next two sections describe, in alphabetical order, the XGL attributes and operators. The XGL programming paradigm is built around objects, which are instances of abstract data types. The application can create an object and apply operators to it. The applica- tion cannot, however, extend the de®nition of an object or modify the behavior of opera- tors. Therefore, XGL is not an object-oriented programming system, although its design does incorporate some object-oriented concepts. The XGL 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: #include <xgl/xgl.h> void xgl_object_set ( Xgl_object obj, <attribute-list> attributes ); The ®rst parameter is of the type Xgl_object, which is a handle to the XGL object data. The next argument, whose type is shown as <attribute-list>,isavariable length list of attribute-value pairs. A zero (ASCII NULL character) is used to mark the end of the list. Each XGL object has a set of attributes associated with it. An attribute is a named ®eld inside the object. The application can set an attribute's value, or it can retrieve its value, or both. The documentation for the XGL attributes speci®es the C data type needed for setting the attribute and the C data type needed for getting (retrieving) its value. The fol- lowing example describes how to set and get the attribute XGL_CTX_LINE_WIDTH_SCALE_- FACTOR(3), which controls the width of lines in the Context object. #include <xgl/xgl.h> Xgl_ctx ctx; xgl_object_set(ctx, XGL_CTX_LINE_WIDTH_SCALE_FACTOR, ¯oat, 0); xgl_object_get(ctx, XGL_CTX_LINE_WIDTH_SCALE_FACTOR, ¯oat ∗); This notation indicates that to set the attribute value, the application passes a ¯oat, and to get the value, the application passes a pointer to a ¯oat, which is overwritten with a new value. Naming Scheme The XGL library de®nes symbols that start with XGL, Xgl, xgl, XGLI, Xgli, and xgli. The application program should not de®ne any symbols (type names, enumerated values, cpp de®nitions, function names, and so on) beginning with these pre®xes. modi®ed August 1994 1 Intro ( 3 ) XGL Graphics Library Printed Manual vs. Most attributes and operators are discussed on their own separate manual page. In some On-line Manual 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 man (1) for any of the topics discussed on that page. For example, both XGL_3D_CTX_SURF_BACK_AMBIENT(3) and XGL_3D_CTX_SURF_FRONT_- AMBIENT(3) are discussed on the page for XGL_3D_CTX_SURF_FRONT_AMBIENT(3). In the printed reference manual, you will ®nd only the page for XGL_3D_CTX_SURF_FRONT_- AMBIENT(3) printed. You can look up XGL_3D_CTX_SURF_BACK_AMBIENT(3) in the index to see where it is discussed. You can issue either of the following commands for the on-line version, however: man XGL_3D_CTX_SURF_BACK_AMBIENT man XGL_3D_CTX_SURF_FRONT_AMBIENT You can also access the following descriptions of other aspects of XGL: Data Structures described in xgl_struct(3) Enumerated Types described in xgl_enum_types(3) Macro Values described in xgl_macro_values(3) Point Lists described in xgl_pt_list(3) Object Types described on their individual man pages XGL_2D_CTX(3) XGL_3D_CTX(3) XGL_CGM_DEV(3) XGL_CMAP(3) XGL_DMAP_TEXTURE(3) XGL_GCACHE(3) XGL_LIGHT(3) XGL_LPAT(3) XGL_MARKER(3) XGL_MEM_RAS(3) XGL_MIPMAP_TEXTURE(3) XGL_PCACHE(3) XGL_SFONT(3) XGL_STREAM(3) XGL_SYS_STATE(3) XGL_TMAP(3) XGL_TRANS(3) XGL_WIN_RAS(3) 2 modi®ed August 1994 XGL Graphics Library Intro ( 3 ) modi®ed August 1994 3 xgl_enum_types( 3 ) XGL Graphics Library NAME xgl_enum_types − XGL Enumerated Types DESCRIPTION This section lists the different C enumerated types XGL uses. The types appear with brief descriptions explaining their use, and they are listed by name in alphabetical order. Accumulation Buffer Depth typedef enum { XGL_ACCUM_DEPTH_1X, XGL_ACCUM_DEPTH_2X } Xgl_accum_depth; Arc Fill Styles Choices available for XGL_CTX_ARC_FILL_STYLE(3). Used when rendering arcs with xgl_- multiarc(3). typedef enum { XGL_ARC_OPEN, XGL_ARC_SECTOR, XGL_ARC_CHORD } Xgl_arc_®ll_style; Axes Used for Rotation Transforms typedef enum { XGL_AXIS_X, XGL_AXIS_Y, XGL_AXIS_Z } Xgl_axis; Bounding Box Data Types typedef enum { XGL_BBOX_I2D, XGL_BBOX_F2D, XGL_BBOX_F3D, XGL_BBOX_STATUS, XGL_BBOX_D2D, XGL_BBOX_D3D } Xgl_bbox_type; Blend Equation typedef enum { XGL_BLEND_NONE, XGL_BLEND_ARBITRARY_BG, XGL_BLEND_CONST_BG, 4 modi®ed February 1995 XGL Graphics Library xgl_enum_types( 3 ) XGL_BLEND_ADD_TO_BG } Xgl_blend_eq; Blend Draw Modes typedef enum { XGL_BLEND_DRAW_ALL, XGL_BLEND_DRAW_NOT_BLENDED, XGL_BLEND_DRAW_BLENDED } Xgl_blend_draw_mode; Status Returned by xgl_context_display_gcache typedef enum { XGL_CACHE_NOT_CHECKED,/∗displayed but not check ∗/ XGL_CACHE_DISPLAY_OK,/∗display OK on this ctx ∗/ XGL_CACHE_ATTR_STATE_DIFFERENT /∗ something in this cache's ∗ saved attribute state is ∗ different from the state in ctx ∗/ } Xgl_cache_display; Homogeneous Color Type typedef enum { XGL_COLOR_RGBW } Xgl_color_homogeneous_type; Color Types typedef enum { XGL_COLOR_INDEX, XGL_COLOR_GRAY, XGL_COLOR_RGB, XGL_COLOR_Z } Xgl_color_type; Curve Approximation Methods Choices available for XGL_CTX_NURBS_CURVE_APPROX(3). Used when rendering curves with xgl_nurbs_curve(3), and when rendering 3D circles using xgl_multicircle(3). typedef enum { XGL_CURVE_UNUSED,/∗was XGL_CURVE_CONST_PARAM_SUBDIV ∗/ XGL_CURVE_CONST_PARAM_SUBDIV_BETWEEN_KNOTS, XGL_CURVE_METRIC_WC, XGL_CURVE_METRIC_VDC, XGL_CURVE_METRIC_DC, XGL_CURVE_CHORDAL_DEVIATION_WC, XGL_CURVE_CHORDAL_DEVIATION_VDC, XGL_CURVE_CHORDAL_DEVIATION_DC, modi®ed February 1995 5 xgl_enum_types( 3 ) XGL Graphics Library XGL_CURVE_RELATIVE_WC, XGL_CURVE_RELATIVE_VDC, XGL_CURVE_RELATIVE_DC } Xgl_curve_approx; Data Types The data types supported within XGL for geometric representation of data, transforma- tions, and internal calculations. typedef enum { XGL_DATA_INT,/∗32-bit integer ∗/ XGL_DATA_FLT, /∗ single precision ¯oating point ∗/ XGL_DATA_DBL /∗ double precision ¯oating point ∗/ } Xgl_data_type; Deferral Modes Choices available for XGL_CTX_DEFERRAL_MODE(3). Used to specify whether to buffer rendering operations. typedef enum { XGL_DEFER_ASTI, XGL_DEFER_ASAP } Xgl_deferral_mode; Depth Cue Modes Choices available for XGL_3D_CTX_DEPTH_CUE_MODE(3). Used to specify the kind of depth-cueing desired. typedef enum { XGL_DEPTH_CUE_OFF, XGL_DEPTH_CUE_LINEAR, XGL_DEPTH_CUE_SCALED } Xgl_depth_cue_mode; Graphics Library Error Categories typedef enum { XGL_ERROR_SYSTEM, XGL_ERROR_CONFIGURATION, XGL_ERROR_RESOURCE, XGL_ERROR_ARITHMETIC, XGL_ERROR_USER } Xgl_error_category; 6 modi®ed February 1995 XGL Graphics