2.7. Graphics Preferences and Configurations

Goals

The Open Inventor graphics configuration management classes provide a platform-independent mechanism for chosing the best combination of graphics parameters and features available on your graphics hardware. It is no longer necessary to check all the pixel formats (on Win32) or all the visuals (on Unix) to find the best one. Of course, what is “best” depends on the graphics hardware capabilities of your system and on the set of graphic preferences you specify.

You can specify many different criteria: double/single buffer, raw stereo, OpenGL acceleration, overlays, Z-buffer depth size, RGBA/indexed colors and size, accumulation buffer and size, stencil buffer and size, etc. Each criterion may be required, forbidden, or preferred. The preferred criterion can be weighted with values ranging from 1 to the largest integer. The sum of all weights determines if one graphics configuration is better than another.

Description

The graphics configuration management classes define three kinds of objects:

You define a graphics configuration template containing your graphics preferences and pass it to the graphics device. The graphics device stores the available graphic configurations and sorts them from best to worst according the given configuration template.

All the viewers based on SoXtGLWidget can use the graphics configuration template: the inherited method named setGraphicTemplate() can be used to specify the OpenGL graphic preferences.

In a viewer derived from SoXtGLWidget , a graphics device is internally used to find the best graphic config if a template is given via the setGraphicConfigTemplate() method. If none is found (because the template is too restrictive), then the template is ignored. The default values of a OpenGL graphics template are the same as the ones that the SoXtGLWidget heuristic looks for when building an OpenGL widget:

  • Double buffer is REQUIRED.

  • Stereo buffer is FORBIDDEN.

  • Accelerated OpenGL is REQUIRED.

  • Depth buffer is REQUIRED; its size is greater than 0.

  • Non-indexed color is REQUIRED; its R/G/B/A sizes are greater than 0.

  • Indexed color is FORBIDDEN.

  • Accumulation buffer is PREFERRED; its R/G/B/A sizes are greater than 0.

  • Stencil buffer is PREFERRED; its size is greater than 0.

  • Overlays are PREFERRED.

  • Full-scene antialiasing is FORBIDDEN.

Every preference can be specified as an integer (1, by default); the sum of all preference weights determines if a particular graphics configuration is better than another one.

Figure 2.4. Graphic template, configuration, and device public classes



How to Use a GL Graphic Template

The following example shows how to define graphic preferences and how to set them into an Examiner Viewer. It shows that preference levels are limitless because they can be SoGraphicConfigTemplate::PREFERREDSoGraphicConfigTemplate.PREFERREDGraphicsConfigTemplate.PREFERRED (equal to 1), 2, 3, 4, 10, 100, 1000, and so forth.

Example 2.5. SoGraphicConfigTemplate object can be given to a viewer

// The graphic template definition.
SoGLGraphicConfigTemplate gTemplate;

// Double buffering is preferred (preference weight is 1 by default).
gTemplate.setDoubleBuffer(SoGraphicConfigTemplate::PREFERRED);

// Raw stereo absolutely must be disabled.
gTemplate.setStereoBuffer(SoGraphicConfigTemplate::FORBIDDEN);

// Z-buffer is required and its size has to be at least 24.
gTemplate.setDepth(SoGraphicConfigTemplate::REQUIRED,
24, INT_MAX);

// Non indexed colors are highly preferred (preference weight is 4)
// and the R/G/B/A sizes have to be 8 or greater.
gTemplate.setRGBAColor((SoGraphicConfigTemplate::Preference)4,
8, INT_MAX, 8, INT_MAX, 8, INT_MAX, 8, INT_MAX);

// Init SoXt
Widget myWindow = SoXt::init("myapp");

// Create an examiner viewer
SoXtExaminerViewer *myViewer = new SoXtExaminerViewer(myWindow);

// The graphic template is given to the examiner viewer
myViewer->setGraphicConfigTemplate(&gTemplate);
       
// The graphic template definition.
SoGLGraphicConfigTemplate gTemplate = new SoGLGraphicConfigTemplate();

// Double buffering is preferred (preference weight is 1 by default).
gTemplate.SetDoubleBuffer(SoGraphicConfigTemplate.Preferences.PREFERRED);

// Raw stereo absolutely must be disabled.
gTemplate.SetStereoBuffer(SoGraphicConfigTemplate.Preferences.FORBIDDEN);

// Z-buffer is required and its size has to be at least 24.
gTemplate.SetDepth(SoGraphicConfigTemplate.Preferences.REQUIRED,
24, int.MaxValue);

// Non indexed colors are highly preferred (preference weight is 4)
// and the R/G/B/A sizes have to be 8 or greater.
gTemplate.SetRGBAColor((SoGraphicConfigTemplate.Preferences)4,
8, int.MaxValue, 8, int.MaxValue, 8, int.MaxValue, 8, int.MaxValue);

// Create an examiner viewer
SoWinExaminerViewer myViewer = new SoWinExaminerViewer(this);

// The graphic template is given to the examiner viewer
myViewer.SetGraphicConfigTemplate(gTemplate);
       
// The graphic template definition.
SwGLGraphicsConfigTemplate gTemplate = new SwGLGraphicsConfigTemplate();

// Double buffering is preferred (preference weight is 1 by default).
gTemplate.setDoubleBuffer(GraphicsConfigTemplate.PREFERRED);

// Raw stereo absolutely must be disabled.
gTemplate.setStereo(GraphicsConfigTemplate.UNNECESSARY);

// Z-buffer is required and its size has to be at least 24.
gTemplate.setDepth(GraphicsConfigTemplate.REQUIRED, 24, Integer.MAX_VALUE);

// RGBA mode is required
gTemplate.setColorIndexed(GraphicsConfigTemplate.UNNECESSARY);

// Create an examiner viewer
SwSimpleViewer myViewer = new SwSimpleViewer(SwSimpleViewer.EXAMINER);

// The graphic template is given to the examiner viewer
myViewer.getArea().setGLGraphicsConfigTemplate(gTemplate);
       


It is recommended to use in an Open Inventor application either:

  • the setGraphicConfigTemplate method and graphic config template, or

  • setPixelFormat, setNormalVisual, setOverlayVisual methods,

but not both.

However, if setGraphicConfigTemplatehas been called, then when setPixelFormat is called, several PREFERRED template preferences are changed either to REQUIRED or to FORBIDDEN to ensure that the new pixel format is one of the best ones.

If setGraphicConfigTemplate has been called, several methods, including setDoubleBuffer and setStereo, will automatically modify the current template to indicate that the new state is REQUIRED.

setRGBAColor sets the integer color buffer depth (0-32 bits). For floating point rendering, use setFloatRGBAColor.

The following example shows how to get pixel format or visual information directly from the graphic configuration.

Example 2.6. SoXt/WinGLGraphicConfig object stores pixel format/visual information data

SoGLGraphicConfigTemplate gTemplate;
...
SoGLGraphicDevice *dev = ...;
SoGLGraphicConfig *gc = (SoGLGraphicConfig *)dev.getBestGraphicConfig(gTemplate);
if (gc != NULL)
  {
#ifdef WIN32
  int pixelFormat = ((SoWinGLGraphicConfig *)gc)->getPixelFormat();
#else
  XVisualInfo *vis = ((SoXtGLGraphicConfig *)gc)->getXVisualInfo();
#endif
  }
       


The following example shows how to get pixel format or visual information directly from the graphic configuration.

Example 2.7. SoWinGLGraphicConfig object stores pixel format/visual information data

SoGLGraphicConfigTemplate gTemplate;
...
SoGLGraphicDevice dev = ...;
SoGLGraphicConfig gc = (SoGLGraphicConfig)dev.GetBestGraphicConfig(gTemplate);
if (gc != null)
{
  int pixelFormat = ((SoWinGLGraphicConfig)gc).GetPixelFormat();
}