doc(mtmd/qwen3vl): warn image_tile_mode zero-init selects batched, not the default

Addresses PR tetherto#175 review (tetherto#3): the shipped enum is 0=batched while the default mode
is sequential, so a zero-initialized clip_context_params/mtmd_context_params silently
selects the batched (unverified ne[3]) path instead of the intended default.

Renumbering to 0=sequential would be the clean fix, but the values are already released
as a string API ("0"/"1"/"2" in consumers), so renumbering would break existing callers.
Instead, document the trap prominently in clip.h and mtmd.h and point callers at
mtmd_context_params_default() (which sets sequential).

Author: yingying0906

tools/mtmd/clip.h

@@ -46,9 +46,16 @@ enum clip_flash_attn_type {
     CLIP_FLASH_ATTN_TYPE_ENABLED  = 1,
 };
 
+// WARNING: value 0 is BATCHED, which is NOT the default mode (sequential is).
+// A zero-initialized clip_context_params/mtmd_context_params (`{}`, memset, calloc)
+// therefore selects BATCHED — the one-forward-pass path whose ne[3] batching is not
+// yet verified on every backend (see the NOTE in models/qwen3vl.cpp). Do not rely on
+// zero-init for the default: initialize via mtmd_context_params_default() (sets
+// sequential) or set image_tile_mode explicitly. These values are part of the shipped
+// API (string "0"/"1"/"2" in consumers), so they are intentionally not renumbered.
 enum clip_image_tile_mode {
-    CLIP_IMAGE_TILE_MODE_BATCHED    = 0,
-    CLIP_IMAGE_TILE_MODE_SEQUENTIAL = 1,
+    CLIP_IMAGE_TILE_MODE_BATCHED    = 0, // NOT the default; zero-init lands here — see warning above
+    CLIP_IMAGE_TILE_MODE_SEQUENTIAL = 1, // the default (via mtmd_context_params_default)
     CLIP_IMAGE_TILE_MODE_DISABLED   = 2,
 };
 
@@ -65,7 +72,7 @@ struct clip_context_params {
     mtmd_progress_callback progress_callback;
     void * progress_callback_user_data;
     const char * backend_device; // optional, if null will use env var or default GPU backend
-    int image_tile_mode;   // 0=batched, 1=sequential (default), 2=disabled
+    int image_tile_mode;   // 0=batched, 1=sequential (default), 2=disabled. NOTE: 0 (batched) is the zero value but NOT the default — init via mtmd_context_params_default() or set explicitly.
     int image_max_tiles;   // override preproc_max_tiles; -1 = use GGUF/model default
 };
 

tools/mtmd/mtmd.h

@@ -114,7 +114,11 @@ struct mtmd_context_params {
     void * progress_callback_user_data;
     const char * backend_device; // optional GPU backend name (e.g. "CUDA", "Metal", "Vulkan"), if null will use env var or default
 
-    // tile encoding mode for multi-tile vision models (Qwen3VL): 0=batched, 1=sequential (default), 2=disabled
+    // tile encoding mode for multi-tile vision models (Qwen3VL): 0=batched, 1=sequential (default), 2=disabled.
+    // WARNING: the DEFAULT is sequential, but the ZERO value is 0=batched — so a zero-initialized
+    // params struct ({}, memset, calloc) selects BATCHED (the ne[3] one-pass path not yet verified on
+    // all backends), NOT the default. Always initialize via mtmd_context_params_default() (which sets
+    // sequential) or set image_tile_mode explicitly. Values are fixed API (consumers pass "0"/"1"/"2").
     int image_tile_mode;
 
     // override preproc_max_tiles from GGUF; -1 = use model default (4 for Qwen3VL 2B/4B)