Domain 3D Graphics Metafile Resource Version 3.1
Release Document
June 21, 1990
Copyright Hewlett-Packard Co. 1990.
First Printing: July 1990
UNIX is a registered trademark of AT&T in the USA and other countries.
The information contained in this document is subject to change
without notice.
HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS
MATERIAL INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MER-
CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard
shall not be liable for errors contained herein or for incidental or
consequential damages in connection with the furnishing, performance
or use of this material. Information in this publicati
Hewlett-Packard assumes no responsibility for the use or reliability
of its software on equipment that is not furnished by Hewlett-Packard.
This document contains proprietary information which is protected by
copyright. All rights reserved. No part of this document may be pho-
tocopied, reproduced or translated to another language without the
prior written consent of Hewlett-Packard Company.
RESTRICTED RIGHTS LEGEND. Use, duplication or disclosure by government
is subject to restrictions as set forth is subdivision (b) (3) (ii) of
the Rights in Technical Data and Computer Software clause at DFARS
52.227-7013. Hewlett-Packard Company, 3000 Hanover Street, Palo Alto,
CA 94304
10 9 8 7 6 5 4 3 2 1
Preface
This document describes 3D GMR Version 3.1 software. It includes an
overview of new and changed functionality, software installation
information, documentation references, a list of known errors and lim-
itations, and information on the new call interfaces and data types.
The normal software installation process places a version of this
release document in each node's /install/doc/apollo directory.
How to Print the Release Notes
You may print the online copy of this document.
In the following commands, pathname is the location of the release
notes, usually /install/doc/apollo/gmr3d.v.3.1notes (note that there
are two underscores before notes); printer_name is the name of the
printer on which you will print the notes.
If your installation uses the SysV lp print daemon, use an lp command
similar to the following:
lp -dprinter_name pathname
If your installation uses the Aegis print system, use the following
Aegis /com/prf command:
prf pathname -pr printer_name -npag
If your installation uses the BSD lpd print daemon, use an lpr command
similar to the following:
lpr -Pprinter_name pathname
CONTENTS
1. Overview of 3D GMR Version 3.1.............................. 1-1
1.1 Software Overview...................................... 1-1
1.2 Features Included from Version 3.0.p................... 1-2
1.3 New Features in Version 3.1............................ 1-3
1.4 Sample Programs........................................ 1-3
2. Installing and Using 3D GMR................................. 2-1
2.1 Using 3D GMR........................................... 2-1
3. Documentation............................................... 3-1
3.1 Current 3D GMR Documentation........................... 3-1
3.2 HP/Apollo VRX Graphics Controllers..................... 3-2
3.3 New Features in 3D GMR................................. 3-2
3.3.1 Two-Stage Initialization....................... 3-2
3.3.2 Triangle Strip and Quadrilateral Mesh.......... 3-4
3.3.3 Transparency................................... 3-4
3.3.4 16/24/32-Bit Z-Buffer.......................... 3-4
3.3.5 Dithered Rendering and the PersonalVRX Graph-
ics Controller................................. 3-4
3.3.6 Double Buffering for the PersonalVRX 3D Con-
troller........................................ 3-5
3.3.7 Overlay Planes Available to 3D GMR Applica-
tions.......................................... 3-7
3.3.8 User Clip Lists................................ 3-7
3.3.9 New Line Style................................. 3-8
3.3.10 Line Width Attribute........................... 3-8
3.3.11 New Opcodes for Packet Interface............... 3-8
3.3.12 Current-bitmap-noclear Initialization.......... 3-9
3.3.13 Changes in GMR/GPR Refresh Handlers............ 3-9
3.4 Window Manager Support................................. 3-9
3.4.1 New Commands and Utilities..................... 3-9
3.4.1.1 Fast Buffer Swapping.................. 3-9
3.4.1.2 New Switch on lcm Command............. 3-10
3.4.1.3 New Switches on the DM Refresh Screen
Command............................... 3-10
3.4.2 Default Color Map Usage........................ 3-11
3.4.3 Colormap Support............................... 3-11
3.5 Performance and Other Notes............................ 3-12
3.5.1 Z-Buffer Compare Types......................... 3-12
3.5.2 Polygon Differences............................ 3-12
3.6 Screen-Door and Alpha Buffering........................ 3-12
4. Limitations and Known Bugs.................................. 4-1
4.1 PostScript Ignores Z-Buffer Parameters................. 4-1
4.2 Limitations............................................ 4-1
4.3 Bugs................................................... 4-1
4.4 Bugs that Have Been Closed............................. 4-2
4.5 Obsoleted Cowriter Mode................................ 4-2
v
A. New Call Interfaces and Data Types......................... A-1
vi
Chapter 1: Overview of 3D GMR Version 3.1
This release presents Version 3.1 of the Domain 3D Graphics Metafile
Resource package. 3D GMR provides a full set of functions for build-
ing, editing, and displaying files of graphics data.
Version 3.1 supersedes Version 2.7 and is an outgrowth of Version
3.0.p ( which was compiled especially for Series 10000 workstations).
Version 3.1 provides support for the new HP/Apollo VRS graphics con-
trollers, which are described in SR10.2 Product Support Kit Release
Document, (SFW-PSK7-10.2) or later Domain/OS release documents.
3D GMR version 3.1 uses the new PersonalVRX 3D color graphics con-
troller to support Z-buffering, double buffering, true color emulation
with 3/3/2 dithering, and screen-door transparency. Libraries are
provided to run on m68k-based Domain/OS platforms with full support of
the functionality supported in such systems in previous versions of 3D
GMR. The m68k gmr3d v3.1 libraries will run with the kernel libraries
released with Domain/OS SR10.2 (SFW-PSK7-10.2).
3D GMR has added a data type for a clip window list, and it provides
new set and inquiry calls. These calls let an application set and
inquire a list of clip regions into which the DM window interior is
divided. 3D GMR will intersect that list with its own list for each
viewport (as computed by current overlapping viewport support code)
and render into the resulting merged list of rectangles.
3D GMR also supports line width and text width attributes. Text width
only affects the width of lines used when rendering stroke text. Line
width affects the width of lines used for rendering 2D and 3D poly-
lines, multilines, circles, and arcs.
1.1 Software Overview
We intend the Domain 3D Graphics Metafile Resource package (3D GMR)
for programmers who wish to develop graphics applications packages
presenting images in three-dimensional space. The 3D Graphics
Metafile Resource package provides a versatile, efficient tool for
developing a graphics applications system that stores and displays
picture data.
3D GMR is a collection of routines that provide the ability to create,
display, edit, and store device-independent files of picture data.
The package provides routines for developing and storing picture data,
and displaying the graphic output defined by that data. It also
Overview of 3D GMR Version 3.1 1-1
3D GMR Version 3.1
integrates graphics output capabilities with file handling and editing
capabilities. In addition, this package provides you with the neces-
sary support to build a graphics system "with a memory."
The standard form of data storage in this package is a metafile. A
metafile is a device-independent collection of picture data, graphics,
and text that can be displayed. The metafiles you create are stored
and are available for you to redisplay, revise, and reuse. They are
not static copies of display bitmaps; rather, metafiles contain lists
of elements used to build a graphic image.
The 3D GMR package reflects the concern in the industry for standardi-
zation. We have designed the 3D GMR package to accommodate and pro-
mote standards for workstation graphics applications.
1.2 Features Included from Version 3.0.p
Table 1 describes the features that have been included from 3D GMR
Version 3.0.p and are now available on the VRX graphics controllers.
Two-stage initialization, and the quadrilateral mesh and triangle
strip drawing primitives are also supported now on all Apollo graphics
controllers.
___________________________________________________________
| | VRX Graphics Controllers |
| Feature | mono | 2-D color | 3D color |
|---------------------------|------|-----------|----------|
| Two-stage initialization | yes | yes | yes |
| Triangle strip drawing | yes | yes | *1 |
| Quadrilateral mesh " | yes | yes | *1 |
| Transparency | | | *2 |
| 16-bit Z buffering | yes | yes | *3 |
| True-color double-buffered| | | |
| dithered rendering | | | *4 |
| Overlay planes | | yes | yes |
|---------------------------|------|-----------|----------|
| NOTES |
| 1. Accelerated in hardware |
| 2. Via the "screen-door" technique |
| 3. Hardware Z buffering on PersonalVRX's; |
| software on other devices |
| 4. Dithering is 3:3:2 on the new 3D color controller |
|_________________________________________________________|
Table 1. VRX-Specific Features
1-2 Overview of 3D GMR Version 3.1
3D GMR Version 3.1
1.3 New Features in Version 3.1
The following features, documented more fully in Chapter 3 of this
release document, are new to this version:
o User clip lists
o New line style
o Line width attribute
o Newly exposed opcodes for packet interface (including an expanded
gmrpacketmacro.h file in domainexamples/gmr3d/packet):
- 3x4 & 4x4 local and global transforms
- model text (2d/3d)
- text attributes
- 2d arcs
- 3d conics
o Current-bitmap-noclear initialization mode
o Revised DM refresh handling
1.4 Sample Programs
Read the following file for instructions on using sample programs:
/domainexamples/gmr3d/readme
This release includes sample 3D GMR programs in Pascal, FORTRAN, and
C. These programs are in the directories:
/domainexamples/gmr3d
There are four example directories for this release:
o /domainexamples/gmr3d/advancedgraphics
o /domainexamples/gmr3d/xwindows
o /domainexamples/gmr3d/viewer
o /domainexamples/gmr3d/packet
The programs in the /domainexamples/gmr3d/advancedgraphics directory
are specifically for DN10000VS.
Overview of 3D GMR Version 3.1 1-3
3D GMR Version 3.1
The programs in the /domainexamples/gmr3d/xwindows directory show
how to run a 3D GMR application in a disowned X Window.
The /domainexamples/gmr3d/viewer directory includes a sample metafile
viewer that uses Domain/Dialogue for the user interface. The source
used to construct the viewer is also in the viewer directory.
Refer to Chapter 17 of Programming with Domain 3D Graphics Metafile
Resource for information on using pixel formats within a
Domain/Dialogue program.
The programs in /domainexamples/gmr3d/packet show how to use the 3D
GMR packet interface. Refer to Appendixes B and C of Programming with
Domain 3D Graphics Metafile Resource.
1-4 Overview of 3D GMR Version 3.1
3D GMR Version 3.1
Chapter 2: Installing and Using 3D GMR
You can install 3D GMR version 3.1 on a user node equipped with moni-
tor and keyboard or on a Domain Server Processor (DSP). You must be
running Version SR10.2 (or later) of the Domain/OS operating system.
There are two versions of 3D GMR on this tape - v2.7 and v3.1. If you
are running Version SR10.1 of the Domain/OS operating system, load
v2.7. If you are running SR10.2 or later, load v3.1. 3D GMR v2.7 has
been provided for compatibility with 3D GMR applications that might
require Domain/OS SR10.1. 3DGMR v2.7 does not contain the new features
and bug fixes described in the release notes.
Note that the VRX graphics controllers require the PSK7 Version of
SR10.2.
The 3D GMR media contains the following products:
Product Version Selection File Override File
gmr3d 3.1 aa.gmr3d ov.gmr3d
Selection and override files reside in the directory
//<authorized_area>/install/templates/apollo/gmr3d.v.3.1
For more directions about installing this product, locating the
authorized area, and using the selection and override files, see the
manual Installing Software with Apollo's Release and Installation
Tools (008860-A02).
NOTE: The user node or DSP must have a minimum of 12,000 1024-byte
blocks of available disk space for a successful installation of
the 3D GMR software.
2.1 Using 3D GMR
To use 3D GMR, you must load the 3D GMR library into every process in
which you want 3D GMR to run. You have the choice of loading the
library explicitly or loading the library dynamically when the appli-
cation program executes. We recommend you use one of the dynamic
loading methods. See Chapter 2 of Programming with Domain 3D Graphics
Metafile Resource (005807-A01) and Domain/OS Programming Environment
Reference (011010-A01) for further information.
Installing and Using 3D GMR 2-1
3D GMR Version 3.1
You can use the ts (timestamp) command to obtain the timestamp of a 3D
GMR library. The ts command is in the /usr/apollo/bin directory.
2-2 Installing and Using 3D GMR
3D GMR Version 3.1
Chapter 3: Documentation
This chapter
o Lists the current 3D GMR documentation,
o Describes the new features included in this release that had been
included in 3D GMR Version 3.0.p,
o Describes features that have not been released before,
o Includes sections on window management support and performance,
and
o Describes portability issues.
3.1 Current 3D GMR Documentation
The 3D GMR documentation set consists of the following two manuals:
o Programming with Domain 3D Graphics Metafile Resource (005807-
A01)
o Domain 3D Graphics Metafile Resource Call Reference (005812-A01)
Programming with Domain 3D Graphics Metafile Resource provides a
task-oriented guide to using 3D GMR. The manual includes program
fragments and complete programs to illustrate the use of 3D GMR rou-
tines and procedures. See Chapters 17 through 22 for information
about the features that have been incorporated from Version 3.0.p into
the current version, 3.1.
Domain 3D Graphics Metafile Resource Call Reference describes the data
types and routines that make up the 3D GMR package. The following
information should be added to the description of gmr$addnameset on
page 2-74 of this manual:
3D GMR restricts the values you can assign to a name set
to the range [1,255]. Using 0 or values greater than
255 generate 'Invalid name set' errors.
Documentation 3-1
3D GMR Version 3.1
3.2 HP/Apollo VRX Graphics Controllers
See the SR10.2 Product Support Kit Release Document, (SFW-PSK7-10.2)
or later Domain/OS release documents for a description of the new
graphics controllers that run this version of 3D GMR.
3.3 New Features in 3D GMR
This section describes changes to the manuals that relate to the
features that have been included from Version 3.0.p. and that are now
available to m68k systems, particularly the PersonalVRX 3D color
graphics controller.
3.3.1 Two-Stage Initialization
As explained in Chapter 17 of Programming with Domain 3D Graphics
Metafile Resource, there are several changes in the area of 3D GMR
initialization and configuration inquiry:
o Initialization has been broken up into a package initialization
and a device-specific display initialization.
o The device-specific initialization and the configuration-inquiry
calls developed for the DN10000VS include mechanisms for select-
ing pixel and projection formats. These have been extended for
this release to provide support for VRX-specific pixel formats
such as 3/3/2 true color emulation mode.
o Both forms of initialization reference a display mode parameter.
This parameter has been extended with a new value that suppresses
initialization of the default viewport.
Note that there are slightly different pixel formats for true color
emulation on the PersonalVRX 3D graphics controller are as follows:
length: 15
pixel_mode: gpr_$pixel_truecolor
image_depth: 24
buffer_count: 2
red_depth 8
green_depth: 8
blue_depth: 8
ovlay_mode: gpr_$ovlay_none
ovlay_depth: 0
ovlay_buffer_count 0
.
.
3-2 Documentation
3D GMR Version 3.1
length: 15
pixel_mode: gpr_$pixel_truecolor
image_depth: 24
buffer_count: 2
red_depth: 8
green_depth: 8
blue_depth: 8
ovlay_mode: gpr_$ovlay_per_rectangle
ovlay_depth: 4
ovlay_buffer_count: 1
.
.
length: 15
pixel_mode: gpr_$pixel_truecolor
image_depth: 24
buffer_count: 2
red_depth 3
green_depth: 3
blue_depth: 2
ovlay_mode: gpr_$ovlay_none
ovlay_depth: 0
ovlay_buffer_count 0
.
.
length: 15
pixel_mode: gpr_$pixel_truecolor
image_depth: 24
buffer_count: 2
red_depth: 3
green_depth: 3
blue_depth: 2
ovlay_mode: gpr_$ovlay_per_rectangle
ovlay_depth: 4
ovlay_buffer_count: 1
.
.
Notice, in the last two formats, that the red, green, and blue depths
add up to 8, and the image depth required for color value is 24.
Therefore, application code should always supply 24-bit color values
for true color screen bitmap rendering emulation to work correctly on
the 3D color graphics controller. Otherwise the results will not be
valid. The first two formats are provided for binary compatibility
with existing applications.
Also, notice that gpr$initialize will accept the 8/8/8 image depths,
but it will change them to 3/3/2 on the 3D color graphics controller.
Documentation 3-3
3D GMR Version 3.1
3.3.2 Triangle Strip and Quadrilateral Mesh
The triangle strip and quadrilateral drawing primitives are described
in Chapter 18 of Programming with Domain 3D Graphics Metafile
Resource.
Note that there is some slight difference in the rendering of tri-
angles in true color emulation between the PersonalVRX 3D color graph-
ics controller and the DN10000VS. Since all dithered fills are done
relative to the window in the new controller, two dithered abutting
triangles in the same window show no noticeable intersection if the
same color is used for both.
3.3.3 Transparency
Transparency is described in Chapter 19 of Programming with Domain 3D
Graphics Metafile Resource. Applications that already make use of
transparency in the DN10000VS do not require source code modifications
to access this feature, beyond the initialization sequence noted in
the section on portability, below.
For the PersonalVRX 3D color graphics controller, we now support
"screen-door transparency," which is the simulation of transparency by
write-enabling and write-disabling individual pixels in a 4x4 cell
that is repeated across the whole screen. One image is drawn, some
pixels are write-disabled, and another image is drawn. Where the
write-disabled pixels are, the first polygon "shows through," and
where the write-enabled pixels are, the second polygon's image
appears.
See the Portability section on "Screen-Door and Alpha Buffering" at
the end of this chapter for more information.
3.3.4 16/24/32-Bit Z-Buffer
See Chapter 20 of Programming with Domain 3D Graphics Metafile
Resource.
3.3.5 Dithered Rendering and the PersonalVRX Graphics Controller
Dithered render mode for true color emulation on the PersonalVRX 3D
color graphics controller changed slightly from the DN10000VS.
The 3D graphics display controller has the capability to 3:3:2 dither
over a 4x4 area while rendering primitives. Dithered rendering is a
process whereby a fill color is represented by a limited number of
different colored pixels, specifically laid out on the screen so that
the human eye blends the different colors into the original.
The 3D graphics controller uses a 4x4 8-bit color dither. The
hardware will perform the dither with some random noise added to the
3-4 Documentation
3D GMR Version 3.1
formula to prevent mach banding. The colors selected for the dither
are sorted by luminosity and filled into the following matrix (the
brighter color is filled into the lowest numbered pixel):
12
--------------------- 15 2
| 1 | 13 | 4 | 16 | 11 7 10 6
|----|----|----|----| 16 1 13 4 16 1
| 9 | 5 | 12 | 8 | 12 8 9 5 12 8 9
|----|----|----|----| 2 14 3 15 2 14 3 15
| 3 | 15 | 2 | 14 | 7 10 6 1 7 10 6 11 7 10
|----|----|----|----| 1 13 4 16 1 13 4 16 1 13 4
| 11 | 7 | 10 | 6 | 9 5 12 8
|----|----|----|----|
A Dither-Filled Triangle
Dither Precedence Matrix Using This Matrix
True color applications using gmr$init() with a true color display
mode will access the true color emulation when run on the PersonalVRX
3D color graphics controller. Filled primitives may look slightly
grainy from less than two feet away.
3.3.6 Double Buffering for the PersonalVRX 3D Controller
On the PersonalVRX 3D graphics controller, Applications using just one
GMR3D viewport should be able to use double buffering calls just as
they do on current devices. Applications using multiple double-
buffered viewports will be responsible for keeping the visible buffers
synchronized across all viewports. There is nothing that GMR3D can do
to simulate multiple, independent, double-buffered viewports. The same
is true for a single GMR3D process running in multiple DM windows.
The main change in this area has to do with the PersonalVRX 3D color
graphics hardware's double buffering mechanism. It requires that the
entire screen be double buffered as one unit. In order to support a
mixture of double buffered and single buffered applications, 3D GMR
ensures that single buffer applications write to both buffers through
the following mechanism:
o By default, bitmaps are assumed to be single buffered, and GMR
automatically writes to both buffers.
o Once an application has specified that a bitmap is double buf-
fered, it can make a GPR call to activate and deactivate the
ability to write into both buffers. This call is
gpr$setrenderbothbuffers.
GMR3D software helps to ensure that drawing in all single buf-
fered viewports occurs simultaneously to both buffers. However,
Documentation 3-5
3D GMR Version 3.1
for non-hidden rendering (single buffered viewport), the applica-
tion must make sure that the draw buffer is set to the last
display buffer value.
In addition, the application needs to ensure that writing to
this single buffered viewport will be performed into both buffers
through the use of the new GPR call, gpr$renderbothbuffers().
The application must control both the activation and deactivation
of rendering into both buffers by using this call.
PROCEDURE gpr_$set_render_both_buffers(
IN screen_bitmap : gpr_$bitmap_desc_t; { bitmap descriptor }
IN value : BOOLEAN; { to render or not }
OUT status : status_$t { returned status }
); EXTERN;
The fact that the entire screen changes at once affects the behavior
of two calls in the current 3D GMR interface:
o gmr$dbuffdisplaybuffer: switches the display buffer with the
draw buffer change options
o gmr$dbuffsetdisplaybuffer: switches the display buffer and
clears the opposite buffer
For both of these calls on systems using the PersonalVRX 3D color
graphics controller, the entire screen is switched to the other
buffer. However, any clearing or other draw buffer change options car-
ried out on the opposite buffer are bounded by the region that defines
the viewport.
For mixed 3D GMR and GPR applications where double buffering takes
place in one or more 3D GMR viewports, and single-buffered GPR graph-
ics take place simultaneously, applications need to ensure that the
single-buffered graphics is preserved during display buffer swaps by
writing into both buffers using the new GPR call mentioned above.
If, for instance, a Domain/Dialogue application uses a double-buffered
3D GMR area, make sure that the application writes to both buffers by
calling gpr$renderbothbuffers(). (The Dialogue regions are treated
as distinct bitmaps.)
If multiple processes invoke double buffering, there is no systematic
way for each process to synchronize its buffer swaps with other
processes. See the "Window Manager Support" section for a description
of how applications can prevent collisions when more than one double-
buffered application is running simultaneously.
3-6 Documentation
3D GMR Version 3.1
3.3.7 Overlay Planes Available to 3D GMR Applications
See Chapter 22 of Programming with Domain 3D Graphics Metafile
Resource.
3.3.8 User Clip Lists
This section describes an extension to 3D GMR that allows an applica-
tion better control over the internal window clip list. The overall
goal of such an extension is to permit the user some extra measure of
control of the visibility and priority of viewports in a GSR, GPR, or
GMR environment. Toward this end, we have added three new procedure
interfaces (which are described in detail in Appendix A). The first
two are for gathering and returning information regarding the
application's own clip list:
PROCEDURE gmr_$set_user_clip_list
( IN window_list : UNIV gmr_$window_list_t
; IN window_cnt : INTEGER32
; OUT status : status_$t
); EXTERN;
PROCEDURE gmr_$inq_user_clip_list
( OUT window_list : UNIV gmr_$window_list_t
; IN max_window_cnt : INTEGER32
; OUT window_cnt : INTEGER32
; OUT status : status_$t
); EXTERN;
where:
TYPE gmr_$window_list_t = ARRAY [ 1 .. gmr_$max_clip_list_len ]
OF gmr_$i2_limits_t;
The user clip lists are applicable to the DM window area as a whole
(as opposed to a per viewport applicability). At viewport refresh
time, the user's clip list is intersected (or merged) with the
viewport's visibility list resulting in a new window clip list. This
new list is presumed to be a subset of the actual internal viewport
visibility or clip list (see below).
As for the third call, the application may need to know what portions
of a viewport are visible and for that we provide
gmr$viewportinqcliplist, as follows:
Documentation 3-7
3D GMR Version 3.1
PROCEDURE gmr_$viewport_inq_clip_list
( IN viewport_id : gmr_$viewport_id_t
; OUT window_list : UNIV gmr_$window_list_t
; IN max_window_cnt : INTEGER32
; OUT window_cnt : INTEGER32
; OUT status : status_$t
); EXTERN;
This call returns the contents of the screen_window_list field in the
internal 3D Virtual Device Record. There is no complementary
gmr$viewportsetcliplist call for the following reasons:
o The application can achieve the same effect with the
gmr$setusercliplist call
o The viewport-specific visibility list is derived internally,
based on viewport priority and transparency attributes, and
therefore it is not amenable to manipulation by the application.
3.3.9 New Line Style
The VRX microcode supports a line pattern definition that is up to 32
bits in length with a repeat count up to 64. GPR/GSR supports an up to
64-bit pattern with a repeat count between 1 and 32767. Pattern defin-
itions that cannot be handed directly to the microcode are supported
by VRX display library software, at a significant performance loss.
For greater performance, the rasterization engine in the VRX controll-
ers buffers the polyline instructions and under some circumstances may
sort the individual strokes and render them in a different order,
perhaps rendering a line from the endpoint to the beginning point.
3.3.10 Line Width Attribute
3D GMR now supports line width attributes. Line width affects the
width of lines used for rendering 2D and 3D polylines, multilines,
circles, and arcs. Wide lines are rendered more slowly than lines
that use the default line width.
3.3.11 New Opcodes for Packet Interface
The new opcodes for the packet interface include an expanded
gmr_packet_macro.h file in /domainexamples/gmr3d/packet that allow
3x4 and 4x4 local and global transforms, model text (2D/3D), text
3-8 Documentation
3D GMR Version 3.1
attributes, 2D arcs, and 3D conics.
3.3.12 Current-bitmap-noclear Initialization
A new display mode, gmr$currentbitmapnc, has been added to
gmr$displaymodet:
gmr_$display_mode_t = (
gmr_$borrow,
gmr_$main_bitmap,
gmr_$direct,
gmr_$no_bitmap,
gmr_$current_bitmap,
gmr_$borrow_rgb,
gmr_$current_bitmap_nc { <= new mode }
);
The purpose of this mode is to prevent the automatic clearing of the
DM window area at initialization time. In addition, this mode keeps
3D GMR from automatically clearing and refreshing the DM window area
at DM refresh time. This mode also causes "viewport autoclear" to
default to FALSE. To override this default, use the
gmr$viewportsetautoclear call.
3.3.13 Changes in GMR/GPR Refresh Handlers
You can now specify GPR DM refresh entry addresses for user-written
GPR refresh handlers without their being overwritten when a GMR
refresh handler is subsequently initialized.
3.4 Window Manager Support
This section describes some new commands and utilities, new switches
on the DM Refresh Screen command, and the default color map usage.
3.4.1 New Commands and Utilities
We've added some new commands and an X client related to fast buffer
swapping. Also, we've added a new switch to the lcm command.
3.4.1.1 Fast Buffer Swapping
On some graphic devices, fast double buffer swapping is supported on
only a limited number of windows. When more than one application
attempts to use GPR's double buffering feature, a new DM command, FBS,
allows the user to select which client uses the fast buffer mechanism
on these devices. (Initially applications have fast buffer swap
enabled.)
Documentation 3-9
3D GMR Version 3.1
If the user is running the DM, the ability to enable/disable fast
buffer swap is in the form of a new DM command:
FBS [-on|-off|-toggle]
The user can use FBS with the dr command (to select a window) or bind
it to a key and select the window that the cursor is in. This way, the
user has total control over which windows are rendering smoothly.
A new X client, xfbs, provides the same services as FBS, except it
provides them within an X environment. This xfbs client prompts the
user to select a window by moving the cursor over the window and
clicking a mouse button, in a manner similar to the xwininfo client.
3.4.1.2 New Switch on lcm Command
The -rgb332 switch has been added to the lcm command to load the exact
dither colormap required by the PersonalVRX 3D color graphics con-
troller. Although this command works on all devices, it is only
relevant to this controller. It loads the values specified in the
`nodedata/etc/dmdisplay/colormap.rgb332 file.
3.4.1.3 New Switches on the DM Refresh Screen Command
The DM's Refresh Screen (RS or ^F) command now has three options to
support runtime color selection. In the first two options, the DM
obtains the pad foreground/background colors from slots 8-15 of
~/userdata/colormap if it exists, otherwise it uses slots 8-15 of
`nodedata/etc/dmdisplay/colormap.
o -f: Force the colors obtained from the color_map file into
available color slots in the currently loaded colormap, if they
don't exactly match the colors already in the map.
o -n: Nearest color matches from the currently loaded colormap to
colors from the color_map file are used for the pad
foreground/background color template.
o -o: Original operation (as in the past) -- the DM locks color
slots 8-15 of the currently loaded colormap, if available.
The default behavior is option -f.
This new behavior can cause some unexpected results especially for
monochrome applications that assume that the pad foreground and back-
ground values for a single pad are adjacent slots in the currently
loaded colormap. This assumption no longer holds for all colormaps.
These applications will behave correctly if you load a colormap that
satisfies this assumption, then execute RS -f or RS -n.
3-10 Documentation
3D GMR Version 3.1
3.4.2 Default Color Map Usage
Window manager support minimizes the visual effects (technicolor)
caused by the fact that there is a single physical lut (color lookup
table) device supporting more than one type of display mode (pseudo-
color, 3/3/2 with dither true color emulation).
The PersonalVRX hardware dither support for true color emulation
requires that a specific colormap be loaded. Undesirable visual
effects result when a different colormap is loaded.
The Display Manager provides support to prevent the visual anomalies
described above. First, the default color map loaded by the DM at
startup will be seeded with the dither colormap with the following
exceptions:
o The first 16 values in the colormap have the standard DM default
colors used on all current Domain Graphics devices. This provides
backward compatibility for applications that assume that the pri-
mary, secondary, and DM colors are in the first 16 values.
o The same 16 colors are placed at their closest match index in the
dither portion of the map. This is so the DM finds its color
values in the dither portion, not in the range 0-16. (This scheme
required a change to CTM which is described in the next section.)
3.4.3 Colormap Support
The Color Table Manager (CTM) implementation of ctm$findcolor()
change slightly to help minimize the visual effects of dithered fil-
ling:
o The ctm$findcolor() call finds the best unused index rather
than the first unused index. In a DM window environment,
ctm$findcolor() now finds the best match within the dither
colormap. This allows applications using this call in pseudo-
color mode to "share" the same colormap with true color clients
and still minimize color problems.
o The CTM locates this best unused index by searching through the
colormap in reverse order (from FF->00, rather than 00->FF).
Again in a DM environment, this means that the default DM colors
are found in the dither colormap's upper range and not within the
first 16 values (which have the DM colors for backward compati-
bility.)
Documentation 3-11
3D GMR Version 3.1
3.5 Performance and Other Notes
This section briefly provides additional notes on 3D GMR.
3.5.1 Z-Buffer Compare Types
The PersonalVRX 3D color graphics controller hardware implements all
Z-buffer comparisons, with the exception of the rarely used = and <>.
On the PersonalVRX P3 (with 8 planes and 4 overlay planes), all of the
Z-buffer comparisons are implemented in software.
3.5.2 Polygon Differences
In 3D GMR, concave polygons and polygon sets specified by the user are
decomposed into a stream of triangles. Rasterization of this stream
may result in occasional single-pixel differences when compared with
rasterization of the original geometry in other Domain display dev-
ices. In addition, the PersonalVRX graphics controller can directly
rasterize convex/concave polygons without decomposition at a higher
performance level. However, 3D GMR applications get higher performance
if they can decompose concave regions into large convex areas: these
are handed to the PersonalVRX hardware directly by 3D GMR (instead of
using concave polygons which force a 3D GMR decomposition into tri-
angles).
3.6 Screen-Door and Alpha Buffering
Screen-door transparency and alpha buffering involve certain con-
siderations as outlined here.
o No special pixel format specification is required for screen-door
transparency: just use true-color initialization (the DN10000VS
requires alpha buffer).
o In both cases, opaque or non-transparent surfaces need to be ren-
dered before transparent or translucent surfaces.
o For rendering to look accurate and as expected, the transparent
or non-opaque surfaces should be sorted from back to front and
rendered in that order. For simple cases (minimal layering),
this step is not always necessary.
o Sorting of the transparent surfaces is often necessary for the
best visible results when using the alpha buffering technique.
With the screen-door technique, sorting of transparent surfaces
is not required. Therefore, the BSP is not that useful with the
screen-door implementation.
o We currently do not have an inquiry in GMR that indicates tran-
sparency is available. The render_mode
3-12 Documentation
3D GMR Version 3.1
gmr$renderfilledtransparency is a superset of
gmr$renderfilled.
o Nor do we currently have an inquiry mechanism that distinguishes
the alpha buffer implementation from the screen-door implementa-
tion. Applications have to know that a DN10000VS requires alpha
buffer specification while the PersonalVRX 3D color graphics con-
troller does not.
Documentation 3-13
3D GMR Version 3.1
Chapter 4: Limitations and Known Bugs
This chapter discusses limitations and known bugs in 3D GMR.
4.1 PostScript Ignores Z-Buffer Parameters
PostScript output ignores Z-buffering parameters: both
gmr$printviewport and gmr$printdisplay ignore Z-buffering values
when creating PostScript output values. BSP is the only option avail-
able to a user wanting to do hidden surface removal using PostScript.
Z buffering is not relevant to 2D output files.
4.2 Limitations
o Invisibility filters are ignored when structures are called
rather than instanced. Use structure instancing rather than cal-
ling structures to get the full functionality of instancing.
o The PersonalVRX does not support individual edge control for quad
meshes and triangle strips. Vertex flags are ignored.
o It should be noted that the call gmr$displayrefresh sets the
display buffer for each viewport after refreshing which by con-
vention causes a clear of the other buffer.
o As a result, this call is not useful in conjunction with
gpr$setrenderbothbuffers since it will not preserve rendering
in both buffers as a result of the clearing.
4.3 Bugs
o Switching between multiple metafiles mapped to a single viewport
is not recognized.
o On a DVS node if you translate geometry off the left edge of the
viewport, when you bring it back into full view, at one point the
geometry disappears. You have to translate it again in order for
it to reappear.
o gmr$shadinginqconfig does not reset status.
o Zooming in extremely close to a model creates a process crash
with a floating point overflow.
Limitations and Bugs 4-1
3D GMR Version 3.1
o On the Desktop Visualization System (DVS), clip and nonclip cases
of different fills produce different colors.
o Incorrect shading of quad meshes on the Desktop Visualization
System (DVS) and E-type controllers.
o Generic quad meshes don't smooth-shade on the DN590.
o GMR_$COLOR_SET_MAP: The manual Programming with Domain 3D Graph-
ics Metafile Resource (5812-A01), p 2-100, says that argument 1
(start_index) is a two-byte integer, yet the type declaration is
gmr$lt, which is a four-byte integer.
o Incompatability between using view_set transform and view_set
other params calls. The documentation for viewinq calls may be
inconsistent: viewinq outputs inconsistent projection type
values; viewinqstate and viewinqprojectiontype should always
return the same projection value.
o Cursor droppings when picking.
4.4 Bugs that Have Been Closed
o APR# DDEA03
3D GMR allocates too much memory at runtime.
o APR# DDA60
An object being dynamically displayed is correctly displayed in
the first three viewports, but is displayed in all four orienta-
tions in the fourth viewport.
o APR# DDA5D
Repeated zooming inward (increased magnification) eventually
causes GMR to loose track of the correct aspect ratio of a view.
o APR# DD642
gmr$displaysetbgcolor does not set its status argument if
there is no error.
o APR# DD839
Shaded object displays differently on systems containing 3DGAs
than on non-3DGA systems.
4.5 Obsoleted Cowriter Mode
As mentioned in the release document for 3D GMR, version 3.0.p, we
have obsoleted the cowriter mode (gmr_$cowriters) from the
gmr$fileopen call in this current release (3.1).
4-2 Limitations and Bugs
3D GMR Version 3.1
Appendix A: New Call Interfaces and Data Types
This Appendix describes the new call interfaces and data types that
have been added at Version 3.1. These include the clip list calls.
New Call Interfaces and Data Types A-1
3D GMR Version 3.1
GMR_$SET_USER_CLIP_LIST
Defines an application-specified window visibility list.
FORMAT
gmr_$set_user_clip_list( window_list, window_cnt, status )
INPUT PARAMETERS
window_list
This is the list of visibility rectangles. This parameter is an
array of values in UNIV gmr_$window_list_t format. Each array element
consists of four 2-byte integer values.
window_cnt
The number of rectangles in window_list. This is a 4-byte integer.
OUTPUT PARAMETERS
status
Completion status, in STATUS_$T format. This procedure may return
a non-zero status for any of the following conditions:
o gmr_$clip_list_too_long : The value of window_cnt is greater
than the constant gmr_$max_clip_list_len. No action is taken
when this condition occurs.
USAGE
This routine accepts, in GPR bitmap coordinates, a list of clipping
windows specified by the caller. At viewport refresh time, this list
of clipping windows is intersected or merged with the internally
derived viewport visibility list as determined by such viewport
attributes as priority and transparency.
Note that setting window_cnt = 0 effectively disables the
application-specified window visibility list.
See also GMR_$INQ_USER_CLIP_LIST
A-2 New Call Interfaces and Data Types
3D GMR Version 3.1
GMR_$INQ_USER_CLIP_LIST
Inquires the application-specified window visibility list.
FORMAT
gmr_$inq_user_clip_list( window_list, max_window_cnt, window_cnt, status )
INPUT PARAMETERS
max_window_cnt
Maximum number of rectangles in window_list. This is a 4-byte integer.
OUTPUT PARAMETERS
window_list
This is the list of visibility rectangles. This parameter is an
array of values in UNIV gmr_$window_list_t format. Each array element
consists of four 2-byte integer values.
window_cnt
The number of rectangles in window_list. This is a 4-byte integer.
status
Completion status, in STATUS_$T format.
USAGE
This is the complementary inquiry routine to GMR_$SET_USER_CLIP_LIST.
Returns the list of user-specified clipping windows in GPR bitmap
coordinate space.
If max_window_cnt > gmr_$max_clip_list_len then values will be
returned in window_list but only up to and including
gmr_$max_clip_list_len -- the rest are disregarded.
New Call Interfaces and Data Types A-3
3D GMR Version 3.1
GMR_$VIEWPORT_INQ_CLIP_LIST
Inquires internally-derived viewport visibility list for a viewport.
FORMAT
gmr_$viewport_inq_clip_list( viewport_id, window_list, max_window_cnt,
window_cnt, status )
INPUT PARAMETERS
viewport_id
The number of the viewport, in gmr_$viewport_id_t format. This parameter
is a 2-byte integer.
max_window_cnt
Maximum number of rectangles in window_list. This is a 4-byte integer.
OUTPUT PARAMETERS
window_list
This is the list of visibility rectangles. This parameter is an
array of values in UNIV gmr_$window_list_t format. Each array element
consists of four 2-byte integer values.
window_cnt
The number of rectangles in window_list. This is a 4-byte integer.
status
Completion status, in STATUS_$T format. This procedure may return
a non-zero status for any of the following conditions:
o gmr_$not_initialized
o gmr_$viewport_id_invalid
o gmr_$viewport_doesnt_exist
USAGE
Returns in the form of a window clip list, the internally-
derived viewport visibility list in GPR bitmap coordinate
space.
A-4 New Call Interfaces and Data Types