gl.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Jeremiah van Oosten
 *
 * vgl OpenGL backend: draws a context's globe with OpenGL 3.3 or OpenGL ES 3.0, into the
 * host's framebuffer (design document, section 7.6). It is a consumer of the render interface
 * (vgl/render.h), linked separately as vgl_gl, and uses vgl only through the C API.
 *
 * The host creates the OpenGL context, makes it current and passes a function loader; the
 * backend never touches EGL, WGL or GLX. A minimal host, with GLFW:
 *
 *     static vgl_gl_proc load(void* user_data, const char* name)
 *     {
 *         (void)user_data;
 *         return (vgl_gl_proc)glfwGetProcAddress(name);
 *     }
 *
 *     vgl_gl_backend_create_info info = {.struct_size = sizeof(info)};
 *     info.get_proc_address = load;
 *     vgl_gl_backend* backend;
 *     vgl_gl_backend_create(context, &info, &backend);
 *
 *     // Each frame, in the host's render pass, after vgl_context_update:
 *     vgl_gl_backend_draw(backend, NULL);
 *
 *     vgl_gl_backend_destroy(backend);  // Before the context and the OpenGL context.
 *
 * State (NFR-08). The backend saves the following state when it draws, and restores it before
 * returning: the current program, the vertex array binding, the GL_ARRAY_BUFFER,
 * GL_COPY_WRITE_BUFFER and GL_PIXEL_UNPACK_BUFFER bindings, the active texture unit, the 2D
 * texture and sampler bindings of units 0 to 5, the unpack alignment, row length and skips,
 * GL_DEPTH_TEST, the depth function and write mask, GL_CULL_FACE, the cull face mode, the front
 * face, GL_BLEND, the blend functions and equations, primitive restart (where it exists) and,
 * for the reversed-Z convention, the clip control depth mode. It draws with the
 * host's framebuffer, viewport, scissor, depth range, color and stencil state unchanged, so a
 * stencil test or color mask the host leaves enabled applies to the globe as well.
 */
#ifndef VGL_GL_H
#define VGL_GL_H
 
#include <vgl/base.h>
#include <vgl/context.h>
#include <vgl/render.h>
 
/* Symbol visibility of the backend library, which is shared when vgl is. */
#if defined(VGL_SHARED)
#    if defined(_WIN32)
#        if defined(VGL_GL_BUILDING)
#            define VGL_GL_API __declspec(dllexport)
#        else
#            define VGL_GL_API __declspec(dllimport)
#        endif
#    else
#        define VGL_GL_API __attribute__((visibility("default")))
#    endif
#else
#    define VGL_GL_API
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef void (*vgl_gl_proc)(void);
 
typedef vgl_gl_proc (*vgl_gl_get_proc_address_fn)(void* user_data, const char* name);
 
typedef struct vgl_gl_backend vgl_gl_backend;
 
typedef struct vgl_gl_backend_create_info
{
    uint32_t struct_size;
    vgl_depth_convention depth_convention;
    vgl_gl_get_proc_address_fn get_proc_address;
    VGL_POINTER_PADDING(get_proc_address_padding)
    void* get_proc_address_user_data;
    VGL_POINTER_PADDING(get_proc_address_user_data_padding)
} vgl_gl_backend_create_info;
 
VGL_GL_API vgl_result vgl_gl_backend_create(vgl_context* context,
                                            const vgl_gl_backend_create_info* info,
                                            vgl_gl_backend** out_backend);
 
VGL_GL_API vgl_result vgl_gl_backend_destroy(vgl_gl_backend* backend);
 
typedef struct vgl_gl_draw_info
{
    uint32_t struct_size;
    vgl_bool mirrored;
    const vgl_dmat4* view_matrix;
    VGL_POINTER_PADDING(view_matrix_padding)
    const vgl_dmat4* projection_matrix;
    VGL_POINTER_PADDING(projection_matrix_padding)
    vgl_dvec3 sun_direction;
    double logarithmic_far;
    uint64_t upload_budget;
    vgl_draw_features features;
    vgl_debug_views debug_views;
    double earth_rotation_angle;
    double contour_interval;
    double cloud_height;
} vgl_gl_draw_info;
 
VGL_GL_API vgl_result vgl_gl_backend_draw(vgl_gl_backend* backend, const vgl_gl_draw_info* info);
 
VGL_GL_API vgl_result vgl_gl_backend_stars_set(vgl_gl_backend* backend,
                                               const vgl_star* stars,
                                               uint32_t star_count);
 
VGL_GL_API vgl_result vgl_gl_backend_clouds_set(vgl_gl_backend* backend,
                                                const uint8_t* coverage,
                                                uint32_t width,
                                                uint32_t height);
 
VGL_GL_API vgl_result vgl_gl_backend_device_reset(vgl_gl_backend* backend);
 
#ifdef __cplusplus
}
#endif
 
#endif /* VGL_GL_H */