mvGrabRelease(3dm)                                          mvGrabRelease(3dm)


NAME
     mvGrabOpenGL, mvReleaseOpenGL - provide safe usage of graphics libraries
     from Movie Playback Library clients


SYNOPSIS
     #include <dmedia/movieplay.h>


     void mvGrabOpenGL(void);

     void mvReleaseOpenGL(void);


DESCRIPTION
     mvGrabOpenGL(3dm) tells the Movie Playback Library that your application
     wishes to use OpenGL.  These functions temporarily suspend display of all
     movie instances until you call mvReleaseOpenGL(3dm).  mvGrabOpenGL(3dm)
     does not stop playback; instead, it merely suspends the display of images
     on the workstation screen.

     Internally, the Movie Playback Library uses the sproc(2) system call to
     provide asynchronous playback in a separate execution thread. Multiple
     threads in the same process may have access to the graphics library, but
     no two threads may issue a graphics library call simultaneously.  Thus,
     you must tell Movie Playback Library when you intend to use the graphics
     library so that it can avoid making a graphics library call at the same
     time you do.  Currently under X11, in order to have multiple threads work
     safely, each thread must have it's own display connection.  The Movie
     Playback Library opens up a separate display connection for each thread
     that needs one and it uses the display connection provided via
     mvOpenPort(3dm) or mvBindOpenGLWindow(3dm) in the thread in which those
     calls were invoked.

     If you perform graphics library rendering in the same process as you use
     the Movie Playback Library for playback, you should call the relevant
     grab function before and release function after those places in your code
     where graphics library calls are invoked.  The Movie Playback Library
     will not update the on-screen images of the movies while you have grabbed
     the graphics library, so if your rendering takes a long time, movie
     playback will appear interrupted.

     Once you grab the graphics library, you must always call
     mvReleaseOpenGL(3dm) to resume normal movie playback.  You must not call
     mvReleaseOpenGL(3dm) without first calling mvGrabOpenGL(3dm).  Finally,
     you should not invoke two grab functions or two release functions in
     succession without calling the counterpart function in between.

     As an alternative to these calls, you may instead tell Movie Playback
     Library not to display images on the screen altogether.  To do this, use
     mvSetEnableVideo(3dm).  Then, you request frame events via the Movie
     Playback Library event queue.  When you receive a frame event, you can


     tell Movie Playback Library to display the frame by calling
     mvShowCurrentFrame(3dm).  This alternate method will eliminate any chance
     of contention for the graphics library, without requiring you to use
     mvGrabOpenGL(3dm).


SEE ALSO
     mvBindOpenGLWindow(3dm), mvIntro(3dm), mvNextEvent(3dm), mvOpenPort(3dm),
     mvRenderMovieToImageBuffer(3dm), mvRenderMovieToOpenGL(3dm),
     mvSetEnableVideo(3dm), sproc(2)


                                                                        Page 2