mvEvent(3dm)mvEvent(3dm)NAME
mvGetEventFD, mvSetSelectEvents, mvGetSelectEvents, mvNextEvent,
mvPeekEvent, mvPendingEvents, mvGetMovieEventFD, mvSetMovieSelectEvents,
mvGetMovieSelectEvents, mvNextMovieEvent, mvPeekMovieEvent,
mvPendingMovieEvents mvGetPlayErrorStr - Movie Playback Library event
handling functions
SYNOPSIS
#include <dmedia/movieplay.h>
/* Per Application event handling */
DMstatus mvGetEventFD(int *fdreturn);
void mvSetSelectEvents(MVeventmask eventmask);
MVeventmask mvGetSelectEvents(void);
void mvNextEvent(MVevent *eventreturn);
void mvPeekEvent(MVevent *eventreturn);
int mvPendingEvents(void);
/* Per Movie event handling */
DMstatus mvGetMovieEventFD(MVid movie, int *fdreturn);
void mvSetMovieSelectEvents(MVid movie, MVeventmask eventmask);
MVeventmask mvGetMovieSelectEvents(MVid movie);
void mvNextMovieEvent(MVid movie, MVevent *eventreturn);
void mvPeekMovieEvent(MVid movie, MVevent *eventreturn);
int mvPendingMovieEvents(MVid movie);
/* Error String */
const char * mvGetPlayErrorStr(int errcode, pid_t pid);
typedef __uint32_t MVeventmask;
#define MV_EVENT_MASK_FRAME (1<<1)
#define MV_EVENT_MASK_STOP (1<<2)
#define MV_EVENT_MASK_ERROR (1<<3)
#define MV_EVENT_MASK_SLOW_PLAY (1<<4)
#define MV_EVENT_MASK_SYNC (1<<5)
#define MV_EVENT_MASK_WARNING (1<<6)
Page 1
mvEvent(3dm)mvEvent(3dm)
#define MV_EVENT_MASK_SCHED (1<<7)
typedef Time MVtime; /* "Time" is from X11 */
typedef enum __MVeventtype
{
MV_EVENT_FRAME = 1,
MV_EVENT_STOP = 2,
MV_EVENT_ERROR = 3,
MV_EVENT_SLOW_PLAY = 4,
MV_EVENT_SYNC = 5,
MV_EVENT_WARNING = 6,
MV_EVENT_SCHED = 7
} MVeventtype;
typedef struct __mvFrameEvent { /* a frame just played */
MVeventtype type; /* event type */
MVtime time; /* obsolete field */
MVid id; /* movie instance which produced the event */
MVframe frame; /* current frame for the movie instance */
} MVframeevent;
typedef struct __mvStopEvent { /* the movie stopped at the end */
MVeventtype type;
MVtime time;
MVid id;
MVframe frame;
} MVstopevent;
typedef struct __mvErrorEvent { /* error condition halting playback */
MVeventtype type;
MVtime time;
MVid id;
MVframe frame;
int errcode;
pid_t pid;
} MVerrorevent;
typedef struct __mvSyncEvent { /* sync information */
MVeventtype type;
MVtime obsolete;
MVid id;
MVport port;
MVsyncInfo syncInfo;
} MVsyncevent;
typedef struct __mvWarningEvent { /* warning condition */
MVeventtype type;
MVtime obsolete;
MVid id;
MVtime movieTime;
MVtime duration;
Page 2
mvEvent(3dm)mvEvent(3dm)
MVtimescale scale;
int errcode;
pid_t pid;
} MVwarningevent;
typedef struct __mvSchedEvent { /* scheduling event */
MVeventtype type;
MVtime obsolete;
MVid id;
DMboolean realTime;
} MVschedevent;
typedef struct {
MVeventtype type;
MVtime obsolete;
MVid id;
} MVgenericevent;
typedef union __mvEvent {
MVeventtype type; /* common to all events */
MVframeevent mvframe;
MVstopevent mvstop;
MVerrorevent mverror;
MVslowplayevent mvslowplay; /* obsolete */
MVsyncevent mvsyncevent;
MVwarningevent mvwarningevent;
MVschedevent mvschedevent;
MVgenericevent mvgeneric; /* all events may be safely cast to this */
} MVevent;
DESCRIPTION
These calls initialize and provide access to the Movie Playback Library
event queues. There is one queue to which events are sent for all
movies. Also, each movie provides an event queue which receives events
for only that movie. An application should choose to either use the
per/movie event queues or the global event queue. Mixing the use of
these is unwise as events are sent to both queues and the application
will see events twice.
Without exception, in the following, each statement about a given event
queue routine holds for both the global application queue as well as the
per movie queues. Thus, this page only documents the global application
queue; behavior of the per movie event queues is implied.
The event queues provide the following types of events:
MV_EVENT_FRAME - A frame has played for a movie
instance. The frame number is in the range from zero to
one less than the length of in the movie's image track.
MV_EVENT_STOP - The movie has stopped playback.
MV_EVENT_ERROR - An error has occurred during
Page 3
mvEvent(3dm)mvEvent(3dm)
playback.
MV_EVENT_SYNC - UST synchronization information
for a playback port is available.
MV_EVENT_WARNING - A non-fatal error has occurred
during playback.
MV_EVENT_SCHED - The scheduling priority for movie playback
has changed.
If you request MV_EVENT_STOP events, the Movie Playback Library will send
you a MV_EVENT_STOP event if it stops playback for any reason. The Movie
Playback Library can stop playback if it reaches the end of the movie, or
if you call mvStop(3dm).
If you request MV_EVENT_SYNC events, the Movie Playback Library will send
you a MV_EVENT_SYNC event every time a port updates its synchronization
information. You can determine if this event pertains to the master
synchonization source for this movie by calling mvGetMovieMasterPort with
the port provided in this event.
If you request MV_EVENT_WARNING events, the Movie Playback Library will
send you a MV_EVENT_WARNING event every time some non-fatal error occurs.
Use the errcode field in the event to determine which error has occured.
The most common warnings are that the Movie Playback Library skipped
(MV_FRAME_SKIPPED) or repeated (MV_FRAME_REPEATED) a frame for some
duration.
In order to achieve real-time behavior, the Movie Playback Library may
attempt to change the IRIX process scheduling priority of one of its
threads. If you request MV_EVENT_SCHED events, the Movie Playback
Library will send you a MV_EVENT_SCHED every time it changes the
scheduling priority for playback. The realTime field in the event
indicates whether or not the Movie Playback Library has attained the
scheduling priority it deems necessary for real-time playback. Note that
the Movie Playback Library will only succeed in changing the priority
under certain circumstances because it uses the schedctl(2) system call.
See the "Lurker's Guide to Video"
(http://reality.sgi.com/employees/cpirazzi_esd/lg) and, in particular,
the link on "Seizing Higher Scheduling Priority" for details.
mvGetEventFD(3dm) returns a file descriptor associated with the event
queue. You should wait upon this file descriptor using the poll(2) or
select(2) system calls to receive notification when there are one or more
pending events from the Movie Playback Library.
There is only one movie event queue, for all of the movies you create.
Therefore, you should call mvGetEventFD(3dm) only once in your
application, regardless of the number of movie instances you create. You
may call mvGetEventFD(3dm) at any time.
mvSetSelectEvents(3dm) allows you to determine which types of movie
events your application code is interested in handling. To indicate that
you wish to receive one or more types of movie playback events, set the
Page 4
mvEvent(3dm)mvEvent(3dm)
appropriate bits in eventmask, using the Movie Playback Library event
mask definitions.
By default, Movie Playback Library reports MV_EVENT_STOP and
MV_EVENT_ERROR to you. If you have not initialized the event queue with
mvGetEventFD(3dm), you will not receive any events.
To determine the current event mask, call mvGetSelectEvents(3dm).
mvNextEvent(3dm) returns the next movie event from the movie event queue.
If there are no movie events pending, your process will block until a
movie event becomes available.
mvNextEvent(3dm) uses the event structures described above. The MVevent
structure is a union of all of the Movie Playback Library event
structures. The type field indicates the event type. Every event may be
safely cast to the MVgenericevent structure, which contains an id field
indicating the movie instance to which the event refers.
The movie event structures add fields pertaining to the specifics of the
event. For example, both the MVerrorevent and MVwarningevent structures
add an additional field indicating the reason for the event.
mvPeekEvent(3dm) returns the next event, without removing it from the
event queue.
mvPendingEvents(3dm) returns the number of movie events currently
pending.
mvGetPlayErrorStr(3dm) should be used to return the error string
associated with an errcode received in an MV_EVENT_ERROR. You should
pass the errcode and process id (pid) received in the error event. (The
Movie Playback Library uses the pid to uniquely identify the error
string.)
The Movie Playback Library event queue is separate from the X Window
System event queue. If your application is based on Xlib, you may wait
upon both the X11 event queue and the Movie Playback Library event queue
using the select(2) system call. To obtain a file descriptor
corresponding to the X11 event queue for a specified display, use the
Xlib ConnectionNumber(3X) macro.
If your application is based upon the X Toolkit (such as the Athena
widget set or the IRIS IM toolkit, Silicon Graphics' port of the
industry-standard OSF/Motif toolkit for use on Silicon Graphics systems),
you may pass the file descriptor returned by mvGetEventFD(3dm) to the X
Toolkit XtAppAddInput(3Xt) call. The X Toolkit will then invoke an Xt
callback procedure in your application whenever one or more events appear
on the Movie Playback Library event queue.
Page 5
mvEvent(3dm)mvEvent(3dm)NOTES
OSF/Motif is a trademark of the Open Software Foundation, Inc.
OBSOLETE EVENTS
MV_EVENT_SLOW_PLAY - In previous versions, the Movie Playback Library
sent this event when it could not play the movie at the desired frame
rate. This event is no longer sent. See the new MV_EVENT_WARNING
described above.
SEE ALSOmvIntro(3dm), mvGetErrorStr(3dm), mvPort(3dm), schedctl(2).
Page 6
