C.6.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:

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.)