Author: ods15 Date: Wed Nov 15 11:24:39 2006 New Revision: 207 Modified: trunk/libnut/libnut.h Log: update the very obsolete libnut.h comment to some of the new API. some of it is not true yet. Modified: trunk/libnut/libnut.h ============================================================================== --- trunk/libnut/libnut.h (original) +++ trunk/libnut/libnut.h Wed Nov 15 11:24:39 2006 @@ -90,9 +90,9 @@ typedef struct { char type[7]; char name[65]; - int64_t val; - int den; - nut_timebase_t tb; + int64_t val; // used in all types, is the length of data if there is data + int den; // used in type=="r" + nut_timebase_t tb; // used in type=="t" uint8_t * data; // must be NULL if carries no data } nut_info_field_t; @@ -134,68 +134,47 @@ void nut_write_info(nut_context_t * nut, const nut_info_packet_t * info); /** do the same as the above function, but deal with frame reordering */ -void nut_muxer_uninit_reorder(nut_context_t * nut); void nut_write_frame_reorder(nut_context_t * nut, const nut_packet_t * p, const uint8_t * buf); +void nut_muxer_uninit_reorder(nut_context_t * nut); // Demuxer -/** Just inits stuff, can never fail. */ +/** Just inits stuff, can never fail, except memory error... */ nut_context_t * nut_demuxer_init(nut_demuxer_opts_t * dopts); /** Just frees stuff. */ void nut_demuxer_uninit(nut_context_t * nut); -/** All these functions return: +/** +All of the following functions return: 0 success 1 unexpected or expected EOF. 2 EAGAIN. negative number: error, detailed error in nut_error(-1 * ret); -fatality: -EAGAIN is never fatal -EOF is always fatal -negative error is NOT fatal, UNLESS it was given by nut_read_next_packet. - -free-ing data malloced by the funtions is only ever needed after a -successful call. - to protect this, things which should've been malloced will -turn to NULL. +All errors except EAGAIN or ERR_NOT_SEEKABLE from nut_seek are fatal. +The only legal operation after a fatal error is nut_demuxer_uninit(). After an EAGAIN, whichever function returned it should always be re-called with same params when data is available. +*/ -nut_read_next_packet should always be called after a negative error. - +/** Read headers, must be called at begginning +Both `s' and `info' are handeled by context, and are illegal pointers +after nut_demuxer_uninit() . If `info' is NULL, no info is read. */ +int nut_read_headers(nut_context_t * nut, nut_stream_header_t * s [], nut_info_packet_t * info []); -/** -@return information about next packet. pd must be alloced. -If not skipped, the _appropriate_ function must be called. */ +/** Gives information on next frame, must be called before each packet. */ int nut_read_next_packet(nut_context_t * nut, nut_packet_t * pd); -/** Unless read_next_packet gives e_eof, skip_packet always works. -MUST be called after an e_unknown -len will be non-zero in the case of EAGAIN or EOF -len is the amount of bytes that are LEFT, not the ones read. */ int nut_skip_packet(nut_context_t * nut, int * len); -/** Read headers, must be called at begginning -@brief "s" is malloced and needs to be free'd. -@brief "info" is malloced and needs to be free'd using nut_free_info() for each packet! can be NULL though. -*/ -int nut_read_headers(nut_context_t * nut, nut_stream_header_t * s [], nut_info_packet_t * info []); - /** Just reads the frame DATA. all it's header has already been read by nut_read_next_packet. buf must be allocated and big enough. len will be non-zero in the case of EAGAIN or EOF len is the amount of bytes that are LEFT, not the ones read. */ int nut_read_frame(nut_context_t * nut, int * len, uint8_t * buf); -/** Allocates everything necessary for info. Last info ends just as -described by spec - 'id = 0'. */ -int nut_read_info(nut_context_t * nut, nut_info_packet_t * info []); - -/** must be called for infodata to be freed... */ -void nut_free_info(nut_info_packet_t info []); - /** "Can't find start code" "invalid frame code" "bad checksum" "bleh" */ const char * nut_error(int error); @@ -211,49 +190,4 @@ */ int nut_seek(nut_context_t * nut, double time_pos, int flags, const int * active_streams); - -/** -Internal secrets: -nut_read_next_packet: -Just about ALL error recovery will be put in nut_read_next_packet. -It should be called after an error, it should never return an error. -Only time nut_read_next_packet can return an error is if it can't -find main headers... - -nut_context remembers if headers have been read or not. - -If headers have not yet been read: -1. if the stream starts with "file_id_string", it will be skipped. -2. if the main headers cannot be found, nut_read_next_packet will - start hunting for them. - -Once they have been read, nut_read_next_packet will always return -e_unknown if it sees any header again. (so they will be skipped) - -nut_read_next_packet will return EOF if it reachs index_startcode, -end_startcode or stream EOF. - -nut_read_next_packet does handling necessary for new frames -regarding last_pts, not read_frame. - -nut_read_next_packet also does syncpoint handling. -It'll start hunting syncpoints if no syncpoint has appeared for a -long time or one of the functions just return a negative error. - -Other black magic: -When nut_read_headers is called, and the stream is seekable, it -searches for an index - -nut_skip_packet works differently according to packet type: -it either reads forward_ptr and skips by that, or it skips by -frame data. It also mallocs and frees memory to discard the -packet if non-seekable or method 0 was chosen. - -nut_read_frame is an incredibly trivial function, it just reads -the actual codec data, that's all. Only errors it could ever give -is EOF or EAGAIN. - -For an example see example.c -*/ - #endif // _NUT_H