feat: SHM cross-process format consistency via per-slot AVPixelFormat

The deprecated Monitors.Colours column was driving the on-disk SHM
image_buffer slot format end-to-end: zmc allocated each slot in
camera->Colours()/SubpixelOrder() shape, zms attached and built its
own per-process Image objects assuming the same shape. Anything that
wrote a different format into a slot — i.e. anything that wasn't
already RGB32 on a Colours=4 monitor — left zmc's local Image with
the new format but zms reading the bytes as RGB32. The visible
artefacts varied with the format pair (4 small images per row for
YUV420P-into-RGB32, 3 tiles for the planar-as-RGB24 fallthrough,
fully garbled colours for image_pixelformats overlapping alarm_image,
etc.) but the underlying contract was just broken — the SHM had no
representation of the per-slot format.

Make the SHM transport any format Image supports without an upfront
convert step:

- Place image_pixelformats[] correctly. mem_size already reserved
  image_buffer_count*sizeof(AVPixelFormat) at the end of the SHM
  region, but the pointer was set to shared_images +
  image_buffer_count*image_size — overlapping the alarm_image
  region. zmc's writes scribbled into alarm_image; zms read alarm
  pixel data back as enum values. Move it to
  +2*image_buffer_count*image_size, after both image regions.
- Add Monitor::WriteShmFrame(index, capture_image): no conversion,
  just Assign and record image_pixelformats[index] =
  capture_image->AVPixFormat(). Used by both the normal Decode path
  and the signal-loss path so they share the same cross-process
  format-consistency contract.
- Add Monitor::ReadShmFrame(index): the read-side counterpart. Calls
  image_buffer[index]->AVPixFormat(image_pixelformats[index]) before
  returning so other-process Image objects interpret the SHM bytes
  correctly per-frame. zm_monitorstream's image_buffer[index]
  accesses go through this accessor.
- image_buffer[i] / alarm_image: initial format is now just a
  placeholder (YUV420P), with allocation sized from
  camera->ImageSize() as the upper bound. The actual format carried
  in each slot is the one zmc wrote, recorded in image_pixelformats
  and adopted on read.

This means the typical capture pipelines run with zero sws_scale
calls in the SHM hot path:

- H.264/H.265 sw decode -> YUV420P -> identity copy via
  av_image_copy in Image::Assign(AVFrame*).
- LocalCamera/MJPEG -> RGB32 (DecodeJpeg target) -> SHM holds RGB32;
  zms reads RGB32 directly.
- H.265 hwaccel -> NV12 -> falls through to YUV420P (NV12 isn't in
  zm_pixformat) — one convert at decode time, then passthrough
  through the rest of the pipeline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: connortechnology

src/zm_monitor.cpp

@@ -1120,19 +1120,33 @@ bool Monitor::connect() {
 
   image_buffer.resize(image_buffer_count);
   for (int32_t i = 0; i < image_buffer_count; i++) {
-    image_buffer[i] = new Image(width, height, camera->Colours(), camera->SubpixelOrder(), &(shared_images[i*image_size]));
+    // The initial format is a placeholder. The actual SHM bytes can be in
+    // any AVPixelFormat zm_pixformat supports — zmc records the per-slot
+    // format via image_pixelformats[index] in WriteShmFrame, and ReadShmFrame
+    // applies it to image_buffer[i] before each consumer access. We pass
+    // image_size as the allocation upper bound so any format up to that
+    // byte count fits the held SHM slot.
+    image_buffer[i] = new Image(width, height, ZM_COLOUR_YUV420P, ZM_SUBPIX_ORDER_YUV420P,
+                                 &(shared_images[i*image_size]), image_size, 0);
     image_buffer[i]->HoldBuffer(true); /* Don't release the internal buffer or replace it with another */
   }
-  alarm_image.AssignDirect(width, height, camera->Colours(), camera->SubpixelOrder(),
-                           &(shared_images[image_buffer_count*image_size]),
-                           image_size,
-                           ZM_BUFTYPE_DONTFREE
-                          );
+  // alarm_image follows the same per-slot format convention. Initial format
+  // is a placeholder; consumers should AVPixFormat()-sync from
+  // image_pixelformats[alarm_index] when reading via GetAlarmImage().
+  alarm_image.AssignDirect(width, height, ZM_COLOUR_YUV420P, ZM_SUBPIX_ORDER_YUV420P,
+                           &(shared_images[image_buffer_count*image_size]), image_size, ZM_BUFTYPE_DONTFREE);
   alarm_image.HoldBuffer(true); /* Don't release the internal buffer or replace it with another */
   if (alarm_image.Buffer() + image_size > mem_ptr + mem_size) {
     Warning("We will exceed memsize by %td bytes!", (alarm_image.Buffer() + image_size) - (mem_ptr + mem_size));
   }
-  image_pixelformats = (AVPixelFormat *)(shared_images + (image_buffer_count*image_size));
+  // Layout in SHM is: image_buffer_count*image_size for image_buffer slots,
+  // then image_buffer_count*image_size for alarm_image slots, THEN the
+  // image_pixelformats[] array (mem_size at line ~1002 reserves the space).
+  // Placing it at +1*image_buffer_count*image_size collides with alarm_image's
+  // buffer region — zmc's writes to image_pixelformats[index] corrupt the
+  // alarm image, and zms reads alarm-image bytes back as AVPixelFormat enum
+  // values, producing per-frame "different format every slot" garble.
+  image_pixelformats = (AVPixelFormat *)(shared_images + (2 * image_buffer_count * image_size));
 
   if (purpose == CAPTURE) {
     memset(mem_ptr, 0, mem_size);
@@ -1226,6 +1240,11 @@ bool Monitor::connect() {
     Error("Shared data not initialised by capture daemon for monitor %s", name.c_str());
     return false;
   }
+  // No zms-side per-slot pixformat adoption needed: image_buffer was
+  // constructed above with the same hardcoded YUV420P that zmc uses, so
+  // both processes interpret the SHM bytes the same way without consulting
+  // the image_pixelformats[] array (which still records the actual format
+  // zmc wrote, kept for diagnostic visibility).
 
   // We set these here because otherwise the first fps calc is meaningless
   last_fps_time = std::chrono::system_clock::now();
@@ -2698,7 +2717,7 @@ int Monitor::Capture() {
     shared_data->signal = false;
     shared_data->last_write_index = index;
     shared_data->last_write_time = shared_timestamps[index].tv_sec;
-    image_buffer[index]->Assign(*capture_image);
+    WriteShmFrame(index, capture_image);
     shared_timestamps[index] = zm::chrono::duration_cast<timeval>(packet->timestamp.time_since_epoch());
     delete capture_image;
     shared_data->image_count++;
@@ -2836,6 +2855,33 @@ bool Monitor::setupConvertContext(const AVFrame *input_frame, const Image *image
   return (convert_context != nullptr);
 }
 
+void Monitor::WriteShmFrame(unsigned int index, Image *capture_image) {
+  // No conversion at the SHM-write side. zmc records the format the bytes
+  // were actually written in via image_pixelformats[index]; consumers in
+  // other processes (zms etc.) sync image_buffer[index]->AVPixFormat() from
+  // that array before reading via ReadShmFrame, so the SHM transports any
+  // format Image can represent without a sws_scale step. This is the
+  // central no-conversion promise of the AVPixelFormat migration.
+  image_buffer[index]->Assign(*capture_image);
+  image_pixelformats[index] = capture_image->AVPixFormat();
+}
+
+Image *Monitor::ReadShmFrame(unsigned int index) {
+  // Adopt the per-slot format zmc recorded into image_pixelformats[]. zms
+  // (and zma, etc.) construct image_buffer[i] at attach time with whatever
+  // initial format was convenient; the actual bytes the capture daemon
+  // wrote into the slot can be in any AVPixelFormat that zm_pixformat
+  // supports, varying per-slot and across reconnections. AVPixFormat()
+  // updates imagePixFormat, colours, subpixelorder, size and linesize
+  // together so the Image object consistently interprets the SHM bytes.
+  // No-op when the slot's format already matches.
+  AVPixelFormat fmt = image_pixelformats[index];
+  if (fmt != AV_PIX_FMT_NONE && image_buffer[index]->AVPixFormat() != fmt) {
+    image_buffer[index]->AVPixFormat(fmt);
+  }
+  return image_buffer[index];
+}
+
 void Monitor::applyOrientation(Image *image) {
   if (orientation == ROTATE_0) return;
 
@@ -3070,12 +3116,17 @@ bool Monitor::Decode() {
     }
 
     if (!packet->image) {
-      // Use a pipeline-friendly pixel format. Prefer the decoded frame's native
-      // format when Image can represent it (currently YUV 4:2:0 / 4:2:2 planar
-      // including the JPEG full-range variants, GRAY8, RGB24, and RGB32) — both
-      // 4:2:0 and 4:2:2 paths now have full coverage in zm_pixformat /
-      // zm_colours_from_pixformat. Anything outside that set falls back to a
-      // YUV420P conversion via swscale.
+      // Pick the most pipeline-friendly format Image can represent. If the
+      // decoder's native format is one Image supports, capture into that
+      // directly so sws_scale becomes a no-op identity copy via av_image_copy
+      // (Image::Assign(AVFrame*) takes that fast path on src_fmt == format).
+      // Otherwise fall back to YUV420P, which is universally supported and
+      // the smallest planar option.
+      //
+      // Cross-process consistency with zms is maintained per-slot via
+      // image_pixelformats[index] (written by WriteShmFrame, read on the
+      // zms side before each frame is consumed) — not by pinning the SHM
+      // to a single format here.
       unsigned int native_colours, native_subpixelorder;
       AVPixelFormat native_fmt = static_cast<AVPixelFormat>(packet->in_frame->format);
       const char *native_fmt_name = av_get_pix_fmt_name(native_fmt);
@@ -3158,11 +3209,10 @@ bool Monitor::Decode() {
       TimestampImage(capture_image, packet->timestamp);
     }
 
-    // Write to shared image buffer
+    // Write to shared image buffer.
     unsigned int index = (shared_data->last_write_index + 1) % image_buffer_count;
     decoding_image_count++;
-    image_buffer[index]->Assign(*capture_image);
-    image_pixelformats[index] = capture_image->AVPixFormat();
+    WriteShmFrame(index, capture_image);
     shared_timestamps[index] = zm::chrono::duration_cast<timeval>(packet->timestamp.time_since_epoch());
     shared_data->signal = signal_check_points ? CheckSignal(capture_image) : true;
     shared_data->last_write_index = index;

src/zm_monitor.h

@@ -985,6 +985,16 @@ class Monitor : public std::enable_shared_from_this<Monitor> {
   bool CheckSignal( const Image *image );
   bool Analyse();
   bool setupConvertContext(const AVFrame *input_frame, const Image *image);
+  // Write capture_image into image_buffer[index] without conversion and
+  // record its AVPixelFormat in image_pixelformats[index] so reading
+  // processes can adopt that format via ReadShmFrame.
+  void WriteShmFrame(unsigned int index, Image *capture_image);
+
+  // Read-side counterpart: ensures image_buffer[index]'s metadata matches
+  // the format zmc wrote via image_pixelformats[index] before returning
+  // it. Use this from zms / zma / event paths instead of touching
+  // image_buffer[index] directly.
+  Image *ReadShmFrame(unsigned int index);
   void applyOrientation(Image *image);
   bool applyDeinterlacing(std::shared_ptr<ZMPacket> &packet, Image *capture_image);
   bool Decode();

src/zm_monitorstream.cpp

@@ -643,7 +643,7 @@ void MonitorStream::runStream() {
       if (!was_paused) {
         int index = monitor->shared_data->last_write_index % monitor->image_buffer_count;
         Debug(1, "Saving paused image from index %d",index);
-        paused_image = new Image(*monitor->image_buffer[index]);
+        paused_image = new Image(*monitor->ReadShmFrame(index));
         paused_timestamp = SystemTimePoint(zm::chrono::duration_cast<Microseconds>(monitor->shared_timestamps[index]));
       }
     } else if (paused_image) {
@@ -756,12 +756,12 @@ void MonitorStream::runStream() {
             send_image = monitor->GetAlarmImage();
             if (!send_image) {
               Debug(1, "Falling back");
-              send_image = monitor->image_buffer[index];
+              send_image = monitor->ReadShmFrame(index);
             }
           } else {
             //AVPixelFormat pixformat = monitor->image_pixelformats[index];
             //Debug(1, "Sending regular image index %d, pix format is %d %s", index, pixformat, av_get_pix_fmt_name(pixformat));
-            send_image = monitor->image_buffer[index];
+            send_image = monitor->ReadShmFrame(index);
           }
 
           if (!sendFrame(send_image, last_frame_timestamp)) {
@@ -829,7 +829,7 @@ void MonitorStream::runStream() {
 
             temp_image_buffer[temp_index].timestamp =
               SystemTimePoint(zm::chrono::duration_cast<Microseconds>(monitor->shared_timestamps[index]));
-            monitor->image_buffer[index]->WriteJpeg(temp_image_buffer[temp_index].file_name, config.jpeg_file_quality);
+            monitor->ReadShmFrame(index)->WriteJpeg(temp_image_buffer[temp_index].file_name, config.jpeg_file_quality);
             temp_write_index = MOD_ADD(temp_write_index, 1, temp_image_buffer_count);
             if (temp_write_index == temp_read_index) {
               // Go back to live viewing
@@ -985,7 +985,7 @@ void MonitorStream::SingleImage(int scale) {
   int index = monitor->shared_data->last_write_index % monitor->image_buffer_count;
   AVPixelFormat pixformat = monitor->image_pixelformats[index];
   Debug(1, "Sending regular image index %d, pix format is %d %s", index, pixformat, av_get_pix_fmt_name(pixformat));
-  Image *snap_image = monitor->image_buffer[index];
+  Image *snap_image = monitor->ReadShmFrame(index);
   if (!config.timestamp_on_capture) {
     monitor->TimestampImage(snap_image,
                             SystemTimePoint(zm::chrono::duration_cast<Microseconds>(monitor->shared_timestamps[index])));