![]() |
![]() |
![]() |
MAFW Reference Manual | ![]() |
---|---|---|---|---|
MafwRenderer; #define MAFW_RENDERER_ERROR #define MAFW_PROPERTY_RENDERER_MUTE #define MAFW_PROPERTY_RENDERER_VOLUME #define MAFW_PROPERTY_RENDERER_XID #define MAFW_PROPERTY_RENDERER_ERROR_POLICY #define MAFW_PROPERTY_RENDERER_AUTOPAINT #define MAFW_PROPERTY_RENDERER_COLORKEY enum MafwRendererError; enum MafwRendererErrorPolicy; enum MafwPlayState; enum MafwRendererSeekMode; void (*MafwRendererPositionCB) (MafwRenderer *self, gint position, gpointer user_data, const GError *error); void (*MafwRendererStatusCB) (MafwRenderer *self, MafwPlaylist *playlist, guint index, MafwPlayState state, const gchar *object_id, gpointer user_data, const GError *error); void (*MafwRendererPlaybackCB) (MafwRenderer *self, gpointer user_data, const GError *error); void (*MafwRendererMetadataResultCB) (MafwRenderer *self, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error); void mafw_renderer_play (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_play_object (MafwRenderer *self, const gchar *object_id, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_play_uri (MafwRenderer *self, const gchar *uri, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_stop (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_pause (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_resume (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_get_status (MafwRenderer *self, MafwRendererStatusCB callback, gpointer user_data); gboolean mafw_renderer_assign_playlist (MafwRenderer *self, MafwPlaylist *playlist, GError **error); void mafw_renderer_next (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_previous (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_goto_index (MafwRenderer *self, guint index, MafwRendererPlaybackCB callback, gpointer user_data); void mafw_renderer_set_position (MafwRenderer *self, MafwRendererSeekMode mode, gint seconds, MafwRendererPositionCB callback, gpointer user_data); void mafw_renderer_get_position (MafwRenderer *self, MafwRendererPositionCB callback, gpointer user_data); void mafw_renderer_get_current_metadata (MafwRenderer *self, MafwRendererMetadataResultCB callback, gpointer user_data); void mafw_renderer_emit_metadata (MafwRenderer *self, const gchar *name, GType type, guint nargs, ...); #define mafw_renderer_emit_metadata_boolean (self, name, ...) #define mafw_renderer_emit_metadata_double (self, name, ...) #define mafw_renderer_emit_metadata_int (self, name, ...) #define mafw_renderer_emit_metadata_int64 (self, name, ...) #define mafw_renderer_emit_metadata_long (self, name, ...) #define mafw_renderer_emit_metadata_string (self, name, ...) #define mafw_renderer_emit_metadata_uint (self, name, ...) #define mafw_renderer_emit_metadata_uint64 (self, name, ...) #define mafw_renderer_emit_metadata_ulong (self, name, ...) void mafw_renderer_emit_buffering_info (MafwRenderer *self, gfloat fraction);
"buffering-info" : Run First / Action "media-changed" : Run First / Action "metadata-changed" : Run First / Action "playlist-changed" : Run First / Action "state-changed" : Run First / Action
A renderer is a point of playback represented with another object of MafwRenderer class. Playback is controlled through renderer objects from an application. Renderers are designed so that any of them can play content from any source, and can be thought of as a GStreamer chain, although this might usually not be the actual case.
MafwRenderer is an abstract base class for renderers. It provides various playback-
related operations to control playback: mafw_renderer_play()
, mafw_renderer_stop()
,
mafw_renderer_pause()
and mafw_renderer_resume()
.
If the renderer has an assigned playlist (mafw_renderer_assign_playlist()
), it plays
continously according to the playing order specified for the playlist.
Skipping items is possible with mafw_renderer_next()
, mafw_renderer_previous()
and
mafw_renderer_goto_index()
. Skipping within the currently playing item can be
achieved with mafw_renderer_set_position()
and the current playback position can
be queried with mafw_renderer_get_position()
.
When assigned playlist is modified, confirmation signal(s) from playlist
daemon must be waited before proceeding with operations that depend on
certain playlist state. E.g. if playlist with single item A is cleared,
item B is added to playlist and mafw_renderer_play()
is called. It is possible
that the play command is handled by renderer before signal about cleared
playlist arrives, this again causes renderer to start playing item A and go
into stopped state when clear playlist signal arrives. By waiting until
clear signal is handled by commanding process, it is guaranteed that renderer
starts playing the correct item B.
The status of the renderer can be queried with mafw_renderer_get_status()
, which
should be used only for initial status update. The rest of the renderer's status
information is sent with signals.
#define MAFW_RENDERER_ERROR g_quark_from_static_string("com.nokia.mafw.error.renderer")
Gets a quark for renderer errors
#define MAFW_PROPERTY_RENDERER_MUTE "mute"
Property to (un)mute renderer.
Type: G_TYPE_BOOLEAN
Valid values: TRUE
- audio muted, FALSE
- audio not muted.
#define MAFW_PROPERTY_RENDERER_VOLUME "volume"
Property for adjusting renderer volume. Type: G_TYPE_UINT Valid values: 0 .. 99
#define MAFW_PROPERTY_RENDERER_XID "xid"
Property to give a renderer an X window to draw video/image content on. Type: G_TYPE_ULONG Valid values: See XID definition in X11/Xdefs.h
#define MAFW_PROPERTY_RENDERER_ERROR_POLICY "error-policy"
Property for selecting an error policy. Type: G_TYPE_UINT Valid values: Any defined in MafwRendererErrorPolicy
#define MAFW_PROPERTY_RENDERER_AUTOPAINT "autopaint"
If TRUE
, the renderer automatically paints the window passed for video
playback with the Xv color key.
Type: G_TYPE_BOOLEAN
#define MAFW_PROPERTY_RENDERER_COLORKEY "colorkey"
Read-only property corresponding to the Xv color key. If its value is not yet known, -1 is returned. Interested parties are suggested to connect to the MafwExtension::property-changed signal to get notified when it's available. Type: G_TYPE_INT
typedef enum { MAFW_RENDERER_ERROR_NO_MEDIA, MAFW_RENDERER_ERROR_URI_NOT_AVAILABLE, MAFW_RENDERER_ERROR_INVALID_URI, MAFW_RENDERER_ERROR_MEDIA_NOT_FOUND, MAFW_RENDERER_ERROR_STREAM_DISCONNECTED, MAFW_RENDERER_ERROR_TYPE_NOT_AVAILABLE, MAFW_RENDERER_ERROR_PLAYBACK, MAFW_RENDERER_ERROR_UNABLE_TO_PERFORM, MAFW_RENDERER_ERROR_UNSUPPORTED_TYPE, MAFW_RENDERER_ERROR_UNSUPPORTED_RESOLUTION, MAFW_RENDERER_ERROR_UNSUPPORTED_FPS, MAFW_RENDERER_ERROR_DRM, MAFW_RENDERER_ERROR_DEVICE_UNAVAILABLE, MAFW_RENDERER_ERROR_CORRUPTED_FILE, MAFW_RENDERER_ERROR_PLAYLIST_PARSING, MAFW_RENDERER_ERROR_CODEC_NOT_FOUND, MAFW_RENDERER_ERROR_VIDEO_CODEC_NOT_FOUND, MAFW_RENDERER_ERROR_AUDIO_CODEC_NOT_FOUND, MAFW_RENDERER_ERROR_NO_PLAYLIST, MAFW_RENDERER_ERROR_INDEX_OUT_OF_BOUNDS, MAFW_RENDERER_ERROR_CANNOT_PLAY, MAFW_RENDERER_ERROR_CANNOT_STOP, MAFW_RENDERER_ERROR_CANNOT_PAUSE, MAFW_RENDERER_ERROR_CANNOT_SET_POSITION, MAFW_RENDERER_ERROR_CANNOT_GET_POSITION, MAFW_RENDERER_ERROR_CANNOT_GET_STATUS /* TODO: gstreamer errors */ /* TODO: dsp errors */ /* TODO: helix errors */ /* TODO: get_metadata related */ /* TODO: policy related */ } MafwRendererError;
MAFW renderer specific error code definitions
typedef enum _MafwRendererErrorPolicy { MAFW_RENDERER_ERROR_POLICY_CONTINUE, MAFW_RENDERER_ERROR_POLICY_STOP } MafwRendererErrorPolicy;
Error management policies for renderers. Define how the renderer behaves in the presence of playback errors.
typedef enum _MafwPlayState { Stopped = 0, Playing, Paused, Transitioning, _LastMafwPlayState } MafwPlayState;
Possible renderer states.
typedef enum { SeekAbsolute = 0, SeekRelative, } MafwRendererSeekMode;
Possible seeking modes, see mafw_renderer_set_position()
.
void (*MafwRendererPositionCB) (MafwRenderer *self, gint position, gpointer user_data, const GError *error);
When mafw_renderer_get_position()
is called, the renderer will send its position
reply through the given callback function that is of this type. This means
that the reply might come asynchronously, usually with renderers accessing the
network.
self : |
A renderer, whose current position has been queried |
position : |
The renderer's current playback position in seconds, counting from the beginning of the current media item or -1 if we could not retrieve it |
user_data : |
Optional user data pointer passed to mafw_renderer_get_position()
|
error : |
A GError that is set if an error has occurred. If not NULL ,
none of the other parameters (except self ) are valid.
|
void (*MafwRendererStatusCB) (MafwRenderer *self, MafwPlaylist *playlist, guint index, MafwPlayState state, const gchar *object_id, gpointer user_data, const GError *error);
When mafw_renderer_get_status()
is called, the renderer will send its status reply
through the given callback function that is of this type. This means that the
reply might come asynchronously (i.e. after mafw_renderer_get_status()
returns).
self : |
A renderer, whose status has been queried |
playlist : |
The renderer's assigned playlist, NULL if none
|
index : |
The playlist index that is being used by the renderer as current item |
state : |
The renderer's current playing state |
object_id : |
The object ID of the renderer's current media |
user_data : |
Optional user data pointer passed to mafw_renderer_get_status()
|
error : |
A GError that is set if an error has occurred. If not NULL ,
none of the other parameters (except self ) are valid.
|
void (*MafwRendererPlaybackCB) (MafwRenderer *self, gpointer user_data, const GError *error);
This callback is called after mafw_renderer_play()
, mafw_renderer_play_uri()
,
mafw_renderer_play_object()
, mafw_renderer_stop()
, mafw_renderer_pause()
,
mafw_renderer_resume()
, mafw_renderer_next()
,* mafw_renderer_previous()
or
mafw_renderer_goto_index()
has been called. If the operation failed for some
reason, the error
parameter is set. This callback might get called
asynchronously, usually with renderers accessing the network.
self : |
A renderer, who has been asked to play/stop/pause/resume |
user_data : |
Optional user data pointer passed when invoking the call |
error : |
A GError that is set if an error has occurred. |
void (*MafwRendererMetadataResultCB) (MafwRenderer *self, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error);
When mafw_renderer_get_current_metadata()
is called, the renderer will send
its metadata reply through the given callback function that is of this type.
This means that the reply might come asynchronously.
self : |
A renderer, whose current media's metadata has been queried. |
object_id : |
The object ID of the current media or NULL if there wasn't any
media.
|
metadata : |
Metadata of the current media. |
user_data : |
Optional user data pointer passed to
mafw_renderer_get_current_metadata()
|
error : |
A GError that is set if an error has occurred. If not NULL , none
of the other parameters (except self ) are valid.
|
void mafw_renderer_play (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Starts playback. If there is no assigned playlist, or the renderer was already playing, this does nothing. In other cases a "state-changed" signal is sent.
self : |
A MafwRenderer instance. |
callback : |
Function that is called after the command has been executed. |
user_data : |
Optional user data pointer. |
void mafw_renderer_play_object (MafwRenderer *self, const gchar *object_id, MafwRendererPlaybackCB callback, gpointer user_data);
Starts playing the given object. If there is an assigned playlist,
the renderer resumes playing the item it left off after it is finished with
object_id
.
self : |
A MafwRenderer instance. |
object_id : |
An object id to play. |
callback : |
Function that is called after the command has been executed. |
user_data : |
Optional user data pointer. |
void mafw_renderer_play_uri (MafwRenderer *self, const gchar *uri, MafwRendererPlaybackCB callback, gpointer user_data);
Starts playing the given URI. If there is an assigned playlist, the renderer
resumes playing the item it left off after it is finished with uri
.
self : |
A MafwRenderer instance. |
uri : |
The URI to play. |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_stop (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Stops playback. If the renderer was playing an object_id, or a URI, a later
mafw_renderer_play()
will resume the assigned playlist (if there is one).
self : |
A MafwRenderer instance |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_pause (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Pauses playback. If the renderer was not playing, this does nothing.
self : |
A MafwRenderer instance |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_resume (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Resumes playback. If the renderer was not paused, this does nothing.
self : |
A MafwRenderer instance |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_get_status (MafwRenderer *self, MafwRendererStatusCB callback, gpointer user_data);
Gets the latest known status of the renderer.
self : |
A MafwRenderer instance. |
callback : |
The callback function that receives the renderer's status reply |
user_data : |
Optional user data pointer that is passed to the callback |
gboolean mafw_renderer_assign_playlist (MafwRenderer *self, MafwPlaylist *playlist, GError **error);
Assigns the given playlist to the renderer for playback. If there was already
a playlist assigned and the renderer was playing from it, the renderer immediately
stops playing from the old playlist. Then, if the new one is not NULL
, it
starts playing the first item from the new playlist.
The renderer should ref the playlist
.
self : |
A MafwRenderer instance. |
playlist : |
The playlist to assign, NULL to clear the assignment.
|
error : |
a GError to store an error if needed |
Returns : | TRUE if the call succeeds, FALSE in other case
|
void mafw_renderer_next (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Skips to the next item in the renderer's playlist. If the current index points to the last item in the playlist, this wraps around to the first item of the playlist, regardless of playlist repeat setting.
After playlist modification(s), wait until changes are confirmed by playlist daemon before attempting to command renderer.
The given callback function is executed with the error parameter set if this
call failed. If the call succeeds, the callback is called with NULL
error.
self : |
A MafwRenderer instance. |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_previous (MafwRenderer *self, MafwRendererPlaybackCB callback, gpointer user_data);
Skips to the previous item in the renderer's playlist. If the current index points to the first item in the playlist, this wraps around to the last item of the playlist, regardless of playlist repeat setting.
After playlist modification(s), wait until changes are confirmed by playlist daemon before attempting to command renderer.
The given callback function is executed with the error parameter set if this
call failed. If the call succeeds, the callback is called with NULL
error.
self : |
A MafwRenderer instance. |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_goto_index (MafwRenderer *self, guint index, MafwRendererPlaybackCB callback, gpointer user_data);
Skips to the given index in the renderer's playlist. Nothing happens if the given index is invalid (out of bounds).
After playlist modification(s), wait until changes are confirmed by playlist daemon before attempting to command renderer.
The given callback function is executed with the error parameter set if this
call failed. If the call succeeds, the callback is called with NULL
error.
self : |
A MafwRenderer instance. |
index : |
The absolute playlist index to skip to |
callback : |
Function that is called after the command has been executed |
user_data : |
Optional user data pointer |
void mafw_renderer_set_position (MafwRenderer *self, MafwRendererSeekMode mode, gint seconds, MafwRendererPositionCB callback, gpointer user_data);
Seeks in the current media; time is given in seconds. If mode
is
SeekAbsolute, it seeks to the given from the beginning, or if seconds
is
negative seeks from the end. If mode
is SeekRelative, the operation is
performed relatively to the actual position. If seconds
is beyond the
length of the current media, the renderer should just proceed to the next item in
the playlist (if any). Success/fail status is received through the callback
that is of type MafwRendererPositionCB.
self : |
A MafwRenderer instance. |
mode : |
MafwRendererSeekMode specifying the seek mode. |
seconds : |
Time in seconds to seek to. |
callback : |
A MafwRendererPositionCB callback that receives the new position |
user_data : |
Optional user data pointer passed to the callback. |
void mafw_renderer_get_position (MafwRenderer *self, MafwRendererPositionCB callback, gpointer user_data);
Gets the renderer's current playback position (in seconds) from the beginning of the current media item. If the renderer is not in Playing or Paused state, the callback returns zero. The position is returned asynchronously through a callback that is of type MafwRendererPositionCB.
self : |
A MafwRenderer instance. |
callback : |
A MafwRendererPositionCB callback that receives the current position |
user_data : |
Optional user data pointer passed to the callback. |
void mafw_renderer_get_current_metadata (MafwRenderer *self, MafwRendererMetadataResultCB callback, gpointer user_data);
Gets the renderer's current media's object ID and its metadata (if there isn't
any media the returned object ID will be NULL
). This information is
asynchronously returned through a MafwRendererMetadataResultCB callback.
self : |
A MafwRenderer instance. |
callback : |
A MafwRendererMetadataResultCB callback that receives the object ID and the metadata of the current media. |
user_data : |
Optional user data pointer passed to the callback. |
void mafw_renderer_emit_metadata (MafwRenderer *self, const gchar *name, GType type, guint nargs, ...);
Emits "metadata-changed" for name
. Pass the metadata
value(s) ("s") in the varargs, following their type and
count. This function exists for the convenience of subclasses.
self : |
a MafwRenderer instance. |
name : |
name of the changed metadata key. |
type : |
GType of the following value(s). |
nargs : |
number of values following. |
... : |
metadata values. |
#define mafw_renderer_emit_metadata_boolean(self, name, ...)
Emits boolean metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_double(self, name, ...)
Emits double metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_int(self, name, ...)
Emits int metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_int64(self, name, ...)
Emits int64 metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_long(self, name, ...)
Emits long metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_string(self, name, ...)
Emits string (gchar*) metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_uint(self, name, ...)
Emits uint metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_uint64(self, name, ...)
Emits uint64 metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
#define mafw_renderer_emit_metadata_ulong(self, name, ...)
Emits ulong metadata on renderer.
self : |
a MafwRenderer instance |
name : |
the metadata key |
... : |
list of values |
void mafw_renderer_emit_buffering_info (MafwRenderer *self, gfloat fraction);
Emits the signal of buffering on the given renderer.
self : |
a MafwRenderer instance |
fraction : |
the percentage of buffering completion |
"buffering-info"
signalvoid user_function (MafwRenderer *self, gfloat status, gpointer user_data) : Run First / Action
Emitted to indicate buffering status as a fraction.
self : |
a MafwRenderer instance. |
status : |
buffering status as a fraction (0.0 - 1.0). |
user_data : |
user data set when the signal handler was connected. |
"media-changed"
signalvoid user_function (MafwRenderer *self, gint index, gchar *object, gpointer user_data) : Run First / Action
Emitted when the currently played media of MafwRenderer has changed.
self : |
a MafwRenderer instance. |
index : |
the renderer's current playlist index or -1 if there is no playlist assigned or playlist is empty |
object : |
object ID of the current item. if index == -1, object = NULL |
user_data : |
user data set when the signal handler was connected. |
"metadata-changed"
signalvoid user_function (MafwRenderer *self, gchar *name, GValueArray *value, gpointer user_data) : Run First / Action
Emitted when some metadata of the currently playing item has changed. If, for example, the duration of a track can be calculated more accurately when the track is played, a renderer can inform of this.
self : |
a MafwRenderer instance. |
name : |
metadata that changed. |
value : |
a GValueArray representing the new value |
user_data : |
user data set when the signal handler was connected. |
"playlist-changed"
signalvoid user_function (MafwRenderer *self, GObject *playlist, gpointer user_data) : Run First / Action
Emitted when the playlist of MafwRenderer has changed.
self : |
a MafwRenderer instance. |
playlist : |
the renderer's current playlist. |
user_data : |
user data set when the signal handler was connected. |
"state-changed"
signalvoid user_function (MafwRenderer *self, gint state, gpointer user_data) : Run First / Action
Emitted when the playback state of MafwRenderer has changed.
self : |
a MafwRenderer instance. |
state : |
the renderer's current playback state (MafwPlayState). |
user_data : |
user data set when the signal handler was connected. |