modlib/b3d.lua
Lars Mueller fc0585e86c b3d -> glTF: Fix handling of static vertices in animated meshes
Introduces a "neutral bone" to attach static vertices to.
2023-04-02 14:52:57 +02:00

1148 lines
34 KiB
Lua

-- Localize globals
local assert, error, math, modlib, next, ipairs, pairs, setmetatable, string_char, table
= assert, error, math, modlib, next, ipairs, pairs, setmetatable, string.char, table
local mat4 = modlib.matrix4
local read_int, read_single = modlib.binary.read_int, modlib.binary.read_single
local write_int, write_uint, write_single = modlib.binary.write_int, modlib.binary.write_uint, modlib.binary.write_single
local fround = modlib.math.fround
-- Set environment
local _ENV = {}
setfenv(1, _ENV)
local metatable = {__index = _ENV}
--+ Reads a single BB3D chunk from a stream
--+ Doing `assert(stream:read(1) == nil)` afterwards is recommended
--+ See `b3d_specification.txt` as well as https://github.com/blitz-research/blitz3d/blob/master/blitz3d/loader_b3d.cpp
--> B3D model
function read(stream)
local left = 8
local function byte()
left = left - 1
return assert(stream:read(1):byte())
end
local function int()
return read_int(byte, 4)
end
local function id()
return int() + 1
end
local function optional_id()
local id = int()
if id == -1 then
return
end
return id + 1
end
local function string()
local rope = {}
while true do
left = left - 1
local char = assert(stream:read(1))
if char == "\0" then
return table.concat(rope)
end
table.insert(rope, char)
end
end
local function float()
return read_single(byte)
end
local function float_array(length)
local list = {}
for index = 1, length do
list[index] = float()
end
return list
end
local function color()
local ret = {}
ret.r = float()
ret.g = float()
ret.b = float()
ret.a = float()
return ret
end
local function vector3()
return float_array(3)
end
local function quaternion()
local w = float()
local x = float()
local y = float()
local z = float()
return {x, y, z, w}
end
local function content()
if left < 0 then
error(("unexpected EOF at position %d"):format(stream:seek()))
end
return left ~= 0
end
local chunk
local chunks = {
TEXS = function()
local textures = {}
while content() do
local tex = {}
tex.file = string()
tex.flags = int()
tex.blend = int()
tex.pos = float_array(2)
tex.scale = float_array(2)
tex.rotation = float()
table.insert(textures, tex)
end
return textures
end,
BRUS = function()
local brushes = {}
local n_texs = int()
assert(n_texs <= 8)
while content() do
local brush = {}
brush.name = string()
brush.color = color()
brush.shininess = float()
brush.blend = int()
brush.fx = int()
brush.texture_id = {}
for index = 1, n_texs do
brush.texture_id[index] = optional_id()
end
table.insert(brushes, brush)
end
return brushes
end,
VRTS = function()
local vertices = {}
vertices.flags = int()
vertices.tex_coord_sets = int()
vertices.tex_coord_set_size = int()
assert(vertices.tex_coord_sets <= 8 and vertices.tex_coord_set_size <= 4)
local has_normal = (vertices.flags % 2 == 1) or nil
local has_color = (math.floor(vertices.flags / 2) % 2 == 1) or nil
while content() do
local vertex = {}
vertex.pos = vector3()
vertex.normal = has_normal and vector3()
vertex.color = has_color and color()
vertex.tex_coords = {}
for tex_coord_set = 1, vertices.tex_coord_sets do
local tex_coords = {}
for tex_coord = 1, vertices.tex_coord_set_size do
tex_coords[tex_coord] = float()
end
vertex.tex_coords[tex_coord_set] = tex_coords
end
table.insert(vertices, vertex)
end
return vertices
end,
TRIS = function()
local tris = {}
tris.brush_id = id()
tris.vertex_ids = {}
while content() do
local i = id()
local j = id()
local k = id()
table.insert(tris.vertex_ids, {i, j, k})
end
return tris
end,
MESH = function()
local mesh = {}
mesh.brush_id = optional_id()
mesh.vertices = chunk{VRTS = true}
mesh.triangle_sets = {}
repeat
local tris = chunk{TRIS = true}
table.insert(mesh.triangle_sets, tris)
until not content()
return mesh
end,
BONE = function()
local bone = {}
while content() do
local vertex_id = id()
assert(not bone[vertex_id], "duplicate vertex weight")
local weight = float()
if weight > 0 then
-- Many exporters include unneeded zero weights
bone[vertex_id] = weight
end
end
return bone
end,
KEYS = function()
local flags = int()
local _flags = flags % 8
local rotation, scale, position
if _flags >= 4 then
rotation = true
_flags = _flags - 4
end
if _flags >= 2 then
scale = true
_flags = _flags - 2
end
position = _flags >= 1
local bone = {
flags = flags
}
while content() do
local frame = {}
frame.frame = int()
if position then
frame.position = vector3()
end
if scale then
frame.scale = vector3()
end
if rotation then
frame.rotation = quaternion()
end
table.insert(bone, frame)
end
return bone
end,
ANIM = function()
local ret = {}
ret.flags = int() -- flags are unused
ret.frames = int()
ret.fps = float()
return ret
end,
NODE = function()
local node = {}
node.name = string()
node.position = vector3()
node.scale = vector3()
node.keys = {}
node.rotation = quaternion()
node.children = {}
local node_type
-- See https://github.com/blitz-research/blitz3d/blob/master/blitz3d/loader_b3d.cpp#L263
-- Order is not validated; double occurrences of mutually exclusive node def are
while content() do
local elem, type = chunk()
if type == "MESH" then
assert(not node_type)
node_type = "mesh"
node.mesh = elem
elseif type == "BONE" then
assert(not node_type)
node_type = "bone"
node.bone = elem
elseif type == "KEYS" then
modlib.table.append(node.keys, elem)
elseif type == "NODE" then
table.insert(node.children, elem)
elseif type == "ANIM" then
node.animation = elem
else
assert(not node_type)
node_type = "pivot"
end
end
-- Ensure frames are sorted ascendingly
table.sort(node.keys, function(a, b)
assert(a.frame ~= b.frame, "duplicate frame")
return a.frame < b.frame
end)
return node
end,
BB3D = function()
local version = int()
local self = {
version = {
major = math.floor(version / 100),
minor = version % 100,
},
textures = {},
brushes = {}
}
assert(self.version.major <= 2, "unsupported version: " .. self.version.major)
while content() do
local field, type = chunk{TEXS = true, BRUS = true, NODE = true}
if type == "TEXS" then
modlib.table.append(self.textures, field)
elseif type == "BRUS" then
modlib.table.append(self.brushes, field)
else
self.node = field
end
end
return self
end
}
local function chunk_header()
left = left - 4
return stream:read(4), int()
end
function chunk(possible_chunks)
local type, new_left = chunk_header()
local parent_left
left, parent_left = new_left, left
if possible_chunks and not possible_chunks[type] then
error("expected one of " .. table.concat(modlib.table.keys(possible_chunks), ", ") .. ", found " .. type)
end
local res = assert(chunks[type])()
assert(left == 0)
left = parent_left - new_left
return res, type
end
local self = chunk{BB3D = true}
return setmetatable(self, metatable)
end
-- Writer
local function write_rope(self)
local rope = {}
local written_len = 0
local function write(str)
written_len = written_len + #str
table.insert(rope, str)
end
local function byte(val)
write(string_char(val))
end
local function int(val)
write_int(byte, val, 4)
end
local function id(val)
int(val - 1)
end
local function optional_id(val)
int(val and (val - 1) or -1)
end
local function string(val)
write(val)
write"\0"
end
local function float(val)
write_single(byte, fround(val))
end
local function float_array(arr, len)
assert(#arr == len)
for i = 1, len do
float(arr[i])
end
end
local function color(val)
float(val.r)
float(val.g)
float(val.b)
float(val.a)
end
local function vector3(val)
float_array(val, 3)
end
local function quaternion(quat)
float(quat[4])
float(quat[1])
float(quat[2])
float(quat[3])
end
local function chunk(name, write_func)
write(name)
-- Insert placeholder for the 4-bit len
table.insert(rope, false)
written_len = written_len + 4
local len_idx = #rope -- save index of placeholder
local prev_written_len = written_len
write_func()
-- Write the length of this chunk
local chunk_len = written_len - prev_written_len
local len_binary = {}
write_int(function(byte)
table.insert(len_binary, string_char(byte))
end, chunk_len, 4)
rope[len_idx] = table.concat(len_binary)
end
local function NODE(node)
chunk("NODE", function()
string(node.name)
vector3(node.position)
vector3(node.scale)
quaternion(node.rotation)
local mesh = node.mesh
if mesh then
chunk("MESH", function()
optional_id(mesh.brush_id)
local vertices = mesh.vertices
chunk("VRTS", function()
int(vertices.flags)
int(vertices.tex_coord_sets)
int(vertices.tex_coord_set_size)
for _, vertex in ipairs(vertices) do
vector3(vertex.pos)
if vertex.normal then vector3(vertex.normal) end
if vertex.color then color(vertex.color) end
for tex_coord_set = 1, vertices.tex_coord_sets do
local tex_coords = vertex.tex_coords[tex_coord_set]
for tex_coord = 1, vertices.tex_coord_set_size do
float(tex_coords[tex_coord])
end
end
end
end)
for _, triangle_set in ipairs(mesh.triangle_sets) do
chunk("TRIS", function()
id(triangle_set.brush_id)
for _, tri in ipairs(triangle_set.vertex_ids) do
id(tri[1])
id(tri[2])
id(tri[3])
end
end)
end
end)
end
if node.bone then
chunk("BONE", function()
for vertex_id, weight in pairs(node.bone) do
id(vertex_id)
float(weight)
end
end)
end
if node.keys then
local keys_by_flags = {}
for _, key in ipairs(node.keys) do
local flags = 0
flags = flags
+ (key.position and 1 or 0)
+ (key.scale and 2 or 0)
+ (key.rotation and 4 or 0)
keys_by_flags[flags] = keys_by_flags[flags] or {}
table.insert(keys_by_flags[flags], key)
end
for flags, keys in pairs(keys_by_flags) do
chunk("KEYS", function()
int(flags)
for _, frame in ipairs(keys) do
int(frame.frame)
if frame.position then vector3(frame.position) end
if frame.scale then vector3(frame.scale) end
if frame.rotation then quaternion(frame.rotation) end
end
end)
end
end
local anim = node.animation
if anim then
chunk("ANIM", function()
int(anim.flags)
int(anim.frames)
float(anim.fps)
end)
end
for _, child in ipairs(node.children) do
NODE(child)
end
end)
end
chunk("BB3D", function()
int(self.version.major * 100 + self.version.minor)
if self.textures[1] then
chunk("TEXS", function()
for _, tex in ipairs(self.textures) do
string(tex.file)
int(tex.flags)
int(tex.blend)
float_array(tex.pos, 2)
float_array(tex.scale, 2)
float(tex.rotation)
end
end)
end
if self.brushes[1] then
local max_n_texs = 0
for _, brush in ipairs(self.brushes) do
for n in pairs(brush.texture_id) do
if n > max_n_texs then
max_n_texs = n
end
end
end
chunk("BRUS", function()
int(max_n_texs)
for _, brush in ipairs(self.brushes) do
string(brush.name)
color(brush.color)
float(brush.shininess)
int(brush.blend)
int(brush.fx)
for index = 1, max_n_texs do
optional_id(brush.texture_id[index])
end
end
end)
end
if self.node then
NODE(self.node)
end
end)
return rope
end
function write_string(self)
return table.concat(write_rope(self))
end
function write(self, stream)
for _, str in ipairs(write_rope(self)) do
stream:write(str)
end
end
-- B3D to glTF converter
-- See https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
--! Highly experimental; expect bugs!
do
-- glTF constants
local array_buffer = 34962 -- "Buffer containing vertex attributes, such as vertices, texcoords or colors."
local element_array_buffer = 34963 -- "Buffer used for element indices."
local component_type = {
signed_byte = 5120,
unsigned_byte = 5121,
signed_short = 5122,
unsigned_short = 5123,
unsigned_int = 5125,
float = 5126,
}
-- Coordinate system conversions:
-- "Blitz 3D uses a left-handed system: X+ is to the right. Y+ is up. Z+ is forward."
-- "glTF uses a right-handed coordinate system. glTF defines +Y as up, +Z as forward, and -X as right;
-- the front of a glTF asset faces +Z."
local function translation_to_gltf(vec)
return {-vec[1], vec[2], vec[3]} -- invert the X-axis
end
local function quaternion_to_gltf(quat)
-- TODO (!) is this correct?
return {-quat[1], quat[2], quat[3], quat[4]} -- invert the X-axis
end
-- Convert a color from table format to glTF RGBA list format
local function color_to_gltf(col)
return {col.r, col.g, col.b, col.a}
end
-- Basic helpers for writing to the buffer, all parameterized in terms of `write_byte`
local function write_index(write_byte, index)
write_uint(write_byte, index - 1 --[[1-based to 0-based]], 4)
end
local function write_float(write_byte, float)
assert(-math.huge < float and float < math.huge)
assert(-math.huge < fround(float) and fround(float) < math.huge, ("%.18g got %.18g"):format(float, fround(float)))
write_single(write_byte, fround(float))
end
local function write_floats(write_byte, floats, expected_len)
assert(#floats == expected_len)
for i = 1, expected_len do
write_float(write_byte, floats[i])
end
end
local function write_vector(write_byte, vec)
return write_floats(write_byte, vec, 3)
end
local function write_translation(write_byte, vec)
return write_vector(write_byte, translation_to_gltf(vec))
end
local function write_quaternion(write_byte, quat)
-- XYZW order is already correct, but we still need to convert left-handed to right-handed
return write_floats(write_byte, quaternion_to_gltf(quat), 4)
end
function to_gltf(self)
-- Accessor helper: Stores arrays of raw data in a buffer, produces views & accessors.
-- Everything is dumped in the same large buffer.
local buffer_rope = {} -- buffer content (table of strings)
local buffer_views = {} -- glTF buffer views
local accessors = {} -- glTF accessors
local offset = 0 -- current byte offset
local function add_accessor(
type, -- name of the composite type (e.g. SCALAR, VEC3, VEC4, MAT4, ...)
comp_type, -- name of the component type (e.g. float, unsigned_int, ...)
index, -- true / false / nil: whether this is an index (true) or vertex data (false) or neither (nil)
func -- `function(write_byte) ... return count, min, max end` to be called to write to the buffer view;
-- the count of elements written must be returned; min and max may be returned
)
-- Always add padding to obtain a multiple of 4
-- TODO (?) don't add padding if it isn't required
table.insert(buffer_rope, ("\0"):rep(offset % 4))
offset = math.ceil(offset / 4) * 4
local bytes_written = 0
local count, min, max = func(function(byte)
table.insert(buffer_rope, string_char(byte))
bytes_written = bytes_written + 1
end)
assert(count)
-- Add buffer view
table.insert(buffer_views, {
buffer = 0, -- 0-based - there only is one buffer
byteOffset = offset,
byteLength = bytes_written,
target = ((index == true) and element_array_buffer) -- index data
or ((index == false) and array_buffer) -- vertex data
or nil, -- no target hint
})
table.insert(accessors, {
bufferView = #buffer_views - 1, -- 0-based
byteOffset = 0, -- view has correct offset
componentType = assert(component_type[comp_type]),
type = type,
count = count,
min = min,
max = max,
})
offset = offset + bytes_written
return #accessors - 1 -- 0-based index of the accessor
end
local textures = {} -- glTF textures
local function add_texture(name)
-- TODO (?) add an appropriate sampler
table.insert(textures, {name = name})
return #textures - 1 -- 0-based texture index
end
for _, tex in ipairs(self.textures) do
-- Assert that all values we don't map properly yet are defaults
-- TODO dig into Blitz3D sources to figure out the meaning of flags & blend
-- TODO (...) deal with flag value of 65536:
-- "The flags field value can conditional an additional flag value of '65536'.
-- This is used to indicate that the texture uses secondary UV values, ala the TextureCoords command."
assert(tex.flags == 1) -- TODO (?) see https://github.com/blitz-research/blitz3d/blob/master/gxruntime/gxcanvas.h#L59
assert(tex.blend == 2)
-- Assert that the texture isn't transformed
assert(tex.rotation == 0)
assert(tex.pos[1] == 0 and tex.pos[2] == 0)
assert(tex.scale[1] == 1 and tex.scale[2] == 1)
add_texture(tex.file)
end
-- Map brushes to materials (& textures)
local materials = {}
for i, brush in ipairs(self.brushes) do
-- Assert defaults
-- See https://github.com/blitz-research/blitz3d/blob/6beb288cb5962393684a59a4a44ac11524894939/blitz3d/brush.cpp#L164-L167:
-- 0 = default/replace, 1 = alpha, 2 = multiply, 3 = add
assert(brush.blend == 1) -- (alpha)
-- TODO (...) figure out what these "effects" are and if/how to map them to glTF
assert(brush.fx == 0)
assert(#brush.texture_id <= 1) -- TODO (...) this supports only a single texture per brush for now
local index
if brush.texture_id[1] then
index = brush.texture_id[1] -- 0-based
else
-- Implementations seem to implicitly assume textures for brushes
index = add_texture(brush.name)
end
materials[i] = {
name = brush.name,
alphaMode = "BLEND",
pbrMetallicRoughness = {
baseColorFactor = color_to_gltf(brush.color),
metallicFactor = brush.shininess, -- TODO (?) are these really equivalent?
-- Add texture if there is none
baseColorTexture = {
index = index,
-- `texCoord = 0` is the default already, no need to set it
},
},
}
end
local meshes = {}
local function add_mesh(mesh, weights, add_neutral_bone)
local attributes = {}
local vertices = mesh.vertices
attributes.POSITION = add_accessor("VEC3", "float", false, function(write_byte)
local inf = math.huge
local min_pos, max_pos = {inf, inf, inf}, {-inf, -inf, -inf}
for _, vertex in ipairs(mesh.vertices) do
local pos = translation_to_gltf(vertex.pos)
write_vector(write_byte, pos)
min_pos = modlib.vector.combine(min_pos, pos, math.min)
max_pos = modlib.vector.combine(max_pos, pos, math.max)
end
return #mesh.vertices, min_pos, max_pos -- vertex accessors MUST provide min & max
end)
local has_normals = vertices.flags % 2 == 1 -- lowest bit set?
if has_normals then
attributes.NORMAL = add_accessor("VEC3", "float", false, function(write_byte)
for _, vertex in ipairs(mesh.vertices) do
-- Some B3D models don't seem to have their normals normalized.
-- TODO (?) raise a warning when handling this gracefully
write_translation(write_byte, modlib.vector.normalize(vertex.normal))
end
return #mesh.vertices
end)
end
local has_colors = vertices.flags % 4 >= 2 -- second lowest bit set?
if has_colors then
attributes.COLOR_0 = add_accessor("VEC4", "float", false, function(write_byte)
for _, vertex in ipairs(mesh.vertices) do
write_floats(write_byte, color_to_gltf(vertex.color), 4)
end
return #mesh.vertices
end)
end
if vertices.tex_coord_sets >= 1 then
assert(vertices.tex_coord_set_size == 2)
for tex_coord_set = 1, vertices.tex_coord_sets do
local tcs_id = tex_coord_set - 1 -- 0-based
attributes[("TEXCOORD_%d"):format(tcs_id)] = add_accessor("VEC2", "float", false, function(write_byte)
for _, vertex in ipairs(mesh.vertices) do
write_floats(write_byte, vertex.tex_coords[tex_coord_set], 2)
end
return #mesh.vertices
end)
end
end
if next(weights) ~= nil then
-- Count (& pack into list) joints influencing vertices, normalize weights
local max_count = 0
local joint_ids = {}
local normalized_weights = {}
-- Handle (supposedly) animated/dynamic vertices (can still be static by having zero weights)
for vertex_id, joint_weights in pairs(weights) do
local total_weight = 0
local count = 0
for _, weight in pairs(joint_weights) do
total_weight = total_weight + weight
count = count + 1
end
if total_weight > 0 then -- animated?
joint_ids[vertex_id] = {}
normalized_weights[vertex_id] = {}
for joint, weight in pairs(joint_weights) do
table.insert(joint_ids[vertex_id], joint)
table.insert(normalized_weights[vertex_id], weight / total_weight)
end
max_count = math.max(max_count, count)
end
end
-- Now search for static vertices
for vertex_id in ipairs(mesh.vertices) do
if not joint_ids[vertex_id] then
-- Vertex isn't influenced by any bones => Add a dummy neutral bone to influence this vertex
-- See https://github.com/KhronosGroup/glTF/issues/2269
-- and https://github.com/KhronosGroup/glTF-Blender-IO/pull/1552/
joint_ids[vertex_id] = {add_neutral_bone()}
normalized_weights[vertex_id] = {1}
max_count = math.max(max_count, 1) -- it is (theoretically) possible that all vertices are static
end
end
assert(max_count > 0) -- TODO (?) warning for max_count > 4
for set_start = 1, max_count, 4 do -- Iterate sets of 4 bones
local set_id = math.floor(set_start / 4) -- 0-based => floor rather than ceil
-- Write the joint IDs
attributes[("JOINTS_%d"):format(set_id)] = add_accessor("VEC4", "unsigned_short", false, function(write_byte)
for vertex_id in ipairs(mesh.vertices) do
for i = set_start, set_start + 3 do
local vrt_joint_ids, vrt_norm_weights = assert(joint_ids[vertex_id]), assert(normalized_weights[vertex_id])
assert(#vrt_joint_ids == #vrt_norm_weights)
local id = vrt_joint_ids[i] or 0
local weight = vrt_norm_weights[i] or 0
if weight == 0 then
id = 0 -- required by the glTF spec
end
write_uint(write_byte, id, 2)
end
end
return #mesh.vertices
end)
-- Write the corresponding weights
attributes[("WEIGHTS_%d"):format(set_id)] = add_accessor("VEC4", "float", false, function(write_byte)
for vertex_id in ipairs(mesh.vertices) do
for i = set_start, set_start + 3 do
local weight = (normalized_weights[vertex_id] or {})[i] or 0
write_float(write_byte, weight)
end
end
return #mesh.vertices
end)
end
end
-- Write the indices per triangle set
local primitives = {}
for i, triangle_set in ipairs(mesh.triangle_sets) do
local index_accessor = add_accessor("SCALAR", "unsigned_int", true, function(write_byte)
for _, tri in ipairs(triangle_set.vertex_ids) do
-- Flip winding order due to the coordinate system transformation
-- TODO (!) is this correct?
for j = 3, 1, -1 do
write_index(write_byte, tri[j])
end
end
return 3 * #triangle_set.vertex_ids
end)
-- Each triangle set is equivalent to one glTF "primitive"
local brush_id = triangle_set.brush_id or mesh.brush_id
if brush_id == 0 then -- default brush
brush_id = nil -- TODO (?) add default material if there are UVs
else
brush_id = brush_id - 1 -- 0-based
end
primitives[i] = {
attributes = attributes,
indices = index_accessor,
material = brush_id,
-- `mode = 4` (triangles) is the default already, no need to set it
}
end
table.insert(meshes, {primitives = primitives})
return #meshes - 1 -- 0-based
end
-- glTF lists
local nodes = {}
local skins = {}
local samplers = {}
local channels = {}
local function add_node(
node, -- b3d node to add
bind_mat, -- bind matrix of the parent bone (may be `nil` if none)
fps, -- fps of the parent bone (may be `nil` if none)
anim -- shared animation of the parent mesh
)
table.insert(nodes, false) -- HACK first insert a placeholder to get a fixed ID
local node_id = #nodes - 1 -- 0-indexed <=> before `table.insert`!
-- Animation (speed)?
fps = node.animation and node.animation.fps or fps
-- Keyframes?
if node.keys then
-- Convert from a list of keyframes of three overrides to three lists of channels
local targets = {
translation = {output_type = "VEC3", b3d_field = "position", write_value = write_translation},
scale = {output_type = "VEC3", b3d_field = "scale", write_value = write_vector},
rotation = {output_type = "VEC4", b3d_field = "rotation", write_value = write_quaternion}
}
for _, keyframe in ipairs(node.keys) do
local frame = keyframe.frame
for _, target in pairs(targets) do
local value = keyframe[target.b3d_field]
if value then
table.insert(target, {frame = frame, value = value})
end
end
end
for target, keyframes in pairs(targets) do
if #keyframes > 0 then
-- Write input (timestamps)
local input = add_accessor("SCALAR", "float", nil, function(write_byte)
local min, max = math.huge, -math.huge
for _, keyframe in ipairs(keyframes) do
local sec = keyframe.frame / (fps or 60) -- convert frames to seconds; default FPS is 60
write_float(write_byte, sec)
min, max = math.min(min, sec), math.max(max, sec)
end
return #keyframes, {min}, {max} -- min and max are mandatory
end)
-- Write output (overrides)
local output = add_accessor(keyframes.output_type, "float", nil, function(write_byte)
for _, keyframe in ipairs(keyframes) do
keyframes.write_value(write_byte, keyframe.value)
end
return #keyframes
end)
table.insert(samplers, {
input = input,
output = output,
-- interpolation default is already linear, matching b3d
})
table.insert(channels, {
sampler = #samplers - 1, -- 0-based
target = {
node = node_id,
path = target,
}
})
end
end
end
if node.mesh then
-- Initialize skeletal animation
assert(not anim)
anim = {
weights = {},
joints = {},
inv_bind_mats = {},
}
end
if node.bone then
local joint_id = #anim.joints
table.insert(anim.joints, node_id)
-- "To compose the local transformation matrix, TRS properties MUST be converted to matrices and postmultiplied in
-- the T * R * S order; first the scale is applied to the vertices, then the rotation, and then the translation."
local translation = translation_to_gltf(node.position)
local rotation = modlib.quaternion.normalize(quaternion_to_gltf(node.rotation))
local scale = node.scale
local loc_trans_mat = mat4.scale(scale)
:compose(mat4.rotation(rotation))
:compose(mat4.translation(translation))
-- Compute a proper inverse bind matrix as the inverse of the product of the transformation matrices
-- along the path from the root (the mesh) to the current node (the bone).
-- See e.g. https://stackoverflow.com/questions/17127994/opengl-bone-animation-why-do-i-need-inverse-of-bind-pose-when-working-with-gp
-- https://computergraphics.stackexchange.com/questions/7603/confusion-about-how-inverse-bind-pose-is-actually-calculated-and-used
bind_mat = bind_mat and bind_mat:multiply(loc_trans_mat) or loc_trans_mat
table.insert(anim.inv_bind_mats, bind_mat:inverse())
-- Insert into reverse lookup `anim.weights[vertex_id][joint_id] = weight`
-- such that writing the mesh can then write the weights per vertex
for vertex_id, weight in pairs(node.bone) do
if weight > 0 then
anim.weights[vertex_id] = anim.weights[vertex_id] or {}
anim.weights[vertex_id][joint_id] = weight
end
end
end
local children = {}
for _, child in ipairs(node.children) do
table.insert(children, add_node(child, bind_mat, fps, anim))
end
local mesh, skin_id, neutral_node_id
if node.mesh then
local neutral_joint_id
-- Lazily adds a placeholder for the neutral joint, returns joint ID
local function add_neutral_joint()
if neutral_joint_id then
return neutral_joint_id
end
neutral_node_id = #nodes -- 0-based
table.insert(nodes, {
name = "neutral_bone",
-- We need to flip the hierarchy: The neutral bone must be a parent of the mesh root;
-- if it were a sibling, there would be no common skeleton root (accepted by Blender but not by glTF validator);
-- if it were a child, transformations of the mesh root would affect it and it wouldn't be a neutral bone anymore.
children = {node_id},
-- translation, scale, rotation all default to identity
})
neutral_joint_id = #anim.joints -- 0-based
table.insert(anim.joints, neutral_node_id)
return neutral_joint_id -- 0-based
end
mesh = add_mesh(node.mesh, anim.weights, add_neutral_joint)
if anim.joints and anim.joints[1] then
if neutral_joint_id then
-- Duplicate the inverse bind matrix of the parent (which the neutral bone will be a child of)
table.insert(anim.inv_bind_mats, bind_mat or mat4.identity())
end
table.insert(skins, {
inverseBindMatrices = add_accessor("MAT4", "float", nil, function(write_byte)
for _, inv_bind_mat in ipairs(anim.inv_bind_mats) do
assert(#inv_bind_mat == 4)
-- glTF uses column-major order (we use row-major order)
for i = 1, 4 do
for j = 1, 4 do
write_float(write_byte, inv_bind_mat[j][i])
end
end
end
return #anim.inv_bind_mats
end),
joints = anim.joints,
skeleton = neutral_node_id, -- make the neutral bone the skeleton root
})
skin_id = #skins - 1 -- 0-based
end
end
-- Now replace the placeholder
nodes[node_id + 1 --[[0-based to 1-based]]] = {
name = node.name,
mesh = mesh,
skin = skin_id,
children = children[1] and children, -- glTF does not allow empty lists
translation = translation_to_gltf(node.position),
scale = node.scale,
rotation = quaternion_to_gltf(node.rotation),
}
-- If a neutral bone exists, return the neutral bone (which has the node as a child) instead of the node
return neutral_node_id or node_id -- 0-based
end
local scene, scenes
if self.node then
scene, scenes = 0, {{nodes = {add_node(self.node)}}}
end
local buffer_string = table.concat(buffer_rope)
return {
asset = {
generator = "modlib b3d:to_gltf",
version = "2.0"
},
-- Textures
textures = textures[1] and textures, -- glTF does not allow empty lists
materials = materials[1] and materials,
-- Accessors, buffer views & buffers
accessors = accessors,
bufferViews = buffer_views,
buffers = {
{
byteLength = #buffer_string,
uri = "data:application/octet-stream;base64,"
.. modlib.base64.encode(buffer_string) -- Note: Blender requires base64 padding
},
},
-- Meshes & nodes
meshes = meshes,
nodes = nodes,
-- A scene is not strictly needed but is useful for getting rid of validator warnings & having a proper root defined
scene = scene,
scenes = scenes,
-- Animation
skins = skins,
-- B3D only contains (up to) a single animation
animations = channels[1] and {
{
channels = channels,
samplers = samplers,
},
},
}
end
end
function write_gltf(self, file)
modlib.json:write_file(self:to_gltf(), file)
end
local binary_search_frame = modlib.table.binary_search_comparator(function(a, b)
return modlib.table.default_comparator(a, b.frame)
end)
--> list of { bone_name = string, parent_bone_name = string, position = vector, rotation = quaternion, scale = vector }
function get_animated_bone_properties(self, keyframe, interpolate)
local function get_frame_values(keys)
local values = keys[keyframe]
if values and values.frame == keyframe then
return {
position = values.position,
rotation = values.rotation,
scale = values.scale
}
end
local index = binary_search_frame(keys, keyframe)
if index > 0 then
return keys[index]
end
index = -index
assert(index > 1 and index <= #keys)
local a, b = keys[index - 1], keys[index]
if not interpolate then
return a
end
local ratio = (keyframe - a.frame) / (b.frame - a.frame)
return {
position = (a.position and b.position and modlib.vector.interpolate(a.position, b.position, ratio)) or a.position or b.position,
rotation = (a.rotation and b.rotation and modlib.quaternion.slerp(a.rotation, b.rotation, ratio)) or a.rotation or b.rotation,
scale = (a.scale and b.scale and modlib.vector.interpolate(a.scale, b.scale, ratio)) or a.scale or b.scale,
}
end
local bone_properties = {}
local function get_props(node, parent_bone_name)
local properties = {parent_bone_name = parent_bone_name}
if keyframe > 0 and node.keys and next(node.keys) ~= nil then
modlib.table.add_all(properties, get_frame_values(node.keys))
end
if not properties.position then -- animation not present, fall back to node position
properties.position = modlib.table.copy(node.position)
end
if properties.rotation then -- animation is relative to node rotation
properties.rotation = modlib.quaternion.compose(node.rotation, properties.rotation)
else
properties.rotation = modlib.table.copy(node.rotation)
end
if not properties.scale then -- animation not present, fall back to node scale
properties.scale = modlib.table.copy(node.scale)
end
if node.bone then
properties.bone_name = node.name
table.insert(bone_properties, properties)
end
for _, child in pairs(node.children or {}) do
get_props(child, properties.bone_name)
end
end
get_props(self.node)
return bone_properties
end
-- Export environment
return _ENV