SwfdecPlayer

SwfdecPlayer — main playback object

Synopsis




enum        SwfdecMouseCursor;
            SwfdecPlayer;
void        swfdec_init                     (void);
SwfdecPlayer* swfdec_player_new             (void);
SwfdecPlayer* swfdec_player_new_from_file   (const char *filename,
                                             GError **error);
void        swfdec_player_set_loader        (SwfdecPlayer *player,
                                             SwfdecLoader *loader);
gboolean    swfdec_player_is_initialized    (SwfdecPlayer *player);
double      swfdec_player_get_rate          (SwfdecPlayer *player);
void        swfdec_player_get_image_size    (SwfdecPlayer *player,
                                             int *width,
                                             int *height);
guint       swfdec_player_get_next_event    (SwfdecPlayer *player);
void        swfdec_player_render            (SwfdecPlayer *player,
                                             cairo_t *cr,
                                             double x,
                                             double y,
                                             double width,
                                             double height);
void        swfdec_player_advance           (SwfdecPlayer *player,
                                             guint msecs);
gboolean    swfdec_player_handle_mouse      (SwfdecPlayer *player,
                                             double x,
                                             double y,
                                             int button);
void        swfdec_player_render_audio      (SwfdecPlayer *player,
                                             gint16 *dest,
                                             guint start_offset,
                                             guint n_samples);
const GList* swfdec_player_get_audio        (SwfdecPlayer *player);

Object Hierarchy


  GObject
   +----SwfdecPlayer

Properties


  "cache-size"           guint                 : Read
  "initialized"          gboolean              : Read
  "mouse-cursor"         SwfdecMouseCursor     : Read
  "next-event"           guint                 : Read

Signals


"advance"   void        user_function      (SwfdecPlayer *player,
                                            guint         msecs,
                                            guint         audio_samples,
                                            gpointer      user_data)          : Run last
"audio-added"
            void        user_function      (SwfdecPlayer *player,
                                            SwfdecAudio  *audio,
                                            gpointer      user_data)      : Run last
"audio-removed"
            void        user_function      (SwfdecPlayer *player,
                                            SwfdecAudio  *audio,
                                            gpointer      user_data)      : Run last
"handle-mouse"
            gboolean    user_function      (SwfdecPlayer *player,
                                            gdouble       x,
                                            gdouble       y,
                                            gint          button,
                                            gpointer      user_data)      : Run last
"invalidate"
            void        user_function      (SwfdecPlayer *player,
                                            gdouble       x,
                                            gdouble       y,
                                            gdouble       width,
                                            gdouble       height,
                                            gpointer      user_data)      : Run last
"launch"    void        user_function      (SwfdecPlayer *player,
                                            gchar        *url,
                                            gchar        *target,
                                            gpointer      user_data)      : Run last
"trace"     void        user_function      (SwfdecPlayer *player,
                                            gchar        *text,
                                            gpointer      user_data)      : Run last

Description

A SwfdecPlayer is the main object used for playing back Flash files through Swfdec.

A player interacts with the outside world in a multitude of ways. The most important ones are described below.

Input is handled via the SwfdecLoader class. A SwfdecLoader is set on a new player using swfdec_player_set_loader().

When the loader has provided enough data, you can start playing the file. This is done in steps by calling swfdec_player_advance() - preferrably as often as swfdec_player_get_next_event() indicates. Or you can provide user input to the player by calling for example swfdec_player_handle_mouse().

You can use swfdec_player_render() to draw the current state of the player. After that, connect to the SwfdecPlayer::invalidate signal to be notified of changes.

Audio output is handled via the SwfdecAudio class. One SwfdecAudio object is created for every output using the SwfdecPlayer::audio-added signal.

Details

enum SwfdecMouseCursor

typedef enum {
  SWFDEC_MOUSE_CURSOR_NORMAL,
  SWFDEC_MOUSE_CURSOR_NONE,
  SWFDEC_MOUSE_CURSOR_TEXT,
  SWFDEC_MOUSE_CURSOR_CLICK
} SwfdecMouseCursor;

This enumeration describes the possible types for the SwfdecPlayer::mouse-cursor property.

SWFDEC_MOUSE_CURSOR_NORMAL a normal mouse cursor
SWFDEC_MOUSE_CURSOR_NONE no mouse image
SWFDEC_MOUSE_CURSOR_TEXT a mouse cursor suitable for text editing
SWFDEC_MOUSE_CURSOR_CLICK a mouse cursor for clicking a hyperlink or a button

SwfdecPlayer

typedef struct _SwfdecPlayer SwfdecPlayer;

This is the base object used for playing Flash files.


swfdec_init ()

void        swfdec_init                     (void);

Initializes the Swfdec library.


swfdec_player_new ()

SwfdecPlayer* swfdec_player_new             (void);

Creates a new player. This function calls swfdec_init() for you if it wasn't called before.

Returns : The new player

swfdec_player_new_from_file ()

SwfdecPlayer* swfdec_player_new_from_file   (const char *filename,
                                             GError **error);

Tries to create a player to play back the given file. If the file does not exist or another error occurs, NULL is returned. This function calls swfdec_init() for you if it wasn't called before.

filename : name of the file to play
error : return location for error or NULL
Returns : a new player or NULL on error.

swfdec_player_set_loader ()

void        swfdec_player_set_loader        (SwfdecPlayer *player,
                                             SwfdecLoader *loader);

Sets the loader for the main data. This function only works if no loader has been set on player yet.

Note

If you want to capture events during the setup process, you want to connect your signal handlers before calling swfdec_player_set_loader() and not use conveniencse functions such as swfdec_player_new_from_file().

player : a SwfdecPlayer
loader : the loader to use for this player. Takes ownership of the given loader.

swfdec_player_is_initialized ()

gboolean    swfdec_player_is_initialized    (SwfdecPlayer *player);

Determines if the player is initalized yet. An initialized player is able to provide basic values like width, height or rate. A player may not be initialized if the loader it was started with does not reference a Flash resources or it did not provide enough data yet. If a player is initialized, it will never be uninitialized again.

player : a SwfdecPlayer
Returns : TRUE if the basic values are known.

swfdec_player_get_rate ()

double      swfdec_player_get_rate          (SwfdecPlayer *player);

Queries the framerate of this movie. This number specifies the number of frames that are supposed to pass per second. It is a multiple of 1/256. It is possible that the movie has no framerate if it does not display a Flash movie but an FLV video for example. This does not mean it will not change however.

player : a SwfdecPlayer
Returns : The framerate of this movie or 0 if it isn't known yet or the movie doesn't have a framerate.

swfdec_player_get_image_size ()

void        swfdec_player_get_image_size    (SwfdecPlayer *player,
                                             int *width,
                                             int *height);

If the size of the movie is already known, fills in width and height with the size. Otherwise width and height are set to 0.

player : a SwfdecPlayer
width : integer to store the width in or NULL
height : integer to store the height in or NULL

swfdec_player_get_next_event ()

guint       swfdec_player_get_next_event    (SwfdecPlayer *player);

Queries how long to the next event. This is the next time when you should call swfdec_player_advance() to forward to.

player : ia SwfdecPlayer
Returns : number of milliseconds until next event or 0 if no outstanding event

swfdec_player_render ()

void        swfdec_player_render            (SwfdecPlayer *player,
                                             cairo_t *cr,
                                             double x,
                                             double y,
                                             double width,
                                             double height);

Renders the given area of the current frame to cr.

player : a SwfdecPlayer
cr : cairo_t to render to
x : x coordinate of top left position to render
y : y coordinate of top left position to render
width : width of area to render or 0 for full width
height : height of area to render or 0 for full height

swfdec_player_advance ()

void        swfdec_player_advance           (SwfdecPlayer *player,
                                             guint msecs);

Advances player by msecs. You should make sure to call this function as often as the SwfdecPlayer::next-event property indicates.

player : the SwfdecPlayer to advance
msecs : number of milliseconds to advance

swfdec_player_handle_mouse ()

gboolean    swfdec_player_handle_mouse      (SwfdecPlayer *player,
                                             double x,
                                             double y,
                                             int button);

Updates the current mouse status. If the mouse has left the area of player, you should pass values outside the movie size for x and y. You will probably want to call swfdec_player_advance() before to update the player to the correct time when calling this function.

player : a SwfdecPlayer
x : x coordinate of mouse
y : y coordinate of mouse
button : 1 for pressed, 0 for not pressed
Returns : TRUE if the mouse event was handled. A mouse event may not be handled if the user clicked on a translucent area for example.

swfdec_player_render_audio ()

void        swfdec_player_render_audio      (SwfdecPlayer *player,
                                             gint16 *dest,
                                             guint start_offset,
                                             guint n_samples);

Renders the data for this frame into the given location. The data is added to dest, so you probably want to initialize dest to silence before calling this function.

player : a SwfdecPlayer
dest : location to add audio signal to. The audio signal will be in 44100kHz signed 16bit stereo.
start_offset : offset in samples at which to start rendering. The offset is calculated relative to the last iteration, so the value set by swfdec_player_set_audio_advance() is ignored.
n_samples : amount of samples to render.

swfdec_player_get_audio ()

const GList* swfdec_player_get_audio        (SwfdecPlayer *player);

Returns a list of all currently active audio streams in player.

player : a SwfdecPlayer
Returns : A GList of SwfdecAudio. You must not modify or free this list.

Property Details

The "cache-size" property

  "cache-size"           guint                 : Read

maximum cache size in bytes.

Default value: 52428800


The "initialized" property

  "initialized"          gboolean              : Read

TRUE when the player has initialized its basic values.

Default value: FALSE


The "mouse-cursor" property

  "mouse-cursor"         SwfdecMouseCursor     : Read

how the mouse pointer should be presented.

Default value: SWFDEC_MOUSE_CURSOR_NONE


The "next-event" property

  "next-event"           guint                 : Read

how many milliseconds until the next event or 0 when no event pending.

Default value: 0

Signal Details

The "advance" signal

void        user_function                  (SwfdecPlayer *player,
                                            guint         msecs,
                                            guint         audio_samples,
                                            gpointer      user_data)          : Run last

Emitted whenever the player advances.

player : the SwfdecPlayer affected
msecs : the amount of milliseconds the player will advance
audio_samples : number of frames the audio is advanced (in 44100Hz steps)
user_data : user data set when the signal handler was connected.

The "audio-added" signal

void        user_function                  (SwfdecPlayer *player,
                                            SwfdecAudio  *audio,
                                            gpointer      user_data)      : Run last

Emitted whenever a new audio stream was added to player.

player : the SwfdecPlayer affected
audio : the audio stream that was added
user_data : user data set when the signal handler was connected.

The "audio-removed" signal

void        user_function                  (SwfdecPlayer *player,
                                            SwfdecAudio  *audio,
                                            gpointer      user_data)      : Run last

Emitted whenever an audio stream was removed from player. The stream will have been added with the SwfdecPlayer::audio-added signal previously.

player : the SwfdecPlayer affected
audio : the audio stream that was removed
user_data : user data set when the signal handler was connected.

The "handle-mouse" signal

gboolean    user_function                  (SwfdecPlayer *player,
                                            gdouble       x,
                                            gdouble       y,
                                            gint          button,
                                            gpointer      user_data)      : Run last

this signal is emitted whenever player should respond to a mouse event. If any of the handlers returns TRUE, swfdec_player_handle_mouse() will return TRUE. Note that unlike many event handlers in gtk, returning TRUE will not stop further event handlers from being invoked. Use g_signal_stop_emission() in that case.

player : the SwfdecPlayer affected
x : new x coordinate of the mouse
y : new y coordinate of the mouse
button : 1 if the button is pressed, 0 if not
user_data : user data set when the signal handler was connected.
Returns : TRUE if this handler handles the event.

The "invalidate" signal

void        user_function                  (SwfdecPlayer *player,
                                            gdouble       x,
                                            gdouble       y,
                                            gdouble       width,
                                            gdouble       height,
                                            gpointer      user_data)      : Run last

This signal is emitted whenever graphical elements inside the player have changed. The coordinates describe the smallest rectangle that includes all changes.

player : the SwfdecPlayer affected
x : x coordinate of invalid region
y : y coordinate of invalid region
width : width of invalid region
height : height of invalid region
user_data : user data set when the signal handler was connected.

The "launch" signal

void        user_function                  (SwfdecPlayer *player,
                                            gchar        *url,
                                            gchar        *target,
                                            gpointer      user_data)      : Run last

Emitted whenever the player encounters an URL that should be loaded into a target the Flash player does not recognize. In most cases this happens when the user clicks a link in an embedded Flash movie that should open a new web page. The effect of calling any swfdec functions on the emitting player is undefined.

player : the SwfdecPlayer affected
url : URL to open
target : target to load the URL into
user_data : user data set when the signal handler was connected.

The "trace" signal

void        user_function                  (SwfdecPlayer *player,
                                            gchar        *text,
                                            gpointer      user_data)      : Run last

Emits a debugging string while running. The effect of calling any swfdec functions on the emitting player is undefined.

player : the SwfdecPlayer affected
text : the debugging string
user_data : user data set when the signal handler was connected.