enhance document description related to display and add return type in display APIs

Change-Id: I2ab2f3a48c7a3083cae96d732356a8fb5f973eca

diff --git a/include/common/player.h b/include/common/player.h
index 8726c5fd73eee58984118a633de85fed96e100d0..2c9457ca037de73a6a2b29414750619246ec09d8 100644 (file)
--- a/include/common/player.h
+++ b/include/common/player.h
@@ -869,8 +869,7 @@ int player_is_looping(player_h player, bool *looping);
  * @brief Sets the video display.
  * @since_tizen 2.3
  * @remarks To get @a display to set, use #GET_DISPLAY().
- * @remarks We are not supporting changing display between different types. \n
- *          If you want to change display handle after calling player_prepare(), you must use the same display type as what you set before.
+ * @remarks We are not supporting changing display.
  * @param[in]   player The handle to the media player
  * @param[in]   type The display type
  * @param[in]   display The handle to display
@@ -880,7 +879,11 @@ int player_is_looping(player_h player, bool *looping);
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
- * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @pre        The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
+ * @see #player_display_type_e
+ * @see player_set_display_mode
+ * @see player_set_display_roi_area
+ * @see player_set_display_visible
  * @see player_set_display_rotation
  */
 int player_set_display(player_h player, player_display_type_e type, player_display_h display);
@@ -1128,8 +1131,12 @@ int player_get_media_stream_buffer_min_threshold(player_h player, player_stream_
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
  * @pre The player should support display mode changes.
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_mode_e
+ * @see player_set_display()
  * @see        player_get_display_mode()
  */
 int player_set_display_mode(player_h player, player_display_mode_e mode);
@@ -1144,13 +1151,17 @@ int player_set_display_mode(player_h player, player_display_mode_e mode);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @see        player_set_display_mode()
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_mode_e
+ * @see player_set_display_mode()
  */
 int player_get_display_mode(player_h player, player_display_mode_e *mode);
 
 /**
  * @brief Sets the ROI(Region Of Interest) area of display.
  * @since_tizen 3.0
+ * @remarks If no display is set, no operation is performed.
  * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI should be set with player_set_display_mode().
  *          The minimum value of width and height are 1.
  * @param[in] player The handle to the media player
@@ -1162,19 +1173,28 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre display_mode should be set to #PLAYER_DISPLAY_MODE_DST_ROI.
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see player_set_display()
+ * @see player_set_display_mode()
  */
 int player_set_display_roi_area(player_h player, int x, int y, int width, int height);
 
 /**
  * @brief Sets the visibility of the x surface video display
  * @since_tizen 2.3
+ * @remarks If no display is set, no operation is performed.
  * @param[in] player   The handle to the media player
  * @param[in] visible The visibility of the display (@c true = visible, @c false = non-visible )
  * @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
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see player_set_display()
  * @see        player_is_display_visible()
  */
 int player_set_display_visible(player_h player, bool visible);
@@ -1188,6 +1208,8 @@ int player_set_display_visible(player_h player, bool visible);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
  * @see        player_set_display_visible()
  */
 int player_is_display_visible(player_h player, bool* visible);
@@ -1195,6 +1217,7 @@ int player_is_display_visible(player_h player, bool* visible);
 /**
  * @brief Sets the rotation settings of the video surface display.
  * @since_tizen 2.3
+ * @remarks If no display is set, no operation is performed.
  * @details Use this function to change the video orientation to portrait mode.
  * @param[in] player   The handle to the media player
  * @param[in] rotation The rotation of the display
@@ -1202,8 +1225,11 @@ int player_is_display_visible(player_h player, bool* visible);
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
  * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_rotation_e
  * @see  player_set_display
  * @see  player_get_display_rotation()
  */
@@ -1218,6 +1244,9 @@ int player_set_display_rotation(player_h player, player_display_rotation_e rotat
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_rotation_e
  * @see     player_set_display_rotation()
  */
 int player_get_display_rotation(player_h player, player_display_rotation_e *rotation);

diff --git a/include/wearable/player.h b/include/wearable/player.h
index cdafc2b464ed5a716beaac68ce72f4b5ecd59168..beb52b5d8949d28a2f8e6c7c88e02ac003028c9b 100755 (executable)
--- a/include/wearable/player.h
+++ b/include/wearable/player.h
@@ -867,8 +867,7 @@ int player_is_looping(player_h player, bool *looping);
  * @brief Sets the video display.
  * @since_tizen 2.3.1
  * @remarks To get @a display to set, use #GET_DISPLAY().
- * @remarks We are not supporting changing display between different types. \n
- *          If you want to change display handle after calling player_prepare(), you must use the same display type as what you set before.
+ * @remarks We are not supporting changing display.
  * @param[in]   player The handle to the media player
  * @param[in]   type The display type
  * @param[in]   display The handle to display
@@ -878,7 +877,11 @@ int player_is_looping(player_h player, bool *looping);
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
- * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @pre        The player state must be set to #PLAYER_STATE_IDLE by calling player_create() or player_unprepare().
+ * @see #player_display_type_e
+ * @see player_set_display_mode
+ * @see player_set_display_roi_area
+ * @see player_set_display_visible
  * @see player_set_display_rotation
  */
 int player_set_display(player_h player, player_display_type_e type, player_display_h display);
@@ -1126,8 +1129,12 @@ int player_get_media_stream_buffer_min_threshold(player_h player, player_stream_
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
  * @pre The player should support display mode changes.
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_mode_e
+ * @see player_set_display()
  * @see        player_get_display_mode()
  */
 int player_set_display_mode(player_h player, player_display_mode_e mode);
@@ -1142,13 +1149,17 @@ int player_set_display_mode(player_h player, player_display_mode_e mode);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @see        player_set_display_mode()
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_mode_e
+ * @see player_set_display_mode()
  */
 int player_get_display_mode(player_h player, player_display_mode_e *mode);
 
 /**
  * @brief Sets the ROI(Region Of Interest) area of display.
  * @since_tizen 3.0
+ * @remarks If no display is set, no operation is performed.
  * @remarks Before set display ROI area, #PLAYER_DISPLAY_MODE_DST_ROI should be set with player_set_display_mode().
  *          The minimum value of width and height are 1.
  * @param[in] player The handle to the media player
@@ -1160,19 +1171,28 @@ int player_get_display_mode(player_h player, player_display_mode_e *mode);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre display_mode should be set to #PLAYER_DISPLAY_MODE_DST_ROI.
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see player_set_display()
+ * @see player_set_display_mode()
  */
 int player_set_display_roi_area(player_h player, int x, int y, int width, int height);
 
 /**
  * @brief Sets the visibility of the x surface video display
  * @since_tizen 2.3.1
+ * @remarks If no display is set, no operation is performed.
  * @param[in] player   The handle to the media player
  * @param[in] visible The visibility of the display (@c true = visible, @c false = non-visible )
  * @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
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see player_set_display()
  * @see        player_is_display_visible()
  */
 int player_set_display_visible(player_h player, bool visible);
@@ -1186,6 +1206,8 @@ int player_set_display_visible(player_h player, bool visible);
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
  * @see        player_set_display_visible()
  */
 int player_is_display_visible(player_h player, bool* visible);
@@ -1193,6 +1215,7 @@ int player_is_display_visible(player_h player, bool* visible);
 /**
  * @brief Sets the rotation settings of the video surface display.
  * @since_tizen 2.3.1
+ * @remarks If no display is set, no operation is performed.
  * @details Use this function to change the video orientation to portrait mode.
  * @param[in] player   The handle to the media player
  * @param[in] rotation The rotation of the display
@@ -1200,8 +1223,11 @@ int player_is_display_visible(player_h player, bool* visible);
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
  * @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_rotation_e
  * @see  player_set_display
  * @see  player_get_display_rotation()
  */
@@ -1216,6 +1242,9 @@ int player_set_display_rotation(player_h player, player_display_rotation_e rotat
  *         otherwise a negative error value
  * @retval  #PLAYER_ERROR_NONE Successful
  * @retval  #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval  #PLAYER_ERROR_INVALID_OPERATION Invalid operation
+ * @pre The player state must be one of these: #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see #player_display_rotation_e
  * @see     player_set_display_rotation()
  */
 int player_get_display_rotation(player_h player, player_display_rotation_e *rotation);

diff --git a/src/player.c b/src/player.c
index cf77518d6691e6e8672d53412fbd4ce971909c07..ac9a1ec10d61a2b87f8d687379bb169088966d3b 100644 (file)
--- a/src/player.c
+++ b/src/player.c
@@ -2154,7 +2154,7 @@ int player_set_display(player_h player, player_display_type_e type, player_displ
                                }
                                if (mm_evas_renderer_create(&EVAS_HANDLE(pc), obj) != MM_ERROR_NONE) {
                                        LOGW("fail to set evas client");
-                                       /* FIXME : need to handle error case */
+                                       return PLAYER_ERROR_INVALID_OPERATION;
                                }
 
                                if (player_set_media_packet_video_frame_decoded_cb(player, mm_evas_renderer_write, (void *)EVAS_HANDLE(pc)) != PLAYER_ERROR_NONE)
@@ -2187,8 +2187,11 @@ int player_set_display_mode(player_h player, player_display_mode_e mode)
 #ifdef TIZEN_FEATURE_EVAS_RENDERER
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_set_geometry(EVAS_HANDLE(pc), mode);
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send1(api, pc, ret_buf, ret, INT, mode);
@@ -2211,8 +2214,11 @@ int player_get_display_mode(player_h player, player_display_mode_e * pmode)
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_get_geometry(EVAS_HANDLE(pc), &mode);
                *pmode = (player_display_mode_e) mode;
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send(api, pc, ret_buf, ret);
@@ -2243,8 +2249,13 @@ int player_set_display_roi_area(player_h player, int x, int y, int width, int he
 #ifdef TIZEN_FEATURE_EVAS_RENDERER
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_set_roi_area(EVAS_HANDLE(pc), x, y, width, height);
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret == MM_ERROR_INVALID_ARGUMENT) {
+                       return PLAYER_ERROR_INVALID_PARAMETER;
+               } else if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        wl_win.wl_window_x = x;
@@ -2285,8 +2296,11 @@ int player_set_display_rotation(player_h player, player_display_rotation_e rotat
 #ifdef TIZEN_FEATURE_EVAS_RENDERER
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_set_rotation(EVAS_HANDLE(pc), rotation);
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send1(api, pc, ret_buf, ret, INT, rotation);
@@ -2309,8 +2323,11 @@ int player_get_display_rotation(player_h player, player_display_rotation_e * pro
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_get_rotation(EVAS_HANDLE(pc), &rotation);
                *protation = (player_display_rotation_e) rotation;
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send(api, pc, ret_buf, ret);
@@ -2335,8 +2352,11 @@ int player_set_display_visible(player_h player, bool visible)
 #ifdef TIZEN_FEATURE_EVAS_RENDERER
        if (EVAS_HANDLE(pc)) {
                ret = mm_evas_renderer_set_visible(EVAS_HANDLE(pc), visible);
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send1(api, pc, ret_buf, ret, INT, visible);
@@ -2365,8 +2385,11 @@ int player_is_display_visible(player_h player, bool * pvisible)
                else
                        *pvisible = FALSE;
 
-               /* FIXME: need to handle error code from evas */
-               return PLAYER_ERROR_NONE;
+               if (ret != MM_ERROR_NONE) {
+                       return PLAYER_ERROR_INVALID_OPERATION;
+               } else {
+                       return PLAYER_ERROR_NONE;
+               }
        }
 #endif
        player_msg_send(api, pc, ret_buf, ret);