Need for better docs for video setup (legacy vs FKMS vs full KMS) & video APIs

[egnor]

👏 Thanks doc team for taking on the thankless work of curating the doc site! 👏

(I'm happy to help with this request given appropriate guidance, but I'm not sure how you'd want to structure things. I've attempted to collect an updated summary here which might be a helpful starting point.)

Questions about video acceleration setup (for 3D, for video stream playback, etc) are common in the forums, the situation is fairly complex, and the existing documentation is scattered at best. For example, these options have a lot of ramifications but are hardly documented (and can be a bit misleading):

Meanwhile, other sections contain references and "if this, do that" switches based on video configuration (legacy vs FKMS vs full KMS) that are often inconsistent (and can be a bit misleading):

The impact of the "legacy" vs FKMS vs full KMS choice on video configuration for Pi3/Pi4 is quite a matrix, so the doc task is nontrivial, at the same time I see plenty of confusion in the forums when people try to configure something and it doesn't work the way they expect (or the documentation indicates).

[aallan]

So this seems to be a topic that's currently spread throughout several places in the documentation. Where do you see the content living?

[egnor]

I was expecting y'all would have opinions about that per some Master Plan for doc organization :-)

My best stab would be to create a new heading under "Configuration" called something like "Video Graphics". Under that, create a subheading like "Video Driver and 3D Acceleration" where we discuss (in summary, with pointers to details) the overall architecture, the three choices, and the ramifications of those choices. Then I would move "HDMI Configuration" and "Rotating your Display" under "Video Graphics" as well; they can have if/thens as appropriate calling back to the first choice.

[aallan]

This might well get covered by #2102, and if it doesn't potentially it should be? /cc @davidplowman

[davidplowman]

I'd be very happy for more display/3D documentation, but I don't think camera documentation is really the place for it. You can run cameras quite happily without any display at all (and many do)!

[aallan]

I'd be very happy for more display/3D documentation, but I don't think camera documentation is really the place for it. You can run cameras quite happily without any display at all (and many do)!

Fair point. Who on the team should I be poking with the stick about this one?

[davidplowman]

I suppose the default starting point would be Gordon... :)

[JamesH65]

@6by9 Dave Stevenson is probably the best person for this sort of task, but he has his plate full at the moment. Also, KMS is still beta although nearly ready, I doubt there will be many changes before its release. There are also ramifications to do with DSI displays etc but we have some plans in place for documenting that already.

[aallan]

Also #2310.