BasisU: Use KTX2 format and add import options to configure encoder

Author: beicause

core/io/image.cpp

@@ -130,7 +130,7 @@ void (*Image::_image_decompress_astc)(Image *) = nullptr;
 Vector<uint8_t> (*Image::webp_lossy_packer)(const Ref<Image> &, float) = nullptr;
 Vector<uint8_t> (*Image::webp_lossless_packer)(const Ref<Image> &) = nullptr;
 Vector<uint8_t> (*Image::png_packer)(const Ref<Image> &) = nullptr;
-Vector<uint8_t> (*Image::basis_universal_packer)(const Ref<Image> &, Image::UsedChannels) = nullptr;
+Vector<uint8_t> (*Image::basis_universal_packer)(const Ref<Image> &p_image, Image::UsedChannels p_channels, const BasisUniversalPackerParams &p_basisu_params) = nullptr;
 
 Ref<Image> (*Image::webp_unpacker)(const Vector<uint8_t> &) = nullptr;
 Ref<Image> (*Image::png_unpacker)(const Vector<uint8_t> &) = nullptr;

core/io/image.h

@@ -182,6 +182,15 @@ class Image : public Resource {
 		ALPHA_BLEND
 	};
 
+	struct BasisUniversalPackerParams {
+		int uastc_level = 0;
+		bool rdo_enabled = false;
+		float rdo_quality_loss = 3;
+		int rdo_dict_size = 1024;
+		bool zstd_supercompression = true;
+		int zstd_supercompression_level = 6;
+	};
+
 	// External saver function pointers.
 
 	static SavePNGFunc save_png_func;
@@ -231,7 +240,7 @@ class Image : public Resource {
 	static Vector<uint8_t> (*webp_lossy_packer)(const Ref<Image> &p_image, float p_quality);
 	static Vector<uint8_t> (*webp_lossless_packer)(const Ref<Image> &p_image);
 	static Vector<uint8_t> (*png_packer)(const Ref<Image> &p_image);
-	static Vector<uint8_t> (*basis_universal_packer)(const Ref<Image> &p_image, UsedChannels p_channels);
+	static Vector<uint8_t> (*basis_universal_packer)(const Ref<Image> &p_image, Image::UsedChannels p_channels, const BasisUniversalPackerParams &p_basisu_params);
 
 	static Ref<Image> (*webp_unpacker)(const Vector<uint8_t> &p_buffer);
 	static Ref<Image> (*png_unpacker)(const Vector<uint8_t> &p_buffer);

doc/classes/PortableCompressedTexture2D.xml

@@ -43,6 +43,19 @@
 				Return whether the flag is overridden for all textures of this type.
 			</description>
 		</method>
+		<method name="set_basisu_compressor_params">
+			<return type="void" />
+			<param index="0" name="uastc_level" type="int" />
+			<param index="1" name="rdo_enabled" type="bool" />
+			<param index="2" name="rdo_quality_loss" type="float" />
+			<param index="3" name="rdo_dict_size" type="int" />
+			<param index="4" name="zstd_supercompression" type="bool" />
+			<param index="5" name="zstd_supercompression_level" type="int" />
+			<description>
+				Sets the compressor parameters for Basis Universal compression. See also the settings in [ResourceImporterTexture].
+				[b]Note:[/b] This must be set before [method create_from_image] to take effect.
+			</description>
+		</method>
 		<method name="set_keep_all_compressed_buffers" qualifiers="static">
 			<return type="void" />
 			<param index="0" name="keep" type="bool" />
@@ -55,6 +68,7 @@
 		<member name="keep_compressed_buffer" type="bool" setter="set_keep_compressed_buffer" getter="is_keeping_compressed_buffer" default="false">
 			When running on the editor, this class will keep the source compressed data in memory. Otherwise, the source compressed data is lost after loading and the resource can't be re saved.
 			This flag allows to keep the compressed data in memory if you intend it to persist after loading.
+			[b]Note:[/b] This must be set before [method create_from_image] to take effect.
 		</member>
 		<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" />
 		<member name="size_override" type="Vector2" setter="set_size_override" getter="get_size_override" default="Vector2(0, 0)">

doc/classes/ResourceImporterLayeredTexture.xml

@@ -10,6 +10,26 @@
 		<link title="Importing images">$DOCS_URL/tutorials/assets_pipeline/importing_images.html</link>
 	</tutorials>
 	<members>
+		<member name="basis_universal/rdo_dict_size" type="int" setter="" getter="" default="1024">
+			The dictionary size for RDO, ranging from [code]64[/code] to [code]65536[/code]. Higher values reduce the file size further, but significantly make encoding times longer.
+		</member>
+		<member name="basis_universal/rdo_enabled" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], enables Rate-Distortion Optimization (RDO) to reduce file size.
+			[b]Note:[/b] Enabling RDO significantly significantly makes encoding times longer, especially when [member basis_universal/rdo_dict_size] is high.
+		</member>
+		<member name="basis_universal/rdo_quality_loss" type="float" setter="" getter="" default="3.0">
+			The RDO quality loss, as a value ranging from [code]0.001[/code] to [code]50.0[/code]. Higher values result in smaller file sizes but lower quality. It is recommended to choose values from [code]0.25[/code] to [code]10.0[/code].
+		</member>
+		<member name="basis_universal/uastc_level" type="int" setter="" getter="" default="0">
+			Sets the UASTC encoding level, ranging from [code]0[/code] to [code]4[/code]. Higher values result in better quality but slower encoding speed.
+		</member>
+		<member name="basis_universal/zstd_supercompression" type="bool" setter="" getter="" default="true">
+			If [code]true[/code], enables Zstandard supercompression to reduce file size.
+			[b]Note:[/b] Basis Universal textures need to be compressed to gain the benefit of smaller file sizes, otherwise they are as large as VRAM-compressed textures.
+		</member>
+		<member name="basis_universal/zstd_supercompression_level" type="int" setter="" getter="" default="6">
+			Specify the Zstandard compression level, ranging from [code]1[/code] to [code]22[/code].
+		</member>
 		<member name="compress/channel_pack" type="int" setter="" getter="" default="0">
 			Controls how color channels should be used in the imported texture.
 			[b]sRGB Friendly:[/b], prevents the RG color format from being used, as it does not support sRGB color.

doc/classes/ResourceImporterTexture.xml

@@ -10,6 +10,26 @@
 		<link title="Importing images">$DOCS_URL/tutorials/assets_pipeline/importing_images.html</link>
 	</tutorials>
 	<members>
+		<member name="basis_universal/rdo_dict_size" type="int" setter="" getter="" default="1024">
+			The dictionary size for RDO, ranging from [code]64[/code] to [code]65536[/code]. Higher values reduce the file size further, but significantly make encoding times longer.
+		</member>
+		<member name="basis_universal/rdo_enabled" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], enables Rate-Distortion Optimization (RDO) to reduce file size.
+			[b]Note:[/b] Enabling RDO significantly significantly makes encoding times longer, especially when [member basis_universal/rdo_dict_size] is high.
+		</member>
+		<member name="basis_universal/rdo_quality_loss" type="float" setter="" getter="" default="3.0">
+			The RDO quality loss, as a value ranging from [code]0.001[/code] to [code]50.0[/code]. Higher values result in smaller file sizes but lower quality. It is recommended to choose values from [code]0.25[/code] to [code]10.0[/code].
+		</member>
+		<member name="basis_universal/uastc_level" type="int" setter="" getter="" default="0">
+			Sets the UASTC encoding level, ranging from [code]0[/code] to [code]4[/code]. Higher values result in better quality but slower encoding speed.
+		</member>
+		<member name="basis_universal/zstd_supercompression" type="bool" setter="" getter="" default="true">
+			If [code]true[/code], enables Zstandard supercompression to reduce file size.
+			[b]Note:[/b] Basis Universal textures need to be compressed to gain the benefit of smaller file sizes, otherwise they are as large as VRAM-compressed textures.
+		</member>
+		<member name="basis_universal/zstd_supercompression_level" type="int" setter="" getter="" default="6">
+			Specify the Zstandard compression level, ranging from [code]1[/code] to [code]22[/code].
+		</member>
 		<member name="compress/channel_pack" type="int" setter="" getter="" default="0">
 			Controls how color channels should be used in the imported texture.
 			[b]sRGB Friendly:[/b] Prevents the RG color format from being used, as it does not support sRGB color.

editor/import/resource_importer_layered_texture.cpp

@@ -125,6 +125,11 @@ bool ResourceImporterLayeredTexture::get_option_visibility(const String &p_path,
 	if ((p_option == "compress/high_quality" || p_option == "compress/hdr_compression") && p_options.has("compress/mode")) {
 		return int(p_options["compress/mode"]) == COMPRESS_VRAM_COMPRESSED;
 	}
+
+	if ((int)(p_options["compress/mode"]) != COMPRESS_BASIS_UNIVERSAL && p_option.begins_with("basis_universal/")) {
+		return false;
+	}
+
 	return true;
 }
 
@@ -156,9 +161,17 @@ void ResourceImporterLayeredTexture::get_import_options(const String &p_path, Li
 			r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "slices/amount", PROPERTY_HINT_RANGE, "1,1024,1,or_greater"), 1));
 		}
 	}
+
+	Image::BasisUniversalPackerParams basisu_params;
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/uastc_level", PROPERTY_HINT_ENUM, "Fastest,Faster,Medium,Slower,Slowest"), basisu_params.uastc_level));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "basis_universal/rdo_enabled"), basisu_params.rdo_enabled));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::FLOAT, "basis_universal/rdo_quality_loss", PROPERTY_HINT_RANGE, "0.001,50,0.001"), basisu_params.rdo_quality_loss));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/rdo_dict_size", PROPERTY_HINT_RANGE, "64,65536,1"), basisu_params.rdo_dict_size));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "basis_universal/zstd_supercompression"), basisu_params.zstd_supercompression));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/zstd_supercompression_level", PROPERTY_HINT_RANGE, "1,22,1"), basisu_params.zstd_supercompression_level));
 }
 
-void ResourceImporterLayeredTexture::_save_tex(Vector<Ref<Image>> p_images, const String &p_to_path, int p_compress_mode, float p_lossy, Image::CompressMode p_vram_compression, Image::CompressSource p_csource, Image::UsedChannels used_channels, bool p_mipmaps, bool p_force_po2) {
+void ResourceImporterLayeredTexture::_save_tex(Vector<Ref<Image>> p_images, const String &p_to_path, int p_compress_mode, float p_lossy, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, Image::CompressSource p_csource, Image::UsedChannels used_channels, bool p_mipmaps, bool p_force_po2) {
 	Vector<Ref<Image>> mipmap_images; //for 3D
 
 	if (mode == MODE_3D) {
@@ -278,11 +291,11 @@ void ResourceImporterLayeredTexture::_save_tex(Vector<Ref<Image>> p_images, cons
 	}
 
 	for (int i = 0; i < p_images.size(); i++) {
-		ResourceImporterTexture::save_to_ctex_format(f, p_images[i], ResourceImporterTexture::CompressMode(p_compress_mode), used_channels, p_vram_compression, p_lossy);
+		ResourceImporterTexture::save_to_ctex_format(f, p_images[i], ResourceImporterTexture::CompressMode(p_compress_mode), used_channels, p_vram_compression, p_lossy, p_basisu_params);
 	}
 
 	for (int i = 0; i < mipmap_images.size(); i++) {
-		ResourceImporterTexture::save_to_ctex_format(f, mipmap_images[i], ResourceImporterTexture::CompressMode(p_compress_mode), used_channels, p_vram_compression, p_lossy);
+		ResourceImporterTexture::save_to_ctex_format(f, mipmap_images[i], ResourceImporterTexture::CompressMode(p_compress_mode), used_channels, p_vram_compression, p_lossy, p_basisu_params);
 	}
 }
 
@@ -375,6 +388,16 @@ Error ResourceImporterLayeredTexture::import(ResourceUID::ID p_source_id, const
 			slices.push_back(slice);
 		}
 	}
+
+	const Image::BasisUniversalPackerParams basisu_params = {
+		p_options["basis_universal/uastc_level"],
+		p_options["basis_universal/rdo_enabled"],
+		p_options["basis_universal/rdo_quality_loss"],
+		p_options["basis_universal/rdo_dict_size"],
+		p_options["basis_universal/zstd_supercompression"],
+		p_options["basis_universal/zstd_supercompression_level"],
+	};
+
 	Array formats_imported;
 	Ref<LayeredTextureImport> texture_import;
 	texture_import.instantiate();
@@ -392,6 +415,8 @@ Error ResourceImporterLayeredTexture::import(ResourceUID::ID p_source_id, const
 	texture_import->used_channels = used_channels;
 	texture_import->high_quality = high_quality;
 
+	texture_import->basisu_params = basisu_params;
+
 	_check_compress_ctex(p_source_file, texture_import);
 	if (r_metadata) {
 		Dictionary meta;
@@ -486,7 +511,8 @@ void ResourceImporterLayeredTexture::_check_compress_ctex(const String &p_source
 	ERR_FAIL_NULL(r_texture_import->csource);
 	if (r_texture_import->compress_mode != COMPRESS_VRAM_COMPRESSED) {
 		// Import normally.
-		_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, Image::COMPRESS_S3TC /* IGNORED */, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, false);
+		_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, r_texture_import->basisu_params,
+				Image::COMPRESS_S3TC /* IGNORED */, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, false);
 		return;
 	}
 	// Must import in all formats, in order of priority (so platform chooses the best supported one. IE, etc2 over etc).
@@ -541,7 +567,8 @@ void ResourceImporterLayeredTexture::_check_compress_ctex(const String &p_source
 	}
 
 	if (use_uncompressed) {
-		_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + extension, COMPRESS_VRAM_UNCOMPRESSED, r_texture_import->lossy, Image::COMPRESS_S3TC /* IGNORED */, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, false);
+		_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + extension, COMPRESS_VRAM_UNCOMPRESSED, r_texture_import->lossy, r_texture_import->basisu_params,
+				Image::COMPRESS_S3TC /* IGNORED */, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, false);
 	} else {
 		if (can_s3tc_bptc) {
 			Image::CompressMode image_compress_mode;
@@ -553,7 +580,7 @@ void ResourceImporterLayeredTexture::_check_compress_ctex(const String &p_source
 				image_compress_mode = Image::COMPRESS_S3TC;
 				image_compress_format = "s3tc";
 			}
-			_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + image_compress_format + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, image_compress_mode, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, true);
+			_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + image_compress_format + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, r_texture_import->basisu_params, image_compress_mode, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, true);
 			r_texture_import->platform_variants->push_back(image_compress_format);
 		}
 
@@ -567,7 +594,7 @@ void ResourceImporterLayeredTexture::_check_compress_ctex(const String &p_source
 				image_compress_mode = Image::COMPRESS_ETC2;
 				image_compress_format = "etc2";
 			}
-			_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + image_compress_format + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, image_compress_mode, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, true);
+			_save_tex(*r_texture_import->slices, r_texture_import->save_path + "." + image_compress_format + "." + extension, r_texture_import->compress_mode, r_texture_import->lossy, r_texture_import->basisu_params, image_compress_mode, *r_texture_import->csource, r_texture_import->used_channels, r_texture_import->mipmaps, true);
 			r_texture_import->platform_variants->push_back(image_compress_format);
 		}
 	}

editor/import/resource_importer_layered_texture.h

@@ -49,6 +49,9 @@ class LayeredTextureImport : public RefCounted {
 	Vector<Ref<Image>> *slices = nullptr;
 	int compress_mode = 0;
 	float lossy = 1.0;
+
+	Image::BasisUniversalPackerParams basisu_params;
+
 	int hdr_compression = 0;
 	bool mipmaps = true;
 	bool high_quality = false;
@@ -108,7 +111,7 @@ class ResourceImporterLayeredTexture : public ResourceImporter {
 	virtual void get_import_options(const String &p_path, List<ImportOption> *r_options, int p_preset = 0) const override;
 	virtual bool get_option_visibility(const String &p_path, const String &p_option, const HashMap<StringName, Variant> &p_options) const override;
 
-	void _save_tex(Vector<Ref<Image>> p_images, const String &p_to_path, int p_compress_mode, float p_lossy, Image::CompressMode p_vram_compression, Image::CompressSource p_csource, Image::UsedChannels used_channels, bool p_mipmaps, bool p_force_po2);
+	void _save_tex(Vector<Ref<Image>> p_images, const String &p_to_path, int p_compress_mode, float p_lossy, const Image::BasisUniversalPackerParams &p_basisu_params, Image::CompressMode p_vram_compression, Image::CompressSource p_csource, Image::UsedChannels used_channels, bool p_mipmaps, bool p_force_po2);
 
 	virtual Error import(ResourceUID::ID p_source_id, const String &p_source_file, const String &p_save_path, const HashMap<StringName, Variant> &p_options, List<String> *r_platform_variants, List<String> *r_gen_files = nullptr, Variant *r_metadata = nullptr) override;