pub struct Texture(/* private fields */);Expand description
Cloning is a handle copy, as in JS.
Implementations§
Source§impl Texture
impl Texture
Sourcepub fn compressed(
mipmaps: Vec<Mipmap>,
width: u32,
height: u32,
format: TextureFormat,
) -> Self
pub fn compressed( mipmaps: Vec<Mipmap>, width: u32, height: u32, format: TextureFormat, ) -> Self
new CompressedTexture( mipmaps, width, height, format, type ).
The constructor’s own differences from Texture (CompressedTexture.js):
flipY = false — “can’t flip compressed textures” — and
generateMipmaps = false — “can’t generate mipmaps for compressed
textures”. The filters stay at the Texture defaults; KTX2Loader
overrides them.
format is the GPU format the renderer creates the texture with —
the port’s stand-in for three’s ( format, type, colorSpace ) triple,
which WebGPUTextureUtils.getFormat() turns into one — and every
mip’s data must be laid out in it.
Sourcepub fn compressed_array(
mipmaps: Vec<Mipmap>,
width: u32,
height: u32,
depth: u32,
format: TextureFormat,
) -> Self
pub fn compressed_array( mipmaps: Vec<Mipmap>, width: u32, height: u32, depth: u32, format: TextureFormat, ) -> Self
new CompressedArrayTexture( mipmaps, width, height, depth, format, type )
— image.depth layers, each mip’s data holding every layer of the
level in order. wrapR is ClampToEdgeWrapping upstream and has no
sampler field to go to in a 2-D-array view, so it is not stored.
Sourcepub fn set_filters(&self, min_filter: MinFilter, mag_filter: TextureFilter)
pub fn set_filters(&self, min_filter: MinFilter, mag_filter: TextureFilter)
texture.minFilter = min; texture.magFilter = mag.
Sourcepub fn set_premultiply_alpha(&self, premultiply_alpha: bool)
pub fn set_premultiply_alpha(&self, premultiply_alpha: bool)
texture.premultiplyAlpha = value.
Source§impl Texture
impl Texture
Sourcepub fn dispose(self)
pub fn dispose(self)
texture.dispose() — drops this handle, and nothing more: a texture
handle is an Rc, so the renderer frees the GPU side once every handle
is gone, at the top of the next render (docs/scene-graph.md,
“Identity and eviction”). Dropping the handle does the same; this
exists so three.js code ports line for line.
Sourcepub fn new(width: u32, height: u32, data: Option<Vec<u8>>) -> Self
pub fn new(width: u32, height: u32, data: Option<Vec<u8>>) -> Self
new Texture() defaults: ClampToEdgeWrapping, LinearFilter,
LinearMipmapLinearFilter, RGBAFormat, UnsignedByteType,
NoColorSpace, flipY = true, generateMipmaps = true, anisotropy 1.
Sourcepub fn render_target(width: u32, height: u32, format: TextureFormat) -> Self
pub fn render_target(width: u32, height: u32, format: TextureFormat) -> Self
The texture behind a render target’s colour attachment: no image data,
no mipmaps, flipY irrelevant, and minFilter = LinearFilter (which is
what RenderTarget’s options set).
Sourcepub fn storage(width: u32, height: u32) -> Self
pub fn storage(width: u32, height: u32) -> Self
new StorageTexture( width, height ) (renderers/common/StorageTexture.js):
a Texture with no image, LinearFilter on both filters and
isStorageTexture = true. generateMipmaps keeps Texture’s true,
so the GPU texture has the full chain; three regenerates it after a
kernel has stored into level 0, before the next draw that samples it
(Bindings._update()’s needsMipmap), and so does the renderer here.
rgba8unorm by default; set_texture_type( TextureType::HalfFloat )
makes it rgba16float, as texture.type = HalfFloatType does. Either
is a format WebGPU allows as a write-only storage texture on every
backend, which is what webgpu_compute_texture* bind it as.
Sourcepub fn is_storage(&self) -> bool
pub fn is_storage(&self) -> bool
texture.isStorageTexture.
Sourcepub fn external(gpu: Texture, color_space: ColorSpace) -> Self
pub fn external(gpu: Texture, color_space: ColorSpace) -> Self
new ExternalTexture( sourceTexture ) — a wgpu::Texture the caller
created and goes on owning, wrapped so a material can sample it.
This is how a host that already has GPU textures hands them to the
scene: a Wayland compositor imports a client’s dmabuf as a
wgpu::Texture and wraps it here, and the renderer samples the client’s
pixels with no copy and no upload. Pair it with
Renderer::with_device, since
the texture only works on the device it was created on.
Size and format are taken from the wgpu texture, so they cannot drift
from it. own_gpu = false: the renderer never re-creates, re-uploads or
destroys it, and never generates mipmaps into it — the handle is a
refcount, so the underlying texture lives as long as either side holds
one. Filters are LinearFilter on both, wrapping ClampToEdge, and
there is no mip chain to filter between.
color_space must agree with the wgpu format’s transfer function —
an *Srgb format is ColorSpace::Srgb and everything else is
ColorSpace::LinearSrgb or ColorSpace::NoColorSpace — because the GPU applies the transfer on
sample and a mismatch is a silently wrong-looking frame rather than an
error. It is asserted here.
Sourcepub fn data_r32float(width: u32, height: u32, data: &[f32]) -> Self
pub fn data_r32float(width: u32, height: u32, data: &[f32]) -> Self
new DataTexture( new Float32Array( data ), width, height, RedFormat, FloatType ) — the SDF atlas texture lib3’s VectorFontAtlas hands to
texture().
DataTexture’s constructor differs from Texture’s in three places
(DataTexture.js): flipY = false, generateMipmaps = false and
minFilter = magFilter = NearestFilter; lib3 then sets both filters back
to LinearFilter, which is what this builds. The colour space stays
NoColorSpace — the field is distance, not colour, and tagging it sRGB
would put a transfer function on the SDF (plan §5.3).
Sourcepub fn data_r16float(width: u32, height: u32, data: &[u16]) -> Self
pub fn data_r16float(width: u32, height: u32, data: &[u16]) -> Self
new DataTexture( new Uint16Array( data ), width, height, RedFormat, HalfFloatType ) — one binary16 bit pattern per texel (r16float),
the format of ImportanceSampledEnvironment’s CDF tables.
Keeps all of DataTexture’s defaults, as data_r8
does: flipY = false, generateMipmaps = false and NearestFilter
on both sides; set the filters afterwards for a filtered lookup.
Sourcepub fn data_r8(width: u32, height: u32, data: &[u8]) -> Self
pub fn data_r8(width: u32, height: u32, data: &[u8]) -> Self
new DataTexture( new Uint8Array( data ), width, height, RedFormat ) —
webgpu_materials_toon’s gradient maps, one byte per texel
(r8unorm).
Unlike data_r32float this keeps all of
DataTexture’s own defaults: NearestFilter on both sides, which makes
the map unfilterable (is_unfilterable), so
three binds it with no sampler and reads it with textureLoad. That is
what gives a toon ramp its hard steps.
Sourcepub fn data_rgba8(width: u32, height: u32, data: Vec<u8>) -> Self
pub fn data_rgba8(width: u32, height: u32, data: Vec<u8>) -> Self
new DataTexture( new Uint8Array( data ), width, height ) — the
defaults, RGBAFormat + UnsignedByteType (rgba8unorm, or
rgba8unorm-srgb once the colour space is set to sRGB), with
DataTexture’s own flipY = false, generateMipmaps = false and
NearestFilter on both sides. webgpu_textures_partialupdate’s
source for copyTextureToTexture.
Sourcepub fn data_rgba16float(width: u32, height: u32, data: &[u16]) -> Self
pub fn data_rgba16float(width: u32, height: u32, data: &[u16]) -> Self
new DataTexture( new Uint16Array( data ), width, height, RGBAFormat, HalfFloatType ) — what DataTextureLoader builds from
HdrLoader::parse’s half-float
result.
DataTexture’s constructor differs from Texture’s in three places
(DataTexture.js): flipY = false, generateMipmaps = false and
minFilter = magFilter = NearestFilter. HDRLoader’s texData then
sets both filters back to LinearFilter and flipY to true, which
HdrLoader::load does; the cube
loader leaves flipY at the DataTexture default. The colour space
is NoColorSpace here, and the loaders then set
LinearSRGBColorSpace. Neither carries a transfer function, so
rgba16float is the right format and nothing is applied on sample.
data is one binary16 bit pattern per channel, four per texel, which is
the Uint16Array upstream hands write_texture unchanged.
Sourcepub fn data_rgba32float(width: u32, height: u32, data: &[f32]) -> Self
pub fn data_rgba32float(width: u32, height: u32, data: &[f32]) -> Self
new DataTexture( new Float32Array( data ), width, height, RGBAFormat, FloatType ) — the FloatType half of the same loader.
Sourcepub fn clone_texture(&self) -> Self
pub fn clone_texture(&self) -> Self
Texture.clone() — new Texture().copy( this ): a second texture over
the same image, with its own id, its own uv transform and its own
channel. Texture‘s Clone impl is JS’ assignment (a handle copy);
this is JS’ .clone(), and the two are deliberately different names.
Three shares the Source between the original and the clone, so the
WebGPU backend uploads the image once. This port keys its GPU textures
on the Texture id, so a clone is uploaded again — same texels, one
more upload. Nothing on this ladder clones more than a handful.
Sourcepub fn set_channel(&self, channel: usize)
pub fn set_channel(&self, channel: usize)
Sourcepub fn set_color_space(&self, color_space: ColorSpace)
pub fn set_color_space(&self, color_space: ColorSpace)
texture.colorSpace = SRGBColorSpace. As with CubeTexture, the
transfer function is applied by the GPU on sample — the format becomes
rgba8unorm-srgb and WGSLNodeBuilder.needsToWorkingColorSpace() stays
false, so no colour-space node appears in the generated WGSL.
WebGPUTextureUtils.getFormat() picks the -srgb twin of whatever
the format is — rgba8unorm-srgb, bc7-rgba-unorm-srgb,
astc-4x4-unorm-srgb — and leaves a format that has none (the float
formats, BC4/BC5/BC6H) alone, which is what wgpu’s
add_srgb_suffix / remove_srgb_suffix do.
Sourcepub fn color_space(&self) -> ColorSpace
pub fn color_space(&self) -> ColorSpace
texture.colorSpace.
Sourcepub fn set_flip_y(&self, flip_y: bool)
pub fn set_flip_y(&self, flip_y: bool)
texture.flipY — an upload-time concern only. Texture.updateMatrix()
goes through Matrix3.setUvTransform( offset, repeat, rotation, center ),
which has no flipY term, so the texture matrix is unaffected.
Sourcepub fn set_generate_mipmaps(&self, generate_mipmaps: bool)
pub fn set_generate_mipmaps(&self, generate_mipmaps: bool)
texture.generateMipmaps = value.
Sourcepub fn set_mipmaps(&self, mipmaps: Vec<Image>)
pub fn set_mipmaps(&self, mipmaps: Vec<Image>)
texture.mipmaps[ i ] = image for every level at once. The levels
must halve from the texture’s own size down, as WebGPU’s mip chain
does; the upload writes each into its level and generates none.
Sourcepub fn set_min_filter(&self, min_filter: MinFilter)
pub fn set_min_filter(&self, min_filter: MinFilter)
texture.minFilter = value.
Sourcepub fn set_mag_filter(&self, mag_filter: TextureFilter)
pub fn set_mag_filter(&self, mag_filter: TextureFilter)
texture.magFilter = value.
Sourcepub fn borrow(&self) -> Ref<'_, TextureInner>
pub fn borrow(&self) -> Ref<'_, TextureInner>
Borrows the texture’s full state.
Sourcepub fn set_wrapping(&self, wrap_s: Wrapping, wrap_t: Wrapping)
pub fn set_wrapping(&self, wrap_s: Wrapping, wrap_t: Wrapping)
texture.wrapS = texture.wrapT = wrapping.
Sourcepub fn set_anisotropy(&self, anisotropy: u16)
pub fn set_anisotropy(&self, anisotropy: u16)
texture.anisotropy = n.
Sourcepub fn set_repeat(&self, x: f64, y: f64)
pub fn set_repeat(&self, x: f64, y: f64)
texture.repeat.set( x, y ) — and updateMatrix(), which three.js runs
for us every frame because matrixAutoUpdate is on by default.
Sourcepub fn set_offset(&self, x: f64, y: f64)
pub fn set_offset(&self, x: f64, y: f64)
texture.offset.set( x, y ).
Sourcepub fn set_center(&self, x: f64, y: f64)
pub fn set_center(&self, x: f64, y: f64)
texture.center.set( x, y ).
Sourcepub fn set_rotation(&self, rotation: f64)
pub fn set_rotation(&self, rotation: f64)
texture.rotation = theta.
Sourcepub fn update_matrix(&self)
pub fn update_matrix(&self)
Texture.updateMatrix().
Sourcepub fn set_matrix(&self, matrix: Matrix3)
pub fn set_matrix(&self, matrix: Matrix3)
texture.matrix.set( … ) with texture.matrixAutoUpdate = false — the
escape hatch GLTFTextureTransformExtension uses, because glTF composes
its uv transform as T * R * S and three.js as T * S * R. There is no
matrixAutoUpdate field here: the matrix is read once, when the texture
node is built, so an override simply has to be the last write.
Sourcepub fn matrix(&self) -> Matrix3
pub fn matrix(&self) -> Matrix3
Texture.matrix — what TextureNode.setupUV() multiplies the UV by.
Sourcepub fn set_size(&self, width: u32, height: u32)
pub fn set_size(&self, width: u32, height: u32)
texture.image.width = width; texture.image.height = height.
Sourcepub fn data_len(&self) -> usize
pub fn data_len(&self) -> usize
The byte length one full mip-0 image of this texture takes: width * height * the format's texel size, which is what set_data asserts
and what the renderer uploads.
Sourcepub fn set_data(&self, data: Vec<u8>)
pub fn set_data(&self, data: Vec<u8>)
texture.image.data.set( data ); texture.needsUpdate = true — new
pixels for a texture that has already been uploaded, at the same size
and format.
This is the per-frame path for a texture whose contents change but whose
allocation should not: a screencast frame, an shm client buffer, a video
texture. The renderer writes the bytes into the GPU texture it already
has (and regenerates the mip chain if generate_mipmaps) instead of
destroying and re-creating it, so the texture, its view and the bind
groups built from it survive.
Unlike Material::set_needs_update, no separate call is needed: setting
the data is the change, so this bumps the version itself. Panics if
data is not exactly data_len bytes — a short
buffer would otherwise shear or tear the image rather than fail.
Calling it on a Texture::external or a render target’s texture is a
mistake: the renderer does not own those and will not upload into them.
Sourcepub fn set_needs_update(&self)
pub fn set_needs_update(&self)
texture.needsUpdate = true: bump the version so the next frame
re-uploads the image into the GPU texture the renderer already has.
set_data does this for you; this is for forcing a
re-upload of bytes that were not replaced through it.
Sourcepub fn version(&self) -> u32
pub fn version(&self) -> u32
Texture.version — how many times the image has been marked changed.
The renderer’s texture cache is keyed on ( id, version ).
Sourcepub fn with_gpu<R>(&self, f: impl FnOnce(&Texture) -> R) -> R
pub fn with_gpu<R>(&self, f: impl FnOnce(&Texture) -> R) -> R
Runs f with the uploaded GPU texture. Panics if the texture has not
been uploaded yet.
Sourcepub fn format(&self) -> TextureFormat
pub fn format(&self) -> TextureFormat
The GPU format this texture uploads as, or renders into.
Sourcepub fn set_format(&self, format: TextureFormat)
pub fn set_format(&self, format: TextureFormat)
Sets the GPU format to use if the renderer has to create the texture — a render target’s attachment.
Sourcepub fn set_texture_type(&self, texture_type: TextureType)
pub fn set_texture_type(&self, texture_type: TextureType)
texture.type = UnsignedByteType — three.js names a render target
attachment’s storage by its data type, and
WebGPUTextureUtils.getFormat() turns that into the GPU format. Set it
on an attachment of a PassNode’s target before the first frame, the
way webgpu_postprocessing_bloom_emissive sets it on the emissive
output so the bloom chain reads an LDR texture.
Panics for a depth type, as color_gpu_format() does.
Sourcepub fn mip_level_count(&self) -> u32
pub fn mip_level_count(&self) -> u32
Texture.mipmapCount — floor( log2( max( w, h ) ) ) + 1, or the
length of mipmaps when the texture brings its own.