Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Rework documentation for Surface::set_buffer #57

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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, }
Expand Down
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
55 changes: 39 additions & 16 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
i509VCB marked this conversation as resolved.
Show resolved Hide resolved
/// 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 {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent addition to have this pre-made example function. I'm not sure if this is the right place for it. Perhaps it should be in an example instead, or just callable as a pub fn in softbuffer. I think that this is ultimately the best place for it, but I'm not certain so I wanted to call attention to this choice.

Copy link
Contributor Author

@i509VCB i509VCB Mar 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The utility of this function being publicly accessible is probably quite low as it is extremely generic. Plus this may change eventually if other pixel formats are supported.

/// let color = blue as u32
/// | ((green as u32) << 8)
/// | ((red as u32) << 16);
/// color
/// }
/// ```
///
/// # Platform dependent behavior
///
Expand All @@ -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() {
Expand Down