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
_______________________________________________
NUT-devel mailing list
NUT-develmplayerhq.hu
http://lists.mplayerhq.hu/mailman/listinfo/nut-devel
|