drivers: video: add format utilities to improve usability #79476

josuah · 2024-10-06T18:51:34Z

Introduce several enhancements for dealing with the video API:

Documentation of formats inspired from this LWN article [EDIT: this representation is convenient, but note that the bit packing of RGB565, RGB555, RGB565X, RGB555X are wrong in it].

note: this image is wrong for RGB565 format!

But in a text-based format to be easy to maintain and colorblindness-friendly, and easy to grep through[EDIT: fixed version below]:

* | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | ...
* | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | ...
*
* | gggBbbbb | RrrrrGgg | ...
*
* | Xxxxxxxx Rrrrrrrr Gggggggg Bbbbbbbb | ...

Add a printf() formatter like stdint.h's PRIu32: printf("video format: " PRIvfmt, PRIvfmt_arg(&fmt));
This is present elsewhere on Zephyr
Convert video_fourcc() to VIDEO_FOURCC() and make it visible to the documentation, now that it is used outside of the header itself.
Add a VIDEO_FOURCC_FROM_STR() to easily convert a string from i.e. Kconfig or the devicetree.

Looking forward to your feedback and advises.

loicpoulain · 2024-10-07T18:29:50Z

include/zephyr/drivers/video.h

+/**
+ * @brief Print formatter to use in printf() style format strings.
+ *
+ * This prints a video format in the form of "{width}x{height} {fourcc}" format


From macro below, should be "{fourcc} {width}x{height}" ?

You are right, I changed it after seeing how v4l2-ctl and the examples show the formats but forgot to update thedoc. I will adjust it along with other doc fixups.
Thank you for pointing it!

josuah · 2024-10-14T21:55:14Z

force-push: CI fixes
force-push: rebase

josuah · 2024-10-15T16:16:47Z

force-push: use _BPP instead of _BITS_PER_PIXEL following this new function naming:
https://github.com/zephyrproject-rtos/zephyr/pull/76475/files#diff-70c4de6949b97c13ac893b4bfb16fbcc433593fbfa96ec8947bb5cb83c4d04bcR835-R852

josuah · 2024-10-21T10:02:42Z

force-push: split <zephyr/drivers/video-formats.h> into <zephyr/drivers/video/formats.h>, like it is done for all other Zephyr driver includes: include/zephyr/drivers

josuah · 2024-10-25T17:34:12Z

force-push:

Doc fix, I did not spot it from running make -C doc doxygen!

include/zephyr/drivers/video.h

kartben · 2024-11-08T16:58:18Z

include/zephyr/drivers/video.h

 */
-static inline unsigned int video_pix_fmt_bpp(uint32_t pixfmt)
+static inline unsigned int video_bits_per_pixel(uint32_t pixfmt)


need migration guide for the dropped API

This one is not an API. It's just an utility / helper function. Do we also need migration guide for this ?

Perhaps I misunderstood ... It seems all functions in a .h are considered as APIs.

Anything that's part of a public header and not explicitly marked as internal is to be considered de-facto API :) (see e.g. https://docs.zephyrproject.org/latest/doxygen/html/group__video__interface.html#gabc1c6fd4e13480b269cac9f224ee1c5b)
You may want to review the current API and look for those utilities you folks would like to mark as internal (but that would still require a heads-up to users in the form of a migration guide so that they are aware they might want to move away from using the now internal API).
FWIW it looks to me as if it would be fine to actually keep this as a public API though, it's a utility that might be useful for any user, not just in-tree drivers..?

yes, it should not be internal and can be used by any user. Thanks

kartben · 2024-12-20T06:52:40Z

@josuah will you be coming back to this?

josuah · 2024-12-20T15:33:37Z

Yes absolutely. As soon as the "must finish before end of the year" race is over if possible.

josuah · 2025-01-10T22:59:23Z

force-push:

rebased on main
added a release note and migration guide

cfriedt · 2025-01-18T09:59:43Z

doc/releases/migration-guide-4.1.rst

+* The ``video_pix_fmt_bpp()`` function was returning a byte count, this got replaced by
+  ``video_bits_per_pixel()`` which return a bit count. For instance, invocations such as
+  ``pitch = width * video_pix_fmt_bpp(pixfmt)`` needs to be replaced by an equivalent
+  ``pitch = width * video_bits_per_pixel(pixfmt) / 8``.


Please use BITS_PER_BYTE throughout this change.

cfriedt

Please use BITS_PER_BYTE instead of /8 or *8

Introduce a new text documentation of the video formats, describing every bit, gives the position of the most significant bit, outline how it is cut in bytes, and show the pixel segmentation. Extra care is taken for the RGB565 which requies paying attention to the bit endianess as well as the byte endianess. Signed-off-by: Josuah Demangeon <[email protected]>

Rename video_fourcc() to VIDEO_FOURCC(), differing from the Linux implementation, but more compliant with the coding style. Also introduce a VIDEO_FOURCC_FROM_STR() to generate a FOURCC format code out of a 4-characters string. Signed-off-by: Josuah Demangeon <[email protected]>

This was present in the form of video_pix_fmt_bpp() inside ST and NXP drivers, and was returning the number of bytes, which does not allow support for 10-bits, 4-bits or non-byte aligned video formats. The helper leverages the VIDEO_PIX_FMT_*_BITS macros. Signed-off-by: Josuah Demangeon <[email protected]>

The previous commit introduces video_bits_per_pixel() and converts all invocation relying on video_pix_fmt_bpp(), 3rd-party users will need to do the same on their code, and this is not a 100% drop-in API, so better document it on the release notes. Signed-off-by: Josuah Demangeon <[email protected]>

josuah · 2025-01-18T14:15:23Z

force-push:

rebase on main
use / BITS_PER_BYTE instead of / 8 when relevant (thank you @cfriedt!)

I also applied BITS_PER_BYTE here location hoping that is what was meant.

cfriedt · 2025-01-18T14:19:05Z

doc/releases/migration-guide-4.1.rst

+* The ``video_pix_fmt_bpp()`` function was returning a byte count, this got replaced by
+  ``video_bits_per_pixel()`` which return a bit count. For instance, invocations such as
+  ``pitch = width * video_pix_fmt_bpp(pixfmt)`` needs to be replaced by an equivalent
+  ``pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_PIXEL``.


this should probably be BYTE instead of PIXEL

Suggested change

``pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_PIXEL``.

``pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_BYTE``.

My bad, I tried to slip this between two other tasks. I'll wait to be less busy and try again.

josuah added Enhancement Changes/Updates/Additions to existing features area: Video Video subsystem labels Oct 6, 2024

josuah requested review from ngphibang, loicpoulain and LucasTambor October 6, 2024 18:51

zephyrbot added the area: Samples Samples label Oct 6, 2024

zephyrbot requested review from kartben and nashif October 6, 2024 18:52

zephyrbot assigned kartben Oct 6, 2024

loicpoulain reviewed Oct 7, 2024

View reviewed changes

loicpoulain self-requested a review October 11, 2024 20:04

josuah force-pushed the pr-video-format-utilities branch from 29a4758 to 6c21f48 Compare October 14, 2024 11:40

loicpoulain previously approved these changes Oct 14, 2024

View reviewed changes

josuah dismissed loicpoulain’s stale review via 6762ced October 14, 2024 13:58

josuah force-pushed the pr-video-format-utilities branch 3 times, most recently from c021247 to d541c10 Compare October 14, 2024 21:53

josuah force-pushed the pr-video-format-utilities branch from d541c10 to a9587f1 Compare October 15, 2024 16:14

josuah mentioned this pull request Oct 15, 2024

Improve NXP CSI and MIPI_CSI2Rx drivers #76475

Merged

zephyrbot added the area: C++ label Oct 21, 2024

zephyrbot requested review from alexanderwachter, cfriedt and stephanosio October 21, 2024 09:59

josuah force-pushed the pr-video-format-utilities branch from 12ca486 to 75345f9 Compare October 21, 2024 10:02

zephyrbot added the area: Process label Oct 21, 2024

zephyrbot requested a review from MaureenHelm October 21, 2024 10:03

josuah force-pushed the pr-video-format-utilities branch from 75345f9 to ac056cf Compare October 21, 2024 10:08

ngphibang reviewed Oct 26, 2024

View reviewed changes

include/zephyr/drivers/video.h Outdated Show resolved Hide resolved

josuah force-pushed the pr-video-format-utilities branch from 5e8e31d to e95d1c6 Compare October 26, 2024 11:47

ngphibang previously approved these changes Oct 26, 2024

View reviewed changes

josuah dismissed ngphibang’s stale review via 7069a8b October 26, 2024 16:05

josuah force-pushed the pr-video-format-utilities branch 2 times, most recently from 7069a8b to 97746bd Compare October 26, 2024 16:22

ngphibang previously approved these changes Oct 26, 2024

View reviewed changes

kartben requested changes Nov 8, 2024

View reviewed changes

josuah added the Release Notes Required Release notes required for this change label Nov 8, 2024

kartben assigned ngphibang and unassigned kartben Dec 12, 2024

josuah dismissed ngphibang’s stale review via 93687b2 January 10, 2025 22:35

josuah force-pushed the pr-video-format-utilities branch from 97746bd to 93687b2 Compare January 10, 2025 22:35

zephyrbot added the Release Notes To be mentioned in the release notes label Jan 10, 2025

josuah removed the Release Notes Required Release notes required for this change label Jan 10, 2025

ngphibang previously approved these changes Jan 15, 2025

View reviewed changes

cfriedt reviewed Jan 18, 2025

View reviewed changes

cfriedt requested changes Jan 18, 2025

View reviewed changes

josuah added 4 commits January 18, 2025 13:17

josuah dismissed ngphibang’s stale review via 6ce200d January 18, 2025 14:12

josuah force-pushed the pr-video-format-utilities branch from e8ad2e7 to 6ce200d Compare January 18, 2025 14:12

cfriedt reviewed Jan 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

drivers: video: add format utilities to improve usability #79476

drivers: video: add format utilities to improve usability #79476

josuah commented Oct 6, 2024 •

edited

Loading

loicpoulain Oct 7, 2024

josuah Oct 7, 2024

josuah commented Oct 14, 2024

josuah commented Oct 15, 2024

josuah commented Oct 21, 2024

josuah commented Oct 25, 2024

kartben Nov 8, 2024

ngphibang Nov 8, 2024 •

edited

Loading

ngphibang Nov 8, 2024 •

edited

Loading

kartben Nov 8, 2024

ngphibang Nov 8, 2024

kartben commented Dec 20, 2024

josuah commented Dec 20, 2024 •

edited

Loading

josuah commented Jan 10, 2025

cfriedt Jan 18, 2025 •

edited

Loading

cfriedt left a comment

josuah commented Jan 18, 2025

cfriedt Jan 18, 2025

josuah Jan 18, 2025

	``pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_PIXEL``.
	``pitch = width * video_bits_per_pixel(pixfmt) / BITS_PER_BYTE``.

drivers: video: add format utilities to improve usability #79476

Are you sure you want to change the base?

drivers: video: add format utilities to improve usability #79476

Conversation

josuah commented Oct 6, 2024 • edited Loading

loicpoulain Oct 7, 2024

Choose a reason for hiding this comment

josuah Oct 7, 2024

Choose a reason for hiding this comment

josuah commented Oct 14, 2024

josuah commented Oct 15, 2024

josuah commented Oct 21, 2024

josuah commented Oct 25, 2024

kartben Nov 8, 2024

Choose a reason for hiding this comment

ngphibang Nov 8, 2024 • edited Loading

Choose a reason for hiding this comment

ngphibang Nov 8, 2024 • edited Loading

Choose a reason for hiding this comment

kartben Nov 8, 2024

Choose a reason for hiding this comment

ngphibang Nov 8, 2024

Choose a reason for hiding this comment

kartben commented Dec 20, 2024

josuah commented Dec 20, 2024 • edited Loading

josuah commented Jan 10, 2025

cfriedt Jan 18, 2025 • edited Loading

Choose a reason for hiding this comment

cfriedt left a comment

Choose a reason for hiding this comment

josuah commented Jan 18, 2025

cfriedt Jan 18, 2025

Choose a reason for hiding this comment

josuah Jan 18, 2025

Choose a reason for hiding this comment

josuah commented Oct 6, 2024 •

edited

Loading

ngphibang Nov 8, 2024 •

edited

Loading

ngphibang Nov 8, 2024 •

edited

Loading

josuah commented Dec 20, 2024 •

edited

Loading

cfriedt Jan 18, 2025 •

edited

Loading