• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • graphics API Reference
  • KDE Home
  • Contact Us
 

digikam

  • extragear
  • graphics
  • digikam
  • core
  • dplugins
  • dimg
  • heif
  • libheif
heif_plugin.h
Go to the documentation of this file.
1 /*
2  * HEIF codec.
3  * Copyright (c) 2017 struktur AG, Dirk Farin <[email protected]>
4  *
5  * This file is part of libheif.
6  *
7  * libheif is free software: you can redistribute it and/or modify
8  * it under the terms of the GNU Lesser General Public License as
9  * published by the Free Software Foundation, either version 3 of
10  * the License, or (at your option) any later version.
11  *
12  * libheif is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License
18  * along with libheif. If not, see <http://www.gnu.org/licenses/>.
19  */
20 
21 #ifndef LIBHEIF_HEIF_PLUGIN_H
22 #define LIBHEIF_HEIF_PLUGIN_H
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 #include <libheif/heif.h>
29 
30 
31 // ====================================================================================================
32 // This file is for codec plugin developers only.
33 // ====================================================================================================
34 
35 // API versions table
36 //
37 // release decoder encoder enc.params
38 // -----------------------------------------
39 // 1.0 1 N/A N/A
40 // 1.1 1 1 1
41 
42 
43 
44 // ====================================================================================================
45 // Decoder plugin API
46 // In order to decode images in other formats than HEVC, additional compression codecs can be
47 // added as plugins. A plugin has to implement the functions specified in heif_decoder_plugin
48 // and the plugin has to be registered to the libheif library using heif_register_decoder().
49 
50 struct heif_decoder_plugin
51 {
52  // API version supported by this plugin
53  int plugin_api_version; // current version: 1
54 
55 
56  // --- version 1 functions ---
57 
58  // Human-readable name of the plugin
59  const char* (*get_plugin_name)();
60 
61  // Global plugin initialization (may be NULL)
62  void (*init_plugin)();
63 
64  // Global plugin deinitialization (may be NULL)
65  void (*deinit_plugin)();
66 
67  // Query whether the plugin supports decoding of the given format
68  // Result is a priority value. The plugin with the largest value wins.
69  // Default priority is 100.
70  int (*does_support_format)(enum heif_compression_format format);
71 
72  // Create a new decoder context for decoding an image
73  struct heif_error (*new_decoder)(void** decoder);
74 
75  // Free the decoder context (heif_image can still be used after destruction)
76  void (*free_decoder)(void* decoder);
77 
78  // Push more data into the decoder. This can be called multiple times.
79  // This may not be called after any decode_*() function has been called.
80  struct heif_error (*push_data)(void* decoder, const void* data, size_t size);
81 
82 
83  // --- After pushing the data into the decoder, the decode functions may be called only once.
84 
85  // Decode data into a full image. All data has to be pushed into the decoder before calling this.
86  struct heif_error (*decode_image)(void* decoder, struct heif_image** out_img);
87 
88 
89  // --- version 2 functions will follow below ... ---
90 
91 
92 
93  // Reset decoder, such that we can feed in new data for another image.
94  // void (*reset_image)(void* decoder);
95 };
96 
97 
98 
99 enum heif_encoded_data_type
100 {
101  heif_encoded_data_type_HEVC_header = 1,
102  heif_encoded_data_type_HEVC_image = 2,
103  heif_encoded_data_type_HEVC_depth_SEI = 3
104 };
105 
106 
107 // Specifies the class of the input image content.
108 // The encoder may want to encode different classes with different parameters
109 // (e.g. always encode alpha lossless)
110 enum heif_image_input_class
111 {
112  heif_image_input_class_normal = 1,
113  heif_image_input_class_alpha = 2,
114  heif_image_input_class_depth = 3,
115  heif_image_input_class_thumbnail = 4
116 };
117 
118 
119 struct heif_encoder_plugin
120 {
121  // API version supported by this plugin
122  int plugin_api_version; // current version: 1
123 
124 
125  // --- version 1 functions ---
126 
127  // The compression format generated by this plugin.
128  enum heif_compression_format compression_format;
129 
130  // Short name of the encoder that can be used as command line parameter when selecting an encoder.
131  // Hence, it should stay stable and not contain any version numbers that will change.
132  const char* id_name;
133 
134  // Default priority is 100.
135  int priority;
136 
137 
138  // Feature support
139  int supports_lossy_compression;
140  int supports_lossless_compression;
141 
142 
143  // Human-readable name of the plugin
144  const char* (*get_plugin_name)();
145 
146  // Global plugin initialization (may be NULL)
147  void (*init_plugin)();
148 
149  // Global plugin cleanup (may be NULL).
150  // Free data that was allocated in init_plugin()
151  void (*cleanup_plugin)();
152 
153  // Create a new decoder context for decoding an image
154  struct heif_error (*new_encoder)(void** encoder);
155 
156  // Free the decoder context (heif_image can still be used after destruction)
157  void (*free_encoder)(void* encoder);
158 
159  struct heif_error (*set_parameter_quality)(void* encoder, int quality);
160  struct heif_error (*get_parameter_quality)(void* encoder, int* quality);
161 
162  struct heif_error (*set_parameter_lossless)(void* encoder, int lossless);
163  struct heif_error (*get_parameter_lossless)(void* encoder, int* lossless);
164 
165  struct heif_error (*set_parameter_logging_level)(void* encoder, int logging);
166  struct heif_error (*get_parameter_logging_level)(void* encoder, int* logging);
167 
168  const struct heif_encoder_parameter** (*list_parameters)(void* encoder);
169 
170  struct heif_error (*set_parameter_integer)(void* encoder, const char* name, int value);
171  struct heif_error (*get_parameter_integer)(void* encoder, const char* name, int* value);
172  struct heif_error (*set_parameter_boolean)(void* encoder, const char* name, int value);
173  struct heif_error (*get_parameter_boolean)(void* encoder, const char* name, int* value);
174  struct heif_error (*set_parameter_string)(void* encoder, const char* name, const char* value);
175  struct heif_error (*get_parameter_string)(void* encoder, const char* name, char* value, int value_size);
176 
177  // Replace the input colorspace/chroma with the one that is supported by the encoder and that
178  // comes as close to the input colorspace/chroma as possible.
179  void (*query_input_colorspace)(enum heif_colorspace* inout_colorspace,
180  enum heif_chroma* inout_chroma);
181 
182  // Encode an image.
183  // After pushing an image into the encoder, you should call get_compressed_data() to
184  // get compressed data until it returns a NULL data pointer.
185  struct heif_error (*encode_image)(void* encoder, const struct heif_image* image,
186  enum heif_image_input_class image_class);
187 
188  // Get a packet of decoded data. The data format depends on the codec.
189  // For HEVC, each packet shall contain exactly one NAL, starting with the NAL header without startcode.
190  struct heif_error (*get_compressed_data)(void* encoder, uint8_t** data, int* size,
191  enum heif_encoded_data_type* type);
192 
193 
194  // --- version 2 functions will follow below ... ---
195 
196 
197 
198 };
199 
200 
201 // Names for standard parameters. These should only be used by the encoder plugins.
202 #define heif_encoder_parameter_name_quality "quality"
203 #define heif_encoder_parameter_name_lossless "lossless"
204 
205 // For use only by the encoder plugins.
206 // Application programs should use the access functions.
207 struct heif_encoder_parameter
208 {
209  int version; // current version: 2
210 
211  // --- version 1 fields ---
212 
213  const char* name;
214  enum heif_encoder_parameter_type type;
215 
216  union {
217  struct {
218  int default_value;
219 
220  uint8_t have_minimum_maximum; // bool
221  int minimum;
222  int maximum;
223 
224  int* valid_values;
225  int num_valid_values;
226  } integer;
227 
228  struct {
229  const char* default_value;
230 
231  const char*const* valid_values;
232  } string; // NOLINT
233 
234  struct {
235  int default_value;
236  } boolean;
237  };
238 
239  // --- version 2 fields
240 
241  int has_default;
242 };
243 
244 
245 
246 extern struct heif_error heif_error_ok;
247 extern struct heif_error heif_error_unsupported_parameter;
248 extern struct heif_error heif_error_invalid_parameter_value;
249 
250 #ifdef __cplusplus
251 }
252 #endif
253 
254 #endif
heif_encoder_plugin::set_parameter_integer
struct heif_error(* set_parameter_integer)(void *encoder, const char *name, int value)
Definition: heif_plugin.h:170
heif_encoder_parameter::default_value
int default_value
Definition: heif_plugin.h:218
heif_error
Definition: heif.h:255
heif_chroma
heif_chroma
Definition: heif.h:714
heif_encoder_plugin::get_parameter_boolean
struct heif_error(* get_parameter_boolean)(void *encoder, const char *name, int *value)
Definition: heif_plugin.h:173
heif_encoder_plugin::cleanup_plugin
void(* cleanup_plugin)()
Definition: heif_plugin.h:151
heif_colorspace
heif_colorspace
Definition: heif.h:733
heif_image_input_class_alpha
Definition: heif_plugin.h:113
heif_encoder_plugin::get_parameter_logging_level
struct heif_error(* get_parameter_logging_level)(void *encoder, int *logging)
Definition: heif_plugin.h:166
heif_encoder_parameter::string
struct heif_encoder_parameter::@22::@25 string
heif_encoder_plugin::init_plugin
void(* init_plugin)()
Definition: heif_plugin.h:147
heif_encoder_parameter::name
const char * name
Definition: heif_plugin.h:213
heif_encoder_plugin::compression_format
enum heif_compression_format compression_format
Definition: heif_plugin.h:128
heif_encoder_plugin::get_compressed_data
struct heif_error(* get_compressed_data)(void *encoder, uint8_t **data, int *size, enum heif_encoded_data_type *type)
Definition: heif_plugin.h:190
heif_encoder_plugin::get_parameter_quality
struct heif_error(* get_parameter_quality)(void *encoder, int *quality)
Definition: heif_plugin.h:160
heif_encoded_data_type
heif_encoded_data_type
Definition: heif_plugin.h:99
heif_encoder_plugin::set_parameter_lossless
struct heif_error(* set_parameter_lossless)(void *encoder, int lossless)
Definition: heif_plugin.h:162
heif_decoder_plugin::free_decoder
void(* free_decoder)(void *decoder)
Definition: heif_plugin.h:76
heif_encoder_parameter::have_minimum_maximum
uint8_t have_minimum_maximum
Definition: heif_plugin.h:220
heif_encoder_parameter::default_value
const char * default_value
Definition: heif_plugin.h:229
heif_encoded_data_type_HEVC_header
Definition: heif_plugin.h:101
heif_encoder_parameter::valid_values
int * valid_values
Definition: heif_plugin.h:224
heif_error_ok
struct heif_error heif_error_ok
Definition: heif_plugin.cc:24
heif_decoder_plugin::new_decoder
struct heif_error(* new_decoder)(void **decoder)
Definition: heif_plugin.h:73
value
qulonglong value
Definition: itemviewutilities.cpp:530
heif_decoder_plugin::deinit_plugin
void(* deinit_plugin)()
Definition: heif_plugin.h:65
heif_encoder_plugin::get_parameter_string
struct heif_error(* get_parameter_string)(void *encoder, const char *name, char *value, int value_size)
Definition: heif_plugin.h:175
heif_encoder_plugin::supports_lossless_compression
int supports_lossless_compression
Definition: heif_plugin.h:140
heif.h
heif_encoder_parameter::valid_values
const char *const * valid_values
Definition: heif_plugin.h:231
heif_encoder_parameter::type
enum heif_encoder_parameter_type type
Definition: heif_plugin.h:214
heif_encoder_plugin::priority
int priority
Definition: heif_plugin.h:135
heif_error_unsupported_parameter
struct heif_error heif_error_unsupported_parameter
Definition: heif_plugin.cc:26
heif_encoder_plugin::encode_image
struct heif_error(* encode_image)(void *encoder, const struct heif_image *image, enum heif_image_input_class image_class)
Definition: heif_plugin.h:185
heif_encoder_plugin::get_parameter_integer
struct heif_error(* get_parameter_integer)(void *encoder, const char *name, int *value)
Definition: heif_plugin.h:171
heif_encoder_plugin::set_parameter_logging_level
struct heif_error(* set_parameter_logging_level)(void *encoder, int logging)
Definition: heif_plugin.h:165
heif_decoder_plugin::decode_image
struct heif_error(* decode_image)(void *decoder, struct heif_image **out_img)
Definition: heif_plugin.h:86
heif_image_input_class_thumbnail
Definition: heif_plugin.h:115
heif_encoder_plugin::plugin_api_version
int plugin_api_version
Definition: heif_plugin.h:122
image
#define image
Definition: var_defines.h:38
heif_decoder_plugin::push_data
struct heif_error(* push_data)(void *decoder, const void *data, size_t size)
Definition: heif_plugin.h:80
heif_encoder_parameter_type
heif_encoder_parameter_type
Definition: heif.h:1022
heif_encoder_plugin
Definition: heif_plugin.h:119
heif_compression_format
heif_compression_format
Definition: heif.h:707
heif_image_input_class_depth
Definition: heif_plugin.h:114
heif_encoded_data_type_HEVC_depth_SEI
Definition: heif_plugin.h:103
heif_encoder_plugin::query_input_colorspace
void(* query_input_colorspace)(enum heif_colorspace *inout_colorspace, enum heif_chroma *inout_chroma)
Definition: heif_plugin.h:179
heif_encoder_plugin::id_name
const char * id_name
Definition: heif_plugin.h:132
heif_decoder_plugin::plugin_api_version
int plugin_api_version
Definition: heif_plugin.h:53
heif_error_invalid_parameter_value
struct heif_error heif_error_invalid_parameter_value
Definition: heif_plugin.cc:30
heif_image_input_class
heif_image_input_class
Definition: heif_plugin.h:110
heif_encoder_parameter::maximum
int maximum
Definition: heif_plugin.h:222
heif_encoder_parameter::version
int version
Definition: heif_plugin.h:209
heif_decoder_plugin
Definition: heif_plugin.h:50
heif_encoder_parameter::has_default
int has_default
Definition: heif_plugin.h:241
heif_encoder_plugin::free_encoder
void(* free_encoder)(void *encoder)
Definition: heif_plugin.h:157
heif_encoder_parameter::minimum
int minimum
Definition: heif_plugin.h:221
heif_encoder_parameter::integer
struct heif_encoder_parameter::@22::@24 integer
heif_encoder_plugin::get_parameter_lossless
struct heif_error(* get_parameter_lossless)(void *encoder, int *lossless)
Definition: heif_plugin.h:163
heif_image_input_class_normal
Definition: heif_plugin.h:112
heif_encoder_plugin::set_parameter_boolean
struct heif_error(* set_parameter_boolean)(void *encoder, const char *name, int value)
Definition: heif_plugin.h:172
heif_encoder_parameter::num_valid_values
int num_valid_values
Definition: heif_plugin.h:225
heif_decoder_plugin::does_support_format
int(* does_support_format)(enum heif_compression_format format)
Definition: heif_plugin.h:70
heif_encoder_plugin::new_encoder
struct heif_error(* new_encoder)(void **encoder)
Definition: heif_plugin.h:154
heif_encoder_plugin::supports_lossy_compression
int supports_lossy_compression
Definition: heif_plugin.h:139
heif_encoder_plugin::set_parameter_quality
struct heif_error(* set_parameter_quality)(void *encoder, int quality)
Definition: heif_plugin.h:159
heif_image
Definition: heif_api_structs.h:38
heif_encoder_parameter
Definition: heif_plugin.h:207
heif_encoded_data_type_HEVC_image
Definition: heif_plugin.h:102
heif_decoder_plugin::init_plugin
void(* init_plugin)()
Definition: heif_plugin.h:62
heif_encoder_plugin::set_parameter_string
struct heif_error(* set_parameter_string)(void *encoder, const char *name, const char *value)
Definition: heif_plugin.h:174
heif_encoder_parameter::boolean
struct heif_encoder_parameter::@22::@26 boolean
This file is part of the KDE documentation.
Documentation copyright © 1996-2019 The KDE developers.
Generated on Wed Dec 11 2019 07:34:19 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

digikam

Skip menu "digikam"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages
-->

graphics API Reference

Skip menu "graphics API Reference"
  • digikam
  • KDiagram
  •     KChart
  •     KGantt
  • KPhotoAlbum
  •   AndroidRemoteControl
  • Krita
  •   libs
  •     KritaBasicFlakes
  •     brush
  •     KritaUndo2
  •     KritaFlake
  •     image
  •     KritaPlugin
  •     Krita
  •     KritaOdf
  •     KritaPigment
  •     KritaStore
  •     ui
  •     KritaWidgets
  •     KritaWidgetUtils
  •   plugins
  •     Assitants
  •     Extensions
  •     Filters
  •         KritaText
  •         KritaTextLayout
  •     Generators
  •     Formats
  •             src
  •     PaintOps
  •       libpaintop
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal