GPUDevice: createSampler() method
=================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`createSampler()`** method of the
 `GPUDevice` interface creates a `GPUSampler`, which controls how shaders transform and filter texture resource data.

Syntax
------


```js
createSampler()
createSampler(descriptor)
```

### Parameters

`descriptor` Optional

An object containing the following properties:

`addressModeU` Optional

An enumerated value specifying the behavior of the sampler when the sample footprint width extends beyond the width of the texture. Possible values are:

* `"clamp-to-edge"`: The texture coordinates are clamped between 0.0 and 1.0, inclusive.
* `"repeat"`: The texture coordinates wrap to the other side of the texture.
* `"mirror-repeat"`: The texture coordinates wrap to the other side of the texture, but the texture is flipped when the integer part of the coordinate is odd.

If omitted, `addressModeU` defaults to `"clamp-to-edge"`.

`addressModeV` Optional

An enumerated value specifying the behavior of the sampler when the sample footprint height extends beyond the height of the texture. Possible and default values are the same as for `addressModeU`.

`addressModeW` Optional

An enumerated value specifying the behavior of the sampler when the sample footprint depth extends beyond the depth of the texture. Possible and default values are the same as for `addressModeU`.

`compare` Optional

If specified, the sampler will be a comparison sampler of the specified type. Possible (enumerated) values are:

* `"never"`: Comparison tests never pass.
* `"less"`: A provided value passes the comparison test if it is less than the sampled value.
* `"equal"`: A provided value passes the comparison test if it is equal to the sampled value.
* `"less-equal"`: A provided value passes the comparison test if it is less than or equal to the sampled value.
* `"greater"`: A provided value passes the comparison test if it is greater than the sampled value.
* `"not-equal"`: A provided value passes the comparison test if it is not equal to the sampled value.
* `"greater-equal"`: A provided value passes the comparison test if it is greater than or equal to the sampled value.
* `"always"`: Comparison tests always pass.

Comparison samplers may use filtering, but the sampling results will be implementation-dependent and may differ from the normal filtering rules.

`label` Optional

A string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.

`lodMinClamp` Optional

A number specifying the minimum level of detail used internally when sampling a texture. If omitted, `lodMinClamp` defaults to 0.

`lodMaxClamp` Optional

A number specifying the maximum level of detail used internally when sampling a texture. If omitted, `lodMaxClamp` defaults to 32.

`maxAnisotropy` Optional

Specifies the maximum anisotropy value clamp used by the sampler. If omitted, `maxAnisotropy` defaults to 1.

Most implementations support `maxAnisotropy` values in a range between 1 and 16, inclusive. The value used will be clamped to the maximum value that the underlying platform supports.

`magFilter` Optional

An enumerated value specifying the sampling behavior when the sample footprint is smaller than or equal to one texel. Possible values are:

* `"nearest"`: Return the value of the texel nearest to the texture coordinates.
* `"linear"`: Select two texels in each dimension and return a linear interpolation between their values.

If omitted, `magFilter` defaults to `"nearest"`.

`minFilter` Optional

An enumerated value specifying the sampling behavior when the sample footprint is larger than one texel. Possible and default values are the same as for `magFilter`.

`mipmapFilter` Optional

An enumerated value specifying the behavior when sampling between mipmap levels. Possible and default values are the same as for `magFilter`.


### Return value

A `GPUSampler` object instance.

### Validation

The following criteria must be met when calling **`createSampler()`**, otherwise a `GPUValidationError` is generated and an invalid `GPUSampler` object is returned:

* `lodMinClamp` is equal to or more than 0.
* `lodMaxClamp` is equal to or more than `lodMinClamp`.
* `maxAnisotropy` is equal to or more than 1.
* If `maxAnisotropy` is more than 1, `magFilter`, `minFilter`, and `mipmapFilter` are `"linear"`.
Examples
--------

The following snippet creates a `GPUSampler` that does trilinear filtering and repeats texture coordinates:


```js
// ...

const sampler = device.createSampler({
  addressModeU: "repeat",
  addressModeV: "repeat",
  magFilter: "linear",
  minFilter: "linear",
  mipmapFilter: "linear",
});
```


The WebGPU samples Shadow Mapping sample uses comparison samplers to sample from a depth texture to render shadows.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-createsampler |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API