[PATCH v2 1/4] media: v4l: dev-decoder: Add source change V4L2_EVENT_SRC_CH_COLORSPACE

[Nicolas Dufresne]

Hi Hans,

Le lundi 07 avril 2025 à 11:54 +0200, Hans Verkuil a écrit :
> On 17/01/2025 07:19, Ming Qian wrote:
> > Add a new source change V4L2_EVENT_SRC_CH_COLORSPACE that
> > indicates colorspace change in the stream.
> > The change V4L2_EVENT_SRC_CH_RESOLUTION will always affect
> > the allocation, but V4L2_EVENT_SRC_CH_COLORSPACE won't.
> > 
> > Signed-off-by: Ming Qian <ming.qian at oss.nxp.com>
> > ---
> >  Documentation/userspace-api/media/v4l/vidioc-dqevent.rst | 9 +++++++++
> >  .../userspace-api/media/videodev2.h.rst.exceptions       | 1 +
> >  include/uapi/linux/videodev2.h                           | 1 +
> >  3 files changed, 11 insertions(+)
> > 
> > diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
> > index 8db103760930..91e6b86c976d 100644
> > --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
> > +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst
> > @@ -369,6 +369,15 @@ call.
> >  	loss of signal and so restarting streaming I/O is required in order for
> >  	the hardware to synchronize to the video signal.
> >  
> > +    * - ``V4L2_EVENT_SRC_CH_COLORSPACE``
> > +      - 0x0002
> > +      - This event gets triggered when a colorsapce change is detected at
> 
> colorsapce -> colorspace
> 
> > +	an input. This can come from a video decoder. Applications will query
> 
> It can also come from a video receiver. E.g. an HDMI source changes colorspace
> signaling, but not the resolution.
> 
> > +	the new colorspace information (if any, the signal may also have been
> > +	lost)
> 
> Missing . at the end. Also, if the signal is lost, then that is a CH_RESOLUTION
> change, not CH_COLORSPACE.
> 
> > +
> > +	For stateful decoders follow the guidelines in :ref:`decoder`.
> 
> I think this should emphasize that if CH_COLORSPACE is set, but not CH_RESOLUTION,
> then only the colorspace changed and there is no need to reallocate buffers.
> 
> I also wonder if the description of CH_RESOLUTION should be enhanced to explain
> that this might also imply a colorspace change. I'm not sure what existing codec
> drivers do if there is a colorspace change but no resolution change.
> 
> I'm a bit concerned about backwards compatibility issues: if a userspace application
> doesn't understand this new flag and just honors CH_RESOLUTION, then it would
> never react to just a colorspace change.
> 
> Nicolas, does gstreamer look at these flags?

So its used in two places:

At runtime (shared between HDMI receiver and decoders):

    if ((event.u.src_change.changes & V4L2_EVENT_SRC_CH_RESOLUTION) ==
0) {
      GST_DEBUG_OBJECT (v4l2object->dbg_obj,
          "Received non-resolution source-change, ignoring.");
      goto again;
    }


Meaning we currently completely ignore the event if it does not have
the flag. And the second usage is while waiting for the initial
resolution:

      if (event.type == V4L2_EVENT_SOURCE_CHANGE &&
          (event.u.src_change.changes & V4L2_EVENT_SRC_CH_RESOLUTION))
{
        GST_DEBUG_OBJECT (v4l2object->dbg_obj,
            "Can't streamon capture as the resolution have changed.");
        ret = GST_V4L2_FLOW_RESOLUTION_CHANGE;
      }



I remember some doc explaining that once we receive that even we must
cycle through streamoff/on, but can't find it now, I'll check further
tomorrow. I wanted to check if that was specific to
V4L2_EVENT_SRC_CH_RESOLUTION or global to V4L2_EVENT_SOURCE_CHANGE.
Also, there is likely some difference between codec and HDMI.

I think backward compatibility will be difficult on that one. I'm happy
that you find the time to have a look, and looking for good ideas.

Nicolas


> 
> Regards,
> 
> 	Hans
> 
> > +
> >  Return Value
> >  ============
> >  
> > diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> > index 35d3456cc812..ac47c6d9448b 100644
> > --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> > +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
> > @@ -526,6 +526,7 @@ replace define V4L2_EVENT_CTRL_CH_RANGE ctrl-changes-flags
> >  replace define V4L2_EVENT_CTRL_CH_DIMENSIONS ctrl-changes-flags
> >  
> >  replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags
> > +replace define V4L2_EVENT_SRC_CH_COLORSPACE src-changes-flags
> >  
> >  replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
> >  
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index c8cb2796130f..242242c8e57b 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -2559,6 +2559,7 @@ struct v4l2_event_frame_sync {
> >  };
> >  
> >  #define V4L2_EVENT_SRC_CH_RESOLUTION		(1 << 0)
> > +#define V4L2_EVENT_SRC_CH_COLORSPACE		(1 << 1)
> >  
> >  struct v4l2_event_src_change {
> >  	__u32 changes;