[libbluray-devel] commit: Docomented some API functions (hpi1 )

[git at videolan.org]

libbluray | branch: master | hpi1 <hpi1 at anonymous.org> | Tue Dec  7 16:12:55 2010 +0200| [6e30aa9426f22e5afa8f288df228e43b8ee353f6] | committer: hpi1 

Docomented some API functions

> http://git.videolan.org/gitweb.cgi/libbluray.git/?a=commit;h=6e30aa9426f22e5afa8f288df228e43b8ee353f6
---

 src/libbluray/bluray.h |  104 ++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 97 insertions(+), 7 deletions(-)

diff --git a/src/libbluray/bluray.h b/src/libbluray/bluray.h
index a22886b..5d60bf6 100644
--- a/src/libbluray/bluray.h
+++ b/src/libbluray/bluray.h
@@ -397,6 +397,13 @@ typedef struct {
 
 } BLURAY_DISC_INFO;
 
+/**
+ *
+ *  Get information about current BluRay disc
+ *
+ * @param bd  BLURAY object
+ * @return pointer to BLURAY_DISC_INFO object, NULL on error
+ */
 const BLURAY_DISC_INFO *bd_get_disc_info(BLURAY*);
 
 /*
@@ -436,7 +443,7 @@ int bd_start_bdj(BLURAY *bd, const char* start_object); // start BD-J from the s
 void bd_stop_bdj(BLURAY *bd); // shutdown BD-J and clean up resources
 
 /*
- * navigaton mode
+ * events
  */
 
 typedef enum {
@@ -475,17 +482,100 @@ typedef struct {
     uint32_t   param;
 } BD_EVENT;
 
-struct bd_overlay_s;
-typedef void (*bd_overlay_proc_f)(void *, const struct bd_overlay_s * const);
+/**
+ *
+ *  Get event from libbluray event queue.
+ *
+ * @param bd  BLURAY object
+ * @param event next BD_EVENT from event queue
+ * @return 1 on success, 0 if no events
+ */
+int  bd_get_event(BLURAY *bd, BD_EVENT *event);
+
+/*
+ * navigaton mode
+ */
 
-int  bd_play(BLURAY *bd); /* start playing disc in navigation mode */
+/**
+ *
+ *  Start playing disc in navigation mode.
+ *
+ *  Playback is started from "First Play" title.
+ *
+ * @param bd  BLURAY object
+ * @return 1 on success, 0 if error
+ */
+int  bd_play(BLURAY *bd);
+
+/**
+ *
+ *  Read from currently playing title.
+ *
+ *  When playing disc in navigation mode this function must be used instead of bd_read().
+ *
+ * @param bd  BLURAY object
+ * @param buf buffer to read data into
+ * @param len size of data to be read
+ * @param event next BD_EVENT from event queue (BD_EVENT_NONE if no events)
+ * @return size of data read, -1 if error, 0 if event needs to be handled first, 0 if end of title was reached
+ */
 int  bd_read_ext(BLURAY *bd, unsigned char *buf, int len, BD_EVENT *event);
-int  bd_get_event(BLURAY *bd, BD_EVENT *event);
 
-int  bd_play_title(BLURAY *bd, unsigned title); /* play title (from disc index) */
-int  bd_menu_call(BLURAY *bd, int64_t pts);     /* open disc root menu */
+/**
+ *
+ *  Play a title (from disc index).
+ *
+ *  Title 0      = Top Menu
+ *  Title 0xffff = First Play title
+ *  Number of titles can be found from BLURAY_DISC_INFO.
+ *
+ * @param bd  BLURAY object
+ * @param title title number from disc index
+ * @return 1 on success, 0 if error
+ */
+int  bd_play_title(BLURAY *bd, unsigned title);
 
+/**
+ *
+ *  Open BluRay disc Top Menu.
+ *
+ *  Current pts is needed for resuming playback when menu is closed.
+ *
+ * @param bd  BLURAY object
+ * @param pts current playback position (1/90000s) or -1
+ * @return 1 on success, 0 if error
+ */
+int  bd_menu_call(BLURAY *bd, int64_t pts);
+
+/*
+ * User interaction and On-screen display controller
+ */
+
+struct bd_overlay_s; /* defined in overlay.h */
+typedef void (*bd_overlay_proc_f)(void *, const struct bd_overlay_s * const);
+
+/**
+ *
+ *  Register overlay graphics handler function.
+ *
+ * @param bd  BLURAY object
+ * @param handle application-specific handle that will be passed to handler function
+ * @param func handler function pointer
+ * @return 1 on success, 0 if error
+ */
 void bd_register_overlay_proc(BLURAY *bd, void *handle, bd_overlay_proc_f func);
+
+/**
+ *
+ *  Pass user input to graphics controller.
+ *  Keys are defined in libbluray/keys.h.
+ *  Current pts can be updated by using BD_VK_NONE key. This is required for animated menus.
+ *
+ * @param bd  BLURAY object
+ * @param pts current playback position (1/90000s) or -1
+ * @param key input key
+ * @return 1 on success, 0 if error
+ */
 void bd_user_input(BLURAY *bd, int64_t pts, uint32_t key);
 
 #endif /* BLURAY_H_ */