C.2.16 64-Bit Portability Changes

Some changes have been made to the Crystal Space API in order to better support 64-bit hardware, which is now becoming common. Additional changes to improve 64-bit support have also been made internally, but the internal changes essentially are transparent to external clients.

The most significant change to the API involves methods and classes dealing with data opaquely. Historically, opaque data has been handled using ‘void*’, and programmers would cast numbers, booleans, and pointers to ‘void*’ when it was necessary to deal with the data in an opaque fashion. This technique, however, is not portable to 64-bit platforms. For this reason, the new standard type ‘intptr_t’ was introduced. This type is guaranteed to be large enough to store any integral numeric or pointer value regardless of the machine's word size.

Crystal Space now uniformly uses ‘intptr_t’, rather than ‘void*’, when dealing with opaque data. Upgrading your code to reflect this change is usually quite simple. Where your code presently declares a variable or casts a value to ‘void*’, change it to ‘intptr_t’. Likewise, ‘void**’ becomes ‘intptr_t*’. For example:

iGraphics2D canvas = ...;
iEventOutlet* outlet = ...;
outlet->Broadcast(cscmdCanvasExposed, (void*)canvas);

Becomes:

outlet->Broadcast(cscmdCanvasExposed, (intptr_t)canvas);

The event system is impacted by this change. Specifically, the following methods and data members now deal with ‘intptr_t’ rather than ‘void*’ for the opaque “info” member of csevCommand-type events.

• csEvent::csEvent()
• csEventCommandData::Info
• iEventOutlet::Broadcast()
• iEventOutlet::ImmediateBroadcast()

The AWS plugin (Alternate Windowing System) and its interfaces have been been updated for 64-bit platform conformance. Specifically, the following methods now deal with ‘intptr_t’ rather than ‘void*’ for all of AWS's opaque data needs.

• iAwsComponent::GetProperty()
• iAwsComponent::SetProperty()
• iAwsParmList::AddOpaque()
• iAwsParmList::GetOpaque()
• iAwsSink::RegisterTrigger()
• iAwsSinkManager::CreateSink()

AWS callback functions (triggers) are likewise impacted. You need to change the declaration of your triggers to use ‘intptr_t’ rather than ‘void*’. For example:

void MyTrigger(void* sink, iAwsSource* source);

Becomes:

void MyTrigger(intptr_t sink, iAwsSource* source);

Since converting client AWS code to the new API can be rather onerous on account of the amount of repetitious manual labor involved, the old ‘void*’ API is still present in AWS, though heavily deprecated. In the interests of 64-bit portability, the old API will be removed at some point in the future. You are encouraged, therefore, to convert your code to the new API. As an aid to clients in upgrading their code to the new API, one of two control macros can be defined which will help to isolate code which needs to be updated. Defining ‘AWS_OBSOLETE_VOIDP’ (via ‘#define’ before including ‘iaws/aws.h’) removes from the API all methods dealing with ‘void*’, thus invocations of any such methods will result in compilation errors. Alternately, defining ‘AWS_DEPRECATE_VOIDP’, will cause invocations of methods dealing with ‘void*’ to generate compilation warnings, assuming that the compiler supports such deprecation warnings. (Presently, only modern version of the GNU compiler are so configured.)

This document was generated using texi2html 1.76.