Model Formats

Model formats

LoadMesh, LoadAnimMesh and LoadAnimSeq read Blitz3D's own .b3d, DirectX .x, 3D Studio .3ds and glTF 2.0 files. The format is told by what is in the file, not by its name.

• LoadMesh makes one mesh of the model as it looks without animation.
• LoadAnimMesh keeps the nodes as entities with the animation of the file, for Animate, SetAnimTime, FindChild and LoadAnimSeq.

The picture of a material is looked for next to the model and then in the folder of the program.

What the formats define themselves is not repeated here, only how it becomes a Blitz3D mesh and what is left out.

DirectX (.x)

Text, binary and compressed (tzip, bzip) files are read, as in the original. A file that ends or breaks in the middle of an object loads what is before the damage, with a warning on the console. Objects without a template are skipped.

• A Frame is a mesh entity with the name of the frame; a skew in its matrix is lost. LoadMesh merges all frames as they are before the animation.
• Faces with more than three corners are split into a fan. A mesh without normals gets them made; one whose MeshNormals or MeshTextureCoords count differs from its vertices uses neither, as in the original. There is one set of texture coordinates, and vertex colors are set on the vertices (EntityFX 2 shows them).
• A material becomes a brush from its face color (alpha 0 counts as opaque, as in the original) and its first TextureFilename, which also makes the color white. Folders of the machine that made the model are cut off. Triangles with the same brush share a surface.
• All animation sets are one animation, as long as the last key. Matrix keys (type 4) are not used, and scales are made positive.
• There are no bones: XSkinMeshHeader and SkinWeights are read but not used, so a mesh moves with its frame, as in the original.
• LoaderMatrix "x", ... turns the vertices, normals, frames and keys of every .x file loaded after it.

3D Studio (.3ds)

An extension: the original names .3ds but its loader never worked with animations. LoadAnimMesh makes a pivot with an entity for each object, light and camera, with the hierarchy and animation of the file.

• The axes are converted to Blitz3D (y and z swapped, triangle corners reordered, v flipped). LoaderMatrix does not change this.
• Normals come from the smoothing groups; a face without a group is flat.
• A material becomes a brush with the diffuse color, shininess, transparency (alpha), two sided (EntityFX 16), additive (blend 3), flat shading (EntityFX 4) and a self-illumination of more than half (EntityFX 1). The first texture map is the texture, with tiling, offset and rotation applied to the vertex coordinates. Other maps (bump, specular, reflection, opacity) and the ambient and specular colors are not used.
• Keys are 30 frames a second and go straight from key to key (tension, continuity and bias are not used). The color of a light over time, the field of view, morphs and visibility keys are not used.
• Lights are LIGHT entities (point, or spot with the hotspot and falloff as the cone), hidden if off. Cameras are pivots that look at their target. A hidden node is a hidden entity and not in the mesh of LoadMesh; a dummy object is a pivot.

glTF (.gltf, .glb)

An extension, read with the cgltf library.

• The conversion mirrors x to go from right-handed to Blitz3D's left-handed axes; a model that faces +z in glTF faces +z here. The unit is what the file says.
• Every node is an entity below one entity that stands for the scene (the scene of the file, the first one, or everything if there is none). Lights (KHR_lights_punctual) and cameras become children of their node, named like the light or camera (or <node> light / <node> camera). A light keeps its color, range and spot cone (the intensity is not used). A camera is made with CameraProjMode 0, so it does not draw over the camera of the program until you switch it on.
• A mesh with several primitives has a surface for each material.
• Triangles, strips and fans are read. Points and lines are not.
• Normals, two sets of coordinates (TEXCOORD_0, TEXCOORD_1), vertex colors and KHR_mesh_quantization are read. A primitive without normals gets smooth ones.
• Tangents and morph targets are not used.
• A material becomes a brush: baseColorFactor is color and alpha, baseColorTexture the picture, 1 - roughnessFactor the shininess, doubleSided is EntityFX 16 and KHR_materials_unlit is EntityFX 1. BLEND gives the picture an alpha channel (flag 2) and MASK cuts it out (flag 4, always at an alpha of one half, whatever alphaCutoff says). KHR_texture_transform is put into the vertex coordinates, CLAMP_TO_EDGE becomes the clamp flags 16 and 32 and mirrored wrapping is a repeat. EXT_texture_webp, EXT_texture_avif and KHR_texture_basisu are tried when a texture has no source, and the formats of Image formats work.
• A brush has one picture, so the metallic-roughness, normal, occlusion and emissive textures and the emissive color (KHR_materials_emissive_strength too) are not used. A normal map would need a tangent space, which the lighting of Blitz3D does not have.
• A node with a skin is skinned, with up to eight joints per vertex (JOINTS_0, JOINTS_1, weights made to add up to 1). The joints are entities that Animate moves. A joint that several skins use has the inverse bind matrix of the first skin that names it.
• Animations move the translation, rotation and scale of nodes (not weights). One second is 60 frames. They are one animation with several sequences: sequence 0 is everything, and 1, 2 and so on are the animations of the file in order, each starting one frame after the one before. A node an animation does not touch stays in its starting pose. CUBICSPLINE is evaluated at eight places between keys.
• LoadTexture("model.glb") gives the first picture of the file and LoadTexture("model.glb#2") the third (the numbers are those of images in the file); 0 is the result if there is no such picture. LoadImage, LoadAnimImage and the other commands that load a picture file read them the same way.