This document outlines the modifications that are required to introduce a new input and/or output module to the program. This should be read in conjunction with the API documentation and source code.
The first task is to examine the structure and element types of the file format. Can all the possible information be stored in the intermediate structure adequately? Remember that initially you only need to work with the features that can be output or converted - especially if you are not planning to write an output module for this format. This can reduce the amount of work required to input complex formats.
If the intermediate structure is not sufficient to represent the new file format, it will need to be modified or extended. When modifying existing elements or effects, ensure that the current API will work unaltered. Always document extensions to the structure and ensure that it is both backward and forward compatible. Make sure that in the future features (or current unimplemented features) can easily be added to the structure: take care when enumerating fields, do not assume the range of values available - especially when using switch or if-else statements - and allow for graceful degradation when an unexpected value or setting is found or applied.
There are a number of things to do when adding a new element. Obviously there is the element's structure itself - make sure it is designed in such a way that it could be extended in the future without compromising original functionality. A number of functions related to the element need to be written - new, copy, destroy, and calculateBoundingBox. Then the Element structure in element.c/element.h needs to be adapted to incorporate the new element. Add an Element_Type constant with a unique number and alter the Element_new, Element_copy, Element_destroy, and Element_calculateBoundingBox functions. Element_setXXX and Element_getXXX functions need to be written as well (where XXX is the new element type).
Then the Support structure needs to be updated to check for the new element type. The size of the array inside the Support structure will need to be increased.
There are two options to allow existing output modules to output the new element type. Either the output modules can be adapted to recognise and output the new structure, or the support routines can be extended to convert the new structure into one used in the existing output or conversion routines. The latter option requires less work, although the former may provide more accurate output if the new element type is significantly different to anything else.
The support routines also have to be updated to support the new structure - edit the reverseVerticleAxis, flattenInheritence and moveEffectsToGroup routines.
The front end to the program - currently a command line interface - needs to be updated to recognise the new input format (the "-I" flag). This will call the XXX_inputPage function.
Firstly consider the structure of the output file format. Is it similar enough to the intermediate structure to allow a simple output routine, or is it so significantly different that the intermediate structure will have to be manipulated considerably before it can be output? If the latter, you may consider extending the intermediate structure to accomodate the new output format more thoroughly - see above for how to extend the structure and support routines. Altering the intermediate structure may be a good idea if it provides future developments (of new input/output modules) to be made more easily, or if an input module is also being developed for the format.
If the output module does not support all the features of the intermediate structure - it is likely that this will be true since the intermediate structure can cover a large range of formats - there are several courses of action that can be taken.
The module could simply ignore unrecognised element types. This could be a bad idea for container elements such as Groups because a lot of supported elements inside the container could be needlessly ignored.
A better solution is to make sure that there are conversion routines, within the Support section of the program, that can convert each unsupported element to a supported variety. This could be implemented by adding a link to the chain of conversions, or by providing a direct conversion step.
The front end to the program - currently a command line interface - needs to be updated to recognise the new output format (the "-O" flag). This will specify the Support structure for the format, call the Support feature-check functions, and call the XXX_outputPage function.