context.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Jeremiah van Oosten
 *
 * vgl context: the object that holds all library state (NFR-06), the packs it reads, and
 * height queries (FR-03, FR-05, FR-06).
 *
 * A minimal host creates a context with an I/O interface, adds packs, and calls
 * vgl_context_update once per frame. Packs load asynchronously; height queries start the loads
 * they need and report VGL_RESULT_NOT_READY until finer data has arrived.
 */
#ifndef VGL_CONTEXT_H
#define VGL_CONTEXT_H
 
#include <vgl/base.h>
#include <vgl/foundation.h>
#include <vgl/geodesy.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct vgl_context vgl_context;
 
typedef struct vgl_context_create_info
{
    uint32_t struct_size;
    vgl_log_level log_level;
    uint64_t cpu_budget;
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
    const vgl_io_interface* io;
    VGL_POINTER_PADDING(io_padding)
    const vgl_task_interface* tasks;
    VGL_POINTER_PADDING(tasks_padding)
    const vgl_ellipsoid* ellipsoid;
    VGL_POINTER_PADDING(ellipsoid_padding)
    vgl_log_fn log;
    VGL_POINTER_PADDING(log_padding)
    void* log_user_data;
    VGL_POINTER_PADDING(log_user_data_padding)
    uint64_t gpu_budget;
} vgl_context_create_info;
 
VGL_API vgl_result vgl_context_create(const vgl_context_create_info* info,
                                      vgl_context** out_context);
 
VGL_API vgl_result vgl_context_destroy(vgl_context* context);
 
VGL_API vgl_result vgl_context_allocator_get(const vgl_context* context,
                                             vgl_allocator_interface* out_allocator);
 
VGL_API vgl_result vgl_context_log(const vgl_context* context,
                                   vgl_log_level level,
                                   const char* message);
 
typedef struct vgl_update_info
{
    uint32_t struct_size;
    uint32_t reserved;
    double time_budget;
} vgl_update_info;
 
/* ---------------------------------------------------------------------------------------- */
/* View and update                                                                          */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_view
{
    uint32_t struct_size;
    uint32_t reserved;
    vgl_dmat4 view_matrix;
    vgl_dmat4 projection_matrix;
    uint32_t viewport_width;
    uint32_t viewport_height;
    double max_screen_space_error;
} vgl_view;
 
VGL_API vgl_result vgl_context_view_set(vgl_context* context, const vgl_view* view);
 
VGL_API vgl_result vgl_view_project(const vgl_view* view,
                                    const vgl_dvec3* position,
                                    vgl_dvec3* out_window);
 
VGL_API vgl_result vgl_view_geodetic_project(const vgl_view* view,
                                             const vgl_ellipsoid* ellipsoid,
                                             const vgl_geodetic* geodetic,
                                             vgl_dvec3* out_window);
 
VGL_API vgl_result vgl_context_view_get(const vgl_context* context, vgl_view* out_view);
 
VGL_API vgl_result vgl_context_update(vgl_context* context, const vgl_update_info* info);
 
/* ---------------------------------------------------------------------------------------- */
/* Packs                                                                                    */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_pack vgl_pack;
 
typedef struct vgl_pack_create_info
{
    uint32_t struct_size;
    int32_t priority;
    const char* uri;
    VGL_POINTER_PADDING(uri_padding)
} vgl_pack_create_info;
 
typedef enum vgl_pack_state
{
    VGL_PACK_STATE_LOADING = 1, 
    VGL_PACK_STATE_READY = 2,   
    VGL_PACK_STATE_FAILED = 3,  
    VGL_PACK_STATE_MAX_ENUM = 0x7FFFFFFF
} vgl_pack_state;
 
VGL_API vgl_result vgl_pack_create(vgl_context* context,
                                   const vgl_pack_create_info* info,
                                   vgl_pack** out_pack);
 
VGL_API vgl_result vgl_pack_destroy(vgl_pack* pack);
 
VGL_API vgl_result vgl_pack_state_get(const vgl_pack* pack,
                                      vgl_pack_state* out_state,
                                      vgl_result* out_failure);
 
VGL_API vgl_result vgl_pack_priority_set(vgl_pack* pack, int32_t priority);
 
VGL_API vgl_result vgl_pack_priority_get(const vgl_pack* pack, int32_t* out_priority);
 
VGL_API vgl_result vgl_pack_opacity_set(vgl_pack* pack, float opacity);
 
VGL_API vgl_result vgl_pack_opacity_get(const vgl_pack* pack, float* out_opacity);
 
/* ---------------------------------------------------------------------------------------- */
/* Height and ray queries                                                                   */
/* ---------------------------------------------------------------------------------------- */
 
typedef enum vgl_height_reference
{
    VGL_HEIGHT_REFERENCE_ELLIPSOID = 0,      
    VGL_HEIGHT_REFERENCE_MEAN_SEA_LEVEL = 1, 
    VGL_HEIGHT_REFERENCE_MAX_ENUM = 0x7FFFFFFF
} vgl_height_reference;
 
VGL_API vgl_result vgl_context_height_query(vgl_context* context,
                                            double latitude,
                                            double longitude,
                                            vgl_height_reference reference,
                                            double* out_height);
 
typedef struct vgl_ray_hit
{
    uint32_t struct_size;
    uint32_t reserved;
    double distance;       
    vgl_dvec3 position;    
    vgl_geodetic geodetic; 
} vgl_ray_hit;
 
VGL_API vgl_result vgl_context_ray_query(vgl_context* context,
                                         const vgl_dvec3* origin,
                                         const vgl_dvec3* direction,
                                         vgl_ray_hit* out_hit);
 
/* ---------------------------------------------------------------------------------------- */
/* Attribution                                                                              */
/* ---------------------------------------------------------------------------------------- */
 
VGL_API vgl_result vgl_context_attribution_get(const vgl_context* context,
                                               uint32_t* inout_count,
                                               const char** out_strings);
 
/* ---------------------------------------------------------------------------------------- */
/* Statistics                                                                               */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_context_statistics
{
    uint32_t struct_size;
    uint32_t reserved;
 
    uint64_t cpu_used;
    uint64_t cpu_budget;
    uint64_t gpu_used; 
    uint64_t gpu_budget;
 
    uint32_t packs_loading;
    uint32_t packs_failed;
 
    uint32_t reads_outstanding;
    uint32_t tiles_decoding; 
    uint32_t tiles_decoded;  
    uint32_t meshes_building;
    uint32_t meshes_waiting;    
    uint32_t textures_decoding; 
    uint32_t textures_waiting;  
    uint32_t resources_resident;
 
    uint32_t tiles_selected;
 
    uint32_t tiles_drawn;
    uint32_t resources_created;
    uint32_t resources_destroyed;
    uint64_t bytes_created;
    uint64_t vertices_drawn;
    uint64_t triangles_drawn;
 
    uint64_t reads_total;
    uint64_t bytes_read_total;
    uint64_t tiles_loaded_total;
 
    double tile_load_time_mean; 
    double update_time;         
    double frame_time;          
} vgl_context_statistics;
 
VGL_API vgl_result vgl_context_statistics_get(const vgl_context* context,
                                              vgl_context_statistics* out_statistics);
 
#ifdef __cplusplus
}
#endif
 
#endif /* VGL_CONTEXT_H */