Tizen Native API  7.0

The Layer API provides functions to manage layers.

Required Header

#include <media_editor.h>

Overview

The Mediaeditor Layer API allows you to:

  • add/remove layer to internal timeline
  • activate/deactivate layer which is already added
  • move layer

Functions

int mediaeditor_add_layer (mediaeditor_h editor, unsigned int *layer_id, unsigned int *layer_priority)
 Adds a layer to timeline.
int mediaeditor_remove_layer (mediaeditor_h editor, unsigned int layer_id)
 Removes a layer from timeline.
int mediaeditor_move_layer (mediaeditor_h editor, unsigned int layer_id, unsigned int layer_priority)
 Moves a layer_id layer to layer_priority position.
int mediaeditor_activate_layer (mediaeditor_h editor, unsigned int layer_id)
 Activates given layer on timeline. The layer will be included when it's rendered.
int mediaeditor_deactivate_layer (mediaeditor_h editor, unsigned int layer_id)
 Deactivates given layer on timeline.
int mediaeditor_get_layer_priority (mediaeditor_h editor, unsigned int layer_id, unsigned int *layer_priority)
 Gets the priority of layer_id layer.
int mediaeditor_get_layer_lowest_priority (mediaeditor_h editor, unsigned int *layer_priority)
 Gets the lowest priority of all layers.
int mediaeditor_get_layer_id (mediaeditor_h editor, unsigned int layer_priority, unsigned int *layer_id)
 Gets the layer ID of layer_priority layer.
int mediaeditor_set_layer_priority_changed_cb (mediaeditor_h editor, mediaeditor_layer_priority_changed_cb callback, void *user_data)
 Sets a callback function to be invoked when a layer priority is changed.
int mediaeditor_unset_layer_priority_changed_cb (mediaeditor_h editor)
 Unsets a layer priority changed callback function.

Typedefs

typedef void(* mediaeditor_layer_priority_changed_cb )(mediaeditor_layer_info_s *layer_infos, unsigned int size, void *user_data)
 Called when the priority of layers is changed.

Typedef Documentation

typedef void(* mediaeditor_layer_priority_changed_cb)(mediaeditor_layer_info_s *layer_infos, unsigned int size, void *user_data)

Called when the priority of layers is changed.

Since :
7.0
Remarks:
layer_info should be released using free().
Parameters:
[in]layer_infosThe layer information including layer id and its priority. It's array.
[in]sizeThe number of layer_infos array
[in]user_dataThe user data passed from the callback registration function
See also:
mediaeditor_set_layer_priority_changed_cb()
mediaeditor_unset_layer_priority_changed_cb()

Function Documentation

int mediaeditor_activate_layer ( mediaeditor_h  editor,
unsigned int  layer_id 
)

Activates given layer on timeline. The layer will be included when it's rendered.

Since :
7.0
Remarks:
Note that the newly created layer will be activated by default.
Parameters:
[in]editorThe media editor handle
[in]layer_idThe layer ID
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_deactivate_layer()
int mediaeditor_add_layer ( mediaeditor_h  editor,
unsigned int *  layer_id,
unsigned int *  layer_priority 
)

Adds a layer to timeline.

Since :
7.0
Remarks:
Layers are responsible for ordering of contained clips. The order is determined by layers' priorities.
The layers are stacked in a hierarchical structure.
e.g. If we have 3 layers, it will have the following hierarchy.
          Top    : layer ID 1, layer priority 0 (The highest priority)
                   layer ID 2, layer priority 1
          Bottom : layer ID 3, layer priority 2 (The lowest priority)
 
Priorities are always a continuous sequence, with no numbers missing in-between.
For example, priorities 0, 1, 3, 4 are not possible.
But, layer Id could be a discontinuous sequence. Please refer to examples of mediaeditor_remove_layer().
The layer_priority of newly added layer will be lowest priority.
Parameters:
[in]editorThe media editor handle
[out]layer_idThe layer ID. It'll be used when you want to control this layer.
[out]layer_priorityThe layer priority represents the hierarchical ordering of contained clips.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_remove_layer()
mediaeditor_move_layer()
mediaeditor_activate_layer()
mediaeditor_deactivate_layer()
int mediaeditor_deactivate_layer ( mediaeditor_h  editor,
unsigned int  layer_id 
)

Deactivates given layer on timeline.

Since :
7.0
Remarks:
The layer is not removed actually but just excluded when it's rendered.
Parameters:
[in]editorThe media editor handle
[in]layer_idThe layer ID
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_activate_layer()
int mediaeditor_get_layer_id ( mediaeditor_h  editor,
unsigned int  layer_priority,
unsigned int *  layer_id 
)

Gets the layer ID of layer_priority layer.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]layer_priorityThe layer priority
[out]layer_idThe layer ID
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
See also:
mediaeditor_add_layer()
mediaeditor_get_layer_priority()
mediaeditor_get_layer_lowest_priority()
int mediaeditor_get_layer_lowest_priority ( mediaeditor_h  editor,
unsigned int *  layer_priority 
)

Gets the lowest priority of all layers.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[out]layer_priorityThe lowest layer priority
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
See also:
mediaeditor_add_layer()
mediaeditor_get_layer_priority()
mediaeditor_get_layer_id()
int mediaeditor_get_layer_priority ( mediaeditor_h  editor,
unsigned int  layer_id,
unsigned int *  layer_priority 
)

Gets the priority of layer_id layer.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]layer_idThe layer ID
[out]layer_priorityThe layer priority
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
See also:
mediaeditor_add_layer()
mediaeditor_get_layer_lowest_priority()
mediaeditor_get_layer_id()
int mediaeditor_move_layer ( mediaeditor_h  editor,
unsigned int  layer_id,
unsigned int  layer_priority 
)

Moves a layer_id layer to layer_priority position.

Since :
7.0
Remarks:
e.g. There're 3 layers.
case 1 : move layer ID 1 to layer priority 0.
Nothing happens.
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before |          layer ID 2, layer priority 1 (including 3 clips)
          moving | bottom : layer ID 3, layer priority 2 (including 5 clips)
          ------------------------------------------------------------------
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          After  |          layer ID 2, layer priority 1 (including 3 clips)
          moving | bottom : layer ID 3, layer priority 2 (including 5 clips)
 

case 2 : move layer ID 3 to layer priority 1.
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before |          layer ID 2, layer priority 1 (including 3 clips)
          moving | bottom : layer ID 3, layer priority 2 (including 5 clips)
          ------------------------------------------------------------------
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          After  |          layer ID 3, layer priority 1 (including 5 clips)
          moving | bottom : layer ID 2, layer priority 2 (including 3 clips)
 

case 3 : move layer ID 1 to layer priority 3.
(Currently, there's no priority 3 layer.)
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before |          layer ID 2, layer priority 1 (including 3 clips)
          moving | bottom : layer ID 3, layer priority 2 (including 5 clips)
          ------------------------------------------------------------------
                 | top    : layer ID 2, layer priority 0 (including 3 clips)
          After  |          layer ID 3, layer priority 1 (including 5 clips)
          moving | bottom : layer ID 1, layer priority 2 (including 1 clips)
 

case 4 : move layer ID 1 to layer priority 5.
(Currently, there's no priority 5 layer and it's not continuous sequence.)
                 | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before |          layer ID 2, layer priority 1 (including 3 clips)
          moving | bottom : layer ID 3, layer priority 2 (including 5 clips)
          ------------------------------------------------------------------
                 | top    : layer ID 2, layer priority 0 (including 3 clips)
          After  |          layer ID 3, layer priority 1 (including 5 clips)
          moving | bottom : layer ID 1, layer priority 2 (including 1 clips)
 

If you can move layer to the lowest priority position, you can get the lowest priority using mediaeditor_get_layer_lowest_priority()
Parameters:
[in]editorThe media editor handle
[in]layer_idThe layer ID
[in]layer_priorityThe target layer priority that layer_id is moved
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
mediaeditor_layer_priority_changed_cb() will be invoked if it's set.
See also:
mediaeditor_add_layer()
mediaeditor_get_layer_lowest_priority()
mediaeditor_set_layer_priority_changed_cb()
mediaeditor_unset_layer_priority_changed_cb()
int mediaeditor_remove_layer ( mediaeditor_h  editor,
unsigned int  layer_id 
)

Removes a layer from timeline.

Since :
7.0
Remarks:
The other layer's layer ID is not changed after removing layer_id.
If layer_id is not bottom layer, layer priority will be rearranged.
e.g. There're 3 layers like the followings.

case 1 : remove layer ID 3.
The layer ID 3 is removed and other layers' priorities are not rearranged.
                   | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before   |          layer ID 2, layer priority 1 (including 3 clips)
          removing | bottom : layer ID 3, layer priority 2 (including 5 clips)
          --------------------------------------------------------------------
          After    | top    : layer ID 1, layer priority 0 (including 1 clips)
          removing | bottom : layer ID 2, layer priority 1 (including 3 clips)
 

case 2 : remove layer ID 1.
                   | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before   |          layer ID 2, layer priority 1 (including 3 clips)
          removing | bottom : layer ID 3, layer priority 2 (including 5 clips)
          --------------------------------------------------------------------
          After    | top    : layer ID 2, layer priority 0 (including 3 clips)
          removing | bottom : layer ID 3, layer priority 1 (including 5 clips)
 

* case 3 : remove layer ID 2 and add a new layer.
                   | top    : layer ID 1, layer priority 0 (including 1 clips)
          Before   |          layer ID 2, layer priority 1 (including 3 clips)
          removing | bottom : layer ID 3, layer priority 2 (including 5 clips)
          --------------------------------------------------------------------
          After    | top    : layer ID 1, layer priority 0 (including 1 clips)
          removing | bottom : layer ID 3, layer priority 1 (including 5 clips)
          --------------------------------------------------------------------
          After    | top    : layer ID 1, layer priority 0 (including 1 clips)
          adding   |        : layer ID 3, layer priority 1 (including 5 clips)
          a layer  | bottom : layer ID 4, layer priority 2 (including 7 clips)
 
Parameters:
[in]editorThe media editor handle
[in]layer_idThe layer ID
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
mediaeditor_layer_priority_changed_cb() will be invoked if it's set.
See also:
mediaeditor_add_layer()
mediaeditor_set_layer_priority_changed_cb()
mediaeditor_unset_layer_priority_changed_cb()

Sets a callback function to be invoked when a layer priority is changed.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
mediaeditor_layer_priority_changed_cb() will be invoked.
See also:
mediaeditor_unset_layer_priority_changed_cb()
mediaeditor_layer_priority_changed_cb()

Unsets a layer priority changed callback function.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_set_layer_priority_changed_cb()