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

Author: beicause

core/io/image.cpp

@@ -132,7 +132,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_pack_level = 0;
+		bool rdo_enabled = false;
+		float rdo_quality_loss = 1;
+		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_pack_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>
+				Set compressor params for Basis Universal compression. See also the settings in [ResourceImporterTexture].
+				Note: 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.
+			Note: 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,24 @@
 		<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">
+			Specify the RDO dict size, ranges from 64 to 65536. Higher values increase memory consumption and reduce encoding speed, but give more compression.
+		</member>
+		<member name="basis_universal/rdo_enabled" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], enables Rate-Distortion Optimization (RDO) to reduce disk size.
+		</member>
+		<member name="basis_universal/rdo_quality_loss" type="float" setter="" getter="" default="1.0">
+			Specify the RDO quality loss, ranges from 0.001 to 50.0. Higher value result in smaller file size but lower quality. Good range to try is from 0.25 to 10.0.
+		</member>
+		<member name="basis_universal/uastc_pack_level" type="int" setter="" getter="" default="0">
+			Sets the UASTC compressor's level, ranges from 0 to 4. Slower encoding speed improves quality.
+		</member>
+		<member name="basis_universal/zstd_supercompression" type="bool" setter="" getter="" default="true">
+			If [code]true[/code], enables Zstandard supercompression to reduce disk size.
+		</member>
+		<member name="basis_universal/zstd_supercompression_level" type="int" setter="" getter="" default="6">
+			Specify the compression level for Zstandard supercompression.
+		</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,24 @@
 		<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">
+			Specify the RDO dict size, ranges from 64 to 65536. Higher values increase memory consumption and reduce encoding speed, but give more compression.
+		</member>
+		<member name="basis_universal/rdo_enabled" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], enables Rate-Distortion Optimization (RDO) to reduce disk size.
+		</member>
+		<member name="basis_universal/rdo_quality_loss" type="float" setter="" getter="" default="1.0">
+			Specify the RDO quality loss, ranges from 0.001 to 50.0. Higher value result in smaller file size but lower quality. Good range to try is from 0.25 to 10.0.
+		</member>
+		<member name="basis_universal/uastc_pack_level" type="int" setter="" getter="" default="0">
+			Sets the UASTC compressor's level, ranges from 0 to 4. Slower encoding speed improves quality.
+		</member>
+		<member name="basis_universal/zstd_supercompression" type="bool" setter="" getter="" default="true">
+			If [code]true[/code], enables Zstandard supercompression to reduce disk size.
+		</member>
+		<member name="basis_universal/zstd_supercompression_level" type="int" setter="" getter="" default="6">
+			Specify the compression level for Zstandard supercompression.
+		</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

@@ -156,9 +156,16 @@ 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));
 		}
 	}
+
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/uastc_pack_level", PROPERTY_HINT_ENUM, "Fastest,Faster,Medium,Slower,Slowest"), 0));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "basis_universal/rdo_enabled"), false));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::FLOAT, "basis_universal/rdo_quality_loss", PROPERTY_HINT_RANGE, "0.001,50,0.001"), 1.0));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/rdo_dict_size", PROPERTY_HINT_RANGE, "64,65536,1"), 1024));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::BOOL, "basis_universal/zstd_supercompression"), true));
+	r_options->push_back(ImportOption(PropertyInfo(Variant::INT, "basis_universal/zstd_supercompression_level"), 6));
 }
 
-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 +285,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);
 	}
 }
 
@@ -300,6 +307,15 @@ Error ResourceImporterLayeredTexture::import(ResourceUID::ID p_source_id, const
 	int layout = (p_options.has("slices/layout")) ? int(p_options["slices/layout"]) : 0;
 	int amount = (p_options.has("slices/amount")) ? int(p_options["slices/amount"]) : 0;
 
+	const Image::BasisUniversalPackerParams basisu_params = {
+		p_options["basis_universal/uastc_pack_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"],
+	};
+
 	if (mode == MODE_CUBEMAP || mode == MODE_CUBEMAP_ARRAY) {
 		switch (arrangement) {
 			case CUBEMAP_FORMAT_1X6: {
@@ -392,6 +408,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 +504,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 +560,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 +573,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 +587,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;