From 4c6d91d1e5b0618eabf8e200f1359cf98f8593bf Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Tue, 13 Apr 2021 23:53:05 +0200 Subject: [PATCH] Use intra-doc links, capitalize `GBM` wording And some more fixes: - Don't use `no_run` in markdown, this only works in rustdoc; - Replace `gbm_bo_write`/`gbm_bo_get_fd` with intra-doc link to its Rust counterpart; - Consistently use two spaces after a period; - Fix a tiny typo in `optain`. --- README.md | 4 ++-- src/buffer_object.rs | 36 ++++++++++++++-------------- src/device.rs | 56 ++++++++++++++++++++++---------------------- src/lib.rs | 4 ++-- src/surface.rs | 15 ++++++------ 5 files changed, 58 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index d13ea38..5122323 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Add to your Cargo.toml ## Example -```rust,no_run +```rust extern crate drm; extern crate gbm; @@ -29,7 +29,7 @@ use gbm::{Device, Format, BufferObjectFlags}; // ... init your drm device ... let drm = init_drm_device(); -// init a gbm device +// init a GBM device let gbm = Device::new(drm).unwrap(); // create a buffer diff --git a/src/buffer_object.rs b/src/buffer_object.rs index 3ce418d..1448a43 100644 --- a/src/buffer_object.rs +++ b/src/buffer_object.rs @@ -12,7 +12,7 @@ use std::os::unix::io::{AsRawFd, RawFd}; use std::ptr; use std::slice; -/// A gbm buffer object +/// A GBM buffer object pub struct BufferObject { pub(crate) ffi: Ptr, pub(crate) _device: WeakPtr<::ffi::gbm_device>, @@ -23,9 +23,9 @@ unsafe impl Send for Ptr<::ffi::gbm_bo> {} bitflags! { /// Flags to indicate the intended use for the buffer - these are passed into - /// `Device::create_buffer_object`. + /// [`Device::create_buffer_object()`]. /// - /// Use `Device::is_format_supported` to check if the combination of format + /// Use [`Device::is_format_supported()`] to check if the combination of format /// and use flags are supported pub struct BufferObjectFlags: u32 { /// Buffer is going to be presented to the screen using an API such as KMS @@ -38,8 +38,8 @@ bitflags! { /// Buffer is to be used for rendering - for example it is going to be used /// as the storage for a color buffer const RENDERING = ::ffi::gbm_bo_flags::GBM_BO_USE_RENDERING as u32; - /// Buffer can be used for gbm_bo_write. This is guaranteed to work - /// with `BufferObjectFlags::Cursor`, but may not work for other combinations. + /// Buffer can be used for [`BufferObject::write()`]. This is guaranteed to work + /// with [`Self::CURSOR`], but may not work for other combinations. const WRITE = ::ffi::gbm_bo_flags::GBM_BO_USE_WRITE as u32; /// Buffer is linear, i.e. not tiled. const LINEAR = ::ffi::gbm_bo_flags::GBM_BO_USE_LINEAR as u32; @@ -195,7 +195,7 @@ impl BufferObject { Err(DeviceDestroyedError) } } - + /// Get the bits per pixel of the buffer object pub fn bpp(&self) -> Result { let device = self._device.upgrade(); @@ -205,7 +205,7 @@ impl BufferObject { Err(DeviceDestroyedError) } } - + /// Get the offset for a plane of the buffer object pub fn offset(&self, plane: i32) -> Result { let device = self._device.upgrade(); @@ -215,7 +215,7 @@ impl BufferObject { Err(DeviceDestroyedError) } } - + /// Get the plane count of the buffer object pub fn plane_count(&self) -> Result { let device = self._device.upgrade(); @@ -225,7 +225,7 @@ impl BufferObject { Err(DeviceDestroyedError) } } - + /// Get the modifier of the buffer object pub fn modifier(&self) -> Result { let device = self._device.upgrade(); @@ -239,7 +239,7 @@ impl BufferObject { /// Get a DMA-BUF file descriptor for the buffer object /// /// This function creates a DMA-BUF (also known as PRIME) file descriptor - /// handle for the buffer object. Each call to gbm_bo_get_fd() returns a new + /// handle for the buffer object. Each call to [`Self::fd()`] returns a new /// file descriptor and the caller is responsible for closing the file /// descriptor. pub fn fd(&self) -> Result { @@ -253,7 +253,7 @@ impl BufferObject { /// Get the handle of the buffer object /// - /// This is stored in the platform generic union `BufferObjectHandle` type. However + /// This is stored in the platform generic union [`BufferObjectHandle`] type. However /// the format of this handle is platform specific. pub fn handle(&self) -> Result { let device = self._device.upgrade(); @@ -266,7 +266,7 @@ impl BufferObject { /// Get the handle of a plane of the buffer object /// - /// This is stored in the platform generic union `BufferObjectHandle` type. However + /// This is stored in the platform generic union [`BufferObjectHandle`] type. However /// the format of this handle is platform specific. pub fn handle_for_plane(&self, plane: i32) -> Result { let device = self._device.upgrade(); @@ -277,9 +277,9 @@ impl BufferObject { } } - /// Map a region of a gbm buffer object for cpu access + /// Map a region of a GBM buffer object for cpu access /// - /// This function maps a region of a gbm bo for cpu read access. + /// This function maps a region of a GBM bo for cpu read access. pub fn map<'a, D, F, S>(&'a self, device: &Device, x: u32, y: u32, width: u32, height: u32, f: F) -> Result, WrongDeviceError> where D: AsRawFd + 'static, @@ -328,9 +328,9 @@ impl BufferObject { } } - /// Map a region of a gbm buffer object for cpu access + /// Map a region of a GBM buffer object for cpu access /// - /// This function maps a region of a gbm bo for cpu read/write access. + /// This function maps a region of a GBM bo for cpu read/write access. pub fn map_mut<'a, D, F, S>( &'a mut self, device: &Device, @@ -389,7 +389,7 @@ impl BufferObject { /// Write data into the buffer object /// - /// If the buffer object was created with the `BufferObjectFlags::Write` flag, + /// If the buffer object was created with the [`BufferObjectFlags::WRITE`] flag, /// this function can be used to write data into the buffer object. The /// data is copied directly into the object and it's the responsibility /// of the caller to make sure the data represents valid pixel data, @@ -573,7 +573,7 @@ impl DrmPlanarBuffer for BufferObject { } #[derive(Debug, Clone, Copy, PartialEq, Eq)] -/// Thrown when the gbm device does not belong to the buffer object +/// Thrown when the GBM device does not belong to the buffer object pub struct WrongDeviceError; impl fmt::Display for WrongDeviceError { diff --git a/src/device.rs b/src/device.rs index 4ff455e..3f85393 100644 --- a/src/device.rs +++ b/src/device.rs @@ -67,10 +67,10 @@ impl Device { /// Open a GBM device from a given unix file descriptor. /// /// The file descriptor passed in is used by the backend to communicate with - /// platform for allocating the memory. For allocations using DRI this would be - /// the file descriptor returned when opening a device such as /dev/dri/card0. + /// platform for allocating the memory. For allocations using DRI this would be + /// the file descriptor returned when opening a device such as `/dev/dri/card0`. /// - /// # Unsafety + /// # Safety /// /// The lifetime of the resulting device depends on the ownership of the file descriptor. /// Closing the file descriptor before dropping the Device will lead to undefined behavior. @@ -92,15 +92,15 @@ impl Device { /// Open a GBM device from a given open DRM device. /// /// The underlying file descriptor passed in is used by the backend to communicate with - /// platform for allocating the memory. For allocations using DRI this would be - /// the file descriptor returned when opening a device such as /dev/dri/card0. + /// platform for allocating the memory. For allocations using DRI this would be + /// the file descriptor returned when opening a device such as `/dev/dri/card0`. pub fn new(fd: T) -> IoResult> { let ptr = unsafe { ::ffi::gbm_create_device(fd.as_raw_fd()) }; if ptr.is_null() { Err(IoError::last_os_error()) } else { Ok(Device { - fd: fd, + fd, ffi: Ptr::<::ffi::gbm_device>::new(ptr, |ptr| unsafe { ::ffi::gbm_device_destroy(ptr) }), }) } @@ -199,7 +199,7 @@ impl Device { Ok(unsafe { BufferObject::new(ptr, self.ffi.downgrade()) }) } } - + /// Allocate a buffer object for the given dimensions with explicit modifiers pub fn create_buffer_object_with_modifiers( &self, @@ -226,13 +226,13 @@ impl Device { } } - /// Create a gbm buffer object from a wayland buffer + /// Create a GBM buffer object from a wayland buffer /// - /// This function imports a foreign `WlBuffer` object and creates a new gbm + /// This function imports a foreign [`WlBuffer`] object and creates a new GBM /// buffer object for it. - /// This enabled using the foreign object with a display API such as KMS. + /// This enables using the foreign object with a display API such as KMS. /// - /// The gbm bo shares the underlying pixels but its life-time is + /// The GBM bo shares the underlying pixels but its life-time is /// independent of the foreign object. #[cfg(feature = "import-wayland")] pub fn import_buffer_object_from_wayland( @@ -255,18 +255,18 @@ impl Device { } } - /// Create a gbm buffer object from an egl buffer + /// Create a GBM buffer object from an egl buffer /// - /// This function imports a foreign `EGLImage` object and creates a new gbm + /// This function imports a foreign [`EGLImage`] object and creates a new GBM /// buffer object for it. - /// This enabled using the foreign object with a display API such as KMS. + /// This enables using the foreign object with a display API such as KMS. /// - /// The gbm bo shares the underlying pixels but its life-time is + /// The GBM bo shares the underlying pixels but its life-time is /// independent of the foreign object. /// - /// ## Unsafety + /// # Safety /// - /// The given EGLImage is a raw pointer. Passing null or an invalid EGLImage will + /// The given [`EGLImage`] is a raw pointer. Passing null or an invalid [`EGLImage`] will /// cause undefined behavior. #[cfg(feature = "import-egl")] pub unsafe fn import_buffer_object_from_egl( @@ -288,13 +288,13 @@ impl Device { } } - /// Create a gbm buffer object from an dma buffer + /// Create a GBM buffer object from a dma buffer /// /// This function imports a foreign dma buffer from an open file descriptor - /// and creates a new gbm buffer object for it. - /// This enabled using the foreign object with a display API such as KMS. + /// and creates a new GBM buffer object for it. + /// This enables using the foreign object with a display API such as KMS. /// - /// The gbm bo shares the underlying pixels but its life-time is + /// The GBM bo shares the underlying pixels but its life-time is /// independent of the foreign object. pub fn import_buffer_object_from_dma_buf( &self, @@ -327,14 +327,14 @@ impl Device { Ok(unsafe { BufferObject::new(ptr, self.ffi.downgrade()) }) } } - - /// Create a gbm buffer object from an dma buffer with explicit modifiers + + /// Create a GBM buffer object from a dma buffer with explicit modifiers /// /// This function imports a foreign dma buffer from an open file descriptor - /// and creates a new gbm buffer object for it. - /// This enabled using the foreign object with a display API such as KMS. + /// and creates a new GBM buffer object for it. + /// This enables using the foreign object with a display API such as KMS. /// - /// The gbm bo shares the underlying pixels but its life-time is + /// The GBM bo shares the underlying pixels but its life-time is /// independent of the foreign object. pub fn import_buffer_object_from_dma_buf_with_modifiers( &self, @@ -382,12 +382,12 @@ impl DrmDevice for Device {} impl DrmControlDevice for Device {} #[derive(Debug, Clone, Copy, PartialEq, Eq)] -/// Thrown when the underlying gbm device was already destroyed +/// Thrown when the underlying GBM device was already destroyed pub struct DeviceDestroyedError; impl fmt::Display for DeviceDestroyedError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - write!(f, "The underlying gbm device was already destroyed") + write!(f, "The underlying GBM device was already destroyed") } } diff --git a/src/lib.rs b/src/lib.rs index d53cccc..e5213d1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -47,7 +47,7 @@ //! // ... init your drm device ... //! let drm = init_drm_device(); //! -//! // init a gbm device +//! // init a GBM device //! let gbm = Device::new(drm).unwrap(); //! //! // create a 4x4 buffer @@ -110,7 +110,7 @@ pub use self::surface::*; use std::sync::{Arc, Weak}; -/// Trait for types that allow to optain the underlying raw libinput pointer. +/// Trait for types that allow to obtain the underlying raw libinput pointer. pub trait AsRaw { /// Receive a raw pointer representing this type. fn as_raw(&self) -> *const T; diff --git a/src/surface.rs b/src/surface.rs index 75802ab..d30a72d 100644 --- a/src/surface.rs +++ b/src/surface.rs @@ -3,7 +3,7 @@ use std::error; use std::fmt; use std::marker::PhantomData; -/// A gbm rendering surface +/// A GBM rendering surface pub struct Surface { ffi: Ptr<::ffi::gbm_surface>, _device: WeakPtr<::ffi::gbm_device>, @@ -46,9 +46,9 @@ impl Surface { /// Return whether or not a surface has free (non-locked) buffers /// /// Before starting a new frame, the surface must have a buffer - /// available for rendering. Initially, a gbm surface will have a free + /// available for rendering. Initially, a GBM surface will have a free /// buffer, but after one or more buffers - /// [have been locked](#method.lock_front_buffer), + /// [have been locked](Self::lock_front_buffer()), /// the application must check for a free buffer before rendering. pub fn has_free_buffers(&self) -> bool { let device = self._device.upgrade(); @@ -62,12 +62,13 @@ impl Surface { /// Lock the surface's current front buffer /// /// Locks rendering to the surface's current front buffer and returns - /// a handle to the underlying `BufferObject` + /// a handle to the underlying [`BufferObject`]. /// - /// If an error occurs a `FrontBufferError` is returned. + /// If an error occurs a [`FrontBufferError`] is returned. /// - /// **Unsafety**: This function must be called exactly once after calling - /// `eglSwapBuffers`. Calling it before any `eglSwapBuffer` has happened + /// # Safety + /// This function must be called exactly once after calling + /// `eglSwapBuffers`. Calling it before any `eglSwapBuffers` has happened /// on the surface or two or more times after `eglSwapBuffers` is an /// error and may cause undefined behavior. pub unsafe fn lock_front_buffer(&self) -> Result, FrontBufferError> {