A GPU-accessible image buffer. More...

#include <RImage.h>

Inheritance diagram for RImage:

Public Member Functions
virtual std::shared_ptr< RGBMBo >	gbmBo (RDevice *device=nullptr) const noexcept=0
	Returns the GBM buffer object backing this image, if any.

virtual std::shared_ptr< RDRMFramebuffer >	drmFb (RDevice *device=nullptr) const noexcept=0
	Returns a DRM framebuffer for this image, if supported.

virtual sk_sp< SkImage >	skImage (RDevice *device=nullptr) const noexcept=0
	Returns an SkImage view of this image, if supported (RImageCap_SkImage).

virtual sk_sp< SkSurface >	skSurface (RDevice *device=nullptr) const noexcept=0
	Returns an SkSurface targeting this image, if supported (RImageCap_SkSurface).

virtual CZBitset< RImageCap >	checkDeviceCaps (CZBitset< RImageCap > caps, RDevice *device=nullptr) const noexcept=0
	Checks which of the given capabilities are supported on a device.

virtual bool	writePixels (const RPixelBufferRegion &region) noexcept=0
	Uploads pixel data into a region of the image.

virtual bool	readPixels (const RPixelBufferRegion &region) noexcept=0
	Downloads pixel data from a region of the image.

SkISize	size () const noexcept
	Returns the image size in pixels.

const RFormatInfo &	formatInfo () const noexcept
	Returns information about the image's pixel format.

const std::unordered_set< RFormat > &	readFormats () const noexcept
	Returns the set of formats the image can be read/sampled as.

const std::unordered_set< RFormat > &	writeFormats () const noexcept
	Returns the set of formats the image can be written to.

SkAlphaType	alphaType () const noexcept
	Returns the image's alpha type.

RModifier	modifier () const noexcept
	Returns the DRM format modifier of the image's storage.

RDevice *	allocator () const noexcept
	Returns the device that allocated this image.

std::shared_ptr< RCore >	core () const noexcept
	Returns the RCore instance that owns this image.

std::shared_ptr< RSync >	readSync () noexcept
	Returns the read sync fence.

void	setReadSync (std::shared_ptr< RSync > sync) noexcept
	Sets the read sync fence.

std::shared_ptr< RSync >	writeSync () noexcept
	Returns the write sync fence.

void	setWriteSync (std::shared_ptr< RSync > sync) noexcept
	Sets the write sync fence.

UInt32	writeSerial () const noexcept
	Returns the write serial.

std::shared_ptr< RGLImage >	asGL () const noexcept
	Attempts to cast this image to an RGLImage.

std::shared_ptr< RRSImage >	asRS () const noexcept
	Attempts to cast this image to an RRSImage.

std::shared_ptr< RVKImage >	asVK () const noexcept
	Attempts to cast this image to an RVKImage.

	~RImage () noexcept
	Destructor.

Public Member Functions inherited from RObject
	RObject ()=default
	Constructs a default RObject.

Static Public Member Functions
static std::shared_ptr< RImage >	Make (SkISize size, const RDRMFormat &format, const RImageConstraints *constraints=nullptr) noexcept
	Allocates a new empty image.

static std::shared_ptr< RImage >	MakeFromPixels (const RPixelBufferInfo &info, const RDRMFormat &format, const RImageConstraints *constraints=nullptr) noexcept
	Allocates a new image and uploads pixel data into it.

static std::shared_ptr< RImage >	LoadFile (const std::filesystem::path &path, const RDRMFormat &format, SkISize size={0, 0}, const RImageConstraints *constraints=nullptr) noexcept
	Loads an image from a file.

static std::shared_ptr< RImage >	FromDMA (const RDMABufferInfo &info, CZOwn ownership, const RImageConstraints *constraints=nullptr) noexcept
	Imports an image from a DMA-buf.

Detailed Description

A GPU-accessible image buffer.

RImage is the fundamental buffer type: a 2D image that can be used as a sampling source, a render target (via RSurface), or shared with other devices and processes.

Images may be backed by different storage depending on the requested capabilities: native (API-optimal) storage, GBM/DMA-buf storage suitable for KMS scanout and cross-device sharing, or dumb buffers. An image can be created with RImage::Make(), imported from a DMA-buf with RImage::FromDMA(), or wrapped around an existing backend handle.

Pixel data can be uploaded/downloaded with writePixels()/readPixels(), and access is coordinated across threads and devices through per-image read/write RSync fences.

Constructor & Destructor Documentation

◆ ~RImage()

~RImage ( )

noexcept

Destructor.

Member Function Documentation

◆ Make()

static std::shared_ptr< RImage > Make	(	SkISize	size,
		const RDRMFormat &	format,
		const RImageConstraints *	constraints = `nullptr`
	)

staticnoexcept

Allocates a new empty image.

Parameters

size	Image size in pixels.
format	Requested DRM format (and modifiers).
constraints	Optional allocation constraints (caps, formats, allocator device).

Returns: A shared pointer to the new image, or nullptr on failure.

◆ MakeFromPixels()

static std::shared_ptr< RImage > MakeFromPixels	(	const RPixelBufferInfo &	info,
		const RDRMFormat &	format,
		const RImageConstraints *	constraints = `nullptr`
	)

staticnoexcept

Allocates a new image and uploads pixel data into it.

The source format (info.format) is automatically added to the required write formats.

Parameters

info	Description of the source pixel buffer.
format	Requested DRM format (and modifiers) for the new image.
constraints	Optional allocation constraints.

Returns: A shared pointer to the new image, or nullptr on failure.

◆ LoadFile()

static std::shared_ptr< RImage > LoadFile	(	const std::filesystem::path &	path,
		const RDRMFormat &	format,
		SkISize	size = `{0, 0}`,
		const RImageConstraints *	constraints = `nullptr`
	)

staticnoexcept

Loads an image from a file.

Supports common raster formats and SVG. The decoded content is scaled/converted to format and, if given, size.

Parameters

size	Desired output size in pixels; {0, 0} keeps the source dimensions.
format	Requested DRM format for the new image.
path	Path to the image file.
constraints	Optional allocation constraints.

Returns: A shared pointer to the new image, or nullptr on failure.

◆ FromDMA()

static std::shared_ptr< RImage > FromDMA	(	const RDMABufferInfo &	info,
		CZOwn	ownership,
		const RImageConstraints *	constraints = `nullptr`
	)

staticnoexcept

Imports an image from a DMA-buf.

Parameters

info	Description of the DMA buffer (fds, offsets, strides, modifier).
ownership	Whether the image takes ownership of the buffer's file descriptors. When CZOwn::Own, the fds are closed on failure.
constraints	Optional allocation constraints.

Returns: A shared pointer to the imported image, or nullptr on failure.

◆ gbmBo()

virtual std::shared_ptr< RGBMBo > gbmBo ( RDevice * device = nullptr ) const

pure virtualnoexcept

Returns the GBM buffer object backing this image, if any.

Parameters

device Device to query. If nullptr, the main device is used.

Returns: The GBM buffer object, or nullptr if unavailable.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ drmFb()

virtual std::shared_ptr< RDRMFramebuffer > drmFb ( RDevice * device = nullptr ) const

pure virtualnoexcept

Returns a DRM framebuffer for this image, if supported.

Parameters

device Device to query. If nullptr, the main device is used.

Returns: The DRM framebuffer, or nullptr if unavailable.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ skImage()

virtual sk_sp< SkImage > skImage ( RDevice * device = nullptr ) const

pure virtualnoexcept

Returns an SkImage view of this image, if supported (RImageCap_SkImage).

Parameters

device Device to query. If nullptr, the main device is used.

Returns: The SkImage, or nullptr if unavailable.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ skSurface()

virtual sk_sp< SkSurface > skSurface ( RDevice * device = nullptr ) const

pure virtualnoexcept

Returns an SkSurface targeting this image, if supported (RImageCap_SkSurface).

Parameters

device Device to query. If nullptr, the main device is used.

Returns: The SkSurface, or nullptr if unavailable.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ checkDeviceCaps()

virtual CZBitset< RImageCap > checkDeviceCaps	(	CZBitset< RImageCap >	caps,
		RDevice *	device = `nullptr`
	)		const

pure virtualnoexcept

Checks which of the given capabilities are supported on a device.

Parameters

caps	The capabilities to test.
device	Device to query. If nullptr, the main device is used.

Returns: The subset of caps that is supported; equals caps when all are supported.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ writePixels()

virtual bool writePixels ( const RPixelBufferRegion & region )

pure virtualnoexcept

Uploads pixel data into a region of the image.

Increments writeSerial() on success.

Parameters

region Source buffer and set of rectangles to copy.

Returns: true on success, false otherwise.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ readPixels()

virtual bool readPixels ( const RPixelBufferRegion & region )

pure virtualnoexcept

Downloads pixel data from a region of the image.

Parameters

region Destination buffer and set of rectangles to copy.

Returns: true on success, false otherwise.

Implemented in RGLImage, RRSImage, and RVKImage.

◆ size()

SkISize size ( ) const

inlinenoexcept

Returns the image size in pixels.

◆ formatInfo()

const RFormatInfo & formatInfo ( ) const

inlinenoexcept

Returns information about the image's pixel format.

◆ readFormats()

const std::unordered_set< RFormat > & readFormats ( ) const

inlinenoexcept

Returns the set of formats the image can be read/sampled as.

◆ writeFormats()

const std::unordered_set< RFormat > & writeFormats ( ) const

inlinenoexcept

Returns the set of formats the image can be written to.

◆ alphaType()

SkAlphaType alphaType ( ) const

inlinenoexcept

Returns the image's alpha type.

◆ modifier()

RModifier modifier ( ) const

inlinenoexcept

Returns the DRM format modifier of the image's storage.

◆ allocator()

RDevice * allocator ( ) const

inlinenoexcept

Returns the device that allocated this image.

◆ core()

std::shared_ptr< RCore > core ( ) const

inlinenoexcept

Returns the RCore instance that owns this image.

◆ readSync()

std::shared_ptr< RSync > readSync ( )

inlinenoexcept

Returns the read sync fence.

Signalled when the image is no longer being read.

◆ setReadSync()

void setReadSync ( std::shared_ptr< RSync > sync )

inlinenoexcept

Sets the read sync fence.

Parameters

sync	The fence signalled when reads on the image complete.

◆ writeSync()

std::shared_ptr< RSync > writeSync ( )

inlinenoexcept

Returns the write sync fence.

Signalled when pending write operations on the image complete.

◆ setWriteSync()

void setWriteSync ( std::shared_ptr< RSync > sync )

inlinenoexcept

Sets the write sync fence.

Parameters

sync	The fence signalled when writes on the image complete.

◆ writeSerial()

UInt32 writeSerial ( ) const

inlinenoexcept

Returns the write serial.

Starts at 0 and is incremented by each successful writePixels() call.

◆ asGL()

std::shared_ptr< RGLImage > asGL ( ) const

noexcept

Attempts to cast this image to an RGLImage.

Returns: A shared pointer to RGLImage if the active API is OpenGL, or nullptr otherwise.

◆ asRS()

std::shared_ptr< RRSImage > asRS ( ) const

noexcept

Attempts to cast this image to an RRSImage.

Returns: A shared pointer to RRSImage if the active API is Raster, or nullptr otherwise.

◆ asVK()

std::shared_ptr< RVKImage > asVK ( ) const

noexcept

Attempts to cast this image to an RVKImage.

Returns: A shared pointer to RVKImage if the active API is Vulkan, or nullptr otherwise.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~RImage()

Member Function Documentation

◆ Make()

◆ MakeFromPixels()

◆ LoadFile()

◆ FromDMA()

◆ gbmBo()

◆ drmFb()

◆ skImage()

◆ skSurface()

◆ checkDeviceCaps()

◆ writePixels()

◆ readPixels()

◆ size()

◆ formatInfo()

◆ readFormats()

◆ writeFormats()

◆ alphaType()

◆ modifier()

◆ allocator()

◆ core()

◆ readSync()

◆ setReadSync()

◆ writeSync()

◆ setWriteSync()

◆ writeSerial()

◆ asGL()

◆ asRS()

◆ asVK()