[ACR-1275] Add new function to set video roi area

- add video roi function
- add remark of _set_play_position function

Change-Id: I8152b3d42b337663857479e1ecad9846ea0e6af5

diff --git a/include/player.h b/include/player.h
index ccfb849..11a5b00 100644 (file)
--- a/include/player.h
+++ b/include/player.h
@@ -833,6 +833,7 @@ int player_pause(player_h player);
  * @remarks This function will trigger the seeking operation on player instance like in the case of player_set_play_position_nsec().
  *          Normally application needs to wait for player_seek_completed_cb() before calling setting position function again.
  *          Otherwise it will return #PLAYER_ERROR_SEEK_FAILED.
+ * @remarks Calling player_pause() or player_start() before player_seek_completed_cb() is invoked will cause #PLAYER_ERROR_INVALID_OPERATION to be returned.
  * @remarks Please note that if application is playing external media data via player_set_media_stream_info(),
  *          then consecutive calling of this function will always succeed and there is no need to wait for player_seek_completed_cb()
  *          before next calling of this function.(since_tizen 3.0)
@@ -867,6 +868,7 @@ int player_set_play_position(player_h player, int milliseconds, bool accurate, p
  * @remarks This function will trigger the seeking operation on player instance like in the case of player_set_play_position().
  *          Normally application needs to wait for player_seek_completed_cb() before calling setting position function again.
  *          Otherwise it will return #PLAYER_ERROR_SEEK_FAILED.
+ * @remarks Calling player_pause() or player_start() before player_seek_completed_cb() is invoked will cause #PLAYER_ERROR_INVALID_OPERATION to be returned.
  * @remarks Please note that if application is playing external media data via player_set_media_stream_info(),
  *          then consecutive calling of this function will always succeed and there is no need to wait for player_seek_completed_cb()
  *          before next calling of this function.
@@ -2367,6 +2369,73 @@ int player_set_replaygain_enabled(player_h player, bool enabled);
 int player_is_replaygain_enabled(player_h player, bool *enabled);
 
 /**
+ * @brief Sets the ROI (Region Of Interest) area of the content video source.
+ * @details This function is to set the ROI area of video content to render it
+ *          on #PLAYER_DISPLAY_TYPE_OVERLAY display with current display mode.
+ *          It can be regarded as zooming operation because the selected video area will be rendered fit to the display.
+ * @since_tizen 5.0
+ * @remarks This function requires the ratio value of the each coordinate and size based on the video resolution size
+ *          to consider the dynamic resolution video content.
+ * @remarks The ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
+ * @param[in] player     The handle to the media player
+ * @param[in] x_scale    X coordinate ratio value of the video source area based on the video width size \n
+ *                       Valid range is 0.0~1.0.
+ * @param[in] y_scale    Y coordinate ratio value of the video source area based on the video height size \n
+ *                       Valid range is 0.0~1.0.
+ * @param[in] w_scale    Width ratio value of the video source area based on the video width size \n
+ *                       Valid range is from greater than 0.0 to 1.0.
+ * @param[in] h_scale    Height ratio value of the video source area based on the video height size \n
+ *                       Valid range is from greater than 0.0 to 1.0.
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval  #PLAYER_ERROR_NONE Successful
+ * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @see #player_display_type_e
+ * @see player_set_display()
+ * @see player_set_display_mode()
+ * @see player_get_video_size()
+ * @see player_get_video_roi_area()
+ * @par Example
+   @code
+       #include <player.h>
+       ...
+       player_h player = NULL;
+       player_display_h display = NULL;
+       int width = 0, height = 0;
+       ...
+       player_set_display (player, PLAYER_DISPLAY_TYPE_OVERLAY, display);
+       player_get_video_size (player, &width, &height);
+       ...
+       player_set_video_roi_area (30/(double)width, 30/(double)height, 480/(double)width, 270/(double)height);
+       ...
+   @endcode
+ */
+int player_set_video_roi_area(player_h player, double x_scale, double y_scale, double w_scale, double h_scale);
+
+/**
+ * @brief Gets the ROI (Region Of Interest) area of the content video source.
+ * @since_tizen 5.0
+ * @remarks This function gets the ratio value of the each coordinate and size based on the video resolution size.
+ * @remarks The ROI area is valid only in #PLAYER_DISPLAY_TYPE_OVERLAY.
+ * @param[in]  player     The handle to the media player
+ * @param[out] x_scale    The current X coordinate ratio value of the video source area based on the video width size
+ * @param[out] y_scale    The current Y coordinate ratio value of the video source area based on the video height size
+ * @param[out] w_scale    The current width ratio value of the video source area based on the video width size
+ * @param[out] h_scale    The current height ratio value of the video source area based on the video height size
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval  #PLAYER_ERROR_NONE Successful
+ * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @see #player_display_type_e
+ * @see player_set_display()
+ * @see player_get_video_size()
+ * @see player_set_video_roi_area()
+ */
+int player_get_video_roi_area(player_h player, double *x_scale, double *y_scale, double *w_scale, double *h_scale);
+
+/**
  * @}
  */