ImageTexture
GPU texture from Image for runtime pixel creation and updates.
Image stores CPU image data; ImageTexture makes those pixels usable as Texture2D. Create a nonempty Image, fill its pixels and pass it to CreateFromImage. Editing that Image later, or a GetImage copy, does not automatically update the texture.
Use Update for repeated uploads with unchanged dimensions, format and mipmaps. Use SetImage when those parameters change. SetSizeOverride changes logical size rather than pixel count; zero keeps the current axis instead of clearing an override. Account for the Update dimension contract after overriding.
Load ordinary imported project assets through ResourceLoader.Load<Texture2D>: their concrete type can be CompressedTexture2D rather than ImageTexture. Reading a source PNG as an external file is a separate path; a file existing in the editor does not guarantee export packaging. Size limits depend on GPU, format and backend; a single fixed number does not guarantee available memory.
Resource operations, pixel copies, updates, format replacement and independent reload were checked in Windows Forward+/Vulkan. UI rendering, export packaging, all formats and alpha-hit correctness after replacing an image were not established in this run.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
ImageTextureConstructor
public ImageTexture();Creates an uninitialized texture: dimensions are 0 and GetImage returns null. Before Update, assign a nonempty image through SetImage or use CreateFromImage. Having a RID alone does not establish uploaded pixels.
Properties1
ImageProperty
public Image Image { get; set; }Internal stored image property. The getter reads a separate image through GetImage; editing its pixels does not change the texture. The setter performs SetImage with data reallocation rather than Update. For frequent updates, use explicit Update with matching dimensions, format and mipmap configuration.
Methods4
CreateFromImageImageTexture
public static ImageTexture CreateFromImage(Image image);Creates a new GPU texture from an Image. Copies current pixels, format and existing mipmap chain; later edits to the separate Image do not automatically update this texture.
| Name | Type | Default |
|---|---|---|
image | Image | — |
imageNonempty Image. If downscaled rendering needs mipmaps, generate them before texture creation and check GenerateMipmaps success.
ImageTextureNew ImageTexture, or null for an invalid empty/null image. To display it, assign the resource to Sprite2D.Texture or another suitable receiver.
SetImagevoid
public void SetImage(Image image);Initializes or replaces texture data from a nonempty Image. Allows different dimensions, format and mipmap configuration by creating new GPU storage. Replacing an existing texture preserves its RID through texture_replace. Pixels are copied: later source Image changes require a separate upload. This void method returns no error code. Use Update when parameters are unchanged.
| Name | Type | Default |
|---|---|---|
image | Image | — |
imageNonempty Image with the desired pixels and an already prepared mipmap chain if needed.
SetSizeOverridevoid
public void SetSizeOverride(Vector2I size);Changes logical texture dimensions without changing physical GetImage pixels. Only nonzero components replace current values: Vector2I.Zero does not restore anything, unlike DpiTexture. Use nonnegative values after initialization. The override changes the dimensions Update compares against its input Image: restore original dimensions explicitly before updating, or call SetImage. Do not use an override to increase resolution.
| Name | Type | Default |
|---|---|---|
size | Vector2I | — |
sizeLogical dimensions; 0 keeps the current size on that axis. These are not dimensions for a new raster copy.
Updatevoid
public void Update(Image image);Uploads new pixels to an initialized texture without replacing its dimensions or format. The input Image must match width, height, format and mipmap presence. Prepare the mipmap chain in Image before upload. On mismatch, the method reports an error rather than automatically resizing or converting. It returns no Error. CPU image edits are not uploaded automatically; GetImage also returns separate data.
| Name | Type | Default |
|---|---|---|
image | Image | — |
imageImage with exactly matching dimensions, format and mipmap configuration.