camera: Reworked to operate with a driver interface, like other subsystems.

include/SDL3/SDL_camera.h

@@ -108,6 +108,71 @@ typedef struct SDL_CameraFrame
 } SDL_CameraFrame;
 
 
+/**
+ * Use this function to get the number of built-in camera drivers.
+ *
+ * This function returns a hardcoded number. This never returns a negative
+ * value; if there are no drivers compiled into this build of SDL, this
+ * function returns zero. The presence of a driver in this list does not mean
+ * it will function, it just means SDL is capable of interacting with that
+ * interface. For example, a build of SDL might have v4l2 support, but if
+ * there's no kernel support available, SDL's v4l2 driver would fail if used.
+ *
+ * By default, SDL tries all drivers, in its preferred order, until one is
+ * found to be usable.
+ *
+ * \returns the number of built-in camera drivers.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetCameraDriver
+ */
+extern DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
+
+/**
+ * Use this function to get the name of a built in camera driver.
+ *
+ * The list of camera drivers is given in the order that they are normally
+ * initialized by default; the drivers that seem more reasonable to choose
+ * first (as far as the SDL developers believe) are earlier in the list.
+ *
+ * The names of drivers are all simple, low-ASCII identifiers, like "v4l2",
+ * "coremedia" or "android". These never have Unicode characters, and are not
+ * meant to be proper names.
+ *
+ * \param index the index of the camera driver; the value ranges from 0 to
+ *              SDL_GetNumCameraDrivers() - 1
+ * \returns the name of the camera driver at the requested index, or NULL if an
+ *          invalid index was specified.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetNumCameraDrivers
+ */
+extern DECLSPEC const char *SDLCALL SDL_GetCameraDriver(int index);
+
+/**
+ * Get the name of the current camera driver.
+ *
+ * The returned string points to internal static memory and thus never becomes
+ * invalid, even if you quit the camera subsystem and initialize a new driver
+ * (although such a case would return a different static string from another
+ * call to this function, of course). As such, you should not modify or free
+ * the returned string.
+ *
+ * \returns the name of the current camera driver or NULL if no driver has been
+ *          initialized.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC const char *SDLCALL SDL_GetCurrentCameraDriver(void);
+
 /**
  * Get a list of currently connected camera devices.
  *

include/SDL3/SDL_hints.h

@@ -355,6 +355,22 @@ extern "C" {
  */
 #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
 
+/**
+ *  A variable that decides what camera backend to use.
+ *
+ *  By default, SDL will try all available camera backends in a reasonable
+ *  order until it finds one that can work, but this hint allows the app
+ *  or user to force a specific target, such as "directshow" if, say, you are
+ *  on Windows Media Foundations but want to try DirectShow instead.
+ *
+ *  The default value is unset, in which case SDL will try to figure out
+ *  the best camera backend on your behalf. This hint needs to be set
+ *  before SDL_Init() is called to be useful.
+ *
+ *  This hint is available since SDL 3.0.0.
+ */
+#define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER"
+
 /**
  * A variable controlling whether DirectInput should be used for controllers
  *
@@ -2478,7 +2494,6 @@ extern "C" {
  */
 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
 
-
 /**
  *  An enumeration of hint priorities
  */

include/SDL3/SDL_init.h

@@ -59,7 +59,8 @@ typedef enum
     SDL_INIT_HAPTIC       = 0x00001000,
     SDL_INIT_GAMEPAD      = 0x00002000,  /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */
     SDL_INIT_EVENTS       = 0x00004000,
-    SDL_INIT_SENSOR       = 0x00008000
+    SDL_INIT_SENSOR       = 0x00008000,
+    SDL_INIT_CAMERA       = 0x00010000   /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */
 } SDL_InitFlags;
 
 /**

include/build_config/SDL_build_config.h.cmake

@@ -467,10 +467,11 @@
 #cmakedefine SDL_FILESYSTEM_N3DS @SDL_FILESYSTEM_N3DS@
 
 /* Enable camera subsystem */
-#cmakedefine SDL_CAMERA_DUMMY @SDL_CAMERA_DUMMY@
-#cmakedefine SDL_CAMERA_V4L2 @SDL_CAMERA_V4L2@
-#cmakedefine SDL_CAMERA_APPLE @SDL_CAMERA_APPLE@
-#cmakedefine SDL_CAMERA_ANDROID @SDL_CAMERA_ANDROID@
+#cmakedefine SDL_CAMERA_DRIVER_DUMMY @SDL_CAMERA_DRIVER_DUMMY@
+/* !!! FIXME: for later cmakedefine SDL_CAMERA_DRIVER_DISK @SDL_CAMERA_DRIVER_DISK@ */
+#cmakedefine SDL_CAMERA_DRIVER_V4L2 @SDL_CAMERA_DRIVER_V4L2@
+#cmakedefine SDL_CAMERA_DRIVER_COREMEDIA @SDL_CAMERA_DRIVER_COREMEDIA@
+#cmakedefine SDL_CAMERA_DRIVER_ANDROID @SDL_CAMERA_DRIVER_ANDROID@
 
 /* Enable misc subsystem */
 #cmakedefine SDL_MISC_DUMMY @SDL_MISC_DUMMY@

include/build_config/SDL_build_config_android.h

@@ -191,6 +191,6 @@
 #define SDL_FILESYSTEM_ANDROID   1
 
 /* Enable the camera driver */
-#define SDL_CAMERA_ANDROID 1
+#define SDL_CAMERA_DRIVER_ANDROID 1
 
 #endif /* SDL_build_config_android_h_ */

include/build_config/SDL_build_config_emscripten.h

@@ -210,6 +210,6 @@
 #define SDL_FILESYSTEM_EMSCRIPTEN 1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */  /* !!! FIXME */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_emscripten_h */

include/build_config/SDL_build_config_ios.h

@@ -213,6 +213,6 @@
 #define SDL_FILESYSTEM_COCOA   1
 
 /* enable camera support */
-#define SDL_CAMERA_APPLE 1
+#define SDL_CAMERA_DRIVER_COREMEDIA 1
 
 #endif /* SDL_build_config_ios_h_ */

include/build_config/SDL_build_config_macos.h

@@ -270,7 +270,8 @@
 #define SDL_FILESYSTEM_COCOA   1
 
 /* enable camera support */
-#define SDL_CAMERA_APPLE 1
+#define SDL_CAMERA_DRIVER_COREMEDIA 1
+#define SDL_CAMERA_DRIVER_DUMMY 1
 
 /* Enable assembly routines */
 #ifdef __ppc__

include/build_config/SDL_build_config_minimal.h

@@ -90,6 +90,6 @@ typedef unsigned int uintptr_t;
 #define SDL_FILESYSTEM_DUMMY  1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_minimal_h_ */

include/build_config/SDL_build_config_ngage.h

@@ -87,6 +87,6 @@ typedef unsigned long      uintptr_t;
 #define SDL_FILESYSTEM_DUMMY 1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_ngage_h_ */

include/build_config/SDL_build_config_windows.h

@@ -312,6 +312,6 @@ typedef unsigned int uintptr_t;
 #define SDL_FILESYSTEM_WINDOWS  1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */  /* !!! FIXME */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_windows_h_ */

include/build_config/SDL_build_config_wingdk.h

@@ -248,7 +248,7 @@
 #define SDL_FILESYSTEM_WINDOWS  1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */  /* !!! FIXME */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 /* Use the (inferior) GDK text input method for GDK platforms */
 /*#define SDL_GDK_TEXTINPUT 1*/

include/build_config/SDL_build_config_winrt.h

@@ -216,6 +216,6 @@
 #define SDL_POWER_WINRT 1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */  /* !!! FIXME */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_winrt_h_ */

include/build_config/SDL_build_config_xbox.h

@@ -237,6 +237,6 @@
 #define SDL_GDK_TEXTINPUT 1
 
 /* Enable the camera driver (src/camera/dummy/\*.c) */
-#define SDL_CAMERA_DUMMY  1
+#define SDL_CAMERA_DRIVER_DUMMY  1
 
 #endif /* SDL_build_config_wingdk_h_ */