Signatur
GPUDevice.prototype.createSampler(descriptor)
Beschreibung
createSampler() erzeugt ein GPUSampler-Objekt. Es legt fest, wie ein Shader beim Abtasten einer Textur (z. B. mit textureSample() in WGSL) die Texel-Werte liest und interpoliert. Der Sampler ist von der Textur selbst getrennt. Deshalb kann man denselben Sampler mit beliebig vielen Texturen kombinieren.
Der Deskriptor steuert vor allem drei Dinge:
- Adressierung (
addressModeU/V/W): Was passiert bei Koordinaten außerhalb von [0, 1]? Die Werte werden auf den Rand begrenzt ("clamp-to-edge"), wiederholt ("repeat") oder gespiegelt wiederholt ("mirror-repeat"). - Filterung (
magFilter,minFilter,mipmapFilter): Mit"nearest"wirkt das Ergebnis pixelig, mit"linear"weich interpoliert. Dazu kommt die Mipmap-Steuerung überlodMinClamp/lodMaxClamp. - Vergleich und Anisotropie: Mit
compareentsteht ein Vergleichs-Sampler (sampler_comparison), etwa für Shadow Mapping.maxAnisotropyverbessert die Qualität bei schräg betrachteten Oberflächen.
Das erzeugte Objekt wird über eine GPUBindGroup an den Shader gebunden. Sampler kosten wenig, sind aber unveränderlich. Soll sich das Verhalten ändern, erzeugt man einen neuen Sampler. Ein Sampler, der sich nicht ändert, wird sinnvollerweise einmal angelegt und wiederverwendet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $descriptor | GPUSamplerDescriptor | {} | Optionales Konfigurationsobjekt. Ohne Angabe gilt: alle Adressmodi "clamp-to-edge", alle Filter "nearest". |
| $descriptor.label | string | "" | Name für Fehlermeldungen und Debugging-Werkzeuge. |
| $descriptor.addressModeU | "clamp-to-edge" | "repeat" | "mirror-repeat" | "clamp-to-edge" | Adressierung in horizontaler Richtung (Breite). |
| $descriptor.addressModeV | "clamp-to-edge" | "repeat" | "mirror-repeat" | "clamp-to-edge" | Adressierung in vertikaler Richtung (Höhe). |
| $descriptor.addressModeW | "clamp-to-edge" | "repeat" | "mirror-repeat" | "clamp-to-edge" | Adressierung in der Tiefe (nur bei 3D-Texturen relevant). |
| $descriptor.magFilter | "nearest" | "linear" | "nearest" | Filter bei Vergrößerung, wenn ein Texel mehr als ein Pixel abdeckt. |
| $descriptor.minFilter | "nearest" | "linear" | "nearest" | Filter bei Verkleinerung, wenn ein Pixel mehrere Texel abdeckt. |
| $descriptor.mipmapFilter | "nearest" | "linear" | "nearest" | Legt fest, wie zwischen Mipmap-Stufen gewählt bzw. überblendet wird. |
| $descriptor.lodMinClamp | number | 0 | Kleinste Detailstufe (LOD), die intern verwendet wird. Muss ≥ 0 sein. |
| $descriptor.lodMaxClamp | number | 32 | Größte Detailstufe (LOD). Muss ≥ lodMinClamp sein. |
| $descriptor.compare | "never" | "less" | "equal" | "less-equal" | "greater" | "not-equal" | "greater-equal" | "always" | Wenn gesetzt, entsteht ein Vergleichs-Sampler (WGSL: sampler_comparison), z. B. für Schattenberechnung mit Tiefentexturen. |
|
| $descriptor.maxAnisotropy | number | 1 | Obergrenze für anisotrope Filterung (1–65535, die Implementierung begrenzt intern meist auf 16). Werte > 1 erfordern, dass alle drei Filter "linear" sind. |
Rückgabewert
Typ
GPUSampler
Beschreibung
Ein neues
GPUSampler-Objekt, das per GPUBindGroup an einen Shader gebunden werden kann. Bei einem ungültigen Deskriptor wird ein ungültiges Objekt zurückgegeben und ein Validierungsfehler gemeldet. Es wird keine Ausnahme geworfen.Beispiele
Linearer, wiederholender Sampler für kachelbare Texturen
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
// Weich gefilterter Sampler, der die Textur kachelt (z. B. Bodenfliesen)
const sampler = device.createSampler({
label: 'Kachel-Sampler',
addressModeU: 'repeat',
addressModeV: 'repeat',
magFilter: 'linear',
minFilter: 'linear',
mipmapFilter: 'linear',
maxAnisotropy: 16
});
console.log(sampler.label);Kachel-Sampler
Pixelart-Sampler an eine Bind Group binden
// WGSL-Seite:
// @group(0) @binding(0) var spriteSampler: sampler;
// @group(0) @binding(1) var spriteTex: texture_2d<f32>;
const pixelSampler = device.createSampler({
magFilter: 'nearest', // harte Pixelkanten beim Vergrößern
minFilter: 'nearest'
});
const bindGroup = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [
{ binding: 0, resource: pixelSampler },
{ binding: 1, resource: spriteTexture.createView() }
]
});
// Im Render-Pass verwenden
passEncoder.setBindGroup(0, bindGroup);Vergleichs-Sampler für Shadow Mapping
// WGSL: @group(0) @binding(2) var shadowSampler: sampler_comparison;
// textureSampleCompare(shadowMap, shadowSampler, uv, depthRef);
const shadowSampler = device.createSampler({
label: 'Schatten-Sampler',
compare: 'less',
magFilter: 'linear', // liefert Hardware-PCF (weiche Schattenkanten)
minFilter: 'linear'
});Validierungsfehler gezielt abfangen
device.pushErrorScope('validation');
// Ungültig: maxAnisotropy > 1 bei "nearest"-Filtern
const bad = device.createSampler({ maxAnisotropy: 8 });
const error = await device.popErrorScope();
if (error) {
console.warn('Sampler ungültig:', error.message);
}Sampler ungültig: ... (browserabhängige Meldung)