[libbluray-devel] [Git][videolan/libbluray][master] 3 commits: Add brief documentation for undocumented public fields/defines/enums/functions
Petri Hintukainen (@hpi)
gitlab at videolan.org
Sat Oct 1 13:01:05 UTC 2022
Petri Hintukainen pushed to branch master at VideoLAN / libbluray
Commits:
048f10d7 by Petri Hintukainen at 2022-10-01T15:59:03+03:00
Add brief documentation for undocumented public fields/defines/enums/functions
- - - - -
1769bf55 by Petri Hintukainen at 2022-10-01T15:59:17+03:00
Fix missing options in help string
- - - - -
7356f5c6 by Petri Hintukainen at 2022-10-01T15:59:41+03:00
Cosmetics (remove trailing space)
- - - - -
6 changed files:
- src/devtools/clpi_dump.c
- src/devtools/mpls_dump.c
- src/libbluray/bluray.h
- src/libbluray/decoders/overlay.h
- src/libbluray/player_settings.h
- src/util/log_control.h
Changes:
=====================================
src/devtools/clpi_dump.c
=====================================
@@ -174,9 +174,9 @@ _show_seq_info(CLPI_SEQ_INFO *si, int level)
indent_printf(level+2, "ATC Sequence %d", jj);
indent_printf(level+3, "SPN STC Start: %u", stc->spn_stc_start);
indent_printf(level+3, "PCR PID: %04x", stc->pcr_pid);
- indent_printf(level+3, "Presentation Start: %u",
+ indent_printf(level+3, "Presentation Start: %u",
stc->presentation_start_time);
- indent_printf(level+3, "Presentation End: %u",
+ indent_printf(level+3, "Presentation End: %u",
stc->presentation_end_time);
}
}
@@ -193,7 +193,7 @@ _show_prog_info(CLPI_PROG_INFO *pi, int level)
for (ii = 0; ii < pi->num_prog; ii++) {
prog = &pi->progs[ii];
indent_printf(level+1, "Program %d", ii);
- indent_printf(level+2, "SPN Program Sequence Start: %d",
+ indent_printf(level+2, "SPN Program Sequence Start: %d",
prog->spn_program_sequence_start);
indent_printf(level+2, "Program Map PID: %d", prog->program_map_pid);
indent_printf(level+2, "Number Streams: %d", prog->num_streams);
@@ -243,7 +243,7 @@ _show_cpi_info(CLPI_CPI *cpi, int level)
indent_printf(level+2, "EP Stream Type: %d", entry->ep_stream_type);
indent_printf(level+2, "Number EP Coarse: %d", entry->num_ep_coarse);
indent_printf(level+2, "Number EP Fine: %d", entry->num_ep_fine);
- indent_printf(level+2, "EP Map Start: %d",
+ indent_printf(level+2, "EP Map Start: %d",
entry->ep_map_stream_start_addr);
for (jj = 0; jj < entry->num_ep_coarse; jj++) {
coarse = &entry->coarse[jj];
@@ -255,9 +255,9 @@ _show_cpi_info(CLPI_CPI *cpi, int level)
for (jj = 0; jj < entry->num_ep_fine; jj++) {
fine = &entry->fine[jj];
indent_printf(level+2, "Fine: %d", jj);
- indent_printf(level+3, "Angle Change Point: %s",
+ indent_printf(level+3, "Angle Change Point: %s",
fine->is_angle_change_point ? "True":"False");
- indent_printf(level+3, "I End Offset: %d",
+ indent_printf(level+3, "I End Offset: %d",
fine->i_end_position_offset);
indent_printf(level+3, "PTS EP: %d", fine->pts_ep);
indent_printf(level+3, "SPN EP: %d", fine->spn_ep);
@@ -295,8 +295,8 @@ _show_cpi_info(CLPI_CPI *cpi, int level)
static void
_usage(char *cmd)
{
- fprintf(stderr,
-"Usage: %s -vcspi <clpi file> [<clpi file> ...]\n"
+ fprintf(stderr,
+"Usage: %s [options] <clpi file> [<clpi file> ...]\n"
"With no options, produces no output (not very useful)\n"
"Options:\n"
" v - Verbose output.\n"
=====================================
src/devtools/mpls_dump.c
=====================================
@@ -301,7 +301,7 @@ _show_clip_list(MPLS_PL *pl, int level)
uint32_t duration;
duration = pi->out_time - pi->in_time;
- indent_printf(level, "%s.m2ts -- Duration: %3d:%02d",
+ indent_printf(level, "%s.m2ts -- Duration: %3d:%02d",
pi->clip[0].clip_id,
duration / (45000 * 60), (duration / 45000) % 60);
} else {
@@ -566,7 +566,7 @@ _process_file(char *name, MPLS_PL *pl_list[], int pl_count)
}
}
if (verbose) {
- indent_printf(0,
+ indent_printf(0,
"%s -- Num Clips: %3d , Duration: minutes %4u:%02u",
basename(name),
pl->list_count,
@@ -604,8 +604,8 @@ _process_file(char *name, MPLS_PL *pl_list[], int pl_count)
static void
_usage(char *cmd)
{
- fprintf(stderr,
-"Usage: %s -vli <mpls file> [<mpls file> ...]\n"
+ fprintf(stderr,
+"Usage: %s [options] <mpls file> [<mpls file> ...]\n"
"With no options, produces a list of the playlist(s) with durations\n"
"Options:\n"
" v - Verbose output.\n"
@@ -649,7 +649,7 @@ main(int argc, char *argv[])
do {
opt = getopt(argc, argv, OPTS);
switch (opt) {
- case -1:
+ case -1:
break;
case 'v':
=====================================
src/libbluray/bluray.h
=====================================
@@ -41,6 +41,7 @@ extern "C" {
(TITLES_FILTER_DUP_TITLE | TITLES_FILTER_DUP_CLIP) /**< remove duplicate
titles and clips */
+/** This structure is opaque. It represents a libbluray instance. */
typedef struct bluray BLURAY;
/*
@@ -48,12 +49,12 @@ typedef struct bluray BLURAY;
*/
/* AACS error codes */
-#define BD_AACS_CORRUPTED_DISC -1
-#define BD_AACS_NO_CONFIG -2
-#define BD_AACS_NO_PK -3
-#define BD_AACS_NO_CERT -4
-#define BD_AACS_CERT_REVOKED -5
-#define BD_AACS_MMC_FAILED -6
+#define BD_AACS_CORRUPTED_DISC -1 /**< Corrupt disc (missing/invalid files) */
+#define BD_AACS_NO_CONFIG -2 /**< AACS configuration file missing */
+#define BD_AACS_NO_PK -3 /**< No valid processing key found */
+#define BD_AACS_NO_CERT -4 /**< No valid certificate found */
+#define BD_AACS_CERT_REVOKED -5 /**< All certificates have been revoked */
+#define BD_AACS_MMC_FAILED -6 /**< MMC (disc drive interaction) failed */
/** HDMV / BD-J title information */
typedef struct {
@@ -68,28 +69,28 @@ typedef struct {
/** BluRay disc information */
typedef struct {
- uint8_t bluray_detected;
+ uint8_t bluray_detected; /**< 1 if BluRay disc was detected */
/* Disc ID */
const char *disc_name; /**< optional disc name in preferred language */
const char *udf_volume_id; /**< optional UDF volume identifier */
- uint8_t disc_id[20];
+ uint8_t disc_id[20]; /**< Disc ID */
- /* HDMV / BD-J titles */
+ /** HDMV / BD-J titles */
uint8_t no_menu_support; /**< 1 if this disc can't be played using on-disc menus */
- uint8_t first_play_supported;
- uint8_t top_menu_supported;
+ uint8_t first_play_supported; /**< 1 if First Play title is present on the disc and can be played */
+ uint8_t top_menu_supported; /**< 1 if Top Menu title is present on the disc and can be played */
- uint32_t num_titles;
+ uint32_t num_titles; /**< number of titles on the disc, not including "First Play" and "Top Menu" */
const BLURAY_TITLE *const *titles; /**< index is title number 1 ... N */
const BLURAY_TITLE *first_play; /**< titles[N+1]. NULL if not present on the disc. */
const BLURAY_TITLE *top_menu; /**< titles[0]. NULL if not present on the disc. */
- uint32_t num_hdmv_titles;
- uint32_t num_bdj_titles;
- uint32_t num_unsupported_titles;
+ uint32_t num_hdmv_titles; /**< number of HDMV titles */
+ uint32_t num_bdj_titles; /**< number of BD-J titles */
+ uint32_t num_unsupported_titles; /**< number of unsupported titles */
- /* BD-J info (valid only if disc uses BD-J) */
+ /** BD-J info (valid only if disc uses BD-J) */
uint8_t bdj_detected; /**< 1 if disc uses BD-J */
uint8_t bdj_supported; /**< (deprecated) */
uint8_t libjvm_detected; /**< 1 if usable Java VM was found */
@@ -101,9 +102,9 @@ typedef struct {
/* disc application info */
uint8_t video_format; /**< \ref bd_video_format_e */
uint8_t frame_rate; /**< \ref bd_video_rate_e */
- uint8_t content_exist_3D;
+ uint8_t content_exist_3D; /**< 1 if 3D content exists on the disc */
uint8_t initial_output_mode_preference; /**< 0 - 2D, 1 - 3D */
- uint8_t provider_data[32];
+ uint8_t provider_data[32]; /**< Content provider data */
/* AACS info (valid only if disc uses AACS) */
uint8_t aacs_detected; /**< 1 if disc is using AACS encoding */
@@ -162,17 +163,17 @@ typedef enum {
BLURAY_VIDEO_FORMAT_720P = 5, /**< SMPTE 296M */
BLURAY_VIDEO_FORMAT_1080P = 6, /**< SMPTE 274M */
BLURAY_VIDEO_FORMAT_576P = 7, /**< ITU-R BT.1358 */
- BLURAY_VIDEO_FORMAT_2160P = 8,
+ BLURAY_VIDEO_FORMAT_2160P = 8, /**< BT.2020 */
} bd_video_format_e;
/** Stream video frame rate */
typedef enum {
- BLURAY_VIDEO_RATE_24000_1001 = 1, /**< 23.976 */
- BLURAY_VIDEO_RATE_24 = 2,
- BLURAY_VIDEO_RATE_25 = 3,
- BLURAY_VIDEO_RATE_30000_1001 = 4, /**< 29.97 */
- BLURAY_VIDEO_RATE_50 = 6,
- BLURAY_VIDEO_RATE_60000_1001 = 7 /**< 59.94 */
+ BLURAY_VIDEO_RATE_24000_1001 = 1, /**< 23.976 Hz */
+ BLURAY_VIDEO_RATE_24 = 2, /**< 24 Hz */
+ BLURAY_VIDEO_RATE_25 = 3, /**< 25 Hz */
+ BLURAY_VIDEO_RATE_30000_1001 = 4, /**< 29.97 Hz */
+ BLURAY_VIDEO_RATE_50 = 6, /**< 50 Hz */
+ BLURAY_VIDEO_RATE_60000_1001 = 7 /**< 59.94 Hz */
} bd_video_rate_e;
/** Stream video aspect ratio */
@@ -213,9 +214,9 @@ typedef enum {
/** Clip still mode type */
typedef enum {
- BLURAY_STILL_NONE = 0x00,
- BLURAY_STILL_TIME = 0x01,
- BLURAY_STILL_INFINITE = 0x02,
+ BLURAY_STILL_NONE = 0x00, /**< No still (normal playback) */
+ BLURAY_STILL_TIME = 0x01, /**< Still playback for fixed time */
+ BLURAY_STILL_INFINITE = 0x02, /**< Infinite still */
} bd_still_mode_e;
/** Mark type */
@@ -233,86 +234,93 @@ typedef enum {
/** Clip substream information */
typedef struct bd_stream_info {
- uint8_t coding_type;
- uint8_t format;
- uint8_t rate;
- uint8_t char_code;
- uint8_t lang[4];
- uint16_t pid;
- uint8_t aspect;
- uint8_t subpath_id;
+ uint8_t coding_type; /**< Stream coding (\ref bd_stream_type_e) */
+ uint8_t format; /**< Stream format (\ref bd_video_format_e or \ref bd_audio_format_e) */
+ uint8_t rate; /**< Stream frame rate (\ref bd_audio_rate_e or \ref bd_video_rate_e) */
+ uint8_t char_code; /**< Text subtitle charachter code (\ref bd_char_code_e) */
+ uint8_t lang[4]; /**< Language code */
+ uint16_t pid; /**< mpeg-ts PID */
+ uint8_t aspect; /**< Stream video aspect ratio (\ref bd_video_aspect_e) */
+ uint8_t subpath_id; /**< Sub path identifier (= separate mpeg-ts mux / .m2ts file) */
} BLURAY_STREAM_INFO;
/** Clip information */
typedef struct bd_clip {
- uint32_t pkt_count;
- uint8_t still_mode;
- uint16_t still_time; /* seconds */
- uint8_t video_stream_count;
- uint8_t audio_stream_count;
- uint8_t pg_stream_count;
- uint8_t ig_stream_count;
- uint8_t sec_audio_stream_count;
- uint8_t sec_video_stream_count;
- BLURAY_STREAM_INFO *video_streams;
- BLURAY_STREAM_INFO *audio_streams;
- BLURAY_STREAM_INFO *pg_streams;
- BLURAY_STREAM_INFO *ig_streams;
- BLURAY_STREAM_INFO *sec_audio_streams;
- BLURAY_STREAM_INFO *sec_video_streams;
+ uint32_t pkt_count; /**< Number of mpeg-ts packets */
+ uint8_t still_mode; /**< Clip still mode (\ref bd_still_mode_e) */
+ uint16_t still_time; /**< Still time (seconds) if still_mode == BD_STILL_TIME */
+ uint8_t video_stream_count; /**< Number of video streams */
+ uint8_t audio_stream_count; /**< Number of audio streams */
+ uint8_t pg_stream_count; /**< Number of PG (Presentation Graphics) streams */
+ uint8_t ig_stream_count; /**< Number of IG (Interactive Graphics) streams */
+ uint8_t sec_audio_stream_count; /**< Number of secondary audio streams */
+ uint8_t sec_video_stream_count; /**< Number of secondary video streams */
+ BLURAY_STREAM_INFO *video_streams; /**< Video streams information */
+ BLURAY_STREAM_INFO *audio_streams; /**< Audio streams information */
+ BLURAY_STREAM_INFO *pg_streams; /**< PG (Presentation Graphics) streams information */
+ BLURAY_STREAM_INFO *ig_streams; /**< IG (Interactive Graphics) streams information */
+ BLURAY_STREAM_INFO *sec_audio_streams; /**< Secondary audio streams information */
+ BLURAY_STREAM_INFO *sec_video_streams; /**< Secondary video streams information */
uint64_t start_time; /**< start media time, 90kHz, ("playlist time") */
uint64_t in_time; /**< start timestamp, 90kHz */
uint64_t out_time; /**< end timestamp, 90kHz */
- char clip_id[6];
+ char clip_id[6]; /**< Clip identifier (.m2ts file name) */
} BLURAY_CLIP_INFO;
/** Chapter entry */
typedef struct bd_chapter {
- uint32_t idx;
+ uint32_t idx; /**< Chapter index (number - 1) */
uint64_t start; /**< start media time, 90kHz, ("playlist time") */
uint64_t duration; /**< duration */
uint64_t offset; /**< distance from title start, bytes */
- unsigned clip_ref;
+ unsigned clip_ref; /**< Clip reference (index to playlist clips list) */
} BLURAY_TITLE_CHAPTER;
/** Playmark information */
typedef struct bd_mark {
- uint32_t idx;
+ uint32_t idx; /**< Mark index (number - 1) */
int type; /**< \ref bd_mark_type_e */
uint64_t start; /**< mark media time, 90kHz, ("playlist time") */
uint64_t duration; /**< time to next mark */
uint64_t offset; /**< mark distance from title start, bytes */
- unsigned clip_ref;
+ unsigned clip_ref; /**< Clip reference (index to playlist clips list) */
} BLURAY_TITLE_MARK;
/** Playlist information */
typedef struct bd_title_info {
- uint32_t idx; /* filled only with bd_get_title_info() */
- uint32_t playlist;
- uint64_t duration;
- uint32_t clip_count;
- uint8_t angle_count;
- uint32_t chapter_count;
- uint32_t mark_count;
- BLURAY_CLIP_INFO *clips;
- BLURAY_TITLE_CHAPTER *chapters;
- BLURAY_TITLE_MARK *marks;
-
- uint8_t mvc_base_view_r_flag;
+ uint32_t idx; /**< Playlist index number (filled only with bd_get_title_info()) */
+ uint32_t playlist; /**< Playlist ID (mpls file name) */
+ uint64_t duration; /**< Playlist duration, 90 kHz */
+ uint32_t clip_count; /**< Number of clips */
+ uint8_t angle_count; /**< Number of angles */
+ uint32_t chapter_count; /**< Number of chapters */
+ uint32_t mark_count; /**< Number of playmarks */
+ BLURAY_CLIP_INFO *clips; /**< Clip information */
+ BLURAY_TITLE_CHAPTER *chapters; /**< Chapter information */
+ BLURAY_TITLE_MARK *marks; /**< Playmark information */
+
+ uint8_t mvc_base_view_r_flag; /**< MVC base view (0 - left, 1 - right) */
} BLURAY_TITLE_INFO;
/** Sound effect data */
typedef struct bd_sound_effect {
uint8_t num_channels; /**< 1 - mono, 2 - stereo */
- uint32_t num_frames;
- const int16_t *samples; /* 48000 Hz, 16 bit LPCM. interleaved if stereo */
+ uint32_t num_frames; /**< Number of audio frames */
+ const int16_t *samples; /**< 48000 Hz, 16 bit LPCM. Interleaved if stereo */
} BLURAY_SOUND_EFFECT;
/**
- * Get library version
+ * Get libbluray version
*
+ * Get the version of libbluray (runtime)
+ *
+ * See also bluray-version.h
+ *
+ * @param major where to store major version
+ * @param minor where to store minor version
+ * @param micro where to store micro version
*/
void bd_get_version(int *major, int *minor, int *micro);
@@ -606,14 +614,14 @@ void bd_seamless_angle_change(BLURAY *bd, unsigned angle);
* libbluray internal decoders or the stream is stored in a sub-path.
*
* @param bd BLURAY object
- * @param stream_type BLURAY_*_STREAM
+ * @param stream_type BLURAY_AUDIO_STREAM or BLURAY_PG_TEXTST_STREAM
* @param stream_id stream number (1..N)
* @param enable_flag set to 0 to disable streams of this type
*/
void bd_select_stream(BLURAY *bd, uint32_t stream_type, uint32_t stream_id, uint32_t enable_flag);
-#define BLURAY_AUDIO_STREAM 0
-#define BLURAY_PG_TEXTST_STREAM 1
+#define BLURAY_AUDIO_STREAM 0 /**< Select audio stream */
+#define BLURAY_PG_TEXTST_STREAM 1 /**< Select subtitle stream */
/*
@@ -723,6 +731,16 @@ typedef enum {
*/
int bd_set_player_setting(BLURAY *bd, uint32_t idx, uint32_t value);
+
+/**
+ *
+ * Update player setting (string)
+ *
+ * @param bd BLURAY object
+ * @param idx Player setting to update
+ * @param value New value for player setting
+ * @return 1 on success, 0 on error (invalid setting)
+ */
int bd_set_player_setting_str(BLURAY *bd, uint32_t idx, const char *value);
@@ -753,7 +771,7 @@ typedef enum {
BD_EVENT_PLAYITEM = 7, /**< current play item, 0...N-1 */
BD_EVENT_CHAPTER = 8, /**< current chapter, 1...N */
BD_EVENT_PLAYMARK = 9, /**< playmark reached */
- BD_EVENT_END_OF_TITLE = 10,
+ BD_EVENT_END_OF_TITLE = 10, /**< end of title reached */
/*
* stream selection
@@ -824,38 +842,38 @@ typedef enum {
/** Event */
typedef struct {
- uint32_t event; /* bd_event_e */
- uint32_t param;
+ uint32_t event; /**< Event type (\ref bd_event_e) */
+ uint32_t param; /**< Event data */
} BD_EVENT;
/* BD_EVENT_ERROR param values */
-#define BD_ERROR_HDMV 1
-#define BD_ERROR_BDJ 2
+#define BD_ERROR_HDMV 1 /**< HDMV VM failed to play the title */
+#define BD_ERROR_BDJ 2 /**< BD-J failed to play the title */
/* BD_EVENT_ENCRYPTED param vlues */
-#define BD_ERROR_AACS 3
-#define BD_ERROR_BDPLUS 4
+#define BD_ERROR_AACS 3 /**< AACS failed or not supported */
+#define BD_ERROR_BDPLUS 4 /**< BD+ failed or not supported */
/* BD_EVENT_TITLE special titles */
-#define BLURAY_TITLE_FIRST_PLAY 0xffff
-#define BLURAY_TITLE_TOP_MENU 0
+#define BLURAY_TITLE_FIRST_PLAY 0xffff /**< "First Play" title started */
+#define BLURAY_TITLE_TOP_MENU 0 /**< "Top Menu" title started */
/* BD_EVENT_KEY_INTEREST flags */
-#define BLURAY_KIT_PLAY 0x1
-#define BLURAY_KIT_STOP 0x2
-#define BLURAY_KIT_FFW 0x4
-#define BLURAY_KIT_REW 0x8
-#define BLURAY_KIT_TRACK_NEXT 0x10
-#define BLURAY_KIT_TRACK_PREV 0x20
-#define BLURAY_KIT_PAUSE 0x40
-#define BLURAY_KIT_STILL_OFF 0x80
-#define BLURAY_KIT_SEC_AUDIO 0x100
-#define BLURAY_KIT_SEC_VIDEO 0x200
-#define BLURAY_KIT_PG_TEXTST 0x400
+#define BLURAY_KIT_PLAY 0x1 /**< BD-J requests to handle "Play" UO */
+#define BLURAY_KIT_STOP 0x2 /**< BD-J requests to handle "Stop" UO */
+#define BLURAY_KIT_FFW 0x4 /**< BD-J requests to handle "Fast Forward" UO */
+#define BLURAY_KIT_REW 0x8 /**< BD-J requests to handle "Reverse" UO */
+#define BLURAY_KIT_TRACK_NEXT 0x10 /**< BD-J requests to handle "Next Track" UO */
+#define BLURAY_KIT_TRACK_PREV 0x20 /**< BD-J requests to handle "Prev Track" UO */
+#define BLURAY_KIT_PAUSE 0x40 /**< BD-J requests to handle "Pause" UO */
+#define BLURAY_KIT_STILL_OFF 0x80 /**< BD-J requests to handle "Still Off" UO */
+#define BLURAY_KIT_SEC_AUDIO 0x100 /**< BD-J requests to handle "Sec. Audio" UO */
+#define BLURAY_KIT_SEC_VIDEO 0x200 /**< BD-J requests to handle "Sec. Video" UO */
+#define BLURAY_KIT_PG_TEXTST 0x400 /**< BD-J requests to handle "Subtitle" UO */
/* BD_EVENT_UO_MASK flags */
-#define BLURAY_UO_MENU_CALL 0x1
-#define BLURAY_UO_TITLE_SEARCH 0x2
+#define BLURAY_UO_MENU_CALL 0x1 /**< "Menu Call" masked (not allowed) */
+#define BLURAY_UO_TITLE_SEARCH 0x2 /**< "Title Search" masked (not allowed) */
/**
*
@@ -867,6 +885,13 @@ typedef struct {
*/
int bd_get_event(BLURAY *bd, BD_EVENT *event);
+/**
+ *
+ * Get name of event
+ *
+ * @param event event type (\ref bd_event_e)
+ * @return 1 on success, 0 if no events
+ */
const char *bd_event_name(uint32_t /* bd_event_e */ event);
/*
@@ -876,8 +901,22 @@ const char *bd_event_name(uint32_t /* bd_event_e */ event);
struct bd_overlay_s; /* defined in overlay.h */
struct bd_argb_overlay_s; /* defined in overlay.h */
struct bd_argb_buffer_s; /* defined in overlay.h */
-typedef void (*bd_overlay_proc_f)(void *, const struct bd_overlay_s * const);
-typedef void (*bd_argb_overlay_proc_f)(void *, const struct bd_argb_overlay_s * const);
+
+/**
+ * YUV overlay handler function type
+ *
+ * @param handle opaque handle that was given to bd_register_overlay_proc()
+ * @param event \ref BD_OVERLAY event
+ */
+typedef void (*bd_overlay_proc_f)(void *handle, const struct bd_overlay_s * const event);
+
+/**
+ * ARGB overlay handler function type
+ *
+ * @param handle opaque handle that was given to bd_register_argb_overlay_proc()
+ * @param event \ref BD_ARGB_OVERLAY event
+ */
+typedef void (*bd_argb_overlay_proc_f)(void *handle, const struct bd_argb_overlay_s * const event);
/**
*
@@ -1033,8 +1072,8 @@ void bd_set_scr(BLURAY *bd, int64_t pts);
*/
int bd_set_rate(BLURAY *bd, uint32_t rate);
-#define BLURAY_RATE_PAUSED 0
-#define BLURAY_RATE_NORMAL 90000
+#define BLURAY_RATE_PAUSED 0 /**< Set playback rate to PAUSED */
+#define BLURAY_RATE_NORMAL 90000 /**< Set playback rate to NORMAL */
/**
*
@@ -1070,11 +1109,17 @@ int bd_mouse_select(BLURAY *bd, int64_t pts, uint16_t x, uint16_t y);
/*
* Testing and debugging
+ *
+ * Note: parsing functions can't be used with UDF images.
*/
/* access to internal information */
struct clpi_cl;
+struct mpls_pl;
+struct bdjo_data;
+struct mobj_objects;
+
/**
*
* Get copy of clip information for requested playitem.
@@ -1084,6 +1129,8 @@ struct clpi_cl;
* @return pointer to allocated CLPI_CL object on success, NULL on error
*/
struct clpi_cl *bd_get_clpi(BLURAY *bd, unsigned clip_ref);
+
+/** Testing/debugging: Parse clip information (CLPI) file */
struct clpi_cl *bd_read_clpi(const char *clpi_file);
/**
@@ -1095,22 +1142,27 @@ struct clpi_cl *bd_read_clpi(const char *clpi_file);
void bd_free_clpi(struct clpi_cl *cl);
-struct mpls_pl;
+/** Testing/debugging: Parse playlist (MPLS) file */
struct mpls_pl *bd_read_mpls(const char *mpls_file);
+/** Testing/debugging: Free parsed playlist */
void bd_free_mpls(struct mpls_pl *);
-struct mobj_objects;
+/** Testing/debugging: Parse movie objects (MOBJ) file */
struct mobj_objects *bd_read_mobj(const char *mobj_file);
+/** Testing/debugging: Free parsed movie objects */
void bd_free_mobj(struct mobj_objects *);
-struct bdjo_data;
+/** Testing/debugging: Parse BD-J object file (BDJO) */
struct bdjo_data *bd_read_bdjo(const char *bdjo_file);
+/** Testing/debugging: Free parsed BDJO object */
void bd_free_bdjo(struct bdjo_data *);
/* BD-J testing */
-int bd_start_bdj(BLURAY *bd, const char* start_object); // start BD-J from the specified BD-J object (should be a 5 character string)
-void bd_stop_bdj(BLURAY *bd); // shutdown BD-J and clean up resources
+/** Testing/debugging: start BD-J from the specified BD-J object (should be a 5 character string) */
+int bd_start_bdj(BLURAY *bd, const char* start_object);
+/** Testing/debugging: shutdown BD-J and clean up resources */
+void bd_stop_bdj(BLURAY *bd);
/**
*
=====================================
src/libbluray/decoders/overlay.h
=====================================
@@ -31,6 +31,7 @@ extern "C" {
#include <stdint.h>
+/** Version number of the interface described in this file. */
#define BD_OVERLAY_INTERFACE_VERSION 2
/**
@@ -57,8 +58,8 @@ typedef enum {
* should not be flushed to display before next FLUSH event
*/
BD_OVERLAY_CLEAR = 2, /**< Clear overlay plane */
- BD_OVERLAY_DRAW = 3, /**< Draw bitmap (x, y, w, h, img, palette, crop) */
- BD_OVERLAY_WIPE = 4, /**< Clear area (x, y, w, h) */
+ BD_OVERLAY_DRAW = 3, /**< Draw bitmap. Size and position within plane (x, y, w, h) and image (img, palette). */
+ BD_OVERLAY_WIPE = 4, /**< Clear area. Size and position within plane (x, y, w, h). */
BD_OVERLAY_HIDE = 5, /**< Overlay is empty and can be hidden */
BD_OVERLAY_FLUSH = 6, /**< All changes have been done, flush overlay to display at given pts */
@@ -67,39 +68,44 @@ typedef enum {
/**
* Overlay palette entry
+ *
+ * Y, Cr and Cb have the same color matrix as the associated video stream.
+ *
+ * Entry 0xff is always transparent.
+ *
*/
typedef struct bd_pg_palette_entry_s {
- uint8_t Y;
- uint8_t Cr;
- uint8_t Cb;
- uint8_t T;
+ uint8_t Y; /**< Y component (16...235) */
+ uint8_t Cr; /**< Cr component (16...240) */
+ uint8_t Cb; /**< Cb component (16...240) */
+ uint8_t T; /**< Transparency ( 0...255). 0 - transparent, 255 - opaque. */
} BD_PG_PALETTE_ENTRY;
/**
* RLE element
*/
typedef struct bd_pg_rle_elem_s {
- uint16_t len;
- uint16_t color;
+ uint16_t len; /**< RLE run length */
+ uint16_t color; /**< palette index */
} BD_PG_RLE_ELEM;
/**
* YUV overlay event
*/
typedef struct bd_overlay_s {
- int64_t pts;
+ int64_t pts; /**< Timestamp, on video grid */
uint8_t plane; /**< Overlay plane (\ref bd_overlay_plane_e) */
uint8_t cmd; /**< Overlay event type (\ref bd_overlay_cmd_e) */
uint8_t palette_update_flag; /**< Set if only overlay palette is changed */
- uint16_t x;
- uint16_t y;
- uint16_t w;
- uint16_t h;
+ uint16_t x; /**< top-left x coordinate */
+ uint16_t y; /**< top-left y coordinate */
+ uint16_t w; /**< region width */
+ uint16_t h; /**< region height */
- const BD_PG_PALETTE_ENTRY * palette;
- const BD_PG_RLE_ELEM * img;
+ const BD_PG_PALETTE_ENTRY * palette; /**< overlay palette (256 entries) */
+ const BD_PG_RLE_ELEM * img; /**< RLE-compressed overlay image */
} BD_OVERLAY;
@@ -108,8 +114,8 @@ typedef struct bd_overlay_s {
it needs to use bd_refcnt_inc() and bd_refcnt_dec().
*/
-const void *bd_refcnt_inc(const void *); /* return object or NULL on invalid object */
-void bd_refcnt_dec(const void *);
+const void *bd_refcnt_inc(const void *); /**< Hold reference-counted object. Return object or NULL on invalid object. */
+void bd_refcnt_dec(const void *); /**< Release reference-counted object */
#if 0
BD_OVERLAY *bd_overlay_copy(const BD_OVERLAY *src)
@@ -158,7 +164,7 @@ typedef enum {
* ARGB overlay event
*/
typedef struct bd_argb_overlay_s {
- int64_t pts;
+ int64_t pts; /**< Event timestamp, on video grid */
uint8_t plane; /**< Overlay plane (\ref bd_overlay_plane_e) */
uint8_t cmd; /**< Overlay event type (\ref bd_argb_overlay_cmd_e) */
@@ -167,10 +173,10 @@ typedef struct bd_argb_overlay_s {
*/
/* destination clip on the overlay plane */
- uint16_t x;
- uint16_t y;
- uint16_t w;
- uint16_t h;
+ uint16_t x; /**< top-left x coordinate */
+ uint16_t y; /**< top-left y coordinate */
+ uint16_t w; /**< region width */
+ uint16_t h; /**< region height */
uint16_t stride; /**< ARGB buffer stride */
const uint32_t * argb; /**< ARGB image data, 'h' lines, line stride 'stride' pixels */
@@ -191,8 +197,8 @@ typedef struct bd_argb_buffer_s {
* - Set by application
* - Called when buffer is accessed or modified
*/
- void (*lock) (struct bd_argb_buffer_s *);
- void (*unlock)(struct bd_argb_buffer_s *);
+ void (*lock) (struct bd_argb_buffer_s *); /**< Lock (or prepare) buffer for writing */
+ void (*unlock)(struct bd_argb_buffer_s *); /**< Unlock buffer (write complete) */
/* ARGB frame buffers
* - Allocated by application (BD_ARGB_OVERLAY_INIT).
@@ -207,15 +213,18 @@ typedef struct bd_argb_buffer_s {
* - If the buffer size is smaller than the size requested in BD_ARGB_OVERLAY_INIT,
* the buffer points only to the dirty area.
*/
- int width;
- int height;
+ int width; /**< overlay buffer width (pixels) */
+ int height; /**< overlay buffer height (pixels) */
/** Dirty area of frame buffers
* - Updated by library before lock() call.
* - Reset after each BD_ARGB_OVERLAY_FLUSH.
*/
struct {
- uint16_t x0, y0, x1, y1;
+ uint16_t x0; /**< top-left x coordinate */
+ uint16_t y0; /**< top-left y coordinate */
+ uint16_t x1; /**< bottom-down x coordinate */
+ uint16_t y1; /**< bottom-down y coordinate */
} dirty[2]; /**< [0] - PG plane, [1] - IG plane */
} BD_ARGB_BUFFER;
=====================================
src/libbluray/player_settings.h
=====================================
@@ -33,45 +33,49 @@
enum {
- /* LPCM */
+ /* LPCM capability */
/* 48/96kHz (mandatory) */
- BLURAY_ACAP_LPCM_48_96_STEREO_ONLY = 0x0001, /**< LPCM 48kHz and 96kHz stereo */
- BLURAY_ACAP_LPCM_48_96_SURROUND = 0x0002, /**< LPCM 48kHz and 96kHz surround */
+ BLURAY_ACAP_LPCM_48_96_STEREO_ONLY = 0x0001, /**< LPCM 48kHz and 96kHz stereo capable */
+ BLURAY_ACAP_LPCM_48_96_SURROUND = 0x0002, /**< LPCM 48kHz and 96kHz surround capable */
/* 192kHz (optional) */
- BLURAY_ACAP_LPCM_192_STEREO_ONLY = 0x0004, /**< LPCM 192kHz stereo */
- BLURAY_ACAP_LPCM_192_SURROUND = 0x0008, /**< LPCM 192kHz surround */
+ BLURAY_ACAP_LPCM_192_NONE = 0x0000, /**< LPCM 192kHz not supported */
+ BLURAY_ACAP_LPCM_192_STEREO_ONLY = 0x0004, /**< LPCM 192kHz stereo capable */
+ BLURAY_ACAP_LPCM_192_SURROUND = 0x0008, /**< LPCM 192kHz surround capable */
- /* Dolby Digital Plus */
+ /* Dolby Digital Plus capability */
/* independent substream (mandatory) */
- BLURAY_ACAP_DDPLUS_STEREO_ONLY = 0x0010,
- BLURAY_ACAP_DDPLUS_SURROUND = 0x0020,
+ BLURAY_ACAP_DDPLUS_STEREO_ONLY = 0x0010, /**< DD Plus independent substream stereo capable */
+ BLURAY_ACAP_DDPLUS_SURROUND = 0x0020, /**< DD Plus independent substream surround capable */
/* dependent substream (optional) */
- BLURAY_ACAP_DDPLUS_DEP_STEREO_ONLY = 0x0040,
- BLURAY_ACAP_DDPLUS_DEP_SURROUND = 0x0080,
+ BLURAY_ACAP_DDPLUS_DEP_NONE = 0x0000, /**< DD Plus dependent substream not supported */
+ BLURAY_ACAP_DDPLUS_DEP_STEREO_ONLY = 0x0040, /**< DD Plus dependent substream stereo capable */
+ BLURAY_ACAP_DDPLUS_DEP_SURROUND = 0x0080, /**< DD Plus dependent substream surround capable */
/* DTS-HD */
/* Core substream (mandatory) */
- BLURAY_ACAP_DTSHD_CORE_STEREO_ONLY = 0x0100,
- BLURAY_ACAP_DTSHD_CORE_SURROUND = 0x0200,
+ BLURAY_ACAP_DTSHD_CORE_STEREO_ONLY = 0x0100, /**< DTS-HD Core stereo capable */
+ BLURAY_ACAP_DTSHD_CORE_SURROUND = 0x0200, /**< DTS-HD Core surround capable */
/* Extension substream (optional) */
- BLURAY_ACAP_DTSHD_EXT_STEREO_ONLY = 0x0400,
- BLURAY_ACAP_DTSHD_EXT_SURROUND = 0x0800,
+ BLURAY_ACAP_DTSHD_EXT_NONE = 0x0000, /**< DTS-HD extension substream not supported */
+ BLURAY_ACAP_DTSHD_EXT_STEREO_ONLY = 0x0400, /**< DTS-HD extension substream stereo capable */
+ BLURAY_ACAP_DTSHD_EXT_SURROUND = 0x0800, /**< DTS-HD extension substream surround capable */
/* Dolby lossless (TrueHD) */
/* Dolby Digital (mandatory) */
- BLURAY_ACAP_DD_STEREO_ONLY = 0x1000,
- BLURAY_ACAP_DD_SURROUND = 0x2000,
+ BLURAY_ACAP_DD_STEREO_ONLY = 0x1000, /**< Dolby Digital audio stereo capable */
+ BLURAY_ACAP_DD_SURROUND = 0x2000, /**< Dolby Digital audio surround capable */
/* MLP (optional) */
- BLURAY_ACAP_MLP_STEREO_ONLY = 0x4000,
- BLURAY_ACAP_MLP_SURROUND = 0x8000,
+ BLURAY_ACAP_MLP_NONE = 0x0000, /**< MLP not supported */
+ BLURAY_ACAP_MLP_STEREO_ONLY = 0x4000, /**< MLP stereo capable */
+ BLURAY_ACAP_MLP_SURROUND = 0x8000, /**< MLP surround capable */
};
@@ -80,18 +84,16 @@ enum {
*
* Player region code (integer)
*
- * Region A: the Americas, East and Southeast Asia, U.S. territories, and Bermuda.
- *
- * Region B: Africa, Europe, Oceania, the Middle East, the Kingdom of the Netherlands,
- * British overseas territories, French territories, and Greenland.
- *
- * Region C: Central and South Asia, Mongolia, Russia, and the People's Republic of China.
- *
*/
enum {
+ /** Region A: the Americas, East and Southeast Asia, U.S. territories, and Bermuda. */
BLURAY_REGION_A = 1,
+
+ /** Region B: Africa, Europe, Oceania, the Middle East, the Kingdom of the Netherlands,
+ * British overseas territories, French territories, and Greenland. */
BLURAY_REGION_B = 2,
+ /** Region C: Central and South Asia, Mongolia, Russia, and the People's Republic of China. */
BLURAY_REGION_C = 4,
};
@@ -103,8 +105,8 @@ enum {
*/
enum {
- BLURAY_OUTPUT_PREFER_2D = 0,
- BLURAY_OUTPUT_PREFER_3D = 1,
+ BLURAY_OUTPUT_PREFER_2D = 0, /**< 2D output preferred */
+ BLURAY_OUTPUT_PREFER_3D = 1, /**< 3D output preferred */
};
@@ -117,12 +119,12 @@ enum {
#define BLURAY_DCAP_1080p_720p_3D 0x01 /**< capable of 1920x1080 23.976Hz and 1280x720 59.94Hz 3D */
#define BLURAY_DCAP_720p_50Hz_3D 0x02 /**< capable of 1280x720 50Hz 3D */
#define BLURAY_DCAP_NO_3D_CLASSES_REQUIRED 0x04 /**< 3D glasses are not required */
-#define BLURAY_DCAP_INTERLACED_3D 0x08 /* */
-
-/* horizintal display size in centimeters */
-#define BLURAY_DCAP_DISPLAY_SIZE_UNDEFINED 0
-#define BLURAY_DCAP_DISPLAY_SIZE(cm) (((cm) > 0xfff ? 0xfff : (cm)) << 8)
+#define BLURAY_DCAP_INTERLACED_3D 0x08 /**< capable of interlaced 3D */
+/* horizontal display size in centimeters */
+#define BLURAY_DCAP_DISPLAY_SIZE_UNDEFINED 0 /**< connected display physical size unknown/undefined */
+#define BLURAY_DCAP_DISPLAY_SIZE_MASK 0xfff00 /**< display size mask */
+#define BLURAY_DCAP_DISPLAY_SIZE(cm) (((cm) > 0xfff ? 0xfff : (cm)) << 8) /**< connected display physical size (cm) */
/**
* BLURAY_PLAYER_SETTING_VIDEO_CAP (PSR29)
@@ -155,8 +157,11 @@ enum {
BLURAY_PLAYER_PROFILE_6_v3_1 = ((0x00 << 16) | (0x0310)), /**< Profile 6, version 3.1 (UHD) */
};
-#define BLURAY_PLAYER_PROFILE_3D_FLAG 0x100000
-#define BLURAY_PLAYER_PROFILE_VERSION_MASK 0xffff
+/* Player profile flags and version mask */
+
+#define BLURAY_PLAYER_PROFILE_3D_FLAG 0x100000 /**< set for 3D profiles */
+#define BLURAY_PLAYER_PROFILE_VERSION_MASK 0xffff /**< bit mask for player version */
+//!@}
/**
* BLURAY_PLAYER_SETTING_DECODE_PG
=====================================
src/util/log_control.h
=====================================
@@ -42,8 +42,8 @@ extern "C" {
/**
* Flags for log filtering.
*/
-enum debug_mask_enum {
- DBG_RESERVED = 0x00001,
+typedef enum debug_mask_enum {
+ DBG_RESERVED = 0x00001, /* (reserved) */
DBG_CONFIGFILE = 0x00002, /* (reserved for libaacs) */
DBG_FILE = 0x00004, /* (reserved for libaacs) */
DBG_AACS = 0x00008, /* (reserved for libaacs) */
@@ -61,11 +61,14 @@ enum debug_mask_enum {
DBG_GC = 0x08000, /**< graphics controller trace */
DBG_DECODE = 0x10000, /**< PG / IG decoders, m2ts demuxer */
DBG_JNI = 0x20000, /**< JNI calls */
-};
+} debug_mask_t;
-typedef enum debug_mask_enum debug_mask_t;
-
-typedef void (*BD_LOG_FUNC)(const char *);
+/**
+ * Log a message
+ *
+ * @param msg Log message as null-terminated string
+ */
+typedef void (*BD_LOG_FUNC)(const char *msg);
/**
* Set (global) debug handler
View it on GitLab: https://code.videolan.org/videolan/libbluray/-/compare/257d5c09762b18a96a86d360a8e0ad916958dd7b...7356f5c6c8d73ac7e912a55993e50c4ec0ecba61
--
View it on GitLab: https://code.videolan.org/videolan/libbluray/-/compare/257d5c09762b18a96a86d360a8e0ad916958dd7b...7356f5c6c8d73ac7e912a55993e50c4ec0ecba61
You're receiving this email because of your account on code.videolan.org.
VideoLAN code repository instance
More information about the libbluray-devel
mailing list