C++ API

The ShiVa C++ API includes the entire Lua API as S3DX plus some specialized S3DClient functions. Its design and naming schemes are very similar to the Lua API, so you should feel at home quite soon.

There are 2 basic ways of interacting with the engine:
- "from the inside", with a C++ plugin, using the "S3DX" API, and
- "from the outside", with a C++ project, using the "S3DClient" API.

S3DX

The Runtime Lua API is the one that you will be dealing with most of the time when creating plugins, hooks and callbacks, and bridge functions between your own C++ code and the translated code ShiVa gives you upon export. The corresponding C++ API is called S3DX and can be used like the Lua API with "S3DX::" in front, as shown in the following snippet:

S3DX::AIVariable tStrings = S3DX::table.newInstance ( ) ;
S3DX::table.add ( tStrings, "foo" ) ;

The C++ runtime API is virtually identical in structure to the Lua runtime API. The entire reference can be found in S3DX/S3DXAIEngineAPI.h in any ShiVa C++ "Project" export:

// for example...
        struct MusicPackage
        {
            // Functions
            //
            inline void             play                                                ( const AIVariable& hScene, const AIVariable& nMusicIndex, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_03( hScene, nMusicIndex, nFadeTime ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.play ( 3, vIn, NULL ) ; }
            inline void             play                                                ( const AIVariable& hScene, const AIVariable& nMusicIndex, const AIVariable& nFadeTime, const AIVariable& nInitialProgress ) const { S3DX_DECLARE_VIN_04( hScene, nMusicIndex, nFadeTime, nInitialProgress ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.play ( 4, vIn, NULL ) ; }
            inline void             pause                                               ( const AIVariable& hScene, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_02( hScene, nFadeTime ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.pause ( 2, vIn, NULL ) ; }
            inline void             resume                                              ( const AIVariable& hScene, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_02( hScene, nFadeTime ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.resume ( 2, vIn, NULL ) ; }
            inline void             stop                                                ( const AIVariable& hScene, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_02( hScene, nFadeTime ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.stop ( 2, vIn, NULL ) ; }
            inline void             setVolume                                           ( const AIVariable& hScene, const AIVariable& nVolume, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_03( hScene, nVolume, nFadeTime ) ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.setVolume ( 3, vIn, NULL ) ; }
            inline AIVariable       getPlaybackProgress                                 ( const AIVariable& hScene ) const { S3DX_DECLARE_VIN_01( hScene ) ; AIVariable vOut ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.getPlaybackProgress ( 1, vIn, &vOut ) ; return vOut ; }
            inline AIVariable       playAdditional                                      ( const AIVariable& hScene, const AIVariable& nMusicName, const AIVariable& nFadeTime ) const { S3DX_DECLARE_VIN_03( hScene, nMusicName, nFadeTime ) ; AIVariable vOut ; S3DX_MODULE_GUID::__pS3DXEAPIMI->music.playAdditional ( 3, vIn, &vOut ) ; return vOut ; }
        } ;
//etc...

S3DClient

The S3DClient API offers additional functions for even more control over your application. This API also allows you to "go beyond" ShiVa and integrate the engine into other frameworks (QT, GTK, MFC, ...).

A detailed list of the S3DClient API can be found in S3DClient_Wrapper.h in any ShiVa C++ "Project" export:

//-----------------------------------------------------------------------------
//  API
//-----------------------------------------------------------------------------

extern "C" bool             S3DClient_Init                                          ( const char * _pWorkPath ) ;
extern "C" void             S3DClient_LoadPack                                      ( const char *_pLoadingPackPath, const char *_pPackPath, const char *_pConfigURI   ) ;
extern "C" void             S3DClient_DisplayOption                                 ( const char * _pOptionPackPath ) ;
extern "C" void             S3DClient_DisplayAbout                                  ( const char * _pOptionPackPath ) ;
extern "C" bool             S3DClient_RunOneFrame			                        ( ) ;
extern "C" void             S3DClient_Pause                                         ( bool _bPause ) ;
extern "C" void             S3DClient_Stop                                          ( ) ;
//etc....

S3DX::AIVariable

Our C++ API comes with its own variable type S3DX::AIVariable which is not compatible with the standard C++ types (char, string, int, etc.) - before you can exchange data between ShiVa and your C++ code, you must transform the types using the following methods:

// getters
(bool) .GetBooleanValue()
(void) .GetHandleValue()
(float32) .GetNumberValue()
(const char*) .GetStringValue()

//setters
.SetBooleanValue(bool _bValue)
.SetBooleanValue(const void* _bValue)
.SetNil()
.SetNumberValue(S3DX::float32_fValue)
.SetStringValue(const char* _pValue)

If you are unsure about the type of an AIVaribale, GetType and SetType are also available.