Author: diego
Date: Fri Feb 1 16:11:48 2008
New Revision: 533
Log:
doxygen comment review, part I
Modified:
src/trunk/libnut/libnut.h
Modified: src/trunk/libnut/libnut.h
==============================================================================
--- src/trunk/libnut/libnut.h (original)
+++ src/trunk/libnut/libnut.h Fri Feb 1 16:11:48 2008
@@ -8,13 +8,13 @@
#include <stdint.h>
#include <sys/types.h>
-/// \defgroup common Common Defines and Enums
-/// \defgroup muxer libnut Muxer
-/// \defgroup demuxer libnut Demuxer
+/// \defgroup common common defines and enums
+/// \defgroup muxer libnut muxer
+/// \defgroup demuxer libnut demuxer
/// \addtogroup common
/// @{
-#define NUT_VERSION 2 ///< Version of NUT specification this library implements
+#define NUT_VERSION 2 ///< Version of NUT specification this library implements.
enum nut_stream_class_t {
NUT_VIDEO_CLASS = 0, ///< = 0
@@ -23,167 +23,167 @@ enum nut_stream_class_t {
NUT_USERDATA_CLASS = 3, ///< = 3
};
-/// Frame flags bitfield (several flags may be set at once)
+/// frame flags bitfield (several flags may be set at once)
enum nut_frame_flags_t {
- NUT_FLAG_KEY = 1, ///< Marks frame as keyframe
- NUT_FLAG_EOR = 2, ///< Marks end of relavence for stream. #NUT_FLAG_KEY \b must be set together with this flag.
+ NUT_FLAG_KEY = 1, ///< Marks a frame as keyframe.
+ NUT_FLAG_EOR = 2, ///< Marks end of relevance for stream. #NUT_FLAG_KEY \b must be set together with this flag.
};
/// @}
typedef struct nut_context_s nut_context_t;
-/// Memory allocation function pointers \ingroup demuxer muxer
+/// memory allocation function pointers \ingroup demuxer muxer
typedef struct {
- void * (*malloc)(size_t size); ///< Memory allocation malloc function pointer
- void * (*realloc)(void *ptr, size_t size); ///< Memory allocation realloc function pointer
- void (*free)(void *ptr); ///< Memory allocation free function pointer
+ void * (*malloc)(size_t size); ///< memory allocation malloc function pointer
+ void * (*realloc)(void *ptr, size_t size); ///< memory allocation realloc function pointer
+ void (*free)(void *ptr); ///< memory allocation free function pointer
} nut_alloc_t;
-/// Timebase struct \ingroup demuxer muxer
+/// timebase struct \ingroup demuxer muxer
typedef struct {
int num; ///< Example: 1001
int den; ///< Example: 24000
} nut_timebase_t;
-/// Stream header struct \ingroup demuxer muxer
+/// stream header struct \ingroup demuxer muxer
typedef struct {
- int type; ///< Possible values are enum ::nut_stream_class_t. Value of -1 terminates a stream header array
- int fourcc_len; ///< Length of fourcc
+ int type; ///< Possible values are enum ::nut_stream_class_t. A value of -1 terminates a stream header array.
+ int fourcc_len; ///< fourcc length
uint8_t * fourcc; ///< fourcc in big-endian format
- nut_timebase_t time_base; ///< Timebase of stream
- int fixed_fps; ///< Flag if stream is fixed fps or not
- int decode_delay; ///< Decode delay of codec in this stream
- int codec_specific_len; ///< Length of codec specific data
- uint8_t * codec_specific; ///< Codec specific data. May be NULL if #codec_specific_len is zero.
- uint64_t max_pts; ///< Only used in demuxer. If non-zero, then it is the highest value in stream
+ nut_timebase_t time_base; ///< stream timebase
+ int fixed_fps; ///< denote stream as fixed or variable fps
+ int decode_delay; ///< decode delay of codec in this stream
+ int codec_specific_len; ///< length of codec-specific data
+ uint8_t * codec_specific; ///< Codec specific data, may be NULL if #codec_specific_len is zero.
+ uint64_t max_pts; ///< Only used in demuxer. If non-zero, then it is the highest value in the stream.
/// \name Video
/// Only used if type is #NUT_VIDEO_CLASS @{
- int width; ///< Width of video in pixels
- int height; ///< Height of video in pixels
- int sample_width; ///< Ratio to stretch the video. May only be zero if #sample_height is zero
- int sample_height; ///< Ratio to stretch the video. May only be zero if #sample_width is zero
+ int width; ///< width of video in pixels
+ int height; ///< height of video in pixels
+ int sample_width; ///< Ratio to stretch the video, may only be zero if #sample_height is zero.
+ int sample_height; ///< Ratio to stretch the video, may only be zero if #sample_width is zero.
int colorspace_type;
/// \name Audio
/// Only used if type is #NUT_AUDIO_CLASS @{
- int samplerate_num; ///< Sample rate of audio. Example: 44100
- int samplerate_denom; ///< Sample rate denominator of audio. Example: 1
- int channel_count; ///< Amount of audio channels
+ int samplerate_num; ///< audio sample rate, example: 44100
+ int samplerate_denom; ///< audio sample rate denominator, example: 1
+ int channel_count; ///< number of audio channels
} nut_stream_header_t;
-/// Single info field struct \ingroup demuxer muxer
+/// single info field struct \ingroup demuxer muxer
typedef struct {
char type[7]; ///< NULL-terminated string
- char name[65]; ///< NULL-terminated string. Name of info field
- int64_t val; ///< Meaning of value defined by #type
- int den; ///< Used if #type is "r". #val is the numerator
- nut_timebase_t tb; ///< Used if #type is "t"
- uint8_t * data; ///< Used if #type is non-numeric
+ char name[65]; ///< NULL-terminated string, name of info field
+ int64_t val; ///< meaning of value defined by #type
+ int den; ///< Used if #type is "r", #val is the numerator.
+ nut_timebase_t tb; ///< Used if #type is "t".
+ uint8_t * data; ///< Used if #type is non-numeric.
} nut_info_field_t;
-/// Single info packet struct \ingroup demuxer muxer
+/// single info packet struct \ingroup demuxer muxer
typedef struct {
- int count; ///< Indicates how many info fields are provided in #fields
- int stream_id_plus1; ///< Zero indicates non-stream-specific info packet
- int chapter_id; ///< Indicates which subsection of file this info packet applies to
- nut_timebase_t chapter_tb; ///< Timebase of #chapter_start and #chapter_len
- uint64_t chapter_start; ///< Start of chapter or complete file
- uint64_t chapter_len; ///< Length of chapter or complete file
- nut_info_field_t * fields; ///< Info fields, has #count elements
+ int count; ///< number of info fields in #fields.
+ int stream_id_plus1; ///< Zero indicates non-stream-specific info packet.
+ int chapter_id; ///< subsection of the file this info packet applies to
+ nut_timebase_t chapter_tb; ///< timebase of #chapter_start and #chapter_len
+ uint64_t chapter_start; ///< start of chapter or complete file
+ uint64_t chapter_len; ///< length of chapter or complete file
+ nut_info_field_t * fields; ///< Info fields, has #count elements.
} nut_info_packet_t;
-/// Single frame packet struct \ingroup demuxer muxer
+/// single frame packet struct \ingroup demuxer muxer
typedef struct {
- int len; ///< Length of frame in bytes. \b Must be zero if #NUT_FLAG_EOR is set.
- int stream; ///< Stream index of frame
- uint64_t pts; ///< Presentation timestamp of frame
- int flags; ///< Frame flags from #nut_frame_flags_t
+ int len; ///< Length of frame in bytes, \b must be zero if #NUT_FLAG_EOR is set.
+ int stream; ///< stream index of frame
+ uint64_t pts; ///< presentation timestamp of frame
+ int flags; ///< frame flags from #nut_frame_flags_t
int64_t next_pts; ///< Only used in muxer. Only necessary if nut_write_frame_reorder() is used.
} nut_packet_t;
/*****************************************
- * Muxer *
+ * muxer *
*****************************************/
/// \addtogroup muxer
/// @{
-/// Output stream struct
+/// output stream struct
typedef struct {
- void * priv; ///< Opaque priv pointer to be given to function calls
- int (*write)(void * priv, size_t len, const uint8_t * buf); ///< If NULL, nut_output_stream_t::priv is used as FILE*
+ void * priv; ///< opaque priv pointer to be passed to function calls
+ int (*write)(void * priv, size_t len, const uint8_t * buf); ///< If NULL, nut_output_stream_t::priv is used as FILE*.
} nut_output_stream_t;
-/// NUT Framecode table input
+/// NUT framecode table input
typedef struct {
- int flag; ///< Flags of framecode entry.
+ int flag; ///< framecode entry flags
int pts; ///< pts delta from previous frame
int stream; ///< stream_id of frame
- int mul; ///< Multiplier for coded frame size
+ int mul; ///< multiplier for coded frame size
int size; ///< LSB for coded frame size
int count; ///< Explicit count of framecode entry, \b should be (mul-size) in almost all cases.
} nut_frame_table_input_t;
-/// Muxer options struct
+/// muxer options struct
typedef struct {
- nut_output_stream_t output; ///< Output stream function pointers
- nut_alloc_t alloc; ///< Memory allocation function pointers
- int write_index; ///< Writes index at end-of-file
- int realtime_stream; ///< Implies no write_index
- int max_distance; ///< Valid values from 32-65536. Recommended value is 32768. Lower values give better seekability and error detection and recovery but cause higher overhead.
- nut_frame_table_input_t * fti; ///< Framecode table. May be NULL.
+ nut_output_stream_t output; ///< output stream function pointers
+ nut_alloc_t alloc; ///< memory allocation function pointers
+ int write_index; ///< whether or not to write an index
+ int realtime_stream; ///< Implies no write_index.
+ int max_distance; ///< Valid values are 32-65536, the recommended value is 32768. Lower values give better seekability and error detection and recovery but cause higher overhead.
+ nut_frame_table_input_t * fti; ///< Framecode table, may be NULL.
} nut_muxer_opts_t;
-/// Allocates NUT muxer context and writes headers to file
+/// Allocates NUT muxer context and writes headers to file.
nut_context_t * nut_muxer_init(const nut_muxer_opts_t * mopts, const nut_stream_header_t s[], const nut_info_packet_t info[]);
-/// Deallocates NUT muxer context
+/// Deallocates NUT muxer context.
void nut_muxer_uninit(nut_context_t * nut);
-/// Writes a single frame to NUT file
+/// Writes a single frame to a NUT file.
void nut_write_frame(nut_context_t * nut, const nut_packet_t * p, const uint8_t * buf);
-/// Write a single info packet to NUT file
+/// Writes a single info packet to a NUT file.
void nut_write_info(nut_context_t * nut, const nut_info_packet_t * info);
-/// Buffers and sorts a single frame to be written NUT file
+/// Buffers and sorts a single frame to be written to a NUT file.
void nut_write_frame_reorder(nut_context_t * nut, const nut_packet_t * p, const uint8_t * buf);
-/// Flushes reorder buffer and deallocates NUT muxer context
+/// Flushes reorder buffer and deallocates NUT muxer context.
void nut_muxer_uninit_reorder(nut_context_t * nut);
-/// Creates an optimized framecode table for NUT main header based on stream info
+/// Creates an optimized framecode table for the NUT main header based on stream info.
void nut_framecode_generate(const nut_stream_header_t s[], nut_frame_table_input_t fti[256]);
/// @}
/*****************************************
- * Demuxer *
+ * demuxer *
*****************************************/
/// \addtogroup demuxer
/// @{
-/// Input stream struct
+/// input stream struct
typedef struct {
- void * priv; ///< Opaque priv pointer to be given to function calls
- size_t (*read)(void * priv, size_t len, uint8_t * buf); ///< Input stream read function. Must return amount of bytes actually read.
- off_t (*seek)(void * priv, long long pos, int whence); ///< Input stream seek function. Must return position in file after seek.
+ void * priv; ///< opaque priv pointer to be passed to function calls
+ size_t (*read)(void * priv, size_t len, uint8_t * buf); ///< Input stream read function, must return amount of bytes actually read.
+ off_t (*seek)(void * priv, long long pos, int whence); ///< Input stream seek function, must return position in file after seek.
int (*eof)(void * priv); ///< Returns if EOF has been met in stream in case of read error.
- off_t file_pos; ///< File position at begginning of read.
+ off_t file_pos; ///< file position at beginning of read
} nut_input_stream_t;
-/// Demuxer options struct
+/// demuxer options struct
typedef struct {
- nut_input_stream_t input; ///< Input stream function pointers
- nut_alloc_t alloc; ///< Memory allocation function pointers
- int read_index; ///< Seeks to end-of-file at begginning of playback to search for index. Implies cache_syncpoints
- int cache_syncpoints; ///< Improoves seekability and error recovery greatly, but costs some memory (0.5mb for very large files).
- void * info_priv; ///< Opaque priv pointer to be given to #new_info
+ nut_input_stream_t input; ///< input stream function pointers
+ nut_alloc_t alloc; ///< memory allocation function pointers
+ int read_index; ///< Seeks to end-of-file at beginning of playback to search for index. Implies cache_syncpoints.
+ int cache_syncpoints; ///< Improves seekability and error recovery greatly, but costs some memory (0.5MB for very large files).
+ void * info_priv; ///< opaque priv pointer to be passed to #new_info
void (*new_info)(void * priv, nut_info_packet_t * info); ///< Function to be called when info is found mid-stream. May be NULL.
} nut_demuxer_opts_t;
@@ -192,7 +192,7 @@ enum nut_errors {
NUT_ERR_EOF = 1, ///< = 1
NUT_ERR_EAGAIN = 2, ///< = 2
NUT_ERR_OUT_OF_MEM = 3, ///< = 3
- NUT_ERR_NOT_SEEKABLE, ///< Can only be returned by nut_seek(). Indicates that the seek was not successful.
+ NUT_ERR_NOT_SEEKABLE, ///< Can only be returned by nut_seek(). Indicates that the seek was unsuccessful.
NUT_ERR_GENERAL_ERROR,
NUT_ERR_BAD_VERSION,
NUT_ERR_NOT_FRAME_NOT_N,
@@ -208,25 +208,25 @@ enum nut_errors {
NUT_ERR_BAD_EOF,
};
-/// Creates a NUT demuxer context. Does not read any information from file
+/// Creates a NUT demuxer context. Does not read any information from file.
nut_context_t * nut_demuxer_init(nut_demuxer_opts_t * dopts);
-/// Frees a NUT demuxer context. No other functions can be called after this
+/// Frees a NUT demuxer context. No other functions can be called after this.
void nut_demuxer_uninit(nut_context_t * nut);
-/// Read headers and index, \b must be called at begginning
+/// Reads headers and index, \b must be called at init.
int nut_read_headers(nut_context_t * nut, nut_stream_header_t * s [], nut_info_packet_t * info []);
-/// Gets frame header, must be called before each packet
+/// Gets frame header, must be called before each packet.
int nut_read_next_packet(nut_context_t * nut, nut_packet_t * pd);
-/// Just reads the frame \b data, not the header
+/// Reads just the frame \b data, not the header.
int nut_read_frame(nut_context_t * nut, int * len, uint8_t * buf);
-/// Gives human readable description of the error return code of any demuxing function
+/// Gives human readable description of the error return code of any demuxing function.
const char * nut_error(int error);
-/// Seeks to requested position in seconds
+/// Seeks to the requested position in seconds.
int nut_seek(nut_context_t * nut, double time_pos, int flags, const int * active_streams);
/// @}
