render.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Jeremiah van Oosten
 *
 * The render interface (docs/render-interface.md): the contract between the core and whatever
 * draws the globe. Each frame, on the render thread, a backend or host takes the resources to
 * destroy and create, and the list of tiles to draw; the core never calls into it.
 */
#ifndef VGL_RENDER_H
#define VGL_RENDER_H
 
#include <vgl/base.h>
#include <vgl/context.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---------------------------------------------------------------------------------------- */
/* Data formats (sections 6 and 7)                                                          */
/* ---------------------------------------------------------------------------------------- */
 
#define VGL_TERRAIN_VERTEX_SIZE 24
#define VGL_TERRAIN_VERTEX_POSITION_OFFSET 0
#define VGL_TERRAIN_VERTEX_HEIGHT_OFFSET 12
#define VGL_TERRAIN_VERTEX_UV_OFFSET 16
#define VGL_TERRAIN_VERTEX_NORMAL_OFFSET 20
 
#define VGL_TERRAIN_SAMPLE_SIZE 8
#define VGL_TERRAIN_SAMPLE_HEIGHT_OFFSET 0
#define VGL_TERRAIN_SAMPLE_NORMAL_OFFSET 4
 
typedef struct vgl_star
{
    float direction[3];
    float magnitude;
    float color[3];
    float reserved; 
} vgl_star;
 
typedef enum vgl_texture_format
{
    VGL_TEXTURE_FORMAT_RGBA8 = 1, 
    VGL_TEXTURE_FORMAT_RGBA8_SRGB = 2,
    VGL_TEXTURE_FORMAT_BC1 = 3,
    VGL_TEXTURE_FORMAT_BC7 = 4,
    VGL_TEXTURE_FORMAT_ETC2_RGB8 = 5,
    VGL_TEXTURE_FORMAT_ASTC_4X4 = 6,
    VGL_TEXTURE_FORMAT_MAX_ENUM = 0x7FFFFFFF
} vgl_texture_format;
 
VGL_API vgl_result vgl_context_texture_formats_set(vgl_context* context,
                                                   const vgl_texture_format* formats,
                                                   uint32_t format_count);
 
/* ---------------------------------------------------------------------------------------- */
/* Depth conventions (section 8)                                                            */
/* ---------------------------------------------------------------------------------------- */
 
typedef enum vgl_depth_convention
{
    VGL_DEPTH_CONVENTION_LOGARITHMIC = 0,
    VGL_DEPTH_CONVENTION_REVERSED_Z = 1,
    VGL_DEPTH_CONVENTION_CONVENTIONAL = 2,
    VGL_DEPTH_CONVENTION_MAX_ENUM = 0x7FFFFFFF
} vgl_depth_convention;
 
#define VGL_LOGARITHMIC_DEPTH_FAR_DEFAULT 1.0e8
 
/* ---------------------------------------------------------------------------------------- */
/* Resources (section 4)                                                                  */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_tile_id
{
    uint32_t level;
    uint32_t x;
    uint32_t y;
    uint32_t reserved;
} vgl_tile_id;
 
typedef struct vgl_index_list_data
{
    uint64_t resource;
    const void* indices;
    VGL_POINTER_PADDING(indices_padding)
    uint32_t index_count;
    uint32_t index_size;
} vgl_index_list_data;
 
typedef struct vgl_mesh_data
{
    uint64_t resource;
    uint64_t index_list;
    const void* vertices;
    VGL_POINTER_PADDING(vertices_padding)
    uint32_t vertex_count;
    uint32_t vertex_size;
    vgl_tile_id tile;
    vgl_dvec3 centre;
    double min_height;
    double max_height;
    const void* samples;
    VGL_POINTER_PADDING(samples_padding)
    uint32_t sample_grid;
    uint32_t sample_size;
} vgl_mesh_data;
 
typedef struct vgl_texture_data
{
    uint64_t resource;
    vgl_texture_format format;
    uint32_t width;
    uint32_t height;
    uint32_t mip_count;
    const void* const* mip_data;
    VGL_POINTER_PADDING(mip_data_padding)
    const size_t* mip_sizes;
    VGL_POINTER_PADDING(mip_sizes_padding)
} vgl_texture_data;
 
/* ---------------------------------------------------------------------------------------- */
/* Frames (sections 3 and 5)                                                                */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_frame vgl_frame;
 
typedef struct vgl_draw_layer
{
    uint64_t texture;
    uint64_t texture_handle;
    float uv_scale_offset[4];
    float opacity;
    uint32_t reserved;
} vgl_draw_layer;
 
typedef struct vgl_draw_item
{
    vgl_tile_id tile;
    uint64_t mesh;
    uint64_t mesh_handle;
    uint64_t index_list;
    uint64_t index_list_handle;
    uint32_t index_count;
    uint32_t index_size;
    uint32_t first_layer;
    uint32_t layer_count;
    float model_view[16];
    vgl_dvec3 centre;
    double min_height;
    double max_height;
    float geoid_heights[4];
    vgl_bool has_geoid;
    uint32_t reserved;
} vgl_draw_item;
 
typedef struct vgl_frame_begin_info
{
    uint32_t struct_size;
    uint32_t draw_item_size;       
    uint32_t draw_layer_size;      
    uint32_t index_list_data_size; 
    uint32_t mesh_data_size;       
    uint32_t texture_data_size;    
    uint64_t upload_budget;
    const vgl_dmat4* view_matrix;
    VGL_POINTER_PADDING(view_matrix_padding)
} vgl_frame_begin_info;
 
VGL_API vgl_result vgl_context_frame_begin(vgl_context* context,
                                           const vgl_frame_begin_info* info,
                                           vgl_frame** out_frame);
 
VGL_API vgl_result vgl_frame_destroys_get(const vgl_frame* frame,
                                          const uint64_t** out_resources,
                                          uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_index_lists_get(const vgl_frame* frame,
                                             const vgl_index_list_data** out_index_lists,
                                             uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_meshes_get(const vgl_frame* frame,
                                        const vgl_mesh_data** out_meshes,
                                        uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_textures_get(const vgl_frame* frame,
                                          const vgl_texture_data** out_textures,
                                          uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_draw_list_get(const vgl_frame* frame,
                                           const vgl_draw_item** out_items,
                                           uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_draw_layers_get(const vgl_frame* frame,
                                             const vgl_draw_layer** out_layers,
                                             uint32_t* out_count);
 
VGL_API vgl_result vgl_frame_resource_handle_set(vgl_frame* frame,
                                                 uint64_t resource,
                                                 uint64_t handle);
 
VGL_API vgl_result vgl_frame_resource_failed(vgl_frame* frame,
                                             uint64_t resource,
                                             vgl_result reason);
 
VGL_API vgl_result vgl_frame_end(vgl_frame* frame);
 
VGL_API vgl_result vgl_context_resources_reset(vgl_context* context);
 
/* ---------------------------------------------------------------------------------------- */
/* What backends draw                                                                       */
/* ---------------------------------------------------------------------------------------- */
 
typedef uint32_t vgl_draw_features;
 
typedef enum vgl_draw_feature
{
    VGL_DRAW_FEATURE_SEA_SURFACE = 0x1,
    VGL_DRAW_FEATURE_ATMOSPHERE = 0x2,
    VGL_DRAW_FEATURE_STARS = 0x4,
    VGL_DRAW_FEATURE_CLOUDS = 0x8,
    VGL_DRAW_FEATURE_CONTOURS = 0x10,
    VGL_DRAW_FEATURE_MAX_ENUM = 0x7FFFFFFF
} vgl_draw_feature;
 
typedef uint32_t vgl_debug_views;
 
typedef enum vgl_debug_view
{
    VGL_DEBUG_VIEW_WIREFRAME = 0x1,
    VGL_DEBUG_VIEW_LEVEL_COLORS = 0x2,
    VGL_DEBUG_VIEW_IMAGERY_SOURCE = 0x4,
    VGL_DEBUG_VIEW_HEIGHT_COLORS = 0x8,
    VGL_DEBUG_VIEW_MAX_ENUM = 0x7FFFFFFF
} vgl_debug_view;
 
#define VGL_UPLOAD_BUDGET_DEFAULT (16ull * 1024 * 1024)
#define VGL_CONTOUR_INTERVAL_DEFAULT 500.0
#define VGL_CLOUD_HEIGHT_DEFAULT 6000.0
#define VGL_STAR_COUNT_MAX 400000u
#define VGL_CLOUD_IMAGE_SIZE_MIN   2u
#define VGL_CLOUD_IMAGE_WIDTH_MAX  16384u
#define VGL_CLOUD_IMAGE_HEIGHT_MAX 8192u
 
#ifdef __cplusplus
}
#endif
 
#endif /* VGL_RENDER_H */