diff options
Diffstat (limited to 'debian/transcode/transcode-1.1.7/libtc/libtc.h')
| -rw-r--r-- | debian/transcode/transcode-1.1.7/libtc/libtc.h | 862 |
1 files changed, 862 insertions, 0 deletions
diff --git a/debian/transcode/transcode-1.1.7/libtc/libtc.h b/debian/transcode/transcode-1.1.7/libtc/libtc.h new file mode 100644 index 00000000..8e2c6938 --- /dev/null +++ b/debian/transcode/transcode-1.1.7/libtc/libtc.h @@ -0,0 +1,862 @@ +/* + * libtc.h - include file for utilities library for transcode + * + * Copyright (C) Thomas Oestreich - August 2003 + * Copyright (C) Transcode Team - 2005-2010 + * + * This file is part of transcode, a video stream processing tool + * + * transcode is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2, or (at your option) + * any later version. + * + * transcode 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 General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with GNU Make; see the file COPYING. If not, write to + * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + * + */ + +#ifndef LIBTC_H +#define LIBTC_H + +#ifdef HAVE_CONFIG_H +#include "config.h" +#endif + +#include <stdarg.h> +#include <stdlib.h> +#include <stdint.h> +#include <sys/types.h> +#include <sys/param.h> +#include <string.h> +#include <pthread.h> + +#ifndef OS_BSD +# ifdef HAVE_MALLOC_H +# include <malloc.h> +# endif +#endif + +#include "tccodecs.h" +#include "tcformats.h" + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + TC_FALSE, + TC_TRUE +}; + +#define TC_NULL_MATCH -1 + +#define TC_BUF_MAX 1024 +#define TC_BUF_LINE 256 +#define TC_BUF_MIN 128 + +#define TC_MAX(a, b) (((a) > (b)) ?(a) :(b)) +#define TC_MIN(a, b) (((a) < (b)) ?(a) :(b)) +/* clamp x between a and b */ +#define TC_CLAMP(x, a, b) TC_MIN(TC_MAX((a), (x)), (b)) + +/* colors macros */ +#define COL(x) "\033[" #x ";1m" +#define COL_RED COL(31) +#define COL_GREEN COL(32) +#define COL_YELLOW COL(33) +#define COL_BLUE COL(34) +#define COL_WHITE COL(37) +#define COL_GRAY "\033[0m" + +#define TC_LOG_COLOR_ENV_VAR "TRANSCODE_LOG_NO_COLOR" +#define TC_LOG_COLOR_OPTION "--log_no_color" + +/* + * Made to be compatible with + * TC_IMPORT_{OK,ERROR,UNKNOWN} + * TC_EXPORT_{OK,ERROR,UNKNOWN} + * see src/transcode.h + */ +typedef enum { + TC_ERROR = -1, + TC_OK = 0, + TC_INTERRUPT = 1, + TC_UNKNOWN, /* MUST always be the last one */ +} TCReturnCode; + + +typedef enum { + TC_LOG_ERR = 0, /* critical error condition */ + TC_LOG_WARN, /* non-critical error condition */ + TC_LOG_INFO, /* informative highlighted message */ + TC_LOG_MSG, /* regular message */ + + TC_LOG_EXTRA, /* must always be the last */ + /* + * on this special log level is guaranteed that message will be logged + * verbatim: no tag, no colours, anything + */ +} TCLogLevel; + + +/* + * libtc_init: + * tune up some libtc settings. + * You DO NOT always NEED to use this function because libtc has it + * (most of time) sane defaults; just use this function to adapt + * libtc behaviour to some unusual conditions, like if stderr is a file + * and not a terminal. + * If you use this function, you MUST call it BEFORE any other libtc call, + * or you will experience undefined behaviours. + * It's safe to call libtc_setup multiple times BEFORE to call any other + * libtc function. + * + * Parameters: + * flags: flag to tune libtc behaviour (see above) + * Return Value: + * N/A + * Side effects: + * various. See description of flags above. + * Preconditions: + * this function, IF used, MUST be called BEFORE any other libtc function. + */ +void libtc_init(int *argc, char ***argv); + +/* + * tc_log: + * main libtc logging function. Log arbitrary messages according + * to a printf-like format chosen by the caller. + * + * Parameters: + * level: priority of message to log; see TCLogLevel definition + * above. + * tag: header of message, to identify subsystem originating + * the message. It's suggested to use __FILE__ as + * fallback default tag. + * fmt: printf-like format string. You must provide enough + * further arguments to fullfill format string, doing + * otherwise will cause an undefined behaviour, most + * likely a crash. + * Return Value: + * 0 if message succesfully logged. + * -1 if message was truncated. + * (message too large and buffer allocation failed). + * Side effects: + * this function store final message in an intermediate string + * before to log it to destination. If such intermediate string + * is wider than a given amount (TC_BUF_MIN * 2 at moment + * of writing), tc_log needs to dinamically allocate some memory. + * This allocation can fail, and as result log message will be + * truncated to fit in avalaible static buffer. + */ +int tc_log(TCLogLevel level, const char *tag, const char *fmt, ...) +#ifdef HAVE_GCC_ATTRIBUTES +__attribute__((format(printf,3,4))) +#endif +; + +/* + * When to use tc_log*() stuff? + * + * tc_log() family should be used for non-output status messages, like + * the ones coming from the various modules and components of transcode. + * For actual output use printf() (or fprintf(), etc.) as appropriate. + * (yes, this means that transcode prints a lot of status and a very + * few output messages). + */ + +/* compatibility macros */ +#define tc_error(format, args...) do { \ + tc_log(TC_LOG_ERR, PACKAGE, format , ## args); \ + exit(1); \ +} while(0) +#define tc_info(format, args...) \ + tc_log(TC_LOG_INFO, PACKAGE, format , ## args) +#define tc_warn(format, args...) \ + tc_log(TC_LOG_WARN, PACKAGE, format , ## args) + +/* macro goodies */ +#define tc_log_error(tag, format, args...) \ + tc_log(TC_LOG_ERR, tag, format , ## args) +#define tc_log_info(tag, format, args...) \ + tc_log(TC_LOG_INFO, tag, format , ## args) +#define tc_log_warn(tag, format, args...) \ + tc_log(TC_LOG_WARN, tag, format , ## args) +#define tc_log_msg(tag, format, args...) \ + tc_log(TC_LOG_MSG, tag, format , ## args) + +#define tc_log_perror(tag, string) do { \ + const char *__s = (string); /* watch out for side effects */ \ + tc_log_error(tag, "%s%s%s", __s ? __s : "", \ + (__s && *__s) ? ": " : "", strerror(errno)); \ +} while (0) + +/*************************************************************************/ + +/* + * tc_mangle_cmdline: + * parse a command line option array looking for a given option. + * Given option can be short or long but must be given literally. + * So, if you want to mangle "--foobar", give "--foobar" not + * "foobar". Same story for short options "-V": use "-V" not "V". + * If given option isn't found in string option array, do nothing + * and return succesfull (see below). If option is found but + * its argument isn't found, don't mangle string options array + * but return failure. + * If BOTH option and its value is found, store a pointer to + * option value into "optval" parameter and remove both option + * and value from string options array. + * Parameters: + * argc: pointer to number of values present into option string + * array. This parameter must be !NULL and it's updated + * by a succesfull call of this function. + * argv: pointer to array of option string items. This parameter + * must be !NULL and it's updated by a succesfull call of + * this function + * opt: option to look for. + * optval: if !NULL, this function will expect a value for given option; + * if such value is found, `optval' will point to it. + * Return value: + * 1: no option found + * 0: succesfull + * -1: bad parameter(s) (NULL) + * -2: bad usage: expected value for option, but not found, + * Postconditions: + * this function must operate trasparently by always leaving + * argc/argv in an usable and consistent state. + */ +int tc_mangle_cmdline(int *argc, char ***argv, + const char *opt, const char **optval); + +/* + * tc_test_program: + * check if a given program is avalaible in current PATH. + * This function of course needs to read (and copy) the PATH + * environment variable + * + * Parameters: + * name: name of program to look for. + * Return Value: + * 0 if program was found in PATH. + * ENOENT if program was not found in PATH + * value of errno if program was found in PATH but it wasn't accessible + * for some reason. + */ +int tc_test_program(const char *name); + +/* + * Safer string functions from OpenBSD, because these are not in all + * libc implementations. + */ + +#ifndef HAVE_STRLCPY +size_t strlcpy(char *dst, const char *src, size_t size); +#endif + +#ifndef HAVE_STRLCAT +size_t strlcat(char *dst, const char *src, size_t size); +#endif + +/* + * tc_strsplit: + * split a given string into tokens using given separator character. + * Return NULL-terminated array of splitted tokens, and optionally + * return (via a out parameter) size of returned array. + * + * Parameters: + * str: string to split + * sep: separator CHARACTER: cut string when sep is found + * pieces_num: if not NULL, store here the size of returned array + * Return value: + * NULL-terminated array of splitted pieces. + * You must explicitely free this returned array by using tc_strfreev + * (see below) in order to avoid memleaks. + */ +char **tc_strsplit(const char *str, char sep, size_t *pieces_num); + +/* + * tc_strfreev: + * return an array of strings as returned by tc_strsplit + * + * Parameters: + * pieces: return value of tc_strsplit to be freed. + * Return value: + * None. + */ +void tc_strfreev(char **pieces); + +/* + * tc_strstrip: + * remove IN PLACE heading and trailing whitespaces from a given + * C-string. This means that given string will be mangled to + * remove such whitespace while moving pointer to first element + * and terminating '\0'. + * It's safe to supply a NULL string. + * Parameters: + * s: string to strip. + * Return Value: + * None + */ +void tc_strstrip(char *s); + +/* + * tc_test_string: + * check the return value of snprintf, strlcpy, and strlcat. + * If an error is detected, prints reason. + * + * Parameters: + * file: name of source code file on which this function is called + * (this parameter is usually equal to __FILE__). + * line: line of source code file on which this function is called + * (this parameter is usually equal to __LINE__). + * limit: maximum size of char buffer previously used. + * ret: return code of one of above function. + * errnum: error code (this parameter is usually equal to errno) + * Return Value: + * < 0 is an internal error. + * >= limit means characters were truncated. + * 0 if not problems. + * 1 if error. + */ +int tc_test_string(const char *file, int line, int limit, + long ret, int errnum); + + +/* + * These versions of [v]snprintf() return -1 if the string was truncated, + * printing a message to stderr in case of truncation (or other error). + */ +#define tc_vsnprintf(buf,limit,format,args...) \ + _tc_vsnprintf(__FILE__, __LINE__, buf, limit, format , ## args) +#define tc_snprintf(buf,limit,format,args...) \ + _tc_snprintf(__FILE__, __LINE__, buf, limit, format , ## args) + +int _tc_vsnprintf(const char *file, int line, char *buf, size_t limit, + const char *format, va_list args); +int _tc_snprintf(const char *file, int line, char *buf, size_t limit, + const char *format, ...); + +/*************************************************************************/ + +/* + * tc_malloc: just a simple wrapper on libc's malloc(), with emits + * an additional warning, specifying calling context, + * if allocation fails + * tc_zalloc: like tc_malloc, but zeroes all acquired memory before + * returning to the caller (this is quite common in + * transcode codebase) + * tc_realloc: the same thing for realloc() + * tc_free: the companion memory releasing wrapper. + */ +#define tc_malloc(size) \ + _tc_malloc(__FILE__, __LINE__, size) +#define tc_zalloc(size) \ + _tc_zalloc(__FILE__, __LINE__, size) +#define tc_realloc(p,size) \ + _tc_realloc(__FILE__, __LINE__, p, size) +#define tc_free(ptr) \ + free(ptr); + +/* + * _tc_malloc: + * do the real work behind tc_malloc macro + * + * Parameters: + * file: name of the file on which call occurs + * line: line of above file on which call occurs + * (above two parameters are intended to be, and usually + * are, filled by tc_malloc macro) + * size: size of desired chunk of memory + * Return Value: + * a pointer of acquired memory, or NULL if acquisition fails + * Side effects: + * a message is printed on stderr if acquisition fails + * Preconditions: + * file param not null + */ +void *_tc_malloc(const char *file, int line, size_t size); + +/* + * _tc_zalloc: + * do the real work behind tc_zalloc macro + * + * Parameters: + * file: name of the file on which call occurs + * line: line of above file on which call occurs + * (above two parameters are intended to be, and usually + * are, filled by tc_malloc macro) + * size: size of desired chunk of memory + * Return Value: + * a pointer of acquired memory, or NULL if acquisition fails + * Side effects: + * a message is printed on stderr if acquisition fails + * Preconditions: + * file param not null + * Postconditions: + * if call succeed, acquired memory contains all zeros + */ +void *_tc_zalloc(const char *file, int line, size_t size); + +/* + * _tc_realloc: + * do the real work behind tc_realloc macro + * + * Parameters: + * file: name of the file on which call occurs + * line: line of above file on which call occurs + * (above two parameters are intended to be, and usually + * are, filled by tc_malloc macro) + * p: pointer to reallocate + * size: size of desired chunk of memory + * Return Value: + * a pointer of acquired memory, or NULL if acquisition fails + * Side effects: + * a message is printed on stderr if acquisition fails + * Preconditions: + * file param not null + */ +void *_tc_realloc(const char *file, int line, void *p, size_t size); + +/* + * Allocate a buffer aligned to the machine's page size, if known. The + * buffer must be freed with buffree() (not free()). + */ + +#define tc_bufalloc(size) \ + _tc_bufalloc(__FILE__, __LINE__, size) + +/* + * _tc_malloc: + * do the real work behind _tc_bufalloc macro + * + * Parameters: + * file: name of the file on which call occurs + * line: line of above file on which call occurs + * (above two parameters are intended to be, and usually + * are, filled by tc_malloc macro) + * size: size of desired chunk of memory + * Return Value: + * a pointer of acquired, aligned, memory, or NULL if acquisition fails + * Side effects: + * a message is printed on stderr (20051017) + * Preconditions: + * file param not null + */ + +void *_tc_bufalloc(const char *file, int line, size_t size); + +/* + * tc_buffree: + * release a memory buffer acquired using tc_bufalloc + * + * Parameters: + * ptr: pointer obtained as return value of a succesfull + * tc_bufalloc() call + * Return Value: + * none + * Preconditions: + * ptr is acquired via tc_bufalloc(). Really BAD things will happen + * if a buffer acquired via tc_bufalloc() is released using anything + * but tc_buffree(), or vice versa. + */ +void tc_buffree(void *ptr); + +/*************************************************************************/ + +/* + * tc_strdup: a macro wrapper on top of _tc_strndup, like tc_malloc, above + * tc_strndup: like tc_strdup, but copies only N byte of given string + * + * This function does the same thing of libc's standard function + * strdup(3) and the GNU extension strndup(3), but using libtc's + * tc_malloc features. + */ +#define tc_strdup(s) \ + _tc_strndup(__FILE__, __LINE__, s, strlen(s)) +#define tc_strndup(s, n) \ + _tc_strndup(__FILE__, __LINE__, s, n) + +/* + * _tc_strndup: + * do the real work behind tc_strdup/tc_strndup macro. This function + * adds automatically and implicitely a '\0' terminator at end of + * copied string. + * + * Parameters: + * file: name of the file on which call occurs + * line: line of above file on which call occurs (above two parameters + * are intended to be, and usually are, filled by tc_malloc macro) + * s: null-terminated string to copy + * n: copy at most 'n' characters of original string. + * Return Value: + * a pointer to a copy of given string. This pointer must be freed using + * tc_free() to avoid memory leaks + * Side effects: + * a message is printed on stderr (20051017) + * Preconditions: + * file param not null + * Postconditions: + * none + */ +char *_tc_strndup(const char *file, int line, const char *s, size_t n); + +/* + * tc_file_check: + * verify the type of a given file (path) this function will be + * deprecated very soon, replaced by a powered tc_probe_path(). + * + * Parameters: + * file: the file (really: path) to verify. + * Return Value: + * -1 if an internal error occur + * 0 if given path is really a file + * 1 if given path is a directory + * Side effects: + * none + * Preconditions: + * none + * Postconditions: + * none + */ +int tc_file_check(const char *file); + +/* + * tc_pread: + * read an entire buffer from a file descriptor, restarting + * automatically if interrupted. This function is basically a wrapper + * around posix read(2); read(2) can be interrupted by a signal, + * so doesn't guarantee that all requested bytes are effectively readed + * when read(2) returns; this function ensures so, except for critical + * errors. + * Parameters: + * fd: read data from this file descriptor + * buf: pointer to a buffer which will hold readed data + * len: how much data function must read from fd + * Return Value: + * size of effectively readed data + * Side effects: + * errno is readed internally + * Postconditions: + * read exactly the requested bytes, if no *critical* + * (tipically I/O related) error occurs. + */ +ssize_t tc_pread(int fd, uint8_t *buf, size_t len); + +/* + * tc_pwrite: + * write an entire buffer from a file descriptor, restarting + * automatically if interrupted. This function is basically a wrapper + * around posix write(2); write(2) can be interrupted by a signal, + * so doesn't guarantee that all requested bytes are effectively writed + * when write(2) returns; this function ensures so, except for critical + * errors. + * Parameters: + * fd: write data on this file descriptor + * buf: pointer to a buffer which hold data to be written + * len: how much data function must write in fd + * Return Value: + * size of effectively written data + * Side effects: + * errno is readed internally + * Postconditions: + * write exactly the requested bytes, if no *critical* (tipically I/O + * related) error occurs. + */ +ssize_t tc_pwrite(int fd, const uint8_t *buf, size_t len); + +/* + * tc_preadwrite: + * read all data avalaible from a file descriptor, putting it on the + * other one. + * Parameters: + * in: read data from this file descriptor + * out: write readed data on this file descriptor + * Return Value: + * -1 if a read error happens + * 0 if no error happens + * Postconditions: + * move the entire content of 'in' into 'out', if no *critical* + * (tipically I/O related) error occurs. + */ +int tc_preadwrite(int in, int out); + +enum { + TC_PROBE_PATH_INVALID = 0, + TC_PROBE_PATH_ABSPATH, + TC_PROBE_PATH_RELDIR, + TC_PROBE_PATH_FILE, + TC_PROBE_PATH_BKTR, + TC_PROBE_PATH_SUNAU, + TC_PROBE_PATH_V4L_VIDEO, + TC_PROBE_PATH_V4L_AUDIO, + TC_PROBE_PATH_OSS, + /* add more elements here */ +}; + +/* + * tc_probe_path: + * verify the type of a given path. + * + * Parameters: + * path: the path to probe. + * Return Value: + * the probed type of path. Can be TC_PROBE_PATH_INVALID if given path + * doesn't exists or an internal error occur. + * Side effects: + * if function fails, one or more debug message can be issued using + * tc_log*(). A name resolve request can be issued to system. + */ +int tc_probe_path(const char *name); + +/* codec helpers ***********************************************************/ + +/* + * tc_translate_codec_id: + * translate a CODEC_* value to corresponding TC_CODEC_* one. + * + * Parameters: + * codec: CODEC_* value to translate. + * Return value: + * corresponding TC_CODEC_* value, or + * TC_CODEC_ERROR if given CODEC_XXX hasn't corresponding TC_CODEC_XXX + * or if it;s just unknown. + */ +int tc_translate_codec_id(TCCodecID codec); + +/* + * tc_codec_to_comment: + * return a short constant descriptive string given the codec identifier. + * + * Parameters: + * codec: TC_CODEC_* value to represent. + * Return value: + * a constant string describing the given codec (there is no need to + * free() it). + * Postconditions: + * Always return something sensible, even if unknown codec id was given. + */ +const char* tc_codec_to_comment(TCCodecID codec); + +/* + * tc_codec_to_string: + * return the codec name as a lowercase constant string, + * given the codec identifier. + * + * Parameters: + * codec: the TC_CODEC_* value to represent. + * Return value: + * a constant string representing the given codec (there is no need to + * free() it). + * NULL if codec is (yet) unknown. + */ +const char* tc_codec_to_string(TCCodecID codec); + +/* + * tc_codec_from_string: + * extract codec identifier from its string representation + * + * Parameters: + * codec: string representation of codec, lowercase (name). + * Return value: + * the correspinding TC_CODEC_* of given string representation, + * or TC_CODEC_ERROR if string is unknown or wrong. + */ +TCCodecID tc_codec_from_string(const char *codec); + +/* + * tc_codec_fourcc: + * extract the FOURCC code for a given codec, if exists. + * + * Parameters: + * codec: TC_CODEC_* value to get the FOURCC for. + * Return value: + * a constant string representing the FOURCC for a given codec (there + * is no need to free() it NULL of codec's FOURCC is (yet) unknown or + * given codec has _not_ FOURCC (es: audio codec identifiers). + */ +const char* tc_codec_fourcc(TCCodecID codec); + +/* + * tc_codec_description: + * describe a codec, given its ID. + * + * Parameters: + * codec: TC_CODEC_* value to get the description for. + * buf: buffer provided to caller. Description will be stored here. + * bufsize: size of the given buffer. + * Return value: + * -1 if requested codec isn't known. + * 0 truncation error (given buffer too small). + * >0 no errors. + */ +int tc_codec_description(TCCodecID codec, char *buf, size_t bufsize); + +/* + * tc_codec_is_multipass: + * tell if a given codec is multipass capable or not. + * + * Parameters: + * codec: TC_CODEC_* value to inquiry. + * Return value: + * TC_TRUE: given codec is multipass capable. + * TC_FALSE: given codec is NOT multipass capable OR is not known. + */ +int tc_codec_is_multipass(TCCodecID codec); + +/*************************************************************************/ + +/* + * tc_compute_fast_resize_values: + * compute internal values needed for video frame fast resize (-B/-X) + * given base resolution (ex_v_{width,height}) and target one + * (zoom_{width,height}). + * WARNING: at moment of writing there are some back compatibility + * constraints, nevethless this function interface (notabley I/O + * parameters passing) needs a SERIOUS rethink. + * + * Parameters: + * _vob: pointer to a structure on which read/store values for + * computation. + * Should ALWAYS really be a pointer to a vob_t structure, + * but vob_t pointer isn't used (yet) in order to avoid + * libtc/transcode.h interdependency. + * I'm not yet convinced that those informations should go + * in TCExportInfo because only transcode core needs them. + * Perhaps the cleanest solution is to introduce yet + * another structure :\. + * If anyone has a better solution just let me know -- FR. + * vob_t fields used: + * ex_v_{width, height}: base resolution (In) + * zoom_{width, height}: target resolution (In) + * resize{1,2}_mult, vert_resize{1,2}, hori_resize{1,2}: + * computed parameters (Out) + * strict: if !0, allow only enlarging and shrinking of frame in + * both dimensions, and fail otherwise. + * Return value: + * 0 succesfull + * -1 error, computation failed + * (i.e. width or height not multiple of 8) + * Side effects: + * if succesfull, zoom_{width,height} will be set to 0. + */ +int tc_compute_fast_resize_values(void *_vob, int strict); + +/*************************************************************************/ + +/** + * tc_find_best_aspect_ratio: + * set sar_num and sar_den to the sample aspect ratio (also called + * pixel aspect ratio) described by vob->ex_par, + * vob->ex_par_width, vob->ex_par_height and vob->ex_asr. + * + * This function might return quite high values in sar_num and + * sar_den. Depending on what codec these parameters are given to, + * eventually a common factor should be reduced first. In case of x264 + * this is not needed, because it's done in x264's code. + * + * Parameters: + * vob: constant pointer to vob structure. + * sar_num: integer to store SAR-numerator in. + * sar_den: integer to store SAR-denominator in. + * tag: tag to use in log messages (if any). + * + * Returns: + * 0 on success, nonzero otherwise (this means bad parameters). + */ +int tc_find_best_aspect_ratio(const void *_vob, + int *sar_num, int *sar_den, + const char *tag); + +/*************************************************************************/ + +/* + * XXX: add some general notes about quantization matrices stored + * into files (format etc. etc.) + * + * tc_*_matrix GOTCHA: + * Why _two_ allowed elements wideness? Why this mess? + * The problem is that XviD and libavcodec wants elements for + * quantization matrix in two different wideness. Obviously + * we DON'T want to patch such sources, so we must handle in + * some way this difference. + * Of course we are looking for cleaner solutions. + * -- fromani 20060305 + */ + +/* + * Total size (=number of elements) of quantization matrix + * for following two support functions + */ +#define TC_MATRIX_SIZE (64) + +/* + * tc_read_matrix: + * read a quantization matrix from given file. + * Can read 8-bit wide or 16-bit wide matrix elements. + * Store readed matrix in a caller-provided buffer. + * + * Caller can select the elements wideness just + * providing a not-NULL buffer for corresponding buffer. + * For example, if caller wants to read a quantization matrix + * from 'matrix.txt', and want 16-bit wide elements, it + * will call + * + * uint16_t matrix[TC_MATRIX_SIZE]; + * tc_read_matrix('matrix.txt', NULL, matrix); + * + * Parameters: + * filename: read quantization matrix from this file. + * m8: buffer for 8-bit wide elements quantization matrix + * m16: buffer for 16-bit wide elements quantization matrix + * + * NOTE: if m8 AND m16 BOTH refers to valid buffers, 8-bit + * wideness is preferred. + * Return value: + * -1 filename not found, or neither buffers is valid. + * +1 read error: matrix incomplete or badly formatted. + * 0 no errors. + * Side effects: + * a file on disk is open, readed, closed. + * Preconditions: + * buffer provided by caller MUST be large enough to hold + * TC_MATRIX_SIZE elements of requested wideness. + * At least one given buffer is valid. + */ +int tc_read_matrix(const char *filename, uint8_t *m8, uint16_t *m16); + +/* + * tc_print_matrix: + * print (using tc_log*) a quantization matrix. + * Can print 8-bit wide or 16-bit wide matrix elements. + * + * Caller must provide a valid pointer correspoinding to + * wideness of elements of matrix to be printed. + * Example: quantization matrix has 8-bit wide elements: + * + * uint8_t matrix[TC_MATRIX_SIZE]; + * // already filled with something useful + * tc_print_matrix(matrix, NULL); + * + * Parameters: + * m8: pointer to 8-bit wide elements quantization matrix. + * m16: pointer to 16-bit wide elements quantization matrix. + * + * NOTE: if m8 AND m16 BOTH refers to valid buffers, 8-bit + * wideness is preferred. + * Preconditions: + * At least one given pointer is valid. + */ +void tc_print_matrix(uint8_t *m8, uint16_t *m16); + +#ifdef __cplusplus +} +#endif + +#endif /* _LIBTC_H */ |