rules

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

@@ -0,0 +1,485 @@
+# 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: []