Director Article

This is the basic Lingo command that allows you to access external files:

member(whichCastMember).fileName = "fileName"

The filename is a cast member property, which you can use to test or specify a file pathname (absolute or relative) or a URL. Here's a few ways you might see it used in a script:

  -- relative pathname to the file:
  member(1, 1).fileName = "@:audio/startsound.mp3"
  -- URL to the file:
  member("StartUpImage").fileName =   "http://MyDomain.com/images/PictureOfTheDay.jpg"
  -- File is in same directory as Director movie:
  the fileName of member "SpotAnimation" = "LogoAnimation2.swf"

The core concept is quite simple. However, there are a few complicated techniques and issues associated with the efficient use of this command. This tutorial is designed to address some of these issues for you.

There's a lot to explain about the dynamic use of external media, and about external media in general. However, before we discuss this in-depth, let's begin with a simple kind of usage—a random image generator. The movie below, called "LuckyNumbers", contains a single linked bitmap member. A script—using the technique shown above—changes the filename of the default linked member to a random image from a list of ten JPEG files.

Creating the LuckyNumbers example
Now you'll build the sample movie above. There are a few steps involved in creating the number images that I'll leave to your creative license. The steps below assume that you are familiar with the Director MX workspace. (For a good overview of the new Director MX interface, check out this week's Director Extreme column).

1. First, create eleven JPEG images: one default image and ten images to represent the numbers zero through nine.
2. Next, create a project folder, with one subfolder called images to store the JPEG files. Name the JPEG files as shown below:

3. Open a new file in Director MX and save it in your project folder as luckynumbers.dir.
4. Import the default image, startup.jpg, as a linked cast member, as shown below:

5. Rename the imported member DynamicMember.
6. Drag the default image to the score and extend the resulting sprite out to frame 40.
7. Add the script below to your movie. The comments in the code describe what each code section does.
   
   global gImageList, gImageHistoryList
global gDynamicMember, gImagePath, gDefaultImagePath

on startMovie
  -- creating the list of images
  gImageList = []
  -- a way of populating the list with image file names
  repeat with x = 0 to 9
  add gImageList, x & ".jpg"
  end repeat
  -- duplicating the list to force a different image than
  -- the previously displayed image, in case of rewind
  gImageHistoryList = duplicate(gImageList)

  -- defining the member to change:
  gDynamicMember = member("DynamicMember",1)

  -- defining path to images:
  gImagePath = "@/images/"

  -- saving start up image:
  gDefaultImagePath = member(gDynamicMember).filename

end

on PickRandomImage
  -- if we have dispensed all of the images, reset the list to   original
  if gImageHistoryList.count = 0 then
  gImageHistoryList = duplicate(gImageList)
  end if
  -- counting everything in image list:
  tTotal = gImageHistoryList.count
  -- getting random number based on total in list:
  tRandomNumber = random(tTotal)
  -- pulling out the image file name:
  tImageFIleName = gImageHistoryList[tRandomNumber]

  --constructing path to image:
  tPathname = gImagePath & tImageFIleName

  -- setting the filename of the default cast member
  member(gDynamicMember).filename = tPathname

end

-- get called by rewind button:
on StartOver
  resetStartupImage
  go 1
end

on resetStartupImage
  member(gDynamicMember).filename = gDefaultImagePath
end


8. Finally, add markers, a "go marker(0)" loop back, and a rewind button.

Note: The sample file above plays well enough with Shockwave, but is unsuitable for the web for performance reasons. To use it in a public website, you should preload the images before resetting the filename.

Real-world application of this technique
Dynamically linked elements are perfect for a project that requires random access to a large batch of pre-existing media files. Projects along these lines might include a sound sample browser, a video kiosk, a photo or clip art library, or any project where you need to display media incrementally. Another example would be an application that asks users to specify which of their own media files to import and use.

Run-time versus authoring-time
Before diving into dynamic linking, let's define run-time versus authoring-time (or "during authoring"). Run-time refers your finished project running live on player outside of the authoring environment. Authoring-time refers to when you are editing and developing your project in the Director authoring tool.

Next, we have dynamic versus fixed. At authoring-time, you can import a linked file and it will show up in your cast library. You can then use it like any other imported cast member. Director does not import the file into the movie. It only stores the link (or the path to the file); the data remains external to your project. If this linked cast member remains unchanged, it is referred to as fixed. In other words, the path to the external file does not change while the movie plays. Dynamic refers to the ability to change a file link in order to access another file on the fly.

Dynamic media in Director MX versus Macromedia Flash MX
Macromedia Flash MX is the first version of Macromedia Flash to allow run-time linking to external media, but it still has a long way to go before it can match the Director support for multimedia file types. While Macromedia Flash MX can import and use a wide variety of media during authoring, Macromedia Flash Player can only use external MP3 files and non-progressive JPEG files (in addition to SWF files, of course). Director, on the other hand, can use all of the flavors at run-time: JPEG, GIF, PICT, BMP, PNG, PSD, MP3, AIF, WAV, MOV, AVI, Real media, SWF, DIR, DXR, DCR, as well as a variety of other file formats.

Advantages of dynamic linking
By default, when you import assets into your Director project, Director will embed them into the cast library (with one exception, because digital video files are always kept external). When you save your Director project as .dir file, Director writes a single file that contains all of your imported items.

Imagine how impractical it would be to import 600 MB of digital photos to your cast library. If you only changed a tiny piece of text, you would have to write 600 MB to the hard disk simply to save your movie. Tracking and archiving versions of your project over time would be a nightmare and the entire development process would slow to a crawl. It is best to keep vast quantities of media separate from your Director file.

One solution is to bring the media files into the cast library as linked cast members. The bulky media data stays separate from your Director movie, yet you gain convenient access to all the files in the cast library. However, there are problems with this approach. The performance cost of generating, maintaining, and displaying a large number of thumbnails in the cast could make authoring cumbersome.

A better plan would be to create new cast members on the fly and then link them to external media as needed. This technique will work for a large media library without reducing performance during authoring. It also works well in a situation when users may introduce their own files into the mix.

In my next tutorial, I'll cover some more advanced techniques for linking external media, including: creating new cast members on the fly, working with external SWF files, and using fileIO in projectors to allow users to import their own media.

Joe Sparks is an artist, animator, musician, and game designer. His work has garnered many industry awards, including New Media's Award of Excellence and Macworld Magazine's Game of the Year. Sparks is known for pioneering the multimedia games Spaceship Warlock and Total Distortion, and more recently, for his popular animation series Radiskull & Devil Doll.