Mercurial > libdvdnav.hg
changeset 43:0ba15bf3dc25 src
Biiiiiiig change to let doxygen generate some docs for the library. Note that I'm in no way sure that the autoconf stuff plays nice.
| author | richwareham |
|---|---|
| date | Thu, 06 Jun 2002 15:03:09 +0000 |
| parents | 131ad65a2398 |
| children | c50cb59dbb19 |
| files | dvd_types.h dvdnav.c dvdnav.h dvdnav_events.h |
| diffstat | 4 files changed, 547 insertions(+), 165 deletions(-) [+] |
line wrap: on
line diff
--- a/dvd_types.h Tue Jun 04 13:35:16 2002 +0000 +++ b/dvd_types.h Thu Jun 06 15:03:09 2002 +0000 @@ -28,6 +28,12 @@ #include <inttypes.h> /** + * \file dvd_types.h + * + * Various useful structs and enums for DVDs. + */ + +/** * DVD Domain */ typedef enum { @@ -279,12 +285,15 @@ int more_to_come; } DVDVideoAttributes_t; +/** + * Atructure containing info on highlight areas. + */ typedef struct { - uint32_t palette; /* The CLUT entries for the highlight palette + uint32_t palette; /*!< The CLUT entries for the highlight palette (4-bits per entry -> 4 entries) */ - uint16_t sx,sy,ex,ey; /* The start/end x,y positions */ - uint32_t pts; /* Highlight PTS to match with SPU */ - uint32_t buttonN; /* Button number for the SPU decoder. */ + uint16_t sx,sy,ex,ey; /*!< The start/end x,y positions */ + uint32_t pts; /*!< Highlight PTS to match with SPU */ + uint32_t buttonN; /*!< Button number for the SPU decoder. */ } dvdnav_highlight_area_t;
--- a/dvdnav.c Tue Jun 04 13:35:16 2002 +0000 +++ b/dvdnav.c Thu Jun 06 15:03:09 2002 +0000 @@ -411,7 +411,7 @@ vobu->vobu_start = nav_dsi->dsi_gi.nv_pck_lbn; /* Absolute offset from start of disk */ vobu->vobu_length = nav_dsi->dsi_gi.vobu_ea; /* Relative offset from vobu_start */ - /** + /* * If we're not at the end of this cell, we can determine the next * VOBU to display using the VOBU_SRI information section of the * DSI. Using this value correctly follows the current angle, @@ -931,6 +931,9 @@ /* * $Log$ + * Revision 1.21 2002/06/06 15:03:09 richwareham + * Biiiiiiig change to let doxygen generate some docs for the library. Note that I'm in no way sure that the autoconf stuff plays nice. + * * Revision 1.20 2002/06/04 13:35:16 richwareham * Removed more C++ style comments *
--- a/dvdnav.h Tue Jun 04 13:35:16 2002 +0000 +++ b/dvdnav.h Thu Jun 06 15:03:09 2002 +0000 @@ -21,6 +21,12 @@ * */ +/** + * \file dvdnav.h + * The main file you should include if you want to access dvdnav + * functionality. + */ + #ifndef DVDNAV_H_INCLUDED #define DVDNAV_H_INCLUDED @@ -36,7 +42,11 @@ #include <dvdread/dvd_reader.h> -/* Opaque dvdnav data-type */ +/** + * Opaque data-type can be viewed as a 'DVD handle'. You should get + * a pointer to a dvdnav_t from the dvdnav_open() function. + * \sa dvdnav_open() + */ typedef struct dvdnav_s dvdnav_t; /* Status */ @@ -46,20 +56,32 @@ #define DVDNAV_STATUS_OK 1 /** - * NOTE: Unless otherwise stated, all functions return DVDNAV_STATUS_OK if + * NOTE: */ + +/** + * \defgroup init Initialisation & housekeeping functions + * These functions allow you to open a DVD device and associate it + * with a dvdnav_t. + * + * Unless otherwise stated, all functions return DVDNAV_STATUS_OK if * they succeeded, otherwise DVDNAV_STATUS_ERR is returned and the error may * be obtained by calling dvdnav_err_to_string(). + * + * A minimal <tt>libdvdnav</tt> program should always call dvdnav_open() + * and dvdnav_close(). + * + * \par Example: + * \include minimal.c + * + * @{ */ -/*** Initialisation & housekeeping functions ***/ - /** * Attempts to open the DVD drive at the specifiec path and pre-cache * any CSS-keys that your hacked libdvdread may use. * - * Arguments: - * dest -- Pointer to a dvdnav_t pointer to fill in. - * path -- Any libdvdread acceptable path + * \param dest Pointer to a dvdnav_t pointer to fill in. + * \param path Any libdvdread acceptable path */ dvdnav_status_t dvdnav_open(dvdnav_t** dest, char *path); @@ -67,70 +89,107 @@ * Closes a dvdnav_t previously opened with dvdnav_open(), freeing any * memory associated with it. * - * Arguments: - * self -- dvdnav_t to close. + * \param self dvdnav_t to close. */ dvdnav_status_t dvdnav_close(dvdnav_t *self); /** - * Resets the VM and buffers in a previously opened dvdnav + * Resets the virtual machine and buffers in a previously opened dvdnav * - * Arguments: - * self -- dvdnav_t to reset. + * \param self dvdnav_t to reset. */ dvdnav_status_t dvdnav_reset(dvdnav_t *self); /** - * Fills a pointer wiht a value pointing to a string describing + * Fills a pointer with a value pointing to a string describing * the path associated with an open dvdnav_t. It assigns it NULL * on error. * - * Arguments: - * path -- Pointer to char* to fill in. + * \param self Pointer to dvdnav_t associated with this operation. + * \param path Pointer to char* to fill in. */ dvdnav_status_t dvdnav_path(dvdnav_t *self, char** path); /** * Returns a human-readable string describing the last error. * - * Returns: A pointer to said string. + * \param self Pointer to dvdnav_t associated with this operation. + * \returns A pointer to said string. */ char* dvdnav_err_to_string(dvdnav_t *self); -/** DVD Player characteristics (FIXME: Need more entries) **/ +/** \@} */ + +/** + * \defgroup char Changing and Reading DVD Player characteristics + * + * These functions allow you to manipulate the various global characteristics + * of the DVD playback engine. + * + * @{ + */ /** - * Returns the region mask (bit 0 - region 1, bit 1 - R 2, etc) of the - * VM + * Returns the region mask (bit 0 set implies region 1, bit 1 set implies + * region 2, etc) of the virtual machine. Generally you will only need to set + * this if you are playing RCE discs which query the virtual machine as to its + * region setting. + * + * \par Note: + * This has <b>nothing</b> to do with the region setting of the DVD drive. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param region Pointer to an int which will receive the region code mask. */ dvdnav_status_t dvdnav_get_region_mask(dvdnav_t *self, int *region); /** - * Sets the region mask of the VM. + * Sets the region mask of the virtual machine. * - * mask: 0x00..0xff + * \param self Pointer to dvdnav_t associated with this operation. + * \param mask 0x00..0xff -- the desired region mask. + * + * \sa dvdnav_get_region_mask() */ dvdnav_status_t dvdnav_set_region_mask(dvdnav_t *self, int mask); /** - * Specify whether read-ahead caching should be used + * Specify whether read-ahead caching should be used. You may not want this if your + * decoding engine does its own buffering or if you don't like the fact that this is + * implemented in a multithreaded manner. * - * use_readahead: 0 - no, 1 - yes + * \param self Pointer to dvdnav_t associated with this operation. + * \param use_readahead 0 - no, 1 - yes */ dvdnav_status_t dvdnav_set_readahead_flag(dvdnav_t *self, int use_readahead); /** - * Query state of readahead flag + * Query whether readahead caching/buffering will be used. * - * flag: pointer to int to recieve flag value + * \param self Pointer to dvdnav_t associated with this operation. + * \param flag Pointer to int to recieve flag value. + * + * \sa dvdnav_get_readahead_flag() */ dvdnav_status_t dvdnav_get_readahead_flag(dvdnav_t *self, int* flag); -/** Getting data **/ +/** + * @} + */ /** - * Gets the next block off the DVD places it in 'buf'. If there is any - * special information, the value pointed to by 'event' gets set + * \defgroup data Reading Data + * + * These functions are used to poll the playback enginge and actually get data + * off the DVD. + * + * @{ + */ + +/** + * Attempts to get the next block off the DVD and copies it into the buffer 'buf'. + * If there is any special actions that may need to be performed, the value + * pointed to by 'event' gets set * accordingly. * * If 'event' is DVDNAV_BLOCK_OK then 'buf' is filled with the next block @@ -138,43 +197,75 @@ * then set to 2048. * * Otherwise, buf is filled with an appropriate event structure and - * len is set to the length of that structure, + * len is set to the length of that structure. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param buf Buffer (at least 2048 octets) to fill with next block/event structure. + * \param event Pointer to int to get event type. + * \param len Pointer to int to get the number of octets written into buf. */ dvdnav_status_t dvdnav_get_next_block(dvdnav_t *self, unsigned char *buf, int *event, int *len); -/** Navigation **/ +/** + * Get video aspect code. + * + * \param self Pointer to dvdnav_t associated with this operation. + * + * \returns Video aspect ratio code, 0 -- 4:3, 2 -- 16:9 + */ +uint8_t dvdnav_get_video_aspect(dvdnav_t *self); /** - * Returns the number of titles on the disk in titles. + * @} + */ + +/** + * \defgroup nav Navigation Commands + * + * @{ + */ + +/** + * Returns the number of titles on the disk. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param titles Pointer to int to receive number of titles. */ dvdnav_status_t dvdnav_get_number_of_titles(dvdnav_t *self, int *titles); /** - * Returns the number of programs within the current title in programs. + * Returns the number of programs within the current title. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param programs Pointer to int to receive number of programs. */ dvdnav_status_t dvdnav_get_number_of_programs(dvdnav_t *self, int *programs); /** - * If we are currently in a still-frame, skip it. + * If we are currently in a still-frame this function skips it (or attempts to). + * This might fail if this still-frame is of infinite duration as most DVD + * authors wouldn't expect you to be able to do this <tt>:)</tt> + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_still_skip(dvdnav_t *self); /** - * Plays a specified title of the DVD + * Plays a specified title of the DVD. * - * Arguments: - * title -- 1..99 + * \param self Pointer to dvdnav_t associated with this operation. + * \param title 1..99 -- Title number to play. */ dvdnav_status_t dvdnav_title_play(dvdnav_t *self, int title); /** * Plays the specifiec title, starting from the specified - * part (chapter) + * part (chapter). * - * Arguments: - * title -- 1..99 - * part -- 1..999 + * \param self Pointer to dvdnav_t associated with this operation. + * \param title 1..99 -- Title number to play. + * \param part 1..999 -- Part to start from. */ dvdnav_status_t dvdnav_part_play(dvdnav_t *self, int title, int part); @@ -182,10 +273,13 @@ * Play the specified amount of parts of the specified title of * the DVD then STOP. * - * Arguments: - * title -- 1..99 - * part -- 1..999 - * parts_to_play -- 1..999 + * \par Note: + * Currently unimplemented! + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param title 1..99 -- Title number to play. + * \param part 1..999 -- Part to start from. + * \param parts_to_play 1..999 -- Number of parts to play. */ dvdnav_status_t dvdnav_part_play_auto_stop(dvdnav_t *self, int title, int part, int parts_to_play); @@ -193,32 +287,53 @@ /** * Play the specified title starting from the specified time * - * Arguments: - * title -- 1..99 - * time: (timecode) hours, minutes, seconds + frames. + * \par Note: + * Currently unimplemented! + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param title 1..99 -- Title number to play. + * \param time Timecode to start from (hours, minutes, seconds + frames). */ dvdnav_status_t dvdnav_time_play(dvdnav_t *self, int title, unsigned long int time); /** * Stops playing the current title (causes a STOP action in - * dvdnav_get_next_block). + * dvdnav_get_next_block()). + * + * \param self Pointer to dvdnav_t associated with this operation. + * + * \sa dvdnav_get_next_block() */ dvdnav_status_t dvdnav_stop(dvdnav_t *self); /** - * Stop playing current title and play the "GoUp"-program chain + * Stop playing current title and play the "GoUp"-program chain + * (which generally leads to the title menu or a higer-level menu). + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_go_up(dvdnav_t *self); -/** SEARCHING **/ +/** + * @} + */ + +/** + * \defgroup search Searching + * + * @{ + */ /** * Stop playing the current title and start playback of the title * from the specified timecode. * - * Arguments: - * time -- timecode. + * \par Note: + * Currently unimplemented! + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param time Timecode to start from. */ dvdnav_status_t dvdnav_time_search(dvdnav_t *self, unsigned long int time); @@ -227,9 +342,9 @@ * Stop playing the current title and start playback of the title * from the specified sector offset. * - * Arguments: - * offset -- sector offset. - * origin -- Start from here, start or end. + * \param self Pointer to dvdnav_t associated with this operation. + * \param offset Sector offset to start from. + * \param origin Start from here, start or end. */ dvdnav_status_t dvdnav_sector_search(dvdnav_t *self, unsigned long int offset, int origin); @@ -238,52 +353,74 @@ * Stop playing the current title and start playback of the title * from the specified part (chapter). * - * Arguments: - * part: 1..999 + * \param self Pointer to dvdnav_t associated with this operation. + * \param part 1..999 -- Part to start from. */ dvdnav_status_t dvdnav_part_search(dvdnav_t *self, int part); /** * Stop playing the current title and start playback of the title - * from the previous program (if it exists) + * from the previous program (if it exists). + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_prev_pg_search(dvdnav_t *self); /** * Stop playing the current title and start playback of the title * from the first program. + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_top_pg_search(dvdnav_t *self); /** * Stop playing the current title and start playback of the title - * from the next program (if it exists) + * from the next program (if it exists). + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_next_pg_search(dvdnav_t *self); /** * Stop playing the current title and jump to the specified menu. * - * Arguments: - * menu -- Which menu to call + * \param self Pointer to dvdnav_t associated with this operation. + * \param menu Which menu to call (see DVDMenuID_t). + * + * \sa DVDMenuID_t (from <tt>libdvdread</tt>) */ dvdnav_status_t dvdnav_menu_call(dvdnav_t *self, DVDMenuID_t menu); /** * Return the title number and chapter currently being played or * -1 if in a menu. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param title Pointer to into which will receive the current title number. + * \param part Pointer to into which will receive the current part number. */ dvdnav_status_t dvdnav_current_title_info(dvdnav_t *self, int *title, int *part); /** - * Return a string describing the title + * Return a string describing the title. This is an ID string encoded on the + * disc byt the author. In many cases this is a descriptive string such as + * `<tt>THE_MATRIX</tt>' but sometimes is sigularly uninformative such as + * `<tt>PDVD-011421</tt>'. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param title_str Pointer to C-style string to receive a string describing the title. */ dvdnav_status_t dvdnav_get_title_string(dvdnav_t *self, char **title_str); /** * Return the current position (in blocks) within the current * part and the length (in blocks) of said part. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param pos Pointer to unsigned int to get the current position. + * \param len Pointer to unsinged int to hold the length of the current part. */ dvdnav_status_t dvdnav_get_position(dvdnav_t *self, unsigned int* pos, unsigned int *len); @@ -291,84 +428,166 @@ /** * Return the current position (in blocks) within the current * title and the length (in blocks) of said title. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param pos Pointer to unsigned int to get the current position. + * \param len Pointer to unsinged int to hold the length of the current title. */ dvdnav_status_t dvdnav_get_position_in_title(dvdnav_t *self, unsigned int* pos, unsigned int *len); -/** Highlights **/ +/** + * @} + */ /** - * Set the value pointed to to the currently highlighted button + * \defgroup highlight Highlights + * + * @{ + */ + +/** + * Get the currently highlighted button * number (1..36) or 0 if no button is highlighed. * - * Arguments: - * button -- Pointer to the value to fill in. + * \param self Pointer to dvdnav_t associated with this operation. + * \param button Pointer to the value to fill in. */ dvdnav_status_t dvdnav_get_current_highlight(dvdnav_t *self, int* button); + +/** + * Returns the Presentation Control Information (PCI) structure associated + * with the current position. + * + * \param self Pointer to dvdnav_t associated with this operation. + * + * \sa pci_t (in <tt>libdvdread</tt>) + */ pci_t* dvdnav_get_current_nav_pci(dvdnav_t *self); + +/** + * Get the area associated with a certain button. + * + * \param nav_pci Pointer to the PCI structure you may have got via + * dvdnav_get_current_nav_pci(). + * + * \param button Button number to query. + * \param mode 0..3 -- Button mode to query. + * \param highlight Pointer to dvdnav_highlight_area_t to fill in. + * + * \sa dvdnav_highlight_area_t + */ dvdnav_status_t dvdnav_get_highlight_area(pci_t* nav_pci , int32_t button, int32_t mode, dvdnav_highlight_area_t* highlight); /** - * Move button highlight around (e.g. with arrow keys) + * Move button highlight around as suggested by function name (e.g. with arrow keys). + * + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_upper_button_select(dvdnav_t *self); +/** + * Move button highlight around as suggested by function name (e.g. with arrow keys). + * + * \param self Pointer to dvdnav_t associated with this operation. + */ dvdnav_status_t dvdnav_lower_button_select(dvdnav_t *self); +/** + * Move button highlight around as suggested by function name (e.g. with arrow keys). + * + * \param self Pointer to dvdnav_t associated with this operation. + */ dvdnav_status_t dvdnav_right_button_select(dvdnav_t *self); +/** + * Move button highlight around as suggested by function name (e.g. with arrow keys). + * + * \param self Pointer to dvdnav_t associated with this operation. + */ dvdnav_status_t dvdnav_left_button_select(dvdnav_t *self); /** - * Activate (press) highlighted button + * Activate (press) the currently highlighted button. + * \param self Pointer to dvdnav_t associated with this operation. */ dvdnav_status_t dvdnav_button_activate(dvdnav_t *self); /** - * Highlight a specific button button + * Highlight a specific button. * - * button -- 1..39. + * \param self Pointer to dvdnav_t associated with this operation. + * \param button 1..39 -- Button number to activate. */ dvdnav_status_t dvdnav_button_select(dvdnav_t *self, int button); /** * Activate (press) specified button. * - * Arguments: - * button: 1..36 + * \param self Pointer to dvdnav_t associated with this operation. + * \param button 1..39 -- Button number to activate. */ dvdnav_status_t dvdnav_button_select_and_activate(dvdnav_t *self, int button); /** * Select button at specified (image) co-ordinates. * - * Arguments: - * x,y: Image co-ordinates + * \param self Pointer to dvdnav_t associated with this operation. + * \param x X co-ordinate in image. + * \param y Y xo-ordinate in image. */ dvdnav_status_t dvdnav_mouse_select(dvdnav_t *self, int x, int y); /** * Activate (press) button at specified co-ordinates. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param x X co-ordinate in image. + * \param y Y xo-ordinate in image. */ dvdnav_status_t dvdnav_mouse_activate(dvdnav_t *self, int x, int y); -/** i18n **/ +/** + * @} + */ + +/** + * \defgroup languages Menu Languages + * + * @{ + */ /** - * Set specified menu language. + * Set which menu language we should use. * - * Arguments: - * code: 1 char ISO 639 Language code + * \param self Pointer to dvdnav_t associated with this operation. + * \param code 2 char ISO639 Language code in a C-style string. */ dvdnav_status_t dvdnav_menu_languge_select(dvdnav_t *self, char *code); -/** SPU/Audio streams **/ +/** + * @} + */ + +/** + * \defgroup streams Sub-Picture Unit (Subtitles) and Audio Streams + * + * All these commands manipulate the audio/subtitle stream numbers that the + * player engine thinks is playing. Note that all the streams are still returned + * multiplexed by dvdnav_get_next_block(). You should try to make sure that the + * MPEG demuxer and the player engine both have the same thoughts on what stream the + * user is currently listening to. + * + * \sa dvdnav_get_next_block() + * + * @{ + */ /** * Set a specific PHYSICAL MPEG stream. * - * Arguments: - * audio: 0..7 + * \param self Pointer to dvdnav_t associated with this operation. + * \param audio 0..7 -- Stream number. */ dvdnav_status_t dvdnav_physical_audio_stream_change(dvdnav_t *self, int audio); @@ -376,8 +595,8 @@ /** * Set a specific logical audio stream. * - * Arguments: - * audio: 0..7 + * \param self Pointer to dvdnav_t associated with this operation. + * \param audio 0..7 -- Stream number. */ dvdnav_status_t dvdnav_logical_audio_stream_change(dvdnav_t *self, int audio); @@ -386,8 +605,8 @@ * Set the int pointed to to the current PHYSICAL audio * stream. * - * Arguments: - * audio: Pointer to value + * \param self Pointer to dvdnav_t associated with this operation. + * \param audio Pointer to int which will receive value. */ dvdnav_status_t dvdnav_get_physical_audio_stream(dvdnav_t *self, int* audio); @@ -395,8 +614,8 @@ * Set the int pointed to to the current LOGICAL audio * stream. * - * Arguments: - * audio: Pointer to value + * \param self Pointer to dvdnav_t associated with this operation. + * \param audio Pointer to int which will receive value. */ dvdnav_status_t dvdnav_get_logical_audio_stream(dvdnav_t *self, int* audio); @@ -404,9 +623,9 @@ * Set a specific PHYSICAL MPEG SPU stream and whether it should be * displayed. * - * Arguments: - * stream: 0..31 or 63 (dummy) - * display: 0..1 + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream 0..31 or 63 (dummy) -- Stram number. + * \param display: 0..1 -- Is this actually being displayed? */ dvdnav_status_t dvdnav_physical_spu_stream_change(dvdnav_t *self, int stream, int display); @@ -415,9 +634,9 @@ * Set a specific LOGICAL SPU stream and whether it should be * displayed. * - * Arguments: - * stream: 0..31 or 63 (dummy) - * display: 0..1 + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream 0..31 or 63 (dummy) -- Stram number. + * \param display: 0..1 -- Is this actually being displayed? */ dvdnav_status_t dvdnav_logical_spu_stream_change(dvdnav_t *self, int stream, int display); @@ -426,77 +645,206 @@ * Set the ints pointed to to the current PHYSICAL SPU * stream & display flag. * - * Arguments: - * stream, display: Pointers to value + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream Pointer which will receive value. + * \param display Pointer which will receive value. */ dvdnav_status_t dvdnav_get_physical_spu_stream(dvdnav_t *self, - int* stream, int* disply); + int* stream, int* display); /** * Set the ints pointed to to the current LOGICAL SPU * stream & display flag. * - * Arguments: - * stream, display: Pointers to value + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream Pointer which will receive value. + * \param display Pointer which will receive value. */ dvdnav_status_t dvdnav_get_logical_spu_stream(dvdnav_t *self, int* stream, int* disply); -/** ANGLES **/ +/** + * Converts a *logical* audio stream id into country code + * (returns <tt>0xffff</tt> if no such stream). + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream Stream number + */ +uint16_t dvdnav_audio_stream_to_lang(dvdnav_t *self, uint8_t stream); + +/** + * Converts a *logical* subpicture stream id into country code + * (returns <tt>0xffff</tt> if no such stream). + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param stream Stream number + */ +uint16_t dvdnav_spu_stream_to_lang(dvdnav_t *self, uint8_t stream); + +/** + * Converts a *physical* audio stream id into a logical stream number + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param audio_num Stream number + */ +int8_t dvdnav_get_audio_logical_stream(dvdnav_t *self, uint8_t audio_num); /** - * Sets the current angle + * Converts a *physical* subpicture stream id into a logical stream number + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param subp_num Stream number + */ +int8_t dvdnav_get_spu_logical_stream(dvdnav_t *self, uint8_t subp_num); + +/** + * Get active spu stream. + * + * \param self Pointer to dvdnav_t associated with this operation. + */ +int8_t dvdnav_get_active_spu_stream(dvdnav_t *self); + +/** + * @} + */ + +/** + * \defgroup angles Multiple angles * - * Arguments: - * angle: 1..9 + * The <tt>libdvdnav</tt> library abstracts away the difference between seamless and + * non-seamless angles. From the point of view of the programmer you just set the + * angle number and all is well in the world. + * + * \par Note: + * It is quite possible that some tremendously strange DVD feature might change the + * angle number from under you. Generally you should always view the results from + * dvdnav_get_angle_info() as definitive only up to the next time you call + * dvdnav_get_next_block(). + * + * @{ + */ + +/** + * Sets the current angle. If you try to follow a non existant angle + * the call fails. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param angle 1..9 -- Currentl angle to follow. */ dvdnav_status_t dvdnav_angle_change(dvdnav_t *self, int angle); /** - * Returns the current angle and number of angles present + * Returns the current angle and number of angles present. + * + * \param self Pointer to dvdnav_t associated with this operation. + * \param current_angle Pointer to int which will get the current angle. + * \param number_of_angles Pointer to int which will get the number of angles. */ dvdnav_status_t dvdnav_get_angle_info(dvdnav_t *self, int* current_angle, int *number_of_angles); +/** + * FIXME: WTF does this do? -- High qulaity documentation huh? + */ dvdnav_status_t dvdnav_get_cell_info(dvdnav_t *self, int* current_angle, int *number_of_angles); + /** - * Converts a *logical* subpicture stream id into country code - * (returns 0xffff if no such stream). + * @} */ -uint16_t dvdnav_audio_stream_to_lang(dvdnav_t *self, uint8_t stream); -uint16_t dvdnav_spu_stream_to_lang(dvdnav_t *self, uint8_t stream); + +/** + * \defgroup domain Domain Queries + * + * The following functions can be used to query whether we are in + * particular domains or not. + * + * @{ + */ /** - * Get substream id for logical stream *_num. + * Are we in the First Play domain. (Menu) + * \param self Pointer to dvdnav_t associated with this operation. + * \returns -1 on failure, 1 if condition is true, 0 if condition is false + */ +int8_t dvdnav_is_domain_fp(dvdnav_t *self); +/** + * Are we in the Video management Menu domain. (Menu) + * \param self Pointer to dvdnav_t associated with this operation. + * \returns -1 on failure, 1 if condition is true, 0 if condition is false */ -int8_t dvdnav_get_audio_logical_stream(dvdnav_t *self, uint8_t audio_num); -int8_t dvdnav_get_spu_logical_stream(dvdnav_t *self, uint8_t subp_num); +int8_t dvdnav_is_domain_vmgm(dvdnav_t *self); +/** + * Are we in the Video Title Menu domain (Menu) + * \param self Pointer to dvdnav_t associated with this operation. + * \returns -1 on failure, 1 if condition is true, 0 if condition is false + */ +int8_t dvdnav_is_domain_vtsm(dvdnav_t *self); +/** + * Are we in the Video Title domain (playing movie)? + * \param self Pointer to dvdnav_t associated with this operation. + * \returns -1 on failure, 1 if condition is true, 0 if condition is false + */ +int8_t dvdnav_is_domain_vts(dvdnav_t *self); /** - * Get active spu stream. + * @} */ -int8_t dvdnav_get_active_spu_stream(dvdnav_t *self); + +/* + * The following info appears on the front page of the reference manual. It is + * included here to keep it with the main dvdnav source files. The copyright notice + * refers to the comments _only_. All machine-readable source code is covered by + * the copyright notice at the top of this file. + * + * Oh, and the official language of the documentation is English -- + * English English (as in the English spoken in England) not US English. + */ /** - * Get video aspect - */ -uint8_t dvdnav_get_video_aspect(dvdnav_t *self); - -/* Following functions returns: - * -1 on failure, - * 1 if condition is true, - * 0 if condition is false + * \mainpage The libdvdnav Reference Documentation + * + * \section intro Introduction + * + * This reference documentation is intended to both provide a comprehensive reference to + * the <tt>libdvdnav</tt> DVD navigation library and a brief introduction to the library + * for new users. + * + * This documentation is automatically generated from the <tt>libdvdnav</tt> code so + * should remain somewhat relevant but as always be wary that <tt>libdvdnav</tt> + * is currently in heavy development and the API is not yet frozen. + * + * \subsection feedback Feedback + * + * All comments, error reports, additional information and criticism of all sorts + * should be directed to <tt>dvd-devel@lists.sf.net</tt>. + * + * \subsection disclaimer Disclaimer + * + * No liability for the contents of this documents can be accepted. Use the concepts, + * examples and other content at your own risk. Additionally, this is an early version, + * with many possibilities for inaccuracies and errors. + * + * As far as I know, all of the programmes mentioned here and example code quoted are + * released under the GNU General Public License or the Lesser GNU Public License. + * + * \subsection copyright Copyright information + * + * This document is copyrighted ©2002 by Richard Wareham and the <tt>libdvdnav</tt> + * project. It is distributed under the following terms: + * + * - This document may be reproduced and distributed in whole or in part, in any medium + * physical or electronic, as long as this copyright notice is retained on all copies. + * Commercial redistribution is allowed and encouraged; however, the author would like + * to be notified of any such distributions. + * - All translations, derivative works, or aggregate works incorporating any parts of + * this document must be covered under this copyright notice. That is, you may not produce + * a derivative work from this manual and impose additional restrictions on its distribution. + * + * \section started Getting started + * + * A good place to look is the <A HREF="modules.html">modules</a> section. */ -/*** Current VM domain state ***/ -/* First Play domain. (Menu) */ -int8_t dvdnav_is_domain_fp(dvdnav_t *self); -/* Video management Menu domain. (Menu) */ -int8_t dvdnav_is_domain_vmgm(dvdnav_t *self); -/* Video Title Menu domain (Menu) */ -int8_t dvdnav_is_domain_vtsm(dvdnav_t *self); -/* Video Title domain (playing movie). */ -int8_t dvdnav_is_domain_vts(dvdnav_t *self); #ifdef __cplusplus }
--- a/dvdnav_events.h Tue Jun 04 13:35:16 2002 +0000 +++ b/dvdnav_events.h Thu Jun 06 15:03:09 2002 +0000 @@ -28,65 +28,87 @@ #include <dvdread/nav_types.h> #include <dvdread/dvd_reader.h> -/* This header defines events and event types */ +/** + * \file dvdnav_events.h + * This header defines events and event types + */ /*** EVENTS ***/ -#define DVDNAV_BLOCK_OK 0 /* The next black was returned */ -#define DVDNAV_NOP 1 /* No action should be taken */ -#define DVDNAV_STILL_FRAME 2 /* The preceeding block was the last in a +#define DVDNAV_BLOCK_OK 0 /*!< The next black was returned */ +#define DVDNAV_NOP 1 /*!< No action should be taken */ +#define DVDNAV_STILL_FRAME 2 /*!< The preceeding block was the last in a still frame. */ -#define DVDNAV_SPU_STREAM_CHANGE 3 /* The SPU stream was changed */ -#define DVDNAV_AUDIO_STREAM_CHANGE 4 /* The Audio stream was changed */ -#define DVDNAV_VTS_CHANGE 5 /* We have changed VTS */ -#define DVDNAV_CELL_CHANGE 6 /* We have jumped to a new cell */ -#define DVDNAV_NAV_PACKET 7 /* The packet just passed was the NAV packet */ -#define DVDNAV_STOP 8 /* The last block was final, no more are coming */ -#define DVDNAV_HIGHLIGHT 9 /* Change highlight region */ -#define DVDNAV_SPU_CLUT_CHANGE 10 /* SPU CLUT */ -#define DVDNAV_SEEK_DONE 11 /* Seek done, subtitles should be reset */ -#define DVDNAV_HOP_CHANNEL 12 /* Sent when non-seemless stream change has happed */ - /* E.g. Menu button pressed causing change in menu */ +#define DVDNAV_SPU_STREAM_CHANGE 3 /*!< The SPU stream was changed */ +#define DVDNAV_AUDIO_STREAM_CHANGE 4 /*!< The Audio stream was changed */ +#define DVDNAV_VTS_CHANGE 5 /*!< We have changed VTS */ +#define DVDNAV_CELL_CHANGE 6 /*!< We have jumped to a new cell */ +#define DVDNAV_NAV_PACKET 7 /*!< The packet just passed was the NAV packet */ +#define DVDNAV_STOP 8 /*!< The last block was final, no more are coming */ +#define DVDNAV_HIGHLIGHT 9 /*!< Change highlight region */ +#define DVDNAV_SPU_CLUT_CHANGE 10 /*!< SPU CLUT */ +#define DVDNAV_SEEK_DONE 11 /*!< Seek done, subtitles should be reset */ +#define DVDNAV_HOP_CHANNEL 12 /*!< Sent when non-seemless stream change has happed + E.g. Menu button pressed causing change in menu */ /*** EVENT TYPES ***/ +/** + * Structure providing information on DVDNAV_STILL_FRAME events. + */ typedef struct { - int length; /* The length (in seconds) the still frame - * should be displayed for, or 0xff if - * indefinate. */ + int length; /*!< + The length (in seconds) the still frame + should be displayed for, or 0xff if + indefinate. */ } dvdnav_still_event_t; +/** + * Structure providing information on DVDNAV_*_STREAM_CHANGE events. + */ typedef struct { - int physical; /* The physical (MPEG) stream number. */ - int logical; /* The logical (DVD) stream number. */ + int physical; /*!< The physical (MPEG) stream number. */ + int logical; /*!< The logical (DVD) stream number. */ } dvdnav_stream_change_event_t; +/** + * Structure providing information on DVDNAV_VTS_CHANGE events. + */ typedef struct { - int old_vtsN; /* The old VTS number */ - dvd_read_domain_t old_domain; /* The old domain */ - int new_vtsN; /* The new one */ - dvd_read_domain_t new_domain; + int old_vtsN; /*!< The old VTS number */ + dvd_read_domain_t old_domain; /*!< The old domain */ + int new_vtsN; /*!< The new VTS number */ + dvd_read_domain_t new_domain; /*!< The new domain */ } dvdnav_vts_change_event_t; +/** + * Structure providing information on DVDNAV_CELL_CHANGE events. + */ typedef struct { - cell_playback_t *old_cell; /* The old cell (or NULL if this is + cell_playback_t *old_cell; /*!< The old cell (or NULL if this is the first cell) */ - cell_playback_t *new_cell; /* The cell_playback_t for the new cell */ + cell_playback_t *new_cell; /*!< The cell_playback_t for the new cell */ } dvdnav_cell_change_event_t; +/** + * Structure providing information on DVDNAV_NAV_PACKET events. + */ typedef struct { pci_t *pci; dsi_t *dsi; } dvdnav_nav_packet_event_t; +/** + * Structure providing information on DVDNAV_HIGHLIGHT events. + */ typedef struct { - int display; /* 0 - hide, 1 - show, entries below only guaranteed useful + int display; /*!< 0 - hide, 1 - show, entries below only guaranteed useful if this is '1' */ - uint32_t palette; /* The CLUT entries for the highlight palette + uint32_t palette; /*!< The CLUT entries for the highlight palette (4-bits per entry -> 4 entries) */ - uint16_t sx,sy,ex,ey; /* The start/end x,y positions */ - uint32_t pts; /* Highlight PTS to match with SPU */ - uint32_t buttonN; /* Button number for the SPU decoder. */ + uint16_t sx,sy,ex,ey; /*!< The start/end x,y positions */ + uint32_t pts; /*!< Highlight PTS to match with SPU */ + uint32_t buttonN; /*!< Button number for the SPU decoder. */ } dvdnav_highlight_event_t; #endif /* DVDNAV_EVENTS_H_INCLUDED */