Skip to content

Instantly share code, notes, and snippets.

@deccer

deccer/troubleshoot.gl.md

Last active June 24, 2024 22:10
Show Gist options
  • Save deccer/dbc53d34a378009c23a432b071273abb to your computer and use it in GitHub Desktop.
Save deccer/dbc53d34a378009c23a432b071273abb to your computer and use it in GitHub Desktop.
Download ZIP
Troubleshoot - OpenGL
Raw
troubleshoot.gl.md

i was wondering if we should/could list common errors in the gl get started thing too, after debugcallback/renderdoc chapters or probably in some appendix, if you have more of those, let me know then we can compile those together into some comprehensive unfuck gl list

  • nothing works:

    • get rid of GLCALL/GLCHECK macros, most of them use glGetError incorrectly anyway
    • setup glDebugMessageCallback see here
    • your shaders could contain errors, make sure you check compile and linking state and fix according to what the error was highlighting

  • renderdoc crashes when i try to capture something from my project:

    • most likely some of your code is fucked, its rarely renderdoc being fucked in that case
    • make sure to hookup glDebugMessageCallback as stated above
    • in newer version of renderdoc it might not tell you that you are using an unsupported function and just crash because of that, therefore check that you are not using an unsupported function like bindless (glGetTextureXXXHandleARB/glMakeTextureResidentARB)

  • screen is black:

    • check if your screen is on/connected properly
    • camera (projection/view matrices are fucked) is not looking at the scene in question
    • no texture is sampled due to missing or wrong uvs => default value is 0 aka black (depends on the driver)
    • no shader bound (especially fragment shader)
    • fragment shader doesnt write anything to its output
    • no viewport is set/is too small
    • you might be rendering to a framebuffer, but not blitting that framebuffer to the default one
    • let clearcolor be something else than pure black
    • are you doing MRT?
      • if yes, check that you called the right gl{Named}DrawBuffers and not n times gl{Named}DrawBuffer, one per render target

  • screen is white:

    • perhaps your clearcolor is too, and no texture is sampled due to missing or wrong uvs => default value can be 1 aka white (depends on the driver)

  • no visible output:

    • check winding order and cullmode, you might be looking at the wrong side of your faces

  • exception when calling glDrawElements - aka "0xC0000005"

    • no indexbuffer is bound/associated to the current vao/inputlayout

  • exception when calling glDrawArrays / or worse the driver is crashing

    • you probably want to draw more primitives than you have in your vertexbuffer, check arguments of your glDrawArrays call

  • textures are black

    • no textures bound
    • are your textures complete? if not should produce an output in debug callback, so, go check that (hmm this might not be the case for glXXXTextureStorage i might take this one off the list)
    • no samplers bound (check your sampler objects if you use them as separate objects)
    • fucked uvs
    • you might be sampling from a corner of your texture where its actually black, check uvs

  • your tringle is black

    • smells like your vao is fucked. make sure you setup the attributes (and stride when binding le vbo using DSA)
    • fucked uvs?
    • forgot to bind a texture?

  • textures look funny, like a garbled version of the actual image

    • make sure your internalformat and actual pixel format match -> you probably used stb_image to load, but used 0 as the last parameter, and pixel data has 3 components, instead of the 4 (GL_RGBA) you told OpenGL about -> request 4 channels from stb_image

  • textures look like one color component is more prominent than others

    • colors are more shifted towards blue -> you probably messed up the format and asked for GL_BRG.. of sorts => make sure they match
    • colors are more shifted towards red -> original pixeldata was probably in BGR... but you asked for GL_RGB... of sorts => make sure they match

  • textures seem to work, but mesh also appears to be some ndotL-esque shaded, or black fog

    • did you generate mipmaps?

  • render artifacts, like small missing tiles on a floor

    • synchronization issues - perhaps a missing glMemoryBarrier at the right spot
    • ubo/ssbo alignment issue - check std140/430 rule in the glsl spec
    • binding multiple textures to the same slot - check your glBindTextureUnit calls
    • you might be using a float to index into a buffer to grab material/texture info, use a flat int

  • depth buffer not cleared

    • despite calling glClear(GL_DEPTH_BUFFER_BIT) => check if glDepthMask was set to GL_FALSE or migrate to glClearNamedFramebuffer()

  • no triangle on screen

    • you check renderdoc and wonder why the vertex list contains the same (perhaps even first element) only, for all vertices => make sure your glDrawElements(..., ..., GL_UNSIGNED_INT, ...) or whatever datatype your indexbuffer consists of matches that parameter

  • you are on a mac

    • port your engine to metal, seriously, no support for debug callback and anything > gl 4.1 is reason enough
    • you are getting UNSUPPORTED (log once): POSSIBLE ISSUE: unit 0 GLD_TEXTURE_INDEX_2D is unloadable and bound to sampler type (Float) - using zero texture because texture unloadable
      • you need to call glGenerateMipmap(GL_TEXTURE_2D) after glTexImage2D() or set max level to 0 if you dont need/want mips

  • you noticed your scene looks like as if z fighting is going on

    • check your depth buffer, near and far planes... try near 0.1f and 512/1024 as farplane
    • your depth buffer might be too small and is set to D16 only, set it to something D24 or D32
    • you use SDL2 and on your platform the default might be set to D16, find the SDL2_GL_Set_Attribute which sets the depth bits for the default fbo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment