camera: Add some category docs about camera device warmup delays.

Fixes #11454.

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_