SvtJpegxs.h

/*
* Copyright(c) 2024 Intel Corporation
* SPDX - License - Identifier: BSD - 2 - Clause - Patent
*/

#ifndef _SVT_JPEG_XS_API_H_
#define _SVT_JPEG_XS_API_H_

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

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

/* API Version */
#define SVT_JPEGXS_API_VER_MAJOR (0)
#define SVT_JPEGXS_API_VER_MINOR (10)

/*Define PREFIX_API*/
#ifdef DEF_DLL
#ifdef DEF_BUILDING_SHARED_LIBS
#if defined(_WIN32)
#define PREFIX_API __declspec(dllexport)
#elif defined(__GNUC__) && __GNUC__ >= 4
#define PREFIX_API __attribute__((visibility("default")))
#else /*other compiler*/
#define PREFIX_API
#endif
#else /*DEF_BUILDING_SHARED_LIBS*/
#if defined(_WIN32)
#define PREFIX_API __declspec(dllimport)
#else /*other compiler*/
#define PREFIX_API
#endif
#endif /*DEF_BUILDING_SHARED_LIBS*/
#else  /*DEF_DLL*/
#define PREFIX_API
#endif /*DEF_DLL*/

/********************************
 * Defines
 ********************************/

#define MAX_COMPONENTS_NUM (4)

/* jpegxs Chroma Format */
typedef enum ColourFormat {
    COLOUR_FORMAT_INVALID = 0,
    COLOUR_FORMAT_PLANAR_YUV400 = 1,
    COLOUR_FORMAT_PLANAR_YUV420 = 2,        //planar: yuv420p, yuv420p10le etc.
    COLOUR_FORMAT_PLANAR_YUV422 = 3,        //planar: yuv422p, yuv422p10le etc.
    COLOUR_FORMAT_PLANAR_YUV444_OR_RGB = 4, //planar: yuv444p, rgbp, gbrp, yuv444p10le, gbrp10le etc.
    COLOUR_FORMAT_PLANAR_4_COMPONENTS = 5,  // planar 4 components, 4:4:4:4 sampling (RGBA, GBRA, YUVA444 etc.)
    COLOUR_FORMAT_GRAY = 6,
    COLOUR_FORMAT_PLANAR_YUV422_ALPHA = 7, // planar 4 components, 4:2:2:4 sampling (Y/Cb/Cr at 4:2:2 plus full-resolution alpha)
    COLOUR_FORMAT_PLANAR_MAX,

    COLOUR_FORMAT_PACKED_MIN = 20,
    COLOUR_FORMAT_PACKED_YUV444_OR_RGB, //packed rgb/bgr, 8:8:8, 24bpp, RGBRGB... / BGRBGR...
    COLOUR_FORMAT_PACKED_MAX
} ColourFormat_t;

enum VerboseMessages {
    VERBOSE_NONE = 0,
    VERBOSE_ERRORS = 1,
    VERBOSE_SYSTEM_INFO = 2,
    VERBOSE_SYSTEM_INFO_ALL = 3,
    VERBOSE_WARNINGS = 4,
    VERBOSE_INFO_MULTITHREADING = 5,
    VERBOSE_INFO_FULL = 6
};

typedef struct svt_jpeg_xs_image_config {
    uint32_t width;
    uint32_t height;
    uint8_t bit_depth;
    ColourFormat_t format;
    uint8_t components_num;
    struct {
        uint32_t width;
        uint32_t height;
        uint32_t byte_size;
    } components[MAX_COMPONENTS_NUM];
} svt_jpeg_xs_image_config_t;

typedef struct svt_jpeg_xs_image_buffer {
    void *data_yuv[MAX_COMPONENTS_NUM];      /*Allocated Data buffer for components*/
    uint32_t stride[MAX_COMPONENTS_NUM];     /*Greater than or equal to width. Not supported in decoder yet.*/
    uint32_t alloc_size[MAX_COMPONENTS_NUM]; /*Used by Encoder and Decoder to validate that the buffer size is enough.*/
    void *release_ctx_ptr;                   /*Used by pool allocator, for different allocation free to use.*/
    /*Set by encoder/decoder,
    1 indicates that buffer can be released by user
    */
    uint8_t ready_to_release;
} svt_jpeg_xs_image_buffer_t;

typedef struct svt_jpeg_xs_bitstream_buffer {
    /* Bitstream buffer,
    this pointer can be changed during encoding process,
    for deallocation please use *release_ctx_ptr
    */
    uint8_t *buffer;
    uint32_t allocation_size; /* Bitstream buffer size */
    uint32_t used_size;       /* Bitstream buffer used size */
    /*
    Encoder/decoder does not modify this pointer,
    Used by pool allocator, for different allocation free to use.
    */
    void *release_ctx_ptr;
    /*
    Set by encoder/decoder,
    1 indicates that buffer can be released by user
    */
    uint8_t ready_to_release;
    /*
    Set by encoder, unused in decoder,
    1 - indicate that this is last packetization unit within frame
    */
    uint8_t last_packet_in_frame;
} svt_jpeg_xs_bitstream_buffer_t;

typedef struct svt_jpeg_xs_frame {
    /*Common structure to keep input and output for encoder and decoder.
     *Encoder: image - is input and bitstream is output.
     *Decoder: bitstream - is input and image is output.*/
    svt_jpeg_xs_image_buffer_t image;         /* YUV buffer */
    svt_jpeg_xs_bitstream_buffer_t bitstream; /* Bitstream buffer */
    void *user_prv_ctx_ptr;                   /* Input user private context pointer, receive in output */
} svt_jpeg_xs_frame_t;

typedef enum SvtJxsErrorType {
    SvtJxsErrorNone = 0,
    SvtJxsErrorInvalidApiVersion = (int32_t)0x40001001,
    SvtJxsErrorCorrupt_Frame = (int32_t)0x4000100C,
    SvtJxsErrorInsufficientResources = (int32_t)0x80001000,
    SvtJxsErrorUndefined = (int32_t)0x80001001,
    SvtJxsErrorInvalidComponent = (int32_t)0x80001004,
    SvtJxsErrorBadParameter = (int32_t)0x80001005,
    SvtJxsErrorDestroyThreadFailed = (int32_t)0x80002012,
    SvtJxsErrorSemaphoreUnresponsive = (int32_t)0x80002021,
    SvtJxsErrorDestroySemaphoreFailed = (int32_t)0x80002022,
    SvtJxsErrorCreateMutexFailed = (int32_t)0x80002030,
    SvtJxsErrorMutexUnresponsive = (int32_t)0x80002031,
    SvtJxsErrorDestroyMutexFailed = (int32_t)0x80002032,
    SvtJxsErrorNoErrorEmptyQueue = (int32_t)0x80002033,
    SvtJxsErrorNoErrorFifoShutdown = (int32_t)0x80002034,

    //Encoder
    SvtJxsErrorEncodeFrameError = (int32_t)0x80002035,

    //Decoder
    SvtJxsErrorDecoderInvalidPointer = (int32_t)0x80003000,
    SvtJxsErrorDecoderInvalidBitstream = (int32_t)0x80003001,
    SvtJxsErrorDecoderInternal = (int32_t)0x80003002,
    SvtJxsErrorDecoderBitstreamTooShort = (int32_t)0x80003003,
    SvtJxsErrorDecoderConfigChange = (int32_t)0x80003004,
    SvtJxsDecoderEndOfCodestream = (int32_t)0x80003005,

    SvtJxsErrorMax = 0x7FFFFFFF
} SvtJxsErrorType_t;

typedef enum {
    proxy_mode_full = 0,    //0 - Off, decode the stream to Full resolution
    proxy_mode_half = 1,    //1 - Proxy-Mode 1/2, decode the stream to half the Width and Height
    proxy_mode_quarter = 2, //2 - Proxy-Mode 1/4, decode the stream to quarter the Width and Height
    proxy_mode_max
} proxy_mode_t;

/**
CPU FLAGS
*/
typedef uint64_t CPU_FLAGS;
#define CPU_FLAGS_C        (0)
#define CPU_FLAGS_MMX      (1 << 0)
#define CPU_FLAGS_SSE      (1 << 1)
#define CPU_FLAGS_SSE2     (1 << 2)
#define CPU_FLAGS_SSE3     (1 << 3)
#define CPU_FLAGS_SSSE3    (1 << 4)
#define CPU_FLAGS_SSE4_1   (1 << 5)
#define CPU_FLAGS_SSE4_2   (1 << 6)
#define CPU_FLAGS_AVX      (1 << 7)
#define CPU_FLAGS_AVX2     (1 << 8)
#define CPU_FLAGS_AVX512F  (1 << 9)
#define CPU_FLAGS_AVX512CD (1 << 10)
#define CPU_FLAGS_AVX512DQ (1 << 11)
#define CPU_FLAGS_AVX512ER (1 << 12)
#define CPU_FLAGS_AVX512PF (1 << 13)
#define CPU_FLAGS_AVX512BW (1 << 14)
#define CPU_FLAGS_AVX512VL (1 << 15)
/* Not instruction sets of their own: the AVX-512 kernels are compiled with
 * -mpopcnt and -mbmi2 for the whole directory, so the processor has to be asked
 * about those separately from AVX-512 itself. */
#define CPU_FLAGS_POPCNT   (1 << 16)
#define CPU_FLAGS_BMI2     (1 << 17)
#define CPU_FLAGS_ALL      ((CPU_FLAGS_BMI2 << 1) - 1)
#define CPU_FLAGS_INVALID  (1ULL << (sizeof(CPU_FLAGS) * 8ULL - 1ULL))

/**
 * @brief Log severity levels
 */
typedef enum {
    SVT_LOG_ALL = -1,
    SVT_LOG_FATAL = 0,
    SVT_LOG_ERROR = 1,
    SVT_LOG_WARN = 2,
    SVT_LOG_INFO = 3,
    SVT_LOG_DEBUG = 4,
} SvtLogLevel;

/**
 * @brief Log callback function signature.
 *
 * Applications can register a callback to intercept log messages from the library.
 * The callback receives every log call unfiltered (no level gating is applied before dispatch),
 * so it is the callback's own responsibility to filter by `level` if desired.
 *
 * @param[in] context Opaque user-provided context pointer (may be NULL)
 * @param[in] level   Severity level of the log message
 * @param[in] tag     Optional log tag (may be NULL)
 * @param[in] fmt     printf-style format string
 * @param[in] args    Variable argument list corresponding to the format string
 */
typedef void (*SvtJxsLogCallback)(void *context, SvtLogLevel level, const char *tag, const char *fmt, va_list args);

/**
 * Register a callback for intercepting log messages.
 *
 * When a callback is registered, all log messages are dispatched to it instead of the default
 * stderr/file output, for all encoder/decoder instances (this is a global setting). Must be called
 * before the first log call happens (i.e. before any encoder/decoder init) to take effect - calling
 * it later is a no-op. Passing a NULL callback is also a no-op.
 *
 * @param[in] callback Callback function pointer. Has no effect if NULL.
 * @param[in] context  Opaque context pointer passed back to the callback. Ignored if callback is NULL.
 */
PREFIX_API void svt_jpeg_xs_set_log_callback(SvtJxsLogCallback callback, void *context);

#ifdef __cplusplus
}
#endif // __cplusplus

#endif /*_SVT_JPEG_XS_API_H_*/