b2dDrawMovie

Draws current movie frame at position (uses b2dDrawImage, frame auto-updated by b2d_Movie_UpdateFrame). Takes handle (movie handle from b2dLoadMovie, integer), x (screen X position in pixels), y (screen Y position in pixels). Returns nothing. Draws movie->currentFrameHandle image (current frame texture, updated automatically during playback), uses b2dDrawImage (delegates to standard image rendering, applies current 2D state), does nothing if currentFrameHandle==0 (no frame loaded yet, movie not started). Use to render playing movie (draw current frame to screen), display video content (cutscenes, background videos, animated textures), or show paused frame (frame remains drawable when paused). Frame update mechanism: automatic (b2d_Movie_UpdateFrame called internally during 2D overlay rendering), timing-based (elapsed time determines which frame to show, frame = floor(elapsed x fps)), on-demand extraction (frame extracted from ZIP when needed, targetFrame != currentFrame), texture reuse (currentFrameHandle reused, GPU texture updated with b2dUpdateImagePixels). Use cases: (1) Cutscene loop (While b2dMoviePlaying(movie): b2dDrawMovie(movie,x,y): b3dRenderWorld() render until complete), (2) Background video (b2dDrawMovie(bgMovie,0,0): draw game content on top animated background), (3) UI video (b2dDrawMovie(logoMovie,x,y) animated logo or UI element), (4) Paused frame (b2dPauseMovie(movie): b2dDrawMovie(movie,x,y) show frozen frame). Common patterns: simple draw = b2dDrawMovie(movie,x,y) at position; centered = b2dDrawMovie(movie,(screenW-movieW)/2,(screenH-movieH)/2); loop = While playing: draw movie. Frame loading: first frame (extracted during first b2d_Movie_UpdateFrame call after b2dPlayMovie, creates image with b2dCreateImageFromPixels), subsequent frames (extracted when targetFrame changes, updates existing texture with b2dUpdateImagePixels), no draw if no frame (if movie not started with b2dPlayMovie, currentFrameHandle==0, draw does nothing). Position and state: x/y position (top-left corner of movie frame), respects 2D state (global color, alpha, rotation, scale from b2dSetColor/b2dSetAlpha/b2dSetRotation/b2dSetScale), respects active shader (if b2dSetImageShader active, applies to movie frame), batched rendering (queued as CMD_DRAW_IMAGE command, executed during flush). Performance: draw cost (same as b2dDrawImage, ~0.01-0.1ms per frame depending on size), frame update cost (ZIP extraction ~1-50ms when frame changes, amortized over frame duration), no update if same frame (if targetFrame==currentFrame, no extraction, just draws cached texture), texture reuse (single GPU texture for all frames, not one per frame, memory efficient). Validation: silently ignores if handle<=0 or not found (negative, zero, or invalid handle), does nothing if currentFrameHandle==0 (no frame loaded, movie not started or no frames extracted), safe to call before b2dPlayMovie (draws nothing, no error). Related: b2dDrawMovieScaled draws scaled to size (target width/height instead of original size), b2dDrawScaledMovie draws with scale factors (scaleX/scaleY applied to dimensions), b2dPlayMovie starts playback (must call before draw shows anything, starts frame extraction), b2dMoviePlaying queries state (check if movie active before drawing), b2dPauseMovie pauses playback (frame remains drawable when paused).