libdc1394 : Migration from 1.x to 2.x

Foreword

Libdc1394 has grown in complexity with time and has been patched and repatched numerous time, making it difficult to maintain. It also starts to be difficult to use it which means it's time for a little cleanup! ;-) I have worked for almost a year on the 2.0 branch which solves many issues with 1.0, but also brings new problems to the light. It's also a beta version at this stage: you have been warned. Nevertheless, the API is more or less stable at this point and following a suggestion from a user I am proposing below a guide on how to migrate your application from the 1.0 branch to the new 2.0 branch. For now the guide is limited to a few guidelines followed by an equivalence table for every function of the library. Enjoy! And don't forget to report omissions, errors or propose enhancement to this guide. ;-)

Changelog

• 2007-12-13: Roughly sync'ed to 2.0.0-rc8 (SVN 514)
• 2007-06-22: THIS PAGE IS NOT UP-TO-DATE. I will update it when 2.0 is out (or better, just before that).
• 2006-12-04: Synch'ed with SVN 331
• 2006-03-25: updated to match the CVS as of today.
• 2005-12-28: update to match libdc1394. dc1394_utils.h and dc1394_conversions.h added.
• 2005-12-19: updated to reflect the latest changes in libdc1394.
• 2005-12-11: added a description of the new error reporting mechanism and 2 new functions of v2 (capture data access)
• 2005-12-10: added dc1394_video_get_data_depth()
• 2005-12-08: initial release

Types and definitions

Here's a short itemized list of what is changed.

• all definitions now start with the 'DC1394_' prefix to avoid conflicts. This means that a lot of definitions have changed. Sorry. I don't mention below the definitions for which it's the only change.
• video modes definitions are different presented because the IIDC 'format' is now hidden (except for format7). That means that you don't have to supply a mode and format anymore; only the mode is necessary. See below for more details.
• color codings names have changed to be more consistant with IIDC names (COLOR_FORMAT to COLOR_CODING).
• color filter definitions are now DC1394_COLOR_FILTER_XXXX instead of COLOR_FILTER_FORMAT7_XXXX
• error definitions are new in libdc 2.0. See the section about error reporting.
• Several enum types have been added:
  • dc1394switch_t (DC1394_ON, DC1394_OFF). I don't like the 'switch' name but it's all I could think of.
  • dc1394trigger_polarity_t (DC1394_TRIGGER_ACTIVE_LOW, DC1394_TRIGGER_ACTIVE_HIGH) for the trigger polarity
  • dc1394feature_mode_t (DC1394_FEATURE_MODE_MANUAL, DC1394_FEATURE_MODE_AUTO, DC1394_FEATURE_MODE_ONE_PUSH_AUTO) for the operation mode of a feature.
  • dc1394video_mode_t
  • dc1394capture_policy_t
  • dc1394iidc_version_t
  • dc1394color_coding_t
  • dc1394color_filter_t
  • dc1394operation_mode_t
  • dc1394trigger_source_t
  • etc... etc...
  Functions prototypes have been modified to reflect this. It will allow stronger 'typing' and error detection at the compilation phase.
• The capture API and camera detection API have changed significantly. A new frame type has been introduced.

Structures

This is one of the areas that needed a cleanup and as you will see it's much simpler now. The general guideline is that everything concerning a camera is now in a single struct called 'dc1394camera_t'. No more handles. And the dc1394capture_t is in there too (it will be removed from the API soon when access functions will be defined). For those who looked at the guts of libdc, we used to access some hidden struct in the raw1394handle, which was quite ugly IMHO. It's much cleaner now.

This big change will be apparent in the API later so I won't comment too much on it now. The next thing is that several structs have been introduced. These are dc1394colormodes_t, dc1394video_modes_t and dc1394framerates_t. It was necessary because the functions for these features are now sending back lists of items instead of ugly binary masks.

Error reporting

Almost all functions have been changed to return a new type of value: dc1394error_t. This is an enum type defined in dc1394/log.h.

Errors are logged and returned to the parent function using four macros:

DC1394_ERR(err, err_string...)
DC1394_ERR_RTN(err, err_string...)
DC1394_ERR_CLN_RTN(err, cleanup, err_string...)
DC1394_ERR_CLN(err, cleanup, err_string...)
DC1394_WRN(err, err_string...)

The last one does not return, it simply logs a warning message.

The macros behaves like this:

• prints an error/warning message with a description of the error code, the filename in which it happened, the function name, the line number and a user supplied string.
• executes the cleanup code supplied (only for *CLN* functions)
• returns the error code to the parent function, halting the execution of the current function (only for *RTN functions).
• DC1394_ERR only returns ("return;") without any value. This breaks the trace but allows the macro to be used within functions that do not return the "dc1394_error_t" or "int" type.
• DC1394_WRN does not "return" and the calling function will continue after printing the error message.

The macros are typically called like this:

dc1394error_t err;
err=dc1394_reset_camera(&camera);
DC1394_ERR_RTN(err, "Ooops, my example program failed\n");

The error code is sent to the successive parent functions and you will thus have several errors printed one after each other, giving you a nice trace of what happened. The use of these macros is not limited to libdc internals: you can also include them in your programs (and you're even encouraged to do so). The macros are built to allow you to add values inside the user-supplied error message (i.e. the number of arguments is variable). Example:

DC1394_ERR(err, "Ooops, my example program failed for the %dth time today!\n",n++);

Note that you should not check errors by including a libdc1394 function inside the call to the error macro, otherwise the libdc function will be executed multiple time, leading to more errors (since it already failed),... in an endless loop. IOW, you should NOT write something like this if you want ot check that the reset worked well:

DC1394_ERR_RTN(dc1394_reset_camera(&camera), "Ooops, my example program failed\n");

This is obvious when you know that you are playing with macros but it's worth repeating anyway. Note also that the error function doesn't do anything if the error code is negative (which denotes a warning only). In that case you have to handle it.

Libdc1394 does not print anything to stdout or stderr anymore, or at least you can ask it to do so. A new error logging mechanism has been written, in which three types of error handlers can be assigned by the user (error, warning, debug)

The function changes (aka The Big Gun)

This is the real thing. Let's go through it.