News    Faq    Status    Downloads    Translation guide      

Translation Guide:


Because Dxbx is primarily focussed on translating Cxbx to the Delphi Language,
we need to maintain a proper set of rules. One problem in translating Cxbx is,
that there are various branches to choose from;
\Cxbx\Trunk . The main source
\Cxbx\branches\private\caustik - Caustic's private work branch
\Cxbx\branches\private\dstien, Based on martin rev. 39 - Nisse's work
\Cxbx\branches\private\martin - Martin's work
\Cxbx\branches\private\shogun - blueshogun96's work

Most of the translation work has used martin's branch. But now that there
are more branches to choose from (namely dstien and shogun), we need to mark
our translations with a header, signifying which branch and revistion where
used when translating a function. Also, update these headers when another
revision comes along!

So, add this header line to each function you translate (with applicable details):
// Branch:martin Revision:39 Translator:PatrickvL

For kernel functions, also specifiy which source was used to determine the
signature of that function, like this :
// Source: OpenXdk
Sources are: Cxbx, OpenXdk, XBMC, ReactOS, APILogger (See below for details).

Calling conventions
-------------------
Calling conventions should be translated as follows :

WINAPI and NTAPI -> stdcall (see http://www.nynaeve.net/?p=42)
__fastcall -> register


Adding patches
--------------
Every time you want to enable a new patch on some function, do the following:

Determine from which Xbox SDK library the function originates, and arrange for
pattern (.pat) files for this library, from as much SDK's as possible.

(If you don't have any SDK, or don't know how to create a .pat file,
contact one of our developers - we might be able to help you out.

Please note, that We can't give you an SDK or the pattern-generation tools,
as these are proprietary software!)

With these .pat files, run PatternTrieBuilder.exe to get an updated version
of the data structure (StoredTrie.dpt) that Dxbx uses to detect functions.
(When compiling the DxbxKrnl.DLL project, this data is linked into the DLL.)
So now, when you run your game, you should see your function being detected,
as mentioned in the log like this :

DxbxHLE : Detected at $00011000 : 'SomeFunction'

Now that Dxbx can detect the function, implement your patch (don't forget to
declare it with the correct arguments and "stdcall" calling convention).

To register it, scroll down to the 'exports' section of the unit where you're
implementing the patch (create one if it's not there yet - look in another
unit, like uEmuD8D.pas, for an example of how this should look).
Add a line that reads (replacing both 'SomeFunction's with your patch) :

EmuSomeFunction name PatchPrefix + 'SomeFunction',

If you followed these steps and made no mistakes, DxbxKrnl.DLL will keep
compiling just fine; But now when running your game, you should see a log
line mentioning that your patch was applied to some address in the game!
This goes fully automatic; To verify, check the log for a line like this :

DxbxHLE : Installed patched from $00204080 (SomeFuntion) to $100ABCDE

The addresses will be different, but the name should match your new patch.



CToPas
------
CToPas is a tool that can help you translating C code to Delphi.
It does this by executing a number of automated replacements, so that C code
starts to resemble Delphi code. This is no reliable translation however,
so to get functionally equivalent code, manual changes are also needed.

When using CToPas, be aware of these syntaxis that might need to be reversed:
" mod " -> "%" (inside strings)
" not " -> "!" (inside strings)


Operators
---------
Converting C/C++ operators to Delphi:
-= operator

var1 -= var2;
{ this equates to: }
var1 := var1 - var2;


+= operator

var1 += var2;
{ this equates to: }
var1 := var1 + var2;


&= operator

var1 &= var2;
{ this equates to: }
var1 := var1 AND var2;


|= operator

var1 |= var2;
{ this equates to: }
var1 := var1 OR var2;


*= operator

var1 *= var2;
{ this equates to: }
var1 := var1 * var2;


Pointer translation
-------------------

C/C++

*variabele = value;
PDWord *pSampleValue;

Delphi

variabele^ := value;
pSampleValue : PDWord;


Xbox Kernel sources
-------------------
Additional sources that can give you more insight into the Xbox Kernel API's :

APILogger - APIReporter source :
http://forums.xbox-scene.com/index.php?showtopic=456303

Cxbx SVN (dstein and shogun's private branches are the most up to date) :
http://cxbx.svn.sourceforge.net/viewvc/cxbx/branches/private/dstien/wip/src/
http://cxbx.svn.sourceforge.net/viewvc/cxbx/branches/private/shogun/wip/src/

JwaNative - Jedi WinAPI project :
http://blog.delphi-jedi.net/jedi-api-headers/

OpenXDK - Open Source, Free Legal Xbox Development Kit :
http://sourceforge.net/projects/openxdk/

ReactOS SVN - Open source windows NT clone, see it's kernel implementation :
http://svn.reactos.org/svn/reactos/trunk/reactos/ntoskrnl/

XBMC - See the xbox folder, and especially Undocumented.h :
http://xbmc.org/trac/browser/trunk/XBMC/xbmc/xbox