---
title: Texture
description: "A GPU texture resource. Public API wrapper that holds a shareable reference to the internal TextureObject and a numeric handle used by uniforms."
category: core
categoryLabel: Core
---

import { Code, Tabs, TabItem, Aside } from "@astrojs/starlight/components";

## Description

A GPU texture resource. Public API wrapper that holds a shareable reference to the internal TextureObject and a numeric handle used by uniforms.

- Construct via [Renderer](/api/core/renderer)::create_texture_* helpers (no direct constructors)
- Set on shaders with shader.set("key", &[Texture](/api/core/texture))
- [Texture](/api/core/texture) owns its sampler; you can tweak filtering and wrapping via set_sampler_options.

## How to use

Create a [Texture](/api/core/texture) and set it on a [Shader](/api/core/shader)



## Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
async fn run() -> Result<(), Box<dyn std::error::Error>> {

use fragmentcolor::{Renderer, Shader, Size};
let renderer = Renderer::new();
let shader = Shader::new(r#"
@group(0) @binding(0) var my_texture: texture_2d<f32>;
@group(0) @binding(1) var my_sampler: sampler;
@vertex fn vs_main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
  let p = array<vec2<f32>,3>(vec2f(-1.,-1.), vec2f(3.,-1.), vec2f(-1.,3.));
  return vec4f(p[i], 0., 1.);
}
@fragment fn main() -> @location(0) vec4<f32> { return vec4f(1.,1.,1.,1.); }
"#)?;

// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];
let texture = renderer.create_texture_with_size(pixels, [1,1]).await?;

// insert  the texture in the shader matching the name in the shader
shader.set("my_texture", &texture)?;

_ = shader;
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }
`}
lang="rust" meta="collapse={1-1, 22-25}"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`

import { Renderer, Shader } from "fragmentcolor";
const renderer = new Renderer();
const shader = new Shader(\`
@group(0) @binding(0) var my_texture: texture_2d<f32>;
@group(0) @binding(1) var my_sampler: sampler;
@vertex fn vs_main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
  let p = array<vec2<f32>,3>(vec2f(-1.,-1.), vec2f(3.,-1.), vec2f(-1.,3.));
  return vec4f(p[i], 0., 1.);
}
@fragment fn main() -> @location(0) vec4<f32> { return vec4f(1.,1.,1.,1.); }

\`);

// 1x1 RGBA (white) raw pixel bytes
const pixels = [255,255,255,255];
const texture = await renderer.createTextureWithSize(pixels, [1,1]);

// insert  the texture in the shader matching the name in the shader
shader.set("my_texture", texture);

`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`

from fragmentcolor import Renderer, Shader
renderer = Renderer()
shader = Shader("""
@group(0) @binding(0) var my_texture: texture_2d<f32>;
@group(0) @binding(1) var my_sampler: sampler;
@vertex fn vs_main(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
  let p = array<vec2<f32>,3>(vec2f(-1.,-1.), vec2f(3.,-1.), vec2f(-1.,3.));
  return vec4f(p[i], 0., 1.);
}
@fragment fn main() -> @location(0) vec4<f32> { return vec4f(1.,1.,1.,1.); }

""")

# 1x1 RGBA (white) raw pixel bytes
pixels = [255,255,255,255]
texture = renderer.create_texture_with_size(pixels, [1,1])

# insert  the texture in the shader matching the name in the shader
shader.set("my_texture", texture)

`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


## Methods


---

### Texture::size

Returns the texture size (w, h[, d]).

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, Size};
let renderer = Renderer::new();
let pixels: &[u8] = &[255,255,255,255];
let tex = renderer.create_texture_with_size(pixels, [1,1]).await?;
let sz = tex.size();
assert_eq!([sz.width, sz.height], [1, 1]);
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }
`}
lang="rust" meta="collapse={1-1, 7-10}"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Renderer } from "fragmentcolor";
const renderer = new Renderer();
const pixels = [255,255,255,255];
const tex = await renderer.createTextureWithSize(pixels, [1,1]);
const sz = tex.size();
`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Renderer
renderer = Renderer()
pixels = [255,255,255,255]
tex = renderer.create_texture_with_size(pixels, [1,1])
sz = tex.size
`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Texture::aspect

Returns width/height as f32.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
async fn run() -> Result<(), Box<dyn std::error::Error>> {

use fragmentcolor::{Renderer, Size};

let renderer = Renderer::new();
// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];
let tex = renderer.create_texture_with_size(pixels, [1, 1]).await?;
let a = tex.aspect();

assert!(a > 0.0);
Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }
`}
lang="rust" meta="collapse={1-1, 11-14}"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`

import { Renderer } from "fragmentcolor";

const renderer = new Renderer();
// 1x1 RGBA (white) raw pixel bytes
const pixels = [255,255,255,255];
const tex = await renderer.createTextureWithSize(pixels, [1, 1]);
const a = tex.aspect();

`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`

from fragmentcolor import Renderer

renderer = Renderer()
# 1x1 RGBA (white) raw pixel bytes
pixels = [255,255,255,255]
tex = renderer.create_texture_with_size(pixels, [1, 1])
a = tex.aspect()

`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>


---

### Texture::set_sampler_options

Update the texture sampler options (filtering, wrapping, etc.).

Note: changes take effect on next bind; the renderer recreates the sampler as needed.

#### Example

<Tabs>

<TabItem label="Rust">
<Code
code={`
async fn run() -> Result<(), Box<dyn std::error::Error>> {
use fragmentcolor::{Renderer, Size, SamplerOptions};
let renderer = Renderer::new();
// 1x1 RGBA (white) raw pixel bytes
let pixels: &[u8] = &[255,255,255,255];

let texture = renderer.create_texture_with_size(pixels, [1,1]).await?;
let opts = SamplerOptions { repeat_x: true, repeat_y: true, smooth: true, compare: None };
texture.set_sampler_options(opts);


Ok(())
}
fn main() -> Result<(), Box<dyn std::error::Error>> { pollster::block_on(run()) }
`}
lang="rust" meta="collapse={1-1, 12-14}"
/>

</TabItem>

<TabItem label="JavaScript">
<Code
code={`
import { Renderer } from "fragmentcolor";
const renderer = new Renderer();
// 1x1 RGBA (white) raw pixel bytes
const pixels = [255,255,255,255];

const texture = await renderer.createTextureWithSize(pixels, [1,1]);
const opts = {repeat_x: true, repeat_y: true, smooth: true, compare: null};
texture.setSamplerOptions(opts);


`}
lang="js"
/>

</TabItem>

<TabItem label="Python">
<Code
code={`
from fragmentcolor import Renderer
renderer = Renderer()
# 1x1 RGBA (white) raw pixel bytes
pixels = [255,255,255,255]

texture = renderer.create_texture_with_size(pixels, [1,1])
opts = {"repeat_x": True, "repeat_y": True, "smooth": True, "compare": None}
texture.set_sampler_options(opts)


`}
lang="python"
/>

</TabItem>

<TabItem label="Swift">
<Aside type="caution" title="Work in progress">Swift bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Swift placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

<TabItem label="Kotlin">
<Aside type="caution" title="Work in progress">Kotlin/Android bindings are not yet available; implementation is in the works.</Aside>
<Code
code={`
// Kotlin placeholder: bindings WIP

`}
lang="text"
/>

</TabItem>

</Tabs>
