Director 12 XDK Readme

Introduction

This release of the Xtra Development Kit (XDK) is for use in developing Xtras for Adobe Director 12. The Macintosh XDK has been updated to support Mach-O universal binary Xtras and the Xcode development environment. The XDK has been updated for the latest release of Director and does not support building Xtras that run on older Director versions. A complete list of all additions and changes made since the Director MX 2004 XDK can be found in the XDK updates file.

This XDK provides resources for developing extensions to Director, including Sprite Xtras, Transition Xtras, Scripting Xtras, Filter Xtras and Tool Xtras. Documentation files in HTML format and several example Xtras are provided as part of this release. A descriptive index of the example Xtras is provided in XDK Examples document.

Table of folders included in the XDK

Xtra Development Environments

Windows

The compiler currently supported for developing Xtras for Windows is Microsoft Visual C++ version 7.0 (MSVC 2003). The workspace files are now in VC7 format.

To build an example Xtra, open one of the example .sln files in Microsoft Visual C++ (e.g. XDK\Examples\Sprite\Oval\winproj\Oval.sln). Choose Build Solution from the Build menu. The compiler will create the Oval.x32 shared library in the XDK\Examples\debug\ directory. If you set the project to make a Release version, the compiled Xtra will be put in XDK\Examples\release\.

To make an Xtra that uses MFC you will need to modify the file include\win32\moatyedg.h. Add an #ifndef _USRDLL around the DllMain() function in the _MOA_XCODE_PREFACE section to disable it if _USRDLL is defined (this is a standard MFC #define). So the _MOA_XCODE_PREFACE is reduced to just declaring gXtraFileRef if you're using MFC. MFC developers also need to set the value of gXtraFileRef somewhere else. You may want to do this in an early MoaCreate() call like so:
gXtraFileRef = AfxGetInstanceHandle();

Debugging Windows Xtras

1. Open Visual C++ and build the Debug target for the project, as described above (i.e. the Oval project).
2. Copy a shortcut to the Debug version of the Xtra (i.e. XDK\Examples\debug\OvalSprite.x32) into the
   C:\Program Files\Adobe\Adobe Director 12\Configuration\Xtras\ folder.
3. In Visual C++, shoose the Properties item from the Project menu.
4. Select the Debugging item in the left panel.
5. Use the Browse... item for the Command text field to fill in the path to Director (or a projector). For example,
   C:\Program Files\Adobe\Adobe Director 12\Director.exe
6. Set breakpoint(s) in one of your source files.
7. Choose Start from the Debug menu.

Macintosh

This version of the XDK has been updated to support Xtra development using Apple Computer Inc's Xcode, and the Mach-O object format. The XDK supports Universal Binary format or processor specific xtras. There is not a way to use older CFM xtras with Mach-O executables, or to use the Mach-O xtras with the older CFM executables. The Mach-O xtra format is a Bundle. Xtra bundles can still store resources in resource files; all of the Adobe Example Xtras are using data fork resource files for this purpose.

The new Xtra projects have been setup for development with Xcode version 2.4 and later. The minimum required operating system is 10.4.

When porting xtras to the Intel Processor macintosh, the most common area that needed attention was the format of data such as castmember data. Older xtras assumed Windows was the same as __LITTLE_ENDIAN__ and Macintosh was the same as __BIG_ENDIAN__. Since xtra castmember file data needs to be stored in a common format with both bit storage approaches, translation is needed for some data types. Each of the sample xtras in the XDK that write out some castmember data needed to have a small code change to deal with this issue.

To build an example Xtra, open one of the example .xcodeproj files in Xcode (e.g. XDK/Examples/Sprite/Oval/macproj/OvalSprite.xcodeproj). Choose Build from the Build menu. The compiler will create the OvalSprite.xtra bundle in the XDK/Examples/build/Release/ directory. If you set the project to make a debug version, a debug version of the compiled Xtra will be put in XDK/Examples/build/Debug/.

The Macintosh example projects have been setup with xcconfig files controlling the project settings. Each project has a Debug and Release configuration defined - the Release project builds a Universal binary with both ppc and i386 architectures. To change the name of the Macintosh Xtra that will be built by a project, edit the common.xcconfig file for the project and change the value assigned to PRODUCT_NAME. Ths value gets used by the linker and also gets stored in the info.plist file for the Xtra bundle.

Debugging Macintosh Xtras

1. Open Xcode and build the Debug target for the project, as described above (i.e. the OvalSprite project).
2. Create an alias to the Debug version of the Xtra (i.e. XDK/Examples/build/Debug/OvalSprite.xtra and copy it into the /Applications/Adobe Director 12/Configuration/Xtras/ folder. For Shockwave debugging you can put the alias here: ~/Application Support/Adobe/Shockwave Player 12/Xtras/
3. In Xcode, choose New Custom Executable... from the Project menu.
4. Use the Choose button to browse the file system and fill in the path to Director (or a projector or Safari) in the Executable Path text field.
5. Debugging Tip: Use the Debug/Tools/Shared Libraries... menu item and set the User Libraries pop-up to All. This will ensure that your debug information gets loaded when the application is launched. You may need clear all items from the Module list if it has stale information.
6. Set breakpoint(s) in one of your source files.
7. From the Debug menu, choose Debug Executable.
8. Director will launch, and your breakpoint should get hit.
9. Debugging Tip: With Xcode, when the host application does not have debugging code, stepping over function calls in your xtra sometimes just does not work. You may end up looking at some assembly language code instead of being on the next line of your source. You may have better luck by adding a temporary breakpoint on the next line of code you want to stop at.

iOS

This version of the XDK has been updated to support Xtra development using Apple Computer Inc.'s Xcode, for iOS.

The new Xtra projects have been setup for development with Xcode version 4.3 and later. The minimum supported operating system version is 10.7.

Unlike the xtras on other platforms, iOS xtras are going to be static libraries. This is because iOS does not support dynamically loaded libraries/frameworks. Shockwave runtime is also provided as a static library(libOtto.a) in the lib/iOS folder of XDK. Only C++ xtras are supported on iOS. When you get duplicate symbol linker error, change the names in your xtra. Better to use namespaces to avoid name collisions.

There are three specific code snippet additions required for your iOS xtras to be registered.

All the above changes are provided for the sample xtras and you can go through them by searching for '@IOS_XDK_CHANGE' in the 'AllExamples_ios.xcodeproject'

To build the example Xtras, open the AllExamples_ios.xcodeproject in Xcode (e.g. XDK/Examples/AllExamples_ios.xcodeproject). Choose Build from the Product menu. The compiler will create the Otto.app bundle in the XDK/Examples/build/Debug-iphoneos/ directory. If you set the project to make a release version, a release version of the 'Otto.app' with the xtras linked will be put in XDK/Examples/build/Release-iphoneos/.

The iOS example projects have been setup with xcconfig files controlling the project settings. Each project has a Debug and Release configuration defined - the Release project builds a binary with armv7 architecture. To change the name of the iOS Xtra that will be built by a project, edit the common.xcconfig file for the project and change the value assigned to PRODUCT_NAME

Debugging iOS Xtras

1. You cannot debug the iOS xtras in Director authoring environment. You need to run it as iOS projector only.
2. Open Xcode and under the 'AllExamples_ios' project expand the Movies group and add the dir/dcr file using which you want to debug your xtra. After adding the dir/dcr in the Resources group make sure its 'Target Membership'(in the utilities pane on the right side) is set to Otto. This will copy the movie file to the final app folder immediately after the build. Under the Resources group, open the otto.ini and modify the [Movies] section with the proper movie name that you just added.Keep the 'Otto.app/' intact and append your movie name to it. build the Debug target for the project, as described above (i.e. the OvalSprite project).
3. Set breakpoint(s) in one of your source files.
4. After connecting iOS device to your mac, in XCode choose 'Otto' as the target and click on the 'Run' button
5. iOS Projector(Otto) will launch on your device, and your breakpoint should get hit.
6. Debugging Tip: With Xcode, when the host application does not have debugging code, stepping over function calls in your xtra sometimes just does not work. You may end up looking at some assembly language code instead of being on the next line of your source. You may have better luck by adding a temporary breakpoint on the next line of code you want to stop at.

Delivering iOS xtras to users

Single Xtra developer can build the otto.app with all his xtras included and release it to the user. User needs to copy it to "Configuration/Projector iOS Resources" folder and follow the regular iOS publishing workflow. In this case, please make sure user backs up the original otto.app that comes by default with Director

If the xtras are coming from different developers, following steps need to be followed.

1. The xtra developers need to share their xtra static libs with the user.
2. User will add the static libs in the otto.xcodeproject(provided in the XDK), add xtra registration entries(one liners i.e CALL_REGISTER_XTRAS(<XtraName>_) for each xtra as mentioned above) in the ottomain.cpp file
3. User will build the xcodeproject to generate the otto.app and copy it to "Configuration/Projector iOS Resources" and follow the regular iOS publishing workflow.

Xtra Developers Support

This XDK is provided as is, without support from Adobe.

Additional Sources of Information

- General MOA information is in "MOA Development Issues" the MOA Developer's Guide.
- Useful tips are in "Tips, Guidelines, and Gotchas" in the Multimedia Developer's Guide.
- For the latest news, online docs, and FAQs about Xtras, surf to the Xtra Developers Center at http://www.adobe.com/support/xtras.