WDMInput Xtra for Macromedia Director and Authorware for Windows

Version 1.3.8 . Built on Wednesday, December 3rd, 2008 .

Demo version, not licensed for distribution or use.

Licensed for evaluation only.

Barebones documentation of Xtra methods

---------------------------------------------------

Xtra level handlers

-------------------

+ xtraAddress object xtraReference

This is an internal method used by the Xtra to communicate between child objects.

It need not be used by any Lingo scripting. It was developed to work around a quirk

in the way Authorware creates Xtra objects.

Global handlers

---------------

* wdmiRegister *

Use the method before any other method of the Xtra. Supply any numeric serial number as a first

argument with the demo version of the Xtra (i.e., "wdmiRegister(0)"). If you license the Xtra,

you will be issued a genuine unique confidential serial number to use with a new registered

version of the Xtra. You will simply need to use the real number instead of 0. The Xtra is

designed to require a registration method call even in the demo version so that there will

be a minimum of Lingo coding changes to make the registered version of the Xtra work.

* wdmiVersion

Returns a floating point version number of the Xtra. This can be helpful in developing Lingo

scripting that handles the capabilities of different version of the Xtra differently.

* wdmiOpen

Call this method before creating any child object representing video input sources or other

objects that participate in the DirectShow filter graph built by Lingo calls to the Xtra.

This initializes DirectShow for use by the Xtra.

* wdmiClose

Call this method when done showing video or capturing video. This releases DirectShow.

* wdmiVideoInputSources

Returns a list of lists holding Xtra child objects, each one representing a possible video

input source on the current machine. You need some strategy for picking which video

input source to use with Lingo or Authorware calculation icon scripting.

The value is returned as a list of list rather than a list of objects due to some

quirks in the way that Authorware handles Xtra child objects. Authoware passes them

and returns them most effectively through sublists. Typically the objectList property

of a sublist holds the single Xtra child instance.

* wdmiAudioInputSources

Returns a list of lists holding Xtra child objects, each one representing a possible audio

input source on the current machine. You need some strategy for picking which audio input

source to use with Lingo.

In some cases a video input source also will include a multiplexed audio stream (such as

a DV video camcorder). Some other DirectShow filter objects can be used to de-multiplex

the audio from the video, depending on your requirements.

* wdmiDirectShowFilters

Returns a list of lists holding Xtra child objects, each one representing a possible DirectShow

filter that might be used in the filter graph you will build with Lingo. For instance, you

might be able to detect television tuner functionality based on the contents of this list.

* wdmiMontivisionImageFilters

Returns a list of lists holding Xtra child objects, each one representing a third party

DirectShow filter published by the unaffiliated company Montivision. Currently the Xtra

supports the use of Montivision's filter that can flip video from left to right, which

is very useful when someone in a camera's angle view needs to pose themselves by

looking into a video monitor close to the camera. (Without such flipping, people have

a hard time moving their body right to make the image move left.)

* wdmiOpenInputSource any inputSourceObject, integer registerForGraphEdit

Returns a list holding a single child object representing a DirectShow filter graph,

based on the provided audio or video input source child object, or other child object

representing a DirectShow object. You get such a child object to supply to this method

using one of the other methods above.

The Xtra represent filter graphs through child objects in order to afford the opportunity

for the Xtra to handle digitizing of displaying from more than once source at a time.

If you provide 1 for registerForGraphEdit, then the DirectShow filter can be attached

to by other DirectShow debugging tools such as GraphEdt.exe (which can be build from

DirectShow source code) or the Montivision Workbench. This can help identify problems

in complicated video and audio filter graphs, or to identify possible work arounds for

problems.

* wdmiGetHostAppWindowPosition

This is a utility method that reports where the host application main window is located,

in relationship to the coordinates of the set of monitors connected to the machine. This

will be the Authorware or Director authoring environment window, or the Authoware

executable package or Director projector main window.

* wdmiSetHostAppWindowPosition rect newPosition

This utility method moves the main host application window to a specific location on the

set of monitors connected to the machine. This is helpful in using a single Director

movie to span multiple monitors reliably, to show interactive content on more than

a single display.

* wdmiHostAppToFront

This forces the host application to become the frontmost window. This can be used

to quickly hide a video preview window that is not a floating window. It can be

used in combination with previewWindowToFront, to prepare a video input source

and allow its auto-brightness, auto-color, etc. circuitry to settle to an

equilibrium before making the video stream visible on the screen.

* wdmiHostAppInsideRect

This utility method reports the main host application window's position in relation to

the set of monitors connected to the machine, not including any window frames or

caption areas. This can help you use wdmiSetHostAppWindowPosition in order to avoid

showing any window edges or caption bars inside the monitor's viewable area.

* wdmiFilePlayback string fileName, integer registerForGraphEdit

You can use this method to set up an existing AVI file on disk to play back through

this Xtra. This provides some advantages over built in movie playback features

of Director, in that you can route the video to more than one window on more

than one monitor. This can be used to play back video recorded with the Xtra,

or videos produced through other ways.

Returns a list with a single Xtra child object representing a filter graph based on

the AVI file.

* wdmiGetMovieOrPieceWindowPosition

Gets the rectangle of the Director movie or Authorware piece within the host application window

* wdmiGetMovieOrPieceWindowPositionInside

Gets the recangle of the Director movie or Authorware piece within the host applicaiton window,

excluding any title bar or sizing margins.

* wdmiGetMovieOrPieceParentWindowPosition

Gets the rectangle of the parent of the Director movie or Authorware piece within the host

application window. In some cases the parent window of the movie is the same window as the

host app window; in some cases - mostly in the authoring environment -- it is not.

* wdmiGetMovieOrPieceParentWindowPositionInside

Gets the rectangle of the parent of the Director movie or Authorware piece within the host

application window, excluding any title bar or sizing margins. In some cases the parent

window of the movie is the same window as the host app window; in some cases - mostly

in the authoring environment -- it is not.

Child handlers

--------------

objectAddress object me

Used internally by the Xtra - needs not be used by any Lingo scripting or Authorware

calculation icon scripting.

objectType object me

Returns a symbol describing the type of Xtra-defined or DirectShow-defined entity represented

by the Xtra child object.

closeInputSource object me

When you are done using a video or audio input source, close it with this method. The object

will have been returned by the wdmiOpenInputSource, wdmiVideoInputSources or

wdmiAudioInputSources global methods.

closeFilter object me

When you you are done using a DirectShow filter, you should close it. The object will have

come from the list returned by the wdmiDirectShowFilters or wdmiMontivisionImageFilters

global methods.

saveStill object me, string bmpFileName, rect cropRect, integer newWidth,

integer newHeight, symbol evenOddOrBoth

This method saves a still image from the current moment of the video input stream

to a BMP file at the provided full path name on disk. With cropRect you can limit

the area to save to disc to a specific rectangle within the video digitizer's full

input rectangle (useful when an analog video source has visual noise or blank space

at the frame edges). You can determine the video digitizer's full rectangle from

the input formats child object's available information.

You can also smoothly scale the image to a new height or width or both, if the

rectangle you want to use within the video digitizer does not match the

requirements for the BMP file.

Some video digitizers (especially analog video input sources) have even and odd

fields, which represent different moments in time. For instance, in broadcast

analog NTSC television signals, there are roughtly thirty frames a second, but

each frame has two fields, so there are sixty moments in time captured in a

second's worth of video. A still image made from both the even and odd fields

has a tendency to shake because of the difference between the images in the

even and odd lines of the image. Consequently, you can specify #even, #odd

or #both to describe how you want to treat the fields in the saved BMP file.

Using #even or #odd will make a bmp file with a single moment in time. You

may need to use a new width or height factor to produce a correct looking

aspect ratio in the saved BMP file (i.e., to maintain a perfect circle in

the input video stream as a perfect circle in the saved BMP file).

For saveStill to work, the opened input source must have been completely set up

with renderGraph and must be set running with runInput. See other child object

method calls below.

getInputFormat object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID

Returns the input format currently in use by a child object returned by opening an

input source child object.

availableInputFormats object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID

For a child object returned by opening an input source child object, you can ask for

all available input formats. This lets your Lingo make a selection of the resolution,

color format, and video aspect ratio you want to use.

setInputFormat object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID, integer formatIndex

Sets the input format that should be used by a child object returned by openeing an

input child object.

getStillFormat object me

Returns the current still image format used by the opened input source child object.

setStillFormatSubType object me, symbol formatSubTypeSymbol

Sets a subtype for the still format used by the opened input source child object.

getDvDecodingQuality object me

Returns the digitial video decoding quality used by the opened input source child object

representing a MiniDV video camcorder.

setDvDecodingQuality object me, symbol quality

Sets the digital video decoding quality used by the opened input source child object

representing a MiniDV video camcorder. You will get better resolution with a higher

decoding quality.

setStreamStartTime object me, float timeIndex

When capturing a video stream to an AVI movie file on disc, this lets you set a time index

to begin capturing.

setStreamStopTime object me, float timeIndex

When capturing a video stream to an AVI movie file on disc, this lets you set a time index

to end capturing.

getStreamReferenceTime object me

When capturing a video stream to an AVI movie file on disc, this lets you get the current

stream time. This can be useful for showing some sort of progress bar user interface.

prepareForStillFromStream object me

When you will capture single frames from a video input source, you may need to prepare the

DirectShow filter graph by adding certain RGB data transform filters. Use this after

you use renderGraph to prepare the graph, but before you use runInput to set the

video stream going. Compare this to the prepareForStream method, which also is needed

to prepare for still capture. Not all video sources require this prepareForStillFromStream

method, because they might intrinsically handle data in RGB format.

runInput object me

Once a DirectShow filter graph has been rendered, this begins the flow of data through

the graph.

stopInput object me

Once a DirectShow filter graph has been rendered and had runInput used on it, this stops

the flow of data through the graph.

collectStill object me

With a rendered and running filter graph, this indicates that the next frame of video

should be captured.

stillReady object me

Reports whether the collectStill request has been fulfilled yet. when it has, you can

use the saveStill method to preserve the still in a disk file.

resetStill object me

Once you have requested to collect a still and have determined it is ready, and you have

saved it, you can stop the collection of additional still iamges with this method.

connectors object me

An advanced method that reports all the input and ouptut pins of the DirectShow object.

This can be used to build advanced filter graphs that, for instance, send a single

video input stream to two different video windows on different monitors.

currentPin object me, integer outputPinIndex

When a DirectShow filter offers a number of output connections and you can use

only one at a time, this method reports what pin is currently in use.

canConnectPins object me, integer outputPinIndex, integer inputPinIndex

Reports whether the output pin can be connected to the input pin of a filter graph.

connectPins object me, integer outputPinIndex, integer inputPinIndex

Connects an input pin to an output pin.

upstreamConnectors object me

When a DirectShow object has an upstream object supplying it (as, for instance,

a crossbar can select among multiple input soruces), this method lists the

connectors.

upstreamCurrentPin object me, integer outputPinIndex

Reports the current upstream pin for a given output pin.

upstreamCanConnectPins object me, integer outputPinIndex, integer inputPinIndex

Reports whether the output pin can be connected to the input pin of an upstream

connection of a filter graph object.

upstreamConnectPins object me, integer outputPinIndex, integer inputPinIndex

Establishes a connection between an output pin and an input pin of an upstream

connection of a filter graph object.

prepareForStill object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID

Prepares a filter graph to be used to capture still iamges. You may also need

to use prepareForStillFromStream if the video input source does not provide

data in RGB format.

prepareForPreview object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID

Prepares a filter graph to be used to show a preview window

prepareForStream object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID

Prepares a filter graph to be used to capture running video to an AVI file.

renderGraph object me

Once various options have been set in a filter graph, this method asks DirectShow

to complete a full filter graph with all necessary supporting filters.

showPreviewWindow object me

For an object tha has used prepareForPreview, this method actually shows the preview

window. It is not required every to show the preview window.

hidePreviewWindow object me

For an object that has used prepareForPreview, this method hides the preview window

after it has been shown.

sizeablePreviewWindow object me

Adds window gadgets allowing the user to resize the preview window.

unsizeablePreviewWindow object me

Removes window gadgets allowing the user to resize the preview window.

setPreviewWindowTitle object me, string titleString

For a preview window using a caption, this sets the text of the caption.

captionPreviewWindow object me

Sets the preview window to use a caption (title bar).

uncaptionPreviewWindow object me

Sets the preview window not to use a caption (title bar).

floatPreviewWindow object me

Sets a preview window to float above all other non-floating windows on the machine.

This is helpful to prevent mouse clicks on the host application window from sending

the preview window behind the host application.

unfloatPreviewWindow object me

Sets a preview window not to float above all other non-floating windows on the machine.

This means the window can move behind other windows.

getPreviewWindowRect object me

Returns the current location of the preview window, relative to the dimensions of the

set of monitors currently connected to the machine.

setPreviewWindowRect object me, any rectRelativeToStage

Sets the preview window upper left corner, size and width relative to the calling script's

movie's window (typically, the stage, which may be within the host app rectangle).

maxIdealPreviewWidth object me

Returns a maximum width in pixels for the preview window that does not necessitate extra

computation to scale up or to shrink the video input stream's pixels.

maxIdealPreviewHeight object me

Returns a maximum height in pixels for the preview window that does not necessitate extra

computation to scale up or to shrink the video input stream's pixels.

minIdealPreviewWidth object me

Returns a minimum width in pixels for the preview window that does not necessitate extra

computation to scale up or to shrink the video input stream's pixels.

minIdealPreviewHeight object me

Returns a minimum height in pixels for the preview window that does not necessitate extra

computation to scale up or to shrink the video input stream's pixels.

previewWindowToFront object me

Explictly moves the preview window to be the frontmost window of its type (floating or

non-floating). Can be used by a periodic Lingo handler to move a preview window back in

front if a mouse click or other system window drawing event changes window order.

setInputDimensions object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID, integer width, integer height

Sets the width and height to use with a video input source.

setInputDepth object me, any categorySymbolOrGUID, any majorTypeSymbolOrGUID, integer bitDepth

Sets the bit depth to use with a video input source.

getOverlaySourceRect object me

Some video input devices or movie playback devices show their video with a hardware overlay

that is not drawn through the Windows graphical drawing API. This gets the current rectangle

of the input source used by such a device.

getOverlayTargetRect object me

Some video input devices or movie playback devices show their video with a hardware overlay

that is not drawn through the Windows graphical drawing API. This gets the current rectangle

of the output rectangle used by such overlay hardware, with reference to the set of monitors

currently connected to the machine.

setCroppedPreviewRect object me, any cropRect

If you want your preview window to display only a cropped rectangle within the full available

rectangle, supply the rectangle here. This can be useful to cut out blank or noisy edges of

analog video signals.

setMovieFile object me, string aviFileName

When capturing an AVI file, this establishes the full path to the AVI file on disc, before

capture actually begins.

doNotPreviewDVAudio object me

Use this method to specify that the audio of a multiplexed video-audio source such as a

MiniDV video camcorder should be discarded, not played out the speakers, during a preview.

This can be helpful to avoid audio feedback while recording.

closeFilePlayback object me

Closes a filter graph that was created by loading an AVI file.

runFile object me

Starts playback of a filter graph that was created by loading an AVI file.

setPreviewWindowRect2 object me, any rectRelativeToStage

Enable the use of a second preview window at the indicated location and size for a filter

graph. At this time, there is a limit of two preview windows.

setCroppedPreviewRect2 object me, any cropRect

Enables a second preview window's cropping rectangle within the video input digitizer's

full available rectangle to be set.

renderPreviewWindow2 object me

Renders the portion of the filter graph necessary to support a second preview window.

showPreviewWindow2 object me

Shows the second preview window.

hidePreviewWindow2 object me

Hides the second preview window.

fileDuration object me

Reports the total time in an AVI file that has been set up for playback.

fileTime object me

Returns the current time index in an AVI file that is playing back. This can be helpful

in showing a progress bar user interface of some sort.

setAudioVolume object me, float newVolume

Sets the audio volume of an audio input device.

getAudioVolume object me

Gets the audio volume of an audio input device.

setAudioBalance object me, float newBalance

Sets the balance setting of an audio input device.

getAudioBalance object me

Gets the audio balance of an audio input device.

setTunerChannel object me, integer channel, any videoSubchannelIntegerOrSymbol, any audioSubchannelIntegerOrSymbol

For a tuner input device, sets the channel to tune.

getTunerChannel object me

For a tuner input device, gets the channel that is tuned in.

getTunerMode object me

Gets the mode of the tuner input device.

setTunerMode object me, symbol tuneMode

Sets the mode of the tuner input device.

availableTunerModes object me

Returns a list of the available modes of the tuner input device.

availableTunerAudioModes object me

Returns a list of the avaialble audio modes of the tuner input device.

availableTunerHardwareAudioModes object me

Returns a list of the available hardware audio modes of the tuner input device.

getTunerAudioMode object me

Get the current tuner audio mode.

setTunerAudioMode object me, symbol tunerAudioMode

Sets the current tuner audio mode.

lowestTunerChannel object me

Returns the lowest channel to which the tuner can tune.

highestTunerChannel object me

Returns the highest channel to which the tuner can tune.

tunerSignalPresent object me

Returns whether a valid signal is current tuned on the currently set channel.

tunerSetCountryCode object me, integer code

Sets the country code of the tuner.

tunerGetCountryCode object me

Sets the country code of the tuner.

availableTunerFormats object me

Returns the available formats of the tuner.

getTunerFormat object me

Gets the current tuner format.

tunerInputCount object me

Gets the number of tuner inputs (for example, antenna, cable)

getTunerInputType object me, integer inputNumber

Gets the type of the tuner input.

setTunerInputType object me, integer inputNumber, symbol cableOrAntenna

Sets the input type of the tuner (use #cable or #antenna).

addAudioToVideo object me, any audioSourceList

When a filter graph is set up to show audio, you need then to use this method to

add an audio input device, if audio is desired.

addAudioToStream object me

This is used to indicate that any audio in an AVI file should be played back.

addMontivisionImageFilter object me, any montivisionImageFilterList

Adds a proprietary third party DirectShow filter from Montivision to the filter graph.

setMontivisionMirrorDirection object me, symbol directionSymbol

Sets the mirroring direction of a Montivision mirror filter object. Can be

#mirrorHorizontal or #mirrorVertical.

setAudioInputLevel object me, any floatOrSymbol

Sets the audio input device volume level.

getAudioInputLevel object me

Gets the current audio input device volume level.

getAudioInputIsMono object me

Returns whether the audio input device is monaural instead of stereo or multichannel.

setAudioInputIsMono object me, symbol trueOrFalse

Makes an audio input get processed as a monaural signal.

getAudioInputSourceCount object me

Returns the number of audio input sources.

getAudioInputSourceName object me, integer sourceNumber

Gets the name of an audio input source.

setAudioInputSourceLevel object me, any floatOrSymbol, integer sourceNumber

Sets the input volume level of an audio input source.

getAudioInputSourceLevel object me, integer sourceNumber

Gets the input volume level currently in use by an audio input source.

getAudioInputSourceIsMono object me, integer sourceNumber

Gets whether the audio input source is monaural.

setAudioInputSourceIsMono object me, symbol trueOrFalse, integer sourceNumber

Gets whether the audio input source is monaural.

getAudioInputSourceIsEnabled object me, integer sourceNumber

Gets whether the audio input soruce is enabled.

setAudioInputSourceIsEnabled object me, symbol trueOrFalse, integer sourceNumber

Enables or disables an audio input source.