src/ascension/shader.h

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * Copyright 2023 Mike Becker. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef ASCENSION_SHADER_H
#define ASCENSION_SHADER_H

#include <cx/allocator.h>

#include "camera.h"

typedef struct asc_scene_node_s AscSceneNode; // avoids full include of scene_node.h

typedef int asc_uniform_loc;

struct asc_shader_code_s {
    /**
     * File name of the shader.
     * Set to @c NULL if the specific type of shader is not used in the program.
     */
    const char *source_file;
    /**
     * An array of code segments, usually preprocessor defines.
     *
     * The maximum number of elements in this array is 64.
     * The preamble_code_flags integer decides which elements of this array shall be prepended to
     * the shader code before compilation.
     */
    const char * const *preamble_code;
    /**
     * Flags for deciding which code segments shall be added to the preamble of the shader.
     */
    uint64_t preamble_code_flags;
};

typedef struct asc_shader_codes_s {
    struct asc_shader_code_s vtx;
    struct asc_shader_code_s frag;
} AscShaderCodes;

typedef struct asc_shader_program_s {
    unsigned int id;
    unsigned int gl_id;
    int model;
    int view;
    int projection;
    cx_destructor_func destr_func;
} AscShaderProgram;

/**
 * The maximum ID for a user-defined shader.
 *
 * The IDs above this number are reserved for the engine.
 */
#define ASC_SHADER_ID_USER_MAX  1'000'000'000u

/**
 * A function to create a shader program.
 * Should return @c NULL when creation fails.
 *
 * Usually this function calls asc_shader_create() with
 * a configuration that depends on the flags passed as parameter.
 *
 * @see asc_shader_create()
 */
typedef AscShaderProgram*(*asc_shader_create_func)(int);

/**
 * Initialization function for a shader.
 *
 * This usually gets all uniform locations and stores them as integers in the struct.
 *
 * To be used with asc_shader_create().
 * @see asc_shader_create()
 * @see asc_shader_init_uniform_loc()
 */
typedef void(*asc_shader_init_func)(AscShaderProgram*, int);

/**
 * Creates a shader program.
 *
 * @param code_info the information about the code that should be loaded
 * @param mem_size the memory size required for the target structure
 * @param init_func the initialization function
 * @param flags the creation flags
 * @return the compiled and linked shader program as a structure of size @p mem_size
 * that contains @c AscShaderProgram as base struct
 */
AscShaderProgram *asc_shader_create(AscShaderCodes code_info,
    size_t mem_size, asc_shader_init_func init_func, int flags);

/**
 * Frees a shader program.
 *
 * @param program the program
 */
void asc_shader_free(AscShaderProgram *program);

/**
 * Activates a shader for use.
 *
 * Does nothing and immediately returns zero when the shader is already active.
 *
 * @param shader the shader program to use or @c NULL to deactivate any shader
 * @param camera the camera matrices (view/projection) to upload
 * @retval zero when the shader is now active
 * @retval non-zero when the shader that was supposed to be activated is invalid
 */
int asc_shader_use(const AscShaderProgram *shader, const AscCamera *camera);


/**
 * Registers a shader under a certain ID.
 *
 * @param id the custom ID of the shader
 * @param create_func the function that creates the shader
 * @param create_flags flags passed to create_func
 * @return the shader created by the @c create_func or @c NULL when shader compilation failed
 * @see asc_shader_lookup()
 */
const AscShaderProgram *asc_shader_register(unsigned int id, asc_shader_create_func create_func, int create_flags);

/**
 * Looks up a shader by ID.
 *
 * @param id the ID of the shader to look up
 * @return the shader or @c NULL if no shader with such ID exists
 * @see asc_shader_register()
 */
const AscShaderProgram *asc_shader_lookup(unsigned int id);

/**
 * Looks up a shader by ID or registers a new one if no shader exists with the specified ID.
 *
 * This function can be used for lazy initialization of shaders.
 *
 * @param id the custom ID of the shader
 * @param create_func the function to create the shader
 * @param create_flags flags passed to create_func
 * @return the found shader or the newly created shader or @c NULL when shader compilation failed
 * @see asc_shader_lookup()
 * @see asc_shader_register()
 */
const AscShaderProgram *asc_shader_lookup_or_create(unsigned int id, asc_shader_create_func create_func, int create_flags);


/**
 * Frees all registered shaders.
 *
 * Completely wipes all shaders.
 * Be careful with this function when shaders are needed that have been registered with @c asc_shader_register().
 * Those need to be registered again, or @a asc_shader_lookup() will fail.
 * Shaders that are used with @a asc_shader_lookup_or_create() will be re-created automatically.
 *
 * TODO: maybe we should add another function that only clears lazy-initialized shaders
 *       another alternative would be to keep the initialization info and lazy-initialize cleared shaders on lookup
 *
 * @see asc_shader_lookup_or_create()
 */
void asc_shader_clear_registry(void);

asc_uniform_loc asc_shader_get_uniform_loc(const AscShaderProgram *shader, const char *name);

/**
 * Gets the location of a uniform as an integer and stores it in the struct.
 *
 * This is a convenient wrapper for asc_shader_get_uniform_loc().
 *
 * @param shader the shader program struct
 * @param mem_offset the offset of the int field in the shader program struct
 * @param name the name of the uniform
 */
void asc_shader_init_uniform_loc(AscShaderProgram *shader, off_t mem_offset, const char *name);

/**
 * Gets the location of a uniform as an integer and stores it in the struct.
 *
 * This is a nicer, but less flexible, wrapper for asc_shader_get_uniform_loc().
 *
 * @param s a pointer to the shader struct
 * @param type_name the type name of the shader struct
 * @param field_name the field name which must match the uniform's name
 */
#define asc_shader_init_uniform_loc_nice(s, type_name, field_name) \
    asc_shader_init_uniform_loc(s, offsetof(type_name, field_name), #field_name)

void asc_shader_upload_model_matrix(const AscShaderProgram *shader, const AscSceneNode *node);

void asc_shader_upload_col4f(int uniform_id, asc_col4f color);

static inline void asc_shader_upload_col4i(int uniform_id, asc_col4i color) {
    asc_shader_upload_col4f(uniform_id, asc_col_itof(color));
}

void asc_shader_upload_float(int uniform_id, float value);

void asc_shader_upload_vec2f(int uniform_id, asc_vec2f value);

#endif //ASCENSION_SHADER_H