text: /*
   * HEIF codec.
   * Copyright (c) 2017 struktur AG, Dirk Farin <farin@struktur.de>
   *
   * This file is part of libheif.
   *
   * libheif is free software: you can redistribute it and/or modify
   * it under the terms of the GNU Lesser General Public License as
   * published by the Free Software Foundation, either version 3 of
   * the License, or (at your option) any later version.
   *
   * libheif is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public License
   * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
   */
  
  #ifndef LIBHEIF_HEIF_PLUGIN_H
  #define LIBHEIF_HEIF_PLUGIN_H
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #include <libheif/heif.h>
  
  
  // ====================================================================================================
  //  This file is for codec plugin developers only.
  // ====================================================================================================
  
  // API versions table
  //
  // release    decoder   encoder   enc.params
  // -----------------------------------------
  //  1.0          1        N/A        N/A
  //  1.1          1         1          1
  //  1.4          1         1          2
  //  1.8          1         2          2
  
  
  // ====================================================================================================
  //  Decoder plugin API
  //  In order to decode images in other formats than HEVC, additional compression codecs can be
  //  added as plugins. A plugin has to implement the functions specified in heif_decoder_plugin
  //  and the plugin has to be registered to the libheif library using heif_register_decoder().
  
  struct heif_decoder_plugin
  {
    // API version supported by this plugin
    int plugin_api_version; // current version: 1
  
  
    // --- version 1 functions ---
  
    // Human-readable name of the plugin
    const char* (* get_plugin_name)();
  
    // Global plugin initialization (may be NULL)
    void (* init_plugin)();
  
    // Global plugin deinitialization (may be NULL)
    void (* deinit_plugin)();
  
    // Query whether the plugin supports decoding of the given format
    // Result is a priority value. The plugin with the largest value wins.
    // Default priority is 100.
    int (* does_support_format)(enum heif_compression_format format);
  
    // Create a new decoder context for decoding an image
    struct heif_error (* new_decoder)(void** decoder);
  
    // Free the decoder context (heif_image can still be used after destruction)
    void (* free_decoder)(void* decoder);
  
    // Push more data into the decoder. This can be called multiple times.
    // This may not be called after any decode_*() function has been called.
    struct heif_error (* push_data)(void* decoder, const void* data, size_t size);
  
  
    // --- After pushing the data into the decoder, the decode functions may be called only once.
  
    struct heif_error (* decode_image)(void* decoder, struct heif_image** out_img);
  
  
    // --- version 2 functions will follow below ... ---
  
    // If not NULL, this can provide a specialized function to convert YCbCr to sRGB, because
    // only the codec itself knows how to interpret the chroma samples and their locations.
    /*
    struct heif_error (*convert_YCbCr_to_sRGB)(void* decoder,
                                               struct heif_image* in_YCbCr_img,
                                               struct heif_image** out_sRGB_img);
  
    */
  
    // Reset decoder, such that we can feed in new data for another image.
    // void (*reset_image)(void* decoder);
  };
  
  
  enum heif_encoded_data_type
  {
    heif_encoded_data_type_HEVC_header = 1,
    heif_encoded_data_type_HEVC_image = 2,
    heif_encoded_data_type_HEVC_depth_SEI = 3
  };
  
  
  // Specifies the class of the input image content.
  // The encoder may want to encode different classes with different parameters
  // (e.g. always encode alpha lossless)
  enum heif_image_input_class
  {
    heif_image_input_class_normal = 1,
    heif_image_input_class_alpha = 2,
    heif_image_input_class_depth = 3,
    heif_image_input_class_thumbnail = 4
  };
  
  
  struct heif_encoder_plugin
  {
    // API version supported by this plugin
    int plugin_api_version; // current version: 2
  
  
    // --- version 1 functions ---
  
    // The compression format generated by this plugin.
    enum heif_compression_format compression_format;
  
    // Short name of the encoder that can be used as command line parameter when selecting an encoder.
    // Hence, it should stay stable and not contain any version numbers that will change.
    const char* id_name;
  
    // Default priority is 100.
    int priority;
  
  
    // Feature support
    int supports_lossy_compression;
    int supports_lossless_compression;
  
  
    // Human-readable name of the plugin
    const char* (* get_plugin_name)();
  
    // Global plugin initialization (may be NULL)
    void (* init_plugin)();
  
    // Global plugin cleanup (may be NULL).
    // Free data that was allocated in init_plugin()
    void (* cleanup_plugin)();
  
    // Create a new decoder context for decoding an image
    struct heif_error (* new_encoder)(void** encoder);
  
    // Free the decoder context (heif_image can still be used after destruction)
    void (* free_encoder)(void* encoder);
  
    struct heif_error (* set_parameter_quality)(void* encoder, int quality);
  
    struct heif_error (* get_parameter_quality)(void* encoder, int* quality);
  
    struct heif_error (* set_parameter_lossless)(void* encoder, int lossless);
  
    struct heif_error (* get_parameter_lossless)(void* encoder, int* lossless);
  
    struct heif_error (* set_parameter_logging_level)(void* encoder, int logging);
  
    struct heif_error (* get_parameter_logging_level)(void* encoder, int* logging);
  
    const struct heif_encoder_parameter** (* list_parameters)(void* encoder);
  
    struct heif_error (* set_parameter_integer)(void* encoder, const char* name, int value);
  
    struct heif_error (* get_parameter_integer)(void* encoder, const char* name, int* value);
  
    struct heif_error (* set_parameter_boolean)(void* encoder, const char* name, int value);
  
    struct heif_error (* get_parameter_boolean)(void* encoder, const char* name, int* value);
  
    struct heif_error (* set_parameter_string)(void* encoder, const char* name, const char* value);
  
    struct heif_error (* get_parameter_string)(void* encoder, const char* name, char* value, int value_size);
  
    // Replace the input colorspace/chroma with the one that is supported by the encoder and that
    // comes as close to the input colorspace/chroma as possible.
    void (* query_input_colorspace)(enum heif_colorspace* inout_colorspace,
                                    enum heif_chroma* inout_chroma);
  
    // Encode an image.
    // After pushing an image into the encoder, you should call get_compressed_data() to
    // get compressed data until it returns a NULL data pointer.
    struct heif_error (* encode_image)(void* encoder, const struct heif_image* image,
                                       enum heif_image_input_class image_class);
  
    // Get a packet of decoded data. The data format depends on the codec.
    // For HEVC, each packet shall contain exactly one NAL, starting with the NAL header without startcode.
    struct heif_error (* get_compressed_data)(void* encoder, uint8_t** data, int* size,
                                              enum heif_encoded_data_type* type);
  
  
    // --- version 2 ---
  
    void (* query_input_colorspace2)(void* encoder,
                                     enum heif_colorspace* inout_colorspace,
                                     enum heif_chroma* inout_chroma);
  
    // --- version 3 ---
  
    // The encoded image size may be different from the input frame size, e.g. because
    // of required rounding, or a required minimum size. Use this function to return
    // the encoded size for a given input image size.
    void (* query_encoded_size)(void* encoder, uint32_t input_width, uint32_t input_height,
                                uint32_t* encoded_width, uint32_t* encoded_height);
  
    // --- version 4 functions will follow below ... ---
  };
  
  
  // Names for standard parameters. These should only be used by the encoder plugins.
  #define heif_encoder_parameter_name_quality  "quality"
  #define heif_encoder_parameter_name_lossless "lossless"
  
  // For use only by the encoder plugins.
  // Application programs should use the access functions.
  struct heif_encoder_parameter
  {
    int version; // current version: 2
  
    // --- version 1 fields ---
  
    const char* name;
    enum heif_encoder_parameter_type type;
  
    union
    {
      struct
      {
        int default_value;
  
        uint8_t have_minimum_maximum; // bool
        int minimum;
        int maximum;
  
        int* valid_values;
        int num_valid_values;
      } integer;
  
      struct
      {
        const char* default_value;
  
        const char* const* valid_values;
      } string; // NOLINT
  
      struct
      {
        int default_value;
      } boolean;
    };
  
    // --- version 2 fields
  
    int has_default;
  };
  
  
  extern struct heif_error heif_error_ok;
  extern struct heif_error heif_error_unsupported_parameter;
  extern struct heif_error heif_error_invalid_parameter_value;
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif
  