diff --git a/src/nodes/gpgpu/SubgroupFunctionNode.js b/src/nodes/gpgpu/SubgroupFunctionNode.js index a9447373f24e98..786e7cfb090a0b 100644 --- a/src/nodes/gpgpu/SubgroupFunctionNode.js +++ b/src/nodes/gpgpu/SubgroupFunctionNode.js @@ -1,6 +1,18 @@ import TempNode from '../core/TempNode.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; + +/** + * This class represents a set of built in WGSL shader functions that sync + * synchronously execute an operation across a subgroup, or 'wave', of compute + * or fragment shader invocations within a workgroup. Typically, these functions + * will synchronously execute an operation using data from all active invocations + * within the subgroup, then broadcast that result to all active invocations. In + * other graphics APIs, subgroup functions are also referred to as wave intrinsics + * (DirectX/HLSL) or warp intrinsics (CUDA). + * + * @augments TempNode + */ class SubgroupFunctionNode extends TempNode { static get type() { @@ -9,13 +21,36 @@ class SubgroupFunctionNode extends TempNode { } + /** + * Constructs a new function node. + * + * @param {String} method - The subgroup/wave intrinsic method to construct. + * @param {Node} [aNode=null] - The method's first argument. + * @param {Node} [bNode=null] - The method's second argument. + */ constructor( method, aNode = null, bNode = null ) { super(); + /** + * The subgroup/wave intrinsic method to construct. + * + * @type {String} + */ this.method = method; + /** + * The method's first argument. + * + * @type {Node} + */ this.aNode = aNode; + + /** + * The method's second argument. + * + * @type {Node} + */ this.bNode = bNode; } @@ -162,30 +197,236 @@ SubgroupFunctionNode.QUAD_BROADCAST = 'quadBroadcast'; export default SubgroupFunctionNode; + + +/** + * Returns true if this invocation has the lowest subgroup_invocation_id + * among active invocations in the subgroup. + * + * @method + * @return {bool} The result of the computation. + */ export const subgroupElect = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_ELECT ); + +/** + * Returns a set of bitfields where the bit corresponding to subgroup_invocation_id + * is 1 if pred is true for that active invocation and 0 otherwise. + * + * @method + * @param {bool} pred - A boolean that sets the bit corresponding to the invocations subgroup invocation id. + * @return {vec4}- A bitfield corresponding to the pred value of each subgroup invocation. + */ export const subgroupBallot = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_BALLOT ); + +/** + * A reduction that adds e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The accumulated result of the reduction operation. + */ export const subgroupAdd = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_ADD ); + +/** + * An inclusive scan returning the sum of e for all active invocations with subgroup_invocation_id less than or equal to this invocation. + * + * @method + * @param {number} e - The value provided to the inclusive scan by the current invocation. + * @return {number} The accumulated result of the inclusive scan operation. + */ export const subgroupInclusiveAdd = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_INCLUSIVE_ADD ); + +/** + * An exclusive scan that returns the sum of e for all active invocations with subgroup_invocation_id less than this invocation. + * + * @method + * @param {number} e - The value provided to the exclusive scan by the current invocation. + * @return {number} The accumulated result of the exclusive scan operation. + */ export const subgroupExclusiveAdd = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_EXCLUSIVE_AND ); + +/** + * A reduction that multiplies e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The accumulated result of the reduction operation. + */ export const subgroupMul = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_MUL ); + +/** + * An inclusive scan returning the product of e for all active invocations with subgroup_invocation_id less than or equal to this invocation. + * + * @method + * @param {number} e - The value provided to the inclusive scan by the current invocation. + * @return {number} The accumulated result of the inclusive scan operation. + */ export const subgroupInclusiveMul = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_INCLUSIVE_MUL ); + +/** + * An exclusive scan that returns the product of e for all active invocations with subgroup_invocation_id less than this invocation. + * + * @method + * @param {number} e - The value provided to the exclusive scan by the current invocation. + * @return {number} The accumulated result of the exclusive scan operation. + */ export const subgroupExclusiveMul = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_EXCLUSIVE_MUL ); + +/** + * A reduction that performs a bitwise and of e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The result of the reduction operation. + */ export const subgroupAnd = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_AND ); + +/** + * A reduction that performs a bitwise or of e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The result of the reduction operation. + */ export const subgroupOr = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_OR ); + +/** + * A reduction that performs a bitwise xor of e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The result of the reduction operation. + */ export const subgroupXor = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_XOR ); + +/** + * A reduction that performs a min of e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The result of the reduction operation. + */ export const subgroupMin = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_MIN ); + +/** + * A reduction that performs a max of e among all active invocations and returns that result. + * + * @method + * @param {number} e - The value provided to the reduction by the current invocation. + * @return {number} The result of the reduction operation. + */ export const subgroupMax = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_MAX ); + +/** + * Returns true if e is true for all active invocations in the subgroup. + * + * @method + * @return {bool} The result of the computation. + */ export const subgroupAll = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_ALL ); + +/** + * Returns true if e is true for any active invocation in the subgroup + * + * @method + * @return {bool} The result of the computation. + */ export const subgroupAny = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_ANY ); + +/** + * Broadcasts e from the active invocation with the lowest subgroup_invocation_id in the subgroup to all other active invocations. + * + * @method + * @param {number} e - The value to broadcast from the lowest subgroup invocation. + * @param {number} id - The subgroup invocation to broadcast from. + * @return {number} The broadcast value. + */ export const subgroupBroadcastFirst = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_BROADCAST_FIRST ); + +/** + * Swaps e between invocations in the quad in the X direction. + * + * @method + * @param {number} e - The value to swap from the current invocation. + * @return {number} The value received from the swap operation. + */ export const quadSwapX = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.QUAD_SWAP_X ); + +/** + * Swaps e between invocations in the quad in the Y direction. + * + * @method + * @param {number} e - The value to swap from the current invocation. + * @return {number} The value received from the swap operation. + */ export const quadSwapY = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.QUAD_SWAP_Y ); + +/** + * Swaps e between invocations in the quad diagonally. + * + * @method + * @param {number} e - The value to swap from the current invocation. + * @return {number} The value received from the swap operation. + */ export const quadSwapDiagonal = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.QUAD_SWAP_DIAGONAL ); + +/** + * Broadcasts e from the invocation whose subgroup_invocation_id matches id, to all active invocations. + * + * @method + * @param {number} e - The value to broadcast from subgroup invocation 'id'. + * @param {number} id - The subgroup invocation to broadcast from. + * @return {number} The broadcast value. + */ export const subgroupBroadcast = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_BROADCAST ); + +/** + * Returns v from the active invocation whose subgroup_invocation_id matches id + * + * @method + * @param {number} v - The value to return from subgroup invocation id^mask. + * @param {number} id - The subgroup invocation which returns the value v. + * @return {number} The broadcast value. + */ export const subgroupShuffle = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_SHUFFLE ); + +/** + * Returns v from the active invocation whose subgroup_invocation_id matches subgroup_invocation_id ^ mask. + * + * @method + * @param {number} v - The value to return from subgroup invocation id^mask. + * @param {number} mask - A bitmask that determines the target invocation via a XOR operation. + * @return {number} The broadcast value. + */ export const subgroupShuffleXor = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_SHUFFLE_XOR ); + +/** + * Returns v from the active invocation whose subgroup_invocation_id matches subgroup_invocation_id - delta + * + * @method + * @param {number} v - The value to return from subgroup invocation id^mask. + * @param {number} delta - A value that offsets the current in. + * @return {number} The broadcast value. + */ export const subgroupShuffleUp = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_SHUFFLE_UP ); + +/** + * Returns v from the active invocation whose subgroup_invocation_id matches subgroup_invocation_id + delta + * + * @method + * @param {number} v - The value to return from subgroup invocation id^mask. + * @param {number} delta - A value that offsets the current subgroup invocation. + * @return {number} The broadcast value. + */ export const subgroupShuffleDown = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.SUBGROUP_SHUFFLE_DOWN ); + +/** + * Broadcasts e from the quad invocation with id equal to id. + * + * @method + * @param {number} e - The value to broadcast. + * @return {number} The broadcast value. + */ export const quadBroadcast = /*@__PURE__*/ nodeProxy( SubgroupFunctionNode, SubgroupFunctionNode.QUAD_BROADCAST ); addMethodChaining( 'subgroupElect', subgroupElect );