Tips and tricks » Troubleshooting

Various tricks to overcome common building and rendering issues.

Building issues

If your project suddenly stops building after Magnum upgrade, check these things:

  • If the building fails on CMake step, be sure that you have up-to-date FindCorrade.cmake, FindMagnum.cmake and other CMake modules in your project (FindSDL2.cmake). They are contained in modules/ directory of Magnum sources (and sources of other projects) also are installed into share/cmake/Magnum.
  • In some cases when the changes done to build system are too drastic, recreating the build dir or clearing CMake cache is needed, but this is a very rare occasion.
  • The library is constantly evolving, thus some API might get deprecated over time (and later removed). Either build the libraries with BUILD_DEPRECATED or switch to non-deprecated features. See Downloading and building for more information.

Rendering issues

If you are experiencing the so-called "black screen of death", weird behavior or crashes on GL calls, you might want to try these things:

  • Enable debug output to see more detailed errors, warnings and performance hints. You can do that easily through the --magnum-gpu-validation command-line option or an environment variable.
    • If you are on Mac, the native OpenGL implementation doesn't support this. Instead you can manually verify that no OpenGL error was emitted.
  • Check that you use only extensions that are available on your system.
  • Check that you didn't exceed any implementation-defined limit (see Magnum GL Info output for a list of all of them).
  • If using framebuffer objects, check that they are complete.
    • Rendering to three-component GL::TextureFormat works on some GPUs but not others. TO avoid platform-dependent issues, always use one-, two- or four-component formats.
  • Change framebuffer clear color to something else than black to verify that at least something is drawn. The engine sets it to 0x1f1f1f_rgbf by default to help you a bit in this regard.
  • If nothing is drawn, use GL::PrimitiveQuery to check that at least some primitives were generated. Use GL::SampleQuery to check whether fragments were drawn.
  • Verify that the mesh is properly set up — nonzero vertex/index count, matching type in buffer and vertex specification, properly set up index buffer and index count for indexed mesh. If you specified index range, be sure that all indices fall into it, otherwise you would get undefined behavior.
  • Try disabling the depth test, face culling and other renderer features that might cause fragments to be discarded.
  • Verify that your projection and transformation matrix is properly set up — try drawing points instead of triangles, to see if they are in proper places at least.
  • For custom shaders you can Validate them. Check that all used uniforms and attributes have proper locations. Try reducing it until it is able to draw something, possibly also with some simpler mesh.
  • Magnum tracks the OpenGL state to improve performance, but the tracker can get confused if you or any other library are doing OpenGL calls outside of Magnum. For that to work, you need to reset the state tracker on boundaries between 3rd party and Magnum calls into GL. The other library also needs to be aware of this fact (either setting all state explicitly every time or having similar ability to reset its state tracker), otherwise you may need to save and restore GL state manually for that library to work.

Debugging rendering

  • Use GL::TimeQuery to find hot spots in the rendering code.
  • Mark relevant parts of code to find them easier in the debugger.
  • Use ApiTrace or RenderDoc to trace the program call by call, verify buffer and texture contents, vertex binding and count of generated primitives, rendered fragments and time spent in various calls.