b3dSetSurfaceMovieTexture

Applies movie (video) texture to surface for dynamic video playback on 3D geometry. Takes meshEntityHandle (mesh entity), surfaceHandle (0-based surface index), movieHandle (movie handle from b2d movie system). Returns nothing. Validates mesh is surface-based and surface exists, gets movie texture GPU resource from b2d system (b2d_GetMovieTextureResource), creates or reuses 3D texture entry for movie (named "movie_N"), creates SRV in 3D descriptor heap referencing movie's GPU resource, creates material with movie texture (white tint, non-metallic, rough, solid blend), assigns material to surface, flags mesh for GPU upload. Movie texture automatically updates each frame as video plays.

This function enables video-on-surface for screens, monitors, and dynamic textures. Movie integration: movies loaded/played via b2d (2D) movie system, this function bridges b2d movie to 3D surface texture. GPU resource sharing: movie texture rendered by b2d system, 3D system creates SRV descriptor referencing same GPU resource (no copy, shared texture). Texture naming: movie textures named "movie_N" (N=movieHandle) for tracking, allows reuse if same movie applied to multiple surfaces. Texture entry creation: if movie not in g_textures, creates new Texture3D entry with isMovieTexture=true flag (prevents cleanup, b2d system owns resource), creates SRV in 3D descriptor heap, stores movie handle for tracking. SRV creation: Shader Resource View maps movie GPU texture to 3D shader-accessible descriptor, format DXGI_FORMAT_R8G8B8A8_UNORM, single mip level. Material properties: white tint (1,1,1,1) shows video colors unmodified, metallic=0.0 (non-metallic), roughness=1.0 (matte, avoids shiny video), blendMode=0 (solid, opaque), stores movieHandle in material for updates. Use cases: (1) TV/monitor screens in 3D scenes, (2) Billboard advertisements (animated), (3) Security camera feeds, (4) In-game cinematics on surfaces, (5) Video walls/projections. Common pattern: movie=b2dLoadMovie("ad.mp4"), b2dPlayMovie(movie), mesh=b3dCreateCube(...), b3dSetSurfaceMovieTexture(mesh, 0, movie), plays video on cube face. Requirements: mesh must be surface-based (isSurfaceBased=true), loaded meshes not supported. Surface must have valid UV coordinates for texture mapping. Movie must be loaded and valid in b2d system. Dynamic updates: as movie plays, b2d system updates GPU texture each frame, 3D rendering automatically shows updated frames (no explicit update needed). Texture persistence: Texture3D entry reused if same movie applied multiple times (checks "movie_N" name), avoids duplicate SRVs. Material lifetime: creates new material per call, allows multiple surfaces to display same or different movies. GPU resource ownership: b2d system owns movie texture resource, 3D system references only (isMovieTexture flag prevents deletion). Handle validation: validates mesh, surface, movie texture resource. Surface handle: 0-based index into mesh->surfaces. GPU upload: sets needsGPUUpload for buffer recreation. Typical workflow: load movie (b2d), create 3D mesh with UVs, apply movie to surface, play movie (b2d), 3D surface shows live video. Related: b2dLoadMovie loads video file, b2dPlayMovie starts playback, b3dCreateMesh/b3dCreateSurface create paintable surfaces, b3dPaintSurface for static textures (non-video).