Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document performance caveats of RGB image formats versus RGBA #79771

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+10 −0
Open

Document performance caveats of RGB image formats versus RGBA #79771

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/classes/Image.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@
<param index="0" name="format" type="int" enum="Image.Format" />
<description>
Converts the image's format. See [enum Format] constants.
[b]Note:[/b] Converting to [constant FORMAT_RGBA8] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[b]Note:[/b] Converting to [constant FORMAT_RGBA8] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
[b]Note:[/b] Converting to [constant FORMAT_RGB8] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], or for images without a blue channel, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBH] and [constant FORMAT_RGBF] versus their RGBA/RG/R counterparts.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can at least do without the bit-alignment piece of knowledge.

Suggested change
[b]Note:[/b] Converting to [constant FORMAT_RGBA8] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
[b]Note:[/b] Converting to [constant FORMAT_RGB8] is [i]very[/i] slow. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], [constant FORMAT_RG8], or [constant FORMAT_R8], which are faster. The same applies to [constant FORMAT_RGBH] and [constant FORMAT_RGBF] compared to their RGBA/RG/R counterparts.

Or

Suggested change
[b]Note:[/b] Converting to [constant FORMAT_RGBA8] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
[b]Note:[/b] Converting to [constant FORMAT_RGB8] is [i]very[/i] slow. If you need to frequently convert an image, consider using [constant FORMAT_RGBA8]. If possible, [constant FORMAT_RG8] or [constant FORMAT_R8] are faster. The same applies to [constant FORMAT_RGBH] and [constant FORMAT_RGBF] compared to their RGBA/RG/R counterparts.

Or similar.

Copy link
Member

@aaronfranke aaronfranke Nov 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like we can make the text both informative and user-friendly by taking your suggestion but prepending "Due to memory alignment reasons," or appending "This slowness happens due to memory alignment reasons."

</description>
</method>
<method name="copy_from">
Expand All @@ -124,6 +125,7 @@
<param index="3" name="format" type="int" enum="Image.Format" />
<description>
Creates an empty image of given size and format. See [enum Format] constants. If [param use_mipmaps] is [code]true[/code], then generate mipmaps for this image. See the [method generate_mipmaps].
[b]Note:[/b] Creating an image in [constant FORMAT_RGBA8] [param format] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently create an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
<method name="create_from_data" qualifiers="static">
Expand All @@ -135,6 +137,7 @@
<param index="4" name="data" type="PackedByteArray" />
<description>
Creates a new image of given size and format. See [enum Format] constants. Fills the image with the given raw data. If [param use_mipmaps] is [code]true[/code] then loads mipmaps for this image from [param data]. See [method generate_mipmaps].
[b]Note:[/b] Creating an image in [constant FORMAT_RGBA8] [param format] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently create an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
<method name="crop">
Expand Down Expand Up @@ -487,6 +490,7 @@
<param index="4" name="data" type="PackedByteArray" />
<description>
Overwrites data of an existing [Image]. Non-static equivalent of [method create_from_data].
[b]Note:[/b] Setting image data with the [constant FORMAT_RGBA8] [param format] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently set image data, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
<method name="set_pixel">
Expand Down Expand Up @@ -582,6 +586,7 @@
<constant name="FORMAT_RGB8" value="4" enum="Format">
OpenGL texture format [code]RGB[/code] with three components, each with a bitdepth of 8.
[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
[b]Note:[/b] This format is slow to procedurally create and update, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently create or update an image, consider using [constant FORMAT_RGBA8], or better, [constant FORMAT_RG8] or [constant FORMAT_R8] if possible. The same applies to [constant FORMAT_RGBAH] and [constant FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</constant>
<constant name="FORMAT_RGBA8" value="5" enum="Format">
OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 8.
Expand Down
1 change: 1 addition & 0 deletions doc/classes/ImageTexture.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@
Replaces the texture's data with a new [Image].
[b]Note:[/b] The texture has to be created using [method create_from_image] or initialized first with the [method set_image] method before it can be updated. The new image dimensions, format, and mipmaps configuration should match the existing texture's image configuration.
Use this method over [method set_image] if you need to update the texture frequently, which is faster than allocating additional memory for a new texture each time.
[b]Note:[/b] Updating an [ImageTexture] that uses the [constant Image.FORMAT_RGBA8] format is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently update an [ImageTexture], consider using [constant Image.FORMAT_RGBA8], or better, [constant Image.FORMAT_RG8] or [constant Image.FORMAT_R8] if possible. The same applies to [constant Image.FORMAT_RGBAH] and [constant Image.FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
</methods>
Expand Down
1 change: 1 addition & 0 deletions doc/classes/ImageTexture3D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
<param index="5" name="data" type="Image[]" />
<description>
Creates the [ImageTexture3D] with specified [param width], [param height], and [param depth]. See [enum Image.Format] for [param format] options. If [param use_mipmaps] is [code]true[/code], then generate mipmaps for the [ImageTexture3D].
[b]Note:[/b] Creating an [ImageTexture3D] with the [constant Image.FORMAT_RGBA8] [param format] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently create an [ImageTexture3D], consider using [constant Image.FORMAT_RGBA8], or better, [constant Image.FORMAT_RG8] or [constant Image.FORMAT_R8] if possible. The same applies to [constant Image.FORMAT_RGBAH] and [constant Image.FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
<method name="update">
Expand Down
3 changes: 3 additions & 0 deletions doc/classes/RenderingServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3254,7 +3254,10 @@
<param index="4" name="mipmaps" type="bool" />
<param index="5" name="data" type="Image[]" />
<description>
Creates a 3-dimensional texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_3d_*[/code] RenderingServer functions.
Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method.
[b]Note:[/b] The equivalent resource is [Texture3D].
[b]Note:[/b] Creating a [Texture3D] with the [constant Image.FORMAT_RGBA8] [param format] is slow, as it is not aligned to 1, 2 or 4 bytes. If you need to frequently create a [Texture3D], consider using [constant Image.FORMAT_RGBA8], or better, [constant Image.FORMAT_RG8] or [constant Image.FORMAT_R8] if possible. The same applies to [constant Image.FORMAT_RGBAH] and [constant Image.FORMAT_RGBAF] versus their RGB/RG/R counterparts.
</description>
</method>
<method name="texture_3d_get" qualifiers="const">
Expand Down