-
Notifications
You must be signed in to change notification settings - Fork 453
/
textures.txt
1742 lines (1428 loc) · 62.4 KB
/
textures.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
[[textures]]
= Image Operations
== Image Operations Overview
Image Operations are steps performed by SPIR-V image instructions, where
those instructions which take an code:OpTypeImage (representing a
sname:VkImageView) or code:OpTypeSampledImage (representing a
(sname:VkImageView, sname:VkSampler) pair) and texel coordinates as
operands, and return a value based on one or more neighboring texture
elements (_texels_) in the image.
[NOTE]
.Note
==================
Texel is a term which is a combination of the words texture and element.
Early interactive computer graphics supported texture operations on
textures, a small subset of the image operations on images described here.
The discrete samples remain essentially equivalent, however, so we retain
the historical term texel to refer to them.
==================
SPIR-V Image Instructions include the following functionality:
* code:OpImageSample* and code:OpImageSparseSample* read one or more
neighboring texels of the image, and <<textures-texel-filtering,filter>>
the texel values based on the state of the sampler.
** Instructions with code:ImplicitLod in the name
<<textures-level-of-detail-operation,determine>> the level of detail
used in the sampling operation based on the coordinates used in
neighboring fragments.
** Instructions with code:ExplicitLod in the name
<<textures-level-of-detail-operation,determine>> the level of detail
used in the sampling operation based on additional coordinates.
** Instructions with code:Proj in the name apply homogeneous
<<textures-projection,projection>> to the coordinates.
* code:OpImageFetch and code:OpImageSparseFetch return a single texel of
the image. No sampler is used.
* code:OpImage*code:Gather and code:OpImageSparse*code:Gather read
neighboring texels and <<textures-gather,return a single component>> of
each.
* code:OpImageRead (and code:OpImageSparseRead) and code:OpImageWrite read
and write, respectively, a texel in the image. No sampler is used.
* Instructions with code:Dref in the name apply
<<textures-depth-compare-operation,depth comparison>> on the texel
values.
* Instructions with code:Sparse in the name additionally return a
<<textures-sparse-residency,sparse residency>> code.
=== Texel Coordinate Systems
Images are addressed by _texel coordinates_. There are three _texel
coordinate systems_:
* normalized texel coordinates (coordinates ranging from 0 to 1 span the
image),
* unnormalized texel coordinates (floating point coordinates ranging from
0 to width/height/depth span the image), and
* integer texel coordinates (integer coordinates ranging from 0 to
width-1/height-1/depth-1 address the texels within the image).
SPIR-V code:OpImageFetch, code:OpImageSparseFetch, code:OpImageRead,
code:OpImageSparseRead, and code:OpImageWrite instructions use integer texel
coordinates. Other image instructions can: use either normalized or
unnormalized texel coordinates (selected by the
pname:unnormalizedCoordinates state of the sampler used in the instruction),
but there are <<samplers-unnormalizedCoordinates,limitations>> on what
operations, image state, and sampler state is supported. Normalized
coordinates are logically <<textures-normalized-to-unnormalized,converted>>
to unnormalized as part of image operations, and
<<textures-normalized-operations,certain steps>> are only performed on
normalized coordinates. The array layer coordinate is always treated as
unnormalized even when other coordinates are normalized.
Normalized texel coordinates are referred to as latexmath:[$(s,t,r,q,a)$],
with the coordinates having the following meanings:
* s: Coordinate in the first dimension of an image.
* t: Coordinate in the second dimension of an image.
* r: Coordinate in the third dimension of an image.
** (s,t,r) are interpreted as a direction vector for Cube images.
* q: Fourth coordinate, for homogeneous (projective) coordinates.
* a: Coordinate for array layer.
The coordinates are extracted from the SPIR-V operand based on the
dimensionality of the image variable and type of instruction. For code:Proj
instructions, the components are in order (s, [t,] [r,] q) with t and r
being conditionally present based on the code:Dim of the image. For
non-code:Proj instructions, the coordinates are (s [,t] [,r] [,a]), with t
and r being conditionally present based on the code:Dim of the image and a
being conditionally present based on the code:Arrayed property of the image.
Projective image instructions are not supported on code:Arrayed images.
Unnormalized texel coordinates are referred to as latexmath:[$(u,v,w,a)$],
with the coordinates having the following meanings:
* u: Coordinate in the first dimension of an image.
* v: Coordinate in the second dimension of an image.
* w: Coordinate in the third dimension of an image.
* a: Coordinate for array layer.
Only the u and v coordinates are directly extracted from the SPIR-V operand,
because only 1D and 2D (non-code:Arrayed) dimensionalities support
unnormalized coordinates. The components are in order (u [,v]), with v being
conditionally present when the dimensionality is 2D. When normalized
coordinates are converted to unnormalized coordinates, all four coordinates
are used.
Integer texel coordinates are referred to as latexmath:[$(i,j,k,l,n)$], and
the first four in that order have the same meanings as unnormalized texel
coordinates. They are extracted from the SPIR-V operand in order (i, [,j],
[,k], [,l]), with j and k conditionally present based on the code:Dim of the
image, and l conditionally present based on the code:Arrayed property of the
image. n is the sample index and is taken from the code:Sample image
operand.
For all coordinate types, unused coordinates are assigned a value of zero.
[[textures-texel-coordinate-systems-diagrams]]
image::images/vulkantexture0.png[Title="Texel Coordinate Systems", align="left", scaledwidth="80%"]
The Texel Coordinate Systems - For the example shown of an 8x4 texel two dimensional image.
* Normalized texel coordinates:
** The s coordinate goes from 0.0 to 1.0, left to right.
** The t coordinate goes from 0.0 to 1.0, top to bottom.
* Unnormalized texel coordinates:
** The u coordinate goes from -1.0 to 9.0, left to right. The u coordinate
within the range 0.0 to 8.0 is within the image, otherwise it is within
the border.
** The v coordinate goes from -1.0 to 5.0, top to bottom. The v coordinate
within the range 0.0 to 4.0 is within the image, otherwise it is within
the border.
* Integer texel coordinates:
** The i coordinate goes from -1 to 8, left to right. The i coordinate
within the range 0 to 7 addresses texels within the image, otherwise it
addresses a border texel.
** The j coordinate goes from -1 to 5, top to bottom. The j coordinate
within the range 0 to 3 addresses texels within the image, otherwise it
addresses a border texel.
* Also shown for linear filtering:
** Given the unnormalized coordinates (u,v), the four texels selected are
i0j0, i1j0, i0j1 and i1j1.
** The weights latexmath:[$\alpha$] and latexmath:[$\beta$].
** Given the offset latexmath:[$\Delta_{i}$] and latexmath:[$\Delta_{j}$],
the four texels selected by the offset are i0j0', i1j0', i0j1' and
i1j1'.
image::images/vulkantexture1.png[Title="Texel Coordinate Systems", align="left", scaledwidth="80%"]
The Texel Coordinate Systems - For the example shown of an 8x4 texel two
dimensional image.
* Texel coordinates as above. Also shown for nearest filtering:
** Given the unnormalized coordinates (u,v), the texel selected is ij.
** Given the offset latexmath:[$\Delta_{i}$] and latexmath:[$\Delta_{j}$],
the texel selected by the offset is ij'.
== Conversion Formulas
ifdef::editing-notes[]
[NOTE]
.editing-note
==================
(Bill) These Conversion Formulas will likely move to Section 2.7 Fixed-Point
Data Conversions (RGB to sRGB and sRGB to RGB) and section 2.6 Numeric
Representation and Computation (RGB to Shared Exponent and Shared Exponent
to RGB)
==================
endif::editing-notes[]
[[textures-RGB-sexp]]
=== RGB to Shared Exponent Conversion
An RGB color latexmath:[$(red, green, blue)$] is transformed to a shared
exponent color latexmath:[$(red_{shared}, green_{shared}, blue_{shared},
exp_{shared})$] as follows:
First, the components latexmath:[$(red, green, blue)$] are clamped to
latexmath:[$(red_{clamped}, green_{clamped}, blue_{clamped})$] as:
[latexmath]
+++++++++++++++++++
\begin{align*}
red_{clamped} & = \max(0,min(sharedexp_{max},red)) \\
green_{clamped} & = \max(0,min(sharedexp_{max},green)) \\
blue_{clamped} & = \max(0,min(sharedexp_{max},blue))
\end{align*}
+++++++++++++++++++
Where:
[latexmath]
+++++++++++++++++++
\begin{align*}
N & = 9 & \textrm{number of mantissa bits per component} \\
B & = 15 & \textrm{exponent bias} \\
E_{max} & = 31 & \textrm{maximum possible biased exponent value} \\
sharedexp_{max} & = \frac{(2^N-1)}{2^N} \times 2^{(E_{max}-B)}
\end{align*}
+++++++++++++++++++
[NOTE]
.Note
==================
latexmath:[$NaN$], if supported, is handled as in IEEE 754-2008 minNum() and
maxNum(). That is the result is a latexmath:[$NaN$] is mapped to zero.
==================
The largest clamped component, latexmath:[$max_{clamped}$] is determined:
[latexmath]
+++++++++++++++++++
\begin{align*}
max_{clamped} = \max(red_{clamped},green_{clamped},blue_{clamped})
\end{align*}
+++++++++++++++++++
A preliminary shared exponent latexmath:[$exp'$] is computed:
[latexmath]
+++++++++++++++++++
\begin{align*}
exp' =
\begin{cases}
\left \lfloor \log_2(max_{clamped}) \right \rfloor + (B+1)
& \textrm{for } max_{clamped} > 2^{-(B+1)} \\
0
& \textrm{for } max_{clamped} \leq 2^{-(B+1)}
\end{cases}
\end{align*}
+++++++++++++++++++
The shared exponent latexmath:[$exp_{shared}$] is computed:
[latexmath]
+++++++++++++++++++
\begin{align*}
max_{shared} =
\left \lfloor
\frac{max_{clamped}}{2^{(exp'-B-N)}}+\frac{1}{2}
\right \rfloor
\end{align*}
+++++++++++++++++++
[latexmath]
+++++++++++++++++++
\begin{align*}
exp_{shared} =
\begin{cases}
exp' & \textrm{for } 0 \leq max_{shared} < 2^N \\
exp'+1 & \textrm{for } max_{shared} = 2^N
\end{cases}
\end{align*}
+++++++++++++++++++
Finally, three integer values in the range latexmath:[$0$] to
latexmath:[$2^N$] are computed:
[latexmath]
+++++++++++++++++++
\begin{align*}
red_{shared} & =
\left \lfloor
\frac{red_{clamped}}{2^{(exp_{shared}-B-N)}}+ \frac{1}{2}
\right \rfloor \\
green_{shared} & =
\left \lfloor
\frac{green_{clamped}}{2^{(exp_{shared}-B-N)}}+ \frac{1}{2}
\right \rfloor \\
blue_{shared} & =
\left \lfloor
\frac{blue_{clamped}}{2^{(exp_{shared}-B-N)}}+ \frac{1}{2}
\right \rfloor
\end{align*}
+++++++++++++++++++
[[textures-sexp-RGB]]
=== Shared Exponent to RGB
A shared exponent color latexmath:[$(red_{shared}, green_{shared},
blue_{shared}, exp_{shared})$] is transformed to an RGB color
latexmath:[$(red, green, blue)$] as follows:
[latexmath]
+++++++++++++++++++
\begin{align*}
red & = red_{shared}\times 2^{(exp_{shared}-B-N)} \\
green & = green_{shared}\times 2^{(exp_{shared}-B-N)} \\
blue & = blue_{shared}\times 2^{(exp_{shared}-B-N)} \\
\end{align*}
+++++++++++++++++++
Where:
[latexmath]
+++++++++++++++++++
\begin{align*}
N & = 9 & \textrm{number of mantissa bits per component} \\
B & = 15 & \textrm{exponent bias}
\end{align*}
+++++++++++++++++++
== Texel Input Operations
_Texel input instructions_ are SPIR-V image instructions that read from an
image. _Texel input operations_ are a set of steps that are performed on
state, coordinates, and texel values while processing a texel input
instruction, and which are common to some or all texel input instructions.
They include the following steps, which are performed in the listed order:
* <<textures-input-validation,Validation operations>>
** <<textures-operation-validation,Instruction/Sampler/Image validation>>
** <<textures-integer-coordinate-validation,Coordinate validation>>
** <<textures-sparse-validation,Sparse validation>>
* <<textures-format-conversion,Format conversion>>
* <<textures-texel-replacement,Texel replacement>>
* <<textures-depth-compare-operation,Depth comparison>>
* <<textures-conversion-to-rgba,Conversion to RGBA>>
* <<textures-component-swizzle,Component swizzle>>
For texel input instructions involving multiple texels (for sampling or
gathering), these steps are applied for each texel that is used in the
instruction. Depending on the type of image instruction, other steps are
conditionally performed between these steps or involving multiple coordinate
or texel values.
[[textures-input-validation]]
=== Texel Input Validation Operations
_Texel input validation operations_ inspect instruction/image/sampler state
or coordinates, and in certain circumstances cause the texel value to be
replaced or become undefined. There are a series of validations that the
texel undergoes.
[[textures-operation-validation]]
==== Instruction/Sampler/Image Validation
There are a number of cases where a SPIR-V instruction can: mismatch with
the sampler, the image, or both. There are a number of cases where the
sampler can: mismatch with the image. In such cases the value of the texel
returned is undefined.
These cases include:
* The sampler pname:borderColor is an integer type and the image
pname:format is not one of the elink:VkFormat integer types or a stencil
aspect of a depth/stencil format.
* The sampler pname:borderColor is a float type and the image pname:format
is not one of the elink:VkFormat float types or a depth aspect of a
depth/stencil format.
* The sampler pname:borderColor is one of the opaque black colors
(ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK or
ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK) and the image
elink:VkComponentSwizzle for any of the slink:VkComponentMapping
components is not ename:VK_COMPONENT_SWIZZLE_IDENTITY.
* If the instruction is code:OpImageRead or code:OpImageSparseRead and the
pname:shaderStorageImageReadWithoutFormat feature is not enabled, or the
instruction is code:OpImageWrite and the
pname:shaderStorageImageWriteWithoutFormat feature is not enabled, then
the SPIR-V Image Format must: be <<spirvenv-image-formats,compatible>>
with the image view's pname:format.
* The sampler pname:unnormalizedCoordinates is ename:VK_TRUE and any of
the <<samplers-unnormalizedCoordinates,limitations of unnormalized
coordinates>> are violated.
* The SPIR-V instruction is one of the code:OpImage*code:Dref*
instructions and the sampler pname:compareEnable is ename:VK_FALSE
* The SPIR-V instruction is not one of the code:OpImage*code:Dref*
instructions and the sampler pname:compareEnable is ename:VK_TRUE
* The SPIR-V instruction is one of the code:OpImage*code:Dref*
instructions and the image pname:format is not one of the depth/stencil
formats with a depth component, or the image aspect is not
ename:VK_IMAGE_ASPECT_DEPTH_BIT.
* The SPIR-V instruction's image variable's properties are not compatible
with the image view:
** Rules for pname:viewType:
*** ename:VK_IMAGE_VIEW_TYPE_1D must: have code:Dim = 1D, code:Arrayed =
0, code:MS = 0.
*** ename:VK_IMAGE_VIEW_TYPE_2D must: have code:Dim = 2D, code:Arrayed = 0.
*** ename:VK_IMAGE_VIEW_TYPE_3D must: have code:Dim = 3D, code:Arrayed =
0, code:MS = 0.
*** ename:VK_IMAGE_VIEW_TYPE_CUBE must: have code:Dim = Cube, code:Arrayed
= 0, code:MS = 0.
*** ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY must: have code:Dim = 1D,
code:Arrayed = 1, code:MS = 0.
*** ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY must: have code:Dim = 2D,
code:Arrayed = 1.
*** ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY must: have code:Dim = Cube,
code:Arrayed = 1, code:MS = 0.
** If the image's pname:samples is not equal to
ename:VK_SAMPLE_COUNT_1_BIT, the instruction must: have code:MS = 1.
[[textures-integer-coordinate-validation]]
==== Integer Texel Coordinate Validation
Integer texel coordinates are validated against the size of the image level,
and the number of layers and number of samples in the image. For SPIR-V
instructions that use integer texel coordinates, this is performed directly
on the integer coordinates. For instructions that use normalized or
unnormalized texel coordinates, this is performed on the coordinates that
result after <<textures-unnormalized-to-integer,conversion>> to integer
texel coordinates.
If the integer texel coordinates satisfy any of the conditions
[latexmath]
+++++++++++++++++++
\begin{align*}
i & < 0 & i \geq w_{s} \\
j & < 0 & j \geq h_{s} \\
k & < 0 & k \geq d_{s} \\
l & < 0 & l \geq layers \\
n & < 0 & n \geq samples
\end{align*}
+++++++++++++++++++
where:
[latexmath]
+++++++++++++++++++
\begin{align*}
& w_{s} & = \textrm{width of the image level} \\
& h_{s} & = \textrm{height of the image level} \\
& d_{s} & = \textrm{depth of the image level} \\
& layers & = \textrm{number of layers in the image} \\
& samples & = \textrm{number of samples per texel in the image}
\end{align*}
+++++++++++++++++++
then the texel fails integer texel coordinate validation.
There are four cases to consider:
* Valid Texel Coordinates
** If the texel coordinates pass validation (that is, the coordinates lie
within the image),
+
then the texel value comes from the value in image memory.
* Border Texel
** If the texel coordinates fail validation, and
** If the read is the result of an image sample instruction or image gather
instruction, and
** If the image is not a cube image,
+
then the texel is a border texel and
<<textures-texel-replacement,texel replacement>> is performed.
* Invalid Texel
** If the texel coordinates fail validation, and
** If the read is the result of an image fetch instruction, image read
instruction, or atomic instruction,
+
then the texel is an invalid texel and <<textures-texel-replacement,texel
replacement>> is performed.
* Cube Map Edge or Corner
** Otherwise the texel coordinates lie on the borders along the edges and
corners of a cube map image, and
<<textures-cubemapedge,Cube map edge handling>> is performed.
[[textures-cubemapedge]]
==== Cube Map Edge Handling
If the texel coordinates lie on the borders along the edges and corners of a
cube map image, the following steps are performed. Note that this only
occurs when using ename:VK_FILTER_LINEAR filtering within a miplevel, since
ename:VK_FILTER_NEAREST is treated as using
ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE.
* Cube Map Edge Texel
** If the texel lies along the border in either only latexmath:[$i$] or only
latexmath:[$j$]
+
then the texel lies along an edge, so the coordinates latexmath:[$(i,j)$]
and the array layer latexmath:[$l$] are transformed to select the adjacent
texel from the appropriate neighboring face.
* Cube Map Corner Texel
** If the texel lies along the border in both latexmath:[$i$] and
latexmath:[$j$]
+
then the texel lies at the corner and there is no unique neighboring face
from which to read that texel. The texel should: be replaced by the average
of the three values of the adjacent texels in each incident face. However,
implementations may: replace the cube map corner texel by other methods,
subject to the constraint that if the three available samples have the same
value, the replacement texel also has that value.
[[textures-sparse-validation]]
==== Sparse Validation
If the texel reads from an unbound region of a sparse image, the texel is a
_sparse unbound texel_, and processing continues with
<<textures-texel-replacement,texel replacement>>.
[[textures-format-conversion]]
=== Format Conversion
Texels undergo a format conversion from the elink:VkFormat of the image view
to a vector of either floating point or signed or unsigned integer
components, with the number of components based on the number of components
present in the format.
* Color formats have one, two, three, or four components, according to the
format.
* Depth/stencil formats are one component. The depth or stencil component
is selected by the pname:aspectMask of the image view.
Each component is converted based on its type and size (as defined in the
<<features-formats-definition,Format Definition>> section for each
elink:VkFormat), using the appropriate equations in
<<fundamentals-fp16,16-Bit Floating-Point Numbers>>,
<<fundamentals-fp11,Unsigned 11-Bit Floating-Point Numbers>>,
<<fundamentals-fp10,Unsigned 10-Bit Floating-Point Numbers>>,
<<fundamentals-fixedconv,Fixed-Point Data Conversion>>, and
<<textures-sexp-RGB,Shared Exponent to RGB>>. Signed integer components
smaller than 32 bits are sign-extended.
If the image format is sRGB, the color components are first converted as if
they are UNORM, and then sRGB to linear conversion is applied to the R, G,
and B components as described in the ``KHR_DF_TRANSFER_SRGB'' section of the
Khronos Data Format Specification. The A component, if present, is
unchanged.
If the image view format is block-compressed, then the texel value is first
decoded, then converted based on the type and number of components defined
by the compressed format.
[[textures-texel-replacement]]
=== Texel Replacement
A texel is replaced if it is one (and only one) of:
* a border texel, or
* an invalid texel, or
* a sparse unbound texel.
Border texels are replaced with a value based on the image format and the
pname:borderColor of the sampler. The border color is:
[[textures-border-replacement-color]]
.Border Color latexmath:[$B$]
[options="header",cols="60%,40%"]
|====
| Sampler pname:borderColor | Corresponding Border Color
| ename:VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK | latexmath:[$B = (0.0, 0.0, 0.0, 0.0)$]
| ename:VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK | latexmath:[$B = (0.0, 0.0, 0.0, 1.0)$]
| ename:VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE | latexmath:[$B = (1.0, 1.0, 1.0, 1.0)$]
| ename:VK_BORDER_COLOR_INT_TRANSPARENT_BLACK | latexmath:[$B = (0, 0, 0, 0)$]
| ename:VK_BORDER_COLOR_INT_OPAQUE_BLACK | latexmath:[$B = (0, 0, 0, 1)$]
| ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE | latexmath:[$B = (1, 1, 1, 1)$]
|====
[NOTE]
.Note
====
The names etext:TRANSPARENT_BLACK, etext:OPAQUE_BLACK, and etext:OPAQUE_WHITE
are meant to describe which components are zeros and ones in the vocabulary of
compositing, and are not meant to imply that the numerical value of
etext:WHITE is a saturating value for integers.
====
This is substituted for the texel value by replacing the number of components
in the image format
[[textures-border-replacement-table]]
.Border Texel Components After Replacement
[width="80%",options="header"]
|====
| Texel Aspect or Format | Component Assignment
| Depth aspect | latexmath:[$D = (B_{r})$]
| Stencil aspect | latexmath:[$S = (B_{r})$]
| One component color format | latexmath:[$C_{r} = (B_{r})$]
| Two component color format | latexmath:[$C_{rg} = (B_{r},B_{g})$]
| Three component color format| latexmath:[$C_{rgb} = (B_{r},B_{g},B_{b})$]
| Four component color format | latexmath:[$C_{rgba} = (B_{r},B_{g},B_{b},B_{a})$]
|====
If the read operation is from a buffer resource, and the
pname:robustBufferAccess feature is enabled, an invalid texel is replaced as
described <<features-features-robustBufferAccess,here>>.
If the pname:robustBufferAccess feature is not enabled, the value of an
invalid texel is undefined.
ifdef::editing-notes[]
[NOTE]
.editing-note
==================
(Bill) This is not currently catching this significant case.
For opImageFetch, which fetches from an *image* not a buffer, the
result is defined if pname:robustBufferAccess is enabled.
==================
endif::editing-notes[]
If the sname:VkPhysicalDeviceSparseProperties property
pname:residencyNonResidentStrict is true, a sparse unbound texel is replaced
with 0 or 0.0 values for integer and floating-point components of the image
format, respectively.
If pname:residencyNonResidentStrict is false, the read must: be safe, but
the value of the sparse unbound texel is undefined.
[[textures-depth-compare-operation]]
=== Depth Compare Operation
If the image view has a depth/stencil format, the depth component is
selected by the pname:aspectMask, and the operation is a code:Dref
instruction, a depth comparison is performed. The value of the
result latexmath:[$D$] is latexmath:[$1.0$] if the result of the
compare operation is latexmath:[$true$], and latexmath:[$0.0$]
otherwise. The compare operation is selected by the pname:compareOp
member of the sampler.
[latexmath]
+++++++++++++++++++
\begin{align*}
D & = 1.0 &
\begin{cases}
D_{ref} \leq D & \textrm{for LEQUAL} \\
D_{ref} \geq D & \textrm{for GEQUAL} \\
D_{ref} < D & \textrm{for LESS} \\
D_{ref} > D & \textrm{for GREATER} \\
D_{ref} = D & \textrm{for EQUAL} \\
D_{ref} \neq D & \textrm{for NOTEQUAL} \\
true & \textrm{for ALWAYS} \\
false & \textrm{for NEVER}
\end{cases} \\
D & = 0.0 & \textrm{otherwise}
\end{align*}
+++++++++++++++++++
where, in the depth comparison:
[latexmath]
+++++++++++++++++++
\begin{align*}
& D_{ref} = shaderOp.D_{ref} & \textrm{(from optional SPIR-V operand)} \\
& D & \textrm{texel depth value}
\end{align*}
+++++++++++++++++++
[[textures-conversion-to-rgba]]
=== Conversion to RGBA
The texel is expanded from one, two, or three to four components based on
the image base color:
[[textures-texel-color-rgba-conversion-table]]
.Texel Color After Conversion To RGBA
[options="header"]
|====
| Texel Aspect or Format | RGBA Color
| Depth aspect | latexmath:[$C_{rgba} = (D,0,0,one)$]
| Stencil aspect | latexmath:[$C_{rgba} = (S,0,0,one)$]
| One component color format | latexmath:[$C_{rgba} = (C_{r},0,0,one)$]
| Two component color format | latexmath:[$C_{rgba} = (C_{rg},0,one)$]
| Three component color format| latexmath:[$C_{rgba} = (C_{rgb},one)$]
| Four component color format | latexmath:[$C_{rgba} = C_{rgba}$]
|====
where latexmath:[$one = 1.0f$] for floating-point formats and depth aspects,
and latexmath:[$one = 1$] for integer formats and stencil aspects.
[[textures-component-swizzle]]
=== Component Swizzle
All texel input instructions apply a _swizzle_ based on the
elink:VkComponentSwizzle enums in the pname:components member of the
slink:VkImageViewCreateInfo structure for the image being read. The swizzle
can: rearrange the components of the texel, or substitute zero and one for
any components. It is defined as follows for the R component, and operates
similarly for the other components.
[latexmath]
+++++++++++++++++++
\begin{align*}
C'_{rgba}[R] & =
\begin{cases}
C_{rgba}[R] & \textrm{for RED swizzle} \\
C_{rgba}[G] & \textrm{for GREEN swizzle} \\
C_{rgba}[B] & \textrm{for BLUE swizzle} \\
C_{rgba}[A] & \textrm{for ALPHA swizzle} \\
0 & \textrm{for ZERO swizzle} \\
one & \textrm{for ONE swizzle} \\
C_{rgba}[R] & \textrm{for IDENTITY swizzle}
\end{cases}
\end{align*}
+++++++++++++++++++
where:
[latexmath]
+++++++++++++++++++
\begin{align*}
C_{rgba}[R] & \textrm{is the RED component} \\
C_{rgba}[G] & \textrm{is the GREEN component} \\
C_{rgba}[B] & \textrm{is the BLUE component} \\
C_{rgba}[A] & \textrm{is the ALPHA component} \\
one & = 1.0\textrm{f} & \textrm{for floating point components} \\
one & = 1 & \textrm{for integer components}
\end{align*}
+++++++++++++++++++
For each component this is applied to, the
ename:VK_COMPONENT_SWIZZLE_IDENTITY swizzle selects the corresponding
component from latexmath:[$C_{rgba}$].
If the border color is one of the etext:VK_BORDER_COLOR_*_OPAQUE_BLACK enums
and the elink:VkComponentSwizzle is not ename:VK_COMPONENT_SWIZZLE_IDENTITY
for all components (or the
<<resources-image-views-identity-mappings,equivalent identity mapping>>),
the value of the texel after swizzle is undefined.
[[textures-sparse-residency]]
=== Sparse Residency
code:OpImageSparse* instructions return a structure which includes a
_residency code_ indicating whether any texels accessed by the instruction
are sparse unbound texels. This code can: be interpreted by the
code:OpImageSparseTexelsResident instruction which converts the residency
code to a boolean value.
== Texel Output Operations
_Texel output instructions_ are SPIR-V image instructions that write to an
image. _Texel output operations_ are a set of steps that are performed on
state, coordinates, and texel values while processing a texel output
instruction, and which are common to some or all texel output instructions.
They include the following steps, which are performed in the listed order:
* <<textures-output-validation,Validation operations>>
** <<textures-format-validation,Format validation>>
** <<textures-output-coordinate-validation,Coordinate validation>>
** <<textures-output-sparse-validation,Sparse validation>>
* <<textures-output-format-conversion,Texel output format conversion>>
[[textures-output-validation]]
=== Texel Output Validation Operations
_Texel output validation operations_ inspect instruction/image state or
coordinates, and in certain circumstances cause the write to have no effect.
There are a series of validations that the texel undergoes.
[[textures-format-validation]]
==== Texel Format Validation
If the image format of the code:OpTypeImage is not compatible with the
sname:VkImageView's pname:format, the effect of the write on the image
view's memory is undefined, but the write mustnot: access memory outside of
the image view.
[[textures-output-coordinate-validation]]
=== Integer Texel Coordinate Validation
The integer texel coordinates are validated according to the same rules as
for texel input
<<textures-integer-coordinate-validation,coordinate validation>>.
If the texel fails integer texel coordinate validation, then the write has
no effect.
[[textures-output-sparse-validation]]
=== Sparse Texel Operation
If the texel attempts to write to an unbound region of a sparse image, the
texel is a sparse unbound texel. In such a case, if the
sname:VkPhysicalDeviceSparseProperties property
pname:residencyNonResidentStrict is ename:VK_TRUE, the sparse unbound texel
write has no effect. If pname:residencyNonResidentStrict is ename:VK_FALSE,
the effect of the write is undefined but must: be safe. In addition, the
write may: have a side effect that is visible to other image instructions,
but mustnot: be written to any device memory allocation.
[[textures-output-format-conversion]]
=== Texel Output Format Conversion
Texels undergo a format conversion from the floating point, signed, or
unsigned integer type of the texel data to the elink:VkFormat of the image
view. Any unused components are ignored.
Each component is converted based on its type and size (as defined in the
<<features-formats-definition,Format Definition>> section for each
elink:VkFormat), using the appropriate equations in
<<fundamentals-fp16,16-Bit Floating-Point Numbers>> and
<<fundamentals-fixedconv,Fixed-Point Data Conversion>>.
== Derivative Operations
SPIR-V derivative instructions include code:OpDPdx, code:OpDPdy,
code:OpDPdxFine, code:OpDPdyFine, code:OpDPdxCoarse, and code:OpDPdyCoarse.
Derivative instructions are only available in a fragment shader.
image::images/vulkantexture2.png[Title="Implicit derivatives",align="left", scaledwidth="50%"]
Derivatives are computed as if there is a 2x2 neighborhood of fragments for
each fragment shader invocation. These neighboring fragments are used to
compute derivatives with the assumption that the values of P in the
neighborhood are piecewise linear. It is further assumed that the values of
P in the neighborhood are locally continuous, therefore derivatives in
non-uniform control flow are undefined.
[latexmath]
+++++++++++++++++++
\begin{align*}
dPdx_{i_1,j_0} & = dPdx_{i_0,j_0} & = P_{i_1,j_0} - P_{i_0,j_0} \\
dPdx_{i_1,j_1} & = dPdx_{i_0,j_1} & = P_{i_1,j_1} - P_{i_0,j_1} \\
\\
dPdy_{i_0,j_1} & = dPdy_{i_0,j_0} & = P_{i_0,j_1} - P_{i_0,j_0} \\
dPdy_{i_1,j_1} & = dPdy_{i_1,j_0} & = P_{i_1,j_1} - P_{i_1,j_0}
\end{align*}
+++++++++++++++++++
The code:Fine derivative instructions must: return the values above, for a
group of fragments in a 2x2 neighborhood. Coarse derivatives may: return
only two values. In this case, the values should: be:
[latexmath]
+++++++++++++++++++
\begin{align*}
dPdx & =
\begin{cases}
dPdx_{i_0,j_0} & \textrm{preferred}\\
dPdx_{i_0,j_1}
\end{cases} \\
dPdy & =
\begin{cases}
dPdy_{i_0,j_0} & \textrm{preferred}\\
dPdy_{i_1,j_0}
\end{cases}
\end{align*}
+++++++++++++++++++
code:OpDPdx and code:OpDPdy must: return the same result as either
code:OpDPdxFine or code:OpDPdxCoarse and either code:OpDPdyFine or
code:OpDPdyCoarse, respectively. Implementations must: make the same choice
of either coarse or fine for both code:OpDPdx and code:OpDPdy, and
implementations should: make the choice that is more efficient to compute.
[[textures-normalized-operations]]
== Normalized Texel Coordinate Operations
If the image sampler instruction provides normalized texel coordinates, some
of the following operations are performed.
[[textures-projection]]
=== Projection Operation
For code:Proj image operations, the normalized texel coordinates
latexmath:[$(s,t,r,q,a)$] and (if present) the latexmath:[$D_{ref}$]
coordinate are transformed as follows:
[latexmath]
+++++++++++++++++++
\begin{align*}
s & = \frac{s}{q}, & \textrm{for 1D, 2D, or 3D image} \\
\\
t & = \frac{t}{q}, & \textrm{for 2D or 3D image} \\
\\
r & = \frac{r}{q}, & \textrm{for 3D image} \\
\\
D_{ref} & = \frac{D_{ref}}{q}, & \textrm{if provided}
\end{align*}
+++++++++++++++++++
=== Derivative Image Operations
Derivatives are used for level-of-detail selection. These derivatives are
either implicit (in an code:ImplicitLod image instruction in a fragment
shader) or explicit (provided explicitly by shader to the image instruction
in any shader).
For implicit derivatives image instructions, the derivatives of texel
coordinates are calculated in the same manner as derivative operations
above. That is:
[latexmath]
+++++++++++++++++++
\begin{align*}
\partial{s}/\partial{x} & = dPdx(s), & \partial{s}/\partial{y} & = dPdy(s), & \textrm{for 1D, 2D, Cube, or 3D image} \\
\partial{t}/\partial{x} & = dPdx(t), & \partial{t}/\partial{y} & = dPdy(t), & \textrm{for 2D, Cube, or 3D image} \\
\partial{u}/\partial{x} & = dPdx(u), & \partial{u}/\partial{y} & = dPdy(u), & \textrm{for Cube or 3D image}
\end{align*}
+++++++++++++++++++
Partial derivatives not defined above for certain image dimensionalities are
set to zero.
For explicit level-of-detail image instructions, if the optional: SPIR-V
operand latexmath:[$Grad$] is provided, then the operand values are used for
the derivatives. The number of components present in each derivative for a
given image dimensionality matches the number of partial derivatives
computed above.
If the optional: SPIR-V operand latexmath:[$Lod$] is provided, then
derivatives are set to zero, the cube map derivative transformation is
skipped, and the scale factor operation is skipped. Instead, the floating
point scalar coordinate is directly assigned to latexmath:[$\lambda_{base}$]
as described in <<textures-level-of-detail-operation,Level-of-Detail
Operation>>.
=== Cube Map Face Selection and Transformations
For cube map image instructions, the latexmath:[$(s,t,r)$] coordinates are
treated as a direction vector latexmath:[$(r_{x},r_{y},r_{z})$]. The
direction vector is used to select a cube map face. The direction vector is
transformed to a per-face texel coordinate system
latexmath:[$(s_{face},t_{face})$]. The direction vector is also used to
transform the derivatives to per-face derivatives.
=== Cube Map Face Selection
The direction vector selects one of the cube map's faces based on the
largest magnitude coordinate direction (the major axis direction). Since two
or more coordinates can: have identical magnitude, the implementation must:
have rules to disambiguate this situation.
The rules should: have as the first rule that latexmath:[$r_{z}$] wins over
latexmath:[$r_{y}$] and latexmath:[$r_{x}$], and the second rule that
latexmath:[$r_{y}$] wins over latexmath:[$r_{x}$]. An implementation may:
choose other rules, but the rules must: be deterministic and depend only on
latexmath:[$(r_{x},r_{y},r_{z})$].
The layer number (corresponding to a cube map face), the coordinate
selections for latexmath:[$s_{c}$], latexmath:[$t_{c}$],
latexmath:[$r_{c}$], and the selection of derivatives, are determined by the
major axis direction as specified in the following two tables.
.Cube map face and coordinate selection
[width="75%",frame="all",options="header"]
|======================
|Major Axis Direction|Layer Number|Cube Map Face|latexmath:[$s_{c}$]|latexmath:[$t_{c}$]|latexmath:[$r_{c}$]
|latexmath:[$+r_{x}$]|latexmath:[$0$]|latexmath:[$Positive X$]|latexmath:[$-r_{z}$]|latexmath:[$-r_{y}$]|latexmath:[$r_{x}$]
|latexmath:[$-r_{x}$]|latexmath:[$1$]|latexmath:[$Negative X$]|latexmath:[$+r_{z}$]|latexmath:[$-r_{y}$]|latexmath:[$r_{x}$]
|latexmath:[$+r_{y}$]|latexmath:[$2$]|latexmath:[$Positive Y$]|latexmath:[$+r_{x}$]|latexmath:[$+r_{z}$]|latexmath:[$r_{y}$]
|latexmath:[$-r_{y}$]|latexmath:[$3$]|latexmath:[$Negative Y$]|latexmath:[$+r_{x}$]|latexmath:[$-r_{z}$]|latexmath:[$r_{y}$]
|latexmath:[$+r_{z}$]|latexmath:[$4$]|latexmath:[$Positive Z$]|latexmath:[$+r_{x}$]|latexmath:[$-r_{y}$]|latexmath:[$r_{z}$]
|latexmath:[$-r_{z}$]|latexmath:[$5$]|latexmath:[$Negative Z$]|latexmath:[$-r_{x}$]|latexmath:[$-r_{y}$]|latexmath:[$r_{z}$]
|======================
.Cube map derivative selection
[width="75%",frame="all",options="header"]
|======================
|Major Axis Direction|latexmath:[$\partial{s_{c}}/\partial{x}$]|latexmath:[$\partial{s_{c}}/\partial{y}$]|latexmath:[$\partial{t_{c}}/\partial{x}$]|latexmath:[$\partial{t_{c}}/\partial{y}$]|latexmath:[$\partial{r_{c}}/\partial{x}$]|latexmath:[$\partial{r_{c}}/\partial{y}$]
|latexmath:[$+r_{x}$]
|latexmath:[$-\partial{r_{z}}/\partial{x}$]|latexmath:[$-\partial{r_{z}}/\partial{y}$]
|latexmath:[$-\partial{r_{y}}/\partial{x}$]|latexmath:[$-\partial{r_{y}}/\partial{y}$]
|latexmath:[$+\partial{r_{x}}/\partial{x}$]|latexmath:[$+\partial{r_{x}}/\partial{y}$]
|latexmath:[$-r_{x}$]
|latexmath:[$+\partial{r_{z}}/\partial{x}$]|latexmath:[$+\partial{r_{z}}/\partial{y}$]
|latexmath:[$-\partial{r_{y}}/\partial{x}$]|latexmath:[$-\partial{r_{y}}/\partial{y}$]
|latexmath:[$-\partial{r_{x}}/\partial{x}$]|latexmath:[$-\partial{r_{x}}/\partial{y}$]
|latexmath:[$+r_{y}$]
|latexmath:[$+\partial{r_{x}}/\partial{x}$]|latexmath:[$+\partial{r_{x}}/\partial{y}$]
|latexmath:[$+\partial{r_{z}}/\partial{x}$]|latexmath:[$+\partial{r_{z}}/\partial{y}$]
|latexmath:[$+\partial{r_{y}}/\partial{x}$]|latexmath:[$+\partial{r_{y}}/\partial{y}$]