HC_Set_Driver_Options

void HC_Set_Driver_Options(char const *list)

Provides information to the system about a variety of special device-specific display options.

“Driver options” are special rendering or display attributes that are particular to one or a few display devices. You can request as many as you want - the device you’re actually running on will pay attention just to the ones it understands.

Supported Options:

absolute line weight, ambient occlusion, anti-alias, backing store, bloom, border, color consolidation, control area, depth of field, debug, clear debug, disable input, display interrupted update, display statistics, display memory statistics, double-buffering, draw degenerate lines, exit update, exit update data, eye dome lighting, fallback font, fast silhouette, first color, fixed colors, font table, force grayscale, fullscreen, gamma correction, gpu resident, * gpu preference, * hardcopy resolution, isolated, landscape orientation, light scaling, locater transform, marker drawing, number of colors, output format, pen speed, post world scale, physical size, quick moves preference, selection proximity, set debug, shadow preference, special events, spotlight interpolation, stencil, stereo, subscreen, subscreen moving, subscreen resizing, subscreen stretching, text preference, title, update interrupts, use colormap ID, use window ID, window opacity, write mask

DETAILS

The list of options is passed to the system as an arbitrarily long formatted string containing one or more option specifications, separated by commas. For example, “border, no control area, title =`DeLuxe Application Co.’”. This is what’s going on. A simple option specification consists of the option name or the word “no” followed by the option name. A specification with a value field consists of the name, an equals sign, and then the value. A string value is a single or double quote (in addition to the quotes you might have surrounding the “list of options” itself), the string, and a matching quote. A single value integer is just the numeral, while a value that requires multiple integers (like a screen location) is passed surrounded by parentheses and separated by commas. Uppercase versus lowercase is not significant, nor any leading or trailing blanks on any specification, nor are any blanks in the value field (except in a quoted string). Embedded blanks within the option name itself are significant.

If your program is actually computing the numeric values, you will need to use a C “sprintf” to turn those integers into the proper character strings.

Each individual driver option inherits up and down the segment tree and is Set independently of all the other options - it is perfectly reasonable to call Set_Driver_Options() several times in a row, feeding in more choices each time. The new choices are merged with the old as they arrive. This avoids having to make the call just once with a single humongous specification string. (Note that UnSet_Driver_Options() removes everything for that segment. Use UnSet_One_Driver_Option() to remove just one of the options as described below.)

The following options are guaranteed always legitimate:

[no] absolute line weight [= on | off]

Sets one pixel in the scene equal to one pixel on the device. The default is “no absolute line weight”, therefore lines with weights greater than 1 will be automatically scaled to maintain their look on high resolution printers. For full manual control of line weights, set “absolute line weight”.

ambient occlusion [= list]

Ambient occlusion is a general term for shading that varies when nearby objects (occluders) would prevent some portion of ambient light from reaching a surface. HOOPS Visualize simulates ambient occlusion by working on the images (including the z-buffer) that result from the render. It applies a filter that looks for small valleys in the depth buffer results, and slightly darkens these areas. Valid choice for list include the following:

  • on|off

Enables or disables ambient occlusion. The default value is off.

strength = xxx

A multiplier on the default contribution of ambient occlusion in the driver’s regular calculations. Higher values mean that ambient occlusion will make a stronger contribution. The default strength is 1.0.

quality = [fast | nice]

When quality is set to “fast”, the driver will attempt to limit the postprocess time to under 50 milliseconds (i.e. 20 frames per second), stripping out parts of the ambient occlusion shader until either the performance target is achieved or a minimum quality level is reached. If quality is set to “nice”, it will use the highest quality shader that will fit within the instruction count limits for hardware acceleration, without regard to execution time. The default is “quality = fast”.

  • radius = fff

A multiplier for the screen-space search radius. Higher values increase the search radius for occluding pixels, but may cause under-sampling artifacts.

  • sharpness = xxx

Lower values will be blurred more but have softer edges; higher values will be blurred less with harder edges, but more potential for banding. It is possible to specify values in the range of 0 to 32. Default sharpness is 32.

Ambient occlusion uses the depth buffer that is generated when we render opaque geometry to approximate ambient occlusion. Drawing of geometry with transparency is always deferred until after all opaque geometry is drawn, and doesn’t write any depth information to the depth buffer. Thus, transparent geometry will effectively not exist for ambient occlusion calculations, and will therefore be unaffected by them. This also means that if all geometry in a scene is transparent, ambient occlusion is effectively disabled.

[no] anti-alias [= xxx]

Prompts HOOPS to request a window from the operating system that is anti-alias capable, and enables the driver to perform anti-aliasing. An integer may be provided in order to specify the requested number of anti-aliasing samples per pixel. In order to have any effect, this option must be set in the driver prior to the first update, and the “anti-alias” rendering option must be enabled. After the first update, ::Show_Device_Info can be used to show whether the window is in fact anti-alias capable. This setting should be used with caution, as windows that are anti-alias-capable can sometimes require large amounts of video memory. The default is “no anti-alias”. Supported on OpenGL_Deprecated (on hardware with the required OpenGL extensions), OpenGL2, and DX11. Note that this value can be changed after the initial update for DX11, and OpenGL2 drivers.

[no] backing store [= on | off]

If HOOPS is running within an external windowing system then “backing store” requests the external system to enable backing store for the graphics window. Some operating systems implement this only for 2D drivers such as X11. The default is “no backing

store”.

bloom = [=(option1, option2,…)]

Bloom is a technique that provides a form of high dynamic range effect. It causes bright objects to bleed into darker ones, simulating the imperfect focus inevitable with the human eye or any other type of lens. This is an image-based post process effect available only on the DX11, and OpenGL2 drivers, and will be ignored on other drivers. Only light contributions based on specular, emission or environment map will be blurred in a bloom effect.

Legal choices for this option include the following:

  • on | off

Enables or disables bloom. The default value is off.

  • strength = xxx

A multiplier on the default contribution of bloom. Higher values mean that bloom will make a stronger contribution. Numbers in the range of 0 to 10 are accepted. The default strength is 1.0.

  • blur = xxx

The number of blur passes to perform on the output. Higher values mean that bloom will affect a wider area and look smoother. Numbers in the range of 1 to 8 are accepted. The default blur is 5.

  • shape [= star | radial]

The type of kernel to apply (i.e., “what shape is it?”). Valid values for this are “star” and “radial”. The default is “radial”.

[no] border [= on | off]

If HOOPS is running within an external windowing system then “border” requests the external system to put its standard border around the outermost graphics window, if it has any. The default is “border”.

[no] color consolidation [= ddd | fff%]

This driver option was included to satisfy those customers who are trying to specify colors that map directly to colors they know are already in the color map of a device. Normally, HOOPS recognizes that color differences are perceptible to an accuracy of one part in 64. HOOPS therefore merges like colors, using one specification to match several “close” colors. With this driver option, you can control this consolidation process.

“color consolidation = ddd” means that ddd colors are discernible in each channel. In other words, if there are two colors requested that differ by less than 1 part in ddd, they are merged. If ddd is small, more colors are consolidated. Conversely, a large value of ddd means that fewer colors are merged. Thus, this option specifies the denominator of a tolerance expression 1/ddd.

“color consolidation = fff%” means colors that differ by less than fff percent in each of the channels are treated as the same color by HOOPS. A larger number results in more colors being merged. A value of 100 percent makes HOOPS merge all colors into one. A value of 0 percent means all colors are distinct if not exactly equal. This style of specification is the reciprocal of the first style.

“no color consolidation” is equivalent to “color consolidation = 0%”.

The default value is “color consolidation = 1.5625%”, which gives 64 distinct colors.

[no] control area [= on | off]

Similarly to “border”, if HOOPS is running within an external windowing system then “control area” requests the external system to put its standard user interaction buttons around the outermost graphics window, if it has any. “Control area” implies “border” on most window systems. The default is “control area”.

[no] depth of field [= list]

The list can be one or more of the following:

  • on|off

Enables or disables depth of field.

  • near = xxx

The camera distance in front of which geometry will begin to appear out of focus. Valid range is positive to negative infinity, though the negative part of that range will have no effect in perspective since geometry behind the camera can never be visible. Default value is negative infinity.

  • far = xxx

The camera distance beyond which geometry will appear out of focus. Valid range is positive to negative infinity. Default value is positive infinity.

  • strength = xxx

A multiplier on the default blur radius. Higher values mean more blurring. Default value is 1.

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 cumulatve effect you should look at either the ‘clear debug’ or ‘set debug’ options. The default is “no debug”.

Bit Mask

Notes

0x00200000

Required for D3DImage usage with dx11 driver in the wpf_image sample project. Setting this bit will affect dpi-sensitive elements (like text and markers) because Visualize will treat such driver instances more like a physical window rather than a virtual off-screen window with a hard-coded dpi.

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. [no] disable input [= all]

In some special cases, your program may wish to handle all the input information coming from the operating system. This might, for example, come up if HOOPS is running within a windowing system, and your application wishes to make direct calls to the window system. “Disable input” tells the driver not to request input from the system. “No disable input” is the default. See also “special events”, below. When disable input = all is specified, the application is responsible for controlling HOOPS updates via Update_Control() .

display interrupted update [= default|on|off] *

This determines if a partial iamge from an interrupted update is displayed.

The default for timed updates is yes. The default for untimed updates is no.

[no] display statistics [= on | off]

When set, the driver will display in the upper-left corner the number of objects drawn during the last update. This option is only supported in the OpenGL and DirectX drivers. The default setting is “no display statistics”.

[no] display memory statistics [= on | off]

Tells the driver to display the amount of memory that HOOPS has allocated, as well as the amount of memory that it is actually using. Information is displayed in the upper-left corner. This option is only supported in the OpenGL and DirectX drivers. The default setting is “no display memory statistics”.

[no] double-buffering [= on | off]

Tells the system to use alternate graphics memory, if such is available, to perform time-consuming renderings. When the new rendering is completed, the alternate memory is rapidly swapped with the visible memory. Double-buffering usually dramatically reduces screen flickering. It might, however, take away from available program space or from the number of simultaneous screen colors you can have, depending on the method of implementation. The default is “no double-buffering”, i.e., allow the maximum number of colors to be available.

[no] draw degenerate lines [= on | off]

Tells the system whether to draw degenerate lines. A degenerate line is a line of zero length. When this setting is enabled, the expected visual result is just a single dot.

[no] exit update [= <callback name>]

When “exit update” is set, the callback registered as callback name will be called at regular intervals during a rendering update. In this callback, the user can, for instance, call the HOOPS IM function ::HIC_Abort_Update() to break out of the update process. If your callback function’s signature has a parameter for your own data as seen in Set_Callback_With_Data(), you can set the exit update data

option as well. This option should be used in place of “update

interrupts”. The default is “no exit update”.

[no] exit update data [= <pointer address>]

This option should be used in conjuction with exit update if your callback function’s signature has a data parameter. Set the option with an address to the pointer that will be populated with application specific data:

HC_Set_Driver_Options ("exit update = the_callback_name, exit update data = 0x12345678");

The default is ‘no exit update data’.

[no] eye dome lighting [= (on, strength=ddd) | off]

Enables or disables eye-dome lighting. The strength parameter ‘ddd’ defaults to 1.0. Reduce this value to smooth the image.

fallback font = (font1, font2)

When HOOPS (for any reason) cannot use a specified font to render a specific character string, it will try to use the fonts from the “fallback font” list before resorting to the built-in stroked font.

[no] fast silhouette edges [= ]

Enables fast drawing of silhouette edges, where list is a comma-separated list of one or more of the following options

  • on|off

    Enables or disables fast silhouettes. The default is off.

  • tolerance = xxx

    A multiplier on the threshold that the driver uses when comparing adjacent pixel depth values to detect silhouettes. This allows the user to control the tradeoff between silhouettes appearing where they shouldn’t, vs disappearing in places they should be. The default value is 1.0.

    <li>[no] heavy exterior [= on | off]<br>
    
    In addition to the normal fast silhouettes that can also appear at discontinuities in the z buffer, draw an extra thick line at the exterior silhouettes. This option, when enabled, causes an extra thick border to be drawn at the boundary between geometry and the window background (as opposed to geometry on top of other geometry). The default is “no heavy exterior”.

Fast silhouette edges require a shader-based driver.

[no] first color [= ddd]

If the device at hand is a color frame buffer, “first color” restrains HOOPS from using any hardware color map entries before the one specified. This is useful in cases where some other screen activity is already making use of some of the color maps. “No

first color” tells HOOPS to start wherever it pleases (usually at zero). See also “number of colors”, below. The default is “no

first color”.

[no] fixed colors [= ddd | (dd,dd,dd)]

If the device at hand is a color frame buffer of less than 24 bits, and if you are using lighting ( Insert_Distant_Light() ) or “RGB” images ( Insert_Image() ), then the system needs to reserve a number of color map entries. These “fixed colors” will be loaded with a fixed table of colors for use in “dithering” the lighted faces (or RGB images). If “no fixed colors” is specified, it means that when a light appears, the system will automatically take about half of the total available colors (the regular “number of colors”). “Fixed colors = 0”, for comparison, will force the allocation to zero.

You can use “fixed colors = ddd” to tell the system to take a particular number. This might be of interest if you want extra precision to the dithering, or if you want extra colors left available for other operations besides dithering. If you do specify a value, only cubes of integers - 8, 27, 64, 125, 216, etc. - are meaningful (other values are rounded down). The system creates a “color cube” with each axis (red, green, and blue) having an equivalent number of intensity gradations, for a total of “ddd” colors. The number of colors specified must be less than the number of colors available on the device.

Alternately, you can specify a “color box” (a parallelepiped) for dithering with the format “fixed colors = (red_count,

green_count, blue_count)” where red_count * green_count * blue_count is less than the available number of colors. This is useful, for example, when you know in advance your scene will have far more blue objects than red, green, or yellow. To insure proper dithering (especially since specular highlights are not the object’s color) HOOPS requires at least two colors for each color axis.

The default is “no fixed colors”.

[no] force grayscale [= on | off]

Forces grayscale throughout the scene. Gray levels are calculated with HOOPS’ standard conversion system, 0.3*red + 0.5*green

  • 0.2*blue. Grayscale can also be forced on a per-segment basis. See the “force grayscale” option in Set_Rendering_Options(). The default is “no force grayscale”.

[no] font table [= (font1, font2, …, fontN)]

When using the CGM3 driver, the user can explicitly set the font table that is written into the output file. The default font table that is used by the CGM3 driver consists of HOOPS’ generic fonts, i.e. “typewriter, sans serif, roman”. If the font table is set explicitly via this option, the generic fonts will be appended to the end of the font table. When used in conjunction with ::HIC_Set_Text_Font_Index(), the font table allows the user to reference fonts installed on the system, so that a viewer application can use system fonts when displaying the CGM3 file. The default is “no font table”.

[no] fullscreen [= on | off]

When HOOPS is working in stand-alone mode, this setting creates a borderless window that extends to the borders of the desktop. NOTE: For the vast majority of applications that use an external windowing system such as MFC or Qt, this setting will not cause the application to run in fullscreen mode. For these applications, users need to write user interface code to go into fullscreen mode. The MFC and Qt sample applications contained on the HOOPS/3dAF distribution both contain reference code showing how to do this. The default setting is “no fullscreen”.

[no] gamma correction [= on | off]

The relationship between numeric color values in the frame buffer and the luminance of the screen pixels is usually expressed by a nonlinear curve. Gamma correction is a process that adjusts these color values to produce uniform results on cathode-ray tubes. An evenly increasing grey-ramp, for example, will look too dark if not corrected. HOOPS can perform the necessary compensation, or pass the colors through unchanged. Usually, you’ll want to let HOOPS fix the colors. Some graphics hardware allows you to control the gamma correction by using a system utility. In that case, you need to prevent HOOPS from performing the correction as well, or the colors may tend to look “washed out”. The default is “no gamma correction”.

[no] gpu preference = [default | high performance | specific = xxx ]

Available for DX11 only: Specify which GPU to use when running Visualize applications. This option only affects windows created using the DirectX11 driver, and should be specified before the first update is called on any segment whose ancestors include a DirectX11 driver segment.

(Note: This option is not available for C# users using D3DImage.)

Visualize will follow the same behavior as before the gpu preference option was made available.

default

Visualize will automatically detect and use the GPU that is likely to yield the highest performance. This option is enabled by default.

high performance

Visualize will automatically detect and use the integrated GPU.

integrated

When using the “specific” option another suboption is required, which represents the name of the GPU to use:

specific

HC_Set_Driver_Options("gpu preference = specific = Nvidia GEForce 1060");

The GPU name must match exactly one of the GPU names returned by Visualize to the user. These can be retrieved using Show_Device_Info(“available gpus”).

[no] gpu resident = [on|off]

Instructs the driver to keep all image data cached on the hardware when possible. Setting this option allows for efficient render to texture without the need for texture data to come to the CPU and back. Only supported in our dx11, and opengl2 drivers and only relevant when driver is being used to render to image. The default is “no gpu resident”.

hardcopy resolution = (ddd)

Specifies resolution in DPI of “pixel data” (i.e., shaded and z-buffered images) for raster hardcopy devices (i.e. PostScript and frame buffer CGM) and for clipboard images when using the MSW display driver. Specifying the “pixel data” resolution small compared to device resolution facilitates ouput files of manageable size. The default is “hardcopy resolution = 75”.

[no] isolated [= on | off]

Allows a driver to be spawned on a separate thread. Used for background printing or multiple views. While view-level changes (e.g. camera settings) are allowed alongside the background process, structural changes (e.g. geometry insert/delete> are not. This option should be used in conjunction with ::Update_One_Display() , as the Update_Display will ignore the driver which uses this setting. Note that since some operating systems (including Windows) automatically spawn separate threads to inform applications about expose events, it is wise to always use this option on drivers that are to be updated with Update_One_Display, even in applications that do not explicitly use multiple threads.

[no] landscape orientation [= on | off]

Pen plotter and laser printer drivers normally print with the smaller paper dimension laid out as the width of the scene and the greater paper dimension as the height. “Landscape orientation” turns the picture 90 degrees, so that the width is greater than the height. The default is “landscape orientation”, and can be changed back with “no landscape orientation”. Only the hardcopy drivers pay attention to this option.

[no] light scaling [= fff]

In normal mode, HOOPS scales down the total brightness of a scene based on the number and colors of lights present in the scene (including ambient light - see Set_Color()). By default, HOOPS scales the R, G, and B components of lights present so that the sum of the largest term (e.g. R) equals 1.0. For the purposes of computing a light scaling, all spotlights (if there are any) are treated as if they were just one light.

The “light scaling” option allows the user to override the calculated light scale and replace it with an explicit fixed scaling factor. For example, if you have three white-colored lights in your scene (and no ambient light), the default scale factor would be 3.0. If you know the lights are spread well apart and don’t all simultaneously illuminate any one face, then a factor of 2.0 or so could be used to brighten up the scene. A factor that’s too small will make the scene white and washed out. A factor that’s too large will make it very dark. As with all driver options, this setting must be set at or above the driver segment (e.g. “?Picture” or “/driver/whatever/window0”) to have any effect. The default is “no light scaling”.

[no] locater transform [= (A, B, C, D, E, F) ]

The locater transform option is driver specific. It currently only affects the HPGL and HPGL2 drivers and is used to control page margins. For those drivers, the values are interpreted as width, left, right, height, bottom and top, respectively. The default is “no locater transform”, which is equal to all zeroes.

marker drawing [= fastest | nicest]

This option controls whether HOOPS will attempt to use hardware acceleration to draw variable-sized markers (these are enabled via ::Set_Variable_Marker_Size). If the graphics hardware is available and certain conditions are met, the drawing performance of variable sized markers will be improved, but at the potential cost of minor drawing artifacts. The default is “nicest”.

There are a number of requirements for the ‘fastest’ option:

  • The markers must be inserted not as individual markers but rather as the vertices of a shell.

  • The marker symbol must be “(*)” or “[*]” (i.e. a filled circle, or a filled square).

  • The filled square symbol will perform significantly faster than the filled circle symbol, and is also more likely to be HW-accelerated.

  • The driver must be DX11, OpenGL or OpenGL2.

  • Older graphics cards may not have the required hardware capabilities for HW-accelerated, variable-sized markers.

  • Filled circles will not be as nicely rounded as those drawn without hardware acceleration.

  • Marker size will be limited to what the hardware is able to provide (often 64 pixels).

[no] number of colors [= ddd]

If the device at hand is a color frame buffer, “number of colors” restrains HOOPS to using only the specified number of hardware color map entries. This can be useful when the screen is being shared by more than one activity. If “first color” is not also specified then HOOPS attempts to ask the system which map entries are free. “No number of colors”, on the other hand, tells HOOPS to use all the color map entries it can get on the current device. The default is “no number of colors”.

[no] output format [= string]

The output format option is driver specific. See the appropriate driver chapter of the HOOPS Installation Guide for details. This option allows certain drivers to output graphics commands in different formats, e.g. encapsulated postscript versus postscript. The default is “no output format”.

pen speed = (fff)

“Pen speed” slows down the drawing speed on pen plotter devices. This can help the drawing pen lay the ink down smoothly. The value is the fraction of full speed that you want, with a value of 1.0 being as fast as possible and 0.0 being a dead stop. The default value is “pen speed = 1.0”.

[no] physical size [= (width, height)]

“Physical size” overrides the normal HOOPS opinion of the size of your screen. The primary use is to allow circles to remain circular when a different size or shape monitor is plugged in. The values are in centimeters. The default value is “no physical

size”, which means HOOPS should use a default value that’s built into each device driver.

[no] post world scale [= fff]

Sets a world scale value used by post-process effects such as ambient occlusion. If not set, scale is computed based on scene bounding.

quick moves preference = xor | overlay | default

Sets the algorithm used when the quick moves heuristic setting in a segment is “on”. Using “overlay” will provide the most visually correct results, however it is not a supported option on some of our drivers. With “default”, 3dGS will use whatever the default is for that driver, which is generally “overlay” for 3D drivers and “xor” for 2D drivers. If users specify a comma separated list, 3dGS will use each preference in that order contingent on it being supported by the driver. The default setting is “quick moves preference = default”. IMPORTANT NOTE: this setting has no effect when the quick moves = spriting heuristic is being used.

A setting of “overlay”, or “xor” causes the geometry in that segment to be drawn immediately to the scene without requiring a full update. This results in the rapid drawing of the geometry in the segment and is often used in applications for drawing zoom-box geometry or to move objects around the scene. With an “overlay” setting, 3dGS will try to use driver dependent logic to draw the geometry without having to use “exclusive or” logic, that can cause the geometry colors to behave in unusual ways. When using “xor” the visible colors will be accurate when the geometry is drawn over the window background, but will probably not be accurate when the geometry happens to be on top of other geometry.

If you set your quick moves preference to “overlay” and there’s no usable accumulation buffer in the opengl driver, HOOPS will attempt to use color-only spriting just like the synthetic swap buffers.

[no] selection proximity [= fff]

The “selection proximity” controls how far away your cursor can be from an object on the screen and still have it select the object. Within that radius, the nearest object is selected. The floating-point value is in centimeters; specifying it as zero makes it very hard to point at anything; specifying it as a large distance may make the system do a bit more work and might surprise the user. “No selection proximity” allows testing the entire screen for the object nearest the cursor. The default is “no selection proximity”.

shadow preference = software | hardware | soft opengl

Determines the method used internally for shadow generation. Default is “software”.

[no] special events [= on | off]

When this is on, the driver is requested to generate and queue any “special” events it’s familiar with, when and as they occur. Most often, special events are used by the driver - - if they are used at all - to notify your program of changes in an external window manager, such as an “iconify” or a “window resize”. At present, there are no standard special events; if they’re available at all they’ll be documented in the driver release notes. The default is “no special events”.

[no] spotlight interpolation [= vertex | pixel ]

The interpolation of light across shell faces can result in incorrect rendering when the interpolation is based on values set on the vertices of each face. This is particularly noticeable when using spot lights with coarsely tesselated models. To minimize the unwanted effects of vertex interpolation, users can set “spotlight interpolation = pixel”, which instructs 3dGS to use texturing that mimics the effect of the spotlight targeted to the center of the face, and which should result in a more correct rendering. The default setting is “vertex”.

[no] stencil = [on/off]

Affects video memory usage. It can be set to request a hardware stencil buffer for convex clip regions at the expense of a little video memory. With the default setting “off”, software code is used for clip regions (see Set_Polygonal_Clip_Region) at quite a severe performance penalty.

[no] stereo [= on | off]

Enables stereo viewing for the driver. This option is only available for the OpenGL1 driver and must be enabled at driver start-up.

[no] subscreen [= (fff, fff, fff, fff)]

The four “fff” floating-point numerals represent a left-right-bottom-top window in the usual -1.0 to +1.0 coordinate system. This option puts a “super-window” around the usual top-level window. Note that some window managers’ boundaries allow windows that go off the edge of the physical screen. On those machines, values outside the -1.0 to +1.0 range are legal and reasonable.

The effect of “subscreen” is to make the physical screen look as if it were suddenly only that big. Locater device coordinates will be in terms of the subscreen, rather than the full screen. Also, if a user does a windowing-system “resize” on the outer window, this will show up as an automatic change in the subscreen display option attached to the picture segment. (If there was no option on that segment, one will be added.)

“Subscreen = (-1, 1, -1, 1)” is equivalent to “no subscreen”, and is the default.

[no] subscreen moving [= on | off]

This is a windowing-system option. If “no subscreen moving” is in effect, the user will not be permitted to move the main graphics window around on the screen. The default is “subscreen moving”.

[no] subscreen resizing [= on | off]

If “no subscreen resizing” is in effect, the user will not be permitted to interactively change the size of the main graphics window. This option is not meaningful unless “subscreen moving” is enabled. This is a windowing-system option. The default is “subscreen resizing”.

[no] subscreen stretching [= on | off]

If “no subscreen stretching” is in effect, the user will not be permitted to change the height-to-width ratio of the main graphics window. It will still be possible to scale the subscreen up or down symmetrically. This option is not meaningful unless “subscreen resizing” is enabled. The default is “no subscreen stretching”.

[no] text preference [= default, vector, raster]

With “text preference = default”, text is drawn according to what the specific driver prefers. In general, this means 3d characters will be drawn as vectors and 2d characters will be drawn as rasters.

The “text preference = vector” option causes both 3d and 2d characters to be drawn as vectors. In some cases (such as when printing from the MSW driver), rasterized characters should be avoided, and this option provides that capability. Default is “default”.

[no] title [= string]

Similar to “border” and “control area”. If HOOPS is running within an external windowing system, then “title” requests the external system to put the specified label on the outermost graphics window, if the window manager implements such an operation. The default takes the title from the “application” system option.

[no] update interrupts [= on | off]

This option tells HOOPS to listen for HOOPS ‘events’ during an update cycle.

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 setting is “update interrupts=on”.

[no] use colormap ID [= ddd]

Use in conjunction with “Use window ID”, “Use colormap ID” allows different HOOPS windows to share colormaps with the already created window, thus reducing the likelihood of color flashing. This is only available on certain drivers. The default is “no use

colormap ID”.

[no] use window ID [default=ddd|image key=ddd]

This option allows you to provide a handle to a rendering context to which HOOPS can draw. Should only be set once per driver - result of setting it multiple times is undefined. You can pass in a decimal or hexidecimal encoding of the window ID. If you want to provide a hexadecimal encoding, you may need to prepend the encoding. Please check whether your implementation of sprintf prepends ‘0x’ to your hexidecimal value when using ‘p’. Note that if you use ‘ld’ instead of ‘p’, your code will not be portable to 64-bit Windows.

If you are using “default”, then you are typically providing a handle to a native system window. If you use “image key” then you are providing a key to a HOOPS image to which HOOPS will then render . The default setting is “no use window ID”.

[no] window opacity [=ddd] Sets the window background opacity. Only available for offscreen windows, and only supported on opengl2 and dx11 drivers. Opacity value should be between 0 and 1. If a value outside this range is specified, the value is clamped to within this range. This feature is incompatible with the bloom post-process effect.

[no] write mask [= ddd]

The write mask option is driver specific. See the appropriate driver chapter of the HOOPS Installation Guide for details. The default is “no write mask”, which is zero.

The Driver Options attribute on the “?Picture” segment can, on most systems, be given a new initial value by means of the environment variable “HOOPS_PICTURE_OPTIONS”. Likewise, “?Hardcopy” can be adjusted via “HOOPS_HARDCOPY_OPTIONS”. The value of “HOOPS_DRIVER_OPTIONS”, if used, is applied at the topmost level of the tree, and so can be overridden with “Picture” - and “Hardcopy” -specific options. ISO Latin-1 characters can be used in the “title” option. See table in Insert_Text() . All ‘fast silhouettes’ will be drawn with the silhouette-edge color that is set at the driver-instance segment (for example, /driver/opengl/window0).

See also

HC_Set_Rendering_Options, HC_Set_Heuristics, HC_Show_Device_Info, HC_Get_Selection.

NOTES

Parameters

list – - A quoted string or a string variable containing a list of the desired option settings.