changeset 147:26334f5fac2b src

since noone objected, I will get serious with that: review dvdnav.h and remove doxygen-style comments

--- a/dvdnav.h	Thu Apr 03 12:55:22 2003 +0000
+++ b/dvdnav.h	Thu Apr 03 12:57:41 2003 +0000
@@ -21,10 +21,9 @@
  *
  */
 
-/**
- * \file dvdnav.h
- * The main file you should include if you want to access dvdnav
- * functionality.
+/*
+ * This is the main header file applications should include if they want
+ * to access dvdnav functionality.
  */
 
 #ifndef DVDNAV_H_INCLUDED
@@ -45,173 +44,150 @@
 #include <dvdread/dvd_reader.h>
 #include <dvdread/ifo_types.h> /* For vm_cmd_t */
 
-/**
+
+/*********************************************************************
+ * dvdnav data types                                                 *
+ *********************************************************************/
+
+/*
  * 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()
+ * Never call free() on the pointer, you have to give it back with
+ * dvdnav_close().
  */
 typedef struct dvdnav_s dvdnav_t;
 
-/* Status */
+/* Status as reported by most of libdvdnav's functions */
 typedef int dvdnav_status_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().
+ */
 #define DVDNAV_STATUS_ERR 0
 #define DVDNAV_STATUS_OK  1
 
-/** 
- * \defgroup init Initialisation & housekeeping functions 
+
+/*********************************************************************
+ * 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
- * 
- * @{
  */
 
-/**
- * Attempts to open the DVD drive at the specifiec path and pre-cache
- * any CSS-keys that your hacked libdvdread may use.
+/*
+ * Attempts to open the DVD drive at the specified path and pre-cache
+ * the CSS-keys. libdvdread is used to access the DVD, so any source
+ * supported by libdvdread can be given with "path". Currently,
+ * libdvdread can access: DVD drives, DVD image files, DVD file-by-file
+ * copies.
  *
- * \param dest Pointer to a dvdnav_t pointer to fill in.
- * \param path Any libdvdread acceptable path
+ * The resulting dvdnav_t handle will be written to *dest.
  */
-dvdnav_status_t dvdnav_open(dvdnav_t** dest, const char *path); 
+dvdnav_status_t dvdnav_open(dvdnav_t **dest, const char *path);
 
-/**
+/*
  * Closes a dvdnav_t previously opened with dvdnav_open(), freeing any 
  * memory associated with it.
- *
- * \param self dvdnav_t to close.
  */
 dvdnav_status_t dvdnav_close(dvdnav_t *self);
 
-/**
- * Resets the virtual machine and buffers in a previously opened dvdnav
- *
- * \param self dvdnav_t to reset.
+/*
+ * Resets the DVD virtual machine and cache buffers.
  */
 dvdnav_status_t dvdnav_reset(dvdnav_t *self);
 
-/**
+/*
  * Fills a pointer with a value pointing to a string describing
- * the path associated with an open dvdnav_t. It assigns it NULL
+ * the path associated with an open dvdnav_t. It assigns *path to NULL
  * on error.
- *
- * \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, const char** path);
+dvdnav_status_t dvdnav_path(dvdnav_t *self, const char **path);
 
-/**
+/*
  * Returns a human-readable string describing the last error.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \returns A pointer to said string.
  */
 const char* dvdnav_err_to_string(dvdnav_t *self);
 
-/** \@} */
 
-/** 
- * \defgroup char Changing and Reading DVD Player characteristics
- * 
+/*********************************************************************
+ * 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 set implies region 1, bit 1 set implies
+/*
+ * Sets 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.
+ * This has _nothing_ to do with the region setting of the DVD drive.
  */
-dvdnav_status_t dvdnav_get_region_mask(dvdnav_t *self, int *region);
+dvdnav_status_t dvdnav_set_region_mask(dvdnav_t *self, int region_mask);
 
-/**
- * Sets the region mask of the virtual machine.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param mask 0x00..0xff -- the desired region mask.
+/*
+ * Returns the region mask (bit 0 set implies region 1, bit 1 set implies
+ * region 2, etc) of the virtual machine.
  *
- * \sa dvdnav_get_region_mask()
+ * This has _nothing_ to do with the region setting of the DVD drive.
  */
-dvdnav_status_t dvdnav_set_region_mask(dvdnav_t *self, int mask);
+dvdnav_status_t dvdnav_get_region_mask(dvdnav_t *self, int *region_mask);
 
-/**
+/*
  * Specify whether read-ahead caching should be used. You may not want this if your
  * decoding engine does its own buffering.
- * 
- * \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 whether readahead caching/buffering will be used.
+ *
+ * The default read-ahead cache does not use an additional thread for the reading
+ * (see read_cache.c for a threaded cache, but note that this code is currently
+ * unmaintained). It prebuffers on VOBU level by reading ahead several buffers
+ * on every read request. The speed of this prebuffering has been optimized to
+ * also work on slow DVD drives.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param flag Pointer to int to recieve flag value.
- *
- * \sa dvdnav_get_readahead_flag()
+ * If in addition you want to prevent memcpy's to improve performance, have a look
+ * at dvdnav_get_next_cache_block().
  */
-dvdnav_status_t dvdnav_get_readahead_flag(dvdnav_t *self, int* flag);
+dvdnav_status_t dvdnav_set_readahead_flag(dvdnav_t *self, int read_ahead_flag);
 
-/**
+/*
+ * Query whether read-ahead caching/buffering will be used.
+ */
+dvdnav_status_t dvdnav_get_readahead_flag(dvdnav_t *self, int *read_ahead_flag);
+
+/*
  * Specify whether the positioning works PGC or PG based.
- * Programs (PGs) on DVDs are similar to Chapters and the program chain (PGC)
+ * Programs (PGs) on DVDs are similar to Chapters and a program chain (PGC)
  * usually covers a whole feature. This affects the behaviour of the
- * functions dvdnav_get_position() and dvdnav_sector_search().
+ * functions dvdnav_get_position() and dvdnav_sector_search(). See there.
  * Default is PG based positioning.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param pgc 0 - PG based, 1 - PGC based
  */
-dvdnav_status_t dvdnav_set_PGC_positioning_flag(dvdnav_t *self, int pgc);
+dvdnav_status_t dvdnav_set_PGC_positioning_flag(dvdnav_t *self, int pgc_based_flag);
 
-/**
+/*
  * Query whether positioning is PG or PGC based.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param flag Pointer to int to recieve flag value.
- *
- * \sa dvdnav_set_PGC_positioning_flag()
  */
-dvdnav_status_t dvdnav_get_PGC_positioning_flag(dvdnav_t *self, int *flag);
+dvdnav_status_t dvdnav_get_PGC_positioning_flag(dvdnav_t *self, int *pgc_based_flag);
+
 
-/**
- * @}
+/*********************************************************************
+ * reading data                                                      *
+ *********************************************************************/
+
+/*
+ * These functions are used to poll the playback enginge and actually get data 
+ * off the DVD.
  */
 
-/**
- * \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.
+ * pointed to by 'event' gets set accordingly.
  *
  * If 'event' is DVDNAV_BLOCK_OK then 'buf' is filled with the next block
  * (note that means it has to be at /least/ 2048 bytes big). 'len' is
@@ -220,312 +196,210 @@
  * Otherwise, buf is filled with an appropriate event structure and
  * 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.
+ * See the dvdnav_events.h header for information on the various events.
  */
 dvdnav_status_t dvdnav_get_next_block(dvdnav_t *self, unsigned char *buf,
 				      int *event, int *len);
 
-/**
+/*
  * This basically does the same as dvdnav_get_next_block. The only difference is
  * that it avoids a memcopy, when the requested block was found in the cache.
  * I such a case (cache hit) this function will return a different pointer than
  * the one handed in, pointing directly into the relevant block in the cache.
- * Those pointer must _never_ be freed but instead returned to the library via
+ * Those pointers must _never_ be freed but instead returned to the library via
  * dvdnav_free_cache_block().
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param buf Buffer (at least 2048 octets) to fill with next block/event structure.
- *            A different buffer might be returned, if the block was found in the internal cache.
- * \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_cache_block(dvdnav_t *self, unsigned char **buf,
 					    int *event, int *len);
 
-/**
+/*
  * All buffers which came from the internal cache (when dvdnav_get_next_cache_block()
  * returned a buffer different from the one handed in) have to be freed with this
  * function. Although handing in other buffers not from the cache doesn't cause any harm.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param buf Buffer received from internal cache.
  */
 dvdnav_status_t dvdnav_free_cache_block(dvdnav_t *self, unsigned char *buf);
 
-/**
- * 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);
-
-/**
- * Get video scaling permissions.
+/*
+ * If we are currently in a still-frame this function skips it.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * 
- * \returns Video scaling permissions, bit0 - deny letterboxing, bit1 - deny pan&scan
- */
-uint8_t dvdnav_get_video_scale_permission(dvdnav_t *self);
-
-/**
- * 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, const char **title_str);
-
-/**
- * @}
- */
-
-/**
- * \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.
- * 
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param titles int to select title.
- * \param parts Pointer to int to receive number of parts.
- */
-dvdnav_status_t dvdnav_get_number_of_parts(dvdnav_t *self, int title, int *parts);
-
-/**
- * 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.
+ * See also the DVDNAV_STILL_FRAME event.
  */
 dvdnav_status_t dvdnav_still_skip(dvdnav_t *self);
 
-/**
+/*
  * If we are currently in WAIT state, that is: the application is required to
  * wait for its fifos to become empty, calling this signals libdvdnav that this
  * is achieved and that it can continue.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
+ * See also the DVDNAV_WAIT event.
  */
 dvdnav_status_t dvdnav_wait_skip(dvdnav_t *self);
 
-/**
- * Returns the still time status from the next cell
+/*
+ * Returns the still time from the currently playing cell.
+ * The still time is given in seconds with 0xff meaning an indefinite still.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
+ * This function can be used to detect still frames before they are reached.
+ * Some players might need this to prepare for a frame to be shown for a
+ * longer time than usual.
  */
 uint32_t dvdnav_get_next_still_flag(dvdnav_t *self);
 
-/**
- * Plays a specified title of the DVD.
+/*
+ * Stops playback. The next event obtained with one of the get_next_block
+ * functions will be a DVDNAV_STOP event.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param title 1..99 -- Title number to play.
+ * It is not required to call this before dvdnav_close().
+ */
+dvdnav_status_t dvdnav_stop(dvdnav_t *self);
+
+
+/*********************************************************************
+ * title/part navigation                                             *
+ *********************************************************************/
+
+/*
+ * Returns the number of titles on the disk.
+ */
+dvdnav_status_t dvdnav_get_number_of_titles(dvdnav_t *self, int *titles);
+
+/*
+ * Returns the number of parts within the given title.
+ */
+dvdnav_status_t dvdnav_get_number_of_parts(dvdnav_t *self, int title, int *parts);
+
+/*
+ * Plays the specified title of the DVD from its beginning (that is: part 1).
  */
 dvdnav_status_t dvdnav_title_play(dvdnav_t *self, int title);
 
-/**
- * Plays the specifiec title, starting from the specified part.
- *
- * \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.
+/*
+ * Plays the specified title, starting from the specified part.
  */
 dvdnav_status_t dvdnav_part_play(dvdnav_t *self, int title, int part);
 
-/**
+/*
  * Play the specified amount of parts of the specified title of
  * the DVD then STOP.
  *
- * \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);
 
-/**
- * Play the specified title starting from the specified time
+/*
+ * Play the specified title starting from the specified time.
  *
- * \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()).
- * 
- * \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 
- * (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);
-
-/**
+/*
  * Stop playing the current position and jump to the specified menu.
  *
- * \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>)
+ * See also DVDMenuID_t from libdvdread
  */
 dvdnav_status_t dvdnav_menu_call(dvdnav_t *self, DVDMenuID_t menu);
 
-/**
+/*
  * Return the title number and part 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);
-
-/**
- * @}
- */
+					  int *part);
 
-/** 
- * \defgroup search Searching
- *
- * @{
+/*
+ * Return the current position (in blocks) within the current
+ * title and the length (in blocks) of said title.
+ * 
+ * Current implementation is wrong and likely to behave unpredictably!
+ * Use is discouraged!
  */
+dvdnav_status_t dvdnav_get_position_in_title(dvdnav_t *self,
+					     unsigned int *pos,
+					     unsigned int *len);
 
-/**
- * Stop playing the current position and start playback of the title
- * from the specified timecode.
- *
- * \par Note:
- * Currently unimplemented!
+/*
+ * This function is only available for compatibility reasons.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param time Timecode to start from.
+ * Stop playing the current position and start playback of the current title
+ * from the specified part.
  */
-dvdnav_status_t dvdnav_time_search(dvdnav_t *self, 
-				   unsigned long int time);
+dvdnav_status_t dvdnav_part_search(dvdnav_t *self, int part);
+
 
-/**
+/*********************************************************************
+ * program chain/program navigation                                  *
+ *********************************************************************/
+
+/*
  * Stop playing the current position and start playback from the last
  * VOBU boundary before the given sector. The sector number is not
  * meant to be an absolute physical DVD sector, but a relative sector
  * in the current program. This function cannot leave the current
  * program and will fail, if asked to do so.
- * 
- * from the specified sector offset.
  *
- * \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.
+ * If program chain based positioning is enabled
+ * (see dvdnav_set_PGC_positioning_flag()), this will seek to the relative
+ * sector inside the current program chain.
+ *
+ * 'origin' can be one of SEEK_SET, SEEK_CUR, SEEK_END as defined in
+ * fcntl.h.
  */
 dvdnav_status_t dvdnav_sector_search(dvdnav_t *self, 
 				     unsigned long int offset, int origin);
 
-/**
- * Stop playing the current position and start playback of the current title
- * from the specified part (chapter).
+/*
+ * Stop playing the current position and start playback of the title
+ * from the specified timecode.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param part 1..999 -- Part to start from.
+ * Currently unimplemented!
  */
-dvdnav_status_t dvdnav_part_search(dvdnav_t *self, int part);
+dvdnav_status_t dvdnav_time_search(dvdnav_t *self, 
+				   unsigned long int time);
 
-/**
+/*
+ * Stop playing current position and play the "GoUp"-program chain.
+ * (which generally leads to the title menu or a higer-level menu).
+ */
+dvdnav_status_t dvdnav_go_up(dvdnav_t *self);
+
+/*
  * Stop playing the current position and start playback at 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 position and start playback at 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 position and start playback at 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);
 
-/**
+/*
  * Return the current position (in blocks) within the current
  * program and the length (in blocks) of current program.
- * 
- * \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 program.
+ *
+ * If program chain based positioning is enabled
+ * (see dvdnav_set_PGC_positioning_flag()), this will return the
+ * relative position in and the length of the current program chain.
  */
 dvdnav_status_t dvdnav_get_position(dvdnav_t *self, unsigned int *pos,
 				    unsigned int *len);
 
-/**
- * Return the current position (in blocks) within the current
- * title and the length (in blocks) of said title.
- * 
- * \par Note:
- * Current implementation is wrong and likely to behave unpredictably.
- * Use is discouraged.
- *
- * \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);
 
-/**
- * @}
- */
+/*********************************************************************
+ * menu highlights                                                   *
+ *********************************************************************/
 
-/**
- * \defgroup highlight Highlights
- *
+/*
  * Most functions related to highlights take a NAV PCI packet as a parameter.
  * While you can get the such a packet from libdvdnav, for players with internal
  * FIFOs, this will result in errors, because due to the FIFO length, libdvdnav will
@@ -533,407 +407,223 @@
  * Therefore, player applications who have a NAV packet available, which is
  * better in sync with the actual playback should always pass this one to these
  * functions.
- *
- * @{
  */
 
-/**
+/*
  * Get the currently highlighted button 
- * number (1..36) or 0 if no button is highlighed.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param button Pointer to the value to fill in.
+ * number (1..36) or 0 if no button is highlighted.
  */
-dvdnav_status_t dvdnav_get_current_highlight(dvdnav_t *self, int* button);
+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>)
+ * Read the general notes above.
+ * See also libdvdreads nav_types.h for definition of pci_t.
  */
 pci_t* dvdnav_get_current_nav_pci(dvdnav_t *self);
 
-/**
- * Returns the DSI (data seach information) structure associated
+/*
+ * Returns the DSI (data search information) structure associated
  * with the current position.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- *
- * \sa pci_t (in <tt>libdvdread</tt>)
+ * Read the general notes above.
+ * See also libdvdreads nav_types.h for definition of dsi_t.
  */
 dsi_t* dvdnav_get_current_nav_dsi(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);
+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 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, pci_t *pci);
-
-/**
- * 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, pci_t *pci);
-
-/**
- * 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, pci_t *pci);
-
-/**
- * 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, pci_t *pci);
 
-/**
- * Activate (press) the currently highlighted button.
- * \param self Pointer to dvdnav_t associated with this operation.
+/*
+ * Activate ("press") the currently highlighted button.
  */
 dvdnav_status_t dvdnav_button_activate(dvdnav_t *self, pci_t *pci);
 
-/**
+/*
  * Highlight a specific button.
- *
- * \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, pci_t *pci, int button);
 
-/**
- * Activate (press) specified button.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param button 1..39 -- Button number to activate.
+/*
+ * Activate ("press") specified button.
  */
 dvdnav_status_t dvdnav_button_select_and_activate(dvdnav_t *self, pci_t *pci, int button);
 
-/**
+/*
  * Activate (press) a button and execute specified command.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param cmd DVD Command to execute.
  */
 dvdnav_status_t dvdnav_button_activate_cmd(dvdnav_t *self, int32_t button, vm_cmd_t *cmd);
 
-/**
- * Select button at specified (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.
+/*
+ * Select button at specified video frame coordinates.
  */
 dvdnav_status_t dvdnav_mouse_select(dvdnav_t *self, pci_t *pci, 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.
+/*
+ * Activate ("press") button at specified video frame coordinates.
  */
 dvdnav_status_t dvdnav_mouse_activate(dvdnav_t *self, pci_t *pci, int x, int y);
 
-/**
- * @}
+
+/*********************************************************************
+ * languages                                                         *
+ *********************************************************************/
+
+/* 
+ * The language codes expected by these functions are two character
+ * codes as defined in ISO639.
  */
 
-/** 
- * \defgroup languages Languages
- *
- * @{
- */
-
-/**
+/*
  * Set which menu language we should use.
- *
- * \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_language_select(dvdnav_t *self,
 					   char *code);
 
-/**
+/*
  * Set which audio language we should use.
- *
- * \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_audio_language_select(dvdnav_t *self,
 					    char *code);
 
-/**
+/*
  * Set which spu language we should use.
- *
- * \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_spu_language_select(dvdnav_t *self,
 					  char *code);
 
-/**
- * @}
- */
 
-/** 
- * \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()
- * 
- * @{
- */
+/*********************************************************************
+ * obtaining stream attributes                                       *
+ *********************************************************************/
 
-/**
- * Set a specific PHYSICAL MPEG stream.
- *
- * \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);
-
-/**
- * Set a specific logical audio stream.
- *
- * \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);
-
-/**
- * Set the int pointed to to the current PHYSICAL audio
- * stream.
- *
- * \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);
-
-/**
- * Set the int pointed to to the current LOGICAL audio
- * stream.
- *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param audio Pointer to int which will receive value.
+/*
+ * Return a string describing the title of the DVD.
+ * This is an ID string encoded on the disc by the author. In many cases
+ * this is a descriptive string such as `THE_MATRIX' but sometimes is sigularly
+ * uninformative such as `PDVD-011421'. Some DVD authors even forget to set this,
+ * so you may also read the default of the authoring software they used, like
+ * `DVDVolume'.
  */
-dvdnav_status_t dvdnav_get_logical_audio_stream(dvdnav_t *self, int* audio);
+dvdnav_status_t dvdnav_get_title_string(dvdnav_t *self, const char **title_str);
 
-/**
- * Set a specific PHYSICAL MPEG SPU stream and whether it should be
- * displayed.
- *
- * \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?
+/*
+ * Get video aspect code.
+ * The aspect code does only change on VTS boundaries.
+ * See the DVDNAV_VTS_CHANGE event.
+ * 
+ * 0 -- 4:3, 2 -- 16:9
  */
-dvdnav_status_t dvdnav_physical_spu_stream_change(dvdnav_t *self,
-					  	  int stream, int display);
-
-/**
- * Set a specific LOGICAL SPU stream and whether it should be
- * displayed.
- *
- * \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);
+uint8_t dvdnav_get_video_aspect(dvdnav_t *self);
 
-/**
- * Set the ints pointed to to the current PHYSICAL SPU
- * stream & display flag.
+/*
+ * Get video scaling permissions.
+ * The scaling permission does only change on VTS boundaries.
+ * See the DVDNAV_VTS_CHANGE event.
  *
- * \param self Pointer to dvdnav_t associated with this operation.
- * \param stream Pointer which will receive value.
- * \param display Pointer which will receive value.
+ * bit0 set = deny letterboxing, bit1 set = deny pan&scan
  */
-dvdnav_status_t dvdnav_get_physical_spu_stream(dvdnav_t *self,
-					       int* stream, int* display);
+uint8_t dvdnav_get_video_scale_permission(dvdnav_t *self);
 
-/**
- * Set the ints pointed to to the current LOGICAL SPU
- * stream & display flag.
- *
- * \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);
-
-/**
- * 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
+/*
+ * Converts a *logical* audio stream id into language code
+ * (returns 0xffff if no such stream).
  */
 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
+ * (returns 0xffff if no such stream).
  */
 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
+/*
+ * Converts a *physical* (MPEG) audio stream id into a logical stream number.
  */
 int8_t dvdnav_get_audio_logical_stream(dvdnav_t *self, uint8_t audio_num);
 
-/**
- * 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
+/*
+ * Converts a *physical* (MPEG) subpicture stream id into a logical stream number.
  */
 int8_t dvdnav_get_spu_logical_stream(dvdnav_t *self, uint8_t subp_num);
 
-/**
+/*
  * Get active audio stream.
- * 
- * \param self Pointer to dvdnav_t associated with this operation.
  */
 int8_t dvdnav_get_active_audio_stream(dvdnav_t *self);
 
-/**
+/*
  * Get active spu stream.
- * 
- * \param self Pointer to dvdnav_t associated with this operation.
  */
 int8_t dvdnav_get_active_spu_stream(dvdnav_t *self);
 
-/**
- * @}
- */
+
+/*********************************************************************
+ * multiple angles                                                   *
+ *********************************************************************/
 
-/** 
- * \defgroup angles Multiple angles
+/*
+ * The libdvdnav 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. You will always see only the
+ * selected angle coming from the get_next_block functions.
  *
- * 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:
+ * 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.
- *
- * \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,
+dvdnav_status_t dvdnav_get_angle_info(dvdnav_t *self, int *current_angle,
 				      int *number_of_angles);
 
-/**
- * @}
- */
+/*********************************************************************
+ * domain queries                                                    *
+ *********************************************************************/
 
-/** 
- * \defgroup domain Domain Queries
- *
- * The following functions can be used to query whether we are in
- * particular domains or not.
- *
- * @{
- */
-
-/**
- * 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
+/*
+ * Are we in the First Play domain?
  */
 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
+/*
+ * Are we in the Video management Menu domain?
  */
 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
+/*
+ * Are we in the Video Title Menu domain?
  */
 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
+/*
+ * Are we in the Video Title Set domain?
  */
 int8_t dvdnav_is_domain_vts(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.
- */
 
 #ifdef __cplusplus
 }