assimp-ruby 1.0.0

data/lib/assimp/native.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "rbconfig"
+require "thread"
+require_relative "native/platform"
+require_relative "native/types"
+
+module Assimp
+  module Native
+    extend FFI::Library
+
+    ENVIRONMENT_KEY = "ASSIMP_LIBRARY_PATH"
+    REQUIRED_MAJOR = 5
+    LOAD_MUTEX = Mutex.new
+
+    class << self
+      def load!
+        return self if @loaded
+
+        LOAD_MUTEX.synchronize do
+          return self if @loaded
+
+          ffi_lib(resolve_library)
+          attach_api
+          verify_version!
+          @loaded = true
+        end
+        self
+      rescue FFI::NotFoundError, LoadError => e
+        raise LibraryError, "could not load Assimp 5.x: #{e.message}"
+      end
+
+      def loaded?
+        @loaded == true
+      end
+
+      def version
+        load!
+        [aiGetVersionMajor, aiGetVersionMinor, @version_patch ? aiGetVersionPatch : 0]
+      end
+
+      def revision
+        load!
+        aiGetVersionRevision
+      end
+
+      def supports_extension?(extension)
+        load!
+        aiIsExtensionSupported(normalize_extension(extension)) != 0
+      end
+
+      def extension_list
+        load!
+        output = StringValue.new
+        aiGetExtensionList(output)
+        output.to_s.split(";").map { |extension| extension.delete_prefix("*.") }.freeze
+      end
+
+      def library_candidates
+        explicit = ENV[ENVIRONMENT_KEY]
+        return [File.expand_path(explicit)] if explicit && !explicit.empty?
+
+        packaged = packaged_library_candidates.select { |path| File.file?(path) }
+        packaged + platform_library_names
+      end
+
+      private
+
+      def resolve_library
+        explicit = ENV[ENVIRONMENT_KEY]
+        if explicit && !File.file?(File.expand_path(explicit))
+          raise LoadError, "#{ENVIRONMENT_KEY} does not point to a file: #{File.expand_path(explicit)}"
+        end
+
+        library_candidates.find { |candidate| loadable?(candidate) } ||
+          raise(LoadError, missing_library_message)
+      end
+
+      def loadable?(candidate)
+        flags = FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_LOCAL
+        FFI::DynamicLibrary.open(candidate, flags)
+        true
+      rescue LoadError
+        false
+      end
+
+      def packaged_library_candidates
+        platform = Platform.tag
+        roots = $LOAD_PATH.map { |path| File.join(path, "assimp", "native") }
+        roots.flat_map do |root|
+          Platform.library_names.flat_map do |name|
+            [File.join(root, platform, name), File.join(root, name)]
+          end
+        end
+      end
+
+      def platform_library_names
+        ["assimp", *Platform.library_names]
+      end
+
+      def attach_api
+        attach_function :aiImportFile, %i[string uint], :pointer, blocking: true
+        attach_function :aiImportFileFromMemory, %i[pointer uint uint string], :pointer, blocking: true
+        attach_function :aiReleaseImport, [:pointer], :void
+        attach_function :aiGetErrorString, [], :string
+        attach_function :aiGetVersionMajor, [], :uint
+        attach_function :aiGetVersionMinor, [], :uint
+        attach_function :aiGetVersionRevision, [], :uint
+        @version_patch = attach_optional_function(:aiGetVersionPatch, [], :uint)
+        attach_function :aiIsExtensionSupported, [:string], :int
+        attach_function :aiGetExtensionList, [:pointer], :void
+
+        attach_function :aiGetMaterialProperty, %i[pointer string uint uint pointer], :int
+        attach_function :aiGetMaterialColor, %i[pointer string uint uint pointer], :int
+        attach_function :aiGetMaterialFloatArray, %i[pointer string uint uint pointer pointer], :int
+        attach_function :aiGetMaterialIntegerArray, %i[pointer string uint uint pointer pointer], :int
+        attach_function :aiGetMaterialString, %i[pointer string uint uint pointer], :int
+        attach_function :aiGetMaterialTextureCount, %i[pointer int], :uint
+        attach_function :aiGetMaterialTexture,
+                        %i[pointer int uint pointer pointer pointer pointer pointer pointer pointer], :int
+      end
+
+      def attach_optional_function(name, arguments, result)
+        attach_function(name, arguments, result)
+        true
+      rescue FFI::NotFoundError
+        false
+      end
+
+      def normalize_extension(extension)
+        value = String(extension)
+        value.start_with?(".") ? value : ".#{value}"
+      end
+
+      def verify_version!
+        major = aiGetVersionMajor
+        return if major == REQUIRED_MAJOR
+
+        raise IncompatibleLibraryError, "Assimp #{REQUIRED_MAJOR}.x is required, found #{major}.x"
+      end
+
+      def missing_library_message
+        "set #{ENVIRONMENT_KEY} or install a compatible libassimp shared library"
+      end
+    end
+  end
+end

data/lib/assimp/native_reader.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Assimp
+  module NativeReader
+    module_function
+
+    def pointers(pointer, count)
+      return [] if count.zero?
+      raise ImportError, "native pointer array is null" if pointer.null?
+
+      pointer.read_array_of_pointer(count)
+    end
+
+    def struct_at(pointer, type, index)
+      type.new(pointer + (type.size * index))
+    end
+
+    def bytes(pointer, size)
+      return "".b.freeze if size.zero?
+      raise ImportError, "native data pointer is null" if pointer.null?
+
+      pointer.read_bytes(size).force_encoding(Encoding::BINARY).freeze
+    end
+  end
+end

data/lib/assimp/node.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Assimp
+  class Node
+    attr_reader :name, :matrix, :children, :mesh_indices
+
+    def initialize(name:, matrix:, children:, mesh_indices:)
+      @name = String(name).dup.freeze
+      @matrix = matrix.map { |value| Float(value) }.freeze
+      raise ArgumentError, "node matrix must contain 16 values" unless @matrix.length == 16
+
+      @children = children.freeze
+      @mesh_indices = mesh_indices.map { |index| Integer(index) }.freeze
+      freeze
+    end
+
+    def find(name)
+      target = String(name)
+      stack = [self]
+      until stack.empty?
+        node = stack.pop
+        return node if node.name == target
+
+        stack.concat(node.children.reverse)
+      end
+      nil
+    end
+  end
+end

data/lib/assimp/post_process.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "native/generated"
+
+module Assimp
+  POST_PROCESS = Native::POST_PROCESS
+
+  PROCESS_PRESETS = {
+    none: [].freeze,
+    fast: %i[triangulate join_identical_vertices gen_normals].freeze,
+    realtime: %i[
+      triangulate join_identical_vertices gen_smooth_normals calc_tangent_space
+      limit_bone_weights improve_cache_locality sort_by_p_type
+    ].freeze
+  }.freeze
+
+  module PostProcess
+    module_function
+
+    def flags(value)
+      names = value.is_a?(Symbol) ? preset(value) : Array(value)
+      names.reduce(0) do |result, name|
+        result | POST_PROCESS.fetch(name.to_sym) do
+          raise ArgumentError, "unknown post-process flag #{name.inspect}"
+        end
+      end
+    end
+
+    def preset(name)
+      PROCESS_PRESETS.fetch(name) do
+        raise ArgumentError, "unknown post-process preset #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/assimp/raw_scene.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Assimp
+  class RawScene
+    class View
+      attr_reader :native_type
+
+      def initialize(owner, native_type, pointer)
+        @owner = owner
+        @native_type = native_type
+        @pointer = pointer
+      end
+
+      def [](field)
+        native[field]
+      end
+
+      def to_ptr
+        ensure_valid!
+        @pointer
+      end
+
+      def inspect
+        state = @owner.valid? ? "valid" : "released"
+        "#<#{self.class.name} #{@native_type.name} #{state}>"
+      end
+
+      private
+
+      def native
+        ensure_valid!
+        @native_type.new(@pointer)
+      end
+
+      def ensure_valid!
+        return if @owner.valid?
+
+        raise ReleasedError, "raw view is only valid inside the Assimp.open block"
+      end
+    end
+
+    def initialize(pointer)
+      @pointer = pointer
+      @valid = true
+    end
+
+    def valid?
+      @valid
+    end
+
+    def native
+      ensure_valid!
+      View.new(self, Native::Scene, @pointer)
+    end
+
+    def pointer
+      ensure_valid!
+      @pointer
+    end
+
+    def meshes
+      source = native_struct
+      NativeReader.pointers(source[:meshes], source[:num_meshes]).map do |item|
+        View.new(self, Native::Mesh, item)
+      end
+    end
+
+    def materials
+      source = native_struct
+      NativeReader.pointers(source[:materials], source[:num_materials]).map do |item|
+        View.new(self, Native::Material, item)
+      end
+    end
+
+    def root
+      node_pointer = native_struct[:root_node]
+      node_pointer.null? ? nil : View.new(self, Native::Node, node_pointer)
+    end
+
+    def invalidate!
+      @valid = false
+      @pointer = nil
+      self
+    end
+
+    private
+
+    def native_struct
+      ensure_valid!
+      Native::Scene.new(@pointer)
+    end
+
+    def ensure_valid!
+      raise ReleasedError, "raw scene is only valid inside the Assimp.open block" unless valid?
+    end
+  end
+end

data/lib/assimp/scene.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Assimp
+  class Scene
+    INCOMPLETE_FLAG = 0x1
+
+    attr_reader :name, :meshes, :materials, :root, :animations, :textures, :flags
+
+    def initialize(name:, meshes:, materials:, root:, animations:, textures:, flags:)
+      @name = String(name).dup.freeze
+      @meshes = meshes.freeze
+      @materials = materials.freeze
+      @root = root
+      @animations = animations.freeze
+      @textures = textures.freeze
+      @flags = Integer(flags)
+      freeze
+    end
+
+    def incomplete?
+      (flags & INCOMPLETE_FLAG) != 0
+    end
+
+    def find_node(name)
+      root&.find(name)
+    end
+
+    def each_mesh_instance
+      return enum_for(__method__) unless block_given?
+      return self unless root
+
+      stack = [[root, Matrix::IDENTITY]]
+      until stack.empty?
+        node, parent_matrix = stack.pop
+        world_matrix = Matrix.multiply(parent_matrix, node.matrix)
+        node.mesh_indices.each { |index| yield meshes.fetch(index), world_matrix }
+        node.children.reverse_each { |child| stack << [child, world_matrix] }
+      end
+      self
+    end
+  end
+end

data/lib/assimp/scene_copier.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Assimp
+  class SceneCopier
+    def initialize(native: Native)
+      @native = native
+      @minor_version = native.version[1]
+      @mesh_copier = MeshCopier.new(native:)
+      @animation_copier = AnimationCopier.new(native:)
+      @texture_copier = TextureCopier.new
+    end
+
+    def copy(pointer)
+      source = Native::Scene.new(pointer)
+      textures = map_pointers(source[:textures], source[:num_textures], @texture_copier)
+      material_copier = MaterialCopier.new(native: @native, embedded_textures: textures)
+      Scene.new(
+        name: @minor_version.zero? ? "" : source[:name].to_s,
+        meshes: map_pointers(source[:meshes], source[:num_meshes], @mesh_copier),
+        materials: map_pointers(source[:materials], source[:num_materials], material_copier),
+        root: copy_node(source[:root_node]),
+        animations: map_pointers(source[:animations], source[:num_animations], @animation_copier),
+        textures:,
+        flags: source[:flags]
+      )
+    end
+
+    private
+
+    def map_pointers(pointer, count, copier)
+      NativeReader.pointers(pointer, count).map { |item| copier.copy(item) }.freeze
+    end
+
+    def copy_node(pointer)
+      return nil if pointer.null?
+
+      source = Native::Node.new(pointer)
+      Node.new(
+        name: source[:name].to_s,
+        matrix: source[:transformation].to_column_major,
+        children: NativeReader.pointers(source[:children], source[:num_children]).map { |child| copy_node(child) },
+        mesh_indices: source[:num_meshes].zero? ? [] : source[:meshes].read_array_of_uint(source[:num_meshes])
+      )
+    end
+  end
+end

data/lib/assimp/texture_copier.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Assimp
+  class TextureCopier
+    def copy(pointer)
+      source = Native::Texture.new(pointer)
+      byte_size = source[:height].zero? ? source[:width] : source[:width] * source[:height] * 4
+      EmbeddedTexture.new(
+        width: source[:width],
+        height: source[:height],
+        format_hint: source[:format_hint].to_ptr.read_string(9).delete("\0"),
+        filename: source[:filename].to_s,
+        bytes: NativeReader.bytes(source[:data], byte_size)
+      )
+    end
+  end
+end

data/lib/assimp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Assimp
+  VERSION = "1.0.0"
+end

data/lib/assimp.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "assimp/version"
+require_relative "assimp/errors"
+require_relative "assimp/post_process"
+require_relative "assimp/math"
+require_relative "assimp/mesh"
+require_relative "assimp/node"
+require_relative "assimp/material"
+require_relative "assimp/animation"
+require_relative "assimp/embedded_texture"
+require_relative "assimp/scene"
+require_relative "assimp/native"
+require_relative "assimp/native_reader"
+require_relative "assimp/mesh_copier"
+require_relative "assimp/material_copier"
+require_relative "assimp/animation_copier"
+require_relative "assimp/texture_copier"
+require_relative "assimp/scene_copier"
+require_relative "assimp/import_source"
+require_relative "assimp/raw_scene"
+require_relative "assimp/importer"
+
+module Assimp
+  class << self
+    def import(source, process: :realtime, hint: nil)
+      Importer.new.import(source, process:, hint:)
+    end
+
+    def open(source, process: :realtime, hint: nil, &block)
+      Importer.new.open(source, process:, hint:, &block)
+    end
+
+    def native_version
+      Native.version
+    end
+
+    def supports?(extension)
+      Native.supports_extension?(extension)
+    end
+
+    def supported_extensions
+      Native.extension_list
+    end
+  end
+end

data/rakelib/native_package.rake

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "fileutils"
+require "rbconfig"
+require_relative "../lib/assimp/native/platform"
+require_relative "../lib/assimp/version"
+
+module AssimpNativePackage
+  extend Rake::FileUtilsExt
+  module_function
+
+  ROOT = File.expand_path("..", __dir__)
+  ASSIMP_VERSION = "5.4.3"
+  PLATFORM = Assimp::Native::Platform.tag
+  SOURCE_DIR = File.expand_path(
+    ENV.fetch("ASSIMP_SOURCE_DIR", File.join(ROOT, "tmp", "assimp-#{ASSIMP_VERSION}"))
+  )
+  BUILD_DIR = File.join(ROOT, "tmp", "native", PLATFORM)
+
+  def explicit_library
+    value = ENV["ASSIMP_LIBRARY_PATH"]
+    return if value.nil? || value.empty?
+
+    path = File.expand_path(value)
+    raise "ASSIMP_LIBRARY_PATH does not point to a file: #{path}" unless File.file?(path)
+
+    path
+  end
+
+  def fetch_source
+    return if File.file?(File.join(SOURCE_DIR, "CMakeLists.txt"))
+    raise "#{SOURCE_DIR} exists but is not an Assimp source tree" if File.exist?(SOURCE_DIR)
+
+    FileUtils.mkdir_p(File.dirname(SOURCE_DIR))
+    sh(
+      "git", "clone", "--depth", "1", "--branch", "v#{ASSIMP_VERSION}",
+      "https://github.com/assimp/assimp.git", SOURCE_DIR
+    )
+  end
+
+  def configure
+    fetch_source
+    host_os = RbConfig::CONFIG.fetch("host_os")
+    bundled_zlib = host_os.match?(/mswin|mingw/) ? "ON" : "OFF"
+    command = [
+      "cmake",
+      "-S", SOURCE_DIR,
+      "-B", BUILD_DIR,
+      "-DCMAKE_BUILD_TYPE=Release",
+      "-DBUILD_SHARED_LIBS=ON",
+      "-DASSIMP_BUILD_ASSIMP_TOOLS=OFF",
+      "-DASSIMP_BUILD_SAMPLES=OFF",
+      "-DASSIMP_BUILD_TESTS=OFF",
+      "-DASSIMP_BUILD_DOCS=OFF",
+      "-DASSIMP_BUILD_DRACO=OFF",
+      "-DASSIMP_BUILD_ZLIB=#{bundled_zlib}",
+      "-DASSIMP_WARNINGS_AS_ERRORS=OFF",
+      "-DASSIMP_INJECT_DEBUG_POSTFIX=OFF",
+      "-DASSIMP_IGNORE_GIT_HASH=ON",
+      "-DASSIMP_NO_EXPORT=ON"
+    ]
+    command << "-DUSE_STATIC_CRT=ON" if host_os.match?(/mswin|mingw/)
+    if host_os.include?("darwin")
+      command << "-DCMAKE_OSX_ARCHITECTURES=#{RbConfig::CONFIG.fetch("host_cpu")}"
+    end
+    sh(*command)
+  end
+
+  def compile
+    configure
+    sh("cmake", "--build", BUILD_DIR, "--config", "Release", "--parallel")
+  end
+
+  def built_library
+    names = Assimp::Native::Platform.library_names
+    files = Dir.glob(File.join(BUILD_DIR, "**", "*")).select { |path| File.file?(path) }
+    match = names.lazy.filter_map do |name|
+      files.find { |path| File.basename(path) == name }
+    end.first
+    match ||= files.find do |path|
+      basename = File.basename(path)
+      basename.match?(/\Alibassimp(?:\.\d+(?:\.\d+)*)?\.(?:so|dylib)\z/) ||
+        basename.match?(/\Aassimp-vc\d+-mt\.dll\z/)
+    end
+    raise "Assimp shared library was not found in #{BUILD_DIR}" unless match
+
+    File.realpath(match)
+  end
+
+  def stage
+    source = explicit_library
+    unless source
+      compile
+      source = built_library
+    end
+
+    destination = File.join(ROOT, "lib", "assimp", "native", PLATFORM)
+    FileUtils.rm_rf(destination)
+    FileUtils.mkdir_p(destination)
+    FileUtils.cp(
+      source,
+      File.join(destination, Assimp::Native::Platform.packaged_library_name)
+    )
+
+    license = File.join(SOURCE_DIR, "LICENSE")
+    FileUtils.cp(license, File.join(destination, "ASSIMP-LICENSE.txt")) if File.file?(license)
+    destination
+  end
+
+  def platform_gem_path
+    platform = Gem::Platform.new(PLATFORM)
+    File.join(ROOT, "assimp-ruby-#{Assimp::VERSION}-#{platform}.gem")
+  end
+end
+
+module AssimpPackageSmoke
+  extend Rake::FileUtilsExt
+  module_function
+
+  ROOT = File.expand_path("..", __dir__)
+
+  def run(gem_path, label)
+    raise "gem was not built: #{gem_path}" unless File.file?(gem_path)
+
+    install_dir = File.join(ROOT, "tmp", "gem-smoke", label)
+    FileUtils.rm_rf(install_dir)
+    FileUtils.mkdir_p(install_dir)
+    sh(
+      "gem", "install", "--local", "--ignore-dependencies", "--no-document",
+      "--install-dir", install_dir, gem_path
+    )
+
+    environment = {
+      "GEM_HOME" => install_dir,
+      "GEM_PATH" => [install_dir, *Gem.path].uniq.join(File::PATH_SEPARATOR),
+      "ASSIMP_RUBY_SMOKE_HOME" => install_dir
+    }
+    Bundler.with_unbundled_env do
+      sh(environment, RbConfig.ruby, File.join(ROOT, "script", "smoke_gem.rb"))
+    end
+  end
+end
+
+namespace :native do
+  desc "Configure Assimp #{AssimpNativePackage::ASSIMP_VERSION}"
+  task :configure do
+    AssimpNativePackage.configure
+  end
+
+  desc "Compile the Assimp shared library"
+  task :compile do
+    AssimpNativePackage.compile
+  end
+
+  desc "Stage a shared library for the current platform gem"
+  task :stage do
+    AssimpNativePackage.stage
+  end
+
+  desc "Build a platform gem containing Assimp"
+  task gem: :stage do
+    Bundler.with_unbundled_env do
+      sh({ "ASSIMP_RUBY_PLATFORM_GEM" => "1" }, "gem", "build", "assimp.gemspec")
+    end
+  end
+
+  desc "Build, install, and execute the current platform gem"
+  task smoke_gem: :gem do
+    AssimpPackageSmoke.run(AssimpNativePackage.platform_gem_path, "platform")
+  end
+end
+
+namespace :package do
+  desc "Build the source gem"
+  task :source_gem do
+    Bundler.with_unbundled_env do
+      sh("gem", "build", "assimp.gemspec")
+    end
+  end
+
+  desc "Build, install, and execute the source gem against a system Assimp"
+  task smoke_source: :source_gem do
+    gem_path = File.join(__dir__, "..", "assimp-ruby-#{Assimp::VERSION}.gem")
+    AssimpPackageSmoke.run(gem_path, "source")
+  end
+end