1 /* 2 * libtc.h - include file for utilities library for transcode 3 * 4 * Copyright (C) Thomas Oestreich - August 2003 5 * Copyright (C) Transcode Team - 2005-2010 6 * 7 * This file is part of transcode, a video stream processing tool 8 * 9 * transcode is free software; you can redistribute it and/or modify 10 * it under the terms of the GNU General Public License as published by 11 * the Free Software Foundation; either version 2, or (at your option) 12 * any later version. 13 * 14 * transcode is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with GNU Make; see the file COPYING. If not, write to 21 * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 22 * 23 */ 24 25 #ifndef LIBTC_H 26 #define LIBTC_H 27 28 #ifdef HAVE_CONFIG_H 29 #include "config.h" 30 #endif 31 32 #include <stdarg.h> 33 #include <stdlib.h> 34 #include <stdint.h> 35 #include <sys/types.h> 36 #include <sys/param.h> 37 #include <string.h> 38 #include <pthread.h> 39 40 #ifndef OS_BSD 41 # ifdef HAVE_MALLOC_H 42 # include <malloc.h> 43 # endif 44 #endif 45 46 #include "tccodecs.h" 47 #include "tcformats.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 enum { 54 TC_FALSE, 55 TC_TRUE 56 }; 57 58 #define TC_NULL_MATCH -1 59 60 #define TC_BUF_MAX 1024 61 #define TC_BUF_LINE 256 62 #define TC_BUF_MIN 128 63 64 #define TC_MAX(a, b) (((a) > (b)) ?(a) :(b)) 65 #define TC_MIN(a, b) (((a) < (b)) ?(a) :(b)) 66 /* clamp x between a and b */ 67 #define TC_CLAMP(x, a, b) TC_MIN(TC_MAX((a), (x)), (b)) 68 69 /* colors macros */ 70 #define COL(x) "\033[" #x ";1m" 71 #define COL_RED COL(31) 72 #define COL_GREEN COL(32) 73 #define COL_YELLOW COL(33) 74 #define COL_BLUE COL(34) 75 #define COL_WHITE COL(37) 76 #define COL_GRAY "\033[0m" 77 78 #define TC_LOG_COLOR_ENV_VAR "TRANSCODE_LOG_NO_COLOR" 79 #define TC_LOG_COLOR_OPTION "--log_no_color" 80 81 /* 82 * Made to be compatible with 83 * TC_IMPORT_{OK,ERROR,UNKNOWN} 84 * TC_EXPORT_{OK,ERROR,UNKNOWN} 85 * see src/transcode.h 86 */ 87 typedef enum { 88 TC_ERROR = -1, 89 TC_OK = 0, 90 TC_INTERRUPT = 1, 91 TC_UNKNOWN, /* MUST always be the last one */ 92 } TCReturnCode; 93 94 95 typedef enum { 96 TC_LOG_ERR = 0, /* critical error condition */ 97 TC_LOG_WARN, /* non-critical error condition */ 98 TC_LOG_INFO, /* informative highlighted message */ 99 TC_LOG_MSG, /* regular message */ 100 101 TC_LOG_EXTRA, /* must always be the last */ 102 /* 103 * on this special log level is guaranteed that message will be logged 104 * verbatim: no tag, no colours, anything 105 */ 106 } TCLogLevel; 107 108 109 /* 110 * libtc_init: 111 * tune up some libtc settings. 112 * You DO NOT always NEED to use this function because libtc has it 113 * (most of time) sane defaults; just use this function to adapt 114 * libtc behaviour to some unusual conditions, like if stderr is a file 115 * and not a terminal. 116 * If you use this function, you MUST call it BEFORE any other libtc call, 117 * or you will experience undefined behaviours. 118 * It's safe to call libtc_setup multiple times BEFORE to call any other 119 * libtc function. 120 * 121 * Parameters: 122 * flags: flag to tune libtc behaviour (see above) 123 * Return Value: 124 * N/A 125 * Side effects: 126 * various. See description of flags above. 127 * Preconditions: 128 * this function, IF used, MUST be called BEFORE any other libtc function. 129 */ 130 void libtc_init(int *argc, char ***argv); 131 132 /* 133 * tc_log: 134 * main libtc logging function. Log arbitrary messages according 135 * to a printf-like format chosen by the caller. 136 * 137 * Parameters: 138 * level: priority of message to log; see TCLogLevel definition 139 * above. 140 * tag: header of message, to identify subsystem originating 141 * the message. It's suggested to use __FILE__ as 142 * fallback default tag. 143 * fmt: printf-like format string. You must provide enough 144 * further arguments to fullfill format string, doing 145 * otherwise will cause an undefined behaviour, most 146 * likely a crash. 147 * Return Value: 148 * 0 if message succesfully logged. 149 * -1 if message was truncated. 150 * (message too large and buffer allocation failed). 151 * Side effects: 152 * this function store final message in an intermediate string 153 * before to log it to destination. If such intermediate string 154 * is wider than a given amount (TC_BUF_MIN * 2 at moment 155 * of writing), tc_log needs to dinamically allocate some memory. 156 * This allocation can fail, and as result log message will be 157 * truncated to fit in avalaible static buffer. 158 */ 159 int tc_log(TCLogLevel level, const char *tag, const char *fmt, ...) 160 #ifdef HAVE_GCC_ATTRIBUTES 161 __attribute__((format(printf,3,4))) 162 #endif 163 ; 164 165 /* 166 * When to use tc_log*() stuff? 167 * 168 * tc_log() family should be used for non-output status messages, like 169 * the ones coming from the various modules and components of transcode. 170 * For actual output use printf() (or fprintf(), etc.) as appropriate. 171 * (yes, this means that transcode prints a lot of status and a very 172 * few output messages). 173 */ 174 175 /* compatibility macros */ 176 #define tc_error(format, args...) do { \ 177 tc_log(TC_LOG_ERR, PACKAGE, format , ## args); \ 178 exit(1); \ 179 } while(0) 180 #define tc_info(format, args...) \ 181 tc_log(TC_LOG_INFO, PACKAGE, format , ## args) 182 #define tc_warn(format, args...) \ 183 tc_log(TC_LOG_WARN, PACKAGE, format , ## args) 184 185 /* macro goodies */ 186 #define tc_log_error(tag, format, args...) \ 187 tc_log(TC_LOG_ERR, tag, format , ## args) 188 #define tc_log_info(tag, format, args...) \ 189 tc_log(TC_LOG_INFO, tag, format , ## args) 190 #define tc_log_warn(tag, format, args...) \ 191 tc_log(TC_LOG_WARN, tag, format , ## args) 192 #define tc_log_msg(tag, format, args...) \ 193 tc_log(TC_LOG_MSG, tag, format , ## args) 194 195 #define tc_log_perror(tag, string) do { \ 196 const char *__s = (string); /* watch out for side effects */ \ 197 tc_log_error(tag, "%s%s%s", __s ? __s : "", \ 198 (__s && *__s) ? ": " : "", strerror(errno)); \ 199 } while (0) 200 201 /*************************************************************************/ 202 203 /* 204 * tc_mangle_cmdline: 205 * parse a command line option array looking for a given option. 206 * Given option can be short or long but must be given literally. 207 * So, if you want to mangle "--foobar", give "--foobar" not 208 * "foobar". Same story for short options "-V": use "-V" not "V". 209 * If given option isn't found in string option array, do nothing 210 * and return succesfull (see below). If option is found but 211 * its argument isn't found, don't mangle string options array 212 * but return failure. 213 * If BOTH option and its value is found, store a pointer to 214 * option value into "optval" parameter and remove both option 215 * and value from string options array. 216 * Parameters: 217 * argc: pointer to number of values present into option string 218 * array. This parameter must be !NULL and it's updated 219 * by a succesfull call of this function. 220 * argv: pointer to array of option string items. This parameter 221 * must be !NULL and it's updated by a succesfull call of 222 * this function 223 * opt: option to look for. 224 * optval: if !NULL, this function will expect a value for given option; 225 * if such value is found, `optval' will point to it. 226 * Return value: 227 * 1: no option found 228 * 0: succesfull 229 * -1: bad parameter(s) (NULL) 230 * -2: bad usage: expected value for option, but not found, 231 * Postconditions: 232 * this function must operate trasparently by always leaving 233 * argc/argv in an usable and consistent state. 234 */ 235 int tc_mangle_cmdline(int *argc, char ***argv, 236 const char *opt, const char **optval); 237 238 /* 239 * tc_test_program: 240 * check if a given program is avalaible in current PATH. 241 * This function of course needs to read (and copy) the PATH 242 * environment variable 243 * 244 * Parameters: 245 * name: name of program to look for. 246 * Return Value: 247 * 0 if program was found in PATH. 248 * ENOENT if program was not found in PATH 249 * value of errno if program was found in PATH but it wasn't accessible 250 * for some reason. 251 */ 252 int tc_test_program(const char *name); 253 254 /* 255 * Safer string functions from OpenBSD, because these are not in all 256 * libc implementations. 257 */ 258 259 #ifndef HAVE_STRLCPY 260 size_t strlcpy(char *dst, const char *src, size_t size); 261 #endif 262 263 #ifndef HAVE_STRLCAT 264 size_t strlcat(char *dst, const char *src, size_t size); 265 #endif 266 267 /* 268 * tc_strsplit: 269 * split a given string into tokens using given separator character. 270 * Return NULL-terminated array of splitted tokens, and optionally 271 * return (via a out parameter) size of returned array. 272 * 273 * Parameters: 274 * str: string to split 275 * sep: separator CHARACTER: cut string when sep is found 276 * pieces_num: if not NULL, store here the size of returned array 277 * Return value: 278 * NULL-terminated array of splitted pieces. 279 * You must explicitely free this returned array by using tc_strfreev 280 * (see below) in order to avoid memleaks. 281 */ 282 char **tc_strsplit(const char *str, char sep, size_t *pieces_num); 283 284 /* 285 * tc_strfreev: 286 * return an array of strings as returned by tc_strsplit 287 * 288 * Parameters: 289 * pieces: return value of tc_strsplit to be freed. 290 * Return value: 291 * None. 292 */ 293 void tc_strfreev(char **pieces); 294 295 /* 296 * tc_strstrip: 297 * remove IN PLACE heading and trailing whitespaces from a given 298 * C-string. This means that given string will be mangled to 299 * remove such whitespace while moving pointer to first element 300 * and terminating '\0'. 301 * It's safe to supply a NULL string. 302 * Parameters: 303 * s: string to strip. 304 * Return Value: 305 * None 306 */ 307 void tc_strstrip(char *s); 308 309 /* 310 * tc_test_string: 311 * check the return value of snprintf, strlcpy, and strlcat. 312 * If an error is detected, prints reason. 313 * 314 * Parameters: 315 * file: name of source code file on which this function is called 316 * (this parameter is usually equal to __FILE__). 317 * line: line of source code file on which this function is called 318 * (this parameter is usually equal to __LINE__). 319 * limit: maximum size of char buffer previously used. 320 * ret: return code of one of above function. 321 * errnum: error code (this parameter is usually equal to errno) 322 * Return Value: 323 * < 0 is an internal error. 324 * >= limit means characters were truncated. 325 * 0 if not problems. 326 * 1 if error. 327 */ 328 int tc_test_string(const char *file, int line, int limit, 329 long ret, int errnum); 330 331 332 /* 333 * These versions of [v]snprintf() return -1 if the string was truncated, 334 * printing a message to stderr in case of truncation (or other error). 335 */ 336 #define tc_vsnprintf(buf,limit,format,args...) \ 337 _tc_vsnprintf(__FILE__, __LINE__, buf, limit, format , ## args) 338 #define tc_snprintf(buf,limit,format,args...) \ 339 _tc_snprintf(__FILE__, __LINE__, buf, limit, format , ## args) 340 341 int _tc_vsnprintf(const char *file, int line, char *buf, size_t limit, 342 const char *format, va_list args); 343 int _tc_snprintf(const char *file, int line, char *buf, size_t limit, 344 const char *format, ...); 345 346 /*************************************************************************/ 347 348 /* 349 * tc_malloc: just a simple wrapper on libc's malloc(), with emits 350 * an additional warning, specifying calling context, 351 * if allocation fails 352 * tc_zalloc: like tc_malloc, but zeroes all acquired memory before 353 * returning to the caller (this is quite common in 354 * transcode codebase) 355 * tc_realloc: the same thing for realloc() 356 * tc_free: the companion memory releasing wrapper. 357 */ 358 #define tc_malloc(size) \ 359 _tc_malloc(__FILE__, __LINE__, size) 360 #define tc_zalloc(size) \ 361 _tc_zalloc(__FILE__, __LINE__, size) 362 #define tc_realloc(p,size) \ 363 _tc_realloc(__FILE__, __LINE__, p, size) 364 #define tc_free(ptr) \ 365 free(ptr); 366 367 /* 368 * _tc_malloc: 369 * do the real work behind tc_malloc macro 370 * 371 * Parameters: 372 * file: name of the file on which call occurs 373 * line: line of above file on which call occurs 374 * (above two parameters are intended to be, and usually 375 * are, filled by tc_malloc macro) 376 * size: size of desired chunk of memory 377 * Return Value: 378 * a pointer of acquired memory, or NULL if acquisition fails 379 * Side effects: 380 * a message is printed on stderr if acquisition fails 381 * Preconditions: 382 * file param not null 383 */ 384 void *_tc_malloc(const char *file, int line, size_t size); 385 386 /* 387 * _tc_zalloc: 388 * do the real work behind tc_zalloc macro 389 * 390 * Parameters: 391 * file: name of the file on which call occurs 392 * line: line of above file on which call occurs 393 * (above two parameters are intended to be, and usually 394 * are, filled by tc_malloc macro) 395 * size: size of desired chunk of memory 396 * Return Value: 397 * a pointer of acquired memory, or NULL if acquisition fails 398 * Side effects: 399 * a message is printed on stderr if acquisition fails 400 * Preconditions: 401 * file param not null 402 * Postconditions: 403 * if call succeed, acquired memory contains all zeros 404 */ 405 void *_tc_zalloc(const char *file, int line, size_t size); 406 407 /* 408 * _tc_realloc: 409 * do the real work behind tc_realloc macro 410 * 411 * Parameters: 412 * file: name of the file on which call occurs 413 * line: line of above file on which call occurs 414 * (above two parameters are intended to be, and usually 415 * are, filled by tc_malloc macro) 416 * p: pointer to reallocate 417 * size: size of desired chunk of memory 418 * Return Value: 419 * a pointer of acquired memory, or NULL if acquisition fails 420 * Side effects: 421 * a message is printed on stderr if acquisition fails 422 * Preconditions: 423 * file param not null 424 */ 425 void *_tc_realloc(const char *file, int line, void *p, size_t size); 426 427 /* 428 * Allocate a buffer aligned to the machine's page size, if known. The 429 * buffer must be freed with buffree() (not free()). 430 */ 431 432 #define tc_bufalloc(size) \ 433 _tc_bufalloc(__FILE__, __LINE__, size) 434 435 /* 436 * _tc_malloc: 437 * do the real work behind _tc_bufalloc macro 438 * 439 * Parameters: 440 * file: name of the file on which call occurs 441 * line: line of above file on which call occurs 442 * (above two parameters are intended to be, and usually 443 * are, filled by tc_malloc macro) 444 * size: size of desired chunk of memory 445 * Return Value: 446 * a pointer of acquired, aligned, memory, or NULL if acquisition fails 447 * Side effects: 448 * a message is printed on stderr (20051017) 449 * Preconditions: 450 * file param not null 451 */ 452 453 void *_tc_bufalloc(const char *file, int line, size_t size); 454 455 /* 456 * tc_buffree: 457 * release a memory buffer acquired using tc_bufalloc 458 * 459 * Parameters: 460 * ptr: pointer obtained as return value of a succesfull 461 * tc_bufalloc() call 462 * Return Value: 463 * none 464 * Preconditions: 465 * ptr is acquired via tc_bufalloc(). Really BAD things will happen 466 * if a buffer acquired via tc_bufalloc() is released using anything 467 * but tc_buffree(), or vice versa. 468 */ 469 void tc_buffree(void *ptr); 470 471 /*************************************************************************/ 472 473 /* 474 * tc_strdup: a macro wrapper on top of _tc_strndup, like tc_malloc, above 475 * tc_strndup: like tc_strdup, but copies only N byte of given string 476 * 477 * This function does the same thing of libc's standard function 478 * strdup(3) and the GNU extension strndup(3), but using libtc's 479 * tc_malloc features. 480 */ 481 #define tc_strdup(s) \ 482 _tc_strndup(__FILE__, __LINE__, s, strlen(s)) 483 #define tc_strndup(s, n) \ 484 _tc_strndup(__FILE__, __LINE__, s, n) 485 486 /* 487 * _tc_strndup: 488 * do the real work behind tc_strdup/tc_strndup macro. This function 489 * adds automatically and implicitely a '\0' terminator at end of 490 * copied string. 491 * 492 * Parameters: 493 * file: name of the file on which call occurs 494 * line: line of above file on which call occurs (above two parameters 495 * are intended to be, and usually are, filled by tc_malloc macro) 496 * s: null-terminated string to copy 497 * n: copy at most 'n' characters of original string. 498 * Return Value: 499 * a pointer to a copy of given string. This pointer must be freed using 500 * tc_free() to avoid memory leaks 501 * Side effects: 502 * a message is printed on stderr (20051017) 503 * Preconditions: 504 * file param not null 505 * Postconditions: 506 * none 507 */ 508 char *_tc_strndup(const char *file, int line, const char *s, size_t n); 509 510 /* 511 * tc_file_check: 512 * verify the type of a given file (path) this function will be 513 * deprecated very soon, replaced by a powered tc_probe_path(). 514 * 515 * Parameters: 516 * file: the file (really: path) to verify. 517 * Return Value: 518 * -1 if an internal error occur 519 * 0 if given path is really a file 520 * 1 if given path is a directory 521 * Side effects: 522 * none 523 * Preconditions: 524 * none 525 * Postconditions: 526 * none 527 */ 528 int tc_file_check(const char *file); 529 530 /* 531 * tc_pread: 532 * read an entire buffer from a file descriptor, restarting 533 * automatically if interrupted. This function is basically a wrapper 534 * around posix read(2); read(2) can be interrupted by a signal, 535 * so doesn't guarantee that all requested bytes are effectively readed 536 * when read(2) returns; this function ensures so, except for critical 537 * errors. 538 * Parameters: 539 * fd: read data from this file descriptor 540 * buf: pointer to a buffer which will hold readed data 541 * len: how much data function must read from fd 542 * Return Value: 543 * size of effectively readed data 544 * Side effects: 545 * errno is readed internally 546 * Postconditions: 547 * read exactly the requested bytes, if no *critical* 548 * (tipically I/O related) error occurs. 549 */ 550 ssize_t tc_pread(int fd, uint8_t *buf, size_t len); 551 552 /* 553 * tc_pwrite: 554 * write an entire buffer from a file descriptor, restarting 555 * automatically if interrupted. This function is basically a wrapper 556 * around posix write(2); write(2) can be interrupted by a signal, 557 * so doesn't guarantee that all requested bytes are effectively writed 558 * when write(2) returns; this function ensures so, except for critical 559 * errors. 560 * Parameters: 561 * fd: write data on this file descriptor 562 * buf: pointer to a buffer which hold data to be written 563 * len: how much data function must write in fd 564 * Return Value: 565 * size of effectively written data 566 * Side effects: 567 * errno is readed internally 568 * Postconditions: 569 * write exactly the requested bytes, if no *critical* (tipically I/O 570 * related) error occurs. 571 */ 572 ssize_t tc_pwrite(int fd, const uint8_t *buf, size_t len); 573 574 /* 575 * tc_preadwrite: 576 * read all data avalaible from a file descriptor, putting it on the 577 * other one. 578 * Parameters: 579 * in: read data from this file descriptor 580 * out: write readed data on this file descriptor 581 * Return Value: 582 * -1 if a read error happens 583 * 0 if no error happens 584 * Postconditions: 585 * move the entire content of 'in' into 'out', if no *critical* 586 * (tipically I/O related) error occurs. 587 */ 588 int tc_preadwrite(int in, int out); 589 590 enum { 591 TC_PROBE_PATH_INVALID = 0, 592 TC_PROBE_PATH_ABSPATH, 593 TC_PROBE_PATH_RELDIR, 594 TC_PROBE_PATH_FILE, 595 TC_PROBE_PATH_BKTR, 596 TC_PROBE_PATH_SUNAU, 597 TC_PROBE_PATH_V4L_VIDEO, 598 TC_PROBE_PATH_V4L_AUDIO, 599 TC_PROBE_PATH_OSS, 600 /* add more elements here */ 601 }; 602 603 /* 604 * tc_probe_path: 605 * verify the type of a given path. 606 * 607 * Parameters: 608 * path: the path to probe. 609 * Return Value: 610 * the probed type of path. Can be TC_PROBE_PATH_INVALID if given path 611 * doesn't exists or an internal error occur. 612 * Side effects: 613 * if function fails, one or more debug message can be issued using 614 * tc_log*(). A name resolve request can be issued to system. 615 */ 616 int tc_probe_path(const char *name); 617 618 /* codec helpers ***********************************************************/ 619 620 /* 621 * tc_translate_codec_id: 622 * translate a CODEC_* value to corresponding TC_CODEC_* one. 623 * 624 * Parameters: 625 * codec: CODEC_* value to translate. 626 * Return value: 627 * corresponding TC_CODEC_* value, or 628 * TC_CODEC_ERROR if given CODEC_XXX hasn't corresponding TC_CODEC_XXX 629 * or if it;s just unknown. 630 */ 631 int tc_translate_codec_id(TCCodecID codec); 632 633 /* 634 * tc_codec_to_comment: 635 * return a short constant descriptive string given the codec identifier. 636 * 637 * Parameters: 638 * codec: TC_CODEC_* value to represent. 639 * Return value: 640 * a constant string describing the given codec (there is no need to 641 * free() it). 642 * Postconditions: 643 * Always return something sensible, even if unknown codec id was given. 644 */ 645 const char* tc_codec_to_comment(TCCodecID codec); 646 647 /* 648 * tc_codec_to_string: 649 * return the codec name as a lowercase constant string, 650 * given the codec identifier. 651 * 652 * Parameters: 653 * codec: the TC_CODEC_* value to represent. 654 * Return value: 655 * a constant string representing the given codec (there is no need to 656 * free() it). 657 * NULL if codec is (yet) unknown. 658 */ 659 const char* tc_codec_to_string(TCCodecID codec); 660 661 /* 662 * tc_codec_from_string: 663 * extract codec identifier from its string representation 664 * 665 * Parameters: 666 * codec: string representation of codec, lowercase (name). 667 * Return value: 668 * the correspinding TC_CODEC_* of given string representation, 669 * or TC_CODEC_ERROR if string is unknown or wrong. 670 */ 671 TCCodecID tc_codec_from_string(const char *codec); 672 673 /* 674 * tc_codec_fourcc: 675 * extract the FOURCC code for a given codec, if exists. 676 * 677 * Parameters: 678 * codec: TC_CODEC_* value to get the FOURCC for. 679 * Return value: 680 * a constant string representing the FOURCC for a given codec (there 681 * is no need to free() it NULL of codec's FOURCC is (yet) unknown or 682 * given codec has _not_ FOURCC (es: audio codec identifiers). 683 */ 684 const char* tc_codec_fourcc(TCCodecID codec); 685 686 /* 687 * tc_codec_description: 688 * describe a codec, given its ID. 689 * 690 * Parameters: 691 * codec: TC_CODEC_* value to get the description for. 692 * buf: buffer provided to caller. Description will be stored here. 693 * bufsize: size of the given buffer. 694 * Return value: 695 * -1 if requested codec isn't known. 696 * 0 truncation error (given buffer too small). 697 * >0 no errors. 698 */ 699 int tc_codec_description(TCCodecID codec, char *buf, size_t bufsize); 700 701 /* 702 * tc_codec_is_multipass: 703 * tell if a given codec is multipass capable or not. 704 * 705 * Parameters: 706 * codec: TC_CODEC_* value to inquiry. 707 * Return value: 708 * TC_TRUE: given codec is multipass capable. 709 * TC_FALSE: given codec is NOT multipass capable OR is not known. 710 */ 711 int tc_codec_is_multipass(TCCodecID codec); 712 713 /*************************************************************************/ 714 715 /* 716 * tc_compute_fast_resize_values: 717 * compute internal values needed for video frame fast resize (-B/-X) 718 * given base resolution (ex_v_{width,height}) and target one 719 * (zoom_{width,height}). 720 * WARNING: at moment of writing there are some back compatibility 721 * constraints, nevethless this function interface (notabley I/O 722 * parameters passing) needs a SERIOUS rethink. 723 * 724 * Parameters: 725 * _vob: pointer to a structure on which read/store values for 726 * computation. 727 * Should ALWAYS really be a pointer to a vob_t structure, 728 * but vob_t pointer isn't used (yet) in order to avoid 729 * libtc/transcode.h interdependency. 730 * I'm not yet convinced that those informations should go 731 * in TCExportInfo because only transcode core needs them. 732 * Perhaps the cleanest solution is to introduce yet 733 * another structure :\. 734 * If anyone has a better solution just let me know -- FR. 735 * vob_t fields used: 736 * ex_v_{width, height}: base resolution (In) 737 * zoom_{width, height}: target resolution (In) 738 * resize{1,2}_mult, vert_resize{1,2}, hori_resize{1,2}: 739 * computed parameters (Out) 740 * strict: if !0, allow only enlarging and shrinking of frame in 741 * both dimensions, and fail otherwise. 742 * Return value: 743 * 0 succesfull 744 * -1 error, computation failed 745 * (i.e. width or height not multiple of 8) 746 * Side effects: 747 * if succesfull, zoom_{width,height} will be set to 0. 748 */ 749 int tc_compute_fast_resize_values(void *_vob, int strict); 750 751 /*************************************************************************/ 752 753 /** 754 * tc_find_best_aspect_ratio: 755 * set sar_num and sar_den to the sample aspect ratio (also called 756 * pixel aspect ratio) described by vob->ex_par, 757 * vob->ex_par_width, vob->ex_par_height and vob->ex_asr. 758 * 759 * This function might return quite high values in sar_num and 760 * sar_den. Depending on what codec these parameters are given to, 761 * eventually a common factor should be reduced first. In case of x264 762 * this is not needed, because it's done in x264's code. 763 * 764 * Parameters: 765 * vob: constant pointer to vob structure. 766 * sar_num: integer to store SAR-numerator in. 767 * sar_den: integer to store SAR-denominator in. 768 * tag: tag to use in log messages (if any). 769 * 770 * Returns: 771 * 0 on success, nonzero otherwise (this means bad parameters). 772 */ 773 int tc_find_best_aspect_ratio(const void *_vob, 774 int *sar_num, int *sar_den, 775 const char *tag); 776 777 /*************************************************************************/ 778 779 /* 780 * XXX: add some general notes about quantization matrices stored 781 * into files (format etc. etc.) 782 * 783 * tc_*_matrix GOTCHA: 784 * Why _two_ allowed elements wideness? Why this mess? 785 * The problem is that XviD and libavcodec wants elements for 786 * quantization matrix in two different wideness. Obviously 787 * we DON'T want to patch such sources, so we must handle in 788 * some way this difference. 789 * Of course we are looking for cleaner solutions. 790 * -- fromani 20060305 791 */ 792 793 /* 794 * Total size (=number of elements) of quantization matrix 795 * for following two support functions 796 */ 797 #define TC_MATRIX_SIZE (64) 798 799 /* 800 * tc_read_matrix: 801 * read a quantization matrix from given file. 802 * Can read 8-bit wide or 16-bit wide matrix elements. 803 * Store readed matrix in a caller-provided buffer. 804 * 805 * Caller can select the elements wideness just 806 * providing a not-NULL buffer for corresponding buffer. 807 * For example, if caller wants to read a quantization matrix 808 * from 'matrix.txt', and want 16-bit wide elements, it 809 * will call 810 * 811 * uint16_t matrix[TC_MATRIX_SIZE]; 812 * tc_read_matrix('matrix.txt', NULL, matrix); 813 * 814 * Parameters: 815 * filename: read quantization matrix from this file. 816 * m8: buffer for 8-bit wide elements quantization matrix 817 * m16: buffer for 16-bit wide elements quantization matrix 818 * 819 * NOTE: if m8 AND m16 BOTH refers to valid buffers, 8-bit 820 * wideness is preferred. 821 * Return value: 822 * -1 filename not found, or neither buffers is valid. 823 * +1 read error: matrix incomplete or badly formatted. 824 * 0 no errors. 825 * Side effects: 826 * a file on disk is open, readed, closed. 827 * Preconditions: 828 * buffer provided by caller MUST be large enough to hold 829 * TC_MATRIX_SIZE elements of requested wideness. 830 * At least one given buffer is valid. 831 */ 832 int tc_read_matrix(const char *filename, uint8_t *m8, uint16_t *m16); 833 834 /* 835 * tc_print_matrix: 836 * print (using tc_log*) a quantization matrix. 837 * Can print 8-bit wide or 16-bit wide matrix elements. 838 * 839 * Caller must provide a valid pointer correspoinding to 840 * wideness of elements of matrix to be printed. 841 * Example: quantization matrix has 8-bit wide elements: 842 * 843 * uint8_t matrix[TC_MATRIX_SIZE]; 844 * // already filled with something useful 845 * tc_print_matrix(matrix, NULL); 846 * 847 * Parameters: 848 * m8: pointer to 8-bit wide elements quantization matrix. 849 * m16: pointer to 16-bit wide elements quantization matrix. 850 * 851 * NOTE: if m8 AND m16 BOTH refers to valid buffers, 8-bit 852 * wideness is preferred. 853 * Preconditions: 854 * At least one given pointer is valid. 855 */ 856 void tc_print_matrix(uint8_t *m8, uint16_t *m16); 857 858 #ifdef __cplusplus 859 } 860 #endif 861 862 #endif /* _LIBTC_H */ 863