Remove libvlc_free

[vlc] / include / vlc / libvlc_media_player.h

diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index b812a5f8b1a622c6089256fdd685197578014b2c..eaaa358279c0bd04eaeb141d791b1158350a8ab8 100644 (file)
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -545,7 +545,7 @@ void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
  * handled. This is needed for DVD menus to work, as well as a few video
  * filters such as "puzzle".
  *
- * \note See also \func libvlc_video_set_key_input().
+ * \note See also libvlc_video_set_key_input().
  *
  * \warning This function is only implemented for X11 at the moment.
  *
@@ -588,6 +588,32 @@ int libvlc_video_get_height( libvlc_media_player_t *p_mi );
 VLC_DEPRECATED_API
 int libvlc_video_get_width( libvlc_media_player_t *p_mi );
 
+/**
+ * Get the mouse pointer coordinates over a video.
+ * Coordinates are expressed in terms of the decoded video resolution,
+ * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
+ * you can query your windowing system directly).
+ *
+ * Either of the coordinates may be negative or larger than the corresponding
+ * dimension of the video, if the cursor is outside the rendering area.
+ *
+ * @warning The coordinates may be out-of-date if the pointer is not located
+ * on the video rendering area. LibVLC does not track the pointer if it is
+ * outside of the video widget.
+ *
+ * @note LibVLC does not support multiple pointers (it does of course support
+ * multiple input devices sharing the same pointer) at the moment.
+ *
+ * \param p_mi media player
+ * \param num number of the video (starting from, and most commonly 0)
+ * \param px pointer to get the abscissa [OUT]
+ * \param py pointer to get the ordinate [OUT]
+ * \return 0 on success, -1 if the specified video does not exist
+ */
+VLC_PUBLIC_API
+int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
+                             int *px, int *py );
+
 /**
  * Get the current video scaling factor.
  * See also libvlc_video_set_scale().
@@ -616,7 +642,7 @@ VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f
  *
  * \param p_mi the media player
  * \return the video aspect ratio or NULL if unspecified
- * (the result must be released with free() or libvlc_free()).
+ * (the result must be released with free()).
  */
 VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );