Merge pull request #63594 from Faless/img/4.x_loader_ext

[Core] Make ImageFormatLoader extensible.

2 files changed, 61 insertions, 0 deletions

diff --git a/doc/classes/ImageFormatLoader.xml b/doc/classes/ImageFormatLoader.xml
new file mode 100644
index 0000000000..c6b1ec922a
--- /dev/null
+++ b/doc/classes/ImageFormatLoader.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="ImageFormatLoader" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Base class to add support for specific image formats.
+	</brief_description>
+	<description>
+		The engine supports multiple image formats out of the box (PNG, SVG, JPEG, WebP to name a few), but you can choose to implement support for additional image formats by extending [ImageFormatLoaderExtension].
+	</description>
+	<tutorials>
+	</tutorials>
+	<constants>
+		<constant name="FLAG_NONE" value="0" enum="LoaderFlags" is_bitfield="true">
+		</constant>
+		<constant name="FLAG_FORCE_LINEAR" value="1" enum="LoaderFlags" is_bitfield="true">
+		</constant>
+		<constant name="FLAG_CONVERT_COLORS" value="2" enum="LoaderFlags" is_bitfield="true">
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/ImageFormatLoaderExtension.xml b/doc/classes/ImageFormatLoaderExtension.xml
new file mode 100644
index 0000000000..b2a7ebc60f
--- /dev/null
+++ b/doc/classes/ImageFormatLoaderExtension.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="ImageFormatLoaderExtension" inherits="ImageFormatLoader" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Base class for creating [ImageFormatLoader] extensions (adding support for extra image formats).
+	</brief_description>
+	<description>
+		The engine supports multiple image formats out of the box (PNG, SVG, JPEG, WebP to name a few), but you can choose to implement support for additional image formats by extending this class.
+		Be sure to respect the documented return types and values. You should create an instance of it, and call [method add_format_loader] to register that loader during the initializaiton phase.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="_get_recognized_extensions" qualifiers="virtual const">
+			<return type="PackedStringArray" />
+			<description>
+				Returns the list of file extensions for this image format. Files with the given extentions will be treated as image file and loaded using this class.
+			</description>
+		</method>
+		<method name="_load_image" qualifiers="virtual">
+			<return type="int" enum="Error" />
+			<param index="0" name="image" type="Image" />
+			<param index="1" name="fileaccess" type="FileAccess" />
+			<param index="2" name="flags" type="int" enum="ImageFormatLoader.LoaderFlags" />
+			<param index="3" name="scale" type="float" />
+			<description>
+				Loads the content of [param fileaccess] into the provided [param image].
+			</description>
+		</method>
+		<method name="add_format_loader">
+			<return type="void" />
+			<description>
+				Add this format loader to the engine, allowing it to recognize the file extensions returned by [method _get_recognized_extensions].
+			</description>
+		</method>
+		<method name="remove_format_loader">
+			<return type="void" />
+			<description>
+				Remove this format loader from the engine.
+			</description>
+		</method>
+	</methods>
+</class>