fluggo-media

For a good while now, I've wanted to ditch the software rendering mode in Canvas.

See, the plan from the start was that you could write your filters in any of three modes: 16-bit software, 32-bit software, or 16-bit hardware. Well, in order to make it possible to do all your rendering in software, I was going to have to require filter writers to duplicate their GL shaders onto the CPU. That's not a trivial task. I wanted to make this simple.

Now, I could maybe make the right hardware a requirement, but my main development system, an old laptop, has a mobile ATI R200 graphics adapter in it, and the old Mesa drivers for it don't support the ATI_texture_float extension. Floating-point textures are essential to Canvas, so I could either insist on a software mode or ditch the laptop. And I just managed to squeeze in more development time by coding on the train on the way to work.

Well, I peek around at the Mesa website, and what do I see? The feature I'm after was added in 7.11, but to the Gallium drivers, which for ATI would be R300 and later. I can't use a Gallium driver for my hardware, but the Mesa people have been hard at work on a nifty side project: a pure software renderer that uses the Gallium architecture (and therefore the extension I need) called llvmpipe. It's not in my system's repositories, but it's just a software drop-in replacement for libGL, so a quick build of Mesa later and... bingo! I have both software and hardware rendering with GL. Well done Mesa. That was a huge time and money saver.

Now people using Canvas can be sure that they can render their video on any hardware, and it should look the exact same. I think the Mesa drivers will also be a little harder on me where my GLSL code is concerned, and that's fantastic.

Turns out the TypeError in QGraphicsScene.items() was my fault. The thought occurred to me that QGraphicsScene had to be trying to call into Python code, but since QGraphicsScene was written in C++, the only way it could do that would be through some sort of override somewhere that PyQt4 was trying to provide.

Well, a lot of the attributes I had in my QGraphicsItem-derived classes were properties. There was a good chance I had stepped on a name already in QGraphicsItem, and PyQt4 was trying to override it using my property object. And lo and behold, that was it. The property:

1 @property
2 def type(self):
3     raise NotImplementedError

(which I admit was stupid in the first place, making an attribute the same name as a builtin) was stepping on QGraphicsItem.type(). Changing the name to stream_type fixed the issue. All is quiet on the console.

There was a good sign that I was in the wrong, and I missed it: nobody else seemed to have the same problem. I keep ignoring that.

The site tells me it's been 545 days since I wrote the only other news post on here. Clearly that's not enough.

I've thought about properly creating a blog to tell of my experiences creating this thing. For now, here's my blog, and here's where I'm going to talk about some build issues I just dealt with.

The thing I'm realizing about open source coding is that you can never be sure when something upstream is going to break on you. You have a few choices about it. You can go with Debian, which updates once in a blue moon, and be stable, but old. (And right now, that's looking pretty good.) Or you can go with Ubuntu or Mint, which seem to keep catching Debian Sid with its pants down.

For example, consider this clang bug. What happened is that libc6-dev moved some of its files to an arch-specific /usr/lib/* directory. The GCC toolchain knew about it. Nobody updated clang, or thought it might be a good idea to symlink those files back from their original location, so that people could find them in the meantime. It's marked fixed in clang, but I think it wasn't fixed in time for the Ubuntu/Mint release, so maybe it'll get fixed in the next release. So the lesson here is, if you want to build the editor with clang on Mint 12, you have to set up some symlinks or rebuild clang.

And so what should I do? It's no good to adjust my build process to deal with a temporary problem. I guess I just need to document it somewhere.

The other that drives me nuts is phantom stuff. Apparently also in Mint 12, a call to items() on QGraphicsScene prints this on the command line:

TypeError: 'property' object is not callable

As far as I can tell, it has nothing to do with my code. The rest of the calling method (in fluggo.editor.ui.scene) executes just fine. But it took me an hour to figure that out.

(Follow-up: It was my fault after all.)

(Incidentally, here's a trick for really hard-to-find exceptions: replace sys.excepthook with a method that calls pdb.set_trace() and then run your program under pdb. When it reaches the trace point, issue the command where.)

Anyhow, I don't expect anyone's been following the events for the last two years, but I'm going to start writing more about my work anyways. Work out some of the decisions I'm making, how and why I'm doing things. I'm working on plugin stuff now; maybe I'll write about that next time.

A few months ago, I thought it would be nice if I had a log of all the things I was encountering when creating Canvas and the media library, and how I was attacking each problem. Aaaaand then months went by. I've installed blogging software before, and then always got busy not writing anything. So this is the first post about fluggo-media, and hopefully I'll be as diligent writing this as I am writing my software.

Also: I know I have no readers at this point. I'm hoping someone can come into Redmine later and go back through the News section on this project to study my thoughts on the matter. If they end up being important. I also hope a few strangers stop by and see what I'm working on, and not losing hope that the last commit was a week or two ago.

So anyhow: what I'm working on now.

Documentation¶

I've got a C# background, so I've experienced awesome inline code documentation at the hands of NDoc (long since eclipsed by Microsoft's own Sandcastle). So I thought, "This is the open source community, the same community that produced NDoc. Surely they've got something just as good, since they work with code all of the time."

Yeah, no. Linux programmers love text files, and aren't real big on presentation. Doxygen is the prime example of that. Yes, it's inline documentation, but it's poorly structured, and it's ugly as sin.

I was adamant that I didn't want to separate my documentation from my code. Working with both together in C# was just so natural, and it made sense: You change the code, you change the documentation to match. Right now, in the git repository, there's a docs target for my SConstruct that attempts to build documentation with Natural Docs. This is a documentation builder that promised to be prettier and more structured than Doxygen and pulled from code comments. The result? Well, difficult to do any sort of serious formatting with it. Not to mention it had some weird formatting choices, not only in its base templates (which use indented paragraphs), but in its HTML generator (which inserts extra spaces after periods-- what? Someone from the typewriter era wrote that.).

I experimented for awhile putting my documentation in Redmine. I didn't like separating the two, but with Redmine, I could really control the documentation structure, and I really liked Textile. I didn't get much of anywhere, especially since I knew it would fall behind the code.

Every time I had searched for documentation generators, though, I kept tripping over Sphinx, the documentation generator for Python. Now, Python has some nice documentation—and they have a lot of it—but I kept skipping over it because I could only do Python docs inline. My C code would have to have separate documentation written.

I finally resolved to give it a try, though, because it seemed to have broader language support and formatting choices than Natural Docs, and did have the benefit that my documentation could be versioned right alongside the code. And you know what? It's beautiful. I love it. The results it produces are pretty, right up there with the Python docs themselves. I don't have to mess with any of the default templates.

I also learned that it's perfectly OK, especially in the case of C, to have documentation separate from the code. The reason is that you really don't want the interfaces to change on you. Sure, you might add a function or two, and you might forget to document them, but you shouldn't be going back and changing old functions.

So that's one thing I'm working on now, getting a whole bunch of documentation written in reST for Sphinx.

Windows¶

The other big thing I've gotten sidetracked with is a Windows port. All of the code written so far has been written with GNU/Linux in mind. I had thought that I might start a Windows port waaay down the road. I changed my mind the other day; Chris, my brother, is interested in contributing to the project, and he's on Windows. I thought, well hey, he should be able to contribute to the Python side of things, and I've been careful to pick cross-platform tools. How hard could it be to get a Windows build going?

Oi! I've programmed on Windows for years. You might say I'm a native there. But all I really ever worked with was Visual Studio (and Borland C++, and QuickC—you remember QuickC?). Getting a build working without Microsoft's help—that is, with MingW and company—is not easy!

I might have had an easier time if I'd chosen to do it with Cygwin. I've worked with Cygwin and I'm used to it. Part of the reason I didn't was that SCons wasn't available for Cygwin. Another was the warning given at a lot of sites that building with Cygwin always left the possibility that you accidentally dragged a Cygwin dependency into your binaries. No, sir, that wasn't for me. Even if MingW is harder, I'm sure I can sort it out and be more confident about the build than I would be with Cygwin.

I still think that's true, but MingW and MSYS aren't always the easiest to work with. I'll save the details of my arcane incantations for later, but suffice it to say, in terms of ease of use for the programmer, UNIX has got Windows' butt thoroughly kicked.

Also: Canvas¶

The Windows thing is kind of a sidetrack. The last thing I was working on in the actual code was support for some of the major features of the Canvas UI, such as narratives, timelines, anchors, groups, etc. Some of that scares me, so it's good to get a break before I go back to it. The good news, and the reason I can move on to that stuff, is that most of the base class library is finished. There are simple tools for the basic tasks: demuxing a file, decoding a picture/sound, reconstructing a picture, editing it, mixing it, restructuring it, encoding it, muxing it, saving it, and displaying it. They all need to be expanded later, but they'll do to get the project off the ground.

So there you have it. Both a first post and a progress report. I hope to commit, sometime soon, a workable Windows build process, and maybe soon after that some of the Sphinx docs, since those will be most useful to anyone hacking on the project. Maybe I'll attract one or two someones like that. Later.