stagecraft 1.0.0

data/lib/stagecraft/renderer/renderer.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  class Renderer
+    attr_reader :device, :queue, :surface_format, :stats, :width, :height, :sample_count
+
+    def self.offscreen(width:, height:, msaa: 1, **options)
+      new(width:, height:, msaa:, **options)
+    end
+
+    def initialize(window: nil, width: 800, height: 600, msaa: 4, device: nil, queue: nil,
+                   surface: nil, backend: nil)
+      @backend = backend
+      @window = window
+      @width = Integer(width)
+      @height = Integer(height)
+      @sample_count = Integer(msaa)
+      @stats = Stats.new
+      @after_render_callbacks = []
+      @disposed = false
+      @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if backend
+
+      @context = GPUContext.new(window:, width:, height:, device:, queue:, surface:)
+      @device = @context.device
+      @queue = @context.queue
+      @surface_format = @context.surface_format
+      @resources = FrameResources.new(context: @context, stats:, sample_count:)
+      @sample_count = @resources.sample_count
+      @resource_cache = ResourceCache.new(device: @device, queue: @queue, stats:)
+      @pipelines = PipelineFactory.new(
+        device: @device, queue: @queue, resources: @resources, resource_cache: @resource_cache,
+        stats:, sample_count: @sample_count
+      )
+      create_post_resources
+    rescue StandardError
+      dispose_after_failed_initialization
+      raise
+    end
+
+    def render(scene, camera)
+      ensure_alive!
+      resize_from_window
+      list = RenderList.new(scene, camera)
+      update_stats(list)
+      if @backend
+        frame = record_frame(list, camera)
+        report_debug_stats
+        return frame
+      end
+
+      light, light_vp = shadow_light_and_matrix(list)
+      @resources.resize_shadow(light.shadow.map_size) if light
+      ordered_items = list.items
+      @resources.begin_frame(
+        ordered_items,
+        camera:,
+        ambient: list.ambient,
+        lights: prioritized_lights(list.lights, light),
+        light_vp:,
+        time: elapsed_time
+      )
+      encoder = device.create_command_encoder(label: "stagecraft frame")
+      encode_shadow_pass(encoder, light ? ordered_items : [])
+      encode_main_pass(encoder, ordered_items, scene)
+      @after_render_callbacks.each { |callback| callback.call(encoder, @resources.hdr_view) }
+      target_texture, target_view = @resources.frame_target
+      encode_post_pass(encoder, target_view)
+      queue.submit([encoder.finish])
+      @context.present
+      @resource_cache.advance_frame
+      frame = Frame.new(
+        texture: target_texture,
+        width:,
+        height:,
+        device:,
+        queue:,
+        readable: @context.surface.nil?
+      )
+      report_debug_stats
+      frame
+    end
+
+    def resize(width, height)
+      ensure_alive!
+      @width = [Integer(width), 1].max
+      @height = [Integer(height), 1].max
+      return self if @backend
+      return self unless @context.resize(@width, @height)
+
+      @resources.resize(@width, @height)
+      create_post_resources
+      self
+    end
+
+    def on_after_render(&block)
+      @after_render_callbacks << block
+      self
+    end
+
+    def dispose
+      return self if @disposed
+
+      @disposed = true
+      first_error = nil
+      [
+        -> { warn_live_resources },
+        -> { release_post_resources },
+        -> { @pipelines&.dispose },
+        -> { @resource_cache&.dispose_all },
+        -> { @resources&.dispose },
+        -> { @context&.dispose }
+      ].each do |cleanup|
+        cleanup.call
+      rescue StandardError => error
+        first_error ||= error
+      end
+      raise first_error if first_error
+
+      self
+    end
+
+    def disposed?
+      @disposed
+    end
+
+    private
+
+    def dispose_after_failed_initialization
+      dispose
+    rescue StandardError
+      nil
+    end
+
+    def warn_live_resources
+      return unless ENV["STAGECRAFT_DEBUG"] == "1"
+      return unless @resource_cache&.live_count&.positive?
+
+      warn "Stagecraft renderer disposed with #{@resource_cache.live_count} live CPU resources"
+    end
+
+    def resize_from_window
+      return unless @window&.respond_to?(:drawable_size)
+
+      next_width, next_height = @window.drawable_size
+      resize(next_width, next_height) if next_width.positive? && next_height.positive?
+    end
+
+    def update_stats(list)
+      stats.reset_frame!
+      stats.increment(:visible_objects, list.items.length)
+      stats.increment(:culled_objects, list.culled_count)
+    end
+
+    def record_frame(list, camera)
+      @backend.begin_frame(camera:) if @backend.respond_to?(:begin_frame)
+      list.items.each do |item|
+        @backend.draw(
+          mesh: item.mesh,
+          features: item.features,
+          depth: item.depth,
+          pipeline_key: [
+            item.mesh.material.class,
+            Features.bits(item.features),
+            Features.vertex_layout_id(item.mesh.geometry)
+          ]
+        )
+        track_draw(item.mesh.geometry)
+      end
+      @backend.end_frame if @backend.respond_to?(:end_frame)
+      nil
+    end
+
+    def shadow_light_and_matrix(list)
+      light = list.lights.find { |candidate| candidate.is_a?(Lights::Directional) && candidate.cast_shadow }
+      return [nil, Larb::Mat4.identity] unless light
+
+      config = light.shadow
+      eye = light.world_position
+      target = eye + light.direction
+      view = Larb::Mat4.look_at(eye, target, Larb::Vec3.up)
+      extent = config.extent
+      projection = Cameras::Orthographic.new(
+        left: -extent, right: extent, top: extent, bottom: -extent,
+        near: config.near, far: config.far
+      ).projection_matrix
+      [light, projection * view]
+    end
+
+    def prioritized_lights(lights, shadow_light)
+      return lights unless shadow_light
+
+      [shadow_light, *lights.reject { |light| light.equal?(shadow_light) }]
+    end
+
+    def encode_shadow_pass(encoder, items)
+      pass = encoder.begin_render_pass(
+        label: "stagecraft shadow",
+        color_attachments: [],
+        depth_stencil_attachment: {
+          view: @resources.shadow_view,
+          depth_load_op: :clear,
+          depth_store_op: :store,
+          depth_clear_value: 1.0
+        }
+      )
+      items.each_with_index do |item, index|
+        next unless item.mesh.cast_shadow
+
+        draw_item(pass, item, index, shadow: true)
+      end
+      pass.end_pass
+    end
+
+    def encode_main_pass(encoder, items, scene)
+      clear = scene.background || Color.new(0.0)
+      attachment = @resources.main_color_attachment.merge(
+        clear_value: { r: clear.r, g: clear.g, b: clear.b, a: clear.a }
+      )
+      pass = encoder.begin_render_pass(
+        label: "stagecraft main",
+        color_attachments: [attachment],
+        depth_stencil_attachment: {
+          view: @resources.depth_view,
+          depth_load_op: :clear,
+          depth_store_op: :store,
+          depth_clear_value: 1.0
+        }
+      )
+      items.each_with_index { |item, index| draw_item(pass, item, index) }
+      pass.end_pass
+    end
+
+    def draw_item(pass, item, index, shadow: false)
+      geometry = @resource_cache.gpu_geometry(item.mesh.geometry)
+      pass.set_pipeline(@pipelines.pipeline_for(item, shadow:))
+      pass.set_bind_group(0, shadow ? @resources.shadow_frame_group : @resources.frame_group)
+      if shadow
+        pass.set_bind_group(1, @resources.empty_group)
+      else
+        pass.set_bind_group(1, @pipelines.material_binding(item.mesh.material, item.features))
+      end
+      pass.set_bind_group(
+        2,
+        @resources.object_group_for(item.mesh),
+        dynamic_offsets: [@resources.object_offset(index)]
+      )
+      bind_vertex_buffers(pass, item.mesh.geometry, geometry, item.mesh.material, shadow:)
+      if geometry.index_buffer
+        pass.set_index_buffer(geometry.index_buffer, geometry.index_format)
+        pass.draw_indexed(geometry.index_count)
+      else
+        pass.draw(geometry.vertex_count)
+      end
+      track_draw(item.mesh.geometry) unless shadow
+    end
+
+    def bind_vertex_buffers(pass, geometry, gpu_geometry, material, shadow:)
+      names = if shadow
+                %i[position joints weights]
+              elsif material.is_a?(Materials::Unlit)
+                %i[position uv uv1 color joints weights]
+              else
+                PipelineFactory::ATTRIBUTE_LOCATIONS.keys
+              end
+      slot = 0
+      names.each do |name|
+        next unless geometry.attribute(name)
+
+        pass.set_vertex_buffer(slot, gpu_geometry.vertex_buffers.fetch(name))
+        slot += 1
+      end
+    end
+
+    def track_draw(geometry)
+      stats.increment(:draw_calls)
+      count = geometry.index&.count || geometry.attribute(:position).count
+      triangles = case geometry.topology
+                  when :triangle_list then count / 3
+                  when :triangle_strip then [count - 2, 0].max
+                  else 0
+                  end
+      stats.increment(:triangles, triangles)
+    end
+
+    def create_post_resources
+      return unless @resources
+
+      release_post_resources
+      @post_sampler = device.create_sampler(mag_filter: :linear, min_filter: :linear)
+      @post_group = device.create_bind_group(
+        layout: @pipelines.post_layout,
+        entries: [
+          { binding: 0, texture_view: @resources.hdr_view },
+          { binding: 1, sampler: @post_sampler }
+        ]
+      )
+      @post_pipeline = @pipelines.post_pipeline(surface_format)
+    end
+
+    def encode_post_pass(encoder, target_view)
+      pass = encoder.begin_render_pass(
+        label: "stagecraft post",
+        color_attachments: [{ view: target_view, load_op: :clear, store_op: :store }]
+      )
+      pass.set_pipeline(@post_pipeline)
+      pass.set_bind_group(0, @post_group)
+      pass.draw(3)
+      pass.end_pass
+    end
+
+    def release_post_resources
+      @post_group&.release
+      @post_sampler&.release
+      @post_group = @post_sampler = nil
+    end
+
+    def elapsed_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+    end
+
+    def report_debug_stats
+      return unless ENV["STAGECRAFT_DEBUG"] == "1"
+
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if @last_debug_report && now - @last_debug_report < 1.0
+
+      warn "Stagecraft #{stats}"
+      @last_debug_report = now
+    end
+
+    def ensure_alive!
+      raise DisposedError, "renderer has been disposed" if disposed?
+    end
+  end
+end

data/lib/stagecraft/renderer/resource_cache.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  class Renderer
+    class ResourceCache
+      GPUGeometry = Data.define(:vertex_buffers, :index_buffer, :index_format, :index_count, :vertex_count, :layout_id)
+      GPUTexture = Data.define(:texture, :view, :sampler)
+      Entry = Struct.new(:owner, :version, :resource)
+
+      attr_reader :frame
+
+      def initialize(device:, queue:, stats:, in_flight_frames: 3)
+        @device = device
+        @queue = queue
+        @stats = stats
+        @in_flight_frames = in_flight_frames
+        @geometries = {}
+        @textures = {}
+        @dispose_queue = []
+        @registered = {}
+        @frame = 0
+      end
+
+      def gpu_geometry(geometry)
+        raise DisposedError, "cannot upload disposed geometry" if geometry.disposed?
+
+        existing = @geometries[geometry.object_id]
+        if existing&.owner&.equal?(geometry) && existing.version == geometry.version
+          return existing.resource
+        end
+
+        schedule_resource(existing.resource) if existing
+        resource = upload_geometry(geometry)
+        @geometries[geometry.object_id] = Entry.new(geometry, geometry.version, resource)
+        register_disposal(geometry)
+        resource
+      end
+
+      def gpu_texture(texture)
+        raise DisposedError, "cannot upload disposed texture" if texture.disposed?
+
+        existing = @textures[texture.object_id]
+        if existing&.owner&.equal?(texture) && existing.version == texture.version
+          return existing.resource
+        end
+
+        schedule_resource(existing.resource) if existing
+        resource = upload_texture(texture)
+        @textures[texture.object_id] = Entry.new(texture, texture.version, resource)
+        register_disposal(texture)
+        resource
+      end
+
+      def schedule_dispose(cpu_object)
+        entry = delete_owned_entry(@geometries, cpu_object) ||
+                delete_owned_entry(@textures, cpu_object)
+        schedule_resource(entry.resource) if entry
+        @registered.delete(cpu_object.object_id)
+        self
+      end
+
+      def advance_frame
+        @frame += 1
+        ready, @dispose_queue = @dispose_queue.partition { |due, _resource| due <= frame }
+        ready.each { |_due, resource| destroy_resource(resource) }
+        self
+      end
+
+      def dispose_all
+        resources = @geometries.values.concat(@textures.values).map(&:resource)
+        resources.concat(@dispose_queue.map(&:last))
+        resources.each { |resource| destroy_resource(resource) }
+        @geometries.clear
+        @textures.clear
+        @dispose_queue.clear
+        @registered.clear
+        self
+      end
+
+      def live_count
+        @geometries.length + @textures.length
+      end
+
+      private
+
+      def upload_geometry(geometry)
+        buffers = geometry.attributes.to_h do |name, attribute|
+          buffer = @device.create_buffer_with_data(
+            label: "stagecraft #{name}",
+            data: attribute.data,
+            usage: %i[vertex copy_dst]
+          )
+          @stats.increment(:buffers)
+          [name, buffer]
+        end
+        index_buffer = if geometry.index
+                         @stats.increment(:buffers)
+                         @device.create_buffer_with_data(
+                           label: "stagecraft index",
+                           data: geometry.index.data,
+                           usage: %i[index copy_dst]
+                         )
+                       end
+        GPUGeometry.new(
+          vertex_buffers: buffers.freeze,
+          index_buffer:,
+          index_format: geometry.index&.format,
+          index_count: geometry.index&.count,
+          vertex_count: geometry.attribute(:position).count,
+          layout_id: Features.vertex_layout_id(geometry)
+        )
+      end
+
+      def upload_texture(texture)
+        require "texel/wgpu"
+        raise Error, "texture has no image" unless texture.image
+
+        image = texture.image
+        if texture.color_space && image.color_space != texture.color_space
+          image = image.dup_with(color_space: texture.color_space)
+        end
+        gpu_texture = Texel::WGPU.upload(image, device: @device, queue: @queue)
+        sampler_state = texture.sampler
+        sampler = @device.create_sampler(
+          address_mode_u: sampler_state.wrap_u,
+          address_mode_v: sampler_state.wrap_v,
+          address_mode_w: sampler_state.wrap_w,
+          mag_filter: sampler_state.mag_filter,
+          min_filter: sampler_state.min_filter,
+          mipmap_filter: sampler_state.mipmap_filter,
+          lod_min_clamp: sampler_state.lod_min,
+          lod_max_clamp: sampler_state.lod_max,
+          compare: sampler_state.compare,
+          max_anisotropy: sampler_state.max_anisotropy
+        )
+        @stats.increment(:textures)
+        GPUTexture.new(texture: gpu_texture, view: gpu_texture.create_view, sampler:)
+      end
+
+      def register_disposal(object)
+        return if @registered[object.object_id]
+
+        @registered[object.object_id] = true
+        object.on_dispose { |disposed| schedule_dispose(disposed) }
+      end
+
+      def delete_owned_entry(collection, owner)
+        entry = collection[owner.object_id]
+        return unless entry&.owner&.equal?(owner)
+
+        collection.delete(owner.object_id)
+      end
+
+      def schedule_resource(resource)
+        @dispose_queue << [frame + @in_flight_frames, resource]
+      end
+
+      def destroy_resource(resource)
+        case resource
+        when GPUGeometry
+          [*resource.vertex_buffers.values, resource.index_buffer].compact.each do |buffer|
+            buffer.destroy if buffer.respond_to?(:destroy)
+            buffer.release if buffer.respond_to?(:release)
+            @stats.decrement(:buffers)
+          end
+        when GPUTexture
+          resource.sampler.release if resource.sampler.respond_to?(:release)
+          resource.view.release if resource.view.respond_to?(:release)
+          resource.texture.destroy if resource.texture.respond_to?(:destroy)
+          resource.texture.release if resource.texture.respond_to?(:release)
+          @stats.decrement(:textures)
+        end
+      end
+    end
+  end
+end

data/lib/stagecraft/renderer/shaders/common.wgsl

@@ -0,0 +1,48 @@
+struct FrameUniforms {
+  view_proj: mat4x4f,
+  camera_pos: vec3f,
+  time: f32,
+  ambient: vec3f,
+  light_count: u32,
+  light_vp: mat4x4f,
+};
+
+struct Light {
+  kind: u32,
+  color: vec3f,
+  position: vec3f,
+  direction: vec3f,
+  range: f32,
+  cone: vec2f,
+};
+
+struct ObjectUniforms {
+  model: mat4x4f,
+  normal_matrix: mat4x4f,
+  receive_shadow: u32,
+};
+
+@group(0) @binding(0) var<uniform> frame: FrameUniforms;
+@group(0) @binding(1) var<storage, read> lights: array<Light>;
+@group(0) @binding(2) var shadow_map: texture_depth_2d;
+@group(0) @binding(3) var shadow_sampler: sampler_comparison;
+@group(2) @binding(0) var<uniform> object: ObjectUniforms;
+@group(2) @binding(1) var<storage, read> joints: array<mat4x4f>;
+
+fn shadow_visibility(world_position: vec3f) -> f32 {
+  let projected = frame.light_vp * vec4f(world_position, 1.0);
+  let uvz = projected.xyz / projected.w;
+  let uv = vec2f(uvz.x * 0.5 + 0.5, 0.5 - uvz.y * 0.5);
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0 || uvz.z > 1.0) {
+    return 1.0;
+  }
+  var visibility = 0.0;
+  let dimensions = vec2f(textureDimensions(shadow_map));
+  for (var y = -1; y <= 1; y = y + 1) {
+    for (var x = -1; x <= 1; x = x + 1) {
+      let offset = vec2f(f32(x), f32(y)) / dimensions;
+      visibility += textureSampleCompare(shadow_map, shadow_sampler, uv + offset, uvz.z - 0.001);
+    }
+  }
+  return visibility / 9.0;
+}