b2dPauseMovie

Pauses movie playback at current frame (sets playing=false, paused=true, preserves currentFrame and activeHandle). Takes handle (movie handle from b2dLoadMovie, integer). Returns nothing. Only pauses if currently playing (checks movie->playing before pausing), sets playing=false (stop frame advancement), sets paused=true (mark as paused state), preserves currentFrame (frame position maintained for resume), preserves g_activeMovieHandle (keeps texture valid, allows drawing paused frame). Use to pause during cutscene (user pause menu, temporary interruption), freeze on current frame (hold frame visible while paused), or interactive control (pause/resume video playback). Pause vs Stop: pause preserves position (currentFrame kept, use b2dResumeMovie to continue from same frame), stop resets to beginning (currentFrame=-1, use b2dPlayMovie to restart from frame 0), pause keeps texture valid (current frame remains drawable with b2dDrawMovie), stop clears state completely (playing=false, paused=false, finished=false). Use cases: (1) User pause (If KeyHit(KEY_P) Then b2dPauseMovie(cutscene) pause cutscene), (2) Pause menu (b2dPauseMovie(movie): show pause UI: b2dResumeMovie(movie) when unpause), (3) Freeze frame (b2dPauseMovie(movie): draw paused frame continuously), (4) Interactive video (pause at decision points, resume after user choice). Common patterns: pause = b2dPauseMovie(movie) freeze at current frame; conditional pause = If paused Then b2dResumeMovie(movie) Else b2dPauseMovie(movie) toggle; draw paused = b2dPauseMovie(movie): b2dDrawMovie(movie,x,y) shows frozen frame. Playback state after pause: playing=false (frame no longer advances with time), paused=true (distinguishes from stopped state), currentFrame preserved (exact frame where paused, used by resume), activeHandle preserved (g_activeMovieHandle still set to this movie, texture remains valid), b2dMoviePlaying returns 1 (movie considered "playing" if playing OR paused). Resume mechanics: b2dResumeMovie adjusts startTime (recalculates to account for pause duration, elapsed frames = currentFrame, new startTime = now - (currentFrame / fps)), continues from preserved frame (frame position maintained across pause/resume), seamless playback (no visible jump or stutter when resuming). Performance: cost zero (only sets state variables, no GPU/IO operations), immediate (no frame processing, texture remains valid), lightweight (safe to call even if not playing, does nothing if not playing). Validation: silently ignores if handle<=0 or not found (negative, zero, or invalid handle), only pauses if playing (checks movie->playing, does nothing if already paused or stopped), safe to call multiple times (idempotent if already paused). Related: b2dResumeMovie resumes playback (continues from paused position, use after pause), b2dStopMovie stops playback (alternative to pause, resets to beginning instead of preserving position), b2dPlayMovie starts playback (use after stop, not after pause, b2dResumeMovie correct after pause), b2dIsMoviePaused queries paused state (returns 1 if paused, 0 if playing or stopped), b2dMoviePlaying queries playing state (returns 1 if playing OR paused).