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.
Page 1
mvPort(3dm)mvPort(3dm)
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
Page 2
mvPort(3dm)mvPort(3dm)
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
Page 3
mvPort(3dm)mvPort(3dm)
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
Page 4
mvPort(3dm)mvPort(3dm)
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 ALSOalIntro(3dm), mvBindOpenGLWindow(3dm), mvEvent(3dm), mvClose(3dm),
mvIntro(3dm), mvOpen(3dm), mvSetNumMoviesHint(3dm), mvVideoDisplay(3dm),
mvVideoStillFrame(3dm).
Page 5
