renderdoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aab8b86504640671b46abb7746f8fd15a8663b70dc4bcc51e5c5ffa113f7a3ae
+  data.tar.gz: e86076c7a2d76ffefea4c798f2c97ddd4d6e548ec6a9f2639672cba44b869afc
+SHA512:
+  metadata.gz: 7b5fc719ae37e729bb4c2a0380468c6a091b893ab1304cebc95e8c33b73f42292259ff1b2391b1ef6e76d9cac7b0582e568ba4132839830657c8da6c10916d6c
+  data.tar.gz: 1e316d373258f1d24542d90eeecd206e43eac527f6077e1003c17f966770867c2bce902f81ab1edfc95e91b07cd5ddedca840fbc29fe0f927d049f99d022aad7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# RenderDoc for Ruby
+
+[![Ruby](https://github.com/ydah/renderdoc/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/renderdoc/actions/workflows/main.yml)
+
+`renderdoc` provides Ruby bindings for [RenderDoc](https://renderdoc.org/)'s in-application API. Use it to capture a specific block of GPU work, schedule frame captures, annotate captures, and open the replay UI from a Ruby application.
+
+The gem binds to RenderDoc but does not bundle, load, or inject RenderDoc itself.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RenderDoc with in-application API 1.6.0 or newer
+- Linux or Windows
+
+The only runtime gem dependency is [`ffi`](https://github.com/ffi/ffi), which Bundler installs automatically. RenderDoc does not officially support macOS, so `RenderDoc.available?` always returns `false` there. Use Xcode GPU Frame Capture for Metal applications.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "renderdoc"
+```
+
+Until the first RubyGems release, install it directly from GitHub:
+
+```ruby
+gem "renderdoc", github: "ydah/renderdoc"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Loading RenderDoc
+
+`ffi` lets Ruby call native functions; it does not place `librenderdoc.so` or `renderdoc.dll` in the process. The RenderDoc library must already be loaded before this gem can use its API.
+
+| Platform | How to load RenderDoc |
+|---|---|
+| Linux | Launch the application from RenderDoc, or use `LD_PRELOAD` |
+| Windows | Launch the application from RenderDoc so `renderdoc.dll` is injected |
+| macOS | Unsupported by RenderDoc |
+
+For a direct Linux launch:
+
+```sh
+LD_PRELOAD=librenderdoc.so bundle exec ruby app.rb
+```
+
+Use an absolute library path if `librenderdoc.so` is not on the dynamic loader's search path:
+
+```sh
+LD_PRELOAD=/path/to/librenderdoc.so bundle exec ruby app.rb
+```
+
+When the application is launched from the RenderDoc UI, do not also set `LD_PRELOAD`. Requiring this gem without RenderDoc attached is safe: `RenderDoc.available?` returns `false`.
+
+## Quick start
+
+```ruby
+require "renderdoc"
+
+if RenderDoc.available?
+  RenderDoc.capture_path_template = "captures/my_app"
+
+  RenderDoc.capture(title: "Bloom pass") do
+    renderer.render(scene, camera)
+  end
+end
+```
+
+`RenderDoc.capture` returns the block's result. If the block raises an exception, the gem discards the capture and re-raises the original exception. Nested and overlapping captures raise `RenderDoc::CaptureError`.
+
+## Capturing frames
+
+### Capture a block
+
+By default, RenderDoc uses wildcard device and window pointers. Supply native pointers when a particular device or window must be selected:
+
+```ruby
+RenderDoc.capture(device: device_pointer, window: window_pointer) do
+  renderer.render(scene, camera)
+end
+```
+
+For Vulkan, `device` must be the dispatch-table pointer described by `RENDERDOC_DEVICEPOINTER_FROM_VKINSTANCE`, not the `VkInstance` handle itself.
+
+### Trigger upcoming frames
+
+Schedule one or more captures without wrapping render code:
+
+```ruby
+RenderDoc.trigger_capture
+RenderDoc.trigger_capture(frames: 3)
+```
+
+## Captures and replay UI
+
+```ruby
+RenderDoc.api_version
+# => [1, 6, 0] or a newer compatible version
+
+RenderDoc.captures.each do |capture|
+  puts "#{capture.path} at #{capture.timestamp.iso8601}"
+end
+
+RenderDoc.comments = "scene=atrium commit=abc123"
+RenderDoc.set_capture_comments("regression case", path: "/tmp/frame.rdc")
+
+pid = RenderDoc.launch_replay_ui(connect: true)
+RenderDoc.show_replay_ui if RenderDoc.target_control_connected?
+```
+
+`Capture#timestamp` is a UTC `Time`. Paths are UTF-8 strings reported by RenderDoc; a listed capture may have been deleted after it was recorded.
+
+## Options, overlay, and keys
+
+```ruby
+RenderDoc.overlay = false
+RenderDoc.capture_keys = [:f12]
+RenderDoc.focus_toggle_keys = [:f11]
+
+RenderDoc.option(:api_validation, true)
+RenderDoc.option(:delay_for_debugger, 3)
+RenderDoc.option_value(:api_validation)
+```
+
+Option names from the API 1.6.0 header are accepted in snake case. Input buttons include function keys, letters, digits, navigation keys, `:print_screen`, and `:pause`. Unknown names and invalid values raise `ArgumentError` before entering FFI.
+
+## Running without RenderDoc
+
+By default, API calls other than `available?` raise `RenderDoc::NotAttachedError` when RenderDoc is absent. Applications where capture support is entirely optional can enable no-op behavior:
+
+```ruby
+RenderDoc.configure(unavailable: :noop)
+
+RenderDoc.capture { renderer.render(scene, camera) } # still renders
+RenderDoc.trigger_capture                            # => false
+RenderDoc.captures                                   # => []
+```
+
+| Error | Meaning |
+|---|---|
+| `RenderDoc::NotAttachedError` | RenderDoc is not loaded in the process |
+| `RenderDoc::VersionError` | The loaded RenderDoc cannot provide API 1.6.0 |
+| `RenderDoc::CaptureError` | A capture failed or another capture is in progress |
+
+## Frame-loop integration
+
+`RenderDoc::FrameTrigger` parses `STAGECRAFT_RENDERDOC=frame:N` and triggers exactly once. A frame loop such as stagecraft's can soft-require the gem and continue working when it is not installed:
+
+```ruby
+begin
+  require "renderdoc"
+  renderdoc_trigger = RenderDoc::FrameTrigger.from_environment
+rescue LoadError
+  renderdoc_trigger = nil
+end
+
+frame_number = 0
+loop do
+  renderdoc_trigger&.tick(frame_number)
+  renderer.render
+  frame_number += 1
+end
+```
+
+For example, set `STAGECRAFT_RENDERDOC=frame:120` before launching the application through RenderDoc to capture frame 120.
+
+## RSpec failure captures
+
+Require the optional integration from `spec_helper.rb`:
+
+```ruby
+require "renderdoc/rspec"
+```
+
+Tag examples whose render work can safely run a second time:
+
+```ruby
+it "renders the bloom pass", :renderdoc_on_failure do
+  render_and_compare
+end
+```
+
+When a tagged example fails and RenderDoc is attached, the integration runs the example body once more inside `RenderDoc.capture`, preserves the original failure, and reports the resulting `.rdc` path. Do not use the tag for examples with non-repeatable external side effects.
+
+## Development
+
+Run the unit suite:
+
+```sh
+bundle exec rake
+```
+
+The Linux integration spec is tagged `:renderdoc` and excluded from the default suite. CI runs it under `renderdoccmd`, Xvfb, SDL2, and Mesa software OpenGL, then verifies the generated `.rdc` file through the in-application API.
+
+The ABI constants in `lib/renderdoc/native/generated.rb` are generated from RenderDoc v1.25's `renderdoc_app.h`. After reviewing an upstream header change, regenerate them with:
+
+```sh
+ruby script/generate_native_api.rb path/to/renderdoc_app.h lib/renderdoc/native/generated.rb
+```
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt). RenderDoc is a separate project and is not distributed with this gem.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/renderdoc/application.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "thread"
+require "time"
+
+require_relative "capture"
+require_relative "configuration"
+require_relative "native"
+require_relative "settings"
+
+module RenderDoc
+  class Application
+    include Settings
+
+    UINT32_MAX = (2**32) - 1
+    NULL_POINTER = FFI::Pointer::NULL
+
+    def initialize(loader: Native::Loader.new, configuration: Configuration.new)
+      @loader = loader
+      @configuration = configuration
+      @api_mutex = Mutex.new
+      @capture_mutex = Mutex.new
+      @capturing = false
+    end
+
+    def available?
+      !load_api.nil?
+    rescue VersionError
+      false
+    end
+
+    def api_version
+      with_api do |api|
+        version = Array.new(3) { FFI::MemoryPointer.new(:int) }
+        api.call(:GetAPIVersion, *version)
+        version.map(&:read_int)
+      end
+    end
+
+    def capture(device: nil, window: nil, title: nil)
+      raise ArgumentError, "capture requires a block" unless block_given?
+
+      api = api_or_nil
+      return yield unless api
+
+      begin_capture(api)
+      begin
+        api.call(:StartFrameCapture, device, window)
+        api.call(:SetCaptureTitle, String(title)) if title
+        result = yield
+      rescue Exception # rubocop:disable Lint/RescueException -- native capture must always be discarded
+        discard_capture(api, device, window)
+        raise
+      else
+        ended = api.call(:EndFrameCapture, device, window)
+        raise CaptureError, "RenderDoc failed to save the frame capture" if ended.zero?
+
+        result
+      ensure
+        finish_capture
+      end
+    end
+
+    def trigger_capture(frames: 1)
+      unless frames.is_a?(Integer) && frames.positive? && frames <= UINT32_MAX
+        raise ArgumentError, "frames must be an integer between 1 and #{UINT32_MAX}"
+      end
+
+      with_api(default: false) do |api|
+        function = frames == 1 ? :TriggerCapture : :TriggerMultiFrameCapture
+        arguments = frames == 1 ? [] : [frames]
+        api.call(function, *arguments)
+        true
+      end
+    end
+
+    def capture_path_template
+      with_api do |api|
+        pointer = api.call(:GetCaptureFilePathTemplate)
+        pointer.null? ? nil : pointer.read_string
+      end
+    end
+
+    def capture_path_template=(path)
+      with_api(default: false) do |api|
+        api.call(:SetCaptureFilePathTemplate, String(path))
+        true
+      end
+    end
+
+    def captures
+      with_api(default: []) do |api|
+        api.call(:GetNumCaptures).times.map { |index| read_capture(api, index) }
+      end
+    end
+
+    def launch_replay_ui(connect: true, command_line: nil)
+      with_api(default: 0) do |api|
+        api.call(:LaunchReplayUI, connect ? 1 : 0, command_line&.to_s)
+      end
+    end
+
+    def target_control_connected?
+      with_api(default: false) { |api| !api.call(:IsTargetControlConnected).zero? }
+    end
+
+    def show_replay_ui
+      with_api(default: false) { |api| !api.call(:ShowReplayUI).zero? }
+    end
+
+    def comments=(comments)
+      with_api(default: false) do |api|
+        api.call(:SetCaptureFileComments, nil, String(comments))
+        true
+      end
+    end
+
+    def set_capture_comments(comments, path: nil)
+      with_api(default: false) do |api|
+        api.call(:SetCaptureFileComments, path&.to_s, String(comments))
+        true
+      end
+    end
+
+    private
+
+    def load_api
+      return @api if @api
+      raise @version_error if @version_error
+
+      @api_mutex.synchronize do
+        return @api if @api
+        raise @version_error if @version_error
+
+        @api = @loader.load
+      rescue VersionError => error
+        @version_error = error
+        raise
+      end
+    end
+
+    def api_or_nil
+      api = load_api
+      return api if api
+      return if @configuration.noop_when_unavailable?
+
+      raise NotAttachedError
+    end
+
+    def with_api(default: nil)
+      api = api_or_nil
+      return default unless api
+
+      yield api
+    end
+
+    def begin_capture(api)
+      @capture_mutex.synchronize do
+        if @capturing || !api.call(:IsFrameCapturing).zero?
+          raise CaptureError, "a RenderDoc frame capture is already in progress"
+        end
+
+        @capturing = true
+      end
+    end
+
+    def finish_capture
+      @capture_mutex.synchronize { @capturing = false }
+    end
+
+    def discard_capture(api, device, window)
+      api.call(:DiscardFrameCapture, device, window)
+    rescue StandardError
+      nil
+    end
+
+    def read_capture(api, index)
+      path_length = FFI::MemoryPointer.new(:uint32)
+      timestamp = FFI::MemoryPointer.new(:uint64)
+      found = api.call(:GetCapture, index, NULL_POINTER, path_length, timestamp)
+      raise CaptureError, "RenderDoc capture #{index} disappeared while enumerating" if found.zero?
+
+      buffer = FFI::MemoryPointer.new(:char, [path_length.read_uint32 + 1, 2].max)
+      path_length.write_uint32(buffer.size)
+      found = api.call(:GetCapture, index, buffer, path_length, timestamp)
+      raise CaptureError, "RenderDoc capture #{index} disappeared while reading its path" if found.zero?
+
+      Capture.new(path: buffer.read_string, timestamp: Time.at(timestamp.read_uint64).utc)
+    end
+  end
+end

data/lib/renderdoc/capture.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  Capture = Data.define(:path, :timestamp)
+end

data/lib/renderdoc/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  class Configuration
+    UNAVAILABLE_BEHAVIORS = %i[raise noop].freeze
+
+    attr_reader :unavailable_behavior
+
+    def initialize
+      @unavailable_behavior = :raise
+    end
+
+    def unavailable_behavior=(behavior)
+      behavior = behavior.to_sym
+      unless UNAVAILABLE_BEHAVIORS.include?(behavior)
+        raise ArgumentError, "unavailable behavior must be :raise or :noop"
+      end
+
+      @unavailable_behavior = behavior
+    end
+
+    def noop_when_unavailable?
+      unavailable_behavior == :noop
+    end
+  end
+end

data/lib/renderdoc/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  class Error < StandardError; end
+
+  class NotAttachedError < Error
+    def initialize(message = nil)
+      super(message || self.class.default_message)
+    end
+
+    def self.default_message
+      return "RenderDoc does not support macOS. Use Xcode GPU Frame Capture for Metal applications." if RUBY_PLATFORM.include?("darwin")
+      return "Launch the application from the RenderDoc UI so renderdoc.dll is already loaded." if Gem.win_platform?
+
+      "Launch via the RenderDoc UI, or run with LD_PRELOAD=librenderdoc.so ruby app.rb."
+    end
+  end
+
+  class VersionError < Error; end
+  class CaptureError < Error; end
+end

data/lib/renderdoc/frame_trigger.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  class FrameTrigger
+    ENVIRONMENT_VARIABLE = "STAGECRAFT_RENDERDOC"
+    FRAME_PATTERN = /\Aframe:(\d+)\z/
+
+    attr_reader :frame
+
+    def self.from_environment(environment: ENV, renderdoc: RenderDoc)
+      specification = environment[ENVIRONMENT_VARIABLE]
+      return unless specification
+
+      match = FRAME_PATTERN.match(specification)
+      unless match
+        raise ArgumentError, "#{ENVIRONMENT_VARIABLE} must use the form frame:N"
+      end
+
+      new(frame: Integer(match[1], 10), renderdoc: renderdoc)
+    end
+
+    def initialize(frame:, renderdoc: RenderDoc)
+      raise ArgumentError, "frame must be a non-negative Integer" unless frame.is_a?(Integer) && frame >= 0
+
+      @frame = frame
+      @renderdoc = renderdoc
+      @triggered = false
+    end
+
+    def call(current_frame)
+      return false if @triggered || current_frame != frame
+
+      @renderdoc.trigger_capture
+      @triggered = true
+      true
+    end
+
+    alias tick call
+  end
+end

data/lib/renderdoc/native/generated.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Generated from RenderDoc's renderdoc_app.h by script/generate_native_api.rb.
+# Source: RenderDoc v1.25, RENDERDOC_API_1_6_0. Do not edit by hand.
+module RenderDoc
+  module Native
+    API_VERSION = 10_600
+
+    API_TABLE_FIELDS = %i[
+      GetAPIVersion
+      SetCaptureOptionU32
+      SetCaptureOptionF32
+      GetCaptureOptionU32
+      GetCaptureOptionF32
+      SetFocusToggleKeys
+      SetCaptureKeys
+      GetOverlayBits
+      MaskOverlayBits
+      RemoveHooks
+      UnloadCrashHandler
+      SetCaptureFilePathTemplate
+      GetCaptureFilePathTemplate
+      GetNumCaptures
+      GetCapture
+      TriggerCapture
+      IsTargetControlConnected
+      LaunchReplayUI
+      SetActiveWindow
+      StartFrameCapture
+      IsFrameCapturing
+      EndFrameCapture
+      TriggerMultiFrameCapture
+      SetCaptureFileComments
+      DiscardFrameCapture
+      ShowReplayUI
+      SetCaptureTitle
+    ].freeze
+
+    FUNCTION_SIGNATURES = {
+      GetAPIVersion: [:void, %i[pointer pointer pointer]],
+      SetCaptureOptionU32: [:int, %i[int uint32]],
+      SetCaptureOptionF32: [:int, %i[int float]],
+      GetCaptureOptionU32: [:uint32, %i[int]],
+      GetCaptureOptionF32: [:float, %i[int]],
+      SetFocusToggleKeys: [:void, %i[pointer int]],
+      SetCaptureKeys: [:void, %i[pointer int]],
+      GetOverlayBits: [:uint32, []],
+      MaskOverlayBits: [:void, %i[uint32 uint32]],
+      RemoveHooks: [:void, []],
+      UnloadCrashHandler: [:void, []],
+      SetCaptureFilePathTemplate: [:void, %i[string]],
+      GetCaptureFilePathTemplate: [:pointer, []],
+      GetNumCaptures: [:uint32, []],
+      GetCapture: [:uint32, %i[uint32 pointer pointer pointer]],
+      TriggerCapture: [:void, []],
+      IsTargetControlConnected: [:uint32, []],
+      LaunchReplayUI: [:uint32, %i[uint32 string]],
+      SetActiveWindow: [:void, %i[pointer pointer]],
+      StartFrameCapture: [:void, %i[pointer pointer]],
+      IsFrameCapturing: [:uint32, []],
+      EndFrameCapture: [:uint32, %i[pointer pointer]],
+      TriggerMultiFrameCapture: [:void, %i[uint32]],
+      SetCaptureFileComments: [:void, %i[string string]],
+      DiscardFrameCapture: [:uint32, %i[pointer pointer]],
+      ShowReplayUI: [:uint32, []],
+      SetCaptureTitle: [:void, %i[string]]
+    }.freeze
+
+    CAPTURE_OPTIONS = {
+      :allow_vsync => 0,
+      :allow_fullscreen => 1,
+      :api_validation => 2,
+      :debug_device_mode => 2,
+      :capture_callstacks => 3,
+      :capture_callstacks_only_draws => 4,
+      :capture_callstacks_only_actions => 4,
+      :delay_for_debugger => 5,
+      :verify_buffer_access => 6,
+      :verify_map_writes => 6,
+      :hook_into_children => 7,
+      :ref_all_resources => 8,
+      :save_all_initials => 9,
+      :capture_all_cmd_lists => 10,
+      :debug_output_mute => 11,
+      :allow_unsupported_vendor_extensions => 12
+    }.freeze
+
+    INPUT_BUTTONS = {
+      :"0" => 48,
+      :"1" => 49,
+      :"2" => 50,
+      :"3" => 51,
+      :"4" => 52,
+      :"5" => 53,
+      :"6" => 54,
+      :"7" => 55,
+      :"8" => 56,
+      :"9" => 57,
+      :a => 65,
+      :b => 66,
+      :c => 67,
+      :d => 68,
+      :e => 69,
+      :f => 70,
+      :g => 71,
+      :h => 72,
+      :i => 73,
+      :j => 74,
+      :k => 75,
+      :l => 76,
+      :m => 77,
+      :n => 78,
+      :o => 79,
+      :p => 80,
+      :q => 81,
+      :r => 82,
+      :s => 83,
+      :t => 84,
+      :u => 85,
+      :v => 86,
+      :w => 87,
+      :x => 88,
+      :y => 89,
+      :z => 90,
+      :divide => 257,
+      :multiply => 258,
+      :subtract => 259,
+      :plus => 260,
+      :f1 => 261,
+      :f2 => 262,
+      :f3 => 263,
+      :f4 => 264,
+      :f5 => 265,
+      :f6 => 266,
+      :f7 => 267,
+      :f8 => 268,
+      :f9 => 269,
+      :f10 => 270,
+      :f11 => 271,
+      :f12 => 272,
+      :home => 273,
+      :end => 274,
+      :insert => 275,
+      :delete => 276,
+      :page_up => 277,
+      :page_down => 278,
+      :backspace => 279,
+      :tab => 280,
+      :print_screen => 281,
+      :pause => 282
+    }.freeze
+  end
+end

data/lib/renderdoc/native.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+require_relative "errors"
+require_relative "native/generated"
+
+module RenderDoc
+  module Native
+    extend FFI::Library
+
+    class APITable < FFI::Struct
+      layout(*API_TABLE_FIELDS.flat_map { |field| [field, :pointer] })
+    end
+
+    class API
+      def initialize(pointer, owner: nil)
+        @table = APITable.new(pointer)
+        @owner = owner
+        @functions = {}
+      end
+
+      def call(name, *arguments)
+        function(name).call(*arguments)
+      end
+
+      private
+
+      def function(name)
+        @functions[name] ||= begin
+          return_type, argument_types = FUNCTION_SIGNATURES.fetch(name)
+          pointer = @table[name]
+          raise VersionError, "RenderDoc returned a null pointer for #{name}" if pointer.null?
+
+          FFI::Function.new(return_type, argument_types, pointer)
+        end
+      end
+    end
+
+    class WindowsAPI
+      KERNEL_LIBRARY = "kernel32.dll"
+
+      def initialize(dynamic_library: FFI::DynamicLibrary)
+        flags = FFI::DynamicLibrary::RTLD_NOW | FFI::DynamicLibrary::RTLD_LOCAL
+        @kernel = dynamic_library.open(KERNEL_LIBRARY, flags)
+        @get_module_handle = windows_function(:pointer, [:string], "GetModuleHandleA")
+        @get_proc_address = windows_function(:pointer, %i[pointer string], "GetProcAddress")
+      end
+
+      def renderdoc_api_pointer
+        handle = @get_module_handle.call("renderdoc.dll")
+        return if handle.null?
+
+        pointer = @get_proc_address.call(handle, "RENDERDOC_GetAPI")
+        pointer unless pointer.null?
+      end
+
+      private
+
+      def windows_function(return_type, argument_types, name)
+        FFI::Function.new(return_type, argument_types, @kernel.find_function(name), convention: :stdcall)
+      end
+    end
+
+    class Loader
+      LINUX_LIBRARY = "librenderdoc.so"
+      GET_API_SYMBOL = "RENDERDOC_GetAPI"
+
+      def initialize(platform: RUBY_PLATFORM, dynamic_library: FFI::DynamicLibrary, windows_api: nil)
+        @platform = platform
+        @dynamic_library = dynamic_library
+        @windows_api = windows_api
+      end
+
+      def load
+        return if macos?
+
+        function_pointer, owner = get_api_pointer
+        return unless function_pointer
+
+        request_api(function_pointer, owner)
+      end
+
+      private
+
+      def get_api_pointer
+        return [windows_api.renderdoc_api_pointer, windows_api] if windows?
+
+        library = open_loaded_library(LINUX_LIBRARY)
+        return [nil, nil] unless library
+
+        [library.find_function(GET_API_SYMBOL), library]
+      rescue FFI::NotFoundError
+        [nil, nil]
+      end
+
+      def open_loaded_library(name)
+        flags = FFI::DynamicLibrary::RTLD_NOW | FFI::DynamicLibrary::RTLD_NOLOAD
+        @dynamic_library.open(name, flags)
+      rescue LoadError
+        nil
+      end
+
+      def request_api(function_pointer, owner)
+        get_api = FFI::Function.new(:int, %i[int pointer], function_pointer)
+        output = FFI::MemoryPointer.new(:pointer)
+        result = get_api.call(API_VERSION, output)
+        pointer = output.read_pointer
+
+        if result.zero? || pointer.null?
+          raise VersionError, "Loaded RenderDoc does not support the required in-application API 1.6.0"
+        end
+
+        API.new(pointer, owner: owner)
+      end
+
+      def windows_api
+        @windows_api ||= WindowsAPI.new(dynamic_library: @dynamic_library)
+      end
+
+      def windows?
+        @platform.match?(/mswin|mingw|cygwin/i)
+      end
+
+      def macos?
+        @platform.include?("darwin")
+      end
+    end
+  end
+end

data/lib/renderdoc/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+require_relative "../renderdoc"
+require_relative "rspec_integration"
+
+RenderDoc::RSpecIntegration.install!

data/lib/renderdoc/rspec_integration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  module RSpecIntegration
+    class FailureCapture
+      def initialize(renderdoc: RenderDoc)
+        @renderdoc = renderdoc
+      end
+
+      def capture(example)
+        return unless example.exception
+        return unless @renderdoc.available?
+
+        captures_before = @renderdoc.captures.length
+        rerun_example_in_capture(example)
+        report_capture(example, captures_before)
+      rescue RenderDoc::Error => error
+        example.reporter.message("RenderDoc capture failed: #{error.message}")
+      end
+
+      private
+
+      def rerun_example_in_capture(example)
+        block = example.instance_variable_get(:@example_block)
+        raise RenderDoc::CaptureError, "RSpec example block is unavailable" unless block
+
+        @renderdoc.capture(title: example.full_description) do
+          rerun_example_block(example, block)
+        end
+      end
+
+      def rerun_example_block(example, block)
+        example.example_group_instance.instance_exec(example, &block)
+      rescue Exception => error # rubocop:disable Lint/RescueException -- RSpec failures inherit directly from Exception
+        raise if error.is_a?(SystemExit) || error.is_a?(SignalException) || error.is_a?(NoMemoryError)
+
+        nil
+      end
+
+      def report_capture(example, captures_before)
+        captures = @renderdoc.captures
+        capture = captures.drop(captures_before).last || captures.last
+        message = capture ? "RenderDoc capture: #{capture.path}" : "RenderDoc capture completed"
+        example.reporter.message(message)
+      end
+    end
+
+    class << self
+      def install!(configuration = ::RSpec.configuration)
+        @installed_configurations ||= {}
+        return if @installed_configurations[configuration.object_id]
+
+        configuration.append_after(:each, :renderdoc_on_failure) do |example|
+          FailureCapture.new.capture(example)
+        end
+        @installed_configurations[configuration.object_id] = true
+      end
+    end
+  end
+end

data/lib/renderdoc/settings.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RenderDoc
+  module Settings
+    def overlay
+      with_api(default: false) { |api| (api.call(:GetOverlayBits) & 1) == 1 }
+    end
+
+    def overlay=(enabled)
+      with_api(default: false) do |api|
+        api.call(:MaskOverlayBits, 0, enabled ? 0xF : 0)
+        true
+      end
+    end
+
+    def capture_keys=(keys)
+      set_keys(:SetCaptureKeys, keys)
+    end
+
+    def focus_toggle_keys=(keys)
+      set_keys(:SetFocusToggleKeys, keys)
+    end
+
+    def option(name, value)
+      option_id = enum_value(Native::CAPTURE_OPTIONS, name, "capture option")
+      function, native_value = option_argument(value)
+      with_api(default: false) { |api| !api.call(function, option_id, native_value).zero? }
+    end
+
+    def option_value(name, type: :uint32)
+      option_id = enum_value(Native::CAPTURE_OPTIONS, name, "capture option")
+      function = {uint32: :GetCaptureOptionU32, float: :GetCaptureOptionF32}.fetch(type) do
+        raise ArgumentError, "type must be :uint32 or :float"
+      end
+      with_api { |api| api.call(function, option_id) }
+    end
+
+    private
+
+    def set_keys(function, keys)
+      values = Array(keys).map { |key| enum_value(Native::INPUT_BUTTONS, key, "input button") }
+      pointer = values.empty? ? NULL_POINTER : FFI::MemoryPointer.new(:int, values.length)
+      pointer.write_array_of_int(values) unless values.empty?
+      with_api(default: false) { |api| api.call(function, pointer, values.length); true }
+    end
+
+    def enum_value(mapping, name, kind)
+      mapping.fetch(name.to_s.downcase.to_sym)
+    rescue KeyError
+      raise ArgumentError, "unknown RenderDoc #{kind}: #{name.inspect}"
+    end
+
+    def option_argument(value)
+      return [:SetCaptureOptionF32, value] if value.is_a?(Float)
+      return [:SetCaptureOptionU32, value ? 1 : 0] if value == true || value == false
+      return [:SetCaptureOptionU32, value] if value.is_a?(Integer) && value.between?(0, UINT32_MAX)
+
+      raise ArgumentError, "option value must be a boolean, Float, or unsigned 32-bit Integer"
+    end
+  end
+end

data/lib/renderdoc/version.rb

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

data/lib/renderdoc.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "renderdoc/version"
+require_relative "renderdoc/errors"
+require_relative "renderdoc/application"
+require_relative "renderdoc/frame_trigger"
+
+module RenderDoc
+  class << self
+    def configure(unavailable: nil)
+      configuration.unavailable_behavior = unavailable if unavailable
+      yield configuration if block_given?
+      configuration
+    end
+
+    def available? = application.available?
+    def api_version = application.api_version
+    def capture(**arguments, &block) = application.capture(**arguments, &block)
+    def trigger_capture(frames: 1) = application.trigger_capture(frames: frames)
+    def capture_path_template = application.capture_path_template
+    def capture_path_template=(path)
+      application.capture_path_template = path
+    end
+    def captures = application.captures
+    def launch_replay_ui(**arguments) = application.launch_replay_ui(**arguments)
+    def target_control_connected? = application.target_control_connected?
+    def show_replay_ui = application.show_replay_ui
+    def comments=(comments)
+      application.comments = comments
+    end
+    def set_capture_comments(comments, path: nil) = application.set_capture_comments(comments, path: path)
+    def overlay = application.overlay
+    def overlay=(enabled)
+      application.overlay = enabled
+    end
+
+    def capture_keys=(keys)
+      application.capture_keys = keys
+    end
+
+    def focus_toggle_keys=(keys)
+      application.focus_toggle_keys = keys
+    end
+    def option(name, value) = application.option(name, value)
+    def option_value(name, type: :uint32) = application.option_value(name, type: type)
+
+    private
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def application
+      @application ||= Application.new(configuration: configuration)
+    end
+  end
+end

data/script/generate_native_api.rb

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: ruby script/generate_native_api.rb path/to/renderdoc_app.h [output]
+#
+# The committed binding was generated from:
+# https://raw.githubusercontent.com/baldurk/renderdoc/v1.25/renderdoc/api/app/renderdoc_app.h
+
+HEADER_PATH = ARGV.fetch(0) do
+  warn "usage: #{$PROGRAM_NAME} path/to/renderdoc_app.h [output]"
+  exit 1
+end
+OUTPUT_PATH = ARGV[1]
+
+TYPE_MAP = {
+  "float" => ":float",
+  "int" => ":int",
+  "uint32_t" => ":uint32",
+  "uint64_t" => ":uint64",
+  "void" => ":void"
+}.freeze
+
+def without_comments(source)
+  source.gsub(%r{/\*.*?\*/}m, "").gsub(%r{//[^\n]*}, "")
+end
+
+def ffi_type(c_type, return_type: false)
+  normalized = c_type.gsub(/\s+/, " ").strip
+  return ":pointer" if normalized.include?("*") && (return_type || !normalized.start_with?("const char"))
+  return ":string" if normalized.start_with?("const char")
+  return ":pointer" if normalized.match?(/RENDERDOC_(DevicePointer|WindowHandle)/)
+  return ":int" if normalized.match?(/RENDERDOC_(CaptureOption|InputButton|Version)/)
+
+  base_type = normalized.sub(/\s+[a-zA-Z_]\w*\z/, "")
+  TYPE_MAP.fetch(base_type) { raise "unsupported C type: #{c_type.inspect}" }
+end
+
+def parse_signatures(header)
+  typedef_pattern = /typedef\s+([^;{}]+?)\(RENDERDOC_CC\s+\*pRENDERDOC_(\w+)\)\s*\((.*?)\)\s*;/m
+
+  without_comments(header).scan(typedef_pattern).to_h do |return_type, name, arguments|
+    argument_types = arguments.strip
+    argument_types = argument_types.split(",").map { |argument| ffi_type(argument) } unless argument_types.empty? || argument_types == "void"
+    argument_types = [] unless argument_types.is_a?(Array)
+    [name, [ffi_type(return_type, return_type: true), argument_types]]
+  end
+end
+
+def parse_table_fields(header)
+  body = header.match(/typedef struct RENDERDOC_API_1_6_0\s*\{(.*?)\}\s*RENDERDOC_API_1_6_0\s*;/m)&.captures&.first
+  raise "RENDERDOC_API_1_6_0 was not found" unless body
+
+  body = without_comments(body).gsub(/union\s*\{(.*?)\}\s*;/m) do
+    Regexp.last_match(1).scan(/(pRENDERDOC_\w+)\s+(\w+)\s*;/).last.join(" ") + ";"
+  end
+  body.scan(/pRENDERDOC_\w+\s+(\w+)\s*;/).flatten
+end
+
+def parse_enum(header, name)
+  body = without_comments(header).match(/typedef enum #{name}\s*\{(.*?)\}\s*#{name}\s*;/m)&.captures&.first
+  raise "#{name} was not found" unless body
+
+  values = {}
+  current_value = -1
+  body.split(",").each do |entry|
+    next if entry.strip.empty?
+
+    constant, expression = entry.strip.split("=", 2).map(&:strip)
+    current_value = if expression
+                      values.fetch(expression) { Integer(expression, 0) }
+                    else
+                      current_value + 1
+                    end
+    values[constant] = current_value
+  end
+  values
+end
+
+def snake_case(name)
+  name.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
+end
+
+def option_name(constant)
+  snake_case(constant.delete_prefix("eRENDERDOC_Option_"))
+    .gsub("v_sync", "vsync")
+    .gsub("apivalidation", "api_validation")
+end
+
+def key_name(constant)
+  name = snake_case(constant.delete_prefix("eRENDERDOC_Key_"))
+  {"page_dn" => "page_down", "prt_scrn" => "print_screen"}.fetch(name, name)
+end
+
+def format_symbol_array(values, indent: 6)
+  padding = " " * indent
+  values.map { |value| "#{padding}#{value}" }.join("\n")
+end
+
+def format_hash(values, key_transform, reject: [])
+  entries = values.filter_map do |constant, value|
+    next if reject.include?(constant)
+
+    "      #{key_transform.call(constant).to_sym.inspect} => #{value}"
+  end
+  entries.join(",\n")
+end
+
+header = File.read(HEADER_PATH)
+fields = parse_table_fields(header)
+signatures = parse_signatures(header)
+missing_signatures = fields.reject { |field| signatures.key?(field) }
+raise "missing signatures: #{missing_signatures.join(', ')}" unless missing_signatures.empty?
+
+options = parse_enum(header, "RENDERDOC_CaptureOption")
+keys = parse_enum(header, "RENDERDOC_InputButton")
+
+function_signatures = fields.map do |field|
+  return_type, argument_types = signatures.fetch(field)
+  arguments = argument_types.empty? ? "[]" : "%i[#{argument_types.map { |type| type.delete_prefix(':') }.join(' ')}]"
+  "      #{field}: [#{return_type}, #{arguments}]"
+end.join(",\n")
+
+generated = <<~RUBY
+  # frozen_string_literal: true
+
+  # Generated from RenderDoc's renderdoc_app.h by script/generate_native_api.rb.
+  # Source: RenderDoc v1.25, RENDERDOC_API_1_6_0. Do not edit by hand.
+  module RenderDoc
+    module Native
+      API_VERSION = 10_600
+
+      API_TABLE_FIELDS = %i[
+  #{format_symbol_array(fields)}
+      ].freeze
+
+      FUNCTION_SIGNATURES = {
+  #{function_signatures}
+      }.freeze
+
+      CAPTURE_OPTIONS = {
+  #{format_hash(options, method(:option_name))}
+      }.freeze
+
+      INPUT_BUTTONS = {
+  #{format_hash(keys, method(:key_name), reject: %w[eRENDERDOC_Key_NonPrintable eRENDERDOC_Key_Max])}
+      }.freeze
+    end
+  end
+RUBY
+
+if OUTPUT_PATH
+  File.write(OUTPUT_PATH, generated)
+else
+  puts generated
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: renderdoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+description: Programmatically capture and inspect GPU frames from Ruby applications
+  with RenderDoc.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/renderdoc.rb
+- lib/renderdoc/application.rb
+- lib/renderdoc/capture.rb
+- lib/renderdoc/configuration.rb
+- lib/renderdoc/errors.rb
+- lib/renderdoc/frame_trigger.rb
+- lib/renderdoc/native.rb
+- lib/renderdoc/native/generated.rb
+- lib/renderdoc/rspec.rb
+- lib/renderdoc/rspec_integration.rb
+- lib/renderdoc/settings.rb
+- lib/renderdoc/version.rb
+- script/generate_native_api.rb
+homepage: https://github.com/ydah/renderdoc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/renderdoc
+  source_code_uri: https://github.com/ydah/renderdoc/tree/main
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby bindings for RenderDoc's in-application API
+test_files: []