From cca5d8a2fb2eaed2929aff2ba982170d8557e1d5 Mon Sep 17 00:00:00 2001 From: i509VCB Date: Sun, 1 Jan 2023 15:19:36 -0600 Subject: [PATCH 1/2] Rework documentation for `GraphicsContext::set_buffer` This includes a more clear description of the pixel format expected. --- src/lib.rs | 55 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 16 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 6e424a3..8f297a5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -236,28 +236,49 @@ impl Surface { } /// Shows the given buffer with the given width and height on the window corresponding to this - /// graphics context. Panics if buffer.len() ≠ width*height. If the size of the buffer does - /// not match the size of the window, the buffer is drawn in the upper-left corner of the window. + /// surface. + /// /// It is recommended in most production use cases to have the buffer fill the entire window. - /// Use your windowing library to find the size of the window. + /// Use your windowing library to determine the size of the window. + /// + /// # Panics + /// + /// - If `buffer.len() ≠ width * height` /// - /// The format of the buffer is as follows. There is one u32 in the buffer for each pixel in - /// the area to draw. The first entry is the upper-left most pixel. The second is one to the right - /// etc. (Row-major top to bottom left to right one u32 per pixel). Within each u32 the highest - /// order 8 bits are to be set to 0. The next highest order 8 bits are the red channel, then the - /// green channel, and then the blue channel in the lowest-order 8 bits. See the examples for - /// one way to build this format using bitwise operations. + /// # Pixel format /// - /// -------- + /// The buffer layout is in a row-major layout. This means that index `0` is at the top-left corner of the + /// window and as the index increases, the position on the x axis grows to the right. When the number of + /// entries for the row is equal to the width of the surface, then the next row is started. /// - /// Pixel format (u32): + /// Each pixel is represented in memory as a [`u32`]. Starting with the most significant byte (MSB) + /// going to the least significant byte (LSB), the byte is ignored but best set to `0`. Then there is + /// a byte for the red, green and blue channel. /// - /// 00000000RRRRRRRRGGGGGGGGBBBBBBBB + /// ```text + /// XXXXXXXXRRRRRRRRGGGGGGGGBBBBBBBB + /// ^ ^ + /// MSB LSB + /// ``` /// - /// 0: Bit is 0 - /// R: Red channel - /// G: Green channel - /// B: Blue channel + /// | Bit | Channel | + /// |------|---------------------| + /// | X | Ignored[^x-channel] | + /// | R | Red channel | + /// | G | Green channel | + /// | B | Blue channel | + /// + /// The function shown below may be used to create a color from a 24-bit RGB color using bitwise\ + /// operations: + /// + /// ``` + /// fn pixel(red: u8, green: u8, blue: u8) -> u32 { + /// let color = blue as u32 + /// | ((green as u32) << 8) + /// | ((red as u32) << 16); + /// color + /// } + /// ``` /// /// # Platform dependent behavior /// @@ -272,6 +293,8 @@ impl Surface { /// /// If the caller wishes to synchronize other surface/window changes, such requests must be sent to the /// Wayland compositor before calling this function. + /// + /// [^x-channel]: On some backends setting these bits to anything other than `0` may cause weird behavior. #[inline] pub fn set_buffer(&mut self, buffer: &[u32], width: u16, height: u16) { if (width as usize) * (height as usize) != buffer.len() { From 8e85b8d6b4bfd2f094c259d0938913a9a2abc9cd Mon Sep 17 00:00:00 2001 From: i509VCB Date: Mon, 13 Mar 2023 22:29:12 -0500 Subject: [PATCH 2/2] Require Rust 1.64 raw-window-handle 0.5.1 requires 1.64, so we have no real choice here. --- .github/workflows/ci.yml | 2 +- Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 54c0137..e425b02 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,7 +22,7 @@ jobs: strategy: fail-fast: false matrix: - rust_version: ['1.60.0', stable, nightly] + rust_version: ['1.64.0', stable, nightly] platform: - { target: x86_64-pc-windows-msvc, os: windows-latest, } - { target: i686-pc-windows-msvc, os: windows-latest, } diff --git a/Cargo.toml b/Cargo.toml index 60be900..4479781 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ repository = "https://github.com/rust-windowing/softbuffer" keywords = ["framebuffer", "windowing"] categories = ["game-development", "graphics", "gui", "multimedia", "rendering"] exclude = ["examples"] -rust-version = "1.60.0" +rust-version = "1.64.0" [features] default = ["x11", "wayland", "wayland-dlopen"]