From 9e3680e3e1680dbf040d0cdd8638ec8d524b7ecf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 20 Jan 2021 15:00:42 +0100 Subject: [PATCH] doc: update the GL troubleshooting docs a bit. And use a bit more English in there. --- doc/troubleshooting.dox | 54 +++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/doc/troubleshooting.dox b/doc/troubleshooting.dox index 4231c4326..f70d9054d 100644 --- a/doc/troubleshooting.dox +++ b/doc/troubleshooting.dox @@ -49,20 +49,25 @@ things: @section troubleshooting-rendering Rendering issues -If you are experiencing so-called "black screen of death", weird behavior or -crashes on GL calls, you might want to try these things: +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: -- Verify that @ref GL::Renderer::error() "no OpenGL error was emitted". -- Check that you use only extensions that are - @ref GL::Context::isExtensionSupported() "available on your system". -- Check that you didn't exceed any implementation-defined limit (see - @ref magnum-gl-info output for list of all of them). - Enable @ref GL::DebugOutput "debug output" to see more detailed errors, warnings and performance hints. You can do that easily through the `--magnum-gpu-validation` @ref GL-Context-command-line "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 + @ref GL::Renderer::error() "no OpenGL error was emitted". +- Check that you use only extensions that are + @ref GL::Context::isExtensionSupported() "available on your system". +- Check that you didn't exceed any implementation-defined limit (see + @ref magnum-gl-info output for a list of all of them). - If using framebuffer objects, @ref GL::Framebuffer::checkStatus() "check that they are complete". + - Rendering to three-component @ref GL::TextureFormat works on some GPUs + but not others. TO avoid platform-dependent issues, always use one-, + two- or four-component formats. - Change @ref GL::Renderer::setClearColor() "framebuffer clear color" to something else than black to verify that at least something is drawn. The engine sets it to @cpp 0x1f1f1f_rgbf @ce by default to help you a bit in @@ -75,31 +80,32 @@ crashes on GL calls, you might want to try these things: properly set up @ref GL::Mesh::setIndexBuffer() "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 @ref GL::Renderer::Feature::DepthTest "depth test", +- Try disabling the @ref GL::Renderer::Feature::DepthTest "depth test", @ref GL::Renderer::Feature::FaceCulling "face culling" and other renderer - features that might affect the fragments. -- Verify that your projection and transformation matrix is properly set up --- - try drawing points instead of triangles, to see if they are at least at - proper places. -- @ref GL::AbstractShaderProgram::validate() "Validate the shader", 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. + 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 @ref GL::AbstractShaderProgram::validate() "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. You can use @ref GL::Context::resetState() to reset the internal - state tracker. 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. + Magnum. For that to work, you need to + @ref opengl-state-tracking "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. @section troubleshooting-debugging Debugging rendering - Use @ref GL::TimeQuery to find hot spots in the rendering code. - @ref GL::DebugMessage::insert() "Mark relevant parts of code" to find them easier in the debugger. -- Use ApiTrace 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. +- 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. */ }