Skip to content

Commit

Permalink
Merge pull request #7 from MarijnS95/docs
Browse files Browse the repository at this point in the history 
Use intra-doc links, capitalize `GBM` wording
  • Loading branch information
@Drakulix
Drakulix authored May 1, 2021
2 parents 6c0fdb0 + 4c6d91d commit a8b07ae
Show file tree
Hide file tree
Showing 5 changed files with 58 additions and 57 deletions.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Add to your Cargo.toml

## Example

```rust,no_run
```rust
extern crate drm;
extern crate gbm;

Expand All @@ -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
Expand Down
36 changes: 18 additions & 18 deletions src/buffer_object.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<T: 'static> {
pub(crate) ffi: Ptr<ffi::gbm_bo>,
pub(crate) _device: WeakPtr<::ffi::gbm_device>,
Expand All @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -195,7 +195,7 @@ impl<T: 'static> BufferObject<T> {
Err(DeviceDestroyedError)
}
}

/// Get the bits per pixel of the buffer object
pub fn bpp(&self) -> Result<u32, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -205,7 +205,7 @@ impl<T: 'static> BufferObject<T> {
Err(DeviceDestroyedError)
}
}

/// Get the offset for a plane of the buffer object
pub fn offset(&self, plane: i32) -> Result<u32, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -215,7 +215,7 @@ impl<T: 'static> BufferObject<T> {
Err(DeviceDestroyedError)
}
}

/// Get the plane count of the buffer object
pub fn plane_count(&self) -> Result<u32, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -225,7 +225,7 @@ impl<T: 'static> BufferObject<T> {
Err(DeviceDestroyedError)
}
}

/// Get the modifier of the buffer object
pub fn modifier(&self) -> Result<Modifier, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -239,7 +239,7 @@ impl<T: 'static> BufferObject<T> {
/// 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<RawFd, DeviceDestroyedError> {
Expand All @@ -253,7 +253,7 @@ impl<T: 'static> BufferObject<T> {

/// 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<BufferObjectHandle, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -266,7 +266,7 @@ impl<T: 'static> BufferObject<T> {

/// 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<BufferObjectHandle, DeviceDestroyedError> {
let device = self._device.upgrade();
Expand All @@ -277,9 +277,9 @@ impl<T: 'static> BufferObject<T> {
}
}

/// 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<D>, x: u32, y: u32, width: u32, height: u32, f: F) -> Result<IoResult<S>, WrongDeviceError>
where
D: AsRawFd + 'static,
Expand Down Expand Up @@ -328,9 +328,9 @@ impl<T: 'static> BufferObject<T> {
}
}

/// 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<D>,
Expand Down Expand Up @@ -389,7 +389,7 @@ impl<T: 'static> BufferObject<T> {

/// 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,
Expand Down Expand Up @@ -573,7 +573,7 @@ impl<T: 'static> DrmPlanarBuffer for BufferObject<T> {
}

#[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 {
Expand Down
56 changes: 28 additions & 28 deletions src/device.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,10 @@ impl Device<FdWrapper> {
/// 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.
Expand All @@ -101,15 +101,15 @@ impl<T: AsRawFd + 'static> Device<T> {
/// 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<Device<T>> {
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) }),
})
}
Expand Down Expand Up @@ -208,7 +208,7 @@ impl<T: AsRawFd + 'static> Device<T> {
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<U: 'static>(
&self,
Expand All @@ -235,13 +235,13 @@ impl<T: AsRawFd + 'static> Device<T> {
}
}

/// 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<U: 'static>(
Expand All @@ -264,18 +264,18 @@ impl<T: AsRawFd + 'static> Device<T> {
}
}

/// 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<U: 'static>(
Expand All @@ -297,13 +297,13 @@ impl<T: AsRawFd + 'static> Device<T> {
}
}

/// 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<U: 'static>(
&self,
Expand Down Expand Up @@ -336,14 +336,14 @@ impl<T: AsRawFd + 'static> Device<T> {
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<U: 'static>(
&self,
Expand Down Expand Up @@ -391,12 +391,12 @@ impl<T: DrmDevice + AsRawFd + 'static> DrmDevice for Device<T> {}
impl<T: DrmControlDevice + AsRawFd + 'static> DrmControlDevice for Device<T> {}

#[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")
}
}

Expand Down
4 changes: 2 additions & 2 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<T> {
/// Receive a raw pointer representing this type.
fn as_raw(&self) -> *const T;
Expand Down
15 changes: 8 additions & 7 deletions src/surface.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<T: 'static> {
ffi: Ptr<::ffi::gbm_surface>,
_device: WeakPtr<::ffi::gbm_device>,
Expand Down Expand Up @@ -46,9 +46,9 @@ impl<T: 'static> Surface<T> {
/// 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();
Expand All @@ -62,12 +62,13 @@ impl<T: 'static> Surface<T> {
/// 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<BufferObject<T>, FrontBufferError> {
Expand Down

0 comments on commit a8b07ae

Please sign in to comment.