On 2025-02-15 09:40, Simon Ser wrote: > On Monday, February 10th, 2025 at 23:03, Harry Wentland <harry.wentland@xxxxxxx> wrote: > >>>> + * DOC: overview >>>> + * >>>> + * A colorop represents a single color operation. Colorops are chained >>>> + * via the NEXT property and make up color pipelines. Color pipelines >>>> + * are advertised and selected via the COLOR_PIPELINE &drm_plane >>>> + * property. >>>> + * >>>> + * A colorop will be of a certain type, advertised by the read-only TYPE >>>> + * property. Each type of colorop will advertise a different set of >>>> + * properties and is programmed in a different manner. Types can be >>>> + * enumerated 1D curves, 1D LUTs, 3D LUTs, matrices, etc. See the >>>> + * &drm_colorop_type documentation for information on each type. >>> >>> It's not super nice to refer to internal kernel docs here, because AFAIU >>> this section is mostly written towards user-space developers. User-space >>> developers have no idea how internal kernel structs work. >>> >>> It would be nicer to have a list of colorop types here, without referring >>> to kernel internals. For instance, we have a list of >> >> I'm not sure I follow. This is linking to the drm_colorop_type >> (from drm_mode.h) enum documentation in drm-uapi.html. >> >> Duplicating it here would mean that sooner or later the two >> docs will get out of sync. > > Oh, I thought this was an internal kernel enum. I guess the only missing > thing is the string exposed to user-space for each enum entry then? > Good point. We'll add that to the enum drm_colorop_type docs. I did a brief survey of other enum properties and noticed that this isn't well documented for others, such as the Content Protection connector property, or the COLOR_RANGE and COLOR_ENCODING plane properties. On the IGT front, some tests set enum properties via enum strings, and other set and get enum properties based on the prop uint64_t prop_values[i] entry from the drmModeObjectPropertiesPtr. Do you know if there's a best practice for enum usage or is it mostly a case of "use what works for you"? Harry > In any case, sounds good to me. > >> I agree with the rest and we'll reflect that in v8. > > Sweet!
