src/lib/Emotion.h

   1 #ifndef EMOTION_H
   2 #define EMOTION_H
   3
   4 /**
   5  * @file
   6  * @brief Emotion Media Library
   7  *
   8  * These routines are used for Emotion.
   9  */
  10
  11 /**
  12  *
  13  * @mainpage Emotion Library Documentation
  14  *
  15  * @version 0.2.0
  16  * @date 2003-2011
  17  *
  18  * @section intro What is Emotion?
  19  *
  20  * A media object library for Evas and Ecore.
  21  *
  22  * Emotion is a library that allows playing audio and video files, using one of
  23  * its backends (gstreamer or xine).
  24  *
  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).
  29  *
  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().
  34  *
  35  * @section work How does Emotion work?
  36  *
  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.
  42  *
  43  * To instantiate an Emotion object, the simple code below is enough:
  44  *
  45  * @code
  46  * em = emotion_object_add(e);
  47  * emotion_object_init(em, NULL);
  48  *
  49  * emotion_object_file_set(em, file_path);
  50  *
  51  * evas_object_move(em, 0, 0);
  52  * evas_object_resize(em, WIDTH, HEIGHT);
  53  * evas_object_show(em);
  54  *
  55  * emotion_object_play_set(em, EINA_TRUE);
  56  * @endcode
  57  *
  58  * See the @ref Emotion_API for a better reference.
  59  *
  60  * Please see the @ref authors page for contact details.
  61  *
  62  */
  63
  64 /**
  65  *
  66  * @page authors Authors
  67  *
  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>
  73  *
  74  * Please contact <enlightenment-devel@lists.sourceforge.net> to get in
  75  * contact with the developers and maintainers.
  76  *
  77  */
  78
  79 #include <Evas.h>
  80
  81 #ifdef EAPI
  82 # undef EAPI
  83 #endif
  84
  85 #ifdef _WIN32
  86 # ifdef EFL_EMOTION_BUILD
  87 #  ifdef DLL_EXPORT
  88 #   define EAPI __declspec(dllexport)
  89 #  else
  90 #   define EAPI
  91 #  endif /* ! DLL_EXPORT */
  92 # else
  93 #  define EAPI __declspec(dllimport)
  94 # endif /* ! EFL_EMOTION_BUILD */
  95 #else
  96 # ifdef __GNUC__
  97 #  if __GNUC__ >= 4
  98 #   define EAPI __attribute__ ((visibility("default")))
  99 #  else
 100 #   define EAPI
 101 #  endif
 102 # else
 103 #  define EAPI
 104 # endif
 105 #endif /* ! _WIN32 */
 106
 107 /**
 108  * @file Emotion.h
 109  * @brief The file that provides Emotion the API, with functions available for
 110  *        play, seek, change volume, etc.
 111  */
 112
 113 enum _Emotion_Module
 114 {
 115   EMOTION_MODULE_XINE,
 116   EMOTION_MODULE_GSTREAMER
 117 };
 118
 119 enum _Emotion_Event
 120 {
 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
 128    EMOTION_EVENT_UP,
 129    EMOTION_EVENT_DOWN,
 130    EMOTION_EVENT_LEFT,
 131    EMOTION_EVENT_RIGHT,
 132    EMOTION_EVENT_SELECT,
 133    EMOTION_EVENT_NEXT,
 134    EMOTION_EVENT_PREV,
 135    EMOTION_EVENT_ANGLE_NEXT,
 136    EMOTION_EVENT_ANGLE_PREV,
 137    EMOTION_EVENT_FORCE,
 138    EMOTION_EVENT_0,
 139    EMOTION_EVENT_1,
 140    EMOTION_EVENT_2,
 141    EMOTION_EVENT_3,
 142    EMOTION_EVENT_4,
 143    EMOTION_EVENT_5,
 144    EMOTION_EVENT_6,
 145    EMOTION_EVENT_7,
 146    EMOTION_EVENT_8,
 147    EMOTION_EVENT_9,
 148    EMOTION_EVENT_10
 149 };
 150
 151 /**
 152  * @enum _Emotion_Meta_Info
 153  *
 154  * Used for retrieving information about the media file being played.
 155  *
 156  * @see emotion_object_meta_info_get()
 157  *
 158  * @ingroup Emotion_Info
 159  */
 160 enum _Emotion_Meta_Info
 161 {
 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 */
 170 };
 171
 172 /**
 173  * @enum _Emotion_Vis
 174  *
 175  * Used for displaying a visualization on the emotion object.
 176  *
 177  * @see emotion_object_vis_set()
 178  *
 179  * @ingroup Emotion_Visualization
 180  */
 181 enum _Emotion_Vis
 182 {
 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 */
 203 };
 204
 205 typedef enum
 206 {
 207   EMOTION_WAKEUP,
 208   EMOTION_SLEEP,
 209   EMOTION_DEEP_SLEEP,
 210   EMOTION_HIBERNATE
 211 } Emotion_Suspend;
 212
 213 typedef enum _Emotion_Module    Emotion_Module;
 214 typedef enum _Emotion_Event     Emotion_Event;
 215 typedef enum _Emotion_Meta_Info Emotion_Meta_Info; /**< Meta info type to be retrieved. */
 216 typedef enum _Emotion_Vis       Emotion_Vis; /**< Type of visualization. */
 217
 218 #define EMOTION_CHANNEL_AUTO -1
 219 #define EMOTION_CHANNEL_DEFAULT 0
 220
 221 #ifdef __cplusplus
 222 extern "C" {
 223 #endif
 224
 225 /* api calls available */
 226
 227 /**
 228  * @brief How to create, initialize, manipulate and connect to signals of an
 229  * Emotion object.
 230  * @defgroup Emotion_API API available for manipulating Emotion object.
 231  *
 232  * @{
 233  *
 234  * Emotion provides an Evas smart object that allows to play, control and
 235  * display a video or audio file. The API is synchronous but not everything
 236  * happens immediately. There are also some signals to report changed states.
 237  *
 238  * Basically, once the object is created and initialized, a file will be set to
 239  * it, and then it can be resized, moved, and controlled by other Evas object
 240  * functions.
 241  *
 242  * However, the decoding of the music and video occurs not in the Ecore main
 243  * loop, but usually in another thread (this depends on the module being used).
 244  * The synchronization between this other thread and the main loop not visible
 245  * to the end user of the library. The user can just register callbacks to the
 246  * available signals to receive information about the changed states, and can
 247  * call other functions from the API to request more changes on the current
 248  * loaded file.
 249  *
 250  * There will be a delay between an API being called and it being really
 251  * executed, since this request will be done in the main thread, and it needs to
 252  * be sent to the decoding thread. For this reason, always call functions like
 253  * emotion_object_size_get() or emotion_object_length_get() after some signal
 254  * being sent, like "playback_started" or "open_done". @ref
 255  * emotion_signals_example.c "This example demonstrates this behavior".
 256  *
 257  * @section signals Available signals
 258  * The Evas_Object returned by emotion_object_add() has a number of signals that
 259  * can be listened to using evas' smart callbacks mechanism. All signals have
 260  * NULL as event info. The following is a list of interesting signals:
 261  * @li "playback_started" - Emitted when the playback starts
 262  * @li "playback_finished" - Emitted when the playback finishes
 263  * @li "frame_decode" - Emitted every time a frame is decoded
 264  * @li "open_done" - Emitted when the media file is opened
 265  * @li "position_update" - Emitted when emotion_object_position_set is called
 266  * @li "decode_stop" - Emitted after the last frame is decoded
 267  *
 268  * @section Examples
 269  *
 270  * The following examples exemplify the emotion usage. There's also the
 271  * emotion_test binary that is distributed with this library and cover the
 272  * entire API, but since it is too long and repetitive to be explained, its code
 273  * is just displayed as another example.
 274  *
 275  * @li @ref emotion_basic_example_c
 276  * @li @ref emotion_signals_example.c "Emotion signals"
 277  * @li @ref emotion_test_main.c "emotion_test - full API usage"
 278  *
 279  */
 280
 281 /**
 282  * @defgroup Emotion_Init Creation and initialization functions
 283  */
 284
 285 /**
 286  * @defgroup Emotion_Audio Audio control functions
 287  */
 288
 289 /**
 290  * @defgroup Emotion_Video Video control functions
 291  */
 292
 293 /**
 294  * @defgroup Emotion_Visualization Visualization control functions
 295  */
 296
 297 /**
 298  * @defgroup Emotion_Info Miscellaneous information retrieval functions
 299  */
 300
 301 EAPI Eina_Bool emotion_init(void);
 302 EAPI Eina_Bool emotion_shutdown(void);
 303
 304 /**
 305  * @brief Add an emotion object to the canvas.
 306  *
 307  * @param evas The canvas where the object will be added to.
 308  * @return The emotion object just created.
 309  *
 310  * This function creates an emotion object and adds it to the specified @p evas.
 311  * The returned object can be manipulated as any other Evas object, using the
 312  * default object manipulation functions - evas_object_*.
 313  *
 314  * After creating the object with this function, it's still necessary to
 315  * initialize it with emotion_object_init(), and if an audio file is going to be
 316  * played with this object instead of a video, use
 317  * emotion_object_video_mute_set().
 318  *
 319  * The next step is to open the desired file with emotion_object_file_set(), and
 320  * start playing it with emotion_object_play_set().
 321  *
 322  * @see emotion_object_init()
 323  * @see emotion_object_video_mute_set()
 324  * @see emotion_object_file_set()
 325  * @see emotion_object_play_set()
 326  *
 327  * @ingroup Emotion_Init
 328  */
 329 EAPI Evas_Object *emotion_object_add                   (Evas *evas);
 330
 331 /**
 332  * @brief Set the specified option for the current module.
 333  *
 334  * @param obj The emotion object which the option is being set to.
 335  * @param opt The option that is being set. Currently supported optiosn: "video"
 336  * and "audio".
 337  * @param val The value of the option. Currently only supports "off" (?!?!?!)
 338  *
 339  * This function allows one to mute the video or audio of the emotion object.
 340  *
 341  * @note Please don't use this function, consider using
 342  * emotion_object_audio_mute_set() and emotion_object_video_mute_set() instead.
 343  *
 344  * @see emotion_object_audio_mute_set()
 345  * @see emotion_object_video_mute_set()
 346  *
 347  * @ingroup Emotion_Audio
 348  * @ingroup Emotion_Video
 349  */
 350 EAPI void         emotion_object_module_option_set     (Evas_Object *obj, const char *opt, const char *val);
 351
 352 /**
 353  * @brief Initializes an emotion object with the specified module.
 354  *
 355  * @param obj The emotion object to be initialized.
 356  * @param module_filename The name of the module to be used (gstreamer or xine).
 357  * @return @c EINA_TRUE if the specified module was successfully initialized for
 358  * this object, @c EINA_FALSE otherwise.
 359  *
 360  * This function is required after creating the emotion object, in order to
 361  * specify which module will be used with this object. Different objects can
 362  * use different modules to play a media file. The current supported modules are
 363  * @b gstreamer and @b xine.
 364  *
 365  * To use any of them, you need to make sure that support for them was compiled
 366  * correctly.
 367  *
 368  * @note It's possible to disable the build of a module with
 369  * --disable-module_name.
 370  *
 371  * @see emotion_object_add()
 372  * @see emotion_object_file_set()
 373  *
 374  * @ingroup Emotion_Init
 375  */
 376 EAPI Eina_Bool    emotion_object_init                  (Evas_Object *obj, const char *module_filename);
 377
 378 /**
 379  * @brief Set the file to be played in the Emotion object.
 380  *
 381  * @param obj The emotion object where the file is being loaded.
 382  * @param filename Path to the file to be loaded. It can be absolute or relative
 383  * path.
 384  * @return EINA_TRUE if the new file could be loaded successfully, and
 385  * EINA_FALSE if the file could not be loaded. This happens when the filename is
 386  * could not be found, when the module couldn't open the file, when no module is
 387  * initialized in this object, or when the @p filename is the same as the
 388  * one previously set.
 389  *
 390  * This function sets the file to be used with this emotion object. If the
 391  * object already has another file set, this file will be unset and unloaded,
 392  * and the new file will be loaded to this emotion object. The seek position
 393  * will be set to 0, and the emotion object will be paused, instead of playing.
 394  *
 395  * If there was already a filename set, and it's the same as the one being set
 396  * now, this function does nothing and returns EINA_FALSE.
 397  *
 398  * Use @c NULL as argument to @p filename if you want to unload the current file
 399  * but don't want to load anything else.
 400  *
 401  * @see emotion_object_init()
 402  * @see emotion_object_play_set()
 403  * @see emotion_object_file_get()
 404  *
 405  * @ingroup Emotion_Init
 406  */
 407 EAPI Eina_Bool    emotion_object_file_set              (Evas_Object *obj, const char *filename);
 408
 409 /**
 410  * @brief Get the filename of the file associated with the emotion object.
 411  *
 412  * @param obj The emotion object from which the filename will be retrieved.
 413  * @return The path to the file loaded into this emotion object.
 414  *
 415  * This function returns the path of the file loaded in this emotion object. If
 416  * no object is loaded, it will return @c NULL.
 417  *
 418  * @note Don't free or change the string returned by this function in any way.
 419  * If you want to unset it, use @c emotion_object_file_set(obj, NULL).
 420  *
 421  * @see emotion_object_file_set()
 422  *
 423  * @ingroup Emotion_Init
 424  */
 425 EAPI const char  *emotion_object_file_get              (const Evas_Object *obj);
 426 /**
 427  * @defgroup Emotion_Play Play control functions
 428  *
 429  * @{
 430  */
 431 /**
 432  *
 433  * @brief Set play/pause state of the media file.
 434  *
 435  * @param obj The emotion object whose state will be changed.
 436  * @param play EINA_TRUE to play, EINA_FALSE to pause.
 437  *
 438  * This functions sets the currently playing status of the video. Using this
 439  * function to play or pause the video doesn't alter it's current position.
 440  */
 441 EAPI void         emotion_object_play_set              (Evas_Object *obj, Eina_Bool play);
 442 /**
 443  * @brief Get play/pause state of the media file.
 444  *
 445  * @param obj The emotion object from which the state will be retrieved.
 446  * @return EINA_TRUE if playing. EINA_FALSE if not playing.
 447  */
 448 EAPI Eina_Bool    emotion_object_play_get              (const Evas_Object *obj);
 449 /**
 450  * @brief Set the position in the media file.
 451  *
 452  * @param obj The emotion object whose position will be changed.
 453  * @param sec The position(in seconds) to which the media file will be set.
 454  *
 455  * This functions sets the current position of the media file to @p sec, this
 456  * only works on seekable streams. Setting the position doesn't change the
 457  * playing state of the media file.
 458  *
 459  * @see emotion_object_seekable_get
 460  */
 461 EAPI void         emotion_object_position_set          (Evas_Object *obj, double sec);
 462 /**
 463  * @brief Get the position in the media file.
 464  *
 465  * @param obj The emotion object from which the position will be retrieved.
 466  * @return The position of the media file.
 467  *
 468  * The position is returned as the number of seconds since the beginning of the
 469  * media file.
 470  */
 471 EAPI double       emotion_object_position_get          (const Evas_Object *obj);
 472 /**
 473  * @brief Get whether the media file is seekable.
 474  *
 475  * @param obj The emotion object from which the seekable status will be
 476  * retrieved.
 477  * @return EINA_TRUE if the media file is seekable, EINA_FALSE otherwise.
 478  */
 479 EAPI Eina_Bool    emotion_object_seekable_get          (const Evas_Object *obj);
 480 /**
 481  * @brief Get the length of play for the media file.
 482  *
 483  * @param obj The emotion object from which the length will be retrieved.
 484  * @return The length of the media file in seconds.
 485  *
 486  * This function returns the length of the media file in seconds.
 487  *
 488  * @warning This will return 0 if called before the "length_change" signal has,
 489  * been emitted.
 490  */
 491 EAPI double       emotion_object_play_length_get       (const Evas_Object *obj);
 492
 493 /**
 494  * @brief Set the play speed of the media file.
 495  *
 496  * @param obj The emotion object whose speed will be set.
 497  * @param speed The speed to be set in the range [0,infinity)
 498  *
 499  * This function sets the speed with which the media file will be played. 1.0
 500  * represents the normal speed, 2 double speed, 0.5 half speed and so on.
 501  *
 502  * @warning The only backend that implements this is the experimental VLC
 503  * backend.
 504  */
 505 EAPI void         emotion_object_play_speed_set        (Evas_Object *obj, double speed);
 506 /**
 507  * @brief Get  the play speed of the media file.
 508  *
 509  * @param obj The emotion object from which the filename will be retrieved.
 510  * @return The current speed of the media file.
 511  *
 512  * @see emotion_object_play_speed_set
 513  */
 514 EAPI double       emotion_object_play_speed_get        (const Evas_Object *obj);
 515 /**
 516  * @brief Get how much of the file has been played.
 517  *
 518  * @param obj The emotion object from which the filename will be retrieved.
 519  * @return The progress of the media file.
 520  *
 521  * @warning Don't change of free the returned string.
 522  * @warning gstreamer xine backends don't implement this(will return NULL).
 523  */
 524 EAPI const char  *emotion_object_progress_info_get     (const Evas_Object *obj);
 525 /**
 526  * @brief Get how much of the file has been played.
 527  *
 528  * @param obj The emotion object from which the filename will be retrieved
 529  * @return The progress of the media file.
 530  *
 531  * This function gets the progress in playing the file, the return value is in
 532  * the [0, 1] range.
 533  *
 534  * @warning gstreamer xine backends don't implement this(will return 0).
 535  */
 536 EAPI double       emotion_object_progress_status_get   (const Evas_Object *obj);
 537 /**
 538  * @}
 539  */
 540 EAPI Eina_Bool    emotion_object_video_handled_get     (const Evas_Object *obj);
 541 EAPI Eina_Bool    emotion_object_audio_handled_get     (const Evas_Object *obj);
 542
 543 /**
 544  * @brief Retrieve the video aspect ratio of the media file loaded.
 545  *
 546  * @param obj The emotion object which the video aspect ratio will be retrieved
 547  * from.
 548  * @return The video aspect ratio of the file loaded.
 549  *
 550  * This function returns the video aspect ratio (width / height) of the file
 551  * loaded. It can be used to adapt the size of the emotion object in the canvas,
 552  * so the aspect won't be changed (by wrongly resizing the object). Or to crop
 553  * the video correctly, if necessary.
 554  *
 555  * The described behavior can be applied like following. Consider a given
 556  * emotion object that we want to position inside an area, which we will
 557  * represent by @c w and @c h. Since we want to position this object either
 558  * stretching, or filling the entire area but overflowing the video, or just
 559  * adjust the video to fit inside the area without keeping the aspect ratio, we
 560  * must compare the video aspect ratio with the area aspect ratio:
 561  * @code
 562  * int w = 200, h = 300; // an arbitrary value which represents the area where
 563  *                       // the video would be placed
 564  * int vw, vh;
 565  * double r, vr = emotion_object_ratio_get(obj);
 566  * r = (double)w / h;
 567  * @endcode
 568  *
 569  * Now, if we want to make the video fit inside the area, the following code
 570  * would do it:
 571  * @code
 572  * if (vr > r) // the video is wider than the area
 573  *   {
 574  *      vw = w;
 575  *      vh = w / vr;
 576  *   }
 577  * else // the video is taller than the area
 578  *   {
 579  *      vh = h;
 580  *      vw = h * vr;
 581  *   }
 582  * evas_object_resize(obj, vw, vh);
 583  * @endcode
 584  *
 585  * And for keeping the aspect ratio but making the video fill the entire area,
 586  * overflowing the content which can't fit inside it, we would do:
 587  * @code
 588  * if (vr > r) // the video is wider than the area
 589  *   {
 590  *      vh = h;
 591  *      vw = h * vr;
 592  *   }
 593  * else // the video is taller than the area
 594  *   {
 595  *      vw = w;
 596  *      vh = w / vr;
 597  *   }
 598  * evas_object_resize(obj, vw, vh);
 599  * @endcode
 600  *
 601  * Finally, by just resizing the video to the video area, we would have the
 602  * video stretched:
 603  * @code
 604  * vw = w;
 605  * vh = h;
 606  * evas_object_resize(obj, vw, vh);
 607  * @endcode
 608  *
 609  * The following diagram exemplifies what would happen to the video,
 610  * respectively, in each case:
 611  *
 612  * @image html emotion_ratio.png
 613  * @image latex emotion_ratio.eps width=\textwidth
 614  *
 615  * @note This function returns the aspect ratio that the video @b should be, but
 616  * sometimes the reported size from emotion_object_size_get() represents a
 617  * different aspect ratio. You can safely resize the video to respect the aspect
 618  * ratio returned by @b this function.
 619  *
 620  * @see emotion_object_size_get()
 621  *
 622  * @ingroup Emotion_Video
 623  */
 624 EAPI double       emotion_object_ratio_get             (const Evas_Object *obj);
 625
 626 /**
 627  * @brief Retrieve the video size of the loaded file.
 628  *
 629  * @param obj The object from which we are retrieving the video size.
 630  * @param iw A pointer to a variable where the width will be stored.
 631  * @param iw A pointer to a variable where the height will be stored.
 632  *
 633  * This function returns the reported size of the loaded video file. If a file
 634  * that doesn't contain a video channel is loaded, then this size can be
 635  * ignored.
 636  *
 637  * The value reported by this function should be consistent with the aspect
 638  * ratio returned by emotion_object_ratio_get(), but sometimes the information
 639  * stored in the file is wrong. So use the ratio size reported by
 640  * emotion_object_ratio_get(), since it is more likely going to be accurate.
 641  *
 642  * @note Use @c NULL for @p iw or @p ih if you don't need one of these values.
 643  *
 644  * @see emotion_object_ratio_get()
 645  *
 646  * @ingroup Emotion_Video
 647  */
 648 EAPI void         emotion_object_size_get              (const Evas_Object *obj, int *iw, int *ih);
 649
 650 /**
 651  * @brief Sets whether to use of high-quality image scaling algorithm
 652  * of the given video object.
 653  *
 654  * When enabled, a higher quality video scaling algorithm is used when
 655  * scaling videos to sizes other than the source video. This gives
 656  * better results but is more computationally expensive.
 657  *
 658  * @param obj The given video object.
 659  * @param smooth Whether to use smooth scale or not.
 660  *
 661  * @see emotion_object_smooth_scale_get()
 662  *
 663  * @ingroup Emotion_Video
 664  */
 665 EAPI void         emotion_object_smooth_scale_set      (Evas_Object *obj, Eina_Bool smooth);
 666
 667 /**
 668  * @brief Gets whether the high-quality image scaling algorithm
 669  * of the given video object is used.
 670  *
 671  * @param obj The given video object.
 672  * @return Whether the smooth scale is used or not.
 673  *
 674  * @see emotion_object_smooth_scale_set()
 675  *
 676  * @ingroup Emotion_Video
 677  */
 678 EAPI Eina_Bool    emotion_object_smooth_scale_get      (const Evas_Object *obj);
 679 EAPI void         emotion_object_event_simple_send     (Evas_Object *obj, Emotion_Event ev);
 680
 681 /**
 682  * @brief Set the audio volume.
 683  *
 684  * @param obj The object where the volume is being set.
 685  * @param vol The new volume parameter. Range is from 0.0 to 1.0.
 686  *
 687  * Sets the audio volume of the stream being played. This has nothing to do with
 688  * the system volume. This volume will be multiplied by the system volume. e.g.:
 689  * if the current volume level is 0.5, and the system volume is 50%, it will be
 690  * 0.5 * 0.5 = 0.25.
 691  *
 692  * The default value depends on the module used. This value doesn't get changed
 693  * when another file is loaded.
 694  *
 695  * @see emotion_object_audio_volume_get()
 696  *
 697  * @ingroup Emotion_Audio
 698  */
 699 EAPI void         emotion_object_audio_volume_set      (Evas_Object *obj, double vol);
 700
 701 /**
 702  * @brief Get the audio volume.
 703  *
 704  * @param obj The object from which we are retrieving the volume.
 705  * @return The current audio volume level for this object.
 706  *
 707  * Get the current value for the audio volume level. Range is from 0.0 to 1.0.
 708  * This volume is set with emotion_object_audio_volume_set().
 709  *
 710  * @see emotion_object_audio_volume_set()
 711  *
 712  * @ingroup Emotion_Audio
 713  */
 714 EAPI double       emotion_object_audio_volume_get      (const Evas_Object *obj);
 715
 716 /**
 717  * @brief Set the mute audio option for this object.
 718  *
 719  * @param obj The object which we are setting the mute audio option.
 720  * @param mute Whether the audio should be muted (@c EINA_TRUE) or not (@c
 721  * EINA_FALSE).
 722  *
 723  * This function sets the mute audio option for this emotion object. The current
 724  * module used for this object can use this to avoid decoding the audio portion
 725  * of the loaded media file.
 726  *
 727  * @see emotion_object_audio_mute_get()
 728  * @see emotion_object_video_mute_set()
 729  *
 730  * @ingroup Emotion_Audio
 731  */
 732 EAPI void         emotion_object_audio_mute_set        (Evas_Object *obj, Eina_Bool mute);
 733
 734 /**
 735  * @brief Get the mute audio option of this object.
 736  *
 737  * @param obj The object which we are retrieving the mute audio option from.
 738  * @return Whether the audio is muted (@c EINA_TRUE) or not (@c EINA_FALSE).
 739  *
 740  * This function return the mute audio option from this emotion object. It can
 741  * be set with emotion_object_audio_mute_set().
 742  *
 743  * @see emotion_object_audio_mute_set()
 744  *
 745  * @ingroup Emotion_Audio
 746  */
 747 EAPI Eina_Bool    emotion_object_audio_mute_get        (const Evas_Object *obj);
 748 EAPI int          emotion_object_audio_channel_count   (const Evas_Object *obj);
 749 EAPI const char  *emotion_object_audio_channel_name_get(const Evas_Object *obj, int channel);
 750 EAPI void         emotion_object_audio_channel_set     (Evas_Object *obj, int channel);
 751 EAPI int          emotion_object_audio_channel_get     (const Evas_Object *obj);
 752
 753 /**
 754  * @brief Set the mute video option for this object.
 755  *
 756  * @param obj The object which we are setting the mute video option.
 757  * @param mute Whether the video should be muted (@c EINA_TRUE) or not (@c
 758  * EINA_FALSE).
 759  *
 760  * This function sets the mute video option for this emotion object. The
 761  * current module used for this object can use this information to avoid
 762  * decoding the video portion of the loaded media file.
 763  *
 764  * @see emotion_object_video_mute_get()
 765  * @see emotion_object_audio_mute_set()
 766  *
 767  * @ingroup Emotion_Video
 768  */
 769 EAPI void         emotion_object_video_mute_set        (Evas_Object *obj, Eina_Bool mute);
 770
 771 /**
 772  * @brief Get the mute video option of this object.
 773  *
 774  * @param obj The object which we are retrieving the mute video option from.
 775  * @return Whether the video is muted (@c EINA_TRUE) or not (@c EINA_FALSE).
 776  *
 777  * This function returns the mute video option from this emotion object. It can
 778  * be set with emotion_object_video_mute_set().
 779  *
 780  * @see emotion_object_video_mute_set()
 781  *
 782  * @ingroup Emotion_Video
 783  */
 784 EAPI Eina_Bool    emotion_object_video_mute_get        (const Evas_Object *obj);
 785 EAPI int          emotion_object_video_channel_count   (const Evas_Object *obj);
 786 EAPI const char  *emotion_object_video_channel_name_get(const Evas_Object *obj, int channel);
 787 EAPI void         emotion_object_video_channel_set     (Evas_Object *obj, int channel);
 788 EAPI int          emotion_object_video_channel_get     (const Evas_Object *obj);
 789 EAPI void         emotion_object_spu_mute_set          (Evas_Object *obj, Eina_Bool mute);
 790 EAPI Eina_Bool    emotion_object_spu_mute_get          (const Evas_Object *obj);
 791 EAPI int          emotion_object_spu_channel_count     (const Evas_Object *obj);
 792 EAPI const char  *emotion_object_spu_channel_name_get  (const Evas_Object *obj, int channel);
 793 EAPI void         emotion_object_spu_channel_set       (Evas_Object *obj, int channel);
 794 EAPI int          emotion_object_spu_channel_get       (const Evas_Object *obj);
 795 EAPI int          emotion_object_chapter_count         (const Evas_Object *obj);
 796 EAPI void         emotion_object_chapter_set           (Evas_Object *obj, int chapter);
 797 EAPI int          emotion_object_chapter_get           (const Evas_Object *obj);
 798 EAPI const char  *emotion_object_chapter_name_get      (const Evas_Object *obj, int chapter);
 799 EAPI void         emotion_object_eject                 (Evas_Object *obj);
 800
 801 /**
 802  * @brief Get the dvd title from this emotion object.
 803  *
 804  * @param obj The object which the title will be retrieved from.
 805  * @return A string containing the title.
 806  *
 807  * This function is only useful when playing a DVD.
 808  *
 809  * @note Don't change or free the string returned by this function.
 810  *
 811  * @ingroup Emotion_Info
 812  */
 813 EAPI const char  *emotion_object_title_get             (const Evas_Object *obj);
 814 EAPI const char  *emotion_object_ref_file_get          (const Evas_Object *obj);
 815 EAPI int          emotion_object_ref_num_get           (const Evas_Object *obj);
 816 EAPI int          emotion_object_spu_button_count_get  (const Evas_Object *obj);
 817 EAPI int          emotion_object_spu_button_get        (const Evas_Object *obj);
 818
 819 /**
 820  * @brief Retrieve meta information from this file being played.
 821  *
 822  * @param obj The object which the meta info will be extracted from.
 823  * @param meta The type of meta information that will be extracted.
 824  *
 825  * This function retrieves information about the file loaded. It can retrieve
 826  * the track title, artist name, album name, etc. See @ref Emotion_Meta_Info
 827  * for all the possibilities.
 828  *
 829  * The meta info may be not available on all types of files. It will return @c
 830  * NULL if the the file doesn't have meta info, or if this specific field is
 831  * empty.
 832  *
 833  * @note Don't change or free the string returned by this function.
 834  *
 835  * @see Emotion_Meta_Info
 836  *
 837  * @ingroup Emotion_Info
 838  */
 839 EAPI const char  *emotion_object_meta_info_get         (const Evas_Object *obj, Emotion_Meta_Info meta);
 840
 841 /**
 842  * @brief Set the visualization to be used with this object.
 843  *
 844  * @param obj The object where the visualization will be set on.
 845  * @param visualization The type of visualization to be used.
 846  *
 847  * The @p visualization specified will be played instead of a video. This is
 848  * commonly used to display a visualization for audio only files (musics).
 849  *
 850  * The available visualizations are @ref Emotion_Vis.
 851  *
 852  * @see Emotion_Vis
 853  * @see emotion_object_vis_get()
 854  * @see emotion_object_vis_supported()
 855  *
 856  * @ingroup Emotion_Visualization
 857  */
 858 EAPI void         emotion_object_vis_set               (Evas_Object *obj, Emotion_Vis visualization);
 859
 860 /**
 861  * @brief Get the type of visualization in use by this emotion object.
 862  *
 863  * @param obj The emotion object which the visualization is being retrieved
 864  * from.
 865  * @return The type of visualization in use by this object.
 866  *
 867  * The type of visualization can be set by emotion_object_vis_set().
 868  *
 869  * @see Emotion_Vis
 870  * @see emotion_object_vis_set()
 871  * @see emotion_object_vis_supported()
 872  *
 873  * @ingroup Emotion_Visualization
 874  */
 875 EAPI Emotion_Vis  emotion_object_vis_get               (const Evas_Object *obj);
 876
 877 /**
 878  * @brief Query whether a type of visualization is supported by this object.
 879  *
 880  * @param obj The object which the query is being ran on.
 881  * @param visualization The type of visualization that is being queried.
 882  * @return EINA_TRUE if the visualization is supported, EINA_FALSE otherwise.
 883  *
 884  * This can be used to check if a visualization is supported. e.g.: one wants to
 885  * display a list of available visualizations for a specific object.
 886  *
 887  * @see Emotion_Vis
 888  * @see emotion_object_vis_set()
 889  * @see emotion_object_vis_get()
 890  *
 891  * @ingroup Emotion_Visualization
 892  */
 893 EAPI Eina_Bool    emotion_object_vis_supported         (const Evas_Object *obj, Emotion_Vis visualization);
 894
 895 EAPI void         emotion_object_last_position_load    (Evas_Object *obj);
 896 EAPI void         emotion_object_last_position_save    (Evas_Object *obj);
 897
 898 EAPI void         emotion_object_suspend_set           (Evas_Object *obj, Emotion_Suspend state);
 899 EAPI Emotion_Suspend emotion_object_suspend_get        (Evas_Object *obj);
 900
 901 EAPI Eina_Bool    emotion_object_extension_may_play_fast_get(const char *file);
 902 EAPI Eina_Bool    emotion_object_extension_may_play_get(const char *file);
 903
 904 EAPI Evas_Object *emotion_object_image_get(const Evas_Object *obj);
 905
 906 typedef struct _Emotion_Webcam Emotion_Webcam;
 907
 908 extern int EMOTION_WEBCAM_UPDATE;
 909
 910 EAPI const Eina_List *emotion_webcams_get(void);
 911 EAPI const char      *emotion_webcam_name_get(const Emotion_Webcam *ew);
 912 EAPI const char      *emotion_webcam_device_get(const Emotion_Webcam *ew);
 913
 914 /**
 915  * @}
 916  */
 917
 918 #ifdef __cplusplus
 919 }
 920 #endif
 921
 922 #endif