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_infos	The layer information including layer id and its priority. It's array.
[in]	size	The number of layer_infos array
[in]	user_data	The 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]	editor	The media editor handle
[in]	layer_id	The layer ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[out]	layer_id	The layer ID. It'll be used when you want to control this layer.
[out]	layer_priority	The layer priority represents the hierarchical ordering of contained clips.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	layer_id	The layer ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	layer_priority	The layer priority
[out]	layer_id	The layer ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid 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]	editor	The media editor handle
[out]	layer_priority	The lowest layer priority

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid 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]	editor	The media editor handle
[in]	layer_id	The layer ID
[out]	layer_priority	The layer priority

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid 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]	editor	The media editor handle
[in]	layer_id	The layer ID
[in]	layer_priority	The target layer priority that layer_id is moved

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	layer_id	The layer ID

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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()

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.

Since :: 7.0

Parameters:

[in]	editor	The media editor handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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()

int mediaeditor_unset_layer_priority_changed_cb ( mediaeditor_h editor )

Unsets a layer priority changed callback function.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid state

Precondition:: editor state must be set to MEDIAEDITOR_STATE_IDLE.

See also:: mediaeditor_set_layer_priority_changed_cb()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation