foundation.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Jeremiah van Oosten
 *
 * vgl foundation: allocator, logging, I/O and task interfaces (docs/c-api.md, sections 10,
 * 12 and 13; design document, section 7.5).
 */
#ifndef VGL_FOUNDATION_H
#define VGL_FOUNDATION_H
 
#include <vgl/base.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum vgl_log_level
{
    VGL_LOG_LEVEL_DEFAULT = 0,
    VGL_LOG_LEVEL_ERROR = 1,
    VGL_LOG_LEVEL_WARNING = 2,
    VGL_LOG_LEVEL_INFO = 3,
    VGL_LOG_LEVEL_DEBUG = 4,
    VGL_LOG_LEVEL_MAX_ENUM = 0x7FFFFFFF
} vgl_log_level;
 
typedef void (*vgl_log_fn)(void* user_data, vgl_log_level level, const char* message);
 
#define VGL_ALLOCATOR_INTERFACE_VERSION 1
 
typedef struct vgl_allocator_interface
{
    uint32_t version; 
    uint32_t reserved;
    void* user_data;
 
    void* (*allocate)(void* user_data, size_t size, size_t alignment);
 
    void (*deallocate)(void* user_data, void* memory, size_t size, size_t alignment);
} vgl_allocator_interface;
 
/* ---------------------------------------------------------------------------------------- */
/* I/O                                                                                      */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_io_request vgl_io_request;
 
#define VGL_IO_SIZE_TO_END UINT64_MAX
 
typedef struct vgl_io_read
{
    const char* uri;
    VGL_POINTER_PADDING(uri_padding)
    uint64_t offset; 
    uint64_t size;
} vgl_io_read;
 
#define VGL_IO_INTERFACE_VERSION 1
 
typedef struct vgl_io_interface
{
    uint32_t version; 
    uint32_t reserved;
    void* user_data;
 
    void (*read)(void* user_data, vgl_io_request* request, const vgl_io_read* read);
 
    void (*cancel)(void* user_data, vgl_io_request* request);
 
    void (*destroy)(void* user_data);
} vgl_io_interface;
 
VGL_API vgl_result vgl_io_request_complete(vgl_io_request* request,
                                           vgl_result result,
                                           const void* data,
                                           size_t size);
 
typedef void (*vgl_io_complete_fn)(void* user_data,
                                   vgl_result result,
                                   const void* data,
                                   size_t size);
 
typedef struct vgl_io_request_create_info
{
    uint32_t struct_size;
    uint32_t reserved;
    vgl_io_complete_fn complete;
    VGL_POINTER_PADDING(complete_padding)
    void* user_data;
    VGL_POINTER_PADDING(user_data_padding)
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
} vgl_io_request_create_info;
 
VGL_API vgl_result vgl_io_request_create(const vgl_io_request_create_info* info,
                                         vgl_io_request** out_request);
 
/* ---------------------------------------------------------------------------------------- */
/* Tasks                                                                                    */
/* ---------------------------------------------------------------------------------------- */
 
typedef void (*vgl_task_fn)(void* user_data);
 
#define VGL_TASK_INTERFACE_VERSION 1
 
typedef struct vgl_task_interface
{
    uint32_t version; 
    uint32_t reserved;
    void* user_data;
 
    vgl_result (*submit)(void* user_data, vgl_task_fn function, void* task_data);
 
    void (*destroy)(void* user_data);
} vgl_task_interface;
 
#ifdef __cplusplus
}
#endif
 
#endif /* VGL_FOUNDATION_H */