Skip to main content

Texture

Struct Texture 

Source
pub struct Texture(/* private fields */);
Expand description

Cloning is a handle copy, as in JS.

Implementations§

Source§

impl Texture

Source

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.

Source

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.

Source

pub fn set_filters(&self, min_filter: MinFilter, mag_filter: TextureFilter)

texture.minFilter = min; texture.magFilter = mag.

Source

pub fn set_premultiply_alpha(&self, premultiply_alpha: bool)

texture.premultiplyAlpha = value.

Source

pub fn is_array(&self) -> bool

texture.isCompressedArrayTexture — sampled with a layer index through a texture_2d_array<f32> binding.

Source§

impl Texture

Source

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.

Source

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.

Source

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).

Source

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.

Source

pub fn is_storage(&self) -> bool

texture.isStorageTexture.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn id(&self) -> usize

texture.id — unique per texture, stable for its lifetime.

Source

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.

Source

pub fn channel(&self) -> usize

Texture.channel.

Source

pub fn set_channel(&self, channel: usize)

texture.channel = n. Only 0 and 1 have an accessor (uv and uv1), so anything else is refused here rather than silently sampled along uv.

Source

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.

Source

pub fn color_space(&self) -> ColorSpace

texture.colorSpace.

Source

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.

Source

pub fn set_generate_mipmaps(&self, generate_mipmaps: bool)

texture.generateMipmaps = value.

Source

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.

Source

pub fn set_min_filter(&self, min_filter: MinFilter)

texture.minFilter = value.

Source

pub fn set_mag_filter(&self, mag_filter: TextureFilter)

texture.magFilter = value.

Source

pub fn borrow(&self) -> Ref<'_, TextureInner>

Borrows the texture’s full state.

Source

pub fn wrapping(&self) -> (Wrapping, Wrapping)

( texture.wrapS, texture.wrapT ).

Source

pub fn set_wrapping(&self, wrap_s: Wrapping, wrap_t: Wrapping)

texture.wrapS = texture.wrapT = wrapping.

Source

pub fn set_anisotropy(&self, anisotropy: u16)

texture.anisotropy = n.

Source

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.

Source

pub fn set_offset(&self, x: f64, y: f64)

texture.offset.set( x, y ).

Source

pub fn set_center(&self, x: f64, y: f64)

texture.center.set( x, y ).

Source

pub fn set_rotation(&self, rotation: f64)

texture.rotation = theta.

Source

pub fn update_matrix(&self)

Texture.updateMatrix().

Source

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.

Source

pub fn matrix(&self) -> Matrix3

Texture.matrix — what TextureNode.setupUV() multiplies the UV by.

Source

pub fn size(&self) -> (u32, u32)

( texture.image.width, texture.image.height ).

Source

pub fn set_size(&self, width: u32, height: u32)

texture.image.width = width; texture.image.height = height.

Source

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.

Source

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.

Source

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.

Source

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 ).

Source

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.

Source

pub fn format(&self) -> TextureFormat

The GPU format this texture uploads as, or renders into.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for Texture

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Texture

The id is identity, not content: leaving it out keeps the Debug of a binding description — what examples/dump_wgsl.rs prints beside the WGSL — a function of the texture itself.

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.