HC_Define_System_Options

void HC_Define_System_Options(char const *list)

Controls non-graphics system behavior.

“System options” are a group of status settings that don’t have anything directly to do with graphics - they just control how the system reacts to some error and debugging situations. “System options” are defined system-wide - they are not a part of the graphics segment tree.

As usual, the options are specified as a list of items separated by commas, and uppercase vs. lowercase doesn’t matter. The options are as follows:

application =

This provides a place to record the name of the currently running application program. This might be convenient for utility routines. For example, a hardcopy utility routine might want to generate some labelling information.

If “application” is not set explicitly, HOOPS uses the environment variable HOOPS_APPLICATION. If that’s not available either, HOOPS asks the operating system for the file name of the currently executing image. If that’s not available either, then a blank string is used.

[no] automatic geometry boundings = [= on | off] (REMOVED)

This option has been removed. By default, Visualize now automatically updates geometry bounding; this setting cannot be turned off.

[no] bounding volumes [= on | off]

This option determines whether or not HOOPS calculates bounding volumes and uses them in rendering and processing selections. Use of bounding volumes improves drawing and selection performance but requires more memory. The default is “bounding volumes”. See Show_Bounding_Info() for more details.

[no] C string length = nnn

When HOOPS is called from a C language program, passed a buffer, and asked to return a string value in the buffer, it can’t tell how big the buffer is. The C language doesn’t provide that information automatically. If the buffer is too small for the string being put into it, the string will run off the end and overwrite other memory. Unfortunate results might ensue.

One solution is to make all your buffers “ample” in size. Alternatively, you can pick a standard size for your buffers and use “C string length” to tell HOOPS what that size is. Then, if a return string exceeds that size, HOOPS will know to issue a clean warning message and will avoid walking on memory.

The “C string length” is the total buffer size - it includes the terminating null byte. The default is “no C string length”.

camera near limit = (fff)

Sets the default camera near limit. Default value is “-0.001”. To get the pre-HOOPS v15 behavior set the value to 0.0001 for an OpenGL/D3D driver, or 0.05 for all other drivers.

[no] code generation [= on | off]

This is a special option available for generating debuggable HOOPS programs. When this option is activated, usually though the HOOPS_SYSTEM_OPTIONS environment variable, HOOPS generates a C program in addition to drawing to a device. The C program, code.c, is a sequential enumeration of HOOPS calls. This is one way to generate test cases for Tech Soft 3D Technical Support without having to send entire applications. Obviously, the default is “no code generation”.

code generation comment = (xxx)

This option has no effect at all other than to show up in code generation output. It is intended to allow users to inject general information about what is going on in their programs into the code generation trace. This option has no default.

[no] code generation directory = ‘path’

Allows the user to specify the directory in which the ‘code generation’ source files should be placed. The default is “no code

generation directory”.

[no] conserve memory [= on | off | memory_option ]

“conserve memory = on” means use all available memory suboptions. Legal values for memory_option include:

face list = on|off - Instructs HOOPS to discard face list information once a shell’s tristrips have been processed (after the shell has been drawn for the first time).
facings = on|off - Halts the generation of temporary ‘screen plane facings’ flags used for determining front & back sides of faces. This latter sub-option saves memory at a slight calculation expense.
circles = on|off - Instructs HOOPS to maintain a lightweight representation of circle-based geometries that have a z-value of zero. This reduces memory footprint with one notable restriction: lightweight circle-based primitives can not be edited using any of the Edit_XXX routines.
polyedges = on|off - Asks HOOPS to draw edges with the tristrip data rather than generating separate polyedge structures. This setting only has effect when the (1) there are no per-edge attributes, (2) the weight of the edges are 1, and (3) there is an edge visibility setting of “on”, “adjacent” or “nonculled”. Currently this option is supported only by the OpenGL driver.

The default is “no conserve memory”.

[no] continuous update [= on | off ]

“Continuous update” causes Update_Display() to be called at the end of each and every HOOPS call that might have changed the picture. This can be useful when there’s a problem occurring in your picture and you’re not sure where in your program the problem originated. When “continuous update” is on, you can step along in a debugger and watch the picture unfold. This option can slow down the running time of your program. The default is “no continuous update”.

[no] debug [= (ddd)]

Enables special (not yet fully supported) capabilities. The definitions of the debug bits change from release to release and so please contact support for a list of specific options. Keep in mind that debug bits set through this API are not cumulative, so subsequent debug bit settings will replace everything. If you wish to have a cumulative effect you should look at either the ‘clear debug’ or ‘set debug’ options. The default is “no debug”.

Bit Mask	Notes
0x00000004	Disables hardware-based visual selection. Please note, you will lose any performance gains hardware-based

visual selection would typically provide. |

[no] deleted key callback = ‘callback name’

The callback name refers to the callback defined by Define_Callback_Name(). Whenever an object with a key is deleted, the function associated with the callback name is called with the key as its argument. If the key is a segment with children, the function will be called on its children first. Note that the deletion does not occur until the next update. Consequently, you may get unexpected keys for unknown/temporary geometry within your callback.

[no] disable ambient material [= on | off]

If set, ambient light bypasses the usual modulation by the material. This would, for example, allow red ambient light to affect a blue surface, and/or any color ambient light to contribute to a black surface. The default is “no disable ambient material”.

[no] dpi scale factor [=<float>]

When set, this option overrides the default value for the system. It is used in point size calculations. A dpi scale factor of 1.0 is equal to 96 dpi. No restores the default value.

driver config file [= filename]

The filename contains a path to a file which can be used to force device specific behavior by our 3D drivers. The file is plaintext and the contents must be written in a specific format. The format corresponds to the arguments that Define_Driver_Config() takes. It can contain any number of sets of arguments. Each set of arguments will be passed into a call to that HC function. The calls will be made in the order they appear in the user’s config file. This matters because of the function’s wildcard matching - entries should go from general to specific. They also occur after 3dGS’ internal settings and consequently supersede them.

The options must be listed in a specified order: named DRIVER, ID, VERSION, and CONFIG (all caps). Each key word must be followed by a colon, a space, and the value. Option and value must be on a single line regardless of length of option. A blank line must be in between chunks. Empty string is a valid CONFIG, but the line “CONFIG: ” must be included.

Example config file contents:

DRIVER: dx11
ID: RADEON*
VERSION: *
CONFIG: config=(BAD_MSAA_SPRITING)

DRIVER: dx11
ID: FIREGL*
VERSION: *
CONFIG: config=(BAD_MSAA_SPRITING)

DRIVER: opengl
ID: *
VERSION: *
CONFIG: general tristrip minimum=3

By default no driver config file is provided.

clear debug = (ddd)

Removes the specified debug bit from the current debug value.

set debug = (ddd)

Adds the specified debug value to the existing debug value.

soft memory limit = (ddd)

Specifies the soft memory limit, in megabytes. Visualize will trigger an informational event when it allocates more memory than specified here. You should set an error handler to intercept this event and respond appropriately.

[no] event checker [= address ]

An “event checker” routine, if provided, is called by the system whenever Await_Event() or Check_For_Events() needs input. It is an opportunity for your program to put input from an unusual source (an event recorder, an unsupported brand of tablet, etc.) into the HOOPS queue manually, via the “Compute Selection” or the “Queue” routines.

On most systems the routine must be written in C. The routine is called with no arguments. The “address” is specified as a decimal number.

Usage of this option is only recommended for standalone HOOPS Programs. For applications which use the “use

window ID” Driver_Option the recommended path for breaking an update is to use the capabilities exposed by the “exit update” driver option.
The default is “no event checker”.

[no] extended font search [= on | off ]

If “no extended font search” is set, it may potentially restrict the number of fonts available but it also puts a cap on how long HOOPS will spend loading fonts. HOOPS will only use true-type fonts that can be found through system-dependent font lookup.

On Windows, this means that fonts available will be restricted to what can be looked up from the windows registry. Windows only keeps track of the fonts that are installed in the standard font directory.

On Mac OS X, the font name (see Set_Text_Font()) needs to be the “postscript name” for the font. This is an identifier that is guaranteed to be 8-bit (i.e. no wide characters) and globally unique on the system. It is, however, case sensitive, so the font name will usually need to be guarded surrounded with single quotes to protect it from HOOPS’ normal parsing, which converts everything to lower case (e.g. “font name = ‘Apple-Chancery’”).

Default is “extended font search”.

[no] fatal errors [= (option, option…) ]

[no] errors [= (option, option…) ]

[no] warnings [= (option, option…) ]

[no] info [= (option, option…) ]

These four options control whether Report_Error() should print out or skip messages of the given classes. They only control the error announcements made by the Report_Error() error handler. The system controls the rest of its normal error recovery. Valid choices for options include:

\li on/enable<br>All messages at the specified severity are on.
\li off/disable<br>All messages at the specified severity are off.
\li on/enable=(#/#,...)<br>One or more messages are turned on.
\li off/disable=(#/#,...)<br>One or more messages are turned off.
\li once=(#/#,...)<br>One or more messages will report only once.

A common use of these error-reporting options is to turn off messages temporarily. This is helpful in situations where you’re aware that what you’re doing might generate a warning. The code might look like this:

Show_System_Options (original_options)
Define_System_Options ("no warnings, no errors")
Delete_Segment ("might-be-gone-already-oh-dear")
Define_System_Options (original_options)

The #/# is the category and specific numbers of the message, as shown in the normal error report. So, for instance,

Define_System_Options("errors=(off,enable=(1/3,13/57),once=21/9")

…would turn all errors off, except that the errors represented by the number pairs (1,3) and (13,57) would still be reported, and the error (21,9) would only be reported the first time it might occur.

Note that the basic on/off settings override (discard) any individual settings that were previously set; moving the “off” to the end in the previous example would leave all errors off.

These setting only control the reporting of messages (calling any registered error handlers, HC_Report_Error by default). Any side effects of the message generation are unchanged - fatal messages still call exit handlers, and the messags id is recorded for Show_Error.

Use this feature judiciously. The default is to print everything.

[no] font directory = pathlist

This option specifies a comma separated list of directories where font information is stored. HOOPS searches each of the specified directories for font files that end with specific “known” suffixes when extended font search is on. Some font formats are understood directly by the HOOPS core and are usable on all drivers. Other formats are understood only by specific device drivers. To find out which fonts are available for a specific driver, use the Begin_Font_Search() routine.

Normally you will need to surround your directory list string with either single or double quotation marks to prevent HOOPS from interpreting any special characters within. The default is “no font directory”.

[no] free [= <function pointer>]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Directs all general memory frees to the provided function. If set, the user must also provide a function to allocate the memory through the malloc option. When using these interfaces, the very first call to HOOPS must be Define_System_Options and the option string must include settings for malloc and free. These memory settings are persistent through calls to Reset_System(). The default setting is “no free”.

[no] legacy mesh face numbering [= on | off ]

Enables the (deprecated) mesh face numbering scheme that was in place prior to HOOPS version 14. See Insert_Mesh for details.

[no] legacy text extent [= on | off ]

HOOPS/3dGS can add the width of an X to the bounding box returned from Compute_Text_Extent calls. This can help ensure that the returned bounding box extends beyond the width of the text string. The default behavior is “legacy text extent = off”. This option was introduced in HOOPS 16 and the behavior prior to HOOPS 16 was the equivalent of “legacy text extent = on”.

[no] license [= ]

The license is used to enable HOOPS operation.

If an invalid or expired license is set, your application will exit when 3DF attempts to start.
If you are using a time-bound evaluation license, the HOOPS/3dGS viewport will display a small piece of text indicating that it’s an evaluation license, along with the number of days remaining until expiration.
The license string must be included inside back-ticks as indicated above.

The default is “no license.”

[no] malloc [= <function pointer>]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Directs all general memory allocations to the provided function. If set, the user must also provide a function to free the memory through the free option. When using these interfaces, the very first call to HOOPS must be Define_System_Options and the option string must include settings for malloc and free. These memory settings are persistent through calls to Reset_System(). The default setting is “no malloc”.

[no] message limit [= (ddd) ]

HOOPS tries hard to be forgiving of error situations, and almost always is able to return control to the application program after printing its error messages. But one error often leads to another. “Message limit” is used to set a limit on the number of messages printed out before HOOPS calls it quits.

The “messages given” counter is incremented and checked in Report_Error() , and reset whenever Define_System_Options() is called on “message limit”. The default is “no message limit”.

[no] metafile directory = ‘pathlist’

This option specifies a comma separated list of directories where HOOPS metafiles are stored. HOOPS searches each of the specified directories for metafiles. When writing metafiles, the first directory in the list is used. The default is “no metafile

directory.”

[no] multi-threading [= off | full ]

Enables semaphores necessary to make 3dGS thread-safe. Performance penalty for this option is minimal. “full” renders each 3dGS call completely thread-safe. Depending on the function call, the block can be either a read or a read/write lock. At this point, database edits may occur during any draw update. “off” affords no thread protection. Default is “off”. As of Release 18, “basic” has been deprecated.

Warning: When using “multi-threading = full”, users should call HC_Reset_System right before their application’s main function exits to ensure all internal HOOPS threads have been safely shutdown.

[no] near limit update promotion [= on | off]

Controls whether changes to top-level bounding volumes can potentially promote incremental updates to full updates. In this case, “top level” means the level where the camera is defined. This option only comes into play when there is an automatically adjusting camera near limit (i.e. when Set_Camera_Near_Limit() is given a value less than or equal to zero, or not called at all).

Examples of changes that will cause full updates when using auto-adjusting near limits are as follows: (1) when geometry is added (but not removed); and (2) when any changes are made within segments that have the “quick moves=spriting” heuristic set.

The default is “near limit update promotion = on”.

[no] obsolete checking [= on | off ]

This is a special option available for generating warning messages when routines considered obsolete in HOOPS are called. The default is “no obsolete checking”.

[no] old style pathnames [= on | off ]

If this option is “on”, HOOPS calls such as Show_Selection_Pathname will return include segment pathnames in a way that is ambiguous, particularly in cases where a selection is instanced more than once. When “off”, include pathnames will indicate which segment in the path was the original include. This option is provided post-6.2-release to accommodate those programs which may directly parse the path string and so depend on the old behavior. The default is “off”. See the documentation of Show_Selection_Element for details on the pathname conventions.

populate memory limit [= (ddd)]

This option is sets how much memory HOOPS will use, in MB, before starting to eject the contents of populated segments. It will attempt to limit database memory use to approximately this value.

This option is currently only used by the OOC point cloud capabilities.

The default is 128.

[no] raw memory [= on | off]

Note: this option is strictly intended for debugging purposes under the advisement of Tech Soft 3D support; it is not support for use in commercially distributed applications.

Disables the memory cache that 3dGS uses for allocating and freeing small objects. Setting this can result in significant performance drops. The default setting is “no raw memory”.

[no] restrip on edit [= on | off ]

When on, this option causes tristrips to be automatically recalculated when a shell’s point list is edited. It should only be set if the change to the shell points array does not change the topology of the shell (which would include adding/removing points, or causing a shell face to go from concave to convex or vice versa). If the topology is changed and this option is set during the edit, then the correctness of the shell is not guaranteed. A synonym is “shell restrip on point edit”. Default is “restrip on edit”.

[no] sanity checking [= on | off ]

This is a dangerous option. It is available for turning off HOOPS checking of anomalies such as inclusions that cause a loop. This option can be deactivated to improve performance once applications are error free. The default is “sanity checking”.

[no] update control [= thread] = [on | off ]

Controls whether HOOPS will propagate redraw activity when modifications are made to the segment tree. If you set the optional “thread” value, then redraw activity will only be affected for modifications caused by that same calling thread. Please note that if you set “update control = off”, then your application will need to call Control_Update() to trigger updates. The default is “update control = on”.

[no] video memory limit [= (xxx) ]

Sets the limit of video memory to use, where xxx is a number that can be specified as “mb” for megabytes, “kb” for kilobytes, or with no units at all for bytes. Textures count towards the limit but are never suppressed. Display lists, on the other hand, are not created if they would put the total video memory usage over the specified limit. On the Windows platform, HOOPS automatically queries the capabilities of the system’s video card and sets the default video memory limit to be 32 MB less than what is available. For all other platforms, the default setting is “no video memory limit”.

\par NOTES

To prevent deadlock, error messages are automatically turned on for the duration of a call to Define_System_Options() .

The starting System Options can be changed on most operating systems by means of the environment variable “HOOPS_SYSTEM_OPTIONS”. This may be convenient, for example, for turning on “continuous update” or for turning messages off temporarily.