Adding a new Camera Server implementation to Godot.

This is a new singleton where camera sources such as webcams or cameras on a mobile phone can register themselves with the Server.
Other parts of Godot can interact with this to obtain images from the camera as textures.
This work includes additions to the Visual Server to use this functionality to present the camera image in the background. This is specifically targetted at AR applications.

7 files changed, 201 insertions, 2 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index ba31a774fc..d36a545c56 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -18,6 +18,9 @@
 		<member name="AudioServer" type="AudioServer" setter="" getter="">
 			[AudioServer] singleton
 		</member>
+		<member name="CameraServer" type="CameraServer" setter="" getter="">
+			[CameraServer] singleton
+		</member>
 		<member name="ClassDB" type="ClassDB" setter="" getter="">
 			[ClassDB] singleton
 		</member>
diff --git a/doc/classes/ARVRInterface.xml b/doc/classes/ARVRInterface.xml
index 11084fb98e..c286811b5d 100644
--- a/doc/classes/ARVRInterface.xml
+++ b/doc/classes/ARVRInterface.xml
@@ -10,6 +10,13 @@
 	<tutorials>
 	</tutorials>
 	<methods>
+		<method name="get_camera_feed_id">
+			<return type="int">
+			</return>
+			<description>
+				If this is an AR interface that requires displaying a camera feed as the background, this method returns the feed id in the [CameraServer] for this interface.
+			</description>
+		</method>
 		<method name="get_capabilities" qualifiers="const">
 			<return type="int">
 			</return>
diff --git a/doc/classes/CameraFeed.xml b/doc/classes/CameraFeed.xml
new file mode 100644
index 0000000000..7f353f7a05
--- /dev/null
+++ b/doc/classes/CameraFeed.xml
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="CameraFeed" inherits="Reference" category="Core" version="3.2">
+	<brief_description>
+		A camera feed gives you access to a single physical camera attached to your device.
+	</brief_description>
+	<description>
+		A camera feed gives you access to a single physical camera attached to your device.
+		When enabled Godot will start capturing frames from the camera which can then be used. Do note that many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Godot does this automatically for you if you set the environment to show the camera image in the background.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_id" qualifiers="const">
+			<return type="int">
+			</return>
+			<description>
+				Get unique id for this feed
+			</description>
+		</method>
+		<method name="get_name" qualifiers="const">
+			<return type="String">
+			</return>
+			<description>
+				Get name of the camera
+			</description>
+		</method>
+		<method name="get_position" qualifiers="const">
+			<return type="int" enum="CameraFeed.FeedPosition">
+			</return>
+			<description>
+				Position of camera on the device.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="feed_is_active" type="bool" setter="set_active" getter="is_active">
+		</member>
+		<member name="feed_transform" type="Transform2D" setter="set_transform" getter="get_transform">
+		</member>
+	</members>
+	<constants>
+		<constant name="FEED_NOIMAGE" value="0" enum="FeedDataType">
+			No image set for the feed.
+		</constant>
+		<constant name="FEED_RGB" value="1" enum="FeedDataType">
+			Feed supplies RGB images.
+		</constant>
+		<constant name="FEED_YCbCr" value="2" enum="FeedDataType">
+			Feed supplies YCbCr images that need to be converted to RGB.
+		</constant>
+		<constant name="FEED_YCbCr_Sep" value="3" enum="FeedDataType">
+			Feed supplies separate Y and CbCr images that need to be combined and converted to RGB.
+		</constant>
+		<constant name="FEED_UNSPECIFIED" value="0" enum="FeedPosition">
+			Unspecified position.
+		</constant>
+		<constant name="FEED_FRONT" value="1" enum="FeedPosition">
+			Camera is mounted at the front of the device.
+		</constant>
+		<constant name="FEED_BACK" value="2" enum="FeedPosition">
+			Camera is moutned at the back of the device.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/CameraServer.xml b/doc/classes/CameraServer.xml
new file mode 100644
index 0000000000..bc76c306fb
--- /dev/null
+++ b/doc/classes/CameraServer.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="CameraServer" inherits="Object" category="Core" version="3.2">
+	<brief_description>
+		Our camera server keeps track of different cameras accessible in Godot. These are external cameras such as webcams or the cameras on your phone.
+	</brief_description>
+	<description>
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="add_feed">
+			<return type="void">
+			</return>
+			<argument index="0" name="feed" type="CameraFeed">
+			</argument>
+			<description>
+				Adds a camera feed to the camera server.
+			</description>
+		</method>
+		<method name="feeds">
+			<return type="Array">
+			</return>
+			<description>
+				Returns an array of [CameraFeed]s.
+			</description>
+		</method>
+		<method name="get_feed">
+			<return type="CameraFeed">
+			</return>
+			<argument index="0" name="index" type="int">
+			</argument>
+			<description>
+				Returns the [CameraFeed] with this id.
+			</description>
+		</method>
+		<method name="get_feed_count">
+			<return type="int">
+			</return>
+			<description>
+				Returns the number of [CameraFeed]s registered.
+			</description>
+		</method>
+		<method name="remove_feed">
+			<return type="void">
+			</return>
+			<argument index="0" name="feed" type="CameraFeed">
+			</argument>
+			<description>
+				Removes a [CameraFeed].
+			</description>
+		</method>
+	</methods>
+	<signals>
+		<signal name="camera_feed_added">
+			<argument index="0" name="id" type="int">
+			</argument>
+			<description>
+				Emitted when a [CameraFeed] is added (webcam is plugged in).
+			</description>
+		</signal>
+		<signal name="camera_feed_removed">
+			<argument index="0" name="id" type="int">
+			</argument>
+			<description>
+				Emitted when a [CameraFeed] is removed (webcam is removed).
+			</description>
+		</signal>
+	</signals>
+	<constants>
+		<constant name="FEED_RGBA_IMAGE" value="0" enum="FeedImage">
+			The RGBA camera image.
+		</constant>
+		<constant name="FEED_YCbCr_IMAGE" value="0" enum="FeedImage">
+			The YCbCr camera image.
+		</constant>
+		<constant name="FEED_Y_IMAGE" value="0" enum="FeedImage">
+			The Y component camera image. 
+		</constant>
+		<constant name="FEED_CbCr_IMAGE" value="1" enum="FeedImage">
+			The CbCr component camera image.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/CameraTexture.xml b/doc/classes/CameraTexture.xml
new file mode 100644
index 0000000000..7477be7825
--- /dev/null
+++ b/doc/classes/CameraTexture.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="CameraTexture" inherits="Texture" category="Core" version="3.2">
+	<brief_description>
+		This texture gives access to the camera texture provided by a [CameraFeed]. Note that many cameras supply YCbCr images which need to be converted in a shader. 
+	</brief_description>
+	<description>
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+	</methods>
+	<members>
+		<member name="camera_feed_id" type="int" setter="set_camera_feed_id" getter="get_camera_feed_id">
+			Id of the [CameraFeed] for which we want to display the image.
+		</member>
+		<member name="camera_is_active" type="bool" setter="set_camera_active" getter="get_camera_active">
+			Convenience property that gives access to the active property of the [CameraFeed].
+		</member>
+		<member name="which_feed" type="int" setter="set_which_feed" getter="get_which_feed" enum="CameraServer.FeedImage">
+			Which image within the [CameraFeed] we want access to, important if the camera image is split in a Y and CbCr component.
+		</member>
+	</members>
+	<constants>
+	</constants>
+</class>
diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml
index 2a4ab4ce0d..eb94447529 100644
--- a/doc/classes/Environment.xml
+++ b/doc/classes/Environment.xml
@@ -57,6 +57,9 @@
 		<member name="auto_exposure_speed" type="float" setter="set_tonemap_auto_exposure_speed" getter="get_tonemap_auto_exposure_speed">
 			Speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure.
 		</member>
+		<member name="background_camera_feed_id" type="int" setter="set_camera_feed_id" getter="get_camera_feed_id">
+			The id of the camera feed to show in the background.
+		</member>
 		<member name="background_canvas_max_layer" type="int" setter="set_canvas_max_layer" getter="get_canvas_max_layer">
 			Maximum layer id (if using Layer background mode).
 		</member>
@@ -266,7 +269,10 @@
 		<constant name="BG_CANVAS" value="4" enum="BGMode">
 			Display a [CanvasLayer] in the background.
 		</constant>
-		<constant name="BG_MAX" value="6" enum="BGMode">
+		<constant name="BG_CAMERA_FEED" value="6" enum="BGMode">
+			Display a camera feed in the background.
+		</constant>
+		<constant name="BG_MAX" value="7" enum="BGMode">
 			Helper constant keeping track of the enum's size, has no direct usage in API calls.
 		</constant>
 		<constant name="GLOW_BLEND_MODE_ADDITIVE" value="0" enum="GlowBlendMode">
diff --git a/doc/classes/VisualServer.xml b/doc/classes/VisualServer.xml
index 3997798cca..d4ca1194d2 100644
--- a/doc/classes/VisualServer.xml
+++ b/doc/classes/VisualServer.xml
@@ -3359,6 +3359,17 @@
 			<description>
 			</description>
 		</method>
+		<method name="texture_bind">
+			<return type="void">
+			</return>
+			<argument index="0" name="texture" type="RID">
+			</argument>
+			<argument index="1" name="number" type="int">
+			</argument>
+			<description>
+				Binds the texture to a texture slot.
+			</description>
+		</method>
 		<method name="texture_create">
 			<return type="RID">
 			</return>
@@ -4427,7 +4438,7 @@
 		</constant>
 		<constant name="ENV_BG_KEEP" value="5" enum="EnvironmentBG">
 		</constant>
-		<constant name="ENV_BG_MAX" value="6" enum="EnvironmentBG">
+		<constant name="ENV_BG_MAX" value="7" enum="EnvironmentBG">
 		</constant>
 		<constant name="ENV_DOF_BLUR_QUALITY_LOW" value="0" enum="EnvironmentDOFBlurQuality">
 		</constant>