Tutorial 130: Run CNA on Desktop OpenGL 4 (OPENGL4)

CNA Tutorials  ·  CNA snapshot 009d40f5

Most of CNA's OpenGL choices are profiles of one implementation, EasyGL, that speaks OpenGL ES 2/3, WebGL or desktop GL 3.3. OPENGL4 is the exception: a renderer family of its own, with its own hand-written function loader, its own draw code and no dependency on the easy-gl or meta-gl sibling checkouts. It asks the platform for a desktop OpenGL 4.1 core-profile context, runs on whatever newer core context the driver grants, and refuses anything older. On a 4.3+ context it also unlocks compute shaders and storage buffers.

In this tutorial you will build CNA with OPENGL4 twice — once on the default SDL3 platform and once with no SDL at all, on native X11 — write a small program that prints what the renderer reports, run CNA's own OPENGL4 tests, and see what to do when the driver grants less than 4.1.

What OPENGL4 is, precisely

Get the sources and packages

Lay the checkouts out side by side. sharp-runtime must be its next branch too; the default branches lack the Resources and Xml.Serialization components this CNA snapshot needs.

mkdir cna-workspace && cd cna-workspace
git clone -b next https://github.com/libcna/cna.git
git clone -b next https://github.com/libcna/sharp-runtime.git
cd cna
git submodule update --init      # SDL3, SDL_image, SDL_mixer, googletest, draco

You do not clone easy-gl or meta-gl for this renderer. (An ordinary Linux build with the default OPENGLES3 renderer does; that is the difference.)

On a Debian-family system the package set CNA's own SDL-free X11 workflow installs for its GL leg is a good starting point. Only libX11, libXext and XKBlib.h are mandatory for the native X11 platform; each of the other X libraries switches on one capability.

sudo apt-get install --no-install-recommends \
  g++ cmake ninja-build pkg-config \
  libx11-dev libxext-dev libxrandr-dev libxi-dev libxcursor-dev libxfixes-dev \
  libxss-dev libxtst-dev libxkbcommon-dev \
  libgl1-mesa-dev libglx-dev libgl1-mesa-dri

Configure and build: the default SDL3 platform

The shortest route changes one option. SDL3 (built from CNA's vendored submodule) supplies the window and the GL context; OPENGL4 supplies everything after that.

cmake -S . -B build -DCNA_GRAPHICS_RENDERER=OPENGL4
cmake --build build --target cna_demo_2d --parallel

Near the top of the configure output you should see CNA: Using OPENGL4 (real desktop OpenGL 4.x core profile) graphics renderer. Run CNA's renderer-agnostic 2D sprite demo for a handful of frames and exit:

./build/cna_demo_2d --smoke 6

--smoke N makes the demo exit cleanly after N drawn frames, so a zero exit status means the whole path — window, GL 4.1 core context, function loading, sprite draws and swap — worked.

Configure and build: no SDL at all (native X11 or Wayland)

Because OPENGL4 gets its context from the platform layer, it can run on CNA's native platforms, which talk to Xlib or the Wayland protocol directly. This is CNA's “CNA without SDL” configuration:

cmake -S . -B build \
  -DCNA_GRAPHICS_RENDERER=OPENGL4 \
  -DCNA_PLATFORM=X11 \
  -DCNA_ENABLE_SDL=OFF \
  -DCNA_AUDIO_PLATFORM=NULL \
  -DCNA_ENABLE_NET=OFF
cmake --build build --target cna_demo_2d --parallel

Every option other than the renderer is what CNA's own SDL-free workflows pass. CNA_ENABLE_SDL=OFF means no SDL source is fetched, built, found or linked, so the audio platform must not be SDL either (NULL here; ALSA on Linux gives you sound). CNA_ENABLE_NET=OFF drops the networking module; leave it out if you want it. Re-run the command with different -D values in the same build directory to change platform; CMake updates its cache.

“None” in the last column is deliberate: no GitHub workflow in this snapshot names OPENGL4. CNA's SDL-free X11 workflow builds the same shape with OPENGL33, VULKAN, SOFTWARE and HEADLESS, not with OPENGL4. The renderer's own test suite is registered and is described in Run CNA's own OpenGL4 tests.

What CMake refuses, and why that helps

• -DCNA_ENABLE_SDL=OFF with an SDL platform, SDL audio or one of the four SDL-linking renderers is a configure FATAL_ERROR that names what needs SDL. Nothing is substituted.
• -DCNA_PLATFORM=X11 or WAYLAND on a machine that cannot build it is a FATAL_ERROR naming the packages to install; it never falls back to SDL3.
• CNA_PLATFORM=TERMINAL accepts only CPU renderers, so OPENGL4 is refused there. HEADLESS has no GL context service.
• Renderer names are case-sensitive in CMake: -DCNA_GRAPHICS_RENDERER=opengl4 is an unknown graphics renderer error; only the 25 exact spellings are accepted.
• OPENGL4 cannot share a binary with PORTABLEGL. PortableGL defines the global gl* symbols itself, so linking it beside a real-GL renderer would be a duplicate-symbol error; CMake refuses the combination up front.

Write a probe program

Place a small consumer project beside the checkouts, using the same add_subdirectory pattern as Tutorial 03:

cna-workspace/
  cna/
  sharp-runtime/
  gl4-probe/          <-- new
    CMakeLists.txt
    main.cpp

cmake_minimum_required(VERSION 3.20)
project(Gl4Probe LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# Choose the renderer before CNA is added. Platform, audio and SDL options are passed
# on the command line so the same file serves the SDL3 and the SDL-free build.
set(CNA_GRAPHICS_RENDERER "OPENGL4" CACHE STRING "CNA graphics renderer")
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../cna ${CMAKE_BINARY_DIR}/cna)

add_executable(gl4_probe main.cpp)
target_link_libraries(gl4_probe PRIVATE CNA)

The program opens a window, asks the graphics device which renderer it really got and how it answers five capability questions that matter for OpenGL 4, draws one frame, and exits:

#include "Microsoft/Xna/Framework/Game.hpp"
#include "Microsoft/Xna/Framework/GraphicsDeviceManager.hpp"
#include "Microsoft/Xna/Framework/Color.hpp"
#include "Microsoft/Xna/Framework/Graphics/GraphicsDevice.hpp"
#include "Microsoft/Xna/Framework/Graphics/GraphicsProfile.hpp"
#include "CNA/GraphicsCapability.hpp"

#include <cstdio>
#include <string_view>

using namespace Microsoft::Xna::Framework;
using namespace Microsoft::Xna::Framework::Graphics;
using CNA::GraphicsCapability;

class GlFourProbe final : public Game {
public:
    GlFourProbe() : graphics_(this) {
        getWindowProperty().setTitleProperty("OPENGL4 probe");
        graphics_.setPreferredBackBufferWidthProperty(640);
        graphics_.setPreferredBackBufferHeightProperty(360);
        // Reach is the default profile and allows one render target; HiDef allows four.
        graphics_.setGraphicsProfileProperty(GraphicsProfile::HiDef);
    }

protected:
    void Initialize() override {
        Game::Initialize();
        auto& device = getGraphicsDeviceProperty();

        const std::string_view name = device.GetGraphicsRendererName();
        std::printf("renderer: %.*s\n", static_cast<int>(name.size()), name.data());

        const auto yesNo = [&](GraphicsCapability capability) {
            return device.SupportsCapability(capability) ? "yes" : "no";
        };
        std::printf("MSAA %s, MRT %s, occlusion %s, compute %s, indirect draw %s\n",
                    yesNo(GraphicsCapability::MultiSampleAntiAliasing),
                    yesNo(GraphicsCapability::MultipleRenderTargets),
                    yesNo(GraphicsCapability::OcclusionQuery),
                    yesNo(GraphicsCapability::ComputeShaders),
                    yesNo(GraphicsCapability::IndirectDraw));
    }

    void Update(GameTime& gameTime) override {
        (void)gameTime;
        Exit();   // one frame is enough for a probe
    }

    void Draw(const GameTime& gameTime) override {
        (void)gameTime;
        auto& device = getGraphicsDeviceProperty();
        device.Clear(Color::CornflowerBlue);
        // No device.Present(): Game presents in EndDraw, after Draw() returns.
    }

private:
    GraphicsDeviceManager graphics_;
};

int main() {
    GlFourProbe game;
    game.Run();
    return 0;
}

Configure and build it. Use the SDL3 flags from the first section, or the native ones from the second:

cd ../gl4-probe

# SDL3 platform (default)
cmake -S . -B build

# ... or native X11, no SDL
cmake -S . -B build -DCNA_PLATFORM=X11 -DCNA_ENABLE_SDL=OFF -DCNA_AUDIO_PLATFORM=NULL -DCNA_ENABLE_NET=OFF

cmake --build build --target gl4_probe --parallel
./build/gl4_probe

The first output line is renderer: OPENGL4. The name is exactly the CNA_GRAPHICS_RENDERER spelling, and it is the device's real renderer, not a compile-time guess (see Tutorial 126 for why that distinction exists). CNA also logs CNA: graphics renderer: OPENGL4 once, at Info level on stderr, and the renderer logs the driver's GL_VERSION and GL_RENDERER strings when it initialises.

What OPENGL4 reports

These answers come from the renderer's own SupportsCapability switch plus the device-level derivations described in Tutorial 101. “Probe” means the answer is read from the live context, so it can differ between two machines running the same binary.

Beyond the 19 legacy capabilities, the renderer answers true for shadow sampling (directional, cascaded, point and spot) and image-based lighting in CNA's lit stock shaders, reports a real GL_TEXTURE_3D sampler path for custom effects, supports GPU timers (timestamp pairs, when the driver reports a non-zero counter width) and base-instance drawing (4.2+ or GL_ARB_base_instance), and stores all 20 classic XNA surface formats. Tutorial 133 shows how to read every one of these answers, plus limits and per-format usage, from the device's RendererCapabilityProfile.

See the 4.1 floor for yourself

Mesa normally answers a 4.1 core request with a 4.6 context, so you rarely see the floor. Mesa can be told to hand out a 4.1 context instead, which is exactly how CNA's own OpenGL4_Gl41Floor test (built when CNA_CNAEXT is on) gets one. Run the probe that way and compute should flip to no while indirect draw stays yes:

MESA_GL_VERSION_OVERRIDE=4.1 MESA_GLSL_VERSION_OVERRIDE=410 ./build/gl4_probe

Those two variables belong to Mesa, not to CNA, and other drivers ignore them.

Custom shaders on OPENGL4

A ShaderEffect on this renderer is desktop GLSL: the vertex and fragment sources reach the driver's compiler. There is one convenience: if a source's very first line is #version 300 es — the dialect CNA authors its own stock shaders in — the renderer rewrites it to #version 410 core and blanks the precision statement that follows, keeping line numbers intact so compiler diagnostics still name the line you wrote. Any other source is compiled as written, so you can also write #version 410 core yourself. Compute payloads must be #version 430 core and need the 4.3+ context above. See Tutorial 52 for the ShaderEffect API itself.

In the capability profile this shows up as ShaderDialectGlslDesktop being supported and the other dialect flags (OpenGL ES, Vulkan GLSL, HLSL, MSL, WGSL) being unsupported; Tutorial 133 shows how to ask.

Run CNA's own OPENGL4 tests

When CNA_BUILD_TESTS (on by default) is set, an OPENGL4 configuration registers its own tests, all labelled OpenGL4. They create a real GL context, so they need a display: either your desktop session, or a private virtual X server that CNA's launcher script starts for you.

# list what is registered
ctest --test-dir build -N -L OpenGL4

# build the smallest test (window + context + a 60-frame Clear/Present loop)
cmake --build build --target cna_test_opengl4_smoke

# run it against a private virtual X server that CNA's launcher starts and stops
sh tools/platform/x11_test_server.sh ./build/cna_test_opengl4_smoke

# or, from your own desktop session (the window opens on your screen)
ctest --test-dir build -R '^OpenGL4_Smoke$' --output-on-failure

The launcher needs Xvfb installed; without it the script exits with status 77 (“skipped”) instead of failing. The tests' DISPLAY is whatever you export, because CNA_TEST_DISPLAY defaults to empty and CNA no longer forces the live desktop display.

What the registrations cover, all verified from the renderer's example CMakeLists.txt:

• Own tests such as OpenGL4_Smoke, OpenGL4_Readback (pixel read-back), OpenGL4_3D, OpenGL4_RenderTarget2D, OpenGL4_MSAA and OpenGL4_Texture3D. Three more — OpenGL4_ModernFeatureDiscovery, OpenGL4_Gl41Floor (the 4.1-floor oracle described above) and a long-running OpenGL4_ModernStress soak — are registered only when the engine layer is on (-DCNA_CNAEXT=ON).
• 32 shared parity fixtures, registered as OpenGL4_Parity_<fixture>. These are renderer-neutral programs whose expected result is stated by the fixture's own assertions. They are not compared against real XNA. Only the EasyGL-backed identities, WEBGPU, SDL_GPU and OPENGL4 register them.
• A copy of the EasyGL example corpus rebuilt against OPENGL4 and registered as OpenGL4_EasyGLParity_<name>, on the reasoning that a program that proves a capability on EasyGL should pass here too.
• A GL-error gate: with KHR_debug available (Debug builds, or CNA_OPENGL4_DEBUG_OUTPUT=1 in the environment) the renderer prints [OpenGL4 GL Error] … for every error or high-severity message, and its CTests fail on that line. CNA_OPENGL4_DEBUG_OUTPUT=verbose also logs informational messages.

CNA's own renderer documentation records local runs of these suites on Wayland (EGL) and X11 (GLX). Those runs are CNA's account of its own machines and are not part of any automatic workflow; neither this page nor the site has re-run them.

When creation fails

With a multi-renderer build (Tutorial 126) you can keep OPENGL4 as the default and list OPENGLES3 or SOFTWARE after it in an explicit fallback chain. Fallback is off unless you opt in, and a renderer that cannot start is an error otherwise.

Next steps

• Tutorial 133: Read the renderer capability profile — the 32 features, 22 limits and per-format usage that go beyond SupportsCapability()
• Tutorial 131: Use the SDL_GPU renderer and Tutorial 132: WebGPU, native and in the browser — the other two renderers that received the same “modern graphics” work
• Tutorial 128: Load compiled XNA effects — the CNA_OPENGL4_COMPILED_EFFECTS option in context
• Tutorial 102: The OpenGL family — the EasyGL profiles, for comparison
• Tutorial 127: Choose platform, renderer and audio independently
• Renderers reference: the OPENGL4 entry