Skip to content

Commit 22e4bf4

Browse files
khyperiakhyperia
authored
Clarify and fix up some image documentation (#678)
1 parent 8c05636 commit 22e4bf4

File tree

8 files changed

+90
-79
lines changed

8 files changed

+90
-79
lines changed

‎crates/spirv-std/macros/src/image.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,7 @@ impl Parse for ImageType {
263263
| ImageFormat::Rg8Snorm
264264
| ImageFormat::R16Snorm
265265
| ImageFormat::R8Snorm => SampledType::F32,
266+
266267
ImageFormat::Rgba32i
267268
| ImageFormat::Rgba16i
268269
| ImageFormat::Rgba8i
@@ -285,6 +286,7 @@ impl Parse for ImageType {
285286
| ImageFormat::R8ui => SampledType::U32,
286287

287288
ImageFormat::R64ui => SampledType::U64,
289+
288290
ImageFormat::R64i => SampledType::I64,
289291

290292
ImageFormat::Unknown => unreachable!(),

‎crates/spirv-std/macros/src/lib.rs

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,8 @@ use syn::{punctuated::Punctuated, spanned::Spanned, ItemFn, Token};
8080

8181
use quote::ToTokens;
8282

83-
/// A macro for creating SPIR-V `OpTypeImage` types.
83+
/// A macro for creating SPIR-V `OpTypeImage` types. Always produces a
84+
/// `spirv_std::image::Image<...>` type.
8485
///
8586
/// The grammar for the macro is as follows:
8687
///
@@ -122,6 +123,11 @@ use quote::ToTokens;
122123
/// Accepted values: `true` or `false`. Default: `unknown`.
123124
///
124125
/// [`ImageFormat`]: spirv_types::image_params::ImageFormat
126+
///
127+
/// Keep in mind that `sampled` here is a different concept than the `SampledImage` type:
128+
/// `sampled=true` means that this image requires a sampler to be able to access, while the
129+
/// `SampledImage` type bundles that sampler together with the image into a single type (e.g.
130+
/// `sampler2D` in GLSL, vs. `texture2D`).
125131
#[proc_macro]
126132
// The `Image` is supposed to be used in the type position, which
127133
// uses `PascalCase`.

‎crates/spirv-std/shared/src/image_params.rs

Lines changed: 44 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -153,92 +153,89 @@ impl From<bool> for Sampled {
153153
pub enum ImageFormat {
154154
/// Representation not known at compile time.
155155
Unknown,
156-
/// RGBA channels, 32 bit floating point integer.
156+
/// RGBA channels, 32 bit floating point per channel.
157157
Rgba32f,
158-
/// RGBA channels, 16 bit floating point integer.
158+
/// RGBA channels, 16 bit floating point per channel.
159159
Rgba16f,
160-
/// RGBA channels, 16 bit floating point integer.
160+
/// Single red channel, 32 bit floating point.
161161
R32f,
162-
/// RGBA channels, 8 bit floating point integer.
162+
/// RGBA channels, 8 bit unsigned normalized integer per channel.
163163
Rgba8,
164-
/// RGBA channels, 8 bit signed normalized integer.
164+
/// RGBA channels, 8 bit signed normalized integer per channel.
165165
Rgba8Snorm,
166-
/// Red+Green channels, 32 bit floating point integer.
166+
/// Red+Green channels, 32 bit floating point per channel.
167167
Rg32f,
168-
/// Red+Green channels, 16 bit floating point integer.
168+
/// Red+Green channels, 16 bit floating point per channel.
169169
Rg16f,
170-
/// 32 bit unsigned integer containing two 11 bit floating point integers
171-
/// for the Red and Green channels, and a 10 bit floating point integer for
172-
/// the Blue channel.
170+
/// 32 bits containing two 11 bit floating point numbers for the Red and Green
171+
/// channels, and a 10 bit floating point number for the Blue channel.
173172
R11fG11fB10f,
174-
/// Red channel, 16 bit floating point.
173+
/// Single red channel, 16 bit floating point.
175174
R16f,
176-
/// RGBA channel, 16 bit floating point.
175+
/// RGBA channels, 16 bit unsigned normalized integer per channel.
177176
Rgba16,
178-
/// 32 bit unsigned integer containing three 10 bit unsigned normalized
179-
/// integers for the Red, Green, and Blue channels; with a 2 unsigned
180-
/// normalized integer for the Alpha channel.
177+
/// 32 bits containing three 10 bit unsigned normalized integers for the Red, Green, and Blue
178+
/// channels, and a 2 bit unsigned normalized integer for the Alpha channel.
181179
Rgb10A2,
182-
/// Red+Green channels, 16 bit floating point integer.
180+
/// Red+Green channels, 16 bit unsigned normalized integer per channel.
183181
Rg16,
184-
/// Red+Green channels, 8 bit floating point integer.
182+
/// Red+Green channels, 8 bit unsigned normalized integer per channel.
185183
Rg8,
186-
/// Red+Green channels, 16 bit floating point integer.
184+
/// Single red channel, 16 bit unsigned normalized integer.
187185
R16,
188-
/// Red channel, 8 bit floating point integer.
186+
/// Single red channel, 8 bit unsigned normalized integer.
189187
R8,
190-
/// RGBA channels, 16 bit signed normalized integer.
188+
/// RGBA channels, 16 bit signed normalized integer per channel.
191189
Rgba16Snorm,
192-
/// RGB channels, 16 bit signed normalized integer.
190+
/// Red+Green channels, 16 bit signed normalized integer per channel.
193191
Rg16Snorm,
194-
/// Red+Green channels, 8 bit signed normalized integer.
192+
/// Red+Green channels, 8 bit signed normalized integer per channel.
195193
Rg8Snorm,
196-
/// Red channel, 16 bit signed normalized integer.
194+
/// Single red channel, 16 bit signed normalized integer.
197195
R16Snorm,
198-
/// Red channel, 16 bit signed normalized integer.
196+
/// Single red channel, 8 bit signed normalized integer.
199197
R8Snorm,
200-
/// RGBA channels, 32 bit signed integer.
198+
/// RGBA channels, 32 bit signed integer per channel (not normalized).
201199
Rgba32i,
202-
/// RGBA channels, 16 bit signed integer.
200+
/// RGBA channels, 16 bit signed integer per channel (not normalized).
203201
Rgba16i,
204-
/// RGBA channels, 8 bit signed integer.
202+
/// RGBA channels, 8 bit signed integer per channel (not normalized).
205203
Rgba8i,
206-
/// Red channel, 32 bit signed integer.
204+
/// Single red channel, 32 bit signed integer (not normalized).
207205
R32i,
208-
/// Red+Green channels, 32 bit signed integer.
206+
/// Red+Green channels, 32 bit signed integer per channel (not normalized).
209207
Rg32i,
210-
/// Red+Green channels, 16 bit signed integer.
208+
/// Red+Green channels, 16 bit signed integer per channel (not normalized).
211209
Rg16i,
212-
/// Red+Green channels, 8 bit signed integer.
210+
/// Red+Green channels, 8 bit signed integer per channel (not normalized).
213211
Rg8i,
214-
/// Red channel, 16 bit signed integer.
212+
/// Single red channel, 16 bit signed integer (not normalized).
215213
R16i,
216-
/// Red channel, 8 bit signed integer.
214+
/// Single red channel, 8 bit signed integer (not normalized).
217215
R8i,
218-
/// RGBA channels, 32 bit unsigned integer.
216+
/// RGBA channels, 32 bit unsigned integer per channel (not normalized).
219217
Rgba32ui,
220-
/// RGBA channels, 16 bit unsigned integer.
218+
/// RGBA channels, 16 bit unsigned integer per channel (not normalized).
221219
Rgba16ui,
222-
/// RGBA channels, 8 bit unsigned integer.
220+
/// RGBA channels, 8 bit unsigned integer per channel (not normalized).
223221
Rgba8ui,
224-
/// Red channel, 32 bit unsigned integer.
222+
/// Single red channel, 32 bit unsigned integer (not normalized).
225223
R32ui,
226-
/// 32 bit unsigned integer containing three 10 bit unsigned integers for
227-
/// the Red, Green, and Blue channels, and a 2 bit unsigned integer for the
228-
/// Alpha channel.
224+
/// 32 bits containing three 10 bit unsigned integers for the Red, Green, and Blue channels,
225+
/// and a 2 bit unsigned integer for the Alpha channel.
229226
Rgb10A2ui,
230-
/// Red+Green channels, 32 bit unsigned integer.
227+
/// Red+Green channels, 32 bit unsigned integer per channel (not normalized).
231228
Rg32ui,
232-
/// Red+Green channels, 16 bit unsigned integer.
229+
/// Red+Green channels, 16 bit unsigned integer per channel (not normalized).
233230
Rg16ui,
234-
/// Red+Green channels, 8 bit unsigned integer.
231+
/// Red+Green channels, 8 bit unsigned integer per channel (not normalized).
235232
Rg8ui,
236-
/// Red channel, 16 bit unsigned integer.
233+
/// Single red channel, 16 bit unsigned integer (not normalized).
237234
R16ui,
238-
/// Red channel, 8 bit unsigned integer.
235+
/// Single red channel, 8 bit unsigned integer (not normalized).
239236
R8ui,
240-
/// Red channel, 64 bit unsigned integer.
237+
/// Single red channel, 64 bit unsigned integer (not normalized).
241238
R64ui,
242-
/// Red channel, 64 bit signed integer.
239+
/// Single red channel, 64 bit signed integer (not normalized).
243240
R64i,
244241
}

‎crates/spirv-std/src/image.rs

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ pub type StorageImage3dI = crate::Image!(3D, type=i32, sampled=false, __crate_ro
5353
pub type Cubemap = crate::Image!(cube, type=f32, sampled, __crate_root=crate);
5454

5555
/// An opaque image type. Corresponds to `OpTypeImage`.
56+
///
57+
/// You likely want to write this type using the [`crate::Image!`] macro helper, as the generic
58+
/// arguments here can get extremely verbose.
5659
#[spirv(generic_image_type)]
5760
#[derive(Copy, Clone)]
5861
pub struct Image<
@@ -914,8 +917,11 @@ impl<
914917
}
915918
}
916919

917-
/// An image combined with a sampler, enabling filtered accesses of the
918-
/// image’s contents.
920+
/// An image combined with a sampler in a single value, enabling filtered accesses of the image's
921+
/// contents. Corresponds to `OpTypeSampledImage`.
922+
///
923+
/// The generic type parameter is the underlying image type, written like
924+
/// `SampledImage<Image!(...)>`.
919925
#[spirv(sampled_image)]
920926
#[derive(Copy, Clone)]
921927
pub struct SampledImage<I> {

‎tests/ui/image/query/query_levels_err.stderr

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
error: OpImageQueryLevels's image has a dimension of DimRect
2-
--> $SPIRV_STD_SRC/image.rs:760:13
2+
--> $SPIRV_STD_SRC/image.rs:763:13
33
|
4-
760 | / asm! {
5-
761 | | "%image = OpLoad _ {this}",
6-
762 | | "{result} = OpImageQueryLevels typeof{result} %image",
7-
763 | | this = in(reg) self,
8-
764 | | result = out(reg) result,
9-
765 | | }
4+
763 | / asm! {
5+
764 | | "%image = OpLoad _ {this}",
6+
765 | | "{result} = OpImageQueryLevels typeof{result} %image",
7+
766 | | this = in(reg) self,
8+
767 | | result = out(reg) result,
9+
768 | | }
1010
| |_____________^
1111
|
1212
= note: Allowed dimensions are 1D, 2D, 3D, and Cube

‎tests/ui/image/query/query_lod_err.stderr

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
error: OpImageQueryLod's image has a dimension of DimRect
2-
--> $SPIRV_STD_SRC/image.rs:793:13
2+
--> $SPIRV_STD_SRC/image.rs:796:13
33
|
4-
793 | / asm! {
5-
794 | | "%typeSampledImage = OpTypeSampledImage typeof*{this}",
6-
795 | | "%image = OpLoad _ {this}",
7-
796 | | "%sampler = OpLoad _ {sampler}",
4+
796 | / asm! {
5+
797 | | "%typeSampledImage = OpTypeSampledImage typeof*{this}",
6+
798 | | "%image = OpLoad _ {this}",
7+
799 | | "%sampler = OpLoad _ {sampler}",
88
... |
9-
804 | | coord = in(reg) &coord
10-
805 | | }
9+
807 | | coord = in(reg) &coord
10+
808 | | }
1111
| |_____________^
1212
|
1313
= note: Allowed dimensions are 1D, 2D, 3D, and Cube

‎tests/ui/image/query/query_size_err.stderr

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
error: OpImageQuerySize is invalid for this image type
2-
--> $SPIRV_STD_SRC/image.rs:822:13
2+
--> $SPIRV_STD_SRC/image.rs:825:13
33
|
4-
822 | / asm! {
5-
823 | | "%image = OpLoad _ {this}",
6-
824 | | "%result = OpImageQuerySize typeof*{result} %image",
7-
825 | | "OpStore {result} %result",
8-
826 | | this = in(reg) self,
9-
827 | | result = in(reg) &mut result,
10-
828 | | }
4+
825 | / asm! {
5+
826 | | "%image = OpLoad _ {this}",
6+
827 | | "%result = OpImageQuerySize typeof*{result} %image",
7+
828 | | "OpStore {result} %result",
8+
829 | | this = in(reg) self,
9+
830 | | result = in(reg) &mut result,
10+
831 | | }
1111
| |_____________^
1212
|
1313
= note: allowed dimensions are 1D, 2D, 3D, Buffer, Rect, or Cube. if dimension is 1D, 2D, 3D, or Cube, it must have either multisampled be true, *or* sampled of Unknown or No

‎tests/ui/image/query/query_size_lod_err.stderr

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
error: OpImageQuerySizeLod is invalid for this image type
2-
--> $SPIRV_STD_SRC/image.rs:868:13
2+
--> $SPIRV_STD_SRC/image.rs:871:13
33
|
4-
868 | / asm! {
5-
869 | | "%image = OpLoad _ {this}",
6-
870 | | "%result = OpImageQuerySizeLod typeof*{result} %image {lod}",
7-
871 | | "OpStore {result} %result",
4+
871 | / asm! {
5+
872 | | "%image = OpLoad _ {this}",
6+
873 | | "%result = OpImageQuerySizeLod typeof*{result} %image {lod}",
7+
874 | | "OpStore {result} %result",
88
... |
9-
874 | | result = in(reg) &mut result,
10-
875 | | }
9+
877 | | result = in(reg) &mut result,
10+
878 | | }
1111
| |_____________^
1212
|
1313
= note: The image's dimension must be 1D, 2D, 3D, or Cube. Multisampled must be false.

0 commit comments

Comments
 (0)