VTK/OpenGL Errors

OpenGL's error handling implementation is designed such that internal error flags remain set with the first error that occurred until they are explicitly checked. With this design it's important to check and clear the error flags regularly otherwise they can become unusable as code checking for errors ends up reporting earlier unrelated errors. In VTK 6.1 functions that make OpenGL calls have been instrumented with new OpenGL error management macros. A number of bugs that were detected by the new error checking and reporting have been fixed.

Changes to the coding standard for VTK 6.1 and beyond

In VTK 6.1 and code introduce after the following policy is recommended.

1. at public entry points into code that uses OpenGL clear the error flags without reporting errors. This guards against reporting unrelated errors, such as those caused by code outside of VTK. See vtkOpenGLClearErrorMacro
2. before returning from functions that made OpenGL calls check for and report OpenGL errors. This detects Open GL errors in the function/method where they occurred facilitating debugging and it clears error flags so that user code doesn't detect errors caused by VTK. See vtkOpenGLCheckErrorMacro

In summary: By calling vtkOpenGLClearErrorMacro at the top of a method that makes OpenGL calls, you isolate the code and prevent it from detecting any preceding errors. By calling vtkOpenGLCheckErrorMacro at the bottom of the method you clear the error flags and report any errors that have occurred in the method where they occurred.

VTK OpenGL error management macros

The following macros, which are found in vtkOpenGLError.h, can be used to detect and report, and/or silently clear OpenGL error flags. The intended usage pattern is to 1) call vtkOpenGLClearErrorMacro at the top of, and 2) vtkOpenGLCheckErrorMacro at the bottom of methods that make OpenGL calls. The macros maybe completely disabled via the CMakeLists variable VTK_REPORT_OPENGL_ERRORS. Note that in that case error flags are never cleared so that if an error occurs the flags will remain dirty making it impossible for anyone else to use them reliably.

vtkOpenGLClearErrorMacro()

Silently clear OpenGL error flags.

vtkOpenGLCheckErrorMacro(message)

Check and clear OpenGL's error flags. Report errors detected via vtkErrorMacro.

vtkOpenGLStaticCheckErrorMacro(message)

Check and clear OpenGL's error flags. Report errors detected via vtkGenericWarningMacro. This may be used in static methods and outside of vtkObjects.

Transitioning to VTK 6.1

When transitioning existing code and applications to VTK 6.1 you may see reports for previously undetected OpenGL errors in your codes or ctest output which will need to be cleaned up.

Apple Mac OSX

On the Mac if you ask VTK to render into an "invalid drawable" you will find that all subsequent OpenGL calls fail (until the drawable becomes valid) with INVALID_FRAMEBUFFER_OPERATION reported. The "invalid drawable" issue is not new (http://vtk.markmail.org/search/?q=invalid%20drawable). However, until now one could ignore this as OpenGL errors were not detected and reported. Going forward you will need to fix your code or disable new gl error detection and reporting. There are three approaches that could be taken:

1. Restructure your code so that windows are visible prior to VTK rendering. This is the recommended approach.
2. Make use of the new vtkRenderWindow::IsDrawable method to detect invalid drawable and avoid asking VTK to render until the drawable is valid. This is useful if one can't ensure window visibility for some reason.
3. As a last resort, you may disable OpenGL error detection via the VTK_REPORT_OPENGL_ERRORS CMake variable, allowing you to ignore the bug.