rojo/.cursor/rules/roblox/reference/engine/classes/EditableImage.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: EditableImage
type: class
memory_category: Instances
summary: |
  Instance which allows for the runtime creation and manipulation of images.
description: |
  `EditableImage` allows for the runtime creation and manipulation of images.

  To create a blank `EditableImage`, use
  `Class.AssetService:CreateEditableImage()`. To create an `EditableImage` from
  an existing image, use `Class.AssetService:CreateEditableImageAsync()`.

  `EditableImage` can be used in any `Datatype.Content` property which takes an
  image, such as `Class.ImageLabel.ImageContent` or
  `Class.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 `Class.AssetService:PromptCreateAssetAsync()` to publish an
  object that has a `Datatype.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 Studio's
  [Experience Settings](../../../studio/experience-settings.md), select
  **Security**, and enable the **Allow Mesh / Image APIs** toggle.

  #### Permissions

  To prevent misuse, `Class.AssetService:CreateEditableImageAsync()` only allows
  you to load and edit image assets:

  - That are owned by the creator of the experience (if the experience is owned
    by an individual).
  - That are owned by a group (if the experience is owned by the group).
  - That are owned by the logged in Studio user (if the place file has not yet
    been saved or published to Roblox).

  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 `Class.EditableImage` to multiple image-related
  `Datatype.Content` data types (multi-referencing) can help with memory
  optimization.
code_samples: []
inherits:
  - Object
descendants: []
tags:
  - NotCreatable
deprecation_message: ''
properties:
  - name: EditableImage.Size
    summary: |
      Size of the `EditableImage` in pixels.
    description: |
      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
      `Class.EditableImage:DrawImageTransformed()|DrawImageTransformed()` to
      transfer the contents; then call
      `Class.EditableImage:Destroy()|Destroy()`.
    code_samples: []
    type: Vector2
    tags:
      - ReadOnly
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: true
    capabilities:
      - DynamicGeneration
methods:
  - name: EditableImage:Destroy
    summary: ''
    description: |
      Destroys the contents of the image, immediately reclaiming used memory.
    code_samples: []
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawCircle
    summary: |
      Draws a circle at the specified point.
    description: |
      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.
    code_samples: []
    parameters:
      - name: center
        type: Vector2
        default:
        summary: |
          Center of the circle, relative to the top-left corner of the
          `EditableImage`. Positions outside the canvas bounds are allowed.
      - name: radius
        type: int
        default:
        summary: |
          Radius of the circle in pixels.
      - name: color
        type: Color3
        default:
        summary: |
          Color of the circle.
      - name: transparency
        type: float
        default:
        summary: |
          Transparency of the circle with 0 being fully opaque and 1 being fully
          transparent.
      - name: combineType
        type: ImageCombineType
        default:
        summary: |
          How the pixels of the source image are blended with the pixels of the
          added image.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawImage
    summary: |
      Draws another `EditableImage` into this `EditableImage` at the given
      position.
    description: |
      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.
    code_samples: []
    parameters:
      - name: position
        type: Vector2
        default:
        summary: |
          Position at which the top-left corner of the added image will be
          drawn.
      - name: image
        type: EditableImage
        default:
        summary: |
          The `EditableImage` to draw into this `EditableImage`.
      - name: combineType
        type: ImageCombineType
        default:
        summary: |
          How the pixels of the source image should be blended with the pixels
          of the added image.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawImageProjected
    summary: |
      Projects another `EditableImage` into an `Class.EditableMesh` and stores
      the result on this `EditableImage`.
    description: |
      Projects another `EditableImage` into an `Class.EditableMesh` and stores
      the result on this `EditableImage` by using the specified projection and
      brush configuration.
    code_samples: []
    parameters:
      - name: mesh
        type: EditableMesh
        default:
        summary: |
          The `Class.EditableMesh` used to project into.
      - name: projection
        type: Dictionary
        default:
        summary: |
          Projection configuration dictionary including the following key-value
          pairs:

          - `Direction` (`Datatype.Vector3`) where the projector is facing.
          - `Position` (`Datatype.Vector3`) as the position in local space with
            respect to the mesh.
          - `Size` (`Datatype.Vector3`) as the size of the projector.
          - `Up` (`Datatype.Vector3`) as the up vector of the projector in local
            space with respect to the mesh.
      - name: brushConfig
        type: Dictionary
        default:
        summary: |
          Brush configuration dictionary including the following key-value
          pairs:

          - `AlphaBlendType` (`Enum.ImageAlphaType`) which determines how this
            projection will blend alpha values.
          - `ColorBlendType` (`Enum.ImageCombineType`) which determines how this
            projection will blend color values.
          - `Decal` (`EditableImage`) as the image used for projection.
          - `FadeAngle` (number) as the angle in degrees for the projection
            edges to start to fall off. The projection will be fully faded out
            at 90 degrees. An angle of 0 means fading starts immediately at 0
            degrees and an angle of 90 means no fading but instead a hard edge
            at 90 degrees. An angle of 70 degrees would mean the projection
            starts to fade at 70 degrees and is fully faded out at 90 degrees.
          - `BlendIntensity` (number) as the value between `0` and `1` which
            controls how much of the projection is blended into the resulting
            image.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawImageTransformed
    summary: |
      Draws an image into this `EditableImage` with transformations including
      scaling and rotation, placing it at the specified position.
    description: |
      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.
    code_samples:
      - EditableImage-DrawImageTransformed
      - EditableImage-DrawImageTransformed-Crop
    parameters:
      - name: position
        type: Vector2
        default:
        summary: |
          Position in pixels where the pivot point of the source image will be
          placed on this image.
      - name: scale
        type: Vector2
        default:
        summary: |
          Scaling factors for the source image along the X and Y axes.
      - name: rotation
        type: float
        default:
        summary: |
          The rotation angle in degrees, applied around the pivot point of the
          source image.
      - name: image
        type: EditableImage
        default:
        summary: |
          The source `EditableImage` to be drawn into this image.
      - name: options
        type: Dictionary?
        default:
        summary: |
          Optional dictionary for additional configuration:

          - `CombineType`: Specifies how the pixels of the source image blend
            with those of the destination. Default is
            `Enum.ImageCombineType.AlphaBlend`.
          - `SamplingMode`: Specifies the sampling method (e.g. `Default` for
            bilinear or `Pixelated` for nearest neighbor). Default is
            `Enum.ResamplerMode.Default`.
          - `PivotPoint`: Specifies the pivot point within the source image for
            scaling and rotation. Default is the center of the source image
            (i.e. `Image.Size / 2`).
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawLine
    summary: |
      Draws a line between two provided points.
    description: |
      Draws an anti-aliased line on the `EditableImage` one pixel thick between
      the two provided points.
    code_samples: []
    parameters:
      - name: p1
        type: Vector2
        default:
        summary: |
          Start point of the line.
      - name: p2
        type: Vector2
        default:
        summary: |
          End point of the line.
      - name: color
        type: Color3
        default:
        summary: |
          Color of the line.
      - name: transparency
        type: float
        default:
        summary: |
          Transparency of the line.
      - name: combineType
        type: ImageCombineType
        default:
        summary: |
          How the pixels of the source image are blended with the pixels of the
          added image.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:DrawRectangle
    summary: |
      Draws a rectangle of the given size at the given top-left position.
    description: |
      Draws a rectangle on the `EditableImage` of the given size at the given
      top-left position.
    code_samples: []
    parameters:
      - name: position
        type: Vector2
        default:
        summary: |
          Position of the top-left of the rectangle. Unlike other drawing
          methods, this cannot be outside the canvas bounds of the
          `EditableImage`.
      - name: size
        type: Vector2
        default:
        summary: |
          Size of the rectangle to draw, in pixels.
      - name: color
        type: Color3
        default:
        summary: |
          Color of the rectangle.
      - name: transparency
        type: float
        default:
        summary: |
          Transparency of the rectangle.
      - name: combineType
        type: ImageCombineType
        default:
        summary: |
          How the pixels of the source image are blended with the pixels of the
          added image.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:ReadPixelsBuffer
    summary: |
      Reads a rectangular region of pixels into a buffer.
    description: |
      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.
    code_samples:
      - EditableImage-ReadPixels1
    parameters:
      - name: position
        type: Vector2
        default:
        summary: |
          Top-left corner of the rectangular region of pixels to read.
      - name: size
        type: Vector2
        default:
        summary: |
          Size of the rectangular region of pixels to read.
    returns:
      - type: buffer
        summary: |
          Buffer where each pixel is represented by four bytes (red, green, blue
          and alpha respectively). The length of the buffer can be calculated as
          `Size.X * Size.Y * 4` bytes.
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Safe
    capabilities:
      - DynamicGeneration
  - name: EditableImage:WritePixelsBuffer
    summary: |
      Writes a rectangular region of pixels into the image.
    description: |
      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.
    code_samples:
      - EditableImage-ReadPixelsWritePixels1
    parameters:
      - name: position
        type: Vector2
        default:
        summary: |
          Top-left corner of the rectangular region to draw the pixels into.
      - name: size
        type: Vector2
        default:
        summary: |
          Size of the rectangular region of pixels to write.
      - name: buffer
        type: buffer
        default:
        summary: |
          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:
      - type: ()
        summary: ''
    tags:
      - CustomLuaState
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - DynamicGeneration
events: []
callbacks: []