heif_library.h

Go to the documentation of this file.

/*
 * HEIF codec.
 * Copyright (c) 2017-2023 Dirk Farin <dirk.farin@gmail.com>
 *
 * 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_LIBRARY_H
#define LIBHEIF_HEIF_LIBRARY_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stddef.h>
#include <stdint.h>
 
 
// API versions table
//
// release    dec.options   enc.options   heif_reader   heif_writer   depth.rep   col.profile
// ------------------------------------------------------------------------------------------
//  1.0            1           N/A           N/A           N/A           1           N/A
//  1.1            1           N/A           N/A            1            1           N/A
//  1.3            1            1             1             1            1           N/A
//  1.4            1            1             1             1            1            1
//  1.7            2            1             1             1            1            1
//  1.9.2          2            2             1             1            1            1
//  1.10           2            3             1             1            1            1
//  1.11           2            4             1             1            1            1
//  1.13           3            4             1             1            1            1
//  1.14           3            5             1             1            1            1
//  1.15           4            5             1             1            1            1
//  1.16           5            6             1             1            1            1
//  1.18           5            7             1             1            1            1
//  1.19           6            7             2             1            1            1
//  1.20           7            7             2             1            1            1
//  1.21           8            7             2             1            1            1
//  1.22           9            8             2             1            1            1
//  1.23          10            8             2             1            1            1
 
// The LIBHEIF_API export macro is defined in its own dependency-free header so
// that heif_error.h (which is needed by this header) can use it without
// creating an include cycle.
#include <libheif/heif_export.h>
 
#define heif_fourcc(a, b, c, d) ((uint32_t)((a<<24) | (b<<16) | (c<<8) | d))
 
#include <libheif/heif_version.h>
#include <libheif/heif_error.h>
 
 
/* === version numbers === */
 
// Version string of linked libheif library.
LIBHEIF_API const char* heif_get_version(void);
 
// Numeric version of linked libheif library, encoded as 0xHHMMLL00 = hh.mm.ll, where hh, mm, ll is the decimal representation of HH, MM, LL.
// For example: 0x02150300 is version 2.21.3
LIBHEIF_API uint32_t heif_get_version_number(void);
 
// Numeric part "HH" from above. Returned as a decimal number.
LIBHEIF_API int heif_get_version_number_major(void);
// Numeric part "MM" from above. Returned as a decimal number.
LIBHEIF_API int heif_get_version_number_minor(void);
// Numeric part "LL" from above. Returned as a decimal number.
LIBHEIF_API int heif_get_version_number_maintenance(void);
 
// Helper macros to check for given versions of libheif at compile time.
#define LIBHEIF_MAKE_VERSION(h, m, l) ((h) << 24 | (m) << 16 | (l) << 8)
#define LIBHEIF_HAVE_VERSION(h, m, l) (LIBHEIF_NUMERIC_VERSION >= LIBHEIF_MAKE_VERSION(h, m, l))
 
typedef struct heif_context heif_context;
typedef struct heif_image_handle heif_image_handle;
 
typedef uint32_t heif_item_id;
typedef uint32_t heif_property_id;
 
LIBHEIF_API
void heif_string_release(const char*);
 
 
// ========================= library initialization ======================
 
typedef struct heif_init_params
{
  int version;
 
  // currently no parameters
} heif_init_params;
 
 
LIBHEIF_API
heif_error heif_init(heif_init_params*);
 
LIBHEIF_API
void heif_deinit(void);
 
 
// --- Codec plugins ---
 
// --- Plugins are currently only supported on Unix platforms.
 
typedef enum heif_plugin_type
{
  heif_plugin_type_encoder,
  heif_plugin_type_decoder
} heif_plugin_type;
 
typedef struct heif_plugin_info
{
  int version; // version of this info struct
  heif_plugin_type type;
  const void* plugin;
  void* internal_handle; // for internal use only
} heif_plugin_info;
 
LIBHEIF_API
heif_error heif_load_plugin(const char* filename, heif_plugin_info const** out_plugin);
 
LIBHEIF_API
heif_error heif_load_plugins(const char* directory,
                             const heif_plugin_info** out_plugins,
                             int* out_nPluginsLoaded,
                             int output_array_size);
 
LIBHEIF_API
heif_error heif_unload_plugin(const heif_plugin_info* plugin);
 
// Get a NULL terminated array of the plugin directories that are searched by libheif.
// This includes the paths specified in the environment variable LIBHEIF_PLUGIN_PATHS and the built-in path
// (if not overridden by the environment variable).
LIBHEIF_API
const char* const* heif_get_plugin_directories(void);
 
LIBHEIF_API
void heif_free_plugin_directories(const char* const*);
 
 
// --- register plugins
 
typedef struct heif_decoder_plugin heif_decoder_plugin;
typedef struct heif_encoder_plugin heif_encoder_plugin;
 
LIBHEIF_API
heif_error heif_register_decoder_plugin(const heif_decoder_plugin*);
 
LIBHEIF_API
heif_error heif_register_encoder_plugin(const heif_encoder_plugin*);
 
 
// DEPRECATED. Use heif_register_decoder_plugin(const struct heif_decoder_plugin*) instead.
LIBHEIF_API
heif_error heif_register_decoder(heif_context* heif, const heif_decoder_plugin*);
 
#ifdef __cplusplus
}
#endif
 
#endif