[Bf-blender-cvs] [ee6507f2b1d] master: Docs: notes on thumbnail sizes

[Campbell Barton]

Commit: ee6507f2b1d776099e199a31a3af0f09d2fbba74
Author: Campbell Barton
Date:   Wed Jan 19 14:04:32 2022 +1100
Branches: master
https://developer.blender.org/rBee6507f2b1d776099e199a31a3af0f09d2fbba74

Docs: notes on thumbnail sizes

The rationale for storing thumbnails at different sizes wasn't obvious.

===================================================================

M	source/blender/blenkernel/BKE_main.h
M	source/blender/windowmanager/intern/wm_files.c

===================================================================

diff --git a/source/blender/blenkernel/BKE_main.h b/source/blender/blenkernel/BKE_main.h
index b7f675e4e97..4c6eb31db4b 100644
--- a/source/blender/blenkernel/BKE_main.h
+++ b/source/blender/blenkernel/BKE_main.h
@@ -406,6 +406,13 @@ int set_listbasepointers(struct Main *main, struct ListBase *lb[]);
   ((main)->versionfile < (ver) || \
    ((main)->versionfile == (ver) && (main)->subversionfile < (subver)))
 
+/**
+ * The size of thumbnails (optionally) stored in the `.blend` files header.
+ *
+ * NOTE(@campbellbarton): This is kept small as it's stored uncompressed in the `.blend` file,
+ * where a larger size would increase the size of every `.blend` file unreasonably.
+ * If we wanted to increase the size, we'd want to use compression (JPEG or similar).
+ */
 #define BLEN_THUMB_SIZE 128
 
 #define BLEN_THUMB_MEMSIZE(_x, _y) \
diff --git a/source/blender/windowmanager/intern/wm_files.c b/source/blender/windowmanager/intern/wm_files.c
index 344f4959a93..1478712c3cd 100644
--- a/source/blender/windowmanager/intern/wm_files.c
+++ b/source/blender/windowmanager/intern/wm_files.c
@@ -1521,11 +1521,29 @@ static void wm_history_file_update(void)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Save Main Blend-File (internal) Screen-Shot
+/** \name Thumbnail Generation: Screen-Shot / Camera View
+ *
+ * Thumbnail Sizes
+ * ===============
+ *
+ * - `PREVIEW_RENDER_LARGE_HEIGHT * 2` is used to render a large thumbnail,
+ *   giving some over-sampling when scaled down:
+ *
+ * - There are two outputs for this thumbnail:
+ *
+ *   - An image is saved to the thumbnail cache, sized at #PREVIEW_RENDER_LARGE_HEIGHT.
+ *
+ *   - A smaller thumbnail is stored in the `.blend` file it's self, sized at #BLEN_THUMB_SIZE.
+ *     The size is kept small to prevent thumbnails bloating the size of `.blend` files.
+ *
+ *     The this thumbnail will be extracted if the file is shared or the local thumbnail cache
+ *     is cleared. see: `blendthumb_extract.cc` for logic that extracts the thumbnail.
  *
- * Screen-shot the active window.
  * \{ */
 
+/**
+ * Screen-shot the active window.
+ */
 static ImBuf *blend_file_thumb_from_screenshot(bContext *C, BlendThumbnail **r_thumb)
 {
   *r_thumb = NULL;
@@ -1571,15 +1589,11 @@ static ImBuf *blend_file_thumb_from_screenshot(bContext *C, BlendThumbnail **r_t
   return ibuf;
 }
 
-/** \} */
-
-/* -------------------------------------------------------------------- */
-/** \name Save Main Blend-File (internal) Camera View
- *
+/**
  * Render the current scene with the active camera.
- * \{ */
-
-/* screen can be NULL */
+ *
+ * \param screen: can be NULL.
+ */
 static ImBuf *blend_file_thumb_from_camera(const bContext *C,
                                            Scene *scene,
                                            bScreen *screen,
@@ -1617,7 +1631,6 @@ static ImBuf *blend_file_thumb_from_camera(const bContext *C,
     return NULL;
   }
 
-  /* gets scaled to BLEN_THUMB_SIZE */
   Depsgraph *depsgraph = CTX_data_ensure_evaluated_depsgraph(C);
 
   /* Note that with scaling, this ends up being 0.5,
@@ -1689,6 +1702,12 @@ static ImBuf *blend_file_thumb_from_camera(const bContext *C,
   return ibuf;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Write Main Blend-File (internal)
+ * \{ */
+
 bool write_crash_blend(void)
 {
   char path[FILE_MAX];
@@ -2017,7 +2036,7 @@ void wm_autosave_delete(void)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/** \name Initialize WM_OT_open_xxx properties
+/** \name Initialize `WM_OT_open_*` Properties
  *
  * Check if load_ui was set by the caller.
  * Fall back to user preference when file flags not specified.