simvx.graphics.streaming.scene3d_serializer

Binary serialization of 3D render state for WebSocket streaming.

Serializes a complete 3D scene frame into compact binary for transmission to a browser-side WebGPU renderer.

Wire format per frame::

HEADER (20 bytes):
    frame_id(u32) flags(u32) viewport_count(u32) light_count(u32) draw_group_count(u32)

Per VIEWPORT (136 bytes):
    x(u32) y(u32) w(u32) h(u32) + view_mat(16×f32) + proj_mat(16×f32)

RESOURCES (only if flags bit 0 set):
    mesh_count(u32) + texture_count(u32) + material_count(u32)
    Per mesh:   mesh_id(u32) vertex_count(u32) index_count(u32)
                vertex_bytes(vertex_count × 32)
                index_bytes(index_count × 4)
    Per texture: tex_id(u32) width(u32) height(u32) pixel_bytes(width × height × 4)
    material_bytes(material_count × MATERIAL_DTYPE.itemsize)

LIGHTS (light_count × LIGHT_DTYPE.itemsize bytes):
    Raw LIGHT_DTYPE data

DRAW GROUPS (draw_group_count entries):
    Per group: mesh_id(u32) index_count(u32) instance_count(u32) pass_type(u32)
    transform_bytes(instance_count × 64)  -- 4×4 model matrix per instance, f32
    material_ids(instance_count × u32)
    pass_type: 0=OPAQUE, 1=DOUBLE_SIDED, 2=TRANSPARENT

POST-PROCESS (only if flags bit 1 set, 16 bytes):
    bloom_enabled(u32) bloom_threshold(f32) bloom_intensity(f32) bloom_soft_knee(f32)

Module Contents

Classes

Scene3DSerializer

Serializes 3D scene state into binary frames for WebSocket streaming.

Data

__all__

FLAG_HAS_RESOURCES

FLAG_HAS_POST_PROCESS

API

simvx.graphics.streaming.scene3d_serializer.__all__

[‘Scene3DSerializer’]

simvx.graphics.streaming.scene3d_serializer.FLAG_HAS_RESOURCES

None

simvx.graphics.streaming.scene3d_serializer.FLAG_HAS_POST_PROCESS

None

class simvx.graphics.streaming.scene3d_serializer.Scene3DSerializer[source]

Serializes 3D scene state into binary frames for WebSocket streaming.

static serialize_frame(frame_id: int, viewports: list[dict[str, Any]], lights: numpy.ndarray, draw_groups: list[dict[str, Any]], resources: dict[str, Any] | None = None, post_process: dict[str, Any] | None = None) → bytes[source]

Serialize a 3D scene frame into compact binary.

Args: frame_id: Monotonic frame counter. viewports: List of dicts with keys x, y, width, height, view_matrix, proj_matrix (matrices are 4x4 float32 arrays). lights: Structured numpy array with dtype LIGHT_DTYPE. draw_groups: List of dicts with keys mesh_id, index_count, transforms, material_ids where transforms is (N, 4, 4) float32 and material_ids is (N,) uint32. resources: Optional dict with keys meshes, textures, materials for initial upload. meshes: list of (mesh_id, vertices, indices). textures: list of (tex_id, width, height, pixels). materials: structured numpy array with dtype MATERIAL_DTYPE. post_process: Optional dict with bloom settings: bloom_enabled (bool), bloom_threshold (float), bloom_intensity (float), bloom_soft_knee (float).

Returns: Compact binary frame ready for WebSocket transmission.

static deserialize_frame(data: bytes) → dict[str, Any][source]

Deserialize a binary frame back into structured data (for testing).

Returns: Dict with keys: frame_id, flags, viewports, lights, draw_groups, resources (optional).