. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



 DirectImage Xtra

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleMacOS X CompatibleWindows Compatible   

DirectImage Xtra™ Version 3.1.1 Documentation

 

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:

 

Sample # 2, importing a GIF file named "Image.gif" which is located in the same folder where the Director movie is, into an image cast member named "MyImage":

 

Sample # 3, Exporting the Director stage into a file named "Wallpaper.bmp" whose location is in the same folder where the Director movie is, then setting it as the Windows desktop wallpaper using our DirectOS Xtra. This sample requires Director 8 or later. In Director 8.5 and later, performance can be improved by calling:
imageLoadFromImage (image, the stage.image)
rather than capturing the stage image into an image cast member and loading it using imageLoadFromMember() as this sample does:

 

Sample # 4, Capturing the screen and saving the captured image into a JPEG file named "MyImage.jpg" that is located in the same folder where the Director movie is:

Sample # 5, Loading a JPEG file named "MyImage.jpg" that is located in the same folder where the Director movie is located, processing a special effect filter that simulates a charcoal painting on the loaded image and saving the result into a BMP file named "MyImage.bmp" that is located in the same folder where the Director movie is:

Sample # 6, Loading a JPEG file named "DirectImage.jpg" that is located in the same folder where the Director movie is located, storing the image into a new image cast member and loading it into the clipboard:

 

Sample # 7, Displaying a file selection dialog box asking the user to select an image file to import, then importing the selected file into a new image cast member. If the format of the selected file is not supported by the Xtra or if the user cancels the file selection dialog, an appropriate error message is displayed in the message window.

The sample is using DirectOS Xtra to display a file selection dialog box. The file selection dialog box can be customized. For example, it can only display certain image file formats. For more details, please refer to the dosSelectFile() documentation.

 

 

Sample Code for Authorware

Sample # 1, exporting a display icon named "MyIcon" into a JPEG file named "Image.jpg" that is located in the same folder where the Authorware application is:

 

Sample # 2, Capturing the screen and saving the captured image into a JPEG file named "MyImage.jpg" that is located in the same folder where the Authorware application is:

 

Sample # 3, Loading a JPEG file named "MyImage.jpg" that is located in the same folder where the Authorware application is located, processing a special effect filter that simulates a charcoal painting on the loaded image and saving the result into a BMP file named "MyImage.bmp" that is located in the same folder where the Authorware file is:

 

JavaScript 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:

 

Sample # 2, importing a GIF file named "Image.gif" which is located in the same folder where the Director movie is, into an image cast member named "MyImage":

 

Sample # 3, Exporting the Director stage into a file named "Wallpaper.bmp" whose location is in the same folder where the Director movie is, then setting it as the Windows desktop wallpaper using our DirectOS Xtra. This sample requires Director 8 or later. In Director 8.5 and later, performance can be improved by calling:
imageLoadFromImage (image, the stage.image)
rather than capturing the stage image into an image cast member and loading it using imageLoadFromMember() as this sample does:

 

Sample # 4, Capturing the screen and saving the captured image into a JPEG file named "MyImage.jpg" that is located in the same folder where the Director movie is:

Sample # 5, Loading a JPEG file named "MyImage.jpg" that is located in the same folder where the Director movie is located, processing a special effect filter that simulates a charcoal painting on the loaded image and saving the result into a BMP file named "MyImage.bmp" that is located in the same folder where the Director movie is:

Sample # 6, Loading a JPEG file named "DirectImage.jpg" that is located in the same folder where the Director movie is located, storing the image into a new image cast member and loading it into the clipboard:

 

 

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.

 

 



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 11/24/2004 4:49:04 PM.