X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_player.h;h=88b858e440985ea9230bd070720a5c02b9b9a074;hb=dd1e8bad853c63c7df40ba28ae62137fc8e5001a;hp=70bebdc3e94fb6cb79d18d92f1205cf4d9b33163;hpb=d34728306e774ee27a195155d55979aaace3b6eb;p=vlc diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 70bebdc3e9..88b858e440 100644 --- a/include/vlc/libvlc_media_player.h +++ b/include/vlc/libvlc_media_player.h @@ -1,7 +1,7 @@ /***************************************************************************** * libvlc_media_player.h: libvlc_media_player external API ***************************************************************************** - * Copyright (C) 1998-2009 the VideoLAN team + * Copyright (C) 1998-2010 the VideoLAN team * $Id$ * * Authors: Clément Stenac @@ -221,7 +221,6 @@ VLC_PUBLIC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t * * * \param p_mi the Media Player * \param drawable the agl handler - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable ); @@ -444,11 +443,12 @@ VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t * ); /** end bug */ /** - * Does this media player have a video output? + * How many video outputs does this media player have? * * \param p_md the media player + * \return the number of video outputs */ -VLC_PUBLIC_API int libvlc_media_player_has_vout( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t * ); /** * Is this media player seekable? @@ -488,18 +488,17 @@ VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t */ /** - * Toggle fullscreen status on a non-embedded video output. + * Toggle fullscreen status on non-embedded video outputs. * * @warning The same limitations applies to this function * as to libvlc_set_fullscreen(). * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t * ); /** - * Enable or disable fullscreen on a non-embedded video output. + * Enable or disable fullscreen on non-embedded video outputs. * * @warning With most window managers, only a top-level windows can switch to * full-screen mode. Hence, this function will not operate properly if @@ -511,18 +510,16 @@ VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *, libvlc_ex * * \param p_mediaplayer the media player * \param b_fullscreen boolean for fullscreen status - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int ); /** * Get current fullscreen status. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer * \return the fullscreen status (boolean) */ -VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t * ); /** * Enable or disable key press events handling, according to the LibVLC hotkeys @@ -557,35 +554,48 @@ void libvlc_video_set_key_input( libvlc_media_player_t *mp, unsigned on ); VLC_PUBLIC_API void libvlc_video_set_mouse_input( libvlc_media_player_t *mp, unsigned on ); +/** + * Get the pixel dimensions of a video. + * + * \param mp media player + * \param num number of the video (starting from, and most commonly 0) + * \param px pointer to get the pixel width [OUT] + * \param py pointer to get the pixel height [OUT] + * \return 0 on success, -1 if the specified video does not exist + */ +VLC_PUBLIC_API +int libvlc_video_get_size( libvlc_media_player_t *mp, unsigned num, + unsigned *px, unsigned *py ); + /** * Get current video height. + * You should use libvlc_video_get_size() instead. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer - * \return the video height + * \return the video pixel height or 0 if not applicable */ -VLC_PUBLIC_API int libvlc_video_get_height( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_DEPRECATED_API +int libvlc_video_get_height( libvlc_media_player_t * ); /** * Get current video width. + * You should use libvlc_video_get_size() instead. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer - * \return the video width + * \return the video pixel width or 0 if not applicable */ -VLC_PUBLIC_API int libvlc_video_get_width( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_DEPRECATED_API +int libvlc_video_get_width( libvlc_media_player_t * ); /** * Get the current video scaling factor. * See also libvlc_video_set_scale(). * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer * \return the currently configured zoom factor, or 0. if the video is set * to fit to the output window/drawable automatically. */ -VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t *, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t * ); /** * Set the video scaling factor. That is the ratio of the number of pixels on @@ -597,122 +607,128 @@ VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t *, * * \param p_mediaplayer the media player * \param i_factor the scaling factor, or zero - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *, float, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *, float ); /** * Get current video aspect ratio. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer - * \return the video aspect ratio + * \return the video aspect ratio or NULL if unspecified + * (the result must be released with free() or libvlc_free()). */ -VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t * ); /** * Set new video aspect ratio. * * \param p_mediaplayer the media player - * \param psz_aspect new video aspect-ratio - * \param p_e an initialized exception pointer + * \param psz_aspect new video aspect-ratio or NULL to reset to default + * \note Invalid aspect ratios are ignored. */ -VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, const char *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, const char * ); /** * Get current video subtitle. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer - * \return the video subtitle selected + * \return the video subtitle selected, or -1 if none */ -VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t * ); /** * Get the number of available video subtitles. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer * \return the number of available video subtitles */ -VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t * ); /** * Get the description of available video subtitles. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer * \return list containing description of available video subtitles */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_spu_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_spu_description( libvlc_media_player_t * ); /** * Set new video subtitle. * * \param p_mediaplayer the media player * \param i_spu new video subtitle to select - * \param p_e an initialized exception pointer + * \return 0 on success, -1 if out of range */ -VLC_PUBLIC_API void libvlc_video_set_spu( libvlc_media_player_t *, int , libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_set_spu( libvlc_media_player_t *, unsigned ); /** * Set new video subtitle file. * * \param p_mediaplayer the media player * \param psz_subtitle new video subtitle file - * \param p_e an initialized exception pointer * \return the success status (boolean) */ -VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char * ); /** * Get the description of available titles. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer * \return list containing description of available titles */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_title_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_title_description( libvlc_media_player_t * ); /** * Get the description of available chapters for specific title. * * \param p_mediaplayer the media player * \param i_title selected title - * \param p_e an initialized exception pointer * \return list containing description of available chapter for title i_title */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_chapter_description( libvlc_media_player_t *, int, libvlc_exception_t * ); + libvlc_video_get_chapter_description( libvlc_media_player_t *, int ); /** * Get current crop filter geometry. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer - * \return the crop filter geometry + * \return the crop filter geometry or NULL if unset */ -VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t * ); /** * Set new crop filter geometry. * * \param p_mediaplayer the media player - * \param psz_geometry new crop filter geometry - * \param p_e an initialized exception pointer + * \param psz_geometry new crop filter geometry (NULL to unset) + */ +VLC_PUBLIC_API +void libvlc_video_set_crop_geometry( libvlc_media_player_t *, const char * ); + +/** + * Get current teletext page requested. + * + * \param p_mediaplayer the media player + * \return the current teletext page requested. + */ +VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_player_t * ); + +/** + * Set new teletext page to retrieve. + * + * \param p_mediaplayer the media player + * \param i_page teletex page number requested */ -VLC_PUBLIC_API void libvlc_video_set_crop_geometry( libvlc_media_player_t *, const char *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_player_t *, int ); /** * Toggle teletext transparent status on video output. * * \param p_mediaplayer the media player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t * ); /** * Get number of available video tracks. @@ -720,35 +736,34 @@ VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t *, libvlc_exce * \param p_mi media player * \return the number of available video tracks (int) */ -VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t * ); /** * Get the description of available video tracks. * * \param p_mi media player - * \param p_e an initialized exception * \return list with description of available video tracks, or NULL on error */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_track_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_track_description( libvlc_media_player_t * ); /** * Get current video track. * * \param p_mi media player - * \param p_e an initialized exception pointer - * \return the video track (int) + * \return the video track (int) or -1 if none */ -VLC_PUBLIC_API int libvlc_video_get_track( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_get_track( libvlc_media_player_t * ); /** * Set video track. * * \param p_mi media player * \param i_track the track (int) - * \param p_e an initialized exception pointer + * \return 0 on success, -1 if out of range */ -VLC_PUBLIC_API void libvlc_video_set_track( libvlc_media_player_t *, int, libvlc_exception_t * ); +VLC_PUBLIC_API +int libvlc_video_set_track( libvlc_media_player_t *, int ); /** * Take a snapshot of the current video window. @@ -757,44 +772,42 @@ VLC_PUBLIC_API void libvlc_video_set_track( libvlc_media_player_t *, int, libvlc * If i_width XOR i_height is 0, original aspect-ratio is preserved. * * \param p_mi media player instance + * \param num number of video output (typically 0 for the first/only one) * \param psz_filepath the path where to save the screenshot to * \param i_width the snapshot's width * \param i_height the snapshot's height - * \param p_e an initialized exception pointer + * \return 0 on success, -1 if the video was not found */ -VLC_PUBLIC_API void libvlc_video_take_snapshot( libvlc_media_player_t *, const char *,unsigned int, unsigned int, libvlc_exception_t * ); +VLC_PUBLIC_API +int libvlc_video_take_snapshot( libvlc_media_player_t *, unsigned num, + const char *,unsigned int, unsigned int ); /** * Enable or disable deinterlace filter * * \param p_mi libvlc media player - * \param b_enable boolean to enable or disable deinterlace filter - * \param psz_mode type of deinterlace filter to use - * \param p_e an initialized exception pointer + * \param psz_mode type of deinterlace filter, NULL to disable */ VLC_PUBLIC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *, - int , const char *, - libvlc_exception_t *); + const char * ); /** * Get an integer marquee option value * * \param p_mi libvlc media player * \param option marq option to get \see libvlc_video_marquee_int_option_t - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *, - unsigned, libvlc_exception_t * ); + unsigned ); /** * Get a string marquee option value * * \param p_mi libvlc media player * \param option marq option to get \see libvlc_video_marquee_string_option_t - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *, - unsigned, libvlc_exception_t * ); + unsigned ); /** * Enable, disable or set an integer marquee option @@ -805,10 +818,9 @@ VLC_PUBLIC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *, * \param p_mi libvlc media player * \param option marq option to set \see libvlc_video_marquee_int_option_t * \param i_val marq option value - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *, - unsigned, int, libvlc_exception_t * ); + unsigned, int ); /** * Set a marquee string option @@ -816,10 +828,9 @@ VLC_PUBLIC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *, * \param p_mi libvlc media player * \param option marq option to set \see libvlc_video_marquee_string_option_t * \param psz_text marq option value - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *, - unsigned, const char *, libvlc_exception_t * ); + unsigned, const char * ); /** option values for libvlc_video_{get,set}_logo_{int,string} */ enum libvlc_video_logo_option_t { @@ -838,36 +849,33 @@ enum libvlc_video_logo_option_t { * * \param p_mi libvlc media player instance * \param option logo option to get, values of libvlc_video_logo_option_t - * \param p_e an pointer to an initialized exception object */ VLC_PUBLIC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi, - unsigned option, libvlc_exception_t *p_e ); + unsigned option ); /** * Set logo option as integer. Options that take a different type value - * cause an invalid argument exception. + * are ignored. * Passing libvlc_logo_enable as option value has the side effect of * starting (arg !0) or stopping (arg 0) the logo filter. * * \param p_mi libvlc media player instance * \param option logo option to set, values of libvlc_video_logo_option_t * \param value logo option value - * \param p_e an pointer to an initialized exception object */ VLC_PUBLIC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi, - unsigned option, int value, libvlc_exception_t *p_e ); + unsigned option, int value ); /** * Set logo option as string. Options that take a different type value - * cause an invalid argument exception. + * are ignored. * * \param p_mi libvlc media player instance * \param option logo option to set, values of libvlc_video_logo_option_t * \param psz_value logo option value - * \param p_e an pointer to an initialized exception object */ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi, - unsigned option, const char *psz_value, libvlc_exception_t *p_e ); + unsigned option, const char *psz_value ); /** @} video */ @@ -928,12 +936,12 @@ VLC_PUBLIC_API void libvlc_audio_output_list_release( libvlc_audio_output_t * ); * Set the audio output. * Change will be applied after stop and play. * - * \param p_instance libvlc instance + * \param mp media player * \param psz_name name of audio output, * use psz_name of \see libvlc_audio_output_t * \return true if function succeded */ -VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_instance_t *, +VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_media_player_t *, const char * ); /** @@ -972,13 +980,13 @@ VLC_PUBLIC_API char * libvlc_audio_output_device_id( libvlc_instance_t *, int ); /** - * Set device for using + * Set audio output device. Changes are only effective after stop and play. * - * \param p_instance libvlc instance + * \param mp media player * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t * \param psz_device_id device */ -VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_instance_t *, +VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_media_player_t *, const char *, const char * ); @@ -986,124 +994,113 @@ VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_instance_t *, * Get current audio device type. Device type describes something like * character of output sound - stereo sound, 2.1, 5.1 etc * - * \param p_instance vlc instance - * \param p_e an initialized exception pointer + * \param mp media player * \return the audio devices type \see libvlc_audio_output_device_types_t */ VLC_PUBLIC_API int libvlc_audio_output_get_device_type( - libvlc_instance_t *, libvlc_exception_t * ); + libvlc_media_player_t * ); /** * Set current audio device type. * - * \param p_instance vlc instance + * \param mp vlc instance * \param device_type the audio device type, according to \see libvlc_audio_output_device_types_t - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_instance_t *, - int, - libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *, + int ); /** * Toggle mute status. * - * \param p_instance libvlc instance + * \param mp media player */ -VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_instance_t * ); +VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_media_player_t * ); /** * Get current mute status. * - * \param p_instance libvlc instance + * \param mp media player * \return the mute status (boolean) */ -VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_instance_t * ); +VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_media_player_t * ); /** * Set mute status. * - * \param p_instance libvlc instance + * \param mp media player * \param status If status is true then mute, otherwise unmute */ -VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_instance_t *, int ); +VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_media_player_t *, int ); /** * Get current audio level. * - * \param p_instance libvlc instance - * \param p_e an initialized exception pointer + * \param mp media player * \return the audio level (int) */ -VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_instance_t * ); +VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_media_player_t * ); /** * Set current audio level. * - * \param p_instance libvlc instance + * \param mp media player * \param i_volume the volume (int) - * \param p_e an initialized exception pointer + * \return 0 if the volume was set, -1 if it was out of range */ -VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_audio_set_volume( libvlc_media_player_t *, int ); /** * Get number of available audio tracks. * * \param p_mi media player - * \param p_e an initialized exception - * \return the number of available audio tracks (int) + * \return the number of available audio tracks (int), or -1 if unavailable */ -VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t * ); /** * Get the description of available audio tracks. * * \param p_mi media player - * \param p_e an initialized exception - * \return list with description of available audio tracks + * \return list with description of available audio tracks, or NULL */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_audio_get_track_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_audio_get_track_description( libvlc_media_player_t * ); /** * Get current audio track. * * \param p_mi media player - * \param p_e an initialized exception pointer - * \return the audio track (int) + * \return the audio track (int), or -1 if none. */ -VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t * ); /** * Set current audio track. * * \param p_mi media player * \param i_track the track (int) - * \param p_e an initialized exception pointer + * \return 0 on success, -1 on error */ -VLC_PUBLIC_API void libvlc_audio_set_track( libvlc_media_player_t *, int, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_set_track( libvlc_media_player_t *, int ); /** * Get current audio channel. * - * \param p_instance vlc instance - * \param p_e an initialized exception pointer + * \param mp media player * \return the audio channel \see libvlc_audio_output_channel_t */ -VLC_PUBLIC_API int - libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_media_player_t * ); /** * Set current audio channel. * - * \param p_instance vlc instance + * \param p_mi media player * \param channel the audio channel, \see libvlc_audio_output_channel_t - * \param p_e an initialized exception pointer + * \return 0 on success, -1 on error */ -VLC_PUBLIC_API void libvlc_audio_set_channel( libvlc_instance_t *, - int, - libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_set_channel( libvlc_media_player_t *, int ); /** @} audio */