[NUT-devel] [nut]: r207 - trunk/libnut/libnut.h

[ods15]

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 []);
 
-/**
- at 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
- at brief "s" is malloced and needs to be free'd.
- at 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