Code Compatibility with Prior Versions

The Scaleform 4 API is straightforward and easy to use. In general, developers should not have a problem getting comfortable with it, whether they are new or current Scaleform users. For current Scaleform users, with pre-existing Scaleform code (written using the Scaleform 3.x SDK), converting their code to the Scaleform 4 API is a relatively routine process. However, the migration process will likely require going through existing Scaleform code, modifying includes, utilizing the new Scaleform 4 namespaces, and changing types where necessary. In some cases, class functions and members have been changed from Scaleform 3.x to be more consistent with Scaleform 4 coding standards. For more information on the typical Scaleform integration process and details on getting started on specific platforms, please see Getting Started with Scaleform.

For most Scaleform code, upgrading to Scaleform 4 is generally just a matter of making minor modifications to existing code to utilize namespaces and convert to new class and type names. The exception to this is rendering code, which is entirely new in Scaleform 4 and has been completely rewritten to provide high performance, multi-threaded display. Developers using the default Scaleform renderers will not have to worry about this, and we recommend that approach unless absolutely necessary.

In Scaleform 3.x, custom renderers were often required to interface with multi-threaded engines or to support game specific texture needs. In Scaleform 4, the renderer is designed to integrate easily with multi-threaded engines and the texture manager can easily be overridden, so it is usually not necessary to create a custom renderer in Scaleform 4. For more details on the new Scaleform renderer and its multi-threaded design, please see the document “Scaleform 4 Renderer Guide” in the documentation section.

Scaleform 4 includes a compatibility header file (Include/GFxCompat.h) which automatically translates most class names, types and defines from Scaleform 3.x syntax to Scaleform 4. The compatibility header uses typedefs, enums and defines to account for most of the changes needed to go from Scaleform 3.X code to Scaleform 4. This provides the fastest route for developers with pre-existing code who want to quickly get up and running with Scaleform 4. On the other hand, keep in mind that code relying on the compatibility header will differ from the Scaleform 4 documentation as well as potentially from new code that is introduced.

An example which uses the compatibility header is Apps/Demos/GFxPlayerTiny/GFxPlayerTinyD3D9Compat.cpp.

Although GFxCompat.h does a lot of the work of getting your old code to run in Scaleform 4, there is still some new code that needs to be added. In general, there are a few states new to Scaleform 4 that need to be set on the GFx Loader: FontProvider, and AS2Support and/or AS3Support. This is fairly simple to do, for example:

// Set Font Provider:
Ptr<FontProviderWin32> fontProvider = *new FontProviderWin32(::GetDC(0));
loader.SetFontProvider(fontProvider);

// Add AS2 Support:
Ptr<ASSupport> pAS2Support = *new GFx::AS2Support();
loader.SetAS2Support(pAS2Support);

// Add AS3 Support:
Ptr<ASSupport> pASSupport = *new GFx::AS3Support();
loader.SetAS3Support(pASSupport);

To better illustrate the process of converting your code, let’s consider some of the areas which have changed from Scaleform 3.x to Scaleform 4 along with suggestions for how to upgrade. Many of these issues are already handled by the GFxCompat.h compatibility header.

Header Files

Since header files are going to be different when migrating from Scaleform 3.x to version 4, the simplest approach is to include the typical Scaleform 4 convenience headers to start with. For example,

    #include "GFx_Kernel.h"
    #include "GFx.h"
    #include "GFx_Renderer_D3D9.h"  // or whatever platform you need

In case the convenience headers (GFx.h) are not included, if you are using AS3, make sure to directly include the mandatory AS3 class registration file “GFx/AS3/AS3_Global.h” in your application. Developers can customize this file to exclude unneeded AS3 classes.

AS3_Global.h and Obj\AS3_Obj_Global.xxx files

Developers must note that AS3_Global.h and Obj\AS3_Obj_global.xxx are completely unrelated files.

AS3_Obj_Global.xxx files contain implementation of so called "global" ActionScript 3 objects. Every swf file contains at least one object called "script", which is a global object. There is also a class GlobalObjectCPP, which is a global object for all classes implemented in C++. This is specific to the Scaleform VM implementation.

AS3_Global.h has a completely different purpose. This file contains the ClassRegistrationTable array. The purpose of this array is to reference C++ classes implementing corresponding AS3 classes. Without this reference, code will be excluded by a linker. So, ClassRegistrationTable has to be defined in your executable, otherwise you will get a linker error. Each of our demo players includes AS3_Global.h for this reason.

The whole purpose of putting the ClassRegistrationTable into an include file and requiring developers to include it, is to allow customization of the ClassRegistrationTable (for the purpose of potential code size reduction). The best way to do that is to make a copy of AS3_Global.h, comment out un-needed classes (after which they will not be linked in), and include the customized version into your app.

However, there is a catch related to this optimization. Because name resolution in the AS3 VM happens at run-time, it is possible that a needed class will not be found if commented out of the table. So, if you want to get rid of "unnecessary" classes, please make sure that your app is functional after that.

Defines

Defines are similar from 3.X to 4, but the GFC prefix is no longer used. System defines use SF_ and Scaleform related defines now use GFX_ as prefixes. For example:

Scaleform 3.X	Scaleform 4
GFC_FX_VERSION_STRING	GFX_VERSION_STRING
GUNUSED	SF_UNUSED
GFC_64BIT_POINTERS	SF_64BIT_POINTERS

Namespaces

Since the use of namespaces was introduced in Scaleform 4, identifiers now need to be referenced using either fully qualified names, such as Scaleform::GFx::Event, or the ‘using namespace’ statement, which specifies that the names in the namespace can be used in the scope where the using directive occurs. As long as no name collisions occur, the easiest way to deal with namespaces is to declare the common ones at the top of your cpp files, such as:

namespace SF = Scaleform;
using namespace Scaleform;
using namespace Render;
using namespace GFx;

Types and Classes

Basic types have generally become simpler in Scaleform 4, so previously used type aliases can now be replaced with native types.

|Scaleform 3.X| Scaleform 4| |---------|-------| |UInt| Unsigned| |SInt| Int| |Float | Float| …

The common Scaleform class types still exist in Scaleform 4 but are named slightly differently since namespaces are in use. For example, in Scaleform 3.x you may utilize a class called GFxEvent, whereas in Scaleform 4 that same class would be called GFx::Event. Here are some examples of the names of common classes in Scaleform 3.3 and their counterparts in Scaleform 4

Code Compatibility with Prior Versions

Header Files

Defines

Namespaces

Types and Classes

Parent topic