rgltf 1.0.0

data/lib/rgltf/builder.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative 'builder/accessor_data'
+require_relative 'builder/accessors'
+require_relative 'builder/materials'
+require_relative 'builder/component_builders'
+require_relative 'builder/document_properties'
+
+module Rgltf
+  class Builder
+    include AccessorData
+    include Accessors
+    include Materials
+    include DocumentProperties
+
+    Handle = Struct.new(:kind, :index, :buffer_view_index, :owner, keyword_init: true)
+    TARGETS = { array_buffer: 34_962, array: 34_962, element_array: 34_963, element_array_buffer: 34_963 }.freeze
+
+    class << self
+      def build(&block)
+        builder = new
+        block.call(builder)
+        builder.document
+      end
+    end
+
+    def initialize
+      @handle_owner = Object.new.freeze
+      @json = { 'asset' => { 'version' => '2.0' } }
+      @binary = String.new(encoding: Encoding::BINARY)
+    end
+
+    def asset(generator: nil, copyright: nil, **properties)
+      values = { 'version' => '2.0' }
+      values['generator'] = generator if generator
+      values['copyright'] = copyright if copyright
+      properties.each { |key, value| values[camelize(key)] = value }
+      @json['asset'] = values
+      self
+    end
+
+    def mesh(name: nil, weights: nil, extensions: nil, extras: nil)
+      mesh_builder = MeshBuilder.new(self)
+      yield mesh_builder
+      value = { 'primitives' => mesh_builder.primitives }
+      add_common_properties(value, name:, extensions:, extras:)
+      value['weights'] = weights if weights
+      handle(:mesh, append('meshes', value))
+    end
+
+    def node(name: nil, mesh: nil, skin: nil, camera: nil, children: nil,
+             translation: nil, rotation: nil, scale: nil, matrix: nil, weights: nil, **properties)
+      value = {}
+      value['name'] = name if name
+      value['mesh'] = reference(mesh, :mesh) if mesh
+      value['skin'] = reference(skin, :skin) if skin
+      value['camera'] = reference(camera, :camera) if camera
+      value['children'] = children.map { |child| reference(child, :node) } if children
+      value['translation'] = translation if translation
+      value['rotation'] = rotation if rotation
+      value['scale'] = scale if scale
+      value['matrix'] = matrix if matrix
+      value['weights'] = weights if weights
+      value.merge!(stringify_properties(properties))
+      handle(:node, append('nodes', value))
+    end
+
+    def camera(type:, name: nil, extensions: nil, extras: nil,
+               projection_extensions: nil, projection_extras: nil, **projection)
+      camera_type = type.to_sym
+      raise ArgumentError, 'camera type must be perspective or orthographic' unless %i[perspective
+                                                                                       orthographic].include?(camera_type)
+
+      projection_value = stringify_properties(projection)
+      projection_value['extensions'] = projection_extensions if projection_extensions
+      projection_value['extras'] = projection_extras unless projection_extras.nil?
+      value = { 'type' => camera_type.to_s, camera_type.to_s => projection_value }
+      add_common_properties(value, name:, extensions:, extras:)
+      handle(:camera, append('cameras', value))
+    end
+
+    def skin(joints:, inverse_bind_matrices: nil, skeleton: nil, name: nil, extensions: nil, extras: nil)
+      value = { 'joints' => joints.map { |joint| reference(joint, :node) } }
+      value['inverseBindMatrices'] = reference(inverse_bind_matrices, :accessor) if inverse_bind_matrices
+      value['skeleton'] = reference(skeleton, :node) if skeleton
+      add_common_properties(value, name:, extensions:, extras:)
+      handle(:skin, append('skins', value))
+    end
+
+    def attach_skin(node, skin)
+      node_handle = verify_handle(node, :node)
+      @json.fetch('nodes').fetch(node_handle.index)['skin'] = reference(skin, :skin)
+      node
+    end
+
+    def animation(name: nil, extensions: nil, extras: nil)
+      animation_builder = AnimationBuilder.new(self)
+      yield animation_builder
+      value = { 'samplers' => animation_builder.samplers, 'channels' => animation_builder.channels }
+      add_common_properties(value, name:, extensions:, extras:)
+      handle(:animation, append('animations', value))
+    end
+
+    def scene(nodes:, name: nil, default: false, **properties)
+      value = { 'nodes' => nodes.map { |node| reference(node, :node) } }
+      value['name'] = name if name
+      value.merge!(stringify_properties(properties))
+      scene_handle = handle(:scene, append('scenes', value))
+      @json['scene'] = scene_handle.index if default
+      scene_handle
+    end
+
+    def document
+      @json['buffers'] = [{ 'byteLength' => @binary.bytesize }] unless @binary.empty?
+      Rgltf.load_json(@json, buffers: @binary.empty? ? nil : [@binary], strict_extensions: false)
+    end
+
+    def mark_accessor_target(handle, target)
+      verify_handle(handle, :accessor)
+      return handle unless handle.buffer_view_index
+
+      @json.fetch('bufferViews').fetch(handle.buffer_view_index)['target'] = TARGETS.fetch(target)
+      handle
+    end
+
+    def reference(handle, kind)
+      verify_handle(handle, kind).index
+    end
+
+    private
+
+    def append(collection, value)
+      (@json[collection] ||= []) << value
+      @json.fetch(collection).length - 1
+    end
+
+    def append_buffer_view(bytes, target:, byte_stride: nil, name: nil, extensions: nil, extras: nil)
+      @binary << ("\0" * ((4 - (@binary.bytesize % 4)) % 4))
+      value = { 'buffer' => 0, 'byteOffset' => @binary.bytesize, 'byteLength' => bytes.bytesize }
+      value.delete('byteOffset') if value['byteOffset'].zero?
+      value['target'] = target if target
+      value['byteStride'] = byte_stride if byte_stride
+      add_common_properties(value, name:, extensions:, extras:)
+      @binary << bytes
+      append('bufferViews', value)
+    end
+
+    def verify_handle(handle, kind)
+      unless handle.is_a?(Handle) && handle.kind == kind && handle.owner.equal?(@handle_owner)
+        raise ArgumentError, "expected a #{kind} builder handle"
+      end
+
+      handle
+    end
+
+    def stringify_properties(properties)
+      properties.to_h { |key, value| [camelize(key), value] }
+    end
+
+    def add_common_properties(value, name: nil, extensions: nil, extras: nil)
+      value['name'] = name if name
+      value['extensions'] = extensions if extensions
+      value['extras'] = extras unless extras.nil?
+      value
+    end
+
+    def handle(kind, index, buffer_view_index: nil)
+      Handle.new(kind:, index:, buffer_view_index:, owner: @handle_owner).freeze
+    end
+
+    def camelize(key)
+      parts = key.to_s.split('_')
+      parts.first + parts.drop(1).map(&:capitalize).join
+    end
+  end
+end

data/lib/rgltf/document.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Document
+    COLLECTIONS = {
+      'buffers' => Buffer,
+      'bufferViews' => BufferView,
+      'accessors' => Accessor,
+      'images' => Image,
+      'samplers' => Sampler,
+      'textures' => Texture,
+      'materials' => Material,
+      'meshes' => Mesh,
+      'cameras' => Camera,
+      'nodes' => Node,
+      'skins' => Skin,
+      'animations' => Animation,
+      'scenes' => Scene
+    }.freeze
+
+    attr_reader :asset, :scenes, :nodes, :meshes, :accessors, :buffer_views,
+                :buffers, :materials, :textures, :images, :samplers, :skins,
+                :animations, :cameras, :extensions_used, :extensions_required,
+                :extensions, :extras, :extension_registry, :buffer_resolver,
+                :raw_json, :validation_result
+
+    def initialize(json, base_dir:, supplied_buffers:, glb_bin:, lazy:,
+                   extension_registry:, validate:, strict_extensions:)
+      @raw_json = json
+      @extension_registry = extension_registry
+      @extensions_used = json.fetch('extensionsUsed', []).freeze
+      @extensions_required = json.fetch('extensionsRequired', []).freeze
+      @extras = json['extras']
+      reject_unsupported_extensions! if strict_extensions
+      @buffer_resolver = BufferResolver.new(base_dir:, glb_bin:, supplied_buffers:)
+      @asset = Asset.new(json.fetch('asset'), document: self)
+      reject_unsupported_version!
+
+      build_collections(json)
+      validate_default_scene_reference!
+      @extensions = parse_extensions(json.fetch('extensions', {}), :document, self).freeze
+      nodes.each(&:resolve_references!)
+      parse_property_extensions!
+      decode_primitives!
+      buffers.each(&:bytes) unless lazy
+
+      @validation_result = Validator.validate(self) if validate || !strict_extensions
+      if validate && !validation_result.errors.empty?
+        raise ValidationError, validation_result.errors.map(&:message).join('; ')
+      end
+    rescue KeyError => e
+      raise FormatError, "missing required glTF property: #{e.message}"
+    end
+
+    def fetch_reference(collection, index, path)
+      objects = public_send(collection)
+      return objects[index] if index.is_a?(Integer) && index >= 0 && index < objects.length
+
+      raise FormatError, "#{path} references missing #{collection.to_s.tr('_', ' ')} index #{index.inspect}"
+    end
+
+    def default_scene
+      @default_scene_index.nil? ? nil : fetch_reference(:scenes, @default_scene_index, 'scene')
+    end
+
+    def extension(name)
+      extensions[name]
+    end
+
+    def each_mesh_instance
+      return enum_for(:each_mesh_instance) unless block_given?
+
+      scenes.each do |scene|
+        scene.nodes.each { |node| visit_mesh_instances(node, Matrix4::IDENTITY, {}) { |*values| yield(*values) } }
+      end
+      self
+    end
+
+    def release_buffers!
+      accessors.each(&:release!)
+      images.each(&:release!)
+      buffer_resolver.release!
+      self
+    end
+
+    def to_glb(validate: true)
+      Writer.new(self, validate:).to_glb
+    end
+
+    def write_glb(path, validate: true)
+      Writer.new(self, validate:).write_glb(path)
+    end
+
+    def write_gltf(path, embed: false, validate: true)
+      Writer.new(self, validate:).write_gltf(path, embed:)
+    end
+
+    private
+
+    def build_collections(json)
+      COLLECTIONS.each do |json_key, klass|
+        ruby_name = json_key == 'bufferViews' ? :buffer_views : json_key.to_sym
+        values = json.fetch(json_key, []).each_with_index.map do |properties, index|
+          klass.new(properties, document: self, index:)
+        end.freeze
+        instance_variable_set("@#{ruby_name}", values)
+      end
+      @default_scene_index = json['scene']
+    end
+
+    def parse_property_extensions!
+      objects = [asset, *COLLECTIONS.keys.flat_map do |json_key|
+        public_send(json_key == 'bufferViews' ? :buffer_views : json_key)
+      end]
+      objects.each(&:parse_extensions!)
+    end
+
+    def decode_primitives!
+      meshes.each do |mesh|
+        decoded = mesh.primitives.map { |primitive| extension_registry.decode_primitive(primitive, doc: self) }
+        mesh.replace_primitives!(decoded)
+      end
+    end
+
+    def validate_default_scene_reference!
+      return if @default_scene_index.nil?
+
+      fetch_reference(:scenes, @default_scene_index, 'scene')
+    end
+
+    def parse_extensions(values, owner_type, owner)
+      values.to_h do |name, value|
+        [name, extension_registry.parse(name, value, on: owner_type, owner:, doc: self)]
+      end
+    end
+
+    def reject_unsupported_extensions!
+      missing = extensions_required.reject { |name| extension_registry.known?(name) }
+      return if missing.empty?
+
+      raise UnsupportedExtensionError, "required extension is not registered: #{missing.join(', ')}"
+    end
+
+    def reject_unsupported_version!
+      version = asset.version.to_s
+      raise UnsupportedError, "glTF version #{version}" unless version.split('.').first == '2'
+    end
+
+    def visit_mesh_instances(node, parent_matrix, visiting, &block)
+      raise FormatError, "node hierarchy contains a cycle at node #{node.index}" if visiting[node.object_id]
+
+      visiting[node.object_id] = true
+      world = node.world_matrix(parent_matrix)
+      block.call(node, node.mesh, world) if node.mesh
+      node.children.each { |child| visit_mesh_instances(child, world, visiting, &block) }
+      visiting.delete(node.object_id)
+    end
+  end
+end

data/lib/rgltf/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Error < StandardError; end
+  class FormatError < Error; end
+  class UnsupportedError < Error; end
+  class UnsupportedExtensionError < UnsupportedError; end
+  class MissingResourceError < Error; end
+  class ValidationError < Error; end
+end

data/lib/rgltf/extension.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class ExtensionRegistry
+    def initialize
+      @entries = {}
+    end
+
+    def add(name, handler, on:)
+      Array(on).each { |owner_type| @entries[[name, owner_type.to_sym]] = handler }
+      self
+    end
+
+    def known?(name)
+      @entries.any? { |(registered_name, _), _| registered_name == name }
+    end
+
+    def parse(name, json, on:, owner:, doc:)
+      handler = @entries[[name, on.to_sym]]
+      handler ? handler.parse(json, owner:, doc:) : json
+    end
+
+    def serialize(name, object, on:, doc:)
+      handler = @entries[[name, on.to_sym]]
+      handler ? handler.serialize(object, doc:) : object
+    end
+
+    def registered_on?(name, on:)
+      @entries.key?([name, on.to_sym])
+    end
+
+    def names
+      @entries.keys.map(&:first).uniq.freeze
+    end
+
+    def decode_primitive(primitive, doc:)
+      primitive.extensions.reduce(primitive) do |current, (name, _value)|
+        handler = @entries[[name, :primitive]]
+        if handler.respond_to?(:decode_primitive)
+          handler.decode_primitive(current, doc:) || current
+        else
+          current
+        end
+      end
+    end
+  end
+
+  class Extension
+    SerializedProperties = Struct.new(:value, :handled_keys, keyword_init: true)
+
+    class << self
+      def register(name, on:)
+        Rgltf.default_extensions.add(name, self, on:)
+      end
+
+      def parse(json, owner:, doc:)
+        json
+      end
+
+      def serialize(object, doc:)
+        object
+      end
+
+      def serialize_properties(value, handled_keys:)
+        SerializedProperties.new(value:, handled_keys: Array(handled_keys).map(&:to_s).freeze).freeze
+      end
+
+      def decode_primitive(primitive, doc:)
+        primitive
+      end
+    end
+  end
+
+  class << self
+    def default_extensions
+      @default_extensions ||= ExtensionRegistry.new
+    end
+  end
+end

data/lib/rgltf/extensions/khr_lights_punctual.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Extensions
+    class KHRLightsPunctual < Extension
+      class Collection
+        attr_reader :lights
+
+        def initialize(json)
+          @lights = json.fetch('lights', []).each_with_index.map { |light, index| Light.new(light, index:) }.freeze
+        end
+      end
+
+      class NodeLight
+        attr_reader :light
+
+        def initialize(light)
+          @light = light
+        end
+      end
+
+      class Light
+        attr_reader :index, :name, :type, :color, :intensity, :range, :spot, :source_json
+
+        def initialize(json, index:)
+          @source_json = json
+          @index = index
+          @name = json['name']
+          @type = json.fetch('type').to_sym
+          raise FormatError, "invalid punctual light type #{@type.inspect}" unless %i[directional point
+                                                                                      spot].include?(@type)
+
+          @color = json.fetch('color', [1.0, 1.0, 1.0]).freeze
+          @intensity = json.fetch('intensity', 1.0)
+          @range = json['range']
+          @spot = Spot.new(json.fetch('spot', {})) if @type == :spot
+        end
+      end
+
+      class Spot
+        attr_reader :inner_cone_angle, :outer_cone_angle, :source_json
+
+        def initialize(json)
+          @source_json = json
+          @inner_cone_angle = json.fetch('innerConeAngle', 0.0)
+          @outer_cone_angle = json.fetch('outerConeAngle', Math::PI / 4.0)
+        end
+      end
+
+      def self.parse(json, owner:, doc:)
+        return Collection.new(json) if owner.is_a?(Document)
+
+        collection = doc.extension('KHR_lights_punctual')
+        index = json.fetch('light')
+        light = collection&.lights&.fetch(index)
+        raise FormatError, "node references missing punctual light #{index}" unless light
+
+        NodeLight.new(light)
+      rescue IndexError, KeyError => e
+        raise FormatError, "invalid KHR_lights_punctual: #{e.message}"
+      end
+
+      def self.serialize(object, doc:)
+        if object.is_a?(Collection)
+          value = { 'lights' => object.lights.map { |light| serialize_light(light) } }
+          return serialize_properties(value, handled_keys: %w[lights])
+        end
+
+        serialize_properties({ 'light' => object.light.index }, handled_keys: %w[light])
+      end
+
+      def self.serialize_light(light)
+        copy_hash(light.source_json).tap do |json|
+          %w[name type color intensity range spot].each { |key| json.delete(key) }
+          json['type'] = light.type.to_s
+          json['name'] = light.name if light.name
+          json['color'] = light.color unless light.color == [1.0, 1.0, 1.0]
+          json['intensity'] = light.intensity unless light.intensity == 1.0
+          json['range'] = light.range if light.range
+          if light.spot
+            spot = copy_hash(light.spot.source_json)
+            %w[innerConeAngle outerConeAngle].each { |key| spot.delete(key) }
+            spot['innerConeAngle'] = light.spot.inner_cone_angle unless light.spot.inner_cone_angle == 0.0
+            spot['outerConeAngle'] = light.spot.outer_cone_angle unless light.spot.outer_cone_angle == Math::PI / 4.0
+            json['spot'] = spot unless spot.empty?
+          end
+        end
+      end
+
+      def self.copy_hash(value)
+        value.to_h { |key, child| [key, child] }
+      end
+    end
+  end
+end
+
+Rgltf.default_extensions.add(
+  'KHR_lights_punctual',
+  Rgltf::Extensions::KHRLightsPunctual,
+  on: %i[document node]
+)

data/lib/rgltf/extensions/khr_materials_emissive_strength.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Extensions
+    class KHRMaterialsEmissiveStrength < Extension
+      attr_reader :emissive_strength
+
+      def initialize(json)
+        @emissive_strength = json.fetch('emissiveStrength', 1.0)
+      end
+
+      def self.parse(json, owner:, doc:)
+        new(json)
+      end
+
+      def self.serialize(object, doc:)
+        value = object.emissive_strength == 1.0 ? {} : { 'emissiveStrength' => object.emissive_strength }
+
+        serialize_properties(value, handled_keys: %w[emissiveStrength])
+      end
+    end
+  end
+end
+
+Rgltf.default_extensions.add(
+  'KHR_materials_emissive_strength',
+  Rgltf::Extensions::KHRMaterialsEmissiveStrength,
+  on: :material
+)

data/lib/rgltf/extensions/khr_materials_unlit.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Extensions
+    class KHRMaterialsUnlit < Extension
+      INSTANCE = new.freeze
+
+      def self.parse(_json, owner:, doc:)
+        INSTANCE
+      end
+
+      def self.serialize(_object, doc:)
+        serialize_properties({}, handled_keys: [])
+      end
+    end
+  end
+end
+
+Rgltf.default_extensions.add('KHR_materials_unlit', Rgltf::Extensions::KHRMaterialsUnlit, on: :material)

data/lib/rgltf/extensions/khr_texture_transform.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Extensions
+    class KHRTextureTransform < Extension
+      attr_reader :offset, :rotation, :scale, :tex_coord
+
+      def initialize(json)
+        @offset = json.fetch('offset', [0.0, 0.0]).freeze
+        @rotation = json.fetch('rotation', 0.0)
+        @scale = json.fetch('scale', [1.0, 1.0]).freeze
+        @tex_coord = json['texCoord']
+      end
+
+      def uv_matrix
+        cosine = Math.cos(rotation)
+        sine = Math.sin(rotation)
+        [
+          cosine * scale[0], sine * scale[0], 0.0,
+          -sine * scale[1], cosine * scale[1], 0.0,
+          offset[0], offset[1], 1.0
+        ].freeze
+      end
+
+      def self.parse(json, owner:, doc:)
+        new(json)
+      end
+
+      def self.serialize(object, doc:)
+        value = {}.tap do |json|
+          json['offset'] = object.offset unless object.offset == [0.0, 0.0]
+          json['rotation'] = object.rotation unless object.rotation == 0.0
+          json['scale'] = object.scale unless object.scale == [1.0, 1.0]
+          json['texCoord'] = object.tex_coord unless object.tex_coord.nil?
+        end
+        serialize_properties(value, handled_keys: %w[offset rotation scale texCoord])
+      end
+    end
+  end
+end
+
+Rgltf.default_extensions.add('KHR_texture_transform', Rgltf::Extensions::KHRTextureTransform, on: :texture_info)

data/lib/rgltf/glb.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module GLB
+    MAGIC = 0x46546C67
+    CHUNK_JSON = 0x4E4F534A
+    CHUNK_BIN = 0x004E4942
+
+    module_function
+
+    def read(data)
+      bytes = data.b
+      raise FormatError, 'truncated GLB header' if bytes.bytesize < 12
+
+      magic, version, length = bytes.unpack('L<L<L<')
+      raise FormatError, 'not a GLB (bad magic)' unless magic == MAGIC
+      raise UnsupportedError, "GLB version #{version}" unless version == 2
+      raise FormatError, 'invalid GLB length' if length < 20
+      raise FormatError, 'GLB length must be 4-byte aligned' unless (length % 4).zero?
+      raise FormatError, 'GLB length does not match input' unless bytes.bytesize == length
+
+      offset = 12
+      json = nil
+      bin = nil
+      first_chunk = true
+      while offset < length
+        raise FormatError, 'truncated GLB chunk header' if offset + 8 > length
+
+        chunk_length, chunk_type = bytes.byteslice(offset, 8).unpack('L<L<')
+        raise FormatError, 'GLB chunk length must be 4-byte aligned' unless (chunk_length % 4).zero?
+
+        chunk_end = offset + 8 + chunk_length
+        raise FormatError, 'truncated GLB chunk' if chunk_end > length
+        raise FormatError, 'GLB JSON must be the first chunk' if first_chunk && chunk_type != CHUNK_JSON
+
+        body = bytes.byteslice(offset + 8, chunk_length)
+        case chunk_type
+        when CHUNK_JSON
+          raise FormatError, 'duplicate JSON chunk' if json
+
+          json = body
+        when CHUNK_BIN
+          raise FormatError, 'duplicate BIN chunk' if bin
+
+          bin = body
+        end
+        first_chunk = false
+        offset = chunk_end
+      end
+
+      raise FormatError, 'GLB chunks do not match declared length' unless offset == length
+      raise FormatError, 'GLB has no JSON chunk' unless json
+
+      [json, bin]
+    end
+
+    def write(json_string, bin_string = nil)
+      json = pad(json_string.b, 0x20)
+      chunks = [[CHUNK_JSON, json]]
+      chunks << [CHUNK_BIN, pad(bin_string.b, 0x00)] if bin_string
+      total = 12 + chunks.sum { |_, chunk| 8 + chunk.bytesize }
+      output = [MAGIC, 2, total].pack('L<L<L<')
+      chunks.each { |type, chunk| output << [chunk.bytesize, type].pack('L<L<') << chunk }
+      output
+    end
+
+    def pad(string, byte)
+      string + (byte.chr * ((4 - (string.bytesize % 4)) % 4))
+    end
+  end
+end