Class
EditableImage
NotCreatable
Object which allows for the runtime creation and manipulation of images.
EditableImage allows for the runtime creation and manipulation of images.
To create a blank EditableImage, use
AssetService:CreateEditableImage(). To create an EditableImage from
an existing image, use AssetService:CreateEditableImageAsync().
EditableImage can be used in any Content property which takes an
image, such as ImageLabel.ImageContent or
MeshPart.TextureContent. This is done by setting the content property
to Datatype.Content.fromObject(editableImage).
The EditableImage coordinate system is relative to the top left of the
image:
- Top-left:
(0, 0) - Bottom-right:
(Size.X - 1, Size.Y - 1)
When you use AssetService:PromptCreatePlatformContentAsync() to
publish an object that has a Content property which references an
EditableImage, the editable image is published as an image and the property
is set to a new asset ID.
Update Limitations#
Only a single EditableImage can be updated per frame on the display side.
For example, if you update three EditableImage objects which are currently
being displayed, it will take three frames for all of them to be updated.
Enabling for Published Experiences#
For security purposes, using EditableImage fails by default for published
experiences. To enable usage, you must be 13+ age verified and ID verified.
After you are verified, open the
Creator Dashboard and toggle
on Enable Mesh / Image APIs.
Permissions#
To prevent misuse, AssetService:CreateEditableImageAsync() only allows
you to load and edit image assets if any of the following is true:
- Owned by or explicitly shared with the experience owner.
- Owned by or explicitly shared with the logged in Studio user.
- Owned by or explicitly shared with the logged in player if the
EditableImageis on the client side. - Owned by a group where the experience owner, Studio user, or player has a role with permission to edit the group's assets. See Roles and permissions for more information.
See Grant permissions to learn how to share assets with users or groups.
The APIs throw an error if they are used to load an asset that does not meet the criteria above.
Memory Limits#
Editable assets are currently expensive for memory usage. To minimize its
impact on client performance, EditableImage has strict client-side memory
budgets, although the server, Studio, and plugins operate with unlimited
memory. Linking one EditableImage to multiple image-related
Content data types (multi-referencing) can help with memory
optimization.
Properties 1#
Size: Vector2#
ReadOnlyNotReplicatedReadSafe
Size of the EditableImage in pixels. The maximum size is
1024×1024. An EditableImage cannot be resized; this property is
read-only. In order to resize or crop an image, create a new
EditableImage and use
DrawImageTransformed() to
transfer the contents; then call
Destroy().
Methods 10#
| Destroy | Destroys the image contents and immediately reclaims the memory they use. |
| DrawCircle | Draws a circle at the specified point. |
| DrawImage | Draws another EditableImage into this EditableImage at the given
position. |
| DrawImageProjected | Projects another EditableImage onto a surface using an
EditableMesh or prepared WrapTextureTransfer and stores
the result on this EditableImage. |
| SampleImageProjected | Projects pixels from a texture into this EditableImage using an
EditableMesh or prepared WrapTextureTransfer. |
| DrawImageTransformed | Draws an image into this EditableImage with transformations including
scaling and rotation, placing it at the specified position. |
| DrawLine | Draws a line between two provided points. |
| DrawRectangle | Draws a rectangle of the given size at the given top-left position. |
| ReadPixelsBuffer | Reads a rectangular region of pixels into a buffer.SafeCustomLuaState |
| WritePixelsBuffer | Writes a rectangular region of pixels into the image.CustomLuaState |
Destroy(): ()#
Destroys the contents of the image, immediately reclaiming used memory.
Returns
()
DrawCircle(center: Vector2, radius: int, color: Color3, transparency: float, combineType: ImageCombineType, antiAliasing: AntiAliasing = Enabled): ()#
Draws a circle at the specified point on the EditableImage. If the
circle is semi-transparent, it will be blended with the pixels behind it
using source over blending.
| Name | Type | Default | Description |
|---|---|---|---|
center | Vector2 | Center of the circle, relative to the top-left corner of the
EditableImage. Positions outside the canvas bounds are allowed. | |
radius | int | Radius of the circle in pixels. | |
color | Color3 | Color of the circle. | |
transparency | float | Transparency of the circle with 0 being fully opaque and 1 being fully transparent. | |
combineType | ImageCombineType | How the drawn pixels (source) are combined with the existing pixels of this image (destination). | |
antiAliasing | AntiAliasing | Enabled | Determines whether anti-aliasing is applied to the circle. When set to
AntiAliasing.Enabled, circle edges are soft. When set to
AntiAliasing.Disabled, circle edges are hard. |
Returns
()
DrawImage(position: Vector2, image: EditableImage, combineType: ImageCombineType): ()#
Draws another EditableImage into this EditableImage at the given
position. Positions outside the canvas bounds are allowed such that only
part of the new image is drawn.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | Position at which the top-left corner of the source image will be drawn. | |
image | EditableImage | The source EditableImage to draw into this EditableImage. | |
combineType | ImageCombineType | How the pixels of the source image are combined with the existing pixels of this image (destination). |
Returns
()
DrawImageProjected(projectionSource: Object, projection: Dictionary, brushConfig: Dictionary): ()#
Projects another EditableImage onto the surface defined by
projectionSource and stores the result on this EditableImage using the
source's UV mapping and the specified projection and brush configuration.
projectionSource accepts an EditableMesh or a
WrapTextureTransfer.
When passing a WrapTextureTransfer, first call
WrapTextureTransfer:PrepareProjectionMeshDataAsync() and wait for
it to complete successfully.
| Name | Type | Default | Description |
|---|---|---|---|
projectionSource | Object | The EditableMesh or prepared WrapTextureTransfer that
provides the geometry and UV mapping for projection. | |
projection | Dictionary | Projection configuration dictionary including the following key-value pairs: | |
brushConfig | Dictionary | Brush configuration dictionary including the following key-value pairs:
|
Returns
()
SampleImageProjected(projectionSource: Object, sourceTexture: EditableImage, projectionConfig: Dictionary, brushConfig: Dictionary): ()#
Projects the pixels in sourceTexture, using the geometry and UV mapping
of projectionSource, onto this EditableImage. projectionSource
accepts an EditableMesh or a WrapTextureTransfer. This is
the inverse of
DrawImageProjected(): it reads
from the mesh texture and writes the sampled pixels into this image in
place.
Only mesh surfaces facing the projector and within the projection volume
are sampled. When multiple mesh surfaces project to the same destination
pixel, the closest surface is used. This makes the method suitable for
sampling a brush-sized region, modifying it in place, and then using
DrawImageProjected() to write
it back onto a texture.
When passing a WrapTextureTransfer, first call
WrapTextureTransfer:PrepareProjectionMeshDataAsync() and wait for
it to complete successfully.
| Name | Type | Default | Description |
|---|---|---|---|
projectionSource | Object | The EditableMesh or prepared WrapTextureTransfer that
maps sourceTexture onto the surface being sampled. | |
sourceTexture | EditableImage | The EditableImage from which pixels are sampled. | |
projectionConfig | Dictionary | Projection configuration dictionary containing the following key-value pairs:
| |
brushConfig | Dictionary | Brush configuration dictionary containing the following key-value pairs:
|
Returns
()
DrawImageTransformed(position: Vector2, scale: Vector2, rotation: float, image: EditableImage, options: Dictionary?): ()#
This method lets you draw an EditableImage into this EditableImage
with transformations applied, such as scaling and rotation. The position
parameter specifies where the pivot point of the source image will be
placed on this image after transformations. Positions outside the canvas
bounds are allowed such that only part of the new image is drawn.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | Position in pixels where the pivot point of the source image will be placed on this image. | |
scale | Vector2 | Scaling factors for the source image along the X and Y axes. | |
rotation | float | The rotation angle in degrees, applied around the pivot point of the source image. | |
image | EditableImage | The source EditableImage to be drawn into this image. | |
options | Dictionary? | Optional dictionary for additional configuration:
|
Returns
()
DrawLine(p1: Vector2, p2: Vector2, color: Color3, transparency: float, combineType: ImageCombineType, antiAliasing: AntiAliasing = Enabled): ()#
Draws a line on the EditableImage one pixel thick between the two
provided points.
| Name | Type | Default | Description |
|---|---|---|---|
p1 | Vector2 | Start point of the line. | |
p2 | Vector2 | End point of the line. | |
color | Color3 | Color of the line. | |
transparency | float | Transparency of the line. | |
combineType | ImageCombineType | How the drawn pixels (source) are combined with the existing pixels of this image (destination). | |
antiAliasing | AntiAliasing | Enabled | Determines whether anti-aliasing is applied to the line. When set to
AntiAliasing.Enabled, line edges are soft. When set to
AntiAliasing.Disabled, line edges are hard. |
Returns
()
DrawRectangle(position: Vector2, size: Vector2, color: Color3, transparency: float, combineType: ImageCombineType): ()#
Draws a rectangle on the EditableImage of the given size at the given
top-left position.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | Position of the top-left of the rectangle. Unlike other drawing
methods, this cannot be outside the canvas bounds of the
EditableImage. | |
size | Vector2 | Size of the rectangle to draw, in pixels. | |
color | Color3 | Color of the rectangle. | |
transparency | float | Transparency of the rectangle. | |
combineType | ImageCombineType | How the drawn pixels (source) are combined with the existing pixels of this image (destination). |
Returns
()
ReadPixelsBuffer(position: Vector2, size: Vector2): buffer#
CustomLuaStateSafe
Reads a rectangular region of pixels from an EditableImage and returns
it as a buffer. Each number in the buffer is a single byte, with pixels
stored in a sequence of four bytes (red, green, blue, and alpha).
Note that this method uses alpha instead of transparency, unlike the
EditableImage drawing methods.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | Top-left corner of the rectangular region of pixels to read. | |
size | Vector2 | Size of the rectangular region of pixels to read. |
Returns
buffer— Buffer where each pixel is represented by four bytes (red, green, blue and alpha respectively). The length of the buffer can be calculated asSize.X * Size.Y * 4bytes.
WritePixelsBuffer(position: Vector2, size: Vector2, buffer: buffer): ()#
CustomLuaState
Writes a rectangular region of pixels to an EditableImage from a buffer.
Each number in the buffer is a single byte, with pixels stored in a
sequence of four bytes (red, green, blue, and alpha).
Note that this method uses alpha instead of transparency, unlike the
EditableImage drawing methods.
| Name | Type | Default | Description |
|---|---|---|---|
position | Vector2 | Top-left corner of the rectangular region to draw the pixels into. | |
size | Vector2 | Size of the rectangular region of pixels to write. | |
buffer | buffer | A buffer where each pixel is represented by four bytes (red, green,
blue, and alpha respectively). The length of the buffer should be
Size.X * Size.Y * 4 bytes. |
Returns
()