nodegl.h.in

/*
 * Copyright 2016-2022 GoPro Inc.
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

#ifndef NODEGL_H
#define NODEGL_H

#define NGL_VERSION_MAJOR @version_major@
#define NGL_VERSION_MINOR @version_minor@
#define NGL_VERSION_MICRO @version_micro@

#define NGL_GET_VERSION(major, minor, micro) ((major)<<16 | (minor)<<8 | (micro))

#define NGL_VERSION_INT NGL_GET_VERSION(NGL_VERSION_MAJOR, \
                                        NGL_VERSION_MINOR, \
                                        NGL_VERSION_MICRO)

#if defined(_WIN32)
#  if defined(BUILD_NODEGL_SHARED_LIB)
#    define NGL_API __declspec(dllexport) /* On Windows, we need to export the symbols while building */
#  elif defined(USE_NODEGL_STATIC_LIB) /* Static library users don't need anything special */
#    define NGL_API
#  else
#    define NGL_API __declspec(dllimport) /* Dynamic library users (default) need a DLL import spec */
#  endif
#else
#  define NGL_API __attribute__((visibility("default"))) /* This cancel the hidden GNU symbol visibility attribute */
#endif

#include <stdarg.h>
#include <stdint.h>

/**
 * Logging levels
 */
enum {
    NGL_LOG_VERBOSE,
    NGL_LOG_DEBUG,
    NGL_LOG_INFO,
    NGL_LOG_WARNING,
    NGL_LOG_ERROR,
    NGL_LOG_QUIET = 1 << 8
};

/**
 * Logging callback prototype.
 *
 * @param arg       forwarded opaque user argument
 * @param level     log level (any of NGL_LOG_*)
 * @param filename  source filename from where the message originates
 * @param ln        line in the source filename
 * @param fn        calling function name
 * @param fmt       printf format string
 * @param vl        variable argument list object associated with the fmt format string
 */
typedef void (*ngl_log_callback_type)(void *arg, int level, const char *filename,
                                      int ln, const char *fn, const char *fmt, va_list vl);

/**
 * Set a global custom logging callback.
 *
 * @param arg       opaque user argument to be forwarded to the callback
 *                  (typically a user context)
 * @param callback  callback function to be called when logging a message
 */
NGL_API void ngl_log_set_callback(void *arg, ngl_log_callback_type callback);

/**
 * Set the minimum global logging level.
 *
 * No message with its level inferior to the specified level will be logged
 * (with or without the callback set).
 *
 * @param level log level (any of NGL_LOG_*)
 */
NGL_API void ngl_log_set_min_level(int level);

/**
 * Opaque structure identifying a node
 */
struct ngl_node;

#define NGLI_FOURCC(a,b,c,d) (((uint32_t)(a))<<24 | (b)<<16 | (c)<<8 | (d))

/**
 * Node FOURCC identifiers
 */
#define NGL_NODE_ANIMATEDBUFFERFLOAT    NGLI_FOURCC('A','B','f','1')
#define NGL_NODE_ANIMATEDBUFFERVEC2     NGLI_FOURCC('A','B','f','2')
#define NGL_NODE_ANIMATEDBUFFERVEC3     NGLI_FOURCC('A','B','f','3')
#define NGL_NODE_ANIMATEDBUFFERVEC4     NGLI_FOURCC('A','B','f','4')
#define NGL_NODE_ANIMATEDCOLOR          NGLI_FOURCC('A','n','m','c')
#define NGL_NODE_ANIMATEDPATH           NGLI_FOURCC('A','n','m','P')
#define NGL_NODE_ANIMATEDTIME           NGLI_FOURCC('A','n','m','T')
#define NGL_NODE_ANIMATEDFLOAT          NGLI_FOURCC('A','n','m','1')
#define NGL_NODE_ANIMATEDVEC2           NGLI_FOURCC('A','n','m','2')
#define NGL_NODE_ANIMATEDVEC3           NGLI_FOURCC('A','n','m','3')
#define NGL_NODE_ANIMATEDVEC4           NGLI_FOURCC('A','n','m','4')
#define NGL_NODE_ANIMATEDQUAT           NGLI_FOURCC('A','n','m','Q')
#define NGL_NODE_ANIMKEYFRAMEBUFFER     NGLI_FOURCC('A','K','F','B')
#define NGL_NODE_ANIMKEYFRAMEFLOAT      NGLI_FOURCC('A','K','F','1')
#define NGL_NODE_ANIMKEYFRAMEVEC2       NGLI_FOURCC('A','K','F','2')
#define NGL_NODE_ANIMKEYFRAMEVEC3       NGLI_FOURCC('A','K','F','3')
#define NGL_NODE_ANIMKEYFRAMEVEC4       NGLI_FOURCC('A','K','F','4')
#define NGL_NODE_ANIMKEYFRAMEQUAT       NGLI_FOURCC('A','K','F','Q')
#define NGL_NODE_ANIMKEYFRAMECOLOR      NGLI_FOURCC('A','K','F','c')
#define NGL_NODE_BLOCK                  NGLI_FOURCC('B','l','c','k')
#define NGL_NODE_BUFFERBYTE             NGLI_FOURCC('B','s','b','1')
#define NGL_NODE_BUFFERBVEC2            NGLI_FOURCC('B','s','b','2')
#define NGL_NODE_BUFFERBVEC3            NGLI_FOURCC('B','s','b','3')
#define NGL_NODE_BUFFERBVEC4            NGLI_FOURCC('B','s','b','4')
#define NGL_NODE_BUFFERINT              NGLI_FOURCC('B','s','i','1')
#define NGL_NODE_BUFFERINT64            NGLI_FOURCC('B','s','l','1')
#define NGL_NODE_BUFFERIVEC2            NGLI_FOURCC('B','s','i','2')
#define NGL_NODE_BUFFERIVEC3            NGLI_FOURCC('B','s','i','3')
#define NGL_NODE_BUFFERIVEC4            NGLI_FOURCC('B','s','i','4')
#define NGL_NODE_BUFFERSHORT            NGLI_FOURCC('B','s','s','1')
#define NGL_NODE_BUFFERSVEC2            NGLI_FOURCC('B','s','s','2')
#define NGL_NODE_BUFFERSVEC3            NGLI_FOURCC('B','s','s','3')
#define NGL_NODE_BUFFERSVEC4            NGLI_FOURCC('B','s','s','4')
#define NGL_NODE_BUFFERUBYTE            NGLI_FOURCC('B','u','b','1')
#define NGL_NODE_BUFFERUBVEC2           NGLI_FOURCC('B','u','b','2')
#define NGL_NODE_BUFFERUBVEC3           NGLI_FOURCC('B','u','b','3')
#define NGL_NODE_BUFFERUBVEC4           NGLI_FOURCC('B','u','b','4')
#define NGL_NODE_BUFFERUINT             NGLI_FOURCC('B','u','i','1')
#define NGL_NODE_BUFFERUIVEC2           NGLI_FOURCC('B','u','i','2')
#define NGL_NODE_BUFFERUIVEC3           NGLI_FOURCC('B','u','i','3')
#define NGL_NODE_BUFFERUIVEC4           NGLI_FOURCC('B','u','i','4')
#define NGL_NODE_BUFFERUSHORT           NGLI_FOURCC('B','u','s','1')
#define NGL_NODE_BUFFERUSVEC2           NGLI_FOURCC('B','u','s','2')
#define NGL_NODE_BUFFERUSVEC3           NGLI_FOURCC('B','u','s','3')
#define NGL_NODE_BUFFERUSVEC4           NGLI_FOURCC('B','u','s','4')
#define NGL_NODE_BUFFERFLOAT            NGLI_FOURCC('B','f','v','1')
#define NGL_NODE_BUFFERVEC2             NGLI_FOURCC('B','f','v','2')
#define NGL_NODE_BUFFERVEC3             NGLI_FOURCC('B','f','v','3')
#define NGL_NODE_BUFFERVEC4             NGLI_FOURCC('B','f','v','4')
#define NGL_NODE_BUFFERMAT4             NGLI_FOURCC('B','f','m','4')
#define NGL_NODE_CAMERA                 NGLI_FOURCC('C','m','r','a')
#define NGL_NODE_CIRCLE                 NGLI_FOURCC('C','r','c','l')
#define NGL_NODE_COMPUTE                NGLI_FOURCC('C','p','t',' ')
#define NGL_NODE_COMPUTEPROGRAM         NGLI_FOURCC('C','p','t','P')
#define NGL_NODE_EVALFLOAT              NGLI_FOURCC('E','v','f','1')
#define NGL_NODE_EVALVEC2               NGLI_FOURCC('E','v','f','2')
#define NGL_NODE_EVALVEC3               NGLI_FOURCC('E','v','f','3')
#define NGL_NODE_EVALVEC4               NGLI_FOURCC('E','v','f','4')
#define NGL_NODE_FILTERALPHA            NGLI_FOURCC('F','a','l','f')
#define NGL_NODE_FILTERCONTRAST         NGLI_FOURCC('F','c','t','r')
#define NGL_NODE_FILTEREXPOSURE         NGLI_FOURCC('F','e','x','p')
#define NGL_NODE_FILTERINVERSEALPHA     NGLI_FOURCC('F','1','-','a')
#define NGL_NODE_FILTERLINEAR2SRGB      NGLI_FOURCC('F','r','g','b')
#define NGL_NODE_FILTEROPACITY          NGLI_FOURCC('F','o','p','a')
#define NGL_NODE_FILTERPREMULT          NGLI_FOURCC('F','p','r','e')
#define NGL_NODE_FILTERSATURATION       NGLI_FOURCC('F','s','a','t')
#define NGL_NODE_FILTERSRGB2LINEAR      NGLI_FOURCC('F','l','i','n')
#define NGL_NODE_GEOMETRY               NGLI_FOURCC('G','e','o','m')
#define NGL_NODE_GRAPHICCONFIG          NGLI_FOURCC('G','r','C','f')
#define NGL_NODE_GROUP                  NGLI_FOURCC('G','r','p',' ')
#define NGL_NODE_IDENTITY               NGLI_FOURCC('I','d',' ',' ')
#define NGL_NODE_IOINT                  NGLI_FOURCC('I','O','i','1')
#define NGL_NODE_IOIVEC2                NGLI_FOURCC('I','O','i','2')
#define NGL_NODE_IOIVEC3                NGLI_FOURCC('I','O','i','3')
#define NGL_NODE_IOIVEC4                NGLI_FOURCC('I','O','i','4')
#define NGL_NODE_IOUINT                 NGLI_FOURCC('I','O','u','1')
#define NGL_NODE_IOUIVEC2               NGLI_FOURCC('I','O','u','2')
#define NGL_NODE_IOUIVEC3               NGLI_FOURCC('I','O','u','3')
#define NGL_NODE_IOUIVEC4               NGLI_FOURCC('I','O','u','4')
#define NGL_NODE_IOFLOAT                NGLI_FOURCC('I','O','f','1')
#define NGL_NODE_IOVEC2                 NGLI_FOURCC('I','O','f','2')
#define NGL_NODE_IOVEC3                 NGLI_FOURCC('I','O','f','3')
#define NGL_NODE_IOVEC4                 NGLI_FOURCC('I','O','f','4')
#define NGL_NODE_IOMAT3                 NGLI_FOURCC('I','O','m','3')
#define NGL_NODE_IOMAT4                 NGLI_FOURCC('I','O','m','4')
#define NGL_NODE_IOBOOL                 NGLI_FOURCC('I','O','b','1')
#define NGL_NODE_MEDIA                  NGLI_FOURCC('M','d','i','a')
#define NGL_NODE_NOISEFLOAT             NGLI_FOURCC('N','z','f','1')
#define NGL_NODE_NOISEVEC2              NGLI_FOURCC('N','z','f','2')
#define NGL_NODE_NOISEVEC3              NGLI_FOURCC('N','z','f','3')
#define NGL_NODE_NOISEVEC4              NGLI_FOURCC('N','z','f','4')
#define NGL_NODE_PATH                   NGLI_FOURCC('P','a','t','h')
#define NGL_NODE_PATHKEYBEZIER2         NGLI_FOURCC('P','h','K','2')
#define NGL_NODE_PATHKEYBEZIER3         NGLI_FOURCC('P','h','K','3')
#define NGL_NODE_PATHKEYLINE            NGLI_FOURCC('P','h','K','1')
#define NGL_NODE_PATHKEYMOVE            NGLI_FOURCC('P','h','K','0')
#define NGL_NODE_PROGRAM                NGLI_FOURCC('P','r','g','m')
#define NGL_NODE_QUAD                   NGLI_FOURCC('Q','u','a','d')
#define NGL_NODE_RENDER                 NGLI_FOURCC('R','n','d','r')
#define NGL_NODE_RENDERCOLOR            NGLI_FOURCC('R','c','l','r')
#define NGL_NODE_RENDERGRADIENT         NGLI_FOURCC('R','g','r','d')
#define NGL_NODE_RENDERGRADIENT4        NGLI_FOURCC('R','g','d','4')
#define NGL_NODE_RENDERTEXTURE          NGLI_FOURCC('R','t','e','x')
#define NGL_NODE_RENDERTOTEXTURE        NGLI_FOURCC('R','T','T',' ')
#define NGL_NODE_RESOURCEPROPS          NGLI_FOURCC('R','e','s','P')
#define NGL_NODE_ROTATE                 NGLI_FOURCC('T','R','o','t')
#define NGL_NODE_ROTATEQUAT             NGLI_FOURCC('T','R','o','Q')
#define NGL_NODE_SCALE                  NGLI_FOURCC('T','s','c','l')
#define NGL_NODE_SKEW                   NGLI_FOURCC('T','s','k','w')
#define NGL_NODE_SMOOTHPATH             NGLI_FOURCC('S','P','t','h')
#define NGL_NODE_STREAMEDINT            NGLI_FOURCC('S','t','i','1')
#define NGL_NODE_STREAMEDIVEC2          NGLI_FOURCC('S','t','i','2')
#define NGL_NODE_STREAMEDIVEC3          NGLI_FOURCC('S','t','i','3')
#define NGL_NODE_STREAMEDIVEC4          NGLI_FOURCC('S','t','i','4')
#define NGL_NODE_STREAMEDUINT           NGLI_FOURCC('S','t','u','1')
#define NGL_NODE_STREAMEDUIVEC2         NGLI_FOURCC('S','t','u','2')
#define NGL_NODE_STREAMEDUIVEC3         NGLI_FOURCC('S','t','u','3')
#define NGL_NODE_STREAMEDUIVEC4         NGLI_FOURCC('S','t','u','4')
#define NGL_NODE_STREAMEDFLOAT          NGLI_FOURCC('S','t','f','1')
#define NGL_NODE_STREAMEDVEC2           NGLI_FOURCC('S','t','f','2')
#define NGL_NODE_STREAMEDVEC3           NGLI_FOURCC('S','t','f','3')
#define NGL_NODE_STREAMEDVEC4           NGLI_FOURCC('S','t','f','4')
#define NGL_NODE_STREAMEDMAT4           NGLI_FOURCC('S','t','m','4')
#define NGL_NODE_STREAMEDBUFFERINT      NGLI_FOURCC('S','B','i','1')
#define NGL_NODE_STREAMEDBUFFERIVEC2    NGLI_FOURCC('S','B','i','2')
#define NGL_NODE_STREAMEDBUFFERIVEC3    NGLI_FOURCC('S','B','i','3')
#define NGL_NODE_STREAMEDBUFFERIVEC4    NGLI_FOURCC('S','B','i','4')
#define NGL_NODE_STREAMEDBUFFERUINT     NGLI_FOURCC('S','B','u','1')
#define NGL_NODE_STREAMEDBUFFERUIVEC2   NGLI_FOURCC('S','B','u','2')
#define NGL_NODE_STREAMEDBUFFERUIVEC3   NGLI_FOURCC('S','B','u','3')
#define NGL_NODE_STREAMEDBUFFERUIVEC4   NGLI_FOURCC('S','B','u','4')
#define NGL_NODE_STREAMEDBUFFERFLOAT    NGLI_FOURCC('S','B','f','1')
#define NGL_NODE_STREAMEDBUFFERVEC2     NGLI_FOURCC('S','B','f','2')
#define NGL_NODE_STREAMEDBUFFERVEC3     NGLI_FOURCC('S','B','f','3')
#define NGL_NODE_STREAMEDBUFFERVEC4     NGLI_FOURCC('S','B','f','4')
#define NGL_NODE_STREAMEDBUFFERMAT4     NGLI_FOURCC('S','B','m','4')
#define NGL_NODE_TEXT                   NGLI_FOURCC('T','e','x','t')
#define NGL_NODE_TEXTURE2D              NGLI_FOURCC('T','e','x','2')
#define NGL_NODE_TEXTURE3D              NGLI_FOURCC('T','e','x','3')
#define NGL_NODE_TEXTURECUBE            NGLI_FOURCC('T','e','x','C')
#define NGL_NODE_TEXTUREVIEW            NGLI_FOURCC('T','e','x','V')
#define NGL_NODE_TIME                   NGLI_FOURCC('T','i','m','e')
#define NGL_NODE_TIMERANGEFILTER        NGLI_FOURCC('T','R','F','l')
#define NGL_NODE_TIMERANGEMODECONT      NGLI_FOURCC('T','R','M','C')
#define NGL_NODE_TIMERANGEMODENOOP      NGLI_FOURCC('T','R','M','N')
#define NGL_NODE_TIMERANGEMODEONCE      NGLI_FOURCC('T','R','M','1')
#define NGL_NODE_TRANSFORM              NGLI_FOURCC('T','r','f','m')
#define NGL_NODE_TRANSLATE              NGLI_FOURCC('T','m','o','v')
#define NGL_NODE_TRIANGLE               NGLI_FOURCC('T','r','g','l')
#define NGL_NODE_UNIFORMBOOL            NGLI_FOURCC('U','n','b','1')
#define NGL_NODE_UNIFORMINT             NGLI_FOURCC('U','n','i','1')
#define NGL_NODE_UNIFORMIVEC2           NGLI_FOURCC('U','n','i','2')
#define NGL_NODE_UNIFORMIVEC3           NGLI_FOURCC('U','n','i','3')
#define NGL_NODE_UNIFORMIVEC4           NGLI_FOURCC('U','n','i','4')
#define NGL_NODE_UNIFORMUINT            NGLI_FOURCC('U','n','u','1')
#define NGL_NODE_UNIFORMUIVEC2          NGLI_FOURCC('U','n','u','2')
#define NGL_NODE_UNIFORMUIVEC3          NGLI_FOURCC('U','n','u','3')
#define NGL_NODE_UNIFORMUIVEC4          NGLI_FOURCC('U','n','u','4')
#define NGL_NODE_UNIFORMMAT4            NGLI_FOURCC('U','n','M','4')
#define NGL_NODE_UNIFORMFLOAT           NGLI_FOURCC('U','n','f','1')
#define NGL_NODE_UNIFORMVEC2            NGLI_FOURCC('U','n','f','2')
#define NGL_NODE_UNIFORMVEC3            NGLI_FOURCC('U','n','f','3')
#define NGL_NODE_UNIFORMVEC4            NGLI_FOURCC('U','n','f','4')
#define NGL_NODE_UNIFORMCOLOR           NGLI_FOURCC('U','n','c','3')
#define NGL_NODE_UNIFORMQUAT            NGLI_FOURCC('U','n','Q','t')
#define NGL_NODE_USERSELECT             NGLI_FOURCC('U','S','e','l')
#define NGL_NODE_USERSWITCH             NGLI_FOURCC('U','S','c','h')
#define NGL_NODE_VELOCITYFLOAT          NGLI_FOURCC('V','l','y','1')
#define NGL_NODE_VELOCITYVEC2           NGLI_FOURCC('V','l','y','2')
#define NGL_NODE_VELOCITYVEC3           NGLI_FOURCC('V','l','y','3')
#define NGL_NODE_VELOCITYVEC4           NGLI_FOURCC('V','l','y','4')

/**
 * Return error codes.
 *
 * All NGL_ERROR_* values shall remain < 0.
 */
#define NGLI_ERROR(a,b,c,d) (-(int32_t)NGLI_FOURCC(a,b,c,d))

#define NGL_ERROR_GENERIC           -1                                  /* Generic error */
#define NGL_ERROR_ACCESS            NGLI_ERROR('E','a','c','c')       /* Operation not allowed */
#define NGL_ERROR_BUG               NGLI_ERROR('E','b','u','g')       /* A buggy code path was triggered, please report if it happens */
#define NGL_ERROR_EXTERNAL          NGLI_ERROR('E','e','x','t')       /* An error occurred in an external dependency */
#define NGL_ERROR_INVALID_ARG       NGLI_ERROR('E','a','r','g')       /* Invalid user argument specified */
#define NGL_ERROR_INVALID_DATA      NGLI_ERROR('E','d','a','t')       /* Invalid input data */
#define NGL_ERROR_INVALID_USAGE     NGLI_ERROR('E','u','s','g')       /* Invalid public API usage */
#define NGL_ERROR_IO                NGLI_ERROR('E','i','o',' ')       /* Input/Output error */
#define NGL_ERROR_LIMIT_EXCEEDED    NGLI_ERROR('E','l','i','m')       /* Hardware or resource limit exceeded */
#define NGL_ERROR_MEMORY            NGLI_ERROR('E','m','e','m')       /* Memory/allocation error */
#define NGL_ERROR_NOT_FOUND         NGLI_ERROR('E','f','n','d')       /* Target not found */
#define NGL_ERROR_UNSUPPORTED       NGLI_ERROR('E','s','u','p')       /* Unsupported operation */

#define NGL_ERROR_GRAPHICS_GENERIC         NGLI_ERROR('G','g','e','n')    /* Generic graphics error */
#define NGL_ERROR_GRAPHICS_LIMIT_EXCEEDED  NGLI_ERROR('G','l','i','m')    /* Graphics hardware or resource limit exceeded */
#define NGL_ERROR_GRAPHICS_MEMORY          NGLI_ERROR('G','m','e','m')    /* Graphics memory/allocation error */
#define NGL_ERROR_GRAPHICS_UNSUPPORTED     NGLI_ERROR('G','s','u','p')    /* Unsupported graphics operation */

/**
 * Allocate a node.
 *
 * This function does not perform any OpenGL operation.
 *
 * The reference counter of the allocated node is set to 1.
 *
 * Must be destroyed using ngl_node_unrefp().
 *
 * @param type  identify the node (any of NGL_NODE_*)
 *
 * @return a new allocated node or NULL on error
 */
NGL_API struct ngl_node *ngl_node_create(int type);

/**
 * Increment the reference counter of a given node by 1.
 *
 * This function is NOT thread-safe.
 *
 * This function does not perform any OpenGL operation.
 *
 * @param node  pointer to the node to reference count
 *
 * @return node with its reference counter incremented.
 */
NGL_API struct ngl_node *ngl_node_ref(struct ngl_node *node);

/**
 * Decrement the reference counter of a given node by 1, and destroy its
 * content if the reference counter reaches 0. The passed node pointer will
 * also be set to NULL.
 *
 * @param nodep  pointer to the pointer to the target node
 */
NGL_API void ngl_node_unrefp(struct ngl_node **nodep);

/**
 * Add nodes to a list-based parameter of an allocated node.
 *
 * The reference counter of the passed nodes will be incremented.
 *
 * @param node      pointer to the target node
 * @param key       string identifying the parameter
 * @param nb_nodes  number of nodes to append
 * @param nodes     pointer to an array of nodes
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_node_param_add_nodes(struct ngl_node *node, const char *key,
                                     int nb_nodes, struct ngl_node **nodes);

/**
 * Add double precision floats to a list-based parameter of an allocated node.
 *
 * @param node      pointer to the target node
 * @param key       string identifying the parameter
 * @param nb_f64s   number of doubles to append
 * @param f64s      pointer to an array of doubles
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_node_param_add_f64s(struct ngl_node *node, const char *key,
                                    int nb_f64s, double *f64s);

/**
 * All ngl_node_param_set_* functions set a parameter value of an allocated
 * node.
 *
 * If the type of the parameter is node based, the reference counter of the
 * passed node will be incremented.
 *
 * @param node      pointer to the target node
 * @param key       string identifying the parameter
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_node_param_set_bool(struct ngl_node *node, const char *key, int value);
NGL_API int ngl_node_param_set_data(struct ngl_node *node, const char *key, int size, const void *data);
NGL_API int ngl_node_param_set_dict(struct ngl_node *node, const char *key, const char *name, struct ngl_node *value);
NGL_API int ngl_node_param_set_f32(struct ngl_node *node, const char *key, float value);
NGL_API int ngl_node_param_set_f64(struct ngl_node *node, const char *key, double value);
NGL_API int ngl_node_param_set_flags(struct ngl_node *node, const char *key, const char *value);
NGL_API int ngl_node_param_set_i32(struct ngl_node *node, const char *key, int value);
NGL_API int ngl_node_param_set_ivec2(struct ngl_node *node, const char *key, const int *value);
NGL_API int ngl_node_param_set_ivec3(struct ngl_node *node, const char *key, const int *value);
NGL_API int ngl_node_param_set_ivec4(struct ngl_node *node, const char *key, const int *value);
NGL_API int ngl_node_param_set_mat4(struct ngl_node *node, const char *key, const float *value);
NGL_API int ngl_node_param_set_node(struct ngl_node *node, const char *key, struct ngl_node *value);
NGL_API int ngl_node_param_set_rational(struct ngl_node *node, const char *key, int num, int den);
NGL_API int ngl_node_param_set_select(struct ngl_node *node, const char *key, const char *value);
NGL_API int ngl_node_param_set_str(struct ngl_node *node, const char *key, const char *value);
NGL_API int ngl_node_param_set_u32(struct ngl_node *node, const char *key, const unsigned value);
NGL_API int ngl_node_param_set_uvec2(struct ngl_node *node, const char *key, const unsigned *value);
NGL_API int ngl_node_param_set_uvec3(struct ngl_node *node, const char *key, const unsigned *value);
NGL_API int ngl_node_param_set_uvec4(struct ngl_node *node, const char *key, const unsigned *value);
NGL_API int ngl_node_param_set_vec2(struct ngl_node *node, const char *key, const float *value);
NGL_API int ngl_node_param_set_vec3(struct ngl_node *node, const char *key, const float *value);
NGL_API int ngl_node_param_set_vec4(struct ngl_node *node, const char *key, const float *value);

/**
 * Serialize in Graphviz format (.dot) a node graph.
 *
 * Must be destroyed using free().
 *
 * @return an allocated string in dot format or NULL on error
 *
 * @see ngl_dot()
 */
NGL_API char *ngl_node_dot(const struct ngl_node *node);

/**
 * Serialize in node.gl format (.ngl).
 *
 * Must be destroyed using free().
 *
 * @return an allocated string in node.gl format or NULL on error
 */
NGL_API char *ngl_node_serialize(const struct ngl_node *node);

/**
 * De-serialize a scene.
 *
 * @param s  string in node.gl serialized format.
 *
 * Must be destroyed using ngl_node_unrefp().
 *
 * @return a pointer to the de-serialized node graph or NULL on error
 */
NGL_API struct ngl_node *ngl_node_deserialize(const char *s);

/*
 * Live controls
 */

union ngl_livectl_data {
    float f[4];     /* f32, vec2, vec3, vec4 */
    int32_t i[4];   /* i32, ivec2, ivec3, ivec4, bool */
    uint32_t u[4];  /* u32, uvec2, uvec3, uvec4 */
    float m[16];    /* mat4 */
    char *s;        /* str */
};

struct ngl_livectl {
    char *id;                   /* printable unique identifier specified by the user through the live_id parameter */
    uint32_t node_type;         /* NGL_NODE_* */
    struct ngl_node *node;      /* the node that was flagged with a live_id */
    union ngl_livectl_data val; /* copy of the value held by the node when ngl_livectls_get() was called */
    union ngl_livectl_data min; /* minimum value specified by the user, to interpret according to node_type */
    union ngl_livectl_data max; /* maximum value specified by the user, to interpret according to node_type */
};

/**
 * Returns the available live controls in a given scene.
 *
 * Any node with a live_id parameter can be exposed as a live control. In order
 * to do so, the user has to set its live_id parameter to an arbitrary string
 * that must be unique to the scene.
 *
 * @param nb_livectlsp a pointer to an integer set to the number of live
 *                     controls available
 * @param livectlsp    a pointer to an array of ngl_livectl structures. The
 *                     array is allocated by ngl_livectls_get() and has a
 *                     size of nb_livectlsp. Must be freed by the user using
 *                     ngl_livectls_freep()
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_livectls_get(struct ngl_node *scene, int *nb_livectlsp, struct ngl_livectl **livectlsp);

NGL_API void ngl_livectls_freep(struct ngl_livectl **livectlsp);

/**
 * Platform-specific identifiers
 */
enum {
    NGL_PLATFORM_AUTO,
    NGL_PLATFORM_XLIB,
    NGL_PLATFORM_ANDROID,
    NGL_PLATFORM_MACOS,
    NGL_PLATFORM_IOS,
    NGL_PLATFORM_WINDOWS,
    NGL_PLATFORM_WAYLAND,
};

/**
 * Rendering backends
 */
enum {
    NGL_BACKEND_AUTO,
    NGL_BACKEND_OPENGL,
    NGL_BACKEND_OPENGLES,
    NGL_BACKEND_VULKAN,
    NGL_NB_BACKEND
};

/**
 * Capture buffer types
 */
enum {
    NGL_CAPTURE_BUFFER_TYPE_CPU,
    NGL_CAPTURE_BUFFER_TYPE_COREVIDEO,
};

/**
 * Backend specific configuration
 */

struct ngl_config_gl {
    /*
     * Whether the OpenGL context is external or not. If the OpenGL context is
     * external, it is the user responsibility to manage the OpenGL context and
     * make sure it is current before calling any of the ngl_* functions.
     */
    int external;
    /*
     * External OpenGL framebuffer used for rendering. The framebuffer must
     * have a color attachment composed of 4 color components (R, G, B, A) and
     * a combined depth and stencil buffer attached to it.
     */
    uint32_t external_framebuffer;
};

/**
 * node.gl configuration
 */
struct ngl_config {
    int platform;  /* Platform-specific identifier (any of NGL_PLATFORM_*) */

    int backend;   /* Rendering backend (any of NGL_BACKEND_*) */

    void *backend_config; /* Optional backend specific configuration (any of ngl_config_*
                             depending on the selected backend) */

    uintptr_t display; /* A native display handle */

    uintptr_t window;  /* A native window handle */

    int swap_interval; /* Specifies the minimum number of video frames that are
                          displayed before a buffer swap will occur. -1 can be
                          used to use the default system implementation value.
                          This option is only honored on Linux, macOS, and
                          Android (iOS does not provide swap interval control).
                          */

    int offscreen; /* Whether the rendering should happen offscreen or not.
                      This field is ignored if the context is external. */

    int width;     /* Graphic context width, mandatory for offscreen rendering */

    int height;    /* Graphic context height, mandatory for offscreen rendering */

    int viewport[4]; /* Viewport defined as x, y, width and height */

    int samples;   /* Number of samples used for multisample anti-aliasing */

    int set_surface_pts; /* Whether pts should be set to the surface or not (Android only).
                            Unsupported with offscreen rendering. */

    float clear_color[4]; /* Clear color (red, green, blue, alpha) */

    void *capture_buffer; /* An optional pointer to a capture buffer.
                             - If the capture buffer type is CPU, the user
                               allocated size of the specified buffer must be of
                               at least width * height * 4 bytes (RGBA)
                             - If the capture buffer type is COREVIDEO, the
                               specified pointer must reference a CVPixelBuffer */

    int capture_buffer_type; /* Any of NGL_CAPTURE_BUFFER_TYPE_* */

    int hud;                 /* Enable the debug HUD */

    int hud_measure_window;  /* Window size for the latency measures displayed by the HUD.
                                Defaults to 60 */

    int hud_refresh_rate[2]; /* HUD refresh rate */

    const char *hud_export_filename; /* Path to the HUD export file (CSV). Disables display if enabled. */

    int hud_scale;           /* Scaling applied to the HUD, useful for high DPI displays */
};

#define NGL_CAP_BLOCK                         NGL_NODE_BLOCK
#define NGL_CAP_COMPUTE                       NGL_NODE_COMPUTE
#define NGL_CAP_DEPTH_STENCIL_RESOLVE         NGLI_FOURCC('D','S','R','s')
#define NGL_CAP_INSTANCED_DRAW                NGLI_FOURCC('I','D','r','w')
#define NGL_CAP_MAX_COLOR_ATTACHMENTS         NGLI_FOURCC('M','C','A','t')
#define NGL_CAP_MAX_COMPUTE_GROUP_COUNT_X     NGLI_FOURCC('C','G','c','x')
#define NGL_CAP_MAX_COMPUTE_GROUP_COUNT_Y     NGLI_FOURCC('C','G','c','y')
#define NGL_CAP_MAX_COMPUTE_GROUP_COUNT_Z     NGLI_FOURCC('C','G','c','z')
#define NGL_CAP_MAX_COMPUTE_GROUP_INVOCATIONS NGLI_FOURCC('C','G','i','v')
#define NGL_CAP_MAX_COMPUTE_GROUP_SIZE_X      NGLI_FOURCC('C','G','s','x')
#define NGL_CAP_MAX_COMPUTE_GROUP_SIZE_Y      NGLI_FOURCC('C','G','s','y')
#define NGL_CAP_MAX_COMPUTE_GROUP_SIZE_Z      NGLI_FOURCC('C','G','s','z')
#define NGL_CAP_MAX_COMPUTE_SHARED_MEMORY_SIZE NGLI_FOURCC('C','S','M','s')
#define NGL_CAP_MAX_SAMPLES                   NGLI_FOURCC('M','S','A','A')
#define NGL_CAP_MAX_TEXTURE_DIMENSION_1D      NGLI_FOURCC('M','T','D','1')
#define NGL_CAP_MAX_TEXTURE_DIMENSION_2D      NGLI_FOURCC('M','T','D','2')
#define NGL_CAP_MAX_TEXTURE_DIMENSION_3D      NGLI_FOURCC('M','T','D','3')
#define NGL_CAP_MAX_TEXTURE_DIMENSION_CUBE    NGLI_FOURCC('M','T','D','C')
#define NGL_CAP_NPOT_TEXTURE                  NGLI_FOURCC('N','P','O','T')
#define NGL_CAP_SHADER_TEXTURE_LOD            NGLI_FOURCC('S','T','L','d')
#define NGL_CAP_TEXTURE_3D                    NGL_NODE_TEXTURE3D
#define NGL_CAP_TEXTURE_CUBE                  NGL_NODE_TEXTURECUBE
#define NGL_CAP_UINT_UNIFORMS                 NGLI_FOURCC('U','i','n','t')

struct ngl_cap {
    unsigned id;            /* any of NGL_CAP_* */
    const char *string_id;  /* unique capability identifier string */
    uint32_t value;
};

struct ngl_backend {
    int id;                 /* any of NGL_BACKEND_* */
    const char *string_id;  /* unique backend identifier string */
    const char *name;
    int is_default;
    struct ngl_cap *caps;
    int nb_caps;
};

/**
 * Returns the available backends for a given configuration.
 *
 * @param user_config a ngl_config structure used to intialize the different
 * backends. If ngl_config.backend is set to NGL_BACKEND_AUTO,
 * ngl_backends_probe() will probe every supported backends, otherwise, it will
 * only probe the specified backend
 *
 * @param nb_backendsp a pointer to an integer set to the number of backends
 * available
 *
 * @param backendsp a pointer to an array of ngl_backend structures. The array
 * is allocated by ngl_backends_probe() and has a size of nb_backends. Must be
 * freed by the user using ngl_backends_freep()
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_backends_probe(const struct ngl_config *user_config, int *nb_backendsp, struct ngl_backend **backendsp);

/**
 * Identical to ngl_backends_probe() without graphics resources initialization.
 *
 * This means that ngl_backend.caps won't be set and that all the returned
 * backends may not be supported on the host.
 */
NGL_API int ngl_backends_get(const struct ngl_config *user_config, int *nb_backendsp, struct ngl_backend **backendsp);

NGL_API void ngl_backends_freep(struct ngl_backend **backendsp);

/**
 * Opaque structure identifying a node.gl context
 */
struct ngl_ctx;

/**
 * Allocate a new node.gl context.
 *
 * Must be destroyed using ngl_freep().
 *
 * This function does not perform any OpenGL operation.
 *
 * @return a pointer to the context, or NULL on error
 */
NGL_API struct ngl_ctx *ngl_create(void);

/**
 * Configure the node.gl context.
 *
 * This function must be called before any ngl_draw() call.
 *
 * This function must be called on the UI/main thread on iOS/macOS.
 *
 * If the context has already been configured, calling ngl_configure() will
 * perform a hard-reconfiguration meaning it will de-allocate the ressources of
 * any associated scene, reconfigure the rendering backend and finally
 * re-allocate the ressources of any previously associated scene.
 *
 * @param s        pointer to a node.gl context
 * @param config   pointer to a node.gl configuration structure (cannot be NULL)
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_configure(struct ngl_ctx *s, struct ngl_config *config);

/**
 * Update the swap chain buffers size.
 *
 * This function must be called on the UI/main thread on iOS/macOS.
 *
 * @param width new width of the swap chain buffers
 * @param height new height of the swap chain buffers
 * @param viewport new viewport of the current render target,
 *                 a NULL pointer will make the new viewport match the
 *                 dimensions of the swap chain buffers
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_resize(struct ngl_ctx *s, int width, int height, const int *viewport);

/**
 * Set a new buffer for offscreen capture.
 *
 * Set a new buffer used for offscreen capture (and replace any previous one).
 * The capture buffer type must match the ngl_config.capture_buffer_type used
 * to configure the node.gl context.
 *
 * @param s               pointer to a node.gl context
 * @params capture_buffer pointer to a capture buffer, if NULL no capture will
 *                        be performed for the following ngl_draw() calls.
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_set_capture_buffer(struct ngl_ctx *s, void *capture_buffer);

/**
 * Associate a scene with a node.gl context.
 *
 * The reference counter of the root node will be incremented and all its node
 * will be associated with the specified node.gl context.
 *
 * The nodes can be associated with only one node.gl context.
 *
 * If any scene was previously associated with the context, it is detached from
 * it and its reference counter decremented.
 *
 * To only detach the currently associated scene, scene=NULL can be used.
 *
 * @param s      pointer to the configured node.gl context
 * @param scene  pointer to the scene
 *
 * @note node.gl context must to be configured before calling this function.
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_set_scene(struct ngl_ctx *s, struct ngl_node *scene);

/**
 * Draw at the specified time.
 *
 * @param s     pointer to the configured node.gl context
 * @param t     target draw time in seconds
 *
 * @note ngl_draw() will only perform a clear if no scene is set.
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_draw(struct ngl_ctx *s, double t);

/**
 * Serialize the current scene in Graphviz format (.dot) a node graph at the
 * specified time. Non active nodes will be grayed.
 *
 * Must be destroyed using free().
 *
 * @return an allocated string in dot format or NULL on error
 *
 * @see ngl_node_dot()
 */
NGL_API char *ngl_dot(struct ngl_ctx *s, double t);

/**
 * Destroy a node.gl context. The passed context pointer will also be set to
 * NULL.
 *
 * @param ss    pointer to the pointer to the node.gl context
 */
NGL_API void ngl_freep(struct ngl_ctx **ss);

/**
 * Evaluate an animation at a given time t.
 *
 * @param anim  the animation node can be any of AnimatedFloat, AnimatedVec2,
 *              AnimatedVec3, AnimatedVec4, AnimatedQuat, VelocityFloat,
 *              VelocityVec2, VelocityVec3 or VelocityVec4
 * @param dst   pointer to the destination for the interpolated value(s), needs
 *              to hold enough space depending on the type of anim:
 *              - float[1]: AnimatedFloat, VelocityFloat
 *              - float[2]: AnimatedVec2, VelocityVec2
 *              - float[3]: AnimatedVec3, VelocityVec3
 *              - float[4]: AnimatedVec4, VelocityVec4, AnimatedQuat
 * @param t     the target time at which to interpolate the value(s)
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_anim_evaluate(struct ngl_node *anim, void *dst, double t);

/**
 * Evaluate an easing at a given time t.
 *
 * @param name      the easing name
 * @param args      a list of arguments some easings may use, can be NULL
 * @param nb_args   number of arguments in args
 * @param offsets   starting and ending offset of the truncation of the easing, can be NULL or point to two doubles
 * @param t         the target time
 * @param v         pointer for the resulting value
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_easing_evaluate(const char *name, const double *args, int nb_args,
                                const double *offsets, double t, double *v);

/**
 * Solve an easing for a given value t.
 *
 * @param name      the easing name
 * @param args      a list of arguments some easings may use, can be NULL
 * @param nb_args   number of arguments in args
 * @param offsets   starting and ending offset of the truncation of the easing, can be NULL or point to two doubles
 * @param v         the target value
 * @param t         pointer for the resulting time
 *
 * @note Not all easings have a resolution function available
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_easing_solve(const char *name, const double *args, int nb_args,
                             const double *offsets, double v, double *t);

/**
 * Derivate an easing for a given time t.
 *
 * @param name      the easing name
 * @param args      a list of arguments some easings may use, can be NULL
 * @param nb_args   number of arguments in args
 * @param offsets   starting and ending offset of the truncation of the easing, can be NULL or point to two doubles
 * @param t         the target time
 * @param v         pointer for the resulting derivative value
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_easing_derivate(const char *name, const double *args, int nb_args,
                                const double *offsets, double t, double *v);

/**
 * OpenGL
 */

/**
 * Wrap a new external OpenGL framebuffer and use it for rendering
 *
 * The framebuffer must have a color attachment composed of 4 color components
 * (R, G, B, A) and a combined depth and stencil buffer attached to it.
 *
 * This function only works if the OpenGL context is external.
 *
 * @param s               pointer to a node.gl context
 * @params framebuffer    OpenGL framebuffer identifier to wrap
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_gl_wrap_framebuffer(struct ngl_ctx *s, uint32_t framebuffer);

/**
 * Android
 */

/**
 * Set a Java virtual machine that will be used to retrieve the JNI
 * environment.
 *
 * @param vm    pointer to the Java virtual machine
 *
 * @return 0 on success, NGL_ERROR_* (< 0) on error
 */
NGL_API int ngl_jni_set_java_vm(void *vm);

/**
 * Get the Java virtual machine pointer that has been set with
 * ngl_jni_set_java_vm().
 *
 * @return a pointer to the Java virtual machine or NULL if none has been set
 */
NGL_API void *ngl_jni_get_java_vm(void);

/**
 * Set the Android application context.
 *
 * @param application_context   JNI global reference of the Android application
 *                              context
 */
NGL_API int ngl_android_set_application_context(void *application_context);

/**
 * Get the Android application context that has been set with
 * ngl_android_set_application_context().
 *
 * @return a pointer to the JNI global reference of the Android application
 *         context or NULL if none has been set
 */
NGL_API void *ngl_android_get_application_context(void);

#endif