Prepare release 0.11.0 (#145)

* Simplify renderdoc-sys/generated_bindings.sh * Regenerate renderdoc-sys/src/bindings.rs with bindgen 0.64.0 * Bump renderdoc-sys crate version to 1.0.0 It's high time for this crate to commit to a 1.x semantic versioning range. The likelihood this API will continue to churn is very low, and if it ever does, compatibility guarantees should be conveyed explicitly using the crate version number. * Improve renderdoc-sys documentation * Remove unused bindgen flags from generate_bindings.sh * Remove renderdoc-sys from workspace default members * Improve renderdoc crate documentation * Gracefully handle RenderDoc absence in triangle.rs example According to the upstream RenderDoc documentation, applications should not panic if RenderDoc isn't loaded. Instead, they should handle its absence gracefully and continue running. The `triangle.rs` example should demonstrate this usage clearly. We should update the `README.md` accordingly too, but considering a total rewrite of this library is coming very soon, it probably isn't worth investing too much time into that. * Bump renderdoc crate version to 0.11.0 * Update CHANGELOG.md * Update copyright year in license file
ebkalderon · Feb 21, 2023 · b75f7ea · b75f7ea
1 parent 18307f9
commit b75f7ea
Show file tree

Hide file tree

Showing 11 changed files with 112 additions and 54 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [0.11.0] - 2023-02-20
+
+### Changed
+
+* Update `renderdoc-sys` dependency to 1.0.0.
+* Update `float-cmp` dependency to 0.9.
+* Update optional `glutin` dependency to 0.30.
+* Update optional `winit` dependency to 0.28.
+* Improve crate-level documentation.
+
+### Fixed
+
+* Fix loading strategy of `renderdoc` library (PR #140).
+* Fix typo in `start_frame_capture` and `end_frame_capture` docs (PR #122).
+* Fix undefined behavior and crash in `get_capture` (PR #143).
+
 ## [0.10.1] - 2021-02-10
 
 ### Changed
@@ -211,7 +227,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 * Type-safe version requests and downgrading.
 * Convenient conversions for `winit::VirtualKeyCode` into RenderDoc `InputButton`.
 
-[Unreleased]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.10.1...HEAD
+[Unreleased]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.10.1...v0.11.0
 [0.10.1]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/ebkalderon/renderdoc-rs/compare/v0.9.0...v0.9.1

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "renderdoc"
-version = "0.10.1"
+version = "0.11.0"
 edition = "2018"
 resolver = "2"
 authors = ["Eyal Kalderon <ebkalderon@gmail.com>"]
@@ -10,14 +10,14 @@ homepage = "https://github.com/ebkalderon/renderdoc-rs"
 repository = "https://github.com/ebkalderon/renderdoc-rs"
 documentation = "https://docs.rs/renderdoc/"
 readme = "README.md"
-categories = ["rendering"]
-keywords = ["graphics", "profile", "renderdoc", "trace"]
+keywords = ["graphics", "profiling", "renderdoc", "tracing"]
+categories = ["development-tools::debugging", "rendering"]
 
 [package.metadata.docs.rs]
 all-features = true
 
 [badges]
-circle-ci = { repository = "ebkalderon/renderdoc-rs" }
+maintenance = { status = "actively-developed" }
 
 [features]
 default = []
@@ -30,7 +30,7 @@ bitflags = "1.0"
 float-cmp = "0.9"
 libloading = "0.7"
 once_cell = "1.0"
-renderdoc-sys = { version = "0.7", path = "./renderdoc-sys" }
+renderdoc-sys = { version = "1.0.0", path = "./renderdoc-sys" }
 
 glutin = { version = "0.30", optional = true }
 winit = { version = "0.28", optional = true }
@@ -47,4 +47,3 @@ winit = "0.28"
 
 [workspace]
 members = [".", "renderdoc-sys"]
-default-members = [".", "renderdoc-sys"]
diff --git a/LICENSE-MIT b/LICENSE-MIT
@@ -1,4 +1,4 @@
-Copyright (c) 2022 Eyal Kalderon
+Copyright (c) 2023 Eyal Kalderon
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

diff --git a/README.md b/README.md
@@ -4,8 +4,8 @@
 [![Crates.io][crate-badge]][crate-url]
 [![Documentation][docs-badge]][docs-url]
 
-[build-badge]: https://circleci.com/gh/ebkalderon/renderdoc-rs.svg?style=shield
-[build-url]: https://circleci.com/gh/ebkalderon/renderdoc-rs
+[build-badge]: https://github.com/ebkalderon/renderdoc-rs/actions/workflows/ci.yml/badge.svg
+[build-url]: https://github.com/ebkalderon/renderdoc-rs/actions
 [crate-badge]: https://img.shields.io/crates/v/renderdoc.svg
 [crate-url]: https://crates.io/crates/renderdoc
 [docs-badge]: https://docs.rs/renderdoc/badge.svg
@@ -15,10 +15,15 @@ Rust bindings to [RenderDoc], a popular graphics debugger.
 
 [RenderDoc]: https://renderdoc.org/
 
-RenderDoc is a free and open source graphics debugging tool. RenderDoc allows
-game developers to take frame captures of their applications, replay them,
-examine the graphics pipeline state, and potentially identify nasty graphics
-bugs.
+RenderDoc is a free and open source debugger for real-time graphics providing
+quick and easy frame captures and detailed introspection of any application
+using [Vulkan], [Direct3D 11], [Direct3D 12], [OpenGL], and [OpenGL ES].
+
+[Vulkan]: https://www.vulkan.org/
+[Direct3D 11]: https://learn.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11
+[Direct3D 12]: https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics
+[OpenGL]: https://www.khronos.org/opengl/
+[OpenGL ES]: https://www.khronos.org/opengles/
 
 These bindings require that RenderDoc be installed on the target machine, with
 either `renderdoc.dll` or `librenderdoc.so` visible from your `$PATH`.

diff --git a/examples/triangle.rs b/examples/triangle.rs
@@ -38,9 +38,12 @@ async fn run(event_loop: EventLoop<()>, window: Window) {
         .await
         .expect("Failed to create device");
 
-    let mut rd: RenderDoc<V110> = RenderDoc::new().expect("RenderDoc is not running");
-    rd.set_focus_toggle_keys(&[InputButton::F]);
-    rd.set_capture_keys(&[InputButton::C]);
+    let mut renderdoc: Result<RenderDoc<V110>, _> = RenderDoc::new();
+
+    if let Ok(rd) = renderdoc.as_mut() {
+        rd.set_focus_toggle_keys(&[InputButton::F]);
+        rd.set_capture_keys(&[InputButton::C]);
+    }
 
     // Load the shaders from disk
     let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
@@ -119,9 +122,9 @@ async fn run(event_loop: EventLoop<()>, window: Window) {
                         ..
                     },
                 ..
-            } => match keycode {
-                VirtualKeyCode::C => rd.trigger_capture(),
-                VirtualKeyCode::R => match rd.launch_replay_ui(true, None) {
+            } => match (keycode, renderdoc.as_mut()) {
+                (VirtualKeyCode::C, Ok(rd)) => rd.trigger_capture(),
+                (VirtualKeyCode::R, Ok(rd)) => match rd.launch_replay_ui(true, None) {
                     Ok(pid) => println!("Launched replay UI (PID {pid})"),
                     Err(e) => eprintln!("Failed to launch replay UI: {e}"),
                 },

diff --git a/renderdoc-sys/Cargo.toml b/renderdoc-sys/Cargo.toml
@@ -1,17 +1,17 @@
 [package]
 name = "renderdoc-sys"
-version = "0.7.1"
+version = "1.0.0"
 authors = ["Eyal Kalderon <ebkalderon@gmail.com>"]
-description = "Raw FFI bindings to the RenderDoc API"
+description = "Low-level bindings to the RenderDoc API"
 license = "MIT OR Apache-2.0"
 homepage = "https://github.com/ebkalderon/renderdoc-rs/tree/master/renderdoc-sys"
 repository = "https://github.com/ebkalderon/renderdoc-rs"
-documentation = "https://docs.rs/renderdoc-sys/"
+documentation = "https://docs.rs/renderdoc-sys"
 readme = "README.md"
-keywords = ["ffi", "renderdoc"]
-exclude = ["/vendor"]
+keywords = ["ffi", "graphics", "profiling", "renderdoc", "tracing"]
+categories = ["development-tools::debugging", "external-ffi-bindings", "rendering"]
 
 [badges]
-circle-ci = { repository = "ebkalderon/renderdoc-rs" }
+maintenance = { status = "passively-maintained" }
 
 [dependencies]
diff --git a/renderdoc-sys/README.md b/renderdoc-sys/README.md
@@ -4,26 +4,44 @@
 [![Crates.io][crate-badge]][crate-url]
 [![Documentation][docs-badge]][docs-url]
 
-[build-badge]: https://circleci.com/gh/ebkalderon/renderdoc-rs.svg?style=shield
-[build-url]: https://circleci.com/gh/ebkalderon/renderdoc-rs/tree/master/renderdoc-sys
+[build-badge]: https://github.com/ebkalderon/renderdoc-rs/actions/workflows/ci.yml/badge.svg
+[build-url]: https://github.com/ebkalderon/renderdoc-rs/actions
 [crate-badge]: https://img.shields.io/crates/v/renderdoc-sys.svg
 [crate-url]: https://crates.io/crates/renderdoc-sys
 [docs-badge]: https://docs.rs/renderdoc-sys/badge.svg
 [docs-url]: https://docs.rs/renderdoc-sys
 
-Low-level Rust FFI bindings to [RenderDoc], a popular graphics debugger.
+Low-level bindings to the [RenderDoc] in-application API.
 
 [RenderDoc]: https://renderdoc.org/
 
-RenderDoc is a free and open source graphics debugging tool. RenderDoc allows
-game developers to take frame captures of their applications, replay them,
-examine the graphics pipeline state, and potentially identify nasty graphics
-bugs.
+RenderDoc is a free and open source debugger for real-time graphics that allows
+quick and easy frame captures and detailed introspection of any application
+using [Vulkan], [Direct3D 11], [Direct3D 12], [OpenGL], and [OpenGL ES].
 
-These raw bindings are generated directly from the [renderdoc_app.h][header]
-file provided upstream. This crate does not provide nor dynamically link to the
-required `renderdoc.dll` or `librenderdoc.so` library itself; it only provides
-the FFI objects for the [in-application RenderDoc API][api].
+[Vulkan]: https://www.vulkan.org/
+[Direct3D 11]: https://learn.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11
+[Direct3D 12]: https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics
+[OpenGL]: https://www.khronos.org/opengl/
+[OpenGL ES]: https://www.khronos.org/opengles/
 
-[header]: https://github.com/baldurk/renderdoc/blob/v1.x/renderdoc/api/app/renderdoc_app.h
+These bindings are automatically generated from [`renderdoc_app.h`] with
+[`bindgen`]. This crate does not provide nor link to `renderdoc.dll` nor
+`librenderdoc.so` by itself; it only contains the FFI symbols. Refer to the
+upstream [In-Application API][api] documentation for correct usage details.
+
+[`renderdoc_app.h`]: https://github.com/baldurk/renderdoc/blob/v1.x/renderdoc/api/app/renderdoc_app.h
+[bindgen]: https://github.com/rust-lang/rust-bindgen
 [api]: https://renderdoc.org/docs/in_application_api.html
+
+For a safe wrapper, see the [`renderdoc`](https://docs.rs/renderdoc) crate.
+
+## License
+
+`renderdoc-sys` is free and open source software distributed under the terms of
+either the [MIT](LICENSE-MIT) or the [Apache 2.0](LICENSE-APACHE) license, at
+your option.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
diff --git a/renderdoc-sys/generate_bindings.sh b/renderdoc-sys/generate_bindings.sh
@@ -3,29 +3,22 @@
 # This script generates Rust bindings to the in-application Renderdoc API.
 #
 # Dependencies:
-# * bindgen
+# * bindgen (>=0.63.0)
 # * curl
 
 set -euo pipefail
 
 readonly VERSION=v1.x
-readonly BASE_DIR="$(cd "$(dirname "$0")" && pwd)"
 readonly TEMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/renderdoc-rs.XXXXXXXXX")"
 
 trap -- "rm -rf '${TEMP_DIR}'" EXIT
 
-cd "${TEMP_DIR}" || exit 1
-
-curl -LO "https://raw.githubusercontent.com/baldurk/renderdoc/${VERSION}/renderdoc/api/app/renderdoc_app.h"
+curl -o "${TEMP_DIR}/renderdoc_app.h" -L "https://raw.githubusercontent.com/baldurk/renderdoc/${VERSION}/renderdoc/api/app/renderdoc_app.h"
 
 bindgen \
   --blocklist-type '__uint64_t|__uint32_t' \
   --allowlist-type 'RENDERDOC.*|pRENDERDOC.*' \
   --generate-inline-functions \
   --no-prepend-enum-name \
   --impl-debug \
-  --impl-partialeq \
-  --with-derive-partialeq \
-  --with-derive-eq \
-  --with-derive-hash \
-  "${TEMP_DIR}/renderdoc_app.h" > "${BASE_DIR}/../src/bindings.rs"
+  "${TEMP_DIR}/renderdoc_app.h" > ./src/bindings.rs
diff --git a/renderdoc-sys/src/bindings.rs b/renderdoc-sys/src/bindings.rs
@@ -1,4 +1,4 @@
-/* automatically generated by rust-bindgen 0.63.0 */
+/* automatically generated by rust-bindgen 0.64.0 */
 
 pub const eRENDERDOC_Option_AllowVSync: RENDERDOC_CaptureOption = 0;
 pub const eRENDERDOC_Option_AllowFullscreen: RENDERDOC_CaptureOption = 1;

diff --git a/renderdoc-sys/src/lib.rs b/renderdoc-sys/src/lib.rs
@@ -1,8 +1,25 @@
-//! Raw FFI bindings to the RenderDoc API.
+//! Low-level bindings to the [RenderDoc](https://renderdoc.org/) in-application API.
 //!
-//! Refer to the [In-Application API][api] documentation for more details.
+//! RenderDoc is a free and open source debugger for real-time graphics providing quick and easy
+//! frame captures and detailed introspection of any application using [Vulkan], [Direct3D 11],
+//! [Direct3D 12], [OpenGL], and [OpenGL ES].
 //!
+//! [Vulkan]: https://www.vulkan.org/
+//! [Direct3D 11]: https://learn.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11
+//! [Direct3D 12]: https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics
+//! [OpenGL]: https://www.khronos.org/opengl/
+//! [OpenGL ES]: https://www.khronos.org/opengles/
+//!
+//! These bindings are automatically generated from [`renderdoc_app.h`] with [`bindgen`]. This
+//! crate does not provide nor link to the `renderdoc.dll` or `librenderdoc.so` libraries on its
+//! own; it only contains FFI symbols. Refer to the official [In-Application API][api]
+//! documentation for correct usage.
+//!
+//! [`renderdoc_app.h`]: https://github.com/baldurk/renderdoc/blob/v1.x/renderdoc/api/app/renderdoc_app.h
+//! [`bindgen`]: https://github.com/rust-lang/rust-bindgen
 //! [api]: https://renderdoc.org/docs/in_application_api.html
+//!
+//! For a safe wrapper, see the [`renderdoc`](https://docs.rs/renderdoc) crate.
 
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]

diff --git a/src/lib.rs b/src/lib.rs
@@ -2,9 +2,15 @@
 //!
 //! [RenderDoc]: https://renderdoc.org/
 //!
-//! RenderDoc is a free and open source graphics debugging tool. RenderDoc allows game developers
-//! to take frame captures of their applications, replay them, examine the graphics pipeline state,
-//! and potentially identify nasty graphics bugs.
+//! RenderDoc is a free and open source debugger for real-time graphics providing quick and easy
+//! frame captures and detailed introspection of any application using [Vulkan], [Direct3D 11],
+//! [Direct3D 12], [OpenGL], and [OpenGL ES].
+//!
+//! [Vulkan]: https://www.vulkan.org/
+//! [Direct3D 11]: https://learn.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11
+//! [Direct3D 12]: https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics
+//! [OpenGL]: https://www.khronos.org/opengl/
+//! [OpenGL ES]: https://www.khronos.org/opengles/
 //!
 //! These bindings require that RenderDoc be installed on the target machine, with either
 //! `renderdoc.dll` or `librenderdoc.so` visible from your `$PATH`.