You are here: Architecture and Design > Other Design Considerations

Other Design Considerations

The C++ classes and functions that make up the MrSID SDK follow a few other general principles and conventions. They are explained here to motivate their usage. For other, less central principles, see "Coding Conventions".

Status Codes

Many of the SDK member functions return status codes to report success or failure conditions, instead of other mechanisms such as throwing exceptions. The status codes are represented using the LT_STATUS datatype (typedef’d to an unsigned integer). Functions that return status codes must be checked for success or failure.

Initializations

Heavy-weight objects requiring nontrivial work in their constructors provide an initialize() member function that must be called immediately after invoking the object’s constructor. While this requires extra code for the developer, it provides a means for returning status codes back to the caller without relying on constructor-thrown exceptions.

Creator Deletes Rule

The SDK classes generally follow the “creator deletes” rule. That is, the object that allocates a new object on the heap is responsible for deleting it as well. (The documentation notes specifically where this rule does not hold and ownership is to be passed across a call-site.) In some cases reference counting, via the RC<> class, is used to address this issue.

“No Magic” Rule

The functions in the SDK tend not to provide features or functionality that attempt to silently “guess” at default values for complex situations or otherwise “just do the right thing.” While such guesses are often correct and occasionally easier for the developer, they are just as often incorrect or serve only to mask deeper errors or workflow inefficiencies. For example, the various decode methods can return pixels only in the colorspace and datatype of the input image stage: no mechanism for implicit conversion is available, e.g. via configuration of the output buffer. In this case, a datatype filter and a colorspace filter must be explicitly built into the image pipeline.

Reference Counting

The SDK uses reference counting to manage the lifespan of objects that comprise image pipelines. This is similar in spirit to “smart” or “auto” pointers. The static member function create() of a class should be used to create a new instance of that class. Similarly, the (non-static) member function release() should be used when you are done with object – for example, when the pointer to the object goes out of scope. The retain()function should be used to hold onto an object, i.e. increment the reference count; if you created the object, however, do not call retain(). When the last reference calls release(), the object will delete itself.