From 73c6b8db2fd548fe1808af3e1bf9496b9f81aac8 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sat, 22 Jul 2023 01:16:21 +0200 Subject: [PATCH] Document performance caveats of RGB image formats versus RGBA --- doc/classes/Image.xml | 5 +++++ doc/classes/ImageTexture.xml | 1 + doc/classes/ImageTexture3D.xml | 1 + doc/classes/RenderingServer.xml | 3 +++ 4 files changed, 10 insertions(+) diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 81954dd7de50..ee2b8729af10 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -107,6 +107,7 @@ 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. @@ -124,6 +125,7 @@ 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. @@ -135,6 +137,7 @@ 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. @@ -487,6 +490,7 @@ 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. @@ -582,6 +586,7 @@ 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. OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 8. diff --git a/doc/classes/ImageTexture.xml b/doc/classes/ImageTexture.xml index 3ac13dded1c0..596becb269b3 100644 --- a/doc/classes/ImageTexture.xml +++ b/doc/classes/ImageTexture.xml @@ -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. diff --git a/doc/classes/ImageTexture3D.xml b/doc/classes/ImageTexture3D.xml index a36271d67b2c..d1a768c76909 100644 --- a/doc/classes/ImageTexture3D.xml +++ b/doc/classes/ImageTexture3D.xml @@ -20,6 +20,7 @@ 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. diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 868079a51667..953a0a12387e 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -3254,7 +3254,10 @@ + 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.