6 * @brief Emotion Media Library
8 * These routines are used for Emotion.
13 * @mainpage Emotion Library Documentation
18 * @section intro What is Emotion?
20 * A media object library for Evas and Ecore.
22 * Emotion is a library that allows playing audio and video files, using one of
23 * its backends (gstreamer or xine).
25 * It is integrated into Ecore through its mainloop, and is transparent to the
26 * user of the library how the decoding of audio and video is being done. Once
27 * the objects are created, the user can set callbacks to the specific events
28 * and set options to this object, all in the main loop (no threads are needed).
30 * Emotion is also integrated with Evas. The emotion object returned by
31 * emotion_object_add() is an Evas smart object, so it can be manipulated with
32 * default Evas object functions. Callbacks can be added to the signals emitted
33 * by this object with evas_object_smart_callback_add().
35 * @section work How does Emotion work?
37 * The Emotion library uses Evas smart objects to allow you to manipulate the
38 * created object as any other Evas object, and to connect to its signals,
39 * handling them when needed. It's also possible to swallow Emotion objects
40 * inside Edje themes, and expect it to behave as a normal image or rectangle
41 * when regarding to its dimensions.
43 * To instantiate an Emotion object, the simple code below is enough:
46 * em = emotion_object_add(e);
47 * emotion_object_init(em, NULL);
49 * emotion_object_file_set(em, file_path);
51 * evas_object_move(em, 0, 0);
52 * evas_object_resize(em, WIDTH, HEIGHT);
53 * evas_object_show(em);
55 * emotion_object_play_set(em, EINA_TRUE);
58 * See the @ref Emotion_API for a better reference.
60 * Please see the @ref authors page for contact details.
66 * @page authors Authors
68 * @author Carsten Haitzler <raster@rasterman.com>
69 * @author Vincent Torri <torri@maths.univ-evry.fr>
70 * @author Nicolas Aguirre <aguirre.nicolas@gmail.com>
71 * @author Sebastian Dransfeld <sd@tango.flipp.net>
72 * @author Cedric Bail <cedric.bail@free.fr>
74 * Please contact <enlightenment-devel@lists.sourceforge.net> to get in
75 * contact with the developers and maintainers.
86 # ifdef EFL_EMOTION_BUILD
88 # define EAPI __declspec(dllexport)
91 # endif /* ! DLL_EXPORT */
93 # define EAPI __declspec(dllimport)
94 # endif /* ! EFL_EMOTION_BUILD */
98 # define EAPI __attribute__ ((visibility("default")))
105 #endif /* ! _WIN32 */
109 * @brief The file that provides Emotion the API, with functions available for
110 * play, seek, change volume, etc.
116 EMOTION_MODULE_GSTREAMER
121 EMOTION_EVENT_MENU1, // Escape Menu
122 EMOTION_EVENT_MENU2, // Title Menu
123 EMOTION_EVENT_MENU3, // Root Menu
124 EMOTION_EVENT_MENU4, // Subpicture Menu
125 EMOTION_EVENT_MENU5, // Audio Menu
126 EMOTION_EVENT_MENU6, // Angle Menu
127 EMOTION_EVENT_MENU7, // Part Menu
132 EMOTION_EVENT_SELECT,
135 EMOTION_EVENT_ANGLE_NEXT,
136 EMOTION_EVENT_ANGLE_PREV,
152 * @enum _Emotion_Meta_Info
154 * Used for retrieving information about the media file being played.
156 * @see emotion_object_meta_info_get()
158 * @ingroup Emotion_Info
160 enum _Emotion_Meta_Info
162 EMOTION_META_INFO_TRACK_TITLE, /**< track title */
163 EMOTION_META_INFO_TRACK_ARTIST, /**< artist name */
164 EMOTION_META_INFO_TRACK_ALBUM, /**< album name */
165 EMOTION_META_INFO_TRACK_YEAR, /**< track year */
166 EMOTION_META_INFO_TRACK_GENRE, /**< track genre */
167 EMOTION_META_INFO_TRACK_COMMENT, /**< track comments */
168 EMOTION_META_INFO_TRACK_DISC_ID, /**< track disc ID */
169 EMOTION_META_INFO_TRACK_COUNT /**< track count - number of the track in the album */
175 * Used for displaying a visualization on the emotion object.
177 * @see emotion_object_vis_set()
179 * @ingroup Emotion_Visualization
183 EMOTION_VIS_NONE, /**< no visualization set */
184 EMOTION_VIS_GOOM, /**< goom */
185 EMOTION_VIS_LIBVISUAL_BUMPSCOPE, /**< bumpscope */
186 EMOTION_VIS_LIBVISUAL_CORONA, /**< corona */
187 EMOTION_VIS_LIBVISUAL_DANCING_PARTICLES, /**< dancing particles */
188 EMOTION_VIS_LIBVISUAL_GDKPIXBUF, /**< gdkpixbuf */
189 EMOTION_VIS_LIBVISUAL_G_FORCE, /**< G force */
190 EMOTION_VIS_LIBVISUAL_GOOM, /**< goom */
191 EMOTION_VIS_LIBVISUAL_INFINITE, /**< infinite */
192 EMOTION_VIS_LIBVISUAL_JAKDAW, /**< jakdaw */
193 EMOTION_VIS_LIBVISUAL_JESS, /**< jess */
194 EMOTION_VIS_LIBVISUAL_LV_ANALYSER, /**< lv analyser */
195 EMOTION_VIS_LIBVISUAL_LV_FLOWER, /**< lv flower */
196 EMOTION_VIS_LIBVISUAL_LV_GLTEST, /**< lv gltest */
197 EMOTION_VIS_LIBVISUAL_LV_SCOPE, /**< lv scope */
198 EMOTION_VIS_LIBVISUAL_MADSPIN, /**< madspin */
199 EMOTION_VIS_LIBVISUAL_NEBULUS, /**< nebulus */
200 EMOTION_VIS_LIBVISUAL_OINKSIE, /**< oinksie */
201 EMOTION_VIS_LIBVISUAL_PLASMA, /**< plasma */
202 EMOTION_VIS_LAST /* sentinel */
206 * @enum Emotion_Suspend
208 * Used for emotion pipeline ressource management.
210 * @see emotion_object_suspend_set()
211 * @see emotion_object_suspend_get()
213 * @ingroup Emotion_Ressource
217 EMOTION_WAKEUP, /**< pipeline is up and running */
218 EMOTION_SLEEP, /**< turn off hardware ressource usage like overlay */
219 EMOTION_DEEP_SLEEP, /**< destroy the pipeline, but keep full resolution pixels output around */
220 EMOTION_HIBERNATE /**< destroy the pipeline, and keep half resolution or object resolution if lower */
224 * @enum _Emotion_Aspect
225 * Defines the aspect ratio option.
229 EMOTION_ASPECT_KEEP_NONE, /**< ignore video aspect ratio */
230 EMOTION_ASPECT_KEEP_WIDTH, /**< respect video aspect, fitting its width inside the object width */
231 EMOTION_ASPECT_KEEP_HEIGHT, /**< respect video aspect, fitting its height inside the object height */
232 EMOTION_ASPECT_KEEP_BOTH, /**< respect video aspect, fitting it inside the object area */
233 EMOTION_ASPECT_CROP, /**< respect video aspect, cropping exceding area */
234 EMOTION_ASPECT_CUSTOM, /**< use custom borders/crop for the video */
237 typedef enum _Emotion_Module Emotion_Module;
238 typedef enum _Emotion_Event Emotion_Event;
239 typedef enum _Emotion_Meta_Info Emotion_Meta_Info; /**< Meta info type to be retrieved. */
240 typedef enum _Emotion_Vis Emotion_Vis; /**< Type of visualization. */
241 typedef enum _Emotion_Aspect Emotion_Aspect; /**< Aspect ratio option. */
243 #define EMOTION_CHANNEL_AUTO -1
244 #define EMOTION_CHANNEL_DEFAULT 0
250 #define EMOTION_VERSION_MAJOR 1
251 #define EMOTION_VERSION_MINOR 7
253 typedef struct _Emotion_Version
261 EAPI extern Emotion_Version *emotion_version;
263 /* api calls available */
266 * @brief How to create, initialize, manipulate and connect to signals of an
268 * @defgroup Emotion_API API available for manipulating Emotion object.
272 * Emotion provides an Evas smart object that allows to play, control and
273 * display a video or audio file. The API is synchronous but not everything
274 * happens immediately. There are also some signals to report changed states.
276 * Basically, once the object is created and initialized, a file will be set to
277 * it, and then it can be resized, moved, and controlled by other Evas object
280 * However, the decoding of the music and video occurs not in the Ecore main
281 * loop, but usually in another thread (this depends on the module being used).
282 * The synchronization between this other thread and the main loop not visible
283 * to the end user of the library. The user can just register callbacks to the
284 * available signals to receive information about the changed states, and can
285 * call other functions from the API to request more changes on the current
288 * There will be a delay between an API being called and it being really
289 * executed, since this request will be done in the main thread, and it needs to
290 * be sent to the decoding thread. For this reason, always call functions like
291 * emotion_object_size_get() or emotion_object_length_get() after some signal
292 * being sent, like "playback_started" or "open_done". @ref
293 * emotion_signals_example.c "This example demonstrates this behavior".
295 * @section signals Available signals
296 * The Evas_Object returned by emotion_object_add() has a number of signals that
297 * can be listened to using evas' smart callbacks mechanism. All signals have
298 * NULL as event info. The following is a list of interesting signals:
299 * @li "playback_started" - Emitted when the playback starts
300 * @li "playback_finished" - Emitted when the playback finishes
301 * @li "frame_decode" - Emitted every time a frame is decoded
302 * @li "open_done" - Emitted when the media file is opened
303 * @li "position_update" - Emitted when emotion_object_position_set is called
304 * @li "decode_stop" - Emitted after the last frame is decoded
308 * The following examples exemplify the emotion usage. There's also the
309 * emotion_test binary that is distributed with this library and cover the
310 * entire API, but since it is too long and repetitive to be explained, its code
311 * is just displayed as another example.
313 * @li @ref emotion_basic_example_c
314 * @li @ref emotion_signals_example.c "Emotion signals"
315 * @li @ref emotion_test_main.c "emotion_test - full API usage"
320 * @defgroup Emotion_Init Creation and initialization functions
324 * @defgroup Emotion_Audio Audio control functions
328 * @defgroup Emotion_Video Video control functions
332 * @defgroup Emotion_Visualization Visualization control functions
336 * @defgroup Emotion_Info Miscellaneous information retrieval functions
340 * @defgroup Emotion_Ressource Video ressource management
343 EAPI Eina_Bool emotion_init(void);
344 EAPI Eina_Bool emotion_shutdown(void);
347 * @brief Add an emotion object to the canvas.
349 * @param evas The canvas where the object will be added to.
350 * @return The emotion object just created.
352 * This function creates an emotion object and adds it to the specified @p evas.
353 * The returned object can be manipulated as any other Evas object, using the
354 * default object manipulation functions - evas_object_*.
356 * After creating the object with this function, it's still necessary to
357 * initialize it with emotion_object_init(), and if an audio file is going to be
358 * played with this object instead of a video, use
359 * emotion_object_video_mute_set().
361 * The next step is to open the desired file with emotion_object_file_set(), and
362 * start playing it with emotion_object_play_set().
364 * @see emotion_object_init()
365 * @see emotion_object_video_mute_set()
366 * @see emotion_object_file_set()
367 * @see emotion_object_play_set()
369 * @ingroup Emotion_Init
371 EAPI Evas_Object *emotion_object_add (Evas *evas);
374 * @brief Set the specified option for the current module.
376 * @param obj The emotion object which the option is being set to.
377 * @param opt The option that is being set. Currently supported optiosn: "video"
379 * @param val The value of the option. Currently only supports "off" (?!?!?!)
381 * This function allows one to mute the video or audio of the emotion object.
383 * @note Please don't use this function, consider using
384 * emotion_object_audio_mute_set() and emotion_object_video_mute_set() instead.
386 * @see emotion_object_audio_mute_set()
387 * @see emotion_object_video_mute_set()
389 * @ingroup Emotion_Init
391 EAPI void emotion_object_module_option_set (Evas_Object *obj, const char *opt, const char *val);
394 * @brief Initializes an emotion object with the specified module.
396 * @param obj The emotion object to be initialized.
397 * @param module_filename The name of the module to be used (gstreamer or xine).
398 * @return @c EINA_TRUE if the specified module was successfully initialized for
399 * this object, @c EINA_FALSE otherwise.
401 * This function is required after creating the emotion object, in order to
402 * specify which module will be used with this object. Different objects can
403 * use different modules to play a media file. The current supported modules are
404 * @b gstreamer and @b xine.
406 * To use any of them, you need to make sure that support for them was compiled
409 * @note It's possible to disable the build of a module with
410 * --disable-module_name.
412 * @see emotion_object_add()
413 * @see emotion_object_file_set()
415 * @ingroup Emotion_Init
417 EAPI Eina_Bool emotion_object_init (Evas_Object *obj, const char *module_filename);
420 * @brief Set borders for the emotion object.
422 * @param obj The emotion object where borders are being set.
423 * @param l The left border.
424 * @param r The right border.
425 * @param t The top border.
426 * @param b The bottom border.
428 * This function sets borders for the emotion video object (just when a video is
429 * present). When positive values are given to one of the parameters, a border
430 * will be added to the respective position of the object, representing that
431 * size on the original video size. However, if the video is scaled up or down
432 * (i.e. the emotion object size is different from the video size), the borders
433 * will be scaled respectively too.
435 * If a negative value is given to one of the parameters, instead of a border,
436 * that respective side of the video will be cropped.
438 * It's possible to set a color for the added borders (default is transparent)
439 * with emotion_object_bg_color_set(). By default, an Emotion object doesn't
442 * @see emotion_object_border_get()
443 * @see emotion_object_bg_color_set()
445 * @ingroup Emotion_Video
447 EAPI void emotion_object_border_set(Evas_Object *obj, int l, int r, int t, int b);
450 * @brief Get the borders set for the emotion object.
452 * @param obj The emotion object from which the borders are being retrieved.
453 * @param l The left border.
454 * @param r The right border.
455 * @param t The top border.
456 * @param b The bottom border.
458 * @see emotion_object_border_set()
460 * @ingroup Emotion_Video
462 EAPI void emotion_object_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b);
465 * @brief Set a color for the background rectangle of this emotion object.
467 * @param obj The emotion object where the background color is being set.
468 * @param r Red component of the color.
469 * @param g Green component of the color.
470 * @param b Blue component of the color.
471 * @param a Alpha channel of the color.
473 * This is useful when a border is added to any side of the Emotion object. The
474 * area between the edge of the video and the edge of the object will be filled
475 * with the specified color.
477 * The default color is 0, 0, 0, 0 (transparent).
479 * @see emotion_object_bg_color_get()
481 * @ingroup Emotion_Video
483 EAPI void emotion_object_bg_color_set(Evas_Object *obj, int r, int g, int b, int a);
486 * @brief Get the background color set for the emotion object.
488 * @param obj The emotion object from which the background color is being retrieved.
489 * @param r Red component of the color.
490 * @param g Green component of the color.
491 * @param b Blue component of the color.
492 * @param a AAlpha channel of the color.
494 * @see emotion_object_bg_color_set()
496 * @ingroup Emotion_Video
498 EAPI void emotion_object_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a);
501 * @brief Set whether emotion should keep the aspect ratio of the video.
503 * @param obj The emotion object where to set the aspect.
504 * @param a The aspect ratio policy.
506 * Instead of manually calculating the required border to set with
507 * emotion_object_border_set(), and using this to fix the aspect ratio of the
508 * video when the emotion object has a different aspect, it's possible to just
509 * set the policy to be used.
513 * - @b #EMOTION_ASPECT_KEEP_NONE - ignore the video aspect ratio, and reset any
514 * border set to 0, stretching the video inside the emotion object area. This
515 * option is similar to EVAS_ASPECT_CONTROL_NONE size hint.
516 * - @b #EMOTION_ASPECT_KEEP_WIDTH - respect the video aspect ratio, fitting the
517 * video width inside the object width. This option is similar to
518 * EVAS_ASPECT_CONTROL_HORIZONTAL size hint.
519 * - @b #EMOTION_ASPECT_KEEP_HEIGHT - respect the video aspect ratio, fitting
520 * the video height inside the object height. This option is similar to
521 * EVAS_ASPECT_CONTROL_VERTIAL size hint.
522 * - @b #EMOTION_ASPECT_KEEP_BOTH - respect the video aspect ratio, fitting both
523 * its width and height inside the object area. This option is similar to
524 * EVAS_ASPECT_CONTROL_BOTH size hint. It's the effect called letterboxing.
525 * - @b #EMOTION_ASPECT_CROP - respect the video aspect ratio, fitting the width
526 * or height inside the object area, and cropping the exceding areas of the
527 * video in height or width. It's the effect called pan-and-scan.
528 * - @b #EMOTION_ASPECT_CUSTOM - ignore the video aspect ratio, and use the
529 * current set from emotion_object_border_set().
531 * @note Calling this function with any value except #EMOTION_ASPECT_CUSTOM will
532 * invalidate borders set with emotion_object_border_set().
534 * @note Calling emotion_object_border_set() will automatically set the aspect
535 * policy to #EMOTION_ASPECT_CUSTOM.
537 * @see emotion_object_border_set()
538 * @see emotion_object_keep_aspect_get()
540 * @ingroup Emotion_Video
542 EAPI void emotion_object_keep_aspect_set(Evas_Object *obj, Emotion_Aspect a);
545 * @brief Get the current emotion aspect ratio policy.
547 * @param obj The emotion object from which we are fetching the aspect ratio
549 * @return The current aspect ratio policy.
551 * @see emotion_object_keep_aspect_set()
553 * @ingroup Emotion_Video
555 EAPI Emotion_Aspect emotion_object_keep_aspect_get(const Evas_Object *obj);
558 * @brief Set the file to be played in the Emotion object.
560 * @param obj The emotion object where the file is being loaded.
561 * @param filename Path to the file to be loaded. It can be absolute or relative
563 * @return EINA_TRUE if the new file could be loaded successfully, and
564 * EINA_FALSE if the file could not be loaded. This happens when the filename is
565 * could not be found, when the module couldn't open the file, when no module is
566 * initialized in this object, or when the @p filename is the same as the
567 * one previously set.
569 * This function sets the file to be used with this emotion object. If the
570 * object already has another file set, this file will be unset and unloaded,
571 * and the new file will be loaded to this emotion object. The seek position
572 * will be set to 0, and the emotion object will be paused, instead of playing.
574 * If there was already a filename set, and it's the same as the one being set
575 * now, this function does nothing and returns EINA_FALSE.
577 * Use @c NULL as argument to @p filename if you want to unload the current file
578 * but don't want to load anything else.
580 * @see emotion_object_init()
581 * @see emotion_object_play_set()
582 * @see emotion_object_file_get()
584 * @ingroup Emotion_Init
586 EAPI Eina_Bool emotion_object_file_set (Evas_Object *obj, const char *filename);
589 * @brief Get the filename of the file associated with the emotion object.
591 * @param obj The emotion object from which the filename will be retrieved.
592 * @return The path to the file loaded into this emotion object.
594 * This function returns the path of the file loaded in this emotion object. If
595 * no object is loaded, it will return @c NULL.
597 * @note Don't free or change the string returned by this function in any way.
598 * If you want to unset it, use @c emotion_object_file_set(obj, NULL).
600 * @see emotion_object_file_set()
602 * @ingroup Emotion_Init
604 EAPI const char *emotion_object_file_get (const Evas_Object *obj);
606 * @defgroup Emotion_Play Play control functions
612 * @brief Set play/pause state of the media file.
614 * @param obj The emotion object whose state will be changed.
615 * @param play EINA_TRUE to play, EINA_FALSE to pause.
617 * This functions sets the currently playing status of the video. Using this
618 * function to play or pause the video doesn't alter it's current position.
620 EAPI void emotion_object_play_set (Evas_Object *obj, Eina_Bool play);
622 * @brief Get play/pause state of the media file.
624 * @param obj The emotion object from which the state will be retrieved.
625 * @return EINA_TRUE if playing. EINA_FALSE if not playing.
627 EAPI Eina_Bool emotion_object_play_get (const Evas_Object *obj);
629 * @brief Set the position in the media file.
631 * @param obj The emotion object whose position will be changed.
632 * @param sec The position(in seconds) to which the media file will be set.
634 * This functions sets the current position of the media file to @p sec, this
635 * only works on seekable streams. Setting the position doesn't change the
636 * playing state of the media file.
638 * @see emotion_object_seekable_get
640 EAPI void emotion_object_position_set (Evas_Object *obj, double sec);
642 * @brief Get the position in the media file.
644 * @param obj The emotion object from which the position will be retrieved.
645 * @return The position of the media file.
647 * The position is returned as the number of seconds since the beginning of the
650 EAPI double emotion_object_position_get (const Evas_Object *obj);
653 * @brief Get the percentual size of the buffering cache.
655 * @param obj The emotion object from which the buffer size will be retrieved.
656 * @return The buffer percent size, ranging from 0.0 to 1.0
658 * The buffer size is returned as a number between 0.0 and 1.0, 0.0 means
659 * the buffer if empty, 1.0 means full.
660 * If no buffering is in progress 1.0 is returned. In all other cases (maybe
661 * the backend don't support buffering) 1.0 is returned, thus you can always
662 * check for buffer_size < 1.0 to know if buffering is in progress.
664 * @warning Generic backend don't implement this (will return 1.0).
666 EAPI double emotion_object_buffer_size_get (const Evas_Object *obj);
669 * @brief Get whether the media file is seekable.
671 * @param obj The emotion object from which the seekable status will be
673 * @return EINA_TRUE if the media file is seekable, EINA_FALSE otherwise.
675 EAPI Eina_Bool emotion_object_seekable_get (const Evas_Object *obj);
677 * @brief Get the length of play for the media file.
679 * @param obj The emotion object from which the length will be retrieved.
680 * @return The length of the media file in seconds.
682 * This function returns the length of the media file in seconds.
684 * @warning This will return 0 if called before the "length_change" signal has,
687 EAPI double emotion_object_play_length_get (const Evas_Object *obj);
690 * @brief Set the play speed of the media file.
692 * @param obj The emotion object whose speed will be set.
693 * @param speed The speed to be set in the range [0,infinity)
695 * This function sets the speed with which the media file will be played. 1.0
696 * represents the normal speed, 2 double speed, 0.5 half speed and so on.
698 * @warning The only backend that implements this is the experimental VLC
701 EAPI void emotion_object_play_speed_set (Evas_Object *obj, double speed);
703 * @brief Get the play speed of the media file.
705 * @param obj The emotion object from which the filename will be retrieved.
706 * @return The current speed of the media file.
708 * @see emotion_object_play_speed_set
710 EAPI double emotion_object_play_speed_get (const Evas_Object *obj);
712 * @brief Get how much of the file has been played.
714 * @param obj The emotion object from which the filename will be retrieved.
715 * @return The progress of the media file.
717 * @warning Don't change of free the returned string.
718 * @warning gstreamer xine backends don't implement this(will return NULL).
720 EAPI const char *emotion_object_progress_info_get (const Evas_Object *obj);
722 * @brief Get how much of the file has been played.
724 * @param obj The emotion object from which the filename will be retrieved
725 * @return The progress of the media file.
727 * This function gets the progress in playing the file, the return value is in
730 * @warning gstreamer xine backends don't implement this(will return 0).
732 EAPI double emotion_object_progress_status_get (const Evas_Object *obj);
736 EAPI Eina_Bool emotion_object_video_handled_get (const Evas_Object *obj);
737 EAPI Eina_Bool emotion_object_audio_handled_get (const Evas_Object *obj);
740 * @brief Retrieve the video aspect ratio of the media file loaded.
742 * @param obj The emotion object which the video aspect ratio will be retrieved
744 * @return The video aspect ratio of the file loaded.
746 * This function returns the video aspect ratio (width / height) of the file
747 * loaded. It can be used to adapt the size of the emotion object in the canvas,
748 * so the aspect won't be changed (by wrongly resizing the object). Or to crop
749 * the video correctly, if necessary.
751 * The described behavior can be applied like following. Consider a given
752 * emotion object that we want to position inside an area, which we will
753 * represent by @c w and @c h. Since we want to position this object either
754 * stretching, or filling the entire area but overflowing the video, or just
755 * adjust the video to fit inside the area without keeping the aspect ratio, we
756 * must compare the video aspect ratio with the area aspect ratio:
758 * int w = 200, h = 300; // an arbitrary value which represents the area where
759 * // the video would be placed
761 * double r, vr = emotion_object_ratio_get(obj);
765 * Now, if we want to make the video fit inside the area, the following code
768 * if (vr > r) // the video is wider than the area
773 * else // the video is taller than the area
778 * evas_object_resize(obj, vw, vh);
781 * And for keeping the aspect ratio but making the video fill the entire area,
782 * overflowing the content which can't fit inside it, we would do:
784 * if (vr > r) // the video is wider than the area
789 * else // the video is taller than the area
794 * evas_object_resize(obj, vw, vh);
797 * Finally, by just resizing the video to the video area, we would have the
802 * evas_object_resize(obj, vw, vh);
805 * The following diagram exemplifies what would happen to the video,
806 * respectively, in each case:
808 * @image html emotion_ratio.png
809 * @image latex emotion_ratio.eps width=\textwidth
811 * @note This function returns the aspect ratio that the video @b should be, but
812 * sometimes the reported size from emotion_object_size_get() represents a
813 * different aspect ratio. You can safely resize the video to respect the aspect
814 * ratio returned by @b this function.
816 * @see emotion_object_size_get()
818 * @ingroup Emotion_Video
820 EAPI double emotion_object_ratio_get (const Evas_Object *obj);
823 * @brief Retrieve the video size of the loaded file.
825 * @param obj The object from which we are retrieving the video size.
826 * @param iw A pointer to a variable where the width will be stored.
827 * @param ih A pointer to a variable where the height will be stored.
829 * This function returns the reported size of the loaded video file. If a file
830 * that doesn't contain a video channel is loaded, then this size can be
833 * The value reported by this function should be consistent with the aspect
834 * ratio returned by emotion_object_ratio_get(), but sometimes the information
835 * stored in the file is wrong. So use the ratio size reported by
836 * emotion_object_ratio_get(), since it is more likely going to be accurate.
838 * @note Use @c NULL for @p iw or @p ih if you don't need one of these values.
840 * @see emotion_object_ratio_get()
842 * @ingroup Emotion_Video
844 EAPI void emotion_object_size_get (const Evas_Object *obj, int *iw, int *ih);
847 * @brief Sets whether to use of high-quality image scaling algorithm
848 * of the given video object.
850 * When enabled, a higher quality video scaling algorithm is used when
851 * scaling videos to sizes other than the source video. This gives
852 * better results but is more computationally expensive.
854 * @param obj The given video object.
855 * @param smooth Whether to use smooth scale or not.
857 * @see emotion_object_smooth_scale_get()
859 * @ingroup Emotion_Video
861 EAPI void emotion_object_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth);
864 * @brief Gets whether the high-quality image scaling algorithm
865 * of the given video object is used.
867 * @param obj The given video object.
868 * @return Whether the smooth scale is used or not.
870 * @see emotion_object_smooth_scale_set()
872 * @ingroup Emotion_Video
874 EAPI Eina_Bool emotion_object_smooth_scale_get (const Evas_Object *obj);
875 EAPI void emotion_object_event_simple_send (Evas_Object *obj, Emotion_Event ev);
878 * @brief Set the audio volume.
880 * @param obj The object where the volume is being set.
881 * @param vol The new volume parameter. Range is from 0.0 to 1.0.
883 * Sets the audio volume of the stream being played. This has nothing to do with
884 * the system volume. This volume will be multiplied by the system volume. e.g.:
885 * if the current volume level is 0.5, and the system volume is 50%, it will be
888 * The default value depends on the module used. This value doesn't get changed
889 * when another file is loaded.
891 * @see emotion_object_audio_volume_get()
893 * @ingroup Emotion_Audio
895 EAPI void emotion_object_audio_volume_set (Evas_Object *obj, double vol);
898 * @brief Get the audio volume.
900 * @param obj The object from which we are retrieving the volume.
901 * @return The current audio volume level for this object.
903 * Get the current value for the audio volume level. Range is from 0.0 to 1.0.
904 * This volume is set with emotion_object_audio_volume_set().
906 * @see emotion_object_audio_volume_set()
908 * @ingroup Emotion_Audio
910 EAPI double emotion_object_audio_volume_get (const Evas_Object *obj);
913 * @brief Set the mute audio option for this object.
915 * @param obj The object which we are setting the mute audio option.
916 * @param mute Whether the audio should be muted (@c EINA_TRUE) or not (@c
919 * This function sets the mute audio option for this emotion object. The current
920 * module used for this object can use this to avoid decoding the audio portion
921 * of the loaded media file.
923 * @see emotion_object_audio_mute_get()
924 * @see emotion_object_video_mute_set()
926 * @ingroup Emotion_Audio
928 EAPI void emotion_object_audio_mute_set (Evas_Object *obj, Eina_Bool mute);
931 * @brief Get the mute audio option of this object.
933 * @param obj The object which we are retrieving the mute audio option from.
934 * @return Whether the audio is muted (@c EINA_TRUE) or not (@c EINA_FALSE).
936 * This function return the mute audio option from this emotion object. It can
937 * be set with emotion_object_audio_mute_set().
939 * @see emotion_object_audio_mute_set()
941 * @ingroup Emotion_Audio
943 EAPI Eina_Bool emotion_object_audio_mute_get (const Evas_Object *obj);
944 EAPI int emotion_object_audio_channel_count (const Evas_Object *obj);
945 EAPI const char *emotion_object_audio_channel_name_get(const Evas_Object *obj, int channel);
946 EAPI void emotion_object_audio_channel_set (Evas_Object *obj, int channel);
947 EAPI int emotion_object_audio_channel_get (const Evas_Object *obj);
950 * @brief Set the mute video option for this object.
952 * @param obj The object which we are setting the mute video option.
953 * @param mute Whether the video should be muted (@c EINA_TRUE) or not (@c
956 * This function sets the mute video option for this emotion object. The
957 * current module used for this object can use this information to avoid
958 * decoding the video portion of the loaded media file.
960 * @see emotion_object_video_mute_get()
961 * @see emotion_object_audio_mute_set()
963 * @ingroup Emotion_Video
965 EAPI void emotion_object_video_mute_set (Evas_Object *obj, Eina_Bool mute);
968 * @brief Get the mute video option of this object.
970 * @param obj The object which we are retrieving the mute video option from.
971 * @return Whether the video is muted (@c EINA_TRUE) or not (@c EINA_FALSE).
973 * This function returns the mute video option from this emotion object. It can
974 * be set with emotion_object_video_mute_set().
976 * @see emotion_object_video_mute_set()
978 * @ingroup Emotion_Video
980 EAPI Eina_Bool emotion_object_video_mute_get (const Evas_Object *obj);
983 * @brief Get the number of available video channel
985 * @param obj The object which we are retrieving the channel count from
986 * @return the number of available channel.
988 * @see emotion_object_video_channel_name_get()
990 * @ingroup Emotion_Video
992 EAPI int emotion_object_video_channel_count (const Evas_Object *obj);
993 EAPI const char *emotion_object_video_channel_name_get(const Evas_Object *obj, int channel);
994 EAPI void emotion_object_video_channel_set (Evas_Object *obj, int channel);
995 EAPI int emotion_object_video_channel_get (const Evas_Object *obj);
996 EAPI void emotion_object_spu_mute_set (Evas_Object *obj, Eina_Bool mute);
997 EAPI Eina_Bool emotion_object_spu_mute_get (const Evas_Object *obj);
998 EAPI int emotion_object_spu_channel_count (const Evas_Object *obj);
999 EAPI const char *emotion_object_spu_channel_name_get (const Evas_Object *obj, int channel);
1000 EAPI void emotion_object_spu_channel_set (Evas_Object *obj, int channel);
1001 EAPI int emotion_object_spu_channel_get (const Evas_Object *obj);
1002 EAPI int emotion_object_chapter_count (const Evas_Object *obj);
1003 EAPI void emotion_object_chapter_set (Evas_Object *obj, int chapter);
1004 EAPI int emotion_object_chapter_get (const Evas_Object *obj);
1005 EAPI const char *emotion_object_chapter_name_get (const Evas_Object *obj, int chapter);
1006 EAPI void emotion_object_eject (Evas_Object *obj);
1009 * @brief Get the dvd title from this emotion object.
1011 * @param obj The object which the title will be retrieved from.
1012 * @return A string containing the title.
1014 * This function is only useful when playing a DVD.
1016 * @note Don't change or free the string returned by this function.
1018 * @ingroup Emotion_Info
1020 EAPI const char *emotion_object_title_get (const Evas_Object *obj);
1021 EAPI const char *emotion_object_ref_file_get (const Evas_Object *obj);
1022 EAPI int emotion_object_ref_num_get (const Evas_Object *obj);
1023 EAPI int emotion_object_spu_button_count_get (const Evas_Object *obj);
1024 EAPI int emotion_object_spu_button_get (const Evas_Object *obj);
1027 * @brief Retrieve meta information from this file being played.
1029 * @param obj The object which the meta info will be extracted from.
1030 * @param meta The type of meta information that will be extracted.
1032 * This function retrieves information about the file loaded. It can retrieve
1033 * the track title, artist name, album name, etc. See @ref Emotion_Meta_Info
1034 * for all the possibilities.
1036 * The meta info may be not available on all types of files. It will return @c
1037 * NULL if the the file doesn't have meta info, or if this specific field is
1040 * @note Don't change or free the string returned by this function.
1042 * @see Emotion_Meta_Info
1044 * @ingroup Emotion_Info
1046 EAPI const char *emotion_object_meta_info_get (const Evas_Object *obj, Emotion_Meta_Info meta);
1049 * @brief Set the visualization to be used with this object.
1051 * @param obj The object where the visualization will be set on.
1052 * @param visualization The type of visualization to be used.
1054 * The @p visualization specified will be played instead of a video. This is
1055 * commonly used to display a visualization for audio only files (musics).
1057 * The available visualizations are @ref Emotion_Vis.
1060 * @see emotion_object_vis_get()
1061 * @see emotion_object_vis_supported()
1063 * @ingroup Emotion_Visualization
1065 EAPI void emotion_object_vis_set (Evas_Object *obj, Emotion_Vis visualization);
1068 * @brief Get the type of visualization in use by this emotion object.
1070 * @param obj The emotion object which the visualization is being retrieved
1072 * @return The type of visualization in use by this object.
1074 * The type of visualization can be set by emotion_object_vis_set().
1077 * @see emotion_object_vis_set()
1078 * @see emotion_object_vis_supported()
1080 * @ingroup Emotion_Visualization
1082 EAPI Emotion_Vis emotion_object_vis_get (const Evas_Object *obj);
1085 * @brief Query whether a type of visualization is supported by this object.
1087 * @param obj The object which the query is being ran on.
1088 * @param visualization The type of visualization that is being queried.
1089 * @return EINA_TRUE if the visualization is supported, EINA_FALSE otherwise.
1091 * This can be used to check if a visualization is supported. e.g.: one wants to
1092 * display a list of available visualizations for a specific object.
1095 * @see emotion_object_vis_set()
1096 * @see emotion_object_vis_get()
1098 * @ingroup Emotion_Visualization
1100 EAPI Eina_Bool emotion_object_vis_supported (const Evas_Object *obj, Emotion_Vis visualization);
1103 * @brief Raise priority of an object so it will have a priviledged access to hardware ressource.
1105 * @param obj The object which the query is being ran on.
1106 * @param priority EINA_TRUE means give me a priority access to the hardware ressource.
1108 * Hardware have a few dedicated hardware pipeline that process the video at no cost for the CPU.
1109 * Especially on SoC, you mostly have one (on mobile phone SoC) or two (on Set Top Box SoC) when
1110 * Picture in Picture is needed. And most application just have a few video stream that really
1111 * deserve high frame rate, hiogh quality output. That's why this call is for.
1113 * Please note that if Emotion can't acquire a priviledged hardware ressource, it will fallback
1114 * to the no-priority path. This work on the first asking first get basis system.
1116 * @see emotion_object_priority_get()
1118 * @ingroup Emotion_Ressource
1120 EAPI void emotion_object_priority_set(Evas_Object *obj, Eina_Bool priority);
1123 * @brief Get the actual priority of an object.
1125 * @param obj The object which the query is being ran on.
1126 * @return EINA_TRUE if the object has a priority access to the hardware.
1128 * This actually return the priority status of an object. If it failed to have a priviledged
1129 * access to the hardware, it will return EINA_FALSE.
1131 * @see emotion_object_priority_get()
1133 * @ingroup Emotion_Ressource
1135 EAPI Eina_Bool emotion_object_priority_get(const Evas_Object *obj);
1138 * @brief Change the state of an object pipeline.
1140 * @param obj The object which the query is being ran on.
1141 * @param state The new state for the object.
1143 * Changing the state of a pipeline should help preserve the battery of an embedded device.
1144 * But it will only work sanely if the pipeline is not playing at the time you change its
1145 * state. Depending on the engine all state may be not implemented.
1147 * @see Emotion_Suspend
1148 * @see emotion_object_suspend_get()
1150 * @ingroup Emotion_Ressource
1152 EAPI void emotion_object_suspend_set(Evas_Object *obj, Emotion_Suspend state);
1155 * @brief Get the current state of the pipeline
1157 * @param obj The object which the query is being ran on.
1158 * @return the current state of the pipeline.
1160 * @see Emotion_Suspend
1161 * @see emotion_object_suspend_set()
1163 * @ingroup Emotion_Ressource
1165 EAPI Emotion_Suspend emotion_object_suspend_get(Evas_Object *obj);
1168 * @brief Load the last known position if available
1170 * @param obj The object which the query is being ran on.
1172 * By using Xattr, Emotion is able, if the system permitt it, to store and retrieve
1173 * the latest position. It should trigger some smart callback to let the application
1174 * know when it succeed or fail. Every operation is fully asynchronous and not
1175 * linked to the actual engine used to play the vide.
1177 * @see emotion_object_last_position_save()
1179 * @ingroup Emotion_Info
1181 EAPI void emotion_object_last_position_load(Evas_Object *obj);
1184 * @brief Save the lastest position if possible
1186 * @param obj The object which the query is being ran on.
1188 * By using Xattr, Emotion is able, if the system permitt it, to store and retrieve
1189 * the latest position. It should trigger some smart callback to let the application
1190 * know when it succeed or fail. Every operation is fully asynchronous and not
1191 * linked to the actual engine used to play the vide.
1193 * @see emotion_object_last_position_load()
1195 * @ingroup Emotion_Info
1197 EAPI void emotion_object_last_position_save(Evas_Object *obj);
1200 * @brief Do we have a chance to play that file
1202 * @param file A stringshared filename that we want to know if Emotion can play.
1204 * This just actually look at the extention of the file, it doesn't check the mime-type
1205 * nor if the file is actually sane. So this is just an hint for your application.
1207 * @see emotion_object_extension_may_play_get()
1209 EAPI Eina_Bool emotion_object_extension_may_play_fast_get(const char *file);
1212 * @brief Do we have a chance to play that file
1214 * @param file A filename that we want to know if Emotion can play.
1216 * This just actually look at the extention of the file, it doesn't check the mime-type
1217 * nor if the file is actually sane. So this is just an hint for your application.
1219 * @see emotion_object_extension_may_play_fast_get()
1221 EAPI Eina_Bool emotion_object_extension_may_play_get(const char *file);
1224 * @brief Get the actual image object that contains the pixels of the video stream
1226 * @param obj The object which the query is being ran on.
1228 * This function is usefull when you want to get a direct access to the pixels.
1230 * @see emotion_object_image_get()
1232 EAPI Evas_Object *emotion_object_image_get(const Evas_Object *obj);
1235 * @defgroup Emotion_Webcam API available for accessing webcam
1238 typedef struct _Emotion_Webcam Emotion_Webcam; /**< Webcam description */
1240 EAPI extern int EMOTION_WEBCAM_UPDATE; /**< Ecore_Event triggered when a new webcam is plugged in */
1243 * @brief Get a list of active and available webcam
1245 * @return the list of available webcam at the time of the call.
1247 * It will return the current live list of webcam. It is updated before
1248 * triggering EMOTION_WEBCAM_UPDATE and should never be modified.
1250 * @ingroup Emotion_Webcam
1252 EAPI const Eina_List *emotion_webcams_get(void);
1255 * @brief Get the human understandable name of a Webcam
1257 * @param ew The webcam to get the name from.
1258 * @return the actual human readable name.
1260 * @ingroup Emotion_Webcam
1262 EAPI const char *emotion_webcam_name_get(const Emotion_Webcam *ew);
1265 * @brief Get the uri of a Webcam that will be understood by emotion
1267 * @param ew The webcam to get the uri from.
1268 * @return the actual uri that emotion will later understood.
1270 * @ingroup Emotion_Webcam
1272 EAPI const char *emotion_webcam_device_get(const Emotion_Webcam *ew);