Added performance mode settings so that Texture2D's can be downsized at runtime for performance reasons

Author: LizzyTB

core/io/image.cpp

@@ -783,7 +783,7 @@ Image::PerformanceMode Image::get_performance_mode() const {
 
 void Image::set_performance_mode(PerformanceMode p_performance_mode) {
 	switch (performance_mode) {
-		case PERFORMANCE_MODE_ORIGINAL_RESOLUTION:
+		case PERFORMANCE_MODE_ORIGINAL_SIZE:
 			break;
 
 		default:
@@ -796,11 +796,11 @@ void Image::set_performance_mode(PerformanceMode p_performance_mode) {
 	Vector2i desired_size = size;
 
 	switch (performance_mode) {
-		case PERFORMANCE_MODE_ORIGINAL_RESOLUTION:
+		case PERFORMANCE_MODE_ORIGINAL_SIZE:
 			break;
 
-		case PERFORMANCE_MODE_MAX_RESOLUTION: {
-			Vector2i max_size = GLOBAL_GET("rendering/textures/performance/max_resolution");
+		case PERFORMANCE_MODE_MAX_SIZE: {
+			Vector2i max_size = GLOBAL_GET("rendering/textures/performance/max_size");
 
 			if (desired_size.x > max_size.x) {
 				desired_size.x = max_size.x;
@@ -813,7 +813,7 @@ void Image::set_performance_mode(PerformanceMode p_performance_mode) {
 			break;
 		}
 
-		case PERFORMANCE_MODE_DOWNSCALE_RESOLUTION: {
+		case PERFORMANCE_MODE_DOWNSCALE_SIZE: {
 			int factor = GLOBAL_GET("rendering/textures/performance/downscale_factor");
 			factor = CLAMP(factor, 1, 14);
 
@@ -1535,7 +1535,7 @@ void Image::resize(int p_width, int p_height, Interpolation p_interpolation) {
 	}
 
 	_copy_internals_from(dst);
-	performance_mode = PERFORMANCE_MODE_ORIGINAL_RESOLUTION;
+	performance_mode = PERFORMANCE_MODE_ORIGINAL_SIZE;
 }
 
 void Image::crop_from_point(int p_x, int p_y, int p_width, int p_height) {
@@ -2351,7 +2351,7 @@ void Image::initialize_data(int p_width, int p_height, bool p_use_mipmaps, Forma
 
 	mipmaps = p_use_mipmaps;
 
-	performance_mode = PERFORMANCE_MODE_ORIGINAL_RESOLUTION;
+	performance_mode = PERFORMANCE_MODE_ORIGINAL_SIZE;
 }
 
 void Image::initialize_data(const char **p_xpm) {
@@ -2361,7 +2361,7 @@ void Image::initialize_data(const char **p_xpm) {
 	mipmaps = false;
 	bool has_alpha = false;
 
-	performance_mode = PERFORMANCE_MODE_ORIGINAL_RESOLUTION;
+	performance_mode = PERFORMANCE_MODE_ORIGINAL_SIZE;
 
 	enum Status {
 		READING_HEADER,
@@ -3759,9 +3759,9 @@ void Image::_bind_methods() {
 	BIND_CONSTANT(MAX_WIDTH);
 	BIND_CONSTANT(MAX_HEIGHT);
 
-	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_ORIGINAL_RESOLUTION);
-	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_MAX_RESOLUTION);
-	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_DOWNSCALE_RESOLUTION);
+	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_ORIGINAL_SIZE);
+	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_MAX_SIZE);
+	BIND_ENUM_CONSTANT(PERFORMANCE_MODE_DOWNSCALE_SIZE);
 	BIND_ENUM_CONSTANT(FORMAT_L8);
 	BIND_ENUM_CONSTANT(FORMAT_LA8);
 	BIND_ENUM_CONSTANT(FORMAT_R8);

core/io/image.h

@@ -72,9 +72,9 @@ class Image : public Resource {
 	};
 
 	enum PerformanceMode {
-		PERFORMANCE_MODE_ORIGINAL_RESOLUTION,
-		PERFORMANCE_MODE_MAX_RESOLUTION,
-		PERFORMANCE_MODE_DOWNSCALE_RESOLUTION
+		PERFORMANCE_MODE_ORIGINAL_SIZE,
+		PERFORMANCE_MODE_MAX_SIZE,
+		PERFORMANCE_MODE_DOWNSCALE_SIZE
 	};
 
 	enum Format : int32_t {
@@ -255,7 +255,7 @@ class Image : public Resource {
 	static void _bind_methods();
 
 private:
-	PerformanceMode performance_mode = PERFORMANCE_MODE_ORIGINAL_RESOLUTION;
+	PerformanceMode performance_mode = PERFORMANCE_MODE_ORIGINAL_SIZE;
 	Format format = FORMAT_L8;
 	Vector<uint8_t> data;
 	int width = 0;

doc/classes/Image.xml

@@ -249,35 +249,35 @@
 				Returns the number of mipmap levels or 0 if the image has no mipmaps. The largest main level image is not counted as a mipmap level by this method, so if you want to include it you can add 1 to this count.
 			</description>
 		</method>
+		<method name="get_mipmap_offset" qualifiers="const">
+			<return type="int" />
+			<param index="0" name="mipmap" type="int" />
+			<description>
+				Returns the offset where the image's mipmap with index [param mipmap] is stored in the [member data] dictionary.
+			</description>
+		</method>
 		<method name="get_original_height" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the original height of the [Image] after the performance mode has been set.
+				Returns the original height of the [Image] after the [enum PerformanceMode] has been set.
 			</description>
 		</method>
 		<method name="get_original_size" qualifiers="const">
 			<return type="Vector2i" />
 			<description>
-				Returns the original size of the [Image] after the performance mode has been set.
+				Returns the original size of the [Image] after the [enum PerformanceMode] has been set.
 			</description>
 		</method>
 		<method name="get_original_width" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the original width of the [Image] after the performance mode has been set.
+				Returns the original width of the [Image] after the [enum PerformanceMode] has been set.
 			</description>
 		</method>
 		<method name="get_performance_mode" qualifiers="const">
-			<return type="PerformanceMode" />
+			<return type="int" enum="Image.PerformanceMode" />
 			<description>
-				Returns the image's current [PerformanceMode]
-			</description>
-		</method>
-		<method name="get_mipmap_offset" qualifiers="const">
-			<return type="int" />
-			<param index="0" name="mipmap" type="int" />
-			<description>
-				Returns the offset where the image's mipmap with index [param mipmap] is stored in the [member data] dictionary.
+				Returns the image's current [enum PerformanceMode]
 			</description>
 		</method>
 		<method name="get_pixel" qualifiers="const">
@@ -584,7 +584,7 @@
 		</method>
 		<method name="set_performance_mode">
 			<return type="void" />
-			<param index="0" name="performance_mode" type="PerformanceMode" />
+			<param index="0" name="performance_mode" type="int" enum="Image.PerformanceMode" />
 			<description>
 				Sets the performance mode of the [Image]. This will change the size of the [Image] based on settings in [ProjectSettings].
 				[method get_size] will return this new size. The original size is always available using [method get_original_size].
@@ -655,7 +655,7 @@
 		</method>
 	</methods>
 	<members>
-		<member name="data" type="Dictionary" setter="_set_data" getter="_get_data" default="{ &quot;data&quot;: PackedByteArray(), &quot;format&quot;: &quot;Lum8&quot;, &quot;height&quot;: 0, &quot;mipmaps&quot;: false, &quot;width&quot;: 0 }">
+		<member name="data" type="Dictionary" setter="_set_data" getter="_get_data" default="{ &quot;data&quot;: PackedByteArray(), &quot;format&quot;: &quot;Lum8&quot;, &quot;height&quot;: 0, &quot;mipmaps&quot;: false, &quot;original_height&quot;: 0, &quot;original_width&quot;: 0, &quot;width&quot;: 0 }">
 			Holds all the image's color data in a given format. See [enum Format] constants.
 		</member>
 	</members>
@@ -666,14 +666,14 @@
 		<constant name="MAX_HEIGHT" value="16777216">
 			The maximal height allowed for [Image] resources.
 		</constant>
-		<constant name="PERFORMANCE_MODE_ORIGINAL_RESOLUTION" value="0" enum="PerformanceMode">
-			Keeps the original width and height of the [Image].
+		<constant name="PERFORMANCE_MODE_ORIGINAL_SIZE" value="0" enum="PerformanceMode">
+			Keeps the original size of the [Image].
 		</constant>
-		<constant name="PERFORMANCE_MODE_MAX_RESOLUTION" value="1" enum="PerformanceMode">
-			Resizes if needed the width and height of the [Image] to fit into [member ProjectSettings.rendering/textures/performance/max_resolution]'s.
+		<constant name="PERFORMANCE_MODE_MAX_SIZE" value="1" enum="PerformanceMode">
+			Ensures that the size of the [Image] is smaller then or equals to the size specified at [member ProjectSettings.rendering/textures/performance/max_size].
 		</constant>
-		<constant name="PERFORMANCE_MODE_DOWNSCALE_RESOLUTION" value="2" enum="PerformanceMode">
-			Downscales the width and height of the [Image] [member ProjectSettings.rendering/textures/performance/downscale_factor] times.
+		<constant name="PERFORMANCE_MODE_DOWNSCALE_SIZE" value="2" enum="PerformanceMode">
+			Reduces the size of [Image] logarithmically according to the equation [code]size = max(floor(original_size / pow(2, downscale_factor)), Vector2i.ONE)[/code], getting downscale_factor from [member ProjectSettings.rendering/textures/performance/downscale_factor].
 		</constant>
 		<constant name="FORMAT_L8" value="0" enum="Format">
 			Texture format with a single 8-bit depth representing luminance.

doc/classes/ProjectSettings.xml

@@ -3351,15 +3351,13 @@
 			If [code]true[/code], the texture importer will import lossless textures using the PNG format. Otherwise, it will default to using WebP.
 		</member>
 		<member name="rendering/textures/performance/default_mode" type="int" setter="" getter="" default="0">
-			The default [member Image.PerformanceMode] of imported [Texture2D]'s. In the [b]Original Resolution[/b], the [Texture2D] resolution is unaffected.
-			[b]Max Resolution[/b] will ensure the [Texture2D]'s width and height are below [member rendering/textures/performance/max_resolution]. The equation is [code]size = min(max_resolution, original_size)[/code].
-			[b]Downscale Resolution[/b] will half the [Texture2D]'s width and height [member rendering/textures/performance/downscale_factor] times. The equation is [code]code = floor(original_size / pow(2, downscale_factor))[/code].
+			Changes the [enum Image.PerformanceMode] used by [Texture2D] when loaded into a scene. [b]Original Size[/b] keeps the [Texture2D] original size. [b]Max Size[/b] ensures that the size of [Texture2D] is smaller then the size at [member rendering/textures/performance/max_size]. [b]Downscale Factor[/b] reduces the size logarithmically according to the equation [code]size = max(floor(original_size / pow(2, downscale_factor)), Vector2i.ONE)[/code], getting downscale_factor from [member rendering/textures/performance/downscale_factor].
 		</member>
 		<member name="rendering/textures/performance/downscale_factor" type="int" setter="" getter="" default="1">
-			If the performance mode is set to [code]Downscale Factor[/code], then this will be used to determin how many times each [Texture2D]'s width and height get's halved.
+			Determines how much a [Texture2D][Image] size will be reduces when the [enum Image.PerformanceMode] is set to [constant Image.PERFORMANCE_MODE_DOWNSCALE_SIZE].
 		</member>
-		<member name="rendering/textures/performance/max_resolution" type="Vector2i" setter="" getter="" default="Vector2i(2048, 2048)">
-			If the performance mode is set to [code]Max Resolution[/code], then this will be used to determin how big each [Texture2D]'s width and height can be.
+		<member name="rendering/textures/performance/max_size" type="Vector2i" setter="" getter="" default="Vector2i(2048, 2048)">
+			The maximum size a [Texture2D]/[Image] can be when the [enum Image.PerformanceMode] is set to [constant Image.PERFORMANCE_MODE_MAX_SIZE].
 		</member>
 		<member name="rendering/textures/vram_compression/cache_gpu_compressor" type="bool" setter="" getter="" default="true">
 			If [code]true[/code], the GPU texture compressor will cache the local RenderingDevice and its resources (shaders and pipelines), allowing for faster subsequent imports at a memory cost.

doc/classes/ResourceImporterTexture.xml

@@ -73,9 +73,8 @@
 		<member name="mipmaps/limit" type="int" setter="" getter="" default="-1">
 			Unimplemented. This currently has no effect when changed.
 		</member>
-		<member name="performance/force_original_resolution" type="bool" setter="" getter="" default="false">
-			If [code]true[/code], then the imported image will always be at full resolution and will not be scaled down according to the active [member Image.PerformanceMode].
-			[b]Node:[/b] This does nothing if the [member Image.PerformanceMode] is set to [code]Original Resolution[/code] in the [ProjectSettings].
+		<member name="performance/force_original_size" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], then the engine will ignore [member ProjectSettings.rendering/textures/performance/default_mode] and will always load the image at full size.
 		</member>
 		<member name="process/channel_remap/alpha" type="int" setter="" getter="" default="3">
 			Specifies the data source of the output image's alpha channel.

editor/import/resource_importer_texture.cpp

@@ -231,7 +231,7 @@ String ResourceImporterTexture::get_preset_name(int p_idx) const {
 }
 
 void ResourceImporterTexture::get_import_options(const String &p_path, List<ImportOption> *r_options, int p_preset) const {
-	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "performance/force_original_resolution"), false));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "performance/force_original_size"), false));
 
 	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "compress/mode", PROPERTY_HINT_ENUM, "Lossless,Lossy,VRAM Compressed,VRAM Uncompressed,Basis Universal", PROPERTY_USAGE_DEFAULT | PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED), p_preset == PRESET_3D ? 2 : 0));
 	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "compress/high_quality"), false));
@@ -353,7 +353,7 @@ void ResourceImporterTexture::save_to_ctex_format(Ref<FileAccess> f, const Ref<I
 	}
 }
 
-void ResourceImporterTexture::_save_ctex(const Ref<Image> &p_image, const String &p_to_path, CompressMode p_compress_mode, float p_lossy_quality, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, bool p_mipmaps, bool p_streamable, bool p_detect_3d, bool p_detect_roughness, bool p_detect_normal, bool p_force_normal, bool p_force_original_resolution, bool p_srgb_friendly, bool p_force_po2_for_compressed, uint32_t p_limit_mipmap, const Ref<Image> &p_normal, Image::RoughnessChannel p_roughness_channel) {
+void ResourceImporterTexture::_save_ctex(const Ref<Image> &p_image, const String &p_to_path, CompressMode p_compress_mode, float p_lossy_quality, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, bool p_mipmaps, bool p_streamable, bool p_detect_3d, bool p_detect_roughness, bool p_detect_normal, bool p_force_normal, bool p_force_original_size, bool p_srgb_friendly, bool p_force_po2_for_compressed, uint32_t p_limit_mipmap, const Ref<Image> &p_normal, Image::RoughnessChannel p_roughness_channel) {
 	Ref<FileAccess> f = FileAccess::open(p_to_path, FileAccess::WRITE);
 	ERR_FAIL_COND(f.is_null());
 
@@ -386,8 +386,8 @@ void ResourceImporterTexture::_save_ctex(const Ref<Image> &p_image, const String
 	if (p_detect_normal) {
 		flags |= CompressedTexture2D::FORMAT_BIT_DETECT_NORMAL;
 	}
-	if (p_force_original_resolution) {
-		flags |= CompressedTexture2D::FORMAT_BIT_FORCE_ORIGINAL_RESOLUTION;
+	if (p_force_original_size) {
+		flags |= CompressedTexture2D::FORMAT_BIT_FORCE_ORIGINAL_SIZE;
 	}
 
 	f->store_32(flags);
@@ -707,7 +707,7 @@ Error ResourceImporterTexture::import(ResourceUID::ID p_source_id, const String
 	// Parse import options.
 	int32_t loader_flags = ImageFormatLoader::FLAG_NONE;
 
-	const bool force_original_resolution = p_options["performance/force_original_resolution"];
+	const bool force_original_size = p_options["performance/force_original_size"];
 
 	// Compression.
 	CompressMode compress_mode = CompressMode(int(p_options["compress/mode"]));
@@ -936,7 +936,7 @@ Error ResourceImporterTexture::import(ResourceUID::ID p_source_id, const String
 
 		if (force_uncompressed) {
 			_save_ctex(image, p_save_path + ".ctex", COMPRESS_VRAM_UNCOMPRESSED, lossy, basisu_params, Image::COMPRESS_S3TC /* This is ignored. */,
-					mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_resolution, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
+					mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_size, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
 		} else {
 			if (can_s3tc_bptc) {
 				Image::CompressMode image_compress_mode;
@@ -950,7 +950,7 @@ Error ResourceImporterTexture::import(ResourceUID::ID p_source_id, const String
 				}
 
 				_save_ctex(image, p_save_path + "." + image_compress_format + ".ctex", compress_mode, lossy, basisu_params, image_compress_mode, mipmaps,
-						stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_resolution, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
+						stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_size, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
 				r_platform_variants->push_back(image_compress_format);
 			}
 
@@ -966,19 +966,19 @@ Error ResourceImporterTexture::import(ResourceUID::ID p_source_id, const String
 				}
 
 				_save_ctex(image, p_save_path + "." + image_compress_format + ".ctex", compress_mode, lossy, basisu_params, image_compress_mode, mipmaps, stream, detect_3d,
-						detect_roughness, detect_normal, force_normal, force_original_resolution, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
+						detect_roughness, detect_normal, force_normal, force_original_size, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
 				r_platform_variants->push_back(image_compress_format);
 			}
 		}
 	} else {
 		// Import normally.
 		_save_ctex(image, p_save_path + ".ctex", compress_mode, lossy, basisu_params, Image::COMPRESS_S3TC /* This is ignored. */,
-				mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_resolution, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
+				mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_size, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
 	}
 
 	if (editor_image.is_valid()) {
 		_save_ctex(editor_image, p_save_path + ".editor.ctex", compress_mode, lossy, basisu_params, Image::COMPRESS_S3TC /* This is ignored. */,
-				mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_resolution, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
+				mipmaps, stream, detect_3d, detect_roughness, detect_normal, force_normal, force_original_size, srgb_friendly_pack, false, mipmap_limit, normal_image, roughness_channel);
 
 		// Generate and save editor-specific metadata, which we cannot save to the .import file.
 		Dictionary editor_meta;

editor/import/resource_importer_texture.h

@@ -86,7 +86,7 @@ class ResourceImporterTexture : public ResourceImporter {
 	static ResourceImporterTexture *singleton;
 	static const char *compression_formats[];
 
-	void _save_ctex(const Ref<Image> &p_image, const String &p_to_path, CompressMode p_compress_mode, float p_lossy_quality, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, bool p_mipmaps, bool p_streamable, bool p_detect_3d, bool p_detect_srgb, bool p_detect_normal, bool p_force_normal, bool p_force_original_resolution, bool p_srgb_friendly, bool p_force_po2_for_compressed, uint32_t p_limit_mipmap, const Ref<Image> &p_normal, Image::RoughnessChannel p_roughness_channel);
+	void _save_ctex(const Ref<Image> &p_image, const String &p_to_path, CompressMode p_compress_mode, float p_lossy_quality, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, bool p_mipmaps, bool p_streamable, bool p_detect_3d, bool p_detect_srgb, bool p_detect_normal, bool p_force_normal, bool p_force_original_size, bool p_srgb_friendly, bool p_force_po2_for_compressed, uint32_t p_limit_mipmap, const Ref<Image> &p_normal, Image::RoughnessChannel p_roughness_channel);
 	void _save_editor_meta(const Dictionary &p_metadata, const String &p_to_path);
 	Dictionary _load_editor_meta(const String &p_to_path) const;
 

editor/project_manager/project_dialog.cpp

@@ -568,7 +568,7 @@ void ProjectDialog::ok_pressed() {
 		} else {
 			fa_import->store_line("[params]");
 			fa_import->store_line("");
-			fa_import->store_line("performance/force_original_resolution=true");
+			fa_import->store_line("performance/force_original_size=true");
 			fa_import->close();
 		}