The Linux Graphics Documentation That's Needed

[Tsiolkovsky]

Needed Linux graphics documentation

I think that what is needed first is a fairly detailed overview of the modern Linux graphics stack, so thet you know what all those many pieces are and how they fit together and so that you know which part you should then focus on.

After this overview each part of the stack should be described with lots of details. Well if there is already a book about some part there could only be a reference to that book. So I guess this would only leave the most modern parts, like Gallium3D, which would need a detailed description in this book/wiki/document, and for which there is no existing book focusing on them yet.

Maybe the documentation could be written in such a way that it would be very usefull to students focusing on computer graphics/GUI and could then become one of the more usefull materials for such students.

[leeyee]

I agree with you, Tsiolkovsky and kde185. It seems that X community lacks a well unified document set to explain how exactly X works and how the components of X stack fit together.

I am not a programmer, but I am quite interested in how X and graphics work in Linux, and I also eager to contributing to these things if it's possible. I tried a lot on various wiki-materials but never gained a comprehensive overview of the stuff(dri documentation on freedesktop.org seems good, but not enough). That's depressed!(Honestly, maybe I lack necessary backgrounds)

So I think it should be better if some skilled developers could collect those information on Internet together, and formed them in a clear order, then it will be easier for users or novice developer to move forward. A book is definitely the best choice, I won't hesitate to buy one.

This is my little suggestion on the matter.

Regards

[JensOwen]

Good Feedback!

I signed up just to respond to this because it's probably the biggest obstacle I've run up against when trying to get involved with X testing and development.

One thing that would be helpful is perhaps some good pointers on books that could teach me how graphics cards and X work. C has the "K&R C" book. The Linux kernel has "Linux Device Drivers" and probably more. Is there something analogous to these fundamental books in the open source graphics drivers world?

I have not seen anything as well documented at the Linux Kernel Book for driver level interfaces. Even in proprietary environments, DDK's simply aren't as well documented as SDK's. Kudo's for setting the bar high, but I doubt we will see anything as detailed as the LInux Device Drivers Book in the near future.

Another thing which might have less to do with documentation and more about packaging. It would be nice if there was an easy way to build an entire X stack, without all of the dependency hell. Perhaps distributions could add a metapackage that pulls in all of the development packages needed. If something like this already exists, then it sure would be nice to know.

In the face to face workshop we experimented with putting together the development environment for all the labs on a virtual machine image. We were then able to provide copies of the image to all the participants and they could bring up the environment in a free version of VMware's VM player and work along during the labs without having to spend time up fronting getting the dependencies worked out.

Do you think this type of approach would be helpful for developers just getting started with Gallium3D?

Another thing is the freedesktop.org and x.org websites. I'm never sure which I need to go to when looking for information about the various layers of the graphics stack. I'm not trying to be nit-picky. I'd really like to help with the graphics stack, but some of these barriers make it pretty tough to get started.

I hear you loud and clear...I just don't know a very elegant solution. The big challenge is that these two very large and separate projects can be used together (in multiple ways) or completely seperate in multiple ways. They really are the swiss army knife of open source graphics capabilities.

Perhaps a more brute force approach would be to pick a common use case scenario, create block diagrams and reference which modules from which projects the blocks come from. We did do elaborate block diagram a decade ago when we first developed the DRI. This diagram showed the blocks from the original architecture:

http://dri.sourceforge.net/doc/images/control_flow.jpg

This diagram would change quite a bit for a modern example, but would adding pointers to various parts of the relevant projects subtrees be useful?

Again, thanks for the really good feedback.

[bridgman]

There are a *lot* of X books around, to the extent that it would take a lot of courage for a publisher to fund a new one - but what you don't see is books about window managers / compositors and the driver stack. We almost need to stop talking about X for a while, since nearly all of the "problems with X" that people like to talk about have almost nothing to do with X.

I'm not sure we even have a good name for what you're talking about -- and a book called "X+drm+mesa+gallium3d+[compiz/kwin/metacity]+[GEM/TTM] made simple" doesn't really fire the imagination.

The window manager / compositor side is tricky because there are so many competing offerings, each with a different set of driver & X dependencies, and the driver internals are pretty dull stuff for everyone except the 20 or 30 people who actually work on the driver code.

In many ways drivers have the same documentation challenge as window manager / compositors - any one of them is reasonably easy to explain, but in there are perhaps a dozen different driver stacks all going through similar architectural changes but at different rates, each with their own set of framework dependencies, and distro packagers have the challenge of making them *all* work at the same time.

You aren't seeing a lot in the way of docs or books right now because the beginning state was relatively simple, the end state is really simple, but the in-between state is (a) changing weekly, (b) being designed along the way (c) complicated by the need to support 2 or 3 different driver architectures at the same time, (d) further complicated by the fact that *each* of those architectures has a different set of dependencies and quirks with the different competing window manager / compositor solutions, made even *more* complicated because two major components (window manager / compositor and driver stack) were designed independently and are only now starting to have the small-but-important details fitted together, and finally (f) "coming to market" through a set of driver, Xorg, kernel and distro releases which all happen on different and uncoordinated schedules.

It's probably fair to say that most of the developers feel that right now their time is better spent getting to the relatively clean and simple end state than trying to document the complicated, constantly shifting and completely transient current state.

A better approach, IMO, is to steer new developers towards components which have reached their "final" architecture, rather than trying to document the in-transition stack and having to throw all that documentation away in 6-9 months anyways. Some of that is already happening and I think we'll see more over the next few months. The driver stack will probably have to offer synchronization and other API solutions to the window manager / compositor teams, but that already seems to be happening.

The final problem is that there is not a lot of commonality in the way that popular apps (particularly browsers and video players) use the graphics APIs. I'm not sure if "providing guidance" to app and toolkit developers would be sufficient, or if that guidance has been provided and it's just a matter of time until the apps start to align.

[Hephasteus]

The computer industry has become a laughing stock. I used to be able to get pin out nitty gritty details of everything for every chip put out. Now they pull a shit storm marketing blizzard out of their ass and call it a "white paper".

[bridgman]

Yep, I remember those days. Back when semiconductor companies had 70% margins, brought out a new family of chips every 10 years, charged a million dollars for a minicomputer, "real" computers came from IBM, and everyone wore wide ties. I don't miss the wide ties, but we did a lot of good things (like documentation) with the higher margins and the time between chip generations.

Not sure I get the connection though -- wasn't this discussion about documentation for a graphics software stack created and maintained by a group of volunteers ?

[Louise]

I think the way WINE have a status page for every small feature is a very good and motiving thing.

http://www.winehq.org/status

It is different from the Status Matrixs Radeon in that, WINE have broken the tasks up in small tasks, where Radeon is high end.

Both methods are good, but for a new comer, WINE's status matrix is much more appealing, as you have a change of changing a few colour here and there

[V!NCENT]

If you want to get dirty with X then why don't you start reading the Linux From Scratch books? I know I learned more about Linux from LFS than from anything else.

In the end I didn't build my own, but it's practically a piece of documentation about the entire Linux OS...

[leeyee]

LFS books are more likely about building a working X(forgive me for using this word again for all the graphics related stuff), rather than talking about development work of it(or in an other word, how these components work internally).

[V!NCENT]

LFS books are more likely about building a working X(forgive me for using this word again for all the graphics related stuff), rather than talking about development work of it(or in an other word, how these components work internally).

Yes that's the entire point. But I figured that if you learn what to compile and why, what is needed and what is not and why, what it depends on and etc ect etc. its would be easyer to understand the X.org implementation, before diving into development documentation. It's cool that you learn the code, but if you don't know what a particular module is for in the first place the... well... yeah...

I, for one, learn a lot faster if I have an overview of things that I am about to learn before I dive into the deep, so to speak...