This is a documentation file. Although it is not needed for the build, I recommend keeping it together with the other files and build up a documentation about the architecture and to start a discussion about useful approaches to avoid diverging developments. It should be beneficial to all when things are not messed up but work properly with each other.

Notes about the architecture so far
-----------------------------------

Before we start: This is just a brief global architecture documentation. Information specific to classes and to tricky parts can be found in the code itself and in the header files.

There are two targets: One is the standalone app and one is the QuickTime component. The underlying language is mainly Objective-C, using both Cocoa and Carbon (I tried to keep them separated as far as I could).

The core is the MyCameraCentral class and the Camera driver classes. The Camera Central is a singleton: There is only one per application. It can be seen as a camera database and an abstract factory. On [startup] of the central, all available camera driver classes are registered with their usb identification (their product/vendor combination). The central keeps a list of the drivers and starts a thread, the wiringThread, that looks for devices that are plugged or unplugged and match these criteria. If a camera is found, it notifies the client (which is set as delegate) about the new device with a [cameraDetected] message which contains an id identifying the device. The client may now call [useCamera] which - in case of successful connection - returns an object of type MyCameraDriver (actually a subclass for that peticular camera - that's why it's an abtract factory). The image grabbing and camera control is done in communication with the Camera Driver. The MyCameraDriver is rather a semi-abstract class (it's not intended for direct use but implements some common behavour and specifies the common camera driver interface). It also implements some tool functions for use by the subcalsses or from outside. There is a hierarchy of subclasses from MyCameraDriver.For more info on this, see the header files of the respective files. To add another camera type, create a new (direct or indirect) subclass of MyCameraDriver and add it to the registration sequence in MyCameraCentral. At the first glance, this might seem to be structural overkill. But I tried to follow the "dry" rule (don't repeat yourself) and move common functionality as far up in the hierarchy.  Don't feel shocked by all these source files - many of them are almost empty. Here's an overview:

                  ------------------MyCameraDriver----------------------------------------------- ..... others
                 /                         |                           \                         \
                /                          |                            \                         \
   MyDummyCameraDriver           MyPhilipsCameraDriver            MyCPIACameraDriver         MySTV680Driver
                                /                     \
                               /                       \
                  MyToUCamFamilyDriver           MyVestaFamilyDriver 
                   /             \                 /             \
                  /               \               /               \
       MyToUCamProDriver   MyToUCamFunDriver  MyVestaDriver   MyVestaProDriver

The DummyCameraDriver has a special role: I doesn't handle a webcam but imitates one. Why? Clients may indicate that they accept such a type of driver in case an error occurred. The video from the dummy will display an error message. This way, clients don't have to deal with errors excessively.

The app consists of two custom objects (put together with the other stuff in a nib file). One is a MyCameraDriver instance and the other is a MyController instance. The controller ties the UI to the driver (according to the MVC paradigm). There is nothing really spectacular in there, just forwarding of user events to the driver, forwarding of driver feedback to the screen and some saving functionality.

The driver consists of four parts: The driver, the video digitizer, the panel and the bridge. video digitizer and the panel files are the QuickTime interface. Pure c. Close to Carbon. Each implements a main entry point which dispatches the functions of the QuickTime component (see Inside Macintosh: QuickTime components: Video Digitizer Components and Sequence Grabber Panels for docs. It's available on http://developer.apple.com/QuickTime and in /Developers/Documentation/QuickTime). The video digitizer implements the video grabbing functionality in QuickTime. It has a global storage structure which includes an instance of the Obj-C MyBridge class. The panel adds a panel to the QT video settings to adjust more webcam-specific features as the resolution, frame rate etc. It also has a global storage, but it borrows the bridge from the video digitizer. The bridge bridges (what else?) between the Component functions and the driver, acting as a translator between the Cocoa and the Carbon world and between the interfaces. It has few functionality on its own, but acts as a thread shield to synchronize the multithreaded driver interaction (needed for background USB transfer) and the single-threaded QuickTime interaction model. Besides, it's a connection to the Central. The QTComponent.r file includes the resources needed to identify the bundle (QT components are bundles with ".component" extension) as a sequence grabber panel - the video digitizer is registered programatically (how, when and why is documented in "QT_architecture.txt").

There are a couple of tool and utility files: yuv2rgb is (nomen est omen) a yuv to rgb converter that handles yuv to rgb, 24bit or 32bit, horizontally flipped and unflipped image decoding. Resolvers offers a couple of utility functions which check and output system errors (most of them found in the USB and IOKit functions) in clear text as well as QuickTime video grabber component function selector look-up to their names. I found this useful during development. GlobalDefs has just come common macros (and I used it to specify build settings and similar things). MiscTools includes - ta-dah! - miscellaneous tools. Functions that didn't fit in anywhere else. MiniGraphicsTools implements a simple and fast method to write text into images without using a system graphics API. RGB888Scaler scales RGB888 Pixmaps.

$Id: source_documentation.txt,v 1.3 2007/02/18 06:06:43 hxr Exp $
