|
Developed by Tomer Berda, DirectXtras Inc. (C) Copyright 1997-2004.
Last updated: August 24th, 2004.
DirectImage (formerly
known as DirectXport) is a
cross-platform, easy to use Scripting Xtra for Macromedia Director,
Authorware and
Shockwave that provides applications with the ability to create, export, import,
capture
and manipulate images.
Using DirectImage
Xtra, Director, Authorware and
Shockwave applications can
perform the following tasks through scripting:
-
Export Director image
cast members, lingo image objects, the Director stage or Authorware display icons into various image file formats, including JPEG, GIF, TIFF, BMP, PICT,
PSD, animated GIF and many more.
-
Import image files into
Director image cast members or lingo image objects. The Xtra can read from more than 30 different image file
formats.
-
Perform a screen capture into a Director image cast member or file.
-
Convert an image from
one format to another.
-
Change the color depth of an image to 1, 2, 4, 8, 16 or 32
bits with palette remapping and dithering support.
-
Resize, scale, magnify and minify images.
-
Flip, flop, roll, chop, crop and shave images.
-
Rotate and shear images.
-
Perform image processing effects: blur,
sharpen, oil paint, charcoal paint,
implode,
explode, motion blur, morph, shade, spread,
swirl, wave, raise, edge , emboss, solarize and
more.
-
Perform image processing enhancements: contrast, modulate, reduce
noise, normalize and more.
-
Get and set the image pixels and background color.
-
Get and set the image resolution, compression type and colorspace.
-
Store application specific data as part of the image.
-
Retrieve the EXIF and IPTC information associated with
imported images.
-
Access and manipulate image frames \ layers.
-
Flatten or coalesce images with multiple frames \ layers.
-
Set the image transparency.
DirectImage Xtra was
designed in a way that it can easily be used in conjunction with our other
Director and Authorware Xtras :
-
Director image cast members or Authorware display icons can be sent via e-mail as file attachments using our DirectEmail
Xtra.
-
Image files can be
imported from an FTP server using our DirectFTP
Xtra, and Director image
cast members or Authorware display icons can be exported to image files on the server.
-
A Director image cast member or an Authorware display icon can
be set as the desktop wallpaper using our DirectOS
Xtra.
-
Applications can use DirectOS
Xtra to manipulate open windows prior to capturing the screen using DirectImage Xtra.
For example, all open windows can be minimized in order to capture the
desktop image.
DirectImage
Xtra is Shockwave safe, so it can also be used with Shockwave 7 and above and when
Director safety features are turned on.
When the Xtra is in safe mode it can import and export image files through
a built-in
file selection dialog box from/to anywhere on the local machine,
or
directly from/to the Shockwave support folder (dswMedia
folder) or any other local dswMedia folder without displaying a dialog box.
An auto downloadable Shockwave safe package of DirectImage
Xtra is also
available. It is a compressed (600K - 800K) version of the Xtra that can be downloaded
automatically
from a web site to the user's local machine whenever needed, and once
installed provides Shockwave applications on the web with the advanced imaging capabilities
that the Xtra provides.
DirectImage
Xtra supports the following file formats :
|
Format |
Description |
Mode |
| AVI |
Microsoft Audio/Visual
Interleaved |
Import |
|
AVS |
AVS X image |
Import & Export |
|
BMP |
Microsoft Windows bitmap |
Import & Export |
|
DCX |
ZSoft IBM PC multi-page Paintbrush
image |
Import & Export |
|
DIB |
Microsoft Windows Device
Independent Bitmap |
Import & Export |
|
DPX |
Digital Moving Picture
Exchange |
Import & Export |
|
EPDF |
Encapsulated Portable Document Format |
Export |
|
EPS |
Adobe Encapsulated PostScript |
Export |
|
EPS2 |
Adobe Level II Encapsulated PostScript |
Export |
|
EPS3 |
Adobe Level III Encapsulated PostScript |
Export |
|
FAX |
Group 3 TIFF |
Import & Export |
|
FITS |
Flexible Image Transport System |
Import & Export |
|
FPX |
FlashPix Format |
Import & Export |
|
GIF |
CompuServe Graphics Interchange Format |
Import & Export |
|
HTML |
Hypertext Markup Language with a
client-side image map |
Export |
|
ICO |
Microsoft icon |
Import |
|
JBIG |
Joint Bi-level Image experts Group file
interchange format |
Import & Export |
|
JP2 |
JPEG-2000 JP2 File Format Syntax |
Import & Export |
|
JPC |
JPEG-2000 Code Stream Syntax |
Import & Export |
|
JPEG |
Joint Photographic Experts Group JFIF
format |
Import & Export |
|
MIFF |
Magick image file format |
Import & Export |
|
MNG |
Multiple-image Network Graphics |
Import & Export |
|
PBM |
Portable bitmap format (black and
white) |
Import & Export |
|
PCD |
Photo CD |
Import & Export |
|
PCDS |
Photo CD with sRGB color tables |
Import & Export |
|
PCX |
ZSoft IBM PC Paintbrush file |
Import & Export |
|
PDF |
Portable Document Format |
Export |
|
PICT |
Apple Macintosh QuickDraw/PICT file |
Import & Export |
|
PNG |
Portable Network Graphics |
Import & Export |
|
PS |
Adobe PostScript file |
Export |
|
PS2 |
Adobe Level II PostScript file |
Export |
|
PS3 |
Adobe Level III PostScript file |
Export |
|
PSD |
Adobe Photoshop bitmap file |
Import & Export |
|
RLE |
Utah Run length encoded image file |
Import & Export |
|
SGI |
Irix RGB image |
Import & Export |
|
SUN |
Sun Rasterfile |
Import & Export |
|
TGA |
Truevision Targa image |
Import & Export |
|
TIFF |
Tagged Image File Format |
Import & Export |
|
TXT |
Raw text file |
Import & Export |
|
WBMP |
Wireless bitmap |
Import & Export |
|
WMF |
Windows Metafile |
Import |
The Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with
Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8, 9
and X.
Installation
Registration
Overview
Using DirectImage Xtra
Functions Reference
Methods to create and dispose an image:
New()
Forget()
Methods to load and save an image:
imageLoadFromFile()
imageLoadFromMember()
imageLoadFromScreen()
imageLoadFromImage()
imageSaveToFile()
imageSaveToMember()
imageSaveToImage()
Methods to access an image:
imageGetWidth()
imageGetHeight()
imageGetPixel()
imageSetPixel()
imageGetBackgroundColor()
imageSetBackgroundColor()
imageGetDepth()
imageSetDepth()
imageTransparent()
imageGetColorspace()
imageSetColorspace()
imageGetCompression()
imageSetCompression()
imageGetResolution()
imageSetResolution()
imageGetAttribute()
imageSetAttribute()
imageGetColorCount()
Methods to manipulate image frames:
imageGetFrameCount()
imageGetCurrentFrame()
imageSetCurrentFrame()
imageDeleteFrame()
imageAddFrame()
imageSwapFrames()
imageReverseFrames()
imageGetFrameDelay()
imageSetFrameDelay()
imageFlatten()
Methods to resize an image:
imageResize()
imageScale()
imageSample()
imageMagnify()
imageMinify()
imageThumbnail()
Methods to transform an image:
imageFlip()
imageFlop()
imageRoll()
imageChop()
imageCrop()
imageShave()
Imaging effects methods:
imageOilPaint()
imageAddNoise()
imageBlur()
imageEdge()
imageEmboss()
imageImplode()
imageMotionBlur()
imageShade()
imageSharpen()
imageSolarize()
imageSpread()
imageSwirl()
imageWave()
imageCycleColormap()
imageCharcoal()
imageRaise()
imageMorph()
imageCoalesce()
Methods to enhance an image:
imageEnhance()
imageContrast()
imageModulate()
imageReduceNoise()
imageMedianFilter()
imageNormalize()
imageDespeckle()
Methods to rotate an image:
imageRotate()
imageShear()
Lingo Sample Code for Director
Sample Code for Authorware
JavaScript Sample Code for Director
Known Issues
Error Codes
History
Installation
DirectImage
Xtra has an authoring version, a run time version and an auto
downloadable Shockwave safe package. The trial version only includes the
authoring version.
The authoring version is used by Director and/or Authorware
authoring
environment while developing your movie/presentation. It should be placed
in
your Director and/or Authorware "Xtras" folder.
The run time version is used when running your movie/presentation
as a
stand-alone application. It should be placed in a folder named "Xtras"
that is
inside the folder that contains the host projector/package. Alternatively,
the run
time version can be bundled in projectors/packages (in a similar way you
bundle other Director\Authorware files).
When creating Director projectors please note that if the
Xtra is listed in the
Modify->Movie->Xtras dialog then the "Include in Projector" checkbox
must be unchecked otherwise Director will bundle the Authoring version of
the
Xtra in the projector, which will not work outside the authoring
environment.
Instead, add the run time version of the Xtra in the "Create Projector"
dialog
or include it in the projector "Xtras" folder.
The run time version is also used with the Authorware web player and can
be
bundled in the web package. When creating packages in Authorware,
please note that by default, Authorware will attempt to bundle the
authoring
version of the Xtra. You'd have to modify the application 'Publish
Settings' in
order to instruct Authorware to bundle the run time version instead of the
authoring version.
The auto downloadable Shockwave safe package is used by Shockwave
for Director. The package should be uploaded to your server from which it
will
automatically get downloaded and installed by your Shockwave movie, if
needed.
The auto downloadable Shockwave safe package consists of the following
files:
DirectImage.w32 - Shockwave safe package for Windows
DirectImage.ppc - Shockwave safe package for MacOS 8.x and 9.x
DirectImage.carb - Shockwave safe package for MacOS X
Please note that Director requires that all the above files would be
uploaded to
your server even if you're only using the Xtra on one platform.
Once you have decided the location on your server where the auto
downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example, if you
uploaded
the downloadable package to "http://www.myserver.com/packs" you should
add the following line to "xtrainfo.txt".
[#namePPC:"DirectImage", #nameW32:"DirectImage.x32",
#package:"http://www.myserver.com/packs/DirectImage"]
Note that the above entry should consist of a single line in the
"xtrainfo.txt" file.
Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectImage
Xtra. From the
Modify->Movie->Xtras dialog in Director, select the DirectImage
Xtra in the
list of Xtras. The "Download if needed" check box should now be enabled.
(If
it's not enabled, make sure the filename in "xtrainfo.txt" matches the
actual
filename of the Xtra.) Click on the check box and Director will load
information from the package file for each platform and add it to the
current
movie.
IMPORTANT: The authoring, run time and Shockwave versions can not
coexist in the same "Xtras" folder, so be sure to place the appropriate
version
in the appropriate folder.
Registration
DirectImage Xtra is a
commercial product.
Basically, there are 3 types of licenses: Single, Site and Corporate.
Single License: Entitles an organization to receive one copy of the
licensed
Xtra(s) which can only be used by a single developer on a single computer
at
any one time.
Site License: Entitles an organization to receive one copy of the
licensed
Xtra(s) which can be used by any number of developers on any number of
workstations within one site.
Corporate License: Entitles an organization to receive one copy of
the
licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).
Once you have licensed DirectImage
Xtra, you will be given a serial number.
Your DirectImage
Xtra serial number should be passed to the New()
function
when creating the DirectImage
Xtra instance in order to unlock the trial
limitations. Once the Xtra is unlocked, trial warnings will no longer be
presented, there will be no other limitations and the run-time and
Shockwave
versions of the Xtra will become activated.
Be sure to protect the call to
New()
so that your DirectImage
Xtra serial
number would not become exposed to others. This can be done in a similar
way you protect the rest of your application source code. If you intend to
distribute your application with open source code then pass
New()
the number
0 as your serial number. This will switch the Xtra into a trial mode and
you can
instruct developers to change the number 0 with their serial number.
Alternatively, you can protect just the appropriate
New()
calls in your code.
The New()
function should be called before any of the other Xtra functions are
called.
You can freely distribute the run time version and Shockwave safe
package of DirectImage Xtra DirectImage
with any application developed by you,
and you alone. You can not redistribute the authoring version.
Please refer to the license agreement for further information.
Note that if your Shockwave movie needs to run on both Windows and
MacOS, you'd need to obtain a license for both the Windows and MacOS
versions of the Xtra.
Overview
DirectImageXtra adds functions to Director and Authorware which provide
applications with the ability to
create, export, import,
capture
and manipulate images.
An image stored in a typical format such as JPEG, PIC and BMP consists of a
single frame. Some image file formats are capable of storing images with
multiple frames \ layers. For example, MNG and animated GIF files can contain
multiple frames which together consist of an animation sequence. Another example
are PSD (Photoshop) files which are capable of storing images in multiple
layers.
DirectImage Xtra supports images with single and multiple frames \
layers. For simplicity reasons, this documentation refers to layers as frames.
When working on a multi frame image the Xtra functions refer to the current
(active) frame unless otherwise specified. By default, the current frame is the
first frame in the image. The Xtra provides functions to change the current as
well as manipulate the image frames.
The Using DirectImage Xtra
section of this document describes in simple step by step instructions how
applications can create, load, save and manipulate images.
The Functions Reference section that follows describes in details all the Xtra functions - what they do, how they work, which parameters they accept
and which value they return.
The
DirectImage
Xtra functions
are synchronous. That means that while they are being executed, the Director
or Authorware playback is halted. No other calls can be made simultaneously. The Xtra
functions return control to Director \ Authorware upon completion, with an error code
indicating whether their task was completed successfully. A list of possible
error codes can be found in the Error Codes section of
this document.
Some functions may not return immediately. The amount of time it takes for a
particular function to complete depends on the image size, the image color
depth, and the task the function has to perform. In addition, some functions may require
more memory than others. If you're working on the MacOS 8/9 and intend to use the
Xtra to manipulate large images it is recommended that you increase the default
memory allocated to the Director \ Authorware authoring environment and projectors.
A sample Director movie is included. It demonstrates most of the Xtra
features by allowing you to capture, import, export and manipulate images. Additional
sample code for both Director and Authorware can be found in the Sample Code section of
this document.
Using DirectImage Xtra
Step 1 - Create a new instance of
DirectImage
Xtra and store it for a later use.
The
DirectImage
instance is a reference to an image that the Xtra stores and manipulates
internally. Applications have to store it in a variable so that they can later
on pass it as the first parameter to the other Xtra functions.
Lingo Sample Code for Director :
Set Image
= new
(Xtra
"DirectImage", 0)
Sample Code for Authorware :
Image
:= NewObject ("DirectImage ", 0)
JavaScript Sample Code for Director :
Image
= new xtra
("DirectImage", 0)
Step 2 - Load an image.
The image can be loaded from a file or captured
directly from the screen. In Director the image can also be loaded from an image
cast member or object, while in Authorware the image can also be loaded from a display
icon.
Example:
When loading an image from a file :
Lingo Sample Code for Director :
imageLoadFromFile (Image, "c:\MyImage.jpg")
Sample Code for Authorware :
CallObject (Image,
"imageLoadFromFile",
"C:\\MyImage.jpg" )
JavaScript Sample Code for Director :
Image .imageLoadFromFile( "C:\\MyImage.jpg"
)
where "C:\MyImage.jpg" (without the quotes) is the full pathname of the image
file to be loaded.
When capturing an image from the screen :
Lingo Sample Code for Director :
imageLoadFromScreen (Image)
Sample Code for Authorware :
CallObject ( Image,
"imageLoadFromScreen")
JavaScript Sample Code for Director :
Image.imageLoadFromScreen ()
When loading an image from an image cast member \ display icon:
Lingo Sample Code for Director :
imageLoadFromMember (Image,
member "MyImage")
where "MyImage" (without the quotes) is the name of the image cast member to
be loaded.
You can also refer to cast members by index, for example:
imageLoadFromMember (Image,
member 1
of castlib
1)
will load the first cast member in the first cast library.
Sample Code for Authorware :
CallObject ( Image,
"imageLoadFromMember", "MyImage")
where "MyImage" (without the quotes) is the name of the
display icon to
be loaded.
JavaScript Sample Code for Director :
Image.imageLoadFromMember (
member ("MyImage"))
where "MyImage" (without the quotes) is the name of the image cast member to
be loaded.
You can also refer to cast members by index, for example:
imageLoadFromMember (Image,
member 1
of castlib
1)
will load the first cast member in the first cast library.
When loading an image from a Director image object:
imageLoadFromImage (Image,
(the
stage).image)
will load the Director stage image.
Step 3 - Manipulate the image.
Once the image is loaded, you can use any of the Xtra imaging functions to
manipulate it.
For example, you can flip the current image frame by calling:
Lingo Sample Code for Director :
imageFlip (Image)
Sample Code for Authorware :
CallObject ( Image,
"imageFlip")
JavaScript Sample Code for Director :
Image.imageFlip()
and/or blur it by calling:
Lingo Sample Code for Director :
imageBlur (Image,
1.0,
1.0)
Sample Code for Authorware :
CallObject (Image,
"imageBlur", 1.0, 1.0)
JavaScript Sample Code for Director :
Image.imageBlur ( 1.01,1.01)
Step 4 - Save the image.
The image can be saved to an image file. In Director, the image can also be
saved to an image cast member or object.
Example:
When saving the image to a file :
Lingo Sample Code for Director :
imageSaveToFile (Image ,
"c:\MyImage.jpg" ,
100, 1, 1)
Sample Code for Authorware :
CallObject ( Image,
"imageSaveToFile",
"C:\\MyImage.jpg",
100, 1, 1)
JavaScript Sample Code for Director :
Image.imageSaveToFile (
"c:\\MyImage.jpg" ,
100, 1, 1)
where "C:\MyImage.jpg" (without the quotes) is the full pathname of
the target file where the image will be saved to. The file extension specifies
the file format in which the image will be stored.
When saving the image to a Director image cast member :
imageSaveToMember (I mage,
member "MyImage",
32,
0,
0)
where "MyImage" (without the quotes) is the name of the target image cast
member.
You can also refer to cast members by index, for example:
imageSaveToMember (Image,
member 1
of castlib
1, 32,
0,
0)
will save the image into the first cast member of the first cast library.
When saving the image to a Director image object :
MyImage = imageSaveToImage (Image)
where "MyImage" (without the quotes) is the name of the
target image object.
Step 5 -
You can now save another copy of the image to a different file or cast
member, as described in step # 4, keep manipulating the existing image as
described in step # 3, or load a new image cast member as described in step # 2.
Once you're done working with the image, delete the
DirectImage
instance that you've created in step 1:
Lingo Sample Code for Director :
Set Image=0
Sample Code for Authorware :
DeleteObject ( Image)
JavaScript Sample Code for Director :
Image=0
Functions Reference
Director: New ( Xtra "DirectImage", integer
SerialNumber )
Authorware: NewObject ( "DirectImage", integer
SerialNumber )
Creates a new DirectImage
Xtra instance.
The returned value is a new instance of
DirectImage
Xtra.
Parameters :
SerialNumber : DirectImage
Xtra Serial Number. If you are using the trial version, pass the number 0.
Returns : DirectImage
instance.
Remarks :
The
DirectImage
instance is a reference to an image that the Xtra stores and manipulates
internally. Applications have to store it in a variable so that they can later
on pass it as the first parameter to the other Xtra functions.
The newly created image has no frames. After creating the instance applications must load an image using the
imageLoadFromFile(),
imageLoadFromMember() or
imageLoadFromScreen() functions or create
a new image frame using the imageAddFrame()
function prior to calling the other Xtra imaging
functions.
Each
DirectImage
instance can reference a single image. In order to manipulate multiple images at
the same time, create multiple instances out of
DirectImage
Xtra and work with them simultaneously.
Director: Forget ( object me
)
Authorware:
DeleteObject ( object me )
Deletes a DirectImage
Xtra instance.
Parameter :
object me : DirectImage
Instance.
Returns : None.
Remarks :
In Director you can also delete the
DirectImage
Xtra instance by setting it to zero.
imageLoadFromFile ( object me, any FileName )
Loads an image from an image file into the current frame.
Parameters :
object me : DirectImage Instance.
FileName : Full pathname of the source image
file.
Returns : 0 (zero) if the image was loaded
successfully or an error code otherwise.
Remarks :
If the image already has one or more frames by the time this function is
called then if the
function succeeds in loading the image file it disposes the image of the current
frame and replaces it with the new one. All the other image frames are kept
intact. If the specified image file has more than one frames, all the image
frames will be loaded and appended after the current frame.
The Xtra will automatically detect the source image file format.
Safe mode notes:
The Xtra is always in safe mode when it is used by a Shockwave
movie that is running from within a web browser. A safe mode can also be set in the
Director authoring environment or projectors by setting the safePlayer lingo
property to true before creating the
DirectImage
Instance.
When the Xtra is in Shockwave safe mode you can precede the FileName
parameter with the "|" character in order to load the specified file from the
Shockwave support folder. The Shockwave support folder is a folder named
dswMedia that is located in the same folder where the Shockwave system
player is installed. For example, passing
"|File.jpg" will have the Xtra load the file "File.jpg" that is
located in the Shockwave support folder.
This technique can also be used in a safe mode while running in the authoring
environment or projectors under which case the Xtra will refer to a folder named
dswMedia that is located in the same folder where the Director executable
or projector files are located, respectively.
If no "|" is preceded the FileName parameter, and the specified
file is located in a local folder named dswMedia, or in one of its sub
folders, the Xtra will import the specified file. Otherwise, a dialog box would
appear asking the user where the file to be imported is located.
When using the built-in dialog box you can use the FileName
parameter to specify the image file type which the dialog box will look for by
passing its extension on Windows (without the dot) or file type on MacOS, otherwise set it to
an empty string and the dialog box will display all files. On Windows only you
can also supply a message for the file type by specifying additional text after
the extension and separating it with a "|".
For example, the following code will display a file selection dialog box when
the Xtra is in safe mode showing files whose extension on Windows or file type
on MacOS is JPEG: imageLoadFromFile (image, "JPEG|JPEG Files")
You may also specify multiple file types as a list. For
example, the following code will display a file selection dialog box when the
Xtra is in safe mode showing files whose extensions are JPEG or BMP:
imageLoadFromFile (image, ["JPEG|JPEG Files","BMP|BMP Files"])
Note that on Windows, the dialog box will include a type selection
for each of the specified types. To display multiple file types in a single type
selection, use *.fileType separated by semi colons and omit the first "*.". For
example, ["JPG;*.JPEG;*.JPE","BMP"] will display all JPEG types in a single type
selection and BMP in a second type selection. This syntax is only compatible
with Windows and will not work on MacOS.
On Windows only, the default filename in the file selection dialog
will be set based on the "Default Filename" image attribute, if one was set prior
to calling this function using the
imageSetAttribute() function. For example, to set the default file name
to "Default.jpg", create a new image frame where the selected file will be
loaded then call imageSetAttribute (image, "Default Filename", "Default.jpg") . After
the user closes the file selection dialog box, this function will set the
"Selected
Filename" attribute to the full pathname of the file selected by the user, or
to an empty string if the user canceled the file selection dialog.
To display a file selection dialog box in a non safe mode you can
use the free FileIO Xtra that comes with Director \ Authorware or the
dosSelectFile() function in our DirectOS
Xtra which provides better control over the appearance and operation of file
selection dialogs.
imageLoadFromMember ( object me, any CastMember )
Loads an image from a Director image cast member or an Authorware display
icon into the current image frame.
Parameters :
object me :
DirectImage Instance.
CastMember : Reference to the source
Director image cast
member or the name of the source Authorware display icon.
Returns : 0 (zero) if the image was loaded
successfully or an error code otherwise.
Remarks :
If the image already has one or more frames by the time this function is
called then if the
function succeeds in loading the image cast member \ icon it disposes the image
of the current frame and replaces it with the new one. All the other image
frames are kept intact.
For better performance under Director 8.5 or later use
imageLoadFromImage()
instead of this function to load the image of a cast member.
On Windows only, the function also loads the cast member's alpha channel, if
it is available. For cross platform alpha channel support, use
imageLoadFromImage() instead, as it
supports alpha channel on both Windows and MacOS.
This function can also be used to load the Director stage image. In order to
do so, first save the Director stage image into a cast member by setting the
target cast member 'Image' property to the stage 'Image' property, then pass to
this function a reference to the cast member with the stage image.
For example, the stage image can be saved to an image cast member named
"flower" using the following call:
member("flower").image = (the stage).image
imageLoadFromScreen ( object me )
Captures the screen image and loads it into the image.
Parameter :
object me :
DirectImage Instance.
Returns : 0 (zero) if the image was loaded
successfully or an error code otherwise.
Remarks :
The function captures whatever is on the screen by the time it is being
called, except the mouse cursor. Applications can use the windowing
functions in our
DirectOS
Xtra to manipulate Director, Authorware and other application's windows prior to
capturing the screen. For example, all open windows can be minimized prior
to calling this function in order to capture the desktop window.
If the image already has one or more frames by the time this function is
called then if the
function succeeds in capturing the screen image it disposes the image of the
current frame and replaces it with the captured image. All the other image
frames are kept intact.
imageLoadFromImage ( object me, any ImageObject )
Loads an image object, including its alpha channel, into the current
image frame.
Parameters :
object me : DirectImage
Instance.
ImageObject :
Reference to the source image object.
Returns : 0 (zero) if the image was loaded
successfully or an error code otherwise.
Remarks :
This function is only available in Director 8.5 or later.
The function loads images faster than
imageLoadFromMember(). Following is
an example showing how this function can be used to load an image cast
member into the current image frame:
imageLoadFromImage (image, member("foo").image)
This function can also be used to load the Director stage image. In
example:
imageLoadFromImage (image, (the stage).image)
If the image already has one or more frames by the time this function is
called then if the
function succeeds in loading the image cast member it disposes the image
of the current frame and replaces it with the new one. All the other image
frames are kept intact.
imageSaveToFile ( object me, any FileName, integer Quality, integer
StartFrame, integer EndFrame )
Saves an image to an image file.
Parameters :
object me : DirectImage
Instance.
FileName : Full pathname of the target image file.
The file format in which the image will be stored can be specified in two ways:
1) As the file extension. For example,
"C:\MyImage.jpg" on Windows or "My Hd:MyImage.jpg" will save the image to a file
named "MyImage.jpg" in a JPEG format.
2) By preceding the pathname with the image format extension following by a
colon. For example, "BMP:C:\MyImage" on Windows or "BMP:My Hd:MyImage" on
MacOS will save the image to a file named "MyImage" in a BMP format on drive C
under Windows or drive "My Hd" under MacOS, respectively. If a file extension is
specified, it will not affect the image format. For example, "BMP:C:\MyImage.jpg" on Windows or "BMP:My Hd:MyImage.jpg" on MacOS will save the image to a file named "MyImage.jpg"
in a BMP format on drive C under Windows or drive "My Hd" under MacOS, respectively.
Quality : Specifies the quality of the
exported image, in percentage. This parameter can be any value between zero
(lowest quality) to 100 (highest quality) and is only applicable to some file
formats, including JPEG, PNG and MIFF.
StartFrame : If the image includes multiple frames
set this parameter to the frame number on which to start exporting the animation
sequence. If the image has a single frame set this parameter to 1. To export a
single frame out of a multi frames image set this parameter to the number of the
frame to export.
EndFrame : If the image includes multiple
frames set this parameter to the frame number on which to end exporting the
animation sequence. If the image has a single frame set this parameter to
1. To export a single frame out of a multi frames image set this parameter to
the number of the frame to export.
Returns : 0 (zero) if the image was saved
successfully or an error code otherwise.
Remarks :
If the target file already exists, the function overwrites it.
Safe mode notes:
The Xtra is always in safe mode when it is used by a Shockwave
movie that is running from within a web browser. A safe mode can also be set in the
Director authoring environment or projectors by setting the safePlayer lingo
property to true before creating the
DirectImage Instance.
When the Xtra is in Shockwave safe mode you can precede the FileName
parameter with the "|" character in order to save the image to the Shockwave
support folder. The Shockwave support folder is a folder named dswMedia
that is located in the same folder where the Shockwave system player is
installed. For example, passing "|File.jpg" will have the Xtra save the image to a file named "File.jpg"
that is located in the Shockwave support folder.
This technique can also be used in a safe mode while running in the authoring
environment or projectors under which case the Xtra will refer to a folder named
dswMedia that is located in the same folder where the Director executable
or projector files are located, respectively.
You can alternatively precede the FileName parameter with the "|*"
string. This special prefix instructs the Xtra to delete the specified file from
the dswMedia folder rather than saving there the image file. For example,
passing "|*File.jpg" will instruct the function to delete the file named "File.jpg"
from the Shockwave support folder.
If no "|" is preceded the FileName parameter, and the specified
file is located in a local folder named dswMedia, or in one of its sub
folders, the Xtra will save the image to the specified file. Otherwise, a dialog box would
appear asking the user
where to save the image file.
When using the built-in dialog box you can use the FileName parameter
to specify the default file type by passing its extension (without the dot). On
Windows, only files of the specified type will be displayed in the file
selection dialog.
If you do not wish to specify a default file type simply set the FileName
parameter to an empty string.
If you specify a default file type but the selected file name does not end with
a
file extension, the Xtra will automatically append the extension specified by
the
FileName parameter hence forcing the Xtra to save the image in the
specified format.
On Windows, you may also supply a message for the file type by specifying
additional text after the extension and separating it with a "|".
For example, the following code will display a file selection dialog box
when the Xtra is in safe mode asking the user to select a file to save the
image to. The format of the exported file will be JPEG: imageSaveToFile
(image, "jpg|JPEG Files", 100, 1, 1)
On Windows, you may also specify multiple file types as a list. For
example, the following code will display a file selection dialog box when
the Xtra is in safe mode showing files whose extensions are JPEG or BMP:
imageSaveToFile (image, ["JPEG|JPEG Files","BMP|BMP Files"], 100, 1, 1)
The image will be saved in the format selected by the user. On MacOS this
feature is not available an the file will be saved in the format specified
first in the list (the default format, JPEG in this example) unless
otherwise specified by the user.
The default filename in the file selection dialog will be
set based on the "Default Filename" image attribute, if one was set prior to
calling this function using the
imageSetAttribute() function. For example, to set the default file
name to "Default.jpg", call imageSetAttribute (image, "Default Filename", "Default.jpg")
. After the user closes the file selection dialog box, this function will
set the "Selected Filename" attribute to the full pathname of the file
selected by the user, or to an empty string if the user canceled the file
selection dialog.
To display a file selection dialog box in a non safe mode you can use the free
FileIO Xtra that comes with Director \ Authorware or the
dosSelectFile()
function in our DirectOS Xtra which
provides better control over the appearance and operation of file selection
dialogs.
imageSaveToMember ( object me, any CastMember, integer ColorDepth, int Dither,
any Palette )
Saves the current image frame into an image cast member.
Parameters :
object me : DirectImage
Instance.
CastMember : Reference to the target image cast
member. The specified target image cast member must exist otherwise the function
would fail. You can use the New() lingo function to create a new image cast
member prior to calling this function.
ColorDepth : Specifies the pixel depth of the
target cast member. Can be one of the following values:
0 - The cast member's existing pixel depth and palette. The
image data is remapped to the cast member pixel depth and palette when placed in
the cast member.
1 - Explicitly specifies 1 bit as the pixel depth of the
target image cast member.
2 - Explicitly specifies 2 bits as the pixel depth of the
target image cast member.
4 - Explicitly specifies 4 bits as the pixel depth of the
target image cast member.
8 - Explicitly specifies 8 bits as the pixel depth of the
target image cast member.
16 - Explicitly specifies 16 bits as the pixel depth of the
target image cast member.
32 - Set the target cast member's pixel depth to 32 bits.
Since
DirectImage
Xtra
internally stores images in 32 bits, the image will be saved as is, without any
remapping, dithering or loss of quality.
Dither : Specifies whether image data will be
dithered or remapped to the specified pixel depth and palette. Pass true for
dithering and false for remapping. This parameter is ignored if the
ColorDepth parameter is set to 32 or 0.
Palette: The palette which will be associated
with
the target image cast member. This parameter can either be a reference to an existing
palette cast member, or a symbol indicating one of the Director built-in
palettes (i.e #systemWin, #systemMac, etc.). This parameter is ignored if the
ColorDepth parameter is set to 32 or 0.
Returns : 0 (zero) if the image was saved
successfully or an error code otherwise.
Remarks : This function is not available for
Authorware.
For better performance under Director 8.5 or later use
imageSaveToImage()
instead of this function to save the image to an image cast member.
Director may automatically trim white space when saving the image
into an image cast member. As a result, the cast member image size may be
smaller. To preserve the white space, use
imageSaveToImage() instead.
On Windows only, the function also saves the image's alpha channel,
if it is available, into the image cast member. For cross platform alpha channel
support use
imageSaveToImage()
instead, as it supports alpha channel on both Windows and MacOS.
If the source image has an alpha channel but the depth of the target image
cast member is less than 32 bits (and therefore the target image cast member can
not store an alpha channel), the alpha channel information will still be taken
into account when saving the image. If you do not wish this to happen simply set
the alpha channel to opaque.
imageSaveToImage ( object me )
Returns an image object containing the current image frame
including its alpha channel.
Parameter :
object me :
DirectImage Instance.
Returns : An image object containing the
current image frame including its alpha channel. The returned image object is always 32 bit.
Remarks :
This function is only available in Director 8.5 or later.
The function saves images faster than
imageSaveToMember(). Following is an example showing how this function can be
used to save the current image frame into an image cast member:
member("foo").image = imageSaveToImage(image)
imageGetWidth (
object me )
Returns the width of the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : The image width, in pixels.
imageGetHeight (
object me )
Returns the height of the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : The image height, in pixels.
imageGetPixel (
object me, integer X, integer Y )
Returns the color of the pixel that is located at the specified
position in the current image frame.
Parameters :
object me : DirectImage
Instance.
X :
The horizontal pixel position in the image.
Y :
The vertical pixel position in the image.
Returns : The color of the specified pixel.
Remarks :
In Director 7 or later the function returns a color object, i.e.
RGB(255,255,255). In Authorware and Director 5 or 6 the function returns an
integer specifying the color, i.e. 16777215 (HEX #FFFFFF) which is equivalent to
RGB(255,255,255). This value is similar to the one returned by the RGB()
function in Authorware.
imageSetPixel (
object me, integer X, integer Y, any Color )
Sets the color of the pixel that is located at the specified position
in the current image frame.
Parameters :
object me :
DirectImage Instance.
X :
The horizontal pixel position in the image.
Y :
The vertical pixel position in the image.
Color : The new color for the specified pixel. In
Director 7 and above this parameter should be set to an RGB color object that
specifies the color, i.e. RGB(255,255,255). In Authorware and Director 5 or 6
this parameter should be set to an integer that specifies the color, i.e.
16777215 (HEX #FFFFFF) for RGB(255,255,255).
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageGetBackgroundColor (
object me )
Returns the background color of the current image frame.
Parameters :
object me : DirectImage
Instance.
Returns : The background color of the current image
frame.
Remarks :
See imageGetPixel() remarks.
imageSetBackgroundColor (
object me, any Color )
Sets the background color of the current image frame.
Parameters :
object me :
DirectImage Instance.
Color : The new background color. In Director 7 and
above this parameter should be set to an RGB color object that specifies the
color, i.e. RGB(255,255,255). In Authorware and Director 5 or 6 this parameter
should be set to an integer that specifies the color, i.e. 16777215 (HEX #FFFFFF)
for RGB(255,255,255).
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageGetDepth (
object me )
Returns the depth of the color components in the current image frame.
By default, pixels components are stored internally by the Xtra as 8-bit
values. This translates into 24 bit color depth for an entire RGB image.
Parameter :
object me : DirectImage
Instance.
Returns : An integer indicating the color depth of
the image pixels. Can be 8 for 8 bit or 16 for 16 bit.
imageSetDepth (
object me, integer ColorDepth )
Sets the depth of the color components in the current image frame.
By default, pixels components are stored internally by the Xtra as
8-bit values. This translates into 24 bit color depth for an entire RGB image.
Parameters :
object me : DirectImage
Instance.
ColorDepth :
An integer indicating the color depth of the image pixels. Can be 8 for 8
bit or 16 for 16 bit.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageTransparent (
object me, any Color, integer Fuzz )
Transparent all the pixels in the current image frame whose color matches the one specified
by the Color parameter.
Parameters :
object me : DirectImage
Instance.
Color : The transparent color. In Director 7 and
above this parameter should be set to an RGB color object that specifies the
color, i.e. RGB(255,255,255). In Authorware and Director 5 or 6 this parameter
should be set to an integer that specifies the color, i.e. 16777215 (HEX #FFFFFF)
for RGB(255,255,255).
Fuzz :
D efines how much tolerance is acceptable to
consider two colors as the same. For example, set fuzz to 10 and the color red
at intensities of 100 and 102 respectively are now interpreted as the same
color.
0 is the default, meaning that the specified Color object must match a
particular pixel color exactly.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageGetColorspace (
object me )
Returns the colorspace of the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : An integer indicating the image
colorspace. Can be one of the following values:
0 - Undefined.
1 - RGB.
2 - GRAY.
3 - Transparent.
4 - OHTA.
5 - XYZ.
6 - YCBCR.
7 - YCC.
8 - YIQ.
9 - YPBPR.
10 - YUV.
11 - CMYK.
12 - SRGB.
imageSetColorspace (
object me, integer Colorspace )
Sets the colorspace of the current image frame.
Parameters :
object me : DirectImage
Instance.
Colorspace :
An integer indicating the image colorspace. Can be one of the following
values:
0 - Undefined.
1 - RGB.
2 - GRAY.
3 - Transparent.
4 - OHTA.
5 - XYZ.
6 - YCBCR.
7 - YCC.
8 - YIQ.
9 - YPBPR.
10 - YUV.
11 - CMYK.
12 - SRGB.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
The function transforms the image pixels to the specified colorspace if the
current image colorspace is RGB or if the colorspace specified by the
Colorspace parameter is RGB.
imageGetCompression (
object me )
Returns the compression type of the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : An integer indicating the image
compression. Can be one of the following values:
0 - Undefined.
1 - None.
2 - BZip.
3 - Fax.
4 - Group4.
5 - JPEG.
6 - Lossless.
7 - LZW.
8 - RLE.
9 - ZIP.
imageSetCompression (
object me, integer Compression )
Sets the compression type of the current image frame.
Parameters :
object me : DirectImage
Instance.
Colorspace :
An integer indicating the image compression. Can be one of the following
values:
0 - Undefined.
1 - None.
2 - BZip.
3 - Fax.
4 - Group4.
5 - JPEG.
6 - Lossless.
7 - LZW.
8 - RLE.
9 - ZIP.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
Compressions are applied when saving the image using
imageSaveToFile(). Some compression types are
not applicable to all image file formats.
imageGetResolution (
object me )
Returns the resolution of the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : A linear list containing the image
resolution information. The first item in the list is a float indicating the
horizontal resolution of the image. The second item in the list is a float
indicating the vertical resolution of the image. The third item in the list is
an integer that is set to 1 if the density specifications are specified in units
of pixels per inch or to 2 if the density specifications are specified in units
of pixels per centimeter. It may also be set to zero in which case the
resolution type is not defined.
imageSetResolution (
object me, float X, float Y, integer Units )
Sets the resolution of the current image frame.
Parameters :
object me : DirectImage
Instance.
X :
A float indicating the horizontal resolution of the image.
Y :
A float indicating the vertical resolution of the image.
Units :
An integer specifying the resolution units. Can be one of the following
values:
0 - Undefined.
1 -
Density specifications are specified in units of pixels per
inch.
2 -
Density specifications are specified in units of pixels per centimeter.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageGetAttribute (
object me, string Key )
Searches the current image frame attributes for the attribute specified by the
Key parameter. If the attribute is found the function returns the attribute
value, otherwise, the function returns an empty string.
Parameters :
object me :
DirectImage Instance.
Key :
A string indicating the name
of the attribute to search.
Returns : A string containing the value
of the attribute whose name is specified by the Key
p arameter or an empty string if the specified attribute was
not found.
Remarks :
This function can be used to get the image EXIF information. To get an
EXIF attribute, precede the Key parameter with the "EXIF:" prefix,
i.e "EXIF:DateTime" will return the date and time the image was
created.
This function can also be used to get the image IPTC information. To
get an IPTC attribute, precede the Key parameter with the "IPTC:"
prefix following by the dataset number following by a colon following by
the record number, i.e "IPTC:2:55" will return the image creation
date from dataset 2.
IPTC Dataset 2 has been adopted by Adobe for their PhotoShop product and
is used to add data to an image using the File Info option.
Applications can use this function to extract and manipulate this data
that contains, amongst other information, Caption text. Following are the
IPTC record numbers for Dataset 2:
5 - Title
10 - Urgency
15 - Category
20 - Supplemental Category
25 - Keywords
40 - Instructions
55 - Creation Date
60 - Creation Time
65 - Originating program
80 - Author / Byline
85 - Author's Position
90 - City
95 - State Province
100, 101 - Country
103 - Transmission reference
105 - Headline
110 - Credit
115 - Source
120 - Caption
122 - Caption writer
When importing a PSD file this function can also be used to get the attributes of
the current layer by setting the Key parameter to the desired
attribute name. The names of supported attributes are "[layer-name]",
"[layer-xpos]", "[layer-ypos]" and "[layer-opacity]".
imageSetAttribute (
object me, string Key, string Value )
Adds or modifies the current image frame attributes. This function
can be used to store application specific data as part of the current image
frame object.
The function searches the list of attributes in the current image
frame
for the attribute specified by the Key parameter. If
the specified attribute exists in the list, the value specified by the Value
parameter is concatenated to the attribute. If the specified attribute is not
found, the attribute name and value is added to the list. If the Value
parameter is set to an empty string, the matching attribute is deleted from the
list.
Parameters :
object me :
DirectImage
Instance.
Key :
A string indicating the name
of the attribute to search.
Value :
A string containing the attribute value to append or set. Set this
parameter to an empty string to delete the matching attribute from the image
attributes list.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
When saving the image to file, image attributes which were set using this
function will not get stored in the file unless the target image file
format is MIFF. Original EXIF and IPTC information will be kept intact.
imageGetColorCount (
object me )
Returns the total number of unique colors in the current image
frame.
Parameter :
object me : DirectImage
Instance.
Returns : The total number of unique
colors in the image.
imageGetFrameCount (
object me )
Returns the total number of frames in the image.
Parameter :
object me : DirectImage
Instance.
Returns : The number of frames in the image.
imageGetCurrentFrame (
object me )
Returns the number of the current (active) frame.
Parameter :
object me : DirectImage
Instance.
Returns : The number of the current frame.
imageSetCurrentFrame ( object me, integer FrameNumber )
Sets the current (active) frame.
Parameters :
object me : DirectImage
Instance.
FrameNumber : The number of the frame to set as active.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageDeleteFrame (
object me )
Deletes the current image frame.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
When the current frame is deleted, the next frame, if available, is set as the
new current frame. If the current frame is deleted and it is the
last frame in the image, its previous frame, if available, is set as the
new current frame.
If the current frame is the only frame in the image, the image would have no
frames.
imageAddFrame (
object me )
Adds a new image frame.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
The new frame is created after the current frame with a dimension of 1x1
pixels.
imageSwapFrames ( object me, integer Frame1, integer Frame2 )
Swaps the specified frames in the image.
Parameters :
object me : DirectImage
Instance.
Frame1 : The number of the first frame to
swap.
Frame2 : The number of the second frame
to swap.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageReverseFrames (
object me )
Reverses the image frames.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageGetFrameDelay (
object me )
Returns the period of time, in milliseconds, which an image viewer has to
wait before displaying the next frame when the image is displayed as an animated
sequence.
Parameter :
object me : DirectImage
Instance.
Returns : The frame delay, in milliseconds. The
returned value can be in the range of 0 to 65535.
imageSetFrameDelay (
object me, integer Delay )
Sets the period of time, in milliseconds, which an image viewer has to wait
before displaying the next frame when the image is displayed as an animated
sequence.
Parameters :
object me : DirectImage
Instance.
Delay : The frame delay, in milliseconds.
The value can be in the range of 0 to 65535.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageFlatten (
object me )
Merges the image frames (layers).
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
This function is useful for combining multiple frames (layers) into
a single image. Some image file formats, such as Photoshop files, may include
more than one layer.
imageResize (
object me, integer Width, integer Height, integer Filter, float Blur )
Scales the current image frame to the desired dimensions.
Parameters :
object me :
DirectImage Instance.
Width : The scaled image width, in pixels.
Height : The scaled image height, in pixels.
Filter : Image filter to use. Can be one of the
following :
0 - Default (Lanczos) 1 -
Point 2 - Box 3 - Triangle 4
- Hermite 5 - Hanning 6 - Hamming
7 - Blackman 8 - Gaussian 9 -
Quadratic 10 - Cubic 11 - Catrom
12 - Mitchell 13 - Lanczos 14 -
Bessel 15 - Sinc
Blur : The blur factor where > 1 is blurry, < 1 is
sharp.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageScale (
object me, integer Width, integer Height )
Changes the current image frame size to the given dimensions.
Parameters :
object me :
DirectImage Instance.
Width : The scaled image width, in pixels.
Height : The scaled image height, in pixels.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageSample (
object me, integer Width, integer Height )
Scales the current image frame to the desired dimensions with pixel sampling. Unlike the
other scaling methods, this method does not introduce any additional color into
the scaled image.
Parameters :
object me :
DirectImage Instance.
Width : The scaled image width, in pixels.
Height : The scaled image height, in pixels.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageMagnify (
object me )
Scales the current image frame proportionally to twice its size.
Parameter :
object me :
DirectImage Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageMinify (
object me )
Scales the current image frame proportionally to half its size.
Parameter :
object me :
DirectImage Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageThumbnail (
object me, integer Width, integer Height )
Changes the current image frame size to the given dimensions and removes any
associated profiles. The goal is to produce small low cost thumbnail images
suited for display on the Web.
Parameters :
object me :
DirectImage Instance.
Width : The scaled image width, in pixels.
Height : The scaled image height, in pixels.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageFlip (
object me )
Creates a vertical mirror image of the current image frame by reflecting the pixels around the central
x-axis.
Parameter :
object me :
DirectImage Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageFlop (
object me )
Creates an horizontal mirror image of the current image frame by reflecting the pixels around the
central y-axis.
Parameter :
object me :
DirectImage Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageRoll ( object me, integer X, integer Y )
Offsets the current image frame as defined by the X and Y parameters.
Parameters :
object me :
DirectImage Instance.
X : The number of columns to roll the image in the
horizontal direction.
Y : The number of rows to roll the image in the
vertical direction.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageChop (
object me, integer Width, integer Height, integer X, integer Y )
Removes a region from the current image frame and collapses the image to occupy the removed
portion.
Parameters :
object me :
DirectImage Instance.
Width : The width of the region to chop, in pixels.
Height : The height of the region to chop, in
pixels.
X : The horizontal pixel position in the
image, indicating the top left corner of the region to chop.
Y : The vertical pixel position in the image,
indicating the top left corner of the region to chop.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageCrop (
object me, integer Width, integer Height, integer X, integer Y )
Extracts a region from the current image frame.
Parameters :
object me :
DirectImage Instance.
Width : The width of the region to extract, in
pixels.
Height : The height of the region to extract, in
pixels.
X : The horizontal pixel position in the
image, indicating the top left corner of the region to extract.
Y : The vertical pixel position in the
image, indicating the top left corner of the region to extract.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageShave (
object me, integer Width, integer Height )
Shaves pixels from the current image frame edges.
Parameters :
object me :
DirectImage Instance.
Width : The amount of pixels to shave from the left
and right edges.
Height : The amount of pixels to shave from the top
and bottom edges.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageOilPaint ( object me, float Radius )
Applies a special effect filter that simulates an oil painting on the current
image frame. Each pixel is
replaced by the most frequent color occurring in a circular region defined by
the Radius parameter.
Parameters :
object me :
DirectImage Instance.
Radius : The radius of the circular neighborhood.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageAddNoise ( object me, integer NoiseType )
Adds random noise to the current image frame.
Parameters :
object me :
DirectImage Instance.
NoiseType : The type of noise. Can be one of the
following:
0 - Uniform 1 - Gaussian
2 - Multiplicative Gaussian 3 - Impulse
4 - Laplacian 5 - Poisson
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageBlur (
object me, float Radius, float Sigma )
Blurs the current image frame. The image is convulsed with a Gaussian operator of the given
radius and standard deviation (sigma).
Parameters :
object me :
DirectImage Instance.
Radius : The radius of the Gaussian, in pixels, not
counting the center pixel. For reasonable results, the radius should be larger
than sigma. Use a radius of 0 and the function will select a suitable radius for
you.
Sigma : The standard deviation of the Gaussian, in
pixels.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageEdge (
object me, float Radius )
Edges the current image frame.
Parameters :
object me :
DirectImage Instance.
Radius : The radius of the convolution filter. Use
a radius of 0 and the function will select a suitable radius for you.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageEmboss (
object me, float Radius, float Sigma )
Grayscales the current image frame with a three-dimensional effect. The image is
convulsed with a Gaussian operator of the given radius and standard deviation
(sigma).
Parameters :
object me :
DirectImage Instance.
Radius : The radius of the pixel neighborhood. For
reasonable results, radius should be larger than sigma. Use a radius of 0 and
the function will select a suitable radius for you.
Sigma : The standard deviation of the Gaussian, in
pixels.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageImplode ( object me, float Amount )
Implodes or explodes the current image frame pixels by the specified percentage.
Parameters :
object me : DirectImage
Instance.
Amount : The extent of the implosion or
explosion. A positive value specifies the extend of implosion and a negative
value specifies the extend of explosion.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageMotionBlur ( object me, float Radius, float Sigma, float Angle )
Simulates motion blur on the current image frame. The image is convulsed with a Gaussian operator of the
given radius and standard deviation (sigma).
Parameters :
object me : DirectImage
Instance.
Radius : The radius of the Gaussian, in pixels, not
counting the center pixel. For reasonable results, radius should be larger than
sigma. Use a radius of 0 and the function will select a suitable radius for you.
Sigma : The standard deviation of the Gaussian, in
pixels.
Angle : The angle of the blurring motion.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageShade (
object me, integer ColorShading, float Azimuth, float Elevation )
Shines a distant light on the current image frame to create a three-dimensional effect. The
positioning of the light can be set using the Azimuth and Elevation
parameters.
Parameters :
object me : DirectImage
Instance.
ColorShading : A value other than zero shades the
red, green, and blue components of the image.
Azimuth : The azimuth of the light, measured in
degrees off the x axis.
Elevation : The elevation of the light, measured in
pixels above the Z axis.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageSharpen (
object me, float Radius, float Sigma )
Sharpens the current image frame. The image is convulsed with a Gaussian operator of the
given radius and standard deviation (sigma).
Parameters :
object me : DirectImage
Instance.
Radius : The radius of the Gaussian, in pixels, not
counting the center pixel. For reasonable results, radius should be larger than
sigma. Use a radius of 0 and the function will select a suitable radius for you.
Sigma : The standard deviation of the Laplacian, in
pixels.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageSolarize ( object me, float Threshold )
Applies a special effect to the current image frame, similar to the effect achieved in a
photo darkroom by selectively exposing areas of photo sensitive paper to light.
Parameters :
object me : DirectImage
Instance.
Threshold : The extent of the solarization. Ranges
from 0 to the maximum RGB value, 65535.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageSpread (
object me, integer Radius )
Applies a special effect to the current image frame that randomly displaces each pixel in a
block defined by the Radius parameter.
Parameters :
object me : DirectImage
Instance.
Radius: The radius of the pixel neighborhood in
which the function displaces pixels.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageSwirl (
object me, float Degrees )
Swirls the pixels about the center of the current image frame, where the Degrees parameter
indicates the sweep of the arc through which each pixel is moved.
Parameters :
object me : DirectImage
Instance.
Degrees: Defines the tightness of the swirling
effect.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageWave(
object me, float Amplitude, float Frequency )
Creates a ripple effect in the current image frame by shifting the pixels vertically along
a sine wave whose amplitude and wavelength are specified by the given
parameters.
Parameters :
object me : DirectImage
Instance.
Amplitude: The amplitude of the sine wave.
Frequency: The frequency of the sine wave.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageCycleColormap( object me, integer Amount )
Displaces the current image frame's color map by a given number of positions to produce a
psychedelic effect.
Parameters :
object me : DirectImage
Instance.
Amount: The number of positions to offset.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageCharcoal ( object me, float Radius, float Sigma )
Applies a special effect filter that simulates a charcoal painting on
the current image frame.
Parameters :
object me : DirectImage
Instance.
Radius : The radius of the Gaussian, in pixels, not
counting the center pixel. For reasonable results, radius should be larger than
sigma. Use a radius of 0 and the function will select a suitable radius for you.
Sigma : The standard deviation of the Gaussian, in
pixels.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageRaise (
object me, integer Width, integer Height, integer Raised )
Simulates a three-dimensional button-like effect by lightening and
darkening the edges of the current image frame.
Parameters :
object me : DirectImage
Instance.
Width : The width of the raised area.
Height : The height of the raised area.
Raised : A value other than zero creates a 3-D
raised effect, otherwise it has a lowered effect.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageMorph (
object me, integer NumOfFrames )
Morph the image frames. Each frame is transformed into the
following frame by a number of intervening images as specified by NumOfFrames.
Parameters :
object me : DirectImage
Instance.
NumOfFrames : The number of frames to
generate in-between each frame. The more in-between frames, the smoother the
morph is.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
This function requires an image with at least two frames.
imageCoalesce (
object me )
Composites a set of images while respecting any frame offsets and disposal
methods.
GIF, MIFF, and MNG animation sequences typically start with an image background
and each subsequent image varies in size and offset. This function composites a
new sequence where each image in the sequence is the same size as the first and
composed with the next image in the sequence.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageEnhance (
object me )
Applies a digital filter on the current image frame that improves the quality of a noisy image.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageContrast (
object me, integer Sharpen )
Enhances the intensity differences between the lighter and darker elements of
the current image frame.
Parameters :
object me : DirectImage
Instance.
Sharpen : A value other than zero increases the
image contrast. A value of zero decreases the image contrast.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageModulate (
object me, integer Brightness, integer Saturation, integer Hue )
Control the brightness, saturation, and hue of the current image
frame.
Parameters :
object me : DirectImage
Instance.
Brightness : The image brightness change
in percentage where 100 would keep the image brightness intact.
Saturation : The image saturation change
in percentage where 100 would keep the image saturation intact.
Hue : The image hue change in percentage
where 100 would keep the image hue intact.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageReduceNoise ( object me, float Radius )
Smoothes the contours of the current image frame while still preserving its edge. The
algorithm works by replacing each pixel with its neighbor closest in value.
Parameters :
object me : DirectImage
Instance.
Radius : The radius of the pixel neighborhood.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageMedianFilter ( object me, float Radius )
Applies a digital filter on the current image frame that improves the quality of a noisy image. Each
pixel is replaced by the median in a set of neighboring pixels as defined by the
Radius parameter.
Parameters :
object me : DirectImage
Instance.
Radius : The radius of the pixel neighborhood.
Returns :
0 (zero) if the function was successful or an error code
otherwise.
imageNormalize (
object me )
Enhances the contrast of a color image by adjusting the pixels
color to span the entire range of colors available.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageDespeckle ( object me )
Reduces the speckle noise in the current image frame while preserving its edges.
Parameter :
object me : DirectImage
Instance.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
imageRotate(
object me, float Degrees )
Rotates the current image frame by the specified number of degrees.
Parameters :
object me : DirectImage
Instance.
Degrees: Specifies the number of degrees to rotate
the image. Positive angles rotate clockwise while negative angles rotate
counter-clockwise.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
Rotated images are usually larger than the originals and have empty
triangular corners. Those empty
triangles left over from rotating the image are filled with the image background
color as defined by the
imageSetBackgroundColor() function.
imageShear(
object me, float ShearX, float ShearY )
Shears the current image frame. Shearing slides one edge of an image along the X or Y axis,
creating a parallelogram.
An X direction shear slides an edge along the X axis, while a Y direction
shear slides an edge along the Y axis. The amount of the shear is controlled by
a shear angle.
Parameters :
object me :
DirectImage Instance.
ShearX: The number of degrees to shear the image on
the X axis.
ShearY: The number of degrees to shear the image on
the Y axis.
Returns : 0 (zero) if the function was successful
or an error code otherwise.
Remarks :
Sheared images are usually larger than the originals and have empty
triangular corners. Those empty
triangles left over from shearing the image are filled with the image background
color as defined by the
imageSetBackgroundColor() function.
Lingo Sample Code for
Director
Unless otherwise specified, the following samples were written to be
compatible with Director 6 and above. An additional, more complex sample
Director movie is included with the Xtra.
Sample # 1, exporting the 5th image cast member in the first
castlib to a JPEG file named "Image.jpg" that is located in the same
folder where the Director movie is:
Known Issues
Can't open exported BMP files, they appear to be
corrupted.
When you load an image from a Director image object, the image is loaded as
32 bit and includes an alpha channel, even if the alpha channel is completely
opaque or is not being used in Director. If you then save the image to a BMP
file, the Xtra saves the image in BMP version 4 to preserve the alpha channel.
BMP version 4 is also used when the source image is an image cast member with an
alpha channel.
Some old software may not be familiar with the newer BMP format and may have
problems reading the exported image.
As a workaround, you can force the Xtra to save the image in BMP version 2 or 3,
discarding the alpha channel, i.e.:
imageSaveToFile (image, "BMP2:"&FilePathName, 100, 1, 1)
or
imageSaveToFile (image, "BMP3:"&FilePathName, 100, 1, 1)
Fatal errors when reading TIF and PICT files.
The Xtra may fail to read TIF and PICT files which were saved with a JPEG
compression. As a workaround save them with a different compression.
The alpha channel is not exported as a separate channel. Instead, it is applied to the image and the image is
exported as if the alpha channel was in use.
For some image file formats such as TIFF and PNG the depth of the image color
components needs to be set to 16 in order to export the alpha channel
separately. This can be done by calling
imageSetDepth(). If the depth is 8 bits the alpha channel will be
applied to the image and the image will be exported as 24 bits.
Error Codes
12000 - No image was loaded.
12001 - Invalid parameter.
12002 - Not enough memory.
12003 - Unsupported DIB format.
12004 - Can't open file.
12005 - Not supported in this version of
Director.
12300 - Limited resources warning.
12310 - Option warning.
12320 - Missing delegate warning.
12325 - Corrupt image warning. If exporting, the disk may be full.
12400 - Fatal exception. Not enough resources.
12430 - File open error. No permission to write to file.
History
12.25.03 - Version 3.1.1 released.
The following functions are now fully compatible with Authorware as well as
old versions of Director (5 and 6):
imageGetPixel()
imageSetPixel()
imageGetBackgroundColor()
imageSetBackgroundColor()
imageTransparent()
7.9.03 - Version 3.1 released.
* Added imageGetResolution() and imageSetResolution()
to get and set the image resolution with support for both pixels per inch and
pixels per centimeter densities.
* Added
imageGetAttribute() and imageSetAttribute()
to get and set image attributes. These functions can be used to obtain the
image EXIF or IPTC information as well as information about imported Photoshop
layers. In addition, the functions can be used to store application specific
data as part of the image object.
* Added imageThumbnail() to
create thumbnail images suited for display on the web.
* Improved imageLoadFromFile() and
imageSaveToFile() in a safe mode. When
running in a safe mode the functions can now display a file selection dialog
box with multiple file types. The default file name can now be
set and the selected file name can be retrieved. In addition,
imageSaveToFile() can now delete files
from the Shockwave support folder.
* Enabled LZW compression.
* Reduced the auto downloadable Shockwave safe package file size to 600K on
MacOS and 800K on Windows.
* Fixed compatibility issue with Windows 95.
2.21.03 - Version 3.02 released.
* New functions: imageGetColorspace(),
imageSetColorspace(),
imageGetCompression(),
imageSetCompression(),
imageGetDepth(),
imageSetDepth().
* Fixed inverted alpha channel bug.
* When the Xtra is in safe mode it can now import from or export to any
local dswMedia folder without the user consent.
* Minor improvements and bug fixes.
11.29.02 - Version 3.01 released.
* Fixed bugs in imageLoadFromImage() and
imageSaveToImage().
11.7.02 - Version 3.0 released.
* Images may now include multiple frames / layers. A new set of functions
was added for manipulating the image frames.
* The Xtra can now import from and export to image file formats that
support multiple frames / layers, such as animated GIF, Photoshop (PSD), DCX and MNG files.
* New methods to enhance an image:
imageContrast(), imageModulate() and imageNormalize().
* New imaging effects: imageMorph() and
imageCoalesce().
* New methods for importing to and exporting from image objects, with alpha
channel support: imageLoadFromImage()
and imageSaveToImage().
* The Xtra now natively supports MacOS X.
* The Xtra is now available for Authorware.
*
imageGetColorCount() was added to
count the number of unique colors in an image.
* imageSaveToFile() now takes
additional two parameters for specifying the beginning and end of the
animation sequence to export.
DirectImage Xtra 2.0 users who wish
to upgrade existing code to version 3 should pass two additional parameters to
all imageSaveToFile() calls and set them
to the number 1.
* imageSaveToMember() and
imageLoadFromMember() now retain alpha
channel information on Windows.
* Various minor bug fixes and improvements.
2.28.02 - Version 2.01 released.
* imageSaveToFile() - A 'Quality'
parameter was added. It specifies the quality of the exported image, in
percentage. This is useful in file formats such as JPEG where various quality
levels can be set.
In addition, the function now provides another way to specify the exported
file format without specifically setting the file extension.
* Fixed a bug related to accessing files that are located in non primary
partitions on MacOS.
* Various minor improvements.
1.8.02 - Version 2.0 released. The Xtra name was changed from DirectXport
to DirectImage.
|