WDMInput Xtra for Macromedia Director and Authorware for Windows

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

Copyright © 2002-2008 Dirigo Multimedia, Inc.

 

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.