#ifndef EMOTION_H
#define EMOTION_H
+/**
+ * @file
+ * @brief Emotion Media Library
+ *
+ * These routines are used for Emotion.
+ */
+
+/**
+ *
+ * @mainpage Emotion Library Documentation
+ *
+ * @version 1.7.0
+ * @date 2003-2012
+ *
+ * @section intro What is Emotion?
+ *
+ * A media object library for Evas and Ecore.
+ *
+ * Emotion is a library that allows playing audio and video files, using one of
+ * its backends (gstreamer or xine).
+ *
+ * It is integrated into Ecore through its mainloop, and is transparent to the
+ * user of the library how the decoding of audio and video is being done. Once
+ * the objects are created, the user can set callbacks to the specific events
+ * and set options to this object, all in the main loop (no threads are needed).
+ *
+ * Emotion is also integrated with Evas. The emotion object returned by
+ * emotion_object_add() is an Evas smart object, so it can be manipulated with
+ * default Evas object functions. Callbacks can be added to the signals emitted
+ * by this object with evas_object_smart_callback_add().
+ *
+ * @section work How does Emotion work?
+ *
+ * The Emotion library uses Evas smart objects to allow you to manipulate the
+ * created object as any other Evas object, and to connect to its signals,
+ * handling them when needed. It's also possible to swallow Emotion objects
+ * inside Edje themes, and expect it to behave as a normal image or rectangle
+ * when regarding to its dimensions.
+ *
+ * To instantiate an Emotion object, the simple code below is enough:
+ *
+ * @code
+ * em = emotion_object_add(e);
+ * emotion_object_init(em, NULL);
+ *
+ * emotion_object_file_set(em, file_path);
+ *
+ * evas_object_move(em, 0, 0);
+ * evas_object_resize(em, WIDTH, HEIGHT);
+ * evas_object_show(em);
+ *
+ * emotion_object_play_set(em, EINA_TRUE);
+ * @endcode
+ *
+ * See the @ref Emotion_API for a better reference.
+ *
+ * Please see the @ref authors page for contact details.
+ *
+ */
+
+/**
+ *
+ * @page authors Authors
+ *
+ * @author Carsten Haitzler <raster@rasterman.com>
+ * @author Vincent Torri <torri@maths.univ-evry.fr>
+ * @author Nicolas Aguirre <aguirre.nicolas@gmail.com>
+ * @author Sebastian Dransfeld <sd@tango.flipp.net>
+ * @author Cedric Bail <cedric.bail@free.fr>
+ *
+ * Please contact <enlightenment-devel@lists.sourceforge.net> to get in
+ * contact with the developers and maintainers.
+ *
+ */
+
#include <Evas.h>
#ifdef EAPI
EMOTION_VIS_LAST /* sentinel */
};
+/**
+ * @enum Emotion_Suspend
+ *
+ * Used for emotion pipeline ressource management.
+ *
+ * @see emotion_object_suspend_set()
+ * @see emotion_object_suspend_get()
+ *
+ * @ingroup Emotion_Ressource
+ */
typedef enum
{
- EMOTION_WAKEUP,
- EMOTION_SLEEP,
- EMOTION_DEEP_SLEEP,
- EMOTION_HIBERNATE
+ EMOTION_WAKEUP, /**< pipeline is up and running */
+ EMOTION_SLEEP, /**< turn off hardware ressource usage like overlay */
+ EMOTION_DEEP_SLEEP, /**< destroy the pipeline, but keep full resolution pixels output around */
+ EMOTION_HIBERNATE /**< destroy the pipeline, and keep half resolution or object resolution if lower */
} Emotion_Suspend;
+/**
+ * @enum _Emotion_Aspect
+ * Defines the aspect ratio option.
+ */
+enum _Emotion_Aspect
+{
+ EMOTION_ASPECT_KEEP_NONE, /**< ignore video aspect ratio */
+ EMOTION_ASPECT_KEEP_WIDTH, /**< respect video aspect, fitting its width inside the object width */
+ EMOTION_ASPECT_KEEP_HEIGHT, /**< respect video aspect, fitting its height inside the object height */
+ EMOTION_ASPECT_KEEP_BOTH, /**< respect video aspect, fitting it inside the object area */
+ EMOTION_ASPECT_CROP, /**< respect video aspect, cropping exceding area */
+ EMOTION_ASPECT_CUSTOM, /**< use custom borders/crop for the video */
+};
+
typedef enum _Emotion_Module Emotion_Module;
typedef enum _Emotion_Event Emotion_Event;
typedef enum _Emotion_Meta_Info Emotion_Meta_Info; /**< Meta info type to be retrieved. */
typedef enum _Emotion_Vis Emotion_Vis; /**< Type of visualization. */
+typedef enum _Emotion_Aspect Emotion_Aspect; /**< Aspect ratio option. */
#define EMOTION_CHANNEL_AUTO -1
#define EMOTION_CHANNEL_DEFAULT 0
extern "C" {
#endif
+#define EMOTION_VERSION_MAJOR 1
+#define EMOTION_VERSION_MINOR 7
+
+ typedef struct _Emotion_Version
+ {
+ int major;
+ int minor;
+ int micro;
+ int revision;
+ } Emotion_Version;
+
+ EAPI extern Emotion_Version *emotion_version;
+
/* api calls available */
/**
* @defgroup Emotion_Info Miscellaneous information retrieval functions
*/
+/**
+ * @defgroup Emotion_Ressource Video ressource management
+ */
+
EAPI Eina_Bool emotion_init(void);
EAPI Eina_Bool emotion_shutdown(void);
* @see emotion_object_audio_mute_set()
* @see emotion_object_video_mute_set()
*
- * @ingroup Emotion_Audio
- * @ingroup Emotion_Video
+ * @ingroup Emotion_Init
*/
EAPI void emotion_object_module_option_set (Evas_Object *obj, const char *opt, const char *val);
EAPI Eina_Bool emotion_object_init (Evas_Object *obj, const char *module_filename);
/**
+ * @brief Set borders for the emotion object.
+ *
+ * @param obj The emotion object where borders are being set.
+ * @param l The left border.
+ * @param r The right border.
+ * @param t The top border.
+ * @param 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 emotion_object_border_get()
+ * @see emotion_object_bg_color_set()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI void emotion_object_border_set(Evas_Object *obj, int l, int r, int t, int b);
+
+/**
+ * @brief Get the borders set for the emotion object.
+ *
+ * @param obj The emotion object from which the borders are being retrieved.
+ * @param l The left border.
+ * @param r The right border.
+ * @param t The top border.
+ * @param b The bottom border.
+ *
+ * @see emotion_object_border_set()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI void emotion_object_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b);
+
+/**
+ * @brief Set a color for the background rectangle of this emotion object.
+ *
+ * @param obj The emotion object where the background color is being set.
+ * @param r Red component of the color.
+ * @param g Green component of the color.
+ * @param b Blue component of the color.
+ * @param 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 emotion_object_bg_color_get()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI void emotion_object_bg_color_set(Evas_Object *obj, int r, int g, int b, int a);
+
+/**
+ * @brief Get the background color set for the emotion object.
+ *
+ * @param obj The emotion object from which the background color is being retrieved.
+ * @param r Red component of the color.
+ * @param g Green component of the color.
+ * @param b Blue component of the color.
+ * @param a AAlpha channel of the color.
+ *
+ * @see emotion_object_bg_color_set()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI void emotion_object_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a);
+
+/**
+ * @brief Set whether emotion should keep the aspect ratio of the video.
+ *
+ * @param obj The emotion object where to set the aspect.
+ * @param 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:
+ *
+ * - @b #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.
+ * - @b #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.
+ * - @b #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.
+ * - @b #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.
+ * - @b #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.
+ * - @b #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().
+ *
+ * @note Calling emotion_object_border_set() will automatically set the aspect
+ * policy to #EMOTION_ASPECT_CUSTOM.
+ *
+ * @see emotion_object_border_set()
+ * @see emotion_object_keep_aspect_get()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI void emotion_object_keep_aspect_set(Evas_Object *obj, Emotion_Aspect a);
+
+/**
+ * @brief Get the current emotion aspect ratio policy.
+ *
+ * @param obj The emotion object from which we are fetching the aspect ratio
+ * policy.
+ * @return The current aspect ratio policy.
+ *
+ * @see emotion_object_keep_aspect_set()
+ *
+ * @ingroup Emotion_Video
+ */
+EAPI Emotion_Aspect emotion_object_keep_aspect_get(const Evas_Object *obj);
+
+/**
* @brief Set the file to be played in the Emotion object.
*
* @param obj The emotion object where the file is being loaded.
* media file.
*/
EAPI double emotion_object_position_get (const Evas_Object *obj);
+
+/**
+ * @brief Get the percentual size of the buffering cache.
+ *
+ * @param obj The emotion object from which the buffer size will be retrieved.
+ * @return The buffer percent size, ranging from 0.0 to 1.0
+ *
+ * The buffer size is returned as a number between 0.0 and 1.0, 0.0 means
+ * the buffer if empty, 1.0 means full.
+ * If no buffering is in progress 1.0 is returned. In all other cases (maybe
+ * the backend don't support buffering) 1.0 is returned, thus you can always
+ * check for buffer_size < 1.0 to know if buffering is in progress.
+ *
+ * @warning Generic backend don't implement this (will return 1.0).
+ */
+EAPI double emotion_object_buffer_size_get (const Evas_Object *obj);
+
/**
* @brief Get whether the media file is seekable.
*
* 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 @c w and @c 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:
+ * @code
+ * 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;
+ * @endcode
+ *
+ * Now, if we want to make the video fit inside the area, the following code
+ * would do it:
+ * @code
+ * 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);
+ * @endcode
+ *
+ * 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:
+ * @code
+ * 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);
+ * @endcode
+ *
+ * Finally, by just resizing the video to the video area, we would have the
+ * video stretched:
+ * @code
+ * vw = w;
+ * vh = h;
+ * evas_object_resize(obj, vw, vh);
+ * @endcode
+ *
+ * The following diagram exemplifies what would happen to the video,
+ * respectively, in each case:
+ *
+ * @image html emotion_ratio.png
+ * @image latex emotion_ratio.eps width=\textwidth
+ *
* @note This function returns the aspect ratio that the video @b 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
*
* @param obj The object from which we are retrieving the video size.
* @param iw A pointer to a variable where the width will be stored.
- * @param iw A pointer to a variable where the height will be stored.
+ * @param 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
* @ingroup Emotion_Video
*/
EAPI Eina_Bool emotion_object_video_mute_get (const Evas_Object *obj);
+
+/**
+ * @brief Get the number of available video channel
+ *
+ * @param obj The object which we are retrieving the channel count from
+ * @return the number of available channel.
+ *
+ * @see emotion_object_video_channel_name_get()
+ *
+ * @ingroup Emotion_Video
+ */
EAPI int emotion_object_video_channel_count (const Evas_Object *obj);
EAPI const char *emotion_object_video_channel_name_get(const Evas_Object *obj, int channel);
EAPI void emotion_object_video_channel_set (Evas_Object *obj, int channel);
*/
EAPI Eina_Bool emotion_object_vis_supported (const Evas_Object *obj, Emotion_Vis visualization);
-EAPI void emotion_object_last_position_load (Evas_Object *obj);
-EAPI void emotion_object_last_position_save (Evas_Object *obj);
+/**
+ * @brief Raise priority of an object so it will have a priviledged access to hardware ressource.
+ *
+ * @param obj The object which the query is being ran on.
+ * @param priority EINA_TRUE means give me a priority access to the hardware ressource.
+ *
+ * Hardware have a few dedicated hardware pipeline that process the video at no cost for the CPU.
+ * Especially on SoC, you mostly have one (on mobile phone SoC) or two (on Set Top Box SoC) when
+ * Picture in Picture is needed. And most application just have a few video stream that really
+ * deserve high frame rate, hiogh quality output. That's why this call is for.
+ *
+ * Please note that if Emotion can't acquire a priviledged hardware ressource, it will fallback
+ * to the no-priority path. This work on the first asking first get basis system.
+ *
+ * @see emotion_object_priority_get()
+ *
+ * @ingroup Emotion_Ressource
+ */
+EAPI void emotion_object_priority_set(Evas_Object *obj, Eina_Bool priority);
+
+/**
+ * @brief Get the actual priority of an object.
+ *
+ * @param obj The object which the query is being ran on.
+ * @return EINA_TRUE if the object has a priority access to the hardware.
+ *
+ * This actually return the priority status of an object. If it failed to have a priviledged
+ * access to the hardware, it will return EINA_FALSE.
+ *
+ * @see emotion_object_priority_get()
+ *
+ * @ingroup Emotion_Ressource
+ */
+EAPI Eina_Bool emotion_object_priority_get(const Evas_Object *obj);
-EAPI void emotion_object_suspend_set (Evas_Object *obj, Emotion_Suspend state);
-EAPI Emotion_Suspend emotion_object_suspend_get (Evas_Object *obj);
+/**
+ * @brief Change the state of an object pipeline.
+ *
+ * @param obj The object which the query is being ran on.
+ * @param state The new state for the object.
+ *
+ * Changing the state of a pipeline should help preserve the battery of an embedded device.
+ * But it will only work sanely if the pipeline is not playing at the time you change its
+ * state. Depending on the engine all state may be not implemented.
+ *
+ * @see Emotion_Suspend
+ * @see emotion_object_suspend_get()
+ *
+ * @ingroup Emotion_Ressource
+ */
+EAPI void emotion_object_suspend_set(Evas_Object *obj, Emotion_Suspend state);
+
+/**
+ * @brief Get the current state of the pipeline
+ *
+ * @param obj The object which the query is being ran on.
+ * @return the current state of the pipeline.
+ *
+ * @see Emotion_Suspend
+ * @see emotion_object_suspend_set()
+ *
+ * @ingroup Emotion_Ressource
+ */
+EAPI Emotion_Suspend emotion_object_suspend_get(Evas_Object *obj);
+
+/**
+ * @brief Load the last known position if available
+ *
+ * @param obj The object which the query is being ran on.
+ *
+ * By using Xattr, Emotion is able, if the system permitt it, to store and retrieve
+ * the latest position. It should trigger some smart callback to let the application
+ * know when it succeed or fail. Every operation is fully asynchronous and not
+ * linked to the actual engine used to play the vide.
+ *
+ * @see emotion_object_last_position_save()
+ *
+ * @ingroup Emotion_Info
+ */
+EAPI void emotion_object_last_position_load(Evas_Object *obj);
+/**
+ * @brief Save the lastest position if possible
+ *
+ * @param obj The object which the query is being ran on.
+ *
+ * By using Xattr, Emotion is able, if the system permitt it, to store and retrieve
+ * the latest position. It should trigger some smart callback to let the application
+ * know when it succeed or fail. Every operation is fully asynchronous and not
+ * linked to the actual engine used to play the vide.
+ *
+ * @see emotion_object_last_position_load()
+ *
+ * @ingroup Emotion_Info
+ */
+EAPI void emotion_object_last_position_save(Evas_Object *obj);
+
+/**
+ * @brief Do we have a chance to play that file
+ *
+ * @param file A stringshared filename that we want to know if Emotion can play.
+ *
+ * This just actually look at the extention of the file, it doesn't check the mime-type
+ * nor if the file is actually sane. So this is just an hint for your application.
+ *
+ * @see emotion_object_extension_may_play_get()
+ */
EAPI Eina_Bool emotion_object_extension_may_play_fast_get(const char *file);
+
+/**
+ * @brief Do we have a chance to play that file
+ *
+ * @param file A filename that we want to know if Emotion can play.
+ *
+ * This just actually look at the extention of the file, it doesn't check the mime-type
+ * nor if the file is actually sane. So this is just an hint for your application.
+ *
+ * @see emotion_object_extension_may_play_fast_get()
+ */
EAPI Eina_Bool emotion_object_extension_may_play_get(const char *file);
-typedef struct _Emotion_Webcam Emotion_Webcam;
+/**
+ * @brief Get the actual image object that contains the pixels of the video stream
+ *
+ * @param obj The object which the query is being ran on.
+ *
+ * This function is usefull when you want to get a direct access to the pixels.
+ *
+ * @see emotion_object_image_get()
+ */
+EAPI Evas_Object *emotion_object_image_get(const Evas_Object *obj);
+
+/**
+ * @defgroup Emotion_Webcam API available for accessing webcam
+ */
+
+typedef struct _Emotion_Webcam Emotion_Webcam; /**< Webcam description */
+
+EAPI extern int EMOTION_WEBCAM_UPDATE; /**< Ecore_Event triggered when a new webcam is plugged in */
+/**
+ * @brief Get a list of active and available webcam
+ *
+ * @return the list of available webcam at the time of the call.
+ *
+ * It will return the current live list of webcam. It is updated before
+ * triggering EMOTION_WEBCAM_UPDATE and should never be modified.
+ *
+ * @ingroup Emotion_Webcam
+ */
EAPI const Eina_List *emotion_webcams_get(void);
-EAPI const char *emotion_webcam_name_get(Emotion_Webcam *ew);
-EAPI const char *emotion_webcam_device_get(Emotion_Webcam *ew);
+
+/**
+ * @brief Get the human understandable name of a Webcam
+ *
+ * @param ew The webcam to get the name from.
+ * @return the actual human readable name.
+ *
+ * @ingroup Emotion_Webcam
+ */
+EAPI const char *emotion_webcam_name_get(const Emotion_Webcam *ew);
+
+/**
+ * @brief Get the uri of a Webcam that will be understood by emotion
+ *
+ * @param ew The webcam to get the uri from.
+ * @return the actual uri that emotion will later understood.
+ *
+ * @ingroup Emotion_Webcam
+ */
+EAPI const char *emotion_webcam_device_get(const Emotion_Webcam *ew);
/**
* @}
projects / profile / ivi / emotion.git / blobdiff