From fa68b20c19dfabfb1be0d29125bed4f6707dabe5 Mon Sep 17 00:00:00 2001 From: chyyran Date: Fri, 13 Jan 2023 18:23:31 -0500 Subject: [PATCH] docs: doc image --- README.md | 17 ++++++++++++----- librashader-runtime/src/image.rs | 12 ++++++++++++ 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 83b53ac..c2c61e7 100644 --- a/README.md +++ b/README.md @@ -32,26 +32,33 @@ of DirectX and OpenGL, as well as Metal, are not supported (but pull-requests ar librashader provides both a Rust API under the `librashader` crate, and a C API. Both APIs are first-class, fully supported. The librashader C API is best used by linking statically with `librashader_ld`, which implements a loader that dynamically -loads the librashader (`librashader.so` or `librashader.dll`) implementation in the search path. +loads the librashader (`librashader.so` or `librashader.dll`) implementation in the search path. You may also link against +`librashader_capi` directly with [`librashader.h`](https://github.com/SnowflakePowered/librashader/blob/master/librashader-capi/librashader.h). -Note that the Rust crate requires nightly Rust to build. +The C API currently does not expose the [shader reflection API](https://docs.rs/librashader/latest/librashader/reflect/index.html). Work +is in progress to expose this to C. In the meanwhile, if you wish to implement a custom runtime for librashader, it will have to be done +in Rust. ### C ABI Compatibility -Since the recommended way of integrating `librashader` is by the `librashader_ld` single header library, ABI stability +The recommended way of integrating `librashader` is by the `librashader_ld` single header library, ABI stability is important to ensure that updates to librashader do not break existing consumers. -Pre-1.0, nothing is guaranteed to be stable, but the following APIs are unlikely to change their ABI. +Pre-1.0, nothing is guaranteed to be stable, but the following APIs are unlikely to change their ABI unless otherwise indicated. * `libra_preset_*` * `libra_error_*` -The following APIs, mostly runtime, are more likely to change their ABI. +The following APIs, mostly runtime, are more likely to change their ABI before a 1.0 release as I experiment with what +works best. * `libra_gl_*` * `libra_vk_*` * `libra_d3d11_*` * `libra_d3d12_*` +If you do not mind linking against `librashader_capi` directly, [`librashader.h`](https://github.com/SnowflakePowered/librashader/blob/master/librashader-capi/librashader.h) +is unlikely to break API stability. + ## Compatibility librashader implements the entire RetroArch shader pipeline and is highly compatible with existing shaders, diff --git a/librashader-runtime/src/image.rs b/librashader-runtime/src/image.rs index 72169e5..bdd2430 100644 --- a/librashader-runtime/src/image.rs +++ b/librashader-runtime/src/image.rs @@ -4,16 +4,28 @@ use std::marker::PhantomData; use std::path::Path; +/// An uncompressed raw image ready to upload to GPU buffers. pub struct Image { + /// The raw bytes of the image. pub bytes: Vec, + /// The size dimensions of the image. pub size: Size, + /// The byte pitch of the image. pub pitch: usize, _pd: PhantomData

, } +/// R8G8B8A8 pixel format. +/// +/// Every RGB with alpha pixel is represented with 32 bits. pub struct RGBA8; + +/// B8G8R8A8 pixel format. +/// +/// Every BGR with alpha pixel is represented with 32 bits. pub struct BGRA8; +/// Represents an image pixel format to convert images into. pub trait PixelFormat { #[doc(hidden)] fn convert(pixels: &mut Vec);