1 /* 2 * H.265 video codec. 3 * Copyright (c) 2013-2014 struktur AG, Dirk Farin <farin@struktur.de> 4 * 5 * This file is part of libde265. 6 * 7 * libde265 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 * libde265 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 libde265. If not, see <http://www.gnu.org/licenses/>. 19 */ 20 21 22 #ifndef DE265_H 23 #define DE265_H 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 #include <libde265/de265-version.h> 30 31 //#define inline static __inline 32 33 34 #ifndef __STDC_LIMIT_MACROS 35 #define __STDC_LIMIT_MACROS 1 36 #endif 37 #include <stdint.h> 38 39 #if defined(_MSC_VER) && !defined(LIBDE265_STATIC_BUILD) 40 #ifdef LIBDE265_EXPORTS 41 #define LIBDE265_API __declspec(dllexport) 42 #else 43 #define LIBDE265_API __declspec(dllimport) 44 #endif 45 #elif HAVE_VISIBILITY 46 #ifdef LIBDE265_EXPORTS 47 #define LIBDE265_API __attribute__((__visibility__("default"))) 48 #else 49 #define LIBDE265_API 50 #endif 51 #else 52 #define LIBDE265_API 53 #endif 54 55 #if __GNUC__ 56 #define LIBDE265_DEPRECATED __attribute__((deprecated)) 57 #elif defined(_MSC_VER) 58 #define LIBDE265_DEPRECATED __declspec(deprecated) 59 #else 60 #define LIBDE265_DEPRECATED 61 #endif 62 63 #if defined(_MSC_VER) 64 #define LIBDE265_INLINE __inline 65 #else 66 #define LIBDE265_INLINE inline 67 #endif 68 69 /* === version numbers === */ 70 71 // version of linked libde265 library 72 LIBDE265_API const char *de265_get_version(void); 73 LIBDE265_API uint32_t de265_get_version_number(void); 74 75 LIBDE265_API int de265_get_version_number_major(void); 76 LIBDE265_API int de265_get_version_number_minor(void); 77 LIBDE265_API int de265_get_version_number_maintenance(void); 78 79 80 /* === error codes === */ 81 82 typedef enum { 83 DE265_OK = 0, 84 DE265_ERROR_NO_SUCH_FILE=1, 85 //DE265_ERROR_NO_STARTCODE=2, obsolet 86 //DE265_ERROR_EOF=3, 87 DE265_ERROR_COEFFICIENT_OUT_OF_IMAGE_BOUNDS=4, 88 DE265_ERROR_CHECKSUM_MISMATCH=5, 89 DE265_ERROR_CTB_OUTSIDE_IMAGE_AREA=6, 90 DE265_ERROR_OUT_OF_MEMORY=7, 91 DE265_ERROR_CODED_PARAMETER_OUT_OF_RANGE=8, 92 DE265_ERROR_IMAGE_BUFFER_FULL=9, 93 DE265_ERROR_CANNOT_START_THREADPOOL=10, 94 DE265_ERROR_LIBRARY_INITIALIZATION_FAILED=11, 95 DE265_ERROR_LIBRARY_NOT_INITIALIZED=12, 96 DE265_ERROR_WAITING_FOR_INPUT_DATA=13, 97 DE265_ERROR_CANNOT_PROCESS_SEI=14, 98 DE265_ERROR_PARAMETER_PARSING=15, 99 DE265_ERROR_NO_INITIAL_SLICE_HEADER=16, 100 DE265_ERROR_PREMATURE_END_OF_SLICE=17, 101 DE265_ERROR_UNSPECIFIED_DECODING_ERROR=18, 102 103 // --- errors that should become obsolete in later libde265 versions --- 104 105 //DE265_ERROR_MAX_THREAD_CONTEXTS_EXCEEDED = 500, obsolet 106 //DE265_ERROR_MAX_NUMBER_OF_SLICES_EXCEEDED = 501, obsolet 107 DE265_ERROR_NOT_IMPLEMENTED_YET = 502, 108 //DE265_ERROR_SCALING_LIST_NOT_IMPLEMENTED = 502, obsolet 109 110 // --- warnings --- 111 112 DE265_WARNING_NO_WPP_CANNOT_USE_MULTITHREADING = 1000, 113 DE265_WARNING_WARNING_BUFFER_FULL=1001, 114 DE265_WARNING_PREMATURE_END_OF_SLICE_SEGMENT=1002, 115 DE265_WARNING_INCORRECT_ENTRY_POINT_OFFSET=1003, 116 DE265_WARNING_CTB_OUTSIDE_IMAGE_AREA=1004, 117 DE265_WARNING_SPS_HEADER_INVALID=1005, 118 DE265_WARNING_PPS_HEADER_INVALID=1006, 119 DE265_WARNING_SLICEHEADER_INVALID=1007, 120 DE265_WARNING_INCORRECT_MOTION_VECTOR_SCALING=1008, 121 DE265_WARNING_NONEXISTING_PPS_REFERENCED=1009, 122 DE265_WARNING_NONEXISTING_SPS_REFERENCED=1010, 123 DE265_WARNING_BOTH_PREDFLAGS_ZERO=1011, 124 DE265_WARNING_NONEXISTING_REFERENCE_PICTURE_ACCESSED=1012, 125 DE265_WARNING_NUMMVP_NOT_EQUAL_TO_NUMMVQ=1013, 126 DE265_WARNING_NUMBER_OF_SHORT_TERM_REF_PIC_SETS_OUT_OF_RANGE=1014, 127 DE265_WARNING_SHORT_TERM_REF_PIC_SET_OUT_OF_RANGE=1015, 128 DE265_WARNING_FAULTY_REFERENCE_PICTURE_LIST=1016, 129 DE265_WARNING_EOSS_BIT_NOT_SET=1017, 130 DE265_WARNING_MAX_NUM_REF_PICS_EXCEEDED=1018, 131 DE265_WARNING_INVALID_CHROMA_FORMAT=1019, 132 DE265_WARNING_SLICE_SEGMENT_ADDRESS_INVALID=1020, 133 DE265_WARNING_DEPENDENT_SLICE_WITH_ADDRESS_ZERO=1021, 134 DE265_WARNING_NUMBER_OF_THREADS_LIMITED_TO_MAXIMUM=1022, 135 DE265_NON_EXISTING_LT_REFERENCE_CANDIDATE_IN_SLICE_HEADER=1023, 136 DE265_WARNING_CANNOT_APPLY_SAO_OUT_OF_MEMORY=1024, 137 DE265_WARNING_SPS_MISSING_CANNOT_DECODE_SEI=1025, 138 DE265_WARNING_COLLOCATED_MOTION_VECTOR_OUTSIDE_IMAGE_AREA=1026 139 } de265_error; 140 141 LIBDE265_API const char* de265_get_error_text(de265_error err); 142 143 /* Returns true, if 'err' is DE265_OK or a warning. 144 */ 145 LIBDE265_API int de265_isOK(de265_error err); 146 147 LIBDE265_API void de265_disable_logging(); // DEPRECATED 148 LIBDE265_API void de265_set_verbosity(int level); 149 150 151 /* === image === */ 152 153 /* The image is currently always 3-channel YCbCr, with 4:2:0 chroma. 154 But you may want to check the chroma format anyway for future compatibility. 155 */ 156 157 struct de265_image; 158 159 enum de265_chroma { 160 de265_chroma_mono=0, 161 de265_chroma_420=1, 162 de265_chroma_422=2, 163 de265_chroma_444=3 164 }; 165 166 typedef int64_t de265_PTS; 167 168 169 LIBDE265_API int de265_get_image_width(const struct de265_image*,int channel); 170 LIBDE265_API int de265_get_image_height(const struct de265_image*,int channel); 171 LIBDE265_API enum de265_chroma de265_get_chroma_format(const struct de265_image*); 172 LIBDE265_API int de265_get_bits_per_pixel(const struct de265_image*,int channel); 173 /* The |out_stride| is returned as "bytes per line" if a non-NULL parameter is given. */ 174 LIBDE265_API const uint8_t* de265_get_image_plane(const struct de265_image*, int channel, int* out_stride); 175 LIBDE265_API void* de265_get_image_plane_user_data(const struct de265_image*, int channel); 176 LIBDE265_API de265_PTS de265_get_image_PTS(const struct de265_image*); 177 LIBDE265_API void* de265_get_image_user_data(const struct de265_image*); 178 LIBDE265_API void de265_set_image_user_data(struct de265_image*, void *user_data); 179 180 /* Get NAL-header information of this frame. You can pass in NULL pointers if you 181 do not need this piece of information. 182 */ 183 LIBDE265_API void de265_get_image_NAL_header(const struct de265_image*, 184 int* nal_unit_type, 185 const char** nal_unit_name, // textual description of 'nal_unit_type' 186 int* nuh_layer_id, 187 int* nuh_temporal_id); 188 189 190 /* === decoder === */ 191 192 typedef void de265_decoder_context; // private structure 193 194 195 196 /* Get a new decoder context. Must be freed with de265_free_decoder(). */ 197 LIBDE265_API de265_decoder_context* de265_new_decoder(void); 198 199 /* Initialize background decoding threads. If this function is not called, 200 all decoding is done in the main thread (no multi-threading). */ 201 LIBDE265_API de265_error de265_start_worker_threads(de265_decoder_context*, int number_of_threads); 202 203 /* Free decoder context. May only be called once on a context. */ 204 LIBDE265_API de265_error de265_free_decoder(de265_decoder_context*); 205 206 #ifndef LIBDE265_DISABLE_DEPRECATED 207 /* Push more data into the decoder, must be raw h265. 208 All complete images in the data will be decoded, hence, do not push 209 too much data at once to prevent image buffer overflows. 210 The end of a picture can only be detected when the succeeding start-code 211 is read from the data. 212 If you want to flush the data and force decoding of the data so far 213 (e.g. at the end of a file), call de265_decode_data() with 'length' zero. 214 215 NOTE: This method is deprecated and will be removed in a future version. 216 You should use "de265_push_data" or "de265_push_NAL" and "de265_decode" 217 instead. 218 */ 219 LIBDE265_API LIBDE265_DEPRECATED de265_error de265_decode_data(de265_decoder_context*, const void* data, int length); 220 #endif 221 222 /* Push more data into the decoder, must be a raw h265 bytestream with startcodes. 223 The PTS is assigned to all NALs whose start-code 0x000001 is contained in the data. 224 The bytestream must contain all stuffing-bytes. 225 This function only pushes data into the decoder, nothing will be decoded. 226 */ 227 LIBDE265_API de265_error de265_push_data(de265_decoder_context*, const void* data, int length, 228 de265_PTS pts, void* user_data); 229 230 /* Indicate that de265_push_data has just received data until the end of a NAL. 231 The remaining pending input data is put into a NAL package and forwarded to the decoder. 232 */ 233 LIBDE265_API void de265_push_end_of_NAL(de265_decoder_context*); 234 235 /* Indicate that de265_push_data has just received data until the end of a frame. 236 All data pending at the decoder input will be pushed into the decoder and 237 the decoded picture is pushed to the output queue. 238 */ 239 LIBDE265_API void de265_push_end_of_frame(de265_decoder_context*); 240 241 /* Push a complete NAL unit without startcode into the decoder. The data must still 242 contain all stuffing-bytes. 243 This function only pushes data into the decoder, nothing will be decoded. 244 */ 245 LIBDE265_API de265_error de265_push_NAL(de265_decoder_context*, const void* data, int length, 246 de265_PTS pts, void* user_data); 247 248 /* Indicate the end-of-stream. All data pending at the decoder input will be 249 pushed into the decoder and the decoded picture queue will be completely emptied. 250 */ 251 LIBDE265_API de265_error de265_flush_data(de265_decoder_context*); 252 253 /* Return number of bytes pending at the decoder input. 254 Can be used to avoid overflowing the decoder with too much data. 255 */ 256 LIBDE265_API int de265_get_number_of_input_bytes_pending(de265_decoder_context*); 257 258 /* Return number of NAL units pending at the decoder input. 259 Can be used to avoid overflowing the decoder with too much data. 260 */ 261 LIBDE265_API int de265_get_number_of_NAL_units_pending(de265_decoder_context*); 262 263 /* Do some decoding. Returns status whether it did perform some decoding or 264 why it could not do so. If 'more' is non-null, indicates whether de265_decode() 265 should be called again (possibly after resolving the indicated problem). 266 DE265_OK - decoding ok 267 DE265_ERROR_IMAGE_BUFFER_FULL - DPB full, extract some images before continuing 268 DE265_ERROR_WAITING_FOR_INPUT_DATA - insert more data before continuing 269 270 You have to consider these cases: 271 - decoding successful -> err = DE265_OK, more=true 272 - decoding stalled -> err != DE265_OK, more=true 273 - decoding finished -> err = DE265_OK, more=false 274 - unresolvable error -> err != DE265_OK, more=false 275 */ 276 LIBDE265_API de265_error de265_decode(de265_decoder_context*, int* more); 277 278 /* Clear decoder state. Call this when skipping in the stream. 279 */ 280 LIBDE265_API void de265_reset(de265_decoder_context*); 281 282 /* Return next decoded picture, if there is any. If no complete picture has been 283 decoded yet, NULL is returned. You should call de265_release_next_picture() to 284 advance to the next picture. */ 285 LIBDE265_API const struct de265_image* de265_peek_next_picture(de265_decoder_context*); // may return NULL 286 287 /* Get next decoded picture and remove this picture from the decoder output queue. 288 Returns NULL is there is no decoded picture ready. 289 You can use the picture only until you call any other de265_* function. */ 290 LIBDE265_API const struct de265_image* de265_get_next_picture(de265_decoder_context*); // may return NULL 291 292 /* Release the current decoded picture for reuse in the decoder. You should not 293 use the data anymore after calling this function. */ 294 LIBDE265_API void de265_release_next_picture(de265_decoder_context*); 295 296 297 LIBDE265_API de265_error de265_get_warning(de265_decoder_context*); 298 299 300 enum de265_image_format { 301 de265_image_format_mono8 = 1, 302 de265_image_format_YUV420P8 = 2, 303 de265_image_format_YUV422P8 = 3, 304 de265_image_format_YUV444P8 = 4 305 }; 306 307 struct de265_image_spec 308 { 309 enum de265_image_format format; 310 int width; 311 int height; 312 int alignment; 313 314 // conformance window 315 316 int crop_left; 317 int crop_right; 318 int crop_top; 319 int crop_bottom; 320 321 int visible_width; // convenience, width - crop_left - crop_right 322 int visible_height; // convenience, height - crop_top - crop_bottom 323 }; 324 325 struct de265_image_allocation 326 { 327 int (*get_buffer)(de265_decoder_context* ctx, // first parameter deprecated 328 struct de265_image_spec* spec, 329 struct de265_image* img, 330 void* userdata); 331 void (*release_buffer)(de265_decoder_context* ctx, // first parameter deprecated 332 struct de265_image* img, 333 void* userdata); 334 }; 335 336 /* The user data pointer will be given to the get_buffer() and release_buffer() functions 337 in de265_image_allocation. */ 338 LIBDE265_API void de265_set_image_allocation_functions(de265_decoder_context*, 339 struct de265_image_allocation*, 340 void* userdata); 341 LIBDE265_API const struct de265_image_allocation *de265_get_default_image_allocation_functions(void); 342 343 LIBDE265_API void de265_set_image_plane(struct de265_image* img, int cIdx, void* mem, int stride, void *userdata); 344 345 346 /* --- frame dropping API --- 347 348 To limit decoding to a maximum temporal layer (TID), use de265_set_limit_TID(). 349 The maximum layer ID in the stream can be queried with de265_get_highest_TID(). 350 Note that the maximum layer ID can change throughout the stream. 351 352 For a fine-grained selection of the frame-rate, use de265_set_framerate_ratio(). 353 A percentage of 100% will decode all frames in all temporal layers. A lower percentage 354 will drop approximately as many frames. Note that this only accurate if the frames 355 are distributed evenly among the layers. Otherwise, the mapping is non-linear. 356 357 The limit_TID has a higher precedence than framerate_ratio. Hence, setting a higher 358 framerate-ratio will decode at limit_TID without dropping. 359 360 With change_framerate(), the output frame-rate can be increased/decreased to some 361 discrete preferable values. Currently, these are non-dropped decoding at various 362 TID layers. 363 */ 364 365 LIBDE265_API int de265_get_highest_TID(de265_decoder_context*); // highest temporal substream to decode 366 LIBDE265_API int de265_get_current_TID(de265_decoder_context*); // currently decoded temporal substream 367 368 LIBDE265_API void de265_set_limit_TID(de265_decoder_context*,int max_tid); // highest temporal substream to decode 369 LIBDE265_API void de265_set_framerate_ratio(de265_decoder_context*,int percent); // percentage of frames to decode (approx) 370 LIBDE265_API int de265_change_framerate(de265_decoder_context*,int more_vs_less); // 1: more, -1: less, returns corresponding framerate_ratio 371 372 373 /* --- decoding parameters --- */ 374 375 enum de265_param { 376 DE265_DECODER_PARAM_BOOL_SEI_CHECK_HASH=0, // (bool) Perform SEI hash check on decoded pictures. 377 DE265_DECODER_PARAM_DUMP_SPS_HEADERS=1, // (int) Dump headers to specified file-descriptor. 378 DE265_DECODER_PARAM_DUMP_VPS_HEADERS=2, 379 DE265_DECODER_PARAM_DUMP_PPS_HEADERS=3, 380 DE265_DECODER_PARAM_DUMP_SLICE_HEADERS=4, 381 DE265_DECODER_PARAM_ACCELERATION_CODE=5, // (int) enum de265_acceleration, default: AUTO 382 DE265_DECODER_PARAM_SUPPRESS_FAULTY_PICTURES=6, // (bool) do not output frames with decoding errors, default: no (output all images) 383 384 DE265_DECODER_PARAM_DISABLE_DEBLOCKING=7, // (bool) disable deblocking 385 DE265_DECODER_PARAM_DISABLE_SAO=8 // (bool) disable SAO filter 386 //DE265_DECODER_PARAM_DISABLE_MC_RESIDUAL_IDCT=9, // (bool) disable decoding of IDCT residuals in MC blocks 387 //DE265_DECODER_PARAM_DISABLE_INTRA_RESIDUAL_IDCT=10 // (bool) disable decoding of IDCT residuals in MC blocks 388 }; 389 390 // sorted such that a large ID includes all optimizations from lower IDs 391 enum de265_acceleration { 392 de265_acceleration_SCALAR = 0, // only fallback implementation 393 de265_acceleration_MMX = 10, 394 de265_acceleration_SSE = 20, 395 de265_acceleration_SSE2 = 30, 396 de265_acceleration_SSE4 = 40, 397 de265_acceleration_AVX = 50, // not implemented yet 398 de265_acceleration_AVX2 = 60, // not implemented yet 399 de265_acceleration_ARM = 70, 400 de265_acceleration_NEON = 80, 401 de265_acceleration_AUTO = 10000 402 }; 403 404 405 /* Set decoding parameters. */ 406 LIBDE265_API void de265_set_parameter_bool(de265_decoder_context*, enum de265_param param, int value); 407 408 LIBDE265_API void de265_set_parameter_int(de265_decoder_context*, enum de265_param param, int value); 409 410 /* Get decoding parameters. */ 411 LIBDE265_API int de265_get_parameter_bool(de265_decoder_context*, enum de265_param param); 412 413 414 415 /* --- optional library initialization --- */ 416 417 /* Static library initialization. Must be paired with de265_free(). 418 Initialization is optional, since it will be done implicitly in de265_new_decoder(). 419 Return value is false if initialization failed. 420 Only call de265_free() when initialization was successful. 421 Multiple calls to 'init' are allowed, but must be matched with an equal number of 'free' calls. 422 */ 423 LIBDE265_API de265_error de265_init(void); 424 425 /* Free global library data. 426 An implicit free call is made in de265_free_decoder(). 427 Returns false if library was not initialized before, or if 'free' was called 428 more often than 'init'. 429 */ 430 LIBDE265_API de265_error de265_free(void); 431 432 433 #ifdef __cplusplus 434 } 435 #endif 436 437 #endif 438