Device Guide

The architecture of HOOPS Visualize is such that there is a common body of code which accepts application directives through the Visualize API and constructs a graphics database. This code is considered common because it is virtually the same on all platforms. In addition to this common code, there is some platform specific code that handles the details of running HOOPS Visualize on a particular platform. Of particular interest in the platform specific category are the Visualize device drivers.

Each HOOPS library comes compiled with the drivers necessary for the particular platform. Drivers that are inappropriate for a particular platform are not available at runtime. A mapping of the appropriate drivers to platforms is as follows:

Driver	Windows	Linux	Mac OS X
CGM3
DX11
HPGL2
Image
MSW
OpenGL2
OpenGL2_Mesa
PostScript
PDF
Printf
Qt
Quartz
X11

Legend

	Driver supported
	Driver unsupported
	Driver deprecated

For the latest information regarding GPU support, visit the HOOPS Developer Zone.

3D Drivers

The following is a list of 3D drivers that can be used by HOOPS Visualize. While specific 3D drivers can be selected, we recommend that developers use the Automatic Driver capability covered below.

DirectX11 Driver

The DirectX 11 driver is a 3D shader-based driver which can be selected using the driver path “/driver/dx11”. For full functionality, the driver requires a GPU that supports DirectX 10.0 or later.

In order to use the DX11 driver, you must ensure that the dx11.hdi file is included in your application’s directory or the runtime PATH. The HDI is located in the /bin/<platform> directory of your HOOPS installation.

If you explicitly use DX11, or if the choice of ‘3ddriver’ results in automatic selection of the DX11 driver, you can also instruct HOOPS/3DGS to perform software-only DirectX rendering by setting the ‘force software’ bit. Even if the hardware is pre-DX11, the DX11 driver will still be able to automatically fall back to software DirectX. This allows you to offer a ‘force software’ mode to your end-users, thereby enabling them to workaround possible lower-level GPU issues.

Debug Options

“debug = 0x01000000” disables the 3D hardware pipeline and engages software DirectX. This can be set by calling Set_Rendering_Options("debug = 0x01000000").

Runtime requirements: In order to use the DirectX11 driver, the d3dcompiler DLL must be made available in the execution environment of the target machine. We distribute this file with the Visualize package. If you are building with Visual Studio 2015 (and using the Windows 8.1 SDK) you need to include the file d3dcompiler_47.dll.

Limitations for Order-Independent Transparency

Intel GPUs performed poorly when dealing with many pixels - for example, resizing window to full screen. Hence, we disabled the DX11 pixel order-independent transparency algorithm for Intel cards.

Radeon cards appear to show some incorrect pixels, which has a “snow” pixel like effect (seemingly random pixels do not appear to be blended correctly).

DX11 Hardware-Accelerated Offscreen Rendering

The DX11 driver supports hardware-accelerated rendering to an offscreen HOOPS Image. This is typically preferable to using the software-based, platform-independent HOOPS Image driver, since use of the native 3D driver will also produce a result that matches its 3d on-screen rendering. More complex HOOPS usage scenarios may also depend on the hardware-accelerated performance of the offscreen rendering.

The HOOPS driver-instance setup is similar to the overall Image driver setup, where the ‘key’ of the HOOPS image primitive is passed in as the “use window id” Driver_Option with the “image key” modifier. Please review the Image Driver usage first.

The program called ogl_image.c located in /demo/common/standard provides an OpenGL-specific example of how to render a HOOPS scene to a HOOPS Image primitive using a 3D hardware-accelerated driver. Note that in the example, all occurrences of the ‘opengl’ string would be replaced with DX11 in order to use the DX11 driver instead.

OpenGL2 Driver

The OpenGL2 driver is a 3D shader-based driver that requires the host platform to support OpenGL 2.0+, and can be selected using the driver path “/driver/opengl2”. The driver name “opengl” will use the OpenGL2 driver.

OpenGL2 Hardware-Accelerated Offscreen Rendering

The OpenGL2 driver supports hardware-accelerated rendering to an offscreen HOOPS image. This is typically preferable to using the software-based, platform-independent HOOPS Image Driver, since use of the native 3d driver will also produce a result that matches its 3d on-screen rendering. More complex HOOPS usage scenarios may also depend on the hardware-accelerated performance of the offscreen rendering.

The HOOPS driver-instance setup is similar to the overall Image Driver setup, where the ‘key’ of the HOOPS Image primitive is passed in as the ‘use window id’ Driver_Option with the “image key” modifier. Please review the Image Driver usage first.

The program called ogl_image.c located in /demo/common/standard provides an OpenGL-specific example of how to render a HOOPS scene to a HOOPS Image primitive using a 3D hardware-accelerated driver. Note that in the example, all occurrences of the ‘opengl’ string would be replaced with ‘opengl2’ in order to use the ‘opengl2’ driver instead.

Custom Shader Code

HC_Define_Shader can be used to inject custom code into the normal shader execution at either the geometry or pixel stages. The code must be GLSL compliant, though it is both possible and practical to write shader code that will cross compile to both hlsl (for direct3d) and glsl (for opengl2).

Double-Precision Hardware Acceleration

The double-precision rendering logic takes advantage hardware acceleration when available. This results in greatly improved rendering performance for double-precision primitives. Any OpenGL 4.1 capable graphics card or any card supporting both GL_ARB_gpu_shader_fp64 and GL_ARB_vertex_attrib_64bit extensions (such as Intel HD 4000) should work on both Windows and Linux. OS X is not supported.

OpenGL2 Known Restrictions

This driver is also not compatible with graphics cards that support OpenGL 1.5 or older.

OpenGL2 Mesa Driver

The OpenGL2_Mesa driver is a software driver interface. This driver is functionally equivalent to our other shader drivers, however, its performance is reduced since it doesn’t make use of the GPU. It’s meant to provide a fallback driver on a system where no other hardware driver is available.

Please note that on Windows 10 systems, Microsoft provides a DirectX11 software fallback in case there is no GPU available in the execution environment, so this driver is normally only useful for other operating systems. On Linux, for example, it would be useful if the user doesn’t have a GPU and is unable to install a Mesa driver on the system.

The OpenGL2_Mesa driver is provided as a separate DLL, and is supported on Windows and Linux systems only. We also include a 32-bit Mesa driver binary for Windows (but not for Linux). The relevant files are named as follows:

OS	Driver Filename
Windows	opengl2_mesa.hdi
Linux	libopengl2_mesahdi.so

In addition to the driver file itself, there’s another dependency you must include. This is named libHGL.so on Linux and hopengl32.dll on Windows. To use the Mesa driver, these files need to be in the application’s path (or LD_LIBRARY_PATH) at runtime.

Print and 2D-Drivers

CGM3 Driver

CGM3 is a hardcopy driver similar to the old CGM driver except that it supports the CGM3 standard. This includes support for color-interpolated interiors. In addition, the CGM3 driver only supports true color, whereas the older CGM driver defaulted to emulating a mapped mode. We recommend that you use the CGM3 driver as the CGM driver is no longer supported.

CGM3 - Gaining Access

To set up your machine so that the CGM3 driver is the default HOOPS driver you must define the environment variable or registry value HOOPS_PICTURE as:

HOOPS_PICTURE = cgm3/output.txt

Line Styles and Widths

The CGM3 driver supports wide lines, which means that if there are unlit, non-default line or edge weights in the segment hierarchy, they will appear as weighted lines in the CGM3 output. Also, if the join and/or end styles are either of “(”, “[” or “|”, then these will also be natively supported within the output. All other end/join styles will be represented in the output by triangles. Finally, if any of the line/edge patterns “-..”, “-.”, “.” or “- -” are used, then these lines will be mapped to CGM3 lines with the equivalent CGM3 line pattern. All other patterns supported by 3DGS, including user defined patterns, will be represented in CGM output as a series of line, polygons, dots or rasters.

Font Table

The CGM3 driver’s internal font table can be overridden by setting the ‘font table’ driver option. The font table set in the driver options is a one based array of comma separated font names. For example: “font table = (font1, font2, script, gothic, symbol, fontN)”. To manually specify the font index for a segment, define an I.M. draw segment callback that makes a call to HIC_Set_Text_Font_Index(...). Setting the index to two would cause the CGM3 driver to use ‘font2’ in the example font table.

HPGL2 Driver

HPGL2 Supported Systems

The HOOPS Visualize HPGL2 driver is a hardcopy driver which works on various host computers running Windows or Linux. The driver supports devices with support the HP-GL/2 and HP RTL languages with merged vector and raster data. The primary target device for the driver is a color ink-jet printers and plotters, though other devices that support these languages should run as well.

Basic Steps

The basic steps to plotting with HOOPS include:

Set the HOOPS picture
Determine the plotter area size
Set the HOOPS options to set the image area (and any other options desired)

Each of these steps is covered in more detail in the remaining sections of this section. The section ends with a section on known restrictions.

Setting HOOPS Picture

The HOOPS HPGL2 driver writes HPGL2 graphics commands to a user specified file on all systems. On some systems, it can write these same commands directly to the plotter if the device name is specified instead of a file name.There are two ways to use the HPGL2 driver from HOOPS. One method is to set the HOOPS_PICTURE variable, and the other is to set the HOOPS_HARDCOPY variable.

Using HOOPS_PICTURE

The simplest method is to direct the graphics output to the plotting device in place of the video screen. The advantage of this method is that the software being used does not have to be modified or recompiled. The disadvantage is that the plotter cannot respond to request for keyboard or mouse input.

To set your computer up so that the HPGL2 driver is the default HOOPS driver for your graphics programs, you define the environment variable HOOPS_PICTURE to be “hpgl2/<plotfile-name>”.

For example:

set HOOPS_PICTURE=hpgl2/hoops.hp

Where hoops.hp is the actual name of the file that captures the HPGL2 output. Once this definition is made, HOOPS programs that refer to the HOOPS “?Picture” segment will write a new page to a file named “hoops.hp” each time they update the display. Any valid file name can be substituted for “hoops.hp”; however, if the name contains HOOPS special characters, you should add extra quote marks as described in the system notes. For example, to send the output to a file in another directory on a UNIX machine, you might type:

setenv HOOPS_PICTURE "hpgl2/'/usr/usha/hoops.hp'"

The extra quotes keep the file system “/” marks from being interpreted as HOOPS segment delimiters. Either single or double quotes will work.

Using HOOPS_HARDCOPY

The other method of obtaining plotter output lets you display your graphics on the screen and also send the same picture to an HPGL2 file; however, to do this you have to add some more code. First specify HOOPS_PICTURE as you would normally, and then define another environment variable, HOOPS_HARDCOPY, as hpgl2/hoops.hp. From within your program use the segment alias ?Hardcopy to refer to the plotter, and of course the segment alias ?Picture to refer to the screen device. To send a single snapshot of your ?Picture scene to an HPGL2 file, a typical code sequence would be:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Update_Display ();
Close_Segment ();
Delete_Segment ("?Hardcopy");

Note that HOOPS will open a new file each time this sequence is called. To obtain an HPGL2 file with each image on a new page, set things up as:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Set_Visibility ("off");
Close_Segment ();

To take a snapshot as your program is running along, do:

Open_Segment ("?Hardcopy");
Set_Visibility ("on");
Close_Segment ();

Update_Display ();
Open_Segment ("?Hardcopy");
Set_Visibility ("off");
Close_Segment ();

Finally, delete “?Hardcopy” when done to properly close the file:

Delete_Segment ("?Hardcopy");

Using the ?Hardcopy variable in the manner above is equivalent to using ?driver/hpgl2/hoops.hp as the segment name. To write to multiple hardcopy files, use segment names such as ?driver/hpgl2/hoops1.hp, ?driver/hpgl2/hoops2.hp, etc.

Please consult your system documentation on how to send a file to a device. On VMS, you might use the copy command. For example, to send an HPGL2 file called “fred.hp” to the plotter at TXA2:, you would type:

$copy fred.hp TXA2:

Determining the Maximum Printable Area

All HPGL2-compatible plotters use built-in plotter points P1 and P2. P1 is located in the lower left corner of the plotting area, and P2 is in the upper right. The driver uses the distance between these points to specify the maximum printable area to which HOOPS can print. The location of these points depends on the device and the size of the paper which is loaded into the device.

To determine the horizontal and vertical distances between these points, consult your device’s user manual, which often lists the maximum printable area for different paper sizes.

A second method of determining the plotting area size for a given paper size is to run any HOOPS program (with window frame on) and then measure the size of the borders (in centimeters). Use the locater transform option described above to specify a maximum printable area that is obviously larger than the paper you have loaded into the device. Specify no (0) margins. For example, the following will work for paper sizes that are less than 100 centimeters in both directions:

Set_Driver_Options("locater transform = (100, 0, 0, 100, 0, 0)");

Run the program and transfer the output file to your device. Two edges of the border will plot and be clipped by the device at the edges of the maximum printable area. Measure the size of the border lines (in centimeters) and you will then have the width and height to use in the locater transform or physical size options for future plots.

Setting HOOPS Driver Options

Use HOOPS driver options to specify printed image and device characteristics. Some options are required; others help customize the print process. Available options are listed below. Include one or more commands such as the following in your program, where “options” is replaced by one of the options listed below:

Set_Driver_Options( "option");

For example, use either the “locater transform” option or the “physical size” option to specify paper size, direction of paper feed, either short-edge feed (SEF) or long-edge feed (LEF), and specific location of the image print area.

“locater transform = (width, left, right, height, bottom, top)”

Specify all dimensions in centimeters.

The width and height are the extents of the “maximum printable area” on the paper. Each device has a specific maximum printable area set in the device hardware. Usually, these also depend on the physical size of the paper that is loaded in the device. In the terms of HPGL2 language jargon, the width and height are the X and Y distances between the HPGL2 scaling points P1 and P2 that define the hard clip limits of the device. Obtain the printable area dimensions from your device documentation, or use the procedure described below for determining the maximum printable area. The width is the dimension along the leading edge of the paper as it exits the device. If the width is less than the height, you are feeding the paper as short-edge feed (SEF). If the width is greater than the height, you are feeding the paper as long-edge feed (LEF).

Left, right, bottom and top are the margins between the “maximum printable area” on the paper and the actual “print area” that you want to use for the image. Note that the margins are measured not from the physical edge of the paper, but from the edge of the “maximum printable area”. For all practical cases, you must set either the “locater transform” option or the “physical size” option described below. The default locater transform for the HPGL2 driver is (1,0,0,1,0,0).

For example, assume the following:

Paper sheet size : 24.00 x 36.00 inches = 60.96 x 91.44 cm
Border on all sides from edge of paper to maximum printable area: 0.20 inches = 0.50 cm (from device’s specifications)
Desired actual print area: 22.00 x 34.00 inches = 55.88 x 86.36 cm
Centered on page
Feed direction: Long-edge feed

Results:

Maximum printable area (sheet size less border from edge to maximum printable area):

(24.00 - (2 x 0.20)) x (36.00 - (2 x 0.20) inches = (60.96 - (2 x 0.50) x (91.44 - (2 x 0.50)) cm

or:

23.60 x 35.60 inches = 59.96 x 90.44 cm

Long-edge feed, so width > height: width = 90.44 cm, height = 59.96 cm.

Margins, from “maximum printable area” to actual “print area”:

left + right = (90.44 cm - 86.36 cm) = 4.08 cm.
left = right = 4.08 cm / 2 = 2.04 cm.
top + bottom = (59.96 cm - 55.88 cm) = 4.08 cm
top = bottom = 4.08 cm / 2 = 2.04 cm

HOOPS Driver option: “locater transform = (90.44, 2.04, 2.04, 59.96, 2.04, 2.04)”

“physical size = (width, height)”

The width and height are the extents in centimeters of the “maximum printable area” as described above under the “locater transform” option.

This option will supercede the “locater transform” option, so do not use this option if you use the “locater transform” option. This option only works with for short-edge feed (SEF), width < height. Use the “locater transform” option instead for long-edge feed (LEF) situations.

Left, right, bottom and top margins will be 0. Use the “locater transform” option instead for non-zero margins. For all practical cases, you must set either the “locater transform” option or the “physical size” option. Without either, the default maximum printable area for the HPGL2 driver is 1 cm x 1 cm.

“[no] landscape orientation”

Use this option to set the orientation of the image within the actual “print area” inside the margins, (i.e. not the “maximum printable area”).

With “landscape orientation” HOOPS will place the bottom of the image along the larger dimension of the actual “print area”. The larger dimension of the “print area” is usually along the larger outside edge of the paper. But it might be the along the smaller outside edge of the paper if some of the margins are large.

In the same way, with “no landscape orientation”, HOOPS will place the bottom of the image along the smaller dimension of the actual “print area”. The smaller dimension of the “print area” is usually along the smaller outside edge of the paper. But it might be along the larger outside edge of the paper if some of the margins are large.

“hardcopy resolution = dpi”

Use this option to set the pixel resolution that HOOPS will use to send data to the device. “dpi” is the resolution in dots per inch. For best performance specify the dpi that is the device’s hardware default, or a sub-multiple of the device’s default. Typical dpi values for ink-jet devices are 300 or 600 dots per inch. Lower values provide a less precise image, but produce smaller data files, especially when handling raster images. The HOOPS default is: “hardcopy resolution = 75”.

Most HPGL2 devices can print raster images only at certain fixed resolutions. You must set hardcopy resolution to one of the allowable resolutions for your device. If you do not, then raster images will not print at the correct size.

NOTE: With the HPGL2 driver, hardcopy resolution affects not only raster but also vector plotting. Therefore, if a low resolution is set (70dpi, for example), vector lines may appear tesselated rather than smooth. It is best to set a slightly higher resolution, around 300dpi.

“output format = "INITinitialization stringINIT TERMtermination stringTERM"”

The HPGL2 driver uses the “output format” option to specify characters strings that it sends to the device at the start of the print data (initialization string) and at the end of the print data (termination string). The delimiter required at the start and end of the initialization string is the four uppercase characters “INIT”. The delimiter required at the start and end of the termination string is the four uppercase characters “TERM”.

If you include the 3 uppercase characters “ESC” in either of these strings, the driver will replace the ESC with the single “escape” character (’033’ = ‘1Bh’).

You can specify none, one or both character strings. The recommend minimum for both character strings for most devices is the Reset command “ESCE” which the driver will send as a default if the string is not specified. In other words, if not specified, the default output format option is:

output format = "INITESCEINIT TERMESCETERM"

“write mask = value”

Use this option to set certain plot settings. Replace “value” with the sum of the numbers listed below for settings that you want to enable.

1 = Do not print raster image data. Certain devices are unable to plot mixed vector and raster data. Use this setting to plot only vector data.

2 = Use Direct RGB (24 bit) color system instead of the drivers default color system. The default color system is a 256-color indexed system. The driver’s default is: “write mask = 0”

Notes on HOOPS Driver Options

Standard HOOPS driver options for color consolidation, force black-and-white, and subscreen function are as specified in the HOOPS VisualizeReference Manual.
The HPGL2 driver is not considered part of a window management system. As such, standard HOOPS driver options for backing store, border, control area, subscreen moving, subscreen resizing, subscreen stretching, and use window ID do not apply.
Keyboard and mouse inputs do not apply. As such, standard HOOPS driver options for disable input, update interrupts, special events, and selection proximity are moot. (The update interrupts option may be used if specifically enabled so that queueing special events can prematurely terminate writing of HPGL2 output files.)
Double-buffering does not apply.

Rendering Options

There is one rendering option that should be set when creating HPGL2 plots with the painters hidden surface removal algorithm. In this case, Painter’s Panelling should be disabled with:

Set_Rendering_Options( "debug = 8");

HPGL2 Heuristics

Hidden line removed scenes are supported through the rendering option ‘hidden surface removal algorithm = hidden line’.
Standard HOOPS heuristics for backplane cull, clipping, concave polygons, hidden surfaces, intersecting polygons, polygon handedness, and transformations function as specified in the HOOPS Visualize Reference Manual</a>.
The incremental updates, partial erase, quick moves, and related selection limit heuristics do not apply.

HPGL2 Known Restrictions

Plotting to monochrome devices is not supported. The device must support 256 HPGL2 pens.
The polygon pattern for “[] []” (checker board) is not exactly as described in the Reference Manual but is distinct from all other polygon patterns.
It is possible to create plot files that are too complicated or too large for a particular device, especially if your image includes entities that must be rendered as raster image data. To reduce file size and complexity:
1. Use the default color system (see write mask option above)
2. Reduce the hardcopy resolution value (see hardcopy resolution option above)
3. Reduce the printable area (see the locater transform and physical size options above).
4. Use the HOOPS rendering option: software z-buffer.

Image Driver

Image Driver Supported Systems

The HOOPS Image driver has been tested on all supported platforms. An example of using the driver can be found in the StdTEST demo program.

Image Driver - Gaining Access

The Image driver draws the contents of the scene directly into a HOOPS image. It operates as a sort of “virtual frame buffer.” The image driver is useful for capturing output that would normally go to a display device. You might use the resulting image to store a “frame” of an animation for later playback, or save it into a file for importing into a paint-program. Use of the image driver is not difficult, but it can be daunting to the novice HOOPS user since it requires a roundabout method of generating a picture.

To use the Image driver, you must first create an image, using Insert_Image. It doesn’t matter where you insert the image. If you’d like to see the image after the image driver is through drawing, you might want to insert it into a segment controlled by a display driver. If you’d prefer to keep the image invisible, you can insert it anywhere else. Pass the key of your image into the image driver via the “use window ID” driver option. Here’s a step by step method (in C) you can use to get HOOPS to render into an image:

Create a large enough array to hold your image data. If you want the image to be the size of your screen, for instance, then use Show_Device_Info to get the number of pixels on the screen. Compute_Coordinates might also be useful to get the size of a HOOPS subwindow.
Insert the image into a segment. It doesn’t matter where you insert the image, but for the sake of argument, we’ll insert it into a place that will not display the final image. The image key is the most important side effect:
```
HC_Open_Segment ("/null");
key = HC_Insert_Image (...); /* keep the key! */
HC_Close_Segment ();
```

Now open up a segment under the image driver:

HC_Open_Segment ("?driver/image/my_segment");

Now you must tell the image driver where to draw. That is, you must point it to the image. You do this by setting the “use window ID” driver option. In this case, that option is functioning as “use image key”. Hereafter, all graphics will go to the image:
```
/* The kto0xa() function puts "0x" in front of the pointer if the system requires it.
If you have HOOPS/MVO installed, you can use the H_EXtrA_POINTER_FORMAT
macro.*/

sprintf (buf, "use window id = %s", kto0xa(key));
HC_Set_Driver_Options (buf);
```
Next, put some geometry under the segment. Usually, you’ll want to do something like this:
```
HC_Include_Segment ("?picture");
```
Don’t forget to close the segment:
```
HC_Close_Segment ();
```
Render the picture:
```
HC_Update_Display ();
```
To show the contents of the image, you’d use:
```
HC_Show_Image (key, ...);
```
When you’re all done, you can stop the image driver from rendering into that image on each update by either setting the driver option to another image, or by deleting the image driver segment:
```
HC_Delete_Segment ("?driver/image/my_segment");
```

Rendering to an Off-Screen Image with 3D-Hardware Acceleration

The HOOPS DX11 and OpenGL2 drivers also support rendering to an offscreen image, which provides WYSIWYG results with the 3d driver’s on-screen display results, and perform hardware-accelerated rendering to the offscreen image. For usage details, refer to the documention for those driver.

Image Driver Options

Standard HOOPS driver options for color consolidation, force black-and-white, gamma correction, light scaling, physical size, and subscreen function as specified in the HOOPS/3DGS Reference Manual.
The Image driver is not considered part of a window management system with a display device. As such, standard HOOPS driver options for backing store, border, control area, double buffering, first color, fixed colors, landscape orientation, number of colors, output format, pen speed, subscreen moving, subscreen resizing, subscreen stretching, title, use colormap ID, and write mask do not apply.
The use window ID driver option is used to specify the key of the image container.
Keyboard and mouse inputs do not apply. As such, standard HOOPS driver options for disable input, locater transform, update interrupts, special events, and selection proximity are typically moot. (The update interrupts option may be used if specifically enabled so that queuing special events can prematurely terminate writing of Image output).

Image Driver Heuristics

Standard HOOPS heuristics for backplane cull, clipping, concave polygons, hidden surfaces, intersecting polygons, polygon handedness, and transformations function as specified in the HOOPS/3DGS Reference Manual.
The incremental updates, partial erase, quick moves, and related selection limit heuristics do not apply.

Image Driver Known Restrictions

The images generated by the Image driver are full-color images. In other words, the color values are returned in an RGB format. Thus, it is considered an error to pass the Image driver the key of a color-mapped image. In addition, there is no provision for having the driver return color map indexes for a particular display device, since the Image driver is a device independent driver. This same rationale applies to pixels.

The image generated by the Image driver can be of any size, M by N pixels, regardless of the size of the display device being used; however, if the image will be displayed on a display device (such as for a frame of animation), it is advisable that the number of pixels match those of the display device if the image is intended to fill the entire drawing area.

Bit-mapped fonts are not available to the image driver, and so all text will be rendered using HOOPS internal stroked fonts or user-defined fonts.

Microsoft Windows Driver

MSW Driver Supported Systems

The Microsoft Windows (MSW) driver is a 2D and hardcopy driver supported on all Windows GDI-compatible devices.

MSW Driver - Gaining Access

To modify your HOOPS_PICTURE for the Microsoft Windows driver, you need to set two registry keys.

Special Performance Notes

To render the database to the screen, HOOPS enters a tight loop of attribute setting and machine native device drawing. In other words, HOOPS translates the generic drawing commands used to construct the database into device specific drawing primitives. In the case of the Microsoft Windows driver, the primitives are GDI. The GDI primitives used to render a scene have a profound effect on drawing performance.

Although the Microsoft Windows driver is a generic driver that can correctly render any HOOPS scene, being aware that the HOOPS rendering options, driver options, and heuristics that influence the mapping of a HOOPS database to GDI primitives are key to optimizing performance on Windows platforms.

Per primitive drawing is the default. In this case HOOPS maps a primitive inserted into its database on an almost one to one basis for a GDI primitive. This type of rendering is typically the slowest. It occurs when the HOOPS rendering option hidden surface removal algorithm is set to hardware (and none is present), painters, z sort only, priority, or none (i.e. the ‘hidden surfaces’ heuristic is set to off). Despite its slower speed, this drawing method is sometimes desirable for an application, particularly in wireframe mode, when user interaction based on small modifications to the screen are critical. (double-buffering would probably be used in this case)
Drawing using a BLock transfer (BLT) of pixels is typically faster than per primitive drawing. This is definitely the preferred method for rendering shaded, complex scenes on Windows. HOOPS creates a buffer to contain the image of a scene and then that buffer is copied into video memory and BLTed to the screen. This method of drawing is used when the hidden surfaces heuristic is on and the hidden surface removal algorithm driver option is set to software Z buffer (These settings should be used for 3D scenes.) For cases where the scene is 2D or hidden surfaces are off, rendering reverts to per primitive drawing even if the software Z buffer is set. For applications that want to avoid per primitive drawing at all times, the ‘technology’ Rendering_Option should be set to software frame buffer. The software Z buffer and the software frame buffer rendering options are an effective combination. (When using BLT drawing, the double buffering driver option is not recommended since the drawing is already being buffered).

Examples

2D scene, or 3d wireframe scene; method 1 (normal, per primitive drawing):

HC_Open_Segment("?driver/msw/window0");
/* no need to perform hidden surface removal */
HC_Set_Heuristics("no hidden surfaces");
/* enable double-buffering */
HC_Set_Driver_Options("double-buffering");
HC_Set_Visibilty("faces = off");
/* turn off visibility of lights and faces */
HC_Close_Segment();

2D scene, or 3d wireframe scene; method 2 (use software frame buffer):

HC_Open_Segment("?driver/msw/window0");
/* no need to perform hidden surface removal */
HC_Set_Heuristics("no hidden surfaces");
/* render to offscreen HOOPS frame buffer, blit to screen*/
HC_Set_Rendering_Options("technology =sfb");
HC_Set_Visibilty("faces = off");
/* turn off visibility of lights and faces */
HC_Close_Segment();

3D scene with surfaces visible, or with lighting, texture mapping, etc… enabled:

HC_Open_Segment("?driver/msw/window0");
HC_Set_Heuristics("hidden surfaces");
/* we need to perform a hidden surface removal */
HC_Set_Rendering_Options("hsra=szb");
/* use software z-buffer for hidden surface removal    */
HC_Set_Visibilty("faces = on, lights = on");
/* turn on visibility of lights and faces */
HC_Close_Segment();

In general, HOOPS applications are abstracted from the details of drawing at the driver level. This is still the case on Windows platforms in that high level HOOPS options are set in place of driver directives that force the driver to execute a fast path; however, to obtain optimal performance it is wise to consider a scene in terms of its rendering characteristics and set HOOPS directives accordingly.

Important MFC/MDI/Application Integration Notes

When using HOOPS in a ‘use window id’ mode, there are MFC/MDI integration guidelines to follow to ensure that HOOPS takes full advantage of the native Windows platform functionality.

The primary reference for such integration issues is the HOOPS/MFC Classes included with the HOOPS distribution. These classes contain HOOPS-specific implementations for all the primary classes of an MDI application, including CView, CDocument, and CMDIFrameWnd, and encapsulate the following platform-specific information. These classes may be used as a starting point for creating implementations which are specific to your application’s needs.

Text Font Names in MSW

For HOOPS on Microsoft Windows with the MSW driver, font names consist of three parts: <basename> <type> <format> where:

<basename> is one of the standard font names found on Windows, e.g. ARIAL.
<type> is one of two designators: GDI or DEVICE.
<format> is one of two designators: RASTER or VECTOR.

This three part identifier allows an application to precisely specify a desired font, i.e., ARIAL-GDI-RASTER, ARIAL-GDI-VECTOR, ARIAL-DEVICE-RASTER, or ARIAL-DEVICE-VECTOR. The need for this level of precision is demonstrated by the following problem.

On an HPGL/2 plotter (the C2848 to be specific), the printer returns three different fonts named ARIAL - a GDI based font and two device based fonts (one vector and one raster). Each of these fonts has different metrics as well as capabilities (e.g. rotation, scaling). These metrics and capabilities affect how HOOPS positions and draws text for an application. Thus it is essential that the relationship between a font and its associated data be maintained. The only way to do this is to precisely identify the fonts. The name “Arial,Helvetica” alone is insufficient.

Keyboard Handling

The status codes for Show_Button_Source include the following bits:

# define HT_SHIFT 0x00000100
# define HT_CONtrOL 0x00000200
# define HT_NUM_LOCK 0x00000400
# define HT_ALT 0x00000800
# define HT_CAPS_LOCK 0x00001000
# define HT_SCROLL_LOCK 0x00002000
# define HT_LEFT_SHIFT 0x00004000
# define HT_RIGHT_SHIFT 0x00008000
# define HT_RIGHT_CONtrOL 0x00010000
# define HT_LEFT_CONtrOL 0x00020000
# define HT_RIGHT_ALT 0x00040000
# define HT_LEFT_ALT 0x00080000

Note that a Right shift key will produce a 0x00010100 code allowing you to test for shift or more specifically for right shift.

MSW Driver Options

Since Microsoft Windows is a windowing system, the driver options “subscreen”, “subscreen moving”, “subscreen resizing”, and “subscreen stretching” may be of interest to you. Please see the Set_Driver_Options pages of the HOOPS/3DGS Reference Manual for details.

By default, the HOOPS Windows driver creates a window with a border and control area. The Windows outer window must be of this type. If your program creates a child window, it is possible to remove the border and / or control area. This is accomplished with the no border and no control area commands via Set_Driver_Options.

In addition to specifying options internal to your program through Set_Driver_Options, you can set up driver options externally to your program(s) by defining the profile string HOOPS_PICTURE_OPTIONS. For example:

HOOPS_PICTURE_OPTIONS=subscreen=(0,1,0,1), title='Beavis'

makes the default window appear in the upper right portion of the screen with the title “Beavis” appearing in the control area.

To use the driver option “use window ID”, you will need to create the window yourself. You then call Set_Driver_Options specifying “use window id=dddd” where “dddd” is the decimal value of the window handle returned from the call to CreateWindow (or it can be accessed in OnInitialUpdate in the MFC case). Creating the window yourself provides you with the greatest amount of control over Window management while still having HOOPS draw within your window. The MSW driver assumes that the window has been created and that the handle is valid at all times. The preferred method of creating windows is to use the CS_OWNDC style, but the driver will handle windows without this attribute although rendering will be slower.

The “use window ID2” driver option has three special and distinct purposes:

Copying to the clipboard. In this case the use window ID2 is specified as the value of the handle to the device context (HDC) in which HOOPS is to draw. HOOPS needs this handle to know where to send the GDI metafile commands. The use window ID2 option is used for the clipboard, since the regular use window ID is already being used to query the system for information to draw. Please see the “Copy to Clipboard” notes covered earlier in this section for details of this usage.
Copying to the printer. In this case use window ID2 is specified as the handle of the HDC where HOOPS is to draw the printed output. This allows HOOPS to query the device context the application has set up (probably through the standard windows printer setup call) to get orientation, resolution, paper tray, etc. Please see the Print/Print-Preview notes covered earlier in this section for details of this usage.

MSW Debug Driver Options

The following debug options are available by setting bits of the debug driver option value:

Debug_FORCE_FULL_COLOR is used to cause HOOPS windows driver to output commands as if the device is full color - dithering will not occur - the device will appear to have no palette and 16777216 colors. Windows will then map the 16777216 colors to the 16 windows colors. This will look very bad on a VGA device and is mainly intended as a workaround for applicaton-specific metafile/printing problems which customers have seen:
```
HOOPS_PICTURE_OPTIONS = debug=16
```
NO_PRINTER_ESCAPES is used so that the user may send his own printer escape codes and provide his own error handling in use window ID programs:
```
HOOPS_PICTURE_OPTION = debug=32
```
Before version 7.0, NO_WINDOWS_HOOK was provided so that applications can tell HOOPS not to hook into the message queue for a window (meaning that the application must process ALL messages including expose and redraw, and call HC_Update_Display when it wants HOOPS to draw into the provided window). This debug option is now officially obsolete, though it will still function in legacy code. The proper way to disable WINDOWS_HOOK is to use the “disable input = all” driver option.
SWAP_MAPPED_COLORS causes the driver to switch the text and background colors on certain draw commands. This is done to compensate for inconsistent behavior in some windows device drivers (e.g. some TIGA boards):
```
HOOPS_PICTURE_OPTIONS = debug=256
```
DO_NOT_SOFTCLIP_METAFILES tells HOOPS not to use its soft clip logic for metafiles. This will cause certain elements of the image to exceed the expected boundaries on the clipboard image since windows MetaFiles that HOOPS will embed on the clipboard will not support clipping. Using the soft clipping logic can cause some edge object (e.g. markers whose center are off screen) not to be drawn. In either case no CLIP commands are placed in the metafile since Windows cannot handle them properly:
```
HOOPS_PICTURE_OPTIONS = debug=512
```
FAST_BLTSWING tells HOOPS to use a faster method for BLTing that improves speed at the expense of providing visual feedback. The driver ponders for a while, appearing to do nothing, then BLTs everything really fast at the end of the update cycle. This debug driver bit is NOT recommended for most users. In the unlikely event that you need to set it:
```
HOOPS_PICTURE_OPTIONS = debug=2048
```
NO_IDENTITY_PALETTE is only useful for those customers who supply their own palette to the HOOPS MSW driver:
```
HOOPS_PICTURE_OPTIONS = debug=8192
```
FAVOR_MEMORY_OVER_SPEED instructs the HOOPS MSW driver to avoid allocating blocks of memory used to BLT groups of pixels, and draw using alternative, albeit slower, methods for drawing. This option may be useful for memory constricted systems where time is NOT of the essence:
```
HOOPS_PICTURE_OPTIONS = debug=32768
```
NO_PAINT_ON_PALETTE_CHANGE tells the driver to avoid redrawing a scene on a palette change. This eliminates painful delays due to redrawing, but leaves background windows in a technicolor state:
```
HOOPS_PICTURE_OPTIONS = debug=65536
```
Debug_PRAINT_VECTOR_PATTERNS instructs HOOPS to use its own stroked face pattern logic. This results in much more discernable patterns, but may increase file size:
```
HOOPS_PICTURE_OPTIONS = debug = 0x100000
```
Debug_LINE_WEIGHT_WYSIWYG causes GDI hardcopy line weights to be similar to display weights:
```
HOOPS_PICTURE_OPTIONS = debug=0x00400000
```

MSW Driver Known Restrictions

The driver option “no subscreen moving” is not supported.
In non ‘use window ID’ programs, the following resizing behavior is exhibited. When the window manager is used to reduce the size of a window, HOOPS does not redraw its scene until the resize is complete. Thus, the scene is cropped until the resizing operation is complete. When the window manager is used to enlarge a window, the reverse occurs. During a resize, the window border and control area are redrawn by the window manager (appearing multiple times) until the resize is complete, at which time, HOOPS redraws its enlarged scene.
Due to an interaction problem between trueType fonts and GDI, the driver may revert quickmoved bit mapped text to a stoked font. (This restriction does not require any changes to your application. The MSW driver automatically handles the font change when necessary).

PDF Driver

PDF Driver - Gaining Access

There are two ways to use the PDF driver from HOOPS Visualize. The simplest is to replace the display with the PDF driver as the graphics output device. The advantage of this method is that the software being used does not have to be modified or recompiled.

To set your computer up in this way so that the PDF driver is the default HOOPS driver for your graphics programs, define the environment variable “HOOPS_PICTURE” to be “pdf/hoops.pdf.”

Please see the release notes for your particular operating system for details on how to define environment variables. Once this definition is made, Visualize programs that refer to the “?Picture” segment will write a new page to a file named “hoops.pdf” each time they update the display. Any valid file name can be substituted for “hoops.pdf”. If the name contains special characters, you should add extra quote marks as described in the system notes. For example, to send the output to a file in another directory on Windows, you might type:

set HOOPS_PICTURE=pdf/'c:\milt\hoops.pdf'

… on UNIX under csh, you might type:

setenv HOOPS_PICTURE \ "pdf/'/usr/milt/hoops.pdf'"

The extra quotes keep the special characters, if any, from being interpreted as Visualize segment delimiters. Either single or double quotes will work.A more useful arrangement lets you display your graphics on the screen, and also send the same picture to a PDF file. To do this, however, you have to add some more code.

First specify “HOOPS_PICTURE” as you would normally, then define “HOOPS_HARDCOPY” as “pdf/hoops.pdf” as above. This will define the segment alias name “?Hardcopy” when your program starts up.

Note that you can specify driver options for “?Hardcopy” from outside of the program by using the environment variable “HOOPS_HARDCOPY_OPTIONS.”

To send a single snapshot of your “?Picture” scene to a PDF file, a typical code sequence would be:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Close_Segment ();
Update_Display ();
Delete_Segment ("?Hardcopy");

Note that HOOPS will open a new file each time this sequence is called. On certain systems, opening a new file means the previous version is overwritten.

To obtain a PDF file containing several images (multiple sheets of paper) without the danger of overwriting, set things up as below:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Set_Visibility ("off");
Close_Segment ();

To take a snapshot as your program is running along, do:

Open_Segment ("?Hardcopy");
Set_Visibility ("on");
Close_Segment ();

Update_Display ();
Open_Segment ("?Hardcopy");
Set_Visibility ("off");
Close_Segment ();

Finally, delete “?Hardcopy” when done to properly close the file:

Delete_Segment ("?Hardcopy");

Note that you can also open the PDF driver explicitly with segment names like “?driver/pdf/hoops.pdf.”

PDF Driver Options

The “hardcopy resolution’’ option can be used to reduce the resolution of a rendered image, so that the amount of data/time need to render the image is reduced. This option is particularly useful when Visualize is sending raster information to the PDF file/device, as is the case when Gouraud/Phong shading, Visualize images, or any other Visualize settings triggering rasterization are present in the scene. (other examples include transparency, texture-mapped geometry, color interpolation and color index interpolation)
The “subscreen” option may be useful to restrict the size of the page to allow for margins.
The “landscape orientation” option will rotate the picture 90 before fitting it onto the page (this is on by default - use “no landscape orientation” to turn it off giving a “portrait” style image).

Text Font Names in PDF Driver

The built-in PDF text fonts are available. Currently, only the 13 “standard” PDF fonts are supported. The “explicit” names for Set_Text_Font purposes are as follows. The first row of fonts are those used as the roman, sans serif, and typewriter generic fonts, respectively:

Roman fonts	sans-serif fonts	Typewriter fonts
Times-Roman	Helevetica	Courier
Times-Bold	Helevetica-Bold	Courier-Bold
Times-Italic	Helevetica-Oblique	Courier-Oblique
Times-BoldItalic	*Helevetica-BoldOblique*	Courier-Bold Oblique

Since the PDF driver is most commonly run along with a screen driver, if you want to name a particular PDF font you will probably want to use the multiple-choice “name=(name1,name2,…)” style in your Set_Text_Font calls, so you can name both your PDF choice and your screen choice.

PostScript Driver

PostScript Drive - Gaining Access

There are two ways to use the PostScript driver from HOOPS Visualize. The simplest is to replace the computer screen with the laser printer as the graphics output device. The advantage of this method is that the software being used does not have to be modified or recompiled. The disadvantage is that the laser printer cannot respond to requests for keyboard or mouse input.To set your computer up in this way so that the PostScript driver is the default Visualize driver for your graphics programs, define the environment variable “HOOPS_PICTURE” to be “PostScript/hoops.ps.”

Please see the release notes for your particular operating system for details on how to define environment variables. Once this definition is made, Visualize programs that refer to the “?Picture” segment will write a new page to a file named hoops.ps each time they update the display.

Any valid file name can be substituted for “hoops.ps”. If the name contains special characters, you should add extra quote marks as described in the system notes. For example, to send the output to a file in another directory on Windows, you might type:

set HOOPS_PICTURE=PostScript/'c:\milt\hoops.ps'

…on UNIX under csh, you might type:

setenv HOOPS_PICTURE \ "PostScript/'/usr/milt/hoops.ps'"

The extra quotes keep the special characters, if any, from being interpreted as Visualize segment delimiters. Either single or double quotes will work.

A more useful arrangement lets you display your graphics on the screen, and also send the same picture to a PostScript file. To do this, however, you have to add some more code.

First specify “HOOPS_PICTURE” as you would normally, then define “HOOPS_HARDCOPY” as “PostScript/hoops.ps” as above. This will define the segment alias name “?Hardcopy” when your program starts up.

Note that you can specify driver options for “?Hardcopy” from outside of the program by using the environment variable “HOOPS_HARDCOPY_OPTIONS.”

To send a single snapshot of your “?Picture” scene to a PostScript file, a typical code sequence would be:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Close_Segment ();
Update_Display ();
Delete_Segment ("?Hardcopy");

Note that HOOPS Visualize will open a new file each time this sequence is called. To obtain a PostScript file containing several images (multiple sheets of paper) without the danger of overwriting, set things up as below:

Open_Segment ("?Hardcopy");
Include_Segment ("?Picture");
Set_Visibility ("off");
Close_Segment ();

To take a snapshot as your program is running along, do:

Open_Segment ("?Hardcopy");
Set_Visibility ("on");
Close_Segment ();

Update_Display ();

Open_Segment ("?Hardcopy");
Set_Visibility ("off");
Close_Segment ();

Finally, delete “?Hardcopy” when done to properly close the file:

Delete_Segment ("?Hardcopy");

Note that you can also open the PostScript driver explicitly with segment names like “?driver/PostScript/hoops.ps.”

PostScript Driver Options

The “hardcopy resolution’’ option can be used to reduce the resolution of a rendered image, so that the amount of data/time need to render the image is reduced. This option is particularly useful when HOOPS is sending raster information to the PostScript file/device, as is the case when Gouraud/Phong shading, HOOPS Images, or any other HOOPSsettingss triggering rasterization are present in the scene. (other examples include transparency, texture-mapped geometry, colorinterpolationn, color index interpolation, etc..).
The “subscreen” option may be useful to restrict the size of the page to allow for margins.
The “landscape orientation” option will rotate the picture 90 before fitting it onto the page (this is on by default — use “no landscape orientation” to turn it off giving a “portrait” style image).
A directory containing PostScript font files can be specified to HOOPS via the “font directory” driver option. HOOPS interrogates the font files for size information, and the PostScript driver uses these fonts when generating its output.
The type of PostScript file generated may be specified to HOOPS using the “output format” driver option.

Supported output type include “standard”, “EPSI” and “DOS-EPS”. The latter two formats support preview images. EPSI is Encapsulated PS with Interchange format preview bitmap. This is a PostScript standard, but is not recognized by most software. DOS-EPS is the de-facto standard preview format, as the file does not really conform to the PostScript conventions because it starts with a small block of binary data. The binary block contains offsets to, and lengths of, the real PS data and a preview image which may be either an enclosed Windows Metafile, or a TIFF image. The HOOPS/3DGS PostScript driver uses a TIFF.

Text Font Names in PostScript

The built-in PostScript text fonts are available. Currently, only the 13 “standard” PostScript fonts are supported. The “explicit’’ names for Set_Text_Font purposes are as follows. The first row of fonts are those used as the roman, sans serif, and typewriter generic fonts, respectively:

Roman fonts	sans-serif fonts	Typewriter fonts
Times-Roman	Helvetica	Courier
Times-Bold	Helvetica-Bold	Courier-Bold
Times-Italic	Helvetica-Oblique	Courier-Oblique
Times-BoldItalic	*Helvetica-BoldOblique*	Courier-BoldOblique

Since the PostScript driver is most commonly run with an on-screen driver, if you want to name a particular PostScript font you will probably want to use the multiple-choice “name=(name1,name2,…)” style in your Set_Text_Font calls, so you can name both your PostScript choice and your screen choice.

Encapsulated PostScript Files

If the file name ends with “eps”, an encapsulated PostScript file will be created. Another way to specify this same functionality is to set the output format driver option to the “eps” string value. Set_Driver_Options ("output format = eps") provides the same functionality as naming the file with a “.eps” suffix. In the case of a conflict, the output format driver option will override any filename specified format. Other valid strings include “output format = ps” for regular PostScript, “output format = epsf” as a synonym for eps, or “output format = eps-atend” to capture multiple output pages with the overall bounding box specified at the end of the output file. (Many programs that read EPS files do not handle the atend format. Use with caution.) HOOPS EPS files conform to version 2.0 of the Adobe Document Structuring Conventions.

Note on Sending Output to a Terminal Line

It is possible to have HOOPS Visualize open and write directly to a hardware terminal line with a printer attached. However, the printer should be reset each time you do this, before you open up the HOOPS PostScript driver. This is done by writing out one (or more) control-D characters (Ascii 4).

PostScript Driver Known Restrictions

On black and white PostScript devices, colors requested will be rendered in shades of gray.
With the very high resolution of PostScript devices, image or raster based output may not be reliable due to extreme memory requirements. Specifically the use of the software Z-buffer, texture maps, user-defined face patterns, and ray-tracing output is not recommended. Many of these image limitations will be addressed in a future version of the driver.

Printf Driver

The Printf driver is available on all platforms that are supported by HOOPS Visualize. You can use this driver when you want to perform actions in your scene graph that require a driver but you do not need to render to the screen. In its default mode, the Printf will write the draw commands into a file.

The file name is the name of the segment which is opened underneath the printf driver segment. If you want the driver to output nothing at all such as when you are running automated scripts, the driver instance name should be “/driver/printf/null”. To create multiple such driver instances the segment names should be “null+1”, “null+2”, “null+3” etc.

Qt Driver

Qt Driver Supported Systems

The HOOPS Qt driver is available on all systems supported by Qt (Windows/OSX/Linux/Unix). It is intended primarily for use in hardcopy.

Qt Driver - Gaining Access

The Qt driver can be specified either in the environment with HOOPS_PICTURE variable, or by creating a segment under /driver/Qt, e.g. /driver/Qt/window0.

Qt Driver Options

The “hardcopy resolution” driver option will be used if it is suported by the printer hardware,otherwise the driver will select a resolution.
Set_Driver_Options(“debug = DEBUG_USE_SCREEN_RESOLUTION”) specifies whether the Qt driver should use “ScreenResolution” mode, or “HighResolution” mode. ScreenResolution will result in lower quality output, and should only be used for drafts.
Set_Driver_Options(“debug = DEBUG_PRINT_DIALOG”) sets whether a QPrintdialog window will pop up at print time and allow printing options and setup to be manually entered.
When Set_Driver_Options(“debug = DEBUG_PASSED_IN_QPRINTER”) is set, along with passing in the address of a QPrinter object via the “use window id” driver option, the Qt driver will use the passed in QPrinter object for printing (rather than creating one for itself). This gives the user greater control over print output. <i>Note that this option and DEBUG_PRINT_DIALOG are mutually exclusive. If you enable both, a print dialog will be opened and overwrite the settings passed in from the user. </i>

Text Font Names in Qt

Only stroked fonts are supported with the Qt driver.

Qt Driver Known Restrictions

The QPainter specification has no provision for anything that could be used to implement Gouraud or Phong shading, so such geometry has to be rendered pixel by pixel. If lighting interpolation (see Set_Rendering_Options()) is required, a two-pass approach to printing is the only way to achieve reasonable speeds.

Quartz Driver

Quartz Driver Supported Systems

The HOOPS Quartz driver is available only on Mac OSX systems. It is intended primarily for use in hardcopy.

Quartz Driver - Gaining Access

The Quartz driver can be specified either in the environment with HOOPS_PICTURE variable, or by creating a segment under /driver/quartz, e.g. /driver/quartz/window0.

A quick note on environment settings on OSX: HOOPS takes settings in the following order of precedence: 1) from whatever had been set by unix-style setenv commands; 2) from the application plist file (whatever Carbon reports for kCFPreferencesCurrentApplication) under the user’s home directory in ~/Library/Preferences; or 3) from the central HOOPS plist file in ~/Library/Preferences/com.techsoft3d.HOOPS.plist

Quartz is a non-blocking interface. As such, any resources that are passed to it (especially images passed as window backgrounds), need to be retained until OSX reports that it is finished with them. If you are using the CPrintMacOSX class, that is when OnPrintFinished is called. Otherwise, it is an event that can be caught with a callback function from OSX.

Quartz Driver Options

The “landscape orientation” driver option will rotate the picture 90 before fitting it onto the page (this is on by default for all drivers — use “no landscape orientation’’ to turn it off giving a “portrait” style image). When using the standard OSX print dialogs, however, we have had best results with always setting “no landsape orientation”.
The “hardcopy resolution” driver option will determine the tradeoff between speed and quality for raster data.
The “border” driver option will reduce the drawing area by 1/2 inch in each direction.

Text Font Names in Quartz

Only truetype fonts are supported on Quartz. On OSX these generally come with the dfont extension. The fonts can be specified by their file name or by the font name as reported inside the font (e.g. “HelveticaNeue.dfont” or “Helvetica Neue”). Use the HOOPS_FONT_DIRECTORY environment setting or the Define_System_Options(“font directory=xxx”) to specify where HOOPS should look for the truetype files.

Quartz Driver Known Restrictions

The Quartz API specification has no provision for anything that could be used to implement Gouraud or Phong shading, so such geometry has to be rendered pixel by pixel. If lighting interpolation (see Set_Rendering_Options()) is required, a two-pass approach to printing is the only way to achieve reasonable speeds.

X11 Driver

X11 Supported Systems

The HOOPS X11 display driver works on Linux and OS X workstations.

X11 Driver - Gaining Access

To set up your environment so that the X11 display driver is the default HOOPS display driver you must define the environment variable “HOOPS_PICTURE”. Insert the following line in your “.cshrc” or “.login” file:

setenv HOOPS_PICTURE "X11/unix:0.0"

Once this definition is made, all programs that refer to the HOOPS “?Picture” segment will display on the local X11 machine. If you wish to display on an X11 screen other than the default X11 screen, substitute “X11/unix:0.n” for “X11/unix:0.0”, where n is the number of the X11 screen you wish to use.

Remote X11 machines can be accessed by substituting “X11/nodename:0.0” for “X11/unix:0.0”, where nodename is appropriate for the remote machine. You will also need to set up permissions on the remote machines. Please see the manufacturer’s documentation.

If you need to open the X11 display driver explicitly (because some other device is already the “picture” device), insert a call (or calls) to Open_Segment in your program similar to the following statement:

Open_Segment ("?driver/X11/decw$display");

If you need to open more than one HOOPS X11 window from the same program at the same time, use secondary segment names that look like “unix:0.0+A”, “unix:0.0+B”, etc., as you open the segments.

If you have more than one X11 server on your machine, substitute “X11/unix:n.0” for “X11/unix:0.0”, where n is the number of the X11 server you wish to use. If you have a workstation with more than one X11 screen, substitute “X11/unix:0.n” for “X11/unix:0.0”, where n is the number of the X11 screen you wish to use.

On some Unix systems HOOPS performs on the local device better if HOOPS_PICTURE is to set to a generic name such as “x11/unix:0.0.”:

define HOOPS_PICTURE "X11/decw$display"

into your “login.com” file.

To access a display on a remote VMS node, either use the VMS “SET DISPLAY/CREATE” command to change the local definition of “decw$display”, or substitute “nodename::decw$display” for remote VMS. You will also need to set up permissions on the remote machines; please see the manufacturer’s documentation.

If you need to open the X11 display driver explicitly (because some other device is already the “picture” device), insert a call (or calls) to Open_Segment in your program similar to the following statement:

Open_Segment ("?driver/X11/decw$display")

If you need to open more than one HOOPS X11 window from the same program at the same time, use secondary segment names that look like “decw$display:A”, “decw$display:B”, etc., as you open the segments.

If you have more than one X11 server on your machine, the hardware device names would replace “decw$display” in the above.

General X11 Display Driver Options

Since X11 is a windowing system, the following driver options may be of interest to you: “control area,” “border,” “subscreen,” “subscreen moving,” “subscreen resizing,” and “subscreen stretching.” Please see Set_Driver_Options in the HOOPS/3DGS Reference Manual for details. You can set up these various options externally to your program(s) with the “HOOPS_PICTURE_OPTIONS” environment variable. For example:

setenv HOOPS_PICTURE_OPTIONS \ "subscreen=(0,1,0,1),subscreen stretching"

makes the default window appear in the upper right of the screen and allows the window to be resized arbitrarily.

The X11 display driver supports double-buffering to make animation appear smoother. This feature is implemented via the X11 multi-buffering extension on workstations that support this X11 extension in their X11 server. Workstations that do not support this X11 extension in their X11 server will use X11 pixmaps for double-buffering. In either case, the speed of double-buffering depends on the speed of the X11 server and its access to possible graphics hardware acceleration of X11 multi-buffering. The X11 driver can be forced to use pixmaps for double buffering by setting HOOPS driver option to “debug = 16” from inside your HOOPS program using Set_Driver_Options (“debug = 16”) or specifying it in the “HOOPS_DRIVER_OPTIONS” environment variable:

setenv HOOPS_DRIVER_OPTIONS "debug = 16"

By default HOOPS will use X11 multi-buffering extension for double buffering, if available.

The double-buffering option is “off” by default; you can turn this feature “on” by specifying it in the “HOOPS_PICTURE_OPTIONS” environment variable:

setenv HOOPS_PICTURE_OPTIONS "double-buffering"

or you can turn this feature on from inside your HOOPS program(s) by using Set_Driver_Options.

The X11 display driver also supports a “backing store” option to activate the X11 server “backing store” capability in the “WhenMapped” mode. This X11 server capability automatically saves the contents of an X11 window while it is obscured to allow for quick recovery of the X11 window when it is exposed. This X11 server option is supported on most workstations. If this X11 display driver option does not work, check to make sure the X11 server on your workstation supports this capability, and that it is turned on in the X11 server (if the X11 server supports this capability, usually it is on by default).

Please see Set_Driver_Options for more information on these options.

Text Font Names in X11

There are a large number of text fonts available for use when you are running HOOPS on X11 machines. Set_Text_Font provides you with some “generic” HOOPS font names: “roman”, “sans serif”, “typewriter”, “stroked”, and “system default”. If one of these “generic” font names is specified as the font to use for HOOPS text, HOOPS will look through the selection of X11 fonts that are available on your X11 server machine and try to pick one that is of the appropriate style and appropriate size.

Specifically-Named Fonts

Alternatively, you can tell Set_Text_Font to use a specific X11 font. This gives you many more choices than with the “generics.” The X11 fonts that are available on your X11 server machine can be listed by using the “xlsfonts” command. (If your X11 server machine doesn’t have the “xlsfonts” command there is probably a demo program in your HOOPS distribution which will serve the same purpose. You may also use the Begin_Font_Search routine in HOOPS.) Specifying the name of an X11 font exactly as it appears when listed by the “xlsfonts” command will result in HOOPS using this font for text display, assuming that your Set_Text_Font “size” and “size tolerance” permit it.

Individual X11 font names have the following official format in X11 Release 3 and later:

-foundry-style-weight-slant-width-add style-pix height-point size-h res-vres-spacing-avg width-char set

An example is:

-adobe-times-medium-r-normal--17-120-100-100-p-84-iso8859-1

where the individual entries have the following meaning:

adobe - Foundry that digitized and supplied the font
times - Font style
medium - Font weight (bold, medium)
r - Slant (r = regular, i = italic, o = oblique)
normal - Set width (font’s proportionate width)
add style - Additional style information (if present; usually absent)
17 - Height of the font in pixels
120 - Size of the font in tenths of a point
100 - Horizontal resolution in dots-per-inch
100 - Vertical resolution in dots-per-inch
p - Spacing type (p = proportional, m = monospaced, c = charcell)
84 - Average width in tenths of a pixel
iso8859-1 - Character set (ISO Latin-1)

Family-Named Official Fonts

An individual X11 font contains a style and a specific size. HOOPS provides “HOOPS-constructed’” X11 font “families” to allow you to specify the X11 font style but let HOOPS pick the appropriate X11 text font size within that style that best matches your specified font size tolerance values. HOOPS does this by creating X11 font “family” names consisting of the style information from individual X11 font names but without the size information.

To figure out the HOOPS family name you want, start by putting down the foundry and the style. For example, “adobe-times”. Then:

If the weight is not “medium”, add a dash and the weight. For example, “-bold” for bold.
If the slant is not “r” (for regular), add a dash and the slant. For example, “-i” for italic.
If the width is not “normal”, add a dash and the width. For example, “-wide” for wide.
If the “additional style” is not blank (missing), add a dash and the name. For example, “-sans” for sans serif.
If you want a vertical resolution different from the usual one for your display, add a dash and the number in dpi appropriate for the vertical resolution you desire (the common choices are 75 and 100 dpi). For example, “-75” or “-100” for 75 or 100 dpi, respectively.
And lastly if the character set is different from the usual “iso8859-1”, add a dash and the character set. For example, “-adobe-fontspecific” for the Adobe symbol fonts.

So, following these rules, an adobe-times that’s italic but otherwise normal would be named “adobe-times-i” in your call to Set_Text_Font.

Family-Named Unofficial Fonts

Most X11 server machines will also have some number of fonts that are left over from previous releases of X and are not named in the official X11R3 and later style. HOOPS Visualize obtains approximate family names by subtracting all the numerals from the name and then subtracting any leftover trailing dash or underscore. For example, “times8bi” and “times10bi” both end up in a family named “timesbi” and “vg-25” and “vg-31” are in the “vg” family.

Rotated and/or Slanted Text

The X11 driver supports rotated text in integral multiples of 90 degrees. For all other angles, (45 degrees, for example) HOOPS will use the built-in stroked text instead of the X11 text fonts. Slanted text with either a positive or negative slant angle is supported for unrotated text or text rotated by an integral multiple of 90 degrees.

X11 Driver Known Restrictions

The X11 server buffers drawing output to such an extent that it can be difficult to synchronize mouse tracking type events. This is especially noticeable in rubber-banding and dragging using “quick move” segments.
Polygons with internal intersections may be drawn incorrectly by many X11 servers.
The X11 standard warns that the periphery of a polygon may or may not be included when the polygon is filled. All the known work-arounds involve making pictures take longer to draw. So in some special cases you may see polygons that are not filled quite as far out as you would want.
The X11 standard warns that an X11 Client program may “request” a specific location for an X11 window on the screen, but an X11 Client program may not “demand” that the X11 window be placed at this specific location. In the X11 display driver, we have tried to locate X11 windows created by Visualize as close to the requested position as this X11 restriction will allow. In some cases, you may wish to move the window with the mouse slightly if it is not exactly where you requested. This is most noticeable when using full screen windows.
When both driver options “no border, no control area” are set, input keys do not work. The combination of these options obviates the Window Manager’s ability to take control of the window for communication purposes.
The X11 driver does not always render properly on black and white devices.
For the most part keyboard mapping is standard for X11 across platforms. The NumLock key is an exception. It varies greatly from platform to platform. Attempts to handle the differences in the Visualize X11 driver were thwarted by the fact that a user may be working at a workstation, i.e. keyboard, for one platform but logged into a different platform. This issue has been reported to the various hardware vendors and is under their consideration.
The X11 driver works with 24-bit trueColor visuals or 8-bit mapped visuals. The driver will attempt to obtain a double-buffering visual to use for all rendering, even if your application only uses single-buffering. Thus you might end up with a double-buffered 8-bit visual rather than a 24-bit single-buffered visual as the visual the screen is created from, which can degrade the visual quality in some applications. From our testing this case appears rarely. This can be worked around by setting HOOPS_DRIVER_OPTIONS (debug=16), which forces pixmap method for double-buffering (see below). This behavior will continue for future releases. (Yes, it’s a feature.) Note that this applies only when you are relying on the Visualize X11 driver to create the window for you.
Advanced topic: the X11 driver and selection of visuals. The X11 driver works correctly with 8-bit mapped color visuals and 24-bit trueColor visuals but not for less-than-24-bit trueColor visuals. Unless you create your own window and pass this to Visualize to use the X11 driver will be responsible for creating the window, in which case it will also choose the X11 visual with which to associate the newly created window. If you pass a window to Visualize for the X11 driver to use, you MUST NOT pass in a trueColor visual of other than 24 bits.

In the case where a window is NOT passed to the X11 driver to use (HOOPS Visualizecreates the window), Visualize will try to find the best double-buffering visual. If this fails it will fall back on selecting the best single-buffering visual. If no double-buffering visual is available, and the Visualize application calls for double-buffering, double-buffering will be simulated by rendering into a frame buffer and then displaying a pixmap to the only available buffer when the application calls Update_Display or otherwise causes a “swap buffers” situation. In addition, this behavior can be forced by setting HOOPS_DRIVER_OPTIONS(debug=16). This can be useful to avoid a sticky situation or two mentioned above. When requesting a double-buffering visual, the X11 driver will reject any trueColor visual of other than 24 bits. However, if no double-buffering visual is found, and no single-buffering 24-bit trueColor visual is found, a 15- or 16-bit trueColor visual may be selected. In this case, there will be extreme rendering errors and repeated X11 errors mentioning “BadMatch.” There is no known work-around for this problem. If you encounter this problem, contact technical support (support@techsoft3d.com) as there may be a fix available. 24-bit trueColor and 8-bit mapped color visuals should work just fine, and most platforms do not provide trueColor visuals at bit depths other than 24, so this is a rare problem to encounter.

Automatic Drivers

HOOPS Visualize can be instructed to automatically select the most appropriate driver based on the current runtime environment, thereby insulating your application from runtime capabilities of the system and graphics card. The driver options are:

“/driver/3ddriver” - under Windows, preference will be given to the DirectX API, followed by OpenGL2. Under all other platforms, only the OpenGL driver is supported. HOOPS will attempt to choose the driver with the highest level API support offered by the runtime environment, by perform runtime query of the 3D capabilities on the end user’s graphics card. This driver should be selected for on-screen viewports.
“/driver/2ddriver” - selects either the ‘X11’ or ‘msw’ driver. This will fail on OS X because OS X does not have a supported 2D driver interface.

We strongly recommend that you utilize ‘3ddriver’ for your onscreen viewports, rather than manually selecting a specific driver. Some developers may be inclined to startup the application with a specific 3D driver, perhaps assuming that a specific driver is the most stable/preferred driver because development and/or QA was performed using driver. However, the results of such testing are typically confined to a very small number of GPUs, and may not be indicative of the wider experience among end users. Additionally, as implied above in the ‘3ddriver’ notes, manually selecting a specific driver could result in the application missing out on better performance or advanced rendering capabilities that would otherwise be provided by a more current Visualize 3D driver.

While ‘3ddriver’ is the recommended approach, we suggest that you also provide your end-users with an option to manually select a driver from a driver-pulldown list. This will allow them to potentially work around runtime graphics-card problems that occur with a specific driver type.

If you need to determine which driver HOOPS Visualize has selected to use at runtime as a result of using ‘3ddriver’, call Show_Device_Info and query for the “driver type”.

Setting Up the Runtime Environment

To assist with executing a HOOPS Visualize program, you can define the HOOPS_PICTURE and HOOPS_SYSTEM_OPTIONS environment variables.

HOOPS_PICTURE will be used to determine the value of the “?Picture” alias at runtime. (See the Programming Guide section on drivers.)

HOOPS_SYSTEM_OPTIONS serves as a runtime equivalent of the Define_System_Options values. Note that the ‘license’ option of Define_System_Options cannot be set using an environment variable. It MUST be set programmatically.

Examples for HOOPS_PICTURE on Linux and Max OS X:

setenv HOOPS_PICTURE opengl2/:0.0

WINDOWS registry HKEY_CURRENT_USER/HOOPS:

HOOPS_PICTURE opengl2/window0