1.0 Streamlining the HOOPS/3dGS Library

2.0 Device Drivers

3.0 Gaining Access

4.0 Graphics Card Information


1.0 Streamlining the HOOPS/3dGS Library

Overview

Developers can build a scaled-down version of HOOPS/3dGS. It will not be provided as a pre-built library; rather developers will be able to compile obfuscated HOOPS/3dGS source code using compiler flags to stub out pieces of functionality that are not needed (for example, -DDISABLE_SHOW in the CFLAGS line).

Functionality Breakout Options

This section will provide details on the areas of core functionality that can be individually stubbed out, along with the estimated corresponding HOOPS/3dGS library size reduction.

The core functionality breakout list covers items that can be broken out as separate components. If all the items are broken out, the size of the HOOPS/3dGS library reduces to ~1MB. This size is largely a function of the core architecture of HOOPS which utilizes sophisticated data-structures and scaffold database/rendering/attribute logic to enable support of all these powerful components. Further reduction of the library size causes a run-in with the 80/20 rule (except in this case it is more like the 95/5 rule). That is, significant additional effort in stripping out functionality would result in minimal incremental size reduction.

1. DISABLE_RASTERIZER - software z-buffer/frame-buffer pipeline/image driver - 130k

This involves removal of all logic to perform software rasterization of the scene, with or without a z-buffering stage, including lookup tables, dc_z functions, etc... The HOOPS software z-buffer and software-frame buffer logic is no longer available to produce non-OpenGL based interactive rendering of complex 3d, shaded scenes.

2. DISABLE_SORTING_HSR - sorting-based HSR algorithms - 25k

These include algorithms such as hidden-line-removal and painter's. This prevents HLR renderings, or mixed-mode (vector and raster) rendering of scenes to hardcopy devices such as a native GDI Printer or Clipboard DC, Postscript file/device, etc. If you wanted to ensure transparent objects were rendered correctly you would need to include at least one sorting algorithm (probably z-sort at a cost of ~ 8K).

If Item 1 is also stubbed out, then HOOPS/3dGS would not be able to rendering a complex scene to a hardcopy device. (Either it needs to be sorted and drawn back-to-front, or it needs to be rendered to an offscreen buffeer using a szb/sfb. A remaining option would be for the developer to manually grab the screen image (or have OpenGL render to an offscreen image) and the blit that image to the hardcopy device.

3. DISABLE_METAFILE - 40k

Reading/writing HMF files would be unsupported.

4. DISABLE_BITSTREAM - Font Engine - 150k

TrueType, Double Byte, and Unicode fonts would no longer be supported.

5. DISABLE_TEXTURING - 30k

This is the texturing software implementation and support code. If diabled then objects could not be textured.

6. DISABLE_BIT_RASTERS
DISABLE_GRAY8_RASTERS
DISABLE_MAPPED16_RASTERS
DISABLE_MAPPED8_RASTERS - 20K

Certain display modes (8-bit, 16-bit; mapped and grayscale)

7. DISABLE_DRAW_3D - Non essential code in standard_3d functions - 50k

Any higher-level HOOPS attributes that apply to the visual appearance of entities (HOOPS-specific line-patterns, face patterns, marker symbols, etc.) that are not supported by OpenGL would no longer be supported.

8. DISABLE_SHOW - Show routines - 270k

The developer would not be able to query attributes in the HOOPS/3dGS scene-graph. (Typically this would be done within an application that provides editing capabilities.)

9. DISABLE_UNSET - UnSet and UnSet_One routines - 35k

The developer would not be able to UnSet attributes in the HOOPS/3dGS scene-graph.

10. DISABLE_GEOMETRY_EDIT / DISABLE_GEOMETRY_SHOW - 40k

The developer would not be able to query/edit geometry primitives stored in the HOOPS/3dGS scene-graph. (Typically this would be done within an application that provides editing capabilities.)

11. DISABLE_DEFINED_FONTS - 10k

The developer could not define custom fonts or use HOOPS internal stroked fonts.

12. DISABLE_STYLE_SEGMENT - 30k

HOOPS-style input handling would not be available. Typically this is only used in standalone 'HOOPS-only' demos.

13. DISABLE_LOD_GENERATION - 25k

Levels-of-detail for HOOPS/3dGS shell primitives could no longer be generated.

14. DISABLE_SEARCH - scene-graph searching support - 30k

Developer could not search for open segments, color names, contents, aliases, textures, etc.

15. DISABLE_COLOR_NAMES - Named color handling - 20k

Developer could not set/show colors using HOOPS/3dGS' built in color names, or create their own color names.

16. DISABLE_DATABASE_EDIT - Basic database routines - 25k

Developer could not manipulate the HOOPS/3dGS scene-graph nodes (segments), such as copy, style, move, rename, flush, etc.

17. DISABLE_COMPUTE - 25k

Developer would not have access to vector and matrix math utility routines, shell optimization routines, etc.

18. DISABLE_SELECTION/DISABLE_POLY_SELECTION - 40k

Developer could not perform selection using aperture, window, or volume selection methods / polygon or polyline selection.

20. DISABLE_CALLBACKS - 20k

The HOOPS I.M. API is no longer available. Developer can no longer make traversal time draw decisions, or utilize the immediate-mode type HIC_ routines to directly draw to the screen.

21. DISABLE_CODE_GENERATION - 15k

Developer could not use Code Generation system option.

22. DISABLE_GEOMETRY_ATTRIBUTES

Developers could not manipulate local face, vertex, and edge attributes from open shells and meshes.

23. DISABLE_EVENTS

HOOPS event handling routines. Developer could not use routines such as HC_Await_Event.

24. DISABLE_TABLE_LOOKUPS

Developer would forfeit certain performance optimizations during operations such as normal vector calculations.

25. DISABLE_SPECIAL_OPTIMIZATIONS

Developer would forfeit certain performance optimizations during some procedures, uch as the use of Show_Existence.

26. DISABLE_PHONG

Developer would forfeit the use of Phong shading and software texturing.

27. DISABLE_COLOR_MAPS - color index interpolation, mapped images

Developer would forfeit the use of color index interpolation or color maps.

28. DISABLE_PARTIAL_ERASE

Developer would forfeit the use of partial erase.

29. DISABLE_INSTANCING

Developer would forfeit the use of partial erase or sub-windows within included segments.

30. DISABLE_CUT_GEOMETRY

disables only HOOPS' internal implementation of capping polygon generation, leaving "cut edges" callbacks intact.

31. DISABLE_SIMPLE_SHADOW

disables HOOPS' internal implementation of fake shadows

Return to Index

2.0 Device Drivers

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

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

Driver AIX HPUX IRIX Win Tru64(OSF/1) Solaris Linux Mac OS X
CGM3
DX9
HPGL2
Image
MSW
OpenGL
OpenGL2
Postscript
PDF
Printf
QT
Quartz
WHIP
X11

Legend


2.1 3D Drivers

The following is a list of 3D Drivers supported on by HOOPS:

DX9 Driver

Supported Systems

The DX9 driver is a shader based driver that is supported on Windows XP Service Pack 2, Vista and 7. It requires the DirectX 9.0c Runtime version 9.26.1590 distributed on March 2009 or a later version of DirectX 9 installed on your system. The driver should run properly with any Direct3D 9.0 compliant graphics hardware with the latest vendor-supplied drivers.

Note for users running Vista: although this version of the OS comes preinstalled with DirectX 9. The DX9 driver uses the d3dx9_41.dll which does not come preinstalled with the OS. Please make sure that this dll is installed before trying to use the DX9 driver.

In some cases you may need to rebuild the HOOPS/3dGS DX9 driver. This might be necessary if you wish to support a version of DirectX that postdates the one against which a particular HOOPS version is built. In this case, you will have to download and install the DirectX Software Development Kit, and then check to make sure the environment variable DXSDK_DIR is set. HOOPS is built against Microsoft DirectX SDK (March 2009).

In order to guarantee that your customers are using a DirectX 9.0c version that is compatible with HOOPS DX9 driver, you can package and distribute the "Redist" directory that comes with the DirectX Software Development Kit. Contact support@techsoft3d.com if you experience any problems with this.

The DX9 driver supersedes the Direct3D driver. The driver path "/driver/direct3d/" is now an alias for "driver/dx9".

Hardware-Accelerated Offscreen Rendering

The DX9 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. However, there is one important difference when using the DX9 driver: the driver-instance must be defined as /driver/dx9/image.

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 DX9 in order to use the DX9 driver instead.

Special Driver Options

Debug Options

There is a debug option:

"debug = 0x01000000" runs rendering in software only. This option is useful for determining if a problem likes in the DX9 driver versus the hardware driver. Note that this mode is significantly slower than the using hardware acceleration.

Custom Shader Code

Developers can have the DX9 driver use their custom shader code by using the "set shader" callback point. The code must be HLSL and be DX9 compliant.

Known Restrictions

Return to Index

OpenGL Driver

Supported Systems

The OpenGL Driver requires the host platform to have OpenGL 1.1.

Windows

The Windows OpenGL driver supports OpenGL v1.1 and higher under all Windows platforms.

The Windows version of the OpenGL driver has been verified on [Soft]OpenGL 1.1 for Windows95, NT4.0, XP, Vista and 7, as well as various OpenGL accelerated hardware. See the Graphics Card Information for more details. The driver should run properly with any OpenGL 1.1 or higher compliant graphics hardware.

LINUX

The HOOPS OpenGL driver has been verified on a wide variety of OpenGL-compliant cards.

AIX

The OpenGL Driver will work on all IBM machines running AIX 4.1.5 or higher (with appropriate OpenGL components installed) with all graphics adapters except the E15, S15, GXT110P, GXT120P 2d graphics adapters. Following is a list of IBM graphics adapters along with recommended driver usage:

DEC

The OpenGL Driver has been verified on various DEC hardware, including the ZLX-E3, ZLX-L1, ZLX-M1, and Powerstorm 4D50T series graphics devices.

HP-UX

The OpenGL driver has been verified on HP Visualize FX-series systems which provide native hardware support for OpenGL. Update problems may exist when running 'use window id' programs in single buffered mode (i.e. HOOPS Motif widget), hence double-buffering should be used.

SOLARIS

The OpenGL driver has been verified on Solaris Creator3D-series systems which provide native hardware support for OpenGL. The driver should also work on more recent graphics systems released by Sun. The driver may work on older Sun graphics systems but is not recommended or supported; on older systems it is preferable to use the XGL driver.

A problem with overlays is apparent (HOOPS "quickmoves") on Solaris Elite3D systems. This should be corrected with patches from Sun. For Solaris 2.6 use patch 105363-07. Patch 105363-07 requires 105361 to be installed as well. For Solaris 2.5.1 use patch 105791-06. Patch 105791-06 requires 105789 to be installed as well. By the time you read this more recent patches may be more appropriate; contact HOOPS or Sun tech support if you are have problems with your Elite3D graphics with HOOPS OpenGL driver.

IMPORTANT: Single-buffering may not work properly in all cases, so double-buffering should be used for all HOOPS applications using OpenGL on Solaris expected to work with the 1.1.1 OpenGL release. This problem appears to be resolved with the 1.1.2 OpenGL library.

Also, the custom HOOPS Motif drawing area widget currently does not work correctly for 1.1.1 OpenGL on Solaris machines. However, we have provided a working Motif example which uses the vendor-supplied GLw drawing area widget. This is in the demo/glw directory. This problem appears to be resolved with the 1.1.2 OpenGL library.

Solaris x86

The libGL shipped with Solaris 10 has been found to not work in 64-bit mode. In order to use HOOPS on 64-bit x86 machines you will need to obtain a driver from the manufacturer of your graphics hardware. This will also allow HOOPS to take advantage of any acceleration provided by your hardware.

UNIX GENERAL INFORMATION

For the OpenGL Driver to work, X11 must be running. The OpenGL Driver is layered on top of the regular X11 Driver so the driver segment names look similar. The HOOPS OpenGL Driver uses the regular X11 Driver to perform all the window management tasks including input and uses OpenGL only for drawing into the window. To set up your environment so that the OpenGL Driver is the default HOOPS driver you must define the environment variable HOOPS_PICTURE. To do this insert the following line in your .cshrc or .login file:

setenv HOOPS_PICTURE "opengl/:0.0"

Once this definition is made, all programs that refer to the HOOPS "?Picture" segment will display in a window on the local workstation.

Note that the unix:0.0 specification is used by HOOPS to direct the OpenGL window to a specific display. This feature operates only on platforms that support GLX extensions. If displaying to platforms without this extension, an error will occur in the application.

Once this definition is made, all programs that refer to the HOOPS "?Picture" segment will open an X11 server window on the local workstation and then open OpenGL within that window.

If you need to open the OpenGL 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/opengl/unix:0.0")

If you need to open more than one HOOPS OpenGL window from the same program at the same time, use secondary segment names that look like display+bar, display+baz, etc., as you open the segments.

HC_Open_Segment ("?driver/opengl/unix:0.0+foo")

Microsoft Windows General Information

To modify your HOOPS_PICTURE for the Windows OpenGL driver, you need to access the registry. To do this, start up the regedit or regedt32 program (under \winnt\system32 on most computers) and select the HKEY_CURRENT_USER on Local machine section. Now select the HKEY_CURRENT_USER entry and Add Key. The key will be HOOPS. Now click on the HOOPS entry to open the folder, and add Value to the HOOPS folder. Once accomplished, the value name will be HOOPS_PICTURE and its value will be opengl/window0.

Hardware Accelerated Offscreen Rendering

The OpenGL 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. However, there is one important difference when using the OpenGL driver: the driver-instance must be defined as /driver/opengl/image.

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.

Special Driver Options

Double Buffering

The OpenGL Driver supports double-buffering to make animation appear smoother. This option is "off" by default; you can turn this feature "on" by specifying it in the HOOPS_DRIVER_OPTIONS environment variable:

setenv HOOPS_DRIVER_OPTIONS "double-buffering" 

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

OpenGL pBuffer Extensions

The opengl image driver uses pbuffers automatically whenever it can. If the required extensions are not present, HOOPS falls back to software-based BMP rendering on windows, but throws an error on UNIX or OSX since there is nothing to fall back to.

Debug Options

There are six debug options:

Setting debug=1 prints out all of the relevant information about the GL device. This debug option must be set before the first update.

Setting debug=2 is only useful when an initial clear of the Z buffer should be avoided. This is typically the case for applications that are only using HOOPS for 2D rendering.

Gamma Correction

By setting the HOOPS driver option "no gamma correction", you can disable the gamma-correction that HOOPS would otherwise perform. The use of this driver option assumes that the user will perform any necessary correction external to the running HOOPS program. On SGI hardware, this is easily accomplished with the /usr/sbin/gamma command.

Windows System-Specific options:

A 32-bit OpenGL z-buffer is enabled by default. Developers interested in using the 16-bit OpenGL z-buffer can use the following Debug Driver_Option:

HC_Set_Driver_Options ("debug = 512"); /* Debug_16BIT_ZBUFFER */ 

Refer to the Microsoft Windows (MSW) Driver section for details about hooking up HOOPS' OpenGL driver to user-created MDI application windows.

However, it should be noted that the software z-buffer, software frame buffer, and palette sections of the MSW driver do NOT apply when using the Windows OpenGL driver for display.

Unix System-Specific options:

Since the OpenGL Driver is layered on top of the X11 Driver and X11 is a windowing system, some driver options that affect the behavior of windows in a windowing system may be of interest to you. Please see the "Special Driver Options" section of the X11 Driver section regarding any driver options that affect the behavior of windows in a windowing system. Please refer to the X11 Driver section for other special driver options.

Text Font Names

The Set_Text_Font routine may be used to set font characteristics from within a HOOPS program. You may also control them externally by setting the environment variable "HOOPS_TEXT_FONT". For example:

setenv HOOPS_TEXT_FONT "name=Courier,size=12pt"

Will set the default font to be 12-point Courier for subsequent executions of the program.

AIX

The OpenGL Driver uses X11 fonts available through the X11 server on your IBM workstation. Set_Text_Font provides you with some "generic" built-in HOOPS font names: "roman", "san 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 to the X11 server on your IBM workstation and try to pick one that is of the appropriate style and appropriate size.

The OpenGL Driver provides access to the full range of individual X11 fonts that are available through the X11 server on your IBM workstation. Please refer to the "Specifically-Named Fonts" section of the X11 Driver section for information on how to use specific-named X11 fonts.

Known Restrictions

Generic

SOLARIS

HP-UX

WINDOWS

Return to Index

OpenGL2 Driver

The OpenGL2 driver is a shader based driver that requires the host platform to have OpenGL 2.0.

Supported Systems

Windows

The OpenGL2 driver is supported on Windows XP Service Pack 2, Vista and 7. It will support non-windows platforms in future releases.

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. However, there is one important difference when using the OpenGL2 driver: the driver-instance must be defined as /driver/opengl2/image.

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.

SPECIAL DRIVER OPTIONS

Custom Shader Code

Developers can have the OpenGL2 driver use their custom shader code by using the "set shader" callback point. The code must be GLSL.

Known Restrictions


2.2 Print and 2D Drivers

CGM3 Driver

Supported Systems

The HOOPS CGM3 Driver is similar to the CGM driver except that it supports the CGM3 standard, which 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.

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

Supported Systems

The HOOPS HPGL2 Driver has been verified on various host computers running Windows, Solaris, AIX, IRIX, HP-UX, and 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:

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. (See Notes to MS-DOS Users that follow.)

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, on a machine running MS-DOS, type:

set HOOPS_PICTURE=hpgl2/hoops.hp

Where hoops.hp is the actual name of the file that captures the HPGL2 output. Please see the Platform and Device Guide entry for your particular operating system for details on how to define environment variables. 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. On certain systems such as MS-DOS and UNIX, opening a new file means the previous version is overwritten.

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:

	QSet_Visibility ("?Hardcopy", "on"); 
	Update_Display (); 
	QSet_Visibility ("?Hardcopy", "off");

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:

Be sure that the system manager has installed the plotter correctly (i.e. baud rate, hand-shaking, etc. is set correctly for your computer).

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).

Example:

Assume:

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.

Restrictions:

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

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");

Heuristics

Known Restrictions

Special Instructions

There are no defined driver debug options.

Return to Index

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.

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 KInsert_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:

  1. 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.
  2. 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_KInsert_Image (...); /* keep the key! */      
    HC_Close_Segment (); 
    
  3. Now open up a segment under the image driver:
    HC_Open_Segment ("?driver/image/my_segment"); 
    
  4. 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.
    /*Checking to see if we need to put "0x" in front of the pointer depending on 
    the system.  If you have HOOPS/MVO installed, you can use the H_EXTRA_POINTER_FORMAT 
    macro.*/	  
    const char* extra_pointer_format()
    {
    	char buffer[MVO_BUFFER_SIZE];
    
    	sprintf (buffer, "%p", (void*) buffer);
    	if (buffer[0] == '0' && buffer[1] == 'x')
    		return "";
    	else 
    		return "0x";
    
    }	  
    
    ...	  
    
    sprintf (buf, "use window id = %s%p", extra_pointer_format(), key); 
    HC_Set_Driver_Options (buf); 
    
  5. Next, put some geometry under the segment. Usually, you'll want to do something like this:
    HC_Include_Segment ("?picture");
    
  6. Don't forget to close the segment.
    HC_Close_Segment ();
    
  7. Render the picture.
    HC_Update_Display (); 
    
  8. To show the contents of the image, you'd use:
    HC_Show_Image (key, ...); 
    
  9. 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 Offscreen Image with 3D Hardware Acceleration

The HOOPS OpenGL and DX9 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.

Driver Options

Heuristics

Known Restrictions


Microsoft Windows Driver

Supported Systems

The Microsoft Windows (MSW) driver is supported on all Windows platforms. The driver should run correctly on any functioning Windows GDI compatible device.

Gaining Access

To modify your HOOPS_PICTURE for the Microsoft Windows driver, you need to access the registry. To do this, start up the regedt32 program (under \winnt\system32 on most computers) and select the HKEY_CURRENT_USER on Local machine section. Now select the HKEY_CURRENT_USER entry and Add Key. The key will be HOOPS. Now click on the HOOPS entry to open the folder. Now add Value to the HOOPS folder. Once accomplished, the value name will be HOOPS_PICTURE and its value will be msw/window0.

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.

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. The Creating A Prototype section of the Getting Started Guide covers application development.

Text Font Names

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.

Driver Options

Special 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:

  1. 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.
  2. 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.

Debug Driver Options

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

Known Restrictions

Return to Index

PDF Driver

Supported Systems

The HOOPS PDF Driver has been verified on various host computers running Windows, Linux, and UNIX.

Gaining Access

There are two ways to use the PDF driver from HOOPS. 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, HOOPS programs that refer to the HOOPS "?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 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 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 HOOPS 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:

QSet_Visibility ("?Hardcopy", "on"); 
Update_Display (); 
QSet_Visibility ("?Hardcopy", "off"); 

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."

Special Driver Options

Text Font Names

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
Symbol

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.

Return to Index

Postscript Driver

Supported Systems

The HOOPS PostScript Driver has been verified on various host computers running Windows, Linux, and UNIX; driving HP LaserJet 4000TN PCL6, IIISi, 4m, 4m+, and NEC Silentwriter laser printers. It should run properly on any computer system driving almost any PostScript output device.

Gaining Access

There are two ways to use the PostScript driver from HOOPS. 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 HOOPS 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, HOOPS programs that refer to the HOOPS "?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 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 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 HOOPS 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 will open a new file each time this sequence is called. On certain systems such as MS-DOS and UNIX, opening a new file means the previous version is overwritten.

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:

QSet_Visibility ("?Hardcopy", "on"); 
Update_Display (); 
QSet_Visibility ("?Hardcopy", "off"); 

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."

Special Driver Options

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

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
Symbol

Since the PostScript driver is most commonly run along with a 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.

For Extended DOS HOOPS users, the files must be present at run time either in the current directory or in the current PATH. For faster access, these files are in a directory defined in the HOOPS_FONTS environment variable.

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 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).

On DOS HOOPS sends out the control-D automatically, but on other systems HOOPS assumes that there is always a print server in the way.

Known Restrictions

Return to Index

Printf Driver

The Printf driver is available on all platforms that are supported by HOOPS. 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.

Return to Index

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.

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.

Special Driver Options

Text Font Names

Only stroked fonts are supported with the 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. The source code provided in demo/qt/qthoopsrefapp_4 has an example of how to do that.

Return to Index

Quartz Driver

Supported Systems

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

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 provided with qthoopsrefapp, that is when OnPrintFinished is called. Otherwise, it is an event that can be caught with a callback function from OSX.

Special Driver Options

Text Font Names

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.

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. The source code provided in demo/qt/qthoopsrefapp has an example of how to do that.

Return to Index

X11 Driver

Supported Systems

The HOOPS X11 Display Driver has been verified on AIX, HP-UX, IRIX, OPENVMS, Tru64 (OSF/1), and Solaris workstations. The HOOPS X11 Display Driver should also work on other X11 compatible machines, e.g. DEC Ultrix, Intergraph Clipper, Sony News, SCO Unix.

Gaining Access

Unix

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." On others, the specific machine name works better, e.g. "x11/razzle:0.0." The following table identifies the preference for supported platforms where the X11 driver is appropriate:

Platform HOOPS Picture Setting
AIX machine:0.0 and unix:0.0 are equivalent
HPUX x11/machine:0.0
IRIX machine:0.0 and unix:0.0 are equivalent
Tru64 (OSF1) machine:0.0 and unix:0.0 are equivalent
Solaris machine:0.0 and unix:0.0 are equivalent
SunOS x11/unix:0.0

OpenVMS

To set up so that the X11 Display Driver is the default HOOPS Display Driver you must define the logical name "HOOPS_PICTURE". If HOOPS was fully installed as a system utility, the default system definition is probably fine. If not, insert:

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.

Special Driver Options

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. Example programs using HOOPS inside Motif widgets with the above mentioned options specified are also provided with your HOOPS distribution.

X11 Display Driver Options For Use With Widgets

The "use window ID," "use colormap ID," "special events," and "disable input" driver options have been encapsulated to allow you to run the X11 Display Driver, as well as 3D drivers (XGL, SBX, GL, OpenGL) in a HOOPS Motif Drawing Area Widget instanced by your program. An example of this is provided in the demo/motif/simple directory. Note that this demo creates a widget with the properties necessary to be able to successfully run not only with the X11 driver but also the OpenGL, GL. Starbase, and XGL drivers when these APIs are supported by the host machine. Normally the X11 Display Driver creates its own X11 window; however, if you wish to use HOOPS in a window created by your own program, you pass the X11 window ID of the relevant X11 window to the HOOPS X11 Driver via the "use window ID" driver option, and HOOPS will use your X11 window instead of creating its own. Hardware Display Drivers which are on top of X11 Display Driver like the GL Display Driver use the driver option "use window ID2" for their drawing needs. Hence, setting the driver option "use window ID2" for the X11 Display Driver might cause problems to your drawing, or you might get an error message from HOOPS, so please do not set the driver option "use window ID2" when you are using X11 Display Driver.

The HOOPS widget can be used just like any other Motif drawing area widget. The HOOPS widget is subclassed off of XmPrimitive (so the XmPrimitive resources are available). These are the resources specific to the HOOPS widget:

These are the callbacks available:

The callbacks send back an (HT_Widget_CallbackStruct *) in the call_data parameter (third parameter to your callback). See hoopsw.h.

The example mwidtest.c uses most of the functionality described here and can be used as another source of reference.

Note to HP-UX Users

Sharing color maps on HP-UX requires some additional coordination. The Motif library on HP-UX has extra code to make the default colors follow the color schemes that the user selects with vuestyle controls. This extra code causes problems for some applications that do not want this unique and unexpected behavior.

You can prevent the entire color scheme mechanism from being used in an application by setting "*useColorObj: False" for the application before creating the first widget. This can be done by adding the resource to the application defaults, the fallback resources, or as an extra "-xrm" "*useColorObj: false" args pair in the argv and argc parameters passed to XtAppInitialize. If you set the resource in xrdb, it would be best to set it for only specific applications like "MyApp*useColorObj: false".

You can use the vue colors and prevent the specific difference between dialog colors vs. non-dialog colors by setting a resource that specifies the behavior of the color scheme mechanism. To force the dialogs to use the same colors as the other windows, set the following resources in your app_defaults file or fallback settings:

*primaryColorSetId: 3 
*secondaryColorSetId: 3

This sets the dialog or "secondary" colors to be the same set as the primary colors. For additional information, this is discussed in the "HP VUE 3.0 User's Guide" in Chapter 26.

Text Font Names

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-v res-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:

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:

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 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 HOOPS 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.

Known Restrictions

In the case where a window is NOT passed to the X11 driver to use (HOOPS creates the window), HOOPS 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 HOOPS application calls for double-buffering, HOOPS will simulate double-buffering 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. This bug should be fixed in the next release (we will avoid non-24-bit TrueColor visuals in the single-buffering case as well as the double-buffering case).

Return to Index

WHIP Driver

Return to Index

3.0 Gaining Access

To execute HOOPS programs you need to define some environment variables. Actually you can run programs without defining any variables at all, but you will get some warnings. The two most important variables to define are HOOPS_PICTURE and the license string within HOOPS_SYSTEM_OPTIONS. HOOPS_PICTURE tells HOOPS which type of display and driver to use. Failing to define this causes HOOPS to generate a warning message that it is using a default value. The license string in HOOPS_SYSTEM_OPTIONS tells HOOPS that you have formally licensed the product. Failing to define the license does allow HOOPS to execute properly, but you get a message that says that HOOPS is being used without a license. Setting the HOOPS license key with the HOOPS_SYSTEM_OPTIONS environment variable is allowed for application development, but replacing the variable with a call to HC_Define_System_Options must be used in shipping applications.

A typical setting for these variables is:

UNIX:

   
setenv HOOPS_PICTURE opengl/:0.0 
setenv HOOPS_SYSTEM_OPTIONS license = (customer = <customer>,product = (im,classic),key    = < xxxxxxxx-xxxxxxx-xxxxxxxx >) 

WINDOWS registry HKEY_CURRENT_USER/HOOPS:

   
HOOPS_PICTURE opengl/window0 
HOOPS_SYSTEM_OPTIONS "license = (customer = <customer>,product = (im,classic),key    = < xxxxxxxx-xxxxxxx-xxxxxxxx >)" 

where <customer> and <xxxxxxxx-xxxxxxx-xxxxxxxx> have been supplied by Tech Soft 3D Technical Support.

Once these settings are established, programs can be run with HOOPS using its OpenGL driver. Settings are similar for X11 where "x11" replaces "opengl", or with Windows GDI where "msw" replaces "opengl".

Return to Index

4.0 Graphics Cards

You should visit the HOOPS Developer Zone for the most up to date information regarding graphics card support.