Marmalade Concepts and Features

Can a single build of an app really target any device? How does this work?

Marmalade builds your app as a single code binary that can run on all supported platforms and devices. The machine code in this binary runs unmodified on every target device, giving you the confidence that exactly the same code is running everywhere.

The app binary is packaged with assets and a platform-dependent binary into the appropriate package format. For example, the same binary and assets will go into an IPA file for iOS and an APK for android. Icons, splash screens and other package features can be specified in the project's MKB file.

How do I handle differences between the devices, like screen resolution, etc?

The system APIs provide reflection for most device capabilities, for example an app can query the device's screen width using s3eSurfaceGetInt(S3E_SURFACE_WIDTH). Marmalade apps use these APIs to customise themselves for the device.

For more abstract device differences the app can combine custom settings with conditional blocks in the ICF file, for example:

[MyApp]<br />
{OS=ANDROID}<br />
StoreLink= <a href="http://market.android.com/<br">http://market.android.com/<br</a> />
{OS=IPHONE}<br />
StoreLink=<a href="http://itunes.apple.com/<br">http://itunes.apple.com/<br</a> />

This has the advantage that further variations can be added in future (often without even recompiling the app).

The s3eDeviceInfo example is useful for identifying device information quickly. It displays basic information about the device and can be easily edited to add more properties. Note that a deployment of any app using a Debug loader will also output basic device information at the start of trace files.

How do I debug on device?

One of the main aims of Marmalade is to minimize the requirement for on-device debugging, which is slower and less unreliable even on the best platforms. A fast, flexible and accurate desktop ARM emulator is included to allow debugging of the actual code that runs on device.

Generally, a debug version of the platform loader can be deployed that will output tracing. The exact method of retrieving this file depends on the platform.

Using Marmalade Mac, a fully native iOS build can be generated in XCode and debugged/profiled with the usual Apple tools.

Can I use native platform code in my app?

Yes, the EDK (Extensions Development Kit) allows developers to call native OS APIs from within their Marmalade apps. The EDK is currently supported for iOS, Android and Windows. There is further information on using the EDK in the documentation here.

Use of native OS APIs is also supported on Android through the JNI (Java Native Interface) S3E Extension. This allows you to include Java code for Android, either directly in the C++ source files of your Marmalade app, or by building and executing standard Java source files and assets. Due to the flexible nature of the MKB system, you can use it to define a project for the native Java part of the process if you wish - i.e. it will include .java files and build them into a .jar that can be used by your C++ app.

Can I use the standard POSIX APIS such as , ?

Yes, Marmalade supports large parts of the POSIX API and also the BSD socket API via . These are implemented via the underlying S3E APIs.

Do Marmalade apps leverage hardware-accelerated floating-point processing?

Yes, it is possible to create builds which use hardware enabled floating point support via the arm-fpu ICF setting, which is to be set as an MKB option. Note that a build prepared in this way will not run on devices with no FPU.

Internally Marmalade uses 1.3.12 fixed-point in all the IwGx, IwGraphics and IwAnim pipelines (positions, normals, colours, UVs). This approach is often preferable to floating point even if an FPU is available. For example, on the iPhone GPU the use of 16-bits per component is half the bandwidth compared to 32-bits per component used by float.

Floating point matrices can be used in the transform stack. Marmalade will soon add support for floating point streams and animations.

How can I fix my app to landscape or portrait aspect ratio?

The ICF setting [s3e] FixScreenOrientation can be used to fix the screen in a given aspect ratio. "1" means portrait and "2" means landscape. The landscape setting will allow either landscape setting based on the device's orientation. In future SDK versions, this may be expanded to allow specification of all 4 orientations explicitly.

Does Marmalade support internationalisation (for example: Japanese, Chinese, Korean,... characters)?

Marmalade does not include any support for switching strings/assets by language out of the box. Most common approaches will work fine.

Displaying non-Roman fonts can be achieved by using the IwGxFont module, which supports rendering of bitmap and TTF fonts, therefore supporting virtually any character set. Bitmap fonts are created using the Marmalade Studio Font Builder.

Note: Please be careful to save any text to be imported as a UTF-8 text file. (See the documentation of your editor on how to save files in this format)

Is Marmalade just for games?

No. Marmalade’s sweet spot is 'rich' apps, by which we mean any combination of: great graphics; audio processing; use of device APIs such as camera, GPS, and microphone; deep C/C++ codebase; or anything else that raises your app above the level of a simple mobile website wrapper. Marmalade's history is in games, so is used very widely in that particular industry.

Marmalade for iOS

Can I use Objective C or native iOS code in Marmalade apps?

Yes, you can code in Objective C and use iOS APIs inside your own custom "extensions" using the Extensions Development Kit (EDK). The EDK allows you to code in C++ and Objective C, using standard iOS or third party frameworks and libraries, and expose them to the app through a C interface. The EDK provides your app with a function to check the availability of the extension on the target device – if running on iOS, the function will return true, and you can then make calls into the extension functionality. The extension library is statically linked into the iOS version of your app at deployment time.

Do I need a Mac to build, deploy and submit iOS apps?

You can fully build, deploy and install standard Marmalade apps for iOS using a Windows PC, with no need for a Mac. This includes all stages of app signing for both development and app store submission (generating certificate requests, obtaining certificates/profiles, signing apps). However, a Mac is currently required to upload final app builds to the App Store due to the store's dependency on the Mac App Loader. This may be improved in a future release. A Mac is also required if you want to *build* EDK extensions for iOS. Note that a Mac is not required if you simply wish to include pre-compiled EDK extension libraries for iOS.

How does Marmalade handle the differing screen resolutions and capabilities of iOS devices?

By default Marmalade deploys apps in "universal" mode so that they will run in native screen resolution on both iPhone/iPods and on iPads. You can specify for apps to be iPad-only or to run in 320x480 standard iPhone resolution on iPad via deployment options. Retina screen (640x960) support for iPhone 4 or newer must be enabled using the iOSScaleFactor ICF setting, but apps using this setting will still run in the native resolution on other devices.

Functionality that is only available on some devices can be queried at runtime through the relevant API. Marmalade's low level S3E APIs are designed so that they can always be called on any device and will simply return an appropriate error value if not supported, rather than causing a crash or exception.

How can I debug my app on an iOS device?

Marmalade Mac supports native device debugging, with live console output, breakpoint and code step-though, using Xcode and the --iphone option. Launch the app's MKB from the command line with "--iphone" to create a native iOS Xcode project with full iOS debugging features. Note that the compiled app uses a special static library version of the iOS loader, which means it will differ from a normal Marmalade app in subtle ways and is NOT supported for App Store submission. --iphone mode is useful for profiling and fixing bugs in EDK extensions. It is more productive to do as much debugging as possible on the desktop in the Marmalade Simulator rather than on device. Use S3E's trace and error output functionality with the console log provided by Xcode on Mac or the iPhone Configuration Utility on Windows.

Why does my Marmalade iOS app fail App Store submission with a "...the signature was invalid..." error?

The likely cause is that the .mobileprovisioning file specified during deployment was not valid. For Distribution builds, a .mobileprovisioning file must be specified but the validity is only checked when installing to devices, not during the signing process. A common error is to include a profile that is linked to a Developer certificate rather than a Distribution one. Check the details of the profile in Xcode, the iPhone Configuration Utility or the iPhone Developer portal.

Apps Program

How much is the financial incentive for joining?

We will assess the app to determine the level of incentive.

Can I choose to retain the publishing rights for certain stores, for example Apple App Store and/or Google Play?

You can choose to retain the publishing rights to any stores when you accept the Apps Program agreement.

Do I need a license to port my app to Marmalade? How do I get it?

To do the initial work, if you don’t have a license, we provide you with one that allows you to port it but cannot be used commercially.

Once the app is accepted, you will receive a free Marmalade SDK license.

What if I already have a license?

As long as your app is accepted into the Apps Program, you will be able to choose whether to have an extra free license, or a 1 year extension to your existing one.

Why are you doing this? What’s the catch?

There is no catch! The Apps Program has been devised as a tool to grow the Marmalade community by maximising revenues for our developers while taking the distribution burden off them. We monetise the apps through direct distribution to as many channels as possible, as well as exclusive OEM projects. We work with clients like RIM, Samsung and LG to provide quality content for their platforms and we are able to negotiate preferential placements and/or additional incentives in order to do so. This, in turn, increases the value of the whole Marmalade proposition, so it’s a win-win situation!

What are the criteria for being part of the Apps Program? How are the apps rated?

The Marmalade Content Team reviews apps internally and evaluates their quality, potential and track record, while looking to constantly grow the quality of our catalogue. For obvious reasons not all apps can be accepted into the Apps Program, only the very best of the crop will be selected. If you app is not accepted into the Apps Program, do not give up! Work on improving you app or submit to us your next creation, we would love to see you join our Apps Program with your best apps!

How do I submit my app?

Once the app has been ported to Marmalade, we will put it through our own internal QA and then work closely with you in the distribution of the app and in its monetisation..

What if I decide I no longer want to be part of the program?

The Apps Program Terms & Conditions specify the termination options.

I understand that I retain the intellectual property rights, but will Marmalade be the name people see as ‘Publisher’ or can it be in my company’s name?

The Publisher’s name will be Marmalade and we will be the publisher for any platform that is not excluded in the agreement. This means that we will communicate with OEMs, submit your app(s), dealing with rejections, manage the channels marketing, etc.

You will be named as the Developer.

Where do I go to for technical support?

You will receive access to our dedicated support team.

How do I get a phone so I can test my apps?

We will aim to provide you with a loan device whenever possible.