mvPort(3dm) mvPort(3dm) NAME mvOpenPort, mvClosePort, mvBindMovieToPorts, mvUnbindMovieFromPorts, mvUnbindPortsFromMovie, mvGetMoviePorts, mvGetPortMovie, mvGetMovieMasterPort, mvGrabPort, mvReleasePort - Functions to handle generic playback ports SYNOPSIS #include <dmedia/movieplay.h> /* Port names */ #define MV_PORT_GFX "mvgfx" #define MV_PORT_AUDIO "mvaudio" #define MV_PORT_VIDEO "mvvideo" MVport mvOpenPort( const char *name, void *portData ); void mvClosePort( MVport port ); DMstatus mvBindMovieToPorts( MVid movieid, MVport *portList, int numPorts, int *numPortsBound ); DMstatus mvUnbindMovieFromPorts( MVid movieid ); DMstatus mvUnbindPortsFromMovie( MVport *ports, int numPorts ); MVid mvGetPortMovie( MVport port ); int mvGetMoviePorts( MVid movieid, MVport **portList ); MVport mvGetMovieMasterPort( MVid movieid ); void mvGrabPort( MVport port ); void mvReleasePort( MVport port ); void mvSetPortEnabled( MVport port, DMboolean enable ); DMboolean mvGetPortEnabled( MVport port ); void mvResizePort( MVport port ); DESCRIPTION Generic playback ports provide the application with more direct control over the playback configuration than the mvBindOpenGLWindow(3dm) interface. For example, applications that need to play movies in double-buffered windows should use open and bind an MV_PORT_GFX port while an application that desires to play only the audio from a movie should use an MV_PORT_AUDIO port. Applications that desire to play movies to video-out should open and bind MV_PORT_VIDEO. Use mvOpenPort(3dm) to open a playback port. name should be one of the port names listed in movieplay.h. portData should be a pointer to the corresponding port-specific data structure cast to a void *. On success, mvOpenPort(3dm) will return a handle that can be used to refer to the port. Errors are indicated by a 0 return value. There is a one to many relationship between movies and ports. Each movie can be bound to multiple ports, but each port can only be bound to one movie at a time. A movie can only be bound to at most one MV_PORT_AUDIO port and at most one MV_PORT_VIDEO or MV_PORT_GFX port at a given time. Ports should not be bound to a movie that has previously been bound with the mvBindOpenGLWindow(3dm) interface. Likewise, a movie should not be bound with mvBindOpenGLWindow(3dm) if it has been previous bound to ports. A port, or a group of ports, can be bound to a window via mvBindMovieToPorts(3dm). This routine returns DM_SUCCESS on success and returns the number of successfully bound ports in numBoundPorts. If numBoundPorts is less than numPorts, the first numBoundPorts in the array are the ports that were successfully bound. mvBindMovieToPorts(3dm) only adds to the list of ports bound to a movie. Use mvUnbindMovieFromPorts(3dm) to unbind a movie from all its ports. mvUnbindPortsFromMovie(3dm) unbinds each of the ports in the given list from its movie. A port maybe closed with mvClosePort(3dm). If the port is currently bound to a movie, it is first unbound before being closed. mvGetPortMovie(3dm) returns the movie to which the given port is bound (or 0 if the port is unbound). mvGetMoviePorts(3dm) returns the number of ports currently bound to the movie along with an array of ports. The memory returned by this call is only good until the movie's set of bound ports changes. You should use mvGrabPort(3dm) and mvReleasePort(3dm) to insure exclusive use of the port's data (e.g., graphics context, X window). See also mvGrabOpenGL(3dm) and mvReleaseOpenGL(3dm). The exact behavior of these calls is specific to each port as described below. mvSetPortEnabled(3dm) can be used to enable or display playback to a given port while it is bound to a movie. mvGetPortEnabled(3dm) returns the current enabled state of the port. When the port's data is changed, you should call mvResizePort(3dm) so the playback engine can update it's state. In particular, when a MV_PORT_GFX port's window has been resized, you should call mvResizePort(3dm). mvGetMovieMasterPort(3dm) returns the port from which synchonization information is being obtained. This may be useful for examining MV_EVENT_SYNC events (see mvEvent(3dm) for more details). This port is typically an MV_PORT_AUDIO port if the movie is bound to more than one port. MV_PORT_GFX typedef struct { Display *dpy; Window win; GLXContext ctxt; XVisualInfo *vInfo; DMboolean onscreenRender; /* obsolete */ } MVgfxPortData; The MV_PORT_GFX port should be used to play movies to a graphics screen window. dpy is an open X display connection, win is the window where the movie should be played, ctxt is an OpenGL/X graphics context that can be used in GL_RGBA_MODE on the specified window (see glXGetConfig(3g) and glXCreateContext(3g)), and vInfo is an X VisualInfo structure that describes the underlying X Visual of the window. The vInfo can be obtained via glXChooseVisual(3g). Multiple MV_PORT_GFX ports may refer to the same underlying X Window. If vInfo describes a double-buffered visual, MV_PORT_GFX will swap buffers after each movie image is drawn. The onscreenRender flag is obsolete and is ignored by the current implementation. When the MV_PORT_GFX port is disabled, images are not displayed but MV_EVENT_FRAME and MV_EVENT_SYNC events are still sent as if the port was clocking out images. Resizing the MV_PORT_GFX port tells it to take into account any changes in the window size. MV_PORT_AUDIO typedef struct { ALconfig config; /* in: config info for an ALport */ int ownsRate; /* in: true if the port can set the AL's rate */ double sampleRate; /* in: sample RATE to use, if 0 use hardware RATE */ } MVaudioPortData; The MV_PORT_AUDIO port should be used to play movies to the default audio output hardware. If config is NULL, the port will choose a configuration based on the movie it is playing. If you want the movie to be played using a specific audio configuration, you may set config in the port data structure. Note that you may not alFreeConfig(3dm) this config until you close the port. If you want the movie to be converted to a specific sample rate before it is played, set the ownsRate flag to DM_TRUE and the sampleRate accordingly. Setting the ownsRate flag to DM_TRUE also causes the port to set the current audio hardware output sample rate. This occurs even if the movie is not the primary audio movie, which can be set with mvSetPrimaryAudio(3dm). When this flag is DM_FALSE, the port will only set the audio hardware output sample rate if there is no other open ALport. When the audio port is disabled, no audio is sent to the hardware and no MV_EVENT_SYNC events are sent. Resizing the MV_PORT_AUDIO port has no effect. MV_PORT_VIDEO typedef struct { Display * dpy; /* If NULL, only show on video-out */ Window win; /* If None, only show on video-out */ GLXContext ctxt; /* If NULL, only show on video-out */ XVisualInfo * vInfo;/* optional */ DMboolean flickerFilter; /* currently unused */ VLServer svr; /* currently unused */ VLPath path; /* currently unused */ VLNode src; /* currently unused */ VLNode drn; /* currently unused */ } MVvideoPortData; The MV_PORT_VIDEO port should be used to play movies to the video output hardware and, optionally, to a simultaneous graphics screen window. If either dpy is NULL or win is None, the movie is only played to the video-output jack. Accurate synchronization with audio is maintained with the video-jack only. The optional graphics display is meant as a convenience and the synchronization may drift slightly. dpy is an (optional) open X display connection, win is an (optional) window where the movie should be played, ctxt is an (optional) OpenGL/X graphics context that can be used in GL_RGBA_MODE on the specified window (see glXGetConfig(3g) and glXCreateContext(3g)), and vInfo is an (optional) X VisualInfo structure that describes the underlying X Visual of the window. The vInfo can be obtained via glXChooseVisual(3g). svr, path, src, drn, and flickerFilter are currently unused. They should be set to 0 to achieve compatibility with future versions of the Movie Playback Library. Resizing the MV_PORT_VIDEO port only affects the optional graphics display. See mvVideoDisplay(3dm) for resizing the movie for video output. Also see mvVideoStillFrame(3dm) for details on how video still frames are displayed. When the MV_PORT_VIDEO port is disabled, images are not displayed but MV_EVENT_FRAME and MV_EVENT_SYNC events are still sent as if the port was clocking out images. HARDWARE DEPENDENCIES MV_PORT_VIDEO is fully suppored on O2. MV_PORT_VIDEO is partially supported on Octane with Octane Video/Octane Compression. For these configurations, only a Octane compatibile JPEG movie can be successfully bound to MV_PORT_VIDEO. MV_PORT_VIDEO is currently unsupported on all other hardware. SEE ALSO alIntro(3dm), mvBindOpenGLWindow(3dm), mvEvent(3dm), mvClose(3dm), mvIntro(3dm), mvOpen(3dm), mvSetNumMoviesHint(3dm), mvVideoDisplay(3dm), mvVideoStillFrame(3dm). Page 5