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) #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; 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 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 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. 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 ALSO mvIntro(3dm), mvGetErrorStr(3dm), mvPort(3dm), schedctl(2). Page 6