Металлическая стандартная библиотека

В этой главе описываются функции, поддерживаемые Металлической библиотекой стандарта языка штриховки.

Пространство имен и заголовочные файлы

Металлические стандартные библиотечные функции и перечисления объявляются в metal пространство имен. В дополнение к заголовочным файлам, описанным в Металлических стандартных библиотечных функциях, <metal_stdlib> заголовок доступен и может получить доступ ко всем функциям, поддерживаемым Металлической стандартной библиотекой.

Общие функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_common>. T один из скалярных или векторных типов с плавающей точкой.

T clamp(T x, T minval, T maxval)
- Возвраты fmin(fmax(x, minval), maxval). Результаты не определены если minval > maxval.
T mix(T x, T y, T a)
- Возвращает линейное смешение x и y реализованный как: x + (y – x ) * a.
- a должно быть значение в диапазоне 0,0 … 1.0. Если a не находится в диапазоне 0,0 … 1.0, возвращаемые значения не определены.
T saturate(T x)
- Зажим x в диапазоне 0,0 к 1,0.
T sign(T x)
- Возвраты 1.0, если x > 0,-0.0, если x =-0.0, +0.0, если x = +0.0, или-1.0, если x <0. Возвраты 0.0, если x NaN.
T smoothstep(T edge0, T edge1, T x)
- Возвраты 0.0, если x <= edge0 и 1.0, если x >= edge1 и выполняет гладкую интерполяцию Эрмита между 0 и 1 когда edge0 < x < edge1. Это полезно в случаях, где Вы хотите пороговую функцию с плавным переходом. Результаты не определены если edge0 >= edge1 или если x, edge0 или edge1 NaN. Это эквивалентно:
  t = clamp((x – edge0)/(edge1 – edge0), 0, 1);
  return t * t * (3 – 2 * t);
T step(T edge, T x)
- Возвраты 0.0, если x < edge, иначе это возвращается 1.0.

Для одинарной точности, с плавающей точкой, Металлической также, поддерживает точный и быстрый вариант следующих общих функций: clamp и saturate. Различие между быстрыми и точными вариантами - то, как обрабатываются NaNs. В быстром варианте поведение NaNs не определено, тогда как точные варианты соблюдают правила IEEE 754 для обработки NaN. -ffast-math параметр компилятора (см. Математику Опции Intrinsics) используется для выбора надлежащего варианта при компиляции Металлического источника. Кроме того, metal::precise и metal::fast вложенные пространства имен доступны для обеспечения разработчиков способ явно выбрать быстрый или точный вариант этих общих функций, соответственно.

Целочисленные функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_integer>. T один из скалярных или векторных целых типов. Tu соответствующий скалярный или векторный целый тип без знака.

T abs(T x))
- Возвраты | x |.
Tu absdiff(T x, T y)
- Возвраты | x – y | без переполнения по модулю.
T clamp(T x, T minval, T maxval)
- Возвраты min(max(x, minval), maxval). Результаты не определены если minval > maxval.
T clz(T x)
- Возвращает число ведущих 0 битов в x, запуск в старшей значащей позиции двоичного разряда. Если x 0, возвращает размер в битах типа x или тип компонента x, если x вектор.
T ctz(T x)
- Возвращает количество запаздывающих 0 битов в x. Если x 0, возвращает размер в битах типа x или тип компонента x, если x вектор.
T hadd(T x, T y)
- Возвраты (x + y)>> 1. Промежуточная сумма по модулю не переполняется.
T madhi(T a, T b, T c)
- Возвраты mulhi(a, b) + c.
T madsat(T a, T b, T c)
- Возвраты a * b + c и насыщает результат.
T max(T x, T y)
- Возвраты y если x < y; иначе, это возвращается x.
T min(T x, T x)
- Возвраты y если y < x; иначе, это возвращается x.
T mulhi(T x, T y)
- Вычисляет x * y и возвращает высокую половину продукта x и y.
T popcount(T x)
- Возвращает число ненулевых битов в x.
T rhadd(T x, T y)
- Возвраты (x + y + 1)>> 1. Промежуточная сумма по модулю не переполняется.
T rotate(T v, T i)
- Для каждого элемента в v, биты смещаются оставленные числом битов, данных соответствующим элементом в i. Биты отложили левую сторону элемента, переключаются на нижний регистр назад от права.
T subsat(T x, T y)
- Возвраты x - y и насыщает результат.

Реляционные функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_relational>. T один из скалярных или векторных типов с плавающей точкой. Ti один из скалярных или векторных целочисленных или булевых типов. Tb относится только к скалярным или векторным булевым типам.

bool all(Tb x)
- Возвращает true только если все компоненты x истина.
bool any(Tb x)
- Возвращает true только если любой компонент x истина.
Tb isfinite(T x)
- Тесты для конечного значения.
Tb isinf(T x)
- Тесты для значения бесконечности (положительный или отрицательный).
Tb isnan(T x)
- Тесты для NaN.
Tb isnormal(T x)
- Тесты для нормального значения.
Tb isordered(T x, T y)
- Тесты, ли параметры x и y упорядочиваются. Возвращает результат (x == x) && (y == y).
Tb isunordered(T x, T y)
- Тесты, ли параметры x и y не упорядочиваются. Возвращает true если x или y NaN и ложь иначе.
Tb not(Tb x)
- Возвращает покомпонентное логическое дополнение x.
T select(T a, T b, Tb c)
Ti select(Ti a, Ti b, Tb c)
- Для каждого компонента типа вектора, result[i] = c[i] ? b[i] : a[i].
  Для скалярного типа, result = c ? b : a.
Tb signbit(T x)
- Тесты для знакового бита. Если знаковый бит установлен для значения с плавающей точкой в, возвращает true x и ложь иначе.

Математические функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_math>. T один из скалярных или векторных типов с плавающей точкой. Ti относится только к скалярным или векторным целым типам.

T abs(T x)
T fabs(T x)
- Вычисляет абсолютное значение x.
T acos(T x)
- Вычисляет функцию арккосинуса x.
T acosh(T x)
- Вычисляет гиперболический арккосинус x.
T asin(T x)
- Вычисляет функцию арксинуса x.
T asinh(T x)
- Вычисляет гиперболический арксинус x.
T atan(T y_over_x)
- Вычисляет функцию арктангенса y_over_x.
T atan2(T y, T x)
- Вычисляет арктангенс y x.
T atanh(T x)
- Вычисляет гиперболический арктангенс x.
T ceil(T x)
- Раунды x к интегральному значению с помощью раунда для положительного режима округления бесконечности.
T copysign(T x, T y)
- Возвраты x с его знаком, измененным для соответствия знака y.
T cos(T x)
- Вычисляет косинус x.
T cosh(T x)
- Вычисляет гиперболический косинус x.
T exp(T x)
- Вычисляет основной-e экспоненциал x.
T exp2(T x)
- Вычисляет основу 2 экспоненциала x.
T exp10(T x)
- Вычисляет основу 10 экспоненциалов x.
T fdim(T x, T y)
- Возвраты x – y если x > y, +0, если x меньше чем или равно y.
T floor(T x)
- Раунды x к интегральному значению с помощью раунда для отрицательного режима округления бесконечности.
T fmod(T x, T y)
- Возвраты x – y * trunc(x/y).
T fract(T x)
- Возвращает дробную часть x это больше, чем или равно 0 или меньше, чем 1.
T frexp(T x, Ti &exp)
- Извлекает мантиссу и экспоненту от x. Для каждого компонента возвратилась мантисса, плавание с величиной в интервале [1/2, 1) или 0. Каждый компонент x равняется мантиссе, возвращенной умноженный на ^2exp.
Ti ilogb(T x)
- Возвращает экспоненту как целочисленное значение.
T ldexp(T x, Ti k)
- Умножается x 2 к питанию k.
T log(T x)
- Вычисляет натуральный логарифм x.
T log2(T x)
- Вычисляет основу 2 логарифма x.
T log10(T x)
- Вычисляет основу 10 логарифмов x.
T max(T x, T y)
T fmax(T x, T y)
- Возвраты y если x < y; иначе, это возвращается x. Если одним параметром является NaN, fmax () возвращает другой параметр. Если обоими параметрами является NaN, fmax() возвращает NaN. (Поведение NaN допустимо только для precise::fmax и precise::max.)
T min(T x, T y)
T fmin(T x, T y)
- Возвраты y если y < x; иначе, это возвращается x. Если одним параметром является NaN, fmin () возвращает другой параметр. Если обоими параметрами является NaN, fmin() возвращает NaN. (Поведение NaN допустимо только для precise::fmin и precise::min.)
T modf(T x, T &intval)
- Анализирует число с плавающей точкой. modf функционируйте повреждает параметр x в неотъемлемые и дробные части, каждая из которых имеет тот же знак как параметр.
  Возвращает дробное значение. Интегральное значение возвращается в intval.
T pow(T x, T y)
- Вычисляет x к питанию y.
T powr(T x, T y)
- Вычисляет x к питанию y, где x > = 0.
T rint(T x)
- Раунды x к интегральному значению с помощью раунда для самого близкого даже округляющегося режима в формате с плавающей точкой.
T round(T x)
- Возвращает интегральное значение, самое близкое x округление промежуточных случаев далеко от нуля.
T rsqrt(T x)
- Вычисляет обратный квадратный корень x.
T sin(T x)
- Вычисляет синус x.
T sincos(T x, T &cosval)
- Вычисляет синус и косинус x. Вычисленный синус является возвращаемым значением, и вычисленный косинус возвращается в cosval.
T sinh(T x)
- Вычисляет гиперболический синус x.
T sqrt(T x)
- Вычисляет квадратный корень x.
T tan(T x)
- Вычисляет касательную x.
T tanh(T x)
- Вычисляет гиперболическую касательную x.
T trunc(T x)
- Раунды x к интегральному значению с помощью режима округления раунда к нулю.

Для одинарной точности, с плавающей точкой, Металлический язык штриховки поддерживает два варианта упомянутых выше математических функций: точное и быстрые варианты. Когда обработка значений NaN не определяется, при использовании быстрых вариантов математические функции выполняются более быстро, но работают по ограниченному диапазону и их поведению. Можно принять решение позволить точной математике вместо этого торговать производительностью для правильности.

-ffast-math параметр компилятора (отсылают к Математике Опции Intrinsics) используется для выбора надлежащего варианта при компиляции Металлического источника программы построения теней. Кроме того, metal::precise и metal::fast вложенные пространства имен также доступны и предоставляют разработчикам способ явно выбрать быстрый или точный вариант этих математических функций для одинарной точности, с плавающей точкой, как показано в Перечислении 5-1.

Перечисление 5-1 быстрые и точные варианты математических функций

#include <metal_stdlib>

using namespace metal;

float x;

float a = sin(x); // use fast or precise version based on compile option:

                  // - equivalent to fast::sin(x) if -ffast-math is specified

                  // - equivalent to precise::sin(x) if -fno-fast-math is specified

float b = fast::sin(x);    // use fast version of sin() always,

                           // regardless of compile option

float c = precise::cos(x); // use precise version of cos() always,

                           // regardless of compile option

Матричные функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_matrix>.

float determinant(floatnxn)
half determinant(halfnxn)
- Вычисляет детерминант matrix, который должен быть квадратной матрицей.
floatmxn transpose(floatnxm)
halfmxn transpose(halfnxm)
- Переместить matrix.

Например:

float4x4 mA;

float det = determinant(mA);

Геометрические функции

Функции в этом разделе находятся в Металлической стандартной библиотеке и определяются в заголовке <metal_geometric>. T векторный тип с плавающей точкой (floatn или halfn). Ts относится к соответствующему скалярному типу (т.е. float если T floatn и half если T halfn).

T cross(T x, T y)
- Возвращает векторное произведение x и y. T должен быть тип вектора с 3 компонентами.
Ts distance(T x, T y)
- Возвращает расстояние между x и y; т.е. length(x - y)
Ts distance_squared(T x, T y)
- Возвращает квадрат расстояния между x и y.
Ts dot(T x, T y)
- Возвращает скалярное произведение x и y; т.е. x[0] * y[0] + x[1] * y[1] + ...
T faceforward(T N, T I, T Nref)
- Если dot(Nref, I) < 0.0, возвраты N; иначе, возвраты -N.
Ts length(T x)
- Возвращает длину вектора x; т.е. sqrt(x[0]^2 + x[1]^2 + ...)
Ts length_squared(T x)
- Возвращает квадрат длины вектора x; т.е. x[0]^2 + x[1]^2 + ...
T normalize(T x)
- Возвращает вектор в том же направлении как x но с длиной 1.
T reflect(T I, T N)
- Для инцидентного вектора I и нормальная поверхность N, возвращает отражательное направление: I – 2 * dot(N, I) * N.
  Для достижения желаемого результата, N должен быть нормализован.
T refract(T I, T N, Ts eta)
- Для инцидентного вектора I, нормальная поверхность N, и отношение индексов преломления eta, возвращает вектор преломления. Входные параметры для инцидентного вектора I и нормальная поверхность N должен уже быть нормализован для получения желаемых результатов.

Для одинарной точности, с плавающей точкой, Металлической также, поддерживает точный и быстрый вариант следующих геометрических функций: distance, length, и normalize. -ffast-math параметр компилятора (отсылают к Математике Опции Intrinsics) используется для выбора надлежащего варианта при компиляции Металлического источника языка штриховки. Кроме того, metal::precise и metal::fast пространства имен также доступны и предоставляют разработчикам способ явно выбрать быстрый или точный вариант этих геометрических функций.

Вычислите функции

Функции в этом разделе и его подразделах могут быть вызваны только от a kernel функционируйте и определяются в заголовке <metal_compute>.

Функции Синхронизации threadgroup

Функция threadgroup, описанная ниже, поддерживается.

void threadgroup_barrier(mem_flags::flag)
- Всем потокам в threadgroup, выполнение ядра должно выполнить эту функцию перед любым потоком, позволяют продолжать выполнение вне точки, в которой вызвана эта функция.

threadgroup_barrier функционируйте действия как выполнение и барьер памяти. threadgroup_barrier с функцией должны встретиться все потоки в threadgroup выполнение ядра.

Если threadgroup_barrier в условном операторе и если какой-либо поток вводит условный оператор и выполняет барьер, все потоки в threadgroup должны ввести условное выражение и выполнить барьер.

Если threadgroup_barrier в цикле, для каждой итерации цикла, все потоки в threadgroup должны выполниться threadgroup_barrier прежде чем любым потокам позволяют продолжать выполнение вне threadgroup_barrier.

threadgroup_barrier функция может также поставить предел памяти в очередь (чтения и записи) для обеспечения корректного упорядочивания операций памяти к памяти устройства или threadgroup.

flag параметр в threadgroup_barrier может быть один из следующих флагов, как описано в Таблице 5-1.

**Таблица 5-1** `mem_flags` Перечислимые значения для `threadgroup_barrier`
mem_flags	Описание
`mem_none`	Никакой предел памяти не применяется, и `threadgroup_barrier` действия только как барьер выполнения.
`mem_device`	Гарантирует корректное упорядочивание операций памяти к памяти устройства.
`mem_threadgroup`	Гарантирует корректное упорядочивание операций памяти к threadgroup памяти для потоков в threadgroup.
`mem_device_and_threadgroup`	Гарантирует корректное упорядочивание операций памяти к устройству и threadgroup памяти для потоков в threadgroup.

Типы перечисления, используемые mem_flags указаны следующим образом:

enum class mem_flags {mem_none,

                      mem_device,

                      mem_threadgroup,

                      mem_device_and_threadgroup };

Графические функции

Этот раздел и его подразделы перечисляют набор графических функций, которые могут быть вызваны функциями фрагмента. Они определяются в заголовке <metal_graphics>.

Функции фрагмента

Функции в этих подразделах могут быть вызваны только в функции фрагмента (функция, объявленная с fragment спецификатор), или в функции вызывается от функции фрагмента. Иначе, поведение не определено и может привести к ошибке времени компиляции.

Функции фрагмента: деривативы

Металл включает следующие функции для вычислений деривативов. T один из float, float2, float3, float4, half, half2, half3, или half4.

T dfdx(T p)
- Возвращается частная производная высокой точности указанного значения относительно экрана располагают координату x с интервалами.
T dfdy(T p)
- Возвращается частная производная высокой точности указанного значения относительно экрана располагают координату y с интервалами.
T fwidth(T p)
- Возвращает сумму абсолютных производных в x и y с помощью локального differencing для p; т.е. fabs(dfdx(p)) + fabs(dfdy(p)).

Функции фрагмента: выборки

Металл включает следующие функции на выборку:

uint get_num_samples()
- Возвращает число выборок для мультивыбранного цветного присоединения.
float2 get_sample_position(uint indx)
- Возвращает нормализованное демонстрационное смещение (x, y) для данного демонстрационного индекса indx. Значения x и y находятся в интервале [-1.0, 1.0).

Функции get_num_samples и get_sample_position возвратите число выборок для цветного присоединения и демонстрационных смещений для данного демонстрационного индекса. Например, для избыточной выборки прозрачности, можно использовать эти функции, чтобы заштриховать на фрагмент, но сделать тестирование альфа-версии на выборку.

Функции фрагмента: управление потоком

Следующая Металлическая функция используется для завершения фрагмента:

void discard_fragment(void)
- Отмечает текущий фрагмент, как завершаемый, и вывод функции фрагмента для этого фрагмента отбрасывается.

Функции текстуры

Металл обеспечивает функции текстуры в семи категориях: выборка от текстуры, выборка выдерживает сравнение от текстуры, читала (не выбирая) от текстуры, собирает из текстуры, собирается, выдерживают сравнение от текстуры, пишут в текстуру и текстурируют функции запроса.

Они определяются в заголовке <metal_texture>.

Текстура sample, sample_compare, gather, и gather_compare функции берут offset параметр за 2D текстуру, 2D массив текстуры, 3D текстуру и кубическую текстуру. offset целочисленное значение, применяющееся к координате текстуры перед поиском каждого пикселя. Это целочисленное значение может быть в диапазоне-8 к +7. Значение по умолчанию 0.

Перегруженные варианты текстуры sample и sample_compare функции для 2D текстуры, 2D массива текстуры, 3D текстуры и кубической текстуры доступны и позволяют текстуре быть выбранной с помощью смещения, применяющегося к mip-уровню прежде, чем выбрать или с предоставленными пользователями градиентами в направлении x и y.

В этом разделе, Tv тип вектора с 4 компонентами на основе шаблонного типа <T> используемый для объявления типа текстуры. Если T float, Tv float4. Если T half, Tv half4. Если T int, Tv int4. Если T uint, Tv uint4. Если T short, Tv short4. Если T ushort, Tv ushort4.

Вся текстура read функции включают параметр Лода, указывая, которые множественно отображают уровень текстуры для чтения из. Указание нулевых чтений от основного (самого большого) уровня множественного отображения и более высоких значений, считанных из выше, множественно отображает уровни до значения, возвращенного get_num_mip_levels.

lodoptions параметр в текстуре sample функции должны использовать один из типов bias, level, или gradientX, где X суффикс, надлежащий типу текстуры (2d, 3d, или cube). Перечисление 5-2 показывает конструкторам для этих типов. Параметр Лода к level конструктор имеет тот же эффект как параметр Лода для текстурирования read функции.

Конструкторы перечисления 5-2 для Текстуры lodoptions Типы

bias(float value)

level(float lod)

gradient2d(float2 dPdx, float2 dPdy)

gradient3d(float3 dPdx, float3 dPdy)

gradientcube(float3 dPdx, float3 dPdy)

1D Текстура

Следующие встроенные функции воздействуют на одномерные текстуры:

Tv sample(sampler s, float coord) const
- Демонстрационные элементы текстуры от 1D текстура.
Tv read(uint coord) const
- Чтения, не выбирая от 1D текстура.
void write(Tv color, uint coord)
- Записи к определенному mip уровню 1D текстура.
uint get_width() const
- Возвращает ширину 1D текстура.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 1D текстура.

1D массив текстуры

Следующие встроенные функции воздействуют на массивы 1D текстуры:

Tv sample(sampler s, float coord, uint array) const
- Демонстрационные элементы текстуры от 1D текстурируют массив.
Tv read(uint coord, uint array) const
- Чтения, не выбирая от 1D текстурируют массив.
void write(Tv color, uint coord, uint array)
- Записи к определенному mip уровню 1D текстурируют массив.
uint get_width() const
- Возвращает ширину 1D массив текстуры.
uint get_array_size() const
- Возвращает число текстур в 1D массив текстуры.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 1D массив текстуры.

2D Текстура

Следующие встроенные функции воздействуют на двумерные текстуры:

Tv sample(sampler s, float2 coord, int2 offset = int2(0)) const
Tv sample(sampler s, float2 coord, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D текстуры. lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
Tv read(uint2 coord, uint lod = 0) const
- Чтения, не выбирая от 2D текстуры.
void write(Tv color, uint2 coord, uint lod = 0)
- Записи к определенному mip уровню 2D текстуры.
enum class component { x, y, z, w };
Tv gather(sampler s, float2 coord, int2 offset = int2(0), component c = component::x) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D текстуры. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D текстуры.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 2D текстуре.

Перечисление 5-3 показывает несколько использования 2D текстуры sample функция, в зависимости от ее параметров.

Пример выборки текстуры перечисления 5-3 2D

#include <metal_stdlib>
using namespace metal;

texture2d<float> tex;
sampler s;
float2 coord;
int2 offset;
float lod;

// no optional arguments
float4 clr = tex.sample(s, coord);

// sample using a mip-level
clr = tex.sample(s, coord, level(lod));

// sample with an offset
clr = tex.sample(s, coord, offset);

// sample using a mip-level and an offset 
clr = tex.sample(s, coord, level(lod), offset);

2D массив текстуры

Следующие встроенные функции воздействуют на массивы 2D текстур:

Tv sample(sampler s, float2 coord, uint array, int2 offset = int2(0)) const
Tv sample(sampler s, float2 coord, uint array, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D массива текстуры. lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
Tv read(uint2 coord, uint array, uint lod = 0) const
- Чтения, не выбирая от 2D массива текстуры.
void write(Tv color, uint2 coord, uint array, uint lod = 0)
- Записи к определенному mip уровню 2D массива текстуры.
enum class component { x, y, z, w };
Tv gather(sampler s, float2 coord, uint array, int2 offset = int2(0), component c = component::x) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D массива текстуры. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D массива текстуры.
uint get_array_size() const
- Возвращает число текстур в 2D массиве текстуры.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 2D массиве текстуры.

3D Текстура

Следующие встроенные функции воздействуют на трехмерные текстуры:

Tv sample(sampler s, float3 coord, int3 offset = int3(0)) const
Tv sample(sampler s, float3 coord, lod_options options, int3 offset = int3(0)) const
- Демонстрационные элементы текстуры от 3D текстуры. lod_options параметр должен быть одним из типов bias, level, или gradient3d. (См. Перечисление 5-2.)
Tv read(uint3 coord, uint lod = 0) const
- Чтения, не выбирая от 3D текстуры.
void write(Tv color, uint3 coord, uint lod = 0)
- Записи к определенному mip уровню 3D текстуры.
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
uint get_depth(uint lod = 0) const
- Возвращает ширину, высоту или глубину 3D текстуры.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 3D текстуре.

Кубическая текстура

Следующие встроенные функции воздействуют на кубические текстуры:

Tv sample(sampler s, float3 coord) const
Tv sample(sampler s, float3 coord, lod_options options) const
- Демонстрационные элементы текстуры от кубической текстуры. lod_options параметр должен быть одним из типов bias, level, или gradientcube. (См. Перечисление 5-2.)
enum class component { x, y, z, w };
Tv gather(sampler s, float3 coord, component c = component::x) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке кубической текстуры. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту кубической текстуры.
uint get_num_mip_levels() const
- Возвращает число mip уровней в кубической текстуре.

2D мультивыбранная текстура

Следующие встроенные функции воздействуют на 2D мультивыбранные текстуры:

Tv read(uint2 coord, uint sample) const
- Чтения, не выбирая от 2D мультивыбранной текстуры.
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D мультивыбранной текстуры.
uint get_num_samples() const
- Возвращает число выборок в 2D мультивыбранной текстуре.

2D текстура глубины

Следующие встроенные функции воздействуют на 2D текстуры глубины:

T sample(sampler s, float2 coord, int2 offset = int2(0)) const
T sample(sampler s, float2 coord, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D текстуры глубины. lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
T sample_compare(sampler s, float2 coord, float compare_value, int2 offset = int2(0)) const
T sample_compare(sampler s, float2 coord, float compare_value, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D глубины текстурируют, и сравнивает единственный компонент с указанным сравнительным значением. T должен быть a float введите, и lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
  Примечание: sample_compare выполняет сравнение compare_value против пиксельного значения (1.0, если передачи сравнения и 0.0, если это перестало работать). Эти результат сравнения оценивает, на пиксель тогда смешиваются вместе как в нормальной фильтрации текстуры, и получающееся значение между 0,0 и 1.0 возвращается.
T read(uint2 coord, uint lod = 0) const
- Чтения, не выбирая от 2D текстуры глубины.
Tv gather(sampler s, float2 coord, int2 offset = int2(0)) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D текстуры глубины. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
Tv gather_compare(sampler s, float2 coord, float compare_value, int2 offset = int2(0)) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D текстуры глубины, затем сравнивают эти выборки с указанным сравнительным значением. Возвраты 1.0 для каждого компонента, куда сравнение передает и 0.0 где это перестало работать. T должен быть a float ввести.
  Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D текстуры глубины.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 2D текстуре глубины.

2D массив текстуры глубины

Следующие встроенные функции воздействуют на массивы 2D текстур глубины.

T sample(sampler s, float2 coord, uint array, int2 offset = int2(0)) const
T sample(sampler s, float2 coord, uint array, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D глубины текстурируют массив. lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
T sample_compare(sampler s, float2 coord, uint array, float compare_value, int2 offset = int2(0)) const
T sample_compare(sampler s, float2 coord, uint array, float compare_value, lod_options options, int2 offset = int2(0)) const
- Демонстрационные элементы текстуры от 2D текстуры глубины выстраивают, и сравнивает единственный компонент с указанным сравнительным значением. T должен быть a float введите, и lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
  Примечание: sample_compare выполняет сравнение compare_value против пиксельного значения (1.0, если передачи сравнения и 0.0, если это перестало работать). Эти результат сравнения оценивает, на пиксель тогда смешиваются вместе как в нормальной фильтрации текстуры, и получающееся значение между 0,0 и 1.0 возвращается.
T read(uint2 coord, uint array, uint lod = 0) const
- Чтения, не выбирая от 2D глубины текстурируют массив.
Tv gather(sampler s, float2 coord, uint array, int2 offset = int2(0)) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D массива текстуры глубины. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
Tv gather_compare(sampler s, float2 coord, uint array, float compare_value, int2 offset = int2(0)) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке 2D массива текстуры глубины, затем сравнивают эти выборки с указанным сравнительным значением. Возвраты 1.0 для каждого компонента, куда сравнение передает и 0.0 где это перестало работать. T должен быть a float ввести.
  Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D массива текстуры глубины.
uint get_array_size() const
- Возвращает число текстур в 2D массиве текстуры глубины.
uint get_num_mip_levels() const
- Возвращает число mip уровней в 2D массиве текстуры глубины.

Текстура глубины куба

Следующие встроенные функции воздействуют на текстуры глубины куба:

T sample(sampler s, float3 coord) const
T sample(sampler s, float3 coord, lod_options options) const
- Демонстрационные элементы текстуры от текстуры глубины куба. lod_options параметр должен быть одним из типов bias, level, или gradientcube. (См. Перечисление 5-2.)
T sample_compare(sampler s, float3 coord, float compare_value) const
T sample_compare(sampler s, float3 coord, float compare_value, lod_options options) const
- Демонстрационные элементы текстуры от глубины куба текстурируют, и сравнивает единственный компонент с указанным сравнительным значением. T должен быть a float введите, и lod_options параметр должен быть одним из типов bias, level, или gradient2d. (См. Перечисление 5-2.)
  Примечание: sample_compare выполняет сравнение compare_value против пиксельного значения (1.0, если передачи сравнения и 0.0, если это перестало работать). Эти результат сравнения оценивает, на пиксель тогда смешиваются вместе как в нормальной фильтрации текстуры, и получающееся значение между 0,0 и 1.0 возвращается.
Tv gather(sampler s, float3 coord) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке массива текстуры глубины куба. Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
Tv gather_compare(sampler s, float3 coord, float compare_value) const
- Собирает четыре выборки, которые могут использоваться для билинейной интерполяции при выборке текстуры глубины куба, затем сравнивают эти выборки с указанным сравнительным значением. Возвраты 1.0 для каждого компонента, куда сравнение передает и 0.0 где это перестало работать. T должен быть a float ввести.
  Компоненты итогового вектора ссылаются на эти четыре выборки в следующем порядке:
  result.x = coord + float2(0, 1)
  result.y = coord + float2(1, 1)
  result.z = coord + float2(1, 0)
  result.w = coord
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту текстуры глубины куба.
uint get_num_mip_levels() const
- Возвращает число mip уровней в текстуре глубины куба.

2D мультивыбранная текстура глубины

Следующие встроенные функции воздействуют на 2D мультивыбранные текстуры глубины.

Tv read(uint2 coord, uint sample) const
- Чтения, не выбирая от 2D мультивыбранной текстуры глубины.
uint get_width(uint lod = 0) const
uint get_height(uint lod = 0) const
- Возвращает ширину или высоту 2D мультивыбранной текстуры глубины.
uint get_num_samples() const
- Возвращает число выборок в 2D мультивыбранной текстуре глубины.

Упакуйте и распакуйте функции

Этот раздел перечисляет Металлические функции для преобразования векторных данных с плавающей точкой к и от упакованного целочисленного значения. Функции определяются в заголовке <metal_pack>. Относитесь для Текстурирования Правил Обращения и Преобразования для подробных данных о том, как преобразовать из 8-разрядного, 10-разрядного или 16-разрядного целого числа со знаком, или целое без знака оценивают нормализованному синглу - или полуточность значение с плавающей точкой и наоборот.

Распакуйте целые числа и преобразуйте в вектор с плавающей точкой

Следующие функции распаковывают многократные значения от единственного целого без знака и затем преобразовывают их в значения с плавающей точкой, которые сохранены в векторе.

float4 unpack_unorm4x8_to_float(uint x)
float4 unpack_snorm4x8_to_float(uint x)
half4 unpack_unorm4x8_to_half(uint x)
half4 unpack_snorm4x8_to_half(uint x)
- Распаковывает 32-разрядное целое без знака в четыре 8-разрядных целых числа со знаком или целых без знака, и затем преобразовывает каждое 8-разрядное целое число со знаком, или целое без знака оценивают нормализованному синглу - или полуточность значение с плавающей точкой для генерации вектора с 4 компонентами.
float4 unpack_unorm4x8_srgb_to_float(uint x)
half4 unpack_unorm4x8_srgb_to_half(uint x)
- Распаковывает 32-разрядное целое без знака в четыре 8-разрядных целых числа со знаком или целых без знака, и затем преобразовывает каждое 8-разрядное целое число со знаком, или целое без знака оценивают нормализованному синглу - или полуточность значение с плавающей точкой для генерации вектора с 4 компонентами. R, g, и b значения цвета преобразовываются от sRGB до линейного RGB.
float2 unpack_unorm2x16_to_float(uint x)
float2 unpack_snorm2x16_to_float(uint x)
half2 unpack_unorm2x16_to_half(uint x)
half2 unpack_snorm2x16_to_half(uint x)
- Распаковывает 32-разрядное целое без знака в два 16-разрядных целых числа со знаком или целых без знака, и затем преобразовывает каждое 16-разрядное целое число со знаком, или целое без знака оценивают нормализованному синглу - или полуточность значение с плавающей точкой для генерации вектора с 2 компонентами. ( unpack_unorm2x16_to_half и unpack_snorm2x16_to_half функции могут привести к потере точности при преобразовании из 16-разрядного нормализованного без знака (unorm) или подписанный нормализованный (snorm) целочисленное значение к значению с плавающей точкой полуточности.)
float4 unpack_unorm10a2_to_float(uint x)
float3 unpack_unorm565_to_float(ushort x)
half4 unpack_unorm10a2_to_half(uint x)
half3 unpack_unorm565_to_half(ushort x)
- Преобразовывает 1010102 (10a2), или 565 значений цвета к соответствующему нормализованному синглу - или полуточность вектор с плавающей точкой.

Преобразуйте Вектор С плавающей точкой в Целые числа, затем Пакет Целые числа

Следующие функции запускаются с вектора с плавающей точкой, преобразовывают компоненты в целочисленные значения, и затем упаковывают многократные значения в единственное целое без знака.

uint pack_float_to_unorm4x8(float4 x)
uint pack_float_to_snorm4x8(float4 x)
uint pack_half_to_unorm4x8(half4 x)
uint pack_half_to_snorm4x8(half4 x)
- Преобразовывает вектор с 4 компонентами, нормализовал единственный - или полуточность значение с плавающей точкой к четырем 8-разрядным целочисленным значениям и упаковывает эти 8-разрядные целочисленные значения в 32-разрядное целое без знака.
uint pack_float_to_srgb_unorm4x8(float4 x)
uint pack_half_to_srgb_unorm4x8(half4 x)
- Преобразовывает вектор с 4 компонентами, нормализовал единственный - или полуточность значение с плавающей точкой к четырем 8-разрядным целочисленным значениям и упаковывает эти 8-разрядные целочисленные значения в 32-разрядное целое без знака. Значения цвета преобразовываются от линейного RGB до sRGB.
uint pack_float_to_unorm2x16(float2 x)
uint pack_float_to_snorm2x16(float2 x)
uint pack_half_to_unorm2x16(half2 x)
uint pack_half_to_snorm2x16(half2 x)
- Преобразовывает вектор с 2 компонентами нормализованного сингла - или полуточность значения с плавающей точкой к двум 16-разрядным целочисленным значениям и упаковывает эти 16-разрядные целочисленные значения в 32-разрядное целое без знака.
uint pack_float_to_unorm10a2(float4)
ushort pack_float_to_unorm565(float3)
uint pack_half_to_unorm10a2(half4)
ushort pack_half_to_unorm565(half3)
- Преобразовывает 4-или вектор с 3 компонентами нормализованного сингла - или полуточность значения с плавающей точкой к упакованному целочисленному значению в формате RGB565 или RGB10A2. Для получения дополнительной информации на этих форматах, посмотрите Pixel Format Codes.

Атомарные функции

Металлический язык штриховки реализует подмножество C++ 11 атомной энергетики и операции синхронизации. Для атомарных операций Металл поддерживает только a memory_order из memory_order_relaxed. Если атомарная работа к threadgroup памяти, объем памяти этих атомарных операций является threadgroup. Если атомарная работа к памяти устройства, то объем памяти является устройством GPU.

Существует только несколько видов операций на атомарных типах, несмотря на то, что существует много экземпляров тех видов. Этот раздел указывает каждый общий вид. Эти операции определяются в заголовке <metal_atomic>.

memory_order перечисление определяется следующим образом:

enum memory_order {

        memory_order_relaxed

};

Атомарные функции хранилища

Эти функции атомарно заменяют значение, которым указывают obj (*obj) с desired:

void atomic_store_explicit(volatile device atomic_int* obj, 
                           int desired,
                           memory_order order)
void atomic_store_explicit(volatile device atomic_uint* obj, 
                           uint desired,
                           memory_order order)
void atomic_store_explicit(volatile threadgroup atomic_int* obj, 
                           int desired,
                           memory_order order)
void atomic_store_explicit(volatile threadgroup atomic_uint* obj, 
                           uint desired,
                           memory_order order)

Атомарные функции загрузки

Эти функции атомарно получают значение, которым указывают obj:

int atomic_load_explicit(volatile device atomic_int* obj,
                          memory_order order)
uint atomic_load_explicit(volatile device atomic_uint* obj,
                          memory_order order)
int atomic_load_explicit(volatile threadgroup atomic_int* obj,
                         memory_order order)
uint atomic_load_explicit(volatile threadgroup atomic_uint* obj,
                          memory_order order)

Атомарные функции Exchange

Эти функции атомарно заменяют значение, которым указывают obj с desired и возвратите значение, ранее сдержанное obj:

int atomic_exchange_explicit(volatile device atomic_int *obj, 
                             int desired,
                             memory_order order)
uint atomic_exchange_explicit(volatile device atomic_uint *obj, 
                              uint desired,
                              memory_order order)
int atomic_exchange_explicit(volatile threadgroup atomic_int *obj, 
                             int desired,
                             memory_order order)
uint atomic_exchange_explicit(volatile threadgroup atomic_uint *obj, 
                              uint desired,
                              memory_order order)

Атомарный выдерживают сравнение и функции Exchange

Эти функции атомарно сравнивают значение, которым указывают obj со значением в expected. Если те значения равны, функциональные замены *obj с desired (путем выполнения работы «чтение изменяет запись»). Каждая функция возвращает булево значение, указывающее, успешно выполнилась ли его работа.

bool atomic_compare_exchange_weak_explicit(
                             volatile device atomic_int *obj,
                             int *expected,
                             int desired,
                             memory_order succ,
                             memory_order fail)
bool atomic_compare_exchange_weak_explicit(
                             volatile device atomic_uint *obj,
                             uint *expected,
                             uint desired,
                             memory_order succ,
                             memory_order fail)
bool atomic_compare_exchange_weak_explicit(
                             volatile threadgroup atomic_int *obj,
                             int *expected,
                             int desired,
                             memory_order succ,
                             memory_order fail)
bool atomic_compare_exchange_weak_explicit(
                             volatile threadgroup atomic_uint *obj,
                             uint *expected,
                             uint desired,
                             memory_order succ,
                             memory_order fail)

Атомарная выборка и изменяет функции

Следующие операции выполняют арифметические и поразрядные вычисления. Все эти операции применимы к объекту любого атомарного типа. Ключ, оператор и корреспонденция вычисления даны в Таблице 5-2.

**Таблица 5-2** атомарные функции работы
Ключ	Оператор	Вычисление
`add`	`+`	дополнение
`and`	`&`	поразрядно и
`max`	`max`	вычислите макс.
`min`	`min`	вычислите минуту
`or`	`\|`	поразрядно включительно или
`sub`	`-`	вычитание
`xor`	`^`	поразрядно монопольный или

Следующие функции атомарно заменяют значение, которым указывают obj с результатом вычисления значения, указанного key и arg, где key соответствует любому значению ключа от Таблицы 5-2. Эти операции являются атомарными операциями «чтение, изменяют запись». Для типов целого числа со знаком арифметика определяется для использования two's-дополнительного представления с тихим переносом на переполнении. Нет никаких неопределенных результатов. Каждая функция возвращает значение, ранее сдержанное obj.

 // addition
int atomic_fetch_add_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_add_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_add_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_add_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // bitwise and
int atomic_fetch_and_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_and_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_and_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_and_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // compute max
int atomic_fetch_max_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_max_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_max_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_max_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // compute min
int atomic_fetch_min_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_min_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_min_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_min_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // bitwise inclusive or
int atomic_fetch_or_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_or_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_or_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_or_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // subtraction
int atomic_fetch_sub_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_sub_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_sub_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_sub_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

 // bitwise exclusive or
int atomic_fetch_xor_explicit(volatile device atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_xor_explicit(volatile device atomic_uint *obj, 
                               uint arg, 
                               memory_order order)
int atomic_fetch_xor_explicit(volatile threadgroup atomic_int *obj, 
                              int arg, 
                              memory_order order)
uint atomic_fetch_xor_explicit(volatile threadgroup atomic_uint *obj, 
                               uint arg, 
                               memory_order order)

Вперед Назад