rgltf 1.0.0

data/lib/rgltf/buffer_resolver.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Rgltf
+  class BufferResolver
+    DATA_URI_PATTERN = /\Adata:([^,]*?),(.*)\z/m
+
+    def initialize(base_dir:, glb_bin: nil, supplied_buffers: nil)
+      @base_dir = base_dir && File.expand_path(base_dir)
+      @glb_bin = glb_bin&.b
+      @supplied_buffers = supplied_buffers
+      @cache = {}
+    end
+
+    def resolve(buffer)
+      return @cache[buffer.index] if @cache.key?(buffer.index)
+
+      bytes = supplied(buffer.index) || resolve_uri(buffer)
+      if bytes.bytesize < buffer.byte_length
+        raise FormatError,
+              "buffer #{buffer.index} is shorter than byteLength (#{bytes.bytesize} < #{buffer.byte_length})"
+      end
+
+      @cache[buffer.index] = bytes.b.freeze
+    end
+
+    def release!
+      @cache.clear
+      @glb_bin = nil
+      @supplied_buffers = nil
+    end
+
+    def resolve_resource(uri)
+      return decode_data_uri(uri) if uri.start_with?('data:')
+
+      resolve_external(uri)
+    end
+
+    def supplied?(index)
+      return index.zero? if @supplied_buffers.is_a?(String)
+      return false unless @supplied_buffers.respond_to?(:[])
+      return false if @supplied_buffers.respond_to?(:key?) && !@supplied_buffers.key?(index)
+
+      !@supplied_buffers[index].nil?
+    rescue StandardError
+      false
+    end
+
+    private :supplied?
+
+    private
+
+    def supplied(index)
+      return unless supplied?(index)
+
+      value = @supplied_buffers.is_a?(String) ? @supplied_buffers : @supplied_buffers[index]
+      value&.b
+    end
+
+    def resolve_uri(buffer)
+      return @glb_bin if buffer.uri.nil? && buffer.index.zero? && @glb_bin
+      return decode_data_uri(buffer.uri) if buffer.uri&.start_with?('data:')
+      return resolve_external(buffer.uri) if buffer.uri
+
+      raise MissingResourceError, "buffer #{buffer.index} has no URI or GLB BIN chunk"
+    end
+
+    def decode_data_uri(uri)
+      match = DATA_URI_PATTERN.match(uri)
+      raise FormatError, 'invalid data URI' unless match
+
+      metadata, payload = match.captures
+      decoded_payload = URI::DEFAULT_PARSER.unescape(payload)
+      metadata.split(';').include?('base64') ? decoded_payload.unpack1('m0') : decoded_payload
+    rescue ArgumentError => e
+      raise FormatError, "invalid data URI: #{e.message}"
+    end
+
+    def resolve_external(uri)
+      raise MissingResourceError, 'cannot resolve external resource without base_dir' unless @base_dir
+
+      decoded = URI.decode_www_form_component(uri)
+      path = File.expand_path(decoded, @base_dir)
+      base_prefix = @base_dir.end_with?(File::SEPARATOR) ? @base_dir : "#{@base_dir}#{File::SEPARATOR}"
+      unless path == @base_dir || path.start_with?(base_prefix)
+        raise MissingResourceError, "external resource escapes base_dir: #{uri}"
+      end
+
+      File.binread(path)
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise MissingResourceError, e.message
+    end
+  end
+end

data/lib/rgltf/builder/accessor_data.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Builder
+    module AccessorData
+      private
+
+      def add_matrix_padding(source, type, component_size, count)
+        dimension = AccessorReader::MATRIX_DIMENSIONS[type]
+        return source unless dimension && component_size < 4
+
+        column_size = dimension * component_size
+        column_padding = (4 - (column_size % 4)) % 4
+        output = String.new(encoding: Encoding::BINARY)
+        offset = 0
+        count.times do
+          dimension.times do
+            output << source.byteslice(offset, column_size) << ("\0" * column_padding)
+            offset += column_size
+          end
+        end
+        output
+      end
+
+      def add_min_max(value, source, info, component_count)
+        elements = source.unpack("#{info.fetch(:pack)}*").each_slice(component_count).to_a
+        return if elements.empty?
+
+        value['min'] = extrema(elements, component_count, &:min)
+        value['max'] = extrema(elements, component_count, &:max)
+      end
+
+      def extrema(elements, component_count)
+        Array.new(component_count) do |component|
+          yield elements.map { |element| element[component] }
+        end
+      end
+    end
+  end
+end

data/lib/rgltf/builder/accessors.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Builder
+    module Accessors
+      def accessor(type, component_type, packed, min_max: false, target: :array_buffer, **properties)
+        type_name = type.to_s.upcase
+        info = AccessorReader::COMPONENTS_BY_SYMBOL.fetch(component_type.to_sym)
+        component_count = AccessorReader::ELEMENT_COUNTS.fetch(type_name)
+        element_size = info[:size] * component_count
+        source = packed.b
+        unless (source.bytesize % element_size).zero?
+          raise ArgumentError,
+                'accessor byte length must be divisible by its element size'
+        end
+
+        count = source.bytesize / element_size
+        stored = add_matrix_padding(source, type_name, info[:size], count)
+        view_index = append_buffer_view(stored, target: target && TARGETS.fetch(target.to_sym))
+        value = accessor_properties(type, component_type, count:, **properties)
+        value['bufferView'] = view_index
+        add_min_max(value, source, info, component_count) if min_max
+        handle(:accessor, append('accessors', value), buffer_view_index: view_index)
+      rescue KeyError => e
+        raise ArgumentError, "unsupported accessor type: #{e.message}"
+      end
+
+      def buffer_view(bytes, byte_stride: nil, target: nil, name: nil, extensions: nil, extras: nil)
+        target_number = target && TARGETS.fetch(target.to_sym)
+        index = append_buffer_view(bytes.b, target: target_number, byte_stride:, name:, extensions:, extras:)
+        handle(:buffer_view, index)
+      rescue KeyError
+        raise ArgumentError, "unsupported buffer view target #{target.inspect}"
+      end
+
+      def accessor_from_view(type, component_type, buffer_view:, count:, byte_offset: 0,
+                             normalized: false, min: nil, max: nil, **properties)
+        value = accessor_properties(type, component_type, count:, byte_offset:, normalized:, min:, max:, **properties)
+        value['bufferView'] = reference(buffer_view, :buffer_view)
+        handle(:accessor, append('accessors', value), buffer_view_index: buffer_view.index)
+      end
+
+      def sparse_accessor(type, component_type, count:, indices:, values:, index_component_type: :u16,
+                          base: nil, normalized: false, sparse_extensions: nil, sparse_extras: nil,
+                          indices_extensions: nil, indices_extras: nil,
+                          values_extensions: nil, values_extras: nil, **properties)
+        index_info = sparse_index_info(index_component_type)
+        index_bytes = indices.is_a?(String) ? indices.b : Array(indices).pack("#{index_info.fetch(:pack)}*")
+        unless (index_bytes.bytesize % index_info.fetch(:size)).zero?
+          raise ArgumentError, 'sparse index byte length must be divisible by its component size'
+        end
+
+        sparse_count = index_bytes.bytesize / index_info.fetch(:size)
+        value_info = AccessorReader::COMPONENTS_BY_SYMBOL.fetch(component_type.to_sym)
+        type_name = type.to_s.upcase
+        component_count = AccessorReader::ELEMENT_COUNTS.fetch(type_name)
+        expected_size = sparse_count * component_count * value_info.fetch(:size)
+        unless values.bytesize == expected_size
+          raise ArgumentError,
+                'sparse value byte length does not match its indices'
+        end
+
+        value_bytes = add_matrix_padding(values.b, type_name, value_info.fetch(:size), sparse_count)
+        sparse = sparse_properties(index_bytes, value_bytes, index_info, sparse_count,
+                                   sparse_extensions:, sparse_extras:, indices_extensions:,
+                                   indices_extras:, values_extensions:, values_extras:)
+        value = accessor_properties(type, component_type, count:, normalized:, **properties)
+        view_index = append_sparse_base(value, base, type_name, value_info, count)
+        value['sparse'] = sparse
+        handle(:accessor, append('accessors', value), buffer_view_index: view_index)
+      rescue KeyError => e
+        raise ArgumentError, "unsupported sparse accessor type: #{e.message}"
+      end
+
+      private
+
+      def sparse_index_info(component_type)
+        symbol = component_type.to_sym
+        raise ArgumentError, 'sparse indices must use u8, u16, or u32' unless %i[u8 u16 u32].include?(symbol)
+
+        AccessorReader::COMPONENTS_BY_SYMBOL.fetch(symbol)
+      end
+
+      def sparse_properties(index_bytes, value_bytes, info, count, sparse_extensions:, sparse_extras:,
+                            indices_extensions:, indices_extras:, values_extensions:, values_extras:)
+        indices = { 'bufferView' => append_buffer_view(index_bytes, target: nil),
+                    'componentType' => info.fetch(:number) }
+        add_extension_properties(indices, indices_extensions, indices_extras)
+        values = { 'bufferView' => append_buffer_view(value_bytes, target: nil) }
+        add_extension_properties(values, values_extensions, values_extras)
+        { 'count' => count, 'indices' => indices, 'values' => values }.tap do |sparse|
+          add_extension_properties(sparse, sparse_extensions, sparse_extras)
+        end
+      end
+
+      def add_extension_properties(value, extensions, extras)
+        value['extensions'] = extensions if extensions
+        value['extras'] = extras unless extras.nil?
+      end
+
+      def append_sparse_base(value, base, type_name, info, count)
+        return unless base
+
+        component_count = AccessorReader::ELEMENT_COUNTS.fetch(type_name)
+        expected_size = count * component_count * info.fetch(:size)
+        unless base.bytesize == expected_size
+          raise ArgumentError,
+                'sparse base byte length does not match accessor count'
+        end
+
+        view_index = append_buffer_view(add_matrix_padding(base.b, type_name, info.fetch(:size), count), target: nil)
+        value['bufferView'] = view_index
+        view_index
+      end
+
+      def accessor_properties(type, component_type, count:, byte_offset: 0, normalized: false,
+                              min: nil, max: nil, **properties)
+        info = AccessorReader::COMPONENTS_BY_SYMBOL.fetch(component_type.to_sym)
+        type_name = type.to_s.upcase
+        AccessorReader::ELEMENT_COUNTS.fetch(type_name)
+        value = { 'componentType' => info.fetch(:number), 'count' => count, 'type' => type_name }
+        value['byteOffset'] = byte_offset unless byte_offset.zero?
+        value['normalized'] = true if normalized
+        value['min'] = min if min
+        value['max'] = max if max
+        value.merge!(stringify_properties(properties))
+      end
+    end
+  end
+end

data/lib/rgltf/builder/component_builders.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Builder
+    class MeshBuilder
+      attr_reader :primitives
+
+      def initialize(builder)
+        @builder = builder
+        @primitives = []
+      end
+
+      def primitive(attributes:, indices: nil, material: nil, mode: :triangles, targets: nil,
+                    extensions: nil, extras: nil, **properties)
+        value = { 'attributes' => attributes_json(attributes) }
+        if indices
+          @builder.mark_accessor_target(indices, :element_array)
+          value['indices'] = @builder.reference(indices, :accessor)
+        end
+        value['material'] = @builder.reference(material, :material) if material
+        mode_number = Primitive::MODES.key(mode.to_sym)
+        raise ArgumentError, "unsupported primitive mode #{mode.inspect}" unless mode_number
+
+        value['mode'] = mode_number unless mode_number == 4
+        value['targets'] = targets.map { |target| attributes_json(target) } if targets
+        value['extensions'] = extensions if extensions
+        value['extras'] = extras unless extras.nil?
+        properties.each { |key, property| value[@builder.send(:camelize, key)] = property }
+        @primitives << value
+        self
+      end
+
+      private
+
+      def attributes_json(attributes)
+        attributes.to_h do |semantic, accessor|
+          @builder.mark_accessor_target(accessor, :array_buffer)
+          [semantic.to_s, @builder.reference(accessor, :accessor)]
+        end
+      end
+    end
+
+    class AnimationBuilder
+      attr_reader :samplers, :channels
+
+      def initialize(builder)
+        @builder = builder
+        @samplers = []
+        @channels = []
+      end
+
+      def sampler(input:, output:, interpolation: :linear, extensions: nil, extras: nil)
+        mode = interpolation.to_s.upcase
+        raise ArgumentError, "unsupported interpolation #{interpolation.inspect}" unless %w[LINEAR STEP
+                                                                                            CUBICSPLINE].include?(mode)
+
+        value = {
+          'input' => @builder.reference(input, :accessor),
+          'output' => @builder.reference(output, :accessor)
+        }
+        value['interpolation'] = mode unless mode == 'LINEAR'
+        value['extensions'] = extensions if extensions
+        value['extras'] = extras unless extras.nil?
+        @samplers << value
+        @samplers.length - 1
+      end
+
+      def channel(sampler:, node:, path:, extensions: nil, extras: nil,
+                  target_extensions: nil, target_extras: nil)
+        target_path = path.to_s
+        unless Animation::Channel::TARGET_PATHS.include?(target_path)
+          raise ArgumentError, "unsupported animation target path #{path.inspect}"
+        end
+
+        target = { 'node' => @builder.reference(node, :node), 'path' => target_path }
+        target['extensions'] = target_extensions if target_extensions
+        target['extras'] = target_extras unless target_extras.nil?
+        value = {
+          'sampler' => sampler,
+          'target' => target
+        }
+        value['extensions'] = extensions if extensions
+        value['extras'] = extras unless extras.nil?
+        @channels << value
+        self
+      end
+    end
+  end
+end

data/lib/rgltf/builder/document_properties.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Builder
+    module DocumentProperties
+      def extensions_used(*names)
+        @json['extensionsUsed'] = names.flatten.map(&:to_s).uniq
+        self
+      end
+
+      def extensions_required(*names)
+        values = names.flatten.map(&:to_s).uniq
+        @json['extensionsRequired'] = values
+        @json['extensionsUsed'] = (@json.fetch('extensionsUsed', []) | values)
+        self
+      end
+
+      def extension(name, value, required: false)
+        string_name = name.to_s
+        (@json['extensions'] ||= {})[string_name] = value
+        @json['extensionsUsed'] = (@json.fetch('extensionsUsed', []) | [string_name])
+        extensions_required(string_name) if required
+        self
+      end
+
+      def extras(value)
+        @json['extras'] = value
+        self
+      end
+    end
+  end
+end

data/lib/rgltf/builder/materials.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Builder
+    module Materials
+      TextureInfoValue = Struct.new(:json, :owner, keyword_init: true)
+
+      def image(bytes: nil, uri: nil, buffer_view: nil, mime_type: nil, name: nil, extensions: nil, extras: nil)
+        sources = [bytes, uri, buffer_view].count { |source| !source.nil? }
+        raise ArgumentError, 'provide exactly one of image bytes, uri, or buffer_view' unless sources == 1
+
+        value = image_properties(bytes:, uri:, buffer_view:, mime_type:)
+        add_common_properties(value, name:, extensions:, extras:)
+        handle(:image, append('images', value))
+      end
+
+      def sampler(mag_filter: nil, min_filter: nil, wrap_s: nil, wrap_t: nil,
+                  name: nil, extensions: nil, extras: nil)
+        value = sampler_properties(mag_filter:, min_filter:, wrap_s:, wrap_t:)
+        add_common_properties(value, name:, extensions:, extras:)
+        handle(:sampler, append('samplers', value))
+      end
+
+      def texture(image: nil, source: nil, mime_type: nil, sampler: nil, name: nil,
+                  extensions: nil, extras: nil)
+        image ||= source
+        raise ArgumentError, 'texture requires an image or source' unless image
+
+        image_handle = image.is_a?(Handle) ? verify_handle(image, :image) : self.image(bytes: image, mime_type:, name:)
+        texture_json = { 'source' => image_handle.index }
+        texture_json['sampler'] = build_sampler(sampler) if sampler
+        add_common_properties(texture_json, name:, extensions:, extras:)
+        handle(:texture, append('textures', texture_json))
+      end
+
+      def material(name: nil, base_color_factor: nil, base_color_texture: nil,
+                   metallic_factor: nil, roughness_factor: nil, metallic_roughness_texture: nil,
+                   normal_texture: nil, occlusion_texture: nil, emissive_texture: nil,
+                   emissive_factor: nil, alpha_mode: nil, alpha_cutoff: nil,
+                   double_sided: nil, pbr_extensions: nil, pbr_extras: nil,
+                   extensions: nil, extras: nil, **properties)
+        pbr = {}
+        pbr['baseColorFactor'] = base_color_factor if base_color_factor
+        pbr['baseColorTexture'] = texture_info_json(base_color_texture) if base_color_texture
+        pbr['metallicFactor'] = metallic_factor unless metallic_factor.nil?
+        pbr['roughnessFactor'] = roughness_factor unless roughness_factor.nil?
+        pbr['metallicRoughnessTexture'] = texture_info_json(metallic_roughness_texture) if metallic_roughness_texture
+        pbr['extensions'] = pbr_extensions if pbr_extensions
+        pbr['extras'] = pbr_extras unless pbr_extras.nil?
+        value = {}
+        add_common_properties(value, name:, extensions:, extras:)
+        value['pbrMetallicRoughness'] = pbr unless pbr.empty?
+        value['normalTexture'] = texture_info_json(normal_texture) if normal_texture
+        value['occlusionTexture'] = texture_info_json(occlusion_texture) if occlusion_texture
+        value['emissiveTexture'] = texture_info_json(emissive_texture) if emissive_texture
+        value['emissiveFactor'] = emissive_factor if emissive_factor
+        value['alphaMode'] = alpha_mode.to_s.upcase if alpha_mode
+        value['alphaCutoff'] = alpha_cutoff unless alpha_cutoff.nil?
+        value['doubleSided'] = double_sided unless double_sided.nil?
+        value.merge!(stringify_properties(properties))
+        handle(:material, append('materials', value))
+      end
+
+      def texture_info(texture, tex_coord: nil, extensions: nil, extras: nil)
+        build_texture_info(texture, tex_coord:, extensions:, extras:)
+      end
+
+      def normal_texture_info(texture, tex_coord: nil, scale: nil, extensions: nil, extras: nil)
+        build_texture_info(texture, tex_coord:, scale:, extensions:, extras:)
+      end
+
+      def occlusion_texture_info(texture, tex_coord: nil, strength: nil, extensions: nil, extras: nil)
+        build_texture_info(texture, tex_coord:, strength:, extensions:, extras:)
+      end
+
+      private
+
+      def image_properties(bytes:, uri:, buffer_view:, mime_type:)
+        return { 'uri' => uri }.tap { |value| value['mimeType'] = mime_type if mime_type } if uri
+        if buffer_view
+          return {
+            'bufferView' => reference(buffer_view, :buffer_view),
+            'mimeType' => mime_type || raise(ArgumentError, 'mime_type is required for buffer view images')
+          }
+        end
+
+        {
+          'bufferView' => append_buffer_view(bytes.b, target: nil),
+          'mimeType' => mime_type || raise(ArgumentError, 'mime_type is required for image bytes')
+        }
+      end
+
+      def build_sampler(properties)
+        return reference(properties, :sampler) if properties.is_a?(Handle)
+
+        reference(sampler(**properties), :sampler)
+      end
+
+      def build_texture_info(texture, **properties)
+        json = { 'index' => reference(texture, :texture) }
+        properties.each do |key, value|
+          next if value.nil?
+
+          json[camelize(key)] = value
+        end
+        TextureInfoValue.new(json:, owner: @handle_owner).freeze
+      end
+
+      def texture_info_json(value)
+        return { 'index' => reference(value, :texture) } if value.is_a?(Handle)
+        unless value.is_a?(TextureInfoValue) && value.owner.equal?(@handle_owner)
+          raise ArgumentError, 'expected a texture or texture-info builder handle'
+        end
+
+        value.json.dup
+      end
+
+      def sampler_properties(mag_filter: nil, min_filter: nil, wrap_s: nil, wrap_t: nil, **unknown)
+        raise ArgumentError, "unknown sampler properties: #{unknown.keys.join(', ')}" unless unknown.empty?
+
+        filters = Sampler::FILTERS.invert
+        wraps = Sampler::WRAPS.invert
+        value = {}
+        value['magFilter'] = filters.fetch(mag_filter) if mag_filter
+        value['minFilter'] = filters.fetch(min_filter) if min_filter
+        value['wrapS'] = wraps.fetch(wrap_s) if wrap_s && wrap_s != :repeat
+        value['wrapT'] = wraps.fetch(wrap_t) if wrap_t && wrap_t != :repeat
+        value
+      end
+    end
+  end
+end