From d20936b5446a52da15f0486ee5f5509a57af1dc1 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 13 Nov 2024 19:29:14 -0500
Subject: [PATCH] camera: Add some category docs about camera device warmup
delays.
Fixes #11454.
---
include/SDL3/SDL_camera.h | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 4ea75908ae5a7..162c4cf64f550 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -28,6 +28,22 @@
* devices can be enumerated, queried, and opened. Once opened, it will
* provide SDL_Surface objects as new frames of video come in. These surfaces
* can be uploaded to an SDL_Texture or processed as pixels in memory.
+ *
+ * ## Camera gotchas
+ *
+ * Consumer-level camera hardware tends to take a little while to warm up,
+ * once the device has been opened. Generally most camera apps have some sort
+ * of UI to take a picture (a button to snap a pic while a preview is showing,
+ * some sort of multi-second countdown for the user to pose, like a photo
+ * booth), which puts control in the users' hands, or they are intended to
+ * stay on for long times (Pokemon Go, etc).
+ *
+ * It's not uncommon that a newly-opened camera will provide a couple of
+ * completely black frames, maybe followed by some under-exposed images.
+ * If taking single frame automatically, or recording video from a camera's
+ * input without the user initiating it from a preview, it could be wise
+ * to drop the first several frames (if not the first several _seconds_ worth
+ * of frames!) before using images from a camera.
*/
#ifndef SDL_camera_h_