Developing applications with Macromedia Director you may face the necessity
of image input from devices like scanners or digital cameras. There are
a lot of reasons for this. You may need to allow user's image input so
your customers are able to acquire images, modify them right in your application,
print them and save the result. Practically all virtual make over CD titles
require image acquisition functionality and there's an infinite number
of subjects to change - from architectural objects to hair styles. This
way users can create digital photo archives, share their creations with
friends by email or uploading to a web site, etc. Placing custom images
to Director's digital world allows your applications a new level of interactivity
and functionality. In this article we will examine for possible solutions
and try to find the answer on "How to?" question.
TWAIN is an Application Programming Interface (API) that standardizes
communication between applications and image acquisition devices such
as scanners or digital cameras. It allows to make standard calls to
any image acquisition device that supports TWAIN interface so the application
would not have to be rewritten to support every single device. You can
find more information about TWAIN at http://www.twain.org
TWAIN exists since 1992 and most of modern scanners and digital cameras
support it. Epson PhotoPC 800 and Canon PowerShot S60 cameras are to
name a few.
Director doesn't support TWAIN interface by itself, and image acquisition
functionality is possible with third party extensions only. Macromedia
Director works with two types of third party extensions: Xtras and ActiveX
controls (for Windows only). So, lets get our review started.
You can find a few Twain ActiveX Controls available on the market.
In this article we will not examine how to handle them in Director
since there's a common approach for using AciveX controls. We believe
you know how to install and use ActiveX Controls on Windows. Here
is a brief description just to give you an idea:
1. Copy the .ocx file to the Windows System folder.
2. Run the following command:
REGSVR32.EXE /s YOURCONTROL.OCX
REGSVR32.EXE also should be in the Windows System folder, check if
it's there before running it.
To insert ActiveX Control in Director select Insert > Controls >
ActiveX menu and then just drag the appropriate cast member to the stage.
Feel free to resize the sprite on the stage as you need.
Each ActiveX control has its own methods, properties and events, refer
to the documentation supplied with the control to learn more on the stuff
provided by the control. You can also find the comprehensive help on using
ActiveX controls in Director's manual.
ActiveX approach to image acquisition in Director has some limitations,
it allows to get the acquired image inside an ActiveX object which
is not a Director bitmap cast member. You can display the acquired
image on stage but no more than this. Twain Xtra is a more flexible
solution because you get a full-featured bitmap cast member to:
- modify with imagine lingo;
- crop, rotate, resize and scale;
- apply a mask;
- set the ink of sprite property for a bitmap sprite;
- use as a texture for a 3D object;
- save to image file on user's HDD;
- upload to server and much more...
The Demo version of Twain
Xtra is fully functional in Director authoring mode so you may use it
for direct image acquisition to Director saving a few steps. The demo
version is supplied with a comprehensive documentation and the demo movie.
Here we will give you some basic ideas but that's not a replacement for
the documentation and the demo movie so you're strongly recommended to
read the documentation and try the demo movie before using the Xtra.
Before working with TWAIN interface the Xtra must be initialized. The
"on startMovie" handler is a good place for things like that:
Result = TwainInit()
Initialization allocates some memory for TWAIN engine, so, when
user quits the application it should be set free. To do so we
need to uninitialize TWAIN and the "on stopMovie" handler
is exactly what we need:
Result = TwainUninit()
You can initialize and uninitialize
the Xtra anywhere in your movie, there are no any restrictions or limitations.
Of course, it's not a good idea to call those functions in a frame script's
handler like "on exitFrame" that's being called a few times
a second. Initialize the Xtra only once before image acquisition session
started and uninitialize after it's been completed. After the Xtra has
been initialized image acquisition can be performed. It's possible to
connect one or more TWAIN compliant devices to a computer, they could
be a scanner plus a digital camera. TWAIN needs user input to define which
device is selected for image acquisition and the "Select Twain Source"
dialog was designed specifically for that purpose.
With the TwainShowSelectDlg() function you can display the dialog
to get user's input. Place this code to the "on mouseDown"
event for the "Select Twain Source" button:
set Result = TwainShowSelectDlg()
if count(Result) = 3 then
set TwainSource = getAt(Result,3)
set TwainSource = ""
function displays the standard device Select Twain Source dialog. This
dialog comprises a list of available devices with two buttons: Select
and Cancel. The function returns a list, the third element of the list
is a string which is the name of the selected Twain Source, we put it
to the global variable TwainSource. TwainSource is not the exact device
name, usually it's just a contracted name or some combination of the name
and abbreviation. It may be something like "FV950_32 v 1.24"
where FV950 is the model name. If user selected some device from the list
and clicked on the "Select" button then the TwainSource variable
would be equal to the selected device name, if user clicked on the "Cancel"
button then the TwainSource variable would be an empty string.
After the source has been selected user can start scanning. That's
what we put to the "on mouseDown" handler for the "Scan
if TwainSource <> ""
set ShowUI = true
set NumberOfImages = 1
set CastMember = member 11
set CallbackHandler = "finishScan"
set Result = TwainAcquireImage(TwainSource,
ShowUI, NumberOfImages, CastMember, CallbackHandler)
TwainAcquireImage() function has five parameters:
- TwainSource - a string with a name of the TWAIN source.
This variable was set when user clicked on the "Select Twain
- ShowUI - boolean to indicate if device specific user interface
should be visible or not. Every device has its own acquisition dialog
that allows to adjust some settings like brightness, contrast, RGB
settings, cropping etc. Note, not all devices allow to adjust this
setting, it completely depends on specific device driver.
- NumberOfImages - number of images to capture during the current
acquisition session. Most digital cameras allow to acquire more than
one image per session. You can set this parameter to -1 to acquire
as many images as the source can provide.
- CastMember - reference to a bitmap or an empty cast member
where the first acquired image will be allocated.
- CallbackHandler - the name of the callback handler. Callback
handler is a movie script handler that will be invoked when acquisition
Callback Handler should look like this:
on finishScan nImage
-- scanning process has been finished
-- do something here
is the number
of images that were actually acquired. User may select 20 images for acquisition
but if the camera had just 15 ones, only 15 cast members would be filled
with images. So, it's just to inform on how many cast members were filled/created.
Please, avoid calling any Twain Xtra functions in the callback handler.
As you may have noticed, it's pretty easy to implement seamless image
acquisition to your Director application - all you need is just to handle
a few functions. For reference:
- TwainInit(), TwainUninit()
- initailization and deinitailization of Twain Xtra (starting
and stopping TWAIN engine);
- TwainShowSelectDlg() - allows user to select twain source;
- TwainAcquireImage(TwainSource, ShowUI, NumberOfImages,
CastMember, CallbackHandler) - acquire image to cast member(s).
That's it, good luck!
On March 1, 2004 we released Twain Xtra version 2.0.
That was a major update since version 1.1 released in March, 2002.
Twain scanning engine was completely redesigned to make the Xtra
compatible with a wider range of TWAIN compliant devices. Besides,
we released a completely new product - Twain Xtra 2.0 Professional
Edition that brought the power of TWAIN 1.9 specification capabilities
Last revised: March 30, 2005