b2dLoadMovie

Loads BBV movie file (BambooBasic Video, ZIP-compressed with header+frames, streaming playback). Takes filename (path to .bbv file, string). Returns movie handle (positive integer, use with b2dPlayMovie/etc), returns 0 on failure (file not found, invalid BBV format, ZIP extraction error). Opens ZIP archive (miniz reader for compressed .bbv files), extracts header.bin (BBVHeader with magic "BBV1", width, height, frameCount, fps), validates format (checks magic number, header size), stores movie data (creates MovieData structure with playback state, ZIP archive handle). Use for video playback (cutscenes, background videos, animated textures), streaming video (frames loaded on-demand from ZIP, low memory footprint), or animated content (pre-rendered animations, video effects). BBV format: ZIP container (contains header.bin + frame_0000.rgba through frame_NNNN.rgba), header.bin (BBVHeader struct: magic[4]="BBV1", width, height, frameCount, fps), frame files (raw RGBA pixel data, widthxheightx4 bytes per frame, uncompressed inside ZIP). File structure: .bbv is standard ZIP archive, extractable with any ZIP tool, frames are named sequentially (frame_0000.rgba, frame_0001.rgba, etc.), streaming approach (only current frame loaded in memory, not entire video). Use cases: (1) Cutscene (movie=b2dLoadMovie("intro.bbv"): b2dPlayMovie(movie): While b2dMoviePlaying(movie): b2dDrawMovie(movie,x,y): b3dRenderWorld()), (2) Background video (bgMovie=b2dLoadMovie("background.bbv"): b2dPlayMovie(bgMovie): draw as animated background), (3) Looping animation (movie=b2dLoadMovie("flames.bbv"): loop playback for animated fire effect), (4) Video texture (load movie, draw to render target, use as animated texture on 3D mesh). Common patterns: load = movie=b2dLoadMovie("video.bbv") returns handle; check = If movie=0 Then Print "Failed to load movie". Movie data structure: MovieData allocated (contains filename, dimensions, frameCount, fps), playback state initialized (playing=false, paused=false, currentFrame=-1), ZIP archive stored (zipArchive pointer for extracting frames on-demand), single frame texture (currentFrameHandle reused, only one frame in GPU memory at a time). Streaming details: frames extracted on-demand (mz_zip_reader_extract_file_to_heap during playback), low memory (only current frame in RAM+GPU, not all frames), ZIP compression (smaller file size than raw frame sequence, ~10-50% compression ratio), seek support (can extract any frame by name, frame_NNNN.rgba format). Performance: load time (opens ZIP, reads header ~1-10ms, no frame loading yet), memory footprint (header + MovieData struct + ZIP reader state ~1-10KB, frames loaded on-demand), first frame cost (extracted during first b2dDrawMovie call, decompression ~1-50ms depending on frame size). Validation: returns 0 if file not found (ZIP reader init fails, file doesn't exist), returns 0 if header missing (no header.bin in ZIP archive), returns 0 if header size wrong (header.bin not sizeof(BBVHeader)), returns 0 if magic invalid (header.magic != "BBV1"), handle valid until freed (use handle with Play/Stop/Pause/Draw functions). Related: b2dFreeMovie releases movie (closes ZIP, frees resources, deallocates MovieData), b2dPlayMovie starts playback (begins streaming frames from ZIP), b2dDrawMovie renders current frame (extracts frame from ZIP if needed, draws as image), b2dMoviePlaying queries playback state (returns 1 if playing or paused), b2dStopMovie stops playback (resets to beginning, closes active stream).