diff options
Diffstat (limited to 'doc/classes/Image.xml')
| -rw-r--r-- | doc/classes/Image.xml | 121 |
1 files changed, 85 insertions, 36 deletions
diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 3b108468de..9d87c9bf9a 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -4,12 +4,26 @@ Image datatype. </brief_description> <description> - Native image datatype. Contains image data, which can be converted to a [Texture2D], and several functions to interact with it. The maximum width and height for an [Image] are [constant MAX_WIDTH] and [constant MAX_HEIGHT]. - [b]Note:[/b] The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images will fail to import. + Native image datatype. Contains image data which can be converted to an [ImageTexture] and provides commonly used [i]image processing[/i] methods. The maximum width and height for an [Image] are [constant MAX_WIDTH] and [constant MAX_HEIGHT]. + An [Image] cannot be assigned to a [code]texture[/code] property of an object directly (such as [Sprite2D]), and has to be converted manually to an [ImageTexture] first. + [b]Note:[/b] The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import. </description> <tutorials> + <link title="Importing images">https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html</link> </tutorials> <methods> + <method name="adjust_bcs"> + <return type="void"> + </return> + <argument index="0" name="brightness" type="float"> + </argument> + <argument index="1" name="contrast" type="float"> + </argument> + <argument index="2" name="saturation" type="float"> + </argument> + <description> + </description> + </method> <method name="blend_rect"> <return type="void"> </return> @@ -66,13 +80,13 @@ Blits [code]src_rect[/code] area from [code]src[/code] image to this image at the coordinates given by [code]dst[/code]. [code]src[/code] pixel is copied onto [code]dst[/code] if the corresponding [code]mask[/code] pixel's alpha value is not 0. [code]src[/code] image and [code]mask[/code] image [b]must[/b] have the same size (width and height) but they can have different formats. </description> </method> - <method name="bumpmap_to_normalmap"> + <method name="bump_map_to_normal_map"> <return type="void"> </return> <argument index="0" name="bump_scale" type="float" default="1.0"> </argument> <description> - Converts a bumpmap to a normalmap. A bumpmap provides a height offset per-pixel, while a normalmap provides a normal direction per pixel. + Converts a bump map to a normal map. A bump map provides a height offset per-pixel, while a normal map provides a normal direction per pixel. </description> </method> <method name="clear_mipmaps"> @@ -226,7 +240,7 @@ <argument index="0" name="renormalize" type="bool" default="false"> </argument> <description> - Generates mipmaps for the image. Mipmaps are pre-calculated and lower resolution copies of the image. Mipmaps are automatically used if the image needs to be scaled down when rendered. This improves image quality and the performance of the rendering. Returns an error if the image is compressed, in a custom format or if the image's width/height is 0. + Generates mipmaps for the image. Mipmaps are precalculated and lower resolution copies of the image. Mipmaps are automatically used if the image needs to be scaled down when rendered. This improves image quality and the performance of the rendering. Returns an error if the image is compressed, in a custom format or if the image's width/height is 0. </description> </method> <method name="get_data" qualifiers="const"> @@ -267,16 +281,18 @@ <argument index="1" name="y" type="int"> </argument> <description> - Returns the color of the pixel at [code](x, y)[/code]. This is the same as [method get_pixelv], but with two integer arguments instead of a [Vector2] argument. + Returns the color of the pixel at [code](x, y)[/code]. + This is the same as [method get_pixelv], but with two integer arguments instead of a [Vector2i] argument. </description> </method> <method name="get_pixelv" qualifiers="const"> <return type="Color"> </return> - <argument index="0" name="src" type="Vector2"> + <argument index="0" name="point" type="Vector2i"> </argument> <description> - Returns the color of the pixel at [code]src[/code]. This is the same as [method get_pixel], but with a [Vector2] argument instead of two integer arguments. + Returns the color of the pixel at [code]point[/code]. + This is the same as [method get_pixel], but with a [Vector2i] argument instead of two integer arguments. </description> </method> <method name="get_rect" qualifiers="const"> @@ -344,6 +360,8 @@ </argument> <description> Loads an image from file [code]path[/code]. See [url=https://docs.godotengine.org/en/latest/getting_started/workflow/assets/importing_images.html#supported-image-formats]Supported image formats[/url] for a list of supported image formats and limitations. + [b]Warning:[/b] This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the [code]user://[/code] directory, and may not work in exported projects. + See also [ImageTexture] description for usage examples. </description> </method> <method name="load_bmp_from_buffer"> @@ -392,11 +410,11 @@ Loads an image from the binary contents of a WebP file. </description> </method> - <method name="normalmap_to_xy"> + <method name="normal_map_to_xy"> <return type="void"> </return> <description> - Converts the image's data to represent coordinates on a 3D plane. This is used when the image represents a normalmap. A normalmap can add lots of detail to a 3D surface without increasing the polygon count. + Converts the image's data to represent coordinates on a 3D plane. This is used when the image represents a normal map. A normal map can add lots of detail to a 3D surface without increasing the polygon count. </description> </method> <method name="premultiply_alpha"> @@ -416,7 +434,7 @@ <argument index="2" name="interpolation" type="int" enum="Image.Interpolation" default="1"> </argument> <description> - Resizes the image to the given [code]width[/code] and [code]height[/code]. New pixels are calculated using [code]interpolation[/code]. See [code]interpolation[/code] constants. + Resizes the image to the given [code]width[/code] and [code]height[/code]. New pixels are calculated using the [code]interpolation[/code] mode defined via [enum Interpolation] constants. </description> </method> <method name="resize_to_po2"> @@ -424,8 +442,10 @@ </return> <argument index="0" name="square" type="bool" default="false"> </argument> + <argument index="1" name="interpolation" type="int" enum="Image.Interpolation" default="1"> + </argument> <description> - Resizes the image to the nearest power of 2 for the width and height. If [code]square[/code] is [code]true[/code] then set width and height to be the same. + Resizes the image to the nearest power of 2 for the width and height. If [code]square[/code] is [code]true[/code] then set width and height to be the same. New pixels are calculated using the [code]interpolation[/code] mode defined via [enum Interpolation] constants. </description> </method> <method name="rgbe_to_srgb"> @@ -471,28 +491,56 @@ <argument index="2" name="color" type="Color"> </argument> <description> - Sets the [Color] of the pixel at [code](x, y)[/code]. Example: - [codeblock] + Sets the [Color] of the pixel at [code](x, y)[/code] to [code]color[/code]. Example: + [codeblocks] + [gdscript] + var img_width = 10 + var img_height = 5 var img = Image.new() img.create(img_width, img_height, false, Image.FORMAT_RGBA8) - img.set_pixel(x, y, color) - [/codeblock] + + img.set_pixel(1, 2, Color.red) # Sets the color at (1, 2) to red. + [/gdscript] + [csharp] + int imgWidth = 10; + int imgHeight = 5; + var img = new Image(); + img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + + img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red. + [/csharp] + [/codeblocks] + This is the same as [method set_pixelv], but with a two integer arguments instead of a [Vector2i] argument. </description> </method> <method name="set_pixelv"> <return type="void"> </return> - <argument index="0" name="dst" type="Vector2"> + <argument index="0" name="point" type="Vector2i"> </argument> <argument index="1" name="color" type="Color"> </argument> <description> - Sets the [Color] of the pixel at [code](dst.x, dst.y)[/code]. Note that the [code]dst[/code] values must be integers. Example: - [codeblock] + Sets the [Color] of the pixel at [code]point[/code] to [code]color[/code]. Example: + [codeblocks] + [gdscript] + var img_width = 10 + var img_height = 5 var img = Image.new() img.create(img_width, img_height, false, Image.FORMAT_RGBA8) - img.set_pixelv(Vector2(x, y), color) - [/codeblock] + + img.set_pixelv(Vector2i(1, 2), Color.red) # Sets the color at (1, 2) to red. + [/gdscript] + [csharp] + int imgWidth = 10; + int imgHeight = 5; + var img = new Image(); + img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + + img.SetPixelv(new Vector2i(1, 2), Colors.Red); // Sets the color at (1, 2) to red. + [/csharp] + [/codeblocks] + This is the same as [method set_pixel], but with a [Vector2i] argument instead of two integer arguments. </description> </method> <method name="shrink_x2"> @@ -512,7 +560,7 @@ </methods> <members> <member name="data" type="Dictionary" setter="_set_data" getter="_get_data" default="{"data": PackedByteArray( ),"format": "Lum8","height": 0,"mipmaps": false,"width": 0}"> - Holds all of the image's color data in a given format. See [enum Format] constants. + Holds all the image's color data in a given format. See [enum Format] constants. </member> </members> <constants> @@ -602,18 +650,19 @@ <constant name="FORMAT_BPTC_RGBFU" value="24" enum="Format"> Texture format that uses [url=https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression]BPTC[/url] compression with unsigned floating-point RGB components. </constant> - <constant name="FORMAT_PVRTC2" value="25" enum="Format"> + <constant name="FORMAT_PVRTC1_2" value="25" enum="Format"> Texture format used on PowerVR-supported mobile platforms, uses 2-bit color depth with no alpha. More information can be found [url=https://en.wikipedia.org/wiki/PVRTC]here[/url]. [b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed. </constant> - <constant name="FORMAT_PVRTC2A" value="26" enum="Format"> - Same as [url=https://en.wikipedia.org/wiki/PVRTC]PVRTC2[/url], but with an alpha component. + <constant name="FORMAT_PVRTC1_2A" value="26" enum="Format"> + Same as [constant FORMAT_PVRTC1_2], but with an alpha component. </constant> - <constant name="FORMAT_PVRTC4" value="27" enum="Format"> - Similar to [url=https://en.wikipedia.org/wiki/PVRTC]PVRTC2[/url], but with 4-bit color depth and no alpha. + <constant name="FORMAT_PVRTC1_4" value="27" enum="Format"> + Texture format used on PowerVR-supported mobile platforms, uses 4-bit color depth with no alpha. More information can be found [url=https://en.wikipedia.org/wiki/PVRTC]here[/url]. + [b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed. </constant> - <constant name="FORMAT_PVRTC4A" value="28" enum="Format"> - Same as [url=https://en.wikipedia.org/wiki/PVRTC]PVRTC4[/url], but with an alpha component. + <constant name="FORMAT_PVRTC1_4A" value="28" enum="Format"> + Same as [constant FORMAT_PVRTC1_4], but with an alpha component. </constant> <constant name="FORMAT_ETC" value="29" enum="Format"> [url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC1]Ericsson Texture Compression format 1[/url], also referred to as "ETC1", and is part of the OpenGL ES graphics standard. This format cannot store an alpha channel. @@ -680,18 +729,18 @@ <constant name="COMPRESS_S3TC" value="0" enum="CompressMode"> Use S3TC compression. </constant> - <constant name="COMPRESS_PVRTC2" value="1" enum="CompressMode"> - Use PVRTC2 compression. - </constant> - <constant name="COMPRESS_PVRTC4" value="2" enum="CompressMode"> - Use PVRTC4 compression. + <constant name="COMPRESS_PVRTC1_4" value="1" enum="CompressMode"> + Use PVRTC1 4-bpp compression. </constant> - <constant name="COMPRESS_ETC" value="3" enum="CompressMode"> + <constant name="COMPRESS_ETC" value="2" enum="CompressMode"> Use ETC compression. </constant> - <constant name="COMPRESS_ETC2" value="4" enum="CompressMode"> + <constant name="COMPRESS_ETC2" value="3" enum="CompressMode"> Use ETC2 compression. </constant> + <constant name="COMPRESS_BPTC" value="4" enum="CompressMode"> + Use BPTC compression. + </constant> <constant name="USED_CHANNELS_L" value="0" enum="UsedChannels"> </constant> <constant name="USED_CHANNELS_LA" value="1" enum="UsedChannels"> |