Video control functions

Functions
Video control functions
Emotion » API available for manipulating Emotion object.

## Functions
EMOTION_API void | emotion_object_border_set (Evas_Object *obj, int l, int r, int t, int b)
| Set borders for the emotion object. More...
EMOTION_API void | emotion_object_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b)
| Get the borders set for the emotion object. More...
EMOTION_API void | emotion_object_bg_color_set (Evas_Object *obj, int r, int g, int b, int a)
| Set a color for the background rectangle of this emotion object. More...
EMOTION_API void | emotion_object_bg_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a)
| Get the background color set for the emotion object. More...
EMOTION_API void | emotion_object_keep_aspect_set (Evas_Object *obj, Emotion_Aspect a)
| Set whether emotion should keep the aspect ratio of the video. More...
EMOTION_API Emotion_Aspect | emotion_object_keep_aspect_get (const Evas_Object *obj)
| Get the current emotion aspect ratio policy. More...
EMOTION_API double | emotion_object_ratio_get (const Evas_Object *obj)
| Retrieve the video aspect ratio of the media file loaded. More...
EMOTION_API void | emotion_object_size_get (const Evas_Object *obj, int *iw, int *ih)
| Retrieve the video size of the loaded file. More...
EMOTION_API void | emotion_object_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth)
| Sets whether to use of high-quality image scaling algorithm of the given video object. More...
EMOTION_API Eina_Bool | emotion_object_smooth_scale_get (const Evas_Object *obj)
| Gets whether the high-quality image scaling algorithm of the given video object is used. More...
EMOTION_API void | emotion_object_video_mute_set (Evas_Object *obj, Eina_Bool mute)
| Set the mute video option for this object. More...
EMOTION_API Eina_Bool | emotion_object_video_mute_get (const Evas_Object *obj)
| Get the mute video option of this object. More...
EMOTION_API void | emotion_object_video_subtitle_file_set (Evas_Object *obj, const char *filepath)
| Set the video's subtitle file path. More...
EMOTION_API const char * | emotion_object_video_subtitle_file_get (const Evas_Object *obj)
| Get the video's subtitle file path. More...
EMOTION_API int | emotion_object_video_channel_count (const Evas_Object *obj)
| Get the number of available video channel. More...
EMOTION_API const char * | emotion_object_video_channel_name_get (const Evas_Object *obj, int channel)
| Get the name of a given video channel. More...
EMOTION_API void | emotion_object_video_channel_set (Evas_Object *obj, int channel)
| Set the channel for a given video object. More...
EMOTION_API int | emotion_object_video_channel_get (const Evas_Object *obj)
| Get the channel for a given video object. More...

## Detailed Description

## Function Documentation

## ◆ emotion_object_border_set()

EMOTION_API void emotion_object_border_set | ( | Evas_Object * | obj,
|  | int | l,
|  | int | r,
|  | int | t,
|  | int | b
| ) |  |

Set borders for the emotion object.

Parameters

  obj | The emotion object where borders are being set.
  l | The left border.
  r | The right border.
  t | The top border.
  b | The bottom border.

This function sets borders for the emotion video object (just when a video is present). When positive values are given to one of the parameters, a border will be added to the respective position of the object, representing that size on the original video size. However, if the video is scaled up or down (i.e. the emotion object size is different from the video size), the borders will be scaled respectively too.

If a negative value is given to one of the parameters, instead of a border, that respective side of the video will be cropped.

It's possible to set a color for the added borders (default is transparent) with emotion_object_bg_color_set(). By default, an Emotion object doesn't have any border.

See also
  emotion_object_border_get()
  emotion_object_bg_color_set()

References EMOTION_ASPECT_CUSTOM, and evas_object_geometry_get().

## ◆ emotion_object_border_get()

EMOTION_API void emotion_object_border_get | ( | const Evas_Object * | obj,
|  | int * | l,
|  | int * | r,
|  | int * | t,
|  | int * | b
| ) |  |

Get the borders set for the emotion object.

Parameters

  obj | The emotion object from which the borders are being retrieved.
  l | The left border.
  r | The right border.
  t | The top border.
  b | The bottom border.

See also
  emotion_object_border_set()

## ◆ emotion_object_bg_color_set()

EMOTION_API void emotion_object_bg_color_set | ( | Evas_Object * | obj,
|  | int | r,
|  | int | g,
|  | int | b,
|  | int | a
| ) |  |

Set a color for the background rectangle of this emotion object.

Parameters

  obj | The emotion object where the background color is being set.
  r | Red component of the color.
  g | Green component of the color.
  b | Blue component of the color.
  a | Alpha channel of the color.

This is useful when a border is added to any side of the Emotion object. The area between the edge of the video and the edge of the object will be filled with the specified color.

The default color is 0, 0, 0, 0 (transparent).

See also
  emotion_object_bg_color_get()

References evas_object_color_set().

## ◆ emotion_object_bg_color_get()

EMOTION_API void emotion_object_bg_color_get | ( | const Evas_Object * | obj,
|  | int * | r,
|  | int * | g,
|  | int * | b,
|  | int * | a
| ) |  |

Get the background color set for the emotion object.

Parameters

  obj | The emotion object from which the background color is being retrieved.
  r | Red component of the color.
  g | Green component of the color.
  b | Blue component of the color.
  a | AAlpha channel of the color.

See also
  emotion_object_bg_color_set()

References evas_object_color_get().

## ◆ emotion_object_keep_aspect_set()

EMOTION_API void emotion_object_keep_aspect_set | ( | Evas_Object * | obj,
|  | Emotion_Aspect | a
| ) |  |

Set whether emotion should keep the aspect ratio of the video.

Parameters

  obj | The emotion object where to set the aspect.
  a | The aspect ratio policy.

Instead of manually calculating the required border to set with emotion_object_border_set(), and using this to fix the aspect ratio of the video when the emotion object has a different aspect, it's possible to just set the policy to be used.

The options are:

- EMOTION_ASPECT_KEEP_NONE - ignore the video aspect ratio, and reset any border set to 0, stretching the video inside the emotion object area. This option is similar to EVAS_ASPECT_CONTROL_NONE size hint.
- EMOTION_ASPECT_KEEP_WIDTH - respect the video aspect ratio, fitting the video width inside the object width. This option is similar to EVAS_ASPECT_CONTROL_HORIZONTAL size hint.
- EMOTION_ASPECT_KEEP_HEIGHT - respect the video aspect ratio, fitting the video height inside the object height. This option is similar to EVAS_ASPECT_CONTROL_VERTIAL size hint.
- EMOTION_ASPECT_KEEP_BOTH - respect the video aspect ratio, fitting both its width and height inside the object area. This option is similar to EVAS_ASPECT_CONTROL_BOTH size hint. It's the effect called letterboxing.
- EMOTION_ASPECT_CROP - respect the video aspect ratio, fitting the width or height inside the object area, and cropping the exceding areas of the video in height or width. It's the effect called pan-and-scan.
- EMOTION_ASPECT_CUSTOM - ignore the video aspect ratio, and use the current set from emotion_object_border_set().

Note
  Calling this function with any value except EMOTION_ASPECT_CUSTOM will invalidate borders set with emotion_object_border_set().
  Calling emotion_object_border_set() will automatically set the aspect policy to EMOTION_ASPECT_CUSTOM.

See also
  emotion_object_border_set()
  emotion_object_keep_aspect_get()

References evas_object_geometry_get().

## ◆ emotion_object_keep_aspect_get()

EMOTION_API Emotion_Aspect emotion_object_keep_aspect_get | ( | const Evas_Object * | obj | ) |

Get the current emotion aspect ratio policy.

Parameters

  obj | The emotion object from which we are fetching the aspect ratio policy.

Returns
  The current aspect ratio policy.

See also
  emotion_object_keep_aspect_set()

References EMOTION_ASPECT_KEEP_NONE.

## ◆ emotion_object_ratio_get()

EMOTION_API double emotion_object_ratio_get | ( | const Evas_Object * | obj | ) |

Retrieve the video aspect ratio of the media file loaded.

Parameters

  obj | The emotion object which the video aspect ratio will be retrieved from.

Returns
  The video aspect ratio of the file loaded.

This function returns the video aspect ratio (width / height) of the file loaded. It can be used to adapt the size of the emotion object in the canvas, so the aspect won't be changed (by wrongly resizing the object). Or to crop the video correctly, if necessary.

The described behavior can be applied like following. Consider a given emotion object that we want to position inside an area, which we will represent by `w` and `h`. Since we want to position this object either stretching, or filling the entire area but overflowing the video, or just adjust the video to fit inside the area without keeping the aspect ratio, we must compare the video aspect ratio with the area aspect ratio:

int w = 200, h = 300; // an arbitrary value which represents the area where
// the video would be placed
int vw, vh;
double r, vr = emotion_object_ratio_get(obj);
r = (double)w / h;
emotion_object_ratio_get
EMOTION_API double emotion_object_ratio_get(const Evas_Object *obj)
Retrieve the video aspect ratio of the media file loaded.
Definition: emotion_smart.c:857

Now, if we want to make the video fit inside the area, the following code would do it:

if (vr > r) // the video is wider than the area
{
vw = w;
vh = w / vr;
}
else // the video is taller than the area
{
vh = h;
vw = h * vr;
}
evas_object_resize(obj, vw, vh);
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition: evas_object_main.c:1236

And for keeping the aspect ratio but making the video fill the entire area, overflowing the content which can't fit inside it, we would do:

if (vr > r) // the video is wider than the area
{
vh = h;
vw = h * vr;
}
else // the video is taller than the area
{
vw = w;
vh = w / vr;
}
evas_object_resize(obj, vw, vh);

Finally, by just resizing the video to the video area, we would have the video stretched:

vw = w;
vh = h;
evas_object_resize(obj, vw, vh);

The following diagram exemplifies what would happen to the video, respectively, in each case:

Note
  This function returns the aspect ratio that the video should be, but sometimes the reported size from emotion_object_size_get() represents a different aspect ratio. You can safely resize the video to respect the aspect ratio returned by this function.

See also
  emotion_object_size_get()

Examples
  emotion_signals_example.c, and emotion_test_main.c.

## ◆ emotion_object_size_get()

EMOTION_API void emotion_object_size_get | ( | const Evas_Object * | obj,
|  | int * | iw,
|  | int * | ih
| ) |  |

Retrieve the video size of the loaded file.

Parameters

  obj | The object from which we are retrieving the video size.
  iw | A pointer to a variable where the width will be stored.
  ih | A pointer to a variable where the height will be stored.

This function returns the reported size of the loaded video file. If a file that doesn't contain a video channel is loaded, then this size can be ignored.

The value reported by this function should be consistent with the aspect ratio returned by emotion_object_ratio_get(), but sometimes the information stored in the file is wrong. So use the ratio size reported by emotion_object_ratio_get(), since it is more likely going to be accurate.

Note
  Use `NULL` for `iw` or `ih` if you don't need one of these values.

See also
  emotion_object_ratio_get()

Examples
  emotion_signals_example.c, and emotion_test_main.c.

## ◆ emotion_object_smooth_scale_set()

EMOTION_API void emotion_object_smooth_scale_set | ( | Evas_Object * | obj,
|  | Eina_Bool | smooth
| ) |  |

Sets whether to use of high-quality image scaling algorithm of the given video object.

When enabled, a higher quality video scaling algorithm is used when scaling videos to sizes other than the source video. This gives better results but is more computationally expensive.

Parameters

  obj | The given video object.
  smooth | Whether to use smooth scale or not.

See also
  emotion_object_smooth_scale_get()

Examples
  emotion_test_main.c.

## ◆ emotion_object_smooth_scale_get()

EMOTION_API Eina_Bool emotion_object_smooth_scale_get | ( | const Evas_Object * | obj | ) |

Gets whether the high-quality image scaling algorithm of the given video object is used.

Parameters

  obj | The given video object.

Returns
  Whether the smooth scale is used or not.

See also
  emotion_object_smooth_scale_set()

## ◆ emotion_object_video_mute_set()

EMOTION_API void emotion_object_video_mute_set | ( | Evas_Object * | obj,
|  | Eina_Bool | mute
| ) |  |

Set the mute video option for this object.

Parameters

  obj | The object which we are setting the mute video option.
  mute | Whether the video should be muted (`EINA_TRUE`) or not (`EINA_FALSE`).

This function sets the mute video option for this emotion object. The current module used for this object can use this information to avoid decoding the video portion of the loaded media file.

See also
  emotion_object_video_mute_get()
  emotion_object_audio_mute_set()

Examples
  emotion_test_main.c.

References DBG.

## ◆ emotion_object_video_mute_get()

EMOTION_API Eina_Bool emotion_object_video_mute_get | ( | const Evas_Object * | obj | ) |

Get the mute video option of this object.

Parameters

  obj | The object which we are retrieving the mute video option from.

Returns
  Whether the video is muted (`EINA_TRUE`) or not (`EINA_FALSE`).

This function returns the mute video option from this emotion object. It can be set with emotion_object_video_mute_set().

See also
  emotion_object_video_mute_set()

Examples
  emotion_test_main.c.

References EINA_FALSE.

## ◆ emotion_object_video_subtitle_file_set()

EMOTION_API void emotion_object_video_subtitle_file_set | ( | Evas_Object * | obj,
|  | const char * | filepath
| ) |  |

Set the video's subtitle file path.

Parameters

  obj | The object which we are setting a subtitle file path.
  filepath | The subtitle file path.

This function sets a video's subtitle file path(i.e an .srt file) for supported subtitle formats consult the backend's documentation.

See also
  emotion_object_video_subtitle_file_get().

Since
  1.8

References DBG.

## ◆ emotion_object_video_subtitle_file_get()

EMOTION_API const char* emotion_object_video_subtitle_file_get | ( | const Evas_Object * | obj | ) |

Get the video's subtitle file path.

Parameters

  obj | The object which we are retrieving the subtitle file path from.

Returns
  The video's subtitle file path previously set, NULL otherwise.

This function returns the video's subtitle file path, if not previously set or in error NULL is returned.

See also
  emotion_object_video_subtitle_file_set().

Since
  1.8

## ◆ emotion_object_video_channel_count()

EMOTION_API int emotion_object_video_channel_count | ( | const Evas_Object * | obj | ) |

Get the number of available video channel.

Parameters

  obj | The object which we are retrieving the channel count from

Returns
  the number of available channel.

See also
  emotion_object_video_channel_name_get()

Examples
  emotion_test_main.c.

## ◆ emotion_object_video_channel_name_get()

EMOTION_API const char* emotion_object_video_channel_name_get | ( | const Evas_Object * | obj,
|  | int | channel
| ) |  |

Get the name of a given video channel.

Parameters

  obj | The object which we are retrieving the channel name from
  channel | the channel number

Returns
  the channel name.

See also
  emotion_object_video_channel_count()

## ◆ emotion_object_video_channel_set()

EMOTION_API void emotion_object_video_channel_set | ( | Evas_Object * | obj,
|  | int | channel
| ) |  |

Set the channel for a given video object.

Parameters

  obj | The target object which we are setting the channel
  channel | the channel number to be setted.

References DBG.

## ◆ emotion_object_video_channel_get()

EMOTION_API int emotion_object_video_channel_get | ( | const Evas_Object * | obj | ) |

Get the channel for a given video object.

Parameters

  obj | The target object which we are getting the channel

Returns
  The current channel number.