DirectX Media Shell Page

DirectX Media SDK DirectAnimation SDK
Direct3D Retained Mode Information
Information Plate Cover
DirectShow SDK
DirectPlay SDK
Direct3D Retained Mode SDK

© 1998 Microsoft Corporation. All rights reserved. Terms of use.


Microsoft DirectAnimation SDK

Welcome to the Microsoft® DirectAnimation™ SDK. Before jumping into any of the reference sections, consider reading the topics in the "Getting Started" and "Programmer's Guide" sections first. These sections provide important overview and conceptual information about DirectAnimation that you will need in other areas of the documentation. For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

Click here to go to the download page for DirectAnimation and DirectShow.

Last Updated: March 27, 1998

Getting Started
Provides general information about Microsoft® DirectAnimation to help you get oriented when first starting.
Guide to Samples
Contains descriptions of the templates, exercises, and showcase samples included with DirectAnimation and step-by-step procedures describing how to create simple animations in JScript, VBScript, and Java, and how to build the C++ samples. When viewed in HTML, includes live links to the DirectAnimation samples. You can also access the samples from the Samples\Da folder.
Scripting Cookbook
Contains simple scripting samples in JScript. Each sample illustrates a basic DirectAnimation construction in its simplest form. The samples include animated lines, arcs, hatching, text, and vectors, and can be cut, pasted, and reused.
DirectAnimation Multimedia Controls
Describes DirectAnimation dynamic HTML multimedia controls.
Programmer's Guide
Discusses a variety of concepts and techniques useful to many types of DirectAnimation authors, such as coordinate systems, URLs and paths, and events in DirectAnimation. Also discusses DirectAnimation behaviors and how to use them, media types (images, geometries, and sound) and the operations that can be performed on them, sequencing, switching, time substitution, integrals and derivatives, and more.
Scripting Reference
Provides detailed reference information about the DirectAnimation functions that make animations accessible to Web authors, script writers, and COM programmers.
Java Reference
Provides detailed reference information about the DirectAnimation Java classes.
Animation Glossary
Defines basic animation terms and how basic animation features are implemented in DirectAnimation.
Tutorials
Describes the construction of some of the Java samples, step by step.
Readme
Contains late-breaking or supplemental information about DirectAnimation.

Note: The icon external link indicates that the link takes you to a URL that is outside the microsoft.com site; you can return to the DirectAnimation site by using the Back button. Note that most of these external links point to servers that are not under Microsoft's control. Please read Microsoft's official statement regarding other servers.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


Getting Started

This section contains the following topics.

  • What is DirectAnimation?
  • Who Should Use DirectAnimation?
  • What Do You Need to Use DirectAnimation?
  • How Can You Use DirectAnimation?
  • The DirectAnimation Samples
  • Documentation Roadmap

What is DirectAnimation?

Microsoft® DirectX® media is a family of high-level APIs and multimedia controls that provide rich support for animation, streaming, and integration of the different media types. Microsoft DirectAnimation™ is the DirectX media component that creates Web animation and integrates dynamic HTML.

DirectAnimation is a COM API and an underlying run time that different users can access in different ways. HTML authors can add multimedia and animation to their pages by using the DirectAnimation controls, without programming at all. You can also animate HTML pages by using Microsoft Visual Basic® Scripting Edition (VBScript), JScript and Java applets. Finally, Java, Visual Basic, and C++ application programmers can develop ActiveX™ Controls or full applications. Thus, DirectAnimation provides multimedia tools that scale from the HTML author to the C++ programmer.

The DirectAnimation SDK provides documentation, samples, and tutorials to help users get started with DirectAnimation.

You can implement DirectAnimation by using the DirectX foundation API and DirectShow™. For a guide on where to find out about particular DirectShow features, see the DirectShow Documentation. For more information about the DirectX foundation components, see http://www.microsoft.com/DirectX/.

Key features of the DirectAnimation API are:

  • Comprehensive support for different media types. 2-D vector graphics, images and sprites, 3-D geometry, video, and sound (including MIDI) are unified in a single animation API.
  • A uniform time and event model that simplifies temporal coordination and interaction of the different media types. This model frees users from frame-level details and provides the foundation for supporting inherently time-based media types such as video and audio.

DirectAnimation provides services that make it easy to build high-performance animation in a variety of environments, such as HTML, VBScript and JScript, Java, and Microsoft Visual C++®. Components include controls for HTML environments and a COM-based animation library accessible from any programming or scripting language.

A set of multimedia run-time controls supply scripting access to some of the DirectAnimation API functions and libraries. The Path, Sequencer, Sprite, and Structured Graphics controls enable you to deliver impressive animation, image, and sound content over the Web with very little code. See DirectAnimation Multimedia Controls for a description of the controls and how to use them. Or see samples to view the control samples.

The following diagram shows the DirectAnimation architecture. The ActiveMovie Control provides an interface to some of the DirectShow API functions. The multimedia controls provide an interface to some of the DirectAnimation library. You can also access the library directly. The DirectAnimation library, in turn, uses the DirectShow API, the DirectX foundation, and certain operating-system services. SG stands for Structured Graphics control and Seq stands for the Sequencer control.

Who Should Use DirectAnimation?

Like other system services such as window management or client/server frameworks, DirectAnimation's functionality supports a number of applications. This documentation focuses on Internet applications.

The multimedia authoring community includes people skilled in a variety of disciplines. From graphics system programmers to creative professionals, Web developers come from many backgrounds and bring as many approaches to the task of producing multimedia for the Web.

Web multimedia developers can be grouped by the tools they use:
Developer | Tools
Creative professional | Painting software, scanners, cameras, image editing software, sound editors
Web site builder | Authoring tools for HTML (Microsoft FrontPage®, for example)
Script writer | JScript, VBScript, HTML source
Application developer | C, C++, Visual Basic, Java, SQL, Active Server, CGI scripts
Graphics systems programmer | Low-level languages (C, C++) and graphics APIs

DirectAnimation serves each of these developers. The multimedia client controls are the quickest approach for common applications, such as sprite sequences or line drawing. The scripting interface for JScript and VBScript adds many animation features in a simple, high-level way. Finally, you can use Java or C++ (or any other COM-enabled language) to access the media and animation library with the full power of an object-oriented, compiled language.

The following table shows the typical ways different developers would access DirectAnimation.
Developer | Accesses DirectAnimation through...
Creative professional | DirectAnimation controls
Web site builder | DirectAnimation controls, DirectAnimation scripting
Script writer | DirectAnimation scripting, DirectAnimation for Java
Application developer | DirectAnimation for Java, DirectAnimation scripting, and C++
Graphics systems programmer | DirectAnimation through native COM, C++, DirectX foundation, and DirectShow

What Do You Need to Use DirectAnimation?

Internet Explorer 4.x contains all the software necessary to view multimedia created with DirectAnimation.

The following list shows what you need to create presentations with DirectAnimation:

  • The DirectAnimation run-time library, which is part of the Internet Explorer 4.x minimal install.
  • The DirectAnimation SDK, which includes samples in JScript, VBScript, Java, and Visual Basic.
  • JScript and VBScript users need only Internet Explorer 4.x to develop animations.
  • Visual Basic, Java, and C++ users need the Microsoft Visual Basic, Microsoft Visual J++®, or Microsoft Visual C++ version 5.x environments or their equivalents. You can also use the DirectAnimation API from VBScript and JScript without compiling.

How Can You Use DirectAnimation?

You can use DirectAnimation in the following ways:

  • As an inline, HTML Web animation through JScript, VBScript, or the DirectAnimation controls.
  • As a Web animation in the form of a Java applet.
  • As a stand-alone application or an ActiveX™ Control implemented through Java, Visual Basic, or C++.
  • To construct animated windowless controls.
  • To animate properties of ActiveX Controls.
  • To load animations asynchronously and hide the load time.

You can access DirectAnimation from JScript, VBScript, Visual Basic, and C++ through the scripting (COM) interfaces directly. Or, you can add DirectAnimation content to your Web pages by using the DirectAnimation controls and setting parameters on these controls; that is, without programming at all. See the DirectAnimation Controls section for more details. Using the DirectAnimation controls directly, or using JScript or VBScript, enables you to describe inline animations with HTML. Such animations can integrate with Dynamic HTML by being windowless on the page (overlaying other elements such as text) or by driving the properties of other entities on the page. You can also import HTML-rendered text and use it as a texture in an animation.

There is a special Java binding for DirectAnimation provided on top of the COM API that takes advantage of specific Java features. For example, operations are overloaded, so that several COM methods that perform similar functions but use different parameter types are given the same name in Java.

The DirectAnimation Samples

The DirectAnimation SDK includes a wide variety of samples to illustrate using DirectAnimation from the different host languages. For each host language there are four categories of samples, as follows:

  • Exercises: Illustrate the most basic use of DirectAnimation.
  • Templates: Provide code that implements common DirectAnimation tasks.
  • Showcases: Demonstrate the breadth of features in the system. Some of them have real-life applications, such as advertising or education.
  • Tutorials: Explain step-by-step details of how to construct some Java samples. These samples include a button labeled Info on the main HTML page that launches a new instance of the browser containing the tutorial, so that you can see the narration side-by-side with the running animation.

Documentation Roadmap

The DirectAnimation documentation is divided into several sections. To help you find the information you need, the following list describes the content of each section and when you will typically use it. For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

  • Getting Started — contains general information about DirectAnimation. Use this section to orient yourself when first starting with DirectAnimation.
  • Guide to Samples — contains a description of the templates, exercises, and showcase samples included with DirectAnimation. When viewing the documents as HTML, you can link directly to each sample described. This section also includes step-by-step procedures describing how to write simple JScript, VBScript, and Java code.
  • Scripting Cookbook — contains basic examples of animation features in JScript, suitable for cutting and pasting.
  • DirectAnimation Controls — contains articles about the DirectAnimation multimedia controls, as well as wizards that allow you to experiment with the controls.
  • Programmer's Guide — contains overview articles covering basic DirectAnimation concepts such as coordinate systems, timelines, and events, plus a detailed discussion of behaviors and media types.
  • DirectAnimation Scripting Reference — contains descriptions of the interfaces and methods used by JScript, VBScript, Visual Basic, and C++ users.
  • DirectAnimation Java Reference — contains descriptions of the DirectAnimation Java classes and interfaces and their methods, event data, a list of default values, and a hierarchy chart.
  • Glossary — contains definitions of basic animation terms and DirectAnimation terms.

The DirectAnimation documentation does not include material on how to program in Java, C/C++, or Visual Basic. Consult the appropriate programming documentation for this information.


Guide to Samples

This article contains descriptions of all the templates, exercises, and showcase samples, plus step-by-step procedures describing how to perform basic Microsoft® DirectAnimation™ tasks.

To go directly to the main sample page for each of the five languages and the DirectAnimation controls, select one of the following:

  • JScript Samples Main Page
  • VBScript Samples Main Page
  • Control Samples Main Page

On the sample main pages you will see a list of all the samples available of that type. To return to the DirectAnimation documentation, choose the Docs button below the left-hand table of contents.

You can also access individual DirectAnimation samples from this Guide to Samples topic by clicking the name of the sample. This will display the sample, but will not take you out of the DirectAnimation documentation and will not display a table of contents listing all the language samples.

See the following sections for descriptions of the samples and step-by-step instructions for building animations. The sample paths refer to the default sample directories create when you install the DirectX Media SDK. You can also access the samples on this Web site by clicking on the links.

When you open a sample it creates a new browser window. Only one sample window will be open at one time. If you minimize the sample window or place the sample window in the background, you have to click the sample window to bring it on top again. You would need to do this, for example, to see the sample window when you open another sample.

  • Samples Overview
  • JScript Samples
  • VBScript Samples
  • Control Samples
  • Java Samples
  • How to Create a JScript Animation
  • How to Create a VBScript Animation
  • How to Build a DirectAnimation Java Applet or Application
  • How to Write a DirectAnimation Java Applet
  • How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces
  • How to Build the DirectAnimation C++ Samples that Use the Windowed Control

Samples Overview

DirectAnimation comes with a wide variety of samples that show you how to use DirectAnimation from different languages. You can cut and paste portions or all of these samples for your own animations. The samples come with a pool of media files, including MIDI, 3-D model, image, video, and sound files. These media files are used by the SDK samples, and are available for use in the DirectAnimation content only. You are not allowed to use these media files in any other fashion.

For each language, there are three categories of samples:

  • Exercises: Illustrate basic use of DirectAnimation at an introductory level.
  • Templates: Provide code that implements common DirectAnimation tasks, such as how to asynchronously download media, use the pixel construction mode, animate HTML and other controls, and sequence animation behaviors along a timeline.
  • Showcase samples: Demonstrate the breadth of features in the system. Some of these samples have real-life applications, such as advertising or education.

The DirectAnimation SDK also contains a set of samples illustrating the DirectAnimation controls.

In addition, the DirectAnimation SDK provides tutorials. Some of the Java showcase samples and most of the Java templates have tutorials that show step-by-step details of their construction. Samples that have associated tutorials include a button labeled Info on the sample's main HTML page. This button launches a new instance of the browser, so that you can see the narration side-by-side with the running animation.

All the examples discussed are in one of the subdirectories in Samples\DA.

JScript Samples

This section describes the JScript Samples included with DirectAnimation. Click any link to display the sample.

This section describes the following types of samples:

  • JScript Exercises
  • JScript Templates
  • JScript Showcase Samples

JScript Exercises

The JScript exercise samples are in the Samples\DA\JScript\Exercises directory. The following table lists the available JScript exercises and the concepts that they illustrate (click any link to display the sample):
JScript exercise name | Description
HelloWorld.html | The HelloWorld JScript sample demonstrates simple text rendering.
StartTime.html | The StartTime JScript sample demonstrates how to use numbers, colors, and string behaviors together. It also demonstrates a cyclic color behavior.
ColorSwitch.html | The ColorSwitch JScript sample demonstrates using Visual Basic buttons to color an animation. It also illustrates modifiable behaviors.
ColorArray.html | The ColorArray JScript sample demonstrates an array with a time-varying index that is used to change colors.
Image.html | The Image JScript sample demonstrates importing an image and rotating it.
ImageOsc.html | The ImageOsc sample demonstrates an oscillating structured graphics image with corresponding MIDI sound.
MeterCoords.html | The MeterCoords JScript sample demonstrates 2-D structured graphics that use the MeterLibrary (instead of the PixelLibrary).
PixelCoords.html | The PixelCoords JScript sample demonstrates 2-D structured graphics that use the PixelLibrary (instead of the MeterLibrary).
Collage3D.html | The Collage3D JScript sample demonstrates how to combine 2-D and 3-D transformations. The transforms include scaling, rotation, translation, and shear.
Movie.html | The Movie JScript sample demonstrates playing a movie in a variable-sized playback window and varying the movie volume with the size of the playback.
Geometry.html | The Geometry JScript sample demonstrates how to import and display an animated geometry (rotating cube), including camera, light, rendering, and 3-D transforms.
AnimatedGlow.html | The AnimatedGlow JScript sample demonstrates a glow filter on a vector graphic using a montage.

JScript Templates

The JScript template samples are in the Samples\DA\JScript\Templates folder. The following table lists the available JScript templates and the concepts that they illustrate (click any link to display the sample):
JScript template name | Description
Basic.html | The Basic JScript sample demonstrates a simple animation (rotating oval) using the core DirectAnimation library. This is useful as a starting point for writing new content.
BasicDS.html | The BasicDS JScript sample is the same animation as Basic but written using the drawing surface API, an API with a slightly different style.
HelloWorldJS.html | The HelloWorldJS JScript sample demonstrates basic text animation as a windowless control.
Resize.html | The Resize JScript sample demonstrates a DirectAnimation control that sizes itself to fit in the browser window.
Cropping.html | The Cropping JScript sample demonstrates a cropped animated image that overlays another variation of itself.
Bounce.html | The Bounce JScript sample demonstrates text bouncing in the browser window, even if the window is resized.
Shapes.html | The Shapes JScript sample illustrates a variety of 2-D structured graphics primitives and fill styles.
AnnotatedLogo.html | The AnnotatedLogo JScript sample demonstrates how to animate HTML text in a coordinated fashion.
Rotational.html | The Rotational JScript sample demonstrates applying 3-D transforms to 2-D structured graphics models.
Sequencing.html | The Sequencing JScript sample demonstrates the mechanisms for sequencing and animation along a timeline. It uses Duration, Repeat, Sequence, and various kinds of transforms. It sequences the transforms with a corresponding text annotation.
CoordsAndPaths.html | The CoordsAndPaths JScript sample demonstrates the pixel construction mode, in which the positive y-axis points downward. It shows SlowInSlowOut interpolation and overlays on an HTML page.
AnimatedProperties.html | The AnimatedProperties JScript sample demonstrates animated strings, numbers, and script callbacks.
Random.html | The Random JScript sample demonstrates how to incorporate periodic randomness into scripting.
JumpURL.html | The JumpURL JScript sample demonstrates a image that interacts with the mouse. When the mouse moves over it, a tip box appears and a sound plays. When you click the mouse on the box, it takes you to another Web page.
BrowserDetect.html | The BrowserDetect JScript sample demonstrates how to detect the type of browser viewing the sample, and to adapt the sample to the browser.
PerspectiveImg.html | The PerspectiveImg JScript sample demonstrates how to render a rotating image in 3-D perspective, while preserving the image's aspect ratios.

JScript Showcase Samples

The JScript showcase samples are in the Samples\DA\JScript\Showcase folder. The following table lists the available JScript showcase samples and the concepts that they illustrate (click any link to display the sample):
JScript showcase name | Description
DxMLogoDots.html | The DxMLogoDots JScript sample shows animation that is coordinated with HTML images specified by IMG tags, using dots that follow the outline of the images. It also demonstrates how to relate between the meter and pixel coordinate systems.
DxMLogoGeo.html | The DxMLogoGeo JScript sample is the same as DxMLogoDots except that the dots are 3-D spotlights.
LightBox.html | The LightBox JScript sample shows how to animate objects along 2-D motion paths. It attaches 3-D spotlights shining into a room. Pressing the left mouse button shows the paths. Two animate points control the audio volume and pan parameters of a looping MIDI sound.
LightBoxBG.html | The LightBoxBG JScript sample is a variation of LightBox, where only the image of the lit room is tiled and used as a background for an HTML page.
Tile.html | The Tile JScript sample shows animated cropping, tiling, and gradient fill colors.
Async_Load.html | The Async_Load JScript sample shows how to use an animation to mask download time for a large media file.
Plane3D.html | The Plane3D JScript sample shows how to construct paths and objects that follow the path. The speed of the object depends on where it is on the path. It also demonstrates the PixelLibrary.
WebVCR.html | The WebVCR JScript sample demonstrates a custom VCR for starting and stopping audio and video playback in a web page, using dynamic HTML.
Eyes.html | The Eyes JScript sample shows an animation that tracks mouse movement.
MSWorldLogo.html | The MSWorldLogo JScript sample shows how DirectAnimation can be used to create Web banners or Web-based advertisements using 3-D objects and vector graphics in an intuitive way.

VBScript Samples

This section describes the VBScript Samples included with DirectAnimation. Click any link to display the sample.

This section describes the following types of samples:

  • VBScript Templates
  • VBScript Showcase Samples

VBScript Templates

The VBScript template samples are in the Samples\DA\VBScript\Templates folder. The following table lists the available VBScript templates and the concepts that they illustrate (click any link to display the sample):
VBScript template name | Description
HelloWorldVBS.html | The HelloWorld VBScript sample demonstrates basic text animation as a windowless control.
Basic.html | The Basic VBScript sample demonstrates a simple animation (rotating oval) using the core DirectAnimation library. This is useful as a starting point for writing new content.
BasicDS.html | The BasicDS VBScript sample is the same animation as Basic but written using the drawing surface API, which has a slightly different style.
Movie.html | The Movie VBScript sample demonstrates how to play a movie.
AudioMixing.html | The AudioMixing VBScript sample demonstrates how to mix audio. The volume and panning of three sounds are controlled by the positions of the scroll bars.
ButtonSwitch | The ButtonSwitch VBScript sample demonstrates how to use modifiable behaviors and buttons.
ScrollSwitch | The ScrollSwitch VBScript sample demonstrates how to use modifiable behaviors and scroll bars.
SplineLogo.html | The SplineLogo VBScript sample demonstrates a spline that is used both as a boundary of a shape and as an animation path.
Callback.html | The Callback VBScript sample demonstrates how to use a scripting callback with two buttons and a piece of HTML text. Pressing the buttons animates the buttons in 3-D, emits a sound, and moves the HTML text in direction the button indicates.
AnimatedProperties.html | The AnimatedProperties VBScript sample demonstrates animated strings, numbers, and script callbacks.

VBScript Showcase Samples

The VBScript showcase samples are in the Samples\DA\VBScript\Showcase. The following table lists the available VBScript showcase samples and the concepts that they illustrate (click any link to display the sample):
VBScript showcase name | Description
Runners.html | The Runners VBScript sample demonstrates instantiating and sequencing two structured graphics models.
Coffee.html | The Coffee VBScript sample demonstrates how to use montages (2.5-D images).
Pick3.html | The Pick3 VBScript sample demonstrates animated and interactive 3-D .x models rendered as windowless controls over the HTML page.
Clock.html | The Clock VBScript sample demonstrates time-accurate animation of a clock with a radially filled background.
Curves.html | The Curves VBScript sample demonstrates time-varying cubic B-spline curves that are used to clip an image whose opacity is also time-varying. The end result is a windowless control on top of HTML text.
MsCubes.html | The MsCubes VBScript sample constructs 3-D animate cubes with motion GIF texturing. A mouse click stops and starts one aspect of the animation.
DancingTrapzoids.html | The DancingTrapzoids VBScript sample shows rectangles with time-varying colors that chase each other along a trajectory.

Control Samples

All of the control samples are contained in the Samples\DA\Controls folder. The following table shows the available controls samples (click any link to display the sample):
Control sample | Description
AniFilt.htm | The AniFilt DirectAnimation control sample demonstrates how to use dynamic filtering for a cut-out effect on text.
Buttons.htm | The Buttons DirectAnimation control sample demonstrates three-state buttons using sprites.
Clock.htm | The Clock DirectAnimation control sample demonstrates time-accurate animation of a clock with a radially filled background.
Complex.htm | The Complex DirectAnimation control sample demonstrates structured graphics.
Count.htm | The Count DirectAnimation control sample demonstrates using structured graphics and sequencing to control multimedia event timing.
Filter.htm | The Filter DirectAnimation control sample demonstrates using filters, including filter information.
Globe.htm | The Globe DirectAnimation control sample demonstrates mouse interaction with sprites.
Mega.htm | The Mega DirectAnimation control sample demonstrates a splash page using structured graphics.
Path.htm | The Path DirectAnimation control sample demonstrates path controls that move objects around a page.
SG-DrawingSurface.htm | The SG-DrawingSurface DirectAnimation control sample demonstrates using the DirectAnimation library for Drawing Surface operations.
SG-Preserve.htm | The SG-Preserve DirectAnimation control sample demonstrates how to preserve an image's aspect ratio as the window is resized.
SpinIE.htm | The SpinIE DirectAnimation control sample demonstrates spinning the letter E in 3-D.
Textmask.htm | The TextMask DirectAnimation control sample demonstrates how to use text for clipping animate structured graphics on an image background.
Yoyo.htm | The Yoyo DirectAnimation control sample demonstrates mouse interaction with a sprite.

Java Samples

This section describes the Java Samples included with DirectAnimation. Click any link to display the sample.

This section describes the following types of samples:

  • Java Exercises
  • Java Templates
  • Java Showcase Samples
  • Chess Application

Java Exercises

Java exercises provide the Java class files and an HTML file to display the applet. You can run the samples without compiling, but if you modify a sample for your own uses you will need to recompile the Java class files. These samples are subdirectories contained in the Samples\DA\Java\Exercises folder. The following table lists the available Java exercises and the concepts that they illustrate:
Java exercise directory | Description
Apple | The Apple Java sample imports three images, tiles one for the background, animates the transform and opacity of a second, and layers the three images on top of one another.
Geometry | The Geometry Java sample imports and spins a cube on a blue background.
Hello | The Hello Java sample displays a "Hello, World" message on a blue background.
HelloBvr | The HelloBvr Java sample displays a "Hello, World" message with a time-varying color.
HelloRBvr | The HelloRBvr Java sample displays a "Hello, World" message with a time-varying color that reacts to a mouse click by switching to red.
HelloCycle | The HelloCycle Java sample displays a "Hello, World" message with a color that cycles between a time-varying color and a red color when the user clicks the left mouse button.
Image | The Image Java sample imports an image and oscillates an image on a black background.
Import | The Import Java sample imports a media file (an image) and displays the result.
Movie | The Movie Java sample imports and plays a movie repeatedly.
Sound | The Sound Java sample oscillates an image on a black background and attenuates a looping sound.
Switch | The Switch Java sample demonstrates the switcher/switching functionality; in this case, an image and a sound behavior that are switched to new values in reaction to external events.

Java Templates

Java templates provide the Java class files and an HTML file to display the applet. You can run the samples without compiling, but if you modify a sample for your own uses you will need to recompile the Java class files. These samples are subdirectories contained in the Samples\DA\Java\Templates folder. The following table lists the available Java templates and the concepts that they illustrate:
Java template directory | Description
Async_Load | The Async_Load Java sample demonstrates how to use an animation to mask download time for a large media file.
BasicApplet | The BasicApplet Java sample demonstrates a minimal applet.
ButtonPick | The ButtonPick Java sample demonstrates a button that changes color when the mouse pointer is over it or when the user clicks a mouse button.
ExtendedApplet | The ExtendedApplet Java sample demonstrates a basic applet with an animated two-dimensional (2-D) image. This includes initialization, creating the model, and scaling the image to fit the size of the applet's window.
GeoApplet1 | The GeoApplet1 Java sample demonstrates a basic applet with an animated geometry. It includes the use of viewport dimensions to scale the geometry, and basic camera settings to render an animated geometry.
GeoApplet2 | The GeoApplet2 Java sample demonstrates an applet that self-controls the frame generation through the tick interface and animates primarily through switching behaviors. Effectively, this looks like a traditional retained mode API such as Direct3D Retained Mode.
GeometryDrag | The GeometryDrag Java sample demonstrates a draggable geometry.
IE4_Windowless | The IE4_Windowless Java sample demonstrates how to construct a windowless control based on a DirectAnimation Java applet.
ImageDrag | The ImageDrag Java sample demonstrates a draggable image.
JumpURL | The JumpURL Java sample demonstrates how to create a pickable image that jumps to a Web site when clicked, and plays a sound and displays a message when the mouse pointer is over it.
Splines | The Splines Java sample demonstrates how to use splines as paths and behaviors.
Using_AFCMenus | The Using_AFCMenus Java sample demonstrates using AFC (Applet Foundation Classes) to create menus in DirectAnimation.
Using_AFCScrollBar | The Using_AFCScrollBar Java sample demonstrates using AFC (Applet Foundation Classes) to create a scroll bar in DirectAnimation.
Using_VBScript | The Using_VBScript Java sample demonstrates using VBScript objects in conjunction with an animation applet.
VCR | The VCR Java sample demonstrates how to control the rate of video playback.

Java Showcase Samples

Java showcase samples provide the Java class files and an HTML file to display the applet. You can run the samples without compiling, but if you modify a sample for your own uses you will need to recompile the Java class files.

These samples are subdirectories contained in the Samples\DA\Java\Showcase folder. The following table lists the available Java showcase samples and the concepts that they illustrate:
Java showcase directory | Description
Album3D | The Album3D Java sample constructs a 3-D photo album that enables you to flip through the pages. It shows a state machine that controls the interaction with the album, including the visual animation and corresponding stereo sound effects.
Americana | The Americana Java sample contrasts autonomous animation and interaction. It shows composition of sprites, how to use interactive sprite animation as a texture on 3-D objects, and the use of Visual Basic buttons to interact with the animation.
CityScape | The CityScape Java sample shows 3-D overlaying a sprite animation with hot spots, live URLs, and sound effects.
Coffee | The Coffee Java sample shows animated montages with sound.
Encarta | The Encarta Java sample illustrates a streaming advertisement. Features include 2-D/3-D interplay, including the use of interactive animations as textures in 3-D, punctuation of the advertisement with MIDI audio, and asynchronous download of media for fast startup time. It also illustrates 3-D animation with audio and camera, 2-D sprite animation with audio and affine transforms applied to sprites, 2-D vector graphics with interactivity, and video with a control panel for play, pause, fast forward, and rewind.
FifteenPuzzle | The FifteenPuzzle Java sample constructs a classic 15-image sorting puzzle using video, 2-D, and 3-D animations as images on the puzzle, which also has a 3-D mode.
GeoImage | The GeoImage Java sample shows 2-D/3-D interplay and the synchronization between a visual animation and a sound effect.
Lighthouse | The Lighthouse Java sample illustrates the use of 3-D in a 2-D composition space by adding 3-D animate and interactive elements to a sprite animation background. This sample also illustrates the use of synthetic sound for the ocean ambient sound.
Magnify | The Magnify Java sample integrates 2-D and 3-D images and sound, and creates a magnifying glass controlled by the user. It illustrates compound compositions in DirectAnimation, first in the magnifying glass and second in texturing the animations on the 3-D parts.
MsCubes | The MsCubes Java sample illustrates tumbling cubes textured with motion .gif files. Includes MIDI sound.
Pick3 | The Pick3 Java sample demonstrates 3-D picking on a significantly changing image.
Solar | The Solar Java sample shows several textured 3-D objects with sound sources, illustrates spatialization and mixing of sound, and has a simple 2-D user interface for restricted manipulation of the camera.
Tile | The Tile Java sample demonstrates animated cropping and tiling.
Union | The Union Java sample demonstrates a cluster of geometry with color and transform behaviors, and a simple looping background sound.

Chess Application

The Java Chess application demonstrates how to import and view an animated playback of chess games from PGN (Portable Game Notation) files. You can move forward and backward in the games, rotate the board, and zoom in or out.


How to Create a JScript Animation

The DirectAnimation library works with the DirectAnimation integrated-media control (DAViewerControl). Library calls are made through a scripting language, such as JScript or VBScript, to construct an animation and play it from an HTML file.

The following steps show how to construct a simple DirectAnimation control in JScript.

  1. In your HTML file, declare your DAViewerControl object. The object's name can be anything. Here, it is called DAControl. The CLSID must be as shown:
    <DIV ID=controlDiv>
<OBJECT ID="DAControl"
    STYLE="position:absolute; left:10; top:10;width:500;height:450"
    CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>
  2. Define your script language.
    <SCRIPT LANGUAGE="JScript">
<!--
  3. Extract either the PixelLibrary or MeterLibrary from your control.
       m = DAControl.PixelLibrary;

    — or —

       m = DAControl.MeterLibrary;

    The variable m is shorthand for the DAStatics Library. Every function and property that is in that library needs to be preceded by this variable so the interpreter knows where to find them.

  4. Write your code. When you have created the image or sound you want to display (which can be as elaborate as you like), set it to the DAViewerControl's Image property or Sound property. In this case, the Image property is set to a solid blue plane that covers the screen:
       DAControl.Image = m.SolidColorImage(m.Blue);
  5. Render the image or sound with the DAViewerControl subroutine Start():
       DAControl.Start();
  6. Close the JScript scripting section:
    //-->
</SCRIPT>


How to Create a VBScript Animation

The DirectAnimation library works with the DirectAnimation integrated-media control (DAViewerControl). Library calls are made through a scripting language, such as JScript or VBScript, to construct an animation and play it from an HTML file.

To construct a simple DirectAnimation control in VBScript:

  1. In your HTML file, declare your DAViewerControl object. The object's name can be anything. Here, it is called DAMyCtl. The CLSID must be as shown:
    <OBJECT ID="DAMyCtl"
   STYLE="position:absolute; left:30%; top:100;width:300;height:300"
   CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
  2. Define your script language.
    <SCRIPT LANGUAGE="VBScript">
<!--
  3. Extract either the PixelLibrary or MeterLibrary from your control.
       Set m = DAMyCtl.PixelLibrary

    — or —

       Set m = DAMyCtl.MeterLibrary
  4. Write your code. When you have created the image or sound you want to display (which can be as elaborate as you like), set it to the DAViewerControl's Image property or Sound property. In this case, the DAViewerControl Image property is set to a solid blue plane that covers the screen:
       DAMyCtl.Image = m.SolidColorImage(m.Blue)
  5. Render the image or sound with the DAViewerControl subroutine Start:
       DAMyCtl.Start
  6. Close the VBScript scripting section:
    -->
</SCRIPT>


DirectAnimation Animated Header --How to Build a DirectAnimation Java Applet or Application DirectAnimation Animated Header --How to Build a DirectAnimation Java Applet or Application * Microsoft DirectAnimation SDK
  * Previous Topic: How to Create a VBScript Animation
  * Next Topic: How to Write a DirectAnimation Java Applet

How to Build a DirectAnimation Java Applet or Application

This section discusses three methods you can use to build a DirectAnimation Java applet or application.

In Microsoft Visual J++™:

  1. From the File menu, choose New.
  2. From the dialog box that appears, choose the Projects tab.
  3. Select Java Project as the project type, type a name into the Project name text box, type a path into the Location text box, and then click OK. The Java project is created.
  4. From the Project menu, choose Add To Project, and then choose Files from the submenu that appears.
  5. In the Insert Files into Project dialog box that appears, browse for your .java files, select the files you want to add, and then click OK.
  6. From the Build menu, choose Build MyApp where MyApp is your project's name. The .class files are built, and a test HTML file is generated automatically.

With the Jvc compiler from the command line:

The Jvc.exe Java compiler is delivered with Visual J++ and the Microsoft SDK for Java.

  1. Set your environment path to include the location of Jvc.exe. For example:

    set path=c:\"program files"\devstudio\sharedide\bin

    or:

    set path=c:\java\sdk\bin
  2. Go to the directory containing the .java files.
  3. At the command line prompt, type:

    jvc *.java

    The class files will be generated. No test HTML will be generated.

With NMAKE and a sample or template makefile

  1. Set your environment path to include the location of NMAKE.exe. For example:

    set path=c:\"program files"\devstudio\vc\bin
  2. Set your environment path to include the location of Jvc.exe. For example:

    set path=c:\"program files"\devstudio\sharedide\bin
  3. Go to the directory containing the makefile.
  4. At the command line prompt, type:

    NMAKE


DirectAnimation Animated Header --How to Write a DirectAnimation Java Applet DirectAnimation Animated Header --How to Write a DirectAnimation Java Applet * Microsoft DirectAnimation SDK
  * Previous Topic: How to Build a DirectAnimation Java Applet or Application
  * Next Topic: How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces

How to Write a DirectAnimation Java Applet

See the BasicApplet.java file in Samples\DA\Java\Templates\BasicApplet.

Every DirectAnimation applet has two main pieces: the DXMApplet class and the Model class. The following steps show how to construct and initialize a simple DirectAnimation applet.

  1. Import the media libraries.

    import com.ms.dxmedia.*;

    If you import multimedia files using URLs, you must also import the Java libraries with:

    import java.net.*;
  2. Define the applet class. This class extends the DXMApplet class. Then, set the model in the init method. Always call the superclass's init first to ensure that the applet's base URL (the directory in which the applet is located) is set. The model you set with the setModel method is the model that is displayed.

    //
    // Class: MyApplet
    //
    class MyApplet extends DXMApplet {

        public void init() {
              super.init() ;

            // Now set the model.
        setModel(new MyModel());
           }
    }
  3. Define the model class. This class extends the Model class. You construct your animation with the createModel method. The following code example constructs a solid blue image.

    //
    // Class: MyModel
    //
    class MyModel extends Model {

           public void createModel(BvrsToRun blist){
    // Set the image that actually gets displayed
          setImage(solidColorImage(blue));
           }
    }
  4. Compile the code with the Jvc compiler.
  5. Insert the applet in an HTML page.

    <title>
    My Applet
    </title>
    <hr>
    <applet code=MyApplet.class width=200 height=200>
    </applet>
    <hr>


DirectAnimation Animated Header --How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces DirectAnimation Animated Header --How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces * Microsoft DirectAnimation SDK
  * Previous Topic: How to Write a DirectAnimation Java Applet
  * Next Topic: How to Build the DirectAnimation C++ Samples that Use the Windowed Control

How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces

To build the DirectAnimation C++ samples from the command line, follow these steps:

  1. Make sure that the directories containing the Danim.dll, Ddrawex.h, and Guids.lib files are in your computer's path, include, and lib environment, respectively. For example:

SET LIB=c:\dxmedia\lib\;

    If you are using untilNotify, make sure that Daguid.lib is also in your lib environment.

    Danim.dll should be located in the Windows\System directory for Windows 95 or Windows\System32 directory for Windows NT; Internet Explorer 4.x installs it.

    If you can't find Ddrawex.h, Guids.lib, or Daguid.lib on your computer, there are copies in the Include and Lib directories of the DirectX Media SDK.

  2. Go to the directory where the samples are located and run NMAKE. Note that for the C++ samples included in this SDK, the Release build is the default build.

To build DirectAnimation C++ samples in Microsoft Visual C++ 5.x, set the paths as described in Step 1, and then follow these steps:

  1. Start Microsoft Visual C++ 5.x and create a new Win32 application.
  2. From the Project menu, choose Settings, and then choose the Link tab.
  3. Select General in the Category drop-down list.
  4. Add Guids.lib (and Daguid.lib if using untilNotify) to the Object/library modules text box.
  5. Click OK.
  6. From the Project menu, choose Add To Project, and then select Files and insert the DirectAnimation C++ files to the project.
  7. Press the F7 key to build.


DirectAnimation Animated Header --How to Build the DirectAnimation C++ Samples that Use the Windowed Control DirectAnimation Animated Header --How to Build the DirectAnimation C++ Samples that Use the Windowed Control * Microsoft DirectAnimation SDK
  * Previous Topic: How to Build the DirectAnimation C++ Samples that Render to DirectDraw Surfaces
  * Next Topic: Scripting Cookbook

How to Build the DirectAnimation C++ Samples that Use the Windowed Control

To build the DirectAnimation C++ samples from the command line, follow these steps:

  1. Make sure that the directories containing the Danim.dll and Ddrawex.h files are in your computer's path, include, and lib environment, respectively. For example:

SET LIB=c:\dxmedia\lib\;

    If you are using untilNotify, make sure that Daguid.lib is also in your lib environment.

    Danim.dll should be located in the Windows\System directory for Windows 95 or Windows\System32 directory for Windows NT; Internet Explorer 4.x installs it.

    If you can't find Ddrawex.h or Daguid.lib on your computer, there are copies in the Include and Lib directories of the DirectX Media SDK.

  2. Go to the directory where the samples are located and run NMAKE. Note that for the C++ samples included in this SDK, the Release build is the default build.

To build DirectAnimation C++ samples in Microsoft Visual C++ 5.x, set the paths as described in Step 1, and then follow these steps:

  1. Start Microsoft Visual C++ 5.x and create a new Win32 application.
  2. From the Project menu, choose Add To Project, and then select Files and insert the DirectAnimation C++ files to the project.
  3. Press the F7 key to build.

If you are using untilNotify, you need to perform the following additional steps before you build:

  1. From the Project menu, choose Settings, and then choose the Link tab.
  2. Select General in the Category drop-down list.
  3. Add Guids.lib (and Daguid.lib if using untilNotify) to the Object/library modules text box.
  4. Click OK.


Scripting Cookbook

The Scripting Cookbook is a collection of samples designed to introduce you to the rudiments of scripting in Microsoft® DirectAnimation™. Each sample is written in JScript and illustrates a single concept, such as displaying text or drawing rectangles. The HTML source code is heavily commented. To see the HTML source code, right-click the title above the Show button and choose View Source from the menu that appears.

Don't be afraid to experiment. Try changing the values in the samples to see what happens. It is assumed that you are already familiar with JScript and elementary programming concepts such as functions and arrays. Also, be sure to look at the simple scripting exercises in the JScript\exercises directory. These are complementary to the material in this section.

3-D Cube

Arcs

Button

Matte

Opacity

Pies

Rectangles

Rotations

Text

Vectors


3-D Cube

This example displays a three-dimensional cube. To display a 3-D object, use some sort of lighting and a camera. For lighting, this demonstration uses both a PointLight and a DirectionalLight. To render the image, it uses a PerspectiveCamera. To make it clearer that the cube is three-dimensional, we rotate it around the x-axis with the Rotate3Anim function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Arcs

This example demonstrates how to draw arcs. It uses the ArcDegrees and the ArcRadiansAnim functions. It also shows how to use an arc as a path with the FollowPath function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Button

This example displays a button that, when you click on it, goes to the Microsoft home page. To make the button, we first draw a square and made it pickable, using the Pickable function. This means the image recognizes when the mouse is within its bounding box. The blue square turns red when this happens. On a left-button click, the button transfers you to the Microsoft home page. This is done with the ScriptCallback function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Matte

This example displays a simple text matte. A matte is analagous to a stencil. In this example, the word "Matte" acts as the stencil, and an image (a SolidColorImage) with a time-varying color is clipped to fit it. An animated matte is also demonstrated. This uses a variety of transforms, including translation, rotation, shearing, and scaling. To see what each of these do, comment out all the transforms but one.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Opacity

This example demonstrates opacity, or how transparent an image or geometry is. It uses the Opacity function to show what an image looks like at different opacity levels. It also uses the OpacityAnim function for a time-varying opacity.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Pies

This example demonstrates how to draw pies. These are segments of ovals connected to the origin (in effect, pie-shaped wedges). It uses the PieDegrees and the PieRadiansAnim functions. It also shows how to use a pie as a path with the FollowPath function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Rectangles

This example demonstrates how to create a rectangle and turn it into an image that can be rendered. An animated rectangle, with a width that varies over time is also shown. Finally, a rectangle is used as a path rather than as an image. A line of text traces out the path. (This also demonstrates the FollowPath function.)

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Rotations

This example demonstrates some simple rotations, using several of the rotate functions. Examples include both clockwise and counterclockwise rotations, use of the SubstituteTime function, and rotating a two-dimensional image in a three-dimensional space, using the ParallelTransform2 function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Text

This example demonstrates how to display text as well as how to set the font and various attributes. It also shows an animated example, where the font cycles through three values, changing every 2 seconds.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


Vectors

This example shows a face whose eyes track the mouse. This is done with two-dimensional vectors. The face is drawn using the Polyline function.

To see the source code, right-click the title above the button and choose View Source from the menu that appears.


DirectAnimation Multimedia Controls

The Microsoft® DirectAnimation™ multimedia controls give you the capability to deliver impressive vector graphics, images, and animation content over the Web without incurring long download times.

  • Path Control Move objects around the page over time, in geometric or spline patterns, with control over speed of motion, forward or reverse playback, looping and bouncing behavior. Sample

  • Sequencer Control Create complex sequences of action involving ActiveX™ Controls, scripts, or dynamic HTML elements. Sample

  • Sprite Control Add still and animated images to your Web page with control over playback speed, forward or reverse playback, dynamic seeking to different positions in the sprite playback, and user interactivity on a frame-by-frame basis. Sample

  • Structured Graphics Control Add extremely lightweight vector graphics to your Web page, fully capable of being scaled or rotated in three dimensions, and then easily apply solid colors, patterns, gradient fills, or bitmap textures to these graphics. Sample

In addition to the controls, this section contains topics that discuss mouse events and a Windows metafile utility.

  • Mouse Events This section describes the MouseEventsEnabled Property and mouse events that enable your control to respond to the mouse.
  • Windows Metafile to Structured Graphic Converter This section describes a utility to convert Microsoft Windows® metafiles into PARAM tags.

The Path wizard sample generates basic code for moving an object around, the Rotating Text Logo wizard (Structured Graphics and Sequencer) sample generates a vector graphic text logo that rotates in three dimensions, and the Polygon Path wizard sample generates a polygon-shaped path.

Note For sound and mixing functionality, see the ActiveMovie Control in the Microsoft DirectShow™ documentation.

Documentation Conventions

Use of PARAM Tag Syntax vs. Script Syntax

Several DirectAnimation controls are documented with both PARAM tag syntax and script syntax.

PARAM tag syntax is generally used for setting parameters during object instantiation as part of an OBJECT tag. In some cases, only PARAM tag syntax can be used. In these cases, only PARAM tag syntax will be documented.

Script syntax is used in Microsoft® Visual Basic® Scripting Edition (VBScript), Microsoft JScript™, or other scripting languages to set initial values or change them during script execution. You should observe case sensitivity to ensure that scripts work as written.

The presence of both types of syntax indicate that you can set the object's parameters or call initialization methods at object instantiation on the HTML page (in the OBJECT tag), or in script. In this event, it is up to you, the author, to determine which syntax best suits your needs. For instance, you could use the PARAM tag syntax to initialize your object and then use script syntax to change it thereafter.

JScript Note When setting a series of optional parameters, JScript requires that any parameters in the middle of the series be present, not just replaced by a space. For example, if you have three optional parameters and only want to set values for parameters 1 and 3, you still need to enter a value for parameter 2 in order for parameter 3 to be read properly.


Path Control

The Path control is a windowless Microsoft® DirectAnimation™ control that animates the position of other controls along a defined vector or spline shape-based path.

To use the Path control, you must first instantiate it on the HTML page, as shown in the following syntax:

Syntax

<OBJECT ID=object
CLASSID="CLSID:D7A7D7C3-D47F-11d0-89D3-00A0C90833E6">
[<PARAM NAME="property" VALUE="setting">]
</OBJECT>

Parameters
object | String identifying the object.
property | One of the properties in the following table.
setting | Value for the property.

Path Control Properties
Property | Description
AutoStart | Determines whether the Path control starts playback upon loading.
Bounce | Sets the path behavior to either reverse direction and return to the beginning, or stop at the end of its playback.
Direction | Sets the direction of the path playback.
Duration | Sets the duration of the path playback.
Library | Retrieves the DirectAnimation library reference.
PlayState | Retrieves the path's current playback state.
Relative | Determines whether the Path control starts playing from its current position or from the absolute position in the target object's coordinate space.
Repeat | Sets the number of times the path loops during playback.
Target | Sets the object that will follow the path.
Time | Retrieves the elapsed playback time from the start of the path.
TimerInterval | Sets or retrieves the length of time, in seconds.milliseconds, between path updates.

Path Control Methods
Method | Description
AddTimeMarker | Sets a marker to fire an event when playback reaches the marker position.
Oval | Specifies an oval structured graphics primitive to be used as the path, with starting point at top center (12 o'clock)
KeyFrame | Specifies points along the path, in x, y coordinates, and a designated time to reach each point.
Pause | Stops playback and maintains current elapsed time.
Play | Begins playback from the current elapsed time.
Polygon | Specifies a closed series of line segments to use as the path.
PolyLine | Specifies an open set of line segments to use as the path.
Rect | Specifies a rectangular structured graphics primitive to use as the path, with starting point at top left.
Seek | Resets the current playback position to a new, specified position.
Spline | Specifies a spline to be used as the path.
Stop | Stops playback at current elapsed time and returns path to the beginning.

Path Control Events
Event | Description
onmarker | Occurs when the path playback reaches a marker at the specified playback position, either when the Path control is playing or when it is stopped (and reaches the marker through a Seek call, for example).
onpause | Occurs when path playback pauses.
onplay | Occurs when the Path control plays back.
onplaymarker | Occurs when path playback reaches a marker at the specified playback position.
onseek | Occurs when the Path control completes a Seek call.
onstop | Occurs when path playback stops.

AutoStart Property

Path Control

Determines whether the path starts playback immediately after loading. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="AutoStart" VALUE=0 | -1>

Script Syntax

object.AutoStart=[fStart]

Parameters
object
String identifying the Path object.
fStart
Starts playback as soon as the path is loaded if True (–1 or nonzero) or, if False (0), simply loads and does not play until explicitly started with the Play method. The default value is False.

Bounce Property

Path Control

Sets the path to either stop at the end of the path or reverse direction and continue playback. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Bounce" VALUE=0 | -1>

Script Syntax

object.Bounce=[fBounce]

Parameters
object
String identifying the Path object.
fBounce
Stops playback at the end of the path if False (0), or reverses direction and continues playback if True (–1 or nonzero). The default value is False.

Direction Property

Path Control

Sets the direction of the path playback, either forward or reverse. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Direction" VALUE=0 | 1>

Script Syntax

object.Direction=fDirection

Parameters
object
String identifying the Path object.
fDirection
Forward (0) or reverse (1). Default setting is 0.

Duration Property

Path Control

Sets the duration of the path playback. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=" Duration" VALUE=" time ">

Script Syntax

object.Duration=[ time ]

Parameters
object
String identifying the Path object.
time
Double value, format 0.000 (seconds.milliseconds), that sets the length of time for the object to move from start to end of the path.
Remarks

The Duration property does not take Bounce behavior into account. If the path is set to bounce, the Duration property sets the time between the start and the end of its playback, and does not include the time when the path behavior reverses direction and returns to the start of the path.

Library Property

Path Control

Retrieves the reference to the DirectAnimation library functions.

Script Syntax

IDALibrary=object.Library

Parameters
IDALibrary
DirectAnimation library pointer.
object
String identifying the Path object.

Playstate Property

Path Control

Retrieves the path's playback state: stopped, playing, or paused. Read-only at run time.

Script Syntax

state=object.Playstate

Parameters
state
Playback state of the Path object; 0 if stopped, 1 if playing, 2 if paused.
object
String identifying the Path object.

Relative Property

Path Control

Determines whether the Path control starts playing from its current position or from the absolute position in the target object's coordinate space. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=Relative VALUE=0 | -1>

Script Syntax

object.Relative=fPos

Parameters
object
Path object.
fpos
True (–1 or nonzero) or False (0). If True, then the path playback starts from the target's current position. If False, then the path playback starts from the absolute position in the target's coordinate space. (For example, if you are using a Rect path, the absolute position starting point is the top left.) The default value is False.
Remarks

The Relative property means relative to the target object's position. The target object's position is set to relative or absolute with the STYLE="POSITION: ABSOLUTE | RELATIVE" attribute.

Relative Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Repeat Property

Path Control

Sets the number of times the path loops playback. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=" Repeat " VALUE=nRepeat >

Script Syntax

object.Repeat=[ nRepeat ]

Parameters
object
String identifying the Path object.
nRepeat
Integer expression setting the number of times the path repeats playback. Default value is 1. Set to –1 to cause the path to repeat infinitely; other negative values are treated as unsigned. Set to 0 to disable the Repeat property.

Target Property

Path Control

Sets the object to follow the path. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=" Target" VALUE=" objTarget ">

Script Syntax

object.Target=[ objTarget ]

Parameters
object
String identifying the Path object.
objTarget
String identifying the path's target object.
Remarks

The target object must have an initial position. This can be set with the target object's STYLE attribute, as shown in the following examples:

<IMG SRC="target1.gif" ID="target1" STYLE="position:relative">

— or —

<IMG SRC="target1.gif" ID="target1" STYLE="position:absolute; left=100; top=100">

Target Property example

Right-click inside the frame and select View Source to see the HTML code for this example.

Time Property

Path Control

Retrieves the elapsed playback time (in milliseconds) from the start of the path playback. Repetitions set with Repeat are included in returned time calculations. Read-only at run time.

Script Syntax

time=object.Time

Parameters
object
String identifying the Path object.
time
Number of milliseconds into path playback. Default value is zero.

TimerInterval Property

Path Control

The default length of time, in seconds.milliseconds, between the path update. Read/write at run time; write access is available at run time only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="TimerInterval" VALUE="nInterval">

Script Syntax

object.TimerInterval=nInterval

Parameters
nInterval
Integer expression giving the minimum number of seconds.milliseconds between path updates. The default interval is 0.100.

AddTimeMarker Method

Path Control

Adds marker at specified playback position, enabling author to generate an event when that playback position is reached. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=" AddTimeMarkerX" VALUE=" time,
markername ,
[ 0 | -1 ]">

Script Syntax

object.AddTimeMarker (
time,
"markername",
[fAbsolute] )

Parameters
object
String identifying the Path object.
X
A sequential integer identifying the time marker, starting at 1 (PARAM tag syntax only). If you are adding more than one time marker through PARAM tag syntax, you must make each AddTimeMarker method call distinct by adding an sequential integer at the end of the AddTimeMarker PARAM name.
time
Time at which the onmarker or onplaymarker event fires.
markername
Name of the marker.
fAbsolute
An optional flag that specifies event firing. Default is True. If True (absolute) the event fires at the specified time once and ignores looping. If False (relative) the event fires everytime, including in loops. For PARAM tag syntax, use 0 for False and use –1 or nonzero for True. For script, use the predefined constants True and False.
Remarks

The onmarker event occurs whenever the path is at the specified marker, whether or not the path is playing. The onplaymarker event occurs only when the path is playing.

This example sets three time markers named MyMark, FrameFour, and FrameZero at 0.0, 4.7, and 8.0 respectively. MyMark and FrameZero are set to occur every time the path reaches that time marker, and FrameFour is set to occur only the first time the path reaches that time marker during uninterrupted playback.

<PARAM name="AddTimeMarker1" value="0.0, MyMark, 0">
<PARAM name="AddTimeMarker2" value="4.7, FrameFour, -1">
<PARAM name="AddTimeMarker3" value="8.0, FrameZero, 0">

AddFrameMarker Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

KeyFrame Method

Path Control

Specifies x and y coordinates along the path, and a time to reach each point. The first point defines the path's starting point. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME=" KeyFrame" VALUE=" npoints,
[ x1,
y1 ,
...,
xN,
yN ],
[ time2,
...,
timeN ]">

Script Syntax

KeyFrameArray=Array(
x1,
y,
...,
xN,
yN )
TimeFrameArray=Array(
time2 ,
...,
timeN )
object.KeyFrame(
npoints,
KeyFrameArray ,
TimeFrameArray )

Parameters
object
String identifying the Path object.
npoints
Number of points to be used to define the polyline.
x1, y1,...,xN, yN
Set of x and y coordinates that identify the keyframe points.
time2,..., timeN
Respective times that the path takes to reach each of the respective points from the previous point.
KeyFrameArray
Array that contains the x and y point definitions (script only).
TimeFrameArray
Array that contains the time values between the points that define the path, starting at the x1 and y1 point through xN and yN points (the last set of points in the path). The path begins at point x1 and y1 with a time value of 0. Script only.
Remarks

The Duration property is ignored when this method is invoked.

KeyFrame Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Oval Method

Path Control

Specifies an oval path, with its starting point at the top center point of the oval (12 o'clock position). This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" Oval(
xpos,
ypos,
width,
height
) ">

Script Syntax

object.Oval(
xpos ,
ypos ,
width ,
height )

Parameters
object
String identifying the Path object.
xpos
The x position defining the topmost point of the oval.
ypos
The y position defining the leftmost point of the oval.
width
Width of the oval.
height
Height of the oval.

Oval Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Pause Method

Path Control

Pauses Path playback at current elapsed time and maintains current playback position.

VBscript Syntax

object.Pause

JScript Syntax

object.Pause( )

Parameters
object
String identifying the Path object.

Play Method

Path Control

Begins Path playback at current elapsed time.

VBscript Syntax

object.Play

JScript Syntax

object.Play( )

Parameters
object
String identifying the Path object.
Remarks

Calls to the Play method while a path is playing are ignored.

Polygon Method

Path Control

Specifies a set of closed line segments to use as a path. The first point defines the path's starting point. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" Polygon(
npoints,
[ x1,
y1,
...,
xN,
yN ]
) ">

Script Syntax

PolygonArray=Array(
x1,
y1,
...,
xN,
yN )
object.Polygon(
npoints,
PolygonArray )

Parameters
object
String identifying the Path object.
n_Points
Number of points in the polygon.
x1, y1,..., xN, yN
Set of x and y coordinates that identify the polygon points.
PolygonArray
Array that contains the x and y point definitions (script only).
Remarks

The array of x, y coordinates can be specified either as an array, or as a comma-delimited string of numbers that will be passed into the coordinates.

Polygon Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

PolyLine Method

Path Control

Specifies a set of line segments to use as a path. The first point defines the path's starting point. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" PolyLine (
npoints,
[ x1,
y1,
...,
xN,
yN ]
) ">

Script Syntax

PolyLineArray=Array(
x1,
y1,
...,
xN,
yN )
object.PolyLine (
npoints,
PolyLineArray
)

Parameters
object
String identifying the Path object.
npoints
Number of points to be used to define the PolyLine.
x1, y1,..., xN, yN
Set of x and y coordinates that identify the polygon points.
PolyLineArray
Array that contains the x and y point definitions (script only).

Polyline Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Rect Method

Path Control

Specifies a rectangular path, with its starting point at the top left point of the rectangle. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE="Rect(
xpos,
ypos,
width,
height ) ">

Script Syntax

object.Rect (
xpos ,
ypos ,
width ,
height )

Parameters
object
String identifying the Path object.
xpos
The x position for the starting point of the rectangle.
ypos
The y position for the starting point of the rectangle.
width
Width of the rectangle.
height
Height of the rectangle.

Rect Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Seek Method

Path Control

Seeks to another position in the Path playback.

Script Syntax

object.Seek (
time )

Parameters
object
String identifying the Path object.
time
Double value, format seconds.milliseconds (s.mss) that represents a different path playback elapsed time.

Spline Method

Path Control

Specifies a vector spline to be used as a path. The first point defines the path's starting point. This method can be used or modified only when the path is stopped.

PARAM Tag Syntax

<PARAM NAME="Shape" VALUE=" Spline(
npoints,
[ x1,
y1,
x2,
y2... ]
) ">

Script Syntax

object.Spline (
npoints,
[ x1,
y1,
x2,
y2... ] )

Parameters
object
String identifying the Path object.
npoints
Number of points to be used to define the Spline.
x1
First x point for the spline.
y1
First y point for the spline.
x2
Second x point for the spline.
y2
Second y point for the spline.
Remarks

You need to specify four points for each curve in the spline. You can specify the array of x, y coordinates either as an array or as a comma-delimited string of numbers that will be passed as the coordinate set. The number of points in the spline and their spacing can have an effect on the path's speed. Having too many points too close together along the path can cause the path to seem as if it is slowing down when it traverses those points.

Spline Method example

Right-click inside the frame and select View Source to see the HTML code for this example.

Stop Method

Path Control

Stops playback of the path at the current position and rewinds the path to its beginning.

VBscript Syntax

object.Stop

JScript Syntax

object.Stop( )

onmarker Event

Path Control

Occurs when the path playback reaches a marker at the specified playback position.

VBScript Syntax

Sub object _ onmarker (
markername )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmarker (
markername ) >
script
<SCRIPT>

Parameters
object
String identifying the Path object.
markername
String containing the marker name established in the AddTimeMarker method.
script
Script to be executed.
Remarks

This event occurs whenever playback reaches the marker point, either when the path is playing or stopped. For example, if you seek to the marker position while the path is paused or stopped, the onmarker event will occur.

onpause Event

Path Control

Occurs when path playback is paused.

VBScript Syntax

Sub object _ onpause ( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onpause >
script
<SCRIPT>

Parameters
object
String identifying the Path object.
script
Script to be executed.

onplay Event

Path Control

Occurs when path playback starts.

VBScript Syntax

Sub object _ onplay ( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onplay >
script
<SCRIPT>

Parameters
object
String identifying the Path object.
script
Script to be executed.

onplaymarker Event

Path Control

Occurs when a marker is reached during path playback.

VBScript Syntax

Sub object _ onplaymarker (
markername )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onplaymarker (
markername ) >
script
<SCRIPT>

Parameters
object
String identifying the Path object.
markername
String containing the marker name established in the AddTimeMarker method.
script
Script to be executed.

onseek Event

Path Control

Occurs after a Seek call has been completed.

VBScript Syntax

Sub object _ onseek (
newtime )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onseek (
newtime ) >
script
<SCRIPT>

Parameters
object
String identifying the Path object.
newtime
Double value, format seconds.milliseconds (s.mss), that represents the new different path playback elapsed time.
script
Script to be executed.

onstop Event

Path Control

Occurs when the path stops playing.

VBScript Syntax

Sub object _ onstop ( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onstop >
script
<SCRIPT>

Parameters
object
String identifying the Path object.


Sequencer Control

This section contains reference material for the Sequencer control and its methods and events, plus the following additional topics:

  • Sequencer Control VBScript Example
  • Action Set

The Sequencer control provides timing and sequencing services for action sets, scripts used to control Microsoft® ActiveX™ Controls or scripts on the page. The Sequencer control calls Microsoft JScript™, Microsoft Visual Basic(r) Scripting Edition (VBScript) or other Web scripts.

These procedures are called by the Sequencer control's At Method and can be performed once or they can be looped by the Sequencer control. The Sequencer control calls the named script with the parameter string and the resolved parameter string is executed. Note that this means unresolved parameters don't get executed.

To use the sequencer object, you must first instantiate it on the HTML page, as shown in the following syntax:

Syntax

<OBJECT id=object
    STYLE=""
    CLASSID=clsid:B0A6BAE2-AAF0-11d0-A152-00A0C908DB96>
</OBJECT>

Parameters
object Name of the Sequencer control, to be used in script.

Sequencer Control Methods
Method | Description
At | Specifies a new action in the action set.
Pause | Stops action set playback at current position. Keeps time pointer and queue.
Play | Starts the action set (if stopped). Resumes sequencer playback if sequencer is paused. Ignored if sequencer is playing.
Seek | Changes the current playback position of the action set to a new, specified time.
Stop | Stops action set playback, resets its playback position to the beginning.

Sequencer Control Events
Event | Description
oninit | Occurs when sequencer is first completely loaded into memory.
onpause | Occurs when action set playback has been paused.
onplay | Occurs when the action set has started playback. This event is only called when the action set starts playback from a stopped or paused state, not when a currently playing action set loops back to the beginning to repeat playback.
onseek | Occurs after the Seek method call has been completed.
onstop | Occurs when the action set playback ends or is stopped.

For optimal performance, use only one sequencer on a page with a single action set that calls a lot of actions. You can run multiple sequencers that each execute fewer action sets simultaneously but will get better performance with a single sequencer executing a larger number of action sets.

As the page is loaded, the sequencers used are loaded into memory. You can use the oninit Event to ensure that the sequencers are fully loaded before starting their playback.

Sequencer Control VBScript Example

This sample demonstrates how to use the Sequencer control in VBScript. It rotates text, and allows the user to stop and restart the rotation by clicking a button.

<HTML>
<HEAD>
<TITLE>Microsoft DirectAnimation Controls - Sequencer</TITLE>

<SCRIPT LANGUAGE=VBSCRIPT>

Sub Window_OnLoad
    call sgMSDHTML.SetIdentity
    Button1.value="Pause"
End Sub

Sub Seq_oninit
    call seq("ActionSet1").At(0.000, "RotateAll",-1, 0.050, 1)
    Call Seq("ActionSet1").Play
End Sub

Sub RotateAll
    Call sgMSDHTML.Rotate(0,9,2)
End Sub

Sub Start
    Select Case Button1.value
    Case "Play"
        Call Seq("ActionSet1").Play
        Button1.value="Pause"
    Case "Pause"
        Call Seq("ActionSet1").Pause
        Button1.value="Play"
    End Select
End Sub

</SCRIPT>
</HEAD>

<BODY BGCOLOR=BLACK>

<OBJECT ID=sgMSDHTML
STYLE="POSITION: ABSOLUTE; HEIGHT:300;WIDTH:450;TOP:100;LEFT:60;VISIBILITY:VISIBLE; ZINDEX:-1"
CLASSID="CLSID:369303C2-D7AC-11d0-89D5-00A0C90833E6">
<PARAM NAME="Line0001" VALUE="SetLineColor(255,255,255)">
<PARAM NAME="Line0002" VALUE="SetFillColor(0,0,255)">
<PARAM NAME="Line0003" VALUE="SetFillSTYLE(1)">
<PARAM NAME="Line0004" VALUE="SetLineSTYLE(1)">
<PARAM NAME="Line0005" VALUE="SetFont('Verdana',60,650,0,0,0)">
<PARAM NAME="Line0006" VALUE="Text('Microsoft', -120, -100, 0)">
<PARAM NAME="Line0007" VALUE="Text('Dynamic', -120, -50, 0)">
<PARAM NAME="Line0008" VALUE="Text('HTML', -90, 0, 0)">
<PARAM NAME="Line0009" VALUE="Text('Multimedia', -120, 50, 0)">
</OBJECT>

<OBJECT ID="Seq"
    CLASSID="CLSID:B0A6BAE2-AAF0-11d0-A152-00A0C908DB96"
    STYLE="WIDTH:2;HEIGHT:2">
</OBJECT>

<INPUT TYPE=button ID="Button1"
STYLE="POSITION:ABSOLUTE; TOP:10; LEFT:10; z-index:2; VALUE=""; OnClick="Start">

</BODY>
</HTML>

Action Set

An action set is a logical grouping of named procedures that are used to control the timing and behavior of objects on the page. Action sets have the following properties:
Name | Description
PlayState | Retrieves the current playback state of the action set: 0=stopped, 1=playing, 2=paused. Read-only at run time.
Time | Retrieves the elapsed time in format seconds/milliseconds (SS.MSS) since the start of action set playback, including iterations. The default setting is zero. Read-only at run time.

PlayState Property

Action Set

Retrieves the state of the sequencer. Read-only at run time.

VBScript Syntax

playstate=object(
"actionsetname"
) .PlayState

JScript Syntax

playstate=object.item(
"actionsetname"
) .Playstate

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.
Return Values

Returns an integer that indicates the sequencer's play state. Possible values are 0 (stopped), 1 (playing) or 2 (paused).

Time Property

Action Set

Represents the amount of time since the start of the sequencer's playback. Read-only at run time.

VBScript Syntax

Time=object(
"actionsetname"
) .Time

JScript Syntax

Time=object.item(
"actionsetname"
) .Time

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.
Return Values

Returns a floating-point value that contains the elapsed sequencer playback time in the format seconds.milliseconds (SS.MSS).

At Method

Sequencer Control

Specifies an action to take place within an action set.

VBScript Syntax

call object(
"actionsetname"
).At(
time,
"script",
[loop,
interval,
tiebreak,
drop threshold]
)

JScript Syntax

object.item(
"actionsetname"
).At(
time,
"script",
[loop,
interval,
tie break,
drop threshold]
);

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.
time
Required. Double value in seconds.milliseconds (SS.MSS) format. Sets the start time for the specified action.
script
Required. Text string identifying the named procedure to be called. Can pass parameters as part of the script call, for example, script(param1)
loop
Optional. Integer. Sets the loop count for this action. The default is 1. If set to –1, looping is infinite. Any negative number other than –1 will be treated as 0. Zero loop count value prevents execution. You can use this to programmatically halt action set execution.
interval
Optional. Double value in seconds.milliseconds (SS.MSS) format. Sets the delay between iterations of the specified action. Minimum interval resolution is 20 milliseconds (00.020). The default is 33 milliseconds (00.033), equivalent to 30 frames per second.
tie break
Optional. Integer whose value can be –1, 0, or a positive integer. The default is –1. Sets the priority for the action. In the event that two actions happen at the same time, the action with the lower tie break number will be performed first. Zero is the highest priority action that can be dropped; –1 is the lowest-priority action and will be executed last.
drop threshold
Optional. Double value in seconds.milliseconds (SS.MSS) format. Sets the time by which the action must be performed before it is dropped from the queue. The default value is for the action to never be dropped (–1.000).
Remarks

The drop threshold parameter is useful for optimizing sequencer performance by streamlining the number of actions that the sequencer has to perform at any given moment; for instance, when starting up a complex action set. Thoughtful use of this parameter can keep the sequencer from slowing down or speeding up from backlog of actions to be executed, and keep the timing of actions within reasonable tolerances.

Pause Method

Sequencer Control

Stops the sequencer's playback, but maintains the current playback position.

VBScript syntax
call object(
"actionsetname"
) .Pause

JScript Syntax
object.item(
"actionsetname"
).Pause( )

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.

Play Method

Sequencer Control

Starts the sequencer or resumes it if the sequencer was paused. If the sequencer is playing, the call is ignored.

VBScript Syntax

call object(
"actionsetname"
) .Play

JScript Syntax
object.item(
"actionsetname"
).Play( )

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.
Remarks

The following example starts a sequencer described by the Seq object when the page loads. This sequencer calls the MoveButton action set at time 0, and calls the named procedure MoveButton.

<SCRIPT LANGUAGE=vbscript>
<!--
Sub window_onLoad
    Call Seq("MoveButton").Play
End Sub
-->
</SCRIPT>

Seek Method

Sequencer Control

Changes the current playback position of the Sequencer control to another specified point in playback.

VBScript Syntax

call object(
"actionsetname"
).Seek(
time
)

JScript Syntax

object.item(
"actionsetname"
).Seek(
time
)

Parameters
object
Name of sequencer.
actionsetname
Name of the action set.
time
New time for sequencer to continue playback.

Stop Method

Sequencer Control

Stops the sequencer and resets its position to the beginning.

VBScript Syntax

call object(
"actionsetname"
) .Stop

JScript Syntax

object.item(
"actionsetname"
).Stop( )

Parameters
object
Name of the sequencer.
actionsetname
Name of the action set.
Remarks

The following code stops the sequence when the btnEnd button is clicked.

<SCRIPT LANGUAGE=vbscript>
<!--
Sub btnEnd_OnClick
    Call Seq("MoveButton").Stop
End Sub
-->
</SCRIPT>

The sequencer automatically stops when the page is unloaded.

oninit Event

Sequencer Control

Called when the sequencer has finished loading into memory and the page is loaded. At this point, the specified script is run. This event is generally used to load the rest of the procedures to be run on the client side.

VBScript Syntax

Sub object_oninit
script
End Sub

JScript Syntax

<script language="javascript" for="object" event="oninit">
<!--
script
//--><script>

Parameters
object
Name of the sequencer to be used in script.
script
Script to be run.
Remarks

The following example shows the oninit event used to play SeqMgr once it has finished loading the other sequencers that it controls. In the example, SeqMgr controls Seq1_Action1.

<SCRIPT LANGUAGE="VBScript">
<!--
Sub SeqMgr_oninit()
    Call SeqMgr("ActionSet1").At(0.000,"Seq1_Action1",300,0.100,1,100.000)
    Call SeqMgr("ActionSet1").Play
End Sub
-->
</SCRIPT>

onpause Event

Sequencer Control

Called when the sequencer playback is paused. At this point, the specified script is run.

VBScript Syntax

Sub object_onpause(
actionsetname
)
script
End Sub

JScript Syntax

<script language="javascript" for="object" event="onpause(
actionsetname
) ">
<!--
script
//--><script>

Parameters
object
Name of the paused sequencer.
actionsetname
Name of the action set that has been paused because the sequencer is paused.
Remarks

In the following example, actionsetname is a variable set to the name of the action set that was last paused. The example tests the actionsetname parameter passed and conditionally executes a script based on which action set has been paused.

Sub Sequencername_onpause(actionsetname)
    If actionsetname="ActionSet1" then
        button1.value="Play"
    Else
        button1.value="Pause"
    Endif
End Sub

onplay Event

Sequencer Control

Occurs when the sequencer starts playback. At this point, the specified script code is run.

VBScript Syntax
Sub SequencerName_onplay(
actionsetname
)
script
End Sub

JScript Syntax

<script language="javascript" for="object" event="onplay(
actionsetname
) ">
<!--
script
//--><script>

Parameters
object
Name of the sequencer played.
actionsetname
Name of the action set played by the sequencer.
Remarks

In the following example, actionsetname is a variable set to the name of the action set that was last played. The example tests the actionsetname parameter passed and conditionally executes a script based on which action set has been played.

Sub Sequencername_onplay(actionsetname)
    If actionsetname="ActionSet1" then
        Call Seq("ActionSet2").stop
    Else
        Call Seq("ActionSet1").stop
    Endif
End Sub

onseek Event

Sequencer Control

Called after the Seek method is invoked against a sequencer has completed changing the playback position. At this point, the specified script code is run.

VBScript Syntax
Sub object_ onseek (
actionsetname,
newtime
)
script
End Sub

JScript Syntax

<script language="javascript" for="object" event="onseek(
actionsetname,
newtime
) ">
<!--
script
//--><script>

Parameters
object
Name of the sequencer.
actionsetname
Specific action set from which the Seek method was invoked.
newtime
New playback time to which the sequencer has been moved.
Remarks

You can use this event to determine where the sequencer playback has been moved and to set up conditional actions based on the sequencer's new position. However, you can't have an onseek event call a Seek method that seeks to a position within the same action set from which the onseek event originated.

Sub Sequencername_onseek(actionsetname, time)
    If actionsetname="ActionSet1" then
        If time=10.000 then
            Call Seq("ActionSet2").Play
        Else
            Call Seq("ActionSet1").Play
        EndIf
    EndIf
End Sub

onstop Event

Sequencer Control

Called when the sequencer is stopped. At this point, the specified script code is run.

VBScript Syntax
Sub SequencerName_onstop(
actionsetname
)
script
End Sub

JScript Syntax

<script language="javascript" for="object" event="onstop(
actionsetname
) ">
<!--
script
//--><script>

Parameters
SequencerName
Name of the stopped sequencer.
actionsetname
Name of the action set stopped by the sequencer.
Remarks

In the following example, actionsetname is a variable set to the name of the action set that was last stopped. The example tests the actionsetname parameter and conditionally executes a script based on which action set has been stopped.

Sub Sequencername_onstop(actionsetname)
    If actionsetname="ActionSet1" then
        Call Seq("ActionSet2").play
    Else
        Call Seq("ActionSet1").play
    Endif
End Sub


Sprite Control

The Sprite control lets you create and control image source-based, flip book-style animation for a Web page, and enables you to have frame-by-frame control over your animation. You can set markers to trigger events at desired points in sprite playback, or create individual mouse events for each frame of the animation.

To use the Sprite control, you must first instantiate it on the HTML page, as shown in the following syntax:

Syntax

<OBJECT ID=object
CLASSID="clsid: FD179533-D86E-11d0-89D6-00A0C90833E6 ">
[<PARAM NAME="Property | Method" VALUE="PropertyValue">]
</OBJECT>

Parameters
object | String identifying the object.
Property | Method | One of the Sprite control properties or methods in the following lists.
PropertyValue | Valid value for the specified property or method.

To use the Sprite control from within a scripting language such as Microsoft JScript™, Microsoft Visual Basic(r) Scripting Edition (VBScript), or other Web scripts, use the following script syntax:

object.Property | Method [=PropertyValue]

Some properties and methods are scriptable only. See the desired topic for syntax details.

Sprite Control Properties
Property | Description
AutoStart | Determines whether the sprite starts playback upon loading.
ColorKey | Sets the transparency color for a source image.
FinalFrame | Sets the sprite to display a designated frame when playback is stopped.
Frame | Retrieves the sprite image frame currently displayed.
FrameMap | Sets or retrieves the order in which sprite frames play back, and the length of time each frame is displayed.
Image | Sets or retrieves a Microsoft® DirectAnimation™ image from the Sprite control (script only).
InitialFrame | Sets or retrieves the frame number that the sprite displays when it becomes visible.
Library | Retrieves the DirectAnimation Library reference (script only).
MaximumRate | Sets or retrieves the sprite's maximum rendering rate (number of times the control will render per second).
MouseEventsEnabled | Sets or retrieves whether the sprite responds to mouse events.
NumFrames | Sets or retrieves the number of frames in the sprite source.
NumFramesAcross | Sets or retrieves the width (in frames) of the sprite source.
NumFramesDown | Sets or retrieves the length (in frames) of the sprite source.
PlayRate | Sets or retrieves the sprite's playback speed.
PlayState | Retrieves the sprite's playback state, whether stopped, playing, or paused.
Repeat | Sets or retrieves the number of times the sprite will loop during playback
SourceURL | Sets or retrieves the URL that points to the sprite source image.
Time | Retrieves the elapsed playback time for the sprite, including looping.
TimerInterval | Sets or retrieves the length of time between frames, (in milliseconds) for the sprite's rendering.
UseColorKey | Sets or retrieves whether to use the sprite's transparency information.

Sprite Control Methods
Method | Description
AddFrameMarker | Sets a marker to fire an event when playback reaches the designated frame.
AddTimeMarker | Sets a marker to fire an event when playback reaches the designated time.
FrameSeek | Sets the sprite playback to a specific frame.
Pause | Stops playback at the current frame and maintains current frame position.
Play | Begins playback from the current frame.
Seek | Sets the sprite playback to a specific elapsed time.
Stop | Ends playback at the current frame.

Sprite Control Events
Event | Description
onclick | Occurs when the user clicks the sprite once.
ondblclick | Occurs when the user double-clicks the sprite.
onframeseek | Occurs after the FrameSeek method has been called.
onmarker | Occurs when a time marker has been reached, either during sprite playback or when stopped.
onmedialoaded | Occurs when a piece of sprite media is completely downloaded.
onmousedown | Occurs when the user presses the mouse button down while the mouse pointer is over a sprite.
onmousemove | Occurs when the user moves the mouse pointer across the sprite's nontransparent area.
onmouseout | Occurs when the cursor leaves the sprite's nontransparent area.
onmouseover | Occurs when the cursor enters a nontransparent area of the sprite.
onmouseup | Occurs when the user releases the mouse button while the mouse pointer is over a sprite.
onpause | Occurs when sprite playback pauses.
onplay | Occurs when the sprite begins playback.
onplaymarker | Occurs when a time marker is reached during sprite playback.
onseek | Occurs after the Seek method is called.
onstop | Occurs when the sprite playback stops.

A Sprite control renders its visual display based on a source file that contains a series of frames. Each frame contains one of the images used to create the animation. This image can be a separate image file or part of a file that provides images for multiple frames in a sequential strip. The file providing the images for a sprite is known as the sprite source.

The images used for a Sprite control can be in different formats. For example, you can use images in .gif, .jpg, .png (Portable Network Graphics), and .wmf (windows metafile) formats. You can't mix image formats within the same sprite source, but you can change the sprite source image dynamically.

A Sprite control can use a frame map to define a specific order in which to display frames. The frame map also defines how long each frame is displayed. If the sprite does not include a frame map, frames are displayed in their order of appearance within the image source file, and each frame appears for the same length of time, as specified by the TimerInterval property.

A Sprite control will not begin its animation sequence until all of its media is downloaded.

AutoStart Property

Sprite Control

Determines whether the sprite starts playback immediately after loading.

PARAM Tag Syntax

<PARAM NAME="AutoStart" VALUE="fStart">

Script Syntax

object.AutoStart [=fStart]

Parameters
object
Name of the sprite.
fStart
Boolean value that sets when the playback starts. If True (–1 or nonzero), playback starts as soon as the sprite is loaded, or if False (0) the sprite simply loads and does not play until explicitly started with a Play method. The default value is False. Read-write at run time; write access is available at run time only when the sprite is stopped.

ColorKey Property

Sprite Control

Sets the transparency color to use with this specific sprite. Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="ColorKey " VALUE="r,
g,
b ">

Script Syntax

object.ColorKey=lib.DAColor

Parameters
r
Integer that specifies the red value (0-255).
g
Integer that specifies the green value (0-255).
b
Integer that specifies the blue value (0-255).
object
Name of the sprite.
DAColor
The DAColor object that specifies the sprite's color.

FinalFrame Property

Sprite Control

Sets the sprite to display the designated frame when playback is stopped. Read-write at run time, write accessible only when sprite is stopped.

PARAM Tag Syntax

<PARAM Name="FinalFrame" Value="fframeflag">

Script Syntax

object.FinalFrame [=fframeflag]

Parameters
object
Name of the sprite.
fframeflag
Integer expression identifying the desired frame to be displayed when sprite playback stops. Values can be –1 (display current frame), 0 (return to the initial frame), or any valid frame number, from 1 to n where n represents the last frame in the sprite source. The default value is 0, return to the initial frame.

Frame Property

Sprite Control

Specifies the sprite image for the frame currently displayed on the page. Read-only at run time.

Script Syntax

nFrame=object.Frame

Parameters
nFrame
Integer expression identifying the current frame, from 0 to n, where n represents the last frame in the sprite source. The default value is 1.
Remarks

If the sprite has a frame map, the value of the Frame property is a one-based index into the frame map. For example, if the frame map defines 10 frames, the Frame property value is 10 when the last frame in the frame map appears on the page.

VBScript note: To use the value returned by the Frame property, you will have to use the Microsoft Visual Basic®, Scripting Edition cInt function to convert the value from an unsigned integer into a variant that VBScript will accept. An example would be FrameNum=cInt(sprite.Frame).

The following example sets the indicator for a form to the value of the current frame for the sprite named SpriteHorse:

document.MyForm.txtFrame.value=SpriteHorse.Frame

FrameMap Property

Sprite Control

Specifies the order in which sprite frames play back and the length of time each frame is displayed. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="FrameMap" VALUE="nImage1,
t1 [; nImage2,
t2 ...] ">

Script Syntax

object.FrameMap="nImage1,
t1 [; nImage2,
t2 ...] "

Parameters
nImage1, nImage2,...
Integer expression denoting the image to draw from the frame source over the duration. The first frame in the sprite is numbered 1. The default value is the order in the source file.
t1, t2, ...
Expression indicating the frame's duration (seconds.milliseconds, 0.000). The default value is the TimerInterval duration.
Remarks

Sprites that use frame maps can display source images in an order other than the images' consecutive order of appearance within the source file. They can also display each frame in the sprite for a different length of time.

If the sprite has not been authored with a FrameMap property setting, frames appear in their order of appearance within the frame source file. The frames are in order from left to right, from top to bottom, within the file. Each frame appears for the number of seconds.milliseconds given by the TimerInterval property.

The following examples create a frame map with six frames.

  • Frame 1 displays image 6 for 100 milliseconds.
  • Frame 2 displays image 5 for 200 milliseconds.
  • Frame 3 displays image 4 for 300 milliseconds.
  • Frame 4 displays image 3 for 400 milliseconds.
  • Frame 5 displays image 2 for 100 milliseconds.
  • Frame 6 displays image 1 for 100 milliseconds.

<PARAM NAME="FrameMap"
VALUE="6,0.100;5,0.200;4,0.300;3,0.400;2,0.100;1,0.100">

object.FrameMap="6,0.100;5,0.200;4,0.300;3,0.400;2,0.100;1,0.100"

Image Property

Sprite Control

Sets or retrieves a DAImage object used for the Sprite control.

Script Syntax

object.Image=DAImage

Parameters
object
Name of the sprite.
DAImage
The DAImage object used for the sprite image.
Remarks

The following JScript code shows how to use this property:

m.DAControl.PixelLibrary;
img=m.ImportImage("mygif.gif");
mysprite.Image=img;

InitialFrame Property

Sprite Control

Specifies the frame the sprite displays when it becomes visible. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="InitialFrame" VALUE="nFrame">

Script Syntax

object.InitialFrame [=nFrame]

Parameters
nFrame
An integer expression specifying the frame that the sprite should seek to before starting playback. The value of the Frame property is a one-based index into the frame map. For example, if the frame map defines 10 frames, the Frame property value is 10 when the last frame in the frame map appears on the page. If the InitialFrame property is set to 0, the sprite will load the media but will display a blank frame until the Play method is invoked. If the InitialFrame property is set to –1 (or any number less than zero), the sprite will not load the media and will display a blank frame until the Play method is invoked, at which point it will begin media download and start playback after the media has been completely downloaded. The default value is 1.
Remarks

This property is scriptable, but if it is set from a script, only the initial frame of the sprite as it is set in the HTML-persistence is changed. The current frame of the sprite is not changed.

The following example sets an initial frame indicator on the page to the value of the InitialFrame property for the sprite named SpriteHorse:

document.MyForm.txtInitialFrame.value=SpriteHorse.InitialFrame

Library Property

Sprite Control

Retrieves a DAStatics object that gives the sprite access to the DirectAnimation library functions and properties.

Script Syntax

lib=object.Library

Parameters
lib
A DAStatics object.
object
Name of the sprite.
Remarks

The following JScript code shows how to use this property:

mysprite.Library=DAControl.PixelLibrary;

MaximumRate Property

Sprite Control

Sets or retrieves the sprite's maximum rendering speed (number of times the control will render per second). Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="MaximumRate" VALUE="fps"

Script Syntax

object.MaximumRate [=fps]

Parameters
fps
Number of frames per second. Default is 30.

NumFrames Property

Sprite Control

The number of frames in the Sprite source. Read/write at run time; write access is available only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="NumFrames" VALUE="nframes">

Script Syntax

object.NumFrames [=nframes]

Parameters
object
Name of the sprite.
nframes
Integer indicating the total number of frames in the image for this frame source.
Remarks

If the sprite includes a frame map, the NumFrames property gives the number of frames defined in the map. If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.

NumFramesAcross Property

Sprite Control

The width (in frames) of the sprite source image. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="NumFramesAcross" VALUE="nAcross">

Script Syntax

object.NumFramesAcross [=nAcross]

Parameters
object
Name of sprite.
nAcross
Integer indicating the number of frames across in the sprite source image.
Remarks

If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.

NumFramesDown Property

Sprite Control

The length (in frames) of the Sprite Frame Source. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="NumFramesDown" VALUE="nDown">

Script Syntax

object.NumFramesDown [=nDown]

Parameters
object
Name of sprite.
nDown
Integer indicating the number of frames in the sprite source image.
Remarks

If you change the NumFrames, NumFramesAcross, or NumFramesDown properties, the sprite does not refresh until you set the SourceURL property again.

PlayRate Property

Sprite Control

Sets or retrieves the sprite's playback speed. Can be used to speed up or slow down sprite playback, or even play the sprite backward. Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="PlayRate" VALUE="rSpeed">

Script Syntax

object.PlayRate=rSpeed

Parameters
rSpeed
Floating-point expression indicating the number used to multiply the duration for each frame. The default value is 1.0. Possible values are:
Value | Meaning
Positive (>0.0) | Sprite plays forward.
0.0 | Disables the PlayRate property.
Negative (<0.0) | Sprite plays backward.
Remarks

If the sprite does not have a frame map, the timer interval is divided by the value of PlayRate to determine the duration for all frames. PlayRate values greater than 1.0 speed up playback; values smaller than 1.0 slow down playback.

The following example sets the play rate for the sprite named SpriteHorse to the value the user enters on the page:

SUB PlayRate_onclick
SpriteHorse.PlayRate=document.MyForm.txtPlayRate.value

PlayState Property

Sprite Control

Retrieves the playback state of the sprite: stopped, playing, or paused.

Script Syntax

state=object.PlayState

Parameters
state
Integer value. Zero if the control is stopped, 1 if the control is playing, 2 if the media is paused.

Repeat Property

Sprite Control

Sets or retrieves the number of times the sprite will loop during playback. Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="Repeat" VALUE="nRepeat" >

Script Syntax

object.Repeat=nRepeat

Parameters
object
Name of the sprite.
nRepeat
Integer expression indicating the number of times the sprite repeats playback. The default is 1. To loop infinitely, use –1. The value 0 disables the Repeat property. Negative values are treated as unsigned.

SourceURL Property

Sprite Control

Sets or retrieves the URL that points to the sprite source image. Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="SourceURL" VALUE="URL">

Script Syntax

object.SourceURL=URL

Parameters
object
Name of the sprite.
URL
String pointing to the image file.

Time Property

Sprite Control

Retrieves the sprite's elapsed playback time (in milliseconds). Playback repetitions are included in the time calculations. Read-only at run time.

Script Syntax

object.Time=eTime

Parameters
object
Name of the sprite.
eTime
Number of milliseconds into the animation. The default value is zero.
Remarks

The onseek event is fired upon completion of the Time property change.

TimerInterval Property

Sprite Control

The length of time, in seconds.milliseconds, between the sprite's frame updates. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="TimerInterval" VALUE="nInterval">

Script Syntax

object.TimerInterval [=nInterval]

Parameters
object
Name of the sprite.
nInterval
Expression defining the number of seconds.milliseconds between sprite frame updates. The default interval is 0.100 seconds (0.100) or 10 frames per second.
Remarks

This property specifies the minimum length of time between sprite frame updates. For example, if the timer interval is set to 0.100 seconds and an image is scheduled to display at 0.150 seconds, the image will not be displayed until 0.200 seconds because the timer interval resolution is set to 0.100 milliseconds. If the image is scheduled to appear for 0.050 seconds or less (because of a frame map) it might not even appear.

The following example sets the value of the timer interval indicator on the page to the value of the TimerInterval property for the sprite named SpriteHorse:

document.MyForm.txtTimerInterval.value=SpriteHorse.TimerInterval

UseColorKey Property

Sprite Control

Sets or retrieves the property that specifies whether to use the sprite's transparency information. Read-write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="UseColorKey" VALUE="0 | 1">

Script Syntax

object.UseColorKey=fFalse

Parameters
object
Name of the sprite.
fFalse
Boolean value, True (1) or False (0). A value of True specifies that the transparency information set by the ColorKey property is used. A value of False specifies that the ColorKey transparency information is not be used. The default is False.
Remarks

If the ColorKey property value is set in a PARAM tag, then you should also set the UseColorKey value in a PARAM tag.

AddFrameMarker Method

Sprite Control

Sets a marker to fire an event when playback reaches the designated frame. This method can be used or modified only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="AddFrameMarkerx" VALUE=" frame ,
marker name ,
[fRelative]">

Script Syntax

object.AddFrameMarker(
frame ,
" marker name " ,
[ fRelative ]
)

Parameters
x
A sequential integer identifying the frame marker, starting at 1 (PARAM tag syntax only). If you are adding more than one frame marker through PARAM tag syntax, you must make each AddFrameMarker method call distinct by adding an sequential integer at the end of the AddFrameMarker PARAM name. starting at 1.
object
Name of the sprite.
Frame
Number or key name of the frame that the onmarker or onplaymarker event fires on.
marker name
Name of the marker.
fRelative
An optional flag that specifies event firing. DAn optional flag that specifies event firing. efault is True. If True (relative) the event fires every time, including in loops. If False (absolute) the event fires at the specified time once and ignores looping. For PARAM Tag syntax, use zero (False) or nonzero (True); for script use predefined constants True and False.
Remarks

onmarker events are fired whether or not the sprite is playing. onplaymarker events are only fired when the sprite is playing.

The following sprite has three markers defined.

<PARAM name="AddFrameMarker1" value="0,FrameEight,0">
<PARAM name="AddFrameMarker2" value="4,FrameFour,0">
<PARAM name="AddFrameMarker3" value="8,FrameZero,0">

AddTimeMarker Method

Sprite Control

Sets a marker to fire an event when playback reaches the designated time. This method can be used or modified only when the sprite is stopped.

PARAM Tag Syntax

<PARAM NAME="AddTimeMarker x " VALUE=" time ,
marker name,
[ fAbsolute ]">

Script Syntax

object.AddTimeMarker(
time ,
" marker name",
[ fAbsolute ]
)

Parameters
object
Name of the sprite.
x
A sequential integer identifying the time marker, starting at 1 (PARAM tag syntax only). If you are adding more than one time marker through PARAM tag syntax, you must make each AddTimeMarker method call distinct by adding an sequential integer at the end of the AddTimeMarker PARAM name.
time
Time for the onmarker or onplaymarker event to fire.
marker name
Name of the marker.
fAbsolute
An optional flag that specifies event firing. Default is True. If True (absolute) the event fires at the specified time once and ignores looping. If False (relative) the event fires everytime, including in loops. For PARAM tag syntax, use 0 for False and use –1 or nonzero for True. For script, use the predefined constants True and False. For PARAM Tag syntax, use zero (False) or nonzero (True); for script use predefined constants True and False.
Remarks

For details on the events fired for markers. onmarker events are fired whether or not the sprite is playing. onplaymarker events are fired only when the sprite is playing.

Example The following PARAM tag examples show how to use this method.

<PARAM name="AddTimeMarker1" value="0.0,MyMark,1">
<PARAM name=" AddTimeMarker2" value="4.7,FrameFour,1">
<PARAM name=" AddTimeMarker3" value="8.0,FrameZero,1">

FrameSeek Method

Sprite Control

Sets the sprite playback to a specific frame.

Script Syntax

object.FrameSeek(
frame
) >

Parameters
object
Name of the sprite.
frame
New playback frame for the sprite.
Remarks

The following example seeks the sprite named SpriteHorse in response to an onclick event:

SUB SpriteHorse_onclick
    SpriteHorse.FrameSeek(5)
END SUB

mouseover example Right click inside the frame and View Source to get source code.

Pause Method

Sprite Control

Stops playback at the current frame and maintains current frame position.

Script Syntax

object.Pause

Parameters
object
Name of the sprite.
Remarks

Does not rewind the media.

The following example pauses the sprite named SpriteHorse in response to an onclick event:

SUB SpriteHorse_onclick
    SpriteHorse.Pause
END SUB

Play Method

Sprite Control

Begins playback from the current frame. This method is scriptable only.

Script Syntax

object.Play

Parameters
object
Name of the sprite.
Remarks

The following example starts playing the sprite named SpriteHorse in response to an onclick event:

SUB Play_onclick
    SpriteHorse.Play
END SUB

Seek Method

Sprite Control

Sets the sprite playback to start at the specified elapsed time.

Script Syntax

object.Seek (
time
)

Parameters
object
Name of the sprite.
time
Elapsed time after which the sprite begins playing.
Remarks

The following example seeks the sprite named SpriteHorse in response to an onclick event:

SUB SpriteHorse_onclick
    SpriteHorse.seek(0.0)
END SUB

Stop Method

Sprite Control

Ends playback at the current frame and resets the sprite's playback position to the beginning. This method is scriptable only.

Script Syntax

object.Stop

Parameters
object
Name of the sprite.
Remarks

The following example stops playing the sprite named SpriteHorse in response to an onclick event:

SUB SpriteHorse_onclick
    SpriteHorse.Stop
END SUB

onframeseek Event

Sprite Control

Occurs after the FrameSeek method has been invoked and the current playback frame has been changed.

VBScript Syntax

Sub object_onframeseek(
newframe
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onframeseek(
newframe
) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be run.
newframe
New frame to which the current playback position has been set.

onmarker Event

Sprite Control

Occurs when a frame or time marker has been reached.

VBScript Syntax

Sub object_onmarker(
markername
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmarker(
markername
) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
markername
String containing the marker name established in the AddTimeMarker or AddFrameMarker methods.
script
Script to be run.
Remarks

This event occurs when the sprite playback position reaches the marker point, either when the sprite is playing, paused, or stopped. For example, if you seek to the marker position while the sprite is paused or stopped, the onmarker event will occur.

onmedialoaded Event

Sprite Control

Occurs when a piece of sprite media is fully downloaded.

VBScript Syntax

Sub object_ onmedialoaded(
URL
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmedialoaded(
URL
) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be run.
URL
URL used to load the media.

onpause Event

Sprite Control

Occurs when sprite playback is paused.

VBScript Syntax

Sub object_onpause( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onpause( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be run when the event occurs.

onplay Event

Sprite Control

Occurs when the sprite starts. The sprite will not start until all media is downloaded.

VBScript Syntax

Sub object_onplay( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onplay( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
script
Script to be run when the event occurs.

onplaymarker Event

Sprite Control

Occurs when a marker is reached during sprite playback.

VBScript Syntax

Sub object_onplaymarker(
markername
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onplaymarker(
markername
) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
markername
String containing the marker name established in the AddTimeMarker or AddFrameMarker methods.
script
Script to be run.
Remarks

This event occurs when the sprite playback position reaches the marker point while the sprite is playing.

onseek Event

Sprite Control

Occurs after a Seek method has been invoked and the playback position has changed.

Sub object_onseek(
newtime
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onseek(
newtime
) >
script
<SCRIPT>

Parameters
object
Name of the sprite.
newtime
Variable that contains the time value of the new playback position, in seconds.milliseconds (0.000).
script
Script to be run.
Remarks

You can use onseek to set up conditional behavior, as shown in the following example:

    Sub sprite1_onseek(newtime)
        If newtime=2.000 then
            sprite1.stop
        Else
            sprite1.play
        End If
    End Sub

onstop Event

Sprite Control

Occurs when the sprite playback stops.

Script Syntax

Sub object_onstop( )
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onstop( ) >
script
<SCRIPT>

Parameters
object
Name of the sprite.


DirectAnimation Animated Header --MouseEventsEnabled Property and Mouse Events DirectAnimation Animated Header --MouseEventsEnabled Property and Mouse Events * Microsoft DirectAnimation SDK
  * Previous Topic: Structured Graphics Control
  * Next Topic: Windows Metafile to Structured Graphics Converter

MouseEventsEnabled Property and Mouse Events

This section describes how to enable your control to respond to the mouse. It contains the following topics:

  • MouseEventsEnabled Property
  • onclick Event
  • ondblclick Event
  • onmousedown Event
  • onmousemove Event
  • onmouseout Event
  • onmouseover Event
  • onmouseup Event

MouseEventsEnabled Property

Determines whether mouse events will be processed against the object. Mouse events are processed against the visible pixels of the structured graphic or sprite object. Read/write at run time; write access is available at run time only when the sprite is stopped.

PARAM Tag Syntax
<PARAM NAME="MouseEventsEnabled" VALUE="0 | 1">

Script Syntax

object.MouseEventsEnabled [=fBoolean]

Parameters
object
Name of the Structured Graphics or Sprite object, as defined in PARAM tag syntax.
0 | 1, fBoolean
Boolean flag that specifies whether to process mouse events. For Structured Graphics, the default is False. For Sprite, the default is True. In HTML PARAM tags, the possible values are 0 (False) or nonzero (True). In script, the flag can support either 0 or False, 1 (a nonzero value) or True.
Remarks

Mouse events are z-order dependent. For example, if you have two objects positioned on top of each other, whichever object has a higher z-order will receive the mouse event when the user clicks, releases, or moves over that region.

Structured Graphics note: Enabling this property turns on a 1-bit bit mask for the control that slows down its rendering when it's being manipulated. For optimal performance, turn this property off unless you're specifically using it. Mouse events are not processed against the outline of the shape.

onclick Event

Occurs when the left mouse button is depressed and released while the mouse pointer is inside the region contained by the object's boundaries. An onclick event can also occur by hitting the ENTER key when an object has focus. The onclick event follows the onmouseup event when it occurs as a result of a mouse button click.

VBScript Syntax

Sub object_onclick
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onclick>
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
script
Script to be executed when the event occurs.

ondblclick Event

Occurs when the left mouse button is depressed and released twice in quick succession while the mouse pointer is inside the region contained by the object's boundaries.

VBScript Syntax

Sub object_ondblclick
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=ondblclick>
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
script
Script to be executed when the event occurs.
Remarks

The sequence of events for an ondblclick event is as follows:

  1. onmousedown
  2. onmouseup
  3. onclick
  4. onmouseup
  5. ondblclick

The user can control the timing of click events by changing the Mouse settings found in the Control Panel.

onmousedown Event

Fires when the left mouse button is pushed down while the pointer is within the region contained by the object.

VBScript Syntax

Sub object_onmousedown(
button,
shift,
x,
y
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmousedown(
button,
shift,
x,
y
) >
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
button
d>Bit field indicating whether the left (bit 0), right (bit 1), or middle (bit 2) mouse buttons are pressed. Returns a value that specifies which mouse button was pressed; 0 for no buttons pressed, 1 for left button pressed, 2 for right button pressed, 4 for middle button pressed.
shift
Bit field indicating whether the SHIFT (bit 0), CTRL (bit 1), or ALT (bit 2) keys are pressed. Returns a value that specifies the key or keys pressed while the mouse event is taking place; 0 for no key pressed, 1 for SHIFT key pressed, 2 for CTRL key pressed, 3 for SHIFT and CTRL keys pressed simultaneously, 4 for ALT key pressed, 5 for SHIFT and ALT keys pressed simultaneously, 6 for CTRL and ALT keys pressed simultaneously, 7 for SHIFT, CTRL, and ALT keys pressed simultaneously.
x, y
Coordinates that specify the location of the mouse pointer. Coordinates are in pixels, relative to the surrounding container, with the origin in the upper-left corner.
script
Script to be executed when the event occurs.

onmousemove Event

Fires when the mouse pointer is moved in the region contained by the object.

VBScript Syntax

Sub object_ onmousemove(
button,
shift,
x,
y
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmousemove(
button,
shift,
x,
y
) >
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
button
Bit field indicating whether the left (bit 0), right (bit 1), or middle (bit 2) mouse buttons are pressed. Returns the value of the mouse button pressed while the mouse event is taking place; 0 for no buttons pressed, 1 for left button pressed, 2 for right button pressed, 3 for left and right buttons pressed, 4 for middle button pressed, 5 for left and middle buttons pressed simultaneously, 6 for right and middle buttons pressed simultaneously, 7 for left, right and middle buttons pressed simultaneously.
shift
Bit field indicating whether the SHIFT (bit 0), CTRL (bit 1), or ALT (bit 2) keys are pressed. Returns the value of the key pressed while the mouse event is taking place; 0 for no key pressed, 1 for SHIFT key pressed, 2 for CTRL key pressed, 3 for SHIFT and CTRL keys pressed simultaneously, 4 for ALT key pressed, 5 for SHIFT and ALT keys pressed simultaneously, 6 for CTRL and ALT keys pressed simultaneously, 7 for SHIFT, CTRL and ALT keys pressed simultaneously.
x, y
Coordinates that specify the location of the mouse pointer. Coordinates are in pixels, relative to the surrounding container, with the origin in the upper-left corner.
script
Script to be executed when the event occurs.

onmouseout Event

Occurs when the mouse pointer is moved out of the region contained by the object's boundaries.

VBScript Syntax

Sub object_onmouseout
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmouseout>
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
script
Script to be executed when the event occurs.

onmouseover Event

Fires when the mouse pointer is moved into the region contained by the object, from a region outside the object's boundaries.

VBScript Syntax

Sub object_onmouseover
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmouseover>
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
script
Script to be executed when the event occurs.

onmouseover example Right click inside the frame and choose View Source to get source code.

onmouseup Event

Fires when the left mouse button is released (from a depressed position) while the pointer is within the region contained by the object.

VBScript Syntax

Sub object_ onmouseup(
button,
shift,
x,
y
)
script
End Sub

JScript Syntax

<SCRIPT LANGUAGE="JavaScript" FOR=object EVENT=onmouseup(
button,
shift,
x,
y
) >
script
<SCRIPT>

Parameters
object
String identifying the Sprite or Structured Graphics object.
button
Bit field indicating whether the left (bit 0), right (bit 1), or middle (bit 2) mouse buttons are released. Returns the value of the mouse button released; 0 for no buttons released, 1 for left button released, 2 for right button released, 4 for middle button released.
shift
Bit field indicating whether the SHIFT (bit 0), CTRL (bit 1), or ALT (bit 2) keys are pressed. Returns the value of the key pressed while mouse event is taking place; 0 for no key pressed, 1 for SHIFT key pressed, 2 for CTRL key pressed, 3 for SHIFT and CTRL keys pressed simultaneously, 4 for ALT key pressed, 5 for SHIFT and ALT keys pressed simultaneously, 6 for CTRL and ALT keys pressed simultaneously, 7 for SHIFT, CTRL, and ALT keys pressed simultaneously.
x, y
Coordinates that specify the location of the mouse pointer. Coordinates are in pixels, relative to the surrounding container, with the origin in the upper-left corner.
script
Script to be executed when the event occurs.


Structured Graphics Control

The Structured Graphics control provides client-side, vector-based graphics, rendered on the fly to add visual impact to your page. This gives you the advantage of low download overhead coupled with high performance on the client. This control renders the resulting vector shape as a windowless graphic, transparent to the background of the page, which can be programmatically manipulated by scaling, rotating, or translating methods.

You can use the Structured Graphics control to create simple primitives and complex polygon vector graphic shapes from a PARAM tag syntax description. Or, you can use the file syntax when the SourceURL property is set to read an external text file that contains the shape description.

For information on creating vector graphics via script, see the DrawingSurface topic in the DirectAnimation Programmer's Guide.

Use the Windows Metafile Converter (Wmfcnv.exe) included in the /BIN directory of the Internet Client SDK to convert existing Windows metafiles into Structured Graphic <PARAM> tags or shape description text files for use with the Structured Graphics control.

When rendering a shape, the Structured Graphics control will stop parsing the shape if it encounters invalid Param tag syntax. Some properties and methods are scriptable only. See the appropriate reference topic for syntax details.

Property Syntax

PARAM Tag Syntax

<OBJECT ID=object
STYLE="WIDTH:width; HEIGHT:height: Z-INDEX:z-index"
CLASSID="CLSID:369303C2-D7AC-11d0-89D5-00A0C90833E6" >
<PARAM NAME="PropertyName" VALUE="Value">
</OBJECT>

Script Syntax

object.PropertyName=Value

Parameters
object | Name of the structured graphics object.
width | Desired width for the structured graphics drawing area (pixels or percentage of page width)
height | Desired height for the structured graphics drawing area (pixels or percentage of page height)
z-index | Desired z-index value for the structured graphics drawing area (integer)
Property | One of the Structured Graphics control properties in the list below.
Value | Valid value for that property.
Property | Description
CoordinateSystem | Sets the coordinate system to use for the world
DrawingSurface | Sets or returns the Microsoft® DirectAnimation™ drawing surface, the visible rendering of the control's contents for use (script only).
ExtentHeight, ExtentWidth, ExtentLeft, ExtentTop Properties | Sets the height, width, left and top values of the shape (in pixels).
HighQuality Property | Turns anti-aliasing on or off.
Image Property | Fills the structured graphic shape with a DirectAnimation DAImage (script only).
Library | Returns the DirectAnimation Library reference (script only).
MouseEventsEnabled | Sets or returns whether Mouse events are to be processed against the structured graphics object.
PreserveAspectRatio Property | Sets or returns a value indicating if aspect ratio should be preserved when extents are set
SourceURL | Enables the Structured Graphic control to use an external file as the shape primitive description.
Transform | Transforms the object using a DirectAnimation DATransform2 behavior (script only).

Method PARAM Tag Syntax

<OBJECT ID=object
STYLE="WIDTH:width; HEIGHT:height: Z-INDEX:z-index"
CLASSID="CLSID:369303C2-D7AC-11d0-89D5-00A0C90833E6">
<PARAM NAME="LINEnnnn" VALUE="method">
</OBJECT>

Parameters
object | String identifying the object.
width | Desired width for the structured graphics drawing area (pixels or percentage of page width)
height | Desired height for the structured graphics drawing area (pixels or percentage of page height)
z-index | Desired z-index value for the structured graphics drawing area (integer)
nnnn | A sequence number for the method execution order. Must be in order starting with 0001. Skipped sequences halt execution.
method | One of the elements in the list below.
Method | Description
Arc | Creates a single circular or elliptical arc.
FillSpline | Creates a closed spline shape, defined by a series of points.
Oval | Creates an ellipse.
Pie | Creates an elliptical arc closed at the center of the bounding rectangle to form a wedge (pie) shape.
Polygon | Creates a closed polygon.
PolyLine | Creates a segmented line.
PolySpline | Creates an open spline shape, defined by a series of points.
Rect | Creates a rectangle.
RoundRect | Creates a rounded rectangle.
SetFillColor | Sets the foreground and background colors for graphic fills.
SetFillStyle | Sets the type of fill.
SetFont | Sets the font for the control.
SetGradientFill | Specifies the start and end points for a gradient fill.
SetHatchFill | Specifies whether the hatch fill is transparent.
SetLineColor | Sets the line color for drawing graphics.
SetLineStyle | Changes the line style for the current shape.
SetGradientShape | Sets the shape of a gradient to be an outline of a polygon shape.
SetTextureFill | Sets the texture source to be used to fill a structured graphics shape.
Text | Creates a string with the current font and color.

Method Script Syntax

The following methods are scriptable only, and use this syntax form:

object.MethodName(Parameters)
object | String identifying the structured graphics object.
MethodName | One of the elements in the list below.
Parameters | Valid parameter for that method.
Clear | Clears the control.
Rotate | Sets the rotation of the world.
Scale | Sets the current scaling in the x-, y-, and z-axes for the world.
SetIdentity | Clears any transforms, sets the shape to its original state.
Transform4x4 | Sets scaling, rotating, and translation information all at once, using a transform matrix.
Translate | Sets the x-, y-, and z-coordinates of the origin.
Events | Description
onclick | Occurs when the user has clicked the left mouse button on the structured graphic.
ondblclick | Occurs when the user has double-clicked on the structured graphic.
onmousedown | Occurs when the left button is pressed over the structured graphic.
onmousemove | Occurs when the user moves the mouse pointer across the non-transparent area of the structured graphic.
onmouseout | Occurs when the cursor leaves the non-transparent area of the structured graphic.
onmouseover | Occurs when the mouse pointer has entered the non-transparent region of the structured graphic.
onmouseup | Occurs when the user releases the mouse button while the mouse pointer is over the structured graphic.

CoordinateSystem Property

Structured Graphics Control

Sets the coordinate system to use for the world. Read-only at runtime.

PARAM Tag Syntax

<PARAM NAME="CoordinateSystem" VALUE="0 | 1">

Parameters
0 | 1
Sets the world's rotation. Value can be Windows (0), where y-axis values start at the top of the page and increase downward, or Cartesian (1), where y-axis values start at the bottom of the page and increase upward.

DrawingSurface Property

Structured Graphics Control

Sets or returns the drawing surface, the visible rendering of the control's contents for use in script. For more information, see the DirectAnimation documentation.

DrawingSurface property example

Right-click inside the frame and choose View Source to see the HTML code for this example.

ExtentHeight, ExtentWidth, ExtentLeft, ExtentTop Properties

Structured Graphics Control

Sets the height, width, left and top values of the shape within the control's coordinate space (as defined by the WIDTH and HEIGHT parameters of the <OBJECT> tag's STYLE attribute).

PARAM Tag Syntax

<PARAM NAME="ExtentHeight" VALUE="height">
<PARAM NAME="ExtentWidth" VALUE="width">
<PARAM NAME="ExtentLeft" VALUE="left">
<PARAM NAME="ExtentTop" VALUE="top">

Parameters
height
The height of the shape (in pixels).
width '
The width of the shape (in pixels).
left
The left edge of the shape (in pixels).
top
The top edge of the shape (in pixels).
Remarks

Top and left values can be set without setting height and width values, but height and width values can only be set if the top and left values are set. An example of the use of this property is as follows; if you set ExtentTop to 0 and ExtentLeft to 0, instead of drawing the shape from the center of the control's coordinate space (as defined in the STYLE attribute of the <OBJECT> tag), the shape will be drawn from the upper left hand corner of the coordinate space.

HighQuality Property

Structured Graphics Control

Turns anti-aliasing on (True) or off (False). Read/write at run time.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE=" HighQuality(
0 | 1
) ">

Script Syntax

object.HighQuality(
fFalse
)

Parameters
0 | 1 , fFalse
Boolean flag that turns anti-aliasing on or off for the structured graphic, default is False. In HTML Param tags, the possible values are 0 (False) or nonzero (True). In script, the flag can support either 0 or False, 1 (a nonzero value) or True.
Remarks

Enabling this property slows down the rendering of the structured graphic. For optimal performance, turn this property off unless you're specifically using it.

Image Property

Structured Graphics Control

Fills the structured graphic shape with a DAImage.

Script Syntax

object.Image=DAImage

Parameters
object
The name of the structured graphics object, as defined in the PARAM tag.
DAImage
The DAImage object used to fill the shape.

Library Property

Structured Graphics Control

Retrieves a DAStatics object that gives the control access to the DirectAnimation library functions and properties.

Script Syntax

lib=object.Library

Parameters
lib
A DAStatics object.
object
Name of the structured graphics object.
Remarks

The following JScript code shows how to use this property:

mySG.Library=DAControl.PixelLibrary;

PreserveAspectRatio Property

Structured Graphics Control

Sets whether or not the graphic should scale proportionally.

PARAM Tag Syntax

<PARAM NAME="PreserveAspectRatio" VALUE="0 | -1">

Script Syntax

object.PreserveAspectRatio=fFalse

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
0 | -1 , fFalse
Boolean flag that sets whether or not the aspect ratio should be preserved. Default is False.
Remarks

This property is effective only if ExtentTop, ExtentLeft, ExtentWidth and ExtentHeight properties are set. An example of the use of this property is as follows; if you set the shape's width and height as a percentage of the page width and height (as one of the STYLE attributes of the <OBJECT> tag), set PreserveAspectRatio to True and the user resizes the browser window, the shape will scale itself proportionally based on the smaller of the new width or height values for the window. If PreserveAspectRatio is set to False, the shape will scale itself in relative to the new width and height of the window.

SourceURL Property

Structured Graphics Control

Enables the Structured Graphic control to use an external file as the vector shape description. You can use the Windows Metafile Converter (WMFCONV.EXE) to convert Windows metafiles into structured graphics shape description text files. Read-write at runtime.

PARAM Tag Syntax

<PARAM NAME="SourceURL" VALUE="URL">

Script Syntax

object.SourceURL=URL

Parameters
URL
String value, describing the location of the specified shape primitive description file. Can be an http://, file://\\ or relative path. Default is null.
Remarks

This can be very useful in the case of creating a structured graphic animation. Using this property, you can write code that very rapidly calls different source URLs, making it seem as if the shape is changing over time in a manner that exceeds scale or rotation transformations.

SourceURL property example

Right-click inside the frame and choose View Source to see the HTML code for this example.

Transform Property

Structured Graphics Control

Transforms the object using a DATransform2 behavior.

Script Syntax

object.Transform=DATransform2

Parameters
object
The name of the structured graphics object, as defined in the PARAM tag.
DATransform2
A DATransform2 behavior.

Arc Method

Structured Graphics Control

Creates a single circular or elliptical arc.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="Arc(
x,
y,
width,
height,
startAngle,
arcAngle,
rotation">

File Syntax

Arc(
x,
y,
width,
height,
startAngle,
arcAngle,
rotation
)

Parameters
x, y
The center of the arc.
width
The width of the rectangle containing the arc.
height
The height of the rectangle containing the arc.
startAngle
The beginning angle, in degrees.
arcAngle
The angle of the arc, relative to startAngle, in degrees.
rotation
The degree of rotation from the 0 degrees position.

Arc Method example

Right click inside the frame and select View Source to see the HTML code for this example.

Clear Method

Structured Graphics Control

Clears the control of its contents, resetting it to null.

Script Syntax
object.Clear

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
Remarks

This method is useful for erasing the graphic before painting another in its place using the DrawingSurface property.

FillSpline Method

Structured Graphics Control

Creates a closed spline shape, defined by a series of points.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="FillSpline (
numpoints[action,
xPoint,
yPoint],
rotation
) ">

File Syntax

FillSpline (
numpoints,
[action,
xPoint,
yPoint],
rotation
)

Parameters
numpoints
Number of points in the spline
Action
An integer that defines what the spline does at the x, y coordinate. Can be one of the following:
0 - Move to: Move to the x, y coordinate.
1 - LineTo: draw a line from the previous x, y coordinate to the current one.
2 - BezierTo: Draw a bezier line from the previous coordinates to the current one.
3 - LineToClose: Close the line to the first coordinate.
4 - BezierClose: Close the bezier to the first coordinate.
xPoint
The x-coordinate for the spline control point.
yPoint
The y-coordinate for the spline control point.
rotation
Degree of rotation.

Oval Method

Structured Graphics Control

Creates an ellipse that fits within the bounding rectangle specified by the x, y, width and height arguments.

PARAM Tag Syntax
<PARAM NAME="Line0001" VALUE="Oval(
x,
y,
width,
height,
rotation
) ">

File Syntax

Oval(
x,
y,
width,
height,
rotation
)

Parameters
x, y
The x- and y-coordinates for the start of the bounding rectangle.
width
The width of the rectangle.
height
The height of the rectangle.
rotation
The degree of rotation from the 0 degrees position.

Oval Method example

Right-click inside the frame and choose View Source to see the HTML code for this example.

Pie Method

Structured Graphics Control

Creates a single elliptical arc filled with the current FillColor, resulting in a wedge-shaped (pie) figure.

The center of the pie shape is the center of a rectangle whose origin is (x, y) and whose size is specified by the width and height arguments. The two axes of the arc are given by the width and height arguments. The arc is drawn from startAngle to startAngle + arcAngle.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="Pie(
x,
y,
width,
height,
startAngle,
arcAngle,
rotation
) ">

File Syntax

Pie(
x,
y,
width,
height,
startAngle,
arcAngle,
rotation
)

Parameters
x
The x-coordinate.
y
The Y coordinate.
width
The width of the rectangle.
height
The height of the rectangle.
startAngle
The beginning angle, in degrees.
arcAngle
The angle of the arc, relative to startAngle, in degrees.
rotation
The degree of rotation from the 0 degrees position.
Remarks

This example draws a 22-degree pie shape.

<PARAM NAME="Line0004" VALUE="Pie(-75,-75, 150,150, 15,22, 0)">">

Pie Method example

Right click inside the frame and select View Source to see the HTML code for this example.

Polygon Method

Structured Graphics Control

Creates a closed polygon defined by a list of points, filled with the current FillColor.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="Polygon>(
nPoints,
x1,
y1,
x2,
y2,
x3,
y3 [,
x4,
y4 ...],
rotation
) ">

File Syntax

Polygon(
nPoints,
x1,
y1,
x2,
y2,
x3,
y3 [,
x4,
y4 ...],
rotation
)

Parameters
nPoints
The total number of points.
x1, y1
The first point defining the shape.
x2, y2
The second point defining the shape.
x3, y3
The third point defining the shape.
x4, y4
Additional points that define the shape.
rotation
The degree of rotation from the 0 degrees position.
Remarks

If you don't want to close the polygon, use PolyLine.

This example creates an elongated hexagon.

<PARAM NAME="Line0005" VALUE="Polygon(6, 0,10, 10,10, 30,30, 30,40, 20,40, 0,20, 0)">

Polygon Method example

Right-click inside the frame and choose View Source to see the HTML code for this example.

PolyLine Method

Structured Graphics Control

Creates an open (nonfilled) line shape defined by a series of points.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="PolyLine(
nPoints,
x1,
y1,
x2,
y2 [,
x3,
y3 ...],
rotation
) ">

File Syntax

PolyLine(
nPoints,
x1,
y1,
x2,
y2 [,
x3,
y3 ...],
rotation
)

Parameters
nPoints
The total number of points.
x1, y1
The first point defining the line.
x2, y2
The second point defining the line.
x3, y3
Additional points that define the line.
rotation
The degree of rotation from the 0 degrees position.
Remarks

To create a closed polygon, use Polygon.

This example creates a stair-stepped line.

<PARAM NAME="Line0001" VALUE="PolyLine(7, 10,10, 30,10, 30,30, 50,30, 50,50, 70,50, 70,70, 0)">

PolyLine Method example

Right click inside the frame and select View Source to see the HTML code for this example.

PolySpline Method

Structured Graphics Control

Creates a spline shape defined by a series of points, filled with the current FillColor.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="PolySpline (
nPoints,
[action,
xPoint,
yPoint],
rotation
) ">

File Syntax

PolySpline (
npoints,
[action,
xPoint,
yPoint],
rotation
)

Parameters
nPoints
The total number of points.
Action
An integer that defines what the spline does at the x, y coordinate. Can be one of the following:
0 - Move to: Move to the x, y coordinate.
1 - LineTo: draw a line from the previous x, y coordinate to the current one.
2 - BezierTo: Draw a bezier line from the previous coordinates to the current one.
3 - LineToClose: Close the line to the first coordinate.
4 - BezierClose: Close the bezier to the first coordinate.
xPoint
The x-coordinate for the spline control point.
yPoint
The y-coordinate for the spline control point.
rotation
Degree of rotation from the 0 degrees position.

Rect Method

Structured Graphics Control

Creates a rectangular shape filled with the current FillColor.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="Rect(
x,
y,
width,
height,
rotation
) ">

File Syntax

Rect(
x,
y,
width,
height,
rotation
)

Parameters
x
The left edge of the rectangle.
y
The top edge of the rectangle.
width
The width of the rectangle.
height
The height of the rectangle.
rotation
The degree of rotation from the 0 degrees position.

Rect Method example

Right click inside the frame and select View Source to see the HTML code for this example.

Rotate Method

Structured Graphics Control

Rotates the shape along the x-, y-, and z-axes.

Script Syntax

object.Rotate(
x-rotation,
y-rotation,
z-rotation
)

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
x-rotation, y-rotation, z-rotation
Sets the new x, y, and z rotation values, in degrees.

Rotate Method example

Right click inside the frame and select View Source to see the HTML code for this example.

RoundRect Method

Structured Graphics Control

Creates a round-cornered rectangle filled with the current FillColor.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="RoundRect(
x,
y,
width,
height,
arcWidth,
arcHeight,
rotation
) ">

File Syntax

RoundRect(
x,
y,
width,
height,
arcWidth,
arcHeight,
rotation
)

Parameters
x
The left edge of the rectangle.
y
The top edge of the rectangle.
width
The width of the rectangle.
height
The height of the rectangle.
arcWidth
The horizontal diameter of the arc at the four corners.
arcHeight
The vertical diameter of the arc at the four corners.
rotation
The degree of rotation from the 0 degrees position.

RoundRect Method example

Right click inside the frame and select View Source to see the HTML code for this example.

Scale Method

Structured Graphics Control

Sets the current scaling of the x-, y-, and z-axes.

Script Syntax

object.Scale(
x-scale,
y-scale,
z-scale
)

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
x-scale, y-scale, z-scale
Sets the new scaling for the x-, y-, and z-axes. The scaling is multiplicative, based on the current values for the shape, with the current size equivalent to 1. For example, scaling the shape by 0.9 sets the shape to 90% of its former size.

Scale Method example

Right click inside the frame and select View Source to see the HTML code for this example.

SetFillColor Method

Structured Graphics Control

Sets the color fill for the shape. Can be used to set foreground and background fills to different colors.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetFillColor(
rForeColor,
gForeColor,
bForeColor [,
rBackColor,
gBackColor,
bBackColor ]
) ">

File Syntax

SetFillColor(
rForeColor,
gForeColor,
bForeColor [,
rBackColor,
gBackColor,
bBackColor ]
)

Parameters
rForeColor, gForeColor, bForeColor
The red, green, and blue values for the foreground color. Each value is an integer in the range 0–255.
rBackColor, gBackColor, bBackColor
Optional. The red, green, and blue values for the background color. Each value is an integer in the range 0–255.
Remarks

This example sets the Fill Color to solid blue.

<PARAM NAME="Line0001" VALUE="SetFillColor(0,0,255)">

SetFillColor property example

Right click inside the frame and select View Source to see the HTML code for this example.

SetFillStyle Method

Structured Graphics Control

Sets the type for a fill.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetFillStyle(
type
) ">

File Syntax

SetFillStyle(
type
)

Parameters
type
Sets the fill type where type is one of the following values.
Value | Description
0 | Null
1 | Solid
3 | Hatch horizontal
4 | Hatch vertical
5 | Hatch forward diagonal
6 | Hatch backward diagonal
7 | Hatch cross
8 | Hatch diagonal cross
9 | Horizontal gradient
10 | Vertical gradient
11 | Radial gradient
12 | Line gradient
13 | Rectangular gradient
14 | Shaped gradient
Remarks

This example fills the shape with a solid fill.

<PARAM NAME="Line0001" VALUE="SetFillStyle(1)">

Based on the value set for type, you can use the SetHatchFill or SetGradientFill methods to set properties for the selected fill type.

SetFillStyle property example

Right click inside the frame and select View Source to see the HTML code for this example.

SetFont Method

Structured Graphics Control

Sets the font to be used for creating text. Used with the Text method.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetFont(
name,
height,
weight,
isItalic,
isUnderline,
isStrikethrough
) ">

File Syntax

SetFont(
name,
height,
weight,
isItalic,
isUnderline,
isStrikethrough
)

Parameters
name
The new font name.
height
The size of the font, in points. If font height is set as negative value, font will be drawn upside down and backwards.
weight
The weight of the font. An integer in the range 0–700, where a value of 300 is normal weight, and a value of 700 is heavy bold.
isItalic, isUnderline, isStrikethrough
Values specifying whether the font is italic, underlined, or strikethrough. If True, the font has the corresponding attribute; if False, the font does not.
Remarks

The following example sets the font attributes to be 80-point Verdana in a medium heavy bold, with no italic, underlined, or strikethrough characteristics.

<PARAM NAME="Line0004" VALUE="SetFont('Verdana',80,650,0,0,0)">

SetGradientFill Method

Structured Graphics Control

Specifies a rectangular area to fill with a gradient. This method can be used with any closed shape.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetGradientFill(
startX,
startY,
finishX,
finishY,
strength
) ">

File Syntax

SetGradientFill(
startX,
startY,
finishX,
finishY,
strength
)

Parameters
startX, startY
The x and y positions, in pixels, for the start point of the rectangle that holds the gradient. These positions are relative to the upper-left corner of the page.
finishX, finishY
The x and y positions, in pixels, for the end point of the rectangle that holds the gradient. These positions are relative to the upper-left corner of the page.
strength
Sets the intensity of the first color.
Remarks

Use the SetFillColor method to specify the foreground and background colors for the gradient fill.

Use this function only if you specified type as 11 for the SetFillStyle method.

The following example sets the gradient fill attributes for the shape to start at (25,15), to fill toward the upper-left corner of the page with a color intensity of 1.

<PARAM NAME="Line0005" VALUE="SetGradientFill(25,15,0,0,1)">

SetGradientFill property example

Right click inside the frame and select View Source to see the HTML code for this example.

SetGradientShape Method

Structured Graphics Control

Sets a gradient shape to that of a specified shape. It will use SetGradientColor to display the color ranges.

PARAM Tag Syntax

<PARAM NAME="Line0005" VALUE="SetGradientShape(
nPoints,
[x0,
y0 ,
x1 ,
y1 ,
xN ,
yN]
) >

File Syntax

SetGradientShape(
nPoints,
[x0,
y0,
x1 ,
y1 ,
xN ,
yN]
)

Parameters
nPoints
The total number of points.
x0, y0 , x1, y1 , xN , yN
The x- and y-coordinate pairs.
Remarks

NOTE: The begin color is color1 and the end color is color2, as set in the SetFillColor method.

SetHatchFill Method

Structured Graphics Control

Specifies whether or not the hatch fill is transparent.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetHatchFill(
0 | 1
) ">

File Syntax

SetHatchFill(
fTransparent
)

Parameters
o | 1 / fTransparent
If False (0), the hatch fill is not transparent. If True (1 or nonzero value), the default, the hatch fill is transparent. Default is False.
Remarks

Use this function only if you specified a value for type between 3 and 8 for the SetFillStyle method.

The following HTML Param tag sets the HatchFill attribute to visible.

<PARAM NAME="Line0005" VALUE="SetHatchFill(1)">

SetIdentity Method

Structured Graphics Control

Sets the shape to its original settings.

Script Syntax

object.SetIdentity( )

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
Remarks

Use SetIdentity to ensure that your shapes are at their initial position, size and orientation when your page loads by using the window_onload event.

This example demonstrates how window_onload is used to initialize the structured graphic SG1.

Sub window_onload()
call SG1.SetIdentity()
End Sub

When SetIdentity is next called, it clears all transforms and returns the shape to its initial settings.

SetLineColor Method

Structured Graphics Control

Sets the line color for the shape outline.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetLineColor(
r,
g,
b
) ">

File Syntax

SetLineColor(
r,
g,
b
)

Parameters
r
The red value for the color. Integer in the range 0–255.
g
The green value for the color. Integer in the range 0–255.
b
The blue value for the color. Integer in the range 0–255.
Remarks

This code sets the line color to red.

<PARAM NAME="Line0001" VALUE="SetLineColor(255,0,0)">

SetLineStyle Method

Structured Graphics Control

Sets the line style of the shape.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="SetLineStyle(
style,
linewidth
) ">

File Syntax

SetLineStyle(
style,
linewidth
)

Parameters
style
Sets the line style for the current shape type using any of the following values.
Value | Description
0 | Null
1 | Solid
2 | Dash
linewidth
integer value, sets the line width in pixels.
Remarks

The following example sets the LineStyle attribute for the shape to a dashed line four pixels wide.

<PARAM NAME="Line0002" VALUE="SetLineStyle(2,4)">

SetTextureFill Method

Structured Graphics Control

Sets the texture or image source file to be used to fill the shape.

PARAM Tag Syntax

<PARAM NAME "Line0001" Value="SetTextureFill(
xpos,
ypos,
'ImageSourceURL',
0 | 1">

Script Syntax

object.SetTextureFill(
xpos,
ypos,
'ImageSourceURL',
0 | 1
)

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
xpos, ypos
Sets the x- and y-coordinates for the origin point of the texture, in pixels.
ImageSourceURL
Sets the source image URL.
0 | 1
Sets the type of texture fill, whether scaled (0) or tiled (1) within the bounds of the shape.

SetTextureFill property example

Right click inside the frame and select View Source to see the HTML code for this example.

Text Method

Structured Graphics Control

Creates a string using the current font and color.

PARAM Tag Syntax

<PARAM NAME="Line0001" VALUE="Text(
'str ',
x,
y,
rotation
) ">

File Syntax

Text(
'str ',
x,
y,
rotation
)

Parameters
str
The string to be drawn.
x, y
The position for the baseline of the first character.
rotation
The degree of rotation from the 0 degrees position.
Remarks

The text primitive draws from the origin point upwards, as opposed to the other primitives which draw from the origin point downwards.

The following code creates the word "Hello" angled 45 degrees from 0.

<OBJECT ID="String"
CLASSID="CLSID:369303C2-D7AC-11d0-89D5-00A0C90833E6"
STYLE="WIDTH:250;HEIGHT:200">
<PARAM NAME="Line0001" VALUE="SetFillColor(0,0,255)">
<PARAM NAME="Line0002" VALUE="SetFont('Verdana', 75, 400, 0, 0, 0)">
<PARAM NAME="Line0003" VALUE="Text('Hello', 0, 0, 45)">
</OBJECT>

Transform4x4 Method

Structured Graphics Control

Sets scaling, rotating, and translation information all at once, using a transform matrix.

Script Syntax

object.Transform4x4(
transform-matrix
)

Parameters
object
The name of the structured graphics object, as defined in the PARAM tag.
transform-matrix
An array containing the 16 values forming a 4x4 transform matrix for the control.
Remarks

The 4x4 matrix with ones on the diagonal is the default setting.

Translate Method

Structured Graphics Control

Sets the x-, y-, and z-coordinates for the shape's origin.

Script Syntax

object.Translate(
x-coordinate,
y-coordinate,
z-coordinate
)

Parameters
object
Name of the structured graphics object, as defined in PARAM tag syntax.
x-coordinate, y-coordinate, z-coordinate
The new x-, y-, and z-coordinates, in pixels, for the graphic.


Windows Metafile to Structured Graphics Converter

This utility converts pre-existing Windows metafiles into structured graphic <PARAM> tags, for use with the Microsoft® DirectAnimation™ Dynamic HTML Structured Graphics control.

Options dialog box

Use the Open command on the File menu to open the Windows metafile you want to convert.

Use the Options command on the File menu to set the scale, orientation, starting line number, and output format.

Use the Save command on the File menu to write the Windows metafile information out in structured graphic format. You can then cut and paste this information into your HTML file source for use with the Structured Graphics control.

For for information, see the following topics:

  • Scale Options
  • Orientation Options
  • Output Format
  • Line Numbering

Scale Options

  • Height — Sets the height of the structured graphic (in pixels).
  • Width — Sets the width of the structured graphic (in pixels).

Orientation Options

  • Flip Horizonta l — Flips the image along the horizontal plane.
  • Flip Vertical — Flips the image along the vertical plane.

Output Format

  • Unformatted — Saves the structured graphic information out without <PARAM> tags or line numbers.
  • HTML <PARAM> tags — Saves the structured graphic information out with <PARAM> tags and line numbers.
  • Visual Basic object tag — Saves the structured graphic information out with line numbers but no <PARAM> tags.

Line Numbering

  • Line Number — Allows you to set the initial line number for the structured graphic information so you don't have to renumber all of the line numbers of the structured graphic to add another <PARAM> tag at the beginning.
  • Reset on open — Resets the initial line number to zero (0) the next time you open the Windows Metafile to Structured Graphic converter.


Programmer's Guide

The Microsoft® DirectAnimation™ Programmer's Guide discusses a variety of ideas and techniques useful to many types of DirectAnimation authors. The Introduction gives you a brief idea of what you can do in DirectAnimation. The Basics section shows how to do simple scripting, and describes media files, coordinate systems, URLs and paths, timelines, arrays, the Drawing Surface, splines, and more. Using Media Behaviors describes the media behaviors (images, geometries, and sound), and how to use them. Using Behaviors describes general DirectAnimation behaviors, how to create and display them, how to use events and picking, and how to use sequencing, switching, and time substitution. Using Models discusses how to use models, which are the sets of behaviors (composed of images and sounds) actually displayed.

Introduction

The Basics

Using Media Behaviors

Using Behaviors

Using Models


Introduction

Animation involves changing media over time or in reaction to user input. Media includes sound, 2-D images, and 3-D objects, along with their corresponding camera and lights, colors, textures, and other visual or audio properties. DirectAnimation™ allows developers to produce sophisticated animation from a relatively small number of classes and methods.

DirectAnimation supports a broad set of functionality for mixed-media animation, including:

  • Importing images, translating and displaying them with pixel-to-pixel mapping to the screen.
  • Creating 3-D scenes and rendering them with traditional lighting, shading, and camera models.
  • Streaming audio and video from files or the network.
  • Combinations of all of the above.

With DirectAnimation, you can create a rich interactive animation that draws on both synthetic media (such as 3-D graphics) and recorded media (such as audio and video). For example, you can navigate a 3-D space to inspect a collection of museum items or commercial products. You can implement spatial navigation by using position and orientation to index different items represented as images and video clips.

There are three basic ways to use DirectAnimation. HTML authors can integrate multimedia using the DirectAnimation controls. The controls can be further enhanced with JScript and/or VBScript. VBScript and JScript writers and Java applet writers can program animations for web pages. Finally, Java, Visual Basic, and C++ application programmers can develop ActiveX Controls or full applications. Thus, DirectAnimation provides a multimedia API and run time that scales from the HTML author to the C++ programmer.

The basic class in DirectAnimation is called a behavior. Use the DirectAnimation classes and methods to construct time-varying, interactive behaviors. You can join sequences of behaviors to produce complex, flexible animation from just a few operations.

Behaviors that are rendered for presentation to the user are called media behaviors. These include:

  • 2-D image behaviors (the DAImage class and Java ImageBvr class)
  • 3-D geometry behaviors (the DAGeometry class and Java GeometryBvr class)
  • sound behaviors (the DASound class and Java SoundBvr class)

Other behaviors control the attributes of the media behaviors, or the way they are rendered to the screen. For example:

  • Color behavior (the DAColor and ColorBvr classes)
  • Camera behavior (the DACamera and CameraBvr classes)
  • Transform behavior (the DATransform2 and DATransform3 classes, and the Java Transform2Bvr and Transform3Bvr classes)


The Basics

This section covers a variety of concepts and techniques useful to many types of DirectAnimation authors: Web site builders, script writers, and application developers. The following topics are discussed in this section:

  • Thinking About DirectAnimation
  • Media Files Supported by DirectAnimation
  • Scripting
  • The Statics Class
  • Naming Conventions in DirectAnimation
  • Viewing DirectAnimation Functions in Visual Basic
  • A Simple JScript Example
  • A Simple Java Example
  • Coordinates in DirectAnimation
  • Scripting Timelines Using Duration
  • Arrays and Tuples
  • URLs and Paths
  • Drawing Surface
  • Splines

Thinking About DirectAnimation

This section introduces the basic elements of the DirectAnimation model, including media expressions in DirectAnimation, and suggests analogies to number expressions and spreadsheets.

Media Expressions

DirectAnimation can be explained in terms of the familiar concept of expressions on numbers in programming languages (Fortran, C++, Visual Basic, Java, and so on). Such expressions are based on operations that construct new numbers from existing numbers. For example, (5 + 7) * 4 + 3 constructs the number 51.

Before expressions were introduced into programming languages, it took the following tedious steps to evaluate this expression:

  Load 5 -> x
  Load 7 -> y
  Add  x,y -> x
  Load 4 -> y
  Mult x,y -> x
  Load 3 -> y
  Add x,y -> x

DirectAnimation uses an expression-based approach to construct more complex media values based on simpler media values and operations working on these values. For example, the expression

frontImage*rotation + backImage

Evaluates to a rotating image overlaying a second image, just like the above expression evaluates to 51.

Just as in number algebra a set of operations and numbers combines to return a result according to certain rules, in DirectAnimation a set of operations on animation and media elements combine to produce interesting interactive, animate and mixed-media content. You can apply many of the concepts of algebra to constructing interesting animation in DirectAnimation.

DirectAnimation has a set of abstract data types, for example, a number behavior (NumberBvr) or a color behavior (ColorBvr). Abstract types are described in terms of the high-level operations they support without exposing implementation or representation details. Since it is typical to have thousands of behaviors in an animation, thinking of behaviors as operations on abstract data types can help make the complexity manageable. Operations create composite behaviors; for example, angle = sin(NumberBvr theta), or redGeo = geo.diffuseColor(ColorBvr red), applies the color constant red to a geometry.

As in algebra, where in an expression such as angle = sin(t* 2*pi/period) t is time, behaviors in DirectAnimation can be time-varying. DirectAnimation generalizes time-varying values beyond numbers. For example, you can construct a time-varying image as follows:

ImageBvr image3 = overlay(image1.transform(rotate(localTime)), image2)

This expression sets image3 to be image1 rotating at one radian per second and overlaying image2.

Behaviors Are Retained

Time-varying behaviors in DirectAnimation are retained, in the sense that executing a behavior expression (such as the one in the previous section) constructs a data structure that is retained after the execution concludes. This is unlike traditional number expressions in programming languages where the expression evaluates conclusively into a result at the time of execution. In this respect, DirectAnimation expressions are more like cells in a spreadsheet; they don't execute just once, but are retained and their value changes as their parameters (other behaviors) change.

Using behavior expressions relieves the developer of significant maintenance work. For example, assume you have defined a path behavior (Path2Bvr ) called line and a transformation behavior (Transform2Bvr) called wiggle that is a sinusoidal translation. You can then combine them into a time-varying image behavior (ImageBvr ) called wigglingLine. You can then import an image (perhaps a JPEG from a file) and call it background, and overlay wigglingLine on background. Call this time-varying image myImage.

Now, assume you have imported or synthesized a 3-D cube and assigned it a path to traverse or a rate at which to expand. You can texture the animated cube with myImage and get a cube that is both animated and has an animated texture. Once you have joined the texture to the cube, since this joining is retained, the texturing operation keeps checking the time-varying value of its wiggling line, calculating the result, and applying the new texture to the cube. The programmer constructs the relation between the texture and the cube, and then doesn't need to intervene any further. If, on the other hand, the line is fixed and not wiggling, DirectAnimation is optimized not to calculate texture values over and over and thus saves CPU cycles.

Reactive Behaviors

There are two key concepts in DirectAnimation: continuous behaviors and events. These are combined into reactive behaviors. A reactive behavior varies continuously with time and reacts to specific events by switching to new behaviors. For example, a ball bouncing (moving on its path) in a room is a continuous behavior. The ball colliding with the wall or floor is an event.

For example, say you have imported two geometries (from two .X files, for example) that are 3-D balls, with radii r1 and r2, separated by a time-varying distance d. You can define a collision event as:

Collide = Predicate(leq(d, add(r1, r2))

That is, when the distance between the two balls is less than or equal to the sum of their radii, they collide.

This event can be used as follows:

bvr1 = until (initial_behavior, Collide, bounce_behavior)

The until operation constructs a behavior which starts as an initial behavior (such as "parabolic path") until the event occurs, then switches to a bounce behavior. The behavior switched to after the event can be constant (the ball stops) or calculated from parameters at the time of the event (a new path calculated from the ball's position and direction of the two balls at the time of the collision). Thus, until creates a new reactive behavior (bvr1) that is the first behavior until the event occurs, and then becomes the second behavior.

Similarly, it is possible to define an event based on the user selecting one of the balls by pointing and clicking:

Grab= andEvent(Pick, leftButtonDown)

And used as follows:

bvr2= until(parabolic_path_behavior, Grab, follow_mouse_position_behavior)

Or you can make the ball explode on either event as follows:

Explosion = orEvent(Collide, Grab)
Explosion_Bvr = until(parabolic_path_behavior, Explosion, flying_ball_fragments_behavior)

DirectAnimation supports both arrays and tuples. An array is a homogeneous list of behaviors (behaviors that are all of the same type, such as all colors or all images). A tuple is a heterogeneous list of behaviors (behaviors that can be different, such as a color behavior and an image behavior). Tuples are especially useful for grouping behaviors that all switch at the same event. For example:

Synch_tuple = until(tuple1, event, tuple2)

This helps to synchronize the switching of different behaviors at one event.

Interactive Versus Reactive Behaviors

Reactivity is the notion of switching from one behavior to another based on some event. Interactivity is the notion of user input and how it influences the progression of the animation. Events can be based on user input (such as a button press) or they can be synthetic (based on computations, such as the collision event discussed previously). User input can be in the form of an event or it can be in the form of a continuous behavior such as moving the mouse cursor. For example, a user can drag the ball with a mouse to give it continuous motion, or click on the ball and stop it with an event. Both plain behaviors and events can be either interactive or computed (synthetically generated).

Media Graphs

DirectAnimation supports rich operations on media types that result in expressions producing composite media values. These expressions construct retained structures that are called a media graph that operates on time-varying entities. Media graphs are akin to scene graphs in 3-D graphics systems, but they differ in that they are mixed-media based and contain combinations of behaviors, events, and user input. User input (as both continuous behaviors and events) feeds into constructed media graphs, which in turn produce visual and audible media behaviors that get presented through a display and speakers.

Media Files Supported by DirectAnimation

DirectAnimation supports the following media file types:

  • 3-D images: .wrl and .x files
  • 2-D images: .gif, .png, .jpg, and .bmp files
  • Video: .avi, .mpg, .mpeg, .mpv, .mp2, .mpe, .mov, and .qt files
  • Audio: .mid and .wav files

DirectAnimation supports all the audio and video file types supported in DirectShow. If the user has a DirectShow filter installed for a particular format, such as DV or Line 21 (for closed captions), then this format will also be supported.

Scripting

The DirectAnimation scripting interfaces make it easy to use DirectAnimation from an HTML environment. The library provides a set of methods for animating multimedia elements such as images, sprites, movies, sound as well as 2-D and 3-D objects. It includes support for animation paths, rotations, and other transformations. A timeline sequencing feature makes it possible to build lifelike animations using simple components as modular building blocks.

The library works in cooperation with the DirectAnimation integrated-media control (DAViewerControl). Library calls are made through a scripting language, such as JScript or VBScript, to construct an animation and play it in the Dynamic HTML compositing space.

Typically, you declare your DAViewerControl object as shown in the following JScript sample. The object's name can be anything. Here it is DAControl. The CLSID must be as shown:

<DIV ID=controlDiv>
<OBJECT ID="DAControl"
        STYLE="position:absolute; left:10; top:10;width:500;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

<SCRIPT LANGUAGE="JScript">
<!--
   m = DAControl.PixelLibrary;
   ...
//-->
</SCRIPT>

The variable "m" is shorthand for the DAStatics Library. Every function and property that is in that library needs to be preceded by an "m" so the interpreter knows where to find them. For example:

  myImage = m.SolidColorImage(m.Red);

In this example, SolidColorImage is a DAStatics function that creates a DAImage object, and Red is a DAStatics property that defines the color red.

Once you have constructed the renderable media type (an image or sound), you tell the DAViewerControl object what to display, as shown in the following JScript code:

   DAControl.Image = myImage;
   DAControl.Sound = mySound;

Then tell the object to start the model with the Start subroutine, as shown in the following JScript code:

   DAControl.Start();

The DAViewerControl has the CLSID B6FFC24C-7E13-11D0-9B47-00C04FC2F51D and is a windowless control, so it can be used with Dynamic HTML, and it can be used over or under other objects on the screen. DirectAnimation also provides the more traditional windowed control (class DAViewerControlWindowed) with the CLSID 69AD90EF-1C20-11D1-8801-00C04FC29D46. If you are working in a traditional environment, such as Visual Basic, it is recommended that you use the windowed control.

The Statics Class

The DAStatics class (in Java, the com.ms.dxmedia.Statics class) collects all the static functions and constants provided by the other classes and makes them available as static methods on the DAStatics (Java Statics class. In scripting languages, this means all the static functions and constants are available through the control object. For example:

<DIV ID=controlDiv>
<OBJECT ID="DAControl"
        STYLE="position:absolute; left:10; top:10;width:500;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

<SCRIPT LANGUAGE="JScript">
<!--
   m = DAControl.PixelLibrary;
   ...
//-->
</SCRIPT>

After this declaration, every function, property, and constant that is in the DAStatics library needs to be preceded by an "m" so the interpreter knows where to find them. For example:

  myImage = m.SolidColorImage(m.Red);

In Java, all of the static methods in the Statics library become available without qualification. For example:

ImageBvr im = solidColorImage(blue);

If programmers want to write DirectAnimation code outside of a Model class and not have to qualify their calls to static methods, they can create their own class that extends the DAStatics class. If this is not feasible (because the class already extends another class) then explicit name qualifications are required.

Naming Conventions in DirectAnimation

This section discusses the naming conventions used in the COM API, which are exposed to JScript and VBScript users. In COM and thus in scripting when two similar methods differ only in the type of at least one of their parameters, then these two methods must have different names. This is in contrast to other languages such as Java and C++, which make it possible to use the same method name in such a case. For this reason, in the Scripting Reference you'll find different variations of essentially the same method, with slightly adapted names. The different suffixes that are used are as follows:

  • Anim
  • Rate
  • Degrees

Anim Naming Convention

The functions with Anim in the name, such as Point2Anim, are counterparts of the non-Anim versions, such as Point2. The difference is that the Anim versions take time-varying parameters, and produce animated results. Functions with Anim take animated parameters of type DANumber or DAString. Functions without Anim take parameters that are doubles, integers, and regular strings. For example the following two statements are equivalent:

   M = DAControl.PixelLibrary;
   P1 = m.Point2(34, 100);
   P2 = m.Point2Anim(m.DANumber(34), m.DANumber(100));

(Note that DANumber(x) converts the regular number x into a number behavior.)

Since the second form is longer, what is its value? It is necessary if you want to construct a time varying point. For example:

   //constructs a number that varies between 34 and 50 in 3 secs.
   xNum = m.SlowInSlowOut(34, 50, 3, 0);
   // constructs a point that travels on the Y = 100 line, between the two X values in 3 secs.
   P2 = m.Point2Anim(xNum, m.DANumber(100));

P2 is a time-varying point that can be used to build other time-varying entities. For example, it can be used as a parameter to Translate2Point. Note that in cases where there is no non-Anim version of a certain function then the Anim suffix is omitted even if the function's parameters are time-varying, as is the case with Translate2Point.

Rate Naming Convention

Sometimes to construct time-varying values it is easier to specify the rate of change of the value than to specify the value itself. DirectAnimation provides variations to functions that accept rate-of-change parameters as a convenience. For example:

   RotXf = m.Rotate2Rate(Math.PI/3);

This code constructs a time varying 2-D rotation of PI/3 per second, and is equivalent to:

   RotXf = m.Rotate2Anim(m.Mul(m.LocalTime, m.DANumber(Math.PI/3)));

Note that Mul is for multiplying two DANumbers together, and LocalTime is time, which increases by one unit per second.

Degrees Naming Convention

Methods with the Degrees suffix take their angle parameters in degrees as opposed to radians. These are, again, convenience functions that spare the user from doing the conversion explicitly, if the user chooses to specify angle parameters in degrees. For example, consider the following statement with radian parameters:

   RotXf = m.Rotate2Rate(Math.PI/3);

This can be expressed with degrees as:

   RotXf = m.Rotate2RateDegrees(60);

Viewing DirectAnimation Functions in Visual Basic

To view the DirectAnimation library functions in Visual Basic, follow these steps:

  1. Install DirectAnimation.
  2. In Visual Basic, choose Components from the Project menu. A Components dialog box appears.
  3. On the Controls tab, check the box next to DirectAnimation Library, and click the OK button. The DAViewerControl will appear as a choice in the Toolbox.
  4. Click on the control in the Toolbox, then draw the control onto a form.
  5. Choose Object Browser from the View menu. The object browser appears.
  6. At the top left of the object browser (where it says All Libraries), choose DirectAnimationCtl from the drop-down list.
  7. Click a class or interface to display its functions.
  8. Click a function to display its Visual Basic syntax (at the bottom of the object browser).

A Simple JScript Example

The following code creates a red oval and spins it around. To create this JScript example, follows these steps:

  1. Declare the DAViewerControl windowless control with an <OBJECT> tag.

    You can use any name for the control. You can set the control's position and size on the HTML page by specifying the value of the left position, the value of the top position, and the height and width of the control. You can also specify whether the windowless control appears underneath other images and text on the page, by specifying z-index: -1.

    <OBJECT ID="DAControl"
  STYLE="position:absolute; left:30%; top:100;width:300;height:300;z-index: -1"
  CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
  2. In the scripting section of your HTML file, declare a DAStatics library object (m in the example below) and attach it to either the PixelLibrary or MeterLibrary.

  m = DAControl.PixelLibrary;
  3. Access functions and subroutines in the DAStatics library through the object (m in the example below) to create or import your media types (such as images, movies, and sound) and animate them.

  fillImg = m.SolidColorImage(m.Red);
  4. Set the media to be displayed as a property of the DAViewerControl object, either the Image property or Sound property.

  DAControl.Image = finalImg;
  5. Invoke rendering of the control with Start(). Whatever Image property or Sound property the DAViewerControl object has when started determines what will be rendered.

  DAControl.Start()

Click the Show button to display the JScript example. To see the code, right-click the title "Simple Sample" and choose View Source from the shortcut menu.

You can add interaction to this sample by changing the code to respond to a user-initiated event. You can make an image red until the left mouse button is clicked, then turn it green with the following statement:

  fillImg = m.Until(m.SolidColorImage(m.Red), m.LeftButtonDown, m.SolidColorImage(m.Green));

The Until function causes fillImg to be red until the LeftButtonDown event occurs, then turns fillImg green.

A Simple Java Example

The following "Hello, World" example demonstrates some of the basic steps involved in developing a DirectAnimation application. The first step uses DirectAnimation for Java to construct an applet that, when displayed, results in a rendered text string that says "Hello, World." There is no animation and no interaction.

import com.ms.dxmedia.*;
public class MyModel extends Model {
  public void createModel(BvrsToRun blist) {
    FontStyleBvr fs = defaultFont.family(toBvr("Arial").color(blue).bold();
    ImageBvr tx = (toBvr("Hello, World"), fs);
    setImage(tx);
  }
}
public class MyApplet extends DXMApplet {
  public void init(){
     // Always call the superclass's init() first to ensure codeBase is set
     super.init();
     // Now set the model
     setModel(new MyModel());
  }
}

This DirectAnimation applet simply renders a piece of static text. You can make this example more interesting by adding just a few more lines of code. First, however, you must understand how the initial example works.

The DirectAnimation Model class includes the abstract createModel method. MyModel subclasses Model and implements createModel to build behaviors; this example has a string behavior and an image behavior. The createModel method then calls the setImage method to set the model's image behavior.

The DirectAnimation ImageBvr type is constructed by converting a character string ("Hello, World") into a ImageBvr behavior with the toBvr method. The toBvr method converts the literal string "Hello, World" into an image of the text with the font style specified in the defaultFont method.

Next, MyApplet subclasses the DirectAnimation DXMApplet subclass of the Abstract Windows Toolkit (AWT) Applet class. This initializes its superclass DXMApplet to take an instance of the MyModel class. When the applet is invoked, DirectAnimation builds the model (by invoking createModel) and displays it in the applet.

Adding Animation

A small addition to the previous code causes the text to change color continuously as it is rendered. The MyApplet class doesn't change at all, while the MyModel class is changed to the following:

public class MyModel extends Model {
  public void createModel(BvrsToRun blist) {
    ColorBvr col = colorHsl(localTime, toBvr(0.5), toBvr(0.5));
    FontStyleBvr fs = defaultFont.family(toBvr("Arial")).color(col).bold();
    ImageBvr tx = (toBvr("Hello, World"), fs);
    setImage(tx);

  }
}

One line was added to the createModel method. It defines a color, using the colorHsl method. This method allows you to define a color using the Hue, Saturation, Lightness (HSL) model. The colorHsl method takes 0.5 for its saturation and lightness arguments, but uses the built-in behavior called localTime for the hue. The localTime behavior is a time-varying value of type NumberBvr that increases at the rate of one unit per second. Values of all the defined DirectAnimation types are potentially time-varying and interactive.

Using localTime in a color-producing method such as colorHsl yields a time-varying color. Using this time-varying color as an argument in the font style color(col) method yields a time-varying font color. Attaching the time-varying color value to text that is converted into an image produces a time-varying image. Because setImage now sets a time-varying image, the result of this code is an image that is animated.

Note that the entire applet is as you see it. No other methods are required and, in particular, there is no need for a frame loop, even though the applet is displaying an animation. For programmers who have been using the awt.Graphics package to do animation, this means you do not need to worry about threads, while() loops, or repainting the screen.

Adding Simple Interaction

The next step is to add some simple interactivity. The new version of MyModel, listed below, uses the time-varying color until the left mouse button is pressed. It then changes the color to red.

public class MyModel extends Model {
  public void createModel(BvrsToRun blist) {
    ColorBvr col = colorHsl(localTime, toBvr(0.5), toBvr(0.5));
    ColorBvr mouseCol = (ColorBvr)until(col, leftButtonDown, red);
    FontStyleBvr fs = defaultFont.family(toBvr("Arial")).color(mouseCol).bold();
    ImageBvr tx = (toBvr("Hello, World"), fs);
    setImage(tx);
  }
}

A single line of code adds the ability to be respond to the mouse:

until(col, leftButtonDown, red);

This expression produces a color behavior that is initially col and remains so until the leftButtonDown event occurs. When this happens, col changes to red. There is still no need to provide a frameloop. In addition, there is no need to provide an event detection/response loop (to wait for the leftButtonDown), because this is dealt with explicitly in the implementation of the until method.

As this sample shows, time-varying, interactive behaviors are constructed out of media data types and operations. The DirectAnimation run-time system then takes on the task of animation, event detection, and media presentation.

Coordinates in DirectAnimation

The DirectAnimation API uses continuous temporal and spatial 2-D and 3-D coordinate systems. The basic unit of time is the second. The basic unit of space is the meter. The x-axis is the horizontal axis, increasing to the right. The y-axis is the vertical axis, increasing upward. Three-dimensional coordinates are y-axis up, positive z-axis near, and negative z-axis far.

The following diagram demonstrates these coordinate systems.

Image coordinate systems

DirectAnimation provides several mechanisms for handling these differences. Fundamentally, the DirectAnimation coordinate system is a meter-based system. When PARAM tags are used to specify all or part of the model, the coordinate system will implicitly be that of HTML. When the library mode of the DirectAnimation control is set to pixel mode the coordinate system is converted from the DirectAnimation default to the pixel convention. With these methods, the scripter can construct models in resolution-independent units. For example, in JScript:

  m = DAControl.PixelLibrary;

- or -

  m = DAControl.MeterLibrary;

This section discusses the following topics:

  • HTML and Pixel Coordinates
  • Units
  • Working with Pixel Values
  • Continuous Coordinate Systems
  • Image Coordinate System
  • Geometry Coordinate System
  • Meter-Based Space
  • Pixel-Based Space
  • Center-Based Positioning

HTML and Pixel Coordinates

HTML uses device pixels as the standard unit of measure with a left-handed coordinate system with the y-axis down and the origin in the upper left corner. When PARAM tags are used to specify animations the coordinate system is that of HTML. The DirectAnimation client controls use a pixel-coordinate system with the y-axis down and the origin in the center of the window.

DirectAnimation is fundamentally a meter-based coordinate system, which is preferred for resolution independent animation. However, DirectAnimation provides the pixel construction mode as a convenience for users who are familiar with the HTML coordinate system and would like their animation coordinates to match that as closely as possible.

When using the PixelLibrary (as opposed to the MeterLibrary) the 2-D coordinate system is left handed with the positive Y axis going downward, and has a centered origin (not an origin in the upper-left-corner, as in the HTML coordinate system). See the sample in Samples\DA\JScript\Templates\CoordsAndPath.html for a detailed example of the pixel construction mode. Also, compare the PixelMode.html and MeterMode.html samples in Samples\DA\JScript\Exercises. All 2-D coordinate references such as points, paths, and translation factors in this construction mode are interpreted as pixel-valued. Note that this is a construction mode only, so when you extract information back, like extents, you get them in meters, since these are the units in the internal representation. For advanced animations, the meter mode is strongly recommended, especially since the conversion from meter to HTML coordinate space is a single transform.

Units

The DirectAnimation API tries to ensure that one unit is actually 1 meter in physical space, but variables such as monitor curvature and monitor controls that change the display area prevent complete accuracy.

DirectAnimation provides predefined constants that you can use as multipliers to convert to other units, including cm, foot, inch, meter, mm, and pixel.

Working with Pixel Values

Given that pixel size differs from one display to another and even across different settings of the same display device, DirectAnimation provides a built-in number behavior, pixel, which is the dimension of a pixel in meters. The pixel is a scalar because the pixel is a square.

The pixel constant allows an author to coordinate synthetic imagery precisely with imported bitmaps regardless of the display resolution.

Continuous Coordinate Systems

Continuous coordinate systems, such as those used by DirectAnimation, provide some key advantages. They remove problems of device- and resolution-dependence, allow for more portable content, and provide more flexibility to the implementation. However, continuous coordinate systems do not always meet the needs of programmers. For example, in addition to continuous time, DirectAnimation also provides the mechanism for applications to control frame generation through application-generated time ticks. Similarly, in spatial coordinates, it is generally the case that a programmer who imports a GIF or JPEG file wants it displayed at the same resolution at which it was authored and stored. For this reason, DirectAnimation supports pixels.

Image Coordinate System

The image coordinate system is called the image plane. Depending on whether the PixelLibrary or MeterLibrary is used, or if PARAM tags are used, the default unit of measure is pixels or meters, and the coordinate system is in pixel coordinates (origin centered, y down), meter coordinates (origin centered, y up), or HTML coordinates (origin in the upper left, y down).

All image and 2-D geometric primitives live in this same continuous coordinate system. This includes all of the Vector2, Point2, Transform2, Path2, Matte, Text, Montage, and Image values.

On its own, the image plane extends infinitely, with an origin and x- and y-axes. DirectAnimation images are constructed in this abstract coordinate system. However, when it is time to display a DirectAnimation image, a certain section of the infinite plane is mapped on a region of a display device called a viewport, as shown in the following illustration.

The programmer decides what the display region or viewport will be. The mapping from the image plane into the viewport is straightforward. The origin of the image plane is mapped to the center of the viewport, and then the mapping happens in like units of measure. For example, if there is a red point 2 centimeters above the origin in the image plane, this point would map to a red pixel 2 centimeters above the center of the viewport. (Note that windowless controls commonly don't occupy their full viewports.)

Geometry Coordinate System

The geometry coordinate system is a 3-D coordinate system of infinite extent where geometric models are specified and transformed. The default unit of measure is the meter. It has an origin and x-, y-, and z-axes. The coordinate system is a right-handed one, as shown in the following illustration.

Geometry coordinate system

The following illustration shows the direction of positive rotation along an axis of rotation (the arrow points in the positive direction).

DirectAnimation geometric models are constructed in this abstract coordinate system. However, you must have a camera to display a model. The camera projects infinite space into an infinite plane, which is the image plane discussed in the Image Coordinate System section. In other words, the 2-D image plane is the 3-D projection plane, because the result of projecting geometry through a camera is an image. The resulting abstract image is amenable to the same operations and rules as other images, including the display through a viewport.

Meter-Based Space

In a meter-based 2-D-composition space, 3-D models are authored to a certain size in meters, which is to be preserved in all renderings, and images are imported and scaled into a predetermined size, also in meters, independent of the pixel resolution. You can determine how much to scale an image by determining the bounding box of the imported image, comparing the desired size to the bounding box, and using that factor to scale the image. This effectively compensates for pixel size variability.

While this technique has the advantage of being independent of the device resolution, you need to scale images before displaying them. It thus requires more processing than simple pixel blitting and is prone to pixel aliasing.

Pixel-Based Space

In a pixel-based composition space, images are imported and displayed in a pixel-to-pixel mapping onto the screen, which is the traditional method in 2-D sprite systems and content (for example, 2-D sprite-based games and Director content). While the result is device-resolution dependent, there are several benefits. One is the large amount of legacy material written in this method. The reuse of this content requires using this pixel-based space.

In addition, because the pixels are mapped pixel-to-pixel, without any transformations, this method tends to be very fast and avoids pixel aliasing. The 3-D parts must be scaled based on the pixel size, so that when they are projected into the image plane they have consistent proportionality and coordination with the 2-D images.

Center-Based Positioning

When DirectAnimation imports or constructs an image, it is centered on the origin in the image plane. Similarly, when an image is created by rendering text (which takes no coordinates as parameters), it also is centered on the origin. The center of a camera's field of view coincides with the origin of the image plane. This means that scenes, when rendered into images, are centered on the origin.

Scripting Timelines Using Duration

A key concept behind DirectAnimation is the idea of "video editing" or "media timelines." Editing a video sequence and moving a sprite (subimage) along an animation path are conceptually very similar. Both scripted animation, such as that used in multimedia applications, and natural media, such as recorded sound and video, are sequences of clips. Each clip has a local timeline. Each can be used in more than one place on the screen (compositing) or in more than one place in time (sequencing). DirectAnimation uses the term behavior to denote these fundamental building blocks of media presentation.

A DirectAnimation behavior is a subsequence of media with its own timeline. You build an animated presentation by sequencing and compositing (overlaying or rendering) the behavior subsequences. DirectAnimation behaviors support a range of media types. For instance, there are image behaviors that treat video, cel animation, sprite (subimage) animation, and animated line graphics uniformly. There is a sound behavior for mixed, parameterized audio. Animated light behaviors illuminate three dimensional scenes.

Timelines are animation fragments of (typically) fixed duration that can be sequenced together to form complex behaviors. Timelines are a flexible mechanism for constructing, manipulating, and running sequences of animation. For example, consider the following JScript code:

 startPt = m.Point2(25, 50);
 endPt = m.Point2(150, 50);
 myPath = m.Line(startPt, endPt);
 followPath = m.FollowPath(myPath, 5);

The FollowPath method creates a behavior of fixed duration that represents movement along a geometric path (myPath) that lasts five seconds. There are several ways to create timelines. The most general way is to construct an animation fragment by setting a Duration for a behavior. For example, in the following JScript example, colors are given a duration of 5 seconds:

color1 = m.Red.Duration(5);
color2 = m.Green.Duration(5);
myImage = m.SolidColorImage(m.Sequence(color1, color2));

In general, you can think of behaviors as animations (movies, sounds, sprite animations, 3-D animations, and so on) that run forever.

Consider the following JScript sample:

This script draws a red circle that moves in a straight line. It starts at the beginning of the line, waits 1 second, and then starts to move. It goes from the beginning of the line to end in 4 seconds. It repeats these actions 3 times and then stops at the end. To view the source code, right-click anywhere on the title "Sequencing" title and select View Source from the menu that appears. All measurements are in pixels, so the code uses the PixelLibrary. Because the control is windowless, the red circle can pass on top of or underneath the button. It passes underneath the button if you specify z-index: -1 in the <STYLE> tag within the <OBJECT> tag, as shown in this example.

Arrays and Tuples

A common way to construct behaviors is to loop through a sequence of other behaviors over time. Examples include flipping through pre-rendered images or a list of colors. DirectAnimation supports this through the DAArray and Java ArrayBvr types.

The following JScript sample constructs a DAArray object from an array and uses the NthAnim function with a time-varying parameter to cycle through the array. Click on the title "Array Sample" and choose View Source to see the source code:

The following Java code constructs an ArrayBvr out of a Java array, and uses the nth method with a time-varying parameter to cycle through that list.

ColorBvr[] arr = { red, green, blue, yellow, green, cyan, magenta };
ArrayBvr arrBvr = new ArrayBvr(arr);
// build an indexer to go from 0 to length - 1, then back to 0, etc.
// going at a rate of one unit per second.
NumberBvr indexer = mod(localTime, toBvr(arr.length -1));
// Use this to index into the ArrayBvr.
ColorBvr cyclingCol = (ColorBvr)arrBvr.nth(indexer);

Note that while nth takes a NumberBvr, it uses the greatest integer value less than the number's value to determine the index. The array's index starts at base 0 and any attempt to index beyond its length generates a run-time error.

Tuple behaviors (DATuple and Java TupleBvr) are the same as array behaviors, except that a tuple object can contain behaviors of different types(such as a DAColor and a DAImage), while the behaviors in an array object must all be the same type. Tuple objects are useful for grouping behaviors that all switch at the same event. For example:

SynchTuple = m.Until(tuple1, event, tuple2);

This helps to synchronize many different behaviors to one event.

Note that unlike array behaviors, a tuple behavior cannot have an animated index.

URLs and Paths

Paths in DirectAnimation are created by building a URL base, and then adding relative paths to the base. For example:

  mediaBase = "..\\..\\..\\..\\media\\";
  sndBase = mediaBase + "sound\\";
  imgBase = mediaBase + "image\\";
  geoBase = mediaBase + "geometry\\";

  mySnd = m.ImportSound(sndBase + "clock1.mp2").Sound;
  myImage = m.ImportImage(imgBase + "bird.gif");
  cubeGeo = m.ImportGeometry(geoBase + "cube.x");

When you install the DirectX Media SDK, geometry, image, and sound files are installed by default in DXMedia\Media\geometry, DXMedia\Media\image, and DXMedia\Media\sound directories, respectively. Your path should be the relative path to your media files from where your HTML file resides.

Alternatively, you can specify the URL absolutely. For example:

 mySnd = m.ImportSound("file://c:/dxmedia/media/sound/clock1.mp2").Sound;
 myImage = m.ImportImage("file://c:/dxmedia/media/image/bird.gif");

In Java, a base URL is set for you automatically. When you build a Java applet, the base URL is set by default to the directory from which your class files are loaded. If you are creating an application instead of an applet, the base URL is set by default to the current working directory. You can also set the base URL explicitly with the setImportBase method, as shown in the following Java code:

try {
   setImportBase(new URL("file:/c:/dx/dxm/media/image/"));
} catch (MalformedURLException exc){
   System.out.println("Bad URL - " + exc);
  }

The URL you specify in setImportBase can be any fully-qualified URL. For example:

setImportBase(new URL("http:/www.mycompany.com/MediaLib/"));

To build your full URL relative to the URL base, you retrieve the URL base with the getImportBase method, and then complete your path relative to this base. For example, if your applet was built in the directory C:\Dxm\Samples\DA\Java\MyApp, the following code would set the URL mediaBase to C:\Dxm\Media.

URL mediaBase = buildURL(getImportBase(),"../../../Media/");

You then use the URL base as shown in the following code:

   ImageBvr image1 = importImage(buildURL(mediaBase, "image/apple.gif"));
   ImageBvr image2 = importImage(buildURL(mediaBase,"../../MyMediaLibrary/MyImages/peach.gif");

You can also override the base URL and specify a fully-qualified URL. Note that the URL does not become the default base URL.

URL altURL = buildURL(getImportBase(),"file:/c:/dx/dxm/media/image/);
URL anotherURL = buildURL(getImportBase(),"http:/www.mycompany/MediaLib/");

You could then import images as show in the following code:

ImageBvr img1 = importImage(buildURL(altURL, "apple.gif"));
ImageBvr img2 = importImage(buildURL(anotherURL, "pictures/orange.gif"));

You can also import from absolute URLs without building a URL base. For example:

ImageBvr img1 = importImage(buildURL(getImportBase(), "file:/c:/dx/dxm/media/image/apple.gif"));
ImageBvr img2 = importImage(buildURL(getImportBase(), "http:/www.mycompany/MediaLib/pictures/orange.gif"));

Drawing Surface

The core DirectAnimation API is based on values and expressions. In contrast, the Drawing Surface API provides an alternative style in which methods are used to set a context and then primitives are rendered based on this context. The context can be saved into a stack and restored. The Drawing Surface API is limited to constructing 2-D vector models, so to get to broader features such as sound, images, and 3-D, use the core API.

You can use the Drawing Surface API in conjunction with the core API. After a 2-D vector model is constructed, it can be rendered into an image and then combined with images based on the core API. In the VBScript sample Runners (\Samples\DA\VBScript\Showcase\Runners.html), the runner model is constructed using the Drawing Surface API, while the animation is constructed using the core API. For basic Drawing Surface samples, see Samples\DA\JScript\Templates\BasicDS.html and Samples\DA\VBScript\Templates\BasicDS.html.

The DADrawingSurface class uses a style of drawing that depends on a graphics context. This is in contrast to the other DirectAnimation classes that use a constructive approach. The constructive approach combines primitive data types into a more complex model, in a hierarchical fashion.

The graphics context approach is analogous to a pen plotter, where the pen acts as the mechanical extension of a hand and the plotter acts as a piece of paper. To draw something, the pen is directed to a location on the plotter and then draws the shape. Many people find this approach to be more familiar than hierarchical modeling. For example, to draw the sun in the sky, it may seem more obvious to simply draw a yellow circle exactly where you want it, instead of first drawing a circle, then creating a yellow circle, and then, with a transform, creating yet another yellow circle that is now correctly placed. The difference is in the approach rather than in capabilities.

A DADrawingSurface object maintains a graphics state object for 2-D graphics. This state includes attributes such as line style, fill style, border style, font style, and 2-D transformations. The drawing commands (such as Oval and RoundRect are always interpreted in terms of the current state. See DADrawingSurface in the Scripting Reference for details about the subroutines and functions.

To use a DADrawingSurface functions and subroutines, create a DAViewerControl object in your HTML as usual, then use the DAStatics subroutine NewDrawingSurface to create the DADrawingSurface object, as shown in the following JScript code:

<DIV ID=controlDiv>
<OBJECT ID="DAControl"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

<SCRIPT LANGUAGE="JScript">
  m  = DAControl.MeterLibrary;
  ds = m.NewDrawingSurface();

Once you have the DADrawingSurface object ds, you can use its functions and subroutines. For example, the following JScript code draws a line between the specified x and y coordinates.

  ds.Line(-0.1,.04, 0.01,.04);
  DAControl.Image = ds.Image;
  DAControl.Start();

</SCRIPT>

Consider the following JScript sample:

This script draws two static lines and a rotating line, as well as text. To view the source code, right-click anywhere on the title "Drawing Surface" title and select View Source from the menu that appears.

You can use the Structured Graphics control with the Drawing Surface interface. For example, the following VBScript code uses the Drawing Surface methods with the Structured Graphics control's drawing surface:

<OBJECT ID=SG1
STYLE="POSITION: absolute; HEIGHT:200;WIDTH:200;TOP:130;LEFT:215;VISIBILITY;VISIBLE; ZINDEX:1"
CLASSID="CLSID:369303C2-D7AC-11d0-89D5-00A0C90833E6">
...
</OBJECT>
<SCRIPT LANGUAGE=VBSCRIPT>
...
Sub renderNew
    Set Lib = SG1.Library
    Set DRS = SG1.DrawSurface
    Call DRS.LineDashStyle(0)
    Call DRS.FillColor(Lib.green)
    Call DRS.SecondaryFillColor(Lib.red)
    Call DRS.GradientExtent(0,0,200,0)
    Call DRS.GradientRolloffPower(1)
    Call DRS.FillStyle(9)
    Call DRS.Rect(-75,-75,100,100)
    SG1.DrawSurface = DRS
End Sub
</SCRIPT>

The statement SG1.DrawSurface = DRS resets the Structured Graphics control's drawing surface to what's been created in DRS.

Note on using the DirectAnimation Structured Graphics control with the Drawing Surface interface in the Pixel construction mode:

Although the positive y axis goes downward, angles in the arc and pie functions are interpreted as counter-clockwise. For example, a pie shape created by calling PieDegrees with a starting angle of 0 degrees and an ending angle of 90 degrees will be above the x axis (negative y), while a pie created with a starting angle of 0 degrees and an ending angle of -90 degrees will be below the x axis (positive y).

Splines

DirectAnimation supports animation splines. These are effectively animation paths for numbers, 2-D points and vectors, and 3-D points and vectors. The paths can be linear, quadratic, or cubic b-splines, both rational and non-rational. In DirectAnimation, an animation spline is constructed by supplying an array of knots, control points, and, possibly, weights (all of which themselves are behaviors and are potentially time varying). This creates either a DANumber, DAPoint2, DAPoint3, DAVector2, or DAVector3 behavior.

The CubicBSplinePath function is a form of spline that constructs a 2-D cubic b-spline polynomial path (other forms construct numbers, points and vectors). This path, like any other path, can be stroked as a line, filled by any fill style, or used for extracting a motion path with the FollowPath, FollowPathAngle, and FollowPathAngleUpright functions. See the JScript sample AnnotatedLogo.html in Samples\DA\JScript\Templates where this spline is used as both the shape of the logo and as an animation path for HTML text in a DIV tag.

You need a knot vector and a list of control elements to construct a spline. The control elements (numbers, points, or vectors) relate intuitively to the shape of the spline, while the knots don't. If you want to construct your spline in terms of control elements and not in terms of the knot vector, chose a uniform knot vector with standard end conditions (interpolate first and last points). This means the first and last knots are repeated d times where d is the degree of the spline, and intermediate knots are 1 unit apart. For example, the following JScript function (used in the sample CoordsAndPaths.html in Samples\DA\JScript\Templates) takes a list of 2-D control points, generates the uniform knot vector automatically, and constructs and returns a CubicBSplinePath.

function SimpleSpline(pts) {
    // divide by 2 since 2-D coordinates.
    numPts = pts.length/2;
    // We need 2 more knots (since cubic spline) than control points.
    knts = new Array(numPts + 2);
    // Set the uniform knots. Note that the knot vector doesn't need
    // to start from 0, only the relative spacing between knots is significant.
    for (i=2; i < numPts; i++) knts[i] = i;
    // first knot must have duplicity 3 (the degree) to interpolate first point
    knts[0] = knts[1] = knts[2];
    // last knot must have duplicity 3 (the degree) to interpolate last point
    knts[numPts+1] = knts[numPts] = knts[numPts-1];
    // finally construct and return the spline path.
    return(m.cubicBSplinePath(pts, knts));
}

In the absence of a visual authoring tool for creating splines, it may be easiest to create them by using a pencil and paper with a square grid. Draw the X and Y axes and draw the desired spline, then place points that follow the general shape of the spline, starting and ending with the same point that needs to be on the spline. You need to pick either the PixelLibrary or the MeterLibrary. If you use pixels, place the spline points only on the grid points and map each square length to 25 pixels.


Using Media Behaviors

This section describes DirectAnimation media behaviors and how to use them. Behaviors that are rendered for presentation to the user are called media behaviors and include 2-D image behaviors (the DAImage class and Java ImageBvr class), 3-D geometry behaviors (the DAGeometry class and Java GeometryBvr class), and sound behaviors (the DASound class and Java SoundBvr class). Textures are also covered in this section since texturing often involves an image textured onto a geometry.

This section contains the following topics:

  • Using Images
  • Using Geometries
  • Rendering Geometries into Images
  • Applying Textures
  • Using Sound

Using Images

DirectAnimation can construct or import 2-D images (DAImage objects or Java ImageBvr objects), and can perform sequences of operations on any source of animated images in any order. This section discusses the following topics.

  • Empty Images
  • Constructing Images
  • Operations on Images

Empty Images

DirectAnimation has two types of empty images. An EmptyImage is the null image. It is transparent and undetectable. A DetectableEmptyImage has infinite extent and is transparent and detectable throughout its extent. The DetectableEmptyImage is useful for specifying hot spots in certain images. An image is said to be tangible at a certain point if it is either detectable or nontransparent at that point. Otherwise, the image at that point is said to be nontangible.

Constructing Images

The following approaches can be used to construct 2-D images.

  • Importing bitmaps from GIF, JPEG, and BMP formats.
  • Drawing lines and polygons.
  • Rendering 3-D geometry into an image.
  • Rendering text into an image.
  • Creating polygons with potentially animated colors at the vertices and smooth color interpolation between vertices (gradient fills).
  • Combining two images.
  • Giving images an explicit Z-order in montages.

This section includes the following:

  • Importing Images
  • Creating Images

Importing Images

A basic way to create images is to import bitmaps represented in commonly used formats. This provides good leverage from the many image-authoring tools that currently exist.

The following JScript code shows how to import an image:

 mediaBase = "..\\..\\..\\..\\media\\";
 imgBase = mediaBase + "image\\";
 myImage = m.ImportImage(imgBase + "bird.gif");

The following Java code shows how to import an image:

   //Create a URL base
   URL imageBase = buildURL(getImportBase(),"file:/c:/DxM/Media/image");
   // Create an image behavior by importing an image file
   ImageBvr img = importImage(buildURL(imageBase, "picture.jpg"));

DirectAnimation supports the importation of bitmaps in the .jpg, .gif, and .bmp formats. The string reference to the image can be any valid URL. Importing an image has the following results.

  • The bitmap is imported and returned to the user as a behavior of type DAImage (or the Java type ImageBvr).
  • The image is centered on the origin (0,0).
  • Only the bitmap portion of the image is detectable.
  • When displayed, the image will map to the display window in a one-to-one pixel correspondence with the bitmap in the file from which it was read. This is true provided the image has not been scaled, sheared, or rotated, although translations are acceptable.
  • A bounding-box (which you can extract with the BoundingBox function or Java boundingBox method) surrounds the tangible region of the image and is measured in meters.

The relationship between pixels and meters changes depending on the display resolution. While one display might have a ratio of 18,000 pixels per meter, another display might have a ratio of 22,000 per meter. This means that the bounding box returned for an imported image varies depending on the specific display resolution.

There are ways to work around the device dependency of imported bitmaps. They involve scaling the bitmap in a device-dependent way so that the resultant image size is of some fixed, desired value across the different device resolutions. See Meter-Based Space for a description.

Creating Images

You can create several kinds of 2-D images: solid color, lines, text, geometric images, gradient filled images, and montages. For a discussion of geometric images, see Using Geometries.

This section discusses the following:

  • Hatch Filled Boxes
  • Text
  • Gradient Fill Images
  • Rendering Geometry into an Image
  • Montages

One of the simplest images to construct is a solid color image, as shown in the following example.

    im = m.solidColorImage(m.Blue);

This results in an infinite-extent image with the DAColor behavior Blue. Typically, such an image is cropped or clipped before being used. Solid color images are commonly used to obtain solid-colored polygons or as viewport backgrounds, where the color can be time-varying.

Hatch Filled Boxes

You can also construct images by creating hatch marks in boxes, as shown in the following example with HatchCross:

   im = m.HatchCross(m.Green, 0.2);

Text

You can construct images by rendering text, as shown in the following example with StringImageAnim and StringImage:

  myText = "This is the default font style.";
  defaultFS = m.DefaultFont;
  myTextImage = m.StringImage(myText, defaultFS);

The text, which can have attributes such as font type, color, and style (bold or italic), is rendered into an image with its extent centered on the origin. By default, the text's color is black, its font family is Times-Roman, its size is 12 points, and it is neither bold nor italic.

You can set the text attributes and where the text is displayed. The following code sample renders bold, red text to the screen centered on position posX, posY.

   im = m.TextImage("Hello, World!", m.Font("Arial", 10, m.Red).Bold;
   im2 = im.Transform(m.Translate2(posX, posY));

Gradient Fill Images

Gradient fills provide a very compact form of color images, where regions are filled with smoothly interpolated colors between specified colors at given vertices. For example, you can construct an image from a gradient-filled square, as shown in the following example with GradientSquare:

   im = m.GradientSquare(m.Red, m.Green, m.Blue, m.Yellow);

You can obtain the most general form of a gradient fill through the DAStatics function GradientPolygon(pts, colors), which specifies an array of points and a corresponding array of colors. The arrays specify a triangular mesh with one color per vertex. The resultant image is based on a linear interpolation of the colors across each triangle in the RGB color space. Although interpolation in other color spaces might be desired, DirectAnimation maps this CPU-intensive operation to hardware, which currently performs the interpolation only in RGB.

Other more specialized forms of gradient fills, which are essentially shortcuts based on the general form described in this section, include the following DAStatics methods:

  • GradientSquare(color1, color2, color3, color4), which generates a unit square centered on the origin and with dimensions of 1 unit. The four colors are averaged into a color at the intersection of the diagonals, and then the four triangles delineated by the diagonals have their vertex colors interpolated.
  • GradientHorizontalAnim(start, stop, power)and GradientHorizontal(start, stop, power), which create an image that smoothly interpolates between the start and stop colors. Colors start on the left and go toward the right, based on the power specified by power.

Rendering Geometry into an Image

You can construct 2-D images by rendering 3-D images (geometries) into two dimensions, as shown in the following example.

   Geo = m.ImportGeometry("cube.x");
   Camera =  m.PerspectiveCamera(projPointNum, maxZNum);
   Img = Geo.Render(Camera);

Note that the Camera parameters must be calculated from the size of the geometry and the display viewport.

Montages

An image can be the rendering of a montage (DAMontage) object which consists of a group of DAImage objects, each with a number that indicates its z-order in the list. The ImageMontage(Image, z-order) and ImageMontageAnim(Image, z-order) functions can be used to add images to a montage. The z-order determines how the images will overlay each other. Images with larger z-values are always on top (in front) of images with smaller z-values. If the z-order number is animated (a DANumber object), the order in which the images are layered changes with time. Montages are ideal for situations where the layering of the different images is dynamic.

Operations on Images

The set of DirectAnimation operations can generate new and more complex images from given images. Also, some of these operations generate useful data, such as the bounding-box around a given image.

The operations for composing animated 2-D images include the following:

  • Overlaying animated images.
  • Polygonal clipping of animated images.
  • Transformations such as scale, rotate, shear, and translate.
  • Animated tiling of animated images into a larger animated image.
  • Applying an animated transparency to an animated image.
  • Applying an animated image as an animated texture map.
  • Creating a 2-D animation along a spline.

You can perform any sequence of the above operations on any source of animated images in any order.

Transformations

You can obtain a transformed version of an image by applying the Transform(xf)method, where xf is of type DATransform2 and can be an arbitrary 2-D affine transform. The DATransform2 type has operations for constructing scales, translations, rotations, and shears from basic parameters such as DANumber objects and DAVector2 objects. You also can construct transforms based on 2 × 3 matrices. Additional operations can compose transforms, obtain their inverses, and check whether they are singular.

You can use combinations of time-varying shears, scales, and translations to construct animation from a single image, for example, to move a sprite over a background image.

Using Geometries

In DirectAnimation, you can construct or import 3-D graphics (DAGeometry objects), and perform sequences of operations on any source of animated images in any order.

This section discusses the following topics.

  • Constructing Geometries
  • Operations on Geometries

Constructing Geometries

The simplest way to construct a geometry behavior is to import a geometry from a .wrl or .X formatted file by using ImportGeometryAsync or ImportGeometry(URL). You can also augment geometry with lights, including ambient, directional, point, and spot lights. You can attach a sound source to a geometry, which is used to give 3-D spatial characteristics to a sound by embedding it in other geometric models. Finally, EmptyGeometry is a constant of the GeometryBvr type and is empty.

DAGeometry objects (and Java GeometryBvr objects)can be:

  • Given an opacity attribute.
  • Textured with an image.
  • Given diffuse attributes with color parameters.

All of these attributes can vary with time.

Operations on Geometries

The operations for composing 3-D geometric animations include:

  • Aggregating animated 3-D geometry. You can combine two geometry values with the union operation.
  • Applying animated images as animated textures.
  • Applying animated transparency and color attributes.
  • Transformations such as scale, rotate, shear, and translate.
  • Projection with animated perspective or parallel cameras to an animated image.
  • Animating 3-D attributes using splines (B-spline format).

You can perform any sequence of the preceding operations on any source of animated geometry in any order.

Rendering Geometries into Images

DirectAnimation uses a camera to project a 3-D model (a DAGeometry object) into a 2-D image (an DAImage object) with the DAGeometry function render.

Using Direct3-D as the underlying 3-D mechanism, the Render operation renders/projects a geometry through a camera.

DirectAnimation supports two cameras: the PerspectiveCameraAnim (and PerspectiveCamera) type for perspective projection, and the ParallelCameraAnim (and ParallelCamera) type for parallel projection.

These cameras consist of the following three elements:

  • The image plane, which is the XY plane.
  • A near clip plane that is parallel to the XY plane.
  • A projection point for PerspectiveCamera that lies on the z-axis, and a projection direction for ParallelCamera) that is in the z-direction.

Rendering involves projecting the geometry located on the side of the near plane opposite the projection point into an image on the image plane. The resultant image extends infinitely. If you are interested in only a section of the image, you must use 2-D operations such as Crop or Clip on the image to extract that section.

The following figure shows the relationship between the projection point, the near clip plane, and the image plane.

DirectAnimation cameras have an origin at (0,0,0) that can be transformed. Such transformations affect the placement of the projection point, the near clip plane, and the image plane. You can use translation and rotation for positioning the camera relative to the geometric model being projected.

You can use the x- and y- scales to zoom in or out in relation to the rendered model. Increasing the XY scale results in a zoom out (the rendered image shrinks), while decreasing the XY scale results in a zoom in (the rendered image grows). Control the perspective effect by changing the distance of the projection point along the positive z-axis in relation to the origin (that is, the image plane). The closer the projection point is to the projected object, the more pronounced the perspective effect becomes.

Applying Textures

Just as you can project a 3-D object (a DAGeometry object) as a 2-D image (an DAImage object) through a camera, you can apply a 2-D image as a texture to a 3-D object through texture mapping.

The DAGeometry Texture function takes an image and an existing geometry, and returns a geometry textured with that image. Because images and geometries are such rich data types, this simple texture method is extremely powerful. The following example shows how to apply a texture to an imported sphere.

    Geo = m.ImportGeometry("sphere.wrl");
    Marble = m.ImportImage("image/marble.jpg"));
    MarbledSphere =  Geo.Texture(Marble);

Often a geometry is constructed by importing an existing geometry file. These files usually have 2-D texture coordinates associated with the vertices, generally ranging from (0,0) to (1,1). When these geometries are texture-mapped with images, the texture coordinates are mapped to the identical image coordinates.

Thus, texture map coordinates of (0.3, 0.7) in the geometry map directly to the (0.3, 0.7) point in texture image coordinate space.

The correspondence between texture coordinate systems and image coordinate systems is simple, but also powerful and flexible. Consider the task of making an image wiggle along the first dimension as a texture on a cube. You can achieve this by texture mapping a horizontally wiggling image onto a static cube, as shown in the following example.

   WiggleTexture = OrigTexture.Transform(m.Translate2(m.Sin(m.LocalTime), 0));
   NewCube = OldCube.Texture(WiggleTexture);

If you want to infinitely tile a small texture onto a geometry, you can create a tiled image using the DAImage Tile function, then use that resultant image as a texture.

Using Sound

The DASound object and the Java SoundBvr behavior class implement sound in DirectAnimation. You can import sound from many audio formats, including WAV, MIDI, and MP2 files, or synthesize sound using built-in synthesizer sound sources. You can mix different sounds even if they originated from files of different audio formats. You can also spatialize sound by embedding sounds in 3-D objects and rendering them with a microphone (DAMicrophone or MicrophoneBvr).

Currently, up to two channels are supported for sound in DirectAnimation. Sound also has infinite resolution and each sound wave is continuous, which means that in the abstract model there are no discrete sample values.

This section gives an overview of the following topics:

  • Constructing Sound
  • Operations on Sound
  • Sound Layering Technique

Constructing Sound

You can import sound from a file in the WAV, MIDI, and MP2 formats with the DAStatics functions ImportSound and ImportSoundAsync, or with the Java method importSound.

For example, to import and play a sound in JScript, you can use the following code:

  m = DAControl.PixelLibrary;
  mySound = m.ImportSound("file://c:/dxmedia/media/sound/clock1.mp2").Sound;
  DAControl.Sound = mySound.Loop();

The ImportSound function returns a DAImportationResult object. To return a DASound object you access the Sound property of the DAImportationResult object by appending ".Sound".

If you use the Java SoundBvr method importSound(URL, length), the length of the imported sound, in seconds, is returned as the length parameter. For example:

URL soundBase = buildURL(getImportBase(), "file:/c:/dxmedia/media/sound/");
NumberBvr length[] = new NumberBvr[1];
SoundBvr snd = importSound(buildURL(soundBase,"earth.wav"), length);

You can then use the length parameter as follows:

SoundBvr twoSounds = (SoundBvr)until(snd, timer(length[0]), anotherSound);

If you are not interested in the length, you can set the length to NULL.

DirectAnimation currently has an internal standard for audio format. That format is a dynamic range of 16 bits and a sampling rate of of 22,050 Hz. For best results, you should import audio files with this format because DirectAnimation will convert the files to its internal standard, which may result in degradation if the files are not in the same format.

You can also synthesize sound. As an example, you can mix multiple sine waves. Each sine wave can have different attributes, so the resulting mix can produce many diverse sounds. The DAStatics property and SoundBvr type sinSynth represents a constant tone. The silence property and type represents complete silence. By default, sinSynth produces a 1 Hz tone which is subaudible, so you need to increase the frequency. For example, the following JScript code produces a tone:

 sndMidC = m.SinSynth.Rate(440);

The following Java code also produces a tone.

SoundBvr sndMidC = sinSynth.rate(toBvr(440));

Operations on Sound

You can obtain new sounds from other sounds by modifying sound parameters or by mixing. In DirectAnimation, the DASound class functions Loop(), functions GainAnim and Gain, RateAnim and Rate, PhaseAnim and Phase, PanAnim and Pan (and the Java SoundBvr methods loop, gain, rate, phase, and pan, and the DAStatics Mix function, allow creation of complex-sounding animations with few operations.

The Loop() function takes a sound and repeats it continuously. If you have a sound whose composition changes with an event or user interaction and you tell the sound to loop, it will loop on its individual parts, not on the composition. For example, assume you have a sound that is sound1 until the left mouse button is pressed, and then becomes sound2, and you loop this composite sound, as shown in the following JScript code:

snd =  m.Until(sound1, m.LeftButtonDown, sound2);
loopsnd= snd.Loop();

The resulting sound is a continuous loop of sound1 until the left mouse button is pressed, then becomes a continuous loop of sound2. It does not loop the composite behavior in that it does not loop sound1 until the button is pressed, then cycle through sound2 once, then go back to playing sound1 until the button is pressed again.

The Gain (volume) function scales the amplitude of the sound wave. The Rate function changes the rate of sample playback; for digital audio and synthesized sounds, this scales the frequency and changes the pitch. For audio in MIDI format, this changes the tempo. The Phase function shifts the point in the sound cycle where the sound starts (all sound is cyclic except pure white noise). For positive phase values, the sound starts later in the sound cycle. For negative values, the sound starts earlier in the sound cycle. The GainAnim, RateAnim, and PhaseAnim parameters are animated. The PanAnim and Pan (balance) functions vary the gain in the left and right channels of a stereo sound.

Consider the following JScript sample:

This script draws a red circle that moves in a straight line. The pan parameter varies with the position of a moving ball. To view the source code, right-click anywhere on the title "Panning" title and select View Source from the menu that appears.

You can perform any sequence of the preceding operations on any source of animated sounds in any order.

You can mimic sound effects by using these DASound functions and SoundBvr methods. For example, you can vary the distance between a moving sound source and a listener, by varying the parameter of GainAnim. However, you can achieve much more realistic effects by embedding sounds in a geometry. This also relieves you of the overhead of tracking relative positions and modifying sounds yourself. For example, the following JScript code embeds the sound Snd in the geometry Geo:

//Get the sound and the geometry.
Snd = m.ImportSound("bird.wav").Sound;
Geo = m.ImportGeometry("sphere.x");

//Embed the sound in a blank geometry.
GeoSound = m.SoundSource(Snd);

//Join the sound with the desired geometry.
GeoWithSound= m.UnionGeometry(Geo, GeoSound);

//Create a microphone at the origin.
Mic = m.DefaultMicrophone;

//Move the microphone somewhere else.
Mic2 = Mic.Transform(m.Translate3(5, 4, 5);

//Render the geometric sound.
AmbSound = GeoWithSound.RenderSound(mic2);

Pan

The PanAnim and Pan functions and pan Java method take a sound and move the energy between the left and right channels according to a pan parameter. The pan parameter varies between –1 and +1. In the stereo case, negative values of the pan parameter increase the energy sent to the left channel and decrease the energy sent to the right channel. Positive values of the pan parameter increase the energy sent to the right channel and decrease the energy sent to the left channel. A value of 0 balances the energy between the two channels.

Gain

When authoring sounds in DirectAnimation you should use the full 16-bit dynamic range to provide the best resolution, then use the Gain function or Java gain method to scale the volume of the sounds in your animation.

For example, the following JScript code varies the gain by the the sin of LocalTime:

 DAControl.Sound = mySound.Loop().GainAnim(m.Sin(m.LocalTime));

DirectAnimation assumes all sounds have been normalized to use the full 16-bit dynamic range. Consequently, all sounds seem equally loud. For example, a jet plane and a whisper will sound as though they are the same volume. Sounds can be prescaled with the Gain function. Because there is no way to change the actual gain of a personal computer's amplifier, sounds can only be attenuated. Attenuating a sound is the same as multiplying it by a value between 0 and 1.

In the following Java example, two sounds, which are heard in the left and right channels respectively, will have an equal volume, even though their gains are 1 and 5 because the gain is clamped at 1:

    URL soundBase = buildURL(getImportBase(), "file:/c:/DxM/Media/sound/");
    SoundBvr snd1 = importSound(buildURL(soundBase, "seagull.wav"), null);
    SoundBvr snd2 = importSound(buildURL(soundBase, "surf.wav"), null);
    setSound( mix(
        snd1.gain( toBvr( 1  ) ).pan( toBvr( -1 ) ),
        snd2.gain( toBvr( 5 ) ).pan( toBvr( 1 ) ) ) );

In the following example, the sound in the left channel is louder than the sound in the right channel because their gains are 1 and 0.2:

        setSound(mix(
        snd1.gain(toBvr(1)).pan(toBvr(-1)),
        snd2.gain(toBvr(0.2)).pan(toBvr(1))));

When sounds are embedded in a geometry and spatialized (using the Java GeometryBvr method soundSource and a MicrophoneBvr), even though gains greater than 1 do not produce louder sounds, they do produce sounds that can be heard at a greater distance by increasing the spatial volume that is at maximum sound (for example, a small sphere of maximum sound or a large sphere of maximum sound).

In particular, loud sounds such as a jet engine should be scaled by a gain greater than 1. Unlike sounds in the real world, the sound only becomes louder as you approach until the gain equals 1. Once this limit is reached, there is no more amplification, and the sound's volume remains constant no matter how much closer you come.

The following diagram shows that, for gains larger than 1, the volume is clamped at 1.

Distance vs. gain of 2

Mix

The DAStatics Mix function and the Java mix method merge two sound waves into one by adding the corresponding waves. You can mix any sounds, even if they originated from different audio formats. If mixing produces an overflow value, the result is clamped.

Sound Layering Technique

The operations provided by DirectAnimation on DASound objects (and Java SoundBvr objects) enable the generation of dynamic high-quality synthetic sounds from basic sound seeds by parameterization and layering (or mixing). These sounds can be always fresh and responsive to the action in the animation.

Traditionally, people have authored loops of compressed sounds for ambient noise. This reduces the size of the audio needed but also produces boring sounds, because a loop soon starts to sound repetitive and unrealistic. With DirectAnimation, you can produce much richer, more realistic sounds, for example, a wave sound that amplifies only when the wave actually breaks on the shore in your animation, a seagull cry that follows the motion of the seagull across the viewport, and wind levels that can be controlled by user interaction (see the Lighthouse sample in Samples\DA\Java\Showcase\Lighthouse.html).

You create synthetic sounds by modifying seed sounds with parameters that are random or are related to your animation. These parameters are usually time-varying. You then mix the results together in a way suitable to your animation. Thus, sound can be as flexibly and synthetically generated as 3-D models are. Simple parts are transformed, colored, or textured and then combined together into more interesting models.

For example, the SinSynth function produces a sine-wave based sound, which can be given a variety of attributes to create a diverse set of synthetically generated sound waves. The Lighthouse sample in Samples\DA\Java\Showcase\Lighthouse.html generates an ocean ambient sound modified by the weather condition parameter. The weather condition parameter is controlled by the user with the slider controls. The Lighthouse sample demonstrates two basic techniques for creating sound. One is the generation of parameterized cyclic sounds and the other is the generation of random periodic sounds (the latter has a silent period between the successive occurrences).


Using Behaviors

This section describes DirectAnimation behaviors and how to use them. The basic class in DirectAnimation is a behavior. See DirectAnimation Behaviors, Creating Behaviors, and Displaying Behaviors for an overview of behaviors.

The topic Reacting to Events describes reactive and non-reactive behaviors, events, picking, and all forms of the Until function.

The topic More Ways to Use Behaviors describes many useful ways to use behaviors, including reaction to events, sequencing, switching, time substitution, integrals and derivatives, and more.

This section contains the following topics:

  • DirectAnimation Behaviors
  • Creating Behaviors
  • Displaying Behaviors
  • Adding Behaviors
  • Reacting to Events
  • More Ways to Use Behaviors
  • Using Behaviors in Java Applications

Microsoft DirectAnimation is composed of several tightly integrated technologies. Different media, such as 2-D, 3-D, video, and audio can be used in a single application, and are all handled in much the same way. Once you learn how to manipulate one kind of media (for example, images), you can apply the same techniques to other media types, such as geometries or sound, which simplifies media integration.

  • Enables smooth, high-performance presentation of interactive graphics, sound, and video in both two and three dimensions.
  • Includes optimized run-time services for animation and media streaming. The run-time services are capable of controlling both the frame and event-generation loops for the application.
  • Provides media access for network entertainment and communications applications.
  • Works in an HTML environment. The scripting library provides functions for animating images, sprites, movies, sound, and other 2-D and 3-D objects. The library works in conjunction with the DirectAnimation integrated-media control (DAViewerControl).

DirectAnimation Behaviors

DirectAnimation supports a set of classes and functions (and Java classes and methods) that are used to construct time-varying, interactive behaviors.

DirectAnimation can perform sequences of operations on images, geometry, or sounds. One of the most important features of the media operations available in DirectAnimation is that animations are completely encapsulated and composable. This provides flexibility, expressiveness, and power with a relatively small number of base operations.

Any component of these compositions can be animated and interactive.

The following table summarizes the behaviors available in DirectAnimation.
Category | Scripting Class/Java Class | Description
any | DAArray/ArrayBvr | Arrays of behaviors that are all the same type. Objects can be selected from the array based on a time-varying index.
2-D/3-D DABbox2/Bbox2Bvr and DABbox3/Bbox3Bvr The DABbox2 and Bbox2Bvr behaviors represent two-dimensional bounding boxes. Extracting a bounding box from an image results in a box that encloses all the tangible parts of the image.

The DABbox3 and Bbox3Bvr behaviors represent three-dimensional bounding boxes. Extracting a bounding box from a geometry results in a box that encloses all the tangible parts of the geometry.

logic | DABoolean/BooleanBvr | Animated TRUE/FALSE values. Traditional Boolean operations such as And, Not, and Or are available. KeyState returns a Boolean object that is true when the specified key is down, and false when the key is up.
2-D/3-D | DAColor/ColorBvr | Animated color values in an abstract color space. The run time supports all color bit depths. These behaviors can be constructed by supplying three animated numbers (DANumbers or NumberBvrs)that are interpreted as either Red/Green/Blue or as Hue/Saturation/Lightness components.
3-D DACamera/CameraBvr Movie camera to turn a 3-D scene into an animated image. All camera attributes can be animated. The camera is used with the Render function on DAGeometry to project a geometry onto an image. There are two basic types of cameras: one for parallel projection and one for perspective projection. Both types of cameras are oriented so that they gaze in the negative z direction, with positive y considered up. Both types of cameras have a near clipping plane. This plane (a product of Z-buffered rendering) specifies the closest distance at which an object is visible. Objects closer than the near clipping plane cannot be seen.

Cameras are manipulated through standard three-dimensional transform operations. These transforms modify the camera characteristics and also position and orient the camera.

text | DAFontStyle/FontStyleBvr | Specifies the font face, size, color, and attributes (such as bold or italic). The functions and methods of these behaviors are similar to the HTML tags specifying the font characteristics.
3-D | DAGeometry/GeometryBvr | 3-D geometry, the primary 3-D data type. Can be created by importing .wrl or .X files, by applying transformations to existing geometries, by applying material properties to geometries, by combining multiple geometries, by embedding sound into 3-D, by specifying 3-D lights, by applying DAImages and ImageBvrs behaviors as textures, by varying opacity, and so on. Given a DACamera or CameraBvr, a geometry can be projected onto an image.
2-D/3-D DAImage/ImageBvr Animated images, including cel animation, bitmaps, vector-graphic animations, animated 3-D projections, partially transparent images, and animated textures for 3-D animated geometry. Images can be constructed by importing GIF, BMP, JPEG, and PNG files. Importing a movie (such as an MPEG or AVI file) also constructs an image. Images can be constructed as solid color images, by rendering text into an image, by projecting a 3-D geometry with a camera into an image, by stroking a line with a path behavior, and by creating an image by smoothly varying colors across the face of a polygon. Java AWT Images can also be used to construct a DirectAnimation ImageBvr.

Images can also be created by overlaying two existing images, by applying an opacity value to an existing image, by clipping an image to a matte behavior, by cropping an image to a box, by tiling an image, and by applying a DATransform2 or Transform2Bvr to an image. Any image, even if it is time-varying and interactive, can serve as a texture on a DAGeometry or GeometryBvr.

line | DALineStyle/LineStyleBvr, DAEndStyle/EndStyleBvr, DAJoinStyle/JoinStyleBvr, and DADashStyle/DashStyleBvr | Specify how lines are drawn. DALineStyle provides for dashing, line width, line end, and line join styles when a DAPath2 is being stroked into a DAImage. DAEndStyle defines the shape applied to the end of line segments when they are drawn. DAJoinStyle defines the shape of joints between intersecting line segments in a path. DADashStyle defines whether lines are drawn as a continuous stroke or as a sequence of dashes.
2-D | DAMatte/MatteBvr | Stencils for creating animated cutouts in images. A matte can be constructed by filling in a DAPath2 or Path2Bvr behavior, by constructing it from a text outline, and by performing logical operations (such as union, intersection, and difference) on other mattes.
sound | DAMicrophone/MicrophoneBvr | Used to make sounds seem to have been recorded in a 3-D space. This behavior is used with the RenderSound function on a geometry to extract a 3-D volume of sound from that geometry and produce a DASound behavior.
2-D | DAMontage/MontageBvr | A layered set of animated images with depth ordering, sometimes called 2.5D images. A montage is constructed by providing an image and a potentially time-varying number as the depth value, and by uniting the montages together. The Render function resolves all the depths and constructs a DAImage.
2-D DANumber/NumberBvr Time-varying numbers. For example, the ColorRgb function takes three static numbers (doubles) as parameters for the red, green, and blue values, while the ColorRgbAnim function takes three potentially time-varying DANumbers as parameters.

A Java NumberBvr can be constructed by using the toBvr method on a Java number. Many arithmetic methods are available. These include addition, subtraction, multiplication, division, exponentiation, sine, cosine, random-number sequences, integrals, and derivatives. Additionally, the time-varying seeds for animation, LocalTime and GlobalTime are DANumbers.

2-D | DAPath2/Path2Bvr | Animated 2-D vector graphics (2-D geometry). These behaviors represent lines (one-dimensional paths) through two-dimensional space. Paths have a direction, and can be open or closed. A path can be constructed as a series of connected line segments, as a B-spline curve, as a concatenation of other paths, or as a 2-D transformation of another path. Closed paths can be filled to create images.
2-D | DAPoint2/Point2Bvr, DAVector2/Vector2Bvr | Animated 2-D points and directed magnitudes. Both points and vectors can be constructed by supplying animated numbers (DANumbers or NumberBvrs) that can be interpreted either as Cartesian coordinates or polar coordinates. Available operations include subtracting points to yield a vector, adding a vector to a point, determining the distance between points, creating a point from a B-spline, and taking the derivative of either a point or a vector.
3-D | DAPoint3/Point3Bvr, DAVector3/Vector3Bvr | Animated 3-D points and directed magnitudes. These behaviors are the 3-D analogs of DAPoint2/Point2Bvr and DAVector3/Vector3Bvr behaviors.
sound, 3-D | DASound/SoundBvr | The main sound data type, which can have animated properties such as gain. Sound can be embedded in a geometry to occupy a 3-D space and the rendered with a microphone. Sound can be created by importing MIDI, WAV, and video files, by applying methods that affect gain, phase, frequency, and pan, or by mixing existing sounds. Also, limited audio synthesis is supported.
text DAString/StringBvr Strings of characters. The JScript syntax for creating a DAString is:

   AnimStr = m.DAString("string");

StringBvrs can be constructed from Java strings. Simple operations such as concatenation (ConcatString or the Java concat) are available. For example:

   MyStr = m.ConcatString("My", " String");
2-D | DATransform2/Transform2Bvr | Animated scaling, rotation, shearing, and translation in 2-D. Transformations can be constructed from translations, uniform and non-uniform scales, rotations, 3x2 matrices, and composition of other transforms.
3-D | DATransform3/Transform3Bvr | Animated scaling, rotation, shearing, and translation in 3-D. These behaviors are the 3-D analogs of DATransform2 and Transform2Bvr.
any | DATuple/TupleBvr | Arrays of behaviors that can be different types. Objects can be selected from the list based on an index.

Remember, all attributes of all behavior types can be animated and can react to events.

Creating Behaviors

Once you have declared your DAViewerControl object, as shown in the section on Scripting, you assign a variable to the object (attached to either the PixelLibrary or the MeterLibrary, depending on the units you want to use). Through the variable (m in the following example), you access functions and properties in the DAStatics library. You use these functions and properties to construct behavior types.

    m = DAViewer.PixelLibrary;
    im = m.SolidColorImage(m.Red);

Compound behaviors are produced by operations that take behaviors and produce new modified behaviors from them, rather than by modifying the original behavior. For example:

   mySound = m.ImportSound("file://c:/dxmedia/media/sound/clock1.mp2").Sound;

  // Loop the imported sound with the position-varying pan for 12 seconds, then
  // silence the sound.
  DAViewer.Sound = m.Until(mySound.Loop().PanAnim(panFac),m.Timer(12),m.Silence);

Java behavior types are created by declaring a behavior and assigning it a value, as shown in the following code:

     ImageBvr im = solidColorImage(red);

Compound Java behaviors are produced in the same way as compound scripting behaviors. For example:

      URL geomBase = buildURL(getImportBase(),"file:/c:/DxM/Media/geometry/");
      GeometryBvr geom = importGeometry(buildURL(geomBase,"cube.x"));
      GeometryBvr geom2 = geom.diffuseColor(red);

In this case, the original behavior geom is cube. The new behavior geom2 is a red cube.

Alternatively, because each of these methods produces a value, you could combine them into the following statement:

     GeometryBvr geom2 = importGeometry(buildURL(geomBase,"cube.x")).diffuseColor(red);

Displaying Behaviors

In DirectAnimation, only sound and image behaviors are actually rendered or displayed. The final animation consists of some combination of image behaviors and sound behaviors.

The DAViewerControl class displays DirectAnimation behaviors in an HTML page. Here is an example of how it is specified:

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

The actual behavior to be rendered is set as the Image property or Sound property of DAViewerControl. The rendering is invoked with the DAViewerControl subroutine Start(). Whatever Image property or Sound property the DAViewerControl object has when started determines what will be rendered. For example, the following code displays a solid blue screen:

   m = DAViewer.MeterLibrary;
   DAViewer.Image = m.SolidColorImage(m.Blue);
   DAViewer.Start();

In Java, you must provide an instance of the Model class to view behaviors. The Model class method createModel builds the behaviors to be viewed.

Applications override the Model class and implement the createModel method. This method creates the set of behaviors to be displayed and calls the setImage and setSound methods on the image and sound behaviors that are intended to be viewed.

The DirectAnimation system is responsible for invoking the createModel method.

Behaviors are run as soon as the model starts.

The following code shows how to use the Model class to construct a blue image.

public class RedImg extends Model {
  // Create the image behavior that will be displayed
  public void createModel(BvrsToRun blist) {
    ImageBvr im = solidColorImage(blue);
    setImage(im);
    }
}

Java behaviors that are not part of the model can also be run when the model is started by calling createModel with the BvrsToRun parameter. For example:

public class OutsideBehavior extends Model {
    public void createModel(BvrsToRun blist)) {
        ...
    }
}

The behaviors in blist will be run when the model is started.

Adding Behaviors

The DAViewerControl displays a DirectAnimation model in an HTML page. The DAViewerControl method, AddBehaviorToRun, adds behaviors to the control that are not specified in the model. When the system starts the model, it retrieves these additional behaviors and runs them with the same start time as the behaviors included in the model.

As an example, consider the following VBScript sample, which displays the local time as a text value.

<HTML>
<BODY>
<CENTER><INPUT TYPE="TEXT" NAME="txtInp" VALUE=""></CENTER>
<OBJECT ID="DAControl" WIDTH=400 HEIGTH=300
CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</HTML>
</BODY>

<OBJECT ID="DAControl" WIDTH=400 HEIGTH=300
CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>

<SCRIPT LANGUAGE="VBScript">
Sub window_onLoad
   Set m = DAControl.MeterLibrary
   Set timeVal = m.Localtime
   Set timeVal = timeVal.AnimateProperty( "txtInp.value", "VBScript", false, .01 )
   DAControl.AddBehaviorToRun( timeVal )
   DAControl.Start
End Sub
</SCRIPT>

Reacting to Events

This section includes the following topics:

  • Non-Reactive Behaviors
  • Reactive Behaviors
  • Events
  • Picking
  • The Until Function
  • The UntilEx Function
  • The untilNotify Method (Java Only)
  • Until and LocalTime

Non-Reactive Behaviors

All behaviors can potentially vary with time, react to events, and interact with the user. Non-reactive behaviors are those that are constant or time-varying (but do not react to events).

Constant behaviors are not time-varying. In the previous example in Creating Behaviors, the rotated cube used behaviors that were constant. Using the LocalTime behavior value in the Rotate3Degrees method, you can construct a new red cube to spin around the y-axis at a rate of one degree per second, as shown in the following code:

mediaBase = "..\\..\\..\\..\\media\\";
geoBase = mediaBase + "geometry\\";
Geo1 = m.ImportGeometry(geoBase + "cube.x").DiffuseColor(m.Red).Geo2.Transform(m.Rotate3Degrees(m.YVector3, m.LocalTime));

The behavior value LocalTime (and the Java equivalent localTime)allows animation to be injected into behaviors. It is a number-valued behavior (DANumber or Java NumberBvr) that starts at time 0 and increases at the rate of one unit per second. It can be used as an argument to any behavior-constructing method that takes a number-valued behavior as an argument to construct a time-varying behavior. For example, consider the following statements:

Sawtooth = m.Mod(m.LocalTime, 1);
MyCol = m.ColorRgb(Sawtooth, 0, 0);

The first creates a number behavior that goes from 0 to 1, 0 to 1, 0 to 1, and so on, by taking the modulus of the ever-increasing LocalTime value and 1. It then uses this value to create a time-varying color whose red component is that number behavior.

Animations constructed using LocalTime are unaffected by fluctuations in the frame rate of the DirectAnimation implementation. This means that the Sawtooth behavior will go from 0 to 1 in a period of 1 second, no matter how many frames are actually generated. This is a very important feature of DirectAnimation because it allows applications to be constructed independently of the hardware on which they will ultimately run.

There are other forms of time-varying input, such as MousePosition that can add interactivity to behaviors. The MousePosition (and Java mouseposition) behavior, for example, provides the continuous 2-D world-coordinate position of the mouse. It can be used, for example, as an argument to a translation function for tracking the mouse.

Reactive Behaviors

Non-reactive behaviors change with time but do not change as the result of discrete events. However, being able to change as a result of events (either internal or external) is important for truly useful behaviors, especially in interactive animations.

Events are discussed in the section DirectAnimation Events. The general data type for events is DAEvent and the Java DXMEvent. This topic discusses creating behaviors that switch from one behavior to another based on events.

Events

DirectAnimation events come from a number of sources, including:

  • Predicates. These are time-varying logical expressions (DABoolean objects) that are converted to events. When the expression becomes true, the event is triggered. These are constructed by calling the Predicate function with a (DABoolean object. For example:
    Event1 = m.Predicate(m.LTE(var1, var2))

    That is, when the var1 becomes less than or equal to var2, Event1 is triggered.

  • Built-in events. There are a number of built-ins events provided, such as key press events, mouse button events, and events resulting from a pick (hit with the mouse).
  • Timer events. These are events that trigger after a given amount of time has elapsed.
  • Application-triggered events. Applications can construct an event, include it as part of a behavior, and then trigger it explicitly through the application, optionally providing event data along with it.
  • Compound events. These are events that can be constructed from other events. For instance, AndEvent, OrEvent, and NotEvent take events and construct conjunction, disjunction, and negation events respectively.

This section gives an overview of the following event topics:

  • Key and Button Events
  • Timer Events
  • Application-Triggered Events
  • Compound Events
  • The AttachData Function
  • Event Data
  • Picking

Key and Button Events

Events can be produced when the user presses a mouse button or keyboard key. For example, considering the following JScript code:

Bvr1 = m.Until (initial_behavior, m.LeftButtonDown, second_behavior);

This defines Bvr1 as an initial behavior until the left mouse button is pressed, then Bvr1 becomes the second behavior.

You can trigger from an event produced when the user presses a specific key. For example:

Bvr2 = m.Until (initial_behavior, m.KeyDown(27), second_behavior);

This defines Bvr2 as an initial behavior until the ESC key is pressed, then Bvr2 becomes the second behavior.

You can also determine the state (whether it is pressed or not) of a mouse button or key with the LeftButtonState, RightButtonState, and KeyState functions. You can then trigger on that state using the Predicate event, as shown in the following JScript code:

Bvr3 = m.Until (initial_behavior, m.Predicate(m.LeftButtonState), second_behavior)

Timer Events

DirectAnimation supports the explicit specification of timer events, based upon LocalTime. For example, the following expression causes a behavior to switch from red to blue two seconds after it starts:

m.Until(m.Red, m.Timer(2), m.Blue)

The value given to timer can be any number-valued behavior.

Application-Triggered Events

Applications often receive events through means other than DirectAnimation. Examples include GUI elements and incoming network data. An application-triggered event is a subclass of the DAEvent type (DXMEvent Java type), and supports an additional trigger method. These events can be constructed with the new operator, placed into reactive behaviors, and triggered at any time by the application. For instance, the following Java example turns a cube from red to blue upon some external application event:

  URL geomBase = buildURL(getImportBase(),"file:/c:/DxM/Media/geometry/");
  GeometryBvr cube = importGeometry(buildURL(geomBase,"cube.wrl"));
  AppTriggeredEvent appEvent = new AppTriggeredEvent();
  ColorBvr col = (ColorBvr)until(red, appEvent, blue);
  GeometryBvr coloredCube = cube.diffuseColor(col);
//... elsewhere, when the application receives the proper event...
appEvent.trigger();
//... now coloredCube will turn blue (assuming it's running)

Note that the trigger method is an immediate method. The trigger occurs when the program executes the statement containing the trigger call.

Compound Events

Events can be combined in a variety of simple ways. The method AndEvent takes two events and creates a third that occurs only when both constituent events occur simultaneously. The event resulting from OrEvent occurs when either of the constituent events occur (or both occur). The event resulting from NotEvent occurs whenever the constituent event does not occur.

The AndEvent function always produces a pair of event data. Each element of the pair is the event data from one of the constituent events. The OrEvent function produces the event data of whichever event caused OrEvent to trigger. The event data from NotEvent is undefined because an event not occurring doesn't produce any information.

The AttachData Function

DirectAnimation events support an AttachData function that takes an event and produces a new event. The new event occurs at the same time as the original event, but its data is now the data that has been specified in the call to AttachData. This allows an application to associate arbitrary client data with an event and know that it will be delivered to the notifier when the event occurs.

This method can be used in conjunction with UntilEx and OrEvent to allow a behavior to switch to one of several new behaviors, depending on which event occurred. For instance, if you want a behavior that is red until the left mouse button is pressed (in which case it turns green) or the right mouse button is pressed (in which case it turns yellow), you could use the following code:

GreenLeft = m.LeftButtonDown.AttachData(m.Green);
YellowRight = m.RightButtonDown.AttachData(m.Yellow);
MyCol = m.UntilEx(m.Red, m.OrEvent(GreenLeft, YellowRight);

Because AttachData can take any behavior, the application can associate any type of data with events, rather than only behaviors.

Event Data

It is often necessary to know more than that an event triggered. This is why some events also produce data. For instance, a pick event provides information about the location of the intersection. To give applications the ability to access this data, DirectAnimation for Java calls the Notify function. This function creates a new event that occurs when the original event occurs. It then calls the notifier and uses the result as its event data. It is the responsibility of the application to retrieve the necessary data.

Event Data from Picking

The pick event returns data that can be accessed through the PickEvent property of the DAPickableResult class or from within an Until or UntilEx function. The data returned is a DAPair behavior whose first element is the intersection point of the event, and whose second element is a vector perpendicular to the surface of the picked object. Both of these pieces of data are supplied in the local coordinate system of the image or geometry used to construct a pickable image object (with the DAImage property Pickable) or pickable geometry object (with the DAGeometry property Pickable). This is needed to enable images and geometries to retain their interactivity independent of the context into which they are embedded. For example, an interactive image that is replicated three times, each time with a different scale, should retain its interactivity in all three contexts.

The sample in Samples\DA\VBScript\Showcase\Pick3.html demonstrates picking.

The samples GeometryDrag and ImageDrag in Samples\DA\Java\Templates\ directory show Java code that creates a geometry and an image that can be picked and, when picked, follows (or is dragged by) the mouse. When released, the geometry or image stays where it was released, waiting for the next pick. Because the event data is returned in the local modeling coordinates of the image itself, the resultant images can be used under any modeling transformation.

Because the draggable operation is so common, dragging utilities are provided in the Samples\DA\Java\Utility directory.

Event Detection

Descriptions of the Predicate function, which creates an event from a Boolean, might give the impression that this event is fired anytime the event occurs. In general, this is not possible, due to the possibilities of temporal aliasing. Therefore, DirectAnimation places implementation-specific restrictions on the form of Boolean that will successfully and consistently trigger events. For example, the event denoted by m.Predicate(m.EQ(m.Sin(m.LocalTime), 0)) is expected to fire exactly when Sin(LocalTime) is 0. However, in reality, this event will rarely, if ever, fire. This is because of the sample-driven nature of detecting predicate events. If the implementation doesn't sample at exactly the right time, the event will be missed. Thus, applications should use inequality events, such as m.Predicate(m.GTE(m.Sin(m.LocalTime), 0)) to test for events on continuous behaviors. It is this imprecision in sampling events that is the motivation for the specialized timer event.

There is a subtlety associated with imprecise sampling. If a notifier is invoked using Notify waiting for the above event, the event time will not generally be the exact time that the event became true. If precise timing is a requirement, the event time should not be used directly. Instead, the inaccuracy must be compensated for in some application-specific manner.

Picking

In DirectAnimation the Pickable property of DAImage and DAGeometry objects provide a simple mechanism by which picking (or hit detection) on images and geometry results in DirectAnimation events. In Java, the same mechanism is supported by the classes PickableImage and PickableGeometry. Applications can use these events as they would any other event. Additionally, information such where on the object the pick occurred is provided with the resulting event data.

The support for image and geometry hit detection is identical.

Hit detection works even when geometry is embedded into an image, and the image is in turn textured onto a geometry.

Images and geometry, even when embedded, retain their interactive nature.

If an application wants to be informed that the mouse is over a particular image, it constructs a DAPickableResult object by invoking the Pickable property on an image or geometry. It can then use the DAPickableResult property PickEvent. If the mouse is directly on top of a pickable image or geometry (without intervening images or geometries) then the event fires. It is possible for a pickable object to appear multiple times in a scene. However, each time the mouse is on top of any of these images, the event occurs. To distinguish multiple uses of an image, and provide separate events based upon separate uses, the application must construct multiple pickable objects. For example:

    pim1 = image.Pickable;
    pim2 = image.Pickable;

A Simple Picking Example

This JScript example demonstrates how to make an image pickable, meaning it reacts to an event when the mouse is within its borders. In this example, the square cycles between blue and red when the mouse is within its borders and the left button is down. Click on the title "Simple Picking Example" and choose View Source to see the source code:

The following simple Java example imports a GIF image and a piece of text rendered on top of the GIF image. The text changes when the mouse is over the GIF image.

URL imageBase =buildURL(getImportBase(),"../../Media/image/");
ImageBvr gif = importImage(buildURL(imageBase,"picture.gif"));

// Grab image, make pickable, grab the event.
PickableImage pGif = new PickableImage(gif);
DXMEvent ev = pGif.getPickEvent();

// Make the string change when mouse is over the image
StringBvr str =(StringBvr) until(toBvr("not picked"), ev,
  toBvr("picked"));

// Render the string to an image, and overlay on top of the
// pickable GIF.
ImageBvr  textIm = simpleText(str).render();
ImageBvr  result = overlay(textIm, pGif.getImageBvr());

Note that the pick event occurs when the mouse is directly over the image (and no other detectable images occlude its visibility.) A mouse button press is not required to fire the event. The effect is analogous to an HTML hotspot. To ensure that the event fires only when the mouse button is pressed, use the event constructed by andEvent(leftButtonDown, ev).

The Until Function

This section discusses the Until function (Java until method), which allows developers to incorporate interactive elements into their animations. Here is an example of how to create a behavior that is red until the left mouse button is pressed, and then turns to blue:

Col = m.Until(m.Red, m.LeftButtonDown, m.Blue);

In general, Until takes a behavior, an event, and another behavior. It produces a new behavior. This new behavior is the first behavior until the event occurs. It then becomes the second behavior. Because Until takes behaviors and returns a behavior, it can be nested, as the following example demonstrates:

Col = m.Until(m.Red, m.LeftButtonDown,
                             m.Until(m.Blue, m.LeftButtonDown, m.Green));

In this example, the resulting behavior is red until the button is pressed. It is then blue until the button is pressed again, and then it is green.

Note that the result is cast to the proper subclass of Behavior, because Until is defined on the Behavior superclass.

The previous example could have been written as:

Col1 = m.Until(m.Blue, m.LeftButtonDown, m.Green)
Col2 = m.Until(m.Red, m.LeftButtonDown, Col1);

Looking at the example in this form raises the following question: "When the LeftButtonDown event occurs, Col2 changes from red to Col1, but Col1 doesn't change from blue to green. Why not? Both of them appear to be waiting for the LeftButtonDown event, so why doesn't the first occurrence of this event cause them both to change?"

The reason the example works properly is because of the way Until works. Consider the following example:

b1 = m.Until(b2, ev, b3);

Behaviors are run automatically by the system when needed. Assume that behavior b1 is started by the system with a start time of t0. This causes b2 to be started at t0 also, and causes the system to start looking for the first occurrence of the event ev after t0. The system does not start behavior b3. When the event does occur (call this time te), the system starts behavior b3 at time te and stops looking for event ev.

In DirectAnimation, global time is ever-increasing, but local time for each behavior starts at 0 when the behavior is started. For example, if behavior b3 starts two seconds after b2, it will start with its own local time of 0.

Consider the original example:

Col1 = m.Until(m.Blue, m.LeftButtonDown, m.Green)
Col2 = m.Until(m.Red, m.LeftButtonDown, Col1);

When Col2 is started, the system looks for the LeftButtonDown event in Col2, but not in Col1. When the Col1 behavior starts, the system looks for the LeftButtonDown event in Col1.

The UntilEx Function

The UntilEx function (untilEx Java method) takes two parameters, a behavior and an event with a behavior associated with it: UntilEx(InitialBehavior, Event). The resulting behavior will have be the initial behavior until the event happens, then will transition to whatever behavior the event produces.

There are several ways to associate a behavior with an event, including the AttachData, Notify, and Snapshot functions (and the Java attachData, notifyEvent, and snapshotEvent methods).

The AttachData function allows you to associate data with an event. The data associated with the event can be a behavior. In the following example, the behavior is red until a mouse button is pressed. It then turns either green or yellow, depending on which event happens first.

GreenLeft = m.LeftButtonDown.AttachData(m.Green);
YellowRight = m.RightButtonDown.AttachData(m.Yellow);
MyCol = m.UntilEx(m.Red, m.OrEvent(GreenLeft, YellowRight);

The Notify function calls the notifier when an event occurs, and uses the result as event data.

The Snapshot function takes a behavior as a parameter. When the event to which it's attached occurs, it samples the behavior and returns it as a constant behavior. In the following example, the value of n is LocalTime until the left mouse button is pressed. It then becomes whatever the value of LocalTime was when the event occurred:

n=m.Until(m.LocalTime, m.LeftButtonDown.Snapshot(m.LocalTime));

The untilNotify Method (Java Only)

The untilNotify method is available only in Java since it is presently the scripting environment does not support notifiers. This method provides a delay mechanism for using event time data to construct the behavior that occurs after the event occurs. At the time of the event, a user-constructed notification method is invoked and passed the current behavior and the event data. This is somewhat like a user callback. The user code (called the notification method) uses the passed current behavior and event data to construct and return the behavior that occurs after the event.

When Does Until Change Behaviors?

This subsection discusses a subtlety present in the DirectAnimation event model.

Consider the statement:

until(b1, ev, b2);

If the event ev occurs at time te, the b2 behavior will not be sampled until the first sample time strictly greater than te. If this rule were not followed, many cyclically defined behaviors would be infinitely recursive.

Consider this example, which is a red behavior until LocalTime is greater than or equal to 2, then is a green behavior:

m.Until(m.Red, m.Predicate(m.GTE(m.LocalTime, 2)), m.Green)

If this behavior is sampled at local time 1.8, the result will be red. At local time 2.1, the predicate will hold true, but the DirectAnimation implementation assumes that the event time is 2.1 (because this is the time the implementation became aware of the event). Because of the "strictly greater than" rule described above, the result will still be red. Not until the next sampling, for example at local time 2.4, will the result be green.

If the application wants to ensure that situations like this react more accurately, it can use the timer method, and rewrite the example as:

m.Until(m.Red, m.Predicate(m.Timer(2)), m.Green)

In Java, this statement would be:

until(red, timer(toBvr(2)), green)

Until and LocalTime

The Until function and the LocalTime behavior starts at 0 and increases at the rate of 1 unit per second. Because Until starts its component behaviors at different times, the use of LocalTime within an Until function allows for the creation of distinct local timelines. For example:

sine = m.Sin(m.LocalTime);
slope = m.LocalTime;
sineSlope = m.Until(sine, m.Timer(5), slope);

The sineSlope behavior behaves like the sine behavior until just after time 5 (in its local time line). It then behaves like the slope behavior. The following is a chart of the running value of sineSlope graphed against its local time line.

Any instances of LocalTime in a behavior will, when that behavior is running, start at 0, including when the behavior is transitioned to as the result of an event.

This local timeline property of LocalTime is important because it allows behaviors to operate in their own local timelines. When placed in any Until function, started at any time, they will follow their prescribed behavior.

This form of Until doesn't describe every situation that might arise when designing a behavior that reacts to events. Specifically, this form only works when the component behaviors can be completely described when the resultant behavior is defined; for example, that the color becomes green when the button is pressed.

However, consider a stopwatch implemented as a number behavior representing a timer that starts counting from 0 and increases 1 unit per second until the left button is pressed. At that time, the behavior is permanently set to the value that existed when the button was pressed. This can be accomplished with the Snapshot function and the UntilEx function, as shown in the following example:

Stopwatch=m.Until(m.LocalTime, m.LeftButtonDown.Snapshot(m.LocalTime));

More Ways to Use Behaviors

This section describes how to use behaviors in different situations for different results. It includes the following topics:

  • Results of Operations on Behaviors
  • Some Defaults When Constructing Behaviors
  • When Are Behaviors Run?
  • Java toBvr Method
  • Constructing Cyclic Java Behaviors
  • Sequencing
  • Switching
  • Integrals and Derivatives
  • The Extract Function
  • The Cond Function
  • Time Substitution
  • Uninitialized Behaviors in Java

Results of Operations on Behaviors

A common feature throughout the behavior classes is that operations generally take behaviors and produce new behaviors from them, rather than modifying the original inputs. For example, consider the expression:

Cube.Transform(xform)

This does not change the specified cube. Instead, it produces a new geometry that is a transform applied to the original cube.

The following example creates a red cube rotated around the y-axis by 60 degrees:

mediaBase = "..\\..\\..\\..\\media\\";
geoBase = mediaBase + "geometry\\";
Geo1 = m.ImportGeometry(geoBase + "cube.x");
Geo2 = Geo1.DiffuseColor(m.Red);
Geo3 = Geo2.Transform(m.Rotate3Degrees(m.YVector3, 60));

Alternatively, because each of these functions produce a value, they could all be combined into the following statement:

Geo1= m.ImportGeometry(geoBase + "cube.x").DiffuseColor(m.Red).Transform(m.Rotate3Degrees(m.YVector3, 60));

It is important to remember that these calls always create new values and never modify the existing values. For example, consider the following code:

Geo1 = m.ImportGeometry(geoBase + "cube.x");
//Incorrect Usage
Geo1.DiffuseColor(m.Red);
Geo1.Transform(m.Rotate3Degrees(m.YVector3, 60));

This code will not create a cube, make that cube red, then rotate that cube. Instead, Geo1 remains the original, imported cube. The second and third lines are useless because they don't do anything with their return values. The results of those operations are inaccessible.

Internally to the implementation, new values may or may not actually be constructed. However, from the developer's point of view, they always are. Additionally, when new values are constructed, they are very inexpensive, in terms of system resources. Generally, they are represented by a pointer to the old value and the data for the new attribute.

Some Defaults When Constructing Behaviors

In DirectAnimation, methods for constructing media data types (images, geometry, points, and so on) use the following defaults:

  • Importing a bitmap image positions that image at the origin of the coordinate system. Transformations are then used on the original image to create new images with different locations.
  • The light constant is located at the 3-D origin, and transformed accordingly.
  • Directional light is in the direction of the negative Z-axis. Ambient light doesn't have geometric aspects.

This approach minimizes the replication of extraneous parameters. You don't need to define image imports, simple text, or light constants to take a position and size parameter. This both simplifies and aids consistency in animations.

When Are Behaviors Run?

This section lists the ways behaviors are run, and how the start time that becomes associated with the running behavior is determined. The different ways of running behaviors are:

  • In the statement "c1 = m.Until(c2, ev, c3)" when behavior c1 is started at t0, behavior c2 gets started at t0. Any time after this, when the event ev occurs at time te, behavior c3 is started at te. Prior to ev, c3 is not running.
  • In all media combination methods, such as "p1 = m.DistancePoint2(p2, p3)", when p1 is started at t0, p2 and p3 are also started at time 0.
  • Scripting behaviors are run as soon as the DAViewerControl Start subroutine is started, and are all started at time 0.
  • Java behaviors established in a Model with the createModel method are run as soon as the model is started, and are all started at time 0. This method is effectively the main entry point for DirectAnimation for Java, and describes the initial model. Behaviors that are not part of the Java Model can be explicitly identified for running by adding them to the list of behaviors passed to createModel method. Behaviors can be added with the BvrsToRun class add method.

The RunOnce Function

Certain applications need to be able to reference a running behavior without the behavior getting restarted when events occur. Consider two animated, time-varying images (perhaps movies), and an application that wants to play the first movie from its beginning for 10 seconds, then, over the course of the next two seconds, fade from it to the second movie, then continue playing the second movie. Assuming the existence of a Fade operation (which can be easily constructed from overlay and opacity), a first attempt might look like this:

Incorrect Usage

wrongResult = m.Until(movie1,
                  m.Timer(10),
                  m.Until(Fade(movie1, movie2),
                        m.Timer(2),
                        movie2);

Unfortunately, this doesn't work. The problem is that, after the first event, the movie1 behavior will be started again, resulting in seconds 1 and 2 of movie1 fading, rather than seconds 11 and 12. Also, after the second event, the movie2 behavior also starts again, replaying seconds 1 and 2, rather than continuing on from the end of 2 seconds.

This particular application calls for a behavior that, once running, is always referred to without restarting. This means that, after the initial start, no new behaviors are created. The RunOnce function satisfies this requirements. With RunOnce, the fader example can be expressed as:

movie1Once = movie1.RunOnce();
movie2Once = movie2.RunOnce();
faderMovie = m.Until(movie1Once, m.Timer(10), m.Until(Fade(movie1Once, movie2Once),
          m.Timer(2), movie2Once);

In this example, movie1Once and movie2Once are constructed as behaviors that are not yet running, but once they are started, subsequent references to these behaviors will return to the behavior already running.

Java toBvr Method

The toBvr method converts a double precision Java number into a constant NumberBvr behavior. This conversion is necessary because the DirectAnimation for Java methods generally take arguments that are behaviors and not Java constant numbers. The toBvr method exists for all core Java types that have DirectAnimation equivalents. For example, it converts Boolean types and java.lang.String types to BooleanBvr and StringBvr respectively.

The only time that toBvr is used is when converting a Java number, Boolean, or String to a DirectAnimation type. It is not used for constants such as red, yVector3, and origin2, because these are defined as constant behaviors.

Constructing Cyclic Java Behaviors

Often, there is a need to construct a behavior that, when an event occurs, cycles through some number of values. The Cycler object solves this problem. It is a subclass of the Behavior class. Here is an example that cycles through the three sounds upon each leftButtonDown event:

URL soundBase =buildURL(getImportBase(),"../../Media/sounds/");
SoundBvr snd1 = importSound(buildURL(soundBase,"do.wav"), null);
SoundBvr snd2 = importSound(buildURL(soundBase,"re.wav"), null);
SoundBvr snd3 = importSound(buildURL(soundBase,"mi.wav"), null);

//Create an array of sounds
Behavior[]snds = {snd1, snd2, snd3};
Cycler cycle = new Cycler(snds, leftButtonDown);
SoundBvr currentSnd = (SoundBvr)(cycle.getBvr());

Note that each component behavior gets started each time there is a transition to it.

The Cycler Class entry in the Java Reference describes Cycler.

The Cycler utility can be easily constructed in Scripting classes, using Until and uninitialized behaviors.

Sequencing

Sequencing allows you to sequence behaviors with finite durations. Consider the following JScript sample, which sequences through a set of labels. You can see how sequencing is used in animation by viewing the sample Samples\DA\JScript\Templates\Sequencing.

labels = new Array("First", "Second", "Third", "Fourth", "Fifth",
                      "Sixth", "Seventh", "Repeat the Sequence Forever");

durations = new Array(tDur, tDur, p1, sDur, p2, tDur, tDur, p1, sDur, p2, 1);

// Construct a sequence of labels
len = labels.length;
label = m.DAString("").Duration(0);
for (i=0; i<len; i++)
   label = m.Sequence(label, m.DAString(labels[i]).Duration(durations[i]));

font = m.DefaultFont.Color(m.Blue);
textImg = m.TextImage(label, font);

Note that the last duration of one second is for the last string, which will stay forever since it is the end of the sequence.

Switching

Sometimes there is a need to modify behaviors that is not dependent on events. The SwitchTo function supplies this need. A switchable object is created with the ModifiableBehavior function and given an initial behavior. When SwitchTo is called with another behavior, the modifiable behavior switches to the provided behavior. Here is an example:

// Create a modifiable color with the initial value blue.
col = m.ModifiableBehavior(m.Red)
im = m.SolidColorImage(col);
//... somewhere else in the program ...
col.SwitchTo(m.Blue);

Anywhere that col was used will turn from red to blue when SwitchTo is called. Calls to SwitchTo must carry arguments of the same behavior type as the initial behavior. The behavior switches when the program executes the statement containing the SwitchTo call.

Integrals and Derivatives

DirectAnimation supports explicit construction of the integrals and derivatives of certain types with respect to time. Integration can be performed on values of type DANumber with the Integral function and on DAVector2 and DAVector3 types with the IntegralVector2 and IntegralVector3 functions. Derivatives can be taken on all these types and also on DAPoint2 and DAPoint3 with the Derivative, DerivativeVector2, DerivativeVector3, DerivativePoint2, and DerivativePoint3 functions.

When an integral behavior begins, it starts building a conceptually continuous summation of values from that start time.

For example, the following JScript code creates a rotating ball that stops and starts on every left mouse button click. Rotate3RateDegrees takes an implicit LocalTime parameter. This parameter is replaced by the integral when SubstituteTime is called. The changingRate variable is a velocity that cycles between 0 and 1. The the integral of that velocity increases gradually. This integral is used as the angle of rotation for the geometry.

Ball = m.ImportImage("ball.gif");
RollingBall = Ball.Transform(m.Rotate3RateDegrees(m.Vector3(1,5,3), 540));
changingRate = new ActiveXObject("DirectAnimation.DANumber");
changingRate.Init(m.Until(m.DANumber(0), m.LeftButtonDown, m.Until(m.DANumber(1), m.LeftButtonDown, changingRate)));
finalImg = RollingBall.SubstituteTime(m.Integral(changingRate));

The following Java code creates a spinning cube that stops and starts on every left mouse button click.

URL mediaBase =buildURL(getImportBase(),"../../Media/");
GeometryBvr geo = importGeometry(buildURL(mediaBase,"cube.x"));
NumberBvr[] zeroAndOne = { toBvr(0), toBvr(1) };
Cycler cyc = new Cycler(zeroAndOne, leftButtonDown);
NumberBvr angularVelocity = (NumberBvr)(cyc.getBvr());
NumberBvr angle = integral(angularVelocity);
GeometryBvr spinningGeo = geo.transform(rotate(zVector3, angle));

The Extract Function

For behavior types that have primitive equivalents, (DABoolean, DANumber, and DAString, and the Java types BooleanBvr, NumberBvr, and StringBvr), a value in the underlying type is often needed. For instance, you might need an actual float in order to call out to a C++ or Java routine. The Extract function (Java extract method) exists for these classes of behaviors, takes no arguments, and is expected to be called on a behavior that is actually constant.

The Cond Function

The Cond function allows the construction of a behavior out of a Boolean behavior and two other behaviors. The value of the resultant behavior at any point in time is equal to the value of one of the two other behaviors. Which value is chosen is determined by the value of the Boolean behavior. This is a behavior-level conditional.

The following example creates a behavior, y, which is either another behavior, x, or 1.0 if x is greater than 0.5:

x = m.Sin(M.LocalTime);
y = m.Cond(m.GTE(x, 0.5), 1.0, x);

Time Substitution

By default, the LocalTime behavior starts at 0 and increases at the rate of one unit per second. However, this behavior can be modified. DirectAnimation supports time substitution. Time substitution creates a new behavior from an existing behavior and a number behavior. In the new behavior, the number behavior replaces all occurrences of LocalTime that were in the original behavior. This includes behaviors where LocalTime is implicit, such as imported movies. Time substitution allows behaviors to be time-scaled so that they can, for example, run faster or slower, be time-shifted to start at a different time, or frozen at a particular point in time. This can be used to accelerate and decelerate animation objects.

The SubstituteTime function takes the following form:

newBvr = origBvr.SubstituteTime(newTime)

The parameter newTime is a DANumber behavior that gets substituted for LocalTime in the origBvr behavior. The value of newBvr at time t is found by taking the value of newTime at time t, and using that as LocalTime in evaluating the behavior origBvr.

Here are some simple examples:

//Create an original behavior: a point moving
//one unit in the x direction per second, starting at 0
pt1 = m.Point2(m.LocalTime, 0);

//Create a new behavior moving 0.5 units per second
//Do this by replacing localTime with LocalTime/2
pt2 = pt2.SubstituteTime(m.Div(m.LocalTime, 2);

//Create a new behavior moving 1 unit per second
//starting at time 33, by replacing LocalTime with
//LocalTime + 33
pt3 = pt1.SubstituteTime(m.Add(m.LocalTime, 33);

//Create new behavior by freezing the original behavior
// at time 77
pt4 = pt1.SubstituteTime(77);

//Tie the new behavior to the x-component of the mouse
pt5 = pt1.SubstituteTime(m.MousePosition.X);

Also note that time substitutions are cumulative. For example, the following series:

c0 = m.Point2(m.LocalTime, 0);
c1 = c0.SubstituteTime(m.Add(m.LocalTime, 33));
c2 = c1.SubstituteTime(m.Mul(m.LocalTime, 2));

Could also be expressed as:

c0 = m.Point2(m.LocalTime, 0);
c1 = c0.SubstituteTime(m.Add(m.Mul(m.LocalTime, 2), 33));

This Java example shows how to make images of sailboats rock on the water. First a simple number behavior is created:

NumberBvr angle = mul(sin(localTime), toBvr(Math.PI/6));

This behavior begins (at local time zero) with the value zero and then varies with time between +/-p/6 radians (that is, +/-30 degrees). It repeats the behavior every 2p seconds. Assume that the applet has already constructed (or imported) a behavior representing the geometry of a sailboat, sailboat0, that is centered at the origin with its long axis aligned along Z. You can use the behavior angle to rock the boat as shown in the following code:

Transform3Bvr heel1 = rotate(zVector3, angle);
GeometryBvr sailboat1 = sailboat0.transform(heel1);

The boat is initially upright and then heels from one side to the other, passing through upright (sin(0)=0) approximately every p seconds.

Now, create a boat that is rocking more slowly than sailboat1:

Transform3Bvr heel2 =
(Transform3Bvr)heel1.substituteTime(div(localTime, toBvr(8)));
GeometryBvr sailboat2 = sailboat0.transform(heel2);

The second sailboat, sailboat2, rotates the same amount as sailboat1 but has a period that is 8 times longer (y = sin1/8x).

Note that, even though the period of rocking is different for each boat, both are initially upright. Now add a third boat that rocks at the same period as sailboat2, but is 90 degrees out of phase with it (y = cos 1/8x). The third boat can be defined as:

GeometryBvr sailboat3 = (GeometryBvr)
sailboat2.substituteTime(add(localTime, toBvr(Math.PI/2)));

At the start, this boat is heeled over by p/6 (cos(0)=1) and rocks at the same rate as sailboat2. Notice how using time substitutions contributes to the modularity of the code. The phase change could be achieved by changing the definition of angle, but this would have also changed the phase of the first two boats as well. The code for angle could have been duplicated and the phase changed, but if angle had a more complicated definition or if the source were not available, this approach would be difficult or impossible.

Time substitutions provide the same modularity benefits in the temporal domain that 2-D and 3-D transformations provide in the spatial domain. They allow objects to be defined, and then manipulated, from outside to alter their behavior, without needing to know the internals of the objects.

Naturally, there are certain restrictions on the time substitutions that can be applied to behaviors. For instance, user-input in general cannot be time substituted, and time-substitution cannot take you back before event transitions that have already occurred.

Uninitialized Behaviors in Java

There is often a need to reference a Java behavior before it has been defined. As an example, consider a colored rectangle whose color changes when picked (when the mouse clicks on it or hovers over it). In this case, the color depends on whether or not the image is picked, but the image is dependent upon the color. The uninitialized behavior is provided for these cases, and for cases of cyclic dependency. This behavior allows programmers to create a behavior, use it in the definition of other behaviors, but not actually define its contents until some later point. Uninitialized behaviors are created with the newUninitBvr method of the behavior object being created. All the behavior types have a newUninitBvr method for this purpose.

The following code shows how to use uninitialized behaviors to construct the animation described above(it assumes you have defined the function makeColoredRectangle elsewhere):

ColorBvr col = ColorBvr.newUninitBvr();
ImageBvr im = makeColoredRectangle(col);
PickableImage pim = new PickableImage(im);
DXMEvent ev = pim.getPickEvent();
col.init( until(red, ev, green) );

This example changes the color from red to green the first time the rectangle is passed over by the mouse. Here the behavior is initialized to the color dependent upon the event once the event occurs.

Consider what happens when the last line of the previous code is changed to the following:

col.init ( until(red, ev, until(green, notEvent(ev), col)) );

The rectangle will be red whenever the mouse is not over it, and green when the mouse is over it. This is accomplished by making the col behavior itself cyclic, going back to red and waiting for the pick after the notEvent(ev) occurs.

When using this feature, you should be aware that the system will generate a run-time error if you:

  • Initialize a non-uninitialized behavior
  • Initialize an uninitialized behavior that's already been initialized
  • Start an uninitialized behavior that has not yet been initialized

Using Behaviors in Java Applications

A Java application can display behaviors in either an applet or a canvas. There are three general steps to displaying behaviors:

  1. The application overrides (subclasses) the DirectAnimation Model class and implements the createModel method to build up the image, sound, and geometry behaviors it wants to view. The application can optionally implement settings that apply specifically to this model.
  2. The application constructs an instance of a DXMApplet or DXMCanvas class, providing an instance of the Model subclass.
  3. The application uses the applet or canvas as it would use any other applet or canvas. The model (and all of its component behaviors) is automatically sampled and displayed.

For example, the following code sample shows how to view the RedImg model created in the previous section.

public class MyApplet extends DXMApplet {
    public void init() {
       // Always call the superclass's init() first to ensure codeBase is set
       super.init();
       // Now set the model
       setModel(new redImg());
    }
}

Given a model, the setModel method is all you need to construct an applet to view that model.

The use of DXMCanvas is identical to DXMApplet, except that you must position the canvas inside an application frame as you would any other canvas.


Using Models

This section discusses how to use models in DirectAnimation. A model is the set of behaviors actually displayed. It is composed of images and sounds. This section contains the following topics:

  • Models in DirectAnimation
  • Setting Preferences
  • DXMApplet and DXMCanvas
  • Causing External Side Effects upon Java Events

Models in DirectAnimation

In DirectAnimation, a model is the set of behaviors actually displayed for the application. A model typically consists of viewing an image behavior and a sound behavior.

In scripting, the model is automatically set when you invoke DAViewerControl's Start subroutine. Whatever image or sound is attached to the control object at the time Start is called is what is displayed. For example:

DAMyControl.Image = MyImage;
DAMyControl.Sound = MySound;
DAMyControl.Start();

DirectAnimation for Java provides a Model class to standardize the construction of DirectAnimation models. In order to view a behavior, an instance of this Model class must be provided as input when constructing a DirectAnimation viewer inside a DXMApplet or DXMCanvas subclass. This is the relevant portion of the Java definition of the Model class:

public abstract class Model extends Statics
{
   // This is to be overridden by the application
   public abstract void createModel(BvrsToRun blist);

   // These are to be invoked by the application
    public void setImage(ImageBvr im1);
    public void setSound(SoundBvr snd);

    // These are invoked by the application to get and set the URL for importing files
    public URL getImportBase();
    public void setImportBase(URL url);

}

Applications override this class and implement at least the createModel method. This method creates the set of behaviors to be displayed, then calls setImage and setSound on the image and sound behaviors that are intended to be viewed.

The following is an example model that simply constructs a red image. This model has no sound.

public class RedImg extends Model {
    public void createModel(BvrsToRun blist) {
        ImageBvr im = solidColorImage(red);
        setImage(im);
    }
}

Setting Preferences

Occasionally, the programmer constructing the model, or the application controlling the viewer, will want to provide explicit rendering/viewing preference settings to DirectAnimation. Such preferences can include texture mapping quality, output audio format, maximum frames per second, polygon fill mode, and so on.

The Preferences object is the means by which these settings are made. A model can set preferences upon model construction, and the application can set them at any time by querying the viewer for them, setting them, and then submitting them back to the viewer.

To set preferences, first create a Preferences object, as shown in the following JScript code:

 p = DAControl.View.Preferences;

When the application is run, the Preferences object will be set to the default preferences in the registry. You can override these settings by calling the Preferences class PutPreference method. For example:

 p = DAControl.View.Preferences;
 oldvalue = p.GetPreference("FILL_MODE");
 p.PutPreference("FILL_MODE", FILL_MODE_SOLID);

Note also that, through the system registry, the user has an opportunity to establish preferences that become the default set of preferences for viewing a model. Changes made by the model or the application override these defaults. Because of this, setting of preferences should be something that both the model and the application approach conservatively, and only do if it is truly appropriate for the situation.

Also see the reference entry for the Java Preferences Class.

DXMApplet and DXMCanvas

In DirectAnimation, a model is the set of behaviors actually displayed and sampled for the application. A model typically consists of some combination of image behaviors and sound behaviors. DirectAnimation for Java provides a Model class to standardize the construction of DirectAnimation models. For example:

public class RedImg extends Model {
    public void createModel(BvrsToRun blist) {
        ImageBvr im = solidColorImage(red);
        setImage(im);
    }
}

In order to view a behavior, an instance of this Model class must be provided as input when constructing a DirectAnimation viewer inside a DXMApplet or DXMCanvas subclass.

DirectAnimation for Java provides the DXMApplet and DXMCanvas classes that extend the standard AWT Applet and Canvas classes and provide applets and canvases specifically for displaying behaviors. Each of these requires a Model upon construction, and each overrides the necessary methods on Applet and Canvas in order to view that model.

By default, DXMApplet and DXMCanvas provide their own frame-loop so the application needn't provide one explicitly (though it may choose to do so by overriding this default behavior). See the GeoApplet2 template in the Samples\DA\Java\Templates\Applet\GeoApplet2 directory.

Here is an example of using the DXMApplet class to view a model:

public class MyApplet extends DXMApplet {
    public void init() {
       // Always call the superclass's init() first to ensure codeBase is set
       super.init();
       // Now set the model
       setModel(new MyModel());
    }
}

Given a model, this is all that is needed to construct an applet to view that model.

The use of DXMCanvas is identical, except, you need to position the canvas inside of an application frame, just as you would any other canvas. For an example of how to use DXMCanvas, see the Java code in Samples\DA\Java\Templates\Application.

Dynamically Changing the Java Model

The DXMApplet and DXMCanvas classes are defined such that once an applet or canvas is built, the model cannot be changed. This is intentional. If there is a need to change the model dynamically, this should be reflected in changes to the behaviors that make up the model, and not by switching to another model. If an application really needs to switch to an entirely different model, it can construct a new applet or canvas.

The Java Viewer Interface

DirectAnimation for Java provides a Java interface called Viewer that encapsulates operations common to all displayers of behaviors. Because it is an interface, it is not constructed directly by applications. Instead, it is provided through concrete classes such as the DXMApplet and DXMCanvas classes. However, it does have a set of methods that can be used by applications.

Most applications never need to call any of these methods or, for that matter, ever need know about the Viewer interface. This is only for more explicit control of the running of behaviors, and for non-default ways of dealing with error handling and preference establishment.

Here are the relevant portions:

public interface Viewer {
    public abstract double getCurrentTime();
    public abstract double getCurrentTickTime();
    public abstract Preferences getPreferences();
    public abstract ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w);
    public abstract void startModel();
    public abstract void stopModel();
    public abstract void tick();
    public abstract void tick(double timeToUse);
}

The viewer gets its model via a mechanism not shown here (it is not meant to be called by applications). The relevant methods are:

  • The startModel() method which starts the behaviors associated with the model at global time 0. This is when the globalTime behavior starts. Incidentally, startModel() is also what causes the createModel() method on the model itself to get invoked.
  • The tick(double timeToUse) method which explicitly does a single sampling and display of the model with timeToUse as the global time.
  • The tick() method, which is shorthand for tick(getCurrentTime()), and is the easiest way to explicitly sample and display the model, thus providing a real-time clock for global time.
  • The rrentTime() method returns the number of seconds since startModel was invoked.
  • The getCurrentTickTime() method returns the time provided for the most recent call to tick, or 0 if it hasn't yet been called.
  • The registerErrorAndWarningReceiver() method which allows the application to register an object that will have its methods invoked upon asynchronous errors encountered when DirectAnimation is controlling the frame loop, or when recoverable warnings occur when sampling and displaying the model.
  • The getPreferences/setPreferences methods which allow the application to dynamically modify the viewer preferences.

Explicit Control of the Frame Loop

The implementations of DXMApplet and DXMCanvas implement a thread that repeatedly calls the tick() method, and thus have a built-in frame loop. If an application wants to explicitly control the frame loop, it must override these classes and provide different implementations that invoke tick() in their application-specific way.

Causing External Side Effects upon Java Events

Sometimes an application wants to cause an external action when an event occurs in DirectAnimation for Java. For instance, the application may want to display a GUI window when the mouse moves past a certain region of the window. This capability is supported by the registerCallback method available on events. The registerCallback method takes an object that implements the EventCallbackObject interface (along with some other parameters), and returns an Object that can later be used to unregister that callback. Whenever that event occurs, the invoke method of the callback is called with the event data produced by that event.

Here is an example:

class MyCallback implements EventCallbackObject {
    MyCallback(...);

    public void invoke(Object eventData) {
        ... pop up my GUI window ...
    }
}
//... elsewhere ...
ev = predicate(gte(mousePosition.getX(), toBvr(0.05)));
Object cookie = ev.registerCallback(new MyCallback(...),
                                    startTime,
                                    false);  // not a one-shot event
// ... from this point, every occurrence of ev will trigger "invoke"
...
// at some later point, unregister the callback
unregisterCallback(cookie);

Registering callbacks can be thought of as a complement to AppTriggeredEvent. The former causes an application action to occur upon a DirectAnimation event, while the latter is an application action triggering a DirectAnimation event.


Scripting Reference - DirectAnimation Classes

The Microsoft® DirectAnimation™ Scripting Reference describes each of the DirectAnimation functions, including syntax, returned values, and how to use the function. The reference is organized by classes, listed alphabetically.

The Scripting Reference Introduction describes the organization of the reference and also discusses the differences between JScript and VBScript, and between the PixelLibrary and the MeterLibrary.
A
DAArray Class
B
DABbox2 Class
DABbox3 Class
DABehavior Class
DABoolean Class
C
DACamera Class
DAColor Class
D
DADashStyle Class
DADrawingSurface Class
E
DAEndStyle Class
DAEvent Class
F
DAFontStyle Class
G
DAGeometry Class
I
DAImage Class
DAImportationResult Class
IDABvrHook Class
IDASite Class
J
DAJoinStyle Class
L
DALineStyle Class
M
DAMatte Class
DAMicrophone Class
DAMontage Class
N
DANumber Class
P
DAPair Class
DAPath2 Class
DAPickableResult Class
DAPoint2 Class
DAPoint3 Class
S
DASound Class
DAStatics Class
DAString Class
T
DATransform2 Class
DATransform3 Class
DATuple Class
U
DAUserData Class
V
DAVector2 Class
DAVector3 Class
DAViewerControl Class


Scripting Reference Introduction

The Scripting Reference is organized by classes. For example, there is a section on the DAImage class. Each class contains a description of its functions, including syntax, returned values, and how to use the function. At the end of each class, there is a list of functions that, while relevant to that particular class, are included in the DAStatics library. This library is very large, and it may be easier to familiarize yourself with its contents by looking at specific classes and seeing what DAStatics functions are pertinent. When parameters are described as animated numbers, this means they must be of type DANumber, not that they must necessarily change over time.

This introduction contains the following topics:

  • Differences between VBScript and JScript
  • The PixelLibrary and the MeterLibrary

Differences between VBScript and JScript

Syntax and terminology are based on VBScript conventions. However, there are only a few simple differences between that and JScript. Those differences that pertain directly to Microsoft® DirectAnimation™ are:

  • This reference is organized according to Visual Basic conventions, which uses functions, which return values, and subroutines, which do not, and properties. JScript distinguishes between methods, which are always associated with objects, functions, which are not, and properties, which are analagous to Visual Basic properties.
  • The syntax differs only in that JScript ends with a semicolon while VBScript does not.
  • The syntax for creating a new object is different. The following example shows how to create new objects both in VBScript and JScript:

// This is VBScript
Set myPt = CreateObject("DirectAnimation.DAPoint2")

// This is JScript
myPt = new ActiveXObject("DirectAnimation.DAPoint2");

The PixelLibrary and the MeterLibrary

The MeterLibrary and the PixelLibrary set the unit of measurement to meters or pixels respectively. Both return the DAStatics object, so, to gain access to that library, one of these libraries must be chosen. There are two important differences between the libraries (other than the obvious one of different units of measurement). They are:

  • The MeterLibrary considers positive-y to be up and the origin to be in the center of the view. The PixelLibrary considers positive-y to be down.
  • If the PixelLibrary is chosen, pixels are the unit of measurement only when something is being constructed. Returned values are always in meters. For example, if you construct a DAPoint2 object in pixels and then ask for its x-coordinate, the value will be returned in meters.


DAArray Class

A DAArray object holds other objects that can be selected based on an index that can either vary over time or not.

This class inherits from DABehavior

  • DAArray Functions
  • Relevant Functions from DAStatics

DAArray Functions

Length

NthAnim

Length

DAArray Class

Finds the length of a DAArray object.

arrayObj.Length( )

Return Values

Returns a DANumber object.

NthAnim

DAArray Class

Selects a DABehavior object based on the value of a (a DANumber). It uses the greatest integer value less than the number's value to determine the index. An array's index begins at 0 and any attempt to index beyond its length results in a run-time error.

arrayObj.NthAnim(
a
)

Parameters
a
The DANumber object used as a time-varying index into the array.
Return Values

Returns the DABehavior object.

Relevant Functions from DAStatics

The following functions are defined in the DAStatics class and are most relevant to objects of type DAArray:

lib.DAArray

lib.UninitializedArray()


DABbox2 Class

An object representing a two-dimensional bounding box. It specifies the lower-left and upper-right corners of a box that encloses the non-transparent portions of an image. Although a bounding box may not always be the smallest bounding box achievable for the image, it is useful for determining the extent or size of the visible portions of the image.

Applications never create bounding boxes explicitly. Instead, create them by calling the BoundingBox function on the DAImage object.

This class inherits from DABehavior.

DABbox2 Properties

Max

Min

Max

DABbox2 Class

A read-only property with a DAPoint2 value that specifies the upper-right corner of the bounding box.

bbox2Obj.Max

Min

DABbox2 Class

A read-only property with a DAPoint2 value that specifies the lower-left corner of the bounding box.

bbox2Obj.Min


DABbox3 Class

An object representing a three-dimensional bounding box. It specifies the back-lower-left and forward-upper-right corners of a cube that encloses the non-transparent portions of a geometry behavior. Although a bounding box may not always be the smallest bounding box achievable for the geometry, it is useful for determining the extent or size of the visible portions of the geometry.

Applications never create bounding boxes explicitly. Instead, they are created by calling the BoundingBox function on the DAGeometry object.

This class inherits from DABehavior.

DABbox3 Properties

Max

Min

Max

DABbox3 Class

A read-only property with a DAPoint3 value that specifies the upper-right corner of the bounding box.

bbox3Obj.Max

See Also

Min

Min

DABbox3 Class

A read-only property with a DAPoint3 value that specifies the lower-left corner of the bounding box.

bbox3Obj.Min

See Also

Max

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


DABehavior Class

All behaviors are potentially time-varying and/or reactive values such as colors, numbers and images. They can be used to construct animated objects. All behavior subclasses inherit the functions of this class.

Because all behaviors (animated objects) are potentially time-varying and/or reactive, their values can change as a function of time or as the result of user input. Time-varying behaviors are created by combining time-based default behaviors (such as LocalTime) with other behaviors. Reactive behaviors are created using the Until and UntilEx functions and by specifying input events, such as mouse clicks. Complex behaviors can be built by combining existing behaviors. The value of a complex behavior always depends on the values of the behaviors that comprise it.

When a behavior runs, its time-varying and reactive qualities are active. This means the user can experience any changes that occur in the behavior as time passes or events occur.

  • DABehavior Functions
  • DABehavior Subroutines
  • Relevant Functions from the DAStatics Class

DABehavior Functions

DurationAnim

Duration

GetClassName

Hook

Init

IsReady

Repeat

RepeatForever

RunOnce

SubstituteTime

DurationAnim

DABehavior Class

Creates an animation fragment by associating a local "stop time" with a behavior. The result is a new behavior that is the same as the original behavior for the length of the duration. Once the duration is over, the behavior is a snapshot of the behavior's state when the duration ended.

DurationAnim(
length
)

Parameters
length
The DANumber object representing the length of time, in seconds, that the duration lasts. This must be an animated number.
Return Values

Returns the DABehavior object.

Duration

DABehavior Class

Same as DurationAnim except that length is a non-animated number (a double).

Duration(
length
)

GetClassName

DABehavior Class

Returns the name of an object's class.

behaviorObj.GetClassName( )

Return Values

Returns a String.

Hook

DABehavior Class

Allows a running behavior to be sampled.

behaviorObj.Hook(
notifier
)

Parameters
notifier
The object that controls the sampling of the DABehavior.
Return Values

Returns a DABehavior object.

Init

DABehavior Class

Initializes an uninitialized object. Here is an example of how to create an uninitialized DAPoint2 object in VBScript:

Set myPt = CreateObject("DirectAnimation.DAPoint2")

And here is how to create an uninitialized object in JScript:

myPt = new ActiveXObject("DirectAnimation.DAPoint2");

To initialize the object in VBScript, use:

myPt.Init(...)

The only difference in JScript is that it needs a semicolon at the end of the line. For example, consider the following JScript code:

myPt.Init(m.Unitl(position, resetEvent,resetPosition);

The Init function can also be used on uninitialized arrays (UninitializedArray) and uninitialized DATuples (UninitializedTuple).

behaviorObj.Init(
behavior
)

IsReady

DABehavior Class

Determines if all the imports for the behavior have been downloaded. Only works when the behavior is, itself, an import. Otherwise returns E_NOTIMPL.

behaviorObj.IsReady(
bBlock
)

Parameters
bBlock
A boolean which, if FALSE, indicates that IsReady should return immediately and, if TRUE, indicates that it should block until the behavior is ready.
Return Values

Returns a boolean which, if TRUE, means all the imports have been downloaded.

Repeat

DABehavior Class

Creates a behavior that repeats itself the number of times specified by repetitions.

behaviorObj.Repeat(
repetitions
)

Parameters
repetitions
The number of times the behavior will repeat.
Return Values

Returns the DABehavior object.

RepeatForever

DABehavior Class

Creates a behavior that repeats infinitely.

behaviorObj.RepeatForever( )

Return Values

Returns the DABehavior object.

RunOnce

DABehavior Class

Used when applications must reference a running behavior once it starts running, but don't require the application to explicitly start that behavior.

behaviorObj.RunOnce( )

SubstituteTime

DABehavior Class

Creates a new behavior from an existing DABehavior and a DANumber. In the new behavior, the animated number replaces all occurrences of LocalTime in the original behavior. (This includes behaviors where LocalTime is implicit, such as imported movies. The function can be used even if LocalTime isn't explicitly in the code.) This allows behaviors to be, for example, time-scaled to run faster or slower, time-shifted to start at a different time, or frozen at a particular point in time.

behaviorObj.SubstituteTime(
a
)

Parameters
a
The DANumber object that replaces LocalTime.
Return Values

Returns the DABehavior object.

DABehavior Subroutines

SwitchTo

SwitchTo

DABehavior Class

Replaces one behavior with another. The inital behavior is set with the ModifiableBehavior function in the DAStatics class.

behaviorObj.SwitchTo(
newBehavior
)

Parameters
newBehavior
The DABehavior object that will replace the initial behavior.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DABehavior.

lib.Cond(bool, a, b)

lib.ModifiableBehavior(initialBehavior)

lib.Sequence(a, b)

lib.Until(a, e, b)

lib.UntilEx(a, e)


DABoolean Class

Creates a DABoolean object that represents an animated boolean value. (This means the boolean value can change over time). At any given time, the value of the DABoolean is either TRUE or FALSE.

This class inherits from the DABehavior class.

  • DABoolean Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DABoolean Functions

Extract

Extract

DABoolean Class

Extracts the value of booleanObj, which is a DABoolean object, and returns a boolean. The DABoolean must have a constant value.

booleanObj.Extract

Return Values

Returns a boolean.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DABoolean:

lib.And(b1, b2)

lib.DABoolean(bool)

lib.KeyState(keyCode)

lib.Not(b)

lib.Or(b1, b2)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DABoolean:

lib.DAFalse

lib.LeftButtonState

lib.RightButtonState

lib.DATrue


DACamera Class

Creates a DACamera object that represents a camera behavior (a camera whose values can be animated, or vary over time). A camera is used with the Render function to project geometry onto an infinite two-dimensional image. Related operations include rendering it into a microphone to extract the sound, or into a pair of microphones to extract stereo sounds.

There are two basic types of cameras: one for parallel projection and one for perspective projection. Both cameras are oriented so that they gaze in the negative z-direction, with positive y-axis considered "up." Also, both cameras have a near clipping plane. This plane (a product of Z-buffered rendering) specifies the closest distance at which an object is visible. Objects closer than the near clipping plane cannot be seen.

Cameras are manipulated via standard three-dimensional transform operations. These transforms modify the camera characteristics and also position and orient the cameras. For more information about these operations, see the transform functions described below.

This class inherits from DABehavior.

  • DACamera Functions
  • Relevant Functions from the DAStatics Class

DACamera Functions

DepthAnim

Depth

DepthResolutionAnim

DepthResolution

Transform

DepthAnim

DACamera Class

Creates a new DACamera object by applying the specified depth to the original object. By default, cameras have infinite depth, which means that all objects in front of the camera are visible. The new object is a DACamera whose maximum viewing depth is the DANumber depth. If depth < 0, the camera will be unable to see anything. If you prefer to think in terms of hither and yon, this function sets yon = hither + depth. It is important to note that depth is the limit on the far plane. As with the near plane, the geometry is bounded as tightly as possible for maximum Z-resolution.

Limiting the depth of the camera is useful for preserving depth resolution when using Z-buffered rendering. It is also useful for a camera inside a building, where no viewing region is larger than some value.

cameraObj.DepthAnim(
d
)

Parameters
d
The DANumber object that sets the maximum viewing depth of the DACamera. This value must be an animated number.
Return Values

Returns the DACamera object.

Depth

DACamera Class

Same as DepthAnim except that d is a non-animated number (a double).

cameraObj.Depth(
d
)

DepthResolutionAnim

DACamera Class

Creates a new DACamera object by applying the specified depth resolution (res) to the original behavior. The Z-buffered rendering approach assigns one depth-value (typically one of 65,536 possibilities) to each pixel on the screen. The depth resolution is the minimum distance between two objects such that they still appear distinct. This resolution varies as you go from the near clipping plane to the far clipping plane (more precision is lost for far objects), and according to the amount of perspective for the given camera. This method (given a minimim distance to be observed for the entire visible space) adjusts the far clipping plane accordingly.

For example, ifthe projection point is at (0,0,2), the image clip is at (0,0,1), and the depth resolution is set to 1cm, then the resultant DACamera will have a viewing depth of slightly over 25.1m. It is important to note that depth represents the limit on the far plane. As with the near plane, the geometry will actually be bounded as tightly as possible for maximum Z-resolution.

cameraObj.DepthResolutionAnim(
res
)

Parameters
res
The DANumber object that sets the minimum depth (in camera coordinates) that is guaranteed to be distinct. This value must be an animated number.
Return Values

Returns the DACamera object.

DepthResolution

DACamera Class

Same as DepthResolutionAnim except that res is a non-animated number (a double).

cameraObj.DepthResolution(
res
)

Transform

DACamera Class

Cameras are modified, positioned, and oriented via standard transforms. Scale transforms modify the camera while translations and rotations position and orient the camera. The basic steps for using a camera are defining it, modifying it if necessary, and then placing it in the scene.

It is important to note that all camera scales should be applied before camera rotations, and that only scales, rotations, and translations are supported on cameras. Transformations that do not meet these criteria will yield a camera with an undefined behavior.

There are two types of scale transformations, called Z-scales and X/Y-scales. Z-scales must be positive, non-zero values. Z-scales affect the position of the near clipping plane (if the clipping plane is set to a non-zero value.) For example, if the near clipping plane is located at 10 (that is, if Z=10), then a scale of [1 1 3] will yield a near clipping plane located at Z=30. More importantly, Z-scales move the projection point for a perspective camera. This means an increasing Z-scale yields a perspective camera that is zooming in, and a decreasing Z-scale yields a perspective camera that is zooming out.

Use X/Y-scales to affect the size of the projected image. One way to think of this is that an X/Y-scale sets the size of the camera relative to the world it's viewing. For example, if you are viewing a microscopic scene, use a small X/Y-scale. On the other hand, if you are viewing a solar system, use a large X/Y scale. Scaling a camera by some value in X/Y is exactly equivalent to inversely scaling the resulting image by the same amount. For example, scaling the camera by [10 10 1] is the same as scaling the resulting image by [1/10 1/10]. Finally, disparate scales in X and Y can be used to change the aspect ratio of the rendered image.

Once the camera is defined (via construction and scaling), it can be placed in the scene via rotations and translations just as a light source, microphone, or any other geometric object is placed.

cameraObj.Transform(
xf
)

Parameters
xf
The DATransform3 object used to create a new camera.
Return Values

Returns the DACamera object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DACamera:

lib.ParallelCameraAnim(nearclip)

lib.ParallelCamera(nearclip)

lib.PerspectiveCameraAnim(projdst, nearclip)

lib.PerspectiveCamera(projdst, nearclip)


DAColor Class

A DAColor is an object that represents a color behavior (this is an animated color, or a color whose value can change over time). At any given time, the value of the object is a color value that represents a specific color. Each color value consists of a combination of component values that specify either red, green and blue intensity or hue, saturation, and lightness.

Because component values can be animated numbers (DANumber objects), the value of the DAColor object can change over time as the animated numbers change.

This class inherits from DABehavior.

  • DAColor Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAColor Properties

Blue

Green

Hue

Lightness

Red

Saturation

Blue

DAColor Class

A read-only property with a DANumber value that represents the value of the blue component of the colorObj.

colorObj.Blue

See Also

Red, Green

Green

DAColor Class

A read-only property with a DANumber value that represents the value of the green component of colorObj.

colorObj.Green

See Also

Red, Blue

Hue

DAColor Class

A read-only property with a DANumber value that represents the value of the hue of colorObj.

colorObj.Hue

See Also

Lightness, Saturation

Lightness

DAColor Class

A read-only property with a DANumber value that represents the value of the lightness of colorObj.

colorObj.Lightness

See Also

Hue, Saturation

Red

DAColor Class

A read-only property with a DANumber value that represents the value of the red component of colorObj.

colorObj.Red

See Also

Green, Blue

Saturation

DAColor Class

A read-only property with a DANumber value that represents the value of the saturation of colorObj.

colorObj.Saturation

See Also

Hue, Lightness

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAColor:

lib.ColorHsl(h, s, l)

lib.ColorHslAnim(h, s, l)

lib.ColorRgb(r, g, b)

lib.ColorRgbAnim(r, g, b)

lib.ColorRgb255(r, g, b)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAColor:

lib.Aqua

lib.Black

lib.Blue

lib.Cyan

lib.Fuchsia

lib.Gray

lib.Green

lib.Lime

lib.Magenta

lib.Maroon

lib.Navy

lib.Olive

lib.Purple

lib.Red

lib.Silver

lib.Teal

lib.White

lib.Yellow


DADashStyle Class

Creates a DADashStyle object representing a dash style that is animated and whose values can vary over time. The object defines whether lines are drawn using a continuous stroke or a sequence of dashes.

Use the DADashStyle object with the Dash function of the DALineStyle class.

This class inherits from DABehavior.

There are no DADashStyle functions, except the functions it inherits from the DABehavior class.

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DADashStyle.

lib.DashStyleDashed

lib.DashStyleSolid


DADrawingSurface Class

The DADrawingSurface class uses a style of drawing that depends on a graphics context. This is in contrast to the other DirectAnimation classes that use a constructive approach. The constructive approach combines primitive data types into a more complex model, in a hierarchical fashion.

The graphics context approach is analagous to the way a pen plotter works, where the pen acts as the mechanical extension of a hand and the plotter acts as a piece of paper. To draw something, the pen is directed to a location on the plotter and then draws the shape. Many people find this approach to be more familiar than hierarchical modeling. For example, to draw the sun in the sky, it may seem more obvious to simply draw a yellow circle exactly where you want it, instead of first drawing a circle, then creating a yellow circle, and then, with a transform, creating yet another yellow circle that is now correctly placed. The difference is in the approach rather than in capabilities.

A DADrawingSurface object maintains a graphics state object for two-dimensional graphics. This state includes attributes such as line style, fill style, border style, font style, and two-dimensional transformations. The drawing commands (such as Oval and RoundRect are always interpreted in terms of the current state.

  • DADrawingSurface Subroutines
  • DADrawingSurface Properties
  • Relevant Functions from the DAStatics Class

DADrawingSurface Subroutines

ArcDegrees

ArcRadians

AutoSizeFillScale

BorderColor

BorderDashStyle

BorderJoinStyle

BorderWidth

Clear

Crop

CropPoints

DrawPath

FillColor

FillImage

FillPath

FillStyle

FillTexture

FixedFillScale

Font

GradientExtent

GradientExtentPoints

GradientRolloffPowerAnim

GradientRolloffPower

GradientShape

HorizontalFillScale

Line

LineColor

LineDashStyle

LineEndStyle

LineJoinStyle

LinePoints

LineWidth

OpacityAnim

Opacity

Oval

OverlayImage

PieDegrees

PieRadians

Polygon

Polyline

Rect

Reset

RestoreGraphicsState

RoundRect

SaveGraphicsState

SecondaryFillColor

Text

TextPoint

Transform

VerticalFillScale

ArcDegrees

DADrawingSurface Class

Draws a portion of an oval. (This is, in effect, an arc).

The following example, in VBScript, draws a series of differently-sized arcs:

<HTML>
<HEAD>
<TITLE>Demonstration of ArcDegrees subroutine</TITLE>
</HEAD>

<BODY>

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

</DIV>

<SCRIPT LANGUAGE="VBScript">

sub window_onLoad

  Set s = DAViewer.MeterLibrary
  Set ds = s.NewDrawingSurface()

  ds.Text "Degrees 0", -.04, .06
  ds.ArcDegrees 0, .05, 0, 0, .01, .01

  ds.Text "Degrees 45", -.04, .04
  ds.ArcDegrees 0, .03, 0, 45, .01, .01

  ds.Text "Degrees 90", -.04, .02
  ds.ArcDegrees 0, .01, 0, 90, .01, .01

  ds.Text "Degrees 180", -.04, 0
  ds.ArcDegrees 0, -.01, 0, 180, .01, .01

  ds.Text "Degrees 270", -.04, -.02
  ds.ArcDegrees 0, -.03, 0, 270, .01, .01

  ds.Text "Degrees 360", -.04, -.04
  ds.ArcDegrees 0, -.05, 0, 360, .01, .01

  DAViewer.Image = ds.Image
  DAViewer.Start

end sub

</SCRIPT>

</BODY>
</HTML>

drawingObj.ArcDegrees(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
xPos
The x-coordinate of the lower-lefthand corner of the oval's bounding box.
yPos
The y-coordinate of the lower-lefthand corner of the oval's bounding box.
startAngle
The angle, in degrees, where the arc begins.
endAngle
The angle, in degrees, where the arc ends.
arcWidth
The arc width, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
arcHeight
The arc height, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.

ArcRadians

DADrawingSurface Class

Same as ArcDegrees except that startAngle and endAngle are expessed in radians.

drawingObj.ArcRadians((
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)

AutoSizeFillScale

DADrawingSurface Class

Scales the fill pattern horizontally and vertically to fit the drawn object's bounding box.

drawingObj.AutoSizeFillScale( )

Remarks

There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.

BorderColor

DADrawingSurface Class

Specifies the color of a filled region's outline (border).

drawingObj.BorderColor(
color
)

Parameters
color
The DAColor object that is the color of the border.

BorderDashStyle

DADrawingSurface Class

Sets the dash style of the border.

drawingObj.BorderDashStyle(
id
)

Parameters
id
A number (a long) that sets the dash style of the border. For a table listing the available choices, see LineDashStyle.

BorderJoinStyle

DADrawingSurface Class

Specifies the border's join style.

drawingObj.BorderJoinStyle(
id
)

Parameters
id
A DAJoinStyle.

BorderWidth

DADrawingSurface Class

Sets the width of the border, in points. Border widths are affected by Transform. For example, scaling by 2 will double the border width.

The following example demonstrates different border widths, using JScript:

<HTML>
<HEAD>
<TITLE>Demonstration of BorderWidth Subroutine</TITLE>
</HEAD>

<BODY>

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

</DIV>

<SCRIPT LANGUAGE="JScript" for="window" event="onload">
  s  = DAViewer.MeterLibrary;
  ds = s.NewDrawingSurface();

  ds.BorderWidth(1);
  ds.Rect(0, .05, .06, .01);

  ds.BorderWidth(2);
  ds.Rect(0, .03, .06, .01);

  ds.BorderWidth(3);
  ds.Rect(0, .01, .06, .01);

  ds.BorderWidth(4);
  ds.Rect(0, -.01, .06, .01);

  ds.BorderWidth(5);
  ds.Rect(0, -.03, .06, .01);

  DAViewer.Image = ds.Image;
  DAViewer.Start();

</SCRIPT>

</BODY>
</HTML>

drawingObj.BorderWidth(
width
)

Parameters
width
A number (a double) that is the border width. The units are in points.

Clear

DADrawingSurface Class

Resets both the global images (Image) and the local context images (LocalContextImage). All attributes for the local context images are set to their defaults.

drawingObj.Clear( )

Crop

DADrawingSurface Class

Sets a rectangular cropping region outside of which drawing commands have no effect. Note that, unlike the DAImage Crop() function, this subroutine affects what will be drawn, not what has been drawn.

drawingObj.Crop(
minX,
minY,
maxX,
maxY
)

Parameters
minX
The number (a double) specifying the minimum x-coordinate of the rectangular cropping region.
minY
The number (a double) specifying the minimum y-coordinate of the rectangular cropping region.
maxX
The number (a double) specifying the maximum x-coordinate of the rectangular cropping region.
maxY
The number (a double) specifying the maximum y-coordinate of the rectangular cropping region.

CropPoints

DADrawingSurface Class

Same as Crop except that the arguments are specified as DAPoint2 objects.

drawingObj.CropPoints(
min,
max
)

Parameters
min
The DAPoint2 object specifying the minimum point of the cropping region.
max
The DAPoint2 object specifying the maximum point of the cropping region.

DrawPath

DADrawingSurface Class

Same as Polyline, except that it takes a DAPath2 object instead of points.

drawingObj.DrawPath(
path
)

Parameters
path
The DAPath2 object defining the line.

FillColor

DADrawingSurface Class

If used with a gradient fill, specifies the starting color. If used with a hatched fill, specifies its color. It is ignored for solid fills. The default foreground color is black.

drawingObj.FillColor(
foreground
)

Parameters
foreground
The DAColor object that is the foreground color.

FillImage

DADrawingSurface Class

Creates a fill pattern that is an image. This subroutine allows you to create your own fill pattern from any type of two-dimensional animation. The default is to scale the image to fit the window. If the mode is set to FixedFillScale and the image is transformed before being passed in, it will retain its position relative to the shape.

drawingObj.FillImage(
image
)

Parameters
img
The DAImage object to be used as the fill.

FillPath

DADrawingSurface Class

Same as Polygon except that it takes a DAPath2 object rather than points.

drawingObj.FillPath(
path
)

Parameters
path
The DAPath2 object defining the polygon.

FillStyle

DADrawingSurface Class

Sets the fill style. The parameter specifying the fill style, id, can be any of the following possible styles:

Id | Style
0 | Empty (does not support mouse events)
1 | Solid
2 | Empty Pickable (supports mouse events)
3 | HatchHorizonal
4 | HatchVertical
5 | HatchForwardVertical
6 | HatchBackwardDiagonal
7 | HatchCross
8 | HatchDiagonalCross
9 | HorizontalGradient
10 | VerticalGradient
11 | RadialGradient
12 | LinearGradient
13 | RectangularGradient
14 | ShapeGradient

Fill styles are used to paint closed regions. The default fill type is the solid fill. Some uses of particular fill styles are:

  • Empty fill styles are transparent and are used for making hollow objects and hotspots.
  • Solid fill styles give a uniform color throughout the selected area.
  • Hatched fill styles give a characteristic line pattern on top of either a transparent or a solid-color background.
  • Texture fill styles underlay the fill region with 2-D media such as a movie or still image.
  • Gradient fill styles blend between two or more colors in a smooth transition.

Fill colors are used in three ways. For gradient fills, the fill color is the first color used for blending. For hatched fills, it is the color used to draw the hatch marks. For solid fills, it is the color used for the entire filled area. It does not apply to empty and texture fill styles. The default color is black.

A secondary (or background) fill color is possible and is also used in several ways. For gradient fills, it specifies the second color used for blending. For hatch fills, it is the color used to fill around the hatch marks. For empty fills, it is always transparent. Solid fills have no secondary color. The default secondary color depends on the fill type. For solid and gradient fills, the default background color is white. For hatched fills, the default background color is transparent.

Gradient and texture fills can either be scaled to fit the shape being filled or can use their own scaling information. This is called a size-to-fit option. It does not apply to empty, solid, or hatched fill styles.

Scale-to-fit uses rectangular bounding regions to scale the fill style into the region to be filled. Thus, scale-to-fit does not guarantee that the entire fill style will appear in the shape, because many fill regions are not rectangular. Gradient fills in which no interpolation coordinates are specified use scale-to-fit by default. Gradient fills with explicit coordinates as well as all texture fills use, by default, their local coordinates and are not scaled to fit the drawing region. For particular scale-to-fit subroutines, see AutoSizeFillScale, FixedFillScale, HorizontalFillScale, and VerticalFillScale.

For gradient fills, it can be useful to explicitly set the starting and ending positions for the transition between the colors. For example, with a radial gradient, (which is a color transition in a circular shape) it may be useful to set the center point. To set these points, use the GradientExtent subroutine.

The GradientRolloffPower subroutine uses an exponent (the power argument) to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue.

More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity].

The following table summarizes the default values of the different fill attributes (such as color) for each fill style:
Default | Empty | Empty/Pickable | Solid | Hatched | Gradient | Texture | Image
Fill Color | N/A | N/A | Black | Black | Black | N/A | N/A
Secondary | N/A | N/A | N/A | Transparent | White | N/A | N/A
Mouse Events? | Always No | Always Yes | No | No | No | No | No
Size-to-fit | N/A | N/A | N/A | N/A | Yes, if no start point, No, if start point specified | Always No | No
Gradient End Points | N/A | N/A | N/A | N/A | No Default | N/A | N/A
Rolloff Power | N/A | N/A | N/A | N/A | 1 | N/A | N/A

drawingObj.FillStyle(
id
)

Parameters
id
The id (a long) of the fillstyle.

FillTexture

DADrawingSurface Class

Specifies a fill image that will be tiled (according to its bounding box) and/or clipped to fit within the extents of the path. It is not scaled. If the image is transformed before being passed in, it will retain its position relative to the shape.

drawingObj.FillTexture(
image
)

Parameters
image
The DAImage used as the fill.

FixedFillScale

DADrawingSurface Class

Specifies that the fill pattern will not be be scaled. The fill style attributes are applied directly to the drawn object, regardless of size.

drawingObj.FixedFillScale( )

Font

DADrawingSurface Class

Sets the font attributes.

drawingObj.Font(
face,
size,
bold,
italic,
underline,
strikethrough
)

Parameters
face
The name of the font family (this is a string).
size
The size of the font, in points.
bold
A boolean that turns the bold attribute on or off.
italic
A boolean that turns the italic attribute on or off.
underline
A boolean that turns the underline attribute on or off.
strikethrough
A boolean that turns the strikethrough attribute on or off.

GradientExtent

DADrawingSurface Class

Specifies a length and a direction for a gradient to transition between colors. The starting color is unblended, as is the ending color. Between the points, the colors are blended according to the gradient type.

drawingObj.GradientExtent(
startX,
startY,
endX,
endY
)

Parameters
startX
The starting x-coordinate(a double).
startY
The starting y-coordinate (a double).
endX
The ending x-coordinate (a double).
endY
The ending y-coordinate (a double).
See Also

FillStyle

GradientExtentPoints

DADrawingSurface Class

Same as GradientExtent except that the arguments are DAPoint2 objects.

drawingObj.GradientExtentPoints(
startPoint,
endPoint
)

Parameters
startPoint
The DAPoint2 object that specifies the location of the starting color.
endPoint
The DAPoint2 object that specifies the location of the ending color.

GradientRolloffPowerAnim

DADrawingSurface Class

Controls the sharpness of the transition between the colors.

drawingObj.GradientRolloffPowerAnim(
power
)

Parameters
power
A number (a double) that is an exponent controlling how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity].

GradientRolloffPower

DADrawingSurface Class

Same as GradientRolloffPowerAnim except that power is a non-animated number (a double).

drawingObj.GradientRolloffPower(
power
)

GradientShape

DADrawingSurface Class

Specifies a polygon that is progressively scaled to control the shape of the color transition. This applies only if the FillStyle subroutine was invoked with an id of 14 (ShapeGradient).

drawingObj.GradientShape(
pts
)

Parameters
pts
The array (variant) of points specifying the polygon.

HorizontalFillScale

DADrawingSurface Class

Stretches or compresses the fill pattern horizontally to match the width of the drawn object's bounding box.

drawingObj.HorizontalFillScale( )

Remarks

There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.

Line

DADrawingSurface Class

Draws a line segment from the starting point to the ending point, using the current LineDashStyle.

drawingObj.Line(
startX,
startY,
endX,
endY
)

Parameters
startX
The starting point's x-coordinate (a double).
startY
The starting point's y-coordinate (a double).
endX
The ending point's x-coordinate (a double).
endY
The ending point's y-coordinate (a double).

LineColor

DADrawingSurface Class

Sets the color of the line.

drawingObj.LineColor(
col
)

Parameters
col
The DAColor object that sets the line color.

LineDashStyle

DADrawingSurface Class

Sets the dash style of the line. The parameter specifying the dash style, id, can be any of the following possible styles:
ID | Dash Style
0 | Null
1 | Solid
2 | Dash

drawingObj.LineDashStyle(
id
)

Parameters
id
The id (a long) of the selected dash style.

LineEndStyle

DADrawingSurface Class

Sets the end style of the line. The parameter specifying the end style, id, can be any of the following possible styles:
ID | End Style
0 | Flat
1 | Square
2 | Round

drawingObj.LineEndStyle(
id
)

Parameters
id
The number (a long) specifying which end style to use.

LineJoinStyle

DADrawingSurface Class

Sets the join style of the line. The parameter specifying the join style, id, can be any of the following possible styles:
ID | Join Style
0 | Bevel
1 | Round
2 | Miter

drawingObj.LineJoinStyle(
id
)

Parameters
id
The id (a long) of the selected join style.

LinePoints

DADrawingSurface Class

Same as Line except that the arguments are DAPoint2 objects (they can be animated).

drawingObj.LinePoints(
pt1,
pt2
)

Parameters
pt1 and pt2
The DAPoint2 objects specifying the line's starting and ending points.

LineWidth

DADrawingSurface Class

Sets the width of the current line, in points. Line widths are affected by Transform. For example, scaling by 2 will double the line width.

drawingObj.LineWidth(
width
)

Parameters
width
The width of the current line, in points.

OpacityAnim

DADrawingSurface Class

Sets the opacity used by drawing commands. In contrast to the DAImage Opacity function, this subroutine affects what will be drawn rather than what has been drawn.

drawingObj.OpacityAnim(
opac
)

Parameters
opac
The DANumber object that sets the opacity. Values can range from 0.0 (fully transparent) to 1.0 (fully opaque). This must be an animated number.

Opacity

DADrawingSurface Class

Same as OpacityAnim except that opac is a non-animated number (a double).

drawingObj.Opacity(
opac
)

Oval

DADrawingSurface Class

Draws an outline of an oval and fills it, using the current fill and border styles.

The following example uses VBScript to draw an oval with a hatch cross fill style:

<HTML>
<HEAD>
<TITLE>Oval with Hatch Cross Fill Style</TITLE>
</HEAD>

<BODY>

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

</DIV>

<SCRIPT LANGUAGE="VBScript">

sub window_onLoad

  Set s = DAViewer.MeterLibrary
  Set ds = s.NewDrawingSurface()

  ds.FillColor          s.ColorRgb255(0,0,200)
  ds.SecondaryFillColor s.ColorRgb255(255,0,0)

  ds.Text "Hatch Cross", -.04, .06
  ds.FillStyle 7
  ds.Oval -.04, -.04, .1, .1

  DAViewer.Image = ds.Image
  DAViewer.Start

end sub

</SCRIPT>

</BODY>
</HTML>

drawingObj.Oval(
xPos,
yPos,
width,
height
)

Parameters
xPos
The x-coordinate (a double) of the lower-lefthand corner of the oval's bounding box.
yPos
The y-cooordiate (a double) of the lower-lefthand corner of the oval's bounding box.
width
The width of the oval, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
height
The height of the oval, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.

OverlayImage

DADrawingSurface Class

Overlays a DAImage object onto the current drawing surface. This means the image can be animated.

drawingObj.OverlayImage(
img
)

Parameters
img
The DAImage image.

PieDegrees

DADrawingSurface Class

Renders a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge).

The following example uses VBScript to draw a series of wedges, each with a solid-red fill:

<HTML>
<HEAD>
<TITLE>Demonstration of PieDegrees Subroutine</TITLE>
</HEAD>

<BODY>

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

</DIV>

<SCRIPT LANGUAGE="VBScript">

sub window_onLoad

  Set s = DAViewer.MeterLibrary
  Set ds = s.NewDrawingSurface()

  ds.FillStyle          1
  ds.FillColor          s.ColorRgb255(255,0,0)

  ds.Text "Degrees 0", -.04, .06
  ds.PieDegrees 0, .05, 0, 0, .01, .01

  ds.Text "Degrees 45", -.04, .04
  ds.PieDegrees 0, .03, 0, 45, .01, .01

  ds.Text "Degrees 90", -.04, .02
  ds.PieDegrees 0, .01, 0, 90, .01, .01

  ds.Text "Degrees 180", -.04, 0
  ds.PieDegrees 0, -.01, 0, 180, .01, .01

  ds.Text "Degrees 270", -.04, -.02
  ds.PieDegrees 0, -.03, 0, 270, .01, .01

  ds.Text "Degrees 360", -.04, -.04
  ds.PieDegrees 0, -.05, 0, 360, .01, .01

  DAViewer.Image = ds.Image
  DAViewer.Start

end sub

</SCRIPT>

</BODY>
</HTML>

drawingObj.PieDegrees(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
xPos
The x-coordinate (a double) of the lower-lefthand corner of the oval's bounding box.
yPos
The y-coordinate (a double) of the lower-lefthand corner of the oval's bounding box.
startAngle
The starting angle, in degrees (a double) of the wedge.
endAngle
The ending angle, in degrees (a double) of the wedge.
arcWidth
The double representing the arc width, expressed in meters, or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected.
arcHeight
The double representing the arc height, expressed in meters, or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected.

PieRadians

DADrawingSurface Class

Same as PieDegrees except that startAngle and endAngle are expressed in radians.

drawingObj.PieRadians(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)

Polygon

DADrawingSurface Class

Draws and fills a polygon, using the current fill and border styles. The points can be specified as a variant array of either DAPoint2[] objects or doubles. The array of doubles array must contain (2 * numPts) because it represents (x, y) coordinate pairs.

drawingObj.Polygon(
points
)

Parameters
points
The array (variant) of either DAPoint2[] objects or (x, y) coordinates (doubles).

Polyline

DADrawingSurface Class

Draws a set of line segments according to the current line style. The points can be specified as a variant array of either DAPoint2[] objects or doubles. The array of doubles array must contain (2 * numPts) because it represents (x, y) coordinate pairs.

drawingObj.Polyline(
points
)

Parameters
points
The array (variant) of either DAPoint2[] objects or (x, y) coordinates (doubles).

Rect

DADrawingSurface Class

Draws and fills a rectangle, using the current fill and border styles.

drawingObj.Rect(
xPos,
yPos,
width,
height
)

Parameters
xPos
A double that is the x-coordinate of the lower-lefthand corner of the rectangle's bounding box.
yPos
A double that is the y-coordinate of the lower-lefthand corner of the rectangle's bounding box.
width
The width of the rectangle (a double), in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
height
The height of the rectangle (a double), in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.

Reset

DADrawingSurface Class

Resets the local context and sets all attributes to their defaults (nested transformations from the context still apply although local transformations are reset). This subroutine affects only the state used for upcoming drawing methods, not the current drawing.

drawingObj.Reset( )

RestoreGraphicsState

DADrawingSurface Class

Restores the drawing surface's graphics state (the font, color, fillstyles, and so on) to what it was before the last SaveGraphicsState.

drawingObj.RestoreGraphicsState( )

RoundRect

DADrawingSurface Class

Draws a rectangle with rounded, rather than square, corners. The corners are considered to be segments of an oval (in effect, an arc).

drawingObj.RoundRect(
xPos,
yPos,
width,
height,
arcWidth,
arcHeight
)

Parameters
xPos
A double that is the x-coordinate of the lower-lefthand corner of the rectangle's bounding box.
yPos
A double that is the y-coordinate of the lower-lefthand corner of the rectangle's bounding box.
width
A double that is the width of the rectangle, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
height
A double that is the the height of the rectangle, in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
arcWidth
The arc width (a double) in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.
arcHeight
The arc height (a double), in either pixels or meters, depending on whether the PixelLibrary or the MeterLibrary is selected.

SaveGraphicsState

DADrawingSurface Class

Saves the drawing surface's current graphics state by pushing it onto an internal stack.

drawingObj.SaveGraphicsState( )

SecondaryFillColor

DADrawingSurface Class

Specifies a secondary fill color. For gradient fills, this is the second color used for blending. For hatch fills, it is the color used to fill around the hatch marks. For empty fills, it is always transparent. It does not apply to solid fills.

drawingObj.SecondaryFillColor(
val
)

Parameters
val
The DAColor object that is the secondary color.
See Also

FillColor

Text

DADrawingSurface Class

Creates a filled region from the text outlines, using the current fontstyle to determine the size of the font and the face. Color and other attributes come from the current fill and border styles. Note that the color attribute of the current font style is ignored. The text's starting location is given by xPos, yPos.

drawingObj.Text(
string,
xPos,
yPos
)

Parameters
string
The text used as the outline (a string).
xPos
The starting point's x-coordinate (a double).
yPos
The starting point's y-coordinate (a double).

TextPoint

DADrawingSurface Class

Same as Text except that the starting location is given by a DAPoint2 object.

drawingObj.TextPoint(
string,
pt
)

Parameters
string
The text used as the outline (a string).
pt
The DAPoint2 object designating the text's starting location. This can be animated.

Transform

DADrawingSurface Class

Transform operations include translation, scaling, and/or shearing. The subroutine affects only the state used for upcoming drawing methods, not the current drawing. This operation is cumulative.

drawingObj.Transform(
xf
)

Parameters
xf
The DATransform2 object that is the two-dimensional transform.

VerticalFillScale

DADrawingSurface Class

Stretches or compresses the fill pattern vertically to match the width of the drawn object's bounding box.

drawingObj.VerticalFillScale( )

Remarks

There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.

DADrawingSurface Properties

BorderStyle

ClipMatte

FontStyle

HatchFillTransparent

Image

LineStyle

LocalContextImage

MouseEventsEnabled

BorderStyle

DADrawingSurface Class

A DALineStyle object that specifies how the outline of a filled region will be drawn. The color specified in the line style determines the color of the border. (Interior fills are specified with FillStyle.) For an alternative way of setting border attributes, see BorderColor, BorderDashStyle, BorderJoinStyle, and BorderWidth.

drawingObj.BorderStyle

ClipMatte

DADrawingSurface Class

Specifies an image matte (or masking stencil) to the drawing context. Note that, unlike the DAImage Clip function, this property affects what will be drawn rather than what has already been drawn.

drawingObj.ClipMatte

FontStyle

DADrawingSurface Class

A DAFontStyle (animated) object that sets font attributes such as face, size, and color.

drawingObj.FontStyle

See Also

Font

HatchFillTransparent

DADrawingSurface Class

A boolean specifying whether the hatch fill is transparent or not.

drawingObj.HatchFillTransparent

Image

DADrawingSurface Class

Returns the DAImage object (animated image) associated with the DrawingSurface.

drawingObj.Image

LineStyle

DADrawingSurface Class

Adds a DALineStyle to the graphics state. A DALineStyle object determines the line color, dash style, width, endpoint, and join style. Setting this property affects how the line drawing commands (such as ArcRadians and Polyline) are drawn.

drawingObj.LineStyle

See Also

LineColor, LineDashStyle, LineEndStyle, LineJoinStyle, LineWidth

LocalContextImage

DADrawingSurface Class

Returns an image that corresponds to what was drawn since the latest SaveGraphicsState call. This property is useful for instancing and procedural tiling.

drawingObj.LocalContextImage

MouseEventsEnabled

DADrawingSurface Class

Specifies whether mouseover and selection events will be detected for the objects subsequently drawn. TRUE means that events are detected and FALSE means they are not.

drawingObj.MouseEventsEnabled

Relevant Functions from the DAStatics Class

lib.ImportDirectDrawSurface(dds, updateEvent)

lib.NewDrawingSurface()


DAEndStyle Class

Creates a DAEndStyle object that can be animated to vary over time. It defines the style (shape) applied to the end of line segments when they are drawn.

Use the DAEndStyle object with the end function of the DALineStyle class.

This class inherits from DABehavior.

There are no DAEndStyle functions, except the functions it inherits from the DABehavior class.

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAEndStyle.

lib.EndStyleFlat

lib.EndStyleRound

lib.EndStyleSquare


DAEvent Class

Creates a DAEvent object that represents an event. Events identify specific times, states or user actions and are used to specify when given actions should occur. Typically, you use events with the Until and UntilEx functions (in the DAStatics class) to create behaviors that change as a result of the event. For example, you can change the color of an object when the user presses a mouse button by using the LeftButtonDown property and the UntilEx function. Every event, when it occurs, returns some event data. This data may or may not be meaningful, depending on the event. For example, LeftButtonDown does not return any meaningful data.

You can combine existing events to create new, more complex events. For example, the AndEvent function in DAStatics lets you combine two events so that the resulting event occurs only if both of the original events occurred simultaneously. The data produced by an event can only be examined within the notifier.

  • DAEvent Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAEvent Functions

AttachData

Notify

ScriptCallback

Snapshot

AttachData

DAEvent Class

Takes a DABehavior object and produces a new event. The new event occurs at the same time as the original event, but its data is now the data that was specified in the call to AttachData. This allows an application to associate arbitrary client data with an event and know that it will be delivered to the notifier when the event occurs.

eventObj.AttachData(
data
)

Parameters
data
The DABehavior object.
Return Values

Returns a DAEvent object. The event data is the event data of the new event.

See Also

DAUserData

Notify

DAEvent Class

Creates a new event. This occurs when the original event occurs. It then calls the notifier and uses the result as its event data.

eventObj.Notify(
notifier
)

Parameters
notifier
Returns the new behavior.
Return Values

Returns the DAEvent object. The event data is the time the event fired and the new behavior.

ScriptCallback

DAEvent Class

Invokes VBScript or JScript functions from within animations.

eventObj.ScriptCallback(
function,
language
)

Parameters
function
The function (a string) to be called.
language
The name (a string) of the scripting language.
Return Values

Returns a DAEvent object. When this event occurs, the data it produces has a trivial value.

Snapshot

DAEvent Class

When called on an instance of a behavior, samples the given behavior and returns it as a constant behavior with the value as data. The event time of the new event is when the original event occurs.

eventObj.Snapshot(
a
)

Parameters
a
The DABehavior object which will be sampled when the function is invoked.
Return Values

Returns the DAEvent object. The event data is the value of the behavior at the time it was sampled, returned as a constant behavior.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAEvent.

lib.AndEvent(first, second)

lib.KeyDown(keyCode)

lib.KeyUp(keyCode)

lib.NotEvent(ev)

lib.OrEvent(first, second)

lib.Predicate(bool)

lib.ThenEvent(e1, e2)

lib.TimerAnim(timeout)

lib.Timer(timeout)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAEvent.

lib.Always

lib.LeftButtonDown

lib.LeftButtonUp

lib.Never

lib.RightButtonDown

lib.RightButtonUp


DAFontStyle Class

The DAFontStyle class is used to specify how strings will be rendered into images. These functions are similar to the HTML tags specifying the font face (called here a family), size, color and attributes (bold and italic).

  • DAFontStyle Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAFontStyle Functions

AntiAliasing

Bold

Color

FamilyAnim

Family

Italic

SizeAnim

Size

Strikethrough

Underline

WeightAnim

Weight

AntiAliasing

DAFontStyle Class

Determines whether or not the font will be antialiased. If antialias is 0 (the default), there is no antialiasing. If it is 1, there is antialiasing.

fontstyleObj.AntiAliasing(
antialias
)

Parameters
antialias
A double that can be either 0 or 1.
Return Values

Returns the DAFontStyle object.

Bold

DAFontStyle Class

Specifies that, when the string is rendered into an image, it will be in bold.

fontstyleObj.Bold( )

Return Values

Returns the DAFontStyle object.

Color

DAFontStyle Class

Specifies the color of the string when it is rendered into an image. Because this is a DAColor object, the color can vary over time.

fontstyleObj.Color(
color
)

Parameters
color
The DAColor object specifying the color of the string.
Return Values

Returns the DAFontStyle object.

FamilyAnim

DAFontStyle Class

Specifies the font face that will be used when the image is rendered. Because this is a DAString object, the face can vary over time.

fontstyleObj.FamilyAnim(
face
)

Parameters
face
The DAString object specifying the font face.
Return Values

Returns the DAFontStyle object.

Family

DAFontStyle Class

Same as FamilyAnim except that face is a non-animated string. For example, consider the following JScript code:

fs = m.DefaultFont.Family("Arial").Color(m.Red).Bold();

fontstyleObj.Family(
face
)

Italic

DAFontStyle Class

Specifies that, when the string is rendered into an image, it will be italicized.

fontstyleObj.Italic( )

Return Values

Returns the DAFontStyle object.

SizeAnim

DAFontStyle Class

Specifies the size of the font, in points. Because this is a DANumber object, the size can vary over time.

fontstyleObj.SizeAnim(
points
)

Parameters
points
The DANumber object specifying the size of the font.
Return Values

Returns the DAFontStyle object.

Size

DAFontStyle Class

Same as SizeAnim except that points is a non-animated number (a double).

fontstyleObj.Size(
points
)

Strikethrough

DAFontStyle Class

Specifies that, when the string is rendered into an image, it will be struck through.

fontstyleObj.Strikethrough( )

Return Values

Returns the DAFontStyle object.

Underline

DAFontStyle Class

Specifies that, when a string is rendered into an image, it will be underlined.

fontstyleObj.Underline( )

Return Values

Returns the DAFontStyle object.

WeightAnim

DAFontStyle Class

Specifies the thickness of the boldness of the font. This attribute can be thought of as an animated bold. Note that the font itself has specific, discrete settings for the weight. Varying the value of the weight results in discrete, rather than continuous, changes. The DAFontStyle.Bold function always overrides this setting.

fontstyleObj.WeightAnim(
weight
)

Parameters
weight
A DANumber object that specifies the thickness of the boldness of the font. The value can range from 0 (the thinnest) to 1 (the thickest).
Return Values

Returns the DAFontStyle object.

See Also

Weight

Weight

DAFontStyle Class

Same as WeightAnim except that the argument is non-animated (a double).

fontstyleObj.Weight( )

See Also

WeightAnim

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAFontStyle.

lib.FontAnim(face, size, color)

lib.Font(face, size, color)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAFontStyle.

lib.DefaultFont


DAGeometry Class

The DAGeometry class is a class of three-dimensional objects that includes surfaces, lights, sounds, their attributes, and/or combinations of these elements. Like other DirectAnimation objects, the value of the elements of the geometry can change over time.

In general, every geometry behavior is spatially infinite and of infinite resolution. Conceptually, each of the infinitely many points in the geometry has associated with it an opacity value, a color, a normal (used for lighting computations), a texture coordinate, a detectability value, and a single-channel sound emanating from that point (generally, this is silence).

Surface geometry is either detectable or not. If a surface is detectable, the geometry fires an event whenever the cursor passes over a surface point. Neither lights nor sounds are detectable (or pickable).

Light geometries include ambient lights, directional lights, point lights, and spotlights. Light geometries can be attributed with both color and distance attenuation.

A texture in a geometry is an image, the points of which are mapped to the surface of the three-dimensional object represented by the geometry. If there is no surface in the geometry, the texture is ignored.

A geometry can also be a sound. The sound is audible when the geometry is within the appropriate range of a microphone behavior.

The bounding box query is used to construct and compose media, and different types of images and behaviors provide specific bounding boxes. This means, for example, that the bounding box of an image is not defined as the smallest axis-aligned, enclosing region of the non-transparent parts of an image. Instead, bounding boxes are defined on a per-operation basis. The emptyGeometry object, for example, has its own definition of a bounding box, defined below.

This class inherits from DABehavior.

  • DAGeometry Functions
  • DAGeometry Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAGeometry Functions

DiffuseColor

LightAttenuationAnim

LightAttenuation

LightColor

OpacityAnim

Opacity

Pickable

Render

RenderSound

Texture

Transform

Undetectable

DiffuseColor

DAGeometry Class

Specifies the diffuse color of the new DAGeometry object. The diffuse color is the diffuse (or matte) reflective color of the surface. By default, the diffuse color is white. The bounding box is the bounding box of the underlying geometry.

geometryObj.DiffuseColor(
col
)

Parameters
col
The DAColor object that is the color.
Return Values

Returns the DAGeometry object.

Remarks

This attribute overrides previous values.

LightAttenuationAnim

DAGeometry Class

Creates a DAGeometry in which any light sources have the given attenuation. The new attenuation is set to 1 / (const + linear ´ d + quadratic ´ d2) where d is the distance from the light to the object. By default, the attenuation coefficients are (1, 0, 0), which means no light attenuation. The bounding box is the bounding box of the underlying geometry.

geometryObj.LightAttenuationAnim(
const,
linear,
quadratic
)

Parameters
const, linear, and quadratic
The DANumber objects specifying the attenuation of a light source. These must be animated numbers.
Return Values

Returns the DAGeometry object.

Remarks

An attenuation of (1, 1, 0) gives a linear attenuation that is useful for light falloff in a room. An attenuation of (1, 0, 1) gives a quadratic attenuation that simulates lights that are in the open, such as street lamps and headlights. This attribute overrides previous values.

LightAttenuation

DAGeometry Class

Same as LightAttenuationAnim except that the arguments are non-animated numbers (doubles).

geometryObj.LightAttenuation(
const,
linear,
quadratic
)

LightColor

DAGeometry Class

Creates a new DAGeometry object in which all embedded lights have the specified color. By default, a light source is white. The bounding box is the bounding box of the underlying geometry.

geometryObj.LightColor(
col
)

Parameters
col
The DAColor object.
Return Values

Returns the DAGeometry object.

Remarks

This attribute overrides previous values.

OpacityAnim

DAGeometry Class

Sets the opacity value for all surfaces to opac. Opacity values can range from 0.0 to 1.0. If the corresponding DANumber object has a value outside this range, the integer part of the value is discarded and only the fractional part is used. By default, the opacity is 1.

geometryObj.OpacityAnim(
opac
)

Parameters
opac
The DANumber object representing the opacity value. The geometry is fully opaque if the value is 1, and fully transparent if the value is 0. This must be an animated number.
Return Values

Returns the DAGeometry object.

Remarks

This function composes values. The resulting opacity is the new value times the old value.

Opacity

DAGeometry Class

Same as OpacityAnim except that opac is a non-animated number (a double).

geometryObj.Opacity(
opac
)

Pickable

DAGeometry Class

Makes a DAGeometry object pickable. Use this function along with the returned DAPickableResult object to create a reactive behavior (This means that, when the mouse is in the pickable area, an event occurs).

The behavior of a "pickable" image is identical to that of an ordinary image until the mouse is in the pickable region and there are no geometries (other than undetectable ones) between it and the mouse. Then, an event (created in DAPickableResult) occurs.

geometryObj.Pickable( )

Return Values

Returns the DAPickableResult object.

Render

DAGeometry Class

Creates a DAImage object that is a two-dimensional projection of geometryObj. The camera parameter defines how the geometry is projected into two dimensions. The resulting image is infinite in extent. The bounding box of a rendered geometry is the axis-aligned extent of the projection of the three-dimensional bounding box onto the image plane.

geometryObj.Render(
camera
)

Parameters
camera
The DACamera object.
Return Values

Returns the DAImage object.

RenderSound

DAGeometry Class

Creates a DASound object that represents the sound associated with geometryObj as detected by the given microphone.

geometryObj.RenderSound(
mic
)

Parameters
mic
The DAMicrophone object.
Return Values

Returns the DASound object.

Texture

DAGeometry Class

Creates a DAGeometry object by mapping the given image, as defined by texture, to the surfaces of the original geometry. If the geometry has no surfaces, the texture is ignored. If the original geometry already has a texture, the new texture completely overlays the original. Texture maps have no effect when applied to a geometry that lacks texture coordinates. By default, a geometry has no texture. The bounding box is the bounding box of the underlying geometry.

geometryObj.Texture(
image
)

Parameters
image
The DAImage object.
Return Values

Returns the DAGeometry object.

Remarks

This attribute overrides previous values.

Transform

DAGeometry Class

Creates a DAGeometry object that is the result of applying the given three-dimensional transformation to the original geometry behavior. The transformation applies to all points in the geometry, including those associated with the positions and orientations of light sources, textures, and sounds. The bounding box of a transformed geometry is the axis-aligned box enclosing the box that is the result of applying the transformation to the underlying geometry.

geometryObj.Transform(
xf
)

Parameters
xf
The DATransform3 object.
Return Values

Returns the DAGeometry object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Undetectable

DAGeometry Class

Creates a new, undetectable DAGeometry object from the original geometry. An undetectable geometry means that, while the geometry is still as visible or as audible as before, any attempts to pick it are ignored.

geometryObj.Undetectable( )

Return Values

Returns the DAGeometry object.

Remarks

The Undetectable function is useful for specifying which objects are detectable and which are not. For example, suppose a semi-transparent green sphere is used to simulate a glow around an object. Because this sphere encloses the object, the object itself would be unpickable. Instead, the pick information would always be for the sphere. Tagging the sphere as unpickable allows the object itself to be picked. This attribute overrides previous values.

DAGeometry Properties

BoundingBox

BoundingBox

DAGeometry Class

A read-only property with a DABbox3 value that creates a bounding box object defining the axis-aligned bounding box enclosing all non-transparent portions of the geometryObj.

geometryObj.BoundingBox

Return Values

Returns the DABbox3 object.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAGeometry.

lib.ImportGeometry(url)

lib.ImportGeometryAsync(url, geoStandIn)

lib.SoundSource(sound)

lib.SpotLightAnim(fullcone, cutoff)

lib.SpotLight(fullcone, cutoff)

lib.UnionGeometry(g1, g2)

lib.UnionGeometryArray(geoArray)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAGeometry.

lib.AmbientLight

lib.DirectionalLight

lib.EmptyGeometry

lib.PointLight


DAImage Class

Creates a DAImage object that represents a (potentially) animated image. Much like a bitmap, an image is a two-dimensional picture composed of individual picture elements. However, because it can be animted, the value of the picture elements can change over time.

Every DAImage object consists of an infinite set of two-dimensional points, each representing a picture element and each having color, opacity, and detectability attributes. Colors in an image are defined using DAColor objects. Opacity values are DANumber objects, and can range in value from 0 through 1, with 0 for fully transparent and 1 for fully opaque. Only points that are "non-transparent" have any visible effect when the image is output or combined with other images.

Points in the image are either detectable or not. If a point is detectable, the image fires a pick event whenever the mouse passes over it.

The bounding box operation is used to construct and compose media, and different types of images and behaviors provide specific bounding boxes. This means, for example, that the bounding box of an image is not defined as the smallest axis-aligned, enclosing region of the non-transparent parts of an image. Instead, bounding boxes are defined on a per-operation basis.

This class inherits from DABehavior.

  • DAImage Functions
  • Relevant Functions from the DAStatics Class
  • Relevant properties from the DAStatics Class

DAImage Functions

BoundingBox

Clip

ClipPolygonImage

Crop

MapToUnitSquare

OpacityAnim

Opacity

Pickable

PickableOccluded

Tile

Transform

Undetectable

BoundingBox

DAImage Class

Creates a DABbox2 object that defines the box that encloses all non-transparent portions of the DAImage object.

imageObj.BoundingBox

Return Values

Returns the DABbox2 object.

Clip

DAImage Class

Creates a DAImage by clipping the original image. The new image consists of the portion of the original image that is within the region(s) defined by the given matte behavior. The bounding box of an image clipped to a matte is the intersection of the matte's bounding box (the axis-aligned box that surrounds the matte), and the bounding box of the underlying image.

imageObj.Clip(
matte
)

Parameters
matte
The DAMatte object.
Return Values

Returns the DAImage object.

ClipPolygonImage

DAImage Class

Creates a DAImage object by clipping the original image. The new image consists of the portion of the original image that is within the closed figure defined by the given DAPoint2 objects. The bounding box is the intersection of the box surrounding the points of the polygon with the box of the underlying image.

imageObj.ClipPolygonImage(
points
)

Parameters
points
The array (variant) of DAPoint2 objects representing the endpoints of the line segments that define the figure. If the first and last points are not the same, these points are implicitly connected to close the figure.
Return Values

Returns the DAImage object.

Crop

DAImage Class

Creates a DAImage object by cropping the original image. The new image consists of the portion of the original image that is within the region given by minPt and maxPt. The bounding box of a cropped image is the intersection of the crop box and the box of the underlying image.

imageObj.Crop(
minPt,
maxPt
)

Parameters
minPt and maxPt
The DAPoint2 objects representing the lower-left and upper-right corners of the box enclosing the portion of the original image to use.
Return Values

Returns the DAImage object.

MapToUnitSquare

DAImage Class

Creates an image that is mapped to the unit square. This is a square at coordinates [(0,0) (1,1)]. It is commonly used for images that will be textured because a geometry's texture coordinates generally span the unit square. It is also used for transforming an image into a space where it is easy to manipulate.

imageObj.MapToUnitSquare

Return Values

Returns the DAImage object.

OpacityAnim

DAImage Class

Creates a DAImage object in which the opacity value for each point is set to the given animated number (DANumber object). By default, an image's opacity is 1 (completely opaque). The bounding box is simply the bounding box of the underlying image itself.

imageObj.OpacityAnim(
opac
)

Parameters
opac
The DANumber object representing the opacity value. The image is fully opaque if the value is 1, and fully transparent if the value is 0. This must be an animated number.
Return Values

Returns the DAImage object.

Remarks

Opacity values can range from 0.0 (no opacity) to 1.0 (completely opaque). If the corresponding number behavior has a value outside this range, the integer part of the value is discarded and only the fractional part is used. This function composes values. The resulting opacity is the new value times the old value.

Opacity

DAImage Class

Same as OpacityAnim except that opac is a non-animated number (a double).

imageObj.Opacity(
opac
)

Pickable

DAImage Class

Makes a DAImage object pickable. Use this function along with the returned DAPickableResult object to create a reactive behavior (This means that, when the mouse is in the pickable area, an event occurs).

The behavior of a "pickable" image is identical to that of an ordinary image until the mouse is in the pickable region and there are no geometries (other than Undetectable ones) between it and the mouse. Then, an event (created in DAPickableResult) occurs.

imageObj.Pickable( )

Return Values

Returns the DAPickableResult object.

See Also

PickableOccluded

PickableOccluded

DAImage Class

Makes a DAImage object pickable when there are other images between it and the mouse. This means that the pickable image will still get the event even if the mouse is on the occluding image.

imageObj.PickableOccluded( )

Return Values

Returns the DAPickableResult object.

See Also

Pickable

Tile

DAImage Class

Creates a DAImage object that consists of the original image tiled (repeated) in all directions. The bounding box is the infinite bounding box.

imageObj.Tile( )

Return Values

Returns the DAImage object.

Transform

DAImage Class

Creates a DAImage object that is the result of applying the given transformation to the points in the original image. For example, you can double the size of the opaque portion of the image by applying a transformation that scales by 2. The bounding box of a transformed image is determined by applying the transform to the bounding box of the underlying image and then enclosing the resultant quadrilateral with an axis-aligned box.

imageObj.Transform(
xf
)

Parameters
xf
The DATransform2 object applied to the original image.
Return Values

Returns the DAImage object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Undetectable

DAImage Class

Creates an undetectable DAImage from the original image.

imageObj.Undetectable

Return Values

Returns the DAImage object.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAImage.

lib.GradientHorizontalAnim(start, stop, power)

lib.GradientHorizontal(start, stop, power)

lib.GradientPolygon(pts, colors)

lib.GradientSquare(lowerLeft, upperLeft, upperRight, lowerRight)

lib.HatchBackwardDiagonalAnim(color, size0

lib.HatchBackwardDiagonal(color, size)

lib.HatchCrossAnim(color, size)

lib.HatchCross(color, size)

lib.HatchDiagonalCrossAnim(color, size)

lib.HatchDiagonalCross(color, size)

lib.HatchForwardDiagonalAnim(color, size)

lib.HatchForwardDiagonal(color, size)

lib.HatchHorizontalAnim(color, size)

lib.HatchHorizontal(color, size)

lib.HatchVerticalAnim(color, size)

lib.HatchVertical(color, size)

lib.ImportImage(url)

lib.ImportImageAsync(url, imgStandIn)

lib.ImportImageAsyncColorKey(url, imgStandIn, red, green, blue)

lib.ImportImageColorKey(url, red, green, blue)

lib.ImportMovie(url)

lib.ImportMovieAsync(url, imgStandIn, sndStandIn)

lib.Overlay(i1, i2)

lib.OverlayArray(im)

lib.RadialGradientPolygonAnim(inner, outer, points, power)

lib.RadialGradientPolygon(inner, outer, points, power)

lib.RadialGradientRegularPolyAnim(inner, outer, edges, power)

lib.RadialGradientRegularPoly(inner, outer, edges, power)

lib.RadialGradientSquareAnim(inner, outer, power)

lib.RadialGradientSquare(inner, outer, power)

lib.SolidColorImage( col)

lib.StringImageAnim(string, font)

lib.StringImage(string, font)

Relevant properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAImage.

lib.DetectableEmptyImage

lib.EmptyImage


DAImportationResult Class

The DAImportationResult object includes properties that contain information about media that is being downloaded either synchronously or asynchronously. For synchronous downloads, it is used in conjunction with ImportSound and ImportMovie. For asynchronous downloads, it is used with ImportGeometryAsync, ImportImageAsync, ImportMovieAsync, and ImportSoundAsync.

DAImportationResult Properties

CompletionEvent

Duration

Geometry

Image

Progress

Size

Sound

CompletionEvent

DAImportationResult Class

A read-only property with a DAEvent value that is the event that fires once a download is complete.

importationResultObj.CompletionEvent

Duration

DAImportationResult Class

A read-only property with a DANumber value that is the length of the media file being downloaded, in seconds.

importationResultObj.Duration

Geometry

DAImportationResult Class

A read-only property with a DAGeometry value that is the geometry being downloaded.

importationResultObj.Geometry

Image

DAImportationResult Class

A read-only property with a DAImage value that is the image being downloaded.

importationResultObj.Image

Progress

DAImportationResult Class

A read-only property with a DANumber value that is the percentage of the download that has been completed. A value of 0 means 0% and a value of 1 means 100%.

importationResultObj.Progress

Size

DAImportationResult Class

A read-only property with a DANumber value that is the size of the medium being downloaded, in bytes.

importationResultObj.Size

Sound

DAImportationResult Class

A read-only property with a DASound value that is the sound being downloaded.

importationResultObj.Sound


IDABvrHook Class

Used with the DABehavior class function, Hook. The IDABvrHook object is passed in as an argument and controls the creation of the new behavior.

IDABvrHook Functions

Notify

Notify

IDABvrHook Class

Calls the notifier method of the object whenever the behavior is started or sampled.

bvrHookObj.Notify(
id,
start,
startTime,
globalTime,
localTime,
sampledVal,
currentRunningBvr
)

Parameters
id
A long that distinguishes one instance of a behavior from another.
start
A boolean that determines if the notifier method is called when the behavior starts or each time it is sampled.
startTime
A double that is the time the behavior was first run.
globalTime
A double that is the time the behavior was sampled, in global time.
localTime
A double that is the time the behavior was sampled, in local time. (If the behavior is sampled when it starts, this value is 0).
sampledValue
The value of the DABehavior object at the time it was sampled. This value is wrapped as a constant behavior.
currentRunningBvr
The DABehavior object that is currently running.
Return Values

Returns the Behavior object.


IDASite Class

Gives an application control over error and status messages. It is used with the Site property in DAStatics.

IDASite Subroutines

ReportGC

SetStatusString

ReportGC

IDASite Class

Determines whether or not there will be notification before garbage collection begins.

siteObj.ReportGC(
bStarting
)

Parameters
bStarting
A boolean that, if TRUE, means there will be notification before garbage collection and, if FALSE, means there won't.

SetStatusString

IDASite Class

Sets the status message.

siteObj.SetStatusString(
statusText
)

Parameters
statusText
A string that is the status message.


DAJoinStyle Class

Creates a DAJoinStyle that represents a (potentially) animated join style. The object defines the style (shape) of the joint between intersecting line segments in a path. A joint is drawn only if some portions of the segments do not touch or overlap at the common endpoint. In this case, the outside corners of the line segments are connected and the resulting enclosed area is filled with the same color as the line.

Use a DAJoinStyle object with the Join function of the DALineStyle class.

This class inherits from DABehavior.

There are no DAJoinStyle functions, except the functions it inherits from the DABehavior class.

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAJoinStyle.

lib.JoinStyleBevel

lib.JoinStyleMiter

lib.JoinStyleRound


DALineStyle Class

Creates a DALineStyle object that represents a (potentially) animated line style. The object defines the various line styles to use when drawing lines. These styles includes the shape of the end of a line, the shape of joints between intersecting lines, the width of the line, and whether the line is drawn with a continuous stroke or as a sequence of dashes.

Use DALineStyle objects with the Draw function in the DAPath2 class.

This class inherits from DABehavior.

  • DALineStyle Functions
  • Relevant Properties from the DAStatics Class

DALineStyle Functions

AntiAliasing

Color

Dash

Detail

End

Join

WidthAnim

Width

AntiAliasing

DALineStyle Class

Determines whether or not the line will be antialiased. If antialias is 0 (the default), there is no antialiasing. If it is 1, there is antialiasing.

linestyleObj.AntiAliasing(
antialias
)

Parameters
antialias
A double that can be either 0 or 1.
Return Values

Returns the DALineStyle object.

Color

DALineStyle Class

Determines the color of a DALineStyle object. The default color is Black.

linestyleObj.Color(
color
)

Parameters
color
The DAColor object that sets the color of the line. The default color is Black.
Return Values

Returns the DALineStyle object.

Dash

DALineStyle Class

Creates a DALineStyle object that is the result of applying the given DADashStyle object to the existing line style. By default, the dash style is solid.

linestyleObj.Dash(
ds
)

Parameters
ds
The DADashStyle object that represents the dash style to apply.
Return Values

Returns the DALineStyle object.

Detail

DALineStyle Class

Creates a detail DALineStyle object from an existing line style. A detail line style is not changed by image scaling operations. The detail line style is the default line style, and it has no width.

linestyleObj.Detail

Return Values

Returns the DALineStyle object.

End

DALineStyle Class

Creates a DALineStyle object that is the result of applying the given end style, es, to the existing line style. By default, the end style is flat.

linestyleObj.End(
es
)

Parameters
es
The DAEndStyle object that represents the end style behavior to apply.
Return Values

Returns the DALineStyle object.

Join

DALineStyle Class

Creates a DALineStyle object that is the result of applying the given DAJoinStyle object to the existing line style. By default, the join style is beveled.

linestyleObj.join(
js
)

Parameters
js
The DAJoinStyle object that represents the join style to apply.
Return Values

Returns the DALineStyle object.

WidthAnim

DALineStyle Class

Creates a DANumber object from an existing line style by setting the width of line to the given amount, expressed in points. If the width results in a line less than a single pixel, the line is always drawn as a detail line.

linestyleObj.WidthAnim(
width
)

Parameters
width
The DANumber object that represents the width of the line. This must be an animated number.
Return Values

Returns the DALineStyle object.

Remarks

This overrides Detail.

Width

DALineStyle Class

Same as WidthAnim except that width is a non-animated number (a double).

linestyleObj.Width(
width
)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DALineStyle.

lib.DefaultLineStyle

lib.EmptyLineStyle


DAMatte Class

Creates a DAMatte object representing a (potentially) animated matte. A matte consists of a path and/or text, and is typically used to clip an image to the shape defined by the path and/or text.

This class inherits from DABehavior.

  • DAMatte Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAMatte Functions

Transform

Transform

DAMatte Class

Creates a DAMatte object that is the result of applying the given transformation xf to the original matte. The transformation affects each point in the path that defines the matte.

matteObj.Transform(
xf
)

Parameters
xf
The DATransform2 object that is applied to matteObj.
Return Values

Returns the DAMatte object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAMatte.

lib.DifferenceMatte(m1, m2)

lib.FillMatte(path)

lib.IntersectMatte(m1, m2)

lib.TextMatte(text, fs)

lib.UnionMatte(m1, m2)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAMatte.

lib.ClearMatte

lib.OpaqueMatte


DAMicrophone Class

Creates a DAMicrophone object that represents a (potentially) animated microphone. A microphone is used with the RenderSound function to produce spatialized sound behaviors from sounds embedded in a geometry.

Every microphone has a location and an orientation in a three-dimensional space, and this location determines how a sound is detected. The closer a microphone is to the source of a sound, the louder and sooner the microphone detects that sound. The effect is to "spatialize" the sound, that is, make it seem that it was actually recorded in a three-dimensional space.

For the default microphone, the location is the origin, looking in the negative z-direction, with positive y-axis considered up. You can create new microphones at different locations by using the Transform function. Microphones are omnidirectional.

This class inherits from the DABehavior class.

  • DAMicrophone Functions
  • Relevant Properties from the DAStatics Class

DAMicrophone Functions

Transform

Transform

DAMicrophone Class

Creates a new DAMicrophone object that is the result of applying the given transformation to the original microphone's location.

microphoneObj.Transform(
xf
)

Parameters
xf
The DATransform3 object to be applied to microphoneObj.
Return Values

Returns the DAMicrophone object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAMicrophone.

lib.DefaultMicrophone


DAMontage Class

A DAMontage object represents a montage that can be animated. A montage is a stack of images in which each image has an explicit depth. Images with larger Z-values are always in front of images with smaller z-values. Rendering a montage creates a new DAImage that is a composite of the images in the montage. The composite is created by overlaying the montage's images by order of depth and applying the same overlay rules as defined by the Overlay function in the DAStatics class.

Because the depth of an image in a montage can vary over time, rendering the montage at different points in time can produce different images in different orders.

This class inherits from the DABehavior class.

  • DAMontage Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAMontage Functions

Render

Render

DAMontage Class

Creates a DAImage object that consists of a composite of all images in the DAMontage object. The composite is created by overlaying the montage's images in order of Z-values, with the largest Z-value on top, and applying the same overlay rules as defined by the Overlay function in the DAImage class. If two images have the same depth, they are overlayed in the order in which they were added to the montage. The bounding box of a rendered montage is simply the union of the bounding boxes of all the images comprising that montage.

montageObj.Render

Return Values

Returns the DAImage object.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAMontage.

lib.ImageMontageAnim(image, depth)

lib.ImageMontage(image, depth)

lib.UnionMontage(m1, m2)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAMontage.

lib.EmptyMontage


DANumber Class

Creates a DANumber object that represents an animated number. This means the value of the object can vary over time.

This class inherits from the DABehavior class.

  • DANumber Functions
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DANumber Functions

AnimateProperty

Extract

ToStringAnim

ToString

AnimateProperty

DANumber Class

Allows control properties to be animated (vary over time). This function forms fragments of script and passes them to the scripting engine on every frame. For example, a DANumber object can be attached to the width property of a frame on an HTML page. When the invoke parameter is FALSE, the property is set directly as shown in this fragment from the JScript sample in JScript\Exercises\AnimatedGlow.html:

glow.AnimateProperty("DAControl.Filter[0].strength", "JScript", false, .08));

If the invoke parameter is TRUE, then a function name should be specified in the string parameter (property) and is invoked as shown in this fragment from the JScript sample in JScript\Templates\AnimatedProperties.html:

filterMethod = getNumber().AnimateProperty("SetFilter", "JScript", true, .1);

numberObj.AnimateProperty(
property,
language,
invoke,
update
)

Parameters
property
A string that is either the name of the property to animate or the name of a scripting function to invoke that will set the property.
language
A string that is name of the scripting language.
invoke
A boolean that determines if the property is set directly or if a function is invoked. If FALSE, the property is set directly. If TRUE, a function is invoked.
update
A double specifying how frequently the position is updated.
Return Values

Returns the DANumber object.

See Also

AnimateControlPositionPixel

Extract

DANumber Class

Extracts the value of numberObj, returning a number (a double). The object must have a constant value.

numberObj.Extract

Return Values

Returns a number (a double).

ToStringAnim

DANumber Class

Converts a DANumber object to a DAString object.

numberObj.ToStringAnim(
a
)

Parameters
a
The DANumber object representing the number of digits to use after the decimal point. This must be an animated number.
Return Values

Returns the DAString object.

ToString

DANumber Class

Converts a double to a DAString.

numberObj.ToString(
a
)

Parameters
a
The double representing the number of digits to use after the decimal point.
Return Values

Returns the DAString object.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant for objects of type DANumber.

lib.Abs(a)

lib.Acos(a)

lib.Add(a, b)

lib.Asin(a)

lib.Atan(a)

lib.Atan2(a, b)

lib.Ceiling(a)

lib.Cos(a)

lib.DANumber(a)

lib.Derivative(a)

lib.Div(a, b)

lib.EQ(a, b)

lib.Exp(a)

lib.Floor(a)

lib.GT(a, b)

lib.GTE(a, b)

lib.Integral(a)

lib.InterpolateAnim(from, to, duration)

lib.Interpolate(from, to, duration)

lib.Ln(a)

lib.Log10(a)

lib.LT(a, b)

lib.LTE(a, b)

lib.Mod(a, b)

lib.Mul(a, b)

lib.NE(a, b)

lib.Neg(a)

lib.NumberBSpline(degree, knots, control_elements, weights, evaluation)

lib.Pow(a, b)

lib.Round(a)

lib.SeededRandom(seed)

lib.Sin(a)

lib.SlowInSlowOut(from, to, duration, acceleration)

lib.SlowInSlowOutAnim(from, to, duration, acceleration)

lib.Sqrt(a)

lib.Sub(a, b)

lib.Tan(a)

lib.ToDegrees(a)

lib.ToRadians(a)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant for objects of type DANumber.

lib.GlobalTime

lib.LocalTime


DAPair Class

Used in conjunction with AndEvent and DAPickableResult. The AndEvent function creates a third event from two simultaneously occurring events. It returns a DAPair whose first member is the event data returned by the first event and whose second member is the data returned by the second event. The DAPickableResults object contains a DAEvent that is a DAPair whose first member is the point of intersection and whose second member is a vector that is perpendicular to the surface. Note that, unlike arrays, a DAPair can contain two objects of different types.

DAPair Properties

First

Second

First

DAPair Class

A read-only property with a DABehavior value that is the first object of the DAPair.

pairObj.First

Second

DAPair Class

A read-only property with a DABehavior value that is the second object of the DAPair.

pairObj.Second


DAPath2 Class

Creates a DAPath2 object that represents a path in two-dimensional space. A DAPath2 object consists of a sequence of two-dimensional points (potentially animated) and is typically used to draw images consisting of line segments or to define borders for geometric shapes.

This class inherits from the DABehavior class.

  • DAPath2 Functions
  • Relevant Functions from the DAStatics Class

DAPath2 Functions

BoundingBox

Close

Draw

Fill

Transform

BoundingBox

DAPath2 Class

Creates a DAPath2 object that is a visible bounding box.

path2Obj.BoundingBox(
style
)

Parameters
style
A DALineStyle object. This argument is ignored. The line style is always the default line style and has a width of 0.
Return Values

Returns the DAPath2 object.

Close

DAPath2 Class

Adds a line segment from the end of the path to the start. This function is useful for animating closed regions.

path2Obj.Close

Return Values

Returns the DAPath2 object.

Draw

DAPath2 Class

Renders the DAPath2 object into a DAImage object. The image is unfilled, which means only the outline is rendered.

path2Obj.Draw(
ls
)

Parameters
ls
The DALineStyle used to render the image.
Return Values

Returns the DAImage object.

Fill

DAPath2 Class

Renders the DAPath2 object into a DAImage object. The im parameter specifies the image used to fill in the new DAImage object. The ls argument specifies the DALineStyle that is used to draw the outline.

path2Obj.Fill(
ls,
im
)

Parameters
ls
The DALineStyle object used to draw the path.
im
The DAImage object used as the fill pattern.
Return Values

Returns the DAImage object.

Transform

DAPath2 Class

Creates a new Path2 object that is the result of applying the given transformation to the points in the original path.

path2Obj.Transform(
xf
)

Parameters
a
The DATransform2 object representing the transformation to apply to the original path.
Return Values

Returns the DAPath2 object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant for objects of type DAPath2.

lib.ArcDegrees(startAngle, endAngle, arcWidth, arcHeight)

lib.ArcRadiansAnim(startAngle, endAngle, arcWidth, arcHeight)

lib.ArcRadians(startAngle, endAngle, arcWidth, arcHeight)

lib.Concat(p1, p2)

lib.ConcatArray(paths)

lib.CubicBSplinePath(points, knots)

lib.Line(p1, p2)

lib.OvalAnim(width, height)

lib.Oval(width, height)

lib.PieDegrees(startAngle, endAngle, arcWidth, arcHeight)

lib.PieRadiansAnim(startAngle, endAngle, arcWidth, arcHeight)

lib.PieRadians(startAngle, endAngle, arcWidth, arcHeight)

lib.PolyDrawPath(points, codes)

lib.Polyline(points)

lib.Ray(p)

lib.RectAnim(width, height)

lib.Rect(width, height)

lib.RoundRectAnim(width, height, arcWidth, arcHeight)

lib.RoundRect(width, height, arcWidth, arcHeight)

lib.StringPathAnim(string, fs)

lib.StringPath(string, fs)


DAPickableResult Class

The properties on a DAPickableResult object are used either with DAGeometry.Pickable function or with DAImage.Pickable function. The properties are either the new, pickable DAGeometry object or DAImage object, and the DAEvent that occurs when the mouse is within the pickable region.

DAPickableResult Properties

Geometry

Image

PickEvent

Geometry

DAPickableResult Class

A read-only property with a DAGeometry value that is the pickable geometry.

pickableResultObj.Geometry

Image

DAPickableResult Class

A read-only property with a DAImage value that is the pickable image.

pickableResultObj.Image

PickEvent

DAPickableResult Class

A read-only property with a DAEvent value that is the event that fires when the mouse is within the pickable region. This event is a DAPair object whose first member is the point of intersection and whose second member is a vector that is perpendicular to the surface.

pickableResultObj.PickEvent


DAPoint2 Class

Creates a DAPoint2 object that represents a two-dimensional point that can be animated (vary over time). At any given time, the value is a point representing a location in a plane or on the screen. Each point has a pair of coordinate values that define the point's location relative to a fixed point called the origin. These coordinate values are given as either Cartesian coordinates (x,y) or polar coordinates (XYangle,length) when the point DAPoint2 object is created.

Because coordinate values are DANumber objects the location of a DAPoint2 can change over time as the DANumbers change.

This class inherits from DABehavior.

  • DAPoint2 Functions
  • DAPoint2 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAPoint2 Functions

AnimateControlPositionPixel

Transform

AnimateControlPositionPixel

DAPoint2 Class

Used to form fragments of script and pass them to the scripting engine on every frame. This function is specifically with DAPoint2 objects to animate the two-dimensional position of an element on the page.

The AnimateControlPositionPixel function always treats the values of the points as pixels rather than meters and considers positive-y to be down rather than up. The (0,0) point is in the upper-left corner.

point2Obj.AnimateControlPositionPixel(
property,
language,
invoke,
interval
)

Parameters
property
A string that is either the name of the property to animate or the name of a scripting function to invoke that will set the property.
language
A string that is name of the scripting language.
invoke
A boolean that determines if the position is set directly or if a function is invoked. If FALSE, the position is set directly. If TRUE, a function is invoked.
interval
A double specifying how frequently the position is updated.
Return Values

Returns the DAPoint2 object.

Transform

DAPoint2 Class

Creates a DAPoint2 object that is the result of applying the given transformation to the original DAPoint2 object.

point2Obj.Transform(
xf
)

Parameters
xf
The DATransform2 object.
Return Values

Returns the DAPoint2 object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

DAPoint2 Properties

PolarCoordAngle

PolarCoordLength

X

Y

PolarCoordAngle

DAPoint2 Class

A read-only property with a DANumber value that represents the counter-clockwise angular displacement, in radians, relative to the positive x-axis, of the pointObj. The range is [-Pi, +Pi].

point2Obj.PolarCoordAngle

See Also

PolarCoordLength, Point2PolarAnim

PolarCoordLength

DAPoint2 Class

A read-only property with a DANumber value that represents the distance of the point from the origin.

point2Obj.PolarCoordLength

See Also

PolarCoordAngle, Point2PolarAnim

X

DAPoint2 Class

A read-only property with a DANumber value that represents the x coordinate of the point2Obj.

point2Obj.X

Return Values

Returns the DANumber object.

See Also

Y, Point2Anim

Y

DAPoint2 Class

A read-only property with a DANumber value that represents the y coordinate of the point2Obj.

point2Obj.Y

See Also

X, Point2Anim

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAPoint2.

lib.AddPoint2Vector(pt, vec)

lib.DerivativePoint2(pt)

lib.DistancePoint2(p1, p2)

lib.DistanceSquaredPoint2(p1, p2)

lib.Point2(x, y)

lib.Point2Anim(x, y)

lib.Point2BSpline(degree, knots, control_elements, weights, evaluation)

lib.Point2PolarAnim(XYangle, length)

lib.Point2Polar(XYangle, length)

lib.SubPoint2(p1, p2)

lib.SubPoint2Vector(pt, vec)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAPoint2.

lib.MousePosition

lib.Origin2


DAPoint3 Class

Creates a DAPoint3 object. At any given time, the value is a point representing a location in a three-dimensional space. Each point has a triplet of coordinate values that define the point's location relative to a fixed point called the origin. These coordinate values are given as either Cartesian coordinates (x,y, z) or spherical coordinates (XYangle,YZangle,length) when the point behavior is created.

Because coordinate values are DANumber objects, the location of a DAPoint3 object can change over time as the DANumber values change.

This class inherits from DABehavior.

  • DAPoint3 Functions
  • DAPoint3 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAPoint3 Functions

Project

Transform

Project

DAPoint3 Class

Creates the DAPoint2 object of the projection of the DAPoint3 object onto the image plane, via the given DACamera object.

point3Obj.Project(
camera
)

Parameters
camera
The DACamera object projecting the three-dimensional point onto the image plane.
Return Values

Returns the DAPoint2 object.

Transform

DAPoint3 Class

Creates a new DAPoint3 object that is the result of applying the given transformation to the original point.

point3Obj.Transform(
xf
)

Parameters
xf
The DATransform3 object.
Return Values

Returns the DAPoint3 object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

DAPoint3 Properties

SphericalCoordLength

SphericalCoordXYAngle

SphericalCoordYZAngle

X

Y

Z

SphericalCoordLength

DAPoint3 Class

A read-only property with a DANumber value that is the distance of the point from the origin.

point3Obj.SphericalCoordLength

See Also

SphericalCoordXYAngle, SphericalCoordYZAngle, Point3SphericalAnim

SphericalCoordXYAngle

DAPoint3 Class

A read-only property with a DANumber value that should more properly be thought of as an XZ angle. For positive values, it is the counter-clockwise angle, in radians, of the point in the XZ plane. When the angle is 0, the point lies on the z-axis. The range is [-Pi, +Pi].

point3Obj.SphericalCoordXYAngle

See Also

SphericalCoordYZAngle, SphericalCoordLength, Point3SphericalAnim

SphericalCoordYZAngle

DAPoint3 Class

A read-only property with a DANumber value that should more properly be thought of as an XY angle. For positive values, it is the counter-clockwise angle, in radians, going from the XZ-plane towards the positive y-ray. When the angle is 0, the point lies on the x-axis. The range is [-Pi/2, +Pi/2].

point3Obj.SphericalCoordYZAngle

Return Values

Returns the DANumber object.

See Also

SphericalCoordXYAngle, SphericalCoordLength, Point3SphericalAnim

X

DAPoint3 Class

A read-only property with a DANumber value that is the x coordinate of this point3Obj.

point3Obj.X

See Also

Y, Z, Point3Anim

Y

DAPoint3 Class

A read-only property with a DANumber value that is the y coordinate of this point3Obj.

point3Obj.Y

See Also

X, Z, Point3Anim

Z

DAPoint3 Class

A read-only property with a DANumber value that is the z coordinate of this point3Obj.

point3Obj.Z

See Also

X, Y, Point3Anim

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAPoint3.

lib.AddPoint3Vector(pt, vec)

lib.DerivativePoint3(pt)

lib.DistancePoint3(p1, p2)

lib.DistanceSquaredPoint3(p1, p2)

lib.Point3Anim(x, y, z)

lib.Point3(x, y, z)

lib.Point3BSpline(degree, knots, control_elements, weights, evaluation)

lib.Point3Spherical(XYangle, YZangle, length)

lib.Point3SphericalAnim(XYangle, YZangle, length)

lib.SubPoint3(p1, p2)

lib.SubPoint3Vector(pt, vec)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAPoint3.

lib.Origin3


DASound Class

DASound Sound behavior objects have gain, rate, phase and pan attributes. Imported sounds (.WAV and .MIDI files) also have a length, returned by the import function. Gain (volume) defines how loud the sound is played. Rate defines how many times faster or slower the sound is played relative to its nominal rate. Phase defines how much to shift the time of the sound, and is useful for creating special sound effects such as echoes. Mixing the same sounds that are out of phase makes the sound richer. Pan defines the strength of the sound relative to the left and right sound channels. This is useful for positioning sounds.

Gain, rate, phase, and pan can use animated numbers and can, therefore, change over time. This is useful for modifying the sound based, not only on time (see SubstituteTime) but also on other computed values such as distance. Sounds can be embedded in a geometry to achieve spatialized effects. Currently, all sounds are omnidirectional.

This class inherits from DABehavior.

  • DASound Functions
  • Relevant Functions from the DAStatics Class

DASound Functions

GainAnim

Gain

Loop

PanAnim

Pan

PhaseAnim

Phase

RateAnim

Rate

GainAnim

DASound Class

Multiplies the gain (volume) by the given amount.

soundObj.GainAnim(
gain
)

Parameters
gain
The factor by which to multiply the volume. Values greater than one increase the volume and values between zero and 1 decrease the sound's volume. Except for sound geometries, only attenuation values of 0-1 have an effect. For sound geometries, gains greater than 1 affect the distance from which sounds can be heard. The sounds, however, never sound louder than 1. This must be an animated number (DANumber).
Return Values

Returns a DASound object representing the newly created sound.

Gain

DASound Class

Same as GainAnim except the parameter is non-animated.

soundObj.Gain

Loop

DASound Class

Creates a DASound object that repeats continuously. This method applies to the primitive sounds themselves. It does not loop a reactive sound behavior. Instead, it loops each of the primitive sounds that are components of the reactive sound behavior. For example, assume you have a sound that is sound1 until the left mouse button is pressed, and then becomes sound2, and you loop this composite sound, as shown in the following JScript code:

snd =  m.Until(sound1, m.LeftButtonDown, sound2);
loopsnd= snd.Loop();

The resulting sound is a continuous loop of sound1 until the left mouse button is pressed, then becomes a continuous loop of sound2. It does not loop the composite behavior in that it does not loop sound1 until the button is pressed, then cycle through sound2 once, then go back to playing sound1 until the button is pressed again.

soundObj.Loop( )

Return Values

Returns a DASound object.

PanAnim

DASound Class

Creates a DASound object by repositioning a monophonic sound between the left and right channels. To do this, the amplitude of the sound in each channel is changed. This is similar to adjusting the balance on a stereo.

soundObj.PanAnim(
pan
)

Parameters
pan
The amount to pan. Can be a value in the range -1.0 to 1.0, with -1.0 as full left, 0 as center, and 1.0 as full right. This must be an animated number (DANumber).
Return Values

Returns a DASound object.

Remarks

With stereophonic sounds, panning away from a channel attenuates it.

Pan

DASound Class

Same as PanAnim except the parameter is non-animated.

soundObj.Pan(
pan
)

PhaseAnim

DASound Class

Creates a new DASound object by shifting the sound in time by the given amount. Shifting the sound and mixing with the original sound allows for special effects, such as echoing.

soundObj.PhaseAnim(
phase
)

Parameters
phase
The amount in seconds (or fractions of seconds) to shift the sound. This must be an animated number (DANumber).
Return Values

Returns a DASound object.

Remarks

For unlooped sounds, a positive phase shift delays the sound's starting time while a negative phase shift clips off the beginning of the sound. For looped sounds, a positive phase shift adds the end of the sound to the beginning of the sound, while a negative phase shift controls how far into the sound the beginning should be. Phase-shifting only takes effect when the sound begins playing. Currently, you cannot dynamically change the position of a running sound. This attribute composes additively.

Phase

DASound Class

Same as PhaseAnim except the parameter is non-animated.

soundObj.Phase(
phase
)

RateAnim

DASound Class

Creates a DASound object by multiplying the playback rate by the given amount.

soundObj.RateAnim(
rate
)

Parameters
rate
Specifies the factor by which to multiply the rate. Values greater than one increase the rate and values between zero and 1 decrease it. This must be an animated number (DANumber).
Return Values

Returns a DASound object.

Remarks

A rate of 0 pauses the sound. Negative rates are not supported. This attribute composes additively.

Rate

DASound Class

Same as RateAnim except the parameter is non-animated.

soundObj.Rate(
rate
)

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DASound.

lib.ImportSound(url)

lib.ImportSoundAsync(url, soundStandIn)

lib.mix(sound1, sound2)

lib.mixArray(sounds)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DASound.

lib.Silence

lib.SinSynth


DAStatics Class

The DAStatics class is a library that holds a variety of functions and properties.

The following table lists the classes that have relevant functions and properties in the DAStatics class. Click on any group of functions to see them.

A
DAStatic Functions Relevant to DAArray Objects
B
DAStatic Functions Relevant to DABehavior Objects
DAStatic Functions Relevant to DABoolean Objects
DAStatic Properties Relevant to DABoolean Objects
C
DAStatic Functions Relevant to DACamera Objects
DAStatic Functions Relevant to DAColor Objects
DAStatic Properties Relevant to DAColor Objects
D
DAStatic Properties Relevant to DADashStyle Objects
DAStatic Functions Relevent to DADrawingSurface Objects
E
DAStatic Properties Relevant to DAEndStyle Objects
DAStatic Functions Relevant to DAEvent Objects
DAStatic Properties Relevant to DAEvent Objects
F
DAStatic Functions Relevant to DAFontStyle Objects
DAStatic Properties Relevant to DAFontStyle Objects
G
DAStatic Functions Relevant to DAGeometry Objects
DAStatic Properties Relevant to DAGeometry Objects
I
DAStatic Functions Relevant to DAImage Objects
DAStatic Properties Relevant to DAImage Objects
J
DAStatic Properties Relevant to DAJoinStyle Objects
L
DAStatic Properties Relevant to DALineStyle Objects
M
DAStatic Functions Relevant to DAMatte Objects
DAStatic Properties Relevant to DAMatte Objects
DAStatic Properties Relevant to DAMicrophone Objects
Miscellaneous DAStatic Functions
Miscellaneous DAStatic Properties
DAStatic Functions Relevant to DAMontage Objects
DAStatic Properties Relevant to DAMontage Objects
N
DAStatic Functions Relevant to DANumber Objects
DAStatic Properties Relevant to DANumber Objects
P
DAStatic Functions Relevant to DAPath2 Objects
DAStatic Functions Relevant to DAPoint2 Objects
DAStatic Properties Relevant to DAPoint2 Objects
DAStatic Functions Relevant to DAPoint3 Objects
DAStatic Properties Relevant to DAPoint3 Objects
S
DAStatic Functions Relevant to DASound Objects
DAStatic Properties Relevant to DASound Objects
DAStatic Functions Relevant to DAString Objects
T
DAStatic Functions Relevant to DATransform2 Objects
DAStatic Properties Relevant to DATransform2 Objects
DAStatic Functions Relevant to DATransform3 Objects
DAStatic Properties Relevant to DATransform3 Objects
DAStatic Functions Relevant to DATuple Objects
V
DAStatic Functions Relevant to DAVector2 Objects
DAStatic Properties Relevant to DAVector2 Objects
DAStatic Functions Relevant to DAVector3 Objects
DAStatic Properties Relevant to DAVector3 Objects


DAStatic Functions Relevant to DAArray Objects

DAArray

DAStatics Class

Constructs a DAArray object.

lib.DAArray(
behaviors
)

Parameters
behaviors
The elements in the array.

UninitializedArray

DAStatics Class

Makes it possible to obtain the signature of a DAArray object before it has been defined. With this function, a DAArray object can be created and used in the definition of other DABehaviors, while its contents are defined at some later point. (This definition is accomplished with the Init function, which is available on all DABehavior objects. To create an uninitialize array, first create an array with a dummy variable and its types, and then call UninitializedArray. This will create a variant array which has a signature only. It is only necessary to give one member of the array, no matter how many members there will actually be.

lib.UninitializedArray( )

See Also

UninitializedTuple


DirectAnimation Animated Header --DAStatic Functions Relevant to DABehavior Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DABehavior Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAArray Objects
  * Next Topic: DAStatic Functions Relevant to DABoolean Objects

DAStatic Functions Relevant to DABehavior Objects

Cond

DAStatics Class

Creates a new behavior from the DABoolean and two other behaviors. The value of the new behavior, at any point in time, is one of those two behaviors. Which of the behaviors chosen depends on the value of the DABoolean.

lib.Cond(
bool,
a,
b
)

Parameters
bool
The DABoolean object that determines which of the two behaviors will become the value of the new behavior.
a
The first of the two possible values the new behavior can assume.
b
The second of the two possible values the new behavior can assume.
Return Values

Returns the DABehavior object.

ModifiableBehavior

DAStatics Class

Returns an object whose animated behavior can be replaced, at run time, with another animated behavior. This is useful when the states of an animation model cannot be predicted at development time, as well as for integrating animation models with other events and functions.

lib.ModifiableBehavior(
initialBehavior
)

Parameters
initialBehavior
The behavior that will later be replaced.
Return Values

Returns the DABehavior object.

See Also

SwitchTo(newBehavior)

Sequence

DAStatics Class

Creates a new behavior that is the sum of the two DABehavior parameters. In other words, the two behaviors are concatenated, according to their order in the parameter list. Once the duration is over, the behavior becomes a snapshot of the second behavior. An exception is when the first behavior is of infinite duration. In this case, the returned behavior is always the infinite behavior, no matter what the second behavior is.

lib.Sequence(
a,
b
)

Parameters
a
The first behavior in the sequence.
b
The second behavior in the sequence.
Return Values

Returns the DABehavior object.

Remarks

Notice that, in contrast to Compose2 and Compose3, which first apply the right-hand argument and then the left, Sequence first applies the left-hand argument and then the right.

Until

DAStatics Class

Creates a behavior that changes when a given event occurs. Up to and including the time the event occurs, the behavior is the same as a. After the event e occurs, the behavior changes to be the same as b. Because Until takes behaviors and returns a behavior, it can be nested.

lib.Until(
a,
e,
b
)

Parameters
a
The DABehavior object that the behavior represents initially.
e
A DAEvent object specifying the event.
b
The DABehavior object that the behavior represents after the event.
Return Values

Returns the DABehavior object.

UntilEx

DAStatics Class

Creates a DABehavior that changes upon a given event. Initially, the behavior is the same as a. When event e occurs, the behavior changes to the behavior returned by the event. This means that only DAEvents that return a DABehavior can be used. These events can be constructed with AttachData, Notify, and Snapshot.

lib.UntilEx(
a,
e
)

Parameters
a
The DABehavior object that the behavior represents initially.
e
The DAEvent object that triggers the switch and returns the new behavior.
Return Values

Returns the DABehavior object caused by the event e.


DirectAnimation Animated Header --DAStatic Functions Relevant to DABoolean Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DABoolean Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DABehavior Objects
  * Next Topic: DAStatic Properties Relevant to DABoolean Objects

DAStatic Functions Relevant to DABoolean Objects

And

DAStatics Class

Creates a DABoolean that represents the logical AND of the given objects. The object's value is TRUE when both b1 and b2 are TRUE; otherwise, it is FALSE.

lib.And(
b1,
b2
)

Parameters
b1 and b2
The DABoolean objects to logically AND.
Return Values

Returns the DABoolean object.

See Also

Or, Not

DABoolean

DAStatics Class

Converts a boolean to a DABoolean object. The only time DABoolean is used is when converting boolean values to their corresponding DABoolean objects.

lib.DABoolean

Parameters
bool
The boolean to be converted.
Return Values

Returns the DABoolean object.

KeyState

DAStatics Class

Creates a DABoolean object that describes whether the key is up or down.

lib.KeyState(
keyCode
)

Parameters
keyCode
A DANumber representing a keycode.
Return Values

Returns the DABoolean object. The value is TRUE when the key is down and FALSE when the key is up.

Not

DAStatics Class

Creates a DABoolean object that represents the logical NOT of b. The object's value is TRUE when b is FALSE; otherwise, it is FALSE.

lib.Not(
b
)

Parameters
b
The DABoolean object that is negated.
Return Values

Returns the DABoolean object.

See Also

And , Or

Or

DAStatics Class

Creates a DABoolean that represents the logical OR of the given behaviors. The object's value is TRUE when either b1 or b2 is TRUE; otherwise it is FALSE.

lib.Or(
b1,
b2
)

Parameters
b1 and b2
The DABoolean objects to be logically OR'd.
Return Values

Returns the DABoolean object.

See Also

And, Not


DirectAnimation Animated Header --DAStatic Properties Relevant to DABoolean Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DABoolean Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DABoolean Objects
  * Next Topic: DAStatic Functions Relevant to DACamera Objects

DAStatic Properties Relevant to DABoolean Objects

DAFalse

DAStatics Class

A read-only property that is always FALSE.

lib.DAFalse

LeftButtonState

DAStatics Class

A read-only property that is TRUE if the left mouse button is down and FALSE if it is up.

lib.LeftButtonState

RightButtonState

DAStatics Class

A read-only property that is TRUE if the right mouse button is down and FALSE if it is up.

lib.RightButtonState

DATrue

DAStatics Class

A read-only property that is always TRUE.

lib.DATrue


DirectAnimation Animated Header --DAStatic Functions Relevant to DACamera Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DACamera Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DABoolean Objects
  * Next Topic: DAStatic Functions Relevant to DAColor Objects

DAStatic Functions Relevant to DACamera Objects

ParallelCameraAnim

DAStatics Class

Creates a parallel camera for parallel (or orthographic) projection. The parallel camera is transformed the same way as the perspective camera, except that Z-scales have no effect (note, however, that zero or negative Z-scales yield undefined results).

Prior to transformation, the parallel camera gazes in the negative z-direction, with positive y-axis considered as "up."

lib.ParallelCameraAnim(
nearclip
)

Parameters
nearclip
The DANumber object that is the Z-location of the near clipping plane. This value must be an animated number.
Return Values

Returns the DACamera object.

ParallelCamera

DAStatics Class

Same as ParallelCameraAnim except nearclip is a non-animated number (a double).

lib.ParallelCamera(
nearclip
)

PerspectiveCameraAnim

DAStatics Class

Creates a perspective camera for perspective rendering. On creation, the projection plane (the plane at which objects appear as their actual size) is located at Z=0, the projection point is located at [0 0 projdst], and the near clipping plane is located at [0 0 nearclip].

The projdst parameter specifies the distance between the projection plane and the projection point, and must be greater than zero. The smaller this distance, the more of a wide-angle effect is achieved. The larger this distance, the more of a telephoto effect is achieved.

The nearclip parameter specifies the Z-location of the near clipping plane and must be less than projdst. In other words, the near clipping plane must lie on the same side of the projection point as the projection plane. Although it is tempting to place the near clipping plane as close as possible to the projection point, Z-buffer precision is lost dramatically as the near clipping plane gets closer to the projection point. (The main result of such precision loss is that far objects are rendered in front of near objects.)

lib.PerspectiveCameraAnim(
projdst,
nearclip
)

Parameters
projdst
The DANumber object that is the Z-location of the projection point. It must be greater than zero. This value must be an animated number.
nearclip
The DANumber object that is the Z-location of the near clipping plane. It must be less than projdst. This value must be an animated number.
Return Values

Returns the DACamera object.

Remarks

The following diagram shows a model of the perspective camera. Note that the nearclip need not be in front of the projection plane.

PerspectiveCamera

DAStatics Class

Same as PerspectiveCameraAnim, except that projdst and nearclip are non-animated numbers (doubles).

lib.PerspectiveCamera(
projdst,
nearclip
)


DirectAnimation Animated Header --DAStatic Functions Relevant to DAColor Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAColor Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DACamera Objects
  * Next Topic: DAStatic Properties Relevant to DAColor Objects

DAStatic Functions Relevant to DAColor Objects

ColorHslAnim

DAStatics Class

Creates a DAColor object that represents a color described by its hue, saturation, and lightness values. The object's value at any given time depends on the values of h, s, and l.

lib.ColorHslAnim(
h,
s,
l
)

Parameters
h
A DANumber object specifying the hue or base color. 0.0 is red, 0.33 is green, and 0.67 is blue. This number is considered "modulo 1," which means, for example, that the numbers 1.67, and 0.67 are both considered to be 0.67. This value must be an animated number.
s
A DANumber object specifying saturation or intensity of the hue. If saturation is 0.0, the color produced is gray regardless of the hue value. This value must be an animated number.
l
A DANumber object specifying lightness or amount of white in the color. If lightness is 1.0, the color produced is white regardless of the hue and saturation values. Similarly, if lightness is 0.0, the color is black. This value must be an animated number.
Return Values

Returns the DAColor object.

Remarks

Hue, saturation, and lightness values can range from 0.0 to 1.0. If the corresponding number behavior has a value outside this range, then the number is considered modulo 1.

See Also

ColorRgbAnim

ColorHsl

DAStatics Class

Same as ColorHslAnim except that h, s, and l are non-animated numbers (doubles).

lib.ColorHsl(
h,
s,
l
)

ColorRgbAnim

DAStatics Class

Creates a DAColor object that represents a color described by its red, green, and blue intensity values. The object's value at any given time depends on the values of r, g, and b.

lib.ColorRgbAnim(
r,
g,
b
)

Parameters
r, g, and b
The DANumber objects specifying the red, green, and blue values, respectively. The value of each specifies that color's intensity, with 0.0 for no color and 1.0 for the highest possible intensity. These values must be animated numbers.
Return Values

Returns the DAColor object.

Remarks

Intensity values can range from 0.0 to 1.0. If the corresponding number behavior has a value outside this range, the integer part of the value is discarded and only the fractional part is used.

See Also

ColorHslAnim

ColorRgb

DAStatics Class

Same as ColorRgbAnim except that r, g, and b are non-animated numbers (doubles).

lib.ColorRgb(
r,
g,
b
)

ColorRgb255

DAStatics Class

Creates a DAColor object that represents a color described by its red, green, and blue intensity values. The behavior's value at any given time depends on the values of r, g, and b. These values can be in the range [0, 255].

lib.ColorRgb255(
r,
g,
b
)

Parameters
r, g, and b
The numbers (integers) specifying the red, green, and blue values, respectively. The value of each specifies that color's intensity, with 0 for no color and 255 for the highest possible intensity.
Return Values

Returns the DAColor object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DAColor Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAColor Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAColor Objects
  * Next Topic: DAStatic Properties Relevant to DADashStyle Objects

DAStatic Properties Relevant to DAColor Objects

Aqua

DAStatics Class

A read-only property with a DAColor value that is always aqua. In a range of [0, 1], its red, green, and blue intensity values are 0.00, 1.00, 1.00. In a range of [0-255], its values are 0, 255, 255.

lib.Aqua

Black

DAStatics Class

A read-only property with a DAColor value that is always black. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 0.00. In a range of [0-255], its values are 0, 0, 0.

lib.Black

Blue

DAStatics Class

A read-only property with a DAColor value that is always blue. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 1.00. In a range of [0-255], its values are 0, 0, 255.

lib.Blue

Cyan

DAStatics Class

A read-only property with a DAColor value that is always cyan. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 1.00. In a range of [0-255], its values are 0, 255, 255.

lib.Cyan

Fuchsia

DAStatics Class

A read-only property with a DAColor value that is always fuchsia. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 1.00). In a range of [0-255], its values are 255, 0, 255.

lib.Fuchsia

Gray

DAStatics Class

A read-only property with a DAColor value that is always gray. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.50,0.50. In a range of [0-255], its values are 128, 128, 128.

lib.Gray

Green

DAStatics Class

A read-only property with a DAColor value that is always green. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 0.00. In a range of [0-255], its values are 0, 255, 0.

lib.Green

Lime

DAStatics Class

A read-only property with a DAColor value that is always lime. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 0.00. In a range of [0-255], its values are 0, 255, 0.

lib.Lime

Magenta

DAStatics Class

A read-only property with a DAColor value that is always magenta. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 1.00. In a range of [0-255], its values are 255, 0, 255.

lib.Magenta

Maroon

DAStatics Class

A read-only property with a DAColor value that is always maroon. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.00, 0.00. In a range of [0-255], its values are 128, 0, 0.

lib.Maroon

Navy

DAStatics Class

A read-only property with a DAColor value that is always navy. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 0.50. In a range of [0-255], its values are 0, 0, 128.

lib.Navy

Olive

DAStatics Class

A read-only property with a DAColor value that is always olive. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.50, 0.00. In a range of [0-255], its values are 128, 128, 0.

lib.Olive

Purple

DAStatics Class

A read-only property with a DAColor value that is always purple. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.00, 0.50. In a range of [0-255], its values are 128, 0, 128.

lib.Purple

Red

DAStatics Class

A read-only property with a DAColor value that is always red. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 0.00. In a range of [0-255], its values are 255, 0, 0.

lib.Red

Silver

DAStatics Class

A read-only property with a DAColor value that is always silver. In a range of [0-1], its red, green, and blue intensity values are 0.75, 0.75, 0.75. In a range of [0-255], its values are 192, 192, 192.

lib.Silver

Teal

DAStatics Class

A read-only property with a DAColor value that is always teal. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.50, 0.50. In a range of [0-255], its values are 0, 128, 128.

lib.Teal

White

DAStatics Class

A read-only property with a DAColor value that is always white. In a range of [0-1], its red, green, and blue intensity values are 1.00, 1.00, 1.00. In a range of [0-255], its values are 255, 255, 255.

lib.White

Yellow

DAStatics Class

A read-only property with a DAColor value that is always yellow. In a range of [0-1], its red, green, and blue intensity values are 1.00, 1.00, 0.00. In a range of [0-255], its values are 255, 255, 0.

lib.Yellow


DirectAnimation Animated Header --DAStatic Properties Relevant to DADashStyle Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DADashStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAColor Objects
  * Next Topic: DAStatic Functions Relevent to DADrawingSurface Objects

DAStatic Properties Relevant to DADashStyle Objects

DashStyleDashed

DAStatics Class

A read-only property with a DADashStyle value indicating a dashed line (a sequence of line segments and spaces).

lib.DashStyleDashed

DashStyleSolid

DAStatics Class

A read-only property with a DADashStyle value indicating a solid line (a continuous stroke).

lib.DashStyleSolid


DirectAnimation Animated Header --DAStatic Functions Relevent to DADrawingSurface Objects DirectAnimation Animated Header --DAStatic Functions Relevent to DADrawingSurface Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DADashStyle Objects
  * Next Topic: DAStatic Functions Relevant to DAEvent Objects

DAStatic Functions Relevent to DADrawingSurface Objects

ImportDirectDrawSurface

DAStatics Class

Imports a DADrawingSurface object and passes it into the DirectAnimation engine. The DADrawingSurface is translated into a DAImage object, and can then use any of the relevant function calls. The import occurs upon a triggering event.

lib.ImportDirectDrawSurface(
dds,
updateEvent
)

Parameters
dds
The DADrawingSurface object to import.
updateEvent
The DAEvent_Class object that triggers the import.
Return Values

Returns the DAImage object.

NewDrawingSurface

DAStatics Class

Creates an empty DADrawingSurface object.

lib.NewDrawingSurface( )


DirectAnimation Animated Header --DAStatic Functions Relevant to DAEvent Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAEvent Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevent to DADrawingSurface Objects
  * Next Topic: DAStatic Properties Relevant to DAEvent Objects

DAStatic Functions Relevant to DAEvent Objects

AndEvent

DAStatics Class

Creates an event that occurs only when the two given events happen simultaneously. The event time for the new event is when both of the given events occur.

lib.AndEvent(
first,
second
)

Parameters
first and second
The DAEvent objects.
Return Values

Returns a DAEvent object. When the event occurs, it produces a DAPair. The first member is the event data returned by the first event. The second member is the event data returned by the second event.

KeyDown

DAStatics Class

Returns a DAEvent when a specific key is pressed. This is a state-transition event.

lib.KeyDown(
keyCode
)

Parameters
keyCode
This is a number (a long). See the table below for information about key codes.
Return Values

Returns the DAEvent object. This event produces no data.

Remarks

The following table lists the hexadecimal values for all the special keycodes. The pattern for each key is 0x10000 plus the win32 scan code.
Key | KeyCode
PGUP | 10021
PGDN | 10022
END | 10023
HOME | 10024
LEFT | 10025
UP | 10026
RIGHT | 10027
DOWN | 10028
INSERT | 1002D
DELETE | 1002E
NUMPAD0 | 10060
NUMPAD1 | 10061
NUMPAD2 | 10062
NUMPAD3 | 10063
NUMPAD4 | 10064
NUMPAD5 | 10065
NUMPAD6 | 10066
NUMPAD7 | 10067
NUMPAD8 | 10068
NUMPAD9 | 10069
MULTIPLY | 1006A
ADD | 1006B
SEPARATOR | 1006C
SUBTRACT | 1006D
DECIMAL | 1006E
DIVIDE | 1006F
F1 | 10070
F2 | 10071
F3 | 10072
F4 | 10073
F5 | 10074
F6 | 10075
F7 | 10076
F8 | 10077
F9 | 10078
F10 | 10079
F11 | 1007A
F12 | 1007B
F13 | 1007C
F14 | 1007D
F15 | 1007E
F16 | 1007F
F17 | 10080
F18 | 10081
F19 | 10082
F20 | 10083
F21 | 10084
F22 | 10085
F23 | 10086
F24 | 10087

KeyUp

DAStatics Class

Returns a DAEvent when a specific key is released. This is a state-transition event.

lib.KeyUp(
keyCode
)

Parameters
keyCode
This is a number (a long). For a list of special keycodes, see KeyDown.
Return Values

Returns the DAEvent object. This event produces no data.

NotEvent

DAStatics Class

Creates an event that occurs when the given event does not occur. This is useful for creating combined events that occur only if the given event is not also occurring. For example, an event that occurs when the left mouse button is down and the right button is not down.

lib.NotEvent(
ev
)

Parameters
ev
The DAEvent object.
Return Values

Returns the DAEvent object. This event produces no data.

OrEvent

DAStatics Class

Creates an event that occurs when either one of the given events occur. The event time for the new event is when either the first or second given event has occurred.

lib.OrEvent(
first,
second
)

Parameters
first and second
The DAEvent objects.
Return Values

Returns a DAEvent object. Its data is the event data of either the first or second event.

Remarks

If both events occur at the same time, the first will be chosen to fire. For example, if you attach a notifier to first and second and the events occur at the same time, only the notifier of first will get called.

Predicate

DAStatics Class

Creates an event that occurs when the value of the given DABoolean behavior changes from FALSE to TRUE. Note that, because of implementation dependencies and the potential for aliasing, the system cannot always detect when a DABoolean behavior becomes TRUE.

lib.Predicate(
bool
)

Parameters
bool
The DABoolean object.
Return Values

Returns the DAEvent. This event produces no data.

ThenEvent

DAStatics Class

Creates an event if e2 occurs after e1. The event time of the new event is the time of the second event.

lib.ThenEvent(
e1,
e2
)

Parameters
e1
The first event, that, when it occurs, triggers the second event.
e2
The second event, caused by the occurrence of the first event.
Return Values

Returns the DAEvent object. Its event data is the time the second event fired and a DAPair containing the event data for both events.

TimerAnim

DAStatics Class

Creates an event that occurs when the specified time has elapsed.

lib.TimerAnim(
timeout
)

Parameters
timeout
The DANumber object that controls when the timer fires. This must be an animated number
Return Values

Returns the DAEvent object. This event produces no data.

Timer

DAStatics Class

The same as TimerAnim except that timeout is a non-animated number (a double).

lib.Timer(
timeout
)


DirectAnimation Animated Header --DAStatic Properties Relevant to DAEvent Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAEvent Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAEvent Objects
  * Next Topic: DAStatic Properties Relevant to DAEndStyle Objects

DAStatic Properties Relevant to DAEvent Objects

Always

DAStatics Class

A read-only property with a DAEvent that occurs at all times. It produces no data.

lib.Always

LeftButtonDown

DAStatics Class

A read-only property with a DAEvent value that occurs when the left mouse button is pressed. This is a state-transition event. It produces no data.

lib.LeftButtonDown

LeftButtonUp

DAStatics Class

A read-only property with a DAEvent value that occurs when the left mouse button is released. This is a state-transition event. It produces no data.

lib.LeftButtonUp

Never

DAStatics Class

A read-only property with a DAEvent value that never occurs. It produces no data.

lib.Never

RightButtonDown

DAStatics Class

A read-only property with a DAEvent value that occurs when the right mouse button is pressed. This is a state-transition event. It produces no data.

lib.RightButtonDown

RightButtonUp

DAStatics Class

A read-only property with a DAEvent value that occurs when the right mouse button is relased. This is a state-transition event. It produces no data.

lib.RightButtonUp


DirectAnimation Animated Header --DAStatic Properties Relevant to DAEndStyle Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAEndStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAEvent Objects
  * Next Topic: DAStatic Functions Relevant to DAFontStyle Objects

DAStatic Properties Relevant to DAEndStyle Objects

EndStyleFlat

DAStatics Class

A read-only property with a DAEndStyle value that draws the end of a line as a line segment, perpendicular to the final direction of the line and through the last point of the line.

lib.EndStyleFlat

EndStyleRound

DAStatics Class

A read-only property with a DAEndStyle value that draws the end of a line as a circle, having a diameter equal to the width of the line and its center at the last point of the line.

lib.EndStyleRound

EndStyleSquare

DAStatics Class

A read-only property with a DAEndStyle value that draws the end of a line as a square, having a height and width equal to the width of the line and its center at the last point of the line.

lib.EndStyleSquare


DirectAnimation Animated Header --DAStatic Functions Relevant to DAFontStyle Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAFontStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAEndStyle Objects
  * Next Topic: DAStatic Properties Relevant to DAFontStyle Objects

DAStatic Functions Relevant to DAFontStyle Objects

FontAnim

DAStatics Class

Specifies the face, size in points, and color of a DAFontStyle object. Because these parameters are all animated, they can vary over time.

lib.FontAnim(
face,
points,
color
)

Parameters
face
The DAString object specifying the font face.
points
The DANumber object specifying the font size, in points. This must be an animated number.
color
The DAColor object specifying the font color.
Return Values

Returns the DAFontStyle object.

Font

DAStatics Class

Same as FontAnim except that points is a non-animated number (a double).

lib.Font(
face,
points,
color>


DirectAnimation Animated Header --DAStatic Properties Relevant to DAFontStyle Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAFontStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAFontStyle Objects
  * Next Topic: DAStatic Functions Relevant to DAGeometry Objects

DAStatic Properties Relevant to DAFontStyle Objects

DefaultFont

DAStatics Class

A read-only property with a DAFontStyle value that is a Times-Roman, black, 12pt font that is neither bold nor italicized.

lib.DefaultFont


DirectAnimation Animated Header --DAStatic Functions Relevant to DAGeometry Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAGeometry Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAFontStyle Objects
  * Next Topic: DAStatic Properties Relevant to DAGeometry Objects

DAStatic Functions Relevant to DAGeometry Objects

ImportGeometry

DAStatics Class

Creates a DAGeometry by synchronously importing the given .X file. Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See ImportGeometryAsync for a description of the asynchronous import function.

lib.ImportGeometry(
url
)

Parameters
url
The pathname (a string) of the file to be downloaded.
Return Values

Returns the DAGeometry object.

ImportGeometryAsync

DAStatics Class

Asynchronously imports the given .X file. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import function, see ImportGeometry.

lib.ImportGeometryAsync(
url,
geoStandIn
)

Parameters
url
The pathname (a string) of the geometry to be downloaded.
geoStandIn
The geometry to use while the contents at url are still being downloaded. This argument cannot be null.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • CompletionEvent, which is the event that triggers once the download is complete.
  • Geometry, which is the imported DAGeometry object.
  • Progress, which is the progress of the download.
  • Size, which is the size of the download.

SoundSource

DAStatics Class

Creates a DAGeometry object that contains sound. The bounding box is the empty bounding box, where the maximum coordinate is less than the minimum coordinate.

lib.SoundSource(
sound
)

Parameters
sound
The DASound object that contained within the geometry.
Return Values

Returns the DAGeometry object.

SpotLightAnim

DAStatics Class

Creates a spotlight geometry. A spotlight is a positioned, directed light source initially located at the origin and directed along the negative z-axis. Examples of real-world spotlights include desklamps, headlights, and flashlights. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent.

The fullcone parameter specifies the half-angle of the region that will receive the full intensity of the spotlight. This parameter can have values from 0.00 to pi.

The cutoff parameter specifies the half-angle of the region past which surfaces will receive no illumination. This parameter can have values from the value of fullcone to pi.

lib.SpotLightAnim(
fullcone,
cutoff
)

Parameters
fullcone
The DANumber object specifying the angle in radians from the main spotlight axis for which surfaces will receive full illumination from the light. This must be an animated number.
cutoff
The DANumber object specifying the angle in radians from the main spotlight axis past which surfaces will receive no illumination from the light. This must be an animated number.
Return Values

Returns the DAGeometry object.

Remarks

Surfaces receive illumination from the spotlight in the following manner:

  • If the surface point is within fullcone radians of the main spotlight axis, the spotlight acts as a pointlight source (including distance attenuation effects).
  • If the surface point is greater than fullcone radians, but is within cutoff radians of the main spotlight axis, the surface receives illumination that is attenuated by the angular displacement.
  • If the surface point is greater than cutoff radians from the main spotlight axis, it receives no illumination.

These rules are illustrated in the following diagram:

Remarks

The following diagram shows how the intensity of the spotlight changes in relationship to the angle:

SpotLight

DAStatics Class

Same as SpotLightAnim except that cutoff is a non-animated number (a double). Note that fullcone is still an animated number (a DANumber).

lib.SpotLight(
fullcone,
cutoff
)

UnionGeometry

DAStatics Class

Creates a DAGeometry object by combining the given geometries. The new geometry contains all elements of the original geometries. The bounding box of a set of unioned geometries is simply the union of the bounding boxes of each of the geometries.

lib.UnionGeometry(
g1,
g2
)

Parameters
g1 and g2
The DAGeometry objects.
Return Values

Returns the DAGeometry object.

UnionGeometryArray

DAStatics Class

Creates a geometry behavior by combining the geometries in the array. The new geometry contains all elements of the original geometries. The bounding box of a set of unioned geometries is simply the union of the bounding boxes of each of the geometries.

lib.UnionGeometryArray(
geoArray
)

Parameters
geoArray
The array of DAGeometry objects.
Return Values

Returns the DAGeometry object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DAGeometry Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAGeometry Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAGeometry Objects
  * Next Topic: DAStatic Functions Relevant to DAImage Objects

DAStatic Properties Relevant to DAGeometry Objects

AmbientLight

DAStatics Class

A read-only property with a DAGeometry value in which the light source is ambient (room) light. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Ambient light is light that, instead of coming directly from a light source, bounces from surface to surface and provides overall scene-lighting. For example, if you are in a room lit by a lamp, everything not directly lit by the lamp is receiving ambient light. It leaves the lamp, bounces off the walls, the floors, the ceiling, and all around, until it reaches almost the entire room. Using too much ambient light can make a scene look washed out, while too little will yield shadowed areas that look unnaturally black. Unlike directional lights and pointlights, transformations have no effect on ambient lights.

lib.AmbientLight

DirectionalLight

DAStatics Class

A read-only property with a DAGeometry value in which the light source is positioned pointing down the negative z axis. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Directional light specifies a light such that the light direction is the same everywhere. This is in contrast to a positional light such as a point or spot light, where the direction to the light source changes depending on where the surface is. Directional lights are useful for simulating the sun because, from our perspective on earth, the sun's rays appear to travel in the same direction. Directional lights are also cheaper to compute than positional lights, though this difference may be negligible and should not be assumed. Transformations do have an effect on directional lights.

lib.DirectionalLight

EmptyGeometry

DAStatics Class

A read-only property with a DAGeometry value in which all points are invisible (transparent) and undetectable. The bounding box is the empty bounding box, where the maximum coordinate is less than the minimum coordinate.

lib.EmptyGeometry

PointLight

DAStatics Class

A read-only property with a DAGeometry value in which the light source is positioned at the origin and radiates light in all directions. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Pointlights simulate most real-world lights such as bare light bulbs, wall-mounted light fixtures, and ceiling lights. They shine in all directions, radiating outward from the center. Transformations do have an effect on pointlights.

lib.PointLight


DirectAnimation Animated Header --DAStatic Functions Relevant to DAImage Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAImage Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAGeometry Objects
  * Next Topic: DAStatic Properties Relevant to DAImage Objects

DAStatic Functions Relevant to DAImage Objects

GradientHorizontalAnim

DAStatics Class

Creates a DAImage object that smoothly interpolates between the start and stop colors. Colors start on the left and go toward the right, based on the power specified by power.

The extent of the generated image is [-0.5,-0.5] to [0.5,0.5]. These dimensions are always in meters, even if the PixelLibrary is selected. To convert from pixels to meters, use the Pixel conversion factor.

lib.GradientHorizontalAnim(
start,
stop,
power
)

Parameters
start
The DAColor object representing the first color of the gradient fill.
stop
The DAColor object representing the final color of the gradient fill.
power
The DANumber object that is an exponent controlling how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity]. This must be an animated number.
Return Values

Returns the DAImage object.

GradientHorizontal

DAStatics Class

Same as GradientHorizontalAnim except that power is a non-animated number.

lib.GradientHorizontal(
start,
stop,
power
)

GradientPolygon

DAStatics Class

Creates a polygon from an array of points and an array of colors. The polygon has a smooth interpolation between the colors at the vertices. This interpolation is in RGB space. The image is transparent and unpickable outside the polygon. The polygon must be convex and fanned, with at least 3 vertices. The tessellation into triangles occurs by fanning around the first vertex. If, for example, the first triangle is from vertices [0, 1, 2], the second is from [0, 2, 3], and so on. The tessellation determines how the color interpolation is done. The bounding box is the box surrounding the points of the polygon.

lib.GradientPolygon(
pts,
colors
)

Parameters
pts
The array (variant) of DAPoint2 points that determine the polygon's vertices.
colors
The array (variant) of DAColor colors corresponding to the vertices.
Return Values

Returns the DAImage object.

GradientSquare

DAStatics Class

Creates a DAImage object with a square color wash. The image is a unit-sized square, centered at the origin, reaching from [-0.5, -0.5] to [0.5, 0.5]. The image contains the specified colors in the specified corners. The gradient fills are determined by bilinearly interpolating between these specified colors. (This means that, rather than being simply a four-cornered polygon, it is a polygon with four corners plus a point in the middle that is the average of the four colors.) The image is transparent and unpickable outside of this region. The interpolation is in RGB space. The bounding box is a box from (-0.5, -0.5) to (0.5, 0.5).

lib.GradientSquare(
lowerLeft,
upperLeft,
upperRight,
lowerRight
)

Parameters
lowerLeft
The DAColor color in the lower-left hand corner of square.
upperLeft
The DAColor color in the upper-left hand corner of the square.
upperRight
The DAColor color in the upper-right hand corner of the square.
lowerRight
The DAColor color in the lower-right hand corner of the square.
Return Values

Returns the DAImage object.

HatchBackwardDiagonalAnim

DAStatics Class

Creates backward diagonal (lines that slant from right to left) hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

lib.HatchBackwardDiagonalAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchBackwardDiagonal

DAStatics Class

Same as HatchBackwardDiagonal except that size is a non-animated number.

lib.HatchBackwardDiagonal(
color,
size
)

HatchCrossAnim

DAStatics Class

Creates cross-hatched markings. This function can be thought of as a combination of the HatchVerticalAnim and the HatchHorizontalAnim functions. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

lib.HatchCrossAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchCross

DAStatics Class

Same as HatchCrossAnim except that size is a non-animated number (a double).

lib.HatchCross(
color,
size
)

HatchDiagonalCrossAnim

DAStatics Class

Creates diagonally criss-crossed hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

lib.HatchDiagonalCrossAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchDiagonalCross

DAStatics Class

Same as HatchDiagonalCrossAnim except that size is a non-animated number (a double).

lib.HatchDiagonalCross(
color,
size
)

HatchForwardDiagonalAnim

DAStatics Class

Creates forward diagonal (lines that slant from left to right) hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines.

lib.HatchForwardDiagonalAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchForwardDiagonal

DAStatics Class

Same as HatchForwardDiagonalAnim except that size is a non-animated number (a double).

lib.HatchForwardDiagonal(
color,
size
)

HatchHorizontalAnim

DAStatics Class

Creates horizontal hatch lines. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

lib.HatchHorizontalAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchHorizontal

DAStatics Class

Same as HatchHorizontalAnim except that size is a non-animated number (a double).

lib.HatchHorizontal(
color,
size
)

HatchVerticalAnim

DAStatics Class

Creates vertical hatch lines. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

lib.HatchVerticalAnim(
color,
size
)

Parameters
color
The DAColor object representing the line color.
size
The DANumber object representing the size of the hatch box. This must be an animated number.
Return Values

Returns the DAImage object.

HatchVertical

DAStatics Class

Same as HatchVerticalAnim except that size is a non-animated number (a double).

lib.HatchVertical(
color,
size
)

ImportImage

DAStatics Class

Creates a DAImage by synchronously importing the given bitmap. The pixels of the bitmap are mapped to points in the image such that the center of the bitmap is placed at (0,0). The extent of the points affected depends on the width and height of the bitmap in pixels and the resolution of the bitmap in pixels per meter. The bounding box of an imported image is calculated as follows:

If the pixel dimensions are WxH, and given that:

halfWidthMeters = lib.mul(lib.DANumber(W/2), lib.Pixel)
halfHeightMeters = lib.mul(lib.DANumber(H/2), lib.Pixel)

then the bounding box will be (-halfWidthMeters, -halfHeightMeters) to (halfWidthMeters, halfHeightMeters) with the resultant image centered at the origin.

Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See below for a description of the asynchronous function, ImportImageAsync.

lib.ImportImage(
url
)

Parameters
url
The pathname of the image to be downloaded.
Return Values

Returns the DAImage object.

Remarks

The file formats that can be imported are .PNG, .JPG, .BMP, and .GIF.

See Also

ImportImageColorKey

ImportImageAsync

DAStatics Class

Asynchronously imports the given bitmap. The pixels of the bitmap are mapped to points in the image such that the center of the bitmap is placed at (0,0). The extent of the points affected depends on the width and height of the bitmap in pixels and the resolution of the bitmap in pixels per meter. The bounding box of an imported image is calculated as follows:

If the pixel dimensions are WxH, and given that:

halfWidthMeters = lib.mul(lib.DANumber(W/2), lib.Pixel)
halfHeightMeters = lib.mul(lib.DANumber(H/2), lib.Pixel)

then the bounding box will be (-halfWidthMeters, -halfHeightMeters) to (halfWidthMeters, halfHeightMeters) with the resultant image centered at the origin.

Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import function, see ImportImage.

lib.ImportImageAsync(
url,
imgStandIn
)

Parameters
url
The pathname (a string) of the image to be downloaded.
imgStandIn
The DAImage object to use while the contents at url are still being downloaded. This argument cannot be null, however, the image can be empty.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • CompletionEvent,which is the event that fires once the download is complete.
  • Image, which is the imported image.
  • Progress, which is the percentage of the download that has completed.
  • Size, which is the size of the imported image, in bytes.
See Also

ImportImageAsyncColorKey

ImportImageAsyncColorKey

DAStatics Class

Allows a particular color in the asynchronously imported image, specified by an RGB value, to be treated as transparent.

lib.ImportImageAsyncColorKey(
url,
imgStandIn,
red,
green,
blue
)

Parameters
url
The pathname (a string) of the image to be downloaded.
imgStandIn
The DAImage object to use while the contents at url are still being downloaded. This argument cannot be null, however, the image can be empty.
red
The red component, expressed as a value (a byte) ranging from 0 to 255.
green
The green component, expressed as a value (a byte) ranging from 0 to 255.
blue
The blue component, expressed as a value (a byte) ranging from 0 to 255.
Return Values

Returns the DAImportationResult object.

See Also

ImportImageAsync

ImportImageColorKey

DAStatics Class

Allows a particular color in the synchronously imported image, specified by an RGB value, to be treated as transparent.

lib.ImportImageColorKey(
url,
red,
green,
blue
)

Parameters
url
The pathname (a string) of the image to be downloaded.
red
The red component, expressed as a value (a byte) ranging from 0 to 255.
green
The green component, expressed as a value (a byte) ranging from 0 to 255.
blue
The blue component, expressed as a value (a byte) ranging from 0 to 255.
Return Values

Returns the DAImage object.

See Also

ImportImage

ImportMovie

DAStatics Class

Downloads a movie synchronously. Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See ImportMovieAsync for a description of the asynchronous import function.

The image portion of a movie has the same bounding box and placement as a static image such as a GIF or PNG. For more information, see ImportImage.

lib.ImportMovie(
url
)

Parameters
url
The pathname (a string) of the movie to be downloaded.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • Duration, which is the length of the movie, in seconds
  • Image, which is the imported image component of the movie.
  • Sound, which is the imported sound component of the movie.

ImportMovieAsync

DAStatics Class

Imports a movie asynchronously. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import function, see ImportMovie.

The image portion of a movie has the same bounding box and placement as a static image such as a GIF or PNG. For more information, see ImportImage.

lib.ImportMovieAsync(
url,
imgStandIn,
sndStandIn
)

Parameters
url
The pathname (a string) of the movie to download.
imgStandIn
The DAImage to use while the movie is still being downloaded. This parameter cannot be null, however, the image can be empty.
sndStandIn
The DASound to use while the movie is still being downloaded. This parameter cannot be null, however, the sound can be silence.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • CompletionEvent, which is the event that triggers once the download is complete.
  • Duration, which is the length of the movie, in seconds
  • Image, which is the imported image component of the movie.
  • Progress, which is the percentage of the download that has completed.
  • Size, which is the size of the imported image, in bytes.
  • Sound, which is the imported sound component of the movie.

Overlay

DAStatics Class

Creates a DAImage object by laying the image i1 over the image behavior i2. The new image consists of all fully opaque points of i1, all points of i2 that are under fully transparent points in i1, and all partially opaque points of i1 modified such that the new point is a combination of the i1 point and the i2 point under it. The bounding box of a set of overlaid images is simply the union of the bounding boxes of the images themselves.

lib.Overlay(
i1,
i2
)

Parameters
i1 and i2
The DAImage objects.
Return Values

Returns the DAImage object.

OverlayArray

DAStatics Class

Creates a DAImage object by layering the DAImage objects. The bounding box of a set of overlaid images is simply the union of the bounding boxes of the images themselves.

lib.OverlayArray(
im
)

Parameters
im
An array (variant) of DAImage objects.
Return Values

Returns the DAImage object.

RadialGradientPolygonAnim

DAStatics Class

Creates a DAImage object that is a regular polygon with a radial fill. The image contains the specified colors at the origin and the exterior points, respectively. The gradient fill is determined by the power argument and occurs in RGB space. Outside of the filled-in region, the image is transparent and unpickable. The bounding box is the box surrounding the points of the polygon.

lib.RadialGradientPolygonAnim(
inner,
outer,
points,
power
)

Parameters
inner
The DAColor object representing the color at the origin of the polygon.
outer
The DAColor object representing the color at the vertices.
points
The DAPoint2 object representing the array of points that determine the polygon's vertices.
power
The DANumber object that is an exponent controlling how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity]. This must be an animated number.
Return Values

Returns the DAImage object.

RadialGradientPolygon

DAStatics Class

Same as RadialGradientPolygonAnim except that power must be an animated number.

lib.RadialGradientPolygon(
inner,
outer,
points,
power
)

RadialGradientRegularPolyAnim

DAStatics Class

Creates a DAImage object that is a regular, gradient polygon with the specified number of sides (there must be at least 3) and a radial fill. It has a unit width and height, centered at the origin, with an extent from (-0.5, -0.5) to (0.5, 0.5). (These dimensions are always in meters, even if the PixelLibrary is selected. To convert from pixels to meters, use the Pixel conversion factor.) The image contains the specified colors at the origin and the exterior points, respectively. The gradient fill is determined by the power argument and occurs in RGB space. Outside of the filled-in region, the image is transparent and unpickable. The bounding box is the box surrounding the points of the polygon.

Creates a DAImage object that smoothly interpolates between the start and stop colors. Colors start on the left and go toward the right, based on the power specified by power.

lib.RadialGradientRegularPolyAnim(
inner,
outer,
edges,
power
)

Parameters
inner
The DAColor object representing the color at the origin of the polygon.
outer
The DAColor object representing the color at the vertices.
edges
The DANumber object representing the number of edges the polygon has. This parameter can also be of type double.
power
The DANumber object that is an exponent controlling how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity]. This must be an animated number.
Return Values

Returns the DAImage object.

RadialGradientRegularPoly

DAStatics Class

Same as RadialGradientRegularPolyAnim except that power is a non-animated number (a double).

lib.RadialGradientRegularPoly(
inner,
outer,
edges,
power
)

RadialGradientSquareAnim

DAStatics Class

Creates a DAImage object with a square radial fill. The image is a unit-sized square, centered at the origin, reaching from [-0.5, -0.5] to [0.5, 0.5]. (These dimensions are always in meters, even if the PixelLibrary is selected. To convert from pixels to meters, use the Pixel conversion factor.) The image contains the specified colors in the center and at the corners, respectively. The gradient fill is determined by the power argument. The interpolation occurs in RGB space. Outside of the fill, the image is transparent and unpickable. The bounding box is a box from [-0.5, -0.5] to [0.5, 0.5].

Creates a DAImage object that smoothly interpolates between the start and stop colors. Colors start on the left and go toward the right, based on the power specified by power.

lib.RadialGradientSquareAnim(
inner,
outer,
power
)

Parameters
inner
The DAColor at the center of the image.
outer
The DAColor at the corners of the image.
power
The DANumber object that is an exponent controlling how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity]. This must be an animated number.
Return Values

Returns the DAImage object.

RadialGradientSquare

DAStatics Class

Same as RadialGradientSquareAnim except that power is a non-animated number (a double).

lib.RadialGradientSquare(
inner,
outer,
power
)

SolidColorImage

DAStatics Class

Creates a DAImage object and applies the given color behavior to all points in the image. The bounding box of a solid-color image is the infinite bounding box.

lib.SolidColorImage(
col
)

Parameters
col
The DAColor object used to color the image.
Return Values

Returns the DAImage object.

StringImageAnim

DAStatics Class

Constructs a DAImage object from a DAString object and a DAFontStyle object. Because both parameters are (potentially) animated, they can vary over time.

lib.StringImageAnim(
string,
font
)

Parameters
string
The DAString object specifying the (potentially) animated text.
font
The DAFontStyle object specifying the font style (this can include the face, the size, the color, and the attributes).
Return Values

Returns the DAImage object.

StringImage

DAStatics Class

Same as StringImageAnim except that string is a string.

lib.StringImage(
string,
font
)


DirectAnimation Animated Header --DAStatic Properties Relevant to DAImage Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAImage Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAImage Objects
  * Next Topic: DAStatic Properties Relevant to DAJoinStyle Objects

DAStatic Properties Relevant to DAImage Objects

DetectableEmptyImage

DAStatics Class

A read-only property with a DAImage value in which all points are transparent but detectable. This image is useful for blocking mouse input from underlying image, allowing that input to be redirected. The bounding box is of infinite extent.

lib.DetectableEmptyImage

EmptyImage

DAStatics Class

A read-only property with a DAImage value in which all points are transparent and undetectable. This has a empty bounding box, which means that its maximum point is less than its minimum point. This allows operations such as union and intersection to produce the correct results.

lib.EmptyImage


DirectAnimation Animated Header --DAStatic Properties Relevant to DAJoinStyle Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAJoinStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAImage Objects
  * Next Topic: DAStatic Properties Relevant to DALineStyle Objects

DAStatic Properties Relevant to DAJoinStyle Objects

JoinStyleBevel

DAStatics Class

A read-only property with a DAJoinStyle object value that joins two line segments by drawing a straight line between the outside corners of the segments and filling the resulting enclosed area.

lib.JoinStyleBevel

JoinStyleMiter

DAStatics Class

A DAJoinStyle value that joins two line segments by extending the outside edges of the segments until they intersect and filling the resulting enclosed area. The miter length is defined as the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls on the outside of the join.

lib.JoinStyleMiter

JoinStyleRound

DAStatics Class

A DAJoinStyle value that joins two line segments by drawing an arc between the outside corners of the segments and filling the resulting enclosed area. The center of the arc is at the common endpoint, the diameter is the width of the line.

lib.JoinStyleRound


DirectAnimation Animated Header --DAStatic Properties Relevant to DALineStyle Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DALineStyle Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAJoinStyle Objects
  * Next Topic: DAStatic Functions Relevant to DAMatte Objects

DAStatic Properties Relevant to DALineStyle Objects

DefaultLineStyle

DAStatics Class

A read-only property with a DALineStyle value whose style is Detail.

lib.DefaultLineStyle

EmptyLineStyle

DAStatics Class

A read-only property with a DALineStyle value that is transparent.

lib.EmptyLineStyle


DirectAnimation Animated Header --DAStatic Functions Relevant to DAMatte Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAMatte Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DALineStyle Objects
  * Next Topic: DAStatic Properties Relevant to DAMatte Objects

DAStatic Functions Relevant to DAMatte Objects

DifferenceMatte

DAStatics Class

Creates a DAMatte object that is the difference between the given mattes. The difference consists of only those elements of the path and/or text in m1 that are not also in m2.

lib.DifferenceMatte(
m1,
m2
)

Parameters
m1 and m2
The DAMatte objects.
Return Values

Returns the DAMatte object.

See Also

IntersectMatte, UnionMatte

FillMatte

DAStatics Class

Creates a DAMatte object consisting of the given path, path. Clipping an image with this matte preserves that portion of the image that is inside the path.

lib.FillMatte(
path
)

Parameters
path
The DAPath2 object. If the path is not closed, the start and end points are implicitly connected to close the path.
Return Values

Returns the DAMatte object.

See Also

TextMatte

IntersectMatte

DAStatics Class

Creates a DAMatte object that is the intersection of the given mattes. The intersection consists of only those elements of the paths and/or text of the original mattes that are the same.

lib.IntersectMatte(
m1,
m2
)

Parameters
m1 and m2
The DAMatte objects.
Return Values

Returns the DAMatte object.

See Also

UnionMatte, DifferenceMatte

TextMatte

DAStatics Class

Creates a DAMatte object consisting of the given DAString object, text, and with an appearance specified by the DAFontStyle object, fs. Clipping an image with this matte preserves that portion of the image that is inside the text.

lib.TextMatte(
text,
fs
)

Parameters
text
The DAString object representing the text.
fs
The DAFontStyle object representing the font style.
Return Values

Returns the DAMatte object.

See Also

FillMatte

UnionMatte

DAStatics Class

Creates a DAMatte object that is the union of the given mattes. The union consists of all elements of the paths and/or text in the original mattes.

lib.UnionMatte(
m1,
m2
)

Parameters
m1 and m2
The DAMatte objects.
Return Values

Returns the DAMatte object.

See Also

IntersectMatte, DifferenceMatte


DirectAnimation Animated Header --DAStatic Properties Relevant to DAMatte Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAMatte Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAMatte Objects
  * Next Topic: DAStatic Properties Relevant to DAMicrophone Objects

DAStatic Properties Relevant to DAMatte Objects

ClearMatte

DAStatics Class

A read-only property with a DAMatte value that, when applied to an image, preserves the entire image (that is, it clips nothing).

lib.ClearMatte

OpaqueMatte

DAStatics Class

A read-only property with a DAMatte value that, when applied to an image, clips the entire image (that is, preserves no part of the image).

lib.OpaqueMatte


DirectAnimation Animated Header --DAStatic Properties Relevant to DAMicrophone Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAMicrophone Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAMatte Objects
  * Next Topic: Miscellaneous DAStatic Functions

DAStatic Properties Relevant to DAMicrophone Objects

DefaultMicrophone

DAStatics Class

A read-only property with a DAMicrophone value that is positioned at the origin, listening along the negative z axis with an upward orientation along the positive y axis.

lib.DefaultMicrophone


Miscellaneous DAStatic Functions

AppTriggeredEvent()

DAStatics Class

Creates the event. The event can be used in the DAStatics subroutines Until and UntilEx to create reactive behaviors based on external events.

staticsObj.AppTriggeredEvent( )

Return Values

Returns the DAEvent object.

TriggerEvent

DAStatics Class

Triggers the event and passes the given data to the event handler.

lib.TriggerEvent(
event,
data
)

Parameters
event
The DAEvent that is triggered.
data
The DABehavior object that is the data.
Remarks

The triggered event occurs as soon as possible.


Miscellaneous DAStatic Properties

AreBlockingImportsComplete

DAStatics Class

A property indicating whether all synchronous imports have been completely downloaded.

lib.AreBlockingImportsComplete

ClientSite

DAStatics Class

A property that, when set, allows imports from a relative file naem by establishing an absolute base. It takes an IOleClientSite. For more information, consult an OLE reference.

lib.ClientSite

Cm

DAStatics Class

A read-only property that is the centimeter unit (a double).

lib.Cm

Foot

DAStatics Class

A read-only property that is the foot unit (a double).

lib.Foot

Inch

DAStatics Class

A read-only property that is the inch unit (a double).

lib.Inch

Meter

DAStatics Class

A read-only property that is the meter unit (a double).

lib.Meter

Mm

DAStatics Class

A read-only property that is the millimeter unit (a double).

lib.Mm

Pixel

DAStatics Class

A read-only property that is the pixel unit (a DANumber).

lib.Pixel

PixelConstructionMode

DAStatics Class

A property with a boolean value that, if TRUE, sets the unit of measure to pixels and, if FALSE, sets the unit of measure to meters (this is the default). Ordinarily, instead of using this property, developers use either the MeterLibrary or the PixelLibrary property, both of which return a DAStatics object. In the case of PixelLibrary, the statics object returned is automatically set to PixelConstructionMode while, in the case of the MeterLibrary it isn't.

lib.PixelConstructionMode

Site

DAStatics Class

A property that, when set, allows control over error messages.

lib.Site

VersionString

DAStatics Class

A read-only property (a string) that is the version string in the form MM.NN.BBBB, where MM is the major version, NN is the minor version, and BBBB is the build number.

lib.VersionString


DirectAnimation Animated Header --DAStatic Functions Relevant to DAMontage Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAMontage Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Miscellaneous DAStatic Properties
  * Next Topic: DAStatic Properties Relevant to DAMontage Objects

DAStatic Functions Relevant to DAMontage Objects

ImageMontageAnim

DAStatics Class

Creates a DAMontage object consisting of a single DAImage object at the given Z-value.

lib.ImageMontageAnim(
image,
Z-value
)

Parameters
image
The DAImage object.
Z-value
The DANumber object, specifying the Z-value. This must be an animated number.
Return Values

Returns the DAMontage object.

ImageMontage

DAStatics Class

Same as ImageMontageAnim except that the arguments are non-animated numbers.

lib.ImageMontage(
image,
Z-value
)

UnionMontage

DAStatics Class

Creates a DAMontage object by combining the given arguments.

lib.UnionMontage(
m1,
m2
)

Parameters
m1 and m2
The DAMontage objects to be combined.
Return Values

Returns the DAMontage object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DAMontage Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAMontage Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAMontage Objects
  * Next Topic: DAStatic Functions Relevant to DANumber Objects

DAStatic Properties Relevant to DAMontage Objects

EmptyMontage

DAStatics Class

A read-only property with a DAMontage value that contains no images.

lib.EmptyMontage


DirectAnimation Animated Header --DAStatic Functions Relevant to DANumber Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DANumber Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAMontage Objects
  * Next Topic: DAStatic Properties Relevant to DANumber Objects

DAStatic Functions Relevant to DANumber Objects

Abs

DAStatics Class

Creates a DANumber that represents the absolute value of the given animated number. The value is equal to the absolute value (the non-negative equivalent) of the value of a.

lib.Abs(
a
)

Parameters
a
The DANumber object to apply the operation to.
Return Values

Returns the DANumber object.

Acos

DAStatics Class

Creates a DANumber object that represents the arccosine (inverse cosine) of the argument.

lib.Acos(
a
)

Parameters
a
The DANumber object. The value is assumed to be a cosine value.
Return Values

Returns the DANumber object.

See Also

Asin

Add

DAStatics Class

Creates a DANumber object representing the sum of the given arguments. The value is the value of a added to the value of b (a + b).

lib.Add(
a,
b
)

Parameters
a and b
The DANumber objects to add.
Return Values

Returns the DANumberobject.

Asin

DAStatics Class

Creates a DANumberobject that represents the arcsine (inverse sine) of the given argument.

lib.Asin(
a
)

Parameters
a
The DANumber object. The value is assumed to be a sine value.
Return Values

Returns the DANumber object.

See Also

Acos

Atan

DAStatics Class

Creates a DANumber object that represents the arctangent (inverse tangent) of the given argument.

lib.Atan(
a
)

Parameters
a
The DANumber object.
Return Values

Returns the DANumber object.

See Also

Acos, Asin, Atan2

Atan2

DAStatics Class

Creates the DANumber object that represents the arctangent (inverse tangent) of the quotient of the given arguments. The value is the inverse tangent of the value of a divided by the value of b.

lib.Atan2(
a,
b
)

Parameters
a and b
The DANumber objects to divide.
Return Values

Returns the DANumber object.

See Also

Acos, Asin

Ceiling

DAStatics Class

Creates the DANumber object that represents the ceiling value, the smallest integer value that is greater than or equal to the value of the given argument.

lib.Ceiling(
a
)

Parameters
a
The DANumber object to find the ceiling for.
Return Values

Returns the DANumber object.

Cos

DAStatics Class

Creates a the DANumber object that represents the cosine of the given argument.

lib.Cos(
a
)

Parameters
a
The DANumber object. The value is assumed to be in radians.
Return Values

Returns the DANumber object.

See Also

Sin

DANumber

DAStatics Class

Converts a number (a double) to a DANumber. The only time DANumber is used is when converting numbers to a corresponding DANumber objects.

lib.DANumber(
a
)

Parameters
a
The number (double) to be converted.
Return Values

Returns the DANumber object.

Derivative

DAStatics Class

Creates a DANumber object that is the instantaneous derivative (rate of change) of the given argument. For example, a constant number yields a constant derivative of 0 and a value equal to "time" yields a constant derivative of 1.

lib.Derivative(
a
)

Parameters
a
The DANumber object for which to calculate the derivative.
Return Values

Returns the DANumber object.

Div

DAStatics Class

Creates DANumber object representing the quotient of the given arguments. The value is the value of a divided by the value of b (a/b).

lib.Div(
a,
b
)

Parameters
a and b
The DANumber objects to divide.
Return Values

Returns DANumber the object.

EQ

DAStatics Class

Creates DABoolean object that represents the relation a = b. The value is TRUE when the value of a is equal to the value of b, otherwise, it is FALSE.

lib.EQ(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

Exp

DAStatics Class

Creates a DANumber object that represents the exponential of the given argument. The value is the base of natural logarithms, e, raised to the power of the value of a.

lib.Exp(
a
)

Parameters
a
The DANumber object to apply as an exponent of e.
Return Values

Returns the DANumber object.

See Also

Ln

Floor

DAStatics Class

Creates the DANumber that represents the floor value, the largest integer value that is less than or equal to the value of the given argument.

lib.Floor(
a
)

Parameters
a
The DANumber object to find the floor for.
Return Values

Returns the DANumber object.

GT

DAStatics Class

Creates a DABoolean object that represents the relation a > b. The value is TRUE when the value of a is greater than the value of b, otherwise, it is FALSE.

lib.GT(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

GTE

DAStatics Class

Creates DABoolean object that represents the relation a ³ b. The value is TRUE when the value of a is greater than or equal to the value of b, otherwise, it is FALSE.

lib.GTE(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

Integral

DAStatics Class

Creates a DANumber object that represents the sum of all values of a from the start time to the present.

lib.Integral(
a
)

Parameters
a
The DANumber object to integrate.
Return Values

Returns the DANumber object.

InterpolateAnim

DAStatics Class

Creates a DANumber object the moves along the interval in duration seconds. Velocity is constant.

lib.InterpolateAnim(
from,
to,
duration
)

Parameters
from
The beginning DANumber object. This must be an animated number.
to
The ending DANumber object. This must be an animated number.
duration
The DANumber object representing the length of time, in seconds. This must be an animated number.
Return Values

Returns the DANumber object.

Interpolate

DAStatics Class

Same as InterpolateAnim except the arguments are non-animated numbers(doubles).

lib.Interpolate(
from,
to,
duration
)

Ln

DAStatics Class

Creates a DANumber object that represents the natural logarithm of the given argument. The value is the value by which the base of natural logarithms, e, must be raised to equal the value of a.

lib.Ln(
DANumber a
)

Parameters
a
The DANumber object for which to calculate the natural logarithm.
Return Values

Returns the DANumber object.

See Also

Exp

Log10

DAStatics Class

Creates DANumber object that represents the common logarithm (base-10 logarithm) of the given argument. The value is the value by which 10 must be raised to equal the value of a.

lib.Log10(
a
)

Parameters
a
The DANumber object for which to calculate the common logarithm.
Return Values

Returns the DANumber object.

LT

DAStatics Class

Creates a DABoolean object that represents the relation a < b. The value is TRUE when the value of a is less than the value of b, otherwise, it is FALSE.

lib.LT(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

LTE

DAStatics Class

Creates a DABoolean object that represents the relation a £ b. The value is TRUE when the value of a is less than or equal to the value of b, otherwise, it is FALSE.

lib.LTE(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

Mod

DAStatics Class

Creates a DANumber object that represents the modulus of the given arguments. The value is the modulus, the remainder of the integer value of a divided by the integer value of b.

lib.Mod(
a,
b
)

Parameters
a and b
The DANumber objects to calculate the modulus for.
Return Values

Returns the DANumber object.

Mul

DAStatics Class

Creates a DANumber representing the product of the given arguments. The value is the value of a multiplied by the value of b (a ´ b).

lib.Mul(
a,
b
)

Parameters
a and b
The DANumber objects to multiply.
Return Values

Returns the DANumber object.

NE

DAStatics Class

Creates a DABoolean object that represents the relation a != b. The value is TRUE when the value of a is not equal to the value of b, otherwise, it is FALSE.

lib.NE(
a,
b
)

Parameters
a and b
The DANumber objects to compare.
Return Values

Returns the DABoolean object.

Neg

DAStatics Class

Creates a DANumber object representing the negation of the given arguments. The value is equal to the value of a subtracted from zero (0 - a).

lib.Neg(
DANumber a
)

Parameters
a
The DANumber object to negate.
Return Values

Returns the DANumber object.

NumberBSpline

DAStatics Class

Creates a DANumber object based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned DANumber is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a DANumber that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

lib.NumberBSpline(
degree,
knots,
control_elements,
weights,
evaluation
)

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of DANumber objects representing the knots used to calculate the B-spline.
control_elements
An array of DANumber objects representing the control elements used to calculate the B-spline.
weights
An array of DANumber objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A DANumber object that controls the spline evaluation.
Return Values

Returns the DANumber object.

Pow

DAStatics Class

Creates a DANumber representing a raised to the power of b. The value is equal to ab.

lib.Pow(
a,
b
)

Parameters
a and b
The DANumber objects to apply the operation to.
Return Values

Returns the DANumber object.

Round

DAStatics Class

Creates a DANumber object that represents the value of the given argument, rounded to the nearest integer.

lib.Round(
a
)

Parameters
a
The DANumber object to be rounded.

SeededRandom

DAStatics Class

Creates a DANumber object that represents an infinite, time-varying sequence of pseudo-random values.

lib.SeededRandom(
seed
)

Parameters
seed
The double that provides the seed, or starting value, for the sequence.
Return Values

Returns the DANumber object.

Sin

DAStatics Class

Creates a DANumber object that represents the sine of the given argument.

lib.Sin(
a
)

Parameters
a
The DANumber object. The value is assumed to be in radians.
Return Values

Returns the DANumber object.

See Also

Cos

SlowInSlowOutAnim

DAStatics Class

Creates a DANumber object that moves along the interval in duration seconds. The animation is dampened so that the number increases slowly, hits a maximum speed at the midpoint, and then decelerates until the end is reached. The acceleration is specified in Gs, or multiples of the earth's gravitational constant.

lib.SlowInSlowOutAnim(
from,
to,
duration,
acceleration
)

Parameters
from
The DANumber object that is the beginning of the animation. This must be an animated number.
to
The DANumber object that is the end of the animation. This must be an animated number.
duration
The DANumber object that is the length of the animation, in seconds.
acceleration
The DANumber object that is the rate of acceleration, in Gs. This must be an animated number.
Return Values

Returns the DANumber object.

SlowInSlowOut

DAStatics Class

Same as SlowInSlowOutAnim except that the arguments are non-animated numbers (doubles).

lib.SlowInSlowOut(
from,
to,
duration,
acceleration
)

Sqrt

DAStatics Class

Creates a DANumber object that represents the square root of the given argument. The value is the square root of the value of a.

lib.Sqrt(
a
)

Parameters
a
The DANumber object to apply the square root operation to.
Return Values

Returns the DANumber object.

Sub

DAStatics Class

Creates a DANumber object representing the difference of the given arguments. The value is the value of b subtracted from a (a - b).

lib.Sub(
a,
b
)

Parameters
a and b
The DANumber objects to subtract.
Return Values

Returns the DANumber object.

Tan

DAStatics Class

Creates a DANumber object that represents the tangent of the given argument.

lib.Tan(
a
)

Parameters
a
The DANumber object. The value is assumed to be in radians.
Return Values

Returns the DANumber object.

See Also

Atan, Cos, Sin

ToDegrees

DAStatics Class

Creates a DANumber object that represents the value of the given argument converted from radians to degrees.

lib.ToDegrees(
a
)

Parameters
a
The DANumber object to convert.
Return Values

Returns the DANumber object.

ToRadians

DAStatics Class

Creates a DANumber object that represents the value of the given argument converted from degrees to radians.

lib.ToRadians(
a
)

Parameters
a
The DANumber object to convert.
Return Values

Returns the DANumber object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DANumber Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DANumber Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DANumber Objects
  * Next Topic: DAStatic Functions Relevant to DAPath2 Objects

DAStatic Properties Relevant to DANumber Objects

GlobalTime

DAStatics Class

A read-only property with a DANumber value which increases at the rate of one unit per second. Unlike LocalTime, the GlobalTime value cannot be reset to zero.

lib.GlobalTime

LocalTime

DAStatics Class

A read-only property with a DANumber value that starts at zero when "started" and increases at the rate of one unit per second.

lib.LocalTime


DirectAnimation Animated Header --DAStatic Functions Relevant to DAPath2 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAPath2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DANumber Objects
  * Next Topic: DAStatic Functions Relevant to DAPoint2 Objects

DAStatic Functions Relevant to DAPath2 Objects

ArcDegrees

DAStatics Class

Creates a DAPath2 object representing a segment of an oval (In effect, this is an arc). The oval is centered at the origin.

lib.ArcDegrees(
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
startAngle
The number (a double) representing the starting angle of the oval segment, expressed in degrees.
endAngle
The number (a double) representing the ending angle of the oval segment, expressed in degrees.
arcWidth
The number (a double) representing the arc width, expressed in either meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that positive-y is down.
arcHeight
The number (a double) representing the arc height, expressed in either meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that positive-y is down..
Return Values

Returns the DAPath2 object.

ArcRadiansAnim

DAStatics Class

Creates a DAPath2 object representing a segment of an oval (In effect, this is an arc). The oval is centered at the origin.

lib.ArcRadiansAnim(
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
startAngle
The DANumber object representing the starting angle of the arc, expressed in radians. This must be an animated number.
endAngle
The DANumber object representing the ending angle of the arc, expressed in radians. This must be an animated number.
arcWidth
The DANumber object representing the arc width, expressed in meters, or pixels, depending on whether the Pixel Library or the MeterLibrary was selected. This must be an animated number.
arcHeight
The DANumber object representing the arc height, expressed in meters, or pixels, depending on whether the Pixel Library or the MeterLibrary was selected. This must be an animated number.
Return Values

Returns the DAPath2 object.

Remarks

If the PixelLibrary is selected, remember that the positive y-axis is down.

ArcRadians

DAStatics Class

Same as ArcRadiansAnim except that the arguments are non-animated numbers (doubles).

lib.ArcRadians(
startAngle,
endAngle,
arcWidth,
arcHeight
)

Concat

DAStatics Class

Creates a DAPath2 object that represents the concatenation of the given paths. In the new path, the points of p1 occur first, followed by those of p2. Path p2 is transformed so that the first point of p2 aligns with the last point of p1.

lib.Concat(
p1,
p2
)

Parameters
p1 and p2
The DAPath2 objects.
Return Values

Returns the DAPath2 object.

ConcatArray

DAStatics Class

Creates a DAPath2 object that represents the concatenation of the DAPath2 objects in the array. In the new path, the points of the first path in the array occur first, followed sequentially by the other paths in the array. The second path, for example, is transformed so that its first point aligns with the last point of the first path.

lib.ConcatArray(
paths
)

Parameters
paths
The array (variant) of DAPath2 objects.
Return Values

Returns the DAPath2 object.

CubicBSplinePath

DAStatics Class

Creates a DAPath2 object based on a cubic B-spline curve. The curve depends on the control points and the knot vector, and requires that:

The control points define the approximate direction and shape of the function. The knots represent the junction values, in parameter space, between the connected polynomial parts. For a number of knots k, the function is valid in the range [3, knotk-2], and is otherwise undefined.

lib.CubicBSplinePath(
points,
knots
)

Parameters
points
An array (variant) of DAPoint2 objects representing the points used to calculate the B-spline.
knots
An array (variant) of DANumber objects representing the knots used to calculate the B-spline.
Return Values

Returns the DAPath2 object.

Line

DAStatics Class

Creates a DAPath2 object that represents the line segment defined by the given points.

lib.Line(
p1,
p2
)

Parameters
p1 and p2
The DAPoint2 objects.
Return Values

Returns the DAPath2 object.

OvalAnim

DAStatics Class

Creates a DAPath2 object that represents an oval, centered about the origin, and whose width and height are described by the given DANumber arguments.

lib.OvalAnim(
width,
height
)

Parameters
width
The DANumber object representing the oval's width. This must be an animated number.
height
The DANumber object representing the oval's height. This must be an animated number.
Return Values

Returns the DAPath2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that positive-y is down.

Oval

DAStatics Class

Same as OvalAnim except that the arguments are non-animated numbers (doubles).

lib.Oval(
width,
height
)

PieDegrees

DAStatics Class

Creates a DAPath2 object representing a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge). The oval is centered at the origin.

lib.PieDegrees(
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
startAngle
The double representing the starting angle of the oval segment, expressed in degrees.
endAngle
The double representing the ending angle of the oval segment, expressed in degrees.
arcWidth
The double representing the arc width, expressed in meters, or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected.
arcHeight
The double representing the arc height, expressed in meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected.
Return Values

Returns the DAPath2 object.

PieRadiansAnim

DAStatics Class

Creates a DAPath2 object representing a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge). The oval is centered at the origin.

lib.PieRadiansAnim(
startAngle,
endAngle,
arcWidth,
arcHeight
)

Parameters
startAngle
The DANumber object representing the starting angle of the oval segment, expressed in radians. This must be an animated number.
endAngle
The DANumber object representing the ending angle of the oval segment, expressed in radians. This must be an animated number.
arcWidth
The DANumber object representing the arc width, expressed in meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. This must be an animated number.
arcHeight
The DANumber object representing the arc height, expressed in meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. This must be an animated number.
Return Values

Returns the DAPath2 object.

PieRadians

DAStatics Class

Same as PieRadiansAnim except that the arguments are non-animated numbers (doubles).

lib.PieRadians(
startAngle,
endAngle,
arcWidth,
arcHeight
)

PolyDrawPath

DAStatics Class

Creates a DAPath2 object by manipulating the array of points with the codes contained in the DANumber array. The codes represent the instructions that can be OR'd together, where:
Code | Name | Meaning
01 | PT_CLOSEFIGURE | Connects points to create a closed figure.
02 | PT_LINETO | Connects points in a line.
04 | PT_BEZIERTO | Connects points in a Bezier curve. These must occur in multiples of 3.
06 | PT_MOVETO | Moves to a point. This is, implicitly, always the first instruction.

lib.PolyDrawPath(
points,
codes
)

Parameters
points
An array of DAPoint2 objects.
codes
An array of DANumber objects representing the instruction codes.
Return Values

Returns the DAPath2 object.

Remarks

This function is the equivalent of the Graphics Drawing Interface (GDI) PolyDraw function.

Polyline

DAStatics Class

Creates a DAPath2 object that consists of the given (animated) points. The path can be used either for drawing or animation. The default line style is the defaultLineStyle.

lib.Polyline(
points
)

Parameters
points
An array (variant) of DAPoint2 objects.
Return Values

Returns the DAPath2 object.

Ray

DAStatics Class

Creates a DAPath2 object that represents the line segment from the origin to the given (animated) point.

lib.Ray(
p
)

Parameters
p
The DAPoint2 object.
Return Values

Returns the DAPath2 object.

RectAnim

DAStatics Class

Creates the DAPath2 object representing a rectangle, centered at the origin.

lib.RectAnim(
width,
height
)

Parameters
width
The DANumber object representing the width of the rectangle, either in meters or pixels depending on whether the MeterLibrary or the PixelLibrary is selected. This must be an animated number.
height
The DANumber object representing the height of the rectangle, either in meters or pixels depending on whether the MeterLibrary or the PixelLibrary is selected. This must be an animated number.
Return Values

Returns the DAPath2 object.

Remarks

If the PixelLibrary is selected, remember that positive-y is down.

Rect

DAStatics Class

Same as RectAnim except that the arguments are non-animated numbers (doubles).

lib.Rect(
width,
height
)

RoundRectAnim

DAStatics Class

Creates a DAPath2 object that is a rectangle, centered about the origin, with rounded, rather than square, corners. The corners are considered to be segments of an oval (in effect, an arc), centered at the origin.

lib.RoundRectAnim(
width,
height,
arcWidth,
arcHeight
)

Parameters
width
The DANumber object representing the rectangle's width. This must be an animated number.
height
The DANumber object representing the rectangle's height. This must be an animated number.
arcWidth
The DANumber object representing the arc width. This must be an animated number.
arcHeight
The DANumber object representing the arc height. This must be an animated number.
Return Values

Returns the DAPath2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that positive-y is down.

RoundRect

DAStatics Class

Same as RoundRectAnim except that the arguments are non-animated numbers (doubles).

lib.RoundRect(
width,
height,
arcWidth,
arcHeight
)

StringPathAnim

DAStatics Class

Creates a DAPath2 object from the supplied DAString object. The appearance is specified by the DAFontStyle object. The path behavior is useful for creating a matte to which an image behavior can be clipped.

lib.StringPathAnim(
string,
fs
)

Parameters
string
The DAString object used to create the DAPath2 object.
fs
The DAFontStyle object specifying the appearance of the text.
Return Values

Returns the DAPath2 object.

See Also

StringPath

StringPath

DAStatics Class

Same as StringPathAnim except that string is non-animated.

lib.StringPath(
string,
fs
)


DirectAnimation Animated Header --DAStatic Functions Relevant to DAPoint2 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAPoint2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAPath2 Objects
  * Next Topic: DAStatic Properties Relevant to DAPoint2 Objects

DAStatic Functions Relevant to DAPoint2 Objects

AddPoint2Vector

DAStatics Class

Creates a DAPoint2 object. The location of the object is calculated by adding the corresponding coordinates of the given DAPoint2 and DAVector2 objects.

lib.AddPoint2Vector(
pt,
vec
)

Parameters
pt
A DAPoint2 object.
vec
A DAVector2 object.
Return Values

Returns the DAPoint2 object.

See Also

SubPoint2Vector

DerivativePoint2

DAStatics Class

Creates a DAVector2 object representing the instantaneous derivative (rate of change) of pt. For example, a constant yields a constant derivative of [0 0], and Point2(time, 0) (without additional time substitutions) yields a constant derivative of [1 0].

lib.DerivativePoint2(
pt
)

Parameters
pt
A DAPoint2 object whose derivative is found.
Return Values

Returns the DAVector2 object.

DistancePoint2

DAStatics Class

Creates a DAPoint2 object representing the distance between the two given points, p1 and p2.

lib.DistancePoint2(
p1,
p2
)

Parameters
p1 and p2
The DAPoint2 objects.
Return Values

Returns the DANumber object.

See Also

DistanceSquaredPoint2

DistanceSquaredPoint2

DAStatics Class

Creates a DANumber object representing the square of the distance between the two points, p1 and p2. This is the same as the DistancePoint2 function except that the distance is squared.

lib.DistanceSquaredPoint2(
p1,
p2
)

Parameters
p1 and p2
The DAPoint2 objects.
Return Values

Returns the DANumber object.

See Also

DistancePoint2

Point2Anim

DAStatics Class

Creates a DAPoint2 object. The location of the object is given in Cartesian coordinates.

lib.Point2Anim(
x,
y
)

Parameters
x and y
The DANumber objects, specifying the coordinate values. The x specifies the distance along the x-axis from the origin to the point, and y specifies the distance along the y-axis. These parameters must be animated numbers.
Return Values

Returns the DAPoint2 object.

See Also

Point2PolarAnim

Point2

DAStatics Class

Same as Point2Anim except that x and y are non-animated numbers (doubles).

lib.Point2(
x,
y
)

Point2BSpline

DAStatics Class

Creates a DAPoint2 object based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned DAPoint2 object is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a DANumber that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

lib.Point2BSpline(
degree,
knots,
control_elements,
weights,
evaluation
)

Parameters
degree
A number (long) representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array (variant) of DANumber objects representing the knots used to calculate the B-spline.
control_elements
An array (variant) of DAPoint2 objects representing the control elements used to calculate the B-spline.
weights
An array (variant) of DANumber objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null. This must be an animated number.
evaluation
A DANumber object that controls the spline evaluation.
Return Values

Returns the DAPoint2 object.

Point2PolarAnim

DAStatics Class

Creates a DAPoint2 object. The location of the object is given in polar coordinates.

lib.Point2PolarAnim(
XYangle,
length
)

Parameters
XYangle
The DANumber object specifying the angle, in radians, between the positive x-axis and the ray that goes from the origin to the point. This must be an animated number.
length
The DANumber object specifying the distance from the origin to the point. This must be an animated number.
Return Values

Returns the DAPoint2 object.

See Also

Point2Anim

Point2Polar

DAStatics Class

Same as Point2PolarAnim except that x and y are non-animated numbers (doubles).

lib.Point2Polar(
x,
y
)

SubPoint2

DAStatics Class

Creates a DAVector2 object. The coordinate values of the vector are calculated by subtracting the coordinates of p2 from the corresponding coordinates of p1.

lib.SubPoint2(
p1,
p2
)

Parameters
p1 and p2
The DAPoint2 objects to be subtracted.
Return Values

Returns the DAVector2 object.

SubPoint2Vector

DAStatics Class

Creates a DAPoint2 object. The location of the point is calculated by subtracting the coordinates of the given vector behavior from the corresponding coordinates of the given point.

lib.SubPoint2Vector(
pt,
vec
)

Parameters
pt
A DAPoint2 object.
vec
A DAVector2 object.
Return Values

Returns the DAPoint2 object.

See Also

AddPoint2Vector

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


DirectAnimation Animated Header --DAStatic Properties Relevant to DAPoint2 Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAPoint2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAPoint2 Objects
  * Next Topic: DAStatic Functions Relevant to DAPoint3 Objects

DAStatic Properties Relevant to DAPoint2 Objects

MousePosition

DAStatics Class

A read-only property with a DAPoint2 value that is the current location of the mouse.

lib.MousePosition

Origin2

DAStatics Class

A read-only property with a DAPoint2 value that is always located at the origin.

lib.Origin2


DirectAnimation Animated Header --DAStatic Functions Relevant to DAPoint3 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAPoint3 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAPoint2 Objects
  * Next Topic: DAStatic Properties Relevant to DAPoint3 Objects

DAStatic Functions Relevant to DAPoint3 Objects

AddPoint3Vector

DAStatics Class

Creates a DAPoint3 object. The location of the point is calculated by adding the corresponding coordinates of the given point and vector behaviors.

lib.AddPoint3Vector(
pt,
vec
)

Parameters
pt
A DAPoint3 object.
vec
A DAVector3 object.
Return Values

Returns the DAPoint3 object.

See Also

SubPoint3Vector

DerivativePoint3

DAStatics Class

Creates a DAVector3 object of the instantaneous derivative (rate of change) of the given point. For example, a constant yields a constant derivative of [0 0 0], and Point3 (time, 0) (without additional time substitutions) yields a constant derivative of [1 0 0].

lib.DerivativePoint3(
pt
)

Parameters
pt
A DAPoint3 object.
Return Values

Returns the DAVector3 object.

DistancePoint3

DAStatics Class

Creates a DANumber representing the distance between two points.

lib.DistancePoint3(
p1,
p2
)

Parameters
p1 and p3
The DAPoint3 objects.
Return Values

Returns the DANumber object.

See Also

DistanceSquaredPoint3

DistanceSquaredPoint3

DAStatics Class

Creates a DANumber object representing the square of the distance between two points. This is the same as the DistancePoint3 function except that the distance is squared.

lib.DistanceSquaredPoint3(
p1,
p2
)

Parameters
p1 and p3
The DAPoint3 objects.
Return Values

Returns the DANumber object.

See Also

DistancePoint3

Point3Anim

DAStatics Class

Creates a DAPoint3 object. The location of the point is given in Cartesian coordinates.

lib.Point3Anim(
x,
y,
z
)

Parameters
x, y, and z
The DANumber objects, specifying the coordinate values. The x specifies the distance along the x-axis from the origin to the point, y specifies the distance along the y-axis, and z the distance along the z-axis. These must be animated numbers.
Return Values

Returns the DAPoint3 object.

See Also

Point3SphericalAnim

Point3

DAStatics Class

Same as Point3Anim except that x, y, and z are non-animated numbers (doubles).

lib.Point3(
x,
y,
z
)

Point3BSpline

DAStatics Class

Creates a DAPoint3 behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned DAPoint3 is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a DANumber that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

lib.Point3BSpline(
degree,
knots,
control_elements,
weights,
evaluation
)

Parameters
degree
A number (long) representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array (variant) of DANumber objects representing the knots used to calculate the B-spline.
control_elements
An array (variant) of DAPoint3 objects representing the control elements used to calculate the B-spline.
weights
An array (variant) of DANumber objects representing the weights used to calculate the B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A DANumber object that controls the spline evaluation.
Return Values

Returns the DAPoint3 object.

Point3SphericalAnim

DAStatics Class

Creates a DAPoint3 object. The location of the point is given in spherical coordinates.

lib.Point3SphericalAnim(
XYangle,
YZangle,
length
)

Parameters
XYangle
A DANumber object of the counter-clockwise XY angle, in radians, of the point about the positive y-ray. The angle begins at the positive z-ray, so that [0 0 1] has a theta of 0, and [1 0 0] has a theta of pi/2. This must be an animated number.
YZangle
A DANumber object of the counter-clockwise elevation angle, in radians, of the point above the XZ-plane. A YZangle of pi/2 means the point is straight up (on the positive y-ray), and a YZangle of -pi/2 is straight down (on the negative y-ray). This must be an animated number.
length
A DANumber object of the distance of the point from the origin. This must be an animated number.
Return Values

Returns the DAPoint3 object.

Remarks

The following table correlates Cartesian coordinates with polar coordinates (X means "Don't Care"):
Cartesian | XYangle | YZangle | Length
Coordinates
[0 0 0] | X | X | 0
[d 0 0] | pi/2 | 0 | d
[-d 0 0] | -pi/2 | 0 | d
[0 d 0] | X | pi/2 | d
[0 -d 0] | X | -pi/2 | d
[0 0 d] | 0 | 0 | d
[0 0 -d] | pi | 0 | d

See Also

Point3Anim

Point3Spherical

DAStatics Class

Same as Point3SphericalAnim except that XYangle, YZangle, and length are non-animated numbers (doubles).

lib.Point3Spherical(
XYangle,
YZangle,
length
)

SubPoint3

DAStatics Class

Creates a DAVector3 object. The coordinate values of the vector are calculated by subtracting the coordinates of p3 from the corresponding coordinates of p1.

lib.SubPoint3(
p1,
p2
)

Parameters
p1 and p3
The DAPoint3 objects.
Return Values

Returns the DAVector3 object.

SubPoint3Vector

DAStatics Class

Creates a DAPoint3 object. The location of the point is calculated by subtracting the coordinates of the given vector behavior from the corresponding coordinates of the given point.

lib.SubPoint3Vector(
pt,
vec
)

Parameters
pt
A DAPoint3 object.
vec
A DAVector3 object.
Return Values

Returns the DAPoint3 object.

See Also

AddPoint3Vector

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


DirectAnimation Animated Header --DAStatic Properties Relevant to DAPoint3 Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAPoint3 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAPoint3 Objects
  * Next Topic: DAStatic Functions Relevant to DASound Objects

DAStatic Properties Relevant to DAPoint3 Objects

Origin3

DAStatics Class

A read-only property with a DAPoint3 value that is always located at the origin.

lib.Origin3


DirectAnimation Animated Header --DAStatic Functions Relevant to DASound Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DASound Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAPoint3 Objects
  * Next Topic: DAStatic Properties Relevant to DASound Objects

DAStatic Functions Relevant to DASound Objects

ImportSound

DAStatics Class

Creates a sound behavior by synchronously importing the given .WAV or MIDI file. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See ImportSoundAsync for a description of the asynchronous import function.

lib.ImportSound(
url
)

Parameters
url
The pathname for importing the sound. This is a String data type.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • Duration, which is the length of the sound, in seconds
  • Sound, which is the imported sound.

ImportSoundAsync

DAStatics Class

Creates a DASound by asynchronously importing the given .WAV or .MIDI file. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import function, see ImportSound.

lib.ImportSoundAsync(
url,
sndStandIn
)

Parameters
url
The pathname (a string) of the file.
sndStandIn
The sound to use while the contents at url are still being downloaded. This argument cannot be null, however, the sound can be silence. This is a DASound.
Return Values

Returns the DAImportationResult object, which has the following relevant properties:

  • CompletionEvent, which is the event that triggers once the download is complete.
  • Duration, which is the length of the sound, in seconds
  • Progress, which is the percentage of the download that has completed.
  • Size, which is the size of the imported sound, in bytes.
  • Sound, which is the imported sound.

Mix

DAStatics Class

Creates a sound behavior that is equivalent to sound1 + sound2.

lib.Mix(
sound1,
sound2
)

Parameters
sound1 and sound2
The DASound objects to be mixed.
Return Values

Returns the DASound object.

MixArray

DAStatics Class

Creates a sound that is equivalent to sound1 + sound2 + soundn.

lib.MixArray(
sounds
)

Parameters
sounds
The DASound objects in the array. This is a Variant array.
Return Values

Returns the DASound object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DASound Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DASound Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DASound Objects
  * Next Topic: DAStatic Functions Relevant to DAString Objects

DAStatic Properties Relevant to DASound Objects

Silence

DAStatics Class

A read-only property with a DASound value that is always completely silent (no sound).

lib.Silence

SinSynth

DAStatics Class

A read-only property with a DASound value that represents a constant tone. This sound is synthesized using a sine wave.

lib.SinSynth


DirectAnimation Animated Header --DAStatic Functions Relevant to DAString Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAString Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DASound Objects
  * Next Topic: DAStatic Functions Relevant to DATransform2 Objects

DAStatic Functions Relevant to DAString Objects

ConcatString

DAStatics Class

Creates a DAString object representing the concatenation of the given DAString objects. The new object's value is the character string consisting of the value of b appended to the end of the value of a.

lib.ConcatString(
a,
b
)

Parameters
a and b
The DAString objects to concatenate.
Return Values

Returns the DAString object.

DAString

DAStatics Class

Converts a String to a DAString object. The only time DAString is used is when converting strings to their corresponding DAString objects.

lib.DAString(
string
)

Parameters
string
The string to be converted.
Return Values

Returns the DAString object.


DirectAnimation Animated Header --DAStatic Functions Relevant to DATransform2 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DATransform2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAString Objects
  * Next Topic: DAStatic Properties Relevant to DATransform2 Objects

DAStatic Functions Relevant to DATransform2 Objects

Compose2

DAStatics Class

Creates a two-dimensional transformation behavior that is a composition of the given transformation behaviors.

lib.Compose2(
xf1,
xf2
)

Parameters
xf1 and xf2
The DATransform2 objects used in the composition.
Return Values

Returns the DATransform2 object.

Remarks

Composing a transform is equivalent to first applying xf2 and then applying xf1.

Compose2Array

DAStatics Class

Creates a two-dimensional transformation behavior that is a composition of the DATransform2 objects included in the array.

lib.Compose2Array(
xforms
)

Parameters
xforms
The DATransform2 objects included in the (variant) array.
Return Values

Returns the DATransform2 object.

Remarks

Composing a transform is equivalent to first applying xfn, then applying xfn -1 and so on.

FollowPathEval

DAStatics Class

Creates a DATransform2 object that is a translation (from the origin) that follows a 2-D vector drawing path. The DAPath2 object is converted into the equivalent translation transform.

lib.FollowPathEval(
path,
evaluator
)

Parameters
path
The DAPath2 object that will be traced.
evaluator
The DANumber object representing a value in the range [0, 1]. This value is a position on the path, where 0 is the beginning of the path and 1 is the end. This must be an animated number.
Return Values

Returns the DATransform2 object.

FollowPath

DAStatics Class

Creates a DATransform2 object that is a translation (from the origin) that follows a 2-D vector drawing path. The DAPath2 object is converted into the equivalent translation transform.

lib.FollowPath(
path,
duration
)

Parameters
path
The DAPath2 object that will be traced.
duration
A double representing the amount of time (in seconds) it will take to go from the beginning of the path to the end.
Return Values

Returns the DATransform2 object.

FollowPathAngleEval

DAStatics Class

Creates a DATransform2 object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative.

lib.FollowPathAngleEval(
path,
evaluator
)

Parameters
path
The DAPath2 object which is traversed.
evaluator
The DANumber object representing a value in the range [0, 1]. This value is a position on the path, where 0 is the beginning of the path and 1 is the end. This must be an animated number.
Return Values

Returns the DATransform2 object.

FollowPathAngle

DAStatics Class

Creates a DATransform2 object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative.

lib.FollowPathAngle(
path,
duration
)

Parameters
path
The DAPath2 object which is traversed.
duration
A double representing the amount of time (in seconds) it will take to go from the beginning of the path to the end.
Return Values

Returns the DATransform2 object.

FollowPathAngleUprightEval

DAStatics Class

Creates a DATransform2 object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative, except that the angle that is perpendicular to the X-axis (in local coordinates) will always be less than 180 degrees.

lib.FollowPathAngleUprightEval(
path,
evaluator
)

Parameters
path
The DAPath2 object which will be traversed.
evaluator
The DANumber object representing a value in the range [0, 1]. This value is a position on the path, where 0 is the beginning of the path and 1 is the end. This must be an animated number.
Return Values

Returns the DATransform2 object.

FollowPathAngleUpright

DAStatics Class

Creates a DATransform2 object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative, except that the angle that is perpendicular to the X-axis (in local coordinates) will always be less than 180 degrees.

lib.FollowPathAngleUpright(
path,
duration
)

Parameters
path
The DAPath2 object which will be traversed.
duration
A double representing the amount of time (in seconds) it will take to go from the beginning of the path to the end.
Return Values

Returns the DATransform2 object.

Rotate2Anim

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in radians).

lib.Rotate2Anim(
radians
)

Parameters
radians
The DANumber object (animated number) representing the angle of rotation.
Return Values

Returns the DATransform2 object.

Remarks

Rotations are counter-clockwise.

Rotate2

DAStatics Class

Same as Rotate2Anim except radians is a non-animated number (a double).

lib.Rotate2(
radians
)

Rotate2-Degrees

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in degrees).

lib.Rotate2-Degrees(
degrees
)

Parameters
degrees
The number (a double) representing the angle of rotation (expressed in degrees).
Return Values

Returns the DATransform2 object.

Remarks

Rotations are counter-clockwise.

Rotate2Rate

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in radians). This value is multiplied by LocalTime to determine the rotation rate.

lib.Rotate2Rate(
radians
)

Parameters
radians
The number (a double) representing the angle of rotation, multiplied by LocalTime. The unit is radians per second.
Return Values

Returns the DATransform2 object.

Remarks

Rotations are counter-clockwise.

Rotate2RateDegrees

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in degrees). This value is multiplied by LocalTime to determine the rotation rate.

lib.Rotate2RateDegrees(
degrees
)

Parameters
degrees
The number (a double) representing the angle of rotation, expressed in degrees, multiplied by LocalTime. The unit is degrees per second.
Return Values

Returns the DATransform2 object.

Remarks

Rotations are counter-clockwise.

Scale2Anim

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, scales it. For example, the transformation modifies the length of a vector by multiplying the vector's coordinates by the values of the corresponding number behaviors.

lib.Scale2Anim(
sx,
sy
)

Parameters
sx and sy
The DANumber objects representing the amount to scale. The value of sx applies to the x coordinate, and sy to the y coordinate. These must be animated numbers.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale2

DAStatics Class

Same as Scale2Anim except the parameter is a non-animated number (a double).

lib.Scale2(
sx,
sy
)

Scale2Rate

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, scales it. The scaling rates are determined by multiplying each argument by LocalTime.

lib.Scale2Rate(
x,
y
)

Parameters
sx and sy
The numbers (doubles) representing the amounts to scale, multiplied by LocalTime. The value of sx applies to the x coordinate, and sy to the y coordinate.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale2UniformAnim

DAStatics Class

Creates a two-dimensional transformation that applies a uniform scale to every coordinate of a two-dimensional object.

lib.Scale2UniformAnim(
uniformFactor
)

Parameters
uniformFactor
The DANumber object representing the value to apply to both the x and y coordinates, respectively. These must be animated numbers.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

Scale2Anim

Scale2Uniform

DAStatics Class

Same as Scale2UniformAnim except uniformFactor is a non-animated number (a double).

lib.Scale2Uniform(
uniformFactor
)

Scale2UniformRate

DAStatics Class

Creates a two-dimensional transformation that applies a uniform scale to every coordinate of a two-dimensional object. The scaling rate is determined by multiplying the argument by LocalTime.

lib.Scale2UniformRate(
rate
)

Parameters
rate
The value to apply to both the x and y coordinates, respectively, multiplied by LocalTime.
Return Values

Returns a DATransform2 object representing the newly created transformation.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected.

Scale2Vector

DAStatics Class

Creates a two-dimensional transformation that, when applied to any two-dimensional vector, scales it. For example, the transformation modifies the location of a point by multiplying the point's coordinates by the values of the corresponding vector coordinates.

lib.Scale2Vector(
v
)

Parameters
v
The DAVector2 object. The x and y coordinates of the vector specify the amounts to scale the x and y coordinates, respectively.
Return Values

Returns the DATransform2 object.

Transform3x2Anim

DAStatics Class

Creates a two-dimensional transformation that consists of a 3 by 2 matrix (array) having the values specified by the given animated numbers.

lib.Transform3x2Anim(
matrix
)

Parameters
matrix
A 3 by 2 matrix. The top row of the matrix could be represented as containing DANumber objects a00, a01, and a02. Use a00 to scale the x coordinate and a02 to translate x.
The bottom row of the matrix could be represented as containing the DANumber objects a10, a11, and a12. Use a11 to scale the y coordinate and a12 to translate y.
Return Values

Returns the DATransform2 object.

Remarks

The X and Y translation components are given by a02 and a12, respectively.

Translate2Anim

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to a point, translates (moves) the point by the amount given by the animated numbers.

lib.Translate2Anim(
tx,
ty
)

Parameters
tx and ty
The DANumber objects representing the amount to translate the point along the x and y axes, respectively. These must be animated numbers.
Return Values

Returns the DATransform2 object.

Remarks

Two-dimensional vectors are unchanged by translations.

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Translate2

DAStatics Class

Same as Translate2Anim except tx and ty are non-animated numbers (doubles).

lib.Translate2(
tx,
ty
)

Translate2Point

DAStatics Class

Creates a two-dimensional transformation that, when applied to a point, translates (moves) the point to the new location loc.

lib.Translate2Point(
loc
)

Parameters
loc
The DAPoint2 object specifying the new location. This must be an animated point.
Return Values

Returns the DATransform2 object.

Translate2Rate

DAStatics Class

Creates a two-dimensional transformation that, when applied to a point, translates (moves) the point by the amount given by the arguments. The translation rates are determined by multiplying the arguments by LocalTime.

lib.Translate2Rate(
x,
y
)

Parameters
x and y
The numbers (doubles) representing the amounts to translate the point along the X and Y axes, respectively, multiplied by LocalTime.
Return Values

Returns the DATransform2 object.

Remarks

Two-dimensional vectors are unchanged by translations.

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Translate2Vector

DAStatics Class

Creates a two-dimensional transformation behavior that, when applied to a point, translates (moves) the point by the amount given by the vector.

lib.Translate2Vector(
v
)

Parameters
v
The DAVector2 object. The x and y coordinates of the vector specify the amount to translate along the x and y axes, respectively. This must be an animated vector.
Return Values

Returns the DATransform2 object.

Remarks

Two-dimensional vectors are unchanged by translations.

XShear2Anim

DAStatics Class

Creates a two-dimensional transformation that shears the x-axis either up or down. This means the X-coordinate of the points remains unchanged, and the Y-coordinate increases by the product of the X-coordinate and the shear factor. In other words, X2 = X1, and Y2 = Y1 + aX1, where a is the shear factor.

lib.XShear2Anim(
a
)

Parameters
a
The DANumber object representing the amount to shear. This must be an animated number.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

YShearAnim

XShear2

DAStatics Class

Same as XShear2Anim except that x is a non-animated number (a double).

lib.XShear2(
a
)

XShear2Rate

DAStatics Class

Creates a two-dimensional transformation that shears the x-axis either up or down. The shear rate is determined by multiplying the argument by LocalTime.

lib.XShear2Rate(
rate
)

Parameters
rate
The number (a double) representing the amount to shear, multiplied by LocalTime.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters/second or pixels/second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

YShear2Anim

DAStatics Class

Creates a two-dimensional transformation that shears the y-axis either left or right. This means the Y-coordinate of the points remains unchanged, and the X-coordinate increases by the product of the Y-coordinate and the shear factor. In other words, Y2 = Y1 and X2 = X1 + aY1, where a is the shear factor.

lib.YShear2Anim(
a
)

Parameters
a
The DANumber object representing the amount to shear. This must be an animated number.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

XShear2Anim

YShear2

DAStatics Class

Same as YShear2Anim except that y is a non-animated number (a double).

lib.YShear2(
a
)

YShear2Rate

DAStatics Class

Creates a two-dimensional transformation that shears the y-axis either left or right. The shear rate is determined by multiplying the argument by LocalTime.

lib.YShear2Rate(
rate
)

Parameters
rate
The number (a double) representing the amount to shear the y-axis, multiplied by LocalTime.
Return Values

Returns the DATransform2 object.

Remarks

The units can either be meters/second or pixels/second, depending on whether the MeterLibrary or the PixelLibrary is selected.


DirectAnimation Animated Header --DAStatic Properties Relevant to DATransform2 Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DATransform2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DATransform2 Objects
  * Next Topic: DAStatic Functions Relevant to DATransform3 Objects

DAStatic Properties Relevant to DATransform2 Objects

IdentityTransform2

DAStatics Class

A read-only property with a DATransform2 value that leaves the two-dimensional space unchanged. Applying this transformation to a point or vector produces the same point or vector.

lib.IdentityTransform2


DirectAnimation Animated Header --DAStatic Functions Relevant to DATransform3 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DATransform3 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DATransform2 Objects
  * Next Topic: DAStatic Properties Relevant to DATransform3 Objects

DAStatic Functions Relevant to DATransform3 Objects

Compose3

DAStatics Class

Creates a three-dimensional transformation that is a composition of the given transformation objects.

lib.Compose3(
xf1,
xf2
)

Parameters
xf1 and xf2
The DATransform3 objects.
Return Values

Returns the DATransform3 object.

Remarks

Composing a transform is equivalent to first applying xf2 and then applying xf1.

Compose3Array

DAStatics Class

Creates a three-dimensional transformation that is a composition of the DATransform3 objects in the array.

lib.Compose3Array(
xforms
)

Parameters
xf1 and xf2
The DATransform3 objects in the (variant) array.
Return Values

Returns the DATransform3 object.

Remarks

Composing a transform is equivalent to first applying xfn, then applying xfn-1, and so on.

LookAtFrom

DAStatics Class

Creates a three-dimensional transformation that transforms an object from a standard position and orientation to the "from" point, and aimed at the "to" point, with "up" mapping to the object's up direction. Prior to this transform, objects must be located at the origin, with the up side aligned with the positive y-axis, and aimed in the negative z-direction.

lib.LookAtFrom(
from,
to,
up
)

Parameters
from
The DAPoint3 object specifying the point from which to view.
to
The DAPoint3 object specifying the point toward which to view.
up
The DAVector3 object specifying the point determining the upright position.
Return Values

Returns the DATransform3 object.

Remarks

This transform is useful for positioning and orienting cameras, lights, microphones, and other three-dimensional objects.

Rotate3Anim

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in radians) around the given axis.

lib.Rotate3Anim(
axis,
radians
)

Parameters
axis
The DAVector3 object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
radians
The DANumber object representing the angle of rotation. This parameter can also be of type double.
Return Values

Returns the DATransform3 object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

Rotate3

DAStatics Class

Same as Rotate3Anim except that axis and radians are non-animated numbers.

lib.Rotate3(
axis,
radians
)

Rotate3-Degrees

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point or vector, rotates the point or vector by the given angle (expressed in degrees) around the given axis.

lib.Rotate3-Degrees(
axis,
degrees
)

Parameters
axis
The DAVector3 object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
degrees
The number (a double) representing the angle of rotation (expressed in degrees).
Return Values

Returns the DATransform3 object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

Rotate3Rate

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in radians) around the given axis. The rotation rate is determined by multiplying the angle by LocalTime.

lib.Rotate3Rate(
axis,
radians
)

Parameters
axis
The DAVector3 object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
radians
The number (a double) representing the angle of rotation, and multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Rotate3RateDegrees

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in degrees) around the given axis. The rotation rate is determined by multiplying the angle by LocalTime.

lib.Rotate3RateDegrees(
axis,
degrees
)

Parameters
axis
The DAVector3 object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
degrees
The number (a double) representing the angle of rotation (expressed in degrees), and multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale3Anim

DAStatics Class

Creates a three-dimensional transformation that, when applied to a three-dimensional object, scales it. For example, the transformation modifies the length of a vector by multiplying the vector's coordinates by the values of the corresponding numbers.

lib.Scale3Anim(
sx,
sy,
sz
)

Parameters
sx, sy, and sz
The DANumber objects representing the amounts to scale. The value of sx applies to the x coordinate, sy to the y coordinate, and sz to the z coordinate.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale3

DAStatics Class

Same as Scale3Anim except that sx, sy, and sz are non-animated numbers (doubles).

lib.Scale3(
sx,
sy,
sz
)

Scale3Rate

DAStatics Class

Creates a three-dimensional transformation that, when applied to a three-dimensional object, scales it. The scaling rates are determined by multiplying the arguments by LocalTime.

lib.Scale3Rate(
x,
y,
z
)

Parameters
x, y, and z
The numbers (doubles) representing the amounts to scale, multiplied by LocalTime. The value of x applies to the x coordinate, y to the y coordinate, and z to the z coordinate.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale3UniformAnim

DAStatics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it uniformly.

lib.Scale3UniformAnim(
uniformFactor
)

Parameters
uniformFactor
The DANumber object representing the value to apply to the x, y, and z coordinates, respectively. These must be animated numbers.
Return Values

Returns the DATransform3 object.

See Also

Scale3Anim, Scale3Vector

Scale3Uniform

DAStatics Class

Same as Scale3UniformAnim except that uniformFactor is a non-animated number (a double).

lib.Scale3Uniform(
uniformFactor
)

Scale3UniformRate

DAStatics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it uniformly. The scaling rate is determined by multiplying the argument by LocalTime.

lib.Scale3UniformRate(
rate
)

Parameters
rate
The number (a double) representing the value to apply to the x, y, and z coordinates, respectively, and multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Scale3Vector

DAStatics Class

Creates a three-dimensional transformation that, when applied to a three-dimensional object, scales it. For example, the transformation modifies the location of a point by multiplying the point's coordinates by the values of the corresponding vector coordinates.

lib.Scale3Vector(
v
)

Parameters
v
The DAVector3 object. The x, y, and z coordinates of the vector behavior specify the amounts to scale the x, y, and z coordinates, respectively.
Return Values

Returns the DATransform3 object.

Transform4x4Anim

DAStatics Class

Creates a three-dimensional transformation behavior that consists of the 4 by 4 matrix having the values specified by the given number behaviors.

lib.Transform4x4Anim(
matrix
)

Parameters
matrix
The 4 by 4 matrix. The first row of the matrix can be represented by the DANumber objects a00, a01, a02, a03. Use a00 to scale the x coordinate and a03 to translate x.
The second row of the matrix can be represented by the DANumber objects a10, a11, a12, a13. Use a11 to scale the y coordinate and a13 to translate y.
The third row of the matrix can be represented by the DANumber objects a20, a21, a22, a23. Use a22 to scale the z coordinate and a23 to translate z.
The fourth row of the matrix can be represented by the DANumber objects a30, a31, a32, a33.
Return Values

Returns the DATransform3 object.

Remarks

The translation components for the matrix are in the last column. The last row of the matrix must be [0 0 0 1].

Translate3Anim

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point, translates (moves) the point by the amounts given by the tx, ty, and tz.

lib.Translate3Anim(
tx,
ty,
tz
)

Parameters
tx, ty, and tz
The DANumber objects representing the amounts to translate the point along the x, y, and z axes, respectively. These must be animated numbers.
Return Values

Returns the DATransform3 object.

Remarks

Vectors are unchanged by translations.

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Translate3

DAStatics Class

Same as Translate3Anim except that x, y, and z are non-animated numbers (doubles).

lib.Translate3(
x,
y,
z
)

Translate3Point

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point, translates (moves) the point to the new location loc.

lib.Translate3Point(
loc
)

Parameters
loc
The DAPoint3 object specifying the new location. This must be an animated point.
Return Values

Returns the DATransform3 object.

Translate3Rate

DAStatics Class

Creates a three-dimensional transformation that, when applied to a point, translates (moves) the point by the amounts given by x, y, z. The translation rate is determined by multiplying the arguments by LocalTime.

lib.Translate3Rate(
x,
y,
z
)

Parameters
x, y, and z
The numbers (doubles) representing the amounts to translate the point along the x, y, and z axes, respectively, and multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

Vectors are unchanged by translations.

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

Translate3Vector

DAStatics Class

Creates a three-dimensional transformation behavior that, when applied to a point, translates (moves) the point by the amounts given by the vector.

lib.Translate3Vector(
v
)

Parameters
v
The DAVector3 object. The x, y, and z coordinates of the vector specify the amounts to translate along the x, y, and z axes, respectively.
Return Values

Returns the DATransform3 object.

Remarks

Vectors are unchanged by translations.

XShear3Anim

DAStatics Class

Shears the x-axis in the positive y-direction by a and in the positive z-direction by b. The X-coordinate remains unchanged, and the Y and Z coordinates increase by the product of the X-coordinate and the shear factors. In other words, X2 = X1, Y2 = Y1 + aX1, and Z2 = Z1 + bX1, where a and b are the shear factors.

lib.XShear3Anim(
a,
b
)

Parameters
a
The DANumber object representing the amount of shear in the Y direction. This must be an animated number.
b
The DANumber object representing the amount of shear in the Z direction. This must be an animated number.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

YShear3Anim, ZShear3Anim

XShear3

DAStatics Class

Same as XShear3Anim except that a and b are non-animated numbers (doubles).

lib.XShear3(
a,
b
)

XShear3Rate

DAStatics Class

Shears the x-axis in the positive y-direction by a and in the positive z-direction by b. The shear rates are determined by multiplying the arguments by LocalTime.

lib.XShear3Rate(
a,
b
)

Parameters
a
The number (a double) representing the amount of shear in the Y direction, multiplied by LocalTime.
b
The number (a double) representing the amount of shear in the Z direction, multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

YShear3Rate, ZShear3Rate

YShear3Anim

DAStatics Class

Shears the y-axis in the positive x-direction by c and in the positive z-direction by d. The Y-coordinate remains unchanged, and the X and Z coordinates increase by the product of the Y-coordinate and the shear factors. In other words, Y2 = Y1, X2 = X1 + cY1, and Z2 = Z1 + dY1, where c and d are the shear factors.

lib.YShear3Anim(
c,
d
)

Parameters
c
The DANumber object representing the amount of shear in the X direction. This must be an animated number.
d
The DANumber object representing the amount of shear in the Z direction. This must be an animated number.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

XShear3Anim, ZShear3Anim

YShear3

DAStatics Class

Same as YShearAnim except that c and d are non-animated numbers (double).

lib.YShear3(
c,
d
)

YShear3Rate

DAStatics Class

Shears the y-axis in the positive x-direction by c and in the positive z-direction by d. The shear rates are determined by multiplying the arguments by LocalTime.

lib.YShear3Rate(
c,
d
)

Parameters
c
The number (a double) representing the amount of shear in the X direction, multiplied by LocalTime.
d
The number (a double) representing the amount of shear in the Z direction, multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

XShear3Rate, ZShear3Rate

ZShear3Anim

DAStatics Class

Shears the z-axis in the positive x-direction by e and in the positive y-direction by f. The Z-coordinate remains unchanged, and the X and Y coordinates increase by the product of the Z-coordinate and the shear factors. In other words, Z2 = Z1, X2 = X1 + eZ1, and Y2 = Y1 + fZ1, where e and f are the shear factors.

lib.ZShear3Anim(
e,
f
)

Parameters
e
The DANumber object representing the amount of shear in the X direction. This must be an animated number.
f
The DANumber object representing the amount of shear in the Y direction. This must be an animated number.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters or pixels, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

XShear3Anim, YShear3Anim

ZShear3

DAStatics Class

Same as ZShear3Anim except that e and f are non-animated numbers (doubles).

lib.ZShear3(
e,
f
)

ZShear3Rate

DAStatics Class

Shears the z-axis in the positive x-direction by e and in the positive y-direction by f. The shear rates are determined by multiplying the arguments by LocalTime.

lib.ZShear3Rate(
e,
f
)

Parameters
e
The number (a double) representing the amount of shear in the X direction, multiplied by LocalTime.
f
The number (a double) representing the amount of shear in the Y direction, multiplied by LocalTime.
Return Values

Returns the DATransform3 object.

Remarks

The units can either be meters per second or pixels per second, depending on whether the MeterLibrary or the PixelLibrary is selected. If the PixelLibrary is selected, remember that the positive y-axis is down.

See Also

XShear3Rate, YShear3Rate


DirectAnimation Animated Header --DAStatic Properties Relevant to DATransform3 Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DATransform3 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DATransform3 Objects
  * Next Topic: DAStatic Functions Relevant to DATuple Objects

DAStatic Properties Relevant to DATransform3 Objects

IdentityTransform3

DAStatics Class

A read-only property with a DATransform3 value that leaves the three-dimensional space unchanged. Applying this transformation to a point or vector produces the same point or vector.

lib.IdentityTransform3


DirectAnimation Animated Header --DAStatic Functions Relevant to DATuple Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DATuple Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DATransform3 Objects
  * Next Topic: DAStatic Functions Relevant to DAVector2 Objects

DAStatic Functions Relevant to DATuple Objects

DATuple

DAStatics Class

Constructs the DATuple object.

lib.DATuple(
behaviors
)

Parameters
behaviors
The behaviors to be included in the DATuple object.
Return Values

Returns the DATuple object.

UninitializedTuple

DAStatics Class

Makes it possible to obtain the signature of a DATuple object before it has been defined. With this function, a DATuple object can be created and used in the definition of other DABehaviors while its contents are defined at some later point. (This definition is accomplished with the Init function, which is available on all classes that inherit from DABehavior.) Because a DATuple can have members of different types, the signature must be exactly as the object will be used.

lib.UninitializedTuple( )

Return Values

Returns the DATuple object.


DirectAnimation Animated Header --DAStatic Functions Relevant to DAVector2 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAVector2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DATuple Objects
  * Next Topic: DAStatic Properties Relevant to DAVector2 Objects

DAStatic Functions Relevant to DAVector2 Objects

AddVector2

DAStatics Class

Creates a DAVector2 object that is the vector-valued sum of the two vectors.

lib.AddVector2(
v1,
v2
)

Parameters
v1 and v2
The DAVector2 objects to be added.
Return Values

Returns the DAVector2 object.

See Also

SubVector2

DerivativeVector2

DAStatics Class

Creates a DAVector2 object that is the instantaneous derivative (rate of change) of the given vector. For example, a constant vector yields a constant derivative of [0 0], and Vector2 (time, 0) (without any additional time substitutions) yields a constant derivative vector of [1 0].

lib.DerivativeVector2(
vec
)

Parameters
vec
A DAVector2 object.
Return Values

Returns the DAVector2 object.

DotVector2

DAStatics Class

Creates a DANumber object that represent the "dot product" of the given vectors. The dot product is the product of the lengths of the vectors and the cosine of the angle between them.

lib.DotVector2(
v1,
v2
)

Parameters
v1 and v2
The DAVector2 objects.
Return Values

Returns the DANumber object.

IntegralVector2

DAStatics Class

Creates a DAVector2 object that represents the sum of the all values of vec from the given start time to the present.

lib.IntegralVector2(
vec
)

Parameters
a
The DAVector2 object.
Return Values

Returns the DAVector2 object.

NegVector2

DAStatics Class

Creates a DAVector2 object that is the same length as the original vector but points in the opposite direction.

lib.NegVector2(
v1
)

Parameters
v1
A DAVector2 object that is the original vector.
Return Values

Returns the DAVector2 object.

SubVector2

DAStatics Class

Creates a DAVector2 object. The direction and length of the vector are calculated by subtracting the coordinates of v2 from the corresponding coordinates of v1.

lib.SubVector2(
v1,
v2
)

Parameters
v1 and v2
The DAVector2 objects.
Return Values

Returns the DAVector2 object.

See Also

AddVector2

Vector2Anim

DAStatics Class

Creates a DAVector2 object having a direction and length as specified by the given Cartesian coordinates.

lib.Vector2Anim(
x,
y
)

Parameters
x
The DANumber object specifying the distance along the x-axis from the origin to a point. This must be an animated number.
y
The DANumber object specifying the distance along the y-axis. This must be an animated number.
Return Values

Returns the DAVector2 object.

See Also

Vector2Polar

Vector2

DAStatics Class

Same as Vector2Anim except that x and y are non-animated numbers (doubles).

lib.Vector2(
x,
y
)

Vector2BSpline

DAStatics Class

Creates a DAVector2 object based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned DAVector2 is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a DANumber that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

lib.Vector2BSpline(
degree,
knots,
control_elements,
weights,
evaluation
)

Parameters
degree
A number (a long) representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array (variant) of DANumber objects representing the knots used to calculate the B-spline.
control_elements
An array (variant) of DAPoint2 objects representing the control elements used to calculate the B-spline.
weights
An array (variant) of DANumber objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A DANumber object that controls the spline evaluation. This must be an animated number.
Return Values

Returns the DAVector2 object.

Vector2PolarAnim

DAStatics Class

Creates a DAVector2 object having a direction and length as specified by the given polar coordinates.

lib.Vector2PolarAnim(
XYangle,
length
)

Parameters
XYangle
The DANumber object that is the counter-clockwise angle of the vector, in radians, from the positive x-ray. This must be an animated number.
length
The DANumber object that is the length of the vector. This must be an animated number.
Return Values

Returns the DAVector2 object.

See Also

Vector2Anim

Vector2Polar

DAStatics Class

Same as Vector2PolarAnim except that XYangle and length are non-animated numbers (doubles).

lib.Vector2Polar(
XYangle,
length
)

Vector2PolarDegrees

DAStatics Class

Creates a DAVector2 object having a direction and length as specified by the given polar coordinates.

lib.Vector2PolarDegrees(
XYangle,
length
)

Parameters
XYangle
The number (a double) that is the counter-clockwise angle of the vector (expressed in degrees) from the positive x-ray.
length
The number (a double) that is the length of the vector.
Return Values

Returns the DAVector2 object.


DirectAnimation Animated Header --DAStatic Properties Relevant to DAVector2 Objects DirectAnimation Animated Header --DAStatic Properties Relevant to DAVector2 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Functions Relevant to DAVector2 Objects
  * Next Topic: DAStatic Functions Relevant to DAVector3 Objects

DAStatic Properties Relevant to DAVector2 Objects

XVector2

DAStatics Class

A read-only property with a DAVector2 value that represents the unit vector on the x-axis. The vector's length is always 1, the direction is always the same as the positive x-axis.

lib.XVector2

YVector2

DAStatics Class

A read-only property with a DAVector2 value that represents the unit vector on the y-axis. The vector's length is always 1, the direction is always the same as the positive y-axis.

lib.YVector2

ZeroVector2

DAStatics Class

A read-only property with a DAVector2 value that represents the null vector. The vector's length is always 0, the direction is undefined.

lib.ZeroVector2


DirectAnimation Animated Header --DAStatic Functions Relevant to DAVector3 Objects DirectAnimation Animated Header --DAStatic Functions Relevant to DAVector3 Objects * Microsoft DirectAnimation SDK
  * Previous Topic: DAStatic Properties Relevant to DAVector2 Objects
  * Next Topic: DAStatic Properties Relevant to DAVector3 Objects

DAStatic Functions Relevant to DAVector3 Objects

AddVector3

DAStatics Class

Creates a DAVector3 object. The direction and length of the vector are calculated by adding the corresponding coordinates of the given vectors.

lib.AddVector3(
v1,
v2
)

Parameters
v1 and v2
The DAVector3 objects.
Return Values

Returns the DAVector3 object.

See Also

SubVector3

CrossVector3

DAStatics Class

Creates a DAVector3 object that represents the "cross product" of the given vectors. The new vector has a length that is equal to the product of the lengths of the original vectors and the sine of the angle between them. The new vector has a direction that is perpendicular to the plane formed by the original vectors and that obeys the right-hand rule.

lib.CrossVector3(
v1,
v2
)

Parameters
v1 and v2
The DAVector3 objects.
Return Values

Returns the DAVector3 object.

DerivativeVector3

DAStatics Class

Creates a DAVector3 object that is the instantaneous derivative (rate of change) of the given vector. For example, a constant vector behavior yields a constant derivative of [0 0 0], and Vector3(time, 0, 0) (without any additional time substitutions) yields a constant derivative vector of [1 0 0].

lib.DerivativeVector3(
vec
)

Parameters
vec
A DAVector3 object.
Return Values

Returns the DAVector3 object.

DotVector3

DAStatics Class

Creates DANumber object that represents the "dot product" of the given vectors. The dot product is the product of the lengths of the vectors and the cosine of the angle between them.

lib.DotVector3(
v1,
v2
)

Parameters
v1 and v2
DAVector3 objects.
Return Values

Returns the DANumber object.

IntegralVector3

DAStatics Class

Creates a DAVector3 object that represents the sum of the all values of vec from the given start time to the present.

lib.IntegralVector3(
vec
)

Parameters
a
The DAVector3 object.
Return Values

Returns the DAVector3 object.

NegVector3

DAStatics Class

Creates a DAVector3 object that has the same length as the original vector, but points in the opposite direction.

lib.NegVector3(
v1
)

Parameters
v1
A DAVector3 object that is the original vector.
Return Values

Returns the DAVector3 object.

SubVector3

DAStatics Class

Creates a DAVector3 object. The direction and length of the vector are calculated by subtracting the coordinates of v2 from the corresponding coordinates of v1.

lib.SubVector3(
v1,
v2
)

Parameters
v1 and v2
DAVector3 objects.
Return Values

Returns the DAVector3 object.

See Also

AddVector3

Vector3Anim

DAStatics Class

Creates a DAVector3 object having a direction and length as specified by the given Cartesian coordinates.

lib.Vector3Anim(
x,
y,
z
)

Parameters
x, y, and z
The DANumber objects specifying the coordinate values. The x specifies a distance along the x-axis from the origin to a point, y specifies a distance along the y-axis, and z a distance along the z-axis. These must be animated numbers.
Return Values

Returns the DAVector3 object.

See Also

Vector3SphericalAnim

Vector3

DAStatics Class

Same as Vector3Anim except that x, y, and z are non-animated numbers (doubles).

lib.Vector3(
x,
y,
z
)

Vector3BSpline

DAStatics Class

Creates a DAVector3 behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned DAVector3 is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a DANumber that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

lib.Vector3BSpline(
degree,
knots,
control_elements,
weights,
evaluation
)

Parameters
degree
A number (long) representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array (variant) of DANumber objects representing the knots used to calculate the B-spline.
control_elements
An array (variant) of DAVector3 objects representing the control elements used to calculate the B-spline.
weights
An array (variant) of DANumber objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A DANumber object that controls the spline evaluation. This must be an animated number.
Return Values

Returns the DAVector3 object.

Vector3SphericalAnim

DAStatics Class

Creates a DAVector3 object having a direction and length as specified by the given spherical coordinates.

lib.Vector3SphericalAnim(
XYangle,
YZangle,
length
)

Parameters
XYangle
A DANumber object of the counter-clockwise XY angle, in radians, of the point about the positive y-axis. The angle begins at the positive z-ray, so that [0 0 1] has a theta of 0, and [1 0 0] has a theta of pi/2. This must be an animated number.
YZangle
A DANumber object of the counter-clockwise elevation angle, in radians, of the point above the XZ-plane. A YZangle of pi/2 means the point is straight up (on the positive y-ray), and a YZangle of -pi/2 is straight down (on the negative y-ray). This must be an animated number.
length
A DANumber object specifying the length of the vector. This must be an animated number.
Return Values

Returns the DAVector3 object.

Remarks

The following table correlates Cartesian coordinates with polar coordinates (X means "Don't Care"):
Cartesian | XYangle | YZangle | Length
Coordinates
[0 0 0] | X | X | 0
[d 0 0] | pi/2 | 0 | d
[-d 0 0] | -pi/2 | 0 | d
[0 d 0] | X | pi/2 | d
[0 -d 0] | X | -pi/2 | d
[0 0 d] | 0 | 0 | d
[0 0 -d] | pi | 0 | d

See Also

Vector3Anim

Vector3Spherical

DAStatics Class

Same as Vector3SphericalAnim except that XYangle, YZangle, and length are non-animated numbers (doubles).

lib.Vector3Spherical(
XYangle,
YZangle,
length
)


DAStatic Properties Relevant to DAVector3 Objects

XVector3

DAStatics Class

A read-only property with a DAVector3 value that represents the unit vector on the x-axis. The vector's length is always 1, the direction is always the same as the positive x-axis.

lib.XVector3

YVector3

DAStatics Class

A read-only property with a DAVector3 value that represents the unit vector on the y-axis. The vector's length is always 1, the direction is always the same as the positive y-axis.

lib.YVector3

ZVector3

DAStatics Class

A read-only property with a DAVector3 value that represents the unit vector on the z-axis. The vector's length is always 1, the direction is always the same as the positive z-axis.

lib.ZVector3

ZeroVector3

DAStatics Class

A read-only property with a DAVector3 that represents the null vector. The vector's length is always 0, the direction is undefined.

lib.ZeroVector3


DAString Class

Creates a DAString object. At any given time, the value of the object is a character string. This value can vary over time.

This class inherits from the DABehavior class.

  • DAString Functions
  • Relevant Functions from the DAStatics Class

DAString Functions

AnimateProperty

Extract

AnimateProperty

DAString Class

Allows control properties to be animated (vary over time). This function forms fragments of script and passes them to the scripting engine on every frame. When the invoke parameter is FALSE, the property is set directly as shown in this fragment from the JScript sample in JScript\Templates\AnimatedProperties.html:

filterStr = filterStr.AnimateProperty("DropWave1.style.filter", "JScript", false, .1));

If the invoke parameter is TRUE, then a function name should be specified in the string parameter (property) and is invoked as shown in this fragment from the same JScript sample:

filterMethod = getNumber().AnimateProperty("SetFilter", "JScript", true, .1);

stringObj.AnimateProperty(
property,
language,
invoke,
update
)

Parameters
property
A string that is either the name of the property to animate or the name of a scripting function to invoke that will set the property.
language
A string that is name of the scripting language.
invoke
A boolean that determines if the property is set directly or if a function is invoked. If FALSE, the property is set directly. If TRUE, a function is invoked.
interval
A double specifying how frequently the position is updated.
Return Values

Returns the DAString object.

See Also

AnimateControlPositionPixel

Extract

DAString Class

Extracts the value of the stringObj, returning a String. This object must have a constant value.

stringObj.Extract

Return Values

Returns a String.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAString.

lib.ConcatString(a, b)

lib.DAString(string)


DATransform2 Class

DATransform2 objects can be applied to two-dimensional point objects to translate, scale, rotate or skew the location of the point, and can be applied to two-dimensional vector objects to scale, rotate, or skew the length and/or direction of the vector.

This class inherits from DABehavior.

  • DATransform2 Functions
  • DATransform2 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DATransform2 Functions

Inverse

Inverse

DATransform2 Class

Creates a transformation that is the inverse of the original transformation. The inverse transformation is useful for removing the effects of the original transformation from a point or vector. Some transforms have no inverse. Use IsSingular to characterize transforms of an unknown type.

transform2Obj.Inverse( )

Return Values

Returns a DATransform2 object representing the newly created transformation.

DATransform2 Properties

IsSingular

IsSingular

DATransform2 Class

A read-only property with a DABoolean value that indicates whether the transform is singular or not. A singular transform is one that has no inverse. The value is TRUE if the transform is singular; otherwise, it is FALSE.

transform2Obj.IsSingular

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DATransform2.

lib.Compose2(xf1, xf2)

lib.Compose2Array(xforms)

lib.FollowPath(path, duration)

lib.FollowPathEval(path, evaluator)

lib.FollowPathAngle(path, duration)

lib.FollowPathAngleEval(path,evaluator)

lib.FollowPathAngleUpright(path, duration)

lib.FollowPathAngleUprightEval(path, evaluator)

lib.Rotate2Anim(radians)

lib.Rotate2(radians)

lib.Rotate2-Degrees(degrees)

lib.Rotate2Rate(radians)

lib.Rotate2RateDegrees(degrees)

lib.Scale2Anim(sx, sy)

lib.Scale2(sx, sy)

lib.Scale2Rate(x, y)

lib.Scale2UniformAnim(uniformFactor)

lib.Scale2Uniform(uniformFactor)

lib.Scale2UniformRate(rate)

lib.Scale2Vector(v)

lib.Transform3x2Anim(matrix)

lib.Translate2Anim(tx, ty)

lib.Translate2(tx, ty)

lib.Translate2Point(loc)

lib.Translate2Rate(x, y)

lib.Translate2Vector(v)

lib.XShear2Anim(a)

lib.XShear2(a)

lib.XShear2Rate(rate)

lib.YShear2Anim(a)

lib.YShear2(a)

lib.YShear2Rate(rate)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DATransform2.

lib.IdentityTransform2


DATransform3 Class

Just as a DATransform2 transforms one two-dimensional object into another two-dimensional object, a DATransform3 transforms one three-dimensional object into another three-dimensional object. Other transforms include the Render function, which transforms three-dimensional objects into two-dimensional objects, and the project function, which transforms a three-dimensional point into a two-dimensional point.

This class inherits from the DABehavior class.

This class inherits from DABehavior.

  • DATransform3 Functions
  • DATransform3 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DATransform3 Functions

Inverse

ParallelTransform2

Inverse

DATransform3 Class

Creates a transformation that is the inverse of the original transformation. The inverse transformation is useful for removing the effects of the original transformation from a three-dimensional object. Use IsSingular to characterize transforms of an unknown type.

transform3Obj.Inverse( )

Return Values

Returns the DATransform3 object.

ParallelTransform2

DATransform3 Class

Creates a DATransform2 object from the DATransform3 object. It is equivalent to casting an orthographic projection of the DATransform3 onto the X-Y plane. For predictable results, the transform must be an affine (4x3) transform rather than a perspective (4x4) transform.

transform3Obj.ParallelTransform2( )

Return Values

Returns the DATransform2 object.

DATransform3 Properties

IsSingular

IsSingular

DATransform3 Class

A read-only property with a DABoolean value indicating whether the transform is singular or not. A singular transform is one that has no inverse. The value is TRUE if the transform is singular; otherwise, it is FALSE.

transform3Obj.IsSingular

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DATransform3.

lib.Compose3(xf1, xf2)

lib.Compose3Array(xforms)

lib.LookAtFrom(from, to, up)

lib.Rotate3Anim(axis, radians)

lib.Rotate3(axis, radians)

lib.Rotate3-Degrees(axis, degrees)

lib.Rotate3Rate(axis, radians)

lib.Rotate3RateDegrees(axis, degrees)

lib.Scale3Anim(sx, sy, sz)

lib.Scale3(sx, sy, sz)

lib.Scale3Rate(x, y, z)

lib.Scale3UniformAnim(uniformFactor)

lib.Scale3Uniform(uniformFactor)

lib.Scale3UniformRate(rate)

lib.Scale3Vector(v)

lib.Transform4x4Anim(matrix)

lib.Translate3Anim(tx, ty, tz)

lib.Translate3(tx, ty, tz)

lib.Translate3Point(loc)

lib.Translate3Rate(x, y, z)

lib.Translate3Vector(v)

lib.XShear3Anim(a, b)

lib.XShear3(a, b)

lib.XShear3Rate(a, b)

lib.YShear3Anim(c, d)

lib.YShear3(c, d)

lib.YShear3Rate(c, d)

lib.ZShear3Anim(e, f)

lib.ZShear3(e, f)

lib.ZShear3Rate(e, f)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DATransform3.

lib.IdentityTransform3


DATuple Class

A DATuple object is similar to an array. It can, however, accept heterogeneous types. Any number of members can be included in a DATuple object.

This class inherits from DABehavior.

  • DATuple Functions
  • Relevant Functions from the DAStatics Class

DATuple Functions

Length

Nth

Length

DATuple Class

Determines the length of a DATuple.

tupleObj.Length

Return Values

Returns a number (a long).

Nth

DATuple Class

Selects a DABehavior object based on the value of i.

tupleObj.Nth(
i
)

Parameters
i
The index (a long) into the DATuple object.

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics and are most relevant to objects of type DATuple.

lib.DATuple(behaviors)

lib.UninitializedTuple()


DAUserData Class

This class is analogous to DANumber. It turns a COM object (IUnknown) into a DABehavior. It is typically used with AttachData.

This class inherits from DABehavior.

DAUserData Properties

Data

Data

DAUserData Class

Turns a COM object (IUnknown) into a DABehavior.

userDataObj.Data(
IUnknown
)


DAVector2 Class

Creates a Vector2 object. At any given time, the value of the object is a direction and length (magnitude), specified as a pair of coordinate values given as either Cartesian coordinates (x, y) or polar coordinates (XYangle, YZangle). The direction of the vector is parallel to the ray that starts at the origin and passes through the point specified by the vector's coordinates, and the length is the distance between the origin and the point.

Because coordinate values are animated numbers (DANumber objects), the direction and length of the Vector2 object can change over time as the values of the animated numbers change.

This class inherits from the DABehavior Class.

  • DAVector2 Functions
  • DAVector2 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAVector2 Functions

DivAnim

Div

MulAnim

Mul

Normalize

Transform

DivAnim

DAVector2 Class

Creates a new two-dimensional DAVector2 object that points in the same direction as the original vector but has a length that has been divided by scalar.

vector2Obj.DivAnim(
scalar
)

Parameters
scalar
A DANumber object used as the divider. This must be an animated number.
Return Values

Returns the DAVector2 object.

See Also

MulAnim

Div

Same as DivAnim except that scalar is a non-animated number (a double).

vector2Obj.Div(
scalar
)

MulAnim

Creates a DAVector2 object that points in the same direction as the original vector but has a length that has been multiplied by scalar.

vector2Obj.MulAnim(
scalar
)

Parameters
scalar
A DANumber object used as the multiplier. This must be an animated number.
Return Values

Returns the DAVector2 object.

See Also

DivAnim

Mul

Same as MulAnim except that scalar is a non-animated number (a double).

vector2Obj.Mul(
scalar
)

Normalize

Creates a normalized, two-dimensional DAVector2 object. The normalized vector has the same direction as the original vector, but the length is 1.

vector2Obj.Normalize

Return Values

Returns the DAVector2 object.

Transform

Creates a DAVector2 object that is the result of applying the given transformation to the original vector. The translation elements of the transformation are ignored because translation does not apply to vectors.

vector2Obj.Transform(
xf
)

Parameters
xf
A DATransform2 object.
Return Values

Returns the DAVector2 object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

DAVector2 Properties

Length

LengthSquared

PolarCoordAngle

PolarCoordLength

X

Y

Length

A read-only property with a DANumber value that represents the length of a DAVector2 object.

vector2Obj.Length

See Also

LengthSquared

LengthSquared

A read-only property with a DANumber value that represents the length of a DAVector2 object squared.

vector2Obj.LengthSquared

See Also

Length

PolarCoordAngle

A read-only property with a DANumber value that represents the counter-clockwise angular displacement, in radians, relative to the positive x-axis, of the DAVector2 object. The range is [-Pi, +Pi].

vector2Obj.PolarCoordAngle

PolarCoordLength

A read-only property with a DANumber value that represents the length (or magnitude) of the vector.

vector2Obj.PolarCoordLength

X

A read-only property with a DANumber value that represents the X-coordinate of the DAVector2 object.

vector2Obj.X

See Also

Y, Vector2Anim

Y

A read-only property with a DANumber value that represents the Y-coordinate of the DAVector2 object.

vector2Obj.Y

See Also

X, Vector2Anim

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAVector2.

lib.AddVector2(v1, v2)

lib.DerivativeVector2(vec)

lib.DotVector2(v1, v2)

lib.IntegralVector2(vec)

lib.NegVector2(v1)

lib.SubVector2(v1, v2)

lib.Vector2Anim(x, y)

lib.Vector2(x, y)

lib.Vector2BSpline(degree, knots, control_elements, weights, evaluation)

lib.Vector2PolarAnim(XYangle, length)

lib.Vector2Polar(XYangle, length)

lib.Vector2PolarDegrees(XYangle, length)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAVector2.

lib.XVector2

lib.YVector2

lib.ZeroVector2


DAVector3 Class

Creates a DAVector3 object that represents a three-dimensional vector. At any given time, the value of the vector is a direction and length (magnitude), specified as a triplet of coordinate values given as either Cartesian coordinates (x, y, z) or spherical coordinates (XYangle, YZangle, length). The direction of the vector is parallel to the ray that starts at the origin and passes through the point specified by the vector's coordinates, and the length is the distance between the origin and the point.

Because coordinate values are animated numbers, (DANumber objects), the direction and length of the vector can change over time as the animated numbers change.

This class inherits from the DABehavior Class.

  • DAVector3 Functions
  • DAVector3 Properties
  • Relevant Functions from the DAStatics Class
  • Relevant Properties from the DAStatics Class

DAVector3 Functions

DivAnim

Div

MulAnim

Mul

Normalize

Transform

DivAnim

DAVector3 Class

Creates a DAVector3 object that points in the same direction as the original vector but has a length that has been divided by scalar.

vector3Obj.DivAnim(
scalar
)

Parameters
scalar
A DANumber object used as the divider. This must be an animated number.
Return Values

Returns the DAVector3 object.

See Also

MulAnim

Div

DAVector3 Class

Same as DivAnim except that scalar is a non-animated number (a double).

vector3Obj.Div(
scalar
)

MulAnim

DAVector3 Class

Creates a DAVector3 object that points in the same direction as the original vector but has a length that has been multiplied by scalar.

vector3Obj.MulAnim(
scalar
)

Parameters
scalar
A DANumber object used as the multiplier. This must be an animated number.
Return Values

Returns the DAVector3 object.

See Also

DivAnim

Mul

DAVector3 Class

Same as MulAnim except that scalar is a non-animated number (a double).

vector3Obj.Mul(
scalar
)

Normalize

DAVector3 Class

Creates a normalized DAVector3 object. The normalized vector has the same direction as the original vector, but the length is 1.

vector3Obj.Normalize

Return Values

Returns the DAVector3 object.

Transform

DAVector3 Class

Creates a DAVector3 object that is the result of applying the given transformation to the original vector. The translation elements of the transformation are ignored because translation does not apply to vectors.

vector3Obj.Transform(
xf
)

Parameters
xf
A DATransform3 object.
Return Values

Returns the DAVector3 object.

Remarks

This function composes values. The resulting transformation is the new value applied to the old value.

DAVector3 Properties

Length

LengthSquared

SphericalCoordLength

vector3Obj.SphericalCoordXYAngle

SphericalCoordYZAngle

X

Y

Z

Length

DAVector3 Class

A read-only property with a DANumber value that represents the length of a DAVector3 object.

vector3Obj.Length

See Also

LengthSquared

LengthSquared

DAVector3 Class

A read-only property with a DANumber value that represents the length of a DAVector3 object squared.

vector3Obj.LengthSquared

See Also

Length

SphericalCoordLength

DAVector3 Class

A read-only property with a DANumber value represents the length (or magnitude) of the vector.

vector3Obj.SphericalCoordLength

vector3Obj.SphericalCoordXYAngle

DAVector3 Class

A read-only property with a DANumber value that is the counter-clockwise angle, in radians, of the vector about the y-axis, starting at positive z. The range is [-Pi, +Pi].

vector3Obj.SphericalCoordXYAngle

SphericalCoordYZAngle

DAVector3 Class

A read-only property with a DANumber object that is the YZ angle, in radians, going up from the XZ-plane towards the positive y-ray. The range is [-Pi/2, +Pi/2].

vector3Obj.SphericalCoordYZAngle

X

DAVector3 Class

A read-only property with a DANumber value that represents the X-coordinate of the DAVector3 object.

vector3Obj.X

See Also

Y, Z, Vector3Anim

Y

DAVector3 Class

A read-only property with a DANumber value that represents the Y-coordinate of the DAVector3 object.

vector3Obj.Y

See Also

X, Z, Vector3Anim

Z

DAVector3 Class

A read-only property with a DANumber value that represents the z coordinate of the DAVector3 object.

vector3Obj.Z

See Also

X, Y, Vector3Anim

Relevant Functions from the DAStatics Class

The following functions are defined in the DAStatics class and are most relevant to objects of type DAVector3.

lib.AddVector3(v1, v2)

lib.CrossVector3(v1, v2)

lib.DerivativeVector3(vec)

lib.DotVector3(v1, v2)

lib.IntegralVector3(vec)

lib.NegVector3(v1)

lib.SubVector3(v1, v2)

lib.Vector3Anim(x, y)

lib.Vector3(x, y)

lib.Vector3BSpline(degree, knots, control_elements, weights, evaluation)

lib.Vector3SphericalAnim(XYangle, YZangle, length)

lib.Vector3Spherical(XYangle, YZangle, length)

Relevant Properties from the DAStatics Class

The following properties are defined in the DAStatics class and are most relevant to objects of type DAVector3.

lib.XVector3

lib.YVector3

lib.ZVector3

lib.ZeroVector3


DAViewerControl Class

The DAViewerControl displays a DirectAnimation model in an HTML page. Here is an example of how it is specified:

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:10; top:10;width:450;height:450"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

  • DAViewerControl Subroutines
  • DAViewerControl Properties
  • DAViewerControl Events

DAViewerControl Subroutines

AddBehaviorToRun

Drag

Move

SetFocus

ShowWhatsThis

Start

ZOrder

AddBehaviorToRun

DAViewerControl Class

Adds DABehavior objects that are not a part of the model. When the system starts the model, it retrieves these additional behaviors and runs them with the same start time as the behaviors included in the model.

viewObj.AddBehaviorToRun(
bvr
)

Parameters
bvr
The DABehavior object to add.

As an example, consider the following VBScript sample, which displays the local time as a text value.

<HTML>
<BODY>
<CENTER><INPUT TYPE="TEXT" NAME="txtInp" VALUE=""></CENTER>
<OBJECT ID="DAControl" WIDTH=400 HEIGTH=300
CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</HTML>
</BODY>

<OBJECT ID="DAControl" WIDTH=400 HEIGTH=300
CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>

<SCRIPT LANGUAGE="VBScript">
Sub window_onLoad
   Set m = DAControl.MeterLibrary
   Set timeVal = m.Localtime
   Set timeVal = timeVal.AnimateProperty( "txtInp.value", "VBScript", false, .01 )
   DAControl.AddBehaviorToRun( timeVal )
   DAControl.Start
End Sub
</SCRIPT>

Drag

DAViewerControl Class

Begins, ends, or cancels a drag operation of any object except Line, Menu, Shape, and Timer. For more information, consult a Visual Basic Reference.

controlObj.Drag(
Action
)

Move

DAViewerControl Class

Moves an object. For more information, consult a Visual Basic reference.

controlObj.Move(
left,
[top],
[width],
[height]
)

SetFocus

DAViewerControl Class

Moves the focus to the specified object. For more information, consult a Visual Basic Reference.

controlObj.SetFocus( )

ShowWhatsThis

DAViewerControl Class

Displays a selected topic in a Help file using the What's This popup provided by Windows 95 Help. For more information, consult a Visual Basic reference.

controlObj.ShowWhatsThis( )

Start

DAViewerControl Class

Starts the model.

controlObj.Start( )

ZOrder

DAViewerControl Class

Places a specified object at the front or back of the z-order within its graphical level. For more information, consult a Visual Basic reference.

controlObj.ZOrder(
[Position]
)

DAViewerControl Properties

BackgroundImage

Container

DragIcon

DragMode

Height

HelpContextID

Image

Index

Left

MeterLibrary

Name

Object

Parent

PixelLibrary

Sound

TabStop

Tag

ToolTipText

Top

UpdateInterval

Visible

WhatsThisHelpID

Width

BackgroundImage

DAViewerControl Class

Sets the background image for situations where the browser does not support windowless controls.

controlObj.BackgroundImage

Return Values

Returns a DAImage object.

Container

DAViewerControl Class

Returns the container of an object. For more information, consult a Visual Basic reference.

controlObj.Container

DragIcon

DAViewerControl Class

Returns/sets the icon to be displayed as the pointer in a drag-and-drop operation. For more information, consult a Visual Basic reference.

controlObj.DragIcon

DragMode

DAViewerControl Class

Returns/sets a value that determines whether manual or automatic drag mode is used. For more information, consult a Visual Basic reference.

controlObj.DragMode

Height

DAViewerControl Class

Returns/sets the height of an object. For more information, consult a Visual Basic reference.

controlObj.Height

HelpContextID

DAViewerControl Class

Specifies the default Help file context ID for an object. For more information, consult a Visual Basic reference.

controlObj.HelpContextID

Image

DAViewerControl Class

Establishes the DAImage displayed by the model.

controlObj.Image

Index

DAViewerControl Class

Returns/sets the number identifying a control in a control array. For more information, consult a Visual Basic reference.

controlObj.Index

Left

DAViewerControl Class

Returns/sets the distance between the internal left edge of an object and the left edge of its container. For more information, consult a Visual Basic reference.

controlObj.Left

MeterLibrary

DAViewerControl Class

Sets the unit of measurement to meters and the positive y-axis to up.

controlObj.MeterLibrary

Return Values

Returns the DAStatics object.

See Also

PixelLibrary

Name

DAViewerControl Class

Returns the name used in code to identify an object. For more information, consult a Visual Basic reference.

controlObj.Name

Object

DAViewerControl Class

Returns an object in a control. For more information, consult a Visual Basic reference.

controlObj.Object

Parent

DAViewerControl Class

Returns the object on which this object is located. For more information, consult a Visual Basic reference.

controlObj.Parent

PixelLibrary

DAViewerControl Class

Sets the unit of measurement to pixel and the positive y-axis to down. Pixel measurements are only available for constructing behaviors. When inquiring for a value, the returned measurement is always in meters.

controlObj.PixelLibrary

Return Values

Returns the DAStatics object.

See Also

Pixel, PixelConstructionMode

Sound

DAViewerControl Class

Establishes the sound behavior when the model is displayed.

controlObj.Sound

Return Values

Returns the DASound object.

TabStop

DAViewerControl Class

Returns/sets a value indicating whether a user can use the TAB key to give the focus to an object. For more information, consult a Visual Basic reference.

controlObj.TabStop

Tag

DAViewerControl Class

Stores any extra data needed for your program. For more information, consult a Visual Basic reference.

controlObj.Tag

ToolTipText

DAViewerControl Class

Returns/sets the text displayed when the mouse is paused over the control. For more information, consult a Visual Basic reference.

controlObj.ToolTipText

Top

DAViewerControl Class

Returns/sets the distance between the internal top edge of an object and the top edge of its container.

controlObj.Top

UpdateInterval

DAViewerControl Class

Sets the interval for updating the model, in seconds (a double). Examples of where this property is useful include navigational controls and menu elements, which can use a low update rate.

controlObj.UpdateInterval

Visible

DAViewerControl Class

Returns/sets a value that determines whether an object is visible or hidden. For more information, consult a Visual Basic reference.

controlObj.Visible

WhatsThisHelpID

DAViewerControl Class

Returns/sets an associated context number for an object. For more information, consult a Visual Basic reference.

controlObj.WhatsThisHelpID

Width

DAViewerControl Class

Returns/sets the width of an object. For more information, consult a Visual Basic reference.

controlObj.Width

DAViewerControl Events

DragDrop

DragOver

GotFocus

LostFocus

DragDrop

DAViewerControl Class

Occurs when a drag-and-drop operation is completed. For more information, consult a Visual Basic reference.

controlObj.DragDrop(
source,
x,
y
)

DragOver

DAViewerControl Class

Occurs when a drag-and-drop operation is in progress. For more information, consult a Visual Basic reference.

controlObj.DragOver(
source,
x,
y,
state
)

GotFocus

DAViewerControl Class

Occurs when an object receives the focus. For more information, consult a Visual Basic reference.

controlObj.GotFocus( )

LostFocus

DAViewerControl Class

Occurs when an object loses the focus. For more information, consult a Visual Basic reference.

controlObj.LostFocus( )


Java Reference - Classes and Interfaces

The Microsoft® DirectAnimation™ Java Reference describes each of the DirectAnimation Java methods, including syntax, returned values, and how to use the function. The reference is organized by classes, listed alphabetically.

The Java Reference Introduction describes the organization of the reference.
A
AppTriggeredEvent Class
ArrayBvr Class
B
Bbox2Bvr Class
Bbox3Bvr Class
Behavior Class
BooleanBvr Class
BvrCallback Interface
BvrsToRun Class
C
CameraBvr Class
ColorBvr Class
Cycler Class
D
DashStyleBvr Class
DXMApplet Class
DXMCanvas Class
DXMEvent Class
DXMException Class
E
EndStyleBvr Class
ErrorAndWarningReceiver Interface
EventCallbackObject Interface
F
FontStyleBvr Class
G
GeometryBvr Class
I
ImageBvr Class
J
JoinStyleBvr Class
L
LineStyleBvr Class
M
MatteBvr Class
MicrophoneBvr Class
Model Class
ModelMakerApplet Class
ModifiableBehavior Class
MontageBvr Class
N
NumberBvr Class
P
PairObject Class
Path2Bvr Class
PickableGeometry Class
PickableImage Class
Point2Bvr Class
Point3Bvr Class
Preferences Class
PropertyDispatcher Class
S
SoundBvr Class
Statics Class
StringBvr Class
T
Transform2Bvr Class
Transform3Bvr Class
TupleBvr Class
U
UntilNotifier Interface
V
Vector2Bvr Class
Vector3Bvr Class
Viewer Interface

Defaults

Java Defaults

Event Data

Java Event Data

Hierarchy Chart

Java Hierarchy Chart

Class/Methods Summary

Java Class/Methods Summary


Java Reference Introduction

The DirectAnimation™ Java Reference is organized by classes. For example, there is a section on the ImageBvr class. Each class contains a description of its methods, including syntax, returned values, and how to use the method. At the end of each class, there is a list of methods that, while relevant to that particular class, are included in the Statics library. This library is very large, and it may be easier to familiarize yourself with its contents by looking at specific classes and seeing what Statics functions are pertinent.

This reference is specific to DirectAnimation. For information about methods that are part of a Java package (for example, repaint), consult a Java reference.


AppTriggeredEvent Class

public class AppTriggeredEvent extends DXMEvent {
     // Methods
     public void trigger();
     public void trigger(Behavior eventData);
}

Creates the event. The event can be used in the until and untilNotify methods to create reactive behaviors based on external events.

In the following example, a cube turns from red to blue, based upon some external application event:

//Turn a cube from red to blue when an external event occurs
//The following code is a fragment from a larger program
//Get the cube
GeometryBvr cube = importGeometry(buildURL(geobase, "cube.wrl");
//Create the external event
AppTriggeredEvent appEvent = new AppTriggeredEvent();
//Set up the color of the cube -- red until the event, then blue
ColorBvr col = (ColorBvr)until(red, appEvent, blue);
//Map the color to all points of the cube
GeometryBvr coloredCube = cube.diffuseColor(col);

//...elsewhere, when the application receives the event...
appEvent.trigger();

//...now coloredCube (assuming it's running) will turn blue

AppTriggeredEvent Methods

trigger()
trigger(eventData)

trigger

AppTriggeredEvent Class

Triggers the event.

public void trigger( );

Remarks

The triggered event occurs as soon as possible.

trigger

AppTriggeredEvent Class

Triggers the event and passes the given data to the event handler or notifier.

public void trigger(
Behavior eventData
);

Parameters
eventData
An object that contains any data representing the event.
Remarks

The triggered event occurs as soon as possible.


ArrayBvr Class

public class ArrayBvr extends Behavior {
     // Methods
     public NumberBvr length();
     public Behavior nth(NumberBvr a);

     public static ArrayBvr newUninitBvr(ArrayBvr arr);
}

Selects an object based on a time-varying index. The following example constructs an ArrayBvr out of a Java array and uses the nth method with a time-varying parameter to cycle through the list of colors:

...ColorBvr[] arr = {red, green, blue, yellow, green, cyan, magenta};
ArrayBvr arrBvr = new ArrayBvr(arr);

//Build an indexer to repeatedly go from 0 to (length - 1)
//at a rate of 1 unit per second
NumberBvr indexer = mod(localTime, toBvr(arr.length - 1));

//Use indexer to index into the ArrayBvr
ColorBvr cyclingCol = (ColorBvr)arrBvr.nth(indexer);

...

ArrayBvr Methods

length

nth

newUninitBvr

length

ArrayBvr Class

Finds the length of an array behavior.

public NumberBvr length( );

Return Values

Returns a NumberBvr object that is the length of an array behavior.

nth

ArrayBvr Class

Selects a Behavior object based on the time-varying value of a NumberBvr. It uses the greatest integer value less than the number's value to determine the index. An array's index begins at 0 and any attempt to index beyond its length results in a runtime error.

public Behavior nth(
NumberBvr a
);

Parameters
a
The NumberBvr object used as an index into the array behavior. This parameter can also be of type double.
Return Values

Returns the Behavior object.

newUninitBvr

ArrayBvr Class

Makes it possible to refer to an array behavior before that behavior has been defined. With this method, a behavior can be created and used in the definition of other behaviors, while its contents are defined at some later point. (This definition is accomplished with the init method, which is available on all behaviors.)

public static ArrayBvr newUninitBvr(
ArrayBvr arr
);

Parameters
arr
Used to establish what type the array holds.
Return Values

Returns the ArrayBvr object.


Bbox2Bvr Class

public class Bbox2Bvr extends Behavior {
    //Methods
    public Point2Bvr getMax();
    public Point2Bvr getMin();

    public static Bbox2Bvr newUninitBvr();
}

Creates an object that represents a two-dimensional bounding box behavior. The behavior specifies the lower-left and upper-right corners of a box that encloses the non-transparent portions of an image behavior. Although a bounding box may not always be the smallest bounding box achievable for the image, it is useful for determining the extent or size of the visible portions of the image.

Applications never create bounding box behaviors explicitly. Instead, create these behaviors by calling the boundingBox method in the ImageBvr class.

For more information about behaviors, see the Behavior class.

Bbox2Bvr Methods

getMax

getMin

newUninitBvr

getMax

Bbox2Bvr Class

Creates a two-dimensional point behavior that specifies the upper-right corner of the bounding box.

public Point2Bvr getMax( );

Return Values

Returns the Point2Bvr object.

getMin

Bbox2Bvr Class

Creates a two-dimensional point behavior that specifies the lower-left corner of the bounding box.

public getMin( );

Return Values

Returns the Point2Bvr object.

newUninitBvr

Bbox2Bvr Class

Makes it possible to refer to a two-dimensional bounding box behavior before that behavior has been defined. With this method, it is possible to create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Bbox2Bvr newUninitBvr( );

Return Values

Returns the Bbox2Bvr object.


Bbox3Bvr Class

public class Bbox3Bvr extends Behavior {
    // Methods
    public Point3Bvr getMax();
    public Point3Bvr getMin();

    public static Bbox3Bvr newUninitBvr();

}

Creates an object that represents a three-dimensional bounding box behavior. The behavior specifies the back-lower-left and forward-upper-right corners of a cube that encloses the non-transparent portions of a geometry behavior. Although a bounding box may not always be the smallest bounding box achievable for the geometry, it is useful for determining the extent or size of the visible portions of the geometry.

Applications never create bounding box behaviors explicitly. Instead, these behaviors are created by calling the boundingBox method in the GeometryBvr class.

For more information about behaviors, see the Behavior class.

Bbox3Bvr Methods

getMax

getMin

newUninitBvr();

getMax

Bbox3Bvr Class

Creates a three-dimensional point behavior that specifies the forward-upper-right corner of the bounding box.

public Point3Bvr getMax( );

Return Values

Returns the Point3Bvr object.

See Also

getMin

getMin

Bbox3Bvr Class

Creates a three-dimensional point behavior that specifies the back-lower-left corner of the bounding box.

public Point3Bvr getMin( );

Return Values

Returns the Point3Bvr object.

See Also

getMax

newUninitBvr();

Bbox3Bvr Class

Makes it possible to refer to a three-dimensional bounding box behavior before that behavior has been defined. With this method, it is possible to create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Bbox3Bvr newUninitBvr( );

Return Values

Returns the Bbox3Bvr object.


Behavior Class

public class Behavior extends java.lang.Object {
    // Methods
    public Behavior bvrHook(BvrCallback callback);
    public Behavior debug();
    public Behavior debug(String name);
    public Behavior debug(String name, boolean onStart);
    public Behavior debug(String name, boolean onStart, PrintStream std);
    public Behavior duration(NumberBvr length)
    public Object extract();
    public void init(Behavior a);
    public Behavior repeat(int repetitions);
    public Behavior repeatForever();
    public Behavior runOnce();
    public Behavior substituteTime(NumberBvr a);

}

All behaviors are potentially time-varying and/or reactive values such as colors, numbers and images. They can be used to construct animated objects. All behavior subclasses inherit the methods of this class.

Because all behaviors are potentially time-varying and/or reactive, their values can change as a function of time or as the result of user input. Time-varying behaviors are created by combining time-based default behaviors (such as localTime) with other behaviors. Reactive behaviors are created using the until, untilEx, and untilNotify methods and specifying input events, such as mouse clicks. Complex behaviors can be built by combining existing behaviors. The value of a complex behavior always depends on the values of the behaviors that comprise it.

Behaviors are started either by the createModel method (which means they start at time = 0) or with the untilNotify.notify method, when they are started at the event time. When a behavior runs, its time-varying and reactive qualities are active. This means the user can experience any changes that occur in the behavior as time passes or events occur.

In order to type-check behaviors, all behavior types must be known at construction time. This is why there is no Behavior.newUninitBvr() method included in the Behavior class.

  • Behavior Methods
  • Relevant Methods from the Statics Class

Behavior Methods

bvrHook
debug()
debug(name)
debug(name, onStart)
debug(name, onStart, std)
duration
extract
init
repeat
repeatForever
runOnce
substituteTime

bvrHook

Behavior Class

Allows a running behavior to be sampled.

public Behavior bvrHook(
BvrCallback callback
);

Parameters
callback
The BvrCallback interface containing the notify method.
Return Values

Returns the Behavior object that is the value of the running behavior at the time it was sampled.

See Also

BvrCallback

debug

Behavior Class

Gives the information about a running behavior.

public Behavior debug( );

Remarks

This method gives the following information about a running behavior:

  • An integer number (the ID), which distinguishes each instance of the behavior.
  • The global time that the behavior was started.
  • The value of the behavior at the time it was started.

The method assumes the following defaults:

  • The behavior is unnamed.
  • The information is displayed each time an instance of the behavior is started.
  • The information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior was started at a global time of 39.66 seconds, and had a value of 0.5:

2 started at 39.66 result = 0.5

This method is unavailable to viewers that don't display the standard output.

debug

Behavior Class

Gives information about a running behavior.

public Behavior debug(
String name
);

Parameters
name
The name of the behavior.
Return Values

Returns the Behavior object.

Remarks

This method gives the following information about a running behavior:

  • The name of the behavior.
  • An integer number (the ID), which distinguishes each instance of the behavior.
  • The global time that the behavior was started.
  • The value of the behavior at the time it was started.

The method assumes the following defaults:

  • The information is displayed each time an instance of the behavior is started.
  • The information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

The next example displays a solid-colored image whose red and green components are 1, and whose blue component is time-varying. The NumberBvr x initially has a value of "b" (a value that varies over time). When the left button of the mouse is pressed, "b" (and therefore, "x" starts all over again, with a value of 0.5.

The debugging information (shown in the previous example) is displayed each time the left mouse button is pressed.

import com.ms.dxmedia.*;

public class DebugTest extends DXMApplet{
  public DebugTest() {
    // Set the model
    setModel(new DebugTestModel()) ;
  }
}

class DebugTestModel extends Model {
  public void createModel(BvrsToRun extraBvrsToRun) {
      NumberBvr b = (NumberBvr) add(localTime, toBvr(0.5)).Debug("b");

      NumberBvr x = NumberBvr.newUninitBvr();
      x.init(until(b, leftButtonDown, x));

      ImageBvr model = solidColorImage(colorRgb(toBvr(1), toBvr(1), x));

      setImage(model);
  }
}

This method is unavailable to viewers that don't display the standard output.

debug

Behavior Class

Gives information about a running behavior.

public Behavior debug(
String name,
boolean onStart
);

Parameters
name
The name of the behavior.
onStart
If true, the debug method is called when the behavior is started. If false, the method is called whenever the behavior is sampled. The default is true.
Return Values

Returns the Behavior object.

Remarks

This method gives the following information about a running behavior:

  • The name of the behavior.
  • An integer number (the ID), which distinguishes each instance of the behavior.
  • The global time that the behavior was started or sampled.
  • The local time that the behavior was sampled. (If debug is being called when the behavior is started, then the local time is 0, which is not displayed.)
  • The value of the behavior at the time it was started or sampled.

This method assumes the information is displayed on the standard output.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

This method is unavailable to viewers that don't display the standard output.

debug

Behavior Class

Gives information about a running behavior.

public Behavior debug(
String name,
boolean onStart,
PrintStream std
);

Parameters
name
The name of the behavior.
onStart
If true, the debug method is called when the behavior is started. If false, the method is called whenever the behavior is sampled. The default is true.
std
The output device. The default is the standard output.
Return Values

Returns the Behavior object.

Remarks

This method gives the following information about a running behavior:

  • The name of the behavior.
  • An integer number (the ID), which distinguishes each instance of the behavior.
  • The global time that the behavior was started or sampled.
  • The local time that the behavior was sampled. (If debug is being called when the behavior is started, then the local time is 0, which is not displayed.)
  • The value of the behavior at the time it was started or sampled.

The following example shows that, when it was started, the second instance of a behavior called "b" was started at a global time of 39.66 seconds, and had a value of 0.5:

"b" 2 started at 39.66 result = 0.5

This method is unavailable to viewers that don't display the standard output.

duration

Behavior Class

Creates an animation fragment by associating a local "stop time" with a behavior. The result is a new behavior that is the same as the original behavior for the length of the duration. Once the duration is over, the behavior is a snapshot of the behavior's state when the duration ended.

public Behavior duration(
NumberBvr length
)

Parameters
length
The NumberBvr object representing the length of time, in seconds, that the duration lasts. This parameter can also be of type double.
Return Values

Returns the Behavior object.

extract

Behavior Class

Extracts the value of the behavior, returning a Java object. This behavior must have a constant value.

public Object extract( );

Return Values

Returns a Java object. For more information about java.lang.Object objects, consult a Java reference.

init

Behavior Class

Initializes a behavior created by the newUninit method.

public void init(
Behavior a
)

Parameters
a
The Behavior object to be initialized.

repeat

Behavior Class

Creates a behavior that repeats itself the number of times specified by repetitions.

public Behavior repeat(
int repetitions
);

Parameters
repetitions
The number of times the behavior will repeat.
Return Values

Returns the Behavior object.

repeatForever

Behavior Class

Creates a behavior that repeats infinitely.

public Behavior repeatForever( );

Return Values

Returns the Behavior object.

runOnce

Behavior Class

Used when applications must reference a running behavior once it starts running, but don't require the application to explicitly start that behavior.

public Behavior runOnce( );

Remarks

The following code fragment plays 2 movies. The first movie plays from the beginning for 10 seconds. It then fades, over a 2 second interval, into a second movie. (Assume the existence of a fade method.)

ImageBvr movie1Once = (ImageBvr)movie1.runOnce();
ImageBvr movie2Once = (ImageBvr)movie2.runOnce();
  until(movie1Once,
    timer(toBvr(10)),
      until(fade(div(localTime, toBvr(2)), movie1Once, movie2Once),
        timer(toBvr(2)),
          movie2Once);

substituteTime

Behavior Class

Creates a new behavior from an existing Behavior and a NumberBvr. In the new behavior, the number behavior replaces all occurrences of localTime in the original behavior. (This includes behaviors where localTime is implicit, such as imported movies. The method can be used even if localTime isn't explicitly in the code.)

public Behavior substituteTime(
NumberBvr a
);

Parameters
a
The NumberBvr object that replaces localTime.
Return Values

Returns the Behavior object.

Remarks

This method allows behaviors to be, for example, time-scaled to run faster or slower, time-shifted to start at a different time, or frozen at a particular point in time. Here are some examples:

//A point moving 1 unit in x/second, starting at 0
    b0 = point2(localTime, toBvr(0));

    //Create new behavior moving 0.5 units/second,
    //by replacing localTime with localTime/2
    b1 = origBvr.substituteTime(div(localTime, toBvr(2)));

    //Create new behavior moving 1 unit/second,
    //starting at 33, by replacing localTime with localTime + 33
    b2 = origBvr.substituteTime(add(localTime, toBvr(33));

    //Create new behavior moving 2 units/second, starting at 33,
    //by replacing localTime with (localTime *2) + 33
    b3 = origBvr.substituteTime(add(mul(localTime, toBvr(2)), toBvr(33));

    //Freeze the original behavior at time 77
    b4 = origBvr.substituteTime(toBvr(77));

    //Tie the new behavior to the x-component of the mouse
    b5 = origBvr.substituteTime(mousePosition.getX());

    //Show that replacements are cumulative. The following sequence:
    c0 = point2(localTime, toBvr(0));
    c1 = c0.substituteTime(add(localTime, toBvr(33)));
    c2 = c1.substituteTime(mul(localTime, toBvr(2)));

    //is equivalent to:
    c0.substituteTime(add(mul(localTime, toBvr(2))), toBvr(33));

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Behavior.

public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b);

public static Behavior sequence(Behavior a, Behavior b);

public static Behavior until(Behavior a, DXMEvent e, Behavior b);

public static Behavior untilEx(Behavior a, DXMEvent e);

public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier);


BooleanBvr Class

public class BooleanBvr extends Behavior {

    // Methods
    public Object extract();

    public static BooleanBvr newUninitBvr();

   }

A BooleanBvr is an object that represents a boolean behavior. At any given time, the value of the behavior is either true or false.

For more information about behaviors, see the Behavior class.

  • BooleanBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

BooleanBvr Methods

extract

newUninitBvr();

extract

BooleanBvr Class

Extracts the value of the behavior, returning a Java object. This behavior must have a constant value.

public Object extract( );

Return Values

Returns a Java object. For more information about java.lang.Object objects, consult a Java reference.

newUninitBvr();

BooleanBvr Class

Makes it possible to refer to a boolean behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static BooleanBvr newUninitBvr( );

Return Values

Returns the BooleanBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type BooleanBvr:

public static BooleanBvr and(BooleanBvr b1, BooleanBvr b2);

public static BooleanBvr keyState(int keyCode);

public static BooleanBvr not(BooleanBvr b);

public static BooleanBvr or(BooleanBvr b1, BooleanBvr b2);

public static BooleanBvr toBvr(boolean bool);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type BooleanBvr:

public final static BooleanBvr falseBvr;

public final static BooleanBvr leftButtonState

public final static BooleanBvr rightButtonState

public final static BooleanBvr trueBvr;


BvrCallback Interface

public interface BvrCallback extends java.lang.Object
{
    public abstract Behavior notify(int id, boolean start, double startTime, double globalTime, double localTime, Behavior sampledValue, Behavior currentRunningBvr);
}

BvrCallback Methods

notify

notify

BvrCallback Interface

Calls the notifier method of the object whenever the behavior is started or sampled.

public abstract Behavior notify(
int id,
boolean start,
double startTime,
double globalTime,
double localTime,
Behavior sampledValue,
Behavior currentRunningBvr
);

Parameters
id
Distinguishes one instance of a behavior from another.
start
Determines if the notifier method is called when the behavior starts or each time it is sampled.
startTime
The time the behavior was first run.
globalTime
The time the behavior was sampled, in global time.
localTime
The time the behavior was sampled, in local time. (If the behavior is sampled when it starts, this value is 0).
sampledValue
The value of the behavior at the time it was sampled. This value is wrapped as a constant behavior.
currentRunningBvr
The behavior that is currently running.
Return Values

Returns the Behavior object.


BvrsToRun Class

public class BvrsToRun extends java.lang.Object {
     // Methods
     public int add(Behavior bvrToAdd);
     public void remove (int id);
}

A BvrsToRun object is an abstract list used to explicitly run behaviors that are not part of the model. To add these extra behaviors, use the add method. To remove these behaviors, use the remove method.

These behaviors will either be run at the same time as the behaviors included in the model (local time = 0) or when an event occurs.

An example of running a behavior that is not part of the model is a movie with both an English and a Spanish soundtrack. Perhaps, initially, the English soundtrack is played but the Spanish soundtrack can be selected at any time. This means it must have the same start time as the English soundtrack so that it is also in sync with the movie.

BvrsToRun Methods

add

remove

add

BvrsToRun Class

Adds behaviors that are not a part of the model. When the system starts the model, it retrieves these additional behaviors and runs them with the same start time as the behaviors included in the model.

public int add(
Behavior extraBvrToRun
);

Parameters
extraBvrToRun
The additional behaviors to run.
Return Values

Returns an integer ID that identifies the behavior.

remove

BvrsToRun Class

Removes behaviors that are not a part of the model. To remove a behavior, save the BvrToRun object and use the ID returned by the BvrsToRun.add method.

public void remove (
int id
);

Parameters
id
The integer identifying the added behavior.


CameraBvr Class

public class CameraBvr extends Behavior {
    // Methods
    public CameraBvr depth(NumberBvr d);
    public CameraBvr depthResolution(NumberBvr n);
    public CameraBvr transform(Transform3Bvr xf);

    public static CameraBvr newUninitBvr();
}

Creates an object that represents a camera behavior. A camera is used with the render method to project geometry onto an infinite two-dimensional image. Related operations include rendering it into a microphone to extract the sound, or into a pair of microphones to extract stereo sounds.

There are two basic types of cameras: one for parallel projection and one for perspective projection. Both cameras are oriented so that they gaze in the negative z direction, with positive y considered "up." Also, both cameras have a near clipping plane. This plane (a product of Z-buffered rendering) specifies the closest distance at which an object is visible. Objects closer than the near clipping plane cannot be seen.

Cameras are manipulated via standard three-dimensional transform operations. These transforms modify the camera characteristics and also position and orient the cameras. For more information about these operations, see the transform methods described below.

For more information about behaviors, see the Behavior class.

  • CameraBvr Methods
  • Relevant Methods from the Statics Class

CameraBvr Methods

depth

depthResolution

transform

newUninitBvr

depth

CameraBvr Class

Creates a new camera behavior that is the result of applying the specified depth to the original behavior.

public CameraBvr depth(
NumberBvr d
);

Parameters
d
The NumberBvr object that sets the maximum viewing depth of the CameraBvr. This parameter can also be of type double.
Return Values

Returns the CameraBvr object.

Remarks

By default, cameras have infinite depth, which means that all objects in front of the camera are visible. The new behavior is a CameraBvr whose maximum viewing depth is the NumberBvr depth. If depth < 0, the CameraBvr will be unable to see anything. If you prefer to think in terms of hither and yon, this method sets yon = hither + depth. It is important to note that depth is the limit on the far plane. As with the near plane, the geometry is bounded as tightly as possible for maximum Z-resolution.

Limiting the depth of the camera is useful for preserving depth resolution when using Z-buffered rendering. It is also useful for a camera inside a building, where no viewing region is larger than some value.

depthResolution

CameraBvr Class

Creates a new camera behavior by applying the specified depth resolution (res) to the original behavior.

public CameraBvr depthResolution(
NumberBvr res
);

Parameters
res
The NumberBvr object that sets the minimum depth (in camera coordinates) that is guaranteed to be distinct. This parameter can also be of type double.
Return Values

Returns the CameraBvr object.

Remarks

The Z-buffered rendering approach assigns one depth-value (typically one of 65,536 possibilities) to each pixel on the screen. The res is the minimum distance between two objects such that they still appear distinct. This resolution varies as you go from the near clipping plane to the far clipping plane (more precision is lost for far objects) and according to the amount of perspective for the given camera. This method (assuming a minimum distance to be observed for the entire visible space) adjusts the far clipping plane accordingly.

For example, if the projection point is at (0,0,2), the image clip is at (0,0,1), and the depth resolution (res) is 1cm, then the resultant camera will have a viewing depth of slightly over 25.1 meters. It is important to note that depth represents the limit on the far plane. As with the near plane, the geometry will actually be bounded as tightly as possible for maximum Z-resolution.

transform

CameraBvr Class

Modifies, moves, or orients a camera.

public CameraBvr transform(
Transform3Bvr xf
);

Parameters
xf
The Transform3Bvr object.
Return Values

Returns the CameraBvr object.

Remarks

Cameras are modified, positioned, and oriented via standard transforms. Scale transforms modify the camera while translations and rotations position and orient the camera. The basic steps for using a camera are defining it, modifying it if necessary, and then placing it in the scene.

It is important to note that all camera scales should be applied before camera rotations, and that only scales, rotations, and translations are supported on cameras. Transformations that do not meet these criteria will yield a camera with undefined behavior.

There are two types of scale transformations called Z-scales and X/Y-scales. Z-scales must be positive, non-zero values. Z-scales affect the position of the near clipping plane (if the clipping plane is set to a non-zero value.) For example, if the near clipping plane is located at 10 (that is, if Z=10), then a scale of [1 1 3] will yield a near clipping plane located at Z=30. More importantly, Z-scales move the projection point for a perspective camera. This means an increasing Z-scale yields a perspective camera that is zooming in, and a decreasing Z-scale yields a perspective camera that is zooming out.

Use X/Y-scales to affect the size of the projected image. One way to think of this is that an X/Y-scale sets the size of the camera relative to the world it's viewing. For example, if you are viewing a microscopic scene, use a small X/Y-scale. On the other hand, if you are viewing a solar system, use a large X/Y scale. Scaling a camera by some value in X/Y is exactly equivalent to inversely scaling the resulting image by the same amount. For example, scaling the camera by [10 10 1] is the same as scaling the resulting image by [1/10 1/10]. Finally, disparate scales in X and Y can be used to change the aspect ratio of the rendered image.

Once the camera is defined (via construction and scaling), it can be placed in the scene via rotations and translations just as a light source, microphone, or any other geometric object is placed.

This attribute composes values.

newUninitBvr

CameraBvr Class

Allows you to refer to a camera behavior before that behavior has been defined. With this method you can create a camera behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static CameraBvr newUninitBvr( );

Return Values

Returns the CameraBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type CameraBvr:

public static CameraBvr parallelCamera(NumberBvr nearclip);

public static CameraBvr perspectiveCamera(NumberBvr projdst, NumberBvr nearclip);


ColorBvr Class

public class ColorBvr extends Behavior {

    // Methods
    public NumberBvr getBlue();
    public NumberBvr getGreen();
    public NumberBvr getHue();
    public NumberBvr getLightness();
    public NumberBvr getRed();
    public NumberBvr getSaturation();

    public static ColorBvr newUninitBvr();
}

A ColorBvr is an object that represents a color behavior. At any given time, the value of the behavior is a color value that represents a specific color. Each color value consists of a combination of component values that specify either red, green and blue intensity or hue, saturation, and lightness.

Because component values are number behaviors (NumberBvr objects), the value of the color behavior may change over time as the number behaviors change.

For more information about behaviors, see the Behavior class.

  • ColorBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

ColorBvr Methods

getBlue

getGreen

getHue

getLightness

getRed

getSaturation

newUninitBvr

getBlue

ColorBvr Class

Creates a number behavior that represents the value of the blue component of the corresponding color behavior.

public NumberBvr getBlue( );

Return Values

Returns the NumberBvr object.

See Also

getRed, getGreen

getGreen

ColorBvr Class

Creates a number behavior that represents the value of the green component of the corresponding color behavior.

public NumberBvr getGreen( );

Return Values

Returns the NumberBvr object.

See Also

getRed, getBlue

getHue

ColorBvr Class

Creates a number behavior that represents the value of the hue of the corresponding color behavior.

public NumberBvr getHue( );

Return Values

Returns the NumberBvr object.

See Also

getLightness, getSaturation

getLightness

ColorBvr Class

Creates a number behavior that represents the value of the lightness of the corresponding color behavior.

public NumberBvr getLightness( );

Return Values

Returns the NumberBvr object.

See Also

getHue, getSaturation

getRed

ColorBvr Class

Creates a number behavior that represents the value of the red component of the corresponding color behavior.

public NumberBvr getRed( );

Return Values

Returns the NumberBvr object.

See Also

getGreen, getBlue

getSaturation

ColorBvr Class

Creates a number behavior that represents the value of the saturation of the corresponding color behavior.

public NumberBvr getSaturation( );

Return Values

Returns the NumberBvr object.

See Also

getHue, getLightness

newUninitBvr

ColorBvr Class

This method allows you to refer to a color behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static ColorBvr newUninitBvr( );

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type ColorBvr:

public static ColorBvr colorHsl(NumberBvr h, NumberBvr s, NumberBvr l);

public static ColorBvr colorRgb(NumberBvr r, NumberBvr g, NumberBvr b);

public static ColorBvr colorRgb255(short r, short g, short b);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type ColorBvr:

public final static ColorBvr aqua;

public final static ColorBvr black;

public final static ColorBvr blue;

public final static ColorBvr cyan;

public final static ColorBvr fuchsia;

public final static ColorBvr gray;

public final static ColorBvr green;

public final static ColorBvr lime;

public final static ColorBvr magenta;

public final static ColorBvr maroon;

public final static ColorBvr navy;

public final static ColorBvr olive;

public final static ColorBvr purple;

public final static ColorBvr red;

public final static ColorBvr silver;

public final static ColorBvr teal;

public final static ColorBvr white;

public final static ColorBvr yellow;


Cycler Class

public class Cycler extends java.lang.Object {
    // Constructor
    Cycler(Behavior[] arrToCycleThrough, DXMEvent eventToCycleUpon);

    //Methods
    public Behavior getBvr();

The Cycler object cycles through an array of values when an event occurs. Here is an example that cycles through the colors red, green, blue, yellow, red, green, and so on, each time the left mouse button is pressed:

//Cycle through a series of colors
//Create the array to contain the values
Behavior behavior[4] = {red, green, blue, yellow};
//Construct Cycler object
//Associate values in array with the left mouse button event
Cycler cyl = new Cycler(behaviors, leftButtonDown);
//Set the color equal to the next value in the array
ColorBvr col = (ColorBvr)(cyl.getBvr());

The following example cycles through an array of sounds:

//Create an array of sounds
Behavior[]snds = {snd1, snd2, snd3};
Cycler cycle = new Cycler(snds, leftButtonDown);
SoundBvr currentSnd = (SoundBvr)(cycle.getBvr();
  • Cycler Constructor
  • Cycler Methods

Cycler Constructor

Cycler Class

Creates a cycler object.

Cycler(
Behavior[] arrToCycleThrough,
DXMEvent eventToCycleUpon
);

Parameters
arrToCycleThrough
The array of values cycled through when an event occurs.
eventToCycleUpon
The event that causes the Cycler object to cycle through the array of values.

Cycler Methods

getBvr

getBvr

Cycler Class

Retrieves a Behavior object from the array. The behavior that is returned doesn't itself respond to the provided event. The behavior must be running before the events can have any effect.

public Behavior getBvr( );

Return Values

Returns the Behavior object.


DashStyleBvr Class

public class DashStyleBvr extends Behavior {

   // Methods
   public static DashStyleBvr newUninitBvr();
}

Creates an object that represents a dashstyle behavior. The behavior defines whether lines are drawn using a continuous stroke or a sequence of dashes.

Use the dashstyle behavior with the dash method of the LineStyleBvr object.

For more information about Behaviors see the Behavior class.

  • DashStyleBvr Methods
  • Relevant Fields from the Statics Class

DashStyleBvr Methods

newUninitBvr();

newUninitBvr();

DashStyleBvr Class

This method allows you to refer to a dash-style behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static DashStyleBvr newUninitBvr( );

Return Values

Returns the DashStyleBvr object.

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type DashStyleBvr.

public final static DashStyleBvr dashStyleDashed;

public final static DashStyleBvr dashStyleSolid;


DXMApplet Class

public class DXMApplet extends java.applet.Applet {
    // Constructor
    public DXMApplet();

    // Methods
    public DXMCanvas getCanvas();
    public Model getModel();
    public Model setModel();
    public start();
    public stop();
}

Creates a Java applet for creating and displaying DirectAnimation behaviors. By default, DXMApplet provides its own frameloop which means the applications need not provide one explicitly. It is possible, of course, to do so by overriding the default behavior. Here is an example of using the DXMApplet to view a model called MyModel:

import com.ms.dxmedia.*;

//Create an applet called MyApplet
public class MyApplet extends DXMApplet{
   public class MyApplet() {
   // Set the model
  setModel(new MyModel());
  }
}

// Code fragment for MyModel
class MyModel extends Model {
  // The createModel method is where the animation is constructed
  public void createModel(BvrsToRun extraBvrsToRun) {

    //Whatever MyModel does
          ...
  }
}
  • DXMApplet Constructor
  • DXMApplet Methods
  • Relevant Methods from the Statics Class

DXMApplet Constructor

DXMApplet Class

Creates an DXMApplet object.

public DXMApplet( );

DXMApplet Methods

getCanvas

getModel

setModel

start

stop

getCanvas

DXMApplet Class

Gets a DXMCanvas. This method should only be called if you are implementing your own ticking.

public DXMCanvas getCanvas( );

Return Values

Returns the DXMCanvas object.

getModel

DXMApplet Class

Gets the model that was set by setModel.

public Model getModel( );

setModel

DXMApplet Class

Sets the model that will be used.

public void setModel(
Model model
);

Parameters
model
The model to be set.
Remarks

This method must be called before the model is started. Calling it after the model has started causes an exception.

start

DXMApplet Class

Adds the canvas.

public start( );

stop

DXMApplet Class

Adds the canvas.

public stop( );

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type DXMApplet.

public static ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w)


DXMCanvas Class

public class DXMCanvas extends java.awt.Canvas{
    // Constructor
    public DXMCanvas();

    // Methods from java.awt.Canvas
    public synchronized void addNotify();
    public synchronized boolean handleEvent(Event e);
    public synchronized void hide();
    public void paint(Graphics g);
    public synchronized void removeNotify();
    public synchronized void reshape(int x, int y, int width, int height);
    public synchronized void show();
    public void update(Graphics g);

    //Methods from Runnable Interface
    public void run();

    // Methods from Viewer Interface
    public double getCurrentTime();
    public double getCurrentTickTime();
    public Preferences getPreferences();
    public ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w);
    public void startModel();
    public void stopModel();
    public void tick();
    public synchronized void tick (double timeToUse);

    // Methods
    public synchronized void addModel();
    public synchronized abstract void addModel();
    public Model getModel();
    public synchronized void hideModel();
    public synchronized abstract void hideModel();
    public synchronized void removeModel();
    public synchronized abstract void removeModel();
    public void setModel(Model);
    public synchronized void showModel();
    public synchronized abstract void showModel();
 }

Creates an Java canvas for creating and displaying DirectAnimation behaviors. By default, DXMCanvas provides its own frameloop which means the applications need not provide one explicitly. It is possible, of course, to do so by overriding the default behavior.

  • DXMCanvas Constructor
  • DXMCanvas Methods from java.awt.Canvas
  • DXMCanvas Methods from Runnable Interface
  • DXMCanvas Methods from Viewer Interface
  • DXMCanvas Methods

DXMCanvas Constructor

DXMCanvas Class

Creates an DXMCanvas object.

public DXMCanvas( );

DXMCanvas Methods from java.awt.Canvas

addNotify

handleEvent

hide

paint

removeNotify

reshape

show

update

addNotify

DXMCanvas Class

Overrides the Java implementation and calls the superclass. This method should not be overridden.

public synchronized void addNotify( );

handleEvent

DXMCanvas Class

Overrides the Java implementation and calls the superclass. For more information, see a Java reference.

public synchronized boolean handleEvent(
Event e
);

hide

DXMCanvas Class

Overrides the Java implementation and calls the superclass. This method should not be overridden. For more information, see a Java reference.

public synchronized void hide( );

paint

DXMCanvas Class

Overrides the Java implementation and calls the superclass. For more information, see a Java reference.

public void paint(
Graphics g
);

removeNotify

DXMCanvas Class

Overrides the Java implementation and calls the superclass. This method should not be overridden.

public synchronized void removeNotify( );

reshape

DXMCanvas Class

Overrides the Java implementation and calls the superclass. For more information, see a Java reference.

public synchronized void reshape(
int x,
int y,
int width,
int height
);

show

DXMCanvas Class

Overrides the Java implementation and calls the superclass. This method should not be overridden. For more information, see a Java reference.

public synchronized void show( );

update

DXMCanvas Class

Overrides the Java implementation and calls the superclass. For more information, see a Java reference.

public void update(
Graphics g
);

Parameters
g
The object to be updated.

DXMCanvas Methods from Runnable Interface

run

run

DXMCanvas Class

Implements the Runnable interface to create a background thread for ticking the model. For more information about Runnable, consult a Java reference.

public void run( );

DXMCanvas Methods from Viewer Interface

getCurrentTime
getCurrentTickTime
getPreferences
registerErrorAndWarningReceiver
startModel
stopModel
tick()
tick(timeToUse)

getCurrentTime

DXMCanvas Class

See getCurrentTime in the Viewer Interface.

public double getCurrentTime( );

getCurrentTickTime

DXMCanvas Class

See getCurrentTickTime in the Viewer Interface.

public void getCurrentTickTime( );

getPreferences

DXMCanvas Class

See getPreferences in the Viewer Interface.

public Preferences getPreferences( );

registerErrorAndWarningReceiver

DXMCanvas Class

See registerErrorAndWarningReceiver in the Viewer Interface section.

public ErrorAndWarningReceiver registerErrorAndWarningReceiver(
ErrorAndWarningReceiver w
);

startModel

DXMCanvas Class

See startModel in the Viewer Interface section.

public void startModel( );

stopModel

DXMCanvas Class

See stopModel in the Viewer Interface section.

public void stopModel( );

tick

DXMCanvas Class

See tick in the Viewer Interface section.

public void tick( );

tick

DXMCanvas Class

See tick in the Viewer Interface section.

public synchronized void tick (
double timeToUse
);

DXMCanvas Methods

addModel
addModel - abstract method
getModel
hideModel
hideModel - abstract method
removeModel
removeModel - abstract method
setModel
showModel
showModel - abstract method

addModel

DXMCanvas Class

Creates a background thread to tick the model and calls startModel. To perform manual ticking, override this method.

public synchronized void addModel( );

addModel

DXMCanvas Class

Implement this to override addModel.

public abstract synchronized void addModel( );

getModel

DXMCanvas Class

Gets the model that was set by setModel.

public Model getModel( );

hideModel

DXMCanvas Class

In the default implementation, this method pauses the background thread. This method can be overridden.

public synchronized void hideModel( );

hideModel

DXMCanvas Class

Implement this to override hideModel.

public synchronized abstract void hideModel( );

removeModel

DXMCanvas Class

This method terminates the thread and then calls stopModel. This method can be overridden.

public synchronized void removeModel( );

removeModel

DXMCanvas Class

Implement this to override removeModel.

public synchronized abstract void removeModel

setModel

DXMCanvas Class

Sets the model that will be used.

public void setModel(
Model model
);

Parameters
model
The model to be set.

showModel

DXMCanvas Class

In the default implementation, this method ensures that the thread is resumed. This method can be overridden.

public synchronized void showModel( );

showModel

DXMCanvas Class

Implement this to override showModel.

public synchronized abstract void showModel( );


DXMEvent Class

public class DXMEvent extends Behavior{

    // Constructor
    public DXMEvent();

    // Methods
    public DXMEvent attachData(Object object);
    public DXMEvent notifyEvent(UntilNotifier notifier);
    public Object registerCallback(EventCallbackObject object, BvrsToRun extraBvrsToRun, boolean bool);
    public DXMEvent snapshotEvent(Behavior a);

    public static DXMEvent newUninitBvr();

}

Creates an object that represents an event. Events identify specific times, states or user actions and are used to specify when given actions should occur. Typically, you use events with the until and untilNotify methods to create behaviors that change as a result of the event. For example, you can change the color of an object when the user presses a mouse button by specifying the mouse button event in a call to the until method of the ColorBvr class. Every event, when it occurs, returns some event data. This data may or may not be meaningful. The data returned, for example, by leftButtonDown has no meaning.

You can combine existing events to create new, more complex events. For example, the andEvent method lets you combine two events so that the resulting event occurs only if both of the original events occur simultaneously.

  • DXMEvent Constructor
  • DXMEvent Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

DXMEvent Constructor

DXMEvent Class

Constructs a DXMEvent object.

public DXMEvent( );

DXMEvent Methods

attachData

notifyEvent

registerCallback

snapshotEvent

newUninitBvr

attachData

DXMEvent Class

Takes an arbitrary object and produces a new event. The new event occurs at the same time as the original event, but its data is now the data that was specified in the call to attachData.

public DXMEvent attachData(
Object object
);

Parameters
object
An arbitrary object.
Return Values

Returns a DXMEvent object. The event data is the event data of the new event.

Remarks

This method allows an application to associate arbitrary client data with an event and know that it will be delivered to the notifier when the event occurs. In the following example, the behavior is red until the left mouse button is pressed. It then passes either green or yellow, depending on what is returned by the notifier.

DXMEvent greenLeft = leftButtonDown.attachData(green);
DXMEvent yellowright = rightButtonDown.attachData(yellow);
ColorBvr myBvr = (ColorBvr)untilNotify(red, orEvent(greenLeft, yellowRight), notifier);

notifyEvent

DXMEvent Class

Creates a new event. This occurs when the original event occurs. It then calls the notifier and uses the result as its event data.

public DXMEvent notifyEvent(
UntilNotifier notifier
);

Parameters
notifier
Returns the new behavior.
Return Values

Returns the DXMEvent object. The event data is the time the event fired and the new behavior.

registerCallback

DXMEvent Class

Causes an external action when an event occurs in DirectAnimation for Java and is used in conjunction with the EventCallbackObject. Whenever that event occurs, the invoke method of the callback is called with the event data produced by the event.

public Object registerCallback(
EventCallbackObject object,
BvrsToRun extraBvrsToRun,
boolean bool
);

Parameters
object
An object that implements the EventCallback interface.
extraBvrsToRun
Behaviors that are not part of the model.
bool
If true, the first occurrence of the event will trigger invoke. If false, every occurrence of the event will trigger invoke.
Return Values

Returns an object of type java.lang.Object. This object can be used to unregister the callback.

Remarks

An example of where this method is used is displaying a GUI window when the mouse moves to a particular area.

See Also

unregisterCallback

snapshotEvent

DXMEvent Class

When called on an instance of a behavior, samples the given behavior and returns it as a constant behavior with the value as data. The event time of the new event is when the original event occurs.

public DXMEvent snapshotEvent(
Behavior a
);

Parameters
a
The Behavior object which will be sampled when the method is invoked.
Return Values

Returns the DXMEvent object. The event data is the value of the behavior at the time it was sampled, returned as a constant behavior.

Remarks

In the following example, the value of n is localTime until the left mouse button is pressed. It then becomes whatever the value of localTime was when the event occurred:

n=until(localTime, leftButtonDown.snapshotEvent(localTime));

newUninitBvr

DXMEvent Class

This method allows you to refer to an DXMEvent behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static newUninitBvr( );

Return Values

Returns the DXMEvent object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type DXMEvent.

public static DXMEvent andEvent(DXMEvent first, DXMEvent second);

public static DXMEvent keyDown(int keyCode)

public static DXMEvent keyUp(int keyCode)

public static DXMEvent notEvent(DXMEvent ev);

public static DXMEvent orEvent(DXMEvent first, DXMEvent second);

public static DXMEvent predicate(BooleanBvr bool);

public static DXMEvent thenEvent(DXMEvent e1, DXMEvent e2);

public static DXMEvent timer(NumberBvr timeout);

public static void unregisterCallback(Object object);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type DXMEvent.

public final static DXMEvent always;

public final static DXMEvent leftButtonDown;

public final static DXMEvent leftButtonUp;

public final static DXMEvent never;

public final static DXMEvent rightButtonDown;

public final static DXMEvent rightButtonUp;


DXMException Class

public class DXMException extends java.lang.RuntimeException {
    // Constructor
    public DXMException(int error, String string);

   // Methods
   public int    getErrorCode();
   public String getErrorString();
}

DXMException objects are thrown when any detected error occurs in the DirectAnimation system. They contain a string that should describe the source or the cause of the exception.

  • DXMException Constructor
  • DXMException Methods

DXMException Constructor

DXMException Class

Constructs a DXMException object.

public DXMException(
int error,
String string
);

Parameters
error
A Win32 error code. Consult a Win32 reference for more information.
string
Describes the cause or source of the exception.

DXMException Methods

getErrorCode

getErrorString

getErrorCode

DXMException Class

Extracts the Win32 error code. Consult a Win32 reference for more information.

public int getErrorCode;

Return Values

Returns the integer error code.

getErrorString

DXMException Class

Extracts the error string from the exception.

public String getErrorString( );

Return Values

Returns an error string of type java.lang.String.


EndStyleBvr Class

public class EndStyleBvr extends Behavior {
   // Methods
   public static EndStyleBvr newUninitBvr();
}

Creates an object that represents an endstyle behavior. The behavior defines the style (shape) applied to the end of line segments when drawn.

Use the endstyle behavior with the end method of the LineStyleBvr object.

  • EndStyleBvr Methods
  • Relevant Fields from the Statics Class

EndStyleBvr Methods

newUninitBvr

newUninitBvr

EndStyleBvr Class

This method allows you to refer to an EndStyleBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static EndStyleBvr newUninitBvr( );

Return Values

Returns the EndStyleBvr object.

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type EndStyleBvr.

public final static EndStyleBvr endStyleFlat;

public final static EndStyleBvr endStyleRound;

public final static EndStyleBvr endStyleSquare;


ErrorAndWarningReceiver Interface

public interface ErrorAndWarningReceiver extends java.lang.Object{
    // Methods
    public abstract void handleError(int error, String s, Viewer v);
    public abstract void handleTickError(int error, String s, Viewer v);
    public abstract void handleTickWarning(int error, String s, Viewer v);
    public abstract void handleWarning(int error, String s, Viewer v);
}

This interface, in conjunction with Viewer.registerErrorAndWarningReceiver, allows the application to register an object that will have its methods called when errors and warnings occur in the DirectAnimation system.

ErrorAndWarningReceiver Methods

handleError

handleTickError

handleTickWarning

handleWarning

handleError

ErrorAndWarningReceiver Interface

Invoked when an error occurs outside of the invocation of a tick(). In addition, ticking is halted.

public abstract void handleError(
int error,
String s,
Viewer v
);

Parameters
error
The Win32 error code. Consult a Win32 reference for more information.
s
The error message.
v
The Viewer object on which the warning occurred.

handleTickError

ErrorAndWarningReceiver Interface

Invoked specifically for error messages incurred inside of a tick. In addition, ticking is halted.

public abstract void handleTickError(
int error,
String s,
Viewer v
);

Parameters
error
The Win32 error code. Consult a Win32 reference for more information.
s
The error message.
v
The Viewer object on which the error occurred.

handleTickWarning

ErrorAndWarningReceiver Interface

Invoked specifically for warning messages incurred inside of a tick().

public abstract void handleTickWarning(
int error,
String s,
Viewer v
);

Parameters
error
The Win32 error code. Consult a Win32 reference for more information.
s
The warning message.
v
The Viewer object on which the error occurred.

handleWarning

ErrorAndWarningReceiver Interface

Invoked when a warning occurs outside of the invocation of a tick().

public abstract void HandleWarning(
int error,
String s,
Viewer v
);

Parameters
error
The Win32 error code. Consult a Win32 reference for more information.
s
The warning message.
v
The Viewer object on which the error occurred.


EventCallbackObject Interface

public interface EventCallbackObject extends java.lang.Object{
    public abstract void invoke(Object object, BvrsToRun extraBvrsToRun);
}

Used in conjunction with registerCallback to cause an external action when an event occurs in DirectAnimation for Java. Whenever that event occurs, the invoke method of the callback is called with the event data produced by that event.

EventCallbackObject Methods

invoke

invoke

EventCallbackObject Interface

Used to cause an external action to occur when an event occurs in DirectAnimation for Java.

public abstract void invoke(
Object object,
BvrsToRun extraBvrsToRun
);

Parameters
object
The object to be invoked.
extraBvrsToRun
Behaviors that are not part of the model.


FontStyleBvr Class

public class FontStyleBvr extends Behavior {

    // Methods
    public FontStyleBvr bold();
    public FontStyleBvr color(ColorBvr color);
    public FontStyleBvr family(StringBvr face);
    public FontStyleBvr italic();
    public FontStyleBvr size(NumberBvr points);
    public FontStyleBvr strikethrough();
    public FontStyleBvr textAntialiasing(double antiAliasing);
    public FontStyleBvr underline();
    public FontStyleBvr weight(NumberBvr weight);

    public static FontStyleBvr newUninitBvr();

The FontStyleBvr class is used to specify how strings will be rendered into images. These methods are similar to the HTML tags specifying the font face (called here a family), size, color and attributes (bold and italic).

  • FontStyleBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

FontStyleBvr Methods

bold

color

family

italic

size

strikethrough

textAntialiasing

underline

weight

newUninitBvr

bold

FontStyleBvr Class

Specifies that, when the string is rendered into an image, it will be in bold.

public FontStyleBvr bold( );

Return Values

Returns the FontStyleBvr object.

color

FontStyleBvr Class

Specifies the color of the string when it is rendered into an image. Because this is a ColorBvr object, the color can vary over time.

public FontStyleBvr color(
ColorBvr color
);

Parameters
color
The ColorBvr object specifying the color of the string.
Return Values

Returns the FontStyleBvr object.

family

FontStyleBvr Class

Specifies the font face that will be used when the image is rendered. Because this is a StringBvr object, the face can vary over time.

public static FontStyleBvr family(
StringBvr face
);

Parameters
face
The StringBvr object specifying the font face. This behavior can also be of type java.lang.String.
Return Values

Returns the FontStyleBvr object.

italic

FontStyleBvr Class

Specifies that, when the string is rendered into an image, it will be italicized.

public FontStyleBvr italic( );

Return Values

Returns the FontStyleBvr object.

size

FontStyleBvr Class

Specifies the size of the font, in points. Because this is a NumberBvr object, the size can vary over time. This parameter can also be of type double.

public FontStyleBvr size(
NumberBvr points
);

Parameters
points
The NumberBvr object specifying the size of the font. This parameter can also be of type double.
Return Values

Returns the FontStyleBvr object.

strikethrough

FontStyleBvr Class

Specifies that, when the string is rendered into an image, it will be struck through.

public FontStyleBvr strikethrough( );

Return Values

Returns the FontStyleBvr object.

textAntialiasing

FontStyleBvr Class

Determines whether the text will be antialiased.

public FontStyleBvr textAntialiasing(
double antiAliasing
);

Parameters
antiAliasing
A double that specifies whether or not the text will be antialiased. A 0 (the default value) means there is no antialiasing and a 1 means there is.
Return Values

Returns the FontStyleBvr object.

underline

FontStyleBvr Class

Specifies that, when a string is rendered into an image, it will be underlined.

public FontStyleBvr underline( );

Return Values

Returns the FontStyleBvr object.

weight

FontStyleBvr Class

Specifies the thickness of the boldness of the font. This attribute can be thought of as an animated bold. Note that the font itself will have specific, discrete settings for the different weights. Varying this value will not, therefore, result in a continuous change but in a series of discrete changes. The FontStyleBvr.bold method always overrides this setting.

public FontStyleBvr weight(
NumberBvr weight
);

Parameters
weight
A NumberBvr object that specifies the thickness of the boldness of the font. The value can range from 0 (the thinnest) to 1 (the thickest). This parameter can also be of type double.
Return Values

Returns the FontStyleBvr object.

newUninitBvr

FontStyleBvr Class

This method allows you to refer to a FontStyleBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.)

public static FontStyleBvr newUninitBvr( );

Return Values

Returns the FontStyleBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type FontStyleBvr.

public static FontStyleBvr font(StringBvr face, NumberBvr size, ColorBvr color);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type FontStyleBvr.

public final static FontStyleBvr defaultFont;


GeometryBvr Class

public class GeometryBvr extends Behavior {

    // Constructor
    public GeometryBvr();

    // Methods
    public Bbox3Bvr boundingBox();
    public GeometryBvr diffuseColor(ColorBvr col);
    public GeometryBvr lightAttenuation(NumberBvr const, NumberBvr linear, NumberBvr quadratic);
    public GeometryBvr lightColor(ColorBvr col);
    public GeometryBvr opacity(NumberBvr opac);
    public ImageBvr render(CameraBvr camera);
    public SoundBvr render(MicrophoneBvr mic);
    public GeometryBvr texture(ImageBvr image);
    public GeometryBvr transform(Transform3Bvr xf);
    public GeometryBvr undetectable();

    public static GeometryBvr newUninitBvr();
}

The GeometryBvr class is a class of three-dimensional objects that includes surfaces, lights, sounds, their attributes, and/or combinations of these elements. Like other behaviors, the value of the elements of the geometry can change over time.

In general, every geometry behavior is spatially infinite and of infinite resolution. Conceptually, each of the infinitely many points in the geometry has associated with it an opacity value, a color, a normal (used for lighting computations), a texture coordinate, a detectability value, and a single-channel sound emanating from that point (generally, this is silence).

Surface geometry is either detectable or not. If a surface is detectable, the geometry fires a pick event whenever the cursor passes over a surface point. Neither lights nor sounds are detectable (or pickable).

Light geometries include ambient lights, directional lights, point lights, and spotlights. Light geometries can be attributed with both color and distance attenuation.

A texture in a geometry is an image, the points of which are mapped to the surface of the three-dimensional object represented by the geometry. If there is no surface in the geometry, the texture is ignored.

A geometry can also be a sound. The sound is audible when the geometry is within the appropriate range of a microphone behavior.

The bounding box query is used to construct and compose media, and different types of images and behaviors provide specific bounding boxes. This means, for example, that the bounding box of an image is not defined as the smallest axis-aligned, enclosing region of the non-transparent parts of an image. Instead, bounding boxes are defined on a per-operation basis. The emptyGeometry object, for example, has its own definition of a bounding box, defined below.

For more information about behaviors, see the Behavior class.

  • GeometryBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

GeometryBvr Methods

boundingBox
diffuseColor
lightAttenuation
lightColor
opacity
render(camera)
render(microphone)
texture
transform
undetectable
newUninitBvr

boundingBox

GeometryBvr Class

Creates a bounding box behavior that defines the axis-aligned bounding box enclosing all non-transparent portions of the geometry behavior.

public Bbox3Bvr boundingBox( );

Return Values

Returns the Bbox3Bvr object.

diffuseColor

GeometryBvr Class

Specifies the diffuse color of the new geometry behavior. The diffuse color is the diffuse (or matte) reflective color of the surface.

public GeometryBvr diffuseColor(
ColorBvr col
);

Parameters
col
The ColorBvr object.
Return Values

Returns the GeometryBvr object.

Remarks

By default, the diffuse color is white. The bounding box is the bounding box of the underlying geometry.

This attribute overrides previous values.

lightAttenuation

GeometryBvr Class

Creates a new geometry behavior in which any light sources have the given attenuation. The new attenuation is set to 1 / (const + linear ´ d + quadratic ´ d2) where d is the distance from the light to the object.

public GeometryBvr lightAttenuation(
NumberBvr const,
NumberBvr linear,
NumberBvr quadratic
);

Parameters
const, linear, and quadratic
The NumberBvr objects specifying the attenuation of a light source. These parameters can also be of type double.
Return Values

Returns the GeometryBvr object.

Remarks

By default, the attenuation coefficients are (1, 0, 0), which means no light attenuation. The bounding box is the bounding box of the underlying geometry.

An attenuation of (1, 1, 0) gives a linear attenuation that is useful for light falloff in a room. An attenuation of (1, 0, 1) gives a quadratic attenuation that simulates lights that are in the open, such as street lamps and headlights. This attribute overrides previous values.

lightColor

GeometryBvr Class

Creates a new geometry behavior in which all embedded lights have the specified color.

public GeometryBvr lightColor(
ColorBvr col
);

Parameters
col
The ColorBvr object.
Return Values

Returns the GeometryBvr object.

Remarks

By default, a light source is white. The bounding box is the bounding box of the underlying geometry.

This attribute overrides previous values.

opacity

GeometryBvr Class

Sets the opacity value for all surfaces to the given number behavior. Opacity values can range from 0.0 to 1.0.

public GeometryBvr opacity(
NumberBvr opac
);

Parameters
opac
The NumberBvr object representing the opacity value. The geometry is fully opaque if the value is 1, and fully transparent if the value is 0. This parameter can also be of type double.
Return Values

Returns the GeometryBvr object.

Remarks

If the opac parameter has a value outside the 0.0 to 1.0 range, the integer part of the value is discarded and only the fractional part is used. By default, the opacity is 1.

This attribute composes values. The resulting opacity is the new value times the old value.

render

GeometryBvr Class

Creates an image behavior that is a two-dimensional projection of this geometry behavior. The camera parameter defines how the geometry is projected into two dimensions.

public ImageBvr render(
CameraBvr camera
);

Parameters
camera
The CameraBvr object.
Return Values

Returns the ImageBvr object.

Remarks

The resulting image is infinite in extent. The bounding box of a rendered geometry is the axis-aligned extent of the projection of the three-dimensional bounding box onto the image plane.

render

GeometryBvr Class

Creates a sound behavior that represents the sound associated with this geometry behavior as detected by the given microphone.

public SoundBvr render(
MicrophoneBvr mic
);

Parameters
mic
The MicrophoneBvr object.
Return Values

Returns the SoundBvr object.

texture

GeometryBvr Class

Creates a new geometry behavior by mapping the given image, as defined by the given image behavior, to the surfaces of the original geometry.

public GeometryBvr texture(
ImageBvr image
);

Parameters
image
The ImageBvr object.
Return Values

Returns the GeometryBvr object.

Remarks

If the geometry has no surfaces, the texture is ignored. If the original geometry already has a texture, the new texture completely overlays the original. Texture maps have no effect when applied to a geometry that lacks texture coordinates. By default, a geometry has no texture. The bounding box is the bounding box of the underlying geometry.

This attribute overrides previous values.

transform

GeometryBvr Class

Creates a new geometry behavior that is the result of applying the given three-dimensional transformation to the original geometry behavior.

public GeometryBvr transform(
Transform3Bvr xf
);

Parameters
xf
The Transform3Bvr object.
Return Values

Returns the GeometryBvr object.

Remarks

The transformation applies to all points in the geometry, including those associated with the positions and orientations of light sources, textures, and sounds. The bounding box of a transformed geometry is the axis-aligned box enclosing the box that is the result of applying the transformation to the underlying geometry. The following example rotates a red cube around the y-axis by PI/3 radians:

//Get the cube (assume there is light)
GeometryBvr c0 = import("cube.wrl");
//Color it red
GeometryBvr c1 = c0.diffuseColor(red);
//Rotate it
GeometryBvr c2 = c1.transform(rotate(yVector3, toBvr(Math.PI/3)));

This attribute composes values.

undetectable

GeometryBvr Class

Creates a new undetectable geometry behavior from the original geometry. An undetectable geometry means that, while the geometry is still as visible or as audible as before, any attempts to pick it are ignored.

public GeometryBvr undetectable( );

Return Values

Returns the GeometryBvr object.

Remarks

The undetectable method is useful for specifying which objects are detectable and which are not. For example, suppose a semi-transparent green sphere is used to simulate a glow around an object. Because this sphere encloses the object, the object itself would be unpickable. Instead, the pick information would always be for the sphere. Tagging the sphere as unpickable allows the object itself to be picked. This attribute overrides previous values.

newUninitBvr

GeometryBvr Class

This method allows you to refer to an GeometryBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static GeometryBvr newUninitBvr( );

Return Values

Returns the GeometryBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type GeometryBvr.

public static GeometryBvr importGeometry(URL url);

public static GeometryBvr importGeometry(URL url, GeometryBvr geoStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);

public static GeometryBvr soundSource(SoundBvr sound);

public static GeometryBvr spotLight(NumberBvr fullcone, NumberBvr cutoff);

public static GeometryBvr union(GeometryBvr g1, GeometryBvr g2);

public static GeometryBvr unionArray(GeometryBvr[], geometries);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type GeometryBvr.

public final static GeometryBvr ambientLight;

public final static GeometryBvr directionalLight;

public final static GeometryBvr emptyGeometry;

public final static GeometryBvr pointLight;


ImageBvr Class

public class ImageBvr extends Behavior {

    // Methods
    public Bbox2Bvr boundingBox();
    public ImageBvr clip(MatteBvr matte);
    public ImageBvr clipPolygon(Point2Bvr[] points);
    public ImageBvr crop(Point2Bvr minPt, Point2Bvr maxPt);
    public ImageBvr mapToUnitSquare();
    public ImageBvr opacity(NumberBvr opac);
    public ImageBvr tile();
    public ImageBvr transform(Transform2Bvr xf);
    public ImageBvr undetectable();

    public static ImageBvr  newUninitBvr();

}

Creates an object that represents an image behavior. Much like a bitmap, an image is a two-dimensional picture composed of individual picture elements. Like other behaviors, however, the value of the picture elements can change over time.

Every image behavior consists of an infinite set of two-dimensional points, each representing a picture element and each having color, opacity, and detectability attributes. Colors in an image are defined using color behaviors. Opacity values are number behaviors, and can range in value from 0 through 1, with 0 for fully transparent and 1 for fully opaque. Only points that are "non-transparent" have any visible effect when the image is output or combined with other images.

Points in the image are either detectable or not. If a point is detectable, the image fires a pick event whenever the mouse passes over it.

The bounding box operation is used to construct and compose media, and different types of images and behaviors provide specific bounding boxes. This means, for example, that the bounding box of an image is not defined as the smallest axis-aligned, enclosing region of the non-transparent parts of an image. Instead, bounding boxes are defined on a per-operation basis. This means, for example, that the clipPolygon method has its own definition of a bounding box, defined below.

For more information about behaviors, see the Behavior class.

  • ImageBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

ImageBvr Methods

boundingBox

clip

clipPolygon

crop

mapToUnitSquare

opacity

tile

transform

undetectable

newUninitBvr

boundingBox

ImageBvr Class

Creates a box behavior that defines the box that encloses all non-transparent portions of the image behavior.

public Bbox2Bvr boundingBox( );

Return Values

Returns the Bbox2Bvr object.

clip

ImageBvr Class

Creates a new image behavior by clipping the original image. The new image consists of the portion of the original image that is within the region(s) defined by the given matte behavior.

public ImageBvr clip(
MatteBvr matte
);

Parameters
matte
The MatteBvr object.
Return Values

Returns the ImageBvr object.

Remarks

The bounding box of an image clipped to a matte is the intersection of the matte's bounding box (the axis-aligned box that surrounds the matte), and the bounding box of the underlying image.

clipPolygon

ImageBvr Class

Creates a new image behavior by clipping the original image. The new image consists of the portion of the original image that is within the closed figure defined by the given point behaviors.

public ImageBvr clipPolygon(
Point2Bvr[] points
);

Parameters
points
The Point2Bvr object representing the endpoints of the line segments that define the figure. If the first and last points are not the same, these points are implicitly connected to close the figure.
Return Values

Returns the ImageBvr object.

Remarks

The bounding box is the intersection of the box surrounding the points of the polygon with the box of the underlying image.

crop

ImageBvr Class

Creates a new image behavior by cropping the original image. The new image consists of the portion of the original image that is within the region given by minPt and maxPt.

public ImageBvr crop(
Point2Bvr minPt,
Point2Bvr maxPt
);

Parameters
minPt and maxPt
The Point2Bvr objects representing the lower-left and upper-right corners of the box enclosing the portion of the original image to use.
Return Values

Returns the ImageBvr object.

Remarks

The bounding box of a cropped image is the intersection of the crop box and the box of the underlying image.

mapToUnitSquare

ImageBvr Class

Creates an image that is mapped to the unit square. This is a square at coordinates [(0,0) (1,1)].

public ImageBvr mapToUnitSquare( );

Remarks

This method is commonly used for images that will be textured because a geometry's texture coordinates generally span the unit square. It is also used for transforming an image into a space where it is easy to manipulate.

opacity

ImageBvr Class

Creates an image behavior in which the opacity value for each point is set to the given number behavior.

public ImageBvr opacity(
NumberBvr opac
);

Parameters
opac
The NumberBvr object representing the opacity value. The image is fully opaque if the value is 1, and fully transparent if the value is 0. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

Remarks

By default, an image's opacity is 1. The bounding box is simply the bounding box of the underlying image itself. Opacity values can range from 0.0 to 1.0. If the corresponding number behavior has a value outside this range, the integer part of the value is discarded and only the fractional part is used.

This attribute composes values. The resulting opacity is the new value times the old value.

tile

ImageBvr Class

Creates a new image behavior that consists of the original image tiled (repeated) in all directions. The bounding box is the infinite bounding box.

public ImageBvr tile( );

Return Values

Returns the ImageBvr object.

transform

ImageBvr Class

Creates a new image behavior that is the result of applying the given transformation to the points in the original image behavior.

public ImageBvr transform(
Transform2Bvr xf
);

Parameters
xf
The Transform2Bvr object.
Return Values

Returns the ImageBvr object.

Remarks

As an example, you can double the size of the opaque portion of the image that is the result of applying a transformation that scales by 2. The bounding box of a transformed image is determined by applying the transform to the bounding box of the underlying image and then enclosing the resultant quadrilateral with an axis-aligned box.

This attribute composes values.

undetectable

ImageBvr Class

Creates a new undetectable image behavior from the original image.

public ImageBvr undetectable( );

Return Values

Returns the ImageBvr object.

newUninitBvr

ImageBvr Class

This method allows you to refer to an ImageBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static ImageBvr newUninitBvr( );

Return Values

Returns the ImageBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type ImageBvr.

public static ImageBvr gradientHorizontal(ColorBvr start, ColorBvr stop, NumberBvr fallOff);

public static ImageBvr gradientPolygon(Point2Bvr[] pts, ColorBvr[] colors);

public static ImageBvr gradientSquare(ColorBvr lowerLeft, ColorBvr upperLeft, ColorBvr upperRight, ColorBvr lowerRight);

public static ImageBvr hatchBackwardDiagonal(ColorBvr color, NumberBvr size);

public static ImageBvr hatchCross(ColorBvr color, NumberBvr size);

public static ImageBvr hatchDiagonalCross(ColorBvr color, NumberBvr size);

public static ImageBvr hatchForwardDiagonal(ColorBvr color, NumberBvr size);

public static ImageBvr hatchHorizontal(ColorBvr color, NumberBvr size);

public static ImageBvr hatchVertical(ColorBvr color, NumberBvr size);

public static ImageBvr importImage(URL url);

public static ImageBvr importImage(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);

public static ImageBvr importImageColorKey(URL url, ColorBvr red, ColorBvr green, ColorBvr blue);

public static ImageBvr importImageColorKey(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size, ColorBvr red, ColorBvr green, ColorBvr blue);

public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd);

public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd);

public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd, ImageBvr imgStandIn, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);

public static ImageBvr overlay(ImageBvr i1, ImageBvr i2);

public static ImageBvr overlayArray(ImageBvr[] im);

public static ImageBvr radialGradientPolygon(ColorBvr inner, ColorBvr outer, Point2Bvr[] points, NumberBvr fallOff);

public static ImageBvr radialGradientRegularPoly(ColorBvr inner, ColorBvr outer, NumberBvr edges, NumberBvr fallOff);

public static ImageBvr radialGradientSquare(ColorBvr inner, ColorBvr outer, NumberBvr fallOff);

public static ImageBvr solidColorImage(ColorBvr col);

public static ImageBvr stringImage(StringBvr string, FontStyleBvr font);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type ImageBvr.

public final static ImageBvr detectableEmptyImage;

public final static ImageBvr emptyImage;


JoinStyleBvr Class

public class JoinStyleBvr extends Behavior {

    // Methods
    public static JoinStyleBvr newUninitBvr();

}

Creates an object that represents a joinstyle behavior. The behavior defines the style (shape) of joint between intersecting line segments in a path. A joint is drawn only if the some portions of the segments do not touch or overlap at the common endpoint. In this case, the outside corners of the line segments are connected and the resulting enclosed area is filled with the same color as the line.

You use the endstyle behavior with the join method of the LineStyleBvr object.

  • JoinStyleBvr Methods
  • Relevant Fields from the Statics Class

JoinStyleBvr Methods

newUninitBvr

newUninitBvr

JoinStyleBvr Class

This method allows you to refer to an JoinStyleBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static JoinStyleBvr newUninitBvr( );

Return Values

Returns the JoinStyleBvr object.

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type JoinStyleBvr.

public final static JoinStyleBvr joinStyleBevel;

public final static JoinStyleBvr joinStyleMiter;

public final static JoinStyleBvr joinStyleRound;


LineStyleBvr Class

public class LineStyleBvr extends Behavior {

    //Methods
    public LineStyleBvr color(ColorBvr color);
    public LineStyleBvr detail();
    public LineStyleBvr dash(DashStyleBvr ds);
    public LineStyleBvr end(EndStyleBvr es);
    public LineStyleBvr join(JoinStyleBvr js);
    public LineStyleBvr lineAntialiasing(double antiAliasing);
    public LineStyleBvr width(NumberBvr width);

    public static LineStyleBvr newUninitBvr();

}

Creates an object that represents a linestyle behavior. The behavior defines the various line styles to use when drawing lines. These styles includes the shape of the end of a line, the shape of joints between intersecting lines, the width of the line, and whether the line is drawn with a continuous stroke or as a sequence of dashes.

You use linestyle behaviors with the draw_path2 method of the Path2Bvr class.

  • LineStyleBvr Methods
  • Relevant Fields from the Statics Class

LineStyleBvr Methods

color

dash

detail

end

join

lineAntialiasing

width

newUninitBvr

color

LineStyleBvr Class

Determines the color of a LineStyleBvr object. The default color is black.

public LineStyleBvr color(
ColorBvr color
);

Parameters
color
The ColorBvr object that sets the color of the line. The default color is black..
Return Values

Returns the LineStyleBvr object.

dash

LineStyleBvr Class

Creates a linestyle behavior that is the result of applying the given dashstyle behavior to the existing linestyle. By default, the dashstyle is solid.

public LineStyleBvr dash(
DashStyleBvr ds
);

Parameters
ds
The DashStyleBvr object that represents the dashstyle behavior to apply.
Return Values

Returns the LineStyleBvr object.

detail

LineStyleBvr Class

Creates a detail linestyle behavior from an existing linestyle. A detail linestyle is not changed by image scaling operations. By default, the detailstyle is on. This means it is the default style and it has no width.

public LineStyleBvr detail( );

Return Values

Returns the LineStyleBvr object.

Remarks

Any width or any endstyle or joinstyle behavior associated with the existing linestyle is discarded when creating the new line style.

end

LineStyleBvr Class

Creates a linestyle behavior that is the result of applying the given endstyle to the existing linestyle. By default, the endstyle is flat.

public LineStyleBvr end(
EndStyleBvr es
);

Parameters
es
The EndStyleBvr object that represents the endstyle behavior to apply.
Return Values

Returns the LineStyleBvr object.

join

LineStyleBvr Class

Creates a linestyle behavior that is the result of applying the given joinstyle behavior to the existing linestyle. By default, the joinstyle is beveled.

public LineStyleBvr join(
JoinStyleBvr js
);

Parameters
js
The JoinStyleBvr object that represents the joinstyle behavior to apply.
Return Values

Returns the LineStyleBvr object.

lineAntialiasing

LineStyleBvr Class

Determines whether or not the line will be antialiased.

public LineStyleBvr lineAntialiasing(
double antiAliasing
);

Parameters
antiAliasing
A double that specifies whether or not there will be antialiasing. A 0 (the default value) means there is no antialiasing and a 1 means there is.
Return Values

Returns the FontStyleBvr object.

width

LineStyleBvr Class

Creates a linestyle behavior from an existing linestyle by setting the width of line to the given amount, expressed in points. If the result is a line less than 1 pixel wide, the line will always be a detail line.

public LineStyleBvr width(
NumberBvr width
);

Parameters
width
The NumberBvr object that represents the width of the line, in points. This parameter can also be of type double.
Return Values

Returns the LineStyleBvr object.

Remarks

This attribute overrides detail.

newUninitBvr

LineStyleBvr Class

This method allows you to refer to an LineStyleBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static LineStyleBvr newUninitBvr( );

Return Values

Returns the LineStyleBvr object.

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type LineStyleBvr.

public final static LineStyleBvr defaultLineStyle;


MatteBvr Class

public class MatteBvr extends Behavior {

    // Methods
    public MatteBvr transform(Transform2Bvr xf);

    public static MatteBvr newUninitBvr();
}

Creates an object representing a matte behavior. A matte consists of a path and/or text, and is typically used to clip an image to the shape defined by the path and/or text.

For more information about behaviors, see the Behavior class.

  • MatteBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

MatteBvr Methods

transform

newUninitBvr

transform

MatteBvr Class

Creates a new matte behavior that is the result of applying the given transformation behavior to the original matte. The transformation affects each point behavior in the path that defines the matte.

public MatteBvr transform(
Transform2Bvr xf
);

Parameters
xf
The Transform2Bvr object.
Return Values

Returns the MatteBvr object.

Remarks

This attribute composes values.

newUninitBvr

MatteBvr Class

This method allows you to refer to an MatteBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static MatteBvr newUninitBvr( );

Return Values

Returns the MatteBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type MatteBvr.

public static MatteBvr difference(MatteBvr m1, MatteBvr m2);

public static MatteBvr fillMatte(Path2Bvr path);

public static MatteBvr intersect(MatteBvr m1, MatteBvr m2);

public static MatteBvr textMatte(StringBvr text, FontStyleBvr fs);

public static MatteBvr union(MatteBvr m1, MatteBvr m2);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type MatteBvr.

public final static MatteBvr clearMatte;

public final static MatteBvr opaqueMatte;


MicrophoneBvr Class

public class MicrophoneBvr extends Behavior {

    // Methods
    public MicrophoneBvr transform(Transform3Bvr xf);

    public static MicrophoneBvr newUninitBvr();
}

Creates an object that represents a microphone behavior. A microphone is used with the render method to produce spatialized sound behaviors from sounds embedded in a geometry.

Every microphone has a location and an orientation in a three-dimensional space, and this location determines how a sound is detected. The closer a microphone is to the source of a sound, the louder and sooner the microphone detects that sound. The effect is to "spatialize" the sound, that is, make it seem that it was actually recorded in a three-dimensional space.

For the default microphone, the location is the origin, looking in the negative z-direction, with positive y considered up. You can create new microphones at different locations by using the transform method. Microphones are omnidirectional.

For more information about behaviors, see the Behavior class.

  • MicrophoneBvr Methods
  • Relevant Fields from the Statics Class

MicrophoneBvr Methods

transform

newUninitBvr

transform

MicrophoneBvr Class

Creates a new microphone behavior that is the result of applying the given transformation to the original microphone's location.

public MicrophoneBvr transform(
Transform3Bvr xf
);

Parameters
xf
The Transform3Bvr object.
Return Values

Returns the MicrophoneBvr object.

Remarks

This attribute composes values.

newUninitBvr

MicrophoneBvr Class

This method allows you to refer to an MicrophoneBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static MicrophoneBvr newUninitBvr( );

Return Values

Returns the MicrophoneBvr object.

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type MicrophoneBvr.

public final static MicrophoneBvr defaultMicrophone;


Model Class

public abstract class Model extends Statics
{
    // Constructor
    public Model();

    // Methods
    public ImageBvr getImage();
    public URL getImportBase();
    public SoundBvr getSound();
    public void setImage(ImageBvr im1);
    public void setImportBase(URL url);
    public void setSound(SoundBvr snd);

    public abstract void createModel(BvrsToRun extraBvrsToRun);
}

The model is the set of behaviors actually sampled and displayed for an application. An instance of the Model class must be provided when constructing a DirectAnimation viewer to actually view a behavior. The Model class can also optionally set some model-specific preferences, such as rendering quality. The following example uses several methods included in the Model class to display the familiar phrase, "Hello, World."

class MyModel extends Model {
  // Create the behaviors that will be displayed
  public void createModel(BvrsToRun extraBvrsToRun) {
    FontStyleBvr fs =
    ImageBvr tx = (toBvr("Hello, World"), fs);

    // set the image
    setImage(tx);
  }
}

For more information about behaviors, see the Behavior class.

  • Model Constructor
  • Model Methods

Model Constructor

Model Class

Creates an Model object.

public Model( );

Model Methods

createModel

getImage

getImportBase

getSound

setImage

setImportBase

setSound

createModel

Model Class

Builds the behaviors to be viewed.

public abstract void createModel(
BvrsToRun extraBvrsToRun
);

Parameters
extraBvrsToRun
Behaviors that are not part of the model.
Remarks

Behaviors are run as soon as the model is started, and are all started at time = startTime. The developer implements this method, constructs the behaviors, sets them in the model with setImage and setSound, and returns. It is up to the DirectAnimation system to invoke this method.

getImage

Model Class

Returns the model's image.

public ImageBvr getImage( );

Return Values

Returns the ImageBvr object.

getImportBase

Model Class

Retrieves the current base to use for constructing URLs. If imports occur outside of an instance of Model, the base must be passed.

public URL getImportBase( );

Return Values

Returns the base URL of the image. For more information about java.net.URL objects, consult a Java reference.

Remarks

All paths should be fully qualified rather than relative. For example, instead of using:

//This is wrong
importImage("../im1.jpg")

use:

//This is right
importImage(new URL(getImportBase(), "../im1.jpg"));

getSound

Model Class

Return's the model's sound.

public SoundBvr getSound( );

Return Values

Returns the SoundBvr object.

setImage

Model Class

Establishes the image behavior displayed by DirectAnimation when this model is displayed. Typically called by the model inside of the createModel method provided by the application.

public void setImage(
ImageBvr im1
);

Parameters
im
The ImageBvr object.
Remarks

See the ImageBvr class for information about image behaviors.

setImportBase

Model Class

Sets the default base URL for importing media files. Typically called in the DXMApplet and DXMCanvas classes to set the default base. It can also be explicitly used by the developer to set the default base.

public void setImportBase(
URL url
);

Parameters
url
The default base URL. For more information about java.net.URl objects, consult a Java reference.
See Also

getImportBase.

setSound

Model Class

Establishes the sound behavior displayed by DirectAnimation when this model is displayed. Typically called by the model inside of the createModel method provided by the application.

public void setSound(
SoundBvr snd
);

Parameters
snd
The SoundBvr object.
Remarks

See the SoundBvr class for information about sound behaviors.


ModifiableBehavior Class

public class ModifiableBehavior extends java.lang.Object {
    // Constructor
    public ModifiableBehavior(Behavior initialBvr);

    // Methods
    public Behavior getBvr();
    public void switchTo(Behavior newBvr);
}

Provides an asynchronous method of modifying behaviors, often in response to externally generated application events. It is instanced with the new operator, is given an initial behavior, and results in a new behavior for the caller to use. Here is an example:

//...Create a solid color image somewhere in program.
//It will have a switchable color.
ModifiableBehavior sw = new ModifiableBehavior(red);
ColorBvr col = (ColorBvr)(sw.getBvr());
ImageBvr im = solidColorImage(col);

//...somewhere else in program...
sw.switchTo(blue);

Anywhere that col was used will turn from red to blue. In this example, sw contains an untyped Behavior which the example explicitly casts to a ColorBvr. This is necessary because ColorBvr is the type provided as the input to the construction of sw. Calls to switchTo must carry arguments of the same runtime behavior type as the one with which sw was constructed. The replacement behavior begins as soon after the transition occurs as is possible.

  • ModifiableBehavior Constructor
  • ModifiableBehavior Methods

ModifiableBehavior Constructor

ModifiableBehavior Class

Use the new operator to construct an instance of the ModifiableBehavior class. Supply an initial behavior and a behavior context.

public ModifiableBehavior(
Behavior initialBvr
);

Parameters
initialBvr
The initial behavior.

ModifiableBehavior Methods

getBvr

switchTo

getBvr

ModifiableBehavior Class

Extracts the Behavior component of the ModifiableBehavior object.

public Behavior getBvr( );

Return Values

Returns the Behavior object.

Remarks

This behavior is subject to the switchTo invocations on the ModifiableBehavior object itself.

switchTo

ModifiableBehavior Class

When invoked, replaces the behavior generated by getBvr to the provided behavior.

public void switchTo(
Behavior newBvr
);

Parameters
newBvr
The behavior that is begun once the switchTo method is invoked.
Remarks

Calls to this method must carry arguments of the same runtime behavior type as the one with which the ModifiableBehavior object was constructed. This is an immediate method, which means the new behavior is started when the transition occurs.


ModelMakerApplet Class

public abstract ModelMakerApplet extends java.lang.Object {

    // Constructor
    public ModelMakerApplet();

    // Methods
    public ImageBvr createBackgroundImage();
    public IDABehavior grabBackgroundImageComPtr();
    public IDABehavior grabImageComPtr();
    public IDABehavior grabSoundComPtr();
    public IDAView grabViewComPtr();
    public ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w);
    public synchronized void setModel(Model model);
}

The ModelMakerApplet class is used for constructing models in Java and using them in windowless controls. It is similar to DXMApplet except that it exposes some COM interfaces and doesn't do any ticking (this is performed by the DirectAnimation control called DAViewer). Here is the basic syntax for using ModelMakerApplet:

public class MyTest extends ModelMakerApplet{
    public MyTest() {
     setModel(new testModel());
   }
}

The grabBackgroundImageComPtr, grabImageComPtr, grabSoundComPtr, and grabViewComPtr methods are used on the HTML page, and can be called either from VBScript or JScript. Here is an example of an HTML page that calls these methods, using VBScript:

<HTML>
<HEAD>
<TITLE>myTest Windowless Control</TITLE>
</HEAD>

<body>

<DIV ID=LAYOUT STYLE="position:absolute; left:0; top:0; width:600; height:400">

<DIV ID=text STYLE="position:absolute; left:0; top:0; width:450; height:280">
<FONT SIZE=4 FACE="Verdana,Tahoma,Arial">
This is standard HTML arranged using DIV tags and atop it we're going
to place our DirectX Animation windowless control.
</FONT></DIV>
</DIV>

<DIV ID=controlDiv>
<OBJECT ID="DAViewer"
        STYLE="position:absolute; left:50; top:10;width:200;height:300"
        CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D">
</OBJECT>
</DIV>

</DIV>

' The width and height parameters are placeholders. They need to be there to specify the applet and must be set to 1.

<applet code=myTest.class codebase=. width=1 height=1 id=javaApp>
</applet>

<script language="VBScript">
   sub window_onLoad
       set a = document.javaApp

       ' Get model components out of the Java applet and give it to the
       ' control.
       DAViewer.View            = a.grabViewComPtr
       DAViewer.Image           = a.grabImageComPtr
       DAViewer.BackgroundImage = a.grabBackgroundImageComPtr
       DAViewer.Sound           = a.grabSoundComPtr

       ' Start the control viewing
       DAViewer.Start

   end sub
</script>

</BODY>
</HTML>
  • ModelMakerApplet Constructor
  • ModelMakerApplet Methods

ModelMakerApplet Constructor

ModelMakerApplet Class

Creates an ModelMakerApplet object.

public ModelMakerApplet( );

ModelMakerApplet Methods

createBackgroundImage

grabBackgroundImageComPtr

grabImageComPtr

grabSoundComPtr

grabViewComPtr

registerErrorAndWarningReceiver

setModel

createBackgroundImage

ModelMakerApplet Class

This method is used so that models constructed in Java, intended for windowless controls, will have a background image if they appear in a browser that does not support this feature. The model will then be displayed in its own window, as if it were in a standard DirectAnimation applet. Just as these models need a background image to be explicitly inserted, so do windowless applets if they are to degrade gracefully to a windowed display.

public ImageBvr createBackgroundImage( );

Return Values

Returns the ImageBvr object.

Remarks

This method should be called within ModelMakerApplet and not during the createModel implementation. Here is an example:

public class myTest extends ModelMakerApplet {

  public ImageBvr createBackgroundImage() {
      return Statics.solidColorImage(Statics.black);
  }
      setModel(new testModel());
}

grabBackgroundImageComPtr

ModelMakerApplet Class

Retrieves the background image component of the model. This method is called from a script on the HTML page.

public IDABehavior grabBackgroundImageComPtr( );

Return Values

Returns the COM pointer to the IDABehavior interface (rather than an ImageBvr.)

grabImageComPtr

ModelMakerApplet Class

Retrieves the image component of the model. This method is called from a script on the HTML page.

public IDABehavior grabImageComPtr( );

Return Values

Returns the COM pointer to the IDABehavior interface (rather than an ImageBvr.)

grabSoundComPtr

ModelMakerApplet Class

Retrieves the sound component of the model. This method is called from a script on the HTML page.

public IDABehavior grabSoundComPtr( );

Return Values

Returns the COM pointer to the IDABehavior interface (rather than a SoundBvr.)

grabViewComPtr

ModelMakerApplet Class

Returns the viewer component of the model. This method is called from a script on the HTML page.

public IDAView grabViewComPtr( );

Return Values

Returns the COM pointer to the IDABehavior interface (rather than a Viewer.)

registerErrorAndWarningReceiver

ModelMakerApplet Class

Allows the application to register an object that will have its methods invoked upon asynchronous errors encountered when DirectAnimation media is controlling the frame loop or when recoverable errors occur when sampling and displaying the model.

public ErrorAndWarningReceiver registerErrorAndWarningReceiver(
ErrorAndWarningReceiver w
);

Parameters
w
The ErrorAndWarningReceiver object to be registered.
Return Values

Returns the ErrorAndWarningReceiver object.

setModel

ModelMakerApplet Class

Sets the model that will be used.

public synchronized void setModel(
Model model
);

Parameters
model
The model to be set.
Remarks

This method must be called before the model is started. Calling it after the model has started causes an exception.


MontageBvr Class

public class MontageBvr extends Behavior {

    // Methods
    public ImageBvr render();

    public static MontageBvr newUninitBvr();
}

A MontageBvr is an object that represents a montage behavior. A montage is a stack of images in which each image has an explicit depth. Images with larger Z-values are always in front of images with smaller z-values. Rendering a montage creates a new image behavior that is a composite of the images in the montage. The composite is created by overlaying the montage's images by order of depth and applying the same overlay rules as defined by the overlay method.

Because the depth of an image in a montage can vary over time, rendering the montage at different points in time can produce different the images in different orders.

For more information about behaviors, see the Behavior class.

  • MontageBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

MontageBvr Methods

render

newUninitBvr

render

MontageBvr Class

Creates an image behavior that consists of a composite of all images in the montage behavior.

public ImageBvr render( )

Return Values

Returns the ImageBvr object.

Remarks

The composite is created by overlaying the montage's images in order of Z-values, with the largest Z-value on top, and applying the same overlay rules as defined by the overlay method. If two images have the same depth, they are layered on top of each other in the order in which they were added to the montage. The bounding box of a rendered montage is simply the union of the bounding boxes of all the images comprising that montage.

newUninitBvr

MontageBvr Class

This method allows you to refer to an MontageBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static MontageBvr newUninitBvr( );

Return Values

Returns the MontageBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type MontageBvr.

public static MontageBvr imageMontage(ImageBvr image, NumberBvr depth);

public static MontageBvr union(MontageBvr m1, MontageBvr m2);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type MontageBvr.

public final static MontageBvr emptyMontage;


NumberBvr Class

public class NumberBvr extends Behavior {

    // Methods
    public Object extract();
    public StringBvr toString(double a);
    public StringBvr toString(NumberBvr a);

    public static NumberBvr  newUninitBvr();
}

Creates an object that represents a number behavior. At any given time, the value of the behavior is a floating point number.

For more information about behaviors, see the Behavior class.

  • NumberBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

NumberBvr Methods

extract
toString(double)
toString(NumberBvr)
newUninitBvr

extract

NumberBvr Class

Extracts the value of behavior, returning a Java object. The behavior must have a constant value.

public Object extract( );

Return Values

Returns a Java object. For more information about java.lang.Object objects, consult a Java reference.

toString

NumberBvr Class

Converts a double to a StringBvr.

public StringBvr toString(
double a
);

Parameters
a
The double representing the number of digits to use after the decimal point.
Return Values

Returns the StringBvr object.

toString

NumberBvr Class

Converts a NumberBvr to a StringBvr.

public StringBvr toString(
NumberBvr a
);

Parameters
a
The NumberBvr object representing the number of digits to use after the decimal point.
Return Values

Returns the StringBvr object.

newUninitBvr

NumberBvr Class

This method allows you to refer to an NumberBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static NumberBvr newUninitBvr( );

Return Values

Returns the NumberBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant for objects of type NumberBvr.

public static NumberBvr abs(NumberBvr a);

public static NumberBvr acos(NumberBvr a);

public static NumberBvr add(NumberBvr a, NumberBvr b);

public static NumberBvr asin(NumberBvr a);

public static NumberBvr atan(NumberBvr a);

public static NumberBvr atan2(NumberBvr a, NumberBvr b);

public static NumberBvr bSpline(int degree, NumberBvr[] knots, NumberBvr[] control_elements, NumberBvr[] weights NumberBvr evaluation);

public static NumberBvr ceiling(NumberBvr a);

public static NumberBvr cos(NumberBvr a);

public static NumberBvr degreesToRadians(NumberBvr a);

public static NumberBvr derivative(NumberBvr a);

public static NumberBvr div(NumberBvr a, NumberBvr b);

public static BooleanBvr eq(NumberBvr a, NumberBvr b);

public static NumberBvr exp(NumberBvr a);

public static NumberBvr floor(NumberBvr a);

public static BooleanBvr gt(NumberBvr a, NumberBvr b);

public static BooleanBvr gte(NumberBvr a, NumberBvr b);

public static NumberBvr integral(NumberBvr a);

public static NumberBvr interpolate(NumberBvr from, NumberBvr to, NumberBvr duration);

public static NumberBvr ln(NumberBvr a);

public static NumberBvr log10(NumberBvr a);

public static BooleanBvr lt(NumberBvr a, NumberBvr b);

public static BooleanBvr lte(NumberBvr a, NumberBvr b);

public static NumberBvr mod(NumberBvr a, NumberBvr b);

public static NumberBvr mul(NumberBvr a, NumberBvr b);

public static BooleanBvr ne(NumberBvr a, NumberBvr b);

public static NumberBvr neg(NumberBvr a);

public static NumberBvr pow(NumberBvr a, NumberBvr b);

public static NumberBvr radiansToDegrees(NumberBvr a);

public static NumberBvr round(NumberBvr a);

public static NumberBvr seededRandom(double seed);

public static NumberBvr sin(NumberBvr a);

public static NumberBvr slowInSlowOut(NumberBvr from, NumberBvr to, NumberBvr duration, NumberBvr acceleration)

public static NumberBvr sqrt(NumberBvr a);

public static NumberBvr sub(NumberBvr a, NumberBvr b);

public static NumberBvr tan(NumberBvr a);

public static NumberBvr toBvr(double a);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant for objects of type NumberBvr.

public final static NumberBvr globalTime;

public final static NumberBvr localTime;


PairObject Class

public class PairObject extends java.lang.Object
{
    // Constructor
    public PairObject(Object a, Object b);

    // Methods
    public Object getFirst();
    public Object getSecond();
}

Used in conjunction with the andEvent and the getPickEvent methods. The andEvent method creates a third event from two simultaneously occurring events. It returns a PairObject whose first member is the event data returned by the first event and whose second member is the data returned by the second event. The getPickEvent method returns a PairObject whose first member is the point of intersection and whose second member is a vector that is perpendicular to the surface. Note that, unlike arrays, a PairObject can contain two objects of different types.

  • PairObject Constructor
  • PairObject Methods

PairObject Constructor

PairObject Class

Constructs a PairObject object. Note that this is not a behavior.

public PairObject(
Object a,
Object b
);

Parameters
a
The first member of the PairObject.
b
The second member of the PairObject.

PairObject Methods

getFirst

getSecond

getFirst

PairObject Class

Returns the first object of the PairObject.

public Object getFirst( );

Return Values

Returns the object that is the first member of the PairObject.

getSecond

PairObject Class

Returns the second object of the PairObject.

public Object getSecond( );

Return Values

Returns the object that is the second member of the PairObject.


Path2Bvr Class

public class Path2Bvr extends Behavior {

    // Methods
    public Bbox2Bvr boundingBox(LineStyleBvr style);
    public Path2Bvr close();
    public ImageBvr draw(LineStyleBvr ls);
    public ImageBvr fill(LineStyleBvr ls, ImageBvr im );
    public Path2Bvr transform(Transform2Bvr xf);

    public static Path2Bvr newUninitBvr();

}

Creates an object that represents a path behavior for two-dimensional space. A path behavior consists of a sequence of two-dimensional point behaviors and is typically used to draw images consisting of line segments or to define borders for geometric shapes.

For more information about behaviors, see the Behavior class.

  • Path2Bvr Methods
  • Relevant Methods from the Statics Class

Path2Bvr Methods

boundingBox

close

draw

fill

transform

newUninitBvr

boundingBox

Path2Bvr Class

Creates a Path2Bvr object that is a visible bounding box.

public Bbox2Bvr boundingBox(
LineStyleBvr style
);

Parameters
style
The LineStyleBvr object that defines the line style of the path. This argument is ignored. The linestyle is always the default linestyle and has a width of 0.
Return Values

Returns the Path2Bvr object.

close

Path2Bvr Class

Adds a line segment from the end of the path to the start. This method is useful for animating closed regions.

public Path2Bvr close( );

Return Values

Returns the Path2Bvr object.

draw

Path2Bvr Class

Renders the Path2Bvr object into an ImageBvr object. The image is unfilled, which means only the outline is rendered.

public ImageBvr draw(
LineStyleBvr ls
);

Parameters
ls
The LineStyleBvr used to render the image.
Return Values

Returns the ImageBvr object.

fill

Path2Bvr Class

Renders the Path2Bvr object into an ImageBvr object. The ls argument specifies the LineStyleBvr that is used to draw the outline. The im parameter specifies the image used to fill in the new ImageBvr object.

public ImageBvr fill(
LineStyleBvr ls,
ImageBvr im );

Parameters
ls
The LineStyleBvr object used to draw the path.
im
The ImageBvr object used as the fill pattern.
Return Values

Returns the ImageBvr object.

transform

Path2Bvr Class

Creates a new path behavior that is the result of applying the given transformation behavior to the points in the original path behavior.

public Path2Bvr transform(
Transform2Bvr xf
);

Parameters
a
The Transform2Bvr object representing the transformation to apply to the original path.
Return Values

Returns the Path2Bvr object.

Remarks

This attribute composes values.

newUninitBvr

Path2Bvr Class

This method allows you to refer to an Path2Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Path2Bvr newUninitBvr( );

Return Values

Returns the Path2Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant for objects of type Path2Bvr.

public static Path2Bvr arc(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight);

public static Path2Bvr arcDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight);

public static Path2Bvr concat(Path2Bvr p1, Path2Bvr p2);

public static Path2Bvr concatArray(Path2Bvr[] paths);

public static Path2Bvr cubicBSplinePath(Point2Bvr[], NumberBvr[]);

public static Path2Bvr line(Point2Bvr p1, Point2Bvr p2);

public static Path2Bvr oval(NumberBvr width, NumberBvr height)

public static Path2Bvr pie(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight);

public static Path2Bvr pieDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight);

public static Path2Bvr polydrawPath(Point2Bvr[] points, NumberBvr[] codes);

public static Path2Bvr polyline(Point2Bvr[] points);

public static Path2Bvr ray(Point2Bvr p);

public static Path2Bvr rect(NumberBvr width, NumberBvr height);

public static Path2Bvr roundRect(NumberBvr width, NumberBvr height, NumberBvr arcWidth, NumberBvr arcHeight);

public static Path2Bvr stringPath(StringBvr string, FontStyleBvr fs);


PickableGeometry Class

public class PickableGeometry extends java.lang.Object {
    // Constructor
    public PickableGeometry(GeometryBvr geo);

    // Method
    public GeometryBvr getGeometryBvr();
    public DXMEvent getPickEvent();
}

Creates an object representing a pickable geometry behavior. The behavior is identical to a geometry behavior except that an event occurs whenever the mouse pointer is "in" the geometry.

Applets typically use the event returned by the getPickEvent method to set an event handler or to create a reactive behavior with the until or untilNotify method.

When the pick event occurs, the event data is a PairObject object. The first element is a Point3Bvr object representing the intersection point, and the second element is a Vector3Bvr object that is a time-varying vector. The vector gives the model-coordinate offset to the point that (from the camera's image plane) is in the plane perpendicular to the viewing direction, and is under the two-dimensional mouse's location.

  • PickableGeometry Constructor
  • PickableGeometry Methods

PickableGeometry Constructor

PickableGeometry Class

Creates a pickable GeometryBvr object.

public PickableGeometry(
GeometryBvr geo
);

Parameters
geo
A new instance of a GeometryBvr that is pickable.

PickableGeometry Methods

getGeometryBvr

getPickEvent

getGeometryBvr

PickableGeometry Class

Returns the GeometryBvr object.

public GeometryBvr getGeometryBvr( );

Return Values

Returns the GeometryBvr object.

getPickEvent

PickableGeometry Class

Creates an event for the pickable geometry behavior.

public DXMEvent getPickEvent( );

Return Values

Returns a DXMEvent object. Its data is a PairObject. The first member is the intersection point that is in the plane perpendicular to the viewing direction and is under the mouse. The second member is a time-varying vector that gives the model-coordinate offset to the intersection point. Each sample taken while the mouse is over the object returns a new point and a new time-varying vector. Each time-varying vector tracks the mouse, relative to the associated intersection point.

Remarks

Use this event to set an event handler or create a reactive behavior with the until or untilNotify method.


PickableImage Class

public class PickableImage extends java.lang.Object {
    // Constructor
    public PickableImage(ImageBvr im);

    // Methods
    public ImageBvr getImageBvr();
    public DXMEvent getPickEvent();
}

Creates an object representing a pickable image behavior. The behavior is identical to an image behavior except that an event occurs whenever the mouse pointer is "in" the image.

Applets typically use the event returned by the getPickEvent method to set an event handler or to create a reactive behavior with the until or untilNotify method.

When the pick event occurs, the event data is a DXMEvent object. The first element is a Point2Bvr object representing the intersection point, and the second element is a Vector2Bvr object that is perpendicular to the surface.

  • PickableImage Constructor
  • PickableImage Methods

PickableImage Constructor

PickableImage Class

Creates a pickable ImageBvr object that, depending on the value of bool, either is or is not pickable when there are other images between it and the mouse.

public PickableImage(
ImageBvr im,
bool
);

Parameters
im
A new instance of the ImageBvr that is pickable.
bool
Determines whether the image is pickable where occluded. (This means that the pickable image will still get the pick event even if the mouse is on an occluding image.) The default is false, which means the image is not pickable where occluded. It isn't necessary to include the false value in the arguments. If true, the image is pickable where occluded. The true value must be included in the argument list.

PickableImage Methods

getImageBvr

getPickEvent

getImageBvr

PickableImage Class

Returns the ImageBvr object.

public ImageBvr getImageBvr( );

Return Values

Returns the ImageBvr object.

getPickEvent

PickableImage Class

Creates an event for the pickable image behavior.

public DXMEvent getPickEvent( );

Return Values

Returns a DXMEvent object. Its data is a PairObject. The first member is the intersection point that is in the plane perpendicular to the viewing direction and is under the mouse. The second member is a time-varying vector that gives the model-coordinate offset to the intersection point. Each sample taken while the mouse is over the object returns a new point and a new time-varying vector. Each time-varying vector tracks the mouse, relative to the associated intersection point.

Remarks

Use this event to set an event handler or create a reactive behavior with the until or untilNotify method.


Point2Bvr Class

public class Point2Bvr extends Behavior {

    // Methods
    public NumberBvr  getPolarCoordLength();
    public NumberBvr  getPolarCoordAngle();
    public NumberBvr  getX();
    public NumberBvr  getY();
    public Point2Bvr  transform(Transform2Bvr xf);

    public static Point2Bvr  newUninitBvr();
}

Creates an object that represents a two-dimensional point behavior. At any given time, the value of the behavior is a point, representing a location in a plane or on the screen. Each point has a pair of coordinate values that define the point's location relative to a fixed point called the origin. These coordinate values are given as either Cartesian coordinates (x,y) or polar coordinates (XY angle,length) when the point behavior is created.

Because coordinate values are number behaviors (NumberBvr objects), the location of a point behavior may change over time as the number behaviors change. For more information about behaviors, see the Behavior class and the Point3Bvr class.

  • Point2Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Point2Bvr Methods

getPolarCoordAngle

getPolarCoordLength()

getX

getY

transform

newUninitBvr

getPolarCoordAngle

Point2Bvr Class

Creates a number behavior that represents the counter-clockwise angular displacement, in radians, relative to the positive x-axis, of the point behavior. The range is [-Pi, +Pi].

public NumberBvr getPolarCoordAngle( );

Return Values

Returns the NumberBvr object.

See Also

getPolarCoordLength, point2Polar

getPolarCoordLength()

Point2Bvr Class

Creates a number behavior that represents the length (or magnitude) of the vector.

public NumberBvr getPolarCoordLength( );

Return Values

Returns the NumberBvr object.

See Also

getPolarCoordAngle, point2Polar

getX

Point2Bvr Class

Creates a number behavior that represents the x coordinate of this point behavior.

public NumberBvr getX( );

Return Values

Returns the NumberBvr object.

See Also

getY, point2

getY

Point2Bvr Class

Creates a number behavior that represents the y coordinate of this point behavior.

public NumberBvr getY( );

Return Values

Returns the NumberBvr object.

See Also

getX, point2

transform

Point2Bvr Class

Creates a new two-dimensional point behavior that is the result of applying the given transformation to the original point behavior.

public Point2Bvr transform(
Transform2Bvr xf
);

Parameters
xf
The Transform2Bvr object.
Return Values

Returns the Point2Bvr object.

Remarks

This attribute composes values.

newUninitBvr

Point2Bvr Class

This method allows you to refer to an Point2Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Point2Bvr newUninitBvr( );

Return Values

Returns the Point2Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Point2Bvr.

public static Point2Bvr add(Point2Bvr pt, Vector2Bvr vec);

public static Point2Bvr bSpline(int degree, NumberBvr[] knots, Point2Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);

public static Vector2Bvr derivative(Point2Bvr pt);

public static NumberBvr distance(Point2Bvr p1, Point2Bvr p2);

public static NumberBvr distanceSquared(Point2Bvr p1, Point2Bvr p2);

public static Point2Bvr point2(NumberBvr x, NumberBvr y);

public static Point2Bvr point2Polar(NumberBvr XYangle, NumberBvr length);

public static Vector2Bvr sub(Point2Bvr p1, Point2Bvr p2);

public static Point2Bvr sub(Point2Bvr pt, Vector2Bvr vec);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Point2Bvr.

public final static Point2Bvr mousePosition;

public final static Point2Bvr origin2;


Point3Bvr Class

public class Point3Bvr extends Behavior {

    // Methods
    public NumberBvr getSphericalCoordLength();
    public NumberBvr getSphericalCoordXYAngle();
    public NumberBvr getSphericalCoordYZAngle();
    public NumberBvr getX();
    public NumberBvr getY();
    public NumberBvr getZ();
    public Point2Bvr project(CameraBvr camera)
    public Point3Bvr transform(Transform3Bvr xf);

    public static Point3Bvr  newUninitBvr();
}

Creates an object that represents a three-dimensional point behavior. At any given time, the value of the behavior is a point, representing a location in a three-dimensional space. Each point has a triplet of coordinate values that define the point's location relative to a fixed point called the origin. These coordinate values are given as either Cartesian coordinates (x,y, z) or spherical coordinates (XY angle,YZ angle,length) when the point behavior is created.

Because coordinate values are number behaviors (NumberBvr objects), the location of a point behavior may change over time as the number behaviors change. For more information about behaviors, see the Behavior class and the Point2Bvr class.

  • Point3Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Point3Bvr Methods

getSphericalCoordLength

getSphericalCoordXYAngle

getSphericalCoordYZAngle

getX

getY

getZ

project

transform

newUninitBvr

getSphericalCoordLength

Point3Bvr Class

Returns the NumberBvr object that represents the length (or magnitude) of the vector.

public NumberBvr getSphericalCoordLength( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordXYAngle, getSphericalCoordYZAngle, point3Spherical

getSphericalCoordXYAngle

Point3Bvr Class

Returns the NumberBvr object that should more properly be thought of as an XZ angle. For positive values, it is the counter-clockwise angle, in radians, of the point in the XZ plane. When the angle is 0, the point lies on the z-axis. The range is [-Pi, +Pi].

public NumberBvr getSphericalCoordXYAngle( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordYZAngle, getSphericalCoordLength, point3Spherical

getSphericalCoordYZAngle

Point3Bvr Class

Returns the NumberBvr object that should more properly be thought of as an XY angle. For positive values, it is the counter-clockwise angle, in radians, going from the XZ-plane towards the positive y-ray. When the angle is 0, the point lies on the x-axis. The range is [-Pi/2, +Pi/2].

public NumberBvr getSphericalCoordYZAngle( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordXYAngle, getSphericalCoordLength, point3Spherical

getX

Point3Bvr Class

Creates a number behavior that represents the x coordinate of this point behavior.

public NumberBvr getX( );

Return Values

Returns the NumberBvr object.

See Also

getY, getZ, point3

getY

Point3Bvr Class

Creates a number behavior that represents the y coordinate of this point behavior.

public NumberBvr getY( );

Return Values

Returns the NumberBvr object.

See Also

getX, getZ, point3

getZ

Point3Bvr Class

Creates a number behavior that represents the z coordinate of this point behavior.

public NumberBvr getZ( );

Return Values

Returns the NumberBvr object.

See Also

getX, getY, point3

project

Point3Bvr Class

Returns the two-dimensional point behavior of the projection of the three-dimensional point onto the image plane, via the given camera behavior.

public Point2Bvr project(
CameraBvr camera
);

Parameters
camera
The CameraBvr object projecting the three-dimensional point onto the image plane.
Return Values

Returns the Point2Bvr object.

transform

Point3Bvr Class

Creates a new three-dimensional point behavior that is the result of applying the given transformation to the original point behavior.

public Point3Bvr transform(
Transform3Bvr xf
);

Parameters
xf
The Transform3Bvr object.
Return Values

Returns the Point3Bvr object.

Remarks

This attribute composes values.

newUninitBvr

Point3Bvr Class

This method allows you to refer to an Point3Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Point3Bvr newUninitBvr( );

Return Values

Returns the Point3Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Point3Bvr.

public static Point3Bvr add(Point3Bvr pt, Vector3Bvr vec);

public static Point3Bvr bSpline(int degree, NumberBvr[] knots, Point3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);

public static Vector3Bvr derivative(Point3Bvr pt);

public static NumberBvr distance(Point3Bvr p1, Point3Bvr p2);

public static NumberBvr distanceSquared(Point3Bvr p1, Point3Bvr p2);

public static Point3Bvr point3(NumberBvr x, NumberBvr y, NumberBvr z);

public static Point3Bvr point3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length);

public static Vector3Bvr sub(Point3Bvr p1, Point3Bvr p2);

public static Point3Bvr sub(Point3Bvr pt, Vector3Bvr vec);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Point3Bvr.

public final static Point3Bvr origin3;


Preferences Class

public class Preferences extends java.lang.Object{

    // Fields
    public final static String COLOR_KEY_BLUE;
    public final static String COLOR_KEY_GREEN;
    public final static String COLOR_KEY_RED;
    public final static String DITHERING;
    public final static String ENGINE_OPTIMIZATIONS;
    public final static String FILL_MODE;
    public final static int    FILL_MODE_POINT;
    public final static int    FILL_MODE_SOLID;
    public final static int    FILL_MODE_WIREFRAME;
    public final static String MAX_FRAMES_PER_SEC;
    public final static String OVERRIDE_APPLICATION_PREFERENCES;
    public final static String PERSPECTIVE_CORRECT;
    public final static String RGB_LIGHTING_MODE;
    public final static String SHADE_MODE;
    public final static int    SHADE_MODE_FLAT;
    public final static int    SHADE_MODE_GOURAUD;
    public final static int    SHADE_MODE_PHONG;
    public final static String TEXTURE_QUALITY;
    public final static int    TEXTURE_QUALITY_LINEAR;
    public final static int    TEXTURE_QUALITY_NEAREST;
    public final static String USE_VIDEOMEM;
    public final static String USE_3-D_HW;

    // Constructor
    public Preferences();

   // Methods
   public boolean getBoolean(String preference);
   public double getDouble(String preference);
   public int getInt(String preference);
   public String getString(String preference);
   public void propagate();
   public void set(String preference, boolean value);
   public void set(String preference, double value);
   public void set(String preference, int value);
   public void set(String preference, String value);
}

A Preferences object controls various model qualities (such as texturing and shading) and hardware preferences. The object contains methods both for setting and retrieving these values. Each preference is identified with a string and its value is set by either a boolean, an integer, or a double. Before getting or setting a preference, first obtain the Preference object with the Viewer.getPreferences method.

The first time DirectAnimation is run, it establishes the default preferences in the registry. This means the end-user can control what the default preference settings are. When the Viewer.getPreferences method is invoked, the Preferences object contains these settings. These settings can be overridden by calling the set() methods on the Preferences object.

A preference called OVERRIDE_APPLICATION_PREFERENCES allows the end-user to decide if a canvas or applet can override the other preferences. If it is TRUE, then explicitly setting the Preferences object will have no effect.

  • Preferences Constructor
  • Preferences Methods
  • Preferences Fields

Preferences Constructor

Preferences Class

Constructs an Preferences object.

public Preferences( );

Preferences Methods

getBoolean
getDouble
getInt
getString
propagate
set(preference, boolean)
set(preference, double)
set(preference, int)
set(preference, string)

getBoolean

Preferences Class

Returns the value of those preferences that are set by booleans.

public boolean getBoolean(
String preference
);

Parameters
preference
The name of the preference.
Return Values

Returns a boolean. For more information about booleans, consult a Java reference.

getDouble

Preferences Class

Returns the value of those preferences that are set by a double.

public double getDouble(
String preference
);

Parameters
preference
The name of the preference.
Return Values

Returns a double. For more information about doubles, consult a Java reference.

getInt

Preferences Class

Returns the value of those preferences that are set by an integer.

public int getInt(
String preference
);

Parameters
preference
The name of the preference.
Return Values

Returns an integer. For more information about integers, consult a Java reference.

getString

Preferences Class

Returns the name of a preference.

public String getString(
String preference
);

Parameters
preference
The name of the preference.
Return Values

Returns the value of those preferences that are set by a string. For more information about strings, consult a Java reference.

propagate

Preferences Class

Tells the system to use the new preferences. Use after calling Viewer.getPreferences and the Preference.set() methods but before the model is running.

public void propagate( );

set

Preferences Class

Sets the value of those preferences that are determined by booleans.

public void set(
String preference,
boolean value
);

Parameters
preference
The name of the preference.
value
The value of the preference.

set

Preferences Class

Sets the value of those preferences that are determined by doubles.

public void set(
String preference,
double value
);

Parameters
preference
The name of the preference.
value
The value of the preference.

set

Preferences Class

Sets the value of those preferences that are determined by integers.

public void set(
String preference,
int value
);

Parameters
preference
The name of the preference.
value
The value of the preference.

set

Preferences Class

Sets the value of those preferences that are determined by strings.

public void set(
String preference,
String value
);

Parameters
preference
The name of the preference.
value
The value of the preference.

Preferences Fields

public final static String COLOR_KEY_BLUE
Determines the value of the blue RGB component. The value is set by an integer that can range from 0 to 255. The default value is 245.
public final static String COLOR_KEY_GREEN
Determines the value of the green RGB component. The value is set by an integer that can range from 0 to 255. The default value is 254.
public final static String COLOR_KEY_RED
Determines the value of the red RGB component. The value is set by an integer that can range from 0 to 255. The default value is 1.
public final static String DITHERING
Determines whether or not dithering is enabled. The value is set by a boolean. The default mode is Enabled.
public final static String ENGINE_OPTIMIZATIONS
Determines whether or not there will be optimizations. Optimizations include such things as image caching and dirty rectangle optimization. The value is set by a boolean. The default value is On.
public final static String FILL_MODE
Determines the fill mode, which can be FILL_MODE_POINT, FILL_MODE_SOLID, or FILL_MODE_WIREFRAME. The value is set by an integer. The default mode is Solid.
public final static int FILL_MODE_POINT
Sets the fill mode to point.
public final static int FILL_MODE_SOLID
Sets the fill mode to solid. This is the default mode.
public final static int FILL_MODE_WIREFRAME
Sets the fill mode to wireframe.
public final static String OVERRIDE_APPLICATION_PREFERENCES
A boolean value that, if true, means the registry overrides any attempts by the application to set preferences. This value cannot be set. It can only be retrieved with getBoolean. The default value is Off.
public final static String PERSPECTIVE_CORRECT
Determines whether or not texturing will be adjusted for perspective. The value is set by a boolean. The default mode is On.
public final static MAX_FRAMES_PER_SEC
Determines the maximum number of frames per second. The value is set by a double. The default value is 30.
public final static String RGB_LIGHTING_MODE
Determines whether or not the lighting mode is RGB. The value is set by a boolean. The default value is On.
public final static String SHADE_MODE
Determines what the shading mode will be. The possibilities are SHADE_MODE_FLAT, SHADE_MODE_GOURAUD, or SHADE_MODE_PHONG. The value is set by an integer. The default mode is GOURAUD.
public final static SHADE_MODE_FLAT
Sets the shading mode to flat.
public final static int SHADE_MODE_GOURAUD
Sets the shading mode to Gouraud. This is the default mode.
public final static int SHADE_MODE_PHONG
Sets the shading mode to Phong.
public final static String TEXTURE_QUALITY
Determines what the texture rendering quality will be. The possibilities are TEXTURE_QUALITY_LINEAR or TEXTURE_QUALITY_NEAREST. The value is set by an integer. The default mode is NEAREST.
public final static int TEXTURE_QUALITY_LINEAR
Sets the texture rendering quality to linear.
public final static int TEXTURE_QUALITY_NEAREST
Sets the texture rendering quality to nearest. This is the default mode.
public final static String USE_3-D_HW
Determines whether or not 3-D hardware will be enabled. The value is set by a boolean. The default is Off. This preference cannot be overridden by the application. It is a read-only value.
public final static USE_VIDEOMEM
Determines whether or not the video memory will be enabled. The value is set by a boolean. The default is On.


PropertyDispatcher Class

public class PropertyDispatcher extends java.lang.Object {
    // Constructor
    public PropertyDispatcher(Behavior a);

    // Methods
    public void detach();
    public Behavior getBvr();
    public Behavior notify(int, boolean, double, double, Behavior, Behavior);
    public void setControl(Object object);
    public void setPropertyName(String name);
}

This class allows DirectAnimation behaviors to be attached to (and detached from) properties in ActiveX controls. For example, a NumberBvr can be attached to the width property of a frame on an HTML page.

  • PropertyDispatcher Constructor
  • PropertyDispatcher Methods

PropertyDispatcher Constructor

PropertyDispatcher Class

Constructs a PropertyDispatcher object.

public PropertyDispatcher(
Behavior a
);

Parameters
a
The behavior to be attached to an ActiveX control property.
Remarks

Th behavior specified by a is used only in the constructor. To attach a behavior to a property, first create the PropertyDispatcher class with that behavior, and then extract an equivalent behavior with getBvr(). Use this behavior in the model. When access to the control and its property name is available, call setControl() and setPropertyName(). Here is an example:

NumberBvr n = the behavior that will be attached to a control
PropertyDispatcher pd = new PropertyDispatcher(n);
NumberBvr attachedN = (NumberBvr)pd.getBvr();

//...At some other point

pd.setControl(ctrl);
pd.setPropertyName("width");

Note that the attachedN behavior must be running to affect the attached property. The behavior is running if:

  • It is part of the image or sound registered with setImage() or setSound() on the model.
  • It was explicitly added to a BvrsToRun list.

PropertyDispatcher Methods

detach

getBvr

setControl

setPropertyName

detach

PropertyDispatcher Class

Detaches an already attached behavior from an ActiveX control property.

public void detach( );

getBvr

PropertyDispatcher Class

Returns a behavior that, while it is the same as the behavior used in the constructor, is updated over time. This is the behavior that should be used once the PropertyDispatcher object has been constructed.

public Behavior getBvr( );

Return Values

Returns the Behavior object.

setControl

PropertyDispatcher Class

Sets the ActiveX control object to which a behavior will be attached.

public void setControl(
Object object
);

Parameters
object
The ActiveX control object to which a behavior will be attached.

setPropertyName

PropertyDispatcher Class

Sets the name of the ActiveX control property to which a DirectAnimation behavior will be attached.

public void setPropertyName(
String name
);

Parameters
name
The name of the property to which a DirectAnimation behavior will be attached.


SoundBvr Class

public class SoundBvr extends Behavior {

    // Methods
    public SoundBvr gain(NumberBvr gainAmt);
    public SoundBvr loop();
    public SoundBvr pan(NumberBvr panAmt);
    public SoundBvr phase(NumberBvr phaseAmt);
    public SoundBvr rate(NumberBvr rateAmt);

    public static SoundBvr newUninitBvr();
}

Creates an object that represents a sound behavior. Sound behaviors have gain, rate, phase, and pan attributes. Imported sounds (.WAV and .MIDI files) also have a length, returned by the import method.

Gain (volume) defines how loudly the sound is played. Rate defines how many times faster or slower the sound is played relative to its nominal rate. Phase defines how much to shift the time of the sound, and is useful for creating special sound effects such as echoes. Mixing the same sounds that are out of phase makes the sound richer. Pan defines the strength of the sound relative to the left and right sound channels. It is useful for positioning sounds.

Gain, rate, phase, and pan are number behaviors and can, therefore, change over time. This is useful for modifying the sound based, not only on time, (See substituteTime) but also on other computed values such as distance. Sounds can be embedded in a geometry to achieve spatialized effects. Currently, all sounds are omnidirectional.

For more information about behaviors, see the Behavior class.

  • SoundBvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

SoundBvr Methods

gain

loop

pan

phase

rate

newUninitBvr

gain

SoundBvr Class

Creates a new sound behavior by multiplying the gain (volume) by the given amount.

public SoundBvr gain(
NumberBvr gainAmt
);

Parameters
gainAmt
The NumberBvr object specifying the factor by which to multiply the volume. Values greater than one increase the volume and values between zero and 1 decrease the sound's volume. Except for sound geometries, only attenuation values of 0-1 have an effect. For sound geometries, gains greater than 1 affect the distance from which sounds can be heard. The sounds, however, never sound louder than 1. This parameter can also be of type double.
Return Values

Returns the SoundBvr object.

Remarks

This attribute composes multiplicatively.

loop

SoundBvr Class

Creates a sound behavior that repeats itself continuously.

public SoundBvr loop( );

Return Values

Returns the SoundBvr object.

Remarks

This method applies to the primitive sounds themselves. It does not loop a reactive sound behavior. Instead, it loops each of the primitive sounds that are the components of the reactive sound behavior. In the following example, snd1 and snd2 are each looped:

SoundBvr snd3 = SoundBvr(until)(snd1, leftButtonDown, snd2);
SoundBvr snd4 = snd3.loop();

This attribute overrides previous values.

pan

SoundBvr Class

Creates a sound behavior by repositioning a monophonic sound between the left and right channels. To do this, the amplitude of the sound in each channel is changed. This is similar to adjusting the balance on a stereo.

public SoundBvr pan(
NumberBvr panAmt
);

Parameters
panAmt
The NumberBvr object specifying the amount to pan. Can be a value in the range -1.0 to 1.0, with -1.0 as full left, 0 as center, and 1.0 as full right. This parameter can also be of type double.
Return Values

Returns the SoundBvr object.

Remarks

With stereophonic sounds, panning away from a channel attenuates it.

Remarks

This attribute composes additively.

phase

SoundBvr Class

Creates a sound behavior by shifting the sound in time by the given amount. Shifting the sound and mixing with the original sound allows for special effects, such as echoing.

public SoundBvr phase(
NumberBvr phaseAmt
);

Parameters
phaseAmt
The NumberBvr object specifying the amount in seconds (or fractions of seconds) to shift the sound. This parameter can also be of type double.
Return Values

Returns the SoundBvr object.

Remarks

For unlooped sounds, a positive phase shift delays the sound's starting time while a negative phase shift clips off the beginning of the sound. For looped sounds, a positive phase shift adds the end of the sound to the beginning of the sound, while a negative phase shift controls how far into the sound the beginning should be. Phase-shifting only takes effect when the sound begins playing. Currently, you cannot dynamically change the position of a running sound. This attribute composes additively.

rate

SoundBvr Class

Creates a sound behavior by multiplying the playback rate by the given amount.

public SoundBvr rate(
NumberBvr rateAmt
);

Parameters
rateAmt
The NumberBvr object specifying the factor by which to multiply the rate. Values greater than one increase the rate and values between zero and 1 decrease it. This parameter can also be of type double.
Return Values

Returns the SoundBvr object.

Remarks

A rate of 0 pauses the sound. Negative rates are not supported. This attribute composes additively.

newUninitBvr

SoundBvr Class

This method allows you to refer to an SoundBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static SoundBvr newUninitBvr( );

Return Values

Returns the SoundBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type SoundBvr.

public static SoundBvr importSound(URL url, NumberBvr[] soundLength);

public static SoundBvr importSound(URL url, NumberBvr[] soundLength, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);

public static SoundBvr mix(SoundBvr sound1, SoundBvr sound2);

public static SoundBvr mixArray(SoundBvr[] sounds);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type SoundBvr.

public final static SoundBvr silence;

public final static SoundBvr sinSynth;


Statics Class

public class Statics{
    // Behavior Static Methods
    public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b);
    public static Behavior sequence(Behavior a, Behavior b);
    public static Behavior until(Behavior a, DXMEvent e, Behavior b);
    public static Behavior untilEx(Behavior a, DXMEvent e);
    public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier);

    // BooleanBvr Static Fields
    public final static BooleanBvr falseBvr;
    public final static BooleanBvr leftButtonState;
    public final static BooleanBvr rightButtonState;
    public final static BooleanBvr trueBvr;

    // BooleanBvr Static Methods
    public static BooleanBvr and(BooleanBvr b1, BooleanBvr b2);
    public static BooleanBvr keyState(int keyCode);
    public static BooleanBvr not(BooleanBvr b);
    public static BooleanBvr or(BooleanBvr b1, BooleanBvr b2);
    public static BooleanBvr toBvr(Boolean bool);

    // CameraBvr Static Methods
    public static CameraBvr parallelCamera(NumberBvr nearclip);
    public static CameraBvr perspectiveCamera(NumberBvr projdst, NumberBvr nearclip);

    // ColorBvr Static Fields
    public final static ColorBvr aqua;
    public final static ColorBvr black;
    public final static ColorBvr blue;
    public final static ColorBvr cyan;
    public final static ColorBvr fuchsia;
    public final static ColorBvr gray;
    public final static ColorBvr green;
    public final static ColorBvr lime;
    public final static ColorBvr magenta;
    public final static ColorBvr maroon;
    public final static ColorBvr navy;
    public final static ColorBvr olive;
    public final static ColorBvr purple;
    public final static ColorBvr red;
    public final static ColorBvr silver;
    public final static ColorBvr teal;
    public final static ColorBvr white;
    public final static ColorBvr yellow;

    // ColorBvr Static Methods
    public static ColorBvr colorHsl(NumberBvr h, NumberBvr s, NumberBvr l);
    public static ColorBvr colorRgb(NumberBvr r, NumberBvr g, NumberBvr b);
    public static ColorBvr colorRgb255(short r, short g, short b);

    // DashStyleBvr Static Fields
    public final static DashStyleBvr dashStyleDashed;
    public final static DashStyleBvr dashStyleSolid;

    // DXMApplet Static Methods
    public ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w);

    // DXMEvent Static Fields
    public final static DXMEvent always;
    public final static DXMEvent leftButtonDown;
    public final static DXMEvent leftButtonUp;
    public final static DXMEvent never;
    public final static DXMEvent rightButtonDown;
    public final static DXMEvent rightButtonUp;

    // DXMEvent Static Methods
    public static DXMEvent andEvent(DXMEvent first, DXMEvent second);
    public static DXMEvent keyDown(int keyCode);
    public static DXMEvent keyUp(int keyCode);
    public static DXMEvent newUninitBvr();
    public static DXMEvent notEvent(DXMEvent ev);
    public static DXMEvent orEvent(DXMEvent first, DXMEvent second);
    public static DXMEvent predicate(BooleanBvr bool);
    public static DXMEvent thenEvent(DXMEvent e1, DXMEvent e2);
    public static DXMEvent timer(NumberBvr timeout);
    public static void     unregisterCallback(Object object);

    // EndStyleBvr Static Fields
    public final static EndStyleBvr endStyleFlat;
    public final static EndStyleBvr endStyleRound;
    public final static EndStyleBvr endStyleSquare;

    // FontStyleBvr Static Fields
    public final static FontStyleBvr defaultFont;

    // FontStyleBvr Static Methods
    public static FontStyleBvr font(StringBvr face, NumberBvr points, ColorBvr color);

    //GeometryBvr Static Fields
    public final static GeometryBvr ambientLight;
    public final static GeometryBvr directionalLight;
    public final static GeometryBvr emptyGeometry;
    public final static GeometryBvr pointLight;

    // GeometryBvr Static Methods
    public static GeometryBvr importGeometry(URL url);
    public static GeometryBvr importGeometry(URL url, GeometryBvr geoStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);
    public static GeometryBvr soundSource(SoundBvr sound);
    public static GeometryBvr spotLight(NumberBvr fullcone, NumberBvr cutoff);
    public static GeometryBvr union(GeometryBvr g1, GeometryBvr g2);
    public static GeometryBvr unionArray(GeometryBvr geometries);

    // ImageBvr Static Fields
    public final static ImageBvr detectableEmptyImage;
    public final static ImageBvr emptyImage;

    // ImageBvr Static Methods
    public static ImageBvr  gradientHorizontal(ColorBvr start, ColorBvr stop, NumberBvr fallOff);
    public static ImageBvr  gradientPolygon(Point2Bvr[] pts, ColorBvr[] colors);
    public static ImageBvr  gradientSquare(ColorBvr lowerLeft, ColorBvr upperLeft, ColorBvr upperRight, ColorBvr lowerRight);
    public static ImageBvr  hatchBackwardDiagonal(ColorBvr color, NumberBvr size);
    public static ImageBvr  hatchCross(ColorBvr color, NumberBvr size);
    public static ImageBvr  hatchForwardDiagonal (ColorBvr color, NumberBvr size);
    public static ImageBvr  hatchHorizontal(ColorBvr color, NumberBvr size);
    public static ImageBvr  hatchVertical(ColorBvr color, NumberBvr size);
    public static ImageBvr  importImage(URL url);
    public static ImageBvr  importImage(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);
    public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd);
    public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd, ImageBvr imgStandIn, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);
    public static ImageBvr  overlay(ImageBvr i1, ImageBvr i2);
    public static ImageBvr  overlayArray(ImageBvr[] im);
    public static ImageBvr  radialGradientPolygon(ColorBvr inner, ColorBvr outer, Point2Bvr[] points, NumberBvr fallOff);
    public static ImageBvr  radialGradientRegularPoly(ColorBvr inner, ColorBvr outer, NumberBvr edges, NumberBvr fallOff);
    public static ImageBvr  radialGradientSquare(ColorBvr inner, ColorBvr outer, NumberBvr fallOff);
    public static ImageBvr  solidColorImage(ColorBvr col);
    public static ImageBvr  stringImage(StringBvr string, FontStyleBvr font);

    // JoinStyleBvr Static Fields
    public final static JoinStyleBvr joinStyleBevel;
    public final static JoinStyleBvr joinStyleMiter;
    public final static JoinStyleBvr joinStyleRound;

    // LineStyleBvr Static Fields
    public final static LineStyleBvr defaultLineStyle;

    // MatteBvr Static Fields
    public final static MatteBvr clearMatte;
    public final static MatteBvr opaqueMatte;

    // MatteBvr Static Methods
    public static MatteBvr difference(MatteBvr m1, MatteBvr m2);
    public static MatteBvr fillMatte(Path2Bvr path);
    public static MatteBvr intersect(MatteBvr m1, MatteBvr m2);
    public static MatteBvr textMatte(StringBvr text, FontStyleBvr fs);
    public static MatteBvr union(MatteBvr m1, MatteBvr m2);

    // MicrophoneBvr Static Fields
    public final static MicrophoneBvr defaultMicrophone;

    // Miscellaneous Static Fields
    public final  static double cm;
    public final  static double foot;
    public final  static double inch;
    public final  static double meter;
    public final  static double mm;
    public final  static NumberBvr pixelBvr;

    // Miscellaneous Static Methods
    public static URL buildURL(URL url, String pathname);
    public static String getVersionString();

    // MontageBvr Static Fields
    public final static MontageBvr emptyMontage;

    // MontageBvr Static Methods
    public static MontageBvr imageMontage(ImageBvr image, NumberBvr depth);
    public static MontageBvr union(MontageBvr m1, MontageBvr m2);

    // NumberBvr Static Fields
    public final static NumberBvr  globalTime;
    public final static NumberBvr  localTime;

    // NumberBvr Static Methods
    public static NumberBvr  abs(NumberBvr a);
    public static NumberBvr  acos(NumberBvr a);
    public static NumberBvr  add(NumberBvr a, NumberBvr b);
    public static NumberBvr  asin(NumberBvr a);
    public static NumberBvr  atan(NumberBvr a);
    public static NumberBvr  atan2(NumberBvr a, NumberBvr b);
    public static NumberBvr  bSpline(int degree, NumberBvr[] knots, NumberBvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);
    public static NumberBvr  ceiling(NumberBvr a);
    public static NumberBvr  cos(NumberBvr a);
    public static NumberBvr  degreesToRadians(NumberBvr a);
    public static NumberBvr  derivative(NumberBvr a);
    public static NumberBvr  div(NumberBvr a, NumberBvr b);
    public static BooleanBvr eq(NumberBvr a, NumberBvr b);
    public static NumberBvr  exp(NumberBvr a);
    public static NumberBvr  floor(NumberBvr a);
    public static BooleanBvr gt(NumberBvr a, NumberBvr b);
    public static BooleanBvr gte(NumberBvr a, NumberBvr b);
    public static NumberBvr  integral(NumberBvr a);
    public static NumberBvr  ln(NumberBvr a);
    public static NumberBvr  log10(NumberBvr a);
    public static BooleanBvr lt(NumberBvr a, NumberBvr b);
    public static BooleanBvr lte(NumberBvr a, NumberBvr b);
    public static NumberBvr  mod(NumberBvr a, NumberBvr b);
    public static NumberBvr  mul(NumberBvr a, NumberBvr b);
    public static BooleanBvr ne(NumberBvr a, NumberBvr b);
    public static NumberBvr  neg(NumberBvr a);
    public static NumberBvr  pow(NumberBvr a, NumberBvr b);
    public static NumberBvr  radiansToDegrees(NumberBvr a);
    public static NumberBvr  round(NumberBvr a);
    public static NumberBvr  seededRandom(double seed);
    public static NumberBvr  sin(NumberBvr a);
    public static NumberBvr  sqrt(NumberBvr a);
    public static NumberBvr  sub(NumberBvr a, NumberBvr b);
    public static NumberBvr  tan(NumberBvr a);
    public static NumberBvr  toBvr(double a);

    // Path2Bvr Static Methods
    public static Path2Bvr arc(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight);
    public static Path2Bvr arcDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight);
    public static Path2Bvr concat(Path2Bvr p1, Path2Bvr p2);
    public static Path2Bvr concatArray(Path2Bvr[] paths);
    public static Path2Bvr cubicBSplinePath(Point2Bvr[], NumberBvr[]);
    public static Path2Bvr line(Point2Bvr p1, Point2Bvr p2);
    public static Path2Bvr oval(NumberBvr width, NumberBvr height);
    public static Path2Bvr pie(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, arcHeight);
    public static Path2Bvr pieDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight);
    public static Path2Bvr polydrawPath(Point2Bvr[] points, NumberBvr[] codes);
    public static Path2Bvr polyline(Point2Bvr[] points);
    public static Path2Bvr ray(Point2Bvr p);
    public static Path2Bvr roundRect(NumberBvr width, NumberBvr height, NumberBvr arcWidth, NumberBvr arcHeight);
    public static Path2Bvr rect(NumberBvr width, NumberBvr height);
    public static Path2Bvr stringPath(StringBvr string, FontStyleBvr fs);

    // Point2Bvr Static Fields
    public final static Point2Bvr mousePosition;
    public final static Point2Bvr origin2;

    // Point2Bvr Static Methods
    public static Point2Bvr  add(Point2Bvr pt, Vector2Bvr vec);
    public static Point2Bvr  bSpline(int degree, NumberBvr[] knots, Point2Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);
    public static Vector2Bvr derivative(Point2Bvr pt);
    public static NumberBvr  distance(Point2Bvr p1, Point2Bvr p2);
    public static NumberBvr  distanceSquared(Point2Bvr p1, Point2Bvr p2);
    public static Point2Bvr  point2(NumberBvr x, NumberBvr y);
    public static Point2Bvr  point2Polar(NumberBvr XYangle, NumberBvr length);
    public static Vector2Bvr sub(Point2Bvr p1, Point2Bvr p2);
    public static Point2Bvr  sub(Point2Bvr pt, Vector2Bvr vec);

    // Point3Bvr Static Fields
    public final static Point3Bvr origin3;

    // Point3Bvr Static Methods
    public static Point3Bvr  add(Point3Bvr pt, Vector3Bvr vec);
    public static Point3Bvr  bSpline(int degree, NumberBvr[] knots, Point3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);
    public static Vector3Bvr derivative(Point3Bvr pt);
    public static NumberBvr  distance(Point3Bvr p1, Point3Bvr p2);
    public static NumberBvr  distanceSquared(Point3Bvr p1, Point3Bvr p2);
    public static Point3Bvr  point3(NumberBvr x, NumberBvr y, NumberBvr z);
    public static Point3Bvr  point3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length);
    public static Vector3Bvr sub(Point3Bvr p1, Point3Bvr p2);
    public static Point3Bvr  sub(Point3Bvr pt, Vector3Bvr vec);

    // SoundBvr Static Fields
    public final static SoundBvr silence;
    public final static SoundBvr sinSynth;

    // SoundBvr Static Methods
    public static SoundBvr importSound(URL url, NumberBvr[] soundLength);
    public static SoundBvr importSound(URL url, NumberBvr[] soundLength, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size);
    public static SoundBvr mix(SoundBvr sound1, SoundBvr sound2);
    public static SoundBvr mixArray(SoundBvr[] sounds);

    // StringBvr Static Methods
    public static StringBvr concat(StringBvr a, StringBvr b);
    public static StringBvr toBvr(String string);

    // Transform2Bvr Static Fields
    public final static Transform2Bvr identityTransform2;

    // Transform2Bvr Static Methods
    public static Transform2Bvr compose(Transform2Bvr xf1, Transform2Bvr xf2);
    public static Transform2Bvr compose2Array(Transform2Bvr[] xforms);
    public static Transform2Bvr followPath(Path2Bvr path, NumberBvr evaluator);
    public static Transform2Bvr followPathAngle(Path2Bvr path, NumberBvr evaluator);
    public static Transform2Bvr followPathAngleUpright(Path2Bvr path, NumberBvr evaluator);
    public static Transform2Bvr rotate(NumberBvr radians);
    public static Transform2Bvr rotateDegrees(double degrees);
    public static Transform2Bvr rotateRate(double radians);
    public static Transform2Bvr rotateRateDegrees(double degrees);
    public static Transform2Bvr scale(NumberBvr sx, NumberBvr sy);
    public static Transform2Bvr scale(Vector2Bvr v);
    public static Transform2Bvr scaleRate(double x, double y);
    public static Transform2Bvr scale2(NumberBvr uniformFactor);
    public static Transform2Bvr scale2Rate(double rate);
    public static Transform2Bvr transform3x2(NumberBvr[] matrix);
    public static Transform2Bvr translate(NumberBvr tx, NumberBvr ty);
    public static Transform2Bvr translate(Vector2Bvr v);
    public static Transform2Bvr translateRate(double x, double y);
    public static Transform2Bvr xShear(NumberBvr x);
    public static Transform2Bvr xShearRate(double xRate);
    public static Transform2Bvr yShear(NumberBvr y);
    public static Transform2Bvr yShearRate(double yRate);

    // Transform3Bvr Static Fields
    public final static Transform3Bvr identityTransform3;

    // Transform3Bvr Static Methods
    public static Transform3Bvr compose(Transform3Bvr xf1, Transform3Bvr xf2);
    public static Transform3Bvr compose3Array(Transform3Bvr[] xforms);
    public static Transform3Bvr lookAtFrom(Point3Bvr from, Point3Bvr to, Vector3Bvr up);
    public static Transform3Bvr rotate(Vector3Bvr axis, NumberBvr radians);
    public static Transform3Bvr rotateDegrees(Vector3Bvr axis, double degrees);
    public static Transform3Bvr rotateRate(Vector3Bvr axis, double radians);
    public static Transform3Bvr rotateRateDegrees(Vector3Bvr axis, double radians);
    public static Transform3Bvr scale(NumberBvr sx, NumberBvr sy, NumberBvr sz);
    public static Transform3Bvr scale(Vector3Bvr v);
    public static Transform3Bvr scaleRate(double x, double y, double z);
    public static Transform3Bvr scale3(NumberBvr uniformFactor);
    public static Transform3Bvr scale3Rate(double rate);
    public static Transform3Bvr transform4x4(NumberBvr[] matrix);
    public static Transform3Bvr translate(NumberBvr tx, NumberBvr ty, NumberBvr tz);
    public static Transform3Bvr translate(Vector3Bvr v);
    public static Transform3Bvr translateRate(double x, double y, double z);
    public static Transform3Bvr xShear(NumberBvr a, NumberBvr b);
    public static Transform3Bvr xShearRate(double a, double b);
    public static Transform3Bvr yShear(NumberBvr c, NumberBvr d);
    public static Transform3Bvr yShearRate(double c, double d);
    public static Transform3Bvr zShear(NumberBvr e, NumberBvr f);
    public static Transform3Bvr zShearRate(double e, double f);

    // TupleBvr Static Methods
    public static TupleBvr pairBvr(Behavior first, Behavior second);
    public static TupleBvr tripleBvr(Behavior first, Behavior second, Behavior third);

    // Vector2Bvr Static Fields
    public final static Vector2Bvr xVector2;
    public final static Vector2Bvr yVector2;
    public final static Vector2Bvr zeroVector2;

    // Vector2Bvr Static Methods
    public static Vector2Bvr add(Vector2Bvr v1, Vector2Bvr v2);
    public static Vector2Bvr bSpline(int degree, NumberBvr[] knots, Vector2Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);
    public static Vector2Bvr derivative(Vector2Bvr vec);
    public static NumberBvr  dot(Vector2Bvr v1, Vector2Bvr v2);
    public static Vector2Bvr integral(Vector2Bvr vec);
    public static Vector2Bvr neg(Vector2Bvr v1);
    public static Vector2Bvr sub(Vector2Bvr v1, Vector2Bvr v2);
    public static Vector2Bvr vector2(NumberBvr x, NumberBvr y);
    public static Vector2Bvr vector2Polar(NumberBvr XYangle, NumberBvr length);
    public static Vector2Bvr vector2PolarDegrees(double XYangle, double length);

    // Vector3Bvr Static Fields
    public final static Vector3Bvr xVector3;
    public final static Vector3Bvr yVector3;
    public final static Vector3Bvr zVector3;
    public final static Vector3Bvr zeroVector3;

    // Vector3Bvr Static Methods
    public static Vector3Bvr add(Vector3Bvr v1, Vector3Bvr v2);
    public static Vector3Bvr bSpline(int degree, NumberBvr[] knots, Vector3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation));
    public static Vector3Bvr cross(Vector3Bvr v1, Vector3Bvr v2);
    public static Vector3Bvr derivative(Vector3Bvr vec);
    public static NumberBvr  dot(Vector3Bvr v1, Vector3Bvr v2);
    public static Vector3Bvr integral(Vector3Bvr vec);
    public static Vector3Bvr neg(Vector3Bvr v1);
    public static Vector3Bvr sub(Vector3Bvr v1, Vector3Bvr v2);
    public static Vector3Bvr vector3(NumberBvr x, NumberBvr y, NumberBvr z);
    public static Vector3Bvr vector3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length);
}

The Statics class collects all the static methods and constants provided by the other classes in com.ms.dxmedia and makes them available as static methods on the Statics class. In addition, the Model class extends from Statics. This means that, when a programmer is implementing the createModel method of the class they extend from Model, all of the static methods in Statics become available without qualification.

The following table lists the classes that have static methods and/or fields:

B
Static Methods Relevant to Behavior Objects
Static Methods Relevant to BooleanBvr Objects
Static Fields Relevant to BooleanBvr Objects
C
Static Methods Relevant to CameraBvr Objects
Static Methods Relevant to ColorBvr Objects
Static Fields Relevant to ColorBvr Objects
D
Static Fields Relevant to DashStyleBvr Objects
Static Methods Relevant to DXMEvent Objects
Static Fields Relevant to DXMEvent Objects
E
Static Fields Relevant to EndStyleBvr Objects
F
Static Methods Relevant to FontStyleBvr Objects
Static Fields Relevant to FontStyleBvr Objects
G
Static Methods Relevant to GeometryBvr Objects
Static Fields Relevant to GeometryBvr Objects
I
Static Methods Relevant to ImageBvr Objects
Static Fields Relevant to ImageBvr Objects
J
Static Fields Relevant to JoinStyleBvr Objects
L
Static Fields Relevant to LineStyleBvr Objects
M
Static Methods Relevant to MatteBvr Objects
Static Fields Relevant to MatteBvr Objects
Static Fields Relevant to MicrophoneBvr Objects
Static Methods (Miscellaneous)
Static Fields (Miscellaneous)
Static Methods Relevant to MontageBvr Objects
Static Fields Relevant to MontageBvr Objects
N
Static Methods Relevant to NumberBvr Objects
Static Fields Relevant to NumberBvr Objects
P
Static Methods Relevant to Path2Bvr Objects
Static Methods Relevant to Point2Bvr Objects
Static Fields Relevant to Point2Bvr Objects
Static Methods Relevant to Point3Bvr Objects
Static Fields Relevant to Point3Bvr Objects
S
Static Methods Relevant to SoundBvr Objects
Static Fields Relevant to SoundBvr Objects
Static Methods Relevant to StringBvr Objects
T
Static Methods Relevant to Transform2Bvr Objects
Static Fields Relevant to Transform2Bvr Objects
Static Methods Relevant to Transform3Bvr Objects
Static Fields Relevant to Transform3Bvr Objects
Static Methods Relevant to TupleBvr Objects
V
Static Methods Relevant to Vector2Bvr Objects
Static Fields Relevant to Vector2Bvr Objects
Static Methods Relevant to Vector3Bvr Objects
Static Fields Relevant to Vector3Bvr Objects


Static Methods Relevant to Behavior Objects

cond

Statics Class

Creates a new behavior from the BooleanBvr and two other behaviors. The value of the new behavior, at any point in time, is one of those two behaviors. Which of the behaviors chosen depends on the value of the BooleanBvr. Here is an example:

//Create a new behavior, y, which is either 1.0 if x > 1.0, or another behavior, x
    NumberBvr y = (NumberBvr)cond(gte(x, toBvr(1.0)), toBvr(1.0), x);

public static Behavior cond(
BooleanBvr bool,
Behavior a,
Behavior b
);

Parameters
bool
The BooleanBvr object that determines which of the two behaviors will become the value of the new behavior.
a
The first of the two possible values the new behavior can assume.
b
The second of the two possible values the new behavior can assume.
Return Values

Returns the Behavior object.

sequence

Statics Class

Creates a new behavior that is the sum of the two Behavior parameters. In other words, the two behaviors are concatenated, according to their order in the parameter list. Once the duration is over, the behavior becomes a snapshot of the second behavior. An exception is when the first behavior is of infinite duration. In this case, the returned behavior is always the infinite behavior, no matter what the second behavior is.

public static Behavior sequence(
Behavior a,
Behavior b
);

Parameters
a
The first behavior in the sequence.
b
The second behavior in the sequence.
Return Values

Returns the Behavior object.

Remarks

Notice that, in contrast to compose, which first apply the right-hand argument and then the left, sequence first applies the left-hand argument and then the right.

until

Statics Class

Creates a behavior that changes when a given event occurs. Up to and including the time the event occurs, the behavior is the same as a. After the event e occurs, the behavior changes to be the same as b. Because until takes behaviors and returns a behavior, it can be nested. Here are some examples:

//The ColorBvr col is initially red
//It turns blue when the left mouse button is pressed
ColorBvr c = (ColorBvr)until(red, leftButtonDown, blue);

//Example of nested behaviors
//The behavior is initially red
//It turns blue when the left mouse button is pressed
//And turns green when it is pressed again
ColorBvr c = (ColorBvr)until(red, leftButtonDown,
            until(blue, leftButtonDown, green));

public static Behavior until(
Behavior a,
DXMEvent e,
Behavior b
);

Parameters
a
The Behavior object that the behavior represents initially.
e
A DXMEvent object specifying the event.
b
The Behavior object that the behavior represents after the event.
Return Values

Returns the Behavior object.

untilEx

Statics Class

Creates a Behavior that changes upon a given event. Initially, the behavior is the same as a. When event e occurs, the behavior changes to the behavior returned by the event. This means that only DXMEvents that return a Behavior can be used. These events can be constructed with attachData, notifyEvent, and snapshotEvent.

public static Behavior untilEx(
Behavior a,
DXMEvent e
);

Parameters
a
The Behavior object that the behavior represents initially.
e
The DXMEvent object that triggers the switch and returns the new behavior.
Return Values

Returns the Behavior object caused by the event e.

untilNotify

Statics Class

Creates a behavior that changes upon a given event. Initially, the behavior is the same as a. When event e occurs, the behavior changes to the behavior returned by the event notifier notifier.

public static Behavior untilNotify(
Behavior a,
DXMEvent e,
UntilNotifier notifier
);

Parameters
a
The Behavior object that the behavior represents initially.
e
A DXMEvent object specifying the event.
b
The UntilNotifier object. The notify method of this object, called on the given event, returns the new behavior.
Return Values

Returns the Behavior object.


DirectAnimation Animated Header --Static Methods Relevant to BooleanBvr Objects DirectAnimation Animated Header --Static Methods Relevant to BooleanBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Behavior Objects
  * Next Topic: Static Fields Relevant to BooleanBvr Objects

Static Methods Relevant to BooleanBvr Objects

and

Statics Class

Creates a boolean behavior that represents the logical AND of the given behaviors. The behavior's value is true when both b1 and b2 are true; otherwise, it is false.

public static BooleanBvr and(
BooleanBvr b1,
BooleanBvr b2
);

Parameters
b1 and b2
The BooleanBvr objects to combine.
Return Values

Returns the BooleanBvr object.

See Also

or, not

keyState

Statics Class

Creates a boolean behavior that describes whether the key is up or down.

public static BooleanBvr keyState(
int keyCode
);

Parameters
keyCode
Can either be quoted characters, such as 'a' or specific Java keycode constants.
Return Values

Returns the BooleanBvr object. The value is TRUE when the key is down and FALSE when the key is up.

not

Statics Class

Creates a boolean behavior that represents the logical NOT of the given behavior. The behavior's value is true when b is false; otherwise, it is false.

public static BooleanBvr not(
BooleanBvr b
);

Parameters
b
The BooleanBvr object to apply the operation to.
Return Values

Returns the BooleanBvr object.

See Also

and , or

or

Statics Class

Creates a boolean behavior that represents the logical OR of the given behaviors. The behavior's value true when either b1 or b2 are true; otherwise it is false.

public static BooleanBvr or(
BooleanBvr b1,
BooleanBvr b2
);

Parameters
b1 and b2
The BooleanBvr objects to combine.
Return Values

Returns the BooleanBvr object.

See Also

and, not

toBvr

Statics Class

Converts a boolean to a BooleanBvr. The only time toBvr is used is when converting Java numbers, booleans, or strings to their corresponding DirectAnimation types. It is not used for constants such as red, yVector3, and origin2 because these are defined as constant behaviors.

public static BooleanBvr toBvr(
boolean bool
);

Parameters
bool
The Java boolean type to be converted.
Return Values

Returns the BooleanBvr object.


DirectAnimation Animated Header --Static Fields Relevant to BooleanBvr Objects DirectAnimation Animated Header --Static Fields Relevant to BooleanBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to BooleanBvr Objects
  * Next Topic: Static Methods Relevant to CameraBvr Objects

Static Fields Relevant to BooleanBvr Objects

falseBvr
A boolean behavior (BooleanBvr object) that is always false.
leftButtonState
The BooleanBvr object that is true if the left mouse button is down and false if it is up.
rightButtonState
The BooleanBvr object that is true if the right mouse button is down and false if it is up.
trueBvr
A boolean behavior (BooleanBvr object) that is always true.


DirectAnimation Animated Header --Static Methods Relevant to CameraBvr Objects DirectAnimation Animated Header --Static Methods Relevant to CameraBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to BooleanBvr Objects
  * Next Topic: Static Methods Relevant to ColorBvr Objects

Static Methods Relevant to CameraBvr Objects

parallelCamera

Statics Class

Creates a parallel camera for parallel (or orthographic) projection. The parallel camera is transformed the same way as the perspective camera, except that Z-scales have no effect (note, however, that zero or negative Z-scales yield undefined results).

Prior to transformation, the parallel camera gazes in the negative z-direction, with positive y considered as "up."

public static CameraBvr parallelCamera(
NumberBvr nearclip
);

Parameters
nearclip
The NumberBvr object that is the Z-location of the near clipping plane. This parameter can also be of type double.
Return Values

Returns the CameraBvr object.

perspectiveCamera

Statics Class

Creates a perspective camera for perspective rendering. On creation, the projection plane (the plane at which objects appear as their actual size) is located at Z=0, the projection point is located at [0 0 projdist], and the near clipping plane is located at [0 0 nearclip].

The projdst parameter specifies the distance between the projection plane and the projection point, and must be greater than zero. The smaller this distance, the more of a wide-angle effect is achieved. The larger this distance, the more of a telephoto effect is achieved.

The nearclip parameter specifies the Z-location of the near clipping plane and must be less than projdst. In other words, the near clipping plane must lie on the same side of the projection point as the projection plane. Although it is tempting to place the near clipping plane as close as possible to the projection point, Z-buffer precision is lost dramatically as the near clipping plane gets closer to the projection point. (The main result of such precision loss is that far objects are rendered in front of near objects.)

public static CameraBvr perspectiveCamera(
NumberBvr projdst,
NumberBvr nearclip
);

Parameters
projdst
The NumberBvr object that is the Z-location of the projection point. It must be greater than zero. This parameter can also be of type double.
nearclip
The NumberBvr object that is the Z-location of the near clipping plane. It must be less than projdst. This parameter can also be of type double.
Return Values

Returns the CameraBvr object.

Remarks

The following diagram shows a model of the perspective camera. Note that the nearclip need not be in front of the projection plane.


DirectAnimation Animated Header --Static Methods Relevant to ColorBvr Objects DirectAnimation Animated Header --Static Methods Relevant to ColorBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to CameraBvr Objects
  * Next Topic: Static Fields Relevant to ColorBvr Objects

Static Methods Relevant to ColorBvr Objects

colorHsl

Statics Class

Creates a color behavior that represents a color given by hue, saturation, and lightness values. The behavior's value at any given time depends on the values of h, s, and l. The following example creates a color whose hue varies with time, but whose saturation and lightness values are constant:

//vary the hue over time
ColorBvr animCol = colorHsl(localTime, toBvr(0.5), toBvr(0.5));

public static ColorBvr colorHsl(
NumberBvr h,
NumberBvr s,
NumberBvr l
);

Parameters
h
A NumberBvr object specifying the hue or base color. 0.0 is red, 0.33 is green, and 0.67 is blue. This number is considered "modulo 1," which means, for example, that the numbers 1.67, and 0.67 are both considered to be 0.67. This parameter can also be of type double.
s
A NumberBvr object specifying saturation or intensity of the hue. If saturation is 0.0, the color produced is gray regardless of the hue value. This parameter can also be of type double.
l
A NumberBvr object specifying lightness or amount of white in the color. If lightness is 1.0, the color produced is white regardless of the hue and saturation values. Similarly, if lightness is 0.0, the color is black. This parameter can also be of type double.
Return Values

Returns the ColorBvr object.

Remarks

Hue, saturation, and lightness values can range from 0.0 to 1.0. If the corresponding number behavior has a value outside this range, then the number is considered modulo 1.

See Also

colorRgb

colorRgb

Statics Class

Creates a color behavior that represents a color given by red, green, and blue intensity values. The behavior's value at any given time depends on the values of r, g, and b. The following example creates a color behavior whose red component varies from 0 to 1:

//Create a sawtooth wave that goes repetitively from 0 to 1
//Do this by taking the modulus of localTime and 1
NumberBvr sawtooth = mod(localTime, toBvr(1));
//Now create the RGB color, making red = to the value of sawtooth
ColorBvr col = colorRgb(sawtooth, toBvr(0), toBvr(0));

public static ColorBvr colorRgb(
NumberBvr r,
NumberBvr g,
NumberBvr b
);

Parameters
r, g, and b
The NumberBvr objects specifying the red, green, and blue values, respectively. The value of each specifies that color's intensity, with 0.0 for no color and 1.0 for the highest possible intensity. These parameters can also be of type double.
Return Values

Returns the ColorBvr object.

Remarks

Intensity values can range from 0.0 to 1.0. If the corresponding number behavior has a value outside this range, the integer part of the value is discarded and only the fractional part is used.

See Also

colorHsl

colorRgb255

Statics Class

Creates a color behavior that represents a color given by red, green, and blue intensity values. The behavior's value at any given time depends on the values of r, g, and b. These values can be in the range [0, 255].

public static ColorBvr colorRgb255(
short r,
short g,
short b
);

Parameters
r, g, and b
The shorts specifying the red, green, and blue values, respectively. The value of each specifies that color's intensity, with 0 for no color and 255 for the highest possible intensity.
Return Values

Returns the ColorBvr object.


DirectAnimation Animated Header --Static Fields Relevant to ColorBvr Objects DirectAnimation Animated Header --Static Fields Relevant to ColorBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to ColorBvr Objects
  * Next Topic: Static Fields Relevant to DashStyleBvr Objects

Static Fields Relevant to ColorBvr Objects

aqua
A color behavior (ColorBvr object) that is always aqua. In a range of [0, 1], its red, green, and blue intensity values are 0.00, 1.00, 1.00. In a range of [0-255], its values are 0, 255, 255.
black
A color behavior (ColorBvr object) that is always black. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 0.00. In a range of [0-255], its values are 0, 0, 0.
blue
A color behavior (ColorBvr object) that is always blue. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 1.00. In a range of [0-255], its values are 0, 0, 255.
cyan
A color behavior (ColorBvr object) that is always cyan. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 1.00. In a range of [0-255], its values are 0, 255, 255.
fuchsia
A color behavior (ColorBvr object) that is always fuchsia. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 1.00). In a range of [0-255], its values are 255, 0, 255.
gray
A color behavior (ColorBvr object) that is always gray. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.50,0.50. In a range of [0-255], its values are 128, 128, 128.
green
A color behavior (ColorBvr object) that is always green. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 0.00. In a range of [0-255], its values are 0, 255, 0.
lime
A color behavior (ColorBvr object) that is always lime. In a range of [0-1], its red, green, and blue intensity values are 0.00, 1.00, 0.00. In a range of [0-255], its values are 0, 255, 0.
magenta
A color behavior (ColorBvr object) that is always magenta. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 1.00. In a range of [0-255], its values are 255, 0, 255.
maroon
A color behavior (ColorBvr object) that is always maroon. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.00, 0.00. In a range of [0-255], its values are 128, 0, 0.
navy
A color behavior (ColorBvr object) that is always navy. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.00, 0.50. In a range of [0-255], its values are 0, 0, 128.
olive
A color behavior (ColorBvr object) that is always olive. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.50, 0.00. In a range of [0-255], its values are 128, 128, 0.
purple
A color behavior (ColorBvr object) that is always purple. In a range of [0-1], its red, green, and blue intensity values are 0.50, 0.00, 0.50. In a range of [0-255], its values are 128, 0, 128.
red
A color behavior (ColorBvr object) that is always red. In a range of [0-1], its red, green, and blue intensity values are 1.00, 0.00, 0.00. In a range of [0-255], its values are 255, 0, 0.
silver
A color behavior (ColorBvr object) that is always silver. In a range of [0-1], its red, green, and blue intensity values are 0.75, 0.75, 0.75. In a range of [0-255], its values are 192, 192, 192.
teal
A color behavior (ColorBvr object) that is always teal. In a range of [0-1], its red, green, and blue intensity values are 0.00, 0.50, 0.50. In a range of [0-255], its values are 0, 128, 128.
white
A color behavior (ColorBvr object) that is always white. In a range of [0-1], its red, green, and blue intensity values are 1.00, 1.00, 1.00. In a range of [0-255], its values are 255, 255, 255.
yellow
A color behavior (ColorBvr object) that is always yellow. In a range of [0-1], its red, green, and blue intensity values are 1.00, 1.00, 0.00. In a range of [0-255], its values are 255, 255, 0.


DirectAnimation Animated Header --Static Fields Relevant to DashStyleBvr Objects DirectAnimation Animated Header --Static Fields Relevant to DashStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to ColorBvr Objects
  * Next Topic: Static Methods Relevant to DXMApplet Objects

Static Fields Relevant to DashStyleBvr Objects

dashStyleDashed
Creates a dashstyle behavior (DashStyleBvr object) that draws a dashed line (sequence of line segments and spaces).
dashStyleSolid
Creates a dashstyle behavior (DashStyleBvr object) that draws a solid line (continuous stroke).


DirectAnimation Animated Header --Static Methods Relevant to DXMApplet Objects DirectAnimation Animated Header --Static Methods Relevant to DXMApplet Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to DashStyleBvr Objects
  * Next Topic: Static Methods Relevant to DXMEvent Objects

Static Methods Relevant to DXMApplet Objects

registerErrorAndWarningReceiver

Statics Class

See registerErrorAndWarningReceiver in the Viewer Interface section.

public static ErrorAndWarningReceiver registerErrorAndWarningReceiver(
ErrorAndWarningReceiver w
);


DirectAnimation Animated Header --Static Methods Relevant to DXMEvent Objects DirectAnimation Animated Header --Static Methods Relevant to DXMEvent Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to DXMApplet Objects
  * Next Topic: Static Fields Relevant to DXMEvent Objects

Static Methods Relevant to DXMEvent Objects

andEvent

Statics Class

Creates an event that occurs only when the two given events happen simultaneously. The event time for the new event is when both of the given events occur.

public static DXMEvent andEvent(
DXMEvent first,
DXMEvent second
);

Parameters
first and second
The DXMEvent objects.
Return Values

Returns a DXMEvent object. When the event occurs, it produces a PairObject. The first member is the event data returned by the first event. The second member is the event data returned by the second event.

keyDown

Statics Class

Returns an DXMEvent when a specific key is pressed. This is a state-transition event.

public static DXMEvent keyDown(
int keyCode
);

Parameters
keyCode
Can either be quoted characters such as 'a' or specific Java keycode constants.
Return Values

Returns the DXMEvent object. This event produces no data.

Remarks

The following table lists the hexadecimal values for all the special keycodes. The pattern for each key is 0x10000 plus the Win32 scan code.
Key | KeyCode
PGUP | 10021
PGDN | 10022
END | 10023
HOME | 10024
LEFT | 10025
UP | 10026
RIGHT | 10027
DOWN | 10028
INSERT | 1002D
DELETE | 1002E
NUMPAD0 | 10060
NUMPAD1 | 10061
NUMPAD2 | 10062
NUMPAD3 | 10063
NUMPAD4 | 10064
NUMPAD5 | 10065
NUMPAD6 | 10066
NUMPAD7 | 10067
NUMPAD8 | 10068
NUMPAD9 | 10069
MULTIPLY | 1006A
ADD | 1006B
SEPARATOR | 1006C
SUBTRACT | 1006D
DECIMAL | 1006E
DIVIDE | 1006F
F1 | 10070
F2 | 10071
F3 | 10072
F4 | 10073
F5 | 10074
F6 | 10075
F7 | 10076
F8 | 10077
F9 | 10078
F10 | 10079
F11 | 1007A
F12 | 1007B
F13 | 1007C
F14 | 1007D
F15 | 1007E
F16 | 1007F
F17 | 10080
F18 | 10081
F19 | 10082
F20 | 10083
F21 | 10084
F22 | 10085
F23 | 10086
F24 | 10087

keyUp

Statics Class

Returns an DXMEvent when a specific key is released. This is a state-transition event.

public static DXMEvent keyUp(
int keyCode
);

Parameters
keyCode
Can either be quoted characters such as 'a' or specific Java keycode constants.
Return Values

Returns the DXMEvent object. This event produces no data.

Remarks

For a list of special keycodes, see keyDown.

notEvent

Statics Class

Creates an event that occurs when the given event does not occur. This is useful for creating combined events that occur only if the given event is not also occurring, for example, an event that occurs when the left mouse button is down and the right button is not down.

public static DXMEvent notEvent(
DXMEvent ev
);

Parameters
ev
The DXMEvent object.
Return Values

Returns the DXMEvent object. This event produces no data.

orEvent

Statics Class

Creates an event that occurs when either one of the given events occur. The event time for the new event is when either the first or second given event has occurred.

public static DXMEvent orEvent(
DXMEvent first,
DXMEvent second
);

Parameters
first and second
The DXMEvent objects.
Return Values

Returns a DXMEvent object. Its data is the event data of either the first or second event.

predicate

Statics Class

Creates an event that occurs when the value of the given boolean behavior changes from false to true. Note that, because of implementation dependencies and the potential for aliasing, the system cannot always detect when a boolean behavior becomes true. For example, the expression: predicate(eq(sin(localTime), toBvr(0))) may never occur unless the system happens to sample it when sin(localTime)is exactly zero. Therefore, it is advisable to use inequality comparisons (for example, gte) rather than equality comparisons (for example, eq). Alternatively, the timer constructor may be a better choice for these situations.

public static DXMEvent predicate(
BooleanBvr bool
);

Parameters
bool
The BooleanBvr object.
Return Values

Returns the DXMEvent. This event produces no data.

thenEvent

Statics Class

Creates an event if e2 occurs after e1. The event time of the new event is the time of the second event.

public static DXMEvent thenEvent(
DXMEvent e1,
DXMEvent e2
);

Parameters
e1
The first event, that, when it occurs, triggers the second event.
e2
The second event, caused by the occurrence of the first event.
Return Values

Returns the DXMEvent object. Its event data is the time the second event fired and a PairObject containing the event data for both events.

timer

Statics Class

Creates an event that occurs when the specified time has elapsed.

public static DXMEvent timer(
NumberBvr timeout
);

Parameters
timeout
The NumberBvr object. This parameter can also be of type double.
Return Values

Returns the DXMEvent object. This event produces no data.

unregisterCallback

Statics Class

Used to unregister the callback.

public static void unregisterCallback(
Object object
);

Parameters
object
The object used to unregister the callback.
See Also

registerCallback


DirectAnimation Animated Header --Static Fields Relevant to DXMEvent Objects DirectAnimation Animated Header --Static Fields Relevant to DXMEvent Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to DXMEvent Objects
  * Next Topic: Static Fields Relevant to EndStyleBvr Objects

Static Fields Relevant to DXMEvent Objects

always
A DXMEvent object that occurs at all times. It produces no data.
leftButtonDown
The DXMEvent object that occurs when the left mouse button is pressed. This is a state-transition event. It produces no data.
leftButtonUp
The DXMEvent object that occurs when the left mouse button is released. This is a state-transition event. It produces no data.
never
An event (DXMEvent object) that never occurs. It produces no data.
rightButtonDown
The DXMEvent object that occurs when the right mouse button is pressed. This is a state-transition event. It produces no data.
rightButtonUp
The DXMEvent object that occurs when the right mouse button is released. This is a state-transition event. It produces no data.


DirectAnimation Animated Header --Static Fields Relevant to EndStyleBvr Objects DirectAnimation Animated Header --Static Fields Relevant to EndStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to DXMEvent Objects
  * Next Topic: Static Methods Relevant to FontStyleBvr Objects

Static Fields Relevant to EndStyleBvr Objects

endStyleFlat
An endstyle behavior (EndStyleBvr object) that draws the end of a line as a line segment, perpendicular to the final direction of the line and through the last point of the line.
endStyleRound
An endstyle behavior (EndStyleBvr object) that draws the end of a line as a circle, having a diameter equal to the width of the line and its center at the last point of the line.
endStyleSquare
An endstyle behavior (EndStyleBvr object) that draws the end of a line as a square, having a height and width equal to the width of the line and its center at the last point of the line.


DirectAnimation Animated Header --Static Methods Relevant to FontStyleBvr Objects DirectAnimation Animated Header --Static Methods Relevant to FontStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to EndStyleBvr Objects
  * Next Topic: Static Fields Relevant to FontStyleBvr Objects

Static Methods Relevant to FontStyleBvr Objects

font

Statics Class

Specifies the face, size in points, and color of a FontStyleBvr object. Because these parameters are all behaviors, they can vary over time.

public static FontStyleBvr font(
StringBvr face,
NumberBvr points,
ColorBvr color>;

Parameters
face
The StringBvr object specifying the font face. This parameter can also be of type java.lang.String.
points
The NumberBvr object specifying the font size, in points. This parameter can also be of type double.
color
The ColorBvr object specifying the font color.
Return Values

Returns the FontStyleBvr object.


DirectAnimation Animated Header --Static Fields Relevant to FontStyleBvr Objects DirectAnimation Animated Header --Static Fields Relevant to FontStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to FontStyleBvr Objects
  * Next Topic: Static Methods Relevant to GeometryBvr Objects

Static Fields Relevant to FontStyleBvr Objects

defaultFont
Creates a FontStyleBvr object that is a Times-Roman, black, 12pt font that is neither bold nor italicized.


DirectAnimation Animated Header --Static Methods Relevant to GeometryBvr Objects DirectAnimation Animated Header --Static Methods Relevant to GeometryBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to FontStyleBvr Objects
  * Next Topic: Static Fields Relevant to GeometryBvr Objects

Static Methods Relevant to GeometryBvr Objects

importGeometry

Statics Class

Creates a geometry behavior by synchronously importing the given VRML or .X file. Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See below for a description of the asynchronous import method.

public static GeometryBvr importGeometry(
URL url
);

Parameters
url
The fully-qualified pathname of the file to be downloaded. This parameter is of type java.net.URL.
Return Values

Returns the GeometryBvr object.

importGeometry

Statics Class

Creates a geometry behavior by asynchronously importing the given VRML or .X file. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import method, see above.

public static GeometryBvr importGeometry(
URL url,
GeometryBvr geoStandIn,
DXMEvent[] ev,
NumberBvr[] progress,
NumberBvr[] size
);

Parameters
url
The fully-qualified pathname of the geometry to be downloaded. This parameter is of type java.net.URL.
geoStandIn
The geometry to use while the contents at url are still being downloaded. This argument cannot be null.
ev
The event to trigger once the download is complete. This argument can be null.
progress
A NumberBvr that goes from 0 to 1, tracking the progress of the download. For files downloaded via http, progress is reported as the percentage of the file that has been downloaded. For other protocols, the value may simply start at 0 and change to 1 once the download is complete. This argument can be null.
size
The size of the geometry, in bytes. The value begins at -1 and will change to the true size if it is available. This argument can be null.
Return Values

Returns the GeometryBvr object.

soundSource

Statics Class

Creates a geometry behavior that contains the given sound behavior. The bounding box is the empty bounding box, where the maximum coordinate is less than the minimum coordinate.

public static GeometryBvr soundSource(
SoundBvr sound
);

Parameters
sound
The SoundBvr object.
Return Values

Returns the GeometryBvr object.

spotLight

Statics Class

Creates a spotlight geometry. A spotlight is a positioned, directed light source initially located at the origin and directed along the negative z-axis. Examples of real-world spotlights include desk lamps, headlights, and flashlights. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent.

The fullcone parameter specifies the half-angle of the region that will receive the full intensity of the spotlight. This parameter can have values from 0.00 to pi.

The cutoff parameter specifies the half-angle of the region past which surfaces will receive no illumination. This parameter can have values from the value of fullcone to pi.

public static GeometryBvr spotLight(
NumberBvr fullcone,
NumberBvr cutoff
);

Parameters
fullcone
The NumberBvr object specifying the angle in radians from the main spotlight axis for which surfaces will receive full illumination from the light.
cutoff
The NumberBvr object specifying the angle in radians from the main spotlight axis past which surfaces will receive no illumination from the light. This parameter can also be of type double.
Return Values

Returns the GeometryBvr object.

Remarks

Surfaces receive illumination from the spotlight in the following manner:

  • If the surface point is within fullcone radians of the main spotlight axis, the spotlight acts as a point light source (including distance attenuation effects).
  • If the surface point is greater than fullcone radians, but is within cutoff radians of the main spotlight axis, the surface receives illumination that is attenuated by the angular displacement.
  • If the surface point is greater than cutoff radians from the main spotlight axis, it receives no illumination.
Remarks

These rules are illustrated in the following diagram:

Remarks

The following diagram shows how the intensity of the spotlight changes in relationship to the angle:

union

Statics Class

Creates a geometry behavior by combining the given geometries. The new geometry contains all elements of the original geometries. The bounding box of a set of unioned geometries is simply the union of the bounding boxes of each of the geometries.

public static GeometryBvr union(
GeometryBvr g1,
GeometryBvr g2
);

Parameters
g1 and g2
The GeometryBvr objects.
Return Values

Returns the GeometryBvr object.

unionArray

Statics Class

Creates a geometry behavior by combining the geometries in the array. The new geometry contains all elements of the original geometries. The bounding box of a set of unioned geometries is simply the union of the bounding boxes of each of the geometries.

public static GeometryBvr unionArray(
GeometryBvr[],
geometries
);

Parameters
geometries
The array of GeometryBvr objects.
Return Values

Returns the GeometryBvr object.


DirectAnimation Animated Header --Static Fields Relevant to GeometryBvr Objects DirectAnimation Animated Header --Static Fields Relevant to GeometryBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to GeometryBvr Objects
  * Next Topic: Static Methods Relevant to ImageBvr Objects

Static Fields Relevant to GeometryBvr Objects

ambientLight
A geometry behavior (GeometryBvr object) in which the light source is ambient (room) light. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Ambient light is light that, instead of coming directly from a light source, bounces from surface to surface and provides overall scene-lighting. For example, if you are in a room lit by a lamp, everything not directly lit by the lamp is receiving ambient light. It leaves the lamp, bounces off the walls, the floors, the ceiling, and all around, until it reaches almost the entire room. Using too much ambient light can make a scene look washed out, while too little will yield shadowed areas that look unnaturally black. Unlike directional lights and point lights, transformations have no effect on ambient lights.
directionalLight
A geometry behavior (GeometryBvr object) in which the light source is positioned pointing down the negative z axis. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Directional light specifies a light such that the light direction is the same everywhere. This is in contrast to a positional light such as a point or spot light, where the direction to the light source changes depending on where the surface is. Directional lights are useful for simulating the sun because, from our perspective on earth, the sun's rays appear to travel in the same direction. Directional lights are also cheaper to compute than positional lights, though this difference may be negligible and should not be assumed. Transformations do have an effect on directional lights.
emptyGeometry
A geometry behavior (GeometryBvr object in which all points are invisible (transparent) and undetectable. The bounding box is the empty bounding box, where the maximum coordinate is less than the minimum coordinate.
pointLight
A geometry behavior (GeometryBvr object) in which the light source is positioned at the origin and radiates light in all directions. The bounding box is the empty bounding box, where the maximum extent is less than the minimum extent. Pointlights simulate most real-world lights such as bare light bulbs, wall-mounted light fixtures, and ceiling lights. They shine in all directions, radiating outward from the center. Transformations do have an effect on point lights.


DirectAnimation Animated Header --Static Methods Relevant to ImageBvr Objects DirectAnimation Animated Header --Static Methods Relevant to ImageBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to GeometryBvr Objects
  * Next Topic: Static Fields Relevant to ImageBvr Objects

Static Methods Relevant to ImageBvr Objects

gradientHorizontal

Statics Class

Creates an image behavior that smoothly interpolates between the start and stop colors. Colors start on the left and go toward the right, based on the power specified by fallOff. The extent of the generated image is [-0.5,-0.5] to [0.5,0.5].

public static ImageBvr gradientHorizontal(
ColorBvr start,
ColorBvr stop,
NumberBvr fallOff
);

Parameters
start
The ColorBvr object representing the first color of the gradient fill.
stop
The ColorBvr object representing the final color of the gradient fill.
fallOff
The NumberBvr object used to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

gradientPolygon

Statics Class

Creates a polygon from an array of points and an array of colors. The polygon has a smooth interpolation between the colors at the vertices. This interpolation is in RGB space. The image is transparent and unpickable outside the polygon. The polygon must be convex and fanned, with at least 3 vertices. The tessellation into triangles occurs by fanning around the first vertex. If, for example, the first triangle is from vertices [0, 1, 2], the second is from [0, 2, 3], and so on. The tessellation determines how the color interpolation is done. The bounding box is the box surrounding the points of the polygon.

public static ImageBvr gradientPolygon(
Point2Bvr[] pts,
ColorBvr[] colors
);

Parameters
pts
The array of points that determine the polygon's vertices.
colors
The array of colors corresponding to the vertices.
Return Values

Returns the ImageBvr object.

gradientSquare

Statics Class

Creates an image behavior with a square color wash. The image is a unit-sized square, centered at the origin, reaching from [-0.5, -0.5] to [0.5, 0.5]. The image contains the specified colors in the specified corners. The gradient fills are determined by bilinearly interpolating between these specified colors. (This means that, rather than being simply a four-cornered polygon, it is a polygon with four corners plus a point in the middle that is the average of the four colors.) The image is transparent and unpickable outside of this region. The interpolation is in RGB space. The bounding box is a box from (-0.5, -0.5) to (0.5, 0.5).

public static ImageBvr gradientSquare(
ColorBvr lowerLeft,
ColorBvr upperLeft,
ColorBvr upperRight,
ColorBvr lowerRight
);

Parameters
lowerLeft
The color in the lower-left hand corner of square.
upperLeft
The color in the upper-left hand corner of the square.
upperRight
The color in the upper-right hand corner of the square.
lowerRight
The color in the lower-right hand corner of the square.
Return Values

Returns the ImageBvr object.

hatchBackwardDiagonal

Statics Class

Creates backward diagonal (lines that slant from right to left) hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

public static ImageBvr hatchBackwardDiagonal(
ColorBvr color NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

hatchCross

Statics Class

Creates cross-hatched markings. This method can be thought of as a combination of the hatchVertical and the hatchHorizontal methods. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

public static ImageBvr hatchCross(
ColorBvr color,
NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

hatchDiagonalCross

Statics Class

Creates diagonally criss-crossed hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

public static ImageBvr hatchDiagonalCross(
ColorBvr color,
NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

hatchForwardDiagonal

Statics Class

Creates forward diagonal (lines that slant from left to right) hatch marks. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines.

public static ImageBvr hatchForwardDiagonal(
ColorBvr color,
NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

hatchHorizontal

Statics Class

Creates horizontal hatch lines. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

public static ImageBvr hatchHorizontal(
ColorBvr color,
NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

hatchVertical

Statics Class

Creates vertical hatch lines. All hatches fit in a box, of dimension size, that is infinitely tiled. For perpendicular hatches, the size of the box is twice the distance between the hatch lines. By default, hatch marks are black and appear on a transparent background.

public static ImageBvr hatchVertical(
ColorBvr color,
NumberBvr size
);

Parameters
color
The ColorBvr object representing the line color.
size
The NumberBvr object representing the size of the hatch box. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

importImage

Statics Class

Creates an image behavior by synchronously importing the given bitmap. The pixels of the bitmap are mapped to points in the image such that the center of the bitmap is placed at (0,0). The extent of the points affected depends on the width and height of the bitmap in pixels and the resolution of the bitmap in pixels per meter. The bounding box of an imported image is calculated as follows: If the pixel dimensions are W´H, and given that:

halfWidthMeters = Statics.pixel * W/2;
halfHeightMeters = Statics.pixel * H/2;

then the bounding box will be (-halfWidthMeters, -halfHeightMeters) to (halfWidthMeters, halfHeightMeters) with the resultant image centered at the origin.

Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See below for a description of the asynchronous import method.

public static importImage(
URL url
);

Parameters
url
The fully-qualified pathname of the image to be downloaded. This parameter is of type java.net.URL.
Return Values

Returns the ImageBvr object.

Remarks

The file formats that can be imported are .PNG, .JPG, .BMP, and .GIF.

See Also

importImageColorKey

importImage

Statics Class

Creates an image behavior by asynchronously importing the given bitmap. The pixels of the bitmap are mapped to points in the image such that the center of the bitmap is placed at (0,0). The extent of the points affected depends on the width and height of the bitmap in pixels and the resolution of the bitmap in pixels per meter. The bounding box of an imported image is calculated as follows: If the pixel dimensions are W´H, and given that:

halfWidthMeters = Statics.pixel * W/2;
halfHeightMeters = Statics.pixel * H/2;

then the bounding box will be (-halfWidthMeters, -halfHeightMeters) to (halfWidthMeters, halfHeightMeters) with the resultant image centered at the origin.

Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import method, see above.

public static ImageBvr importImage(
URL url,
ImageBvr imgStandIn,
DXMEvent[] ev,
NumberBvr[] progress,
NumberBvr[] size
);

Parameters
url
The fully-qualified pathname of the image to be downloaded. This parameter is of type java.net.URL.
imgStandIn
The image to use while the contents at url are still being downloaded. This argument cannot be null, however, the image can be empty.
ev
The event to trigger once the download is complete. This argument can be null.
progress
A NumberBvr that goes from 0 to 1, tracking the progress of the download. For files downloaded via http, progress is reported as the percentage of the file that has been downloaded. Other protocols, the value may simply start at 0 and change to 1 once the download is complete. This argument can be null.
size
A NumberBvr that is the size of the image, in bytes. The value begins at -1 and will change to the true size if it is available. This argument can be null.
Return Values

Returns the ImageBvr object.

Remarks

The file formats that can be imported are .PNG, .JPG, .BMP, and .GIF.

See Also

importImageColorKey

importImageColorKey

Statics Class

Allows a particular color in the synchronously imported image, specified by an RGB value, to be treated as transparent.

public static ImageBvr importImageColorKey(
URL url,
ColorBvr red,
ColorBvr green,
ColorBvr blue
);

Parameters
url
The pathname (a string) of the image to be downloaded.
red
The ColorBvr red component, expressed as a value ranging from 0 to 255.
green
The ColorBvr green component, expressed as a value ranging from 0 to 255.
blue
The ColorBvr blue component, expressed as a value ranging from 0 to 255.
Return Values

Returns the ImageBvr object.

Remarks

The file formats that can be imported are .PNG, .JPG, .BMP, and .GIF.

See Also

ImportImage

importImageColorKey

Statics Class

Allows a particular color in the asynchronously imported image, specified by an RGB value, to be treated as transparent.

public static ImageBvr importImage(
URL url,
ImageBvr imgStandIn,
DXMEvent[] ev,
NumberBvr[] progress,
NumberBvr[] size,
ColorBvr red,
ColorBvr green,
ColorBvr blue
);

Parameters
url
The pathname (a string) of the image to be downloaded.
imgStandIn
The image to use while the contents at url are still being downloaded. This argument cannot be null, however, the image can be empty.
ev
The event to trigger once the download is complete. This argument can be null.
progress
A NumberBvr that goes from 0 to 1, tracking the progress of the download. For files downloaded via http, progress is reported as the percentage of the file that has been downloaded. Other protocols, the value may simply start at 0 and change to 1 once the download is complete. This argument can be null.
size
A NumberBvr that is the size of the image, in bytes. The value begins at -1 and will change to the true size if it is available. This argument can be null.
red
The ColorBvr red component, expressed as a value ranging from 0 to 255.
green
The ColorBvr green component, expressed as a value ranging from 0 to 255.
blue
The ColorBvr blue component, expressed as a value ranging from 0 to 255.
Return Values

Returns the ImageBvr object.

Remarks

The file formats that can be imported are .PNG, .JPG, .BMP, and .GIF.

See Also

importImage

importMovie

Statics Class

Downloads a movie synchronously. Synchronous loads are blocking calls, which means that ticking will not continue on any model until all synchronous downloads are completed. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See below for a description of the asynchronous import method.

The image portion of a movie has the same bounding box and placement as a static image such as a PNG or JPEG. For more information, seeimportImage.

public static NumberBvr importMovie(
URL url,
ImageBvr[] img,
SoundBvr[] snd
);

Parameters
url
The fully-qualified pathname of the movie to be downloaded. This parameter is of type java.net.URL.
img
The image portion of the movie (passed by reference).
snd
The sound portion of the movie (passed by reference).
Return Values

Returns the NumberBvr object that is the length of the movie in seconds.

importMovie

Statics Class

Imports a movie asynchronously. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import method, see above.

The image portion of a movie has the same bounding box and placement as a static image such as a PNG or GIF. For more information, seeimportImage.

public static NumberBvr importMovie(
URL url,
ImageBvr[] img,
SoundBvr[] snd,
ImageBvr imgStandIn,
SoundBvr sndStandIn,
DXMEvent[] ev,
NumberBvr[] progress,
NumberBvr[] size
);

Parameters
url
The fully-qualified pathname of the movie to download. This parameter is of type java.net.URL.
img
The image portion of the movie (passed by reference).
snd
The sound portion of the movie (passed by reference).
imgStandIn
The image to use while the movie is still being downloaded. This parameter cannot be null, however, the image can be empty.
sndStandIn
The sound to use while the movie is still being downloaded. This parameter cannot be null, however, the sound can be silence.
progress
A NumberBvr that goes from 0 to 1, tracking the progress of the download. For files downloaded via http, progress is reported as the percentage of the file that has been downloaded. Other protocols, the value may simply start at 0 and change to 1 once the download is complete. This argument can be null.
size
A NumberBvr that is the size of the image, in bytes. The value begins at -1 and will change to the true size if it is available. This argument can be null.
Return Values

Returns the NumberBvr object that is the length of the movie in seconds.

overlay

Statics Class

Creates an image behavior by laying the image behavior i1 over the image behavior i2. The new image consists of all fully opaque points of i1, all points of i2 that are under fully transparent points in i1, and all partially opaque points of i1 modified such that the new point is a combination of the i1 point and the i2 point under it. The bounding box of a set of overlaid images is simply the union of the bounding boxes of the images themselves.

public static ImageBvr overlay(
ImageBvr i1,
ImageBvr i2
);

Parameters
i1 and i2
The ImageBvr objects.
Return Values

Returns the ImageBvr object.

overlayArray

Statics Class

Creates an image behavior by layering the ImageBvr objects. The bounding box of a set of overlaid images is simply the union of the bounding boxes of the images themselves.

public static ImageBvr overlayArray(
ImageBvr[] im
);

Parameters
im
The ImageBvr objects in the array.
Return Values

Returns the ImageBvr object.

radialGradientPolygon

Statics Class

Creates an image behavior that is a regular polygon with a radial fill. The image contains the specified colors at the origin and the exterior points, respectively. The gradient fill is determined by the fallOff argument and occurs in RGB space. Outside of the filled-in region, the image is transparent and unpickable. The bounding box is the box surrounding the points of the polygon.

public static ImageBvr radialGradientPolygon(
ColorBvr inner,
ColorBvr outer,
Point2Bvr[] points,
NumberBvr fallOff
);

Parameters
inner
The ColorBvr object representing the color at the origin of the polygon.
outer
The ColorBvr object representing the color at the vertices.
points
The Point2Bvr object representing the array of points that determine the polygon's vertices.
fallOff
The NumberBvr object used to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

radialGradientRegularPoly

Statics Class

Creates an image behavior that is a regular, gradient polygon with the specified number of sides (there must be at least 3) and a radial fill. The image contains the specified colors at the origin and the exterior points, respectively. The gradient fill is determined by the fallOff argument and occurs in RGB space. Outside of the filled-in region, the image is transparent and unpickable. The bounding box is the box surrounding the points of the polygon.

public static ImageBvr radialGradientRegularPoly(
ColorBvr inner,
ColorBvr outer,
NumberBvr edges,
NumberBvr fallOff
);

Parameters
inner
The ColorBvr object representing the color at the origin of the polygon.
outer
The ColorBvr object representing the color at the vertices.
edges
The NumberBvr object representing the number of edges the polygon has. This parameter can also be of type double.
fallOff
The NumberBvr object used to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

radialGradientSquare

Statics Class

Creates an image behavior with a square radial fill. The image is a unit-sized square, centered at the origin, reaching from [-0.5, -0.5] to [0.5, 0.5]. The image contains the specified colors in the center and at the corners, respectively. The gradient fill is determined by the fallOff argument. The interpolation occurs in RGB space. Outside of the fill, the image is transparent and unpickable. The bounding box is a box from [-0.5, -0.5] to [0.5, 0.5].

public static ImageBvr radialGradientSquare(
ColorBvr inner,
ColorBvr outer,
NumberBvr fallOff
);

Parameters
inner
The ColorBvr at the center of the image.
outer
The ColorBvr at the corners of the image.
fallOff
The NumberBvr object used to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue. This parameter can also be of type double.
Return Values

Returns the ImageBvr object.

solidColorImage

Statics Class

Creates an image behavior and applies the given color behavior to all points in the image. The bounding box of a solid-color image is the infinite bounding box.

public static ImageBvr solidColorImage(
ColorBvr col
);

Parameters
col
The ColorBvr object.
Return Values

Returns the ImageBvr object.

stringImage

Statics Class

Constructs an ImageBvr object from a StringBvr object and a FontStyleBvr object.

public static ImageBvr stringImage(
StringBvr string,
FontStyleBvr font
);

Parameters
string
The StringBvr object specifying the (potentially) animated text. This parameter can also be of type java.lang.String.
font
The FontStyleBvr object specifying the font style (this can include the face, the size, the color, and the attributes).
Return Values

Returns the ImageBvr object.


DirectAnimation Animated Header --Static Fields Relevant to ImageBvr Objects DirectAnimation Animated Header --Static Fields Relevant to ImageBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to ImageBvr Objects
  * Next Topic: Static Fields Relevant to JoinStyleBvr Objects

Static Fields Relevant to ImageBvr Objects

detectableEmptyImage
An image behavior (ImageBvr object) in which all points are transparent but detectable. This image is useful for blocking mouse input from underlying image, allowing that input to be redirected. The bounding box is of infinite extent.
emptyImage
An image behavior (ImageBvr object) in which all points are transparent and undetectable. This has a empty bounding box, which means that its maximum point is less than its minimum point. This allows operations such as union and intersection to produce the correct results.


DirectAnimation Animated Header --Static Fields Relevant to JoinStyleBvr Objects DirectAnimation Animated Header --Static Fields Relevant to JoinStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to ImageBvr Objects
  * Next Topic: Static Fields Relevant to LineStyleBvr Objects

Static Fields Relevant to JoinStyleBvr Objects

joinStyleBevel
An joinstyle behavior (JoinStyleBvr object) that joins two line segments by drawing a straight line between the outside corners of the segments and filling the resulting enclosed area.
joinStyleMiter
An joinstyle behavior (JoinStyleBvr object) that joins two line segments by extending the outside edges of the segments until they intersect and filling the resulting enclosed area. The miter length is defined as the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls on the outside of the join.
joinStyleRound
An joinstyle behavior (JoinStyleBvr object) that joins two line segments by drawing an arc between the outside corners of the segments and filling the resulting enclosed area. The center of the arc is at the common endpoint, the diameter is the width of the line.


DirectAnimation Animated Header --Static Fields Relevant to LineStyleBvr Objects DirectAnimation Animated Header --Static Fields Relevant to LineStyleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to JoinStyleBvr Objects
  * Next Topic: Static Methods Relevant to MatteBvr Objects

Static Fields Relevant to LineStyleBvr Objects

defaultLineStyle
A linestyle behavior (LineStyleBvr object) whose style is detail.


DirectAnimation Animated Header --Static Methods Relevant to MatteBvr Objects DirectAnimation Animated Header --Static Methods Relevant to MatteBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to LineStyleBvr Objects
  * Next Topic: Static Fields Relevant to MatteBvr Objects

Static Methods Relevant to MatteBvr Objects

difference

Statics Class

Creates a matte behavior that is the difference between the given mattes. The difference consists of only those elements of the path and/or text in m1 that are not also in m2.

public static MatteBvr difference(
MatteBvr m1,
MatteBvr m2
);

Parameters
m1 and m2
The MatteBvr objects.
Return Values

Returns the MatteBvr object.

See Also

intersect, union

fillMatte

Statics Class

Creates a matte behavior consisting of the given path behavior. Clipping an image with this matte preserves that portion of the image that is inside the path.

public static MatteBvr fillMatte(
Path2Bvr path
);

Parameters
path
The Path2Bvr object. If the path is not closed, the start and end points are implicitly connected to close the path.
Return Values

Returns the MatteBvr object.

See Also

textMatte

intersect

Statics Class

Creates a matte behavior that is the intersection of the given mattes. The intersection consists of only those elements of the paths and/or text of the original mattes that are the same.

public static MatteBvr intersect(
MatteBvr m1,
MatteBvr m2
);

Parameters
m1 and m2
The MatteBvr objects.
Return Values

Returns the MatteBvr object.

See Also

union, difference

textMatte

Statics Class

Creates a matte behavior consisting of the given StringBvr object, and with an appearance specified by the FontStyleBvr object. Clipping an image with this matte preserves that portion of the image that is inside the text.

public static MatteBvr textMatte(
StringBvr text,
FontStyleBvr fs
);

Parameters
text
The StringBvr object representing the text.
fs
The FontStyleBvr object representing the font style.
Return Values

Returns the MatteBvr object.

See Also

fillMatte

union

Statics Class

Creates a matte behavior that is the union of the given mattes. The union consists of all elements of the paths and/or text in the original mattes.

public static MatteBvr union(
MatteBvr m1,
MatteBvr m2
);

Parameters
m1 and m2
The MatteBvr objects.
Return Values

Returns the MatteBvr object.

See Also

intersect, difference


DirectAnimation Animated Header --Static Fields Relevant to MatteBvr Objects DirectAnimation Animated Header --Static Fields Relevant to MatteBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to MatteBvr Objects
  * Next Topic: Static Fields Relevant to MicrophoneBvr Objects

Static Fields Relevant to MatteBvr Objects

clearMatte
A matte behavior (MatteBvr object) that when applied to an image preserves the entire image (that is, it clips nothing).
opaqueMatte
A matte behavior (MatteBvr object) that when applied to an image clips the entire image (that is, preserves no part of the image).


DirectAnimation Animated Header --Static Fields Relevant to MicrophoneBvr Objects DirectAnimation Animated Header --Static Fields Relevant to MicrophoneBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to MatteBvr Objects
  * Next Topic: Static Methods (Miscellaneous)

Static Fields Relevant to MicrophoneBvr Objects

defaultMicrophone
A microphone behavior (MicrophoneBvr object) that is positioned at the origin, listening along the negative z axis with an upward orientation along the positive y axis.


Static Methods (Miscellaneous)

buildURL

Statics Class

Constructs a fully-qualified path from a base URL and a file pathname. The following code fragment constructs one URL for the directory where images are stored and another for where sounds are stored:

{
// This is a piece of a larger program
// Construct the URLs
URL mediabase = buildURL(getImportBase(), "../../../../../../Media/");
URL imgBase = buildURL(mediabase, "image/");
URL sndBase = buildURL(mediabase, "sound/");

//Create an image behavior by importing a bitmap
ImageBvr img = importImage(buildURL(imgBase, "img1.jpg");

//The rest of the program

}

public static URL buildURL(
URL url,
String pathname
);

Parameters
url
The base URL.
pathname
The file path.
Return Values

Returns a java.net.URL object.

getVersionString

Statics Class

Returns the version string in the form MM.NN.BBBB, where MM is the major version, NN is the minor version, and BBBB is the build number.

public static String getVersionString( );

Return Values

Returns the String object.


Static Fields (Miscellaneous)

cm
The centimeter unit. This returns a double
foot
The foot unit. This returns a double.
inch
The inch unit. This returns a double.
meter
The meter unit. This returns a double.
mm
The millimeter unit. This returns a double.
pixelBvr
The pixel unit. This returns a NumberBvr.


Static Methods Relevant to MontageBvr Objects

imageMontage

Statics Class

Creates a montage behavior consisting of a single image behavior at the given Z-value.

public static MontageBvr imageMontage(
ImageBvr image,
NumberBvr Z-value
);

Parameters
image
The ImageBvr object.
Z-value
The NumberBvr object. This parameter can also be of type double.
Return Values

Returns the MontageBvr object.

union

Statics Class

Creates a montage behavior by combining the given montage behaviors.

public static MontageBvr union(
MontageBvr m1,
MontageBvr m2
);

Parameters
m1 and m2
The MontageBvr objects.
Return Values

Returns the MontageBvr object.


DirectAnimation Animated Header --Static Fields Relevant to MontageBvr Objects DirectAnimation Animated Header --Static Fields Relevant to MontageBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to MontageBvr Objects
  * Next Topic: Static Methods Relevant to NumberBvr Objects

Static Fields Relevant to MontageBvr Objects

emptyMontage
A montage behavior (MontageBvr object) that contains no images.


DirectAnimation Animated Header --Static Methods Relevant to NumberBvr Objects DirectAnimation Animated Header --Static Methods Relevant to NumberBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to MontageBvr Objects
  * Next Topic: Static Fields Relevant to NumberBvr Objects

Static Methods Relevant to NumberBvr Objects

abs

Statics Class

Creates a number behavior that represents the absolute value of the given number behavior. The behavior's value is equal to the absolute value (the non-negative equivalent) of the value of a.

public static NumberBvr abs(
NumberBvr a
);

Parameters
a
The NumberBvr object to apply the operation to.
Return Values

Returns the NumberBvr object.

acos

Statics Class

Creates a number behavior that represents the arccosine (inverse cosine) of the given behavior.

public static NumberBvr acos(
NumberBvr a
);

Parameters
a
The NumberBvr object. The value of the behavior is assumed to be a cosine value.
Return Values

Returns the NumberBvr object.

See Also

asin

add

Statics Class

Creates a number behavior representing the sum of the given number behaviors. The behavior's value is the value of a added to the value of b (a + b).

public static NumberBvr add(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to add.
Return Values

Returns the NumberBvrobject.

asin

Statics Class

Creates a number behavior that represents the arcsine (inverse sine) of the given behavior.

public static NumberBvr asin(
NumberBvr a
);

Parameters
a
The NumberBvr object. The value of the behavior is assumed to be a sine value.
Return Values

Returns the NumberBvr object.

See Also

acos

atan

Statics Class

Creates a number behavior that represents the arctangent (inverse tangent) of the given behavior.

public static NumberBvr atan(
NumberBvr a
);

Parameters
a
The NumberBvr object.
Return Values

Returns the NumberBvr object.

See Also

acos, asin, atan2

atan2

Statics Class

Creates a number behavior that represents the arctangent (inverse tangent) of the quotient of the given behaviors. The behavior's value is the inverse tangent of the value of a divided by the value of b.

public static NumberBvr atan2(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to divide.
Return Values

Returns the NumberBvr object.

See Also

acos, asin

bSpline

Statics Class

Creates a NumberBvr behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned NumberBvr is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a NumberBvr that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

public static NumberBvr bSpline(
int degree,
NumberBvr[] knots,
NumberBvr[] control_elements,
NumberBvr[] weights,
NumberBvr evaluation
);

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
control_elements
An array of NumberBvr objects representing the control elements used to calculate the B-spline.
weights
An array of NumberBvr objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A NumberBvr object that controls the spline evaluation.
Return Values

Returns the NumberBvr object.

ceiling

Statics Class

Creates a number behavior that represents the ceiling value, the smallest integer value that is greater than or equal to the value of the given behavior.

public static NumberBvr ceiling(
NumberBvr a
);

Parameters
a
The NumberBvr object to find the ceiling for.
Return Values

Returns the NumberBvr object.

cos

Statics Class

Creates a number behavior that represents the cosine of the given behavior.

public static NumberBvr cos(
NumberBvr a
);

Parameters
a
The NumberBvr object. The value of the behavior is assumed to be in radians.
Return Values

Returns the NumberBvr object.

See Also

sin

degreesToRadians

Statics Class

Creates a number behavior that represents the value of the given behavior converted from degrees to radians.

public static NumberBvr degreesToRadians(
NumberBvr a
);

Parameters
a
The NumberBvr object to convert.
Return Values

Returns the NumberBvr object.

derivative

Statics Class

Creates a number behavior of the instantaneous derivative (rate of change) of the given number behavior. For example, a constant number yields a constant derivative of 0 and a value equal to "time" yields a constant derivative of 1.

public static NumberBvr derivative(
NumberBvr a
);

Parameters
a
The NumberBvr object for which to calculate the derivative.
Return Values

Returns the NumberBvr object.

div

Statics Class

Creates an number behavior representing the quotient of the given number behaviors. The behavior's value is the value of a divided by the value of b (a/b).

public static NumberBvr div(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to divide.
Return Values

Returns NumberBvr the object.

eq

Statics Class

Creates a boolean behavior that represents the relation a = b. The behavior's value is true when the value of a is equal to the value of b, otherwise, it is false.

public static BooleanBvr eq(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

exp

Statics Class

Creates a number behavior that represents the exponential of the given behavior. The behavior's value is the base of natural logarithms, e, raised to the power of the value of a.

public static NumberBvr exp(
NumberBvr a
);

Parameters
a
The NumberBvr object to apply as an exponent of e.
Return Values

Returns the NumberBvr object.

See Also

ln

floor

Statics Class

Creates a number behavior that represents the floor value, the largest integer value that is less than or equal to the value of the given behavior.

public static NumberBvr floor(
NumberBvr a
);

Parameters
a
The NumberBvr object to find the floor for.
Return Values

Returns the NumberBvr object.

gt

Statics Class

Creates a boolean behavior that represents the relation a > b. The behavior's value is true when the value of a is greater than the value of b, otherwise, it is false.

public static BooleanBvr gt(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

gte

Statics Class

Creates a boolean behavior that represents the relation a ³ b. The behavior's value is true when the value of a is greater than or equal to the value of b, otherwise, it is false.

public static BooleanBvr gte(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

integral

Statics Class

Creates a number behavior that represents the sum of all values of a from the start time to the present.

public static NumberBvr integral(
NumberBvr a
);

Parameters
a
The NumberBvr object to integrate.
Return Values

Returns the NumberBvr object.

interpolate

Statics Class

Creates a NumberBvr object that moves along the interval in duration seconds. Velocity is constant.

public static NumberBvr interpolate(
NumberBvr from,
NumberBvr to,
NumberBvr duration
);

Parameters
from
The beginning NumberBvr object. This parameter can also be of type double.
to
The ending NumberBvr object. This parameter can also be of type double.
duration
The NumberBvr object representing the length of time, in seconds. This parameter can also be of type double.
Return Values

Returns the NumberBvr object.

ln

Statics Class

Creates a number behavior that represents the natural logarithm of the given behavior. The behavior's value is the value by which the base of natural logarithms, e, must be raised to equal the value of a.

public static NumberBvr ln(
NumberBvr a
);

Parameters
a
The NumberBvr object for which to calculate the natural logarithm.
Return Values

Returns the NumberBvr object.

See Also

exp

log10

Statics Class

Creates a number behavior that represents the common logarithm (base-10 logarithm) of the given behavior. The behavior's value is the value by which 10 must be raised to equal the value of a.

public static NumberBvr log10(
NumberBvr a
);

Parameters
a
The NumberBvr object for which to calculate the common logarithm.
Return Values

Returns the NumberBvr object.

lt

Statics Class

Creates a boolean behavior that represents the relation a < b. The behavior's value is true when the value of a is less than the value of b, otherwise, it is false.

public static BooleanBvr lt(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

lte

Statics Class

Creates a boolean behavior that represents the relation a £ b. The behavior's value is true when the value of a is less than or equal to the value of b, otherwise, it is false.

public static BooleanBvr lte(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

mod

Statics Class

Creates a number behavior that represents the modulus of the given behaviors. The behavior's value is the modulus, the remainder of the integer value of a divided by the integer value of b.

public static NumberBvr mod(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to calculate the modulus for.
Return Values

Returns the NumberBvr object.

mul

Statics Class

Creates a number behavior representing the product of the given number behaviors. The behavior's value is the value of a multiplied by the value of b (a ´ b).

public static NumberBvr mul(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to multiply.
Return Values

Returns the NumberBvr object.

ne

Statics Class

Creates a BooleanBvr behavior that represents the relation a != b. The behavior's value is true when the value of a is not equal to the value of b, otherwise, it is false.

public static BooleanBvr ne(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to compare.
Return Values

Returns the BooleanBvr object.

neg

Statics Class

Creates a number behavior representing the negation of the given number behavior. The behavior's value is equal to the value of a subtracted from zero (0 - a).

public static NumberBvr neg(
NumberBvr a
);

Parameters
a
The NumberBvr object to negate.
Return Values

Returns the NumberBvr object.

pow

Statics Class

Creates a number behavior representing a raised to the power of b. The behavior's value is equal to ab.

public static NumberBvr pow(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to apply the operation to.
Return Values

Returns the NumberBvr object.

radiansToDegrees

Statics Class

Creates a number behavior that represents the value of the given behavior converted from radians to degrees.

public static NumberBvr radiansToDegrees(
NumberBvr a
);

Parameters
a
The NumberBvr object to convert.
Return Values

Returns the NumberBvr object.

round

Statics Class

Creates a number behavior that represents the value of the given behavior, rounded to the nearest integer.

public static NumberBvr round(
NumberBvr a
);

Parameters
a
The NumberBvr object to be rounded.

seededRandom

Statics Class

Creates a number behavior that represents an infinite, time-varying sequence of pseudo-random values.

public static NumberBvr seededRandom(
double seed
);

Parameters
seed
The double that provides the seed, or starting value, for the sequence.
Return Values

Returns the NumberBvr object.

sin

Statics Class

Creates a number behavior that represents the sine of the given behavior.

public static NumberBvr sin(
NumberBvr a
);

Parameters
a
The NumberBvr object. The value of the behavior is assumed to be in radians.
Return Values

Returns the NumberBvr object.

See Also

cos

slowInSlowOut

Statics Class

Creates a NumberBvr object that moves along the interval in duration seconds. The animation is dampened so that the number increases slowly, hits a maximum speed at the midpoint, and then decelerates until the end is reached. The acceleration is specified in Gs, or multiples of the earth's gravitational constant.

public static NumberBvr slowInSlowOut(
NumberBvr from,
NumberBvr to,
NumberBvr duration,
NumberBvr acceleration
);

Parameters
from
The NumberBvr object that is the beginning of the animation. This parameter can also be of type double.
to
The NumberBvr object that is the end of the animation. This parameter can also be of type double.
duration
The NumberBvr object that is the length of the animation, in seconds. This parameter can also be of type double.
acceleration
The NumberBvr object that is the rate of acceleration, in Gs. This parameter can also be of type double.
Return Values

Returns the NumberBvr object.

sqrt

Statics Class

Creates a number behavior that represents the square root of the given number behavior. The behavior's value is the square root of the value of a.

public static NumberBvr sqrt(
NumberBvr a
);

Parameters
a
The NumberBvr object to apply the square root operation to.
Return Values

Returns the NumberBvr object.

sub

Statics Class

Creates a number behavior representing the difference of the given number behaviors. The behavior's value is the value of b subtracted from a (a - b).

public static NumberBvr sub(
NumberBvr a,
NumberBvr b
);

Parameters
a and b
The NumberBvr objects to subtract.
Return Values

Returns the NumberBvr object.

tan

Statics Class

Creates a number behavior that represents the tangent of the given behavior.

public static NumberBvr tan(
NumberBvr a
);

Parameters
a
The NumberBvr object. The value of the behavior is assumed to be in radians.
Return Values

Returns the NumberBvr object.

See Also

atan, cos, sin

toBvr

Statics Class

Converts a double floating-point number to a NumberBvr. The only time toBvr is used is when converting Java numbers, booleans, or strings to their corresponding DirectAnimation types. It is not used for constants such as red, yVector3, and origin2 because these are defined as constant behaviors.

public static NumberBvr toBvr(
double a
);

Parameters
a
The double floating-point number to be converted.
Return Values

Returns the NumberBvr object.


DirectAnimation Animated Header --Static Fields Relevant to NumberBvr Objects DirectAnimation Animated Header --Static Fields Relevant to NumberBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to NumberBvr Objects
  * Next Topic: Static Methods Relevant to Path2Bvr Objects

Static Fields Relevant to NumberBvr Objects

globalTime
A number behavior (NumberBvr object) the value of which increases at the rate of one unit per second. Unlike localTime, the globalTime value cannot be reset to zero.
localTime
A number behavior (NumberBvr object) that starts a zero when "started" and increases at the rate of one unit per second.


DirectAnimation Animated Header --Static Methods Relevant to Path2Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Path2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to NumberBvr Objects
  * Next Topic: Static Methods Relevant to Point2Bvr Objects

Static Methods Relevant to Path2Bvr Objects

arc

Statics Class

Creates a Path2Bvr object representing a segment of an oval (In effect, an arc). The oval is centered at the origin.

public static Path2Bvr arc(
NumberBvr startAngle,
NumberBvr endAngle,
NumberBvr arcWidth,
NumberBvr arcHeight
);

Parameters
startAngle
The NumberBvr object representing the starting angle of the arc, expressed in radians. This parameter can also be of type double.
endAngle
The NumberBvr object representing the ending angle of the arc, expressed in radians. This parameter can also be of type double.
arcWidth
The NumberBvr object representing the width of the arc, expressed in meters. This parameter can also be of type double.
arcHeight
The NumberBvr object representing the height of the arc, expressed in meters. This parameter can also be of type double.
Return Values

Returns the Path2Bvr object.

arcDegrees

Statics Class

Creates a Path2Bvr object representing a segment of an oval (In effect, this is an arc). The oval is centered at the origin.

public static Path2Bvr arcDegrees(
double startAngle,
double endAngle,
double arcWidth,
double arcHeight
);

Parameters
startAngle
The double representing the starting angle of the oval segment, expressed in degrees.
endAngle
The double representing the ending angle of the oval segment, expressed in degrees.
arcWidth
The double representing the width of the arc, expressed in meters.
arcHeight
The double representing the height of the arc, expressed in meters.
Return Values

Returns the Path2Bvr object.

concat

Statics Class

Creates a path behavior that represents the concatenation of the given path behaviors. In the new path, the points of p1 occur first, followed by those of p2. Path p2 is transformed so that the first point of p2 aligns with the last point of p1.

public static Path2Bvr concat(
Path2Bvr p1,
Path2Bvr p2
);

Parameters
p1 and p2
The Path2Bvr objects.
Return Values

Returns the Path2Bvrobject.

concatArray

Statics Class

Creates a path behavior that represents the concatenation of the Path2Bvr objects in the array. In the new path, the points of the first path in the array occur first, followed sequentially by the other paths in the array. The second path, for example, is transformed so that its first point aligns with the last point of the first path.

public static Path2Bvr concatArray(
Path2Bvr[] paths
);

Parameters
paths
The array of Path2Bvr objects.
Return Values

Returns the Path2Bvrobject.

cubicBSplinePath

Statics Class

Creates a Path2Bvr behavior based on a cubic B-spline curve. The curve depends on the control points and the knot vector, and requires that:

numberofPoints = numberofKnots - 2

The control points define the approximate direction and shape of the function. The knots represent the junction values, in parameter space, between the connected polynomial parts. For a number of knots k, the function is valid in the range [3, knotk-2], and is otherwise undefined.

public static Path2Bvr cubicBSplinePath(
Point2Bvr[] points,
NumberBvr[] knots
);

Parameters
points
An array of Point2Bvr objects representing the points used to calculate the B-spline.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
Return Values

Returns the Path2Bvr object.

line

Statics Class

Creates a path behavior that represents the line segment defined by the given point behaviors.

public static Path2Bvr line(
Point2Bvr p1,
Point2Bvr p2
);

Parameters
p1 and p2
The Point2Bvr objects.
Return Values

Returns the Path2Bvrobject.

oval

Statics Class

Creates a Path2Bvr object that represents an oval, centered about the origin, and whose width and height are described by the given NumberBvr arguments.

public static Path2Bvr oval(
NumberBvr width,
NumberBvr height
);

Parameters
x-radius
The NumberBvr object representing the oval's width. This parameter can also be of type double.
y-radius
The NumberBvr object representing the oval's height. This parameter can also be of type double.
Return Values

Returns the Path2Bvr object.

pie

Statics Class

Creates a Path2Bvr object representing a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge). The oval is centered at the origin.

public static Path2Bvr pie(
NumberBvr startAngle,
NumberBvr endAngle,
NumberBvr arcWidth,
arcHeight
);

Parameters
startAngle
The NumberBvr object representing the starting angle of the oval segment, expressed in radians. This parameter can also be of type double.
endAngle
The NumberBvr object representing the ending angle of the oval segment, expressed in radians. This parameter can also be of type double.
arcWidth
The NumberBvr object representing the width of the arc, expressed in meters. This parameter can also be of type double.
arcHeight
The NumberBvr object representing the height of the arc, expressed in meters. This parameter can also be of type double.
Return Values

Returns the Path2Bvr object.

pieDegrees

Statics Class

Creates a Path2Bvr object representing a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge). The oval is centered at the origin.

public static Path2Bvr pieDegrees(
double startAngle,
double endAngle,
double arcWidth,
double arcHeight
);

Parameters
startAngle
The double representing the starting angle of the oval segment, expressed in degrees.
endAngle
The double representing the ending angle of the oval segment, expressed in degrees.
arcWidth
The double representing the width of the arc, expressed in meters.
arcHeight
The double representing the height of the arc, expressed in meters.
Return Values

Returns the Path2Bvr object.

polydrawPath

Statics Class

Creates a Path2Bvr object by manipulating the array of points with the codes contained in the NumberBvr array. The codes represent the instructions that can be OR'd together, where:
Code | Name | Meaning
01 | PT_CLOSEFIGURE | Connects points to create a closed figure.
02 | PT_LINETO | Connects points in a line.
04 | PT_BEZIERTO | Connects points in a Bezier curve. These must occur in multiples of 3.
06 | PT_MOVETO | Moves to a point. This is, implicitly, always the first instruction.

public static Path2Bvr polydrawPath(
Point2Bvr[] points,
NumberBvr[] codes
);

Parameters
points
An array of Point2Bvr objects.
codes
An array of NumberBvr objects representing the instruction codes.
Return Values

Returns the Path2Bvr object.

Remarks

This function is equivalent to the Graphics Drawing Interface (GDI) polydraw function.

polyline

Statics Class

Creates a path behavior that consists of the given point behaviors. The path can be used either for drawing or animation. The default line style is the defaultLineStyle.

public static Path2Bvr polyline(
Point2Bvr[] points
);

Parameters
points
An array of Point2Bvr objects.
Return Values

Returns the Path2Bvr object.

ray

Statics Class

Creates a path behavior that represents the line segment from the origin to the given point behavior.

public static Path2Bvr ray(
Point2Bvr p
);

Parameters
p
The Point2Bvr object.
Return Values

Returns the Path2Bvrobject.

rect

Statics Class

Creates the Path2Bvr object representing a rectangle, centered at the origin.

public static Path2Bvr rect(
NumberBvr width,
NumberBvr height
);

Parameters
width
The NumberBvr object representing the width of the rectangle. This parameter can also be of type double.
height
The NumberBvr object representing the height of the rectangle. This parameter can also be of type double.
Return Values

Returns the Path2Bvr object.

roundRect

Statics Class

Creates a Path2Bvr object that is a rectangle, centered about the origin, with rounded, rather than square, corners. The corners are considered to be segments of an oval (in effect, an arc), centered at the origin.

public static Path2Bvr roundRect(
NumberBvr width,
NumberBvr height,
NumberBvr arcWidth,
NumberBvr arcHeight
);

Parameters
width
The NumberBvr object representing the rectangle's width. This parameter can also be of type double.
height
The NumberBvr object representing the rectangle's height. This parameter can also be of type double.
arcWidth
The NumberBvr object representing the width of the arc, expressed in meters. This parameter can also be of type double.
arcHeight
The NumberBvr object representing the height of the arc, expressed in meters. This parameter can also be of type double.
Return Values

Returns the Path2Bvr object.

stringPath

Statics Class

Creates a Path2Bvr object from the supplied StringBvr object. The appearance is specified by the FontStyleBvr object. The path behavior is useful for creating a matte to which an image behavior can be clipped.

public static Path2Bvr stringPath(
StringBvr string,
FontStyleBvr fs
);

Parameters
string
The StringBvr object used to create the Path2Bvr object. This parameter can also be of type java.lang.String.
fs
The FontStyleBvr object specifying the appearance of the string.
Return Values

Returns the Path2Bvr object.

See Also

draw, fill


DirectAnimation Animated Header --Static Methods Relevant to Point2Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Point2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Path2Bvr Objects
  * Next Topic: Static Fields Relevant to Point2Bvr Objects

Static Methods Relevant to Point2Bvr Objects

add

Statics Class

Creates a two-dimensional point behavior. The location of the point is calculated by adding the corresponding coordinates of the given point and vector behaviors.

public static Point2Bvr add(
Point2Bvr pt,
Vector2Bvr vec
);

Parameters
pt
A Point2Bvr object.
vec
A Vector2Bvr object.
Return Values

Returns the Point2Bvr object.

See Also

sub

bSpline

Statics Class

Creates a Point2Bvr behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned Point2Bvr is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a NumberBvr that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

public static Point2Bvr bSpline(
int degree,
NumberBvr[] knots,
Point2Bvr[] control_elements,
NumberBvr[] weights,
NumberBvr evaluation
);

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
control_elements
An array of Point2Bvr objects representing the control elements used to calculate the B-spline.
weights
An array of NumberBvr objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A NumberBvr object that controls the spline evaluation.
Return Values

Returns the Point2Bvr object.

derivative

Statics Class

Creates a two-dimensional vector behavior of the instantaneous derivative (rate of change) of the given point behavior. For example, a constant yields a constant derivative of [0 0], and point2(time, 0) (without additional time substitutions) yields a constant derivative of [1 0].

public static Vector2Bvr derivative(
Point2Bvr pt
);

Parameters
pt
A Point2Bvr object.
Return Values

Returns the Vector2Bvr object.

distance

Statics Class

Creates a number behavior representing the distance between two point behaviors.

public static NumberBvr distance(
Point2Bvr p1,
Point2Bvr p2
);

Parameters
p1 and p2
The Point2Bvr objects.
Return Values

Returns the NumberBvr object.

See Also

distanceSquared

distanceSquared

Statics Class

Creates a number behavior representing the square of the distance between two point behaviors. This is the same as the distance method except that the distance is squared.

public static NumberBvr distanceSquared(
Point2Bvr p1,
Point2Bvr p2
);

Parameters
p1 and p2
The Point2Bvr objects.
Return Values

Returns the NumberBvr object.

See Also

distance

point2

Statics Class

Creates a two-dimensional point behavior. The location of the point is given in Cartesian coordinates.

public static Point2Bvr point2(
NumberBvr x,
NumberBvr y
);

Parameters
x and y
The NumberBvr objects, specifying the coordinate values. The x specifies the distance along the x-axis from the origin to the point, and y specifies the distance along the y-axis. These parameters can also be of type double.
Return Values

Returns the Point2Bvr object.

See Also

point2Polar

point2Polar

Statics Class

Creates a two-dimensional point behavior. The location of the point is given in polar coordinates.

public static Point2Bvr point2Polar(
NumberBvr XYangle,
NumberBvr length
);

Parameters
XYangle
The NumberBvr object specifying the angle, in radians, between the positive x-axis and the ray that goes from the origin to the point. This parameter can also be of type double.
length
The NumberBvr object specifying the distance from the origin to the point. This parameter can also be of type double.
Return Values

Returns the Point2Bvr object.

See Also

point2

sub

Statics Class

Creates a two-dimensional vector behavior. The coordinate values of the vector are calculated by subtracting the coordinates of p2 from the corresponding coordinates of p1.

public static Vector2Bvr sub(
Point2Bvr p1,
Point2Bvr p2
);

Parameters
p1 and p2
The Point2Bvr objects.
Return Values

Returns the Vector2Bvr object.

sub

Statics Class

Creates a two-dimensional point behavior. The location of the point is calculated by subtracting the coordinates of the given vector behavior from the corresponding coordinates of the given point behavior.

public static Point2Bvr sub(
Point2Bvr pt,
Vector2Bvr vec
);

Parameters
pt
A Point2Bvr object.
vec
A Vector2Bvr object.
Return Values

Returns the Point2Bvr object.

See Also

add

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


DirectAnimation Animated Header --Static Fields Relevant to Point2Bvr Objects DirectAnimation Animated Header --Static Fields Relevant to Point2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Point2Bvr Objects
  * Next Topic: Static Methods Relevant to Point3Bvr Objects

Static Fields Relevant to Point2Bvr Objects

mouseposition
A two-dimensional point behavior (Point2Bvr object) that is the current location of the mouse.
origin2
A two-dimensional point behavior (Point2Bvr object) that is always located at the origin.


DirectAnimation Animated Header --Static Methods Relevant to Point3Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Point3Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to Point2Bvr Objects
  * Next Topic: Static Fields Relevant to Point3Bvr Objects

Static Methods Relevant to Point3Bvr Objects

add

Statics Class

Creates a three-dimensional point behavior. The location of the point is calculated by adding the corresponding coordinates of the given point and vector behaviors.

public static Point3Bvr add(
Point3Bvr pt,
Vector3Bvr vec
);

Parameters
pt
A Point3Bvr object.
vec
A Vector3Bvr object.
Return Values

Returns the Point3Bvr object.

See Also

sub

bSpline

Statics Class

Creates a Point3Bvr behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned Point3Bvr is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a NumberBvr that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

public static Point3Bvr bSpline(
int degree,
NumberBvr[] knots,
Point3Bvr[] control_elements,
NumberBvr[] weights,
NumberBvr evaluation
);

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
control_elements
An array of Point3Bvr objects representing the control elements used to calculate the B-spline.
weights
An array of NumberBvr objects representing the weights used to calculate the B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A NumberBvr object that controls the spline evaluation.
Return Values

Returns the Point3Bvr object.

derivative

Statics Class

Creates a three-dimensional vector behavior of the instantaneous derivative (rate of change) of the given point behavior. For example, a constant yields a constant derivative of [0 0 0], and point3(time, 0) (without additional time substitutions) yields a constant derivative of [1 0 0].

public static Vector3Bvr derivative(
Point3Bvr pt
);

Parameters
pt
A Point3Bvr object.
Return Values

Returns the Vector3Bvr object.

distance

Statics Class

Creates a number behavior representing the distance between two point behaviors.

public static NumberBvr distance(
Point3Bvr p1,
Point3Bvr p2
);

Parameters
p1 and p3
The Point3Bvr objects.
Return Values

Returns the NumberBvr object.

See Also

distanceSquared

distanceSquared

Statics Class

Creates a number behavior representing the square of the distance between two point behaviors. This is the same as the distance method except that the distance is squared.

public static NumberBvr distanceSquared(
Point3Bvr p1,
Point3Bvr p2
);

Parameters
p1 and p3
The Point3Bvr objects.
Return Values

Returns the NumberBvr object.

Remarks

This method is slightly more efficient than the distance method.

See Also

distance

point3

Statics Class

Creates a three-dimensional point behavior. The location of the point is given in Cartesian coordinates.

public static Point3Bvr point3(
NumberBvr x,
NumberBvr y,
NumberBvr z
);

Parameters
x, y, and z
The NumberBvr objects, specifying the coordinate values. The x specifies the distance along the x-axis from the origin to the point, y specifies the distance along the y-axis, and z the distance along the z-axis. These parameters can also be of type double.
Return Values

Returns the Point3Bvr object.

See Also

point3Spherical

point3Spherical

Statics Class

Creates a three-dimensional point behavior. The location of the point is given in spherical coordinates.

public static Point3Bvr point3Spherical(
NumberBvr XYangle,
NumberBvr YZangle,
NumberBvr length
);

Parameters
XYangle
A NumberBvr object of the counter-clockwise XY angle, in radians, of the point about the positive y-ray. The angle begins at the positive z-ray, so that [0 0 1] has a XYangle of 0, and [1 0 0] has a XYangle of pi/2. This parameter can also be of type double.
YZangle
A NumberBvr object of the counter-clockwise elevation angle, in radians, of the point above the XZ-plane. A YZangle of pi/2 means the point is straight up (on the positive y-ray), and a YZangle of -pi/2 is straight down (on the negative y-ray). This parameter can also be of type double.
length
A NumberBvr object of the distance of the point from the origin. This parameter can also be of type double.
Return Values

Returns the Point3Bvr object.

Remarks

The following table correlates Cartesian coordinates with polar coordinates:
Cartesian | XYangle | YZangle | Length
Coordinates
[0 0 0] | X | X | 0
[d 0 0] | pi/2 | 0 | d
[-d 0 0] | -pi/2 | 0 | d | X = Don't Care
[0 d 0] | X | pi/2 | d
[0 -d 0] | X | -pi/2 | d
[0 0 d] | 0 | 0 | d
[0 0 -d] | pi | 0 | d

See Also

point3

sub

Statics Class

Creates a three-dimensional vector behavior. The coordinate values of the vector are calculated by subtracting the coordinates of p3 from the corresponding coordinates of p1.

public static Vector3Bvr sub(
Point3Bvr p1,
Point3Bvr p2
);

Parameters
p1 and p3
The Point3Bvr objects.
Return Values

Returns the Vector3Bvr object.

sub

Statics Class

Creates a three-dimensional point behavior. The location of the point is calculated by subtracting the coordinates of the given vector behavior from the corresponding coordinates of the given point behavior.

public static Point3Bvr sub(
Point3Bvr pt,
Vector3Bvr vec
);

Parameters
pt
A Point3Bvr object.
vec
A Vector3Bvr object.
Return Values

Returns the Point3Bvr object.

See Also

add

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


DirectAnimation Animated Header --Static Fields Relevant to Point3Bvr Objects DirectAnimation Animated Header --Static Fields Relevant to Point3Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Point3Bvr Objects
  * Next Topic: Static Methods Relevant to SoundBvr Objects

Static Fields Relevant to Point3Bvr Objects

origin3
A three-dimensional point behavior (Point3Bvr object) that is always located at the origin.


DirectAnimation Animated Header --Static Methods Relevant to SoundBvr Objects DirectAnimation Animated Header --Static Methods Relevant to SoundBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to Point3Bvr Objects
  * Next Topic: Static Fields Relevant to SoundBvr Objects

Static Methods Relevant to SoundBvr Objects

importSound

Statics Class

Creates a sound behavior by synchronously importing the given .WAV or MIDI file. The soundLength parameter receives the length of the sound. These downloads should be small and listed before asynchronous downloads. Use asynchronous downloads for more complex images and sounds. See below for a description of the asynchronous import method.

public static SoundBvr importSound(
URL url,
NumberBvr[] soundLength
)

Parameters
url
soundLength
A NumberBvr array that receives the length of the sound in seconds. An array is used because this is an output parameter, and the system writes into the first element of the array. In Java, this is the simplest way to pass information back to the caller if you are already using the return value, which, in this case, is the sound).
Return Values

Returns the SoundBvr object.

importSound

Statics Class

Creates a SoundBvr by asynchronously importing the given .WAV or .MIDI file. Asynchronous downloads should be listed after synchronous ones and used for more complex sounds and images. For a description of the synchronous import method, see above.

public static SoundBvr importSound(
URL url,
NumberBvr[] soundLength,
SoundBvr sndStandIn,
DXMEvent[] ev,
NumberBvr[] progress,
NumberBvr[] size
);

Parameters
url
The fully qualified pathname of the file. It is of type java.net.URL.
soundLength
The length, in seconds, of the sound.
sndStandIn
The sound to use while the contents at url are still being downloaded. This argument cannot be null, however, the sound can be silence.
ev
The event to trigger once the download is complete. This argument can be null. Using this event is probably the best way to determine when the download is complete. (Otherwise, the Java constant Double.POSITIVE_INFINITY must be extracted.
progress
A NumberBvr that goes from 0 to 1, tracking the progress of the download. For files downloaded via http, progress is reported as the percentage of the file that has been downloaded. Other protocols, the value may simply start at 0 and change to 1 once the download is complete. This argument can be null.
size
A NumberBvr that is the size of the sound, in bytes. The value begins at -1 and will change to the true size if it is available. This argument can be null.
Return Values

Returns the SoundBvr object.

mix

Statics Class

Creates a sound behavior that is equivalent to sound1 + sound2.

public static SoundBvr mix(
SoundBvr sound1,
SoundBvr sound2
);

Parameters
sound1 and sound2
The SoundBvr objects.
Return Values

Returns the SoundBvr object.

mixArray

Statics Class

Creates a sound behavior that is equivalent to sound1 + sound2 + soundn.

public static SoundBvr mixArray(
SoundBvr[] sounds
);

Parameters
sounds
The SoundBvr objects in the array.
Return Values

Returns the SoundBvr object.


DirectAnimation Animated Header --Static Fields Relevant to SoundBvr Objects DirectAnimation Animated Header --Static Fields Relevant to SoundBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to SoundBvr Objects
  * Next Topic: Static Methods Relevant to StringBvr Objects

Static Fields Relevant to SoundBvr Objects

silence
A sound behavior (SoundBvr object) that is always completely silent (no sound).
sinSynth
A sound behavior (SoundBvr object) that represents a constant tone. This sound is synthesized using a sine wave.


DirectAnimation Animated Header --Static Methods Relevant to StringBvr Objects DirectAnimation Animated Header --Static Methods Relevant to StringBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to SoundBvr Objects
  * Next Topic: Static Methods Relevant to Transform2Bvr Objects

Static Methods Relevant to StringBvr Objects

concat

Statics Class

Creates a string behavior representing the concatenation of the given behaviors. The behavior's value is the character string consisting of the value of b appended to the end of the value of a.

public static StringBvr concat(
StringBvr a,
StringBvr b
);

Parameters
a and b
The StringBvr objects to concatenate.
Return Values

Returns the StringBvr object.

toBvr

Statics Class

Converts a type of Java.lang.String to a StringBvr. The only time toBvr is used is when converting Java numbers, booleans, or strings to their corresponding DirectAnimation types. It is not used for constants such as red, yVector3, and origin2 because these are defined as constant behaviors.

public static StringBvr toBvr(
String string
);

Parameters
string
The String type to be converted.
Return Values

Returns the StringBvr object;


DirectAnimation Animated Header --Static Methods Relevant to Transform2Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Transform2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to StringBvr Objects
  * Next Topic: Static Fields Relevant to Transform2Bvr Objects

Static Methods Relevant to Transform2Bvr Objects

compose

Statics Class

Creates a two-dimensional transformation behavior that is a composition of the given transformation behaviors.

public static Transform2Bvr compose(
Transform2Bvr xf1,
Transform2Bvr xf2
);

Parameters
xf1 and xf2
The Transform2Bvr objects.
Return Values

Returns the Transform2Bvr object.

Remarks

Composing a transform is equivalent to first applying xf2 and then applying xf1. In other words:

im.transform(compose(xf1, xf2) == im.transform(xf2).transform(xf1)

compose2Array

Statics Class

Creates a two-dimensional transformation behavior that is a composition of the Transform2Bvr objects included in the array.

public static Transform2Bvr compose2Array(
Transform2Bvr[] xforms
);

Parameters
xforms
The Transform2Bvr objects.
Return Values

Returns the Transform2Bvr object.

Remarks

Composing a transform is equivalent to first applying the nth transform, then applying the (nth-1) transform, and so on.

followPath

Statics Class

Creates a Transform2Bvr object that is a translation (from the origin) that follows a 2-D vector drawing path. The Path2Bvr object is converted into the equivalent translation transform.

public static Transform2Bvr followPath(
Path2Bvr path,
NumberBvr evaluator
);

Parameters
path
The Path2Bvr object that will be traced.
evaluator
The NumberBvr object representing an evaluator with a value in the range [0, 1]. This value is equivalent to a position on the path, where 0 is the beginning of the path and 1 is the end. This parameter can also be of type double. If it is, then the parameter is treated as a duration, representing the amount of time it will take (in seconds) to trace the entire path.
Return Values

Returns the Transform2Bvr object.

followPathAngle

Statics Class

Creates a Transform2Bvr object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative.

public static Transform2Bvr followPathAngle(
Path2Bvr path,
NumberBvr evaluator
);

Parameters
path
The Path2Bvr object this is traversed.
evaluator
The NumberBvr object representing an evaluator with a value in the range [0, 1]. This value is equivalent to a position on the path, where 0 is the beginning of the path and 1 is the end. This parameter can also be of type double. If it is, then the parameter is treated as a duration, representing the amount of time it will take (in seconds) to trace the entire path.
Return Values

Returns the Transform2Bvr object.

followPathAngleUpright

Statics Class

Creates a Transform2Bvr object that is equal to the angle of the path's tangent while it is being traversed, translated by its position. This is equivalent to rotating the position by its derivative, except that the angle that is perpendicular to the X-axis (in local coordinates) will always be less than 180 degrees.

public static Transform2Bvr followPathAngleUpright(
Path2Bvr path,
NumberBvr evaluator
);

Parameters
path
The Path2Bvr object that is traversed.
evaluator
The NumberBvr object representing an evaluator with a value in the range [0, 1]. This value is equivalent to a position on the path, where 0 is the beginning of the path and 1 is the end. This parameter can also be of type double. If it is, then the parameter is treated as a duration, representing the amount of time it will take (in seconds) to trace the entire path.
Return Values

Returns the Transform2Bvr object.

rotate

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in radians).

public static Transform2Bvr rotate(
NumberBvr radians
);

Parameters
radians
The NumberBvr object representing the angle of rotation. This parameter can also be of type double.
Return Values

Returns the Transform2Bvr object.

Remarks

Rotations are counter-clockwise.

rotateDegrees

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in degrees).

public static Transform2Bvr rotateDegrees(
double degrees
);

Parameters
degrees
The double representing the angle of rotation (expressed in degrees).
Return Values

Returns the Transform2Bvr object.

Remarks

Rotations are counter-clockwise.

rotateRate

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in radians). This value is multiplied by localTime to determine the rotation rate.

public static Transform2Bvr rotateRate(
double radians
);

Parameters
radians
The double representing the angle of rotation, multiplied by localTime. The unit is radians/second.
Return Values

Returns the Transform2Bvr object.

Remarks

Rotations are counter-clockwise.

rotateRateDegrees

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, rotates it by the given angle (expressed in degrees). This value is multiplied by localTime to determine the rotation rate.

public static Transform2Bvr rotateRateDegrees(
double degrees
);

Parameters
degrees
The double representing the angle of rotation, multiplied by localTime. The unit is degrees/second.
Return Values

Returns the Transform2Bvr object.

Remarks

Rotations are counter-clockwise.

scale

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, scales it. For example, the transformation modifies the length of a vector by multiplying the vector's coordinates by the values of the corresponding number behaviors.

public static Transform2Bvr scale(
NumberBvr sx,
NumberBvr sy
);

Parameters
sx and sy
The NumberBvr objects representing the amount to scale. The value of sx applies to the x coordinate, and sy to the y coordinate. These parameters can also be of type double.
Return Values

Returns the Transform2Bvr object.

scale

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, scales it. For example, the transformation modifies the location of a point by multiplying the point's coordinates by the values of the corresponding vector coordinates.

public static Transform2Bvr scale(
Vector2Bvr v
);

Parameters
v
The Vector2Bvr object. The x and y coordinates of the vector behavior specify the amount to scale the x and y coordinates, respectively.
Return Values

Returns the Transform2Bvr object.

scaleRate

Statics Class

Creates a two-dimensional transformation behavior that, when applied to any two-dimensional object, scales it. The scaling rates are determined by multiplying each argument by localTime.

public static Transform2Bvr scaleRate(
double x,
double y
);

Parameters
sx and sy
The doubles representing the amounts to scale. The value of sx applies to the x coordinate, and sy to the y coordinate.
Return Values

Returns the Transform2Bvr object.

scale2

Statics Class

Creates a two-dimensional transformation behavior that applies a uniform scale to every coordinate of a two-dimensional object.

public static Transform2Bvr scale2(
NumberBvr uniformFactor
);

Parameters
uniformFactor
The NumberBvr object representing the value to apply to both the x and y coordinates, respectively. This parameter can also be of type double.
Return Values

Returns the Transform2Bvr object.

See Also

scale, scale

scale2Rate

Statics Class

Creates a two-dimensional transformation behavior that applies a uniform scale to every coordinate of a two-dimensional object. The scaling rate is determined by multiplying the argument by localTime.

public static Transform2Bvr scale2Rate(
double rate
);

Parameters
rate
The double representing the value to apply to both the x and y coordinates, respectively.
Return Values

Returns the Transform2Bvr object.

transform3x2

Statics Class

Creates a two-dimensional transformation behavior that consists of a 3 by 2 matrix having the values specified by the given number behaviors.

public static Transform2Bvr transform3x2(
NumberBvr[] matrix
);

Parameters
matrix
A 3 by 2 matrix. The top row of the matrix could be represented as containing NumberBvr objects a00, a01, and a02. Use a00 to scale the x coordinate and a02 to translate x.
The bottom row of the matrix could be represented as containing the NumberBvr objects a10, a11, and a12. Use a11 to scale the y coordinate and a12 to translate y.
Return Values

Returns the Transform2Bvr object.

Remarks

The X and Y translation components are given by a02 and a12, respectively.

translate

Statics Class

Creates a two-dimensional transformation behavior that, when applied to a point behavior, translates (moves) the point by the amount given by the number behaviors.

public static Transform2Bvr translate(
NumberBvr tx,
NumberBvr ty
);

Parameters
tx and ty
The NumberBvr objects representing the amount to translate the point along the x and y axes, respectively. These parameters can also be of type double.
Return Values

Returns the Transform2Bvr object.

Remarks

Two-dimensional vectors are unchanged by translations.

translate

Statics Class

Creates a two-dimensional transformation that, when applied to a point, translates (moves) the point to the new location loc.

public static Transform2Bvr translate(
Point2Bvr loc
);

Parameters
loc
The Point2Bvr object specifying the new location.
Return Values

Returns the Transform2Bvr object.

translate

Statics Class

Creates a two-dimensional transformation behavior that when applied to a point behavior translates (moves) the point by the amount given by the vector behavior.

public static Transform2Bvr translate(
Vector2Bvr v
);

Parameters
v
The Vector2Bvr object. The x and y coordinates of the vector behavior specify the amount to translate along the x and y axes, respectively.
Return Values

Returns the Transform2Bvr object.

Remarks

Two-dimensional vectors are unchanged by translations.

translateRate

Statics Class

Creates a two-dimensional transformation behavior that, when applied to a point, translates (moves) the point by the amount given by the arguments. The translation rates are determined by multiplying the arguments by localTime.

public static Transform2Bvr translateRate(
double x,
double y
);

Parameters
x and y
The doubles representing the amounts to translate the point along the X and Y axes, respectively.
Return Values

Returns the Transform2Bvr object.

Remarks

Two-dimensional vectors are unchanged by translations.

xShear

Statics Class

Creates a two-dimensional transformation behavior that shears the x-axis either up or down. This means the X-coordinate of the points remains unchanged, and the Y-coordinate increases by the product of the X-coordinate and the shear factor. In other words, X2 = X1, and Y2 = Y1 + aX1, where a is the shear factor.

public static Transform2Bvr xShear(
NumberBvr x
);

Parameters
x
The NumberBvr object representing the amount to shear. This parameter can also be of type double.
Return Values

Returns the Transform2Bvr object.

See Also

yShear

xShearRate

Statics Class

Creates a two-dimensional transformation behavior that shears the x-axis either up or down. The shear rate is determined by multiplying the argument by localTime.

public static Transform2Bvr xShearRate(
double rate
);

Parameters
rate
The double representing the amount to shear, multiplied by localTime. The unit is meters/second.
Return Values

Returns the Transform2Bvr object.

yShear

Statics Class

Creates a two-dimensional transformation behavior that shears the y-axis either left or right. This means the Y-coordinate of the points remains unchanged, and the X-coordinate increases by the product of the Y-coordinate and the shear factor. In other words, Y2 = Y1 and X2 = X1 + aY1, where a is the shear factor.

public static Transform2Bvr yShear(
NumberBvr y
);

Parameters
y
The NumberBvr object representing the amount to shear. This parameter can also be of type double.
Return Values

Returns the Transform2Bvr object.

See Also

xShear

yShearRate

Statics Class

Creates a two-dimensional transformation behavior that shears the y-axis either left or right. The shear rate is determined by multiplying the argument by localTime.

public static Transform2Bvr yShearRate(
double rate
);

Parameters
rate
The double representing the amount to shear the y-axis, multiplied by localTime. The unit is meters/second.
Return Values

Returns the Transform2Bvr object.


DirectAnimation Animated Header --Static Fields Relevant to Transform2Bvr Objects DirectAnimation Animated Header --Static Fields Relevant to Transform2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Transform2Bvr Objects
  * Next Topic: Static Methods Relevant to Transform3Bvr Objects

Static Fields Relevant to Transform2Bvr Objects

identityTransform2
A two-dimensional transformation behavior (Transform2Bvr object) that leaves the two-dimensional space unchanged. Applying this transformation to a point or vector produces the same point or vector.


DirectAnimation Animated Header --Static Methods Relevant to Transform3Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Transform3Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to Transform2Bvr Objects
  * Next Topic: Static Fields Relevant to Transform3Bvr Objects

Static Methods Relevant to Transform3Bvr Objects

compose

Statics Class

Creates a three-dimensional transformation behavior that is a composition of the given transformation behaviors.

public static Transform3Bvr compose(
Transform3Bvr xf1,
Transform3Bvr xf2
);

Parameters
xf1 and xf2
The Transform3Bvr objects.
Return Values

Returns the Transform3Bvr object.

Remarks

Composing a transform is equivalent to first applying xf2 and then applying xf1. In other words:

geo.transform(compose(xf1, xf2) == geo.transform(xf2).transform(xf1)

compose3Array

Statics Class

Creates a three-dimensional transformation behavior that is a composition of the Transform3Bvr objects in the array.

public static Transform3Bvr compose3Array(
Transform3Bvr[] xforms
);

Parameters
xf1 and xf2
The Transform3Bvr objects.
Return Values

Returns the Transform3Bvr object.

Remarks

Composing a transform is equivalent to first applying the nth transform, then applying the (nth-1) transform, and so on.

lookAtFrom

Statics Class

Creates a three-dimensional transformation behavior that transforms an object from a standard position and orientation to the "from" point, and aimed at the "to" point, with "up" mapping to the object's up direction. Prior to this transform, objects must be located at the origin, with the up side aligned with positive y, and aimed in the negative z-direction.

public static Transform3Bvr lookAtFrom(
Point3Bvr from,
Point3Bvr to,
Vector3Bvr up
);

Parameters
from
The Point3Bvr object specifying the point from which to view.
to
The Point3Bvr object specifying the point toward which to view.
up
The Point3Bvr object specifying the point determining the upright position.
Return Values

Returns the Transform3Bvr object.

Remarks

This transform is useful for positioning and orienting cameras, lights, microphones, and other three-dimensional objects.

rotate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in radians) around the given axis.

public static Transform3Bvr rotate(
Vector3Bvr axis,
NumberBvr radians
);

Parameters
axis
The Vector3Bvr object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
radians
The NumberBvr object representing the angle of rotation. This parameter can also be of type double.
Return Values

Returns the Transform3Bvr object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

rotateDegrees

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in degrees) around the given axis.

public static Transform3Bvr rotateDegrees(
Vector3Bvr axis,
double degrees
);

Parameters
axis
The Vector3Bvr object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
degrees
The double representing the angle of rotation (expressed in degrees).
Return Values

Returns the Transform3Bvr object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

rotateRate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in radians) around the given axis. The rotation rate is determined by multiplying the angle by localTime.

public static Transform3Bvr rotateRate(
Vector3Bvr axis,
double radians
);

Parameters
axis
The Vector3Bvr object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
radians
The double representing the angle of rotation, multiplied by localTime. The unit is radians/second.
Return Values

Returns the Transform3Bvr object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

rotateRateDegrees

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point or vector behavior, rotates the point or vector by the given angle (expressed in degrees) around the given axis. The rotation rate is determined by multiplying the angle by localTime.

public static Transform3Bvr rotateRateDegrees(
Vector3Bvr axis,
double degrees
);

Parameters
axis
The Vector3Bvr object representing the axis around which to rotate. The plane of rotation is perpendicular to the ray defined by this vector.
degrees
The double representing the angle of rotation (expressed in degrees) multiplied by localTime. The unit is degrees/second.
Return Values

Returns the Transform3Bvr object.

Remarks

Rotations obey the right-hand rule. This means that, when looking down the axis vector, they are counter-clockwise.

scale

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it. For example, the transformation modifies the length of a vector by multiplying the vector's coordinates by the values of the corresponding number behaviors.

public static Transform3Bvr scale(
NumberBvr sx,
NumberBvr sy,
NumberBvr sz
);

Parameters
sx, sy, and sz
The NumberBvr objects representing the amounts to scale. The value of sx applies to the x coordinate, sy to the y coordinate, and sz to the z coordinate. These parameters can also be of type double.
Return Values

Returns the Transform3Bvr object.

scale

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it. For example, the transformation modifies the location of a point by multiplying the point's coordinates by the values of the corresponding vector coordinates.

public static Transform3Bvr scale(
Vector3Bvr v
);

Parameters
v
The Vector3Bvr object. The x, y, and z coordinates of the vector behavior specify the amounts to scale the x, y, and z coordinates, respectively.
Return Values

Returns the Transform3Bvr object.

scaleRate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it. The scaling rates are determined by multiplying the arguments by localTime.

public Transform3Bvr scaleRate(
double x,
double y,
double z
);

Parameters
x, y, and z
The doubles representing the amounts to scale. The value of x applies to the x coordinate, y to the y coordinate, and z to the z coordinate.
Return Values

Returns the Transform3Bvr object.

scale3

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it uniformly.

public static Transform3Bvr scale3(
NumberBvr uniformFactor
);

Parameters
uniformFactor
The NumberBvr object representing the value to apply to the x, y, and z coordinates, respectively. This parameter can also be of type double.
Return Values

Returns the Transform3Bvr object.

See Also

scale, scale

scale3Rate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a three-dimensional object, scales it uniformly. The scaling rate is determined by multiplying the argument by localTime.

public Transform3Bvr scale3Rate(
double rate
);

Parameters
rate
The double representing the value to apply to the x, y, and z coordinates, respectively, multiplied by localTime. The unit is degrees/second.
Return Values

Returns the Transform3Bvr object.

transform4x4

Statics Class

Creates a three-dimensional transformation behavior that consists of the 4 by 4 matrix having the values specified by the given number behaviors.

public static Transform3Bvr transform4x4(
NumberBvr[] matrix
);

Parameters
matrix
The 4 by 4 matrix. The first row of the matrix can be represented by the NumberBvr objects a00, a01, a02, a03. Use a00 to scale the x coordinate and a03 to translate x.
The second row of the matrix can be represented by the NumberBvr objects a10, a11, a12, a13. Use a11 to scale the y coordinate and a13 to translate y.
The third row of the matrix can be represented by the NumberBvr objects a20, a21, a22, a23. Use a22 to scale the z coordinate and a23 to translate z.
The fourth row of the matrix can be represented by the NumberBvr objects a30, a31, a32, a33.
Return Values

Returns the Transform3Bvr object.

Remarks

The translation components for the matrix are in the last column. The last row of the matrix must be [0 0 0 1].

translate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point behavior, translates (moves) the point by the amounts given by the number behaviors.

public static Transform3Bvr translate(
NumberBvr tx,
NumberBvr ty,
NumberBvr tz
);

Parameters
tx, ty, and tz
The NumberBvr objects representing the amounts to translate the point along the x, y, and z axes, respectively. These parameters can also be of type double.
Return Values

Returns the Transform3Bvr object.

Remarks

Vectors are unchanged by translations.

translate

Statics Class

Creates a two-dimensional transformation that, when applied to a point, translates (moves) the point to the new location loc.

public static Transform3Bvr translate(
Point3Bvr loc
);

Parameters
loc
The Point3Bvr object specifying the new location.
Return Values

Returns the Transform3Bvr object.

translate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point behavior, translates (moves) the point by the amounts given by the vector behavior.

public static Transform3Bvr translate(
Vector3Bvr v
);

Parameters
v
The Vector3Bvr object. The x, y, and z coordinates of the vector behavior specify the amounts to translate along the x, y, and z axes, respectively.
Return Values

Returns the Transform3Bvr object.

Remarks

Vectors are unchanged by translations.

translateRate

Statics Class

Creates a three-dimensional transformation behavior that, when applied to a point behavior, translates (moves) the point by the amounts given by the doubles. The translation rate is determined by multiplying the arguments by localTime.

public Transform3Bvr translateRate(
double x,
double y,
double z
);

Parameters
x, y, and z
The doubles representing the amounts to translate the point along the x, y, and z axes, respectively.
Return Values

Returns the Transform3Bvr object.

Remarks

Vectors are unchanged by translations.

xShear

Statics Class

Shears the x-axis in the positive y-direction by a and in the positive z-direction by b. The X-coordinate remains unchanged, and the Y and Z coordinates increase by the product of the X-coordinate and the shear factors. In other words, X2 = X1, Y2 = Y1 + aX1, and Z2 = Z1 + bX1, where a and b are the shear factors.

public static Transform3Bvr xShear(
NumberBvr a,
NumberBvr b
);

Parameters
a
The NumberBvr object representing the amount of shear in the Y direction. This parameter can also be of type double.
b
The NumberBvr object representing the amount of shear in the Z direction. This parameter can also be of type double.
Return Values

Returns the Transform3Bvr object.

See Also

yShear, zShear

xShearRate

Statics Class

Shears the x-axis in the positive y-direction by a and in the positive z-direction by b. The shear rates are determined by multiplying the arguments by localTime.

public static Transform3Bvr xShearRate(
double a,
double b
);

Parameters
a
The double representing the amount of shear in the Y direction, multiplied by localTime. The unit is meters/second.
b
The double representing the amount of shear in the Z direction, multiplied by localTime. The unit is meters/second.
Return Values

Returns the Transform3Bvr object.

See Also

yShear, zShear

yShear

Statics Class

Shears the y-axis in the positive x-direction by c and in the positive z-direction by d. The Y-coordinate remains unchanged, and the X and Z coordinates increase by the product of the Y-coordinate and the shear factors. In other words, Y2 = Y1, X2 = X1 + cY1, and Z2 = Z1 + dY1, where c and d are the shear factors.

public static Transform3Bvr yShear(
NumberBvr c,
NumberBvr d
);

Parameters
c
The NumberBvr object representing the amount of shear in the X direction. This parameter can also be of type double.
d
The NumberBvr object representing the amount of shear in the Z direction. This parameter can also be of type double.
Return Values

Returns the Transform3Bvr object.

See Also

xShear, zShear

yShearRate

Statics Class

Shears the y-axis in the positive x-direction by c and in the positive z-direction by d. The shear rates are determined by multiplying the arguments by localTime.

public static Transform3Bvr yShearRate(
double c,
double d
);

Parameters
c
The double representing the amount of shear in the X direction, multiplied by localTime. The unit is meters/second.
d
The double representing the amount of shear in the Z direction, multiplied by localTime. The unit is meters/second.
Return Values

Returns the Transform3Bvr object.

See Also

xShear, zShear

zShear

Statics Class

Shears the z-axis in the positive x-direction by e and in the positive y-direction by f. The Z-coordinate remains unchanged, and the X and Y coordinates increase by the product of the Z-coordinate and the shear factors. In other words, Z2 = Z1, X2 = X1 + eZ1, and Y2 = Y1 + fZ1, where e and f are the shear factors.

public static Transform3Bvr zShear(
NumberBvr e,
NumberBvr f
);

Parameters
e
The NumberBvr object representing the amount of shear in the X direction. This parameter can also be of type double.
f
The NumberBvr object representing the amount of shear in the Y direction. This parameter can also be of type double.
Return Values

Returns the Transform3Bvr object.

See Also

xShear, yShear

zShearRate

Statics Class

Shears the z-axis in the positive x-direction by e and in the positive y-direction by f. The shear rates are determined by multiplying the arguments by localTime.

public static Transform3Bvr zShearRate(
double e,
double f
);

Parameters
e
The double representing the amount of shear in the X direction, multiplied by localTime. The unit is meters/second.
f
The double representing the amount of shear in the Y direction, multiplied by localTime. The unit is meters/second.
Return Values

Returns the Transform3Bvr object.

See Also

xShear, yShear


DirectAnimation Animated Header --Static Fields Relevant to Transform3Bvr Objects DirectAnimation Animated Header --Static Fields Relevant to Transform3Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Transform3Bvr Objects
  * Next Topic: Static Methods Relevant to TupleBvr Objects

Static Fields Relevant to Transform3Bvr Objects

identityTransform3
A three-dimensional transformation behavior (Transform3Bvr object) that leaves the three-dimensional space unchanged. Applying this transformation to a point or vector produces the same point or vector.


DirectAnimation Animated Header --Static Methods Relevant to TupleBvr Objects DirectAnimation Animated Header --Static Methods Relevant to TupleBvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to Transform3Bvr Objects
  * Next Topic: Static Methods Relevant to Vector2Bvr Objects

Static Methods Relevant to TupleBvr Objects

pairBvr

Statics Class

A convenience utility for creating a TupleBvr object with two members.

public static TupleBvr pairBvr(
Behavior first,
Behavior second
);

Parameters
first
The first Behavior object in the TupleBvr.
second
The second Behavior object in the TupleBvr.
Return Values

Returns the TupleBvr object.

tripleBvr

Statics Class

A convenience utility for creating a TupleBvr object with three members.

public static TupleBvr tripleBvr(
Behavior first,
Behavior second,
Behavior third
);

Parameters
first
The first Behavior object in the TupleBvr.
second
The second Behavior object in the TupleBvr.
third
The third Behavior object in the TupleBvr.
Return Values

Returns the TupleBvr object.


DirectAnimation Animated Header --Static Methods Relevant to Vector2Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Vector2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to TupleBvr Objects
  * Next Topic: Static Fields Relevant to Vector2Bvr Objects

Static Methods Relevant to Vector2Bvr Objects

add

Statics Class

Creates a two-dimensional vector behavior that is the vector-valued sum of the two vectors.

public static Vector2Bvr add(
Vector2Bvr v1,
Vector2Bvr v2
);

Parameters
v1 and v2
The Vector2Bvr objects.
Return Values

Returns the Vector2Bvr object.

See Also

sub

bSpline

Statics Class

Creates a Vector2Bvr behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned Vector2Bvr is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a NumberBvr that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

public static Vector2Bvr bSpline(
int degree,
NumberBvr[] knots,
Vector2Bvr[] control_elements,
NumberBvr[] weights,
NumberBvr evaluation
);

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
control_elements
An array of Point2Bvr objects representing the control elements used to calculate the B-spline.
weights
An array of NumberBvr objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
evaluation
A NumberBvr object that controls the spline evaluation.
Return Values

Returns the Vector2Bvr object.

derivative

Statics Class

Creates a new, two-dimensional vector behavior that is the instantaneous derivative (rate of change) of the given vector behavior. For example, a constant vector behavior yields a constant derivative of [0 0], and vector2(time, 0) (without any additional time substitutions) yields a constant derivative vector of [1 0].

public static Vector2Bvr derivative(
Vector2Bvr vec
);

Parameters
vec
A Vector2Bvr object.
Return Values

Returns the Vector2Bvr object.

dot

Statics Class

Creates a number behavior that represent the "dot product" of the given vectors. The dot product is the product of the lengths of the vectors and the cosine of the angle between them.

public static NumberBvr dot(
Vector2Bvr v1,
Vector2Bvr v2
);

Parameters
v1 and v2
The Vector2Bvr objects.
Return Values

Returns the NumberBvr object.

integral

Statics Class

Creates an two-dimensional vector that represents the sum of the all values of vec from the given start time to the present.

public static Vector2Bvr integral(
Vector2Bvr vec
);

Parameters
a
The Vector2Bvr object.
Return Values

Returns the Vector2Bvr object.

neg

Statics Class

Creates a new two-dimensional vector that is the same length as the original vector but points in the opposite direction.

public static Vector2Bvr neg(
Vector2Bvr v1
);

Parameters
v1
A Vector2Bvr object that is the original vector.
Return Values

Returns the Vector2Bvr object.

sub

Statics Class

Creates a two-dimensional vector behavior. The direction and length of the vector are calculated by subtracting the coordinates of v2 from the corresponding coordinates of v1.

public static Vector2Bvr sub(
Vector2Bvr v1,
Vector2Bvr v2
);

Parameters
v1 and v2
The Vector2Bvr objects.
Return Values

Returns the Vector2Bvr object.

See Also

add

vector2

Statics Class

Creates a two-dimensional vector behavior, having a direction and length as specified by the given Cartesian coordinates.

public static Vector2Bvr vector2(
NumberBvr x,
NumberBvr y
);

Parameters
x
The NumberBvr object specifying the distance along the x-axis from the origin to a point. This parameter can also be of type double.
y
NumberBvr object specifying the distance along the y-axis. This parameter can also be of type double.
Return Values

Returns the Vector2Bvr object.

See Also

vector2Polar

vector2Polar

Statics Class

Creates a two-dimensional vector behavior, having a direction and length as specified by the given polar coordinates.

public static Vector2Bvr vector2Polar(
NumberBvr XYangle,
NumberBvr length
);

Parameters
XYangle
The NumberBvr object that is the counter-clockwise angle of the vector, in radians, from the positive x-ray. This parameter can also be of type double.
length
The NumberBvr object that is the length of the vector. This parameter can also be of type double.
Return Values

Returns the Vector2Bvr object.

See Also

vector2

vector2PolarDegrees

Statics Class

Creates a two-dimensional vector behavior, having a direction and length as specified by the given polar coordinates.

public static Vector2Bvr vector2PolarDegrees(
double XYangle,
double length
);

Parameters
XYangle
The double that is the counter-clockwise angle of the vector (expressed in degrees) from the positive x-ray.
length
The double that is the length of the vector.
Return Values

Returns the Vector2Bvr object.


DirectAnimation Animated Header --Static Fields Relevant to Vector2Bvr Objects DirectAnimation Animated Header --Static Fields Relevant to Vector2Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Methods Relevant to Vector2Bvr Objects
  * Next Topic: Static Methods Relevant to Vector3Bvr Objects

Static Fields Relevant to Vector2Bvr Objects

xVector2
A two-dimensional vector behavior (Vector2Bvr object) that represents the unit vector on the x-axis. The vector's length is always 1, the direction is always the same as the positive x-axis.
yVector2
A two-dimensional vector behavior (Vector2Bvr object) that represents the unit vector on the y-axis. The vector's length is always 1, the direction is always the same as the positive y-axis.
zeroVector2
A two-dimensional vector behavior (Vector2Bvr object) that represents the null vector. The vector's length is always 0, the direction is undefined.


DirectAnimation Animated Header --Static Methods Relevant to Vector3Bvr Objects DirectAnimation Animated Header --Static Methods Relevant to Vector3Bvr Objects * Microsoft DirectAnimation SDK
  * Previous Topic: Static Fields Relevant to Vector2Bvr Objects
  * Next Topic: Static Fields Relevant to Vector3Bvr Objects

Static Methods Relevant to Vector3Bvr Objects

add

Statics Class

Creates a three-dimensional vector behavior. The direction and length of the vector are calculated by adding the corresponding coordinates of the given vectors.

public static Vector3Bvr add(
Vector3Bvr v1,
Vector3Bvr v2
);

Parameters
v1 and v2
The Vector3Bvr objects.
Return Values

Returns the Vector3Bvr object.

See Also

sub

bSpline

Statics Class

Creates a Vector3Bvr behavior based on a B-spline function. The function depends on the control elements, the knot vector, the mathematical degree, and the weights of the control elements (these are optional).

A B-spline function without weights is piecewise polynomial and with weights is piecewise rational (the quotient of two polynomials). It requires that:

numberOfControlElements = numberOfKnots - degree + 1

The control elements define the approximate direction and shape of the function. The knots represent junction values, in parameter space, between the connected polynomial parts.

Given a degree d and a number of knots k, the function is valid in the range knotd to knotk-d+1, and is otherwise undefined. For example, for a degree 2 curve, the valid range is from the second knot to the next to the last knot, inclusive.

The returned Vector3Bvr is the traversal of the spline function according to the evaluation parameter. The evaluation parameter is a NumberBvr that must be in the valid range of the spline, which is [knotd, knotk-d+1]. Any values outside this range are automatically clamped to the end values.

public static Vector3Bvr bSpline(
int degree,
NumberBvr[] knots,
Vector3Bvr[] control_elements,
NumberBvr[] weights,
NumberBvr evaluation
);

Parameters
degree
A number representing the mathematical degree of the B-spline to evaluate. Must be 1, 2, or 3.
knots
An array of NumberBvr objects representing the knots used to calculate the B-spline.
control_elements
An array of Vector3Bvr objects representing the control elements used to calculate the B-spline.
weights
An array of NumberBvr objects representing the weights used to calculate the rational B-spline. There must be the same number of weights as control elements. For non-rational B-splines, the value of weights is null.
Return Values

Returns the Vector3Bvr object.

cross

Statics Class

Creates a vector behavior that represents the "cross product" of the given vectors. The new vector has a length that is equal to the product of the lengths of the original vectors and the sine of the angle between them. The new vector has a direction that is perpendicular to the plane formed by the original vectors and that obeys the right-hand rule.

public static Vector3Bvr cross(
Vector3Bvr v1,
Vector3Bvr v2
);

Parameters
v1 and v2
The Vector3Bvr objects.
Return Values

Returns the Vector3Bvr object.

derivative

Statics Class

Creates a new, three-dimensional vector behavior that is the instantaneous derivative (rate of change) of the given vector behavior. For example, a constant vector behavior yields a constant derivative of [0 0 0], and vector3(time, 0, 0) (without any additional time substitutions) yields a constant derivative vector of [1 0 0].

public static Vector3Bvr derivative(
Vector3Bvr vec
);

Parameters
vec
A Vector3Bvr object.
Return Values

Returns the Vector3Bvr object.

dot

Statics Class

Creates a number behavior that represent the "dot product" of the given vectors. The dot product is the product of the lengths of the vectors and the cosine of the angle between them.

public static NumberBvr dot(
Vector3Bvr v1,
Vector3Bvr v2
);

Parameters
v1 and v2
Vector3Bvr objects.
Return Values

Returns the NumberBvr object.

integral

Statics Class

Creates an three-dimensional vector that represents the sum of the all values of vec from the given start time to the present.

public static Vector3Bvr integral(
Vector3Bvr vec
);

Parameters
a
The Vector3Bvr object.
Return Values

Returns the Vector3Bvr object.

neg

Statics Class

Creates a new three-dimensional vector behavior that has the same length as the original vector, but points in the opposite direction.

public static Vector3Bvr neg(
Vector3Bvr v1
);

Parameters
v1
A Vector3Bvr object that is the original vector.
Return Values

Returns the Vector3Bvr object.

sub

Statics Class

Creates a three-dimensional vector behavior. The direction and length of the vector are calculated by subtracting the coordinates of v2 from the corresponding coordinates of v1.

public static Vector3Bvr sub(
Vector3Bvr v1,
Vector3Bvr v2
);

Parameters
v1 and v2
Vector3Bvr objects.
Return Values

Returns the Vector3Bvr object.

See Also

add

vector3Spherical

Statics Class

Creates a three-dimensional vector behavior, having a direction and length as specified by the given spherical coordinates.

public static Vector3Bvr vector3Spherical(
NumberBvr XYangle,
NumberBvr YZangle,
NumberBvr length
);

Parameters
XYangle
A NumberBvr object of the counter-clockwise XY angle, in radians, of the point about the positive y-axis. The angle begins at the positive z-ray, so that [0 0 1] has a XYangle of 0, and [1 0 0] has a XYangle of pi/2. This parameter can also be of type double.
YZangle
A NumberBvr object of the counter-clockwise elevation angle, in radians, of the point above the XZ-plane. A YZangle of pi/2 means the point is straight up (on the positive y-ray), and a YZangle of -pi/2 is straight down (on the negative y-ray). This parameter can also be of type double.
length
A NumberBvr object specifying the length of the vector. This parameter can also be of type double.
Return Values

Returns the Vector3Bvr object.

Remarks

The following table correlates Cartesian coordinates with polar coordinates:
Cartesian | XYangle | YZangle | Length
Coordinates
[0 0 0] | X | X | 0
[d 0 0] | pi/2 | 0 | d
[-d 0 0] | -pi/2 | 0 | d | X = Don't Care
[0 d 0] | X | pi/2 | d
[0 -d 0] | X | -pi/2 | d
[0 0 d] | 0 | 0 | d
[0 0 -d] | pi | 0 | d

See Also

vector3

vector3

Statics Class

Creates a three-dimensional vector behavior, having a direction and length as specified by the given Cartesian coordinates.

public static Vector3Bvr vector3(
NumberBvr x,
NumberBvr y,
NumberBvr z
);

Parameters
x, y, and z
The NumberBvr objects specifying the coordinate values. The x specifies a distance along the x-axis from the origin to a point, y specifies a distance along the y-axis, and z a distance along the z-axis. These parameters can also be of type double.
Return Values

Returns the Vector3Bvr object.

See Also

vector3Spherical

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


Static Fields Relevant to Vector3Bvr Objects

xVector3
A three-dimensional vector behavior (Vector3Bvr object) that represents the unit vector on the x-axis. The vector's length is always 1, the direction is always the same as the positive x-axis.
yVector3
A three-dimensional vector behavior (Vector3Bvr object) that represents the unit vector on the y-axis. The vector's length is always 1, the direction is always the same as the positive y-axis.
zVector3
A three-dimensional vector behavior (Vector3Bvr object) that represents the unit vector on the z-axis. The vector's length is always 1, the direction is always the same as the positive z-axis.
zeroVector3
A three-dimensional vector behavior (Vector3Bvr object) that represents the null vector. The vector's length is always 0, the direction is undefined.


StringBvr Class

public class StringBvr extends Behavior {
    // Methods
    public Object extract();

    public static StringBvr newUninitBvr();
}

Creates an object that represents a string behavior. At any given time, the value of the behavior is a character string.

For more information about behaviors, see the Behavior class.

  • StringBvr Methods
  • Relevant Methods from the Statics Class

StringBvr Methods

extract

newUninitBvr

extract

StringBvr Class

Extracts the value of the behavior, returning a Java object. This behavior must have a constant value.

public Object extract( );

Return Values

Returns a Java object. For more information about java.lang.Object objects, consult a Java reference.

newUninitBvr

StringBvr Class

Allows you to refer to an StringBvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static StringBvr newUninitBvr( );

Parameters
b
A character string.
Return Values

Returns the StringBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type StringBvr.

public static StringBvr concat(StringBvr a, StringBvr b);

public static StringBvr toBvr(String string);


Transform2Bvr Class

public class Transform2Bvr extends Behavior {

    // Methods
    public Transform2Bvr inverse();
    public BooleanBvr    isSingular();

    public static Transform2Bvr newUninitBvr();
}

Creates an object that represents a two-dimensional transformation behavior. The behavior consists of a 3 by 2 matrix of number behaviors that can be applied to two-dimensional point behaviors to translate, scale, rotate or skew the location of the point, and can be applied to two-dimensional vector behaviors to scale, rotate, or skew the length and/or direction of the vector.

Because matrix values are number behaviors (NumberBvr objects), the transformation behavior may change over time as the number behaviors change. For more information about behaviors, see the Behavior class.

  • Transform2Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Transform2Bvr Methods

inverse

isSingular

newUninitBvr

inverse

Transform2Bvr Class

Creates a transformation behavior that is the inverse of the original transformation.

public Transform2Bvr inverse( );

Return Values

Returns the Transform2Bvr object.

Remarks

The inverse transformation is useful for removing the effects of the original transformation from a point or vector behavior. Some transforms have no inverse. To characterize transforms of an unknown type, use isSingular.

isSingular

Transform2Bvr Class

Creates a boolean behavior that indicates whether the transform is singular or not. A singular transform is one that has no inverse.

public BooleanBvr isSingular( );

Return Values

Returns the BooleanBvr object. This object's value is true if the transform is singular; otherwise, it is false.

newUninitBvr

Transform2Bvr Class

This method allows you to refer to an Transform2Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Transform2Bvr newUninitBvr( );

Return Values

Returns the Transform2Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Transform2Bvr.

public static Transform2Bvr compose(Transform2Bvr xf1, Transform2Bvr xf2);

public static Transform2Bvr compose2Array(Transform2Bvr[] xforms);

public static Transform2Bvr followPath(Path2Bvr path, NumberBvr evaluator);

public static Transform2Bvr followPathAngle(Path2Bvr path, NumberBvr evaluator);

public static Transform2Bvr followPathAngleUpright(Path2Bvr path, NumberBvr evaluator);

public static Transform2Bvr rotate(NumberBvr radians);

public static Transform2Bvr rotateDegrees(double degrees);

public static Transform2Bvr rotateRate(double radians);

public static Transform2Bvr rotateRateDegrees(double degrees);

public static Transform2Bvr scale(NumberBvr sx, NumberBvr sy);

public static Transform2Bvr scale(Vector2Bvr v);

public static Transform2Bvr scaleRate(double x, double y);

public static Transform2Bvr scale2(NumberBvr uniformFactor);

public static Transform2Bvr scale2Rate(double rate);

public static Transform2Bvr transform3x2(NumberBvr[] matrix);

public static Transform2Bvr translate(NumberBvr tx, NumberBvr ty);

public static Transform2Bvr translate(Point2Bvr loc);

public static Transform2Bvr translate(Vector2Bvr v);

public static Transform2Bvr translate(double x, double y);

public static Transform2Bvr translateRate(double x, double y);

public static Transform2Bvr xShear(NumberBvr x);

public static Transform2Bvr xShearRate(double rate);

public static Transform2Bvr yShear(NumberBvr y);

public static Transform2Bvr yShearRate(double rate);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Transform2Bvr.

public final static Transform2Bvr identityTransform2;


Transform3Bvr Class

public class Transform3Bvr extends Behavior {

    // Methods
    public Transform3Bvr inverse();
    public BooleanBvr    isSingular();
    public Transform2Bvr parallelTransform2();

    public static Transform3Bvr newUninitBvr();

}

Just as a Transform2Bvr transforms a two-dimensional object into another two-dimensional object, a Transform3Bvr transforms a three-dimensional object into another three-dimensional object. Other transforms include the render method, which transforms three-dimensional objects into two-dimensional objects, and the project method, which transforms a three-dimensional point into a two-dimensional point.

For more information about behaviors, see the Behavior class.

  • Transform3Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Transform3Bvr Methods

inverse

isSingular

parallelTransform2

newUninitBvr

inverse

Transform3Bvr Class

Creates a transformation behavior that is the inverse of the original transformation.

public Transform3Bvr inverse( );

Return Values

Returns the Transform3Bvr object.

Remarks

The inverse transformation is useful for removing the effects of the original transformation from a three-dimensional object. To characterize transforms of an unknown type, use isSingular.

isSingular

Transform3Bvr Class

Creates a boolean behavior that indicates whether the transform is singular or not. A singular transform is one that has no inverse.

public BooleanBvr isSingular( );

Return Values

Returns the BooleanBvr object. This object's value is true if the transform is singular; otherwise, it is false.

parallelTransform2

Transform3Bvr Class

Creates a Transform2Bvr object from the Transform3Bvr object.

public Transform2Bvr parallelTransform2( );

Return Values

Returns the Transform2Bvr object.

Remarks

This method is equivalent to casting an orthographic projection of the Transform3Bvr onto the X-Y plane. For predictable results, the transform must be an affine (4´3) transform rather than a perspective (4´4) transform.

newUninitBvr

Transform3Bvr Class

This method allows you to refer to an Transform3Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Transform3Bvr newUninitBvr( );

Return Values

Returns the Transform3Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Transform3Bvr.

public static Transform3Bvr compose(Transform3Bvr xf1, Transform3Bvr xf2);

public static Transform3Bvr compose3Array(Transform3Bvr[] xforms);

public static Transform3Bvr lookAtFrom(Point3Bvr from, Point3Bvr to, Vector3Bvr up);

public static Transform3Bvr rotate(Vector3Bvr axis, NumberBvr radians);

public static Transform3Bvr rotateDegrees(Vector3Bvr axis, double degrees);

public static Transform3Bvr rotateRate(Vector3Bvr axis, double radians);

public static Transform3Bvr rotateRateDegrees(Vector3Bvr axis, double degrees);

public static Transform3Bvr scale(NumberBvr sx, NumberBvr sy, NumberBvr sz);

public static Transform3Bvr scale(Vector3Bvr v);

public static Transform3Bvr scaleRate(double x, double y, double z);

public static Transform3Bvr scale3(NumberBvr uniformFactor);

public static Transform3Bvr scale3Rate(double rate);

public static Transform3Bvr transform4x4(NumberBvr[] matrix);

public static Transform3Bvr translate(NumberBvr tx, NumberBvr ty, NumberBvr tz);

public static Transform3Bvr translate(Point3Bvr loc);

public static Transform3Bvr translate(Vector3Bvr v);

public static Transform3Bvr translateRate(double x, double y, double z)

public static Transform3Bvr xShear(NumberBvr a, NumberBvr b);

public static Transform3Bvr xShearRate(double a, double b);

public static Transform3Bvr yShear(NumberBvr c, NumberBvr d);

public static Transform3Bvr yShearRate(double c, double d);

public static Transform3Bvr zShear(NumberBvr e, NumberBvr f);

public static Transform3Bvr zShearRate(double e, double f);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Transform3Bvr.

public final static Transform3Bvr identityTransform3;


TupleBvr Class

public class TupleBvr extends Behavior
     //Constructor
     public TupleBvr(Behavior[] tuple);

     //Methods
     public Behavior nth(int i);
     public int length();

     public static TupleBvr newUninitBvr(TupleBvr tuple);
}

A TupleBvr object is similar to an array. It can, however, accept heterogeneous types. The two methods included in this class are convenience utilities. Any number of members can be included in a TupleBvr object.

  • TupleBvr Constructor
  • TupleBvr Methods
  • Relevant Methods from the Statics Class

TupleBvr Constructor

TupleBvr Class

Constructs the TupleBvr object.

public TupleBvr(
Behavior behaviors[]
);

Parameters
behaviors
The behaviors to be included in the TupleBvr.

TupleBvr Methods

length

nth

newUninit

length

TupleBvr Class

Determines the length of a tuple behavior.

public int length( );

Return Values

Returns an integer. For more information about integers, consult a Java reference.

nth

TupleBvr Class

Selects a Behavior object based on the value of i.

public Behavior nth(
int i
);

Parameters
i
The index into the TupleBvr object. Note that this is not a time-varying index.

newUninit

TupleBvr Class

Allows you to refer to an Transform3Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static TupleBvr newUninitBvr(
TupleBvr tuple
);

Parameters
tuple
Used to establish the type the tuple holds.
Return Values

Returns the TupleBvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics and are most relevant to objects of type TupleBvr.

public static TupleBvr pairBvr(Behavior first, Behavior second);

public static TupleBvr tripleBvr(Behavior first, Behavior second, Behavior third);


UntilNotifier Interface

public interface UntilNotifier extends java.lang.Object{
    public abstract Behavior notify(Object eventData, Behavior previous, BvrsToRun extraBvrsToRun);
}

Represents the event notifier used to generate a replacement behavior for a behavior created using a untilNotify method.

UntilNotifier Methods

notify

notify

UntilNotifier Interface

Creates a behavior in response to an event. This method is called when the event specified in a call to a untilNotify method occurs. The eventData and previous parameters specify the state of the event and the initial behavior, and can be used to determine how to create the new behavior.

public Behavior notify(
Object eventData,
Behavior previous,
BvrsToRun extraBvrsToRun
);

Parameters
eventData
An object that contains any data produced by the event itself.
previous
A Behavior object that represents the running behavior from which the application is transitioning.
extraBvrsToRun
Behaviors that are not a part of the model.
Return Values

Returns the Behavior object.

See Also

untilNotify


Vector2Bvr Class

public class Vector2Bvr extends Behavior {

    // Methods
    public Vector2Bvr div(NumberBvr scalar);
    public NumberBvr  getPolarCoordAngle();
    public NumberBvr  getPolarCoordLength();
    public NumberBvr  getX();
    public NumberBvr  getY();
    public NumberBvr  length();
    public NumberBvr  lengthSquared();
    public Vector2Bvr mul(NumberBvr scalar);
    public Vector2Bvr normalize();
    public Vector2Bvr transform(Transform2Bvr xf);

    public static Vector2Bvr newUninitBvr();
}

Creates an object that represents a two-dimensional vector behavior. At any given time, the value of the behavior is a direction and length (magnitude), specified as a pair of coordinate values given as either Cartesian coordinates (x, y) or polar coordinates (XYangle, length). The direction of the vector is parallel to the ray that starts at the origin and passes through the point specified by the vector's coordinates, and the length is the distance between the origin and the point.

Because coordinate values are number behaviors (NumberBvr objects), the direction and length of the vector behavior may change over time as the number behaviors change. For more information about behaviors, see the Behavior class.

  • Vector2Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Vector2Bvr Methods

div

getPolarCoordAngle

getPolarCoordLength

getX

getY

length

lengthSquared

mul

normalize

transform

newUninitBvr

div

Vector2Bvr Class

Creates a new two-dimensional vector behavior that points in the same direction as the original vector but has a length that has been divided by scalar.

public Vector2Bvr div(
NumberBvr scalar
);

Parameters
scalar
A NumberBvr object. This parameter can also be of type double.
Return Values

Returns the Vector2Bvr object.

See Also

mul

getPolarCoordAngle

Vector2Bvr Class

Creates a number behavior that represents the counter-clockwise angular displacement, in radians, relative to the positive x-axis, of the vector behavior. The range is [-Pi, +Pi].

public NumberBvr getPolarCoordAngle( );

Return Values

Returns the NumberBvr object.

See Also

getPolarCoordLength, vector2Polar

getPolarCoordLength

Vector2Bvr Class

Creates a number behavior that is the length of the vector.

public NumberBvr getPolarCoordLength( );

Return Values

Returns the NumberBvr object.

See Also

getPolarCoordAngle, vector2Polar

getX

Vector2Bvr Class

Creates a number behavior that represents the x coordinate of this vector behavior.

public NumberBvr getX( );

Return Values

Returns the NumberBvr object.

See Also

getY, vector2

getY

Vector2Bvr Class

Creates a number behavior that represents the y coordinate of this vector behavior.

public NumberBvr getY( );

Return Values

Returns the NumberBvr object.

See Also

getX, vector2

length

Vector2Bvr Class

Creates a number behavior that represents the length of a vector behavior.

public NumberBvr length( );

Return Values

Returns the NumberBvr object.

See Also

lengthSquared

lengthSquared

Vector2Bvr Class

Creates a number behavior that represents the length of a vector behavior squared.

public NumberBvr lengthSquared( );

Return Values

Returns the NumberBvr object.

Remarks

It is slightly more efficient to calculate lengthSquared than length.

See Also

length

mul

Vector2Bvr Class

Creates a new two-dimensional vector behavior that points in the same direction as the original vector but has a length that has been multiplied by scalar.

public Vector2Bvr mul(
NumberBvr scalar
);

Parameters
scalar
A NumberBvr object. This parameter can also be of type double.
Return Values

Returns the Vector2Bvr object.

See Also

div

normalize

Vector2Bvr Class

Creates a normalized, two-dimensional vector behavior. The normalized vector has the same direction as the original vector, but the length is 1.

public Vector2Bvr normalize( );

Return Values

Returns the Vector2Bvr object.

transform

Vector2Bvr Class

Creates a new two-dimensional vector behavior that is the result of applying the given transformation to the original vector. The translation elements of the transformation are ignored; translation does not apply to vectors.

public Vector2Bvr transform(
Transform2Bvr xf
);

Parameters
xf
A Transform2Bvr object.
Return Values

Returns the Vector2Bvr object.

Remarks

This attribute composes values.

newUninitBvr

Vector2Bvr Class

This method allows you to refer to an Vector2Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Vector2Bvr newUninitBvr( );

Return Values

Returns the Vector2Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Vector2Bvr.

public static Vector2Bvr add(Vector2Bvr v1, Vector2Bvr v2);

public static Vector2Bvr bSpline(int degree, NumberBvr[] knots, Vector2Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation);

public static Vector2Bvr derivative(Vector2Bvr vec);

public static NumberBvr dot(Vector2Bvr v1, Vector2Bvr v2);

public static Vector2Bvr integral(Vector2Bvr vec);

public static Vector2Bvr neg(Vector2Bvr v1);

public static Vector2Bvr sub(Vector2Bvr v1, Vector2Bvr v2);

public static Vector2Bvr vector2(NumberBvr x, NumberBvr y);

public static Vector2Bvr vector2Polar(NumberBvr XYangle, NumberBvr length);

public static Vector2Bvr vector2PolarDegrees(double XYangle, double length);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Vector2Bvr.

public final static Vector2Bvr xVector2;

public final static Vector2Bvr yVector2;

public final static Vector2Bvr zeroVector2;


Vector3Bvr Class

public class Vector3Bvr extends Behavior {
    // Methods

    public Vector3Bvr div(NumberBvr scalar);
    public NumberBvr  getSphericalCoordLength();
    public NumberBvr  getSphericalCoordXYAngle();
    public NumberBvr  getSphericalCoordYZAngle();
    public NumberBvr  getPolarCoordAngle();
    public NumberBvr  getX();
    public NumberBvr  getY();
    public NumberBvr  getZ();
    public NumberBvr  length();
    public NumberBvr  lengthSquared();
    public Vector3Bvr mul(NumberBvr scalar);
    public Vector3Bvr normalize();
    public Vector3Bvr transform(Transform3Bvr xf);

    public static Vector3Bvr newUninitBvr();

}

Creates an object that represents a three-dimensional vector behavior. At any given time, the value of the behavior is a direction and length (magnitude), specified as a triplet of coordinate values given as either Cartesian coordinates (x, y, z) or spherical coordinates (XYangle, YZangle, lenght). The direction of the vector is parallel to the ray that starts at the origin and passes through the point specified by the vector's coordinates, and the length is the distance between the origin and the point.

Because coordinate values are number behaviors (NumberBvr objects), the direction and length of the vector behavior may change over time as the number behaviors change. For more information about behaviors, see the Behavior class.

  • Vector3Bvr Methods
  • Relevant Methods from the Statics Class
  • Relevant Fields from the Statics Class

Vector3Bvr Methods

div

getSphericalCoordLength

getSphericalCoordXYAngle

getSphericalCoordYZAngle

getX

getY

getZ

length

lengthSquared

mul

normalize

transform

newUninitBvr

div

Vector3Bvr Class

Creates a new three-dimensional vector behavior that points in the same direction as the original vector but has a length that has been divided by scalar.

public Vector3Bvr div(
NumberBvr scalar
);

Parameters
scalar
A NumberBvr object. This parameter can also be of type double.
Return Values

Returns the Vector3Bvr object.

See Also

mul

getSphericalCoordLength

Vector3Bvr Class

Returns the NumberBvr object that is the distance of the vector from the origin.

public NumberBvr getSphericalCoordLength( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordXYAngle, getSphericalCoordYZAngle, vector3Spherical

getSphericalCoordXYAngle

Vector3Bvr Class

Returns the NumberBvr object that is the counter-clockwise angle, in radians, of the vector about the y-axis, starting at positive z. The range is [-Pi, +Pi].

public NumberBvr getSphericalCoordXYAngle( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordYZ, getSphericalCoordLength, vector3Spherical

getSphericalCoordYZAngle

Vector3Bvr Class

Returns the NumberBvr object that is the YZ angle, in radians, going up from the XZ-plane towards the positive y-ray. The range is [-Pi/2, +Pi/2].

public NumberBvr getSphericalCoordYZAngle( );

Return Values

Returns the NumberBvr object.

See Also

getSphericalCoordXYAngle, getSphericalCoordLength, vector3Spherical

getX

Vector3Bvr Class

Creates a number behavior that represents the x coordinate of this vector behavior.

public NumberBvr getX( );

Return Values

Returns the NumberBvr object.

See Also

getY, getZ, vector3

getY

Vector3Bvr Class

Creates a number behavior that represents the y coordinate of this vector behavior.

public NumberBvr getY( );

Return Values

Returns the NumberBvr object.

See Also

getX, getZ, vector3

getZ

Vector3Bvr Class

Creates a number behavior that represents the z coordinate of this vector behavior.

public NumberBvr getZ( );

Return Values

Returns the NumberBvr object.

See Also

getX, getY, vector3

length

Vector3Bvr Class

Creates a number behavior that represents the length of a vector behavior.

public NumberBvr length( );

Return Values

Returns the NumberBvr object.

See Also

lengthSquared

lengthSquared

Vector3Bvr Class

Creates a number behavior that represents the length of a vector behavior squared.

public NumberBvr lengthSquared( );

Return Values

Returns the NumberBvr object.

See Also

length

mul

Vector3Bvr Class

Creates a new three-dimensional vector behavior that points in the same direction as the original vector but has a length that has been multiplied by scalar.

public Vector3Bvr mul(
NumberBvr scalar
);

Parameters
scalar
A NumberBvr object. This parameter can also be of type double.
Return Values

Returns the Vector3Bvr object.

See Also

div

normalize

Vector3Bvr Class

Creates a normalized, three-dimensional vector behavior. The normalized vector has the same direction as the original vector, but the length is 1.

public Vector3Bvr normalize( );

Return Values

Returns the Vector3Bvr object.

transform

Vector3Bvr Class

Creates a new three-dimensional vector behavior that is the result of applying the given transformation to the original vector. The translation elements of the transformation are ignored; translation does not apply to vectors.

public Vector3Bvr transform(
Transform3Bvr xf
);

Parameters
xf
A Transform3Bvr object.
Return Values

Returns the Vector3Bvr object.

Remarks

This attribute composes values.

newUninitBvr

Vector3Bvr Class

This method allows you to refer to an Vector3Bvr behavior before that behavior has been defined. With this method you can create the behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.

public static Vector3Bvr newUninitBvr( );

Return Values

Returns the Vector3Bvr object.

Relevant Methods from the Statics Class

The following methods are defined in the Statics class and are most relevant to objects of type Vector3Bvr.

public static Vector3Bvr add(Vector3Bvr v1, Vector3Bvr v2);

public static Vector3Bvr bSpline(int degree, NumberBvr[] knots, Vector3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation));

public static Vector3Bvr cross(Vector3Bvr v1, Vector3Bvr v2);

public static Vector3Bvr derivative(Vector3Bvr vec);

public static NumberBvr dot(Vector3Bvr v1, Vector3Bvr v2);

public static Vector3Bvr integral(Vector3Bvr vec);

public static Vector3Bvr neg(Vector3Bvr v1);

public static Vector3Bvr sub(Vector3Bvr v1, Vector3Bvr v2);

public static Vector3Bvr vector3(NumberBvr x, NumberBvr y, NumberBvr z);

public static Vector3Bvr vector3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length);

Relevant Fields from the Statics Class

The following fields are defined in the Statics class and are most relevant to objects of type Vector3Bvr.

public final static Vector3Bvr xVector3;

public final static Vector3Bvr yVector3;

public final static Vector3Bvr zVector3;

public final static Vector3Bvr zeroVector3;


Viewer Interface

public interface Viewer extends java.lang.Object {
    // Methods
    public abstract double getCurrentTime();
    public abstract double getCurrentTickTime();
    public abstract Preferences getPreferences();
    public abstract ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w);
    public abstract void startModel();
    public abstract void stopModel();
    public abstract void tick();
    public abstract void tick(double timeToUse);
}

The Viewer interface methods give complete control over a rendering device. Every method needed to view a model is included here. By implementing these abstract methods, it is possible to write custom viewers that can provide unique functionality. Developers can, for instance, control the tick rate of their models.

Viewer Methods

getCurrentTime
getCurrentTickTime
getPreferences
registerErrorAndWarningReceiver
startModel
stopModel
tick()
tick(timeToUse)

getCurrentTime

Viewer Interface

Returns the number of seconds since startModel was invoked.

public abstract double getCurrentTime( );

Return Values

Returns a double floating-point number.

getCurrentTickTime

Viewer Interface

Returns the time provided for the most recent call to tick or 0 if tick has not yet been called.

public abstract double getCurrentTickTime( );

Return Values

Returns the double floating-point number representing the current tick time.

getPreferences

Viewer Interface

Allows the application to dynamically view the viewer preferences. For more information about preferences, see Preferences.

public abstract Preferences getPreferences( );

Return Values

Returns the Preferences object.

registerErrorAndWarningReceiver

Viewer Interface

Allows the application to register an object that will have its methods invoked upon asynchronous errors encountered when DirectAnimation media is controlling the frame loop or when recoverable errors occur when sampling and displaying the model.

public abstract ErrorAndWarningReceiver registerErrorAndWarningReceiver(
ErrorAndWarningReceiver w
);

Parameters
w
The ErrorAndWarningReceiver object to be registered.
Return Values

Returns the ErrorAndWarningReceiver object.

startModel

Viewer Interface

Starts the behaviors associated with the model at global time 0. Also causes the createModel method on the model itself to be invoked.

public abstract void startModel( );

stopModel

Viewer Interface

Forces all media to stop immediately. It is not required to call this method, however, without it, some media (such as sounds) will continue playing until the object is released.

public abstract void stopModel( );

tick

Viewer Interface

Acutally a shorthand way of writing tick(getCurrentTime()). It is the easiest way to explicitly sample and display model and provides a real-time clock for global time.

public abstract void tick( );

tick

Viewer Interface

Explicitly performs a single sampling and display of the model, where timeToUse represents the global time.

public abstract void tick(
double timeToUse
);

Parameters
timeToUseThe global time for the single sampling.


Java Defaults

This is a list of defaults, by class. Defaults are system-defined.

Java Defaults by Class

Behavior.debug
The default of the boolean is true, which means the behavior is sampled when it's started. The default output device is the standard output device.
GeometryBvr.diffuseColor(ColorBvr col)
The default diffuse color is white.
GeometryBvr.lightAttenuation(NumberBvr const, NumberBvr linear, NumberBvr quadratic)
The default attenuation coefficients are (1, 0, 0). This means there is no light attenuation.
GeometryBvr.lightColor(ColorBvr col)
The default light color is white.
GeometryBvr.opacity((NumberBvr opac)
The default opacity is 1. This means complete opacity.
GeometryBvr.texture(ImageBvr image)
The default texture is no texture.
ImageBvr.opacity(NumberBvr opac)
The default opacity is 1.
LineStyleBvr.color(ColorBvr color)
The default color is black.
LineStyleBvr.dash(DashStyleBvr ds)
The default dash style is solid.
LineStyleBvr.detail()
The default detail style is on. This is the default LineStyleBvr and it has no width.
LineStyleBvr.end(EndStyleBvr es)
The default end style is flat.
LineStyleBvr.join(JoinStyleBvr js)
The default join style is beveled.
Path2Bvr.draw(LineStyleBvr ls)
The default line style behavior is defaultLineStyle.
Path2Bvr fill(ImageBvr im, LineStyleBvr ls)
The default line style behavior is defaultLineStyle.
MicrophoneBvr
The default microphone is located at the origin.
Preferences.COLOR_KEY_BLUE
The default is 245.
Preferences.COLOR_KEY_GREEN
The default is 254.
Preferences.COLOR_KEY_RED
The default is 1.
Preferences.DITHERING
The default is Enabled.
Preferences.ENGINE_OPTIMIZATIONS
The default is On.
Preferences.FILL_MODE
The default is FILL_MODE_SOLID.
Preferences.MAX_FRAMES_PER_SEC
The default is 30.
Preferences.OVERRIDE_APPLICATION_PREFERENCES
The default is Off.
Preferences.PERSPECTIVE_CORRECT
The default is On.
Preferences.RGB_LIGHTING_MODE
The default is On.
Preferences.SHADE_MODE
The default is SHADE_MODE_GOURAUD.
Preferences.TEXTURE_QUALITY
The default is TEXTURE_QUALITY_NEAREST.
Preferences.USE_3-D_HW
The default is Off.
Preferences.USE_VIDEOMEM
The default is On.
Statics.defaultFont
The default font is Times-Roman, black, 12pts in size, and neither bold nor italicized.
Statics.defaultLineStyle
The default is detail. This style has no width. It must be specified in meters.
Statics.public static Path2Bvr polyline(Point2Bvr[] points)
The default linestyle.


Java Event Data

The following table summarizes the DirectAnimation events and the data they produce when the event occurs:
Event | Data
always | No data
andEvent(DXMEvent first, DXMEvent second) | A PairObject containing the event data of the first and second events
attachData(Object object) | The event data of the new event
GeometryBvr.getPickEvent() | A PairObject containing the intersection point and a time-varying vector
ImageBvr.getPickEvent() | A PairObject containing the intersection point and a time-varying vector
leftButtonDown | No data
leftButtonUp | No data
never | No data
notEvent(DXMEvent ev) | No data
notifyEvent(UntilNotifier notifier) | The results returned by the notifier
orEvent(DXMEvent first, DXMEvent second) | The event data of either the first or second event
predicate | No data
rightButtonDown | No data
rightButtonUp | No data
snapshotEvent | The value of the behavior at the time it was sampled, returned as a constant behavior.
thenEvent(DXMEvent e1, DXMEvent e2) | The time the second event fired and a PairObject containing event data for both events
timer(NumberBvr timeout) | No data
trigger() | No data
trigger(Behavior eventData | The event data of the given event


Java Hierarchy Chart

The DirectAnimation Java Hierarchy chart shows the relationships among the DirectAnimation Java classes and interfaces and the standard Java library classes.


Java Class/Methods Summary

The following table lists all the classes and interfaces (constructor are not shown). Select an entry to see its fields and methods.

AppTriggeredEvent Class
ArrayBvr Class
Bbox2Bvr Class
Bbox3Bvr Class
Behavior Class
BooleanBvr Class
CameraBvr Class
BvrCallback Interface
ColorBvr Class
Cycler Class
DashStyleBvr Class
DXMApplet Class
DXMCanvas Class
DXMEvent Class
DXMException Class
EndStyleBvr Class
ErrorAndWarningReceiver Interface
EventCallbackObject Interface
FontStyleBvr Class
GeometryBvr Class
ImageBvr Class
JoinStyleBvr Class
LineStyleBvr Class
MatteBvr Class
MicrophoneBvr Class
Model Class
ModifiableBehavior Class
MontageBvr Class
NumberBvr Class
PairObject Class
Path2Bvr Class
PickableGeometry Class
PickableImage Class
Point2Bvr Class
Point3Bvr Class
Preferences Class
PropertyDispatcher Class
SoundBvr Class
Statics Class
StringBvr Class
Transform2Bvr Class
Transform3Bvr Class
TupleBvr Class
UntilNotifier Interface
Vector2Bvr Class
Vector3Bvr Class
Viewer Interface


AppTriggeredEvent Class

These are the fields and methods for the AppTriggeredEvent Class

public void trigger()
public void trigger(Behavior eventData)


ArrayBvr Class

These are the methods for the ArrayBvr Class:

public NumberBvr length()
public Behavior nth(NumberBvr a)
public static ArrayBvr newUninitBvr(ArrayBvr arr)


Bbox2Bvr Class

These are the methods for the Bbox2Bvr Class:

public Point2Bvr getMax()
public Point2Bvr getMin()
public static Bbox2Bvr newUninitBvr()


Bbox3Bvr Class

These are the methods for the Bbox3Bvr Class:

public Point3Bvr getMax()
public Point3Bvr getMin()
public static Bbox3Bvr newUninitBvr()


Behavior Class

These are the methods for the Behavior Class:

public Behavior BvrHook(BvrCallback callback)
public Behavior debug()
public Behavior debug(String name)
public Behavior debug(String name, boolean onStart)
public Behavior debug(String name, boolean onStart, PrintStream std)
public Behavior duration(NumberBvr length)
public Object extract()
public void init(Behavior a)
public Behavior repeat(int repetitions)
public Behavior repeatForever()
public Behavior runOnce()
public Behavior substituteTime(NumberBvr a)
Methods Defined in Statics
public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b)
public static Behavior until(Behavior a, DXMEvent e, Behavior b)
public static Behavior untilEx(Behavior a, DXMEvent e)
public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier)


BooleanBvr Class

These are the fields and methods for the BooleanBvr Class:

public Object extract()
public static BooleanBvr newUninitBvr()
Fields Defined in Statics
public static BooleanBvr falseBvr
public static BooleanBvr leftButtonState
public static BooleanBvr keyState(int keyCode)
public static BooleanBvr rightButtonState
public static BooleanBvr trueBvr
Methods Defined in Statics
public static BooleanBvr and(BooleanBvr b1, BooleanBvr b2)
public static BooleanBvr not(BooleanBvr b)
public static BooleanBvr or(BooleanBvr b1, BooleanBvr b2)
public static BooleanBvr toBvr(boolean bool)


CameraBvr Class

These are the methods for the CameraBvr Class:

public CameraBvr depth(NumberBvr d)
public CameraBvr depthResolution(NumberBvr n)
public CameraBvr transform(Transform3Bvr xf)
public static CameraBvr newUninitBvr()
Methods Defined in Statics
public static CameraBvr parallelCamera(NumberBvr n)
public static CameraBvr perspectiveCamera(NumberBvr n, NumberBvr p)


BvrCallback Interface

These are the methods for the BvrCallback Interface:

public abstract Behavior notify(int id, boolean start, double startTime, double globalTime, double localTime, Behavior sampledValue, Behavior currentRunningBvr)


ColorBvr Class

These are the fields and methods for the ColorBvr Class:

public NumberBvr getBlue()
public NumberBvr getGreen()
public NumberBvr getHue()
public NumberBvr getLightness()
public NumberBvr getRed()
public NumberBvr getSaturation()
public static ColorBvr newUninitBvr()
Fields Defined in Statics
public final static ColorBvr aqua
public final static ColorBvr black
public final static ColorBvr blue
public final static ColorBvr cyan
public final static ColorBvr fuchsia
public final static ColorBvr gray
public final static ColorBvr green
public final static ColorBvr lime
public final static ColorBvr magenta
public final static ColorBvr maroon
public final static ColorBvr navy
public final static ColorBvr olive
public final static ColorBvr purple
public final static ColorBvr red
public final static ColorBvr silver
public final static ColorBvr teal
public final static ColorBvr white
public final static ColorBvr yellow
Methods Defined in Statics
public static ColorBvr colorHsl(NumberBvr h, NumberBvr s, NumberBvr l)
public static ColorBvr colorRgb(NumberBvr r, NumberBvr g, NumberBvr b)
public static ColorBvr colorRgb255(short r, short g, short b)


DirectAnimation Animated Header --Cycler Class DirectAnimation Animated Header --Cycler Class * Microsoft DirectAnimation SDK
  * Previous Topic: ColorBvr Class
  * Next Topic: DashStyleBvr Class

Cycler Class

These are the methods for the Cycler Class:

public Behavior getBvr()


DashStyleBvr Class

These are the fields and methods for the DashStyleBvr Class:

public static DashStyleBvr newUninitBvr()
Fields Defined in Statics
public static DashStyleBvr dashStyleDashed
public static DashStyleBvr dashStyleSolid


DXMApplet Class

These are the methods for the DXMApplet Class:

public DXMCanvas getCanvas()
public Model getModel()
public void setModel(Model)
public start()
public stop()
Methods Defined in Statics
public static ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w)


DXMCanvas Class

These are the methods for the DXMCanvas Class:

public synchronized void addModel()
public synchronized abstract void addModel()
public synchronized void addNotify()
public double getCurrentTime()
public double getCurrentTickTime()
public Model getModel()
public Preferences getPreferences()
public synchronized boolean handleEvent(Event e)
public synchronized void hide()
public synchronized void hideModel()
public synchronized abstract void hideModel()
public void paint(Graphics g)
public ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w)
public synchronized void removeModel()
public synchronized abstract void removeModel()
public synchronized void removeNotify()
public synchronized void reshape(int x, int y, int width, int height)
public void run()
public void setModel(Model model)
public synchronized void show()
public synchronized void showModel()
public synchronized abstract void showModel()
public void startModel()
public void stopModel()
public void tick()
public synchronized void tick (double timeToUse)
public void update(Graphics g)


DXMEvent Class

These are the fields and methods for the DXMEvent Class:

public DXMEvent attachData(Object object)
public DXMEvent notifyEvent(UntilNotifier notifier)
public Object registerCallback(EventCallbackObject object, BvrsToRun extraBvrsToRun, boolean bool)
public DXMEvent snapshotEvent(Behavior a)
public static DXMEvent newUninitBvr()
Fields Defined in Statics
public static DXMEvent always
public static DXMEvent leftButtonDown
public static DXMEvent leftButtonUp
public static DXMEvent never
public static DXMEvent rightButtonDown
public static DXMEvent rightButtonUp
Methods Defined in Statics
public static DXMEvent andEvent(DXMEvent first, DXMEvent second)
public static DXMEvent keyDown(int keyCode)
public static DXMEvent keyUp(int keyCode)
public static DXMEvent notEvent(DXMEvent ev)
public static DXMEvent orEvent(DXMEvent first, DXMEvent second)
public static DXMEvent predicate(BooleanBvr bool)
public Behavior snapshotEvent(Behavior a)
public static DXMEvent thenEvent(DXMEvent e, DXMEvent e)
public static DXMEvent timer(NumberBvr timeout)
public static void unregisterCallback(Object object)


DirectAnimation Animated Header --DXMException Class DirectAnimation Animated Header --DXMException Class * Microsoft DirectAnimation SDK
  * Previous Topic: DXMEvent Class
  * Next Topic: EndStyleBvr Class

DXMException Class

These are the methods for the DXMException Class:

public int getErrorCode()
public String getErrorString()


EndStyleBvr Class

These are the fields and methods for the EndStyleBvr Class:

public static EndStyleBvr newUninitBvr()
Fields Defined in Statics
public static EndStyleBvr endStyleFlat
public static EndStyleBvr endStyleRound
public static EndStyleBvr endStyleSquare


ErrorAndWarningReceiver Interface

These are the methods for the ErrorAndWarningReceiver Interface:

public abstract void handleError(String s, Viewer v)
public abstract void handleTickError(String s, Viewer v)
public abstract void handleTickWarning(String s, Viewer v)
public abstract void handleWarning(String s, Viewer v)


DirectAnimation Animated Header --EventCallbackObject Interface DirectAnimation Animated Header --EventCallbackObject Interface * Microsoft DirectAnimation SDK
  * Previous Topic: ErrorAndWarningReceiver Interface
  * Next Topic: FontStyleBvr Class

EventCallbackObject Interface

These are the methods for the EventCallbackObject Interface:

public abstract void invoke(Object object, BvrsToRun extraBvrsToRun)


FontStyleBvr Class

These are the fields and methods for the FontStyleBvr Class:

public FontStyleBvr bold()
public FontStyleBvr color(ColorBvr color)
public FontStyleBvr family(StringBvr face)
public FontStyleBvr italic()
public FontStyleBvr size(NumberBvr points)
public FontStyleBvr strikethrough()
public FontStyleBvr textAntialiasing(double antiAliasing)
public FontStyleBvr underline()
public FontStyleBvr weight(NumberBvr weight)
public static FontStyleBvr newUninitBvr()
Fields Defined in Statics
public static final FontStyleBvr defaultFont
Methods Defined in Statics
public static FontStyleBvr font(StringBvr face, NumberBvr points, ColorBvr color)
public static ImageBvr stringImage(StringBvr string, FontStyleBvr fs)


GeometryBvr Class

These are the fields and methods for the GeometryBvr Class:

public Bbox3Bvr boundingBox()
public GeometryBvr diffuseColor(ColorBvr col)
public GeometryBvr lightAttenuation(NumberBvr const, NumberBvr linear, NumberBvr quadratic)
public GeometryBvr lightColor(ColorBvr col)
public GeometryBvr opacity(NumberBvr opac)
public ImageBvr render(CameraBvr camera)
public SoundBvr render(MicrophoneBvr mic)
public GeometryBvr texture(ImageBvr image)
public GeometryBvr transform(Transform3Bvr xf)
public GeometryBvr undetectable()
public static GeometryBvr newUninitBvr()
Fields Defined in Statics
public static GeometryBvr ambientLight
public static GeometryBvr directionalLight
public static GeometryBvr emptyGeometry
public static GeometryBvr pointLight
Methods Defined in Statics
public static GeometryBvr importGeometry(String pathname)
public static GeometryBvr importGeometry(URL url, GeometryBvr geoStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static GeometryBvr soundSource(SoundBvr sound)
public static GeometryBvr spotLight(NumberBvr fullcone, NumberBvr cutoff)
public static GeometryBvr union(GeometryBvr g1, GeometryBvr g2)
public static GeometryBvr unionArray(GeometryBvr[], geometries)


ImageBvr Class

These are the fields and methods for the ImageBvr Class:

public Bbox2Bvr boundingBox()
public ImageBvr clip(MatteBvr matte)
public ImageBvr clipPolygon(Point2Bvr[] points)
public ImageBvr crop(Point2Bvr minPt, Point2Bvr maxPt)
public ImageBvr mapToUnitSquare()
public ImageBvr opacity(NumberBvr opac)
public ImageBvr tile()
public ImageBvr transform(Transform2Bvr xf)
public ImageBvr undetectable()
public static ImageBvr newUninitBvr()
Fields Defined in Statics
public static ImageBvr detectableEmptyImage
public static ImageBvr emptyImage
Methods Defined in Statics
public static ImageBvr gradientHorizontal(ColorBvr start, ColorBvr stop, NumberBvr fallOff)
public static ImageBvr gradientPolygon(Point2Bvr[] pts, ColorBvr[] colors)
public static ImageBvr gradientSquare(ColorBvr lowerLeft, ColorBvr upperLeft, ColorBvr upperRight, ColorBvr lowerRight)
public static ImageBvr hatchBackwardDiagonal(ColorBvr color, NumberBvr size)
public static ImageBvr hatchCross(ColorBvr color, NumberBvr size)
public static ImageBvr hatchDiagonalCross(ColorBvr color, NumberBvr size)
public static ImageBvr hatchForwardDiagonal(ColorBvr color, NumberBvr size)
public static ImageBvr hatchHorizontal(ColorBvr color, NumberBvr size)
public static ImageBvr hatchVertical(ColorBvr color, NumberBvr size)
public static ImageBvr importImage(URL url)
public static ImageBvr importImage(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static ImageBvr importImageColorKey(URL url, ColorBvr red, ColorBvr green, ColorBvr blue)
public static ImageBvr importImageColorKey(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size, ColorBvr red, ColorBvr green, ColorBvr blue)
public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd)
public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd, ImageBvr imgStandIn, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static ImageBvr overlay(ImageBvr i1, ImageBvr i2)
public static ImageBvr overlayArray(ImageBvr[] im)
public static ImageBvr radialGradientPolygon(ColorBvr inner, ColorBvr outer, Point2Bvr[] points, NumberBvr fallOff)
public static ImageBvr radialGradientRegularPoly(ColorBvr inner, ColorBvr outer, NumberBvr edges, NumberBvr fallOff)
public static ImageBvr radialGradientSquare(ColorBvr inner, ColorBvr outer, NumberBvr fallOff)
public static ImageBvr solidColorImage(ColorBvr col)


JoinStyleBvr Class

These are the fields and methods for the JoinStyleBvr Class:

public static JoinStyleBvr newUninitBvr()
Fields Defined in Statics
public static JoinStyleBvr joinStyleBevel
public static JoinStyleBvr joinStyleMiter
public static JoinStyleBvr joinStyleRound


LineStyleBvr

These are the fields and methods for the LineStyleBvr Class:

public LineStyleBvr color(ColorBvr color)
public LineStyleBvr detail()
public LineStyleBvr dash(DashStyleBvr ds)
public LineStyleBvr end(EndStyleBvr es)
public LineStyleBvr join(JoinStyleBvr js)
public LineStyleBvr lineAntialiasing(double antiAliasing)
public LineStyleBvr width(NumberBvr width)
public static LineStyleBvr newUninitBvr()
Fields Defined in Statics
public static LineStyleBvr defaultLineStyle


MatteBvr Class

These are the fields and methods for the MatteBvr Class:

public MatteBvr transform(Transform2Bvr xf)
public static MatteBvr newUninitBvr()
Fields Defined in Statics Class
public static MatteBvr clearMatte
public static MatteBvr opaqueMatte
Methods Defined in Statics Class
public static MatteBvr difference(MatteBvr m1, MatteBvr m2)
public static MatteBvr fillMatte(Path2Bvr path)
public static MatteBvr intersect(MatteBvr m1, MatteBvr m2)
public static MatteBvr textMatte(StringBvr text, FontStyleBvr fs)
public static MatteBvr union(MatteBvr m1, MatteBvr m2)


MicrophoneBvr Class

These are the fields and methods for the MicrophoneBvr Class:

public MicrophoneBvr transform(Transform3Bvr xf)
public static MicrophoneBvr newUninitBvr()
Fields Defined in Statics Class
public static MicrophoneBvr defaultMicrophone


Model Class

These are the methods for the Model Class:

public ImageBvr getImage()
public URL getImportBase()
public SoundBvr getSound()
public void setImage(ImageBvr im1)
public void setImportBase(URL url)
public void setSound(SoundBvr snd)
public abstract void createModel(BvrsToRun extraBvrsToRun)


MontageBvr Class

These are the fields and methods for the MontageBvr Class:

public ImageBvr render()
public static MontageBvr imageMontage(ImageBvr image, NumberBvr depth)
public static MontageBvr newUninitBvr()
Fields Defined in Statics Class
public static MontageBvr emptyMontage
Methods Defined in Statics Class
public static MontageBvr union(MontageBvr m1, MontageBvr m2)


NumberBvrClass

These are the fields and methods for the NumberBvr Class:

public Object extract()
public StringBvr toString(double a)
public StringBvr toString(NumberBvr a)
public static NumberBvr newUninitBvr()
Fields Defined in Statics Class
public static NumberBvr globalTime
public static NumberBvr localTime
Methods Defined in Statics Class
public StringBvr toString(NumberBvr a)
public static NumberBvr abs(NumberBvr a)
public static NumberBvr acos(NumberBvr a)
public static NumberBvr add(NumberBvr a, NumberBvr b)
public static NumberBvr asin(NumberBvr a)
public static NumberBvr atan(NumberBvr a)
public static NumberBvr atan2(NumberBvr a, NumberBvr b)
public static NumberBvr bSpline(int degree, NumberBvr[] knots, NumberBvr[] points, NumberBvr [] weights)
public static NumberBvr ceiling(NumberBvr a)
public static NumberBvr cos(NumberBvr a)
public static NumberBvr degreesToRadians(NumberBvr a)
public static NumberBvr derivative(NumberBvr a)
public static NumberBvr div(NumberBvr a, NumberBvr b)
public static BooleanBvr eq(NumberBvr a, NumberBvr b)
public static NumberBvr exp(NumberBvr a)
public static NumberBvr floor(NumberBvr a)
public static BooleanBvr gt(NumberBvr a, NumberBvr b)
public static BooleanBvr gte(NumberBvr a, NumberBvr b)
public static NumberBvr integral(NumberBvr a)
public static NumberBvr ln(NumberBvr a)
public static NumberBvr log10(NumberBvr a)
public static BooleanBvr lt(NumberBvr a, NumberBvr b)
public static BooleanBvr lte(NumberBvr a, NumberBvr b)
public static NumberBvr mod(NumberBvr a, NumberBvr b)
public static NumberBvr mul(NumberBvr a, NumberBvr b)
public static BooleanBvr ne(NumberBvr a, NumberBvr b)
public static NumberBvr neg(NumberBvr a)
public static NumberBvr pow(NumberBvr a, NumberBvr b)
public static NumberBvr radiansToDegrees(NumberBvr a)
public static NumberBvr round(NumberBvr a)
public static NumberBvr seededRandom(double seed)
public static NumberBvr sin(NumberBvr a)
public static NumberBvr sqrt(NumberBvr a)
public static NumberBvr sub(NumberBvr a, NumberBvr b)
public static NumberBvr tan(NumberBvr a)
public static NumberBvr toBvr(double a)


DirectAnimation Animated Header --PairObject DirectAnimation Animated Header --PairObject * Microsoft DirectAnimation SDK
  * Previous Topic: NumberBvrClass
  * Next Topic: Path2Bvr Class

PairObject

These are the methods for the PairObject Class:

public Object getFirst()
public Object getSecond()


Path2Bvr Class

These are the methods for the Path2Bvr Class:

public Bbox2Bvr boundingBox(LineStyleBvr style)
public Path2Bvr close()
public ImageBvr draw(LineStyleBvr ls)
public ImageBvr fill(ImageBvr im, LineStyleBvr ls)
public Path2Bvr transform(Transform2Bvr xf)
public static Path2Bvr newUninitBvr()
Methods Defined in Statics Class
public static Path2Bvr arc(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight)
public static Transform2Bvr arcDegrees(double startingAngle, double endingAngle, double arcWidth, double arcHeight)
public static Path2Bvr concat(Path2Bvr p1, Path2Bvr p2)
public static Path2Bvr concatArray(Path2Bvr[] paths)
public static Path2Bvr cubicBSplinePath(Point2Bvr[], NumberBvr[])
public static Path2Bvr line(Point2Bvr p1, Point2Bvr p2)
public static Path2Bvr oval(NumberBvr width, NumberBvr height)
public static Path2Bvr pie(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight)
public static Path2Bvr pieDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight)
public static Path2Bvr polydrawPath(Point2Bvr[] points, NumberBvr[] codes)
public static Path2Bvr polyline(Point2Bvr[] points)
public static Path2Bvr ray(Point2Bvr p)
public static Path2Bvr rect(NumberBvr width, NumberBvr height)
public static Path2Bvr roundRect(NumberBvr width, NumberBvr height, NumberBvr arcWidth, NumberBvr arcHeight)
public static Path2Bvr stringPath(StringBvr string, FontStyleBvr fs)


PickableGeometry

These are the fields for the PickableGeometry Class:

public GeometryBvr getGeometryBvr()
public DXMEvent getPickEvent()


DirectAnimation Animated Header --Pickable Image Class DirectAnimation Animated Header --Pickable Image Class * Microsoft DirectAnimation SDK
  * Previous Topic: PickableGeometry
  * Next Topic: Point2Bvr Class

Pickable Image Class

These are the methods for the PickableImage Class:

public ImageBvr getImageBvr()
public DXMEvent getPickEvent()


Point2Bvr Class

These are the fields and methods for the Point2Bvr Class:

public NumberBvr getPolarCoordAngle()
public NumberBvr getPolarCoordLength()
public NumberBvr getX()
public NumberBvr getY()
public Point2Bvr transform(Transform2Bvr xf)
public static Point2Bvr newUninitBvr()
Fields Defined in Statics Class
public static Point2Bvr mousePosition
public static Point2Bvr origin2
Methods Defined in Statics Class
public static Point2Bvr add(Point2Bvr pt, Vector2Bvr vec)
public static Point2Bvr bSpline(int degree, NumberBvr[] knots, Point2Bvr[] points, NumberBvr[] weights)
public static Vector2Bvr derivative(Point2Bvr pt)
public static NumberBvr distance(Point2Bvr p1, Point2Bvr p2)
public static NumberBvr distanceSquared(Point2Bvr p1, Point2Bvr p2)
public static Point2Bvr point2(NumberBvr x, NumberBvr y)
public static Point2Bvr point2Polar(NumberBvr XYangle, NumberBvr length)
public static Vector2Bvr sub(Point2Bvr p1, Point2Bvr p2)
public static Point2Bvr sub(Point2Bvr pt, Vector2Bvr vec)


Point3Bvr Class

These are the fields and methods for the Point3Bvr Class:

public NumberBvr getSphericalCoordLength()
public NumberBvr getSphericalCoordXYAngle()
public NumberBvr getSphericalCoordYZAngle()
public NumberBvr getX()
public NumberBvr getY()
public NumberBvr getZ()
public Point2Bvr project(CameraBvr camera)
public Point3Bvr transform(Transform3Bvr xf)
public static Point3Bvr newUninitBvr()
Fields Defined in Statics Class
Point3Bvr Static Fields
public static Point3Bvr origin3
Methods Defined in Statics Class
public static Point3Bvr add(Point3Bvr pt, Vector3Bvr vec)
public static Point3Bvr bSpline(int degree, NumberBvr[] knots, Point3Bvr[] points, NumberBvr[] weights)
public static Vector3Bvr derivative(Point3Bvr pt)
public static NumberBvr distance(Point3Bvr p1, Point3Bvr p3)
public static NumberBvr distanceSquared(Point3Bvr p1, Point3Bvr p3)
public static Point3Bvr point3(NumberBvr x, NumberBvr y, NumberBvr z)
public static Point3Bvr point3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length)
public static Vector3Bvr sub(Point3Bvr p1, Point3Bvr p3)
public static Point3Bvr sub(Point3Bvr pt, Vector3Bvr vec)


Preferences Class

These are the fields and methods for the Preferences Class:

Fields
public final static String COLOR_KEY_BLUE
public final static String COLOR_KEY_GREEN
public final static String COLOR_KEY_RED
public final static String DITHERING
public final static String ENGINE_OPTIMIZATIONS
public final static String FILL_MODE
public final static int FILL_MODE_POINT
public final static int FILL_MODE_SOLID
public final static int FILL_MODE_WIREFRAME
public final static String MAX_FRAMES_PER_SEC
public final static String OVERRIDE_APPLICATION_PREFERENCES
public final static String PERSPECTIVE_CORRECT
public final static String RGB_LIGHTING_MODE
public final static String SHADE_MODE
public final static int SHADE_MODE_FLAT
public final static int SHADE_MODE_GOURAUD
public final static int SHADE_MODE_PHONG
public final static String TEXTURE_QUALITY
public final static int TEXTURE_QUALITY_LINEAR
public final static int TEXTURE_QUALITY_NEAREST
public final static String USE_VIDEOMEM
Methods
public boolean getBoolean(String string)
public double getDouble(String string)
public int getInt(String)
public String getString(String string)
public void set(String string, Boolean boolean)
public void set(String string, double double)
public void set(String string, int int)
public void set(String preference, String value)


PropertyDispatcher Class

These are the methods for the PropertyDispatcher Class:

public void detach()
public Behavior getBvr()
public void setControl(Object object)
public void setPropertyName(String name)


SoundBvr Class

These are the fields and methods for the SoundBvr Class:

public SoundBvr gain(NumberBvr gainAmt)
public SoundBvr loop()
public SoundBvr pan(NumberBvr panAmt)
public SoundBvr phase(NumberBvr phaseAmt)
public SoundBvr rate(NumberBvr rateAmt)
public static SoundBvr newUninitBvr()
Fields Defined in Statics
public static SoundBvr silence
public static SoundBvr sinSynth
Methods Defined in Statics
public static SoundBvr importSound(String pathname, double[] soundLength)
public static SoundBvr importSound(URL url, NumberBvr[] soundLength, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static SoundBvr mix(SoundBvr sound1, SoundBvr sound2)
public static SoundBvr mixArray(SoundBvr[] sounds)


Statics Class

These are the fields and methods for the Statics Class:

Behavior Static Methods
public static Behavior cond(BooleanBvr bool, Behavior a, Behavior b)
public static Behavior until(Behavior a, DXMEvent e, Behavior b)
public static Behavior untilEx(Behavior a, DXMEvent e)
public static Behavior untilNotify(Behavior a, DXMEvent e, UntilNotifier notifier)
BooleanBvr Static Fields
public static BooleanBvr falseBvr
public static BooleanBvr leftButtonState
public static BooleanBvr rightButtonState
public static BooleanBvr trueBvr
BooleanBvr Static Methods
public static BooleanBvr and(BooleanBvr b1, BooleanBvr b2)
public static BooleanBvr not(BooleanBvr b)
public static BooleanBvr or(BooleanBvr b1, BooleanBvr b2)
public static BooleanBvr keyState(int keyCode)
public static BooleanBvr toBvr(boolean bool)
CameraBvr Static Methods
public static CameraBvr parallelCamera(NumberBvr n)
public static CameraBvr perspectiveCamera(NumberBvr n, NumberBvr p)
ColorBvr Static Fields
public final static ColorBvr aqua
public final static ColorBvr black
public final static ColorBvr blue
public final static ColorBvr cyan
public final static ColorBvr fuchsia
public final static ColorBvr gray
public final static ColorBvr green
public final static ColorBvr lime
public final static ColorBvr magenta
public final static ColorBvr maroon
public final static ColorBvr navy
public final static ColorBvr olive
public final static ColorBvr purple
public static ColorBvr red
public static ColorBvr silver
public static ColorBvr teal
public static ColorBvr white
public static ColorBvr yellow
ColorBvr Static Methods
public static ColorBvr colorHsl(NumberBvr h, NumberBvr s, NumberBvr l)
public static ColorBvr colorRgb(NumberBvr r, NumberBvr g, NumberBvr b)
public static ColorBvr colorRgb255(short r, short g, short b)
DashStyleBvr Static Fields
public static DashStyleBvr dashStyleDashed
public static DashStyleBvr dashStyleSolid
DXMApplet Static Methods
public static ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w)
DXMEvent Static Fields
public static DXMEvent always
public static DXMEvent keyUp(int keyCode)
public static DXMEvent leftButtonDown
public static DXMEvent leftButtonUp
public static DXMEvent never
public static DXMEvent rightButtonDown
public static DXMEvent rightButtonUp
DXMEvent Static Methods
public static DXMEvent andEvent(DXMEvent first, DXMEvent second)
public static DXMEvent keyDown(int keyCode)
public static DXMEvent notEvent(DXMEvent ev)
public static DXMEvent orEvent(DXMEvent first, DXMEvent second)
public static DXMEvent predicate(BooleanBvr bool)
public Behavior snapshotEvent(Behavior a)
public static DXMEvent thenEvent(DXMEvent e, DXMEvent e)
public static DXMEvent timer(NumberBvr timeout)
public static void unregisterCallback(Object object)
EndStyleBvr Static Fields
public static EndStyleBvr endStyleFlat
public static EndStyleBvr endStyleRound
public static EndStyleBvr endStyleSquare
FontStyleBvr Static Fields
public static final defaultFont
FontStyleBvr Static Methods
public static FontStyleBvr font(StringBvr face, NumberBvr points, ColorBvr color)
public static ImageBvr stringImage(StringBvr string, FontStyleBvr fs)
GeometryBvr Static Fields
public static GeometryBvr ambientLight
public static GeometryBvr directionalLight
public static GeometryBvr emptyGeometry
public static GeometryBvr pointLight
GeometryBvr Static Methods
public static GeometryBvr importGeometry(String pathname)
public static GeometryBvr importGeometry(URL url, GeometryBvr geoStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static GeometryBvr soundSource(SoundBvr sound)
public static GeometryBvr spotLight(NumberBvr fullcone, NumberBvr cutoff)
public static GeometryBvr union(GeometryBvr g1, GeometryBvr g2)
public static GeometryBvr unionArray(GeometryBvr[], geometries)
ImageBvr Static Fields
public static ImageBvr detectableEmptyImage
public static ImageBvr emptyImage
ImageBvr Static Methods
public static ImageBvr gradientHorizontal(ColorBvr start, ColorBvr stop, NumberBvr fallOff)
public static ImageBvr gradientPolygon(Point2Bvr[] pts, ColorBvr[] colors)
public static ImageBvr gradientSquare(ColorBvr lowerLeft, ColorBvr upperLeft, ColorBvr upperRight, ColorBvr lowerRight)
public static ImageBvr hatchBackwardDiagonal(ColorBvr color, NumberBvr spacing)
public static ImageBvr hatchCross(ColorBvr color, NumberBvr spacing)
public static ImageBvr hatchDiagonalCross(ColorBvr color, NumberBvr size)
public static ImageBvr hatchForwardDiagonal(ColorBvr color, NumberBvr spacing)
public static ImageBvr hatchHorizontal(ColorBvr color, NumberBvr spacing)
public static ImageBvr hatchVertical(ColorBvr color, NumberBvr spacing)
public static ImageBvr importImage(String pathname)
public static ImageBvr importImage(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static ImageBvr importImageColorKey(URL url, ColorBvr red, ColorBvr green, ColorBvr blue)
public static ImageBvr importImageColorKey(URL url, ImageBvr imgStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size, ColorBvr red, ColorBvr green, ColorBvr blue)
public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd)
public static NumberBvr importMovie(URL url, ImageBvr[] img, SoundBvr[] snd, ImageBvr imgStandIn, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static ImageBvr overlay(ImageBvr i1, ImageBvr i2)
public static ImageBvr overlayArray(ImageBvr[] im)
public static ImageBvr radialGradientPolygon(ColorBvr inner, ColorBvr outer, Point2Bvr[] points, NumberBvr fallOff)
public static ImageBvr radialGradientRegularPoly(ColorBvr inner, ColorBvr outer, NumberBvr edges, NumberBvr fallOff)
public static ImageBvr radialGradientSquare(ColorBvr inner, ColorBvr outer, NumberBvr fallOff)
public static ImageBvr solidColorImage(ColorBvr col)
JoinStyleBvr Fields
public static JoinStyleBvr joinStyleBevel
public static JoinStyleBvr joinStyleMiter
public static JoinStyleBvr joinStyleRound
LineStyleBvr Static Fields
public static LineStyleBvr defaultLineStyle
MatteBvr Static Fields
public static MatteBvr clearMatte
public static MatteBvr opaqueMatte
MatteBvr Static Methods
public static MatteBvr difference(MatteBvr m1, MatteBvr m2)
public static MatteBvr fillMatte(Path2Bvr path)
public static MatteBvr intersect(MatteBvr m1, MatteBvr m2)
public static MatteBvr textMatte(StringBvr text, FontStyleBvr fs)
public static MatteBvr union(MatteBvr m1, MatteBvr m2)
MicrophoneBvr Static Fields
public static MicrophoneBvr defaultMicrophone
Miscellaneous Static Fields
public final static double cm
public final static double foot
public final static double inch
public final static double meter
public final static double mm
public static double pixel
Miscellaneous Static Methods
public static URL buildURL(URL url, String pathname)
public static String getVersionString()
MontageBvr Static Fields
public static MontageBvr emptyMontage
MontageBvr Static Methods
public static MontageBvr union(MontageBvr m1, MontageBvr m2)
NumberBvr Static Fields
public static NumberBvr globalTime
public static NumberBvr localTime
NumberBvr Static Methods
public StringBvr toString(NumberBvr a)
public static NumberBvr abs(NumberBvr a)
public static NumberBvr acos(NumberBvr a)
public static NumberBvr add(NumberBvr a, NumberBvr b)
public static NumberBvr asin(NumberBvr a)
public static NumberBvr atan(NumberBvr a)
public static NumberBvr atan2(NumberBvr a, NumberBvr b)
public static NumberBvr bSpline(int degree, NumberBvr[] knots, NumberBvr[] points, NumberBvr [] weights)
public static NumberBvr ceiling(NumberBvr a)
public static NumberBvr cos(NumberBvr a)
public static NumberBvr degreesToRadians(NumberBvr a)
public static NumberBvr derivative(NumberBvr a)
public static NumberBvr div(NumberBvr a, NumberBvr b)
public static BooleanBvr eq(NumberBvr a, NumberBvr b)
public static NumberBvr exp(NumberBvr a)
public static NumberBvr floor(NumberBvr a)
public static BooleanBvr gt(NumberBvr a, NumberBvr b)
public static BooleanBvr gte(NumberBvr a, NumberBvr b)
public static NumberBvr integral(NumberBvr a)
public static NumberBvr ln(NumberBvr a)
public static NumberBvr log10(NumberBvr a)
public static BooleanBvr lt(NumberBvr a, NumberBvr b)
public static BooleanBvr lte(NumberBvr a, NumberBvr b)
public static NumberBvr mod(NumberBvr a, NumberBvr b)
public static NumberBvr mul(NumberBvr a, NumberBvr b)
public static BooleanBvr ne(NumberBvr a, NumberBvr b)
public static NumberBvr neg(NumberBvr a)
public static NumberBvr pow(NumberBvr a, NumberBvr b)
public static NumberBvr radiansToDegrees(NumberBvr a)
public static NumberBvr round(NumberBvr a)
public static NumberBvr seededRandom(double seed)
public static NumberBvr sin(NumberBvr a)
public static NumberBvr sqrt(NumberBvr a)
public static NumberBvr sub(NumberBvr a, NumberBvr b)
public static NumberBvr tan(NumberBvr a)
public static NumberBvr toBvr(double a)
Path2Bvr Static Methods
public static Path2Bvr arc(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight)
public static Path2Bvr arcDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight)
public static Path2Bvr concat(Path2Bvr p1, Path2Bvr p2)
<public static Path2Bvr concatArray(Path2Bvr[] paths)
public static Path2Bvr cubicBSplinePath(Point2Bvr[], NumberBvr[])
public static Path2Bvr line(Point2Bvr p1, Point2Bvr p2)
public static Path2Bvr pie(NumberBvr startAngle, NumberBvr endAngle, NumberBvr arcWidth, NumberBvr arcHeight)
public static Path2Bvr pieDegrees(double startAngle, double endAngle, double arcWidth, double arcHeight)
public static Path2Bvr polydrawPath(Point2Bvr[] points, NumberBvr[] codes)
public static Path2Bvr polyline(Point2Bvr[] points)
public static Path2Bvr ray(Point2Bvr p)
public static Path2Bvr rect(NumberBvr width, NumberBvr height)
public static Path2Bvr roundRect(NumberBvr width, NumberBvr height, NumberBvr arcWidth, NumberBvr arcHeight)
public static Path2Bvr stringPath(StringBvr string, FontStyleBvr fs)
Point2Bvr Static Fields
public static Point2Bvr mousePosition
public static Point2Bvr origin2
Point2Bvr Static Methods
public static Point2Bvr add(Point2Bvr pt, Vector2Bvr vec)
public static Point2Bvr bSpline(int degree, NumberBvr[] knots, Point2Bvr[] points, NumberBvr[] weights)
public static Vector2Bvr derivative(Point2Bvr pt)
public static NumberBvr distance(Point2Bvr p1, Point2Bvr p2)
public static NumberBvr distanceSquared(Point2Bvr p1, Point2Bvr p2)
public static Point2Bvr point2(double x, double y)
public static Point2Bvr point2(NumberBvr x, NumberBvr y)
public static Point2Bvr point2Polar(NumberBvr XYangle, NumberBvr YZangle)
public static Vector2Bvr sub(Point2Bvr p1, Point2Bvr p2)
public static Point2Bvr sub(Point2Bvr pt, Vector2Bvr vec)
Point3Bvr Static Fields
public static Point3Bvr origin3
Point3Bvr Static Methods
public static Point3Bvr add(Point3Bvr pt, Vector3Bvr vec)
public static Point3Bvr bSpline(int degree, NumberBvr[] knots, Point3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation)
public static Vector3Bvr derivative(Point3Bvr pt)
public static NumberBvr distance(Point3Bvr p1, Point3Bvr p2)
public static NumberBvr distanceSquared(Point3Bvr p1, Point3Bvr p2)
public static Point3Bvr point3(double x, double y, double z)
public static Point3Bvr point3(NumberBvr x, NumberBvr y, NumberBvr z)
public static Point3Bvr point3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length)
public static Vector3Bvr sub(Point3Bvr p1, Point3Bvr p2)
public static Point3Bvr sub(Point3Bvr pt, Vector3Bvr vec)
SoundBvr Static Fields
public static SoundBvr silence
public static SoundBvr sinSynth
SoundBvr Static Methods
public static SoundBvr importSound(URL url, NumberBvr[] soundLength)
public static SoundBvr importSound(URL url, NumberBvr[] soundLength, SoundBvr sndStandIn, DXMEvent[] ev, NumberBvr[] progress, NumberBvr[] size)
public static SoundBvr mix(SoundBvr sound1, SoundBvr sound2)
public static SoundBvr mixArray(SoundBvr[] sounds);
StringBvr Static Methods
public static StringBvr concat(StringBvr a, StringBvr b)
public static StringBvr toBvr(String string)
Transform2Bvr Static Fields
public static Transform2Bvr identityTransform2
Transform2Bvr Static Methods
public static Transform2Bvr compose(Transform2Bvr xf1, Transform2Bvr xf2)
public static Transform2Bvr compose(Transform2Bvr[] xforms)
public static Transform2Bvr followPath(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr followPathAngle(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr followPathAngleUpright(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr rotate(NumberBvr radians)
public static Transform2Bvr rotateDegrees(double degrees)
public static Transform2Bvr rotateRate(double radians)
public static Transform2Bvr rotateRateDegrees(double degrees)
public static Transform2Bvr scale(NumberBvr sx, NumberBvr sy)
public static Transform2Bvr scale(Vector2Bvr v)
public static Transform2Bvr scaleRate(double x, double y)
public static Transform2Bvr scale2(NumberBvr uniformFactor)
public static Transform2Bvr scale2Rate(double rate)
public static Transform2Bvr transform3x2(NumberBvr [] matrix)
public static Transform2Bvr translate(NumberBvr tx, NumberBvr ty)
public static Transform2Bvr translate(Point2Bvr loc);
public static Transform2Bvr translate(Vector2Bvr v)
public static Transform2Bvr translateRate(double x, double y)
public static Transform2Bvr xShear(NumberBvr x)
public static Transform2Bvr xShearRate (double rate)
public static Transform2Bvr yShear(NumberBvr y)
public static Transform2Bvr yShearRate(double y)
Transform3Bvr Static Fields
public static Transform3Bvr identityTransform3
Transform3Bvr Static Methods
public static Transform3Bvr compose(Transform3Bvr xf1, Transform3Bvr xf2)
public static Transform3Bvr compose3Array(Transform3Bvr[] xforms)
public static Transform3Bvr lookAtFrom(Point3Bvr from, Point3Bvr to, Vector3Bvr up)
public static Transform3Bvr rotateDegrees(Vector3Bvr axis, double degrees)
public static Transform3Bvr rotate(Vector3Bvr axis, NumberBvr radians)
public static Transform3Bvr rotateRate(Vector3Bvr axis, double radians)
public static Transform3Bvr rotateRateDegrees(Vector3Bvr axis, double degrees)
public static Transform3Bvr scale(NumberBvr sx, NumberBvr sy, NumberBvr sz)
public static Transform3Bvr scale(Vector3Bvr v)
public static Transform3Bvr scaleRate(double x, double y, double z)
public static Transform3Bvr scale3(NumberBvr uniformFactor)
public static Transform3Bvr scale3Rate(double rate)
public static Transform3Bvr transform4x4(NumberBvr[] matrix)
public static Transform3Bvr translate(NumberBvr tx, NumberBvr ty, NumberBvr tz)
public static Transform3Bvr translate(Point3Bvr loc)
public static Transform3Bvr translate(Vector3Bvr v)
public static Transform3Bvr translateRate(double x, double y, double z)
public static Transform3Bvr xShear(NumberBvr a, NumberBvr b)
public static Transform3Bvr xShearRate(double a, double b)
public static Transform3Bvr yShear(NumberBvr c, NumberBvr d)
public static Transform3Bvr yShearRate(double c, double d)
public static Transform3Bvr zShear(NumberBvr e, NumberBvr f)
public static Transform3Bvr zShearRate(double e, double f)
TupleBvr Static Methods
public static TupleBvr pairBvr(Behavior first, Behavior second)
public static TupleBvr tripleBvr(Behavior first, Behavior second, Behavior third)
Vector2Bvr Static Fields
public static Vector2Bvr xVector2
public static Vector2Bvr yVector2
public static Vector2Bvr zeroVector2
Vector2Bvr Static Methods
public static Vector2Bvr add(Vector2Bvr v1, Vector2Bvr v2)
public static Vector2Bvr bSpline(int degree, NumberBvr[] knots, Vector2Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation)
public static Vector2Bvr derivative(Vector2Bvr vec)
public static NumberBvr dot(Vector2Bvr v1, Vector2Bvr v2)
public static Vector2Bvr integral(Vector2Bvr vec)
public static Vector2Bvr neg(Vector2Bvr v1)
public static Vector2Bvr sub(Vector2Bvr v1, Vector2Bvr v2)
public static Vector2Bvr vector2(NumberBvr x, NumberBvr y)
public static Vector2Bvr vector2Polar(NumberBvr XYangle, NumberBvr length)
public static Vector2Bvr vector2PolarDegrees(double XYangle, double length);
Vector3Bvr Static Fields
public static Vector3Bvr xVector3
public static Vector3Bvr yVector3
public static Vector3Bvr zVector3
public static Vector3Bvr zeroVector3
Vector3Bvr Static Methods
public static Vector3Bvr add(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr bSpline(int degree, NumberBvr[] knots, Vector3Bvr[] control_elements, NumberBvr[] weights, NumberBvr evaluation))
public static Vector3Bvr cross(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr derivative(Vector3Bvr vec)
public static NumberBvr dot(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr integral(Vector3Bvr vec)
public static Vector3Bvr neg(Vector3Bvr v1)
public static Vector3Bvr sub(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr vector3(NumberBvr x, NumberBvr y, NumberBvr z)
public static Vector3Bvr vector3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length)


StringBvr Class

These are the methods for the StringBvr Class:

public Object extract()
public static StringBvr newUninitBvr()
Methods Defined in Statics
public static StringBvr concat(StringBvr a, StringBvr b)
public static StringBvr toBvr(String string)


ModifiableBehavior Class

These are the methods for the ModifiableBehavior Class:

public Behavior getBvr()
public void switchTo(Behavior newBvr)


Transform2Bvr

These are the fields and methods for the Transform2Bvr Class:

public Transform2Bvr inverse()
public BooleanBvr isSingular()
public static Transform2Bvr newUninitBvr()
Fields Defined in Statics
public static Transform2Bvr identityTransform2
Methods Defined in Statics
public static Transform2Bvr compose(Transform2Bvr xf1, Transform2Bvr xf2)
public static Transform2Bvr compose(Transform2Bvr xf1, Transform2Bvr xf2)
public static Transform2Bvr followPath(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr followPathAngle(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr followPathAngleUpright(Path2Bvr path, NumberBvr evaluator)
public static Transform2Bvr rotate(NumberBvr radians)
public static Transform2Bvr rotateDegrees(double degrees)
public static Transform2Bvr rotateRate(double radians)
public static Transform2Bvr rotateRateDegrees(double degrees)
public static Transform2Bvr scale(NumberBvr sx, NumberBvr sy)
public static Transform2Bvr scale(Vector2Bvr v)
public static Transform2Bvr scaleRate(double x, double y)
public static Transform2Bvr scale2(NumberBvr uniformFactor)
public static Transform2Bvr scale2Rate(double rate)
public static Transform2Bvr transform3x2(NumberBvr[] matrix)
public static Transform2Bvr translate(NumberBvr tx, NumberBvr ty)
public static Transform2Bvr translate(Point2Bvr loc);
public static Transform2Bvr translate(Vector2Bvr v)
public static Transform2Bvr translateRate(double x, double y)
public static Transform2Bvr xShear(NumberBvr x)
public static Transform2Bvr xShearRate (double rate)
public static Transform2Bvr yShear(NumberBvr y)
public static Transform2Bvr yShearRate(double y)


Transform3Bvr Class

These are the fields and methods for the Transform3Bvr Class:

public Transform3Bvr inverse(Transform3Bvr xf1)
public BooleanBvr isSingular(Transform3Bvr xf1)
public Transform2Bvr parallelTransform2();
public static Transform3Bvr newUninitBvr()
Fields Defined in Statics
public static Transform3Bvr identityTransform3
Methods Defined in Statics
public static Transform3Bvr compose(Transform3Bvr xf1, Transform3Bvr xf2)
public static Transform3Bvr compose3Array(Transform3Bvr[] xforms)
public static Transform3Bvr lookAtFrom(Point3Bvr from, Point3Bvr to, Vector3Bvr up)
public static Transform3Bvr rotate(Vector3Bvr axis, NumberBvr radians)
public static Transform3Bvr rotate(Vector3Bvr axis, double degrees)
public static Transform3Bvr rotateRate(Vector3Bvr axis, double radians)
public static Transform3Bvr rotateRateDegrees(Vector3Bvr axis, double degrees)
public static Transform3Bvr scale(NumberBvr sx, NumberBvr sy, NumberBvr sz)
public static Transform3Bvr scale(Vector3Bvr v)
public static Transform3Bvr scaleRate(double x, double y, double z)
public static Transform3Bvr scale3(NumberBvr uniformFactor)
public static Transform3Bvr scale3Rate(rate)
public static Transform3Bvr transform4x4(NumberBvr[] matrix)
public static Transform3Bvr translate(NumberBvr tx, NumberBvr ty, NumberBvr tz)
public static Transform3Bvr translate(Point3Bvr loc)
public static Transform3Bvr translate(Vector3Bvr v)
public static Transform3Bvr translateRate(double x, double y, double z)
public static Transform3Bvr xShear(NumberBvr a, NumberBvr b)
public static Transform3Bvr xShearRate(double a, double b)
public static Transform3Bvr yShear(NumberBvr c, NumberBvr d)
public static Transform3Bvr yShearRate(double c, double d)
public static Transform3Bvr zShear(NumberBvr e, NumberBvr f)
public static Transform3Bvr zShearRate(double e, double f)


TupleBvr

These are the methods for the TupleBvr:

public int length()
public Behavior nth(int i)
public static TupleBvr newUninitBvr(TupleBvr tuple)
Methods Defined in Statics Class
public static TupleBvr pairBvr(Behavior first, Behavior second)
public static TupleBvr tripleBvr(Behavior first, Behavior second, Behavior third)


UntilNotifier Interface

These are the methods for the UntilNotifier Interface:

public abstract Behavior notify(Object eventData, Behavior previous, BvrsToRun extraBvrsToRun)


Vector2Bvr Class

These are the fields and methods for the Vector2Bvr Class:

public Vector2Bvr div(NumberBvr scalar)
public NumberBvr getPolarCoordAngle()
public NumberBvr getPolarCoordLength()
public NumberBvr getX()
public NumberBvr getY()
public NumberBvr length()
public NumberBvr lengthSquared()
public Vector2Bvr mul(NumberBvr scalar)
public Vector2Bvr normalize()
public Vector2Bvr transform(Transform2Bvr xf)
public static Vector2Bvr newUninitBvr()
Fields Defined in Statics Class
public static Vector2Bvr xVector2
public static Vector2Bvr yVector2
public static Vector2Bvr zeroVector2
Methods Defined in Statics Class
public static Vector2Bvr add(Vector2Bvr v1, Vector2Bvr v2)
public static Vector2Bvr bSpline(int degree, NumberBvr[] knots, Vector2Bvr[] points, NumberBvr[] weights)
public static Vector2Bvr derivative(Vector2Bvr vec)
public static Vector2Bvr integral(Vector2Bvr vec)
public static Vector2Bvr neg(Vector2Bvr v1)
public static Vector2Bvr sub(Vector2Bvr v1, Vector2Bvr v2)
public static Vector2Bvr vector2(NumberBvr x, NumberBvr y)
public static Vector2Bvr vector2Polar(NumberBvr XYangle, NumberBvr length)
public static Vector2Bvr vector2PolarDegrees(double XYangle, double length);


Vector3Bvr Class

These are the fields and methods for the Vector3Bvr Class:

public Vector3Bvr div(NumberBvr scalar)
public NumberBvr getSphericalCoordLength()
public NumberBvr getSphericalCoordXYAngle()
public NumberBvr get SphericalCoordYZAngle()
public NumberBvr getX()
public NumberBvr getY()
public NumberBvr getZ()
public NumberBvr length()
public NumberBvr lengthSquared()
public Vector3Bvr mul(NumberBvr scalar)
public Vector3Bvr normalize()
public Vector3Bvr transform(Transform3Bvr xf)
public static Vector3Bvr newUninitBvr()
Fields Defined in Statics Class
public static Vector3Bvr xVector3
public static Vector3Bvr yVector3
public static Vector3Bvr zVector3
public static Vector3Bvr zeroVector3
Methods Defined in Statics Class
public static Vector3Bvr add(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr bSpline(int degree, NumberBvr[] knots, Vector3Bvr[] points, NumberBvr[] weights)
public static Vector3Bvr cross(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr derivative(Vector3Bvr vec)
public static NumberBvr dot(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr integral(Vector3Bvr vec)
public static Vector3Bvr neg(Vector3Bvr v1)
public static Vector3Bvr sub(Vector3Bvr v1, Vector3Bvr v2)
public static Vector3Bvr vector3(NumberBvr x, NumberBvr y, NumberBvr z)
public static Vector3Bvr vector3Spherical(NumberBvr XYangle, NumberBvr YZangle, NumberBvr length)


Viewer Interface

These are the methods for the Viewer Interface:

public abstract double getCurrentTime()
public abstract double getCurrentTickTime()
public abstract Preferences getPreferences()
public abstract ErrorAndWarningReceiver registerErrorAndWarningReceiver(ErrorAndWarningReceiver w)
public abstract void startModel()
public abstract void tick()
public abstract void tick(double timeToUse)


Animation Glossary

This section provides a definition of basic animation terms and how some basic animation features are implemented in Microsoft® DirectAnimation™. It applies to both the Java and Scripting references. (Classes that begin with the "DA" prefix are in the Scripting reference.)
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

action set
A logical grouping of procedures used to control the timing and behavior of objects on an HTML page. The Sequencer control provides timing and sequencing services for action sets.
ambient light
The light that determines the general illumination of a scene and keeps shadows from being completely black. Ambient light is created by approximating the background lighting level caused by the reflections from each surface in the scene. In DirectAnimation, ambient light is available as DAGeometry.ambientLight (or Java GeometryBvr.ambientLight).


B

bounding box
Defines the part of an image or geometry that is detectable or nontransparent (tangible). The DAImage.BoundingBox function (or Java ImageBvr.boundingBox method) returns a 2-D bounding box (a DABbox2 or Bbox2Bvr class object) that encloses all the tangible parts of the image. The DAGeometry.BoundingBox function (or Java GeometryBvr.boundingBox method) returns a 3-D bounding box (a DABbox3 or Bbox3Bvr class object) that encloses all the tangible parts of the geometry.


C

camera
DirectAnimation uses a camera to render a geometry (3-D image) into a 2-D image. DirectAnimation has two kinds of cameras: perspective cameras and parallel cameras. A perspective camera projects an image as if it comes from a point. A parallel camera uses parallel projection lines as if projected from an infinite distance away (the image's plane is the same as the viewing plane). Every camera consists of a projection plane (which is the xy plane), a near clip plane, and either a projection point (for a perspective camera) that lies on the z-axis, or a projection direction (for a parallel camera). The near clip plane is a cut-off point on the z-axis that makes everything on the camera side of it invisible. See Rendering Geometries into Images for a diagram.

Cameras in DirectAnimation are objects of the DACamera (or Java CameraBvr) class type. They can be constructed with the DAStatics.PerspectiveCamera (or Java Statics.perspectiveCamera)or the DAStatics.ParallelCamera (or Java Statics.parallelCamera) methods, and are operated on by methods such as DACamera.transform (or Java CameraBvr.transform).

To render 3-D geometries as 2-D images, use the DAGeometry.render (or Java GeometryBvr.render) method, which works on a geometry and returns an image.

The following Java code fragment constructs a scene from the union of lights and an imported cube, and then renders that scene into a 2-D image with a perspective camera.

      URL geomBase = buildURL(getImportBase(),"file:/c:/DxM/Media/geometry/");
      GeometryBvr cube = importGeometry(buildURL(geomBase,"cube.x"));
      GeometryBvr lights = ambientLight;
      GeometryBvr scene = union(lights, cube);
      CameraBvr camera = perspectiveCamera(1, 0);
      ImageBvr renderedGeometry = scene.render(camera);

The perspectiveCamera method's n and p parameters define, respectively, the position of the near clip plane and of the projection point on the positive z-axis.

clip
Clipping is a form of cropping where the clipped region need not be rectangular. To clip an image so that it conforms to the size of the matte, use the DAImage.Clip(matte)) function (or Java ImageBvr.clip(matte) method) where matte is a DAMatte behavior (or Java MatteBvr behavior). A DAMatte behavior (or Java MatteBvr behavior) is a behavior with operations for constructing matte (stencil) regions.

The resulting image is the portion of the original image that falls in the matte region and is otherwise transparent and undetectable.

A shortcut to clipping an image with a polygonal region is the DAImage.ClipPolygon function (or Java ImageBvr.clipPolygon method), which generates a polygonal matte and does a clip.

color
Color in DirectAnimation is represented by a DAColor (or Java ColorBvr) behavior. You can create color either by specifying hue, saturation, and lightness values with the DAStatics.ColorHsl function (or Java Statics.colorHsl method), or by specifying red-green-blue color components with the DAColor.ColorRgb function (or Java Statics.colorRgb method). As shown in the following JScript code:

thisColor = m.ColorHsl(0.5, 0.5, 0.5);
col = m.ColorRgb(1, 0, 0); //red

DirectAnimation defines the following color constants:
Java Reference Scripting Reference
aqua Aqua
black Black
blue Blue
cyan Cyan
fuchsia Fuchsia
gray Gray
green Green
lime Lime
magenta Magenta
maroon Maroon
navy Navy
olive Olive
purple Purple
red Red
silver Silver
teal Teal
white White
yellow Yellow

crop
Cropping limits the part of the image that is accessible to the user visually or for interaction. To crop an image, apply the DAImage.crop(lowLeftPt, upRightPt) function (or Java ImageBvr.crop(lowLeftPt, upRightPt) method). This defines the detectable or visible portion of the subject image as the part that falls within the two given points.


D

detectability
The points of images or the surfaces of geometries are either detectable or not. If they are detectable, they fire an event (a hit detection event) whenever the mouse passes over a point or surface. The DAImage.Undetectable function (or Java ImageBvr.undetectable method) creates a copy of an existing image that is undetectable.
directional light
Light in which rays arrive in the scene parallel to each other. This light mimics the light from a very distant source, such as the sun. In DirectAnimation, directional light is available as DAGeometry.DirectionalLight (or Java GeometryBvr.directionalLight).


G

geometry
Geometries have width, height, and depth, and are rendered into 2-D images. Geometries are objects of the DAGeometry (or Java GeometryBvr) class type, and are operated on by functions such as DAGeometry.Texture (or Java GeometryBvr.texture), DAGeometry.DiffuseColor (or Java GeometryBvr.diffuseColor), and DAGeometryBvr.Transform (or Java GeometryBvr.transform).

You can import a geometry into DirectAnimation from a URL or local file. DirectAnimation supports the DirectX .x file format. First build your URL base, then use the ImportGeometry function (or Java importGeometry method) to import a geometry, as shown in the following Java code:

   //Create a URL base
   URL geoBase = buildURL(getImportBase(),"file:/c:/DxM/Media/geometry/");
   // Create a geometry behavior by importing a geometry file
   GeometryBvr cube = importGeometry(buildURL(geoBase,"cube.x"));

The following example shows how to import a geometry from a local file, using JScript:

  mediaBase = "..\\..\\..\\..\\media\\";
  // the following form will also work as well
  // mediaBase = "file://c:\\dxm\\media\\";

  geoBase = mediaBase + "geo\\";
  myImage = m.ImportGeometry(geoBase + "cube.x");

The following example shows how to import a geometry over a network, using JScript:

 mediaBase = "http://dxmedia/directanimation/dxm_sdk/media/";
 geoBase = mediaBase + "geo/";
 myImage = m.ImportGeometry(geoBase + "cube.x");

You can augment a geometry with lights, including ambient, directional, point, and spot lights. (Because there is no default lighting, you must include some sort of lighting so that the geometry is visible.) You can also attach a sound source to a geometry to give the sound 3-D spatial characteristics. See Using Geometries for more information.


I

image
Images are 2-D. They have width and height, but no depth. Images are objects of the DAImage (or Java ImageBvr) class type, and can be operated on by methods, such as DAImage.Crop (or Java ImageBvr.crop), DAImage.Tile (or Java ImageBvr.tile), and DAImage.Transform (or Java ImageBvr.transform).

You can import images into DirectAnimation from a URL or local file. DirectAnimation supports .png, .jpg, .gif, and .bmp formats. Importing is done in two steps: first you construct your URL base, then you use the ImportImage function (or Java importImage method), as shown in the following Java example:

   //Create a URL base
   URL imageBase = buildURL(getImportBase(),"file:/c:/DxM/Media/image/");
   // Create an image behavior by importing an image file
    ImageBvr img = importImage(buildURL(imageBase, "square.jpg"));

The following example shows how to import an image from a local file, using JScript:

  mediaBase = "..\\..\\..\\..\\media\\";
  // the following form will also work as well
  // mediaBase = "file://c:\\dxm\\media\\";

  imageBase = mediaBase + "image\\";
  myImage = m.ImportImage(imageBase + "foliageUtah.jpg");

The following example shows how to import an image from over the Internet, using JScript:

  mediaBase = "http://dxmedia/directanimation/dxm_sdk/media/";
  imageBase = mediaBase + "image/";
  myImage = m.ImportImage(imageBase + "foliageUtah.jpg");

You can also construct an image by rendering lines, text, or geometries. See Using Images for more information.


L

light
Computer displays use additive light. Additive light is created by combining red, green, and blue light components, in some proportion. White light is created from equal parts of red, green, and blue light. Intensity is the brightness of the light. Attenuation is the decrease in light intensity over distance.

There are two basic kinds of light: ambient light and source light. Ambient light determines the general illumination of a scene. Source light comes from a light source. There are three kinds of source light: point sources (light radiates in all directions from a point source), spotlight sources (light radiates in a specified cone from a point source), and directional light (light rays arrive in the scene parallel to each other, which mimics the light from a very distant source).

In DirectAnimation, ambient light, directional light, and point light are available as DAGeometry.ambientLight (or Java GeometryBvr.ambientLight), DAGeometry.DirectionalLight (or Java GeometryBvr.directionalLight), and DAGeometry.PointLight (or Java GeometryBvr.pointLight).

Diffuse light is light that scatters from rough surfaces in all directions. Depending on the object's material, it can reflect and diffuse incoming light in varying degrees. In DirectAnimation, diffuse light characteristics are set with the DAGeometry.DiffuseColor function (or Java GeometryBvr.diffuseColor method).


O

opacity
The measure of an object's ability to block light transmission — the opposite of transparency. In DirectAnimation, you set it with the DAImage.Opacity function (or Java ImageBvr.opacity method) or DAGeometry.Opacity function (or Java GeometryBvr.opacity method), respectively. When the opacity is 0, the resulting image or geometry is fully transparent. When the opacity is 1, the image or geometry is fully opaque.
overlay
An overlay takes two images as parameters and returns an image that is made by laying the first image on top of the second. Blending takes place where the images overlap and the image laid on top is partially opaque (neither fully opaque nor fully transparent). To create an overlay, use the DAImage.Overlay function (or Java ImageBvr.overlay method).


P

path
A sequence of 2-D points, typically used to draw images consisting of line segments or to define borders for geometric shapes. Paths in DirectAnimation are objects of the DAPath2 (or Java Path2Bvr) class type.
point (2-D)
Represents a location in a plane or on the screen. In DirectAnimation, it is a DAPoint2 (or Java Point2Bvr) object. It can be defined either by its Cartesian (x, y) or polar (theta, rho) coordinate values. (In DirectAnimation, theta is also called the polar coordinate angle, and rho is the polar coordinate length.) These coordinates define the point's location relative to a fixed point called Origin2 (or Java origin2).
point (3-D)
Represents a location in 3-D space. In DirectAnimation, it is a DAPoint3 (or Java Point3Bvr) object. It can be defined either by its Cartesian (x, y, z) or spherical (theta, phi, rho) coordinate values. (In DirectAnimation, theta is also called the spherical coordinate x-y angle, phi is also called the spherical coordinate y-z angle, and rho is also called the spherical coordinate length.) These coordinates define the point's location relative to a fixed point called Origin3 (or Java origin3).
point light
Light that radiates in all directions from a point source. In DirectAnimation, point light is available as DAGeometry.PointLight (or Java GeometryBvr.pointLight).


S

sound
Audio in DirectAnimation is represented by the DASound (or Java SoundBvr) class. Sound can be imported from WAV or MIDI files, synthesized by mixing multiple sine waves, or constructed by rendering a geometry with embedded sounds into a single microphone for a single channel sound, or into two microphones for stereo sound. Microphones are implemented in DirectAnimation by the DAMicrophone (or Java MicrophoneBvr) class.

Operations on sounds include DASound.Loop (or Java SoundBvr.loop), DASound.Gain (or Java SoundBvr.gain), DASound.Rate (or Java SoundBvr.rate), DASound.Phase (or Java SoundBvr.phase), DASound.Pan (or Java SoundBvr.pan), and DASound.Mix (or Java SoundBvr.mix).

source light
Light that comes from a light source. There are three kinds of source light: point sources (light radiates in all directions from a point source), spotlight sources (light radiates in a specified cone from a point source), and directional light (light rays arrive in the scene parallel to each other, which mimics the light from a very distant source).

In DirectAnimation, directional light and point light are available as DAGeometry.DirectionalLight(or Java GeometryBvr.directionalLight), and DAGeometry.PointLight (or Java GeometryBvr.pointLight).

spline
A polynomial function that follows defining points. The defining points can carry different weights. DirectAnimation supports B-splines through the DAStatics functions CubicBSplinePath, NumberBSpline, Point2BSpline, Point3BSpline, Vector2BSpline, and Vector3BSpline (or the Java Statics method cubicBSplinePath) and through the Java NumberBvr, Point2Bvr, Point3Bvr, Vector2Bvr, and Vector3Bvr class method bSpline).
sprite
A 2-D image that can move over a background without disturbing it. In DirectAnimation, sprites are images operated on by the DAImage.Transform function (or the Java ImageBvr.transform method).


T

texture
An image that is mapped onto a geometry to define its surface qualities. You do this with the DAGeometry.Texture function (or the Java GeometryBvr.texture method). For example, the following Java code imports a geometry and an image and uses the image to make the sphere look like a marble:

      URL mediaBase = buildURL(getImportBase(),"file/c:/DxM/Media/");
      GeometryBvr sphere = importGeometry(buildURL(mediaBase,"geometry/sphere.x"));
      ImageBvr marbleImage = importImage(buildURL(mediaBase,"image/marble.jpg"));
      GeometryBvr marbledSphere = sphere.texture(marbleImage);
tile
The technique of repeating an image over a large area. When applied to an image, the DAImage.tile function (or Java ImageBvr.tile method) infinitely replicates the image in all four directions. Typically, tiling is followed either with a DAImage.Crop (or Java ImageBvr.crop) or a DAImage.Clip (or Java ImageBvr.clip)operation, or else it is used to generate the background of a viewport, and is, therefore, implicitly clipped while displayed.


V

vector
Describes magnitude and direction. In DirectAnimation, 2-D vectors are DAVector2 (or Java Vector2Bvr) behaviors and can be constructed from polar or Cartesian coordinates. Three-dimensional vectors are DAVector3 (or Java Vector3Bvr) behaviors and can be constructed from spherical or Cartesian coordinates. Vectors can also be constructed from points, as shown in the following JScript code:

myVec3 = m.Sub(firstPt3, secondPt3);


Microsoft DirectShow SDK

Welcome to the Microsoft® DirectShow™ SDK. Before jumping into any of the reference sections, consider reading the articles in the "Getting Started" and "DirectShow Basics" sections first. These articles provide important overview and conceptual information about DirectShow that you will need in other areas of the documentation. For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

Click here to go to the download page for DirectAnimation and DirectShow.

Last Updated: March 27, 1998

Getting Started
What is DirectShow?
What's New in the DirectShow SDK?
Porting Code from ActiveMovie
What Background Do You Need?
Documentation Roadmap
Redistribution
Frequently Asked Questions
ActiveMovie Control
Using the ActiveMovie Control
Visual Basic Objects
DirectShow Basics
Using DirectShow
Filter Graph Manager and Filter Graphs
Filters and Pins
Stream Control Architecture
Quality-Control Management
About Capture Filter Graphs
Improving Capture Performance
Data Flow in the Filter Graph
Constructing Filter Graphs Using Visual Basic
Controlling Filter Graphs Using Visual Basic
List of Filters and Samples
About the DirectShow Filter Graph Editor
Using the Filter Graph Editor
COM Overview
Overview of DVD Interfaces and Data Types
About WDM Video Capture
Application Developer's Guide
How to...
Clocks
Controlling Filter Graphs Using C
Creating a Capture Application
About Cutlists
Using Cutlists
DVD for Title Vendors
Filter Developer's Guide
How to...
Stream Architecture
Plug-in Distributors
DirectShow and COM
File Formats
Transform Filters
About Effect Filters
Video Renderers
Exposing Capture and Compression Formats
C/C++ Reference
DirectShow COM Interfaces
Base Classes
Utility Functions
Debugging
Structures
Data Types
Property Sets
Event Notification Codes
DVD Event Notification Codes
Error and Success Codes
Filters and Samples
DirectShow Filters
DirectShow Samples
Multimedia Streaming
About the Multimedia Streaming Architecture
List of Multimedia Streaming Interfaces
Multimedia Streaming Reference
Multimedia Streaming Component Objects
Multimedia Streaming Sample Code
DirectDrawEx
Using DirectDrawEx
IDirectDrawFactory Interface
IDirectDraw3 Interface
Appendixes
Media Types
MPEG-1 Media Types
CLSIDs in DirectShow
Time Stamps
Sample Properties
DirectShow DVD Support
Country Codes and Channel to Frequency Mappings
Reserved Identifiers
Further Reading
Glossary
Glossary
Readme
Readme

Note The icon external link indicates that the link takes you to a URL that is outside the microsoft.com site; you can return to the DirectShow site by using the Back button. Note that most of these external links point to servers that are not under Microsoft's control. Please read Microsoft's official statement regarding other servers.


Getting Started

This section introduces you to the DirectShow SDK and helps you get oriented. It includes a description of the SDK, information about porting from previous versions, background needed to understand different parts of DirectShow, a guide to the documentation, redistribution information, and answers to frequently asked questions.

What is DirectShow?

What's New in the DirectShow SDK?

Porting Code from ActiveMovie

What Background Do You Need?

Documentation Roadmap

Redistribution

Frequently Asked Questions


What is DirectShow?

The Microsoft® DirectShow™ SDK gives developers access to DirectShow services, which provide playback multimedia streams from local files or Internet servers, and capture of multimedia streams from devices. Specifically, this enables playback of video and audio content compressed in various formats, including MPEG, Apple® QuickTime®, audio-video interleaved (AVI), and WAV, and both Video for Windows-based capture and WDM-based (Windows Driver Model) capture.

At the heart of the DirectShow services is a modular system of pluggable components called filters, arranged in a configuration called a filter graph. A component called the filter graph manager oversees the connection of these filters and controls the stream's data flow.

Applications control the filter graph's activities by communicating with the filter graph manager. You can do this indirectly by using the ActiveMovie Control, or directly by calling COM interface methods. The SDK also enables you to create your own filters using the DirectShow class library. The base classes in the C/C++ library implement the required COM interfaces on the filters and provide the basic filter framework.

The DirectShow SDK is based on several other Microsoft services and supports at least one other Microsoft service. For example, the video display components in DirectShow rely on Microsoft® DirectX® services whenever possible.

The amount you must know about an underlying or supported technology depends on what you are doing. For example, you'll need to understand COM programming if you are using C or C++ to control DirectShow playback or create a filter. But you don't need to understand COM programming to use the ActiveMovie Control.

DirectShow developers can use the following Microsoft services (you can find information about most of these in the Platform SDK or on the World Wide Web at http://www.microsoft.com/msdn/.)

  • DirectX
  • Component Object Model (COM)
  • Media control interface (MCI)

You can also use the following Microsoft languages for DirectShow development:

  • Microsoft Visual Basic® — used to create and control filter graphs.
  • Microsoft Visual C++® — used to create and control filter graphs, and create filters.

See the product documentation for more information on these languages.


What's New in the DirectShow SDK?

DirectShow Animated Header -- What's New in the DirectShow SDK? DirectShow Animated Header -- What's New in the DirectShow SDK? * Microsoft DirectShow SDK
  * Previous Topic: What is DirectShow?
  * Next Topic: Porting Code from ActiveMovie

What's New in the DirectShow 5.2b SDK?

The Microsoft® DirectX® Media 5.2b SDK is an update to the DirectX Media 5.1 SDK, released in November 1997. For a description of what was new in the DirectShow 5.1 SDK, see What's New in the DirectShow 5.1 SDK?

The DirectX Media 5.2b run time has improvements in two specific areas—DVD Playback and WDM Capture support.

For DVD playback, the run time provides support for PAL DVD discs as well as improved interactive responsiveness. The run time has also been tested with many new DVD titles that were released in the last two months.

The Overlay Mixer, which is a key rendering component for DVD playback, has been improved in the following areas.

  • New interfaces added on each pin of Overlay Mixer.
    • IOverlay enables upstream filters to do the rendering themselves, leaving only the window management to the Overlay Mixer.
    • IMixerPinConfig2 has methods to set and get brightness, contrast, and other color control features, as if setting the color controls on the overlay surface.
    • IVPNotify2 has methods to make the video port the sync master of the VGA, and to determine if the video port is the sync master.
  • The IMixerPinConfig methods SetZOrder, GetZOrder, SetBlendingParameter, and GetBlendingParameter, which previously returned E_NOTIMPL, have been enabled now.
  • Overlay Mixer now tries to create the overlay surface in AGP memory if allocation in video memory fails.
  • Some important scaling bugs, including one that did not allow shrinking of overlay surfaces on certain video cards (like ATI rage pro), have now been fixed.
  • Previously, using IBasicVideo to zoom or stretch video did not do the correct thing. That has now been fixed.

The video and audio capture infrastructure has been enhanced to add support for more types of WDM streaming class capture hardware running under Microsoft® Windows® 98 or Windows NT® 5.0. If your application is going to work with this new hardware, you should re-read the capture interface descriptions and re-read the code for our sample capture application, Amcap.exe found in the Capture sample directory.

In addition, a new video control interface has been added, IAMVideoControl, that enables you to flip a picture horizontally and/or vertically, to set up a stream so that it can capture from an external trigger, to simulate an external trigger in software, and to list the current frame rate, maximum frame rate, and available frame rates.

A new filter, Smart Tee, has been added to aid preview on capture filters that only have a capture pin and not a preview pin.

What's New in the DirectShow 5.1 SDK?

The Microsoft® DirectShow™ SDK (formerly the Microsoft ActiveMovie™ SDK) is now part of the Microsoft DirectX® Media SDK. Features added since ActiveMovie 1.x include video and audio capture and compression, device enumeration, digital versatile disc (DVD) support, digital video (DV) support, cutlist support, device control and timecode support, and multimedia streaming. See the topics in the following lists for details of all the DirectShow SDK's new features. For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

Articles

  • Porting Code from ActiveMovie
  • What Background Do You Need?
  • Documentation Roadmap
  • About Capture Filter Graphs
  • Improving Capture Performance
  • Creating a Capture Application
  • Write an Audio Capture Filter
  • Write a Video Capture Filter
  • Enumerate and Access Hardware Devices in DirectShow Applications
  • DVD for Title Vendors
  • DirectShow DVD Support
  • About Cutlists
  • Using Cutlists
  • About Compression Filters
  • Recompress an AVI File
  • DV Data in the AVI File Format
  • AVI 2.0 File Format Extensions
  • Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming
  • Play a Movie from C++
  • Control the Video Playback Window from C++
  • Display a Filter's Property Page from C++
  • Use Multimedia Streaming in DirectShow Applications
  • Build a Filter or Application with Visual C++ 5.x
  • Exposing Capture and Compression Formats
  • About the DirectShow Filter Graph Editor
  • Using the Filter Graph Editor
  • About WDM Video Capture
  • Using DirectDrawEx

Multimedia Streaming

  • About the Multimedia Streaming Architecture
  • List of Multimedia Streaming Interfaces
  • Multimedia Streaming Reference
  • Multimedia Streaming Data Types
  • Error and Success Codes for Multimedia Streaming
  • Multimedia Streaming Component Objects
  • Multimedia Streaming Sample Code

DirectDrawEx

  • What Is DirectDrawEx?
  • IDirectDrawFactory Interface
  • IDirectDraw3 Interface

DirectShow COM Interfaces

The following lists group the new DirectShow interfaces by area. In addition, the Multimedia Streaming Reference contains interfaces specific to multimedia streaming.

Capture, Compression, Device Enumeration, and Windows Driver Model (WDM) Capture Interfaces

  • IAMAudioInputMixer
  • IAMBufferNegotiation
  • IAMCrossbar
  • IAMDroppedFrames
  • IAMStreamConfig
  • IAMStreamControl
  • IAMStreamSelect
  • IAMTVTuner
  • IAMVfwCaptureDialogs
  • IAMVfwCompressDialogs
  • IAMVideoCompression
  • IAMVideoProcAmp
  • ICaptureGraphBuilder
  • IConfigAviMux
  • IConfigInterleaving
  • ICreateDevEnum
  • IFileSinkFilter2
  • IFilterGraph2
  • IMediaPropertyBag
  • ISeekingPassThru

DirectSound Interface

  • IAMDirectSound

Digital Versatile Disc (DVD), Closed Captioning, Property Set, and Video Port (VP) Interfaces

  • IAMLine21Decoder
  • IDvdControl
  • IDvdGraphBuilder
  • IDvdInfo
  • IKsPropertySet
  • IVPBaseConfig
  • IVPBaseNotify
  • IVPConfig
  • IVPNotify

Cutlist Interfaces

  • IAMAudioCutListElement
  • IAMCutListElement
  • ICutListGraphBuilder
  • IFileClip
  • IAMFileCutListElement
  • IStandardCutList
  • IAMVideoCutListElement

Device Control and Timecode Interfaces

  • IAMExtDevice
  • IAMExtTransport
  • IAMTimecodeDisplay
  • IAMTimecodeGenerator
  • IAMTimecodeReader

Memory Allocation/Media Sample Interfaces

  • IAMDevMemoryAllocator
  • IAMDevMemoryControl
  • IMediaSample2

Samples

  • AMCap Sample (DirectShow Capture Application)
  • CLText Sample (Text Cutlist Application)
  • ShowStrm Sample (Multimedia Streaming Application)
  • Simplecl Sample (Cutlist Application)
  • Vcrctrl Sample (VCR Control Filter)
  • VidClip Sample (Video Editing Application)
  • VidCap Sample (Video Capture Filter)
  • Dvdsampl Sample (DVD Player Application)
  • PlayFile Sample (Simple Playback Application)
  • InWindow Sample (Window Playback Application)
  • MPEGProp Sample (MPEG Property Page Display Application)

Filters

The following lists group the filters by category. Some filters can fit in more than one category so be sure to look at the different categories to see what new filters are available.

Capture, WDM Capture, and File Writing Filters

  • Analog Video Crossbar
  • Audio Capture
  • AVI MUX
  • File Writer
  • TV Audio
  • TV Tuner
  • VFW Video Capture
  • WDM Video Capture

Digital Video (DV) Filters

  • DV Muxer
  • DV Splitter
  • DV Video Decoder
  • DV Video Encoder

Cutlist Filter

  • Cutlist File Source

Closed Captioning Filters

  • Lyric Parser
  • Line 21 Decoder
  • Multi-File Parser
  • SAMI (CC) Parser

Compression and Decompression Filters (Codecs)

  • ACM Audio Compressor
  • AVI Compressor
  • Indeo 4.3 Video Compression
  • Indeo 4.3 Video Decompression
  • Indeo 5.0 Audio Decompression
  • Indeo 5.0 Video Compression
  • Indeo 5.0 Video Decompression
  • QuickTime Decompressor
  • TrueMotion 2.0 Decompressor

Parser, Renderer, and Mixer Filters

  • AVI Draw
  • DSound Audio Renderer
  • File Stream Renderer
  • Internal Script Command Renderer
  • MIDI Parser
  • MIDI Renderer
  • Overlay Mixer

DVD Filter

  • DVD Navigator

Classes, Functions, and Macros

  • CBaseRenderer callback function class
  • CBaseStreamControl class
  • Functions for creating DLLs and registering and unregistering filters
  • IUnknown Macro

The following material relating to the ActiveMovie Control has been significantly updated:

  • About the DirectShow ActiveMovie Control
  • Control Events
  • Control Methods
  • Control Properties
  • Control Property Sheet
  • Control Shortcut Keys
  • Using the ActiveMovie Control in HTML Pages


Porting Code from ActiveMovie

This article describes the steps you must take to port your Microsoft® ActiveMovie™ 1.0 code to Microsoft DirectShow™.

Contents of this article:

  • Recompiling ActiveMovie 1.0 Code with DirectShow
  • Interfaces and Services Improved Since ActiveMovie 1.0

Recompiling ActiveMovie 1.0 Code with DirectShow

If you are recompiling your ActiveMovie 1.0 code with the DirectShow header files and libraries, you must make the following changes:

  1. The name of the IFilter interface has been changed to IBaseFilter. You need to change the name to compile with DirectShow libraries and headers. ActiveMovie 1.0 binaries will continue to work because the IID (Interface Identifier) GUID for the interface is still the same.
  2. The constructor of the CBasePropertyPage::CBasePropertyPage function has one less parameter. Once again, if you are recompiling your code with the DirectShow base class libraries, you will have to modify the parameters for the CBasePropertyPage constructor.

    The old prototype for the constructor was:

CBasePropertyPage(TCHAR *pName,       // Debug only name
                      LPUNKNOWN pUnk,         // COM Delegator
                      HRESULT *phr,                 // Return code
                      int DialogId,                      // Resource ID
                      int TitleId);                        // To get title

    The new prototype is:

CBasePropertyPage(TCHAR *pName,       // Debug only name
                      LPUNKNOWN pUnk,         // COM Delegator
                      int DialogId,                      // Resource ID
                      int TitleId);                        // To get title

Interfaces and Services Improved Since ActiveMovie 1.0

Some interfaces and services in ActiveMovie 1.0 have been improved in DirectShow. You should use the following improved interfaces and services:

  1. A new interface, IFilterMapper2, has been introduced to support the concept of filter categories and registering filters in correct categories. IFilterMapper will still work for filters that were shipped with ActiveMovie 1.0 and are now part of the standard filters in the Filter Graph Editor. IFilterMapper might not do the right thing for filters that are in the new categories. For example, you might end up with filters that you can't instantiate.
  2. The AMovieSetupRegisterFilter2 function has been added to use IFilterMapper2. AMovieSetupRegisterFilter will still work and will use IFilterMapper.


What Background Do You Need?

The amount you need to know for a particular DirectShow task depends on the task. For example, you must understand basic COM principles and C or C++ to create a filter. But you don't need to understand either to use the ActiveMovie Control.

The following tables show what you might need to know to perform different tasks and get the most out of the DirectShow documentation. To find the information you need, see Documentation Roadmap for a description of what you'll find in the different sections of the DirectShow documentation. See Where Can I Learn About... for the location of answers to specific questions within the DirectShow documentation, and see How to Get More Information for the location of useful information outside the DirectShow documentation.

The following table shows the background you might need to understand different sections of the DirectShow documentation.
Section | Background needed
Getting Started | None.
Using the ActiveMovie Control | You must know Microsoft® Visual Basic® or C/C++ if you're using the control from within them. If you're using the control as an end-user and not developing applications with it, the section is self-sufficient.
DirectShow Basics | None.
Application Developer's Guide | You must know the language you are developing your application in, and basic COM programming.
Filter Developer's Guide | You must be experienced with C/C++ and basic COM programming.
C/C++ Reference | You must know C/C++ and basic COM. For the "Debugging" section, it would be useful to understand basic debugging procedures, such as how to generate debug information or check for memory leaks. For the Event Notification Codes section, it might be helpful to know a little about Windows messaging.
Filters and Samples | You must know C/C++ and basic COM. Depending on your filter, you might need to know a little about DirectSound® and DirectDraw®, or understand multimedia capture and compression.
Appendixes | You must know a little about C to understand Reserved Identifiers, and you need to know a little about multimedia to understand Media Types.
Glossary | None.

The following table shows the background you might need to accomplish a sampling of tasks in DirectShow.
Task | Background needed
Use the ActiveMovie Control as an end-user. | None.
Use the Filter Graph Editor tool. | None.
Write a filter. | You must be experienced with C/C++ and basic COM.
Create or control a filter graph in Visual Basic. | You must be familiar with Visual Basic and basic COM.
Play a movie. | To play a movie in a Visual Basic or C/C++ application, you must be familiar with those languages and with basic COM programming. To play a movie from a Web page, you should be familiar with HTML, but the DirectShow documents will explain the rudiments, such as using the OBJECT and HREF tags.
Write a media-streaming application. | You must be familiar with C/C++ and basic COM.


Documentation Roadmap

The Microsoft® DirectShow™ SDK documentation is delivered in HTML format (which you can read by using a browser) and in .ivt format (which you can read using Microsoft InfoViewer). The Microsoft Developer Network (MSDN) Library and Microsoft Visual C++®, as well as other Microsoft products, install InfoViewer for you.

When you install the DirectShow SDK, the HTML documentation is always installed. The HTML start page, Start.htm, is available in the main installation directory (Dxmedia by default). If the DirectShow installation finds InfoViewer on your computer, it also installs and registers the .ivt documentation. The next time you open InfoViewer (through Visual C++, MSDN, or another program) the DirectShow SDK documentation will be available under the "DirectX Media SDK" heading.

For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

The DirectShow SDK documentation contains general sections that provide information useful to everyone, and sections that apply to particular tasks. Getting Started and DirectShow Basics contain high-level information useful to everyone. ActiveMovie Control, Application Developer's Guide, and Filter's Developer's Guide contain procedures and technical information specific to their respective topics. Multimedia Streaming describes the simplified streaming interfaces that enable developers to interface to a stream without creating a custom renderer or source filter. DirectDrawEx describes the DirectDrawEx dynamic-link library, which extends the current functionality of DirectDraw. Filters and Samples contains a brief description of the filters and sample applications shipped with DirectShow. C/C++ Reference is the DirectShow Reference. Appendixes contain supplemental information to the reference, and Glossary defines DirectShow terms.

See What Background Do You Need? to find out what background different tasks require.

Contents of this article:

  • Where Can I Learn About...
  • How to Get More Information

To help you find the information you need, the following list describes the content of each section in the DirectShow documentation and when you will typically use it.

  • Getting Started — gives general information about DirectShow, such as background needed to use DirectShow, material new in this release, and frequently asked questions. Read this section to orient yourself when first starting with DirectShow.
  • ActiveMovie Control — describes the ActiveMovie Control's features and how to use it to play back movies in different applications, such as C/C++, Visual Basic, or an HTML Web page. This section also contains the HTML reference and the Visual Basic 5.x reference, which describes using DirectShow COM interfaces as Visual Basic objects. Read this section if you want to use the control.
  • DirectShow Basics — contains overview articles covering basic DirectShow concepts, such as filter graph architecture and data flow, how to use the Filter Graph Editor tool, and a list of the filters and sample filters supplied with DirectShow. Read this section for a high-level introduction to DirectShow, whether you are developing your own filters or developing an application that uses the supplied filters.
  • Application Developer's Guide — contains articles about developing applications, including a discussion of media streaming, a list of application interfaces, and step-by-step procedures for adding features to your applications. Read this section if you want to develop applications with DirectShow.
  • Filter's Developer's Guide — contains technical articles about creating filters, including different filter types, connecting and controlling filters, and step-by-step procedures for creating specific filters, such as capture filters and DirectSound renderer filters. Read this section if you want to write your own filters.
  • C/C++ Reference — contains the COM interface and class library references, structures, utility functions, events, error messages, and debugging tips. Read this section to get details about an interface or a data type.
  • Filters and Samples — contains a brief description of the filters and sample applications shipped with DirectShow and available for use or for modification in your own applications. Read this section to create a prototype application from the supplied filters or to see if the filter you want to create already exists.
  • Multimedia Streaming — contains an overview of the multimedia streaming architecture, a list of the multimedia streaming interfaces, and the multimedia interface references. Read this section to learn how to use the multimedia streaming interfaces to automatically negotiate the transfer and conversion of data from the source to the application, so you don't have to write code to handle the connection, transfer of data, data conversion, and actual data rendering or file storage. The streaming interfaces provide a uniform and predictable method of data access and control, which makes it easy for an application to play back data, regardless of its original source or format.
  • DirectDrawEx — contains an overview of the DirectDrawEx dynamic-link library, which extends the current functionality of DirectDraw, and reference material for the IDirectDrawFactory and IDirectDraw3 interfaces.
  • Appendixes — contains miscellaneous technical information, including a list of AM_MEDIA_TYPE structure values supported in DirectShow, information about time stamps and DirectShow DVD support, country codes and channel-to-frequency mappings for TV tuner applications, and the reserved identifiers in the DirectShow header files. Read this section if you need details about one of these topics.
  • Glossary — defines DirectShow-specific terminology you might not be familiar with.

Where Can I Learn About...

This section tells you where to find information in the DirectShow documentation about specific tasks and topics. Also see the "Frequently Asked Questions" section for answers to common questions.

Q. Where should I begin reading in the DirectShow documentation?

A. Read for an overview and then read the articles in the and sections that match your interest. See Debugging with DirectShow for debugging information.

Q: Where can I find information about capture?

A: See the following capture topics.

  • About Capture Filter Graphs
  • Improving Capture Performance
  • Creating a Capture Application
  • Recompress an AVI File
  • Write an Audio Capture Filter
  • Write a Video Capture Filter
  • Enumerate and Access Hardware Devices in DirectShow Applications

DirectShow provides the following capture-related filters. The video renderer is often used for purposes other than capture.

  • ACM Audio Compressor
  • Audio Capture
  • AVI MUX
  • DV Muxer filter
  • File Writer
  • VFW Video Capture
  • VidCap Sample (Video Capture Filter)
  • Video Renderer

Capture-related interfaces:

  • IAMAudioInputMixer
  • IAMDroppedFrames
  • IAMStreamConfig
  • IAMVfwCaptureDialogs
  • IAMVfwCompressDialogs
  • IAMVideoCompression
  • ICaptureGraphBuilder
  • ICreateDevEnum

Q. Where can I find information about playing back movies using the C or C++ language?

A. Read Play a Movie from C++ in the .

Q. Where can I find information about playing back movies using Microsoft® Visual Basic®?

A. If you are using the ActiveMovie Control, see Using the ActiveMovie Control in Visual Basic. If you are constructing or controlling a filter graph with Visual Basic, see Constructing Filter Graphs Using Visual Basic and Controlling Filter Graphs Using Visual Basic in the section.

Q. Where can I find information about playing back movies from a Web page?

A. Read Using the ActiveMovie Control in HTML Pages in the section.

Q. Where can I find a class hierarchy diagram for the DirectShow base classes?

A. Each class in the DirectShow C++ Class Library section has its own class hierarchy diagram at the top of its opening page.

Q. Where can I find information about the filters shipped with DirectShow?

A. For a description of each of the filters included with the DirectShow run time, as well as the sample filters included with the SDK, see . When the SDK is installed, all sample filters are built and registered.

How to Get More Information

You can find most of the information you need beyond a knowledge of your particular programming language and the DirectShow documents themselves in the Platform SDK, available in the Microsoft Developer Network. See http://www.microsoft.com/msdn/ for more information.

COM Overview and DirectShow and COM can give you an introduction to Component Object Model (COM), and this might suffice for many development tasks in DirectShow. If you need more information, see the "COM" section in the Platform SDK, or an introductory book such as Understanding ActiveX OLE by David Chappell.

For more information about DirectDraw or DirectSound, see the Microsoft DirectX® SDK documentation in the Platform SDK.

For more information about multimedia in general, see the "Graphics and Multimedia Services" section in the Platform SDK.

For more information about Microsoft Windows® messaging, see the "Win32 Messages" section in the "Reference" portion of the Platform SDK.

For more information about media control interface (MCI), see the "MCI" section in the Platform SDK.

For more information about C/C++ programming, read the product documentation for your C/C++ compiler (such as the Microsoft Visual C++® documentation), or a standard C or C++ programming book. For more information about Visual Basic programming, read the Visual Basic product documentation.


Redistribution

The DirectShow SDK includes a redistributable package under the Redist directory. The DirectX Media redistributable package is called Dxmedia.exe. An application must register itself as a client of the redist package by running Dxmedia.exe with the -id switch and a unique identifier for the application, as shown in the following syntax:

dxmedia.exe -id:identifier

The identifier should uniquely identify your application. It can be the GUID of your registered application, or a unique string. You should probably not use a string such as "game," but a more distinctive string. For example:

dxmedia.exe -id:myrocketgame

- or -

dxmedia.exe -id:my_GUID

The identifier is required. If you simply type "Dxmedia.exe" or simply double-click on the Dxmedia.exe icon, nothing will be installed.

The same syntax is used for all platforms, Windows 95, Windows NT x86, and Windows NT Alpha. Note that each processor has its own executable (either an Alpha or an x86 version).

If successful, the installation can return one of the following success codes:

  • ERROR_SUCCESS - the installation completed successfully.
  • ERROR_SUCCESS_REBOOT_REQUIRED - the installation was successful, but changes will not be effective until the system is rebooted.

If unsuccessful, the installation returns an HRESULT describing the error; for example, E_FAIL or E_INVALIDARG.

The installation is totally quiet, and no dialog boxes appear.

The install/uninstall identifier does not need to be a GUID, but it must be unique. GUIDs are essentially guaranteed to be unique.

The install package automatically handles different versions during install. Files are only overwritten (after backup) if they use the same platform and are older than the files about to be installed.

An application can uninstall the DirectX Media package it installed during its own installation by calling the uninstall executable Purgedxm.exe, included with the redist package. You can uninstall by running Purgedxm.exe with the application identifier that was used during install, as shown in the following syntax:

purgedxm.exe identifier

Note: Do not use the -id switch when uninstalling.

The redistributable DirectX Media run-time setup installs the DirectX Media run-time components. It also installs a minimum version of DirectX Foundation on x86 and Alpha platforms, as appropriate. The application can install DirectX Foundation separately if the full installation is needed, after the redistributable package has been installed.

The source to the Filter Graph Editor (Graphedt.exe) tool is not available, and Graphedt.exe is not redistributable.


Frequently Asked Questions

This section answers many frequently asked questions about DirectShow. It is divided into three parts: answers to general questions, answers to questions asked by application developers, and answers to questions asked by filter developers.

Contents of this article:

  • General Questions
  • Redistribution Questions
  • Application Development Questions
  • Filter Development Questions

General Questions

Q. What are the differences between DirectShow™, DirectDraw®, DirectSound®, and DirectX®?

A. For an overview of these Microsoft® technologies as well as many others, see http://www.microsoft.com/directx/.

Q. What operating systems does DirectShow support?

A. DirectShow supports Windows® 95 or later and Windows NT® version 4.x or later.

Q. Is there an DirectShow Hardware Compatibility List (HCL)?

A. No. DirectShow uses all DirectDraw® and DirectSound hardware capabilities where they are available. Where no special hardware is available, DirectShow uses GDI to draw video and the waveOut* Multimedia APIs to play back audio.

Q. What multimedia file formats does DirectShow support?

A. DirectShow supports the following formats.

  • MIDI (.mid)
  • MPEG-1 (.mpg, .mpeg, .mpv, .mp2, .mpa, .mpe)
  • Audio-video interleaved (.avi)
  • Nonproprietary Apple® QuickTime® files (.mov, .qt)
  • Wave (.wav)
  • AU (.au, .snd)
  • AIFF (.aif, .aifc, .aiff)

Q. Where can I obtain detailed file format specifications?

A. One source is Encyclopedia of Graphics File Formats, second edition, by James D. Murray and William vanRyper, published by O'Reilly & Associates, Inc. That book describes MPEG-1, AVI, and some QuickTime file formats. See AVI 2.0 File Format Extensions for more information about DirectShow's support of this format.

Q. Does DirectShow provide video capture services?

A. Yes, DirectShow provides video capture.

Q. What version of Internet Explorer do I need to use DirectShow for Web content?

A. DirectShow is designed for Internet Explorer 3.x and later.

Q. What HTML tags would I use with DirectShow?

A. For information on the HTML tags to use to play movies using DirectShow, see Using the ActiveMovie Control in HTML Pages.

Q. Is there any sample code showing how to program DirectShow?

A. The DirectShow SDK includes sample source code in C, C++, and Microsoft Visual Basic®. For more information, see DirectShow Samples.

Q. What compiler do I need for DirectShow development?

A. DirectShow was designed with Visual C++® 5.x in mind, but any compiler capable of generating Component Object Model (COM) objects should work once the compiler's environment has been configured correctly. The base class libraries might need to be rebuilt to work completely since compilers can vary between versions.

Q. Do I need a compiler to play back movies?

A. No. Once DirectShow is installed, double-click any media file to view it. If you want more specialized applications, you can program DirectShow by using either C/C++ (in which case a compiler is required) or any Automation-compatible language (such as Visual Basic).

Q. When will DirectShow be integrated with Microsoft's operating systems?

A. DirectShow will be included in the next and future versions of Windows.

Q. Is the source for the ActiveMovie Control (Amovie.ocx) available?

A. No, the source is not available.

Q. What DirectX technologies are available on Windows NT?

A. Windows NT 5.x supports DirectX Foundation 5.x, including DirectDraw, DirectPlay®, DirectSound, Direct3D®, and DirectInput®. Windows NT 4.x supports DirectDraw, DirectPlay, and DirectSound.

Q. Can you recommend any reference books for Windows programming or COM?

A. Several books from Microsoft Press, including Advanced Windows by Jeffrey Richter and Understanding ActiveX and OLE by David Chappell, make great references for DirectShow developers.

Q. What is a GUID ?

A. A globally unique identifier (GUID) is a 128-bit (16-byte) integer that an algorithm creates. The algorithm uses several criteria, including the current date, time, and a machine identifier, to ensure that it will be unique. GUIDs are used extensively in the Component Object Model (COM) and have an important role in DirectShow.

Q. How do I get a GUID ?

A. GUIDs can be generated using Guidgen.exe. Guidgen, a Windows-native program, is included with Microsoft's Visual C++® products. Developers can also use Uuidgen.exe, a console application, in the Platform SDK.

Q. When do I need to call QueryInterface ?

A. Whenever you need to obtain an interface for an object.

Q. What are some typical "getting started" problems with COM?

A. Some typical problems involving COM are:

  • Forgetting to create a new GUID is a very common problem in filter development. For example, if you create a new filter based on one of the sample filters, you must create a new GUID for your filter. Otherwise, when you install your filter, it will overwrite the information that was already registered for the sample filter. Create a new GUID by using the Guidgen.exe tool.
  • Omitting the address of (&)' operator in the last parameter of a call to QueryInterface or CoCreateInstance causes an exception when trying to use the object specified in that last parameter. The problem can be difficult to debug, because the void cast required prevents a compiler warning. The following example shows both the bad and the good syntax in a call to QueryInterface.

IUnknown *pUnk;

// bad -- you will hit an exception when you try to use pUnk
// HRESULT hr = pObject->QueryInterface(IID_IPersist,
//                                     (void **)pUnk); // <-- bad

// good -- note the '&' is required for the last parameter
HRESULT hr = pObject->QueryInterface(IID_IPersist,
                                     (void **)&pUnk); // <-- good

Redistribution Questions

Q. What parts of DirectShow can I redistribute?

A. The SDK includes a redistributable package under the Redist directory.

Q. Is the source to the Filter Graph Editor (Graphedt.exe) tool available? Can the Filter Graph Editor be redistributed?

A. No, the source is not available, and Graphedt.exe is not redistributable.

Q. How can I install the DirectX Media redistributables package from my application?

A. The DirectX Media redistributable package is called Dxmedia.exe. An application must register itself as a client of the redist package by running Dxmedia.exe with the -id switch and a unique identifier for the application, as shown in the following syntax:

dxmedia.exe -id:identifier

The identifier should uniquely identify your application. It can be the GUID of your registered application, or a unique string. You should probably not use a string such as "game," but a more distinctive string. For example:

dxmedia.exe -id:myrocketgame

— or —

dxmedia.exe -id:my_GUID

The identifier is required. If you simply type "Dxmedia.exe" or simply double-click on the Dxmedia.exe icon, nothing will be installed.

The same syntax is used for all platforms, Windows 95, Windows NT x86, and Windows NT Alpha. Note that each processor has its own executable (either an Alpha or an x86 version).

If successful, the installation can return one of the following success codes:

  • ERROR_SUCCESS — the installation completed successfully.
  • ERROR_SUCCESS_REBOOT_REQUIRED — the installation was successful, but changes will not be effective until the system is rebooted.

If unsuccessful, the installation returns an HRESULT describing the error; for example, E_FAIL or E_INVALIDARG.

The installation is totally quiet, and no dialog boxes appear.

Q. Does the install/uninstall identifier need to be a GUID?

A. No, but it must be unique. GUIDs are essentially guaranteed to be unique.

Q. Does the install package handle different versions during install?

A. Yes, automatically. Files are only overwritten (after backup) if they use the same platform and are older than the files about to be installed.

Q. How does an application uninstall the DirectX Media package it installed during its own installation?

A. The redist package includes an uninstall executable called Purgedxm.exe. Uninstall by running Purgedxm.exe with the application's identifier that was used during install, as shown in the following syntax:

purgedxm.exe identifier

Note: Do not use the -id switch when uninstalling.

Q. Does the redistributable DirectX Media run-time setup install DirectX?

A. It installs the DirectX Media run-time components. It also installs a minimum version of DirectX Foundation on x86 and Alpha platforms, as appropriate. The application can install DirectX Foundation separately if the full installation is needed, after the redistributable package has been installed.

Application Development Questions

Q. How can you detect whether DirectShow is installed on a given machine?

A. Use the following code fragment to detect whether DirectShow is installed. It assumes that you have already included the Streams.h header file and initialized the COM subsystem by using the CoInitialize function with a null parameter. It also assumes that you will uninitialize COM by using the CoUninitialize function before closing your application.

IGraphBuilder * lpAMovie;

HRESULT hr = CoCreateInstance(
    CLSID_FilterGraph,
    0,
    CLSCTX_INPROC_SERVER,
    IID_IGraphBuilder,
    (void **) &lpAMovie );

if (SUCCEEDED(hr)) {
    lpAMovie->Release();
    // DirectShow is installed
} else {
    // DirectShow is not installed
}

Q. Which interfaces do applications typically use?

A. IGraphBuilder, IMediaEvent, IMediaControl, and IVideoWindow.

Q. How do I change the owner of the video window?

A. Use the IVideoWindow::put_Owner method.

Q. How do I play a movie in a specific window?

A. Use IVideoWindow::put_Owner to specify the window you want. Set the style of the video window to include WS_CHILD using the IVideoWindow::put_WindowStyle method, and then position the video window inside your window using the IVideoWindow::SetWindowPosition method. The following sample code demonstrates this process.

#include <windows.h>
#include <streams.h>

#define FILENAME L"C:\\WIN95.AVI"

void PlayVideoInWindow(HWND hTargetWindow)

{   // PlayVideoInWindow //

    CoInitialize(NULL);

    HRESULT hr;
    IGraphBuilder *pigb;

    // Create an empty filter graph object
    hr = CoCreateInstance(CLSID_FilterGraph,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IGraphBuilder,
        (void **)&pigb);

    if (FAILED(hr))
        return;

    hr = pigb->RenderFile(FILENAME, NULL);

    if (FAILED(hr)) {
        pigb->Release();
        return;
        }   // Bail out, file probably wasn't found! //

    RECT rc;
    IVideoWindow *pivw;

    hr = pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);
    pivw->put_Owner((OAHWND)hTargetWindow);

    // Here's the key: we must set the required flags,
    //   AND set the position
    pivw->put_WindowStyle(WS_CHILD | WS_CLIPCHILDREN | WS_CLIPSIBLINGS);
    GetClientRect(hTargetWindow, &rc);
    pivw->SetWindowPosition(rc.left, rc.top, rc.right rc.bottom);

    IMediaControl *pimc;

    hr = pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);

    long l;
    IMediaEvent *pime;

    hr = pigb->QueryInterface(IID_IMediaEvent, (void **)&pime);
    pimc->Run();

    pime->WaitForCompletion(INFINITE, &l);

    // The following MUST be called otherwise nasty things can happen!
    pivw->put_Owner(NULL);

    pime->Release();
    pimc->Release();
    pivw->Release();
    pigb->Release();

    CoUninitialize();

}   // PlayVideoInWindow

Q. Why doesn't my video always repaint correctly after being covered by another window?

A. You need to specify the WS_CLIPCHILDREN style for the video window's owner.

Q. When I try to build an application using DirectShow I get the following link error:

Error LNK2001: unresolved external symbol IID_IGraphBuilder

I have included the Strfim.h file provided with the DirectX Media SDK but within Strfim.h IDD_IGraphBuilder is defined as an external. Why?

A. The symbols are defined in Strmiids.lib, which is one of the libraries located in the \LIB directory. You need to link this library into your project. See Build a Filter or Application with Visual C++ 5.x for information on how to do this in Microsoft Developer Studio. The VC5KIT kit in the \TOOLS directory also describes how to configure Developer Studio to build DirectShow-based applications.

Q. Where are the DirectShow-specific return codes (HRESULTs) defined?

A. The error return codes specific to DirectShow are found in Vfwmsgs.h, located in the DirectShow SDK Include directory. More general errors, such as error codes returned by CoCreateInstance, can be found in \Msdev\Include\Winerror.h if you have Microsoft Developer Studio. Vfwmsgs.h and Winerror.h also provide information about the layout of HRESULT values. Before you search for a particular error in Winerror.h, you might need to convert the low portion to decimal, depending on the error.

Q. How do I interpret errors from Visual Basic?

A. Calls to DirectShow object methods and properties can return error codes; these codes are stored in (and can be retrieved from) the Number property of the Err object. Error numbers can be returned in one of two forms: an DirectShow error or a Visual Basic run-time error code. DirectShow errors are referred to by number, starting at 0x80040200 (2147746304 in decimal). You can look up the error number by its hexadecimal value in the Include\Vfwmsgs.h header file. When Visual Basic can interpret the external object error, it generates a Visual Basic run-time error. For example, the E_INVALIDARG return code from an interface generates Visual Basic run-time error 5, "remote procedure call failed". In cases when Visual Basic cannot interpret a system error (such as E_ABORT), error 287 is returned in the Err object.

Q. Why does the filter graph manager return E_NOTIMPL when I call IVideoWindow methods?

A. The E_NOTIMPL return value indicates that no filter is in the graph that supports IVideoWindow. In other words, your graph does not contain a video renderer. One solution is to call the IGraphBuilder::Render method and allow the filter graph manager to automatically insert any necessary filters and complete the filter graph.

Q. Why does the filter graph manager return VFW_E_NOT_CONNECTED when I call IVideoWindow methods?

A. The VFW_E_NOT_CONNECTED return value indicates that the video renderer's input pin is not connected.

Q. I want to use the ActiveMovie Control to play a video, but I only want the image to show and not the toolbar or controls. How do I do this?

A. You can turn off the controls and display through the property pages. Or, you can change the options programmatically by setting the ShowControls and ShowDisplay properties to FALSE (0).

Q. How do enumerators work?

A. Enumerators are COM objects created to traverse an ordered set. The application or filter can call a method such as IEnumPins::Next to obtain an item from the set. Enumerators are usually matched to the data type they retrieve. In DirectShow, there are different enumerators to retrieve items such as filters, pins, and media types.

Q. How do I change a filter's settings without displaying the property page?

A. If the filter exposes a custom interface for this purpose, then you can access the filter properties. The DirectShow SDK includes a sample called Contrast, which exposes methods such as get_ContrastLevel and put_ContrastLevel to enable you to change its properties programmatically. For more details, see the implementation of Contrast's property page. You can find a description of the Contrast filter in About Effect Filters and Contrast Sample (Video Contrast Filter).

Q. Can I change the properties of the MPEG audio decoder without displaying its property page?

A. Currently the MPEG audio codec does not allow you to set its properties programmatically.

Q. Can DirectShow notify me of its current position on a regular basis?

A. There is no callback notification of position. Use a timer and poll for the current position by using the IMediaSeeking::GetCurrentPosition method.

Q. My application monitors the frame rate and sets a new frame rate every time a certain event takes place. However, playback stutters as the rate adjusts. How do I switch the rate smoothly?

A. Alter the time stamps instead of changing the frame rate.

Filter Development Questions

Q. What programming languages can filters be developed in?

A. You can write DirectShow filters in any language that can generate objects adhering to Microsoft's Component Object Model (COM). The base classes for DirectShow are written in C++.

Q. Can I develop my filter using the Microsoft Foundation Classes (MFC)?

A.The DirectShow class library is totally independent of MFC and contains most of the base classes you might need for filter development. See Build a Filter or Application with Visual C++ 5.x for information on how to build DirectShow applications with Visual C++. You can use the VC5Kit located in the Tools directory for assistance in building these applications.

Q. What are the differences between source, rendering, and transform filters?

A. Source filters form the point of origin for data, while rendering filters present the data in a final format on various devices such as a video card, audio card, disk file, and so on. Transform filters manipulate, modify, or alter the data in some way.

Q. How do I install my filter?

A. For information about how to install (self-register) a filter, see Register DirectShow Objects and the IAMovieSetup interface.

Q. Where do I install my filter on an end-user system?

A. You can install the filter anywhere you want, because the filter registration process records the filter's full path and file name at the time of registration. There is no need to put your filter in the Windows System or System32 directory.

Q. What causes the Filter Graph Editor to report that "The filter could not be created. Resources used by this filter might already be in use." when I try to insert a filter?

A. The Filter Graph Editor (Graphedt.exe) displays this message when it can't find the filter's .ax file. The filter has probably been moved, renamed, deleted, or was not properly set up. It needs to be properly registered. For information about how to self-register a filter, see Register DirectShow Objects and the IAMovieSetup interface.

Q. What is the resolution of time stamps in DirectShow?

A. The minimum resolution is 100 nanoseconds.

Q. Can a filter graph have only one filter that performs the work of source, transform, and renderer?

A. Yes, but to take advantage of DirectShow's "plug-in" nature, it is best to use different combinations of filters chained together. This also provides easier code reuse and flexibility in design, and is strongly recommended.

Q. Can I have a filter with many input and output pins (with some fixed one-to-one correspondence between them)?

A. Yes. Ensure that you implement the IPin::QueryInternalConnections method on every pin. Without this, the graph builder will assume that each input pin streams through to every output pin. While you can have a filter with many input and output pins, it's often more desirable to have several filters. Otherwise, you might find yourself writing more code (overriding more and more functions from the base classes) than if you just use an individual filter for each stream.

Q. Why does the graph builder stream each of my input pins through to every output pin?

A. This is the default behavior. Implement the IPin::QueryInternalConnections method on every pin to avoid this.

Q. Can I use a filter outside an DirectShow filter graph?

A. No, filters are integrated with the DirectShow architecture and require a filter graph.

Q. How do I determine the number of pins on a filter?

A. Call the IBaseFilter::EnumPins method, and then keep calling the IEnumPins::Next method until you don't get any more pins.

Q. At what privilege ring do filters run?

A. Filters in DirectShow run at user-privilege level three (ring three on x86 processors).

Q. How do filters communicate with one another?

A. Filters typically communicate with one another through their pins. Pins negotiate a common format and transport for exchanging data.

Q. Can I test my filter with the Filter Graph Editor (Graphedt.exe)?

A. Graphedt was designed to help filter developers visualize the connections and interaction between filters during filter development. It is not meant as a robust test platform.

Q. Can pin direction change dynamically?

A. DirectShow pins are not designed to have their direction changed. You could create two pins, one for each direction, and use a single piece of code to drive both pins.

Q. Why is the MPEG audio codec filter sometimes missing from an auto-rendered graph? How can the MPEG stream splitter audio output pin connect directly to an audio renderer?

A. Codec filters are only required by the renderer if the audio driver does not support a given audio format. Renderers often query the audio driver inside CheckMediaType to determine if the proposed format is supported, and if supported, pass the media samples directly to the audio subsystem when the graph is run. If the driver incorrectly indicates a format is supported, the most obvious symptom is garbled audio. You then need to get corrected drivers from your audio board manufacturer.

Q. My source/capture filter feeds streaming data from a network card into a filter graph. How do I get the DirectShow ActiveMovie Control to automatically use my source filter?

A1. If you want your source filter to be recognized like the DirectShow file and URL source filters, then use one of the methods below.

Method 1: Refer to your object using some protocol name you make up (for example, ABC). Add an entry in the registry under HKEY_CLASSES_ROOT\ABC, specifying the CLSID of your source filter. Your source filter will be used for your fictional ABC protocol, much like HTTP is used for internet addresses.

Method 2: Use a special file to start up your filter with a known set of bytes (for example a UUID you define yourself). Add the necessary check bytes to the registry under HKEY_CLASSES_ROOT\Media Type, making up your own major type, or stick with MEDIATYPE_Stream as other filters do and specify the proper subtype. Put your filter's CLSID in the Source Filter value. Check bytes are (decimal start, decimal length, mask (default all FF), hex value) so for a CLSID at the start you want (0, 36, , your CLSID). See Registering a Custom File Type for more information.

A2.If you want your capture filter to show up in the list of devices in a video capture application, see Write a Video Capture Filter.


ActiveMovie Control

The ActiveMovie™ Control enables you to add movies and sound to your applications and Web pages. You can play back multimedia files that are in formats such as MPEG, AVI, WAV, and MOV, among others. Microsoft® Internet Explorer and the DirectShow SDK include the ActiveMovie Control. The DirectShow SDK provides background information about DirectShow's capabilities and architecture beyond the information provided in this section.

Using the ActiveMovie Control

Visual Basic Objects


Using the ActiveMovie Control

This section explains how to use the Microsoft® ActiveMovie™ Control, both in HTML pages and in Visual Basic applications. It contains a description of the control properties, methods, events, property sheet, and shortcut keys.

About the DirectShow ActiveMovie Control

Using the ActiveMovie Control in HTML Pages

Using the ActiveMovie Control in Visual Basic

Control Properties

Control Methods

Control Events

Control Property Sheet

Control Shortcut Keys


About the DirectShow ActiveMovie Control

You can use the DirectShow ActiveMovie Control to quickly add support for multimedia to your applications. DirectShow supports the many media types, including MPEG audio and video, AVI video, WAV audio, MIDI audio, and Apple® QuickTime® video. The DirectShow SDK provides samples and examples that illustrate how to write programs that use the control with either Microsoft® Visual Basic® or Microsoft Visual C++®.

The ActiveMovie Control represents an easy-to-use programming interface that lets you manage multimedia using the control's properties, methods, and events. The control handles all video and audio rendering for you, which simplifies your programming tasks and makes it easy to add support for multimedia to your application. In addition to the ActiveMovie Control, you can use the DirectShow Component Object Model (COM) interfaces. (See Summary of DirectShow COM Interfaces in the DirectShow SDK documentation.)


Using the ActiveMovie Control in HTML Pages

Files on a Web page are referenced using URL names and various protocols, such as HTTP, file, FTP, or Gopher. These names can be either explicit or relative.

Following are two examples of explicit references. The first example uses the HTTP protocol to access the file. The second uses a network path and file name.

"http://directshow/samples/web/RoadRun.avi"

"file://directshow/samples/web/RoadRun.avi"

Here is an example of a relative reference:

"/samples/web/RoadRun.avi"

In the examples in this article, you can assume that either relative or explicit file names will work and any protocol for accessing these file names will also work.

Contents of this article:

  • Invoking Playback on HTML Pages
  • Using the OBJECT Tag
  • Using the OBJECT Tag with the CODEBASE Attribute
  • Using the EMBED Tag
  • Using the IMG tag with the DYNSRC= Attribute
  • Using the A Tag with the HREF Attribute
  • How Progressive Downloading Works
  • Setting ActiveMovie Control Properties on a Web Page

Invoking Playback on HTML Pages

You can play files in one of two ways: either embedded in a Web page, or externally in a window displayed outside or on top of the page. There are four ways of playing back media using HTML tags. Three of these result in embedded playback:

  • OBJECT
  • EMBED
  • IMG DYNSRC=

The fourth means of implementing playback results in an external window:

  • A HREF

Although not restricted to playback, you can use an attribute of the OBJECT tag to automatically download a file that contains required components for playback.

  • OBJECT CODEBASE

The following examples show how you use these tags to reference the file, but do not show all possible properties and attributes (width, height, color, and so on) that could be specified as well. See Setting ActiveMovie Control Properties on a Web Page for more information.

Using the OBJECT Tag

When you use the OBJECT tag, you must explicitly specify the class identifier (CLSID) for the playback control, as shown in the following example.

<OBJECT CLASSID="CLSID:05589FA1-C356-11CE-BF01-00AA0055595A">
<PARAM NAME="FileName" VALUE="//directshow/samples/web/RoadRun.avi">
</OBJECT>

The preceding CLSID is that of the ActiveMovie Control. The application loads the control and passes it the file name. The control parses the file name and downloads and plays the file. If the protocol is "file," the control instantiates the File Source (async) filter to play back the file. If the protocol is "http," the control instantiates the File Source (URL) filter instead. See the DirectShow SDK documentation for more information on these filters.

Using this tag, you can play back certain media types using "progressive downloading," which allows the user to play back the downloaded portion of the file as the data is downloading. See How Progressive Downloading Works for more information.

Using this tag along with the CODEBASE attribute, you can download components required for playback. See Using the OBJECT Tag with the CODEBASE Attribute for more information.

Using the OBJECT Tag with the CODEBASE Attribute

As the author of a Web page, you might find that using components such as specialized DirectShow filters can enhance playback of your media files on the user's machine. However, if the necessary components aren't already installed on the user's computer, you need a method to install those components. Internet Explorer supports using the CODEBASE attribute of the OBJECT tag for automatic file download, and cabinet (.cab) files for automatic installation. See http://www.microsoft.com/workshop/prog/cab/default.htm for information about the Cabinet SDK and .cab files.

The CODEBASE attribute works in conjunction with the OBJECT tag. See Using the OBJECT Tag for another example that uses the OBJECT tag.

An example of filter download using the CODEBASE attribute and a .cab file follows:

<OBJECT ID=GargleFilter1
CLASSID="CLSID:d616f350-d622-11ce-aac5-0020af0b99a3"
CODEBASE="http://directshow/samples/gargle.cab">
</OBJECT>

The preceding class identifier (CLSID) is the ID of the Gargle filter, which applies a "gargle" sound effect to a sound file. Internet Explorer checks the target computer's registry for the specified CLSID. If the specified CLSID is not present (indicating the filter is not installed on the machine), the browser attempts to find the file (Gargle.cab) at the site specified by the CODEBASE attribute and download it. Once downloaded, the .cab file provides the information to automatically install the filter.

Note: The .cab file must have been properly constructed for automatic installation to work. The .cab must include the filter (Gargle.ax in this case) and an .inf file that contains installation information. The .inf file should handle copying each filter to a specific directory (such as the Windows® System directory) on the user's computer and properly registering each filter. See the Platform SDK for information about .inf files.

Using the EMBED Tag

Netscape introduced this tag for embedding source. The following example uses this tag.

<EMBED autostart="FALSE" loop="FALSE" SRC="http://directshow/samples/web/RoadRun.avi">

This tag works identically to the OBJECT tag, except that you don't need to specify the CLSID. Internally, DirectShow examines the HKCR/MIME/Database/Content Type registry entries, retrieves the appropriate CLSID (DirectShow automatically registers all compatible data types at install time), and launches the control with that media type.

Using the IMG tag with the DYNSRC= Attribute

Internet Explorer can use the DYNSRC= attribute to play back audio-video interleaved (AVI) files. You can use this playback mechanism, but it is preferable to use the OBJECT tag. The following example demonstrates this HTML tag.

<IMG start=1 loop=0 DYNSRC="http://directshow/samples/web/RoadRun.avi">

Using the A Tag with the HREF Attribute

To play back a movie in an external movie, use the A tag with the HREF attribute. An example of this follows:

<A HREF="http://directshow/samples/web/dwad.cinepack.avi">AVI_CINEPACK</A>

The parsing steps that Internet Explorer 3.0 (or later) goes through are similar to the "EMBED SRC tag" case, in that it gets the file extension, maps it to a content type and looks in the HKCR/MIME/Database/Content Type area of the registry to get a CLSID to invoke. However, in this case the control plays in an external window. The ActiveMovie Control is in control of downloading the file.

How Progressive Downloading Works

The following series of steps describes what happens during progressive downloading.

  1. As soon as possible after activation, the ActiveMovie Control displays the first frame in the file (for movies). The filter graph remains in a paused state.
  2. The control does not start to play until it determines that it has enough data to play uninterrupted while the remaining amount downloads. At this time, playback starts and downloading will continue.
  3. The user can click the Play button during this time. In this case, the control will play until the play cursor reaches the end of the current amount downloaded and will automatically transition from the running state to the paused state.
  4. The download of the file will not stop if the user clicks Stop. The user can stop the download by closing the control.
  5. For most AVI or QuickTime files, you can't start playback until DirectShow has read the entire file (because the indexes are at the end of the file). However, the download bar is displayed to show how much of the file has been downloaded. The Play control button remains unavailable until the control downloads the file completely.

Setting ActiveMovie Control Properties on a Web Page

You can set any ActiveMovie Control property by using the PARAM tag inside an OBJECT container. For Boolean values, –1 is TRUE and 0 is FALSE. All other values are set as they would be in the Microsoft® Visual Basic® design environment.

The following example demonstrates playing a movie with most controls shown. If you have a video file and you want to try this, you can copy and paste this code onto your Web page and modify the parameters as you want. If you do this, be sure to change the movie's file name, perhaps using a relative path and file protocol (for example, PARAM NAME="FileName" VALUE="file://c:\mymovie.mpg") to play the movie from your hard drive.

<HTML>
<HEAD>
<TITLE>ActiveMovie Embedded MPG Object Test Page</TITLE>
</HEAD>
<BODY>
Scene from Stargate (MPG File)

<OBJECT ID="ActiveMovie1" WIDTH=357 HEIGHT=322
CLASSID="CLSID:05589FA1-C356-11CE-BF01-00AA0055595A">
<PARAM NAME="Version" VALUE="1">
<PARAM NAME="EnableContextMenu" VALUE="-1">
<PARAM NAME="ShowDisplay" VALUE="-1">
<PARAM NAME="ShowControls" VALUE="-1">
<PARAM NAME="ShowPositionControls" VALUE="0">
<PARAM NAME="ShowSelectionControls" VALUE="0">
<PARAM NAME="EnablePositionControls" VALUE="-1">
<PARAM NAME="EnableSelectionControls" VALUE="-1">
<PARAM NAME="ShowTracker" VALUE="-1">
<PARAM NAME="EnableTracker" VALUE="-1">
<PARAM NAME="AllowHideDisplay" VALUE="-1">
<PARAM NAME="AllowHideControls" VALUE="-1">
<PARAM NAME="MovieWindowSize" VALUE="0">
<PARAM NAME="FullScreenMode" VALUE="0">
<PARAM NAME="MovieWindowWidth" VALUE="353">
<PARAM NAME="MovieWindowHeight" VALUE="318">
<PARAM NAME="AutoStart" VALUE="0">
<PARAM NAME="AutoRewind" VALUE="-1">
<PARAM NAME="PlayCount" VALUE="1">
<PARAM NAME="SelectionStart" VALUE="0">
<PARAM NAME="SelectionEnd" VALUE="48.5151388">
<PARAM NAME="Appearance" VALUE="1">
<PARAM NAME="BorderStyle" VALUE="1">
<PARAM NAME="FileName" VALUE="http://DirectShow/samples/web/stargate1.mpg">
<PARAM NAME="DisplayMode" VALUE="0">
<PARAM NAME="AllowChangeDisplayMode" VALUE="-1">
<PARAM NAME="DisplayForeColor" VALUE="16777215">
<PARAM NAME="DisplayBackColor" VALUE="0">
</OBJECT>
</BODY>


Using the ActiveMovie Control in Visual Basic

This article describes how Microsoft® Visual Basic® applications can use the ActiveMovie Control. The ActiveMovie Control is a high-level interface that meets the needs of most multimedia application developers. Additional lower-level interfaces are also available to Visual Basic programmers.

Contents of this article:

  • Quick Start: Insert and Use the ActiveMovie Control
  • The Visual Basic Ocxvb01 Sample
  • Opening and Running DirectShow Source Files
  • Managing the User Interface of the ActiveMovie Control
  • Monitoring ActiveMovie Control Events

Quick Start: Insert and Use the ActiveMovie Control

This section describes how to insert the ActiveMovie Control and use it in a Visual Basic application. It is a simple example to get you started, and implements only playing and stopping a movie.

Follow these steps to insert the ActiveMovie Control into a Visual Basic form and play a movie:

  1. Install Internet Explorer to install the ActiveMovie Control.
  2. Open a project or create a new project in Visual Basic.
  3. Choose Components from the Projects menu. Choose the Controls tab. If the ActiveMovie Control does not appear in the list of Controls, click the Browse button. In the Add ActiveX Control dialog box that appears, navigate to the directory containing the control (by default, the \Windows\System or \Winnt\System32 directory). Double-click the Amovie.ocx file to add the ActiveMovie Control to the Controls list.
  4. Add the ActiveMovie Control to the Visual Basic toolbox by selecting the check box next to Microsoft ActiveMovie Control in the Controls list.
  5. Add the ActiveMovie Control to your form and size the control to the screen size you want for your movie. (Click the control in the Toolbox, and then draw its size on the form.)
  6. In the Properties list for the ActiveMovie Control, initialize the FileName property to the movie file you want to play. The FileName property should contain the full path. For example:
    c:\movies\mymovie.avi
  7. Set the ShowControls and ShowDisplay properties to FALSE.
  8. Add code to start and stop the movie to two events the ActiveMovie Control supports. For example:
    Private Sub ActiveMovie1_Click()
    ActiveMovie1.Run
End Sub

Private Sub ActiveMovie1_KeyPress(KeyAscii As Integer)
     ActiveMovie1.Stop
End Sub
  9. Compile the application.
  10. Run the application. In this example, click anywhere on the movie screen to start the movie. Press any key to stop the movie.

Follow these steps to use the ActiveMovie Control to play a movie controlled by Visual Basic controls:

  1. Follow steps 1-6 as shown earlier in this section.
  2. Add Visual Basic controls (such as a CommandButton or ListBox) to your form to play and stop the movie.
  3. Add code to play and stop the movie. For example:
    Private Sub Command1_Click()
ActiveMovie1.Run
End Sub

Private Sub Command2_Click()
ActiveMovie1.Stop
End Sub
  4. Compile the application.
  5. Run the application. In this example, Click the Command1 button to start the movie. Click the Command2 button to stop the movie.

The Visual Basic Ocxvb01 Sample

This section describes some of the features of the DirectShow Visual Basic sample application called Ocxvb01 in the VB\OCX directory of the DirectShow samples. The ActiveMovie Control manages most of the details of the display and playback of DirectShow files, while giving the Visual Basic developer control over the image size, playback rate, volume, balance, and position. With the control, the developer can manage a variety of standard user interface controls, such as rewind and fast forward, and a trackbar control to set positions within the media file.

The Visual Basic sample application Ocxvb01 consists of two forms: the main control form frmMain (Ocxvb01.frm) and the display form frmViewer (Viewer.frm).

The frmMain form's menu commands call ActiveMovie Control methods to run, pause, and stop multimedia playback, set and retrieve the control's properties, and enable and disable different parts of the user interface.

The frmMain form contains two command buttons that change the CurrentPosition property of the IMediaPosition object; you can use these buttons to move forward or backward through the multimedia source file, if the multimedia source type supports this functionality. The frmMain form's trackbar control sets the Playback property; its valid range is 0.5 to 1.5. This value is used as a multiplier; 1.0 is the authored speed, so 0.5 is half the authored speed and 2.0 is twice the authored speed. You can set this property to values outside this range, but the audio portion tends to become incomprehensible.

The main control form also contains option buttons that set the display configuration to half size, full size (default), and double size. The main control form appears as shown in the following illustration.

Main control form

The display form, frmViewer, contains the ActiveMovie Control that is displayed when the DirectShow multimedia source file is active or when the source is playing. The application resizes the display form to correspond to the selected source. The display form, with all ActiveMovie Control user interface elements visible and enabled, appears as shown in the following illustration.

Display form with all ActiveMovie Control elements visible and enabled

The following sections describe how to use some of the properties, methods, and events.

Opening and Running DirectShow Source Files

To load and play a DirectShow file, set the ActiveMovie Control's FileName property. Depending on your application's requirements, you can play the file from your code by using methods like Run and Stop, or you can let the user interact with the user interface elements offered by the control.

The FileName property specifies the name of the multimedia source file. When you set the FileName property, several other properties are updated to indicate characteristics of that source file.

Once the FileName property contains a valid file name, you can call the control's Run method to play the multimedia file. Or, you can enable the control buttons on the display form and let the user play the file.

The sample application contains an Open command on the File menu that sets the value of the FileName property. It invokes the File Open common dialog box to obtain a file name:

   Private Sub mnu_File_Open_Click()

      CommonDialog1.Filter = "All files (*.*)|*.*|DirectShow files
(*.mpg;*.mpa;*.mpv;*.mov;*.mpeg;*.enc;*.m1v;*.mp2)|*.mpg;*.mpa;*.mpv;*.mov;*.mpeg;*.enc;*.m1v;*.
mp2|Audio files (.wav)|*.wav|Video for Windows files
(.avi)|*.avi"
      CommonDialog1.Flags = 4 'Hide read-only check box
      CommonDialog1.ShowOpen
      ' only set the property if the user selected a filename from the common dialog
      If CommonDialog1.filename <> "" Then
         frmViewer.ActiveMovie1.filename = CommonDialog1.filename
         g_FileOpened = True
         g_FileExtension = Right$(CommonDialog1.filename, Len(CommonDialog1.filename) -
InStr(CommonDialog1.filename, "."))
      Else
         GoTo err_FileOpen
      End If
      Call ResizeViewer
      ...

First, the subroutine prepares the common dialog box to display only movie files. After the common dialog box returns, the subroutine checks to determine if a file name was returned.

If a file name was returned, the subroutine sets the FileName property of the ActiveMovie Control, in addition to some other global variables: gFileOpened to determine whether or not a file has been opened, and gFileExtension to determine the type of the file.

Finally, the subroutine calls the ResizeViewer subroutine to make the dimensions of the viewer form match those of the DirectShow file. The dimensions of the Visual Basic form are expressed in twips, while the dimensions of the multimedia source are expressed in pixels. The ResizeViewer subroutine considers these differences to size the form by using the form's ScaleHeight and ScaleWidth properties:

' Resize form to dimensions of ActiveMovie Control + nonclient region.
    With frmViewer
        .Visible = False
        .Height = .ActiveMovie1.Height + (.Height - .ScaleHeight)
        .Width = .ActiveMovie1.Width + (.Width - .ScaleWidth)
        .Visible = True
    End With

After the file is loaded successfully, you can play it by clicking Play on the control, or by using the Run method. The sample application provides a Run command on its File menu that calls the Run method:

   Private Sub mnu_File_Run_Click()

      If g_FileOpened = True Then
         frmViewer.ActiveMovie1.Run
         frmViewer.ZOrder 0
      End If

Managing the User Interface of the ActiveMovie Control

The display form of the sample application (Viewer.frm) contains the ActiveMovie Control. The following illustration shows the control with the status bar visible and the control bar hidden.

ActiveMovie Control with status bar visible and control bar hidden

You can use the ActiveMovie Control properties to show or hide and enable or disable user interface elements of the ActiveMovie Control. The sample application includes selected menu commands that enable you to individually control each of the user interface elements. The commands on the View menu enable you to control whether the element is visible. The commands on the Enable menu enable you to control whether the element is enabled.

When the sample application loads a new file, it resets the ActiveMovie Control properties to default values and initializes the values of these selected menu commands. This fragment is from the mnu_File_Open_Click procedure:

   With frmViewer.ActiveMovie1
      .EnablePositionControls = False              'Disable/Enable controls.
      .EnableSelectionControls = False
      .EnableTracker = False
      .ShowPositionControls = False                'Show/don't show controls.
      .ShowSelectionControls = False
      .ShowTracker = True
      mnu_Enable_PositionControls.Checked = False  'Check/uncheck menus to match
      mnu_Enable_SelectionControls.Checked = False 'controls.
      mnu_Enable_Tracker.Checked = False
      mnu_View_Tracker.Checked = True
      mnu_View_PositionControls.Checked = False
      mnu_View_SelectionControls.Checked = False
      ...
   End With

Many of the control elements have two properties associated with them: one to enable them and another to make them visible. To use the position controls, set both the EnablePositionControls and ShowPositionControls properties. The following illustration shows the display controls and all position controls with all elements of the user interface both visible and enabled.

Display form with all ActiveMovie Control elements visible and enabled

Monitoring ActiveMovie Control Events

The ActiveMovie Control automatically monitors certain events and calls event procedures accordingly. To handle one of these events, you provide only the event handling code. For example, the StateChange event indicates a change in the state of the multimedia source, such as the change from running to stopped, or the change from paused to running. To take some action when this event occurs, the application provides code as part of the control's StateChange event.

To demonstrate these event handlers, the sample application provides trivial code that increments a variable. The variable represents a count of the number of times the event has occurred. The current values for these counter variables are displayed at the bottom of the main form. The following example shows the code for the StateChange event.

   Private Sub ActiveMovie1_StateChange(ByVal oldState As Long, ByVal newState As Long)

      g_cStateChange = g_cStateChange + 1
      UpdateStatusBar

Each event procedure passes some informational parameters too. For the StateChange event, you can determine the previous state, in addition to the control's current state, by examining the oldState and newState parameters.


Control Properties

The ActiveMovie Control supports the following properties.
Property | Description
AllowChangeDisplayMode | Indicates whether or not the end-user can change the display mode at run time between seconds and frames.
AllowHideControls | Indicates whether or not the end-user can hide the control panel at run time.
AllowHideDisplay | Indicates whether or not the end-user can hide the display panel at run time.
Appearance | Specifies the appearance of the display panel's border.
AutoRewind | Indicates whether or not the multimedia stream should automatically return to the selection's starting point when it reaches the end of the selection.
AutoStart | Indicates whether or not to automatically start playing the multimedia stream.
Balance | Specifies the stereo balance.
BorderStyle | Specifies the control's border style.
CurrentPosition | Specifies the current position within the playback file, in seconds.
CurrentState | Specifies the playback file's current state: stopped, paused, or running.
DisplayBackColor | Specifies the display panel's background color.
DisplayForeColor | Specifies the display panel's foreground color.
DisplayMode | Indicates whether or not the display panel shows the current position in seconds or frames.
EnableContextMenu | Indicates whether or not to enable the shortcut menu.
Enabled | Specifies whether or not the control is enabled.
EnablePositionControls | Indicates whether or not to show the position buttons in the controls panel.
EnableSelectionControls | Indicates whether or not to show the selection buttons in the controls panel.
EnableTracker | Indicates whether or not to show the trackbar control in the controls panel.
FileName | Specifies the name of the source data file.
FilterGraph | Contains the IUnknown interface pointer to the current filter graph object.
FilterGraphDispatch | Contains the IDispatch interface pointer to the current filter graph object.
FullScreenMode | Expands the area of the playback panel to fill the entire screen.
MovieWindowSize | Specifies the size of the playback panel.
PlayCount | Specifies the number of times to play the multimedia stream.
Rate | Specifies the playback rate for the stream.
ReadyState | Specifies the state of readiness for this ActiveMovie Control, based on how completely the source file has loaded.
SelectionEnd | Specifies the ending position in this multimedia stream, in seconds, relative to the stream's beginning.
SelectionStart | Specifies the starting position in this multimedia stream, in seconds, relative to the stream's beginning.
ShowControls | Indicates whether or not the controls panel is visible.
ShowDisplay | Indicates whether or not the display panel is visible.
ShowPositionControls | Indicates whether or not the position controls are visible.
ShowSelectionControls | Indicates whether or not the selection controls are visible.
ShowTracker | Indicates whether or not the trackbar is visible.
Volume | Specifies the volume, in hundredths of decibels.

The ActiveMovie Control supports the following properties that are common to other controls: Appearance, BorderStyle, Enabled, and hWnd. For information about these properties, see the documentation for Visual Basic.

AllowChangeDisplayMode Property

Control Properties

Indicates whether or not the end-user can change the display mode at run time between time and frames.

[form.]object.AllowChangeDisplayMode [ = { True | False } ]

Remarks

This property controls run-time access to the DisplayMode property, which specifies whether to show the multimedia file's current position in time or frames. If you set this property to True, the end-user can change how the control displays the current position by right-clicking the control window and choosing Time or Frames from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The end-user can change the type of display at run time.
False | The end-user cannot change the type of display at run time.

Data Type

Boolean

AllowHideControls Property

Control Properties

Indicates whether or not the end-user can control the visibility of the controls panel at run time.

[form.]object.AllowHideControls [ = { True | False } ]

Remarks

This property controls run-time access to the ShowControls property, which hides and displays the controls panel. If you set this property to True, the end-user can show or hide the controls panel by right-clicking the control window and choosing Controls from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The end-user can hide or show the controls panel.
False | The end-user cannot hide or show the controls panel.

Data Type

Boolean

AllowHideDisplay Property

Control Properties

Indicates whether or not the end-user can hide the display panel at run time.

[form.]object.AllowHideDisplay [ = { True | False } ]

Remarks

This property controls run time access to the ShowDisplay property, which hides and displays the display panel. If you set this property to True, the end-user can show or hide the display panel by right-clicking the control window and choosing Display from the shortcut menu.

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The end-user can hide or show the display panel.
False | The end-user cannot hide or show the display panel.

Data Type

Boolean

Appearance Property

Control Properties

Specifies the appearance of the display panel's border.

[form.]object.Appearance [ = long ]

Remarks

This property is identical to the standard Visual Basic Appearance property.

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
1 | (Default) The display panel has an inset border, which gives the illusion of depth. This value is the same as 3D.
0 | The display panel has no border. This value is the same as Flat.

Data Type

Long

AutoRewind Property

Control Properties

Indicates whether or not the multimedia stream should automatically return to the selection's starting point when it reaches the end of the selection.

[form.]object.AutoRewind [ = { True | False } ]

Remarks

If you set this property to True, DirectShow sets CurrentPosition to the position specified by SelectionStart when it reaches the position specified by SelectionEnd.

To retain the current position within the multimedia stream, set AutoRewind to False or use the Pause method.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) Reposition the multimedia stream to the start of the selection after playback stops.
False | Do not reposition the multimedia stream to the start of the selection after playback stops.

Data Type

Boolean

See Also

AutoStart

AutoStart Property

Control Properties

Indicates whether or not to automatically start playing the multimedia stream.

[form.]object.AutoStart [ = { True | False } ]

Remarks

If you set this property to False, you must make an explicit call to the Run method to play the stream.

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
True | Automatically start playing the multimedia stream.
False | (Default) Do not automatically start the multimedia stream.

Data Type

Boolean

See Also

PlayCount

Balance Property

Control Properties

Specifies the stereo balance.

[form.]object.Balance [ = long ]

Remarks

The value 0 indicates that the sound is balanced equally between the left and right speakers. A value of –10,000 indicates that all sound is going to the left speaker and 10,000 that all sound is going to the right speaker.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
long | Numeric expression that specifies the balance value. The number ranges from –10,000 to 10,000 and defaults to 0.

Data Type

Long

See Also

Volume Property

BorderStyle Property

Control Properties

Specifies the control's border style.

[form.]object.BorderStyle [ = long ]

Remarks

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
0 | No border.
1 | (Default) Fixed, single-line border.

Data Type

Integer (Enumerated)

CurrentPosition Property

Control Properties

Specifies the current position within the multimedia stream, in seconds.

[form.]object.CurrentPosition [ = double ]

Remarks

The new value must be within the range specified by the SelectionStart and SelectionEnd properties.

The current position value displayed by the control's user interface can represent either seconds or frames. The DisplayMode property determines the units shown.

Setting the CurrentPosition property at run time is similar to a seek operation and changes the position to the specified point in the multimedia stream.

Run-time access: read/write. Design-time access: not applicable.

Settings
Setting | Description
double | New position within the stream, in seconds.

Data Type

double

CurrentState Property

Control Properties

Describes the playback file's current state.

[form.]object.CurrentState

Remarks

You cannot assign a value to this property. You can change it by calling the Stop, Run, or Pause method, and DirectShow notifies the application of the change by sending the StateChange event.

The amv settings are available only to C/C++ programmers; scripters and other programmers should use the numerical values.

Run-time access: read-only. Design-time access: not applicable.

Settings
Setting | Value | Description
amvStopped | 0 | The player is stopped.
amvPaused | 1 | The player is paused.
amvRunning | 2 | The player is playing the multimedia file.

Data Type

Long

DisplayBackColor Property

Control Properties

Specifies the display panel's background color.

[form.]object.DisplayBackColor [ = color ]

Remarks

At design time, the default setting is black (0x0).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Object Browser's object library.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Windows® operating environment substitutes the user's choices as specified in the Control Panel settings.

See Also

DisplayForeColor

DisplayForeColor Property

Control Properties

Specifies the display panel's foreground color.

[form.]object.DisplayForeColor [ = color ]

Remarks

At design time, the default setting is white (&HFFFFFF).

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the Object Browser's object library.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
Normal RGB colors | Colors specified by using the color palette or by using the Visual Basic RGB or QBColor functions in code.
System default colors | Colors specified by system color constants listed in the Object Browser's object library. The Windows operating environment substitutes the user's choices as specified in the Control Panel settings.

See Also

DisplayBackColor

DisplayMode Property

Control Properties

Indicates whether the display panel shows the current position in seconds or frames.

[form.]object.DisplayMode [ = setting ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
0 | (Default) Display the current position in seconds.
1 | Display the current position in frames.

Data Type

Integer (Enumerated)

See Also

AllowHideDisplay, ShowDisplay

EnableContextMenu Property

Control Properties

Indicates whether or not to enable the control's shortcut menu.

[form.]object.EnableContextMenu [ = { True | False } ]

Remarks

The shortcut menu appears when the end-user right-clicks anywhere on the control.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The shortcut menu is enabled.
False | The shortcut menu is disabled.

Data Type

Boolean

See Also

ShowDisplay

Enabled Property

Control Properties

Specifies whether or not the control is enabled.

[form.]object.Enabled [ = setting ]

Remarks

This property is identical to the standard Visual Basic Enabled property.

A disabled control remains visible (if it already was) and will continue to play, if it was already playing. When a control is disabled, none of the commands or menus respond to user input.

Disabling a control at design time is useful if you want to control the media stream from an external source, such as a custom group of controls on a Web page, instead of from the built-in controls panel.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
-1 | (Default) The control is enabled.
0 | The control is disabled.

Data Type

Integer (Enumerated)

EnablePositionControls Property

Control Properties

Indicates whether or not to show the position buttons in the controls panel.

[form.]object.EnablePositionControls [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The position controls are visible.
False | The position controls are not visible.

Data Type

Boolean

See Also

ShowPositionControls

EnableSelectionControls Property

Control Properties

Indicates whether or not to show the selection controls in the controls panel.

[form.]object.EnableSelectionControls [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The selection controls are visible.
False | The selection controls are not visible.

Data Type

Boolean

See Also

ShowSelectionControls

EnableTracker Property

Control Properties

Indicates whether or not to show the trackbar control.

[form.]object.EnableTracker [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The trackbar is visible.
False | The trackbar is not visible.

Data Type

Boolean

See Also

ShowTracker

FileName Property

Control Properties

Specifies the name of the source data file.

[form.]object.FileName [ = string ]

Remarks

The ActiveMovie Control asynchronously opens the file specified by this property at run time. This means that an application must receive the ReadyStateChange event with an amvInteractive or amvComplete value before attempting to call the Run method.

When designing an application using Microsoft® Visual Basic® that uses the ActiveMovie Control, you can choose the media source file at design time. After you add a control to the application, fill in the full path to the media file as the value for the FileName property in Properties. You can also double-click the "..." value in the uninitialized FileName property and its property page will appear. If you click the Browse button, you can pick the desired source file from the Open dialog box.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
string | Name of the file that contains the multimedia stream.

Data Type

String

FilterGraph Property

Control Properties

Contains the IUnknown interface pointer to the current filter graph object.

[form.]object.FilterGraph [ = punk ]

Remarks

The filter graph represents a specific configuration of source, transform, and rendering filters. The filter graph is the complete set of software components needed to process a given multimedia stream within the DirectShow architecture.

You can set this property to change the current filter graph.

The IDispatch interface pointer for the filter graph object is contained in the FilterGraphDispatch property.

Run-time access: read/write. Design-time access: read-only.

Settings
Setting | Description
punk | IUnknown pointer for the filter graph object.

Data Type

Integer (IUnknown*)

See Also

IFilterGraph Interface in the DirectShow SDK documentation.

FilterGraphDispatch Property

Control Properties

Contains an IDispatch interface pointer to the current filter graph object.

[form.]object.FilterGraphDispatch [ = pdisp ]

Remarks

The filter graph represents a specific configuration of source, transform, and rendering filters. The filter graph represents the complete set of software components needed to process a given multimedia stream within the DirectShow architecture.

Run-time access: read-only. Design-time access: read-only.

Settings
Setting | Description
pdisp | IDispatch pointer to the current filter graph object.

Data Type

Integer (IDispatch*)

See Also

FilterGraph

FullScreenMode Property

Control Properties

Expands the area of the playback panel to fill the entire screen.

[form.]object.FullScreenMode [ = { True | False } ]

Remarks

Run-time access: read-only. Design-time access: read/write.

Settings
Setting | Description
True | Use full-screen mode.
False | Do not use full-screen mode.

Data Type

Boolean

See Also

MovieWindowSize

MovieWindowSize Property

Control Properties

Specifies the size of the playback panel.

[form.]object.MovieWindowSize [ = setting ]

Remarks

The amv settings are available only to C/C++ programmers; scripters and other programmers should use the numerical values.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Value | Description
amvOriginalSize | 0 | (Default) Uses the authored size.
amvDoubleOriginalSize | 1 | Increases the image projection size to twice the authored size.
amvOneSixteenthScreen | 2 | Projects the images onto an area the size of one-sixteenth of the screen.
amvOneFourthScreen | 3 | Projects the images onto an area the size of one-quarter of the screen.
amvOneHalfScreen | 4 | Projects the images onto an area the size of half of the screen.

Data Type

Long

PlayCount Property

Control Properties

Specifies the number of times to play the multimedia stream.

[form.]object.PlayCount [ = long ]

Remarks

If you set this property to zero, the control will play the multimedia stream repeatedly, restarting as soon as it reaches the end.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
long | Numeric expression that specifies the number of times to play the multimedia stream.

Data Type

Long

See Also

AutoStart

Rate Property

Control Properties

Specifies the playback rate for the multimedia stream.

[form.]object.Rate [ = double ]

Remarks

This property acts as a multiplier value that allows you to play the stream at a faster or slower rate. The value 1.0 indicates the authored speed. Note that the audio track becomes difficult to understand at rates lower than 0.5 and higher than 1.5.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
double | Numeric expression that represents the playback rate; 1.0 corresponds to the authored rate and is the default value.

Data Type

double

ReadyState Property

Control Properties

Specifies the control's state of readiness.

[form.]object.ReadyState

Remarks

The ActiveMovie Control changes this property at run time, and its value is passed as a parameter to the ReadyStateChange event. The run method will only work on the control after the ReadyState property has reached the amvInteractive or amvComplete state.

Run-time access: read-only. Design-time access: read-only.

Settings
Setting | Value | Description
amvUninitialized | 1 | The FileName property has not been initialized.
amvLoading | 0 | The ActiveMovie Control is asynchronously loading a file.
amvInteractive | 3 | The control loaded a file, and has downloaded enough data to play the file, but has not yet received all data.
amvComplete | 4 | All data has been downloaded.

Data Type

Long

SelectionEnd Property

Control Properties

Specifies the ending position in this multimedia stream, in seconds, relative to the stream's beginning.

[form.]object.SelectionEnd [ = double ]

Remarks

The default value for SelectionEnd is the length of the multimedia stream; this value is not accessible until the file is loaded completely. When DirectShow sends the ReadyStateChange event with a value of Complete, you can access the value of this property.

Run-time access: read/write. Design-time access: none.

Settings
Setting | Description
double | Numeric expression that specifies the position in the multimedia stream that represents the end of the playback sequence.

Data Type

double

See Also

SelectionStart

SelectionStart Property

Control Properties

Specifies the starting position in this multimedia stream, in seconds, relative to the stream's beginning.

[form.]object.SelectionStart [ = double ]

Remarks

The default value for SelectionStart is zero; this value is not accessible until the file is loaded completely. When DirectShow sends the ReadyStateChange event with a value of Complete, you can access the value of this property.

Run-time access: read/write. Design-time access: none.

Settings
Setting | Description
double | Numeric expression that specifies the position within the multimedia stream that represents the beginning of the playback sequence.

Data Type

double

See Also

SelectionEnd

ShowControls Property

Control Properties

Indicates whether or not the controls panel is visible.

[form.]object.ShowControls [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The controls panel is visible.
False | The controls panel is not visible.

Data Type

Boolean

See Also

ShowDisplay

ShowDisplay Property

Control Properties

Indicates whether or not the display panel is visible.

[form.]object.ShowDisplay [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The display panel is visible.
False | The display panel is not visible.

Data Type

Boolean

See Also

ShowControls

ShowPositionControls Property

Control Properties

Indicates whether or not the position controls are visible.

[form.]object.ShowPositionControls [ = { True | False } ]

Remarks

The position controls consist of four buttons: Previous, Rewind, Forward, and Next. Rewind and Forward move the media position rapidly backward and forward. If the current media position is after the position specified in SelectionStart, Previous sets the media position to the value of SelectionStart. If not, Previous sets the media position to the start of the data stream. If the current media position is before the position specified in SelectionStart, Next sets the media position to the value of SelectionStart. If not, Next sets the media position to the end of the data stream.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | The position controls are visible.
False | (Default) The position controls are not visible.

Data Type

Boolean

See Also

EnablePositionControls

ShowSelectionControls Property

Control Properties

Indicates whether or not the selection controls are visible.

[form.]object.ShowSelectionControls [ = { True | False } ]

Remarks

There are two selection buttons—Start Selection and End Selection. Start Selection sets the SelectionStart property to the current media position and End Selection sets the SelectionEnd property to the current media position. If you choose an invalid selection, such as an end time that is earlier than the start time, DirectShow automatically sets SelectionStart to the start of the data stream and SelectionEnd to the end.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | The selection controls are visible.
False | (Default) The selection controls are not visible.

Data Type

Boolean

See Also

EnableSelectionControls

ShowTracker Property

Control Properties

Indicates whether or not the trackbar is visible.

[form.]object.ShowTracker [ = { True | False } ]

Remarks

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
True | (Default) The trackbar is visible.
False | The trackbar is not visible.

Data Type

Boolean

See Also

EnableTracker

Volume Property

Control Properties

Specifies the volume, in hundredths of decibels.

[form.]object.Volume [ = long ]

Remarks

The value ranges from –10,000 to 0. The value 0 is full volume and –10,000 is no volume. Not all devices support 10,000 discrete steps of volume.

Run-time access: read/write. Design-time access: read/write.

Settings
Setting | Description
long | Numeric expression that specifies the audio volume, in hundredths of decibels. The default value is zero.

Data Type

Long

See Also

Balance Property

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


Control Methods

The ActiveMovie Control supports the following methods.
Method | Description
AboutBox | Displays version and copyright information about the ActiveMovie Control.
IsSoundCardEnabled | Determines whether the computer's sound card is enabled.
Pause | Suspends a play operation without changing the current position.
Run | Starts a multimedia stream from the specified starting position or continues playing a paused stream.
Stop | Stops playback and resets the position as indicated by the AutoRewind and SelectionStart properties.

The ActiveMovie Control also supports several methods that are common to other controls: Drag, Move, SetFocus, ShowWhatsThis, and ZOrder. For information about these methods, see documentation for Visual Basic.

AboutBox Method

Control Methods

Displays version and copyright information about the ActiveMovie Control.

object.AboutBox

IsSoundCardEnabled Method

Control Methods

Determines whether the computer's sound card is enabled.

object.IsSoundCardEnabled [ = { True | False } ]

Remarks

The IsSoundCardEnabled method determines whether the computer has one or more sound cards enabled.

Run-time access: read. Design-time access: read.

Settings
Setting | Description
True | Sound card is enabled.
False | No sound cards are enabled.

Data Type

Boolean

Pause Method

Control Methods

Suspends a play operation without changing the current position.

object.Pause

Remarks

The Pause method pauses the multimedia stream at the current position. To continue playing the multimedia stream, use the Run method.

To stop the multimedia stream, use the Stop method.

Run Method

Control Methods

Starts a multimedia stream from the specified starting position or continues playing a paused stream.

object.Run

Remarks

The Run method starts the multimedia stream at the starting position specified by the SelectionStart property. In the absence of other user or application input, the Run method continues playing the stream to the position specified by the SelectionEnd property.

The Run method is also used to resume playing a paused multimedia stream.

To pause playing, call the Pause method. To stop playing, call the Stop method.

Stop Method

Control Methods

Stops playback and resets the position as indicated by the AutoRewind and SelectionStart properties.

object.Stop

Remarks

The Stop method changes the CurrentState property.

When the Stop method halts a play operation, you can reset the current position to the starting point for the multimedia stream, as indicated by the SelectionStart property. The AutoRewind property determines whether the position is reset to this starting position.

To halt a play operation without changing the current position, use the Pause method.

See Also

Run Method

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


Control Events

The ActiveMovie Control supports the following events.
Event | Description
DisplayModeChange | Indicates changes to the DisplayMode property.
Error | Indicates that an error occurred.
OpenComplete | Specifies the state of readiness for this ActiveMovie Control, based on how completely the source file has loaded.
PositionChange | Indicates changes to the current media position, such as when the user selects (or seeks to) a new media position.
ReadyStateChange | Indicates changes to the control's state of readiness.
StateChange | Indicates player state changes.
Timer | Handles timer events.

The ActiveMovie Control also supports several events common to other controls: Click, DblClick, KeyDown, KeyPress, KeyUp, MouseDown, MouseMove, and MouseUp. For information about these events, see the event documentation for Visual Basic.

DisplayModeChange Event

Control Events

Indicates changes to the DisplayMode property, such as from full-screen to half.

Private Sub object_DisplayModeChange()

Remarks

The DisplayModeChange event is raised when the DisplayMode property changes. The current display mode appears in the DisplayMode property. State flags are listed under DisplayMode property.

Error Event

Control Events

Indicates that an error occurred.

Private Sub object_Error(ByVal SCode As Integer, ByVal Description As String, ByVal Source As String, CancelDisplay As Boolean)

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
SCode
Error code.
Description
String describing the error that occurred.
Source
String containing the ActiveMovie Control's name.
CancelDisplay
Value that the client can set to cancel the default error messages.
Remarks

The Error event is sent when DirectShow reports an error during playback. By default, the ActiveMovie Control displays a message box containing the description string. To avoid displaying this box, set the CancelDisplay parameter of the Error event to False.

OpenComplete Event

Control Events

Indicates the control finished opening the media file and is ready for playback.

Private Sub object_OpenComplete()

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
Remarks

This event is provided for backward compatibility; use the ReadyStateChange event instead.

PositionChange Event

Control Events

Indicates changes to the current media position, such as when the user selects (or seeks to) a new media position.

Private Sub object_PositionChange(ByVal oldPosition As Double, ByVal newPosition As Double)

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
oldPosition
Position before it changed, in seconds.
newPosition
Current position, in seconds, after the position change occurred.
Remarks

Changes made directly to the CurrentPosition property do not trigger this event.

ReadyStateChange Event

Control Events

Indicates changes to the control's state of readiness.

Private Sub object_ReadyStateChange(ByVal ReadyState As Long)

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
ReadyState
Current state of readiness, after the change occurred.
Remarks

When you change the FileName property, applications should check the control's state of readiness before attempting to call the Run method on the newly opened file. Applications should call the Run method only if the ReadyState parameter equals amvInteractive or amvComplete.

Settings

Following are possible settings for the ReadyState parameter.
Setting | Value | Description
amvUninitialized | 1 | The FileName property has not been initialized.
amvLoading | 0 | The ActiveMovie Control is asynchronously loading a file.
amvInteractive | 3 | The control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
amvComplete | 4 | All data has been downloaded.

StateChange Event

Control Events

Indicates that the player state changed, such as from running to stopped.

Private Sub object_StateChange(ByVal oldState As Long, ByVal newState As Long)

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
oldState
Previous state, before the change occurred.
newState
Current state, after the change occurred.
Remarks

The ActiveMovie Control raises the StateChange event when the player state changes, such as from stopped to running. The current player state appears in the CurrentState property. You can find the player state flags in the CurrentState property documentation.

Settings

Following are possible settings for the oldState or newState parameters.
Setting | Value | Description
amvStopped | 0 | The player is stopped.
amvPaused | 1 | The player is paused.
amvRunning | 2 | The player is playing the multimedia file.

Timer Event

Control Events

Provides the rate at which DirectShow refreshes the control panel's display.

Private Sub object_Timer( )

Parameters
object
Object expression that evaluates to an ActiveMovie Control.
Remarks

The Timer event is raised at the intervals specified by the control's timer.


Control Property Sheet

A property sheet is a dialog box with tabbed pages that you can use to set properties on a control. You can access the ActiveMovie Control Properties property sheet at either design or run time.

To activate a property page at design time, select the control, press F4, then click Custom in the Properties page. To activate a property page at run time, right-click, and then click Properties on the shortcut menu that appears. The following is a list of the tabs in the ActiveMovie Control Properties property sheet.

  • Playback
  • Movie Size
  • Controls
  • Advanced

Playback Tab

Use the controls on the Playback tab at run time to set options such as volume, rate of play, and the number of times you want the current video to play.

The Playback tab
Property | Description
Volume | Adjusts the control's volume. For information about how to set this property in code, see Volume.
Balance | Adjusts balance for the control.
Start Time | Identifies the start time for the current file.
Stop Time | Identifies the stop time for the current file. For information about how to set this property in code, see the AllowChangeDisplayMode property.
Play Count | Specifies the number of times to play the current file consecutively. For information about how to set this property in code, see the PlayCount property.
Auto Repeat | Causes the ActiveMovie Control to play the current file repeatedly. For information about how to set this property in code, see the AutoStart property.
Auto Rewind | Indicates whether to rewind the multimedia stream automatically and reposition at the beginning after playing stops. For information about how to set this property in code, see the AutoRewind property.

Movie Size Tab

Use the controls on the Movie Size tab at run time to specify the size of the window in which you want to play video.

The Movie Size tab
Property | Description
Movie Size | Use this option list to specify the movie's size. For information about how to set this property in code, see the MovieWindowSize property.
Run Full Screen | Select this option to maximize the ActiveMovie Control so that it fills the entire screen. For information about how to set this property in code, see the FullScreenMode property.

Controls Tab

Use the controls on the Controls tab at run time to specify which ActiveMovie controls you want to be visible.

The Controls tab
Property | Description
Display Panel | Select this check box if you want the display panel to be visible at run time. For information about how to set this property in code, see the ShowDisplay property.
Control Panel | Select this check box if you want the control panel to be visible at run time. For more information about how to set this property in code, see the ShowControls property.
Position Controls | Select this check box if you want the video stream position to be displayed at run time. For information about how to set this property in code, see the DisplayMode property.
Selection Controls | Select this check box to make the selection controls visible. For information about how to set this property in code, see the SelectionStart property.
Show Trackbar | Select this check box to toggle the visibility of the trackbar. For information about how to set this property in code, see the ShowTracker property.
Foreground Color | Use this control to show and set the foreground color of the ActiveMovie Control. For information about how to set this property in code, see the DisplayForeColor property.
Background Color | Use this control to show and set the background color of the ActiveMovie Control. For information about how to set this property in code, see the DisplayBackColor property.

Advanced Tab

Use the Advanced tab to run a filter on the currently playing video.

The Advanced tab
Property | Description
Filter Properties | Selects the filter property page to display when the Properties button is clicked.
Properties | Displays the property page of the filter selected in the Filter Properties list. Property pages allow you to change parameters on individual filters in the DirectShow filter graph. For more information about properties of DirectShow filters, see Filters in the DirectShow SDK documentation.


Control Shortcut Keys

You can use the following key combinations to activate ActiveMovie Control commands.
Key(s) | Result
CTRL+D | Toggle display
CTRL+LEFT ARROW | Rewind
CTRL+P | Pause
CTRL+R | Run
CTRL+RIGHT ARROW | Forward
CTRL+S | Stop
CTRL+SHIFT+LEFT ARROW | Previous
CTRL+SHIFT+RIGHT ARROW | Next
CTRL+T | Toggle control panel
ALT+ENTER | Toggle between full-screen and windowed modes
SHIFT+window resize | Stretches video to fill the control window


Visual Basic Objects

DirectShow interfaces on the filter graph manager are available to applications based on Microsoft® Visual Basic® version 5.x. A Visual Basic-based application can use these interfaces (called objects in Visual Basic) to build and control DirectShow filter graphs.

IAMCollection Object

IBasicAudio Object

IBasicVideo Object

IFilterInfo Object

IMediaControl Object

IMediaEvent Object

IMediaPosition Object

IMediaTypeInfo Object

IPinInfo Object

IRegFilterInfo Object

IVideoWindow Object


IAMCollection Object

The filter graph manager exposes the IAMCollection object, which allows access to object collections. These collections contain IPinInfo, IFilterInfo, or IMediaTypeInfo objects.

Properties
Name | Description
Count | Returns the number of items in the collection.

Methods
Name | Description
Item | Retrieves the specified member of the collection.

Count Property (IAMCollection Object)

IAMCollection Object

Returns the number of items in the collection.

objCollection.Count

Parts
objCollection
Object expression that evaluates to an IAMCollection object.

Item Method (IAMCollection Object)

IAMCollection Object

Retrieves the specified collection member and stores it in the passed-in object.

objCollection.Item lItem, objNew

Parts
objCollection
Object expression that evaluates to an IAMCollection object.
lItem
Index of the item to retrieve.
objNew
Object expression that can evaluate to an IFilterInfo, IPinInfo, or IMediaTypeInfo object depending on the collection type. This argument will contain the retrieved item.
Remarks

The index value ranges from 0 to (Count – 1).


IBasicAudio Object

The IBasicAudio object supports the audio component of the filter graph. It allows access to volume and balance functionality.

The Volume property is a value between –10,000 and 0 representing a set of linear steps. Not all devices support 10,000 distinguishable steps.

The Balance property is a value between –10,000 and 10,000. A value of –10,000 indicates that the right speaker has been disabled and only the left speaker is receiving an audio signal. A value of 0 indicates that both speakers are receiving equivalent audio signals. A value of 10,000 indicates that the left speaker has been disabled and only the right speaker is receiving an audio signal.

Properties
Name | Description
Balance | Sets or returns the balance for the audio signal.
Volume | Sets or returns the volume (amplitude) of the audio signal.

Balance Property (IBasicAudio Object)

IBasicAudio Object

Sets or returns the balance of the audio channel.

objAudio.Balance [= lValue ]

Parts
objAudio
Object expression that evaluates to an IBasicAudio object.
lValue
New value for the Balance property.
Remarks

The Balance property is a value between –10,000 and 10,000. A value of –10,000 indicates that the right speaker has been disabled and only the left speaker is receiving an audio signal. A value of 0 indicates that both speakers are receiving equivalent audio signals. A value of 10,000 indicates that the left speaker has been disabled and only the right speaker is receiving an audio signal.

Note that not all devices support 10,000 distinguishable steps.

If you try to set the Balance property to values outside this range, the IBasicAudio object raises run-time error 5.

Volume Property (IBasicAudio Object)

IBasicAudio Object

Sets or returns the volume of the audio channel.

objAudio.Volume [= lValue]

Parts
objAudio
Object expression that evaluates to an IBasicAudio object.
lValue
New value for the Volume property.
Remarks

The allowable input range is –10,000 to 0.

Full volume is 0; –10,000 is silence. The scale is linear. Values outside this range will return run-time error 5.

Note that not all devices support 10,000 distinguishable steps.


IBasicVideo Object

The filter graph manager exposes the IBasicVideo object, which supports the video properties of a generic video window. Generally, this is a video renderer that draws video into a window on the display.

The video renderer must be connected to use IBasicVideo object methods. If it isn't connected, all methods return run-time error 521. Properties set on a video renderer generally persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

When working with video, the application can select a portion of the video to use. This portion is the source rectangle that the IBasicVideo object controls. IBasicVideo allows the source rectangle to be set and retrieved. All IBasicVideo rectangles have top, left, width, and height properties. When no source rectangle has been set, the properties of the source rectangle return the full, native video size.

Properties
Name | Description
AvgTimePerFrame | Retrieves the average time between successive frames in 100-nanosecond units.
BitErrorRate | Retrieves an approximate bit error rate for the video stream.
BitRate | Retrieves an approximate bit rate for the video stream.
DestinationLeft | Sets or retrieves the x-axis coordinate for the destination video rectangle.
DestinationHeight | Sets or retrieves the height of the destination video rectangle.
DestinationTop | Sets or retrieves the y-axis coordinate for the destination video rectangle.
DestinationWidth | Sets or retrieves the width of the destination video rectangle.
SourceHeight | Sets or retrieves the height of the source video rectangle.
SourceLeft | Sets or retrieves the x-axis coordinate for the source video rectangle.
SourceTop | Sets or retrieves the y-axis coordinate for the source video rectangle.
SourceWidth | Sets or retrieves the width of the source video rectangle.
VideoHeight | Retrieves the current video height.
VideoWidth | Retrieves the current video width.

Methods
Name | Description
GetCurrentImage | Returns a copy of the image that is currently waiting at the renderer.
GetDestinationPosition | Retrieves the destination rectangle for the window.
GetSourcePosition | Retrieves the source video rectangle.
GetVideoPaletteEntries | Retrieves the color palette entries required by the video.
GetVideoSize | Retrieves the native video dimensions.
IsUsingDefaultSource | Indicates whether the default source is being used.
SetDefaultDestinationPosition | Sets the default destination position for the window.
SetDefaultSourcePosition | Informs the renderer to use the default source rectangle.
SetDestinationPosition | Sets the destination rectangle for the window.
SetSourcePosition | Sets the source video rectangle.

AvgTimePerFrame Property (IBasicVideo Object)

IBasicVideo Object

Retrieves the average time between successive frames in 100-nanosecond units.

objVideo.AvgTimePerFrame

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.

BitErrorRate Property (IBasicVideo Object)

IBasicVideo Object

Retrieves a bit error rate for the video stream (one error for approximately this many bits).

objVideo.BitErrorRate

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.

BitRate Property (IBasicVideo Object)

IBasicVideo Object

Retrieves an approximate bit rate for the video stream (in bits per second).

objVideo.BitRate

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.

DestinationHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the height of the destination rectangle.

objVideo.DestinationHeight [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value for the destination rectangle height.
Remarks

Setting this coordinate does not affect the destination rectangle y-axis origin.

DestinationLeft Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the destination x-axis origin coordinate.

objVideo.DestinationLeft [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value of the destination x-axis origin.
Remarks

Setting this coordinate does not affect the destination rectangle width.

DestinationTop Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the destination y-axis origin coordinate.

objVideo.DestinationTop [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value of the y-axis origin.
Remarks

Setting this coordinate does not affect the destination rectangle height.

DestinationWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the width of the destination rectangle.

objVideo.DestinationWidth [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New width value.
Remarks

Setting this coordinate does not affect the destination rectangle x-axis origin.

GetCurrentImage Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the image currently waiting at the renderer.

objVideo.GetCurrentImage BufferSize, DIBImage

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
BufferSize
Long value that specifies the size of the buffer the caller is passing in. GetCurrentImage sets this value to the actual number of bytes in the buffer before exiting.
DIBImage
Long value that will contain the buffer where the complete image will be stored in device-independent bitmap (DIB) format. You must pass the buffer by reference.
Remarks

Pause the video renderer before calling this method; calling this method in any other state returns run-time error 549. Depending on what data the source filter has available, the video renderer is not guaranteed to service this request.

An application can use this method to get a copy of the current image the video renderer holds when paused by calling the method with DIBImage set to Nothing.

GetDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the position of the destination rectangle in window coordinates.

objVideo.GetDestinationPosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long integer value that will contain the destination window's x-axis origin.
Top
Long integer value that will contain the destination window's y-axis origin.
Width
Long integer value that will contain the destination window's width.
Height
Long integer value that will contain the destination window's height.
Remarks

This method has the same effect as individually retrieving the DestinationLeft, DestinationTop, DestinationWidth, and DestinationHeight properties.

GetSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the source position that is clipped to the available video.

objVideo.GetSourcePosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long integer value that will contain the source window's x-axis origin.
Top
Long integer value that will contain the source window's y-axis origin.
Width
Long integer value that will contain the source window's width.
Height
Long integer value that will contain the source window's height.
Remarks

This method has the same effect as retrieving the values of the SourceLeft, SourceTop, SourceWidth, and SourceHeight properties.

GetVideoPaletteEntries Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the palette colors for the video.

objVideo.GetVideoPaletteEntries StartIndex, Entries, Retrieved, Palette

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
StartIndex
Long integer value that specifies the start index for the palette.
Entries
Long integer value that specifies the number of palette entries required.
Retrieved
Long integer value that will contain the number of entries actually returned in Palette.
Palette
Long integer value that will contain a pointer to an array of Microsoft® Win32® PALETTEENTRY structures.

GetVideoSize Method (IBasicVideo Object)

IBasicVideo Object

Retrieves the native video dimensions.

objVideo.GetVideoSize Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Width
Long integer value that will contain the video window's width.
Height
Long integer value that will contain the video window's height.
Remarks

Retrieves the native video width and height, disregarding any source rectangle that might have been set. ActiveX™ Controls or other applications can use this information to negotiate space in compound documents.

IsUsingDefaultSource Method (IBasicVideo Object)

IBasicVideo Object

Retrieves whether or not this object is using the default source.

objVideo.IsUsingDefaultSource

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Return Values

True indicates that the IBasicVideo object is using the default source; False indicates that it is not.

SetDefaultDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

Sets the default destination position of the video window so that the renderer uses the entire window for playback.

objVideo.SetDefaultDestinationPosition

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.

SetDefaultSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

Informs the renderer to use the default source rectangle.

objVideo.SetDefaultSourcePosition

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.

SetDestinationPosition Method (IBasicVideo Object)

IBasicVideo Object

Sets the destination rectangle in window coordinates.

objVideo.SetDestinationPosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long value specifying the x-axis origin of the destination window, in pixels.
Top
Long value specifying the y-axis origin of the destination window, in pixels.
Width
Long value specifying the width of the destination window, in pixels.
Height
Long value specifying the height of the destination window, in pixels.
Remarks

This method has the same effect as setting the DestinationLeft, DestinationTop, DestinationWidth, and DestinationHeight properties individually.

SetSourcePosition Method (IBasicVideo Object)

IBasicVideo Object

Sets the source rectangle and is clipped against the available video.

objVideo.SetSourcePosition Left, Top, Width, Height

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Left
Long value specifying the x-axis origin of the source window.
Top
Long value specifying the y-axis origin of the source window.
Width
Long value specifying the width of the source window.
Height
Long value specifying the height of the source window.
Remarks

This method has the same effect as setting the SourceLeft, SourceTop, SourceWidth, and SourceHeight properties individually.

SourceHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the height of the source rectangle.

objVideo.SourceHeight [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the current rectangle height, in pixels.
Remarks

Setting the height of the source rectangle has no effect on the width and other source values.

SourceLeft Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle's x-coordinate.

objVideo.SourceLeft [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
New value for the x-axis origin of the source rectangle.
Remarks

Changes to this property do not affect the width and other source values.

SourceTop Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle y-axis origin coordinate.

objVideo.SourceTop [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the distance from the top of the display to the top of the current window, in pixels.
Remarks

Setting this method has no effect on the source rectangle height.

SourceWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves or sets the source rectangle width.

objVideo.SourceWidth [= lValue]

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
lValue
Long value specifying the current width, in pixels.
Remarks

This method has no effect on the source rectangle x-axis coordinate.

VideoHeight Property (IBasicVideo Object)

IBasicVideo Object

Retrieves the native height of the video.

objVideo.VideoHeight

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Remarks

This method returns the actual height of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native vertical dimension. It can be used by applications to negotiate size requirements with in-place container documents.

VideoWidth Property (IBasicVideo Object)

IBasicVideo Object

Retrieves the native width of the video.

objVideo.VideoWidth

Parts
objVideo
Object expression that evaluates to an IBasicVideo object.
Remarks

This method returns the actual width of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native horizontal dimension. It can be used by applications to negotiate size requirements with in-place container documents.


IFilterInfo Object

IFilterInfo is an object that manages information about a filter and allows access to the filter object and IPinInfo object.

Properties
Name | Description
Filename | Retrieves or sets the file name associated with the source filter.
Filter | Retrieves the actual filter object.
IsFileSource | Indicates whether the filter is a file source filter.
Name | Retrieves the filter name.
Pins | Retrieves an IAMCollection object containing the IPinInfo objects for this filter.
VendorInfo | Retrieves a string containing optional information supplied by a vendor about the specified filter.

Methods
Name | Description
FindPin | Locates a pin, given an identifier, and returns an object supporting IPinInfo.

Filename Property (IFilterInfo Object)

IFilterInfo Object

Retrieves or sets the name of the file containing the filter.

objFilterInfo.Filename [= string]

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
string
String expression that specifies the new file name.

Filter Property (IFilterInfo Object)

IFilterInfo Object

Retrieves the filter object.

Set objFilter = objFilterInfo.Filter

Parts
objFilter
Object expression that evaluates to an IBaseFilter object.
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
Remarks

No programmable object interface is offered for the IBaseFilter interface. However, Visual Basic® programmers can use the returned object as a parameter in calls to functions that take an IBaseFilter interface pointer as a parameter.

FindPin Method (IFilterInfo Object)

IFilterInfo Object

Locates a pin, given an identifier, and returns an IPinInfo object.

objFilterInfo.FindPin string, objPin

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
string
String that contains the name of the pin to find.
objPin
IPinInfo object that will contain the specified pin, if the pin exists.
Remarks

No programmable object interface is offered for the IPin interface. However, Visual Basic programmers can use the returned object as a parameter in calls to functions that take the IPin interface pointer as a parameter.

IsFileSource Property (IFilterInfo Object)

IFilterInfo Object

Determines if the file contains the source video.

objFilterInfo.IsFileSource

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
Return Values

The value True indicates that the file contains the source video. False indicates that the file does not contain the source video.

Name Property (IFilterInfo Object)

IFilterInfo Object

Retrieves the filter name.

objFilterInfo.Name

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
Remarks

The vendor specifies the filter name.

Pins Property (IFilterInfo Object)

IFilterInfo Object

Retrieves an IAMCollection object containing the IPinInfo objects for this filter.

Set objPinCollection = objFilterInfo.Pins

Parts
objPinCollection
IAMCollection object that will contain the specific filter's pins.
objFilterInfo
IFilterInfo object that specifies the filter whose pins you want to retrieve.
Remarks

You can use the Count property and Item method to iterate through each of the pin objects in the collection.

VendorInfo Property (IFilterInfo Object)

IFilterInfo Object

Retrieves a string containing optional information supplied by a vendor about the specified filter.

objFilterInfo.VendorInfo

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
Remarks

This property contains any information the vendor chooses to supply. It is usually descriptive information about the filter.


IMediaControl Object

The filter graph exposes the IMediaControl object to allow applications to control the streaming of media through the filters in the graph. The interface provides methods for running, pausing, and stopping the streaming of data. It also provides applications with a simple method that builds graphs to play back media files.

Properties
Name | Description
FilterCollection | Retrieves a collection of IFilterInfo objects representing the current filters in the graph.
RegFilterCollection | Retrieves a collection of IRegFilterInfo objects representing the filters available in the registry.

Methods
Name | Description
AddSourceFilter | Adds to the graph the source filter that can read the given file name.
GetState | Retrieves the state of the filter graph.
Pause | Pauses all filters in the filter graph.
RenderFile | Adds and connects all filters needed to play the specified file.
Run | Switches the entire filter graph into run mode.
Stop | Switches all filters in the filter graph to a stopped state.

AddSourceFilter Method (IMediaControl Object)

IMediaControl Object

Adds the source filter that can read the given file name to the graph and returns the created IFilterInfo object.

objMediaControl.AddSourceFilter string, objFilterInfo

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
string
Name of the file containing the source media.
objFilterInfo
IFilterInfo object; the source filter created for the specified source file.

FilterCollection Property (IMediaControl Object)

IMediaControl Object

Retrieves a collection of IFilterInfo objects representing the filters in the graph. Returns an IAMCollection object.

Set objCollection = objMediaControl.FilterCollection

Parts
objCollection
IAMCollection object that represents the collection of filters currently present in the filter graph.
objMediaControl
Object expression that evaluates to an IMediaControl object.

GetState Method (IMediaControl Object)

IMediaControl Object

Returns a Long integer indicating the current state value.

objMediaControl.GetState msTimeout, State

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
msTimeout
Duration of the time-out, in milliseconds.
State
Long value that will contain the current state. This argument will be one of the following:
Value | Description
State_Paused | The media source is paused.
State_Running | The media source is running.
State_Stopped | The media source is stopped.
Return Values

Returns run-time error 567 if the state transition is not complete, or 0 if it completed successfully.

Remarks

Not all state transitions are synchronous. For example, even though the Pause method returns immediately, the graph typically does not complete the transition into paused mode until data is ready at the renderer. This method will not return zero until the state transition has been completed.

If you specify a nonzero time-out, the method waits up to that number of milliseconds for the graph to leave the intermediate state. If the time-out expires before the state transition is complete, the return code will be 567, and the returned state will be the state into which the graph is transitioning (either State_Stopped, State_Paused, or State_Running).

RegFilterCollection Property (IMediaControl Object)

IMediaControl Object

Retrieves a collection of IRegFilterInfo objects representing the filters available in the registry.

Set objCollection = objMediaControl.RegFilterCollection

Parts
objCollection
IAMCollection object that contains IRegFilterInfo objects.
objMediaControl
Object expression that evaluates to an IMediaControl object.
Return Values

Returns an IAMCollection object.

Pause Method (IMediaControl Object)

IMediaControl Object

Pauses all the filters in the filter graph.

objMediaControl.Pause

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
Remarks

In the paused state, filters process data but do not render it. Data is pushed down the filter graph and is processed by transform filters as far as buffering permits. No data is rendered (except that media types capable of being rendered statically, such as video, have a static, poster frame rendered in paused mode). Therefore, putting a filter graph into a paused state cues the graph for immediate rendering when put into a running state.

RenderFile Method (IMediaControl Object)

IMediaControl Object

Adds and connects filters needed to play the specified file.

objMediaControl.RenderFile string

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
string
Name of the file to render.
Remarks

This method allows an application to pass the name of a media file that it wants rendered to the filter graph manager. The filter graph manager will build a graph of the filters that are needed to play back this file.

Run Method (IMediaControl Object)

IMediaControl Object

Switches the entire filter graph into a running state.

objMediaControl.Run

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
Remarks

If the filter graph is in the stopped state, this method first pauses the graph before running.

If an error value is returned, some filters within the graph might have successfully entered the running state. In a multistream graph, entire streams might be playing successfully. The application must determine whether to stop execution or not.

Stop Method (IMediaControl Object)

IMediaControl Object

Switches all filters in the filter graph to a stopped state.

objMediaControl.Stop

Parts
objMediaControl
Object expression that evaluates to an IMediaControl object.
Remarks

In this mode, filters release resources and no data is processed. If the filters are in a running state, this method pauses them before stopping them. This allows video renderers to make a copy of the current frame for poster frame display while stopped.


IMediaEvent Object

This object supports event notification from the filter graph and the filters within it to the application.

An event code and two parameters represent event notification information. This can be used for typical completion of asynchronous operations, errors that occur during asynchronous operation, or user-initiated events, such as when a user clicks a hot spot.

Filters within the filter graph and the filter graph itself raise event notifications. Possible events include playback completion or asynchronous playback errors. In addition, the filter graph provides a method to generate events at specific reference clock times.

Event notifications are placed in a queue. An application calls the IMediaEvent object's GetEvent method to retrieve the next notification from the queue. This method blocks until there is an event to return. The GetEvent method's time-out parameter allows the application to specify the time, in milliseconds, to wait for an event, including values of zero (do not wait) and infinite (wait forever).

In addition, applications can retrieve the event handle. GetEventHandle returns a handle to a manual-reset event created by the Microsoft® Win32® CreateEvent function. This event is in a signaled state as long as there are event notifications to collect. The event is cleared by the GetEvent method when there are no more event notifications to collect. This allows an application to use an application programming interface (API), such as MsgWaitForMultipleObjects, to wait for events and other occurrences at the same time. This event handle will be closed when the filter graph is released; therefore, applications should ensure that they are not using it after this point.

The filter graph handles some events raised by filters that are not passed to the application. One example of this is the EC_REPAINT event notification. The default handling for this event is to repaint the video renderer's static images by pausing the filter graph. An application can override default handling for a specific event by calling the CancelDefaultHandling method with the event value as a parameter. The RestoreDefaultHandling method reinstates default handling for the specified event value. These methods have no effect on events that have no default handling.

If an error occurs during the transition to a running state on any filter, an error value is returned by the Run method. In this case, some filters within the graph might be running successfully. The filter graph leaves it up to the application to determine whether to stop the graph in case of an error. After the Run method has returned, event notifications report any additional errors. The EC_ERRORABORT and EC_USERABORT event notifications indicate that playback has probably stopped in the graph (certainly in the filter that reported it). Other errors and events indicate that it is still running. Note, however, that in all cases the graph remains in running mode until the application explicitly changes it to stopped or paused mode.

If the streams in the filter graph detect the end of the stream, the streams report this by using the EC_COMPLETE event notification. The filter graph asks filters if they can report EC_COMPLETE via seekable renderers.

A seekable renderer is a renderer that supports the IMediaPosition object from the filter and has only input pins, or is a renderer whose input pins report that they are rendered at that point. The filter graph detects seekable renderers. A seekable renderer reports EC_COMPLETE once when all seekable streams on that filter have reached the end of the stream.

The filter graph manager will then not pass EC_COMPLETE to the application until an EC_COMPLETE event notification has been received from each stream. For example, if a live camera stream is playing as the background to a video playing out of a file, the application will be notified about EC_COMPLETE when the video and audio streams from the file have come to the end of the stream, even though the live source is still playing. In this case, too, the filter graph remains in running mode until the application explicitly calls the Pause or Stop method.

The aggregation of EC_COMPLETE messages can be disabled by calling CancelDefaultHandling with EC_COMPLETE as the parameter. In this case, all EC_COMPLETE events raised by the filters will be passed directly to the application.

For a list of system-defined event notifications, see the GetEvent method.

Methods
Name | Description
CancelDefaultHandling | Cancels any default handling of the specified event by the filter graph.
GetEvent | Retrieves the next notification event.
GetEventHandle | Retrieves a handle to a manual-reset event that will be signaled.
RestoreDefaultHandling | Restores default handling for this event.
WaitForCompletion | Waits until the filter graph's operation has completed.

CancelDefaultHandling Method (IMediaEvent Object)

IMediaEvent Object

Cancels default handling of the specified event by the filter graph and ensures that the event is passed to the application.

objMediaEvent.CancelDefaultHandling lEvCode

Parts
objMediaEvent
Object expression that evaluates to an IMediaEvent object.
lEvCode
Long value specifying the event code which cancels default handling. The following values are valid.
EC_COMPLETE
EC_ERRORABORT
EC_PALETTE_CHANGED
EC_REPAINT
EC_USERABORT
Return Values

This method raises an error if the event does not have any default handling.

Remarks

Currently the filter graph manager only applies default handling to EC_COMPLETE and EC_REPAINT.

GetEvent Method (IMediaEvent Object)

IMediaEvent Object

Retrieves the next notification event.

objMediaEvent.GetEvent lEventCode, lParam1, lParam2, msTimeout

Parts
objMediaEvent
Object expression that evaluates to an IMediaEvent object.
IEventCode
Returns the next event notification. The following values are valid.
EC_COMPLETE
EC_ERRORABORT
EC_PALETTE_CHANGED
EC_REPAINT
EC_USERABORT
lParam1
Long value specifying the first parameter of the event.
lParam2
Long value specifying the second parameter of the event.
msTimeout
Time, in milliseconds, to wait before assuming that there are no events. To return immediately, specify a time-out value of 0.
Remarks

This method removes the next event notification from the head of the queue and returns it. It waits up to msTimeout milliseconds if there are no events.

GetEventHandle Method (IMediaEvent Object)

IMediaEvent Object

Returns a handle to a manual-reset event that will be signaled as Long as there are event notifications to deliver.

objMediaEvent.GetEventHandle hEvent

Parts
objMediaEvent
Object expression that evaluates to an IMediaEvent object.
hEvent
Long value that will contain the event handle.
Remarks

The event can be passed to the Win32 WaitForMultipleObjects or MsgWaitForMultipleObjects function to wait for event notifications at the same time as other messages and events on a single thread.

RestoreDefaultHandling Method (IMediaEvent Object)

IMediaEvent Object

Reinstates the normal default handling by a filter graph for the specified event if there is one.

objMediaEvent.RestoreDefaultHandling lEvCode

Parts
objMediaEvent
Object expression that evaluates to an IMediaEvent object.
lEvCode
Event to restore. The following list contains system-defined event notifications.
EC_COMPLETE
EC_ERRORABORT
EC_PALETTE_CHANGED
EC_REPAINT
EC_USERABORT
Remarks

Events that have default handling in place, such as EC_REPAINT, are not typically passed to the application.

WaitForCompletion Method (IMediaEvent Object)

IMediaEvent Object

Waits until the filter graph's operation has completed.

objMediaEvent.WaitForCompletion msTimeout, EvCode

Parts
objMediaEvent
Object expression that evaluates to an IMediaEvent object.
msTimeout
Long value that specifies the duration of the time-out, in milliseconds. To block indefinitely, pass –1. To return immediately, pass zero.
EvCode
Long value that will contain the value of the event completion code, such as EC_COMPLETE. A value of zero indicates that the operation has not completed.
Remarks

This method performs the equivalent of blocking by calling GetEvent repeatedly until the method receives the EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT event notification, or until it reaches the time-out period, whichever comes first.

If the time-out value is reached, the method returns a completion code value of 0 and raises run-time error 287, "Application-defined or object-defined error." When setting the msTimeOut parameter to anything other than –1 (infinite), you are likely to get this run-time error. You can handle this error with an On Error Resume Next statement and then check the value of EvCode, which will be 0 if a time-out has occurred or 1 (EC_COMPLETE) or greater if completion has occurred. The following example illustrates using this method with a time-out of 0.

    Dim pME As IMediaEvent
    Dim EventCode As Long
    Set pME = pMC

    On Error Resume Next

    pME.WaitForCompletion 0, EventCode	'Return from WaitForCompletion immediately

    Set pME = Nothing

    If EventCode = 0 Then Exit Sub

To use an infinite time-out, check for a returned event code of 1 as in the following example.

    Dim pME As IMediaEvent
    Dim EventCode As Long
    Set pME = pMC

    pME.WaitForCompletion -1, EventCode	'Wait until EC_COMPLETE

    If EventCode = 1 Then Exit Sub

When the method returns, the filter graph is still in a running state. This method assumes that the application is not making separate calls to the IMediaEvent object. This method fails if the graph is not in or transitioning into a running state.


IMediaPosition Object

The filter graph exposes the IMediaPosition object if any of the filters within the graph are seekable (can seek to an arbitrary position in the stream). Filters will expose IMediaPosition if they can seek their data or if they connect to an output pin that represents a seekable stream.

Applications that communicate with the filter graph can call methods on this interface to set or retrieve properties such as the stream's duration, the start and stop times, the preroll time, the rate, and the current position. The filter graph uses these properties on seekable filters to control the playback of streams within the graph; where there are multiple streams, the filter graph sets them all to play in parallel, beginning at the same position, and will report the duration as being the duration of the longest stream. The parameters used in this interface are double values representing a fractional number of seconds. Internally, filters will store time to an accuracy of 100 nanoseconds.

Properties
Name | Description
CurrentPosition | Retrieves or sets the current position in terms of the total length of the media stream.
Duration | Retrieves the total duration of the media stream.
PrerollTime | Retrieves or sets the time prior to the start position at which nonrandom access devices should start rolling.
Rate | Retrieves or sets the playback rate, relative to normal playback of the media stream.
StopTime | Retrieves or sets the position within the media stream at which playback should stop.

Methods
Name | Description
CanSeekBackward | Retrieves whether or not you can seek backward in the current stream.
CanSeekForward | Retrieves whether or not you can seek forward in the current stream.

CurrentPosition Property (IMediaPosition Object)

IMediaPosition Object

Retrieves or sets the current position in terms of the total length of the media stream.

objMediaPosition.CurrentPosition [=dblValue]

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
dblValue
Double value specifying the new current position.
Remarks

The CurrentPosition property represents the position that playback has reached. It is a value between zero and the duration (that is, it has been adjusted for rate and start time). If the graph is paused, this is the position at which it will restart.

This property can also be used to set the start time. When used in this way, the current position indicates a position between zero and the duration of the media at which playback should begin when the Run method is called.

When the filter graph is stopped or paused, this property returns the position at which playback will recommence. When the filter graph is running, the filter graph manager returns the position according to the reference clock. If an individual filter implements this, it should return the stream time of the sample it is currently processing (that is, the offset time from the beginning) when paused or running.

After stopping or pausing, a run command causes playback to begin at the current position. This will be where playback stopped or paused, unless the application changes the CurrentPosition call in the meantime.

If this method is called when the filter graph manager is running, the filter graph manager will pause the graph, run the method, and then issue a new run command.

Setting the current position when paused or stopped causes playback to resume from the new start position when the run command is issued.

The current position is applied before the rate and therefore is the position at typical playback speed.

Duration Property (IMediaPosition Object)

IMediaPosition Object

Retrieves the total duration of the media stream.

objMediaPosition.Duration

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate.

PrerollTime Property (IMediaPosition Object)

IMediaPosition Object

Retrieves or sets the time prior to the start position that devices should start rolling.

objMediaPosition.PrerollTime [=dblValue]

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
dblValue
Double value for the PrerollTime property.
Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

Rate Property (IMediaPosition Object)

IMediaPosition Object

Retrieves or sets the playback rate relative to normal playback speed.

objMediaPosition.Rate [= dblValue]

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
dblValue
New value for the rate. Double.
Remarks

This property allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop samples. A rate of 0.5 indicates half speed.

StopTime Property (IMediaPosition Object)

IMediaPosition Object

Retrieves or sets the time at which the media stream stops.

objMediaPosition.StopTime [ = dblValue]

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
dblValue
New value for the stop time.
Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

CanSeekBackward Method (IMediaPosition Object)

IMediaPosition Object

Retrieves whether or not you can seek backward through the current stream.

objMediaPosition.CanSeekBackward

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
Remarks

The return value is of type If the value is 0, you cannot seek through the current stream. If the value is –1, you can seek. If you cannot seek through the stream, you can still set the stream's current position with CurrentPosition.

This method can return only –1 (True) with media streams that consist of a single media type, such as a WAV file or video-only MPEG file.

CanSeekForward Method (IMediaPosition Object)

IMediaPosition Object

Retrieves whether or not you can seek forward through the current stream.

objMediaPosition.CanSeekForward

Parts
objMediaPosition
Object expression that evaluates to an IMediaPosition object.
Remarks

The return value is of type If the value is 0, you cannot seek through the current stream. If the value is –1, you can seek. If you cannot seek through the stream, you can still set the stream's current position with CurrentPosition.

This method can return only –1 (True) with media streams that consist of a single media type, such as a WAV file or video-only MPEG file.


IMediaTypeInfo Object

The filter graph manager exposes IMediaTypeInfo, which allows access to media type information such as the major GUIDs (globally unique identifiers).

Properties
Name | Description
Subtype | Retrieves the subtype GUID as a string.
Type | Retrieves the major type GUID as a string.

Subtype Property (IMediaTypeInfo Object)

IMediaTypeInfo Object

Retrieves the subtype GUID as a string.

objMediaTypeInfo.Subtype

Parts
objMediaTypeInfo
Object expression that evaluates to an IMediaTypeInfo object.
Return Values

Returns a string that contains the subtype GUID.

Type Property (IMediaTypeInfo Object)

IMediaTypeInfo Object

Retrieves the major type GUID as a string.

objMediaTypeInfo.Type

Parts
objMediaTypeInfo
Object expression that evaluates to an IMediaTypeInfo object.
Return Values

Returns a string containing the major type GUID.


IPinInfo Object

The filter graph manager exposes the IPinInfo object, which allows access to pin information such as the media type and the pin direction. It also allows control of pins, such as connecting, disconnecting, and rendering.

Properties
Name | Description
ConnectedTo | Retrieves the IPinInfo object for the pin to which the filter is connected.
ConnectionMediaType | Retrieves the media type on this connection.
Direction | Retrieves the pin direction.
FilterInfo | Retrieves the IFilterInfo object for the filter to which this pin belongs.
MediaTypes | Retrieves the IAMCollection object of preferred media types.
Name | Retrieves the name of this pin.
Pin | Retrieves the pin associated with this IPinInfo object.
PinID | Retrieves the pin identifier.

Methods
Name | Description
Connect | Connects to the following pin.
ConnectDirect | Connects directly to the specified pin.
ConnectWithType | Connects directly to the specified pin using the specified media type only.
Disconnect | Disconnects this pin and the corresponding connected pin from each other.
Render | Completes the filter graph downstream from this pin; that is, generates all filters and connections needed to generate a graph from this pin to the renderer filter.

Connect Method (IPinInfo Object)

IPinInfo Object

Connects two pins, using transform filters as necessary.

objPinInfo.Connect objPin

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
objPin
IPinInfo object specifying the other pin in the connection.

ConnectDirect Method (IPinInfo Object)

IPinInfo Object

Connects the two pins directly, without using transform filters.

objPinInfo.ConnectDirect objPin

Parts
objPinInfo
IPinInfo object specifying the other pin in the connection.
objPin
IPinInfo object specifying the other pin in the connection.

ConnectedTo Property (IPinInfo Object)

IPinInfo Object

Retrieves the IPinInfo object for the pin to which the filter is connected.

Set objConnectedPinInfo = objPinInfo.ConnectedTo

Parts
objConnectedPinInfo
IPinInfo object for the pin.
objPinInfo
Object expression that evaluates to an IPinInfo object.

ConnectionMediaType Property (IPinInfo Object)

IPinInfo Object

Retrieves the IMediaTypeInfo object for this connection.

Set objMediaTypeInfo = objPinInfo.ConnectionMediaType

Parts
objMediaTypeInfo
IMediaTypeInfo object that will contain the new media type.
objPinInfo
IPinInfo object specifying the source pin; the objMediaTypeInfo object copies this pin's media type.
Remarks

The IMediaTypeInfo object contains information about the major type and subtype that this pin supports.

ConnectWithType Method (IPinInfo Object)

IPinInfo Object

Connects directly to the specified pin using the specified media type.

objPinInfo.ConnectWithType objPin, objMediaType

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
objPin
IPinInfo object specifying the other pin in the connection.
objMediaType
Value specifying the media type used in the connection. The objMediaType object must support IPinInfo.
Remarks

The Connect and ConnectDirect methods can also be used to connect pins.

Direction Property (IPinInfo Object)

IPinInfo Object

Retrieves the pin direction.

objPinInfo.Direction

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

The value 0 indicates input, and the value 1 indicates output.

Disconnect Method (IPinInfo Object)

IPinInfo Object

Disconnects this pin and the corresponding connected pin from each other.

objPinInfo.Disconnect

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

Each pin has its own connection to the other. This method disconnects both pins.

FilterInfo Property (IPinInfo Object)

IPinInfo Object

Retrieves the IFilterInfo object for the filter that contains the current pin.

Set objFilterInfo = objPinInfo.FilterInfo

Parts
objFilterInfo
Object expression that evaluates to an IFilterInfo object.
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

For more information, see the reference entry for IFilterInfo.

MediaTypes Property (IPinInfo Object)

IPinInfo Object

Retrieves the IAMCollection object that specifies the preferred media types for the current pin.

Set objCollection = objPinInfo.MediaTypes

Parts
objCollection
IAMCollection object that is returned.
objPinInfo
Object expression that evaluates to an IPinInfo object.

Name Property (IPinInfo Object)

IPinInfo Object

Retrieves the name of this pin.

objPinInfo.Name

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.

Pin Property (IPinInfo Object)

IPinInfo Object

Returns the IPin object.

Set objPin = objPinInfo.Pin

Parts
objPin
IPinInfo object that will contain the retrieved pin.
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

No IPin programmable object interface is offered for Visual Basic® programmers. This property is provided for use with DLLs that take an IPin parameter, and for use as a parameter in calls to the IPinInfo object's Connect, ConnectDirect, and ConnectWithType methods.

PinID Property (IPinInfo Object)

IPinInfo Object

Retrieves the pin identifier.

objPinInfo.PinID

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

You can pass the PinID as a parameter to the FindPin method of the IFilterInfo object.

Render Method (IPinInfo Object)

IPinInfo Object

Builds a filter graph capable of rendering the media type belonging to this source filter output pin, adding all transform and rendering filters and establishing all connections that are needed.

objPinInfo.Render

Parts
objPinInfo
Object expression that evaluates to an IPinInfo object.
Remarks

This method establishes only those connections that are needed downstream from the specified pin; that is, in the direction of the renderer filter. It differs from the RenderFile method, which establishes a complete filter graph for all pins.


IRegFilterInfo Object

The IRegFilterInfo object provides information about filters registered on this computer.

Properties
Name | Description
Name | Retrieves the name of the filter.

Methods
Name | Description
Filter | Creates an instance of this filter, adds it to the graph, and returns an IFilterInfo object for the newly added filter.

Filter Method (IRegFilterInfo Object)

IRegFilterInfo Object

Creates an instance of this filter and adds it to the graph.

objRegFilterInfo.Filter objFilterInfo

Parts
objRegFilterInfo
Object expression that evaluates to an IRegFilterInfo object.
objFilterInfo
IFilterInfo object specifying the filter to add.

Name Property (IRegFilterInfo Object)

IRegFilterInfo Object

Retrieves the name of the filter.

objRegFilterInfo.Name

Parts
objRegFilterInfo
Object expression that evaluates to an IRegFilterInfo object.
Return Values

Returns the name of the registered filter object.

Remarks

The vendor specifies the filter name.


IVideoWindow Object

The IVideoWindow object supports the video window properties of a video renderer. It is a dual interface, accessible through Visual Basic® and Visual C++®, that controls a generic video window. Generally, this is a video renderer that draws video into a window on the display.

The IVideoWindow object supports both properties and methods. When operations require several properties to be changed simultaneously; methods are provided that allow a number of related properties to be changed simultaneously. For example, setting the position and size of the window can be done by four individual property calls or by the single method SetWindowPosition.

The video renderer must be connected to use the IVideoWindow properties and methods.

Properties
Name | Description
AutoShow | Retrieves or sets the flag that specifies if the window will be automatically shown on the first state change.
BackgroundPalette | Retrieves or sets the flag that indicates whether the renderer realizes its palette in the background.
BorderColor | Retrieves or sets the border color for the video window.
Caption | Retrieves or sets the text caption on the playback window.
FullScreenMode | Retrieves or sets the type of full-screen mode.
Height | Retrieves or sets the height of the video window.
Left | Retrieves or sets the x-axis coordinate for the video window.
MessageDrain | Retrieves or sets a window handle that is used by the video window to receive or post messages.
NotifyOwnerMessage | Forwards messages that have been received by a parent window to a child window owned by a filter.
Owner | Retrieves or sets the owning parent window for the video playback window.
Top | Retrieves or sets the y-axis coordinates for the video window.
Visible | Retrieves or sets the visibility of the window.
Width | Retrieves or sets the width of the video window.
WindowState | Retrieves or sets the current window state (such as visible or minimized).
WindowStyle | Retrieves or sets the playback window style.
WindowStyleEx | Retrieves or sets the playback window's extended style bits.

Methods
Name | Description
GetMaxIdealImageSize | Gets the ideal maximum image size for the video image playback (client) area.
GetMinIdealImageSize | Gets the ideal minimum image size for the video image playback (client) area.
GetRestorePosition | Retrieves the restored video window size when maximizing and minimizing.
GetWindowPosition | Retrieves the video window position.
HideCursor | Hides the cursor.
IsCursorHidden | Retrieves whether the cursor is visible or not.
NotifyOwnerMessage | Passes palette and color change messages on the filter graph.
SetWindowForeground | Sets the video window as the foreground window and optionally gives it focus.
SetWindowPosition | Sets the video window position on the display.

AutoShow Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets information about whether the window will be automatically shown.

objVideoWindow.AutoShow [= boolean]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
boolean
True means the window will be made visible when the state is changed.
Remarks

Many simple applications require a displayed window when a filter graph is set to the running state. This method is set on (–1) by default so that when the graph changes state to paused or running, the window will be made visible (it will also be set to be the foreground window). It will be shown on all subsequent state changes to paused or running unless the window is closed, in which case it will not be shown again until the renderer goes through a stopped state. If this property is set to off (0), the window will remain hidden until explicitly shown. You can do this by setting the Visible property.

BackgroundPalette Property (IVideoWindow Object)

IVideoWindow Object

Determines whether any palette required will be realized in the background.

objVideoWindow.BackgroundPalette [= boolean]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
boolean
Flag that indicates whether the palette will be realized.
Remarks

If this is True (–1), the renderer realizes any required video palette in the background. This means that any colors the palette uses will change to their closest match in the display palette prior to drawing. This ensures that an application will not have its palette disturbed when playing a video. It does, however, impose severe performance penalties on the video and should not be used unless absolutely necessary. The default value for this property is False (0).

BorderColor Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the border color for the video window.

objVideoWindow.BorderColor [= Color]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Color
New border color.
Remarks

When a destination rectangle that is set differs from the window's visible client area, a border is exposed around the edge. This method allows an application to change the border color. It is set to black by default. Any nonsystem color passed in is converted to its closest match, according to the current palette, before being used (this is not an issue on true-color devices). Setting this causes the window border to be repainted in the new color automatically.

Caption Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the textual title string for the video window.

objVideoWindow.Caption [= string]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
string
New value for the window title caption.

FullScreenMode Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets a flag indicating whether to use full-screen mode for the video window.

objVideoWindow.FullScreenMode [= boolean]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
boolean
New flag value. True means use full-screen mode; False means do not use full-screen mode.

GetMaxIdealImageSize Method (IVideoWindow Object)

IVideoWindow Object

Retrieves the ideal maximum image size for the video image playback (client) area.

objVideoWindow.GetMaxIdealImageSize Width, Height

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Width
Long value that will contain the image width.
Height
Long value that will contain the image height.

GetMinIdealImageSize Method (IVideoWindow Object)

IVideoWindow Object

Gets the ideal minimum image size for the video image playback (client) area.

objVideoWindow.GetMinIdealImageSize Width, Height

Parts
objVideoWindow
An object expression that evaluates to an IVideoWindow object.
Width
Long value that will contain the image width.
Height
Long value that will contain the image height.

GetRestorePosition Method (IVideoWindow Object)

IVideoWindow Object

Retrieves the size and position of the window when it is to be restored after being minimized.

objVideoWindow.GetRestorePosition Left, Top, Width, Height

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Left
Returns the x-axis origin of the video window.
Top
Returns the y-axis origin of the video window.
Width
Returns the width of the video window.
Height
Returns the height of the video window.

GetWindowPosition Method (IVideoWindow Object)

IVideoWindow Object

Retrieves the current window rectangle (not the client rectangle) in device coordinates.

objVideoWindow.GetWindowPosition Left, Top, Width, Height

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Left
Returns the x-axis origin of the window.
Top
Returns the y-axis origin of the window.
Width
Returns the width of the window.
Height
Returns the height of the window.
Remarks

This method has the same effect as individually setting the Left, Top, Width, and Height properties.

Height Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the height of the video window.

objVideoWindow.Height [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the vertical dimension of the video window.
Remarks

Changes to the Height property are independent of the Width property (the y-coordinate of the video window).

HideCursor Method (IVideoWindow Object)

IVideoWindow Object

Specifies whether the cursor is visible or hidden when it passes over the video playback window.

objVideoWindow.HideCursor bValue

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
bValue
Boolean value that specifies whether the cursor is visible or not; True hides the cursor and False makes it visible.
Remarks

When you use full-screen playback, it is common to hide the cursor to avoid distracting the user.

The following code fragment shows how to use this method.

    Dim o_objVideoWindow As IVideoWindow		'Initialize the IVideoWindow Object
    Dim g_objMediaControl As IMediaControl    	'Initialize the IMediaControl Object

    Set g_objVideoWindow = g_objMediaControl		'Assign the playback window to the filter graph
    g_objVideoWindow.HideCursor (True)			'Hide the cursor

IsCursorHidden Method (IVideoWindow Object)

IVideoWindow Object

Retrieves whether the cursor is visible or not.

objVideoWindow.IsCursorHidden bValue

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
bValue
Boolean value that will contain the cursor's state of visibility; True if the cursor is hidden and False if it is visible.
Remarks

When you use full-screen playback, it is common to hide the cursor to avoid distracting the user.

The following code fragment shows how to use this method.

    Dim o_objVideoWindow As IVideoWindow		'Initialize the IVideoWindow Object
    Dim g_objMediaControl As IMediaControl    	'Initialize the IMediaControl Object
    Dim bTest As Boolean					'Initialize the storage variable

    Set g_objVideoWindow = g_objMediaControl		'Assign the playback window to the filter graph
    g_objVideoWindow.IsCursorHidden (bTest)		'Check if the cursor is hidden

Left Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the x-coordinate for the video window.

objVideoWindow.Left [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the x-axis coordinate.
Remarks

Calling this method does not affect the width of the video window.

MessageDrain Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the window handle of the window that receives posted messages for the video window.

objVideoWindow.MessageDrain [= handle]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
handle
New value for the window handle.

NotifyOwnerMessage Method (IVideoWindow Object)

IVideoWindow Object

Forwards messages that have been received by a parent window to a child window owned by a filter.

objVideoWindow.NotifyOwnerMessage hwnd, uMsg, wParam, lParam

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
hwnd
Window handle.
uMsg
Message being sent.
wParam
Message's wParam.
lParam
Message's lParam.

Owner Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the owning parent for the video window.

objVideoWindow.Owner [= handle]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
handle
New value for the window handle.
Remarks

This property offers a way for applications to set the owner of the video window. This is often used when playing videos in compound documents.

SetWindowForeground Method (IVideoWindow Object)

IVideoWindow Object

Sets the video window as the foreground window and optionally gives it focus.

objVideoWindow.SetWindowForeground Focus

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Focus
Long value that specifies whether the video window will have focus. A value of –1 gives the window focus and 0 does not.

SetWindowPosition Method (IVideoWindow Object)

IVideoWindow Object

Sets the position of the video window (not the client rectangle position) in device coordinates.

objVideoWindow.SetWindowPosition Left, Top, Width, Height

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
Left
Specifies the x-axis origin of the window.
Top
Specifies the y-axis origin of the window.
Width
Specifies the width of the window.
Height
Specifies the height of the window.
Remarks

Specify, in window coordinates, where the video should appear. For example, setting a destination of (100,50,200,400) positions the video playback at an origin of 100 pixels from the left of the client area, 50 pixels from the top, and with an overall size of 200 x 400 pixels. If the video is smaller than this (or a source rectangle has been specified that is smaller than the video), it will be stretched appropriately. Similarly, if the video is larger than the destination rectangle, the video is compressed into the visible rectangle. There are fairly severe performance penalties if an application does not keep the source and destination rectangles the same size.

Under typical circumstances, when no destination rectangle has been set, the video fills the entire visible client window area (regardless of how much the user has stretched the window). Also, the destination rectangle properties correctly return the size of the video window client area.

This method has the same effect as individually setting the Left, Top, Width, and Height properties.

Top Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the y-axis coordinate of the video window.

objVideoWindow.Top [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the y-axis origin.
Remarks

Calling this method does not affect the height of the video window.

Visible Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the visibility of the video window.

objVideoWindow.Visible [= boolean]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
boolean
If set to True, the window is shown; if False, the window is hidden.

Width Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the width of the video window.

objVideoWindow.Width [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value of the width.
Remarks

The Width property is independent of the video window's Height property (the x-coordinate).

WindowState Property (IVideoWindow Object)

IVideoWindow Object

Returns or sets the state of the video window.

objVideoWindow.WindowState [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the WindowState property.

WindowStyle Property (IVideoWindow Object)

IVideoWindow Object

Retrieves or sets the style parameters for the video window.

objVideoWindow.WindowStyle [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the WindowStyle property.
Remarks

For a complete list of window styles, see the CreateWindow function in the Microsoft® Platform Software Development Kit (SDK).

WindowStyleEx Property (IVideoWindow Object)

IVideoWindow Object

Changes the style parameters for the video window.

objVideoWindow.WindowStyleEx [= lValue]

Parts
objVideoWindow
Object expression that evaluates to an IVideoWindow object.
lValue
New value for the flags. Valid values include only those flags that can be set by the GWL_STYLE value of the Microsoft Win32 GetWindowLong function.


DirectShow Basics

This section contains articles covering basic DirectShow concepts, such as filter graph architecture and data flow, how to use the Filter Graph Editor tool, and a list of the filters and sample filters supplied with DirectShow. You can use this section as a high-level introduction to DirectShow. You need only a general understanding of programming and media to understand the topics in this section.

Using DirectShow

Filter Graph Manager and Filter Graphs

Filters and Pins

Stream Control Architecture

Quality-Control Management

About Capture Filter Graphs

Improving Capture Performance

Data Flow in the Filter Graph

Constructing Filter Graphs Using Visual Basic

Controlling Filter Graphs Using Visual Basic

List of Filters and Samples

About the DirectShow Filter Graph Editor

Using the Filter Graph Editor

COM Overview

Overview of DVD Interfaces and Data Types

About WDM Video Capture


Using DirectShow

Microsoft® DirectShow™ is an architecture that controls and processes streams of multimedia data through custom or built-in filters. You can also use the set of media streaming interfaces to stream media data without creating filters. See Use Multimedia Streaming in DirectShow Applications for more information.

In addition to the architecture and the set of classes and interfaces to support it, DirectShow is also a run time that uses this architecture to enable users to play digital movies and sound encoded in various formats, including MPEG, AVI, MOV (Apple® QuickTime®) and WAV-formatted files. The DirectShow run time is a control (.ocx), called the ActiveMovie Control, and a set of dynamic-link libraries (DLLs) that enable you to play back supported media files.

DirectShow playback uses video and audio hardware cards that support the Microsoft DirectX® set of application programming interfaces (APIs). The video and audio capture capability lets you programmatically control your system's video and audio capture hardware, as well as video and audio compressors and decompressors (codecs). The Plug and Play capability lets DirectShow automatically retrieve and use your filters, once you register their properties.

Use the DirectShow architecture for most new multimedia applications for Windows® 95 or Windows NT®. With a few exceptions, it replaces multimedia playback services, APIs, and architectures provided by Microsoft in earlier versions of the Windows Software Development Kit (SDK). However, libraries will continue to be available and supported for applications that use the earlier Microsoft multimedia playback services, such as Microsoft Video for Windows.

Contents of this article:

  • DirectShow Architecture
  • Choosing the Right Programming Model
  • Playing Back Files Over the Internet

DirectShow Architecture

The DirectShow architecture defines how to control and process streams of multimedia data using modular components called filters. The filters have input or output pins, or both, and are connected to each other in a configuration called a filter graph. Applications use an object called the filter graph manager to assemble the filter graph and move data through it. By default, the filter graph manager automatically handles data flow for you; for example, it automatically inserts the proper codec if needed, and it automatically connects a transform filter's output pin to the default rendering filter. You can always specify your own filters and connections if you don't want to use the default configuration.

The filter graph manager provides a set of Component Object Model (COM) interfaces so that applications can access the filter graph. Applications can directly call the filter graph manager interfaces to control the media stream or retrieve filter events, or they can use the ActiveMovie Control to play back media files.

Thus, you can access DirectShow through the COM interface, the ActiveMovie Control, or media control interfaces (MCI), as shown in the following illustration.

Illustration of DirectShow architecture

Because of the DirectShow architecture's flexible, modular design, filter graphs have many potential uses and applications. Examples include filter graphs that implement video capture, control remote devices such as VCRs, or enable MIDI recording and editing.

Choosing the Right Programming Model

DirectShow is accessible at several levels, and the approach you use depends on what you need and how much programming you want to do. You might plan to rewrite an existing multimedia program, write a new multimedia program, or add multimedia capabilities to an existing program. Typically, existing applications that use the MCI command set are easily ported, whereas applications that access lower-level multimedia services require more time to rewrite. You can quickly add DirectShow playback services to new applications by using the ActiveMovie Control, or with a few direct functions that call the COM interfaces. C or C++ programmers can write filters that change or enhance multimedia data already managed by existing filter graphs.

This section contains the following topics.

  • Rewriting Existing Applications
  • Writing New Applications

Rewriting Existing Applications

If you have an application that plays AVI-encoded movies and sounds and want to adapt it to use DirectShow to play AVI files, porting is straightforward if your application uses MCI commands or the Microsoft Video for Windows® API. Your choice depends on the services the application uses and your goals. If your application uses MCI commands, you can use the MCI subset that DirectShow provides. In the majority of cases, this will be a straightforward upgrade that maintains AVI playback and adds MPEG and QuickTime playback capabilities to your application. If your existing C-based application uses Video for Windows API, you can replace most of these with calls to the COM interfaces.

Writing New Applications

You can take a variety of approaches when writing a new application with DirectShow. For example, if you only want to add MPEG playback to your application, you can incorporate the ActiveMovie Control into your application or directly access the COM interfaces on the filter graph manager. Both Microsoft Visual Basic® version 5.x and later and Microsoft Visual C++® version 5.x and later allow access to the ActiveMovie Control or the COM interfaces. Filters within a filter graph are typically written in C++ using the DirectShow class library.

If your application must process the media stream in some way or capture a media stream, you can incorporate both the filter graph manager and a custom filter into your application. The instantiated filter graph manager generates and manages the filter graph. You can insert the custom filter into a preconfigured filter graph (which you create and save by using the Filter Graph Editor tool in the DirectShow SDK). You also could insert the filter into an existing filter graph at run time.

Playing Back Files Over the Internet

The ActiveMovie Control is incorporated into Microsoft Internet Explorer so that you can place the control on a Web page and program it by using Microsoft Visual Basic® Scripting Edition (VBScript) commands. To a programmer, the ActiveMovie Control is another ActiveX™ Control, one that has real-time playback capability. Real-time playback means that the ActiveMovie Control can play video or audio files over the Internet while the file is downloading, rather than requiring the user to wait until the whole file is downloaded to begin playback.

The same filter graphs constructed to play media from files can play media from the Internet by simply changing the source filter. Take, for example, a filter graph that plays MPEG movies from a disk file. The first filter in the graph might be a file reader filter. By replacing this filter with a filter capable of reading from an Internet URL address, you can play MPEG movies from the Internet. Both file and URL reader source filters just deliver an unparsed stream of data. A parser filter pulls the data from the reader, parses it into separate streams of video, audio, text, or other data types, and pushes it downstream. This filter remains unchanged regardless of whether the source filter is a file or URL reader filter.

The source filter that reads from an Internet server is called the File Source (URL) filter. DirectShow provides this as a built-in filter. It knows how to read, but not parse, data from a URL address. Therefore, a media parser follows the File Source (URL) filter in the filter graph. For MPEG sources, this parser is built into the MPEG splitter filter. Other media types have their own parser filters (for example, a QuickTime parser).

The source filter that reads from files is the File Source (Async) filter. DirectShow also provides this as a built-in filter. It does no parsing on its own but simply reads data off a disk to play back. Most DirectShow filter graphs use this source filter.

The architecture's modularity allows most of the same components to be reused between file and Internet playback. This modularity also means that if you want to render a new type of data, often you only need to write a parser and renderer, and you can still use the existing file or URL filter.


Filter Graph Manager and Filter Graphs

To use the filter graph manager from an application, it is not necessary to know much about the underlying filter graphs. However, it is useful to understand at least the basic principles of filter graphs if you ever want to configure your own filter graph rather than letting the filter graph manager configure them for you.

A filter graph is composed of a collection of filters of different types. Most filters can be categorized into one of the following three types.

  • A source filter, which takes the data from some source, such as a file on disk, a satellite feed, an Internet server, or a VCR, and introduces it into the filter graph.
  • A transform filter, which takes the data, processes it, and then passes it along.
  • A rendering filter, which renders the data; typically this is rendered to a hardware device, but could be rendered to any location that accepts media input (such as memory or a disk file).

In addition to these three types, there are other kinds of filters, for example, effect filters, which add effects without changing the data type, and parser filters, which understand the format of the source data and know how to read the correct bytes, create times stamps, and perform seeks.

For example, a filter graph whose purpose is to play back an MPEG-compressed video from a file would use the following filters.

  • A source filter to read the data off the disk.
  • An MPEG filter to parse the stream and split the MPEG audio and video data streams.
  • A transform filter to decompress the video data.
  • A transform filter to decompress the audio data.
  • A video renderer filter to display the video data on the screen.
  • An audio renderer filter to send the audio to the sound card.

The following illustration shows such a filter graph.

MPEG filter graph example

It is possible for some filters to represent a combination of types. For example, a filter might be an audio renderer that also acts as a transform filter by passing through the video data. But typically, filters fit only one of these three types.

Filter graphs stream multimedia data through filters. In the media stream, one filter passes the media downstream to the next filter. An upstream filter describes the filter that passes data to the filter; a downstream filter describes the next filter in line for the data. This distinction is important because media flows downstream, but other information can go upstream.

To make a filter graph work, filters must be connected in the proper order, and the data stream must be started and stopped in the proper order. The filter graph manager connects filters and controls the media stream. It also has the ability to search for a configuration of filters that will render a particular media type and build that filter graph. Filter graphs can also be preconfigured, in which case the filter graph manager does not need to search for a configuration.

When searching for a rendering configuration, the filter graph manager uses the filter mapper, which first reads the registry and determines the types of filters available. The filter graph manager then attempts to link filters that accept that data type until it reaches a rendering filter. A merit value is registered with each filter and, of the filters that might be capable of handling the data, the filters with the highest merit are tried first.

Controlling the media stream means starting, pausing, or stopping the media stream. It can also mean playing for a particular duration or seeking to a particular point in the stream. The filter graph manager allows the application or ActiveX Control to specify these activities, and then calls the appropriate methods on the filters to invoke them. It also allows filters to post events that the application can retrieve. Therefore an application can, for example, retrieve status about some special filter it has installed.


Filters and Pins

The two basic components used in the stream architecture are filters and pins. A filter is a COM object that performs a specific task, such as reading data from a disk. For each stream it handles, it exposes at least one pin. A pin is a COM object created by the filter, that represents a point of connection for a unidirectional data stream on the filter, as shown in the following illustration.

Input pins accept data into the filter, and output pins provide data to other filters. A source filter provides one output pin for each stream of data in the file. A typical transform filter, such as a compression/decompression (codec) filter, provides one input pin and one output pin, while an audio output filter typically exposes only one input pin. More complex arrangements are also possible.

You can name pins anything you want. If your pin name begins with the tilde (~) character, the filter graph will not automatically render that pin when an application calls IGraphBuilder::RenderFile. This can apply to pins that are just informational and are not meant to be rendered, or need to be enumerated so that their properties can be set. The tilde (~) prefix only affects the behavior of RenderFile and intelligent connect (IGraphBuilder::Connect). Note that intelligent connect can still be used to connect pins with this property if they implement the IPin::Connect method. However, output pins of intermediate filters which are being used to complete the connection which have the tilde at the start of their name will not be connected as part of the intelligent connection attempt.

At a minimum, a filter exposes the IBaseFilter interface. This interface provides methods that allow the enumeration of the pins on the filter and return filter information. It also provides the inherited methods from IMediaFilter; these methods allow control of state processing (for example running, pausing, and stopping) and synchronization, and are called primarily by the filter graph manager.

In addition, a filter might expose several other interfaces, depending on the media types supported and tasks performed. For example, a filter can expose the ISpecifyPropertyPages interface to support a property page.

Pins are responsible for providing interfaces to connect with other pins and for transporting the data. The pin interfaces support the following:

  • The transfer of time-stamped data using shared memory or other resource.
  • Negotiation of data formats at each pin-to-pin connection.
  • Buffer management and buffer allocation negotiation designed to minimize data copying and maximize throughput.

Pin interfaces differ slightly, depending on whether they are output pins or input pins.

An output pin typically exposes the following interfaces.

  • IPin methods are called to allow the pin to be queried for pin, connection, and data type information, and to send flush notifications downstream when the filter graph stops.
  • IMediaSeeking allows information about the stream's duration, start time, and stop time to be relayed from the renderer. The renderer passes the media position information upstream to the filter (typically the source filter) responsible for queuing the stream to the appropriate position.
  • IQualityControl passes quality-control messages upstream from the renderer to the filter that is responsible for increasing or decreasing the media supply.

An input pin typically exposes the following interfaces.

  • IPin allows the pin to connect to an output pin and provides information about the pin and its internal connections.
  • IMemInputPin allows the pin to propose its own transport memory allocator, to be notified of the allocator that an output pin is supplying, to receive media samples through the established allocator, and to flush the buffer. This interface can create a shared memory allocator object if the connected pin does not supply a transport memory allocator.

The standard transport interface, IMemInputPin, provides data transfer through shared memory buffers, although other transport interfaces can be used. For example, where two components are connected directly in hardware, they can connect to each other by using the IPin interface, and then seek a private interface that can manage the transfer of data directly between the two components.


Stream Control Architecture

The stream architecture allows applications to communicate with the filter graph manager; it also allows the filter graph manager to communicate with individual filters to control the movement of the data through the filter graph. Using the stream architecture, filters can post events that the application can retrieve, so an application can, for example, retrieve status information about a special filter it has installed.

The filter graph manager exposes media control and media positioning interfaces to the application. The media control interface, IMediaControl, allows the application to issue commands to run, pause, and stop the stream. The positioning interface, IMediaSeeking, lets the application specify which section of the stream to play.

Individual filters expose an IBaseFilter interface so that the filter graph manager can issue the run, pause, and stop control commands. The filter graph manager is responsible for calling these methods in the correct order on all the filters in the filter graph. (The application should not do this directly.)

For position commands, the filter graph manager is called by the application to, for example, play a specified length of media stream starting at some specified stream time. However, unlike the IBaseFilter interface, only the renderer filter exposes an IMediaSeeking interface. Therefore, the filter graph manager calls only the renderer filter with positioning information. The renderer then passes this position control information upstream through IMediaSeeking interfaces exposed on the pins, which simply pass it on. The positioning of the media stream is actually handled by the output pin on the filter that is able to seek to a particular position, usually a parser filter such as the AVI splitter.

Position information is passed serially upstream because there might be filters between the renderer and the source filter that require position information. Consider a transform filter that is written to perform some video or audio modification only during the first 10 seconds of a video clip (for example, increasing the volume or fading in the video). This filter probably needs to have information about where the stream is starting so that it can determine its correct behavior. For example, it should not perform if the start time is after the first 10 seconds, or it should adjust accordingly if the start time is within this duration.

Filters also get position information from the IPin::NewSegment method which provides the media start and stop times for the next set of samples and the rate to be associated with those samples.


Quality-Control Management

The Microsoft® DirectShow™ stream architecture provides for graceful adaptation of media rendering to overloaded or underloaded media streams. The IQualityControl interface is used to send quality-control notifications from a renderer filter either upstream, eventually to be acted on by some filter in the graph, or directly to a designated quality control manager. The base classes implement the passing of quality control notifications upstream by providing the IQualityControl interface on the output pins of filters. Quality control notification uses a Quality structure, which indicates whether the renderer is overloaded or underloaded. A filter capable of, say, discarding samples to relieve an overloaded condition, can then act on this notification. This is typically done by a source filter but could be done by other filters. For example, the DirectShow AVI Decoder filter skips samples until the next key frame when it receives a quality control notification.


About Capture Filter Graphs

This article provides a brief introduction to capture and introduces the fundamentals of filter graphs that provide video or audio capture or preview capabilities. It includes conceptual diagrams of the most common capture-related filter graphs to help you visualize the components in each filter graph and see how they fit together. It discusses the role of particular filters such as video and audio capture filters, the AVI MUX (multiplexer) filter, and the file writer filter. It also highlights unusual points such as filters (for audio capture in this case) that have input pins.

See Where Can I Learn About... for a list of topics relating to capture, including articles that discuss writing code to perform capture.

If you are new to DirectShow, read Filter Graph Manager and Filter Graphs and Filters and Pins to familiarize yourself with the architecture's fundamental concepts.

Contents of this article:

  • Capture Introduction
  • Video and Audio Capture Filter Graphs

Capture Introduction

Video and audio capture enable you to take multimedia data from an external source such as a VCR or camera, and view it, listen to it, or save it on your computer's hard drive. Your computer must include video or audio capture hardware to perform capture. For audio capture, a sound card with a microphone or line-in jack is usually sufficient. Some video capture cards support audio capture as well, so you might not need two separate cards. The DirectShow architecture provides default components (filters) that enable you to capture video and audio data streams given the appropriate capture hardware and drivers. DirectShow takes advantage of new capture drivers that are written as DirectShow filters and also uses existing Video for Windows-style drivers.

Video and Audio Capture Filter Graphs

Typical filter graphs that provide video and audio capture and video preview capability must include video capture, audio capture, multiplexer (MUX), file writer, and video renderer filters. If you need a subset of these features your filter graph can be simpler and contain fewer filters. This section begins by discussing the simpler capture filter graphs and the components they contain. It then discusses filter graphs that combine features and build upon the basic capture filter graphs to provide more functionality.

This section contains the following topics:

  • Video Preview Filter Graphs
  • Video Capture Filter Graphs
  • Video Capture and Preview Filter Graphs Combined
  • Adding Audio Capture
  • Capture Filter Input Pins
  • Example Capture Filter Graph

Video Preview Filter Graphs

A video preview filter graph enables you to watch the video on your computer screen as it plays from your VCR, camera, or other video source. The video preview filter graph is very simple. It contains a video capture filter and a video renderer. The capture filter provides the video data from the capture card, exposing a pin called Preview to which the video renderer connects. The video renderer provides a playback window in which it displays the video data. If the capture filter produces compressed data, you must insert a decompressor filter between the capture filter and the renderer.

Note Capture filters are not required to expose a preview pin.

The portion of the graph from the preview pin downstream to and including the video renderer is called the preview section of the filter graph.

DirectShow provides video capture and video renderer filters. If you have an existing Video for Windows-style capture driver, the video capture filter wraps the functionality provided by that driver so that it works with the DirectShow architecture. You can also write your own video capture filter or use third-party capture filters.

The following diagram illustrates a simple video preview filter graph.

Video preview filter graph

Video capture filters expose a pin for capture as well as an optional pin for preview. Pin names can vary from those shown in the diagram above. The next section of this article discusses the capture pin.

Note Some capture filters have a capture pin and do not have a preview pin. If the capture pin is the only pin on a capture filter, connect the renderer to the capture pin.

Video Capture Filter Graphs

A video capture filter graph takes captured video data and saves it to a file. The term "video capture filter graph" often encompasses video capture and preview functionality, but this section uses the term in the strict "capture to file" sense.

The simplest video capture filter graphs contain a video capture filter, multiplexer filter, and file writer filter. The capture filter provides video data from the capture card, just as it does in video preview filter graphs. It exposes a pin for capture to which the multiplexer filter (MUX) connects. The multiplexer filter understands a particular file format, such as audio-video interleaved (AVI). It has multiple input pins and one output pin. Each input pin takes in a stream of audio or video data. The MUX combines the separate streams of data into the appropriate file format and then passes the newly combined data through its output pin to the file writer. The file writer filter writes the data stream from the MUX to disk without any knowledge of the particular data format.

The MUX and file writer work together as a unit.

DirectShow provides the AVI MUX and File Writer filters. The AVI MUX filter packages data streams into an AVI file stream; therefore, the File Writer always writes files in AVI format if it is connected to the AVI MUX.

The following diagram illustrates a simple video capture filter graph.

Video capture filter graph

Video Capture and Preview Filter Graphs Combined

A filter graph that provides both video capture and video preview capabilities combines all the filters from video capture and video preview filter graphs. All the filters serve the same role as in the smaller filter graphs.

The following diagram illustrates the combined video capture and video preview filter graph.

Video preview and capture filter graph

Adding Audio Capture

None of the filter graphs discussed thus far capture audio data. As a result, they produce movies that are silent upon playback. Adding an audio capture filter to the video capture and preview filter graph, as illustrated in the following diagram, provides the missing audio capture capability.

Video and audio capture and video preview filter graph

Audio capture filters accept audio data from the audio capture card much as video capture filters accept video data. A capture card might provide both video and audio capture capabilities, so the corresponding video and audio capture filters might process data from the same capture card. If your system contains separate audio and video capture cards, the video capture and audio capture filters process data from separate capture cards.

Audio capture filters also expose a capture pin that connects to the multiplexer filter in the same way that the capture pin on a video capture filter connects to the multiplexer. The multiplexer's role becomes more important in this filter graph because it has more than one connected input pin. Each connected input on the MUX provides a separate data stream (one video and one audio in this case), which the MUX combines into its supported file format, and the file writer saves the resulting data to a file on disk.

Capture Filter Input Pins

An unusual feature of audio and video capture filters is that they can expose input pins, unlike other source filters. Source filters do not typically expose input pins because they are the source of the data. They typically pass data on to the next filter in the graph rather than accepting input data from another filter. The input pins provide a mechanism to access input characteristics. Audio capture filters support the IAMAudioInputMixer interface to provide access to such characteristics as recording and bass levels on each input line. Each input pin represents an input line such as microphone, CD audio, or MIDI on the audio card.

The following diagram shows a full-featured filter graph that provides video preview, and video and audio capture. The audio capture filter exposes an input pin for each input line on the capture card. Internally, each pin supports IAMAudioInputMixer to enable applications to access input characteristics on each line.

Capture filter graph including input pins on the audio capture filter

Example Capture Filter Graph

Now that you're familiar with capture filter graphs in general, here's a screen shot of a capture filter graph from the Filter Graph Editor tool that is included with the DirectShow SDK. It builds upon the conceptual diagrams examined earlier.

Capture filter graph screen shot

The preceding screen shot shows a motion JPEG video capture filter and an audio capture filter in a capture filter graph. Both filters process data from the same capture card because the capture card happens to capture both video and audio data streams. A computer might include a sound card in addition to a capture card, giving you a choice between two audio sources and therefore between audio capture filters to insert in the capture filter graph.

The screen shot is very similar to the conceptual diagrams examined earlier with the exception of filter names and input pin names. The input pins on the audio capture filter are labeled Intern and Extern. The file writer filter saves captured video and audio data to a file called Testcap.avi at the root of the C: drive.

If you have capture hardware installed on your system and use the Filter Graph Editor tool to create a capture filter graph, it will appear similar to the preceding screen shot. The names of the video and audio capture filters depend on the capture drivers installed on the computer. If present, the audio capture filter's input pins might have different names from those illustrated. The name of the file to which captured data is saved will differ as well. The preview pin will connect to a decoder if the data from the pin is compressed, and the decoder will then connect to the renderer.


Improving Capture Performance

Capturing is a hardware-intensive operation that requires saving a large amount of information to disk as quickly as possible. This information is typically in the form of video and audio data. Reducing bottlenecks that slow down the system is very important, because it can help improve the quality of the captured movie.

This article presents some general suggested practices and hints and tips that can help you, as the user of a capture application, set up the capture system for optimal capture performance.

Note Be sure to read your capture card manual for information specific to your capture card. Systems vary as well, so all the information presented in this article might not apply to your system configuration.

See Capture Introduction for a brief introduction to capture. See capture topics for a list of Microsoft® DirectShow™ interfaces and articles relating to capture.

Contents of this article:

  • Capture Numbers
  • Optimizing the Hard Disk for Capture
  • Disk Settings in Window 95 and Later
  • Reducing Noncapture-Related Machine Activity
  • Additional Hints and Tips for Improving Capture Performance
  • Choosing a Capture System
  • Suggested Capture Reading

Capture Numbers

Capturing involves transferring a large amount of data from a capture card to disk. To get an idea of the amount of data and the data throughput required for a particular capture scenario, consider the following:

Suppose you want to capture a movie with a height of 320 pixels, a width of 240 pixels, a capture rate of 30 frames per second (fps), and in 24-bit color format. The movie does not include any sound.

Use the following formula to determine the number of bytes of uncompressed data that must be transferred every second in order to capture all of the image data, and therefore to maintain the image quality.

bytes of transferred video data = height (in pixels) x width (in pixels) x rate (in fps) x color depth (in bytes)

Plugging in the numbers from the preceding scenario produces the following result.

320 x 240 x 30 x 3 = 6912000 bytes of transferred video data

Capturing one second of this movie at the desired size, frame rate, and color depth requires approximately 6.9 million bytes of disk space. Multiplying by 60 seconds produces the results for a minute; each minute of capture requires 414,720,000 bytes in this case. You can reduce the amount of data required by reducing any of the parameters in the above formula: capture a smaller image, at fewer frames per second, or with fewer colors. However, in cases where your image requirements push the system to its limits and you need to be able to capture at the highest possible number of megabytes per second, you'll want to optimize your system as much as possible. After all, the capture settings you use affect how the movie will look when someone plays it back.

The preceding numbers are for a silent movie. If you want to capture audio as well as video, you have to add the amount of required audio data. For example, CD-quality audio, recorded at 44 kilohertz (kHz), 16-bit, stereo, requires about 172 kilobytes (KB) per second. Audio capture is also very CPU-intensive, and synchronizing the audio and video data (to achieve proper lip synch, for example) can cause delays as well.

You might find that your system can't keep up with the required amount of data transfer for the settings you've chosen. When capturing, your system might pause, the video might be jerky or jitter (not smooth), and some of the frames might be dropped (not saved to disk). Playback quality of such an image is typically unsatisfactory. To avoid such problems, you can follow a number of practices to optimize your system for capturing.

The suggestions presented in this article can help you reach the goal of optimal capture performance. At the same time, bear in mind that each system is different and something that improves performance on one system might not be effective on another system.

Optimizing the Hard Disk for Capture

Because capturing is very hard-disk intensive, optimizing the files on the hard drive that you'll use for capturing (also called the data drive or data disk) is the most important task in optimizing capture performance. The following list contains goals in optimizing the data drive and techniques you might use to achieve those goals. The techniques discussed here are suggestions and might not be helpful given particular capture requirements. Your requirements and resources govern precisely which techniques you might want to try.

  • Ensure the capture file is in a contiguous (nonfragmented) location on the data drive.

    The heads of a hard drive can read from and write to a contiguous file more efficiently than if they have to seek to other, nonadjacent portions of the disk. Use a tool such as the Microsoft Windows® Disk Defragmenter (Defrag.exe) to defragment your data disk. Defragment both the data drive and the operating system drive. The operating system drive comes into play when using drivers (such as audio and video drivers), writing to the system cache, writing to the registry, using overlays, and so forth. Run the Windows 95 Scandisk tool to ensure the integrity of the data drive and the operating system drive.

  • Preallocate a capture file that is larger than any movie clips you expect to save.

    Allocating file space is time-consuming, so you should allocate your file before you capture. Capture software such as the DirectShow AMCap sample lets you allocate space for the capture file. If you capture more data than will fit in the capture file, the system has to allocate more space for the file as you capture, which, again, slows down capture. Avoid the reallocation of file space during capture, and the speed penalty, by allocating a file that is large enough to meet your needs. Saving the captured data can require as much space as the original capture file, so ensure you have enough free hard disk space to save your captured data to another file. Be sure to regularly defragment your capture file as well.

  • Devote an entire hard disk, or partition on the disk, for the capture file.

    This technique is particularly useful under Windows NT® because Windows NT does not include a Scandisk or Disk Defragmenter tool. Reserving an entire disk or partition on the disk for the capture file can make it easier to keep the capture file space clean and contiguous. You can format such a disk or partition, and then preallocate file space again, or defragment it without having to worry about other files on the disk or partition. When you format a dedicated capture drive, use the full format to initialize the disk rather than a quick format that leaves old data on the disk.

    Save your captured images to a directory that is not on your data drive or data partition to help keep your data drive clean. If you can't devote an entire drive to capture, allocate space for the capture file, defragment the file, and (in Windows 95) run the Windows 95 Scandisk tool.

  • Place the capture file at the beginning (outer rim) of the data drive.

    If you allocate the capture file as the only file on the disk, or as the only file in the first partition on the disk, it will begin at the outer rim of the disk. Access to the outer portion of a hard disk is faster than access to the inner portion of the disk. If you don't have a hard drive to devote to capture, you can use disk utilities to move your capture file to the beginning of the disk.

Revisit these goals as necessary before each capture session to ensure your disk is configured for optimal performance. Defragment the data disk before each capture session and defragment the drive containing your saved images before you play back the saved files.

Disk Settings in Window 95 and Later

The System applet of the Windows 95 and OSR2 Control Panel contains several options you can disable for optimal capture performance. In high-bandwidth situations like capture, it's important to make sure the drive is writing as much data as possible and not spending time with software optimizations or checking for system changes. The options to disable include the following:

  • Automatic detection that a CD-ROM disc has been inserted in the CD-ROM drive
  • Read-ahead optimization for the hard disk
  • Write-behind caching for all drives

To access these options in Windows 95, click the Start menu. Under Settings, click Control Panel, and double-click the System applet. Select the appropriate tab and proceed as outlined below:

  • Device Manager tab: Click CD-ROM and click your CD-ROM drive. Click the Properties button, select the Settings tab and clear the Auto insert notification check box.
  • Performance tab: Click the File System button and drag the Read-ahead optimization slider to None. (The default is Full.) While still on the File System Properties dialog, select the Troubleshooting tab and check Disable write-behind caching for all drives.

You will have to restart your machine for the new settings to take effect.

Note For optimal performance for other applications, be sure to return these settings to their original values after your capture session is complete.

Reducing Noncapture-Related Machine Activity

Anything that interrupts the system or consumes CPU time for purposes other than capture can potentially decrease capture performance. Consider performing the following tasks to see if they affect performance on your system.

  • Close all applications except the capture application.
  • Turn off the clock that Windows 95 displays on the taskbar. To do so, right-click the taskbar, click Properties and clear the Show Clock check box on the Taskbar Options tab.
  • Turn off the screen saver. To do so, right-click the desktop, click Properties, select the Screen Saver tab, and choose "(None)" from the screen saver drop-down combo box.
  • Turn off your printer.
  • Disable your network card if you have one. Sending and receiving data over the network can interrupt the system, even if you aren't actively doing anything over the network.

Additional Hints and Tips for Improving Capture Performance

This section contains a collection of hints and tips for improving capture performance that you might want to try after experimenting with the other suggestions in this article. The suggestions are grouped according to hardware and software-related suggestions.

Software

  • Consider capturing on Windows NT, because the Windows NT file system (NTFS) is typically faster than the traditional FAT file system, due to its use of threads. You might need to contact the manufacturer of your capture card for a driver that will work on Windows NT. Use a dedicated NTFS drive rather than a drive that is part NTFS and part FAT. The FAT-32 file system is typically faster than the FAT file system.
  • Using your capture software, experiment with different compression ratios (for example 2:1 or 1:1) to decrease the amount of data that has to be saved. Start with the default compression ratio and increase it until you drop frames. Try three passes and take the best results of the three. After you've saved the captured image to another drive, run Scandisk on the standard setting to quickly defragment the drive.
  • If you installed Windows 95 over your Windows 3.1 installation, put the line "verify=off" in your Autoexec.bat file. This line will prevent DOS from re-reading data after a write operation to make sure the correct data was written. Verification slows down the writing operation.

Hardware

  • Insert the capture card in PCI slot zero so it will be checked for activity before other cards on the system.
  • Make sure the hard drive cache is turned on for the data drive. Refer to your SCSI card manual for more information.
  • Heat buildup inside a system can wear down the system components and decrease capture performance. If you will be capturing continuously for hours at a time, make sure your system has three fans: one each for the power supply, CPU, and components (cards). If your captured images look fine at first, but become jittery after the system has been capturing for a while, the capture card might be overheating.
  • Some capture cards include a built-in audio card. Whether you use the on-board audio card or a separate audio card depends on your needs. You might find that a separate audio card provides features you need, or the on-board audio card might suit you just as well.
  • Some capture cards have an external connection for a monitor so you don't have to go through software to preview what you're capturing. That feature can help with performance, because the system isn't busy with the preview window.

Choosing a Capture System

Capturing is possible with a wide range of systems and capture cards. Shop around to compare capture cards and features to see what best meets your needs. See Suggested Capture Reading for possible sources of information. The optimal hardware configuration varies depending on the capture card.

If you're setting up a new machine to devote to capture, consider a 166-megahertz Pentium or later, with 64 megabytes or more of EDO RAM (as much RAM as possible), and a 2-gigabyte or larger Wide SCSI 2.0 AV-certified hard disk. AV-certified drives are designed for high-bandwidth data transfer. The SCSI hard disk controller should support PCI bus mastering 2.0 and later, which uses 32-bit drivers. If your capture card supports overlays, ensure that your video card also supports overlays. Make sure the capture card has drivers for the operating system you plan to use.

Suggested Capture Reading

This section lists possible sources of information about capture.

  • external link http://www.ccs.queensu.ca/pubs/itsnote/VideoCapture.html contains a general introduction to video capturing.
  • external link http://gcunix.gc.maricopa.edu/~IC/vidph/vidph05.html contains information about organizing the capture process.
  • external link http://fre.www.ecn.purdue.edu/FrE/asee/fie95/3a2/3a25/3a25.htm contains an article titled "Effective Video Capture Techniques for Educational Multimedia."
  • external link http://www.worldguide.com/Tech/videocapture.html contains information about setting up a system for video capture and compression.
  • external link http://cctpwww.cityu.edu.hk/public/graphics/g3_vidcap.htm contains information about some capture card and chip manufacturers.
  • Search the World Wide Web for "capturing".
  • Contact the manufacturers of various capture cards, many of whom are available on the Web.
  • See the manual for each capture card for its particular requirements.
  • For general background regarding digital video, see "PC Video Madness!", by Ron Wodaski, Sams Publishing, Carmel, Indiana, c. 1993, ISBN 0-672-30322-1.


Data Flow in the Filter Graph

This article examines the types of data, including samples, events, and notifications, that move through a filter graph, including where this data and information originates, where it is routed, and the protocols that must be followed for data to flow correctly.

Contents of this article:

  • How Data Moves in a Filter Graph
  • Media Sample Data Flow
  • Control Information Data
    • End-Of-Stream Notifications
    • Flushing
  • Event Notifications
  • Filter Graph Control Data
  • Quality Control Data
  • Serializing Data
  • IAsyncReader Transport

How Data Moves in a Filter Graph

Data flow in the filter graph can be viewed by examining the paths through which it flows, and also by examining the protocols that are used within those paths. Data flows primarily in the following paths.

  • Media sample data flows from one filter to the next — originating at a source filter and terminating, eventually, at a renderer filter.
  • Control information, such as end-of-stream and flushing notifications, travels with the media data stream from filter to filter.
  • Event notification events flow from the filters to the filter graph manager and, optionally, to the application.
  • Filter graph control data flows from the application to the filter graph manager and finally to the filters themselves.
  • Quality control data originates in the renderer and flows upstream through the filters until it finds a filter capable of increasing or decreasing the media data flow. It might also flow directly to a quality control manager if one is registered.

This article describes each of these data paths. Data movement in a filter graph is enabled by implementation of the following Microsoft® DirectShow™ filter graph protocols.

  • Media sample protocol, which defines the way that media samples are allocated and passed between filters.
  • End-of-stream protocol, which defines how filters generate and process end-of-stream information and how the filter graph manager is notified.
  • Flushing protocol, which defines how filters flush data through the filter graph.
  • Error detection and reporting protocol, which defines how errors are handled by filters and propagated to the filter graph manager.
  • New segment protocol, which defines a means to enable start and stop times and data rate information to be presented to a filter in advance of the data, so that a filter can adjust its processing accordingly.
  • Quality management protocol, which defines how the filter graph adapts dynamically to hardware and network conditions to degrade or improve performance gracefully.

Media Sample Data Flow

DirectShow filters pass media data downstream, that is, from the output pin of one filter to the input pin of the next filter. The flow and control of the data is effected by the interfaces on those pins and the filters themselves. The filters serialize data streaming activity; all data streaming calls for a given pin are explicitly serialized and usually originate from a single thread.

Data starts at a source filter and ends at a renderer filter. The source filter can either push the data down the graph (that is, originate the thread and send data to the IMemInputPin::Receive method of the downstream pin), or implement the IAsyncReader interface and let the downstream filter originate the thread, pull the data from the source filter, and send it downstream. For a description of how this latter case differs from other protocols, see IAsyncReader Transport.

Every filter should accept and process data received by its input pins, with the following exceptions.

  • The filter is in a stopped state.
  • The pin is in the middle of a flush operation. That is, the pin's IPin::BeginFlush method has been called but its IPin::EndFlush method has not been called yet (see Flushing).
  • The input pin rejected some previous data and no flush or stop action has occurred since (in which case the connected output pin should have stopped sending data anyway).

There can be other conditions for a filter to reject data as well. For instance, a transform filter would reject data at its input pin if its output pin was not connected.

Media samples are data objects that support the IMediaSample interface. They are usually obtained from an allocator, which is most likely represented by an object supporting the IMemAllocator interface. The two connected pins of adjacent filters agree on a common method of exchanging data, called a transport. Many of the base classes for the DirectShow class library are used to implement objects that support the local memory transport.

In the local memory transport, the input pin for a connection supports the IMemInputPin interface. An output pin can determine that it can use the local memory transport if a call to the IUnknown::QueryInterface method on the input pin to request the IMemInputPin interface succeeds. For this transport, data is passed from the output pin of one filter to the input pin of an adjacent filter in media samples. During connection, the output pin and input pin agree on the connection's allocator object, which is used to create the media samples.

Filters must follow protocols to pass and receive media samples. The connected pins must agree on the allocator to be used, must have a means of passing the data, and must follow the correct procedure for holding on to a sample or releasing it back to the sender.

For the local memory transport, an output pin passes a media sample to the input pin it is connected to by calling the input pin's IMemInputPin::Receive or IMemInputPin::ReceiveMultiple methods, depending on whether it is passing single or multiple samples. Before it can pass this data, however, the output pin must obtain a media sample. The IMemInputPin interface on the input pin provides an IMemAllocator object when requested to provide an allocator. If the output pin is not using its own allocator, or one provided to it from further upstream, it calls the IMemAllocator::GetBuffer method on the input pin to retrieve one.

The input pin can either process the data right away or save it for later processing. In the latter case, it must call the IUnknown::AddRef method on the media sample to prevent the sample from being returned to the allocator. When the output pin has called the input pin's IMemInputPin::Receive method, it must call the IUnknown::Release method to free the sample. If the input pin did not save the sample by calling IUnknown::AddRef, the sample is immediately returned to the allocator.

The output pin can decide not to pass the media sample on to the input, in which case it can just call the sample's IUnknown::Release method without calling the input pin's IMemInputPin::Receive method.

Control Information Data

There are two types of control information which are passed downstream filter to filter:

  • End-of-stream notifications
  • Flushing

End-Of-Stream Notifications

It is important for filters to indicate when there will be no more data in the current set of data. A filter does this by sending an end-of-stream notification to the next filter, which is accomplished by the output pin calling the IPin::EndOfStream method on the downstream filter's input pin.

When a source filter (an originator of data) reaches the end of its data, it calls the IPin::EndOfStream method on all pins connected to its output pins. This mechanism is propagated down the filter graph so that each filter that processes its EndOfStream method in turn calls EndOfStream on the pins connected to its output pins. When the notification reaches the end of the line in the filter graph, the renderer passes an EC_COMPLETE notification to the filter graph manager. The filter graph manager counts the EC_COMPLETE notifications it receives and when all renderer filters have completed, passes the notification to the application. The filter graph manager counts rendered streams by counting the number of filters (not pins) that support IMediaSeeking or IMediaPosition and have a rendered input pin. A rendered input pin is a pin with no corresponding outputs, which can be determined with IPin::QueryInternalConnections. input pins. A renderer input pin returns zero pins when its IPin::QueryInternalConnections is called. Note that the filter, not the pins, support IMediaSeeking in this case.

Although source filters usually originate the end-of-stream notification, it is also possible for other filters to detect this condition and generate the notification downstream. Most notably, this applies to parser filters that connect to asynchronous reader filters (filters implementing the IAsyncReader interface).

For example, the MPEG parser (in the MPEG splitter filter) can detect the end of the stream and when it does, return S_FALSE from the Receive method, which signals the upstream filter to stop sending data until a seek occurs or the filter graph is stopped. In this case, the upstream filter does not need to call EndOfStream. Instead, EndOfStream should be called by the filter detecting the end-of-stream condition (the downstream splitter or parser) before returning from Receive or ReceiveMultiple.

Note that EndOfStream should be serialized with data passed in the stream. It is a single piece of information that must be passed after all the other data in the stream.

Flushing

In the DirectShow filter graph architecture, flushing is a two-stage process. Flushing is not usually initiated as part of normal data flow, but rather as a result of a control action from the filter graph manager. As such, it is an asynchronous event which requires flushing of old data followed by a resynchronization and pushing of new data.

In a flushing operation, first IPin::BeginFlush is called by the source filter on all input pins connected to its output pins. This call is propagated down the graph by all filters to the rendering filter or filters. BeginFlush should flush any pending EndOfStream calls or EC_COMPLETE notifications. After BeginFlush has been called, an input pin should reject all data until its IPin::EndFlush method has been called (this includes end-of-stream notifications). It should also free any connected pins waiting for any of its resources. In the case of the local memory transport, this means that every filter should free any filter waiting for a sample from its allocator. This is usually done by calling IMemAllocator::Decommit on the allocator.

After a filter has called BeginFlush on the pins connected to its output pins, and when it can guarantee that all processing of samples by its pins is complete and no more samples will be processed, it should call EndFlush. For source filters this means shutting down data generation, then calling EndFlush on the pins connected to its output pins. For other filters it means waiting for an EndFlush call (which guarantees that no more samples will be sent) and then waiting for any queues it maintains itself to empty. Because calls can block on downstream filters for the local memory transport model, it is important to wait for queues to empty when EndFlush is called, rather than trying to do so when BeginFlush is called.

Event Notifications

Notification data goes from filters to the filter graph manager and can be passed on to the application. The EC_COMPLETE notification, which is sent from renderers at the end of a data stream, has already been mentioned.

The filter graph manager should not be notified of EC_COMPLETE until a Run command is issued. A renderer filter that has EndOfStream called on its input pin while in a paused state must not notify the filter graph manager until its IMediaFilter::Run method is called. Stop and EndFlush calls cancel any such deferred notifications and allow more data to be subsequently processed by the pin. After notifying the filter graph manager once with EC_COMPLETE, the renderer must not generate another EC_COMPLETE notification before processing a Stop or EndFlush method.

If a running filter graph is paused while at the end of its stream and IMediaFilter::Run is subsequently called, renderers should notify the filter graph manager with EC_COMPLETE again.

Besides EC_COMPLETE, there are many other event notifications, many of which are sent by specialized filters, such as the renderer, to communicate with a host application. Error notifications are another class of notifications that are also sent from filters to the filter graph manager.

The convention for DirectShow filters is that when a filter detects an error, it passes a notification to the filter graph manager by calling the IMediaEventSink::Notify method. Errors in processing data can generate several error events, including the following:

  • EC_STREAM_ERROR_STOPPED, if no more data can be processed.
  • EC_STREAM_ERROR_STILLPLAYING, if data can still be processed.

If processing can no longer continue, the filter graph manager should be notified with EC_STREAM_ERROR_STOPPED and the appropriate convention for the particular transport should be used to notify the upstream output pin. In the case of the local memory transport, this involves returning an error value from IMemInputPin::Receive. In addition to notifying the filter graph manager of the error, a filter should also either call EndOfStream on all the pins connected to its output pins or, if it is a renderer, also notify the filter graph manager with EC_COMPLETE. This ensures the play will complete gracefully.

Errors of this type can be caused by encountering events such as being out of memory or other resource problems. Or they might be caused by other events such as a failure to obtain a buffer when trying to pass data downstream.

On the other hand, when an error occurs but processing can still continue, EC_STREAM_ERROR_STILLPLAYING should be sent to the filter graph manager. In this case, the upstream output pin should not be notified. Specifically, for the local memory transport, the input pin's IMemInputPin::Receive method should return NOERROR when this type of error occurs.

Filter Graph Control Data

Control data originates at the application and is passed to the filter graph manager. At the COM level, this is handled by filter graph manager interfaces in the Control.odl type definition library. Examples of control data are calls to the IMediaControl interfaces, such as IMediaControl::Run, IMediaControl::Pause, and IMediaControl::Stop. The IMediaPosition and IMediaSeeking interfaces provide a means of moving forward or backward in a media stream.

The most important thing to understand about the flow of control data is that it should always pass through the filter graph manager first. This is because there is usually an order that must be followed in controlling the filters in the filter graph to make sure filters are called in the correct order and with regard for internal filter graph states.

Quality Control Data

The DirectShow stream architecture provides a means of gracefully adapting to load differences in the media stream so that rendering of the data is maintained at the highest possible resolution. The IQualityControl interface is used to send quality-control notification messages from a renderer filter either upstream, to be acted on eventually by some filter in the graph, or directly to a designated location. For example, a renderer that is getting too many frames to process can try to get an upstream filter to cut down on the number of frames it is sending. This is usually more efficient than simply dropping frames at the renderer. (A video decompressor filter uses many CPU cycles to decompress frames, so it is better to discard samples before processing them rather than after processing them.) Likewise, when the renderer filter can handle more data, it sends notifications to increase the number of samples.

Quality-control messages are passed upstream by default; if a filter has no registered quality sink, the default action passes the message to the IQualityControl interface of the connected output pin. Internally, the output pin passes the quality-control message to its input pin, if it has one, and the message travels upstream until it reaches a filter that can affect the data stream quality in the requested manner. DirectShow handles this mechanism automatically in the transform base classes.

If a filter can handle the quality notification (by increasing or decreasing the flow) and if it is not appropriate for filters further upstream to take any action, that filter will act on the notification and not pass it on. A filter must pass the quality-control message on if it does not act on the message. It can also pass it on even if it does act on the message. Silently accepting the message without acting on it or passing it on is considered bad behavior, and might damage the performance of the filter graph as a whole.

A quality sink is a feature implemented by the IQualityControl::SetSink method. When this method is called, the filter is instructed not to send messages upstream, but rather to send them to the object passed to the SetSink method. Typically, this object would be a component called a quality-control manager. Such a component would set itself as the sink for all the filters to send the quality-control messages rather than anywhere else. It would then determine whether to route the messages upstream or to take some other action, such as cutting back the video stream to avoid breaking the audio. A quality-control manager can be implemented by using the IQualityControl interface and should be anticipated when writing filters.

Serializing Data

A filter usually has to synchronize two contexts: filter state and data flow. Usually a filter will create a critical section for each context.

The data flow critical section is held during streaming operations. For example, for the local memory transport, this critical section should be held while processing the following methods.

  • IPin::NewSegment
  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream

The filter state critical section is held while processing state changes when the following IBaseFilter methods are called.

  • Stop
  • Pause
  • Run

It is also held during BeginFlush and EndFlush streaming control operations.

During Stop and EndFlush calls, the stream state must be synchronized with the filter state. An example of how to do this is in the base class CTransformFilter. In the case of implementing the Stop method for the local memory transport, for example, the stream must be "released" to avoid deadlocks by decommitting the input allocator pin. This is not required to process EndFlush, because this will have already been done in BeginFlush processing. Once the stream is released, the data flow critical section (as implemented in Receive) can also be locked to synchronize with the stream state.

Note that because Stop requires access to the filter state before synchronizing with the data flow component, these two critical sections must be different.

A filter should not, in general, have its filter state critical section locked while calling methods on other filters. The filter graph synchronizes graph-wide operations such as setting the current position.

IAsyncReader Transport

For source parsing filters, the IAsyncReader interface helps implement a "pull" data flow model, as opposed to the "push" model, in which a thread in the source filter pushes data downstream. The parsing filter is connected downstream to the filter whose pin implements IAsyncReader. In this case, the downstream parsing filter initiates data transfer by calling IAsyncReader methods such as SyncReadAligned. The parsing filter, in this case, creates the thread, pulls data from the source, and pushes it downstream.

Because all data flow activity in this transport is initiated by the downstream filter, several of the protocols mentioned previously operate in reverse. For example:

  • The downstream pin initiates BeginFlush and EndFlush upstream during seek operations.
  • The downstream pin reports errors to the filter graph manager.


Constructing Filter Graphs Using Visual Basic

This article describes how to use ActiveMovie Control type library objects to manage the components of a filter graph — filters and pins — in applications based on Microsoft® Visual Basic®, version 5.x. It also describes the functionality demonstrated by the Builder sample application. This article is written for the Visual Basic developer who is already familiar with application programming in Microsoft Windows®, Windows-based multimedia programming, and Automation features of the Visual Basic programming system.

Contents of this article:

  • About Filter Graphs
  • About the DirectShow Quartz.dll Objects
  • Creating a Filter Graph
  • Generating the Complete Filter Graph
  • Creating a New Filter Graph and Adding Filters
  • Connecting Filter Pins
    • Listing Filters in the Filter Graph
    • Listing Pins Defined for a Filter
    • Explicitly Connecting Two Pins
    • Automatically Connecting Pins
  • Viewing Pin Connection Information
  • Creating a Custom Graph
  • Summary

About Filter Graphs

The Filter Graph Editor provided with the Microsoft DirectShow™ Software Development Kit (SDK) is a graphical tool that creates and manages filter graphs. There are three types of filters: source filters, transform filters, and renderer filters. The Filter Graph Editor is a graphic user interface you use to construct filter graphs by inserting filters and creating connections between them. For example, you can render the filter graph for a specific multimedia source file, such as Dolphin.mov, and see each of the connections in the graph, as in the following example.

Filter Graph Editor example

The same filter graph objects, filters and pins, can be managed from a sample Visual Basic-based application that uses Quartz.dll. For simplicity, the Visual Basic-based application uses list boxes rather than graphical elements to show the parts of the filter graph, and displays information for only one filter and only one pin at a time. (The purpose of the application is not to compete with the Filter Graph Editor, but to demonstrate how to retrieve and manage the same underlying filter graph information using Visual Basic.)

The following illustration shows the same multimedia source file, Dolphin.mov, as depicted by the Visual Basic-based sample application.

VB Builder sample

The list box labeled "Filters in current filter graph" lists the four filters required for this source file. The list box labeled "Pins in selected filter" lists the two pins defined for the selected Indeo Video R4.1 Decompression Filter: the "XForm In" and "XForm Out" pins. The XForm In pin is selected, so the application displays detailed information about this pin, including its direction and connection information.

The remainder of this article discusses the Visual Basic code you can use to retrieve and manage such filter graph information. In addition to the general-purpose code that works with any source input, the application includes a routine that illustrates a more likely use of these properties and methods—building a specific hard-coded filter graph for your Visual Basic-based application.

This article assumes you have already set up your Visual Basic environment to use Quartz.dll. For more information about setting up your Visual Basic environment, see Controlling Filter Graphs Using Visual Basic.

About the DirectShow Quartz.dll Objects

Quartz.dll provides objects that you can use in your Visual Basic-based applications to manage filters and pins. There is an implicit hierarchy among these objects; that is, you must often access the properties of one object to obtain another object. In the following example, an object that appears indented below another indicates that you obtain that lower-level object from a property or method of the higher-level object.

Filter graph object (IMediaControl)
  Filter collection (RegFilterCollection, FilterCollection properties)
    Filter Info object (IFilterInfo or IRegFilterInfo in filter collection)
      Pin collection (Pins property)
        Pin Info object (IPinInfo item in pins collection)

The top-level object in the hierarchy is the filter graph object, or the IMediaControl object, which represents the entire filter graph. You can access two properties of the IMediaControl object to obtain collections of filter objects. The RegFilterCollection property represents the filters registered with the system. The FilterCollection property represents the filters that are part of the filter graph.

As with other collections accessible to Visual Basic, you can access individual items in the collections by using the Visual Basic for each...next statement. The number of items in the collection is indicated by the Count property of the collection.

The filter collection contains IFilterInfo objects. Each IFilterInfo object has a Pins property that represents a collection of pins defined for that filter.

The pins collection contains IPinInfo objects. Each IPinInfo object includes detailed information about that pin, including its media type and its connection to another pin.

To examine a specific pin on a filter in the filter graph, use the following procedure.

  1. Obtain the filter graph object.
  2. Use the IMediaControl.FilterCollection property of the filter graph object to obtain the collection of filters present in the filter graph.
  3. Search through the filter collection for the specific filter.
  4. Use the IFilterInfo.Pins property of the filter object to obtain the collection of pins defined for the filter.
  5. Search through the pins collection for the specific pin.
  6. Examine the properties of the pin object to find connection information and other information for the pin.

Creating a Filter Graph

There are three distinct ways to use Quartz.dll to create a filter graph; each way offers a different amount of control over the filter graph. These range from automatically generating the entire filter graph to specifying every filter and pin connection. The three approaches are as follows:

  • Automatic.

    Generate the complete filter graph from either a multimedia source or a stored filter graph file.

  • Semi-automatic.

    Create a new (empty) filter graph, add one or more filters, then automatically generate all filters and connections needed to render a specific pin.

  • Manual.

    Create a new (empty) filter graph, add individual filters to the graph, and explicitly add connections between pins.

The sample application, Builder, demonstrates all three approaches. The application's "Generate from input file" command on the FilterGraph menu supports the first approach. The New command (empty) on the FilterGraph menu supports the other two approaches.

Generating the Complete Filter Graph

The following code fragment demonstrates how to generate the complete filter graph based on the multimedia source or stored filter graph. After creating an IMediaControl object that is initially "empty," the application calls the IMediaControl.RenderFile method to build up the complete graph:

' fragment from the Filter Graph menu's Generate from input file command
    ' start by creating a new, empty filter graph;
    Dim g_objMC as IMediaControl  ' from the General Declarations section
    ...
    Set g_objMC = New FilgraphManager  ' create the new filter graph
    ' ...
    ' Use the common File Open dialog to let the user select the input file
    CommonDialog1.ShowOpen  ' user selects a source or filter graph
    ' call IMediaControl.RenderFile to add all filters and connect all pins
    g_objMC.RenderFile CommonDialog1.filename  ' generates the complete graph

Creating a New Filter Graph and Adding Filters

The following code fragment demonstrates how to create the new (empty) filter graph object.

' fragment from the Filter Graph menu's New (empty) command handler
    Dim g_objMC as IMediaControl  ' from the General Declarations section
    ...
    Set g_objMC = New FilgraphManager  ' create the new filter graph

When you choose to create an empty filter graph and add individual filters, you must know the filter type. In general, there are three categories of filters: source filters, transform filters, and renderer filters. The procedure for adding source filters uses a different method than the procedure for adding transform and renderer filters.

Add source filters to the filter graph by calling the IMediaControl.AddSourceFilter method and supplying the name of a file of the specified source type or stored filter graph.

The main form of the application includes a button labeled "Add Source Filter..." that uses the common File Open dialog box to query the user for the name of the source file or stored filter graph. The application supplies the specified file as the parameter to AddSourceFilter.

Dim objFilter As Object  ' temporary object for valid syntax; not used

    CommonDialog1.ShowOpen  ' get the name of the source or filter graph file
    g_objMC.AddSourceFilter CommonDialog1.filename, objFilter

Add transform and renderer filters to the filter graph by calling the IRegFilterInfo.Filter method. The IRegFilterInfo object can be obtained from the IMediaControl.RegFilterCollection property, which represents the collection of filter objects registered with the system and available for use.

After creating the filter graph and obtaining the IMediaControl object, use the following procedure to add filters.

  1. Obtain the list of registered filters by getting the IMediaControl.RegFilterCollection property.
  2. Search through the collection for the desired filter. Each element in the collection is an IRegFilterInfo object.
  3. Add the filter to the filter graph by calling the IRegFilterInfo.Filter method.

In the sample program, the list box labeled "Registered filters" contains the names of all the filters that appear in the RegFilterCollection property. The following code fragment illustrates steps 1 and 2 in the previous procedure.

 ' code fragment that populates the registered filter list box
' global variable g_objRegFilters is set to IMediaControl.RegFilterCollection
' Set g_objRegFilters = g_objMC.RegFilterCollection
Dim filter As IRegFilterInfo
    listRegFilters.Clear
    If Not g_objRegFilters Is Nothing Then
        For Each filter In g_objRegFilters  ' for each filter in collection
            listRegFilters.AddItem filter.Name ' add name to the list box
        Next filter
    End If

The sample application contains an Add button that adds the selected registered filter to the current filter graph. The following code fragment illustrates step 3 in the previous procedure.

' code fragment from the event handler for the "Add" button
Dim filter As IRegFilterInfo
' find the selected filter and add it to the graph
' g_objRegFilters is the IMediaControl object RegFilterCollection property
For Each filter In g_objRegFilters
    If filter.Name = listRegFilters.Text Then  ' the selected filter?
        Dim f As IFilterInfo  ' yes
        filter.filter f  ' add to the filter graph, return IFilterInfo f
        If f.IsFileSource Then
            CommonDialog1.ShowOpen
            f.filename = CommonDialog1.filename
        End If
        Exit For
    End If
Next filter

Connecting Filter Pins

After adding individual filters to the filter graph, you can establish connections between the filters by explicitly connecting each pin, or by automatically generating all connections that are needed downstream from a specific pin.

In both cases, you must traverse the hierarchy of DirectShow objects to obtain the IPinInfo object that represents a pin of the filter object. This involves finding the desired filter in the filter collection of the filter graph object, then finding the desired pin in the pin collection of the filter object.

Listing Filters in the Filter Graph

All filters in the filter graph are available in a collection that you can access using the IMediaControl.FilterCollection property.

When the user adds a filter to the filter graph, the application refreshes the list of current filters by using the IMediaControl.FilterCollection property, as shown in the following code fragment.

' refresh the list box that contains the current filters in the graph
    listFilters.Clear
    For Each objFI In g_objMC.FilterCollection
        listFilters.AddItem objFI.Name ' add to list box
    Next objFI

Listing Pins Defined for a Filter

You can access the pins defined for a filter object through the IFilterInfo.Pins property. The Pins property is a collection of individual IPinInfo objects.

After you obtain an individual IPinInfo object from the collection, you can access its properties and call its methods, as shown in the following code fragment.

For Each objPin In g_objSelFilter.Pins
    If objPin.Name = listPins.Text Then  ' selected pin?
        Set g_objSelPin = objPin ' yes, update information
        ' ... perform operations using that pin
    End If
Next objPin

After you have obtained the pin object, you can explicitly connect to one other pin or automatically generate all subsequent pin connections needed to render the pin.

Explicitly Connecting Two Pins

The IPinInfo object provides three methods to connect pins: Connect, ConnectDirect, and ConnectWithType. Connect adds other transform filters as needed, ConnectDirect does not add transform filters, and ConnectWithType performs the connection only if the specified pin matches the specified media type.

The sample application connects two pins using the IPinInfo.Connect method, as shown in the following code fragment. You can call the Connect method from either of the two pins that are to be connected.

' The sample application displays another form to select the second pin
' or "other pin" that is to be connected to this pin.
    frmSelectPin.OtherDir = g_objSelPin.Direction
    Set frmSelectPin.Graph = g_objMC  ' give that form a copy of the graph
    Set frmSelectPin.SelFilter = g_objSelFilter  ' and the current filter
    frmSelectPin.RefreshFilters  ' display available filters to connect
    frmSelectPin.Show 1  ' display the form
    If frmSelectPin.bOK Then ' user has selected one--used OK button
        Dim objPI As IPinInfo
        Set objPI = frmSelectPin.SelPin ' get the new pin from the form
        g_objSelPin.Connect objPI  ' connect the two pins
        RefreshFilters  ' display the latest pin information
    End If

Automatically Connecting Pins

Call the IPinInfo.Render method to automatically generate all portions of the filter graph that are needed downstream from that pin.

The term downstream refers to all connections needed to construct a complete path from that pin to a renderer filter. For example, consider the representation of the filter graph by the Filter Graph Editor, which shows connections as moving from the source filter at the left to the renderer filter at the right. The Render method adds all required filters and connections to the right of the specified pin.

The application includes a Connect Downstream command button. The code that handles this command automatically establishes all pin connections downstream from the specified pin object, as shown in the following code fragment.

' call IPinInfo.Render
' complete the graph downstream from this pin
' g_objSelPin refers to the pin selected in the list box labeled 'Pins'
    g_objSelPin.Render

Viewing Pin Connection Information

When you have obtained a pin object from the collection available from the IFilterInfo.Pins property of the filter object, you can list its connection and other information.

The sample application uses the IPinInfo.ConnectedTo property to obtain the pin object to which it is connected, as shown in the following code fragment.

' Add detailed pin information to the text box on the right
' when the user clicks on a pin in the list box on the left
  Dim strTemp As String
  On Error Resume Next
  Dim objPin As IPinInfo
  For Each objPin In g_objSelFilter.Pins
    If objPin.Name = listPins.Text Then ' selected in list box?
      Set g_objSelPin = objPin  'yes, get all information
      strTemp = ""  ' clear existing displayed pin information
      Dim objPinOther As IPinInfo
      Set objPinOther = objPin.ConnectedTo
      If Err.Number = 0 Then  ' yes, there is a connection
        strTemp = "Connected to pin: " + objPinOther.Name + " "
        Dim objPeer As IFilterInfo
        Set objPeer = objPinOther.FilterInfo
        strTemp = strTemp + " on filter: " + objPeer.Name + " "
        Dim objMTI As IMediaTypeInfo
        Set objMTI = objPin.ConnectionMediaType
        strTemp = strTemp + vbCrLf + "Media Type: " + objMTI.Type
      End If
      If objPin.Direction = 0 Then
        strTemp = strTemp + " " + vbCrLf + "Direction: Input"
      Else
        strTemp = strTemp + " " + vbCrLf + "Direction: Output"
      End If
    txtPinInfo.Text = strTemp
    End If
  Next objPin

Creating a Custom Graph

The sample application featured in this article is similar to the filter graph editor utility, allowing a user to create and manage any filter graph. Most applications will not provide such a general-purpose interface—they are more likely to create only the specific filter graphs needed by the application.

The sample application provides one subroutine that creates such a custom filter graph. The Options menu offers a "Build custom graph" command that calls this subroutine.

The routine that handles this command creates five filter objects and eight pin objects. The routine then connects pins by calling the IPinInfo.Connect method.

The graph connects the following filters: AVI Source, AVI Decompressor, AVI Splitter, Video Renderer, and Audio Renderer. These filters can be connected by reusing just two pin object variables. For clarity, however, each pin object is defined using a name that indicates its position in the filter graph.

The filters and pins are declared as follows:

Dim pSourceFilter As IFilterInfo  ' AVI Source Filter; has two pins
Dim SourceOutputPin As IPinInfo  'Source Filter output pin

Dim pAVISplitter As IFilterInfo ' AVI Splitter
Dim SplitterInPin As IPinInfo   ' AVI Splitter pin "Input"
Dim SplitterOut00Pin As IPinInfo  ' AVI Splitter pin "Stream 00"
Dim SplitterOut01Pin As IPinInfo  ' AVI Splitter pin "Stream 01"

Dim pDECFilter As IFilterInfo  ' AVI Decompressor; has two pins
Dim DECInPin As IPinInfo   'AVI Decompressor pin "XForm In"
Dim DECOutPin As IPinInfo   ' AVI Decompressor pin "XForm Out"

Dim pVidRenderer As IFilterInfo ' Video Renderer, has one pin
Dim VidRendInPin As IPinInfo  ' Video Renderer pin "Input"

Dim pAudioRenderer As IFilterInfo 'Audio Renderer, has one pin
Dim AudioRendInPin As IPinInfo ' Audio Renderer pin "Input"

The application adds the source filter object by calling the IMediaControl.AddSourceFilter method:

' create the source filter using IMediaControl.AddSourceFilter
    CommonDialog1.ShowOpen  ' get the name of the source AVI file
    g_objMC.AddSourceFilter CommonDialog1.filename, pSourceFilter

The application adds the other filter objects by searching for a specific name in the registered filter collection (the filter collection is available from the IMediaControl.RegFilterCollection property), and calling the IRegFilterInfo.Filter method when it finds the specific filter to add:

' add all non-source filters from the collection of registered filters
    Set g_objRegFilters = g_objMC.RegFilterCollection
' use the local subroutine AddFilter to find the filter named
' "AVI Decompressor" in the collection, and set the variable pDECFilter
    AddFilter "AVI Decompressor", pDECFilter

The AddFilter subroutine of the application loops through all the filters present in the collection. When the names match, it calls the IRegFilterInfo.Filter method to add the filter to the filter graph:

Private Sub AddFilter(FName As String, f As IFilterInfo)
' call IRegFilterInfo.Filter

    Set LocalRegFilters = g_objMC.RegFilterCollection
    Dim filter As IRegFilterInfo
    For Each filter In LocalRegFilters
        If filter.Name = FName Then
            filter.filter f
            Exit For
        End If
    Next filter

The application calls similar code for the AVI Compressor, AVI Splitter, Video Renderer, and Audio Renderer filters. After obtaining all the filter objects, the application uses the IFilterInfo.Pins property to find specific pin objects. The code loops through all pin objects in the collection, searching for the specific pin names and setting the individual pin objects when they are found, as shown in the following code fragment.

' Get the source filter pin we need to build the graph
For Each pPin In pSourceFilter.Pins
      Debug.Print pPin.Name
      If pPin.Name = "Output" Then
          Set SourceOutputPin = pPin
      End If
    Next pPin

'Add DEC filter
    AddFilter "AVI Decompressor", pDECFilter
    'Print out list of pins on decompressor filter
    For Each pPin In pDECFilter.Pins
      Debug.Print pPin.Name
      ' save specific pins to connect them
      If pPin.Name = "XForm In" Then
          Set DECInPin = pPin
      End If
      If pPin.Name = "XForm Out" Then
          Set DECOutPin = pPin
      End If
    Next pPin

'Add AVI Splitter
    AddFilter "AVI Splitter", pAVISplitter
    'Print out list of pins on decompressor filter
    For Each pPin In pAVISplitter.Pins
      Debug.Print pPin.Name
      ' save specific pins to connect them
      ' pin 0, pin 1
      If pPin.Name = "input pin" Then
          Set SplitterInPin = pPin
      ElseIf pPin.Name = "Stream 00" Then
          Set SplitterOut00Pin = pPin
      ElseIf pPin.Name = "Stream 01" Then
          Set SplitterOut01Pin = pPin
      End If
    Next pPin

After initializing the eight pin objects, it is a simple matter to call the IPinInfo.Connect method to establish the four connections between them. The following code fragment demonstrates the connection calls.

' connect the pins
' Note:  error handling omitted for brevity
'Connect Source video output pin to AVI splitter input pin
    SourceOutputPin.Connect SplitterInPin
' Connect AVI splitter stream 00 to AVI decompressor
    SplitterOut00Pin.Connect DECInPin
' Connect AVI splitter stream 01 to audio renderer
    SplitterOut01Pin.Connect AudioRendInPin
 'Connect AVI decompressor output pin to Video renderer input pin
    DECOutPin.Connect VidRendInPin

You can establish the connection from either pin; after a successful call to the Connect method, you can access the connection information from either pin object.

Summary

In summary, this article discussed the use of the following DirectShow objects, properties, and methods.
Task | DirectShow properties or methods
Create a new, empty filter graph. | Set objMediaControl = New FilgraphManager.
Generate the complete filter graph for a specific file. | Call the IMediaControl.RenderFile method.
Add a source filter. | Call the IMediaControl.AddSourceFilter method.
Add a renderer or transform filter. | Get the IRegFilterInfo objects using the IMediaControl.RegFilterCollection property; call the IRegFilterInfo.Filter method.
List the pins of a filter object. | Get the IPinInfo objects using the IFilterInfo.Pins property.
Explicitly connect two pins. | Call the IPinInfo.Connect method.
Create all connections from the pin to the renderer filter. | Call the IPinInfo.Render method.


Controlling Filter Graphs Using Visual Basic

This article describes how to use the methods, events, and properties exposed by the Microsoft® DirectShow™ dynamic-link library, Quartz.dll, to render a stream of time-stamped video data in applications based in Microsoft Visual Basic®. This article is written for the Visual Basic developer who is already familiar with Windows®-based application programming, Windows-based multimedia programming, and Automation features of the Visual Basic programming system version 5.0.

Contents of this article:

  • DirectShow Filters and Filter Graphs
  • DirectShow Interfaces, Visual Basic Objects, and Registering Quartz.dll
  • The VBDemo Sample Application
    • Installing the Files
    • Registering Quartz.dll with Visual Basic
    • Preparing to Use the DirectShow Objects
    • Instantiating the Filter Graph
    • Rendering Video
    • Controlling Audio
    • Scaling and Translating the Video Output
    • Tracking Status
    • Getting and Setting the Start Position
    • Getting and Setting the Rate
    • Cleaning Up

DirectShow Filters and Filter Graphs

When multimedia is displayed in an application by using Quartz.dll, the application is using a collection of objects called filters; this collection is sometimes called a filter graph. The following diagram depicts a filter graph that is capable of rendering an audio-video interleaved (.avi) file.

AVI filter graph

In this illustration, the AVI source filter reads the file from disk. The AVI decompressor filter (codec) decompresses the video data as it is passed from the source filter. The codec filter then passes this data to the video renderer. The video renderer, in turn, passes the data to the device in a format that the device understands. The AVI source filter passes the audio data directly to the audio renderer, which, in turn, passes the data to the audio device.

In addition to filters, DirectShow supports an Automation object called the filter graph manager. This object knows about the available filters and understands which filter types are required to render which file formats. The filter graph manager exposes the methods, events, and properties supported by the filters in a given graph. The filter graph manager also exposes its own set of methods, events, and properties. These are exposed by using interfaces, which are simply collections of related methods, events, and properties.

The following table identifies the DirectShow interfaces available in Quartz.dll for use with Visual Basic-based applications, and describes the purpose of each interface.
Interface | Description
IAMCollection | Accesses pin and filter collections.
IBasicAudio | Controls and retrieves current volume setting.
IBasicVideo | Controls a generic video renderer.
IFilterInfo | Retrieves information about a filter and about pin objects in the filter.
IMediaControl | Instantiates the filter graph and controls media flow (running, paused, stopped).
IMediaEvent | Allows customized event handling for events such as repainting, user termination, completion, and so on.
IMediaPosition | Controls and retrieves start time, stop time, rate, and current position.
IMediaTypeInfo | Retrieves the media type and subtype.
IPinInfo | Accesses pin information, such as pin direction and media type, and controls pin connection, disconnection, and rendering.
IRegFilterInfo | Contains information about registered (transform and render) filters.
IVideoWindow | Controls window aspects of a video renderer.

DirectShow Interfaces, Visual Basic Objects, and Registering Quartz.dll

To use the DirectShow interfaces in your Microsoft Visual Basic-based application, you must register the ActiveMovie Control type library in your Visual Basic project.

When you register the ActiveMovie Control type library by using the Visual Basic References dialog box, you are identifying the type library that contains the Automation information that Visual Basic requires. The following illustration shows the References dialog box.

Visual Basic References dialog box

Once the type library is registered, you can use the Object Browser dialog box to view the list of methods, events, and properties associated with a given interface.

Object Browser dialog box

Note The type information in the filter graph manager is organized by interface, rather than object.

The VBDemo Sample Application

This section is based on the VBDemo sample application, which enables the user to do the following:

  • Choose an DirectShow file (.avi, .mpg, or .mov).
  • Display a simple toolbar that lets the user play, pause, or stop the rendering.
  • Display the length of the video and the elapsed time.
  • Display start position and run rate.
  • Display a volume control and a balance control.
  • Position the destination window (a shape control) below all other controls in the main form.

The application, when running a file, appears as follows:

VBDemo sample application

Installing the Files

Before using the DirectShow objects in your Visual Basic-based application, you must install Quartz.dll in the Windows\System directory and ensure that the appropriate entries are made in your system's registry database. Currently, the DirectShow Software Development Kit (SDK) setup program automates this process. To install, start Setup.exe and choose the Runtime option. The dynamic-link library (DLL) will be copied to the correct location, and the registry will be automatically updated.

Registering Quartz.dll with Visual Basic

Open the Visual Basic application and choose the References command from the Tools menu to verify that the files were installed succesfully. (At startup, Visual Basic examines the registry database for registered automation controls and adds their names to the list that appears in this dialog box.) To use the filter graph manager, click the box that appears next to the ActiveMovie Control type library name.

Once Visual Basic registers the type information, you can use the filter graph manager and its associated interfaces in your application.

Preparing to Use the DirectShow Objects

Visual Basic initializes all objects in the VBDemo sample program using the FilgraphManager object, which implements the following interfaces.

  • IBasicAudio
  • IBasicVideo
  • IMediaControl
  • IMediaEvent
  • IMediaPosition
  • IVideoWindow

Each of the interfaces is accessed by a Visual Basic programmable object defined to be of that interface type. The objects in the sample application are defined as global variables in the general declarations section, as shown in the following example.

Dim g_objVideoWindow As IVideoWindow  		'VideoWindow Object
Dim g_objMediaControl As IMediaControl          'MediaControl Object
Dim g_objMediaPosition As IMediaPosition        'MediaPosition Object
Dim g_objBasicAudio  As IBasicAudio             'Basic Audio Object
Dim g_objBasicVideo As IBasicVideo              'Basic Video Object

All the programmable objects are initialized using FilgraphManager, as shown in the following example:

     Set g_objMediaControl = New FilgraphManager
    g_objMediaControl.RenderFile (g_strFileName)    ' name of input file
    ...
    Set g_objBasicAudio = g_objMediaControl
    Set g_objVideoWindow = g_objMediaControl
    Set g_objMediaEvent = g_objMediaControl
    Set g_objMediaPosition = g_objMediaControl

The other interfaces available for use with Visual Basic-based applications are obtained by calling methods that explicitly return the desired interface. The following table summarizes how to obtain these interfaces.
Interface | Methods that return the interface pointer
IAMCollection IPinInfo.MediaTypes, IFilterInfo.Pins, IMediaControl.FilterCollection, IMediaControl.RegFilterCollection
IFilterInfo | First IMediaControl.FilterCollection, then IAMCollection.Item or IPinInfo.FilterInfo
IMediaTypeInfo IPinInfo.ConnectionMediaType
IPinInfo IFilterInfo.FindPin, IAMCollection.Item
IRegFilterInfo | First IMediaControl.RegFilterCollection, then IAMCollection.Item

For a sample that shows how to manipulate these filter and pin interfaces, see Constructing Filter Graphs Using Visual Basic.

Instantiating the Filter Graph

You can use the filter graph manager to render existing files of the following types.

  • .avi (audio-video interleaved)
  • .mov (Apple® QuickTime®)
  • .mpg (Motion Picture Experts Group)

In addition, you can use the filter graph manager to render an existing filter graph by specifying the file that contains that graph as a parameter to the RenderFile method.

Because the filters in a filter graph are dependent on the type of file being rendered, the sample application does not instantiate a filter graph until the user selects a file. The code that handles this selection is embedded in the procedure that opens the file, mnu_FileOpen. This code displays the Show Open common dialog box and stores the selected file name in a g_strFileName variable. After this, the code verifies that the correct file type was chosen. Quartz.dll issues an error message if it is passed a file extension other than .mpg, .avi, or .mov.

Once the g_strFileName variable is set, the application instantiates the filter graph manager and creates the filter graph object. The filter graph manager is instantiated when the Visual Basic keyword New is used to create the AUTOMATION object. The filter graph object is created when the IMediaControl::RenderFile method is called, as shown in the following example.

    'Instantiate a filter graph for the requested
    'file format.

    Set g_objMediaControl = New FileGraphManager
    g_objMediaControl.RenderFile (g_strFileName)

Rendering Video

The IMediaControl interface supports three methods (Run, Pause, and Stop) that an application can call to render, pause, or stop a video stream. After the filter graph object is instantiated, your application can call these methods.

The sample application displays a toolbar from which the user controls video rendering. When the user clicks Run, the Run method is activated and a global Boolean variable (fVideoRun) is set to True. This variable is used in a timer procedure that retrieves the current media position (or elapsed rendering time). If the Pause or Stop button is clicked, this variable is set to False, and the current media position is not retrieved during timer events.

The code that activates the Run, Pause, and Stop methods is found in the Toolbar1_ButtonClick procedure. The toolbar contains buttons that are numbered 1, 3, and 5; the buttons numbered 2 and 4 are separators that provide additional space between the buttons, as shown in the following example.

Private Sub Toolbar1_ButtonClick(ByVal Button As Button)
' handle buttons on the toolbar
' buttons 1, 3 and 5 are defined; 2 and 4 are separators
' all DirectShow objects are defined only if the user
' has already selected a filename and initialized the objects

    ' if the objects aren't defined, avoid errors
    If g_objMediaControl Is Nothing Then
        Exit Sub
    End If

    If Button.Index = 1 Then 'PLAY
        'Invoke the MediaControl Run() method
        'and play the video through the predefined
        'filter graph.

        g_objMediaControl.Run
        g_fVideoRun = True

    ElseIf Button.Index = 3 Then  'PAUSE
        'Invoke the MediaControl Pause() method
        'and pause the video that is being
        'displayed through the predefined
        'filter graph.

        g_objMediaControl.Pause
        g_fVideoRun = False

    ElseIf Button.Index = 5 Then  'STOP

        'Invoke the MediaControl Stop() method
        'and stop the video that is being
        'displayed through the predefined
        'filter graph.

        g_objMediaControl.Stop
        g_fVideoRun = False
        ' reset to the beginning of the video
        g_objMediaPosition.CurrentPosition = 0
        txtElapsed.Text = "0.0"

Controlling Audio

The IBasicAudio interface supports two properties: the Volume property and the Balance property. The Volume property retrieves or sets the volume. In the sample application, this property is bound to the slider control slVolume. The Balance property retrieves or sets the stereo balance. In the sample application, this property is bound to the slider control slBalance.

Note The volume is a linear volume scale, so only the far right side of the slider is useful.

The following example shows the code that adjusts the volume (by setting the g_objBasicAudio.Volume property) is found in the slVolume_Change procedure.

Private Sub slVolume_Change()

    'Set the volume on the slider

    If Not g_objMediaControl Is Nothing Then
    'if g_objMediaControl has been assigned

       g_objBasicAudio.Volume = slVolume.Value

    End If

End Sub

Scaling and Translating the Video Output

The IVideoWindow interface supports the methods and properties you can use to alter the size, state, owner, palette, visibility, and so on, for the destination window. If you are not concerned with the location or appearance of the destination window, you can render output in the default window (which appears in the upper-left corner of the desktop) without calling any of these methods or properties.

The sample application moves the destination window to a position below the other controls on its main form. In addition to moving the window, the sample application alters the window style by removing the caption, border, and dialog box frame. To do this, set the g_objVideoWindow.WindowStyle property to 0x06000000. This corresponds to the logical OR operation of the values WS_DLGFRAME (0x04000000) and WS_VSCROLL (0x02000000). For a complete list of window styles and corresponding values, see the Winuser.h file in the Microsoft® Platform SDK.

To move the destination window onto the form, specify a new position by setting the Top and Left properties of g_objVideoWindow. The Top and Left properties are set to correspond to the upper-left corner of a blank control with a rectangular shape, a placeholder of sorts, that appears on the form. The ScaleMode property for the form was set to 3, which specifies units of pixels. This allows the form properties and DirectShow object properties to be used without conversion. The DirectShow object properties are also expressed in pixels. The default units for a Visual Basic form are twips.

The sample application uses the left top of the placeholder rectangle, then resizes the shape based on the size of the specified video. The application determines the required size of the rectangle by retrieving the source video width and height. These values correspond to the VideoWidth and VideoHeight properties of the g_objBasicVideo object.

In addition to setting the Top and Left properties, it is necessary to identify the form of the application as the new parent window by passing the window handle of the form, hWnd, to the g_objVideoWindow.Owner property. If the handle is not passed, the destination window will appear relative to the desktop and not the form.

The following example shows the tasks that are accomplished in the mnu_FileOpen procedure.

    Set g_objVideoWindow = g_objMediaControl
    g_objVideoWindow.WindowStyle = CLng(&H6000000)   ' WS_DLGFRAME | WS_VSCROLL
    g_objVideoWindow.Left = CLng(Shape1.Left)   ' shape is a placeholder on the form
    g_objVideoWindow.Top = CLng(Shape1.Top)
    Shape1.Width = g_objVideoWindow.Width    ' resize the shape given the input video
    Shape1.Height = g_objVideoWindow.Height
    g_objVideoWindow.Owner = frmMain.hWnd    ' set the form as the parent

The following example shows how the ScaleMode property is initialized in the Form_Load procedure.

' code fragment from the Form_Load procedure
' ...
    frmMain.ScaleMode = 3    ' pixels
' ...

Avoid attempting to scale the destination window by setting the Width and Height properties for the g_objVideoWindow object, because performance suffers considerably.

Tracking Status

The g_objMediaPosition object exposes a number of properties that you can use to retrieve or set the current position, stop point, duration, and rate. When the user selects a file, the sample application retrieves and displays the duration, starting position, and rate. The corresponding code appears in the mnu_FileOpen procedure, as shown in the following example.

    Set g_objMediaPosition = g_objMediaControl
    g_dblRunLength = g_objMediaPosition.Duration
    txtDuration.Text = CStr(g_dblRunLength)   ' display the duration
    g_dblStartPosition = 0.0
    txtStart.Text = CDbl(g_dblStartPosition)   ' display the start time
    g_dblRate = g_objMediaPosition.Rate
    txtRate.Text = CStr(g_dblRate)

The current position is also displayed, using a timer that is started when the user clicks Run. When the user clicks Run, a global Boolean variable, g_fVideoRun, is set to True, indicating that the program should retrieve and display the current media position, which is expressed as the elapsed rendering time from the absolute beginning of the multimedia stream.

If Pause or Stop is clicked, the variable is set to False, and the current media position is not retrieved. The corresponding code (which displays the current position) appears in the Timer1_Timer procedure, as shown in the following example.

Private Sub Timer1_Timer()
    'Retrieve the Elapsed Time and
    'display it in the corresponding
    'textbox.
Dim Dbl As Double

    If g_fVideoRun = True Then
        Dbl = g_objMediaPosition.CurrentPosition
        If Dbl < g_dblRunLength Then
            txtElapsed.Text = CStr(Dbl)
        Else
            txtElapsed.Text = CStr(g_dblRunLength)
        End If
    End If
End Sub

Getting and Setting the Start Position

The sample application uses the IMediaPosition.CurrentPosition property to let the user adjust the point at which the video begins rendering. If the user enters a new CurrentPosition and then clicks Play, the video begins rendering at the frame whose timestamp is closest to the requested time.

In addition to adjusting the starting time, the user can jump to new frames while the video is rendering by specifying a new value in the corresponding text box and then pressing ENTER.

The code that handles the CurrentPosition property is found in the following example of the txtStart_KeyDown procedure.

 Private Sub txtStart_KeyDown(KeyCode As Integer, Shift As Integer)
' handle user input to change the start position
If KeyCode = vbKeyReturn Then
    If g_objMediaPosition Is Nothing Then
        Exit Sub
    ElseIf CDbl(txtStart.Text) > g_dblRunLength Then
        MsgBox "Specified position invalid: re-enter new position."
    ElseIf CDbl(txtStart.Text) < 0 Then
        MsgBox "Specified position invalid: re-enter new position."
    ElseIf CDbl(txtStart.Text) <> "" Then
        g_dblStartPosition = CDbl(txtStart.Text)
        g_objMediaPosition.CurrentPosition = g_dblStartPosition
    End If
End If
End Sub

Getting and Setting the Rate

The sample application uses the IMediaPosition.Rate property to let the user adjust the rate at which the video is rendered. This rate is a ratio with respect to typical playback speed. For example, a rate of 0.5 causes the video to be rendered at one-half its typical speed, and a rate of 2.0 causes the video to be rendered at twice its typical speed.

Unlike the CurrentPosition property, which can be set while the video is being rendered, the Rate property must be set prior to rendering.

Note The sound track can be disabled for some videos when the rate is less than 1.0.

The code that handles the Rate property is found in the following txtRate_KeyDown procedure.

Private Sub txtRate_KeyDown(KeyCode As Integer, Shift As Integer)
' DirectShow VB sample
' handle user updates to the Rate value
If KeyCode = vbKeyReturn Then
    If g_objMediaPosition Is Nothing Then
        Exit Sub
    ElseIf CDbl(txtRate.Text) < 0# Then
        MsgBox "Negative values invalid: re-enter value between 0 and 2.0"
    ElseIf CStr(txtRate.Text) <> "" Then
        g_dblRate = CDbl(txtRate.Text)
        g_objMediaPosition.Rate = g_dblRate
    End If
End If
End Sub

Cleaning Up

Each time your application uses the Visual Basic Set statement to instantiate a new DirectShow object, it must include a corresponding Set statement to remove that object (and its corresponding resources) from memory prior to shutdown. For example, in the mnu_FileOpen procedure, a new g_objBasicAudio object is instantiated with the following syntax.

Set g_objBasicAudio = g_objMediaControl

When the user selects Exit from the File menu, a corresponding Set statement removes this object:

Set g_objBasicAudio = Nothing


List of Filters and Samples

Microsoft® DirectShow™ provides filters and samples as part of the DirectShow Software Development Kit (SDK). The filters are supplied as binary code only and are listed among the filters available in the Filter Graph Editor when you choose Insert Filters from the Graph menu. A sample filter includes source code and you must build and register it before it will appear in the Filter Graph Editor. In addition to sample filters, the SDK contains sample applications that demonstrate how to use filters.

See the following sections for a list of filters, sample filters, and sample applications supplied with DirectShow:

  • Filters
  • Sample Filters
  • Sample Applications

Filters

The DirectShow SDK provides the following filters:

  • ACM Audio Compressor
  • Analog Video Crossbar
  • Audio Capture
  • Audio Renderer
  • AVI Compressor
  • AVI Decompressor
  • AVI Draw
  • AVI MUX
  • AVI Splitter
  • AVI/WAV File Source
  • Color Space Converter
  • Cutlist File Source
  • DSound Audio Renderer
  • DV Muxer
  • DV Splitter
  • DV Video Decoder
  • DV Video Encoder
  • DVD Navigator
  • File Source (Async)
  • File Source (URL)
  • File Stream Renderer
  • File Writer
  • Full Screen Renderer
  • Indeo 4.3 Video Compression
  • Indeo 4.3 Video Decompression
  • Indeo 5.0 Audio Decompression
  • Indeo 5.0 Video Progressive Download Sources
  • Indeo 5.0 Video Compression
  • Indeo 5.0 Video Decompression
  • Internal Script Command Renderer
  • Line 21 Decoder
  • Lyric Parser
  • MIDI Parser
  • MIDI Renderer
  • MPEG Audio Decoder
  • MPEG Video Decoder
  • MPEG-1 Stream Splitter
  • Multi-File Parser
  • Overlay Mixer
  • QuickTime Decompressor
  • QuickTime Movie Parser
  • SAMI (CC) Parser
  • TrueMotion 2.0 Decompressor
  • TV Audio
  • TV Tuner
  • VFW Video Capture
  • VGA 16 Color Ditherer
  • Video Renderer
  • WAVE Parser
  • WDM Video Capture

Sample Filters

The DirectShow SDK provides the following sample filters:

  • Async Sample (Asynchronous Reader Filter)
  • Ball Sample (Bouncing Ball Filter)
  • Contrast Sample (Video Contrast Filter)
  • Dump Sample (Dump Filter)
  • EzRGB24 Sample (Image Effect Filter)
  • Gargle Sample (Gargle Filter)
  • Inftee Sample (Infinite-Pin Tee Filter)
  • MPGAudio Sample (MPEG Audio Decoder Filter)
  • MPGVideo Sample (MPEG Video Decoder Filter)
  • Nullip Sample (Null In Place Filter)
  • Nullnull Sample (Minimal Null Filter)
  • Scope Sample (Oscilloscope Filter)
  • Synth Sample (Audio Synthesizer Filter)
  • SampVid Sample (Video Renderer Filter)
  • TextOut Sample (Text Display Filter)
  • Vcrctrl Sample (VCR Control Filter)
  • VidCap Sample (Video Capture Filter)

Sample Applications

The DirectShow SDK provides the following sample applications:

  • AMCap Sample (DirectShow Capture Application)
  • CLText Sample (Text Cutlist Application)
  • CPlay Sample (C/COM-based Media Player Application)
  • Dvdsampl Sample (DVD Player Application)
  • InWindow Sample (Window Playback Application)
  • IPlay Sample (Indeo Player Application)
  • MFCPlay Sample (C++/COM-based Media Player Application)
  • MPEGProp Sample (MPEG Property Page Display Application)
  • PlayFile Sample (Simple Playback Application)
  • PID Sample (Plug-In Distributor Application)
  • ShowStrm Sample (Multimedia Streaming Application)
  • Simplecl Sample (Cutlist Application)
  • VidClip Sample (Video Editing Application)
  • Visual Basic-Based ActiveX Player
  • Visual Basic-Based Filter Graph Builder
  • Visual Basic-Based Filter Graph Player
  • Visual Basic-Based Player


About the DirectShow Filter Graph Editor

The Microsoft® DirectShow™ SDK provides the Filter Graph Editor tool (also referred to as "Graphedt.exe" or "GraphEdit") that you can use to create, edit, and save filter graphs. This article introduces GraphEdit, and discusses the purpose of the buttons on the GraphEdit toolbar in About the GraphEdit Toolbar. See Using the Filter Graph Editor for detailed information about how to use GraphEdit.

The DirectShow architecture uses filter graphs to manage multimedia streams in Microsoft Windows® 95 and Microsoft Windows NT®. A filter graph consists of a set of filters connected in sequence; the sequence typically includes a source filter reading from a media file, a transform filter, and a renderer, although your graph will vary depending on its purpose. A graph to play a media file with video and audio typically includes a source filter, a stream splitter, a video decompression filter, and appropriate renderers. The following screen shot shows a filter graph in GraphEdit that includes both audio and video streams.

Filter graph with audio and video

GraphEdit helps you visualize a filter graph as shown in the preceding screen shot. A rectangle represents a filter, with tiny attached squares representing pins. Pins are key to understanding DirectShow, from format negotiation to data transportation. Arrows joining the pins represent data flow paths, much like a pipe directs the flow of water. GraphEdit displays input pins on the left side of the filter's rectangle and output pins on the right side. Output pins might not be present until you connect an input pin. Input pins only connect to output pins, and vice versa.

GraphEdit indicates the audio renderer that provides the clock for the filter graph by a small yellow-filled clock symbol within the audio renderer's rectangle. You can disable the clock by canceling the selection of Use Clock on the Graph menu. Graphs without clocks play the audio and video streams as fast as possible, independently of each other.

The following filter graph plays back audio from the Audio Synthesizer source filter (Synth). Synth generates its own audio data rather than reading data from a file. The audio renderer's clock is enabled in this filter graph.

Audio Synthesizer filter graph

The following filter graph is one of the simplest possible filter graphs. The Bouncing Ball source filter generates video data and the video renderer filter displays it.

Bouncing Ball filter graph

About the GraphEdit Toolbar

GraphEdit's toolbar appears beneath the menu bar. It provides shortcut commands for opening new filter graphs, saving the current filter graph, and playing, pausing, or stopping the multimedia source file. You can display or hide the toolbar by clicking Toolbar on the View menu.
Button | Effect
New | Creates a new, empty filter graph.
Open | Opens an existing multimedia source file or an existing filter graph (.grf) file.
Save | Saves the current filter graph as a filter graph (.grf) file.
Print | Prints the current filter graph.
Play | Plays the multimedia source using the current filter graph.
Pause | Pauses play of the multimedia source.
Stop | Stops play of the multimedia source.
Help | Displays Help information for GraphEdit.


Using the Filter Graph Editor

This article steps through how to open and use the Filter Graph Editor (GraphEdit) to create filter graphs and to play them back. See About the DirectShow Filter Graph Editor for an introduction to GraphEdit.

Contents of this article:

  • Starting GraphEdit
  • Creating a New Filter Graph
  • Running and Editing a Filter Graph
  • Viewing Properties in GraphEdit

Starting GraphEdit

Start GraphEdit in one of the following ways.

  • Click Start, and then point to Programs. On the DirectX Media SDK version 5.x submenu, click GraphEdit.
  • Open the DXMedia\Tools folder (assuming the default installation directory for the DirectX media SDK) and double-click the Graphedt icon.
  • Drag and drop a multimedia file, such as .avi or .mpg, onto the Graphedt icon.

Creating a New Filter Graph

This section discusses ways to create a new filter graph using GraphEdit. It contains the following topics:

  • Drag Files Onto GraphEdit
  • Use the Open Command
  • Use the Render Media File Command
  • Manually Build a Filter Graph

Drag Files Onto GraphEdit

If GraphEdit is not running, you can drag a multimedia file, such as .avi or .mpg, onto the Graphedt icon and GraphEdit will run and automatically build the filter graph for the media file.

If GraphEdit is already running, drag a multimedia file into its client area to have it automatically build the filter graph.

Use the Open Command

Choose the Open command from the GraphEdit File menu, or choose the Open button from the GraphEdit toolbar, to open a media file or saved filter graph file (.grf). GraphEdit automatically generates the complete filter graph.

Use the Render Media File Command

You can use the GraphEdit Render Media File command to automatically generate the complete filter graph for a multimedia source.

To generate a complete filter graph for a given source file perform the following steps:

  1. On the File menu, click Render Media File.
  2. From the "Select a file to be rendered" dialog box, choose a multimedia source file, such as a .avi, .mpg, or .wav file.
  3. Click Open.

GraphEdit adds and connects all filters needed to render the source file automatically.

Manually Build a Filter Graph

To create an empty filter graph and manually add filters and connections, perform the following steps. This example assumes you want to play a file from your hard disk.

See About the DirectShow Filter Graph Editor for information about how GraphEdit represents filters, pins, and connections graphically.

  1. On the File menu, click New to create a new filter graph.
  2. On the Graph menu, click Insert Filters. GraphEdit displays the "Which filters do you want to insert?" dialog box, which contains a list of filter categories.
  3. Click the plus symbol (+) immediately to the left of the DirectShow Filters category to see the drop-down list of filters. The plus symbol becomes a minus symbol (–) when the list is expanded, as the following illustration shows. Click the minus symbol to contract the list.

    "Which filters do you want to insert" dialog box

  4. Select File Source (Async) from the filter list (scrolling if necessary) and click the Insert Filters button. Because the Asynchronous File Source filter requires an input file, GraphEdit displays the "Select an input file for this filter to use" dialog box.
  5. Select a multimedia file that you have on your hard disk (for this example, assume you chose a file called Jupiter.avi). Click the Open button. GraphEdit inserts a rectangle labeled Jupiter.avi in its client area. This rectangle represents the Asynchronous File Source filter and has a small square attached to its right side, labeled Output, which represents the filter's output pin.
  6. At this point, you could right-click the Async filter's output pin and choose Render from the resulting shortcut menu to have GraphEdit render the rest of the filter graph for you automatically. Instead, continue by inserting a few more filters manually. From the "Which filters do you want to insert?" dialog box, select the AVI Splitter filter. Like the File Source (Async) filter, this filter is listed in the DirectShow Filters category. Click Insert Filters and GraphEdit inserts the AVI Splitter filter in its client area. This filter has one input pin, shown by a small square attached to the left side of the AVI Splitter filter rectangle.
  7. Connect the Async File Source filter to the AVI Splitter filter as follows.
    1. Click the Async filter's Output pin and drag to the AVI Splitter's input pin. GraphEdit creates an arrow representing the connection between the filters, and moves the arrow in response to the dragging operation.
    2. Release the mouse button when the tip of the arrow head is over the small square representing the AVI Splitter's input pin. The interior of the pin's square turns black when the arrow head is in a valid location. After you've connected these filters, the AVI Splitter filter sprouts one output pin for each stream in the file. If Jupiter.avi contains an audio stream and a video stream, the pins will be labeled Stream 01 and Stream 00.
  8. At this point, you could right-click each of the AVI Splitter's output pins in turn and choose Render to have GraphEdit render the rest of the filter graph for you automatically. Instead, continue by inserting one more filter manually. From the "Which filters do you want to insert?" dialog box, open the Audio Renderers filter category by clicking on the plus symbol (+) immediately to the left of the Audio Renderers label. Select a default audio renderer (for example, the Default WaveOut Device or Default DirectSound Device if available) and click the Insert Filters button.
  9. Connect the AVI Splitter's Stream 01 output pin by dragging from that pin and releasing the mouse button when the arrowhead is over the input pin of the audio renderer.
  10. You could continue to insert filters manually, much in the same way that you have so far. Instead, right-click the AVI Splitter's Stream 00 output pin and choose Render to have GraphEdit build up the rest of the filter graph for you automatically.

Running and Editing a Filter Graph

After you've built a filter graph as outlined in Creating a New Filter Graph, you can play or pause the filter graph. To do so, select Play or Pause from the GraphEdit Graph menu.

Play plays the filter graph. If the graph includes the video renderer filter, any video data (such as a movie), plays in the video renderer window. If the filter graph includes an audio renderer, any sound associated with the movie plays as well. Pause cues up data in the filter graph and displays the first frame of video data, enabling playback to happen quickly if you later select Play. When the filter graph is playing or paused, you can select Stop from the Graph menu to stop playback.

You can also play, pause, or stop the filter graph by choosing the appropriate buttons from the GraphEdit toolbar. See About the GraphEdit Toolbar for more information.

You can edit the filter graph when it is stopped. Select either a filter or connection between filters by clicking the filter or connecting arrow. GraphEdit highlights the object by placing a blue border around it. You can highlight multiple objects at once by clicking outside an object and dragging diagonally to create a selection rectangle. When you release the mouse button, objects contained within the selection rectangle are highlighted. Press the DELETE key to delete a highlighted object or group of objects. Insert new filters by choosing Insert Filters from the Graph menu, and make new connections as outlined in Manually Build a Filter Graph.

You can drag filters in the GraphEdit client area if you want to reposition them. You might want to do this to make the filters fit on one screen without scrolling.

Viewing Properties in GraphEdit

GraphEdit enables you to view the properties of filters, pins, and connections. To view the properties of an object such as a filter, right-click the filter and choose Properties from the resulting shortcut menu. The options provided by a property sheet vary depending on the filter, pin, or connection. Typically, the property sheet for a filter includes tabs for its pins.


COM Overview

The Component Object Model (COM) is a binary standard that defines how objects are created and destroyed and, most importantly, how they interact with each other. As long as applications follow the COM standard, different applications from different sources can communicate with each other across process boundaries. People use COM to make communication with other applications easy.

Because COM is a binary standard, it is language independent. You do not have to use C++ to implement COM. You can use any language that supports tables of function pointers.

A COM interface is a collection of logically related methods that express a single functionality. For example, the IAsyncReader interface enables reading of MEDIATYPE_Stream data. All COM interfaces derive from IUnknown, and all are named by a globally unique interface identifier (IID).

A COM class is an implementation of one or more COM interfaces, and a COM object is an instance of a COM class. A Microsoft® DirectShow™ filter, for example, is a COM object. Each object has a globally unique class identifier (CLSID).

Globally unique identifiers (GUIDs) are extremely long integers that identify COM interfaces and objects, and are used to eliminate name collisions across applications.

All access to a COM object is through pointers to its interfaces. Interface methods are purely virtual and are stored in a table called a vtable. The interface pointer points to the vtable's beginning. A COM interface defines the parameter types and the syntax for each of its methods. The COM class provides an implementation for each method of the interface.

Once a COM class has been defined and assigned a CLSID, you can create an instance of the object. There are several ways to create an instance of the class, including using the COM CoCreateInstance or IClassFactory::CreateInstance methods , or the C++ new operator.

When you create an instance of an object, the call returns a pointer to one of the object's interfaces. Once you have an initial pointer to an interface on the object, you can use the IUnknown::QueryInterface method to find out whether the object supports another specific interface, and, if so, to get a pointer to that interface. COM supplies many standard interfaces that support data storage and transfer, notification, and basic connectivity with other objects, including IStream, IPropertyPage, and IMoniker. DirectShow, in turn, adds its own COM interfaces, such as IAMDirectSound, that clients of DirectShow objects can query for to determine if the object supports a particular functionality. To use COM interfaces, clients must know the interface definitions and the IID to query for (IID_interfacename). For example, assume you have a pointer to a COM object's IUnknown interface in the pUnknown variable. You can query to see if the object supports IAMDirectSound with the following code.

hr=pUnknown->QueryInterface(IID_IAMDirectSound, (void **)&pIAMDSound);

IUnknown is the basic COM interface on which all others are based. IUnknown has three methods—QueryInterface, AddRef, and Release—that implement interface querying and reference counting. All COM interfaces inherit these three methods from IUnknown.

Reference counting is the technique by which an object (or, strictly, an interface) decides when it is no longer being used and can therefore destroy itself. COM objects are dynamically allocated from within the object and multiple clients can use them simultaneously. To avoid wasting memory, the COM object must keep track of the number of clients using it, and destroy itself when clients no longer need it. The number of clients using the object is maintained in the reference count. Every time a new interface pointer to the COM object is created, the client using the object must increase the reference count by calling AddRef on the interface pointer. Every time a client destroys an interface pointer to the object, it must first decrease the reference count by calling Release on the interface pointer.

Binding associates a method with a pointer to its memory location. At compile time, a COM object's client is bound to the vtable locations of the object's interface methods. This is called early binding. With some languages, such as Microsoft® Visual Basic®, a vtable interface is difficult to access. Dispatch interfaces, identified by dispatch identifiers (DISPIDs), allow clients to access member functions not by position in a vtable, but by a human-readable name. Dispatch interfaces are accessed through the COM IDispatch interface and its Invoke method, which converts the names of the dispatch interface's functions to DISPIDs. The client retrieves the DISPIDs at run time. This is called late binding. To allow late binding, a COM object must implement the IDispatch interface and a mapping of function names and function parameters to a set of DISPIDs. In DirectShow, CBaseDispatch implements the IDispatch interface.

Marshaling is the process of passing function arguments and return values among processes and machines. An in-process proxy packages arguments for the member function of an object in another process, and generates a remote procedure call to the other process. In the other process, a stub receives the call and unpacks the data, and calls the object through its interface. Dispatch interfaces do not need proxies and stubs and so are easier to use than vtable interfaces in out-of-process applications. Vtable interfaces, however, can be considerably faster, particularly in in-process applications. You can also write dual interfaces that have both tables of function pointers and dispatch interfaces. Dual interfaces can be nearly as fast as vtable interfaces, while allowing the flexibility of dispatch interfaces.

For more information about how DirectShow uses COM, see DirectShow and COM. For general information about COM, see the "COM" section in the Microsoft Platform SDK, or an introductory book such as ActiveX OLE by David Chappell.


Overview of DVD Interfaces and Data Types

This article provides an overview of the DVD interfaces and data types used in Microsoft® DirectShow™.

Contents of this article:

  • DVD Application-Level Interfaces
  • DVD Decoder Filter Interfaces
  • DVD Filter Graph Media Types, Formats, and Events

DVD Application-Level Interfaces

The following list shows DVD interfaces that media developers can use to create applications.

IAMLine21Decoder
Provides access to closed captioning information and settings. Closed captioning information is transmitted in the vertical blanking interval (VBI) of television signals, specifically on line 21 (Line21) of field 1 in the VBI.
IDvdControl
Controls the playback and search mechanisms of a DVD-Video disc that contains one or more video movies.
IDvdGraphBuilder
Enables the DVD application writer to easily build a filter graph for DVD-Video playback.
IDvdInfo
Enables an application to query for attributes of available DVD-Video titles and the DVD player status. This interface also allows for control of a DVD player beyond Annex J in the DVD specification.
IMixerPinConfig
Exposed on the input pins of overlay mixer filters and contains methods that manipulate video streams in various ways. The overlay mixer filter contains multiple input pins that are dynamically created as video input streams are added.

DVD Decoder Filter Interfaces

The following list shows DVD interfaces that developers can use to set and retrieve device and sample properties.

IKsPropertySet
Enables you to set and retrieve device properties. Use this interface to set and retrieve any of the properties from the following list.
  • DVD Copy Protection Property Set — These properties provide authentication of copy protection information from hardware or software decrypters.
  • DVD Subpicture Property Set — These properties control the color, contrast, and output of the subpicture display.
  • DVD Time Stamp Rate Change Property Set — These properties enable you to change DVD playback rate, by modifying timestamps between input and output pins on two filters.
IMediaSample2
Enables you to set and to retrieve sample properties. This interface is derived from the IMediaSample interface and uses the following data types:
  • AM_MEDIA_TYPE structure — Describes a media sample type. This structure can include the following substructures.
    • VIDEOINFOHEADER2 structure — Describes the bitmap and color information for a video image, including interlace, copy protection, and pixel aspect ratio information.
    • MPEG2VIDEOINFO structure — Describes an MPEG-2 video stream.
  • AM_SAMPLE_PROPERTY_FLAGS enumerated type — Indicates values for the dwSampleFlags member of the AM_SAMPLE2_PROPERTIES structure.
  • AM_SAMPLE2_PROPERTIES structure — Generic media sample properties structure.
IVPConfig
Enables a video port (VP) mixer filter to communicate with a VP driver (decoder), to set and retrieve configuration information. This interface assumes that the mixer filter creates the video port.
IVPNotify
Enables you to control the properties of a filter that uses a video port. This interface derives from the IVPBaseNotify interface.

DVD Filter Graph Media Types, Formats, and Events

The following articles provide more information about DVD:

  • DirectShow DVD Support — Provides a diagram of a DVD filter graph and outlines the media types and data formats used in each connection.
  • DVD Event Notification Codes — Describes DirectShow system-defined events, which filters in the filter graph pass to the filter graph manager. Filters pass these events to the filter graph manager by using the IMediaEventSink::Notify method, and the application retrieves them with the IMediaEvent::GetEvent method.


About WDM Video Capture

This article provides an overview of video capture using the Microsoft® Windows® 98 and Windows NT® Driver Model (WDM) and Microsoft DirectShow™. It describes the close association between WDM video capture and DirectShow.

This article also briefly describes the close association between the Stream class and WDM Connection and Streaming Architecture (CSA) and video capture minidrivers (which are clients of the Stream class driver). However, you should have a basic understanding of these topics before reading this article. For background information, see http://www.microsoft.com/hwdev/pcfuture/.

Contents of this article:

  • A Brief History of Windows Video Capture
  • WDM Overview
  • WDM Video Capture Architecture
  • Filter Graph Configuration
  • Conclusion
  • New WDM Capture Interfaces and Filters

A Brief History of Windows Video Capture

Microsoft released Video for Windows 1.x in November 1992 for Windows 3.1 and optimized it for capturing movies to disk. Since then, video capture rates have risen dramatically due to use of the PCI bus, bus mastering controllers, NT striped sets, Fast/Wide SCSI, and direct transfer of captured video from adapter memory to disk without data copies. Despite capture rates that now exceed 20 MB per second, and a large number of clients for Video for Windows, deficiencies in the Video for Windows architecture exposed by the emergence of video conferencing required development of a new video capture technology.

The Video for Windows architecture lacks features important to video conferencing, television viewing, capture of video fields, and additional data streams such as vertical blanking interval (VBI). Vendors have extended Video for Windows by implementing proprietary extensions, which are product specific, to circumvent these limitations. However, without standardized interfaces, applications that use these features must include hardware-dependent code. The tight coupling between Video for Windows capture drivers and display drivers means that changes made to capture drivers require changes to display drivers as well.

In addition, the Video for Windows interface, AVICap, doesn't work well with DirectShow because AVICap allocates buffers. If DirectShow is accessed through AVICap, the buffers must be copied at the transition point, which is very inefficient. With the integration of digital versatile disc (DVD), MPEG decoders, video decoders and tuners, video port extensions (VPE), and audio codecs on single adapters, a unified driver model that supports all of these devices and handles resource contention is needed.

WDM Overview

DirectShow supplies backward compatibility for Video for Windows applications without the shortcomings of Video for Windows. WDM video capture aims to provide additional support for the following: USB conferencing cameras, 1394 DV devices, desktop cameras, TV viewing, multiple video streams support and VPE capture support. This support is provided through kernel-based streaming.

WDM-based streaming extends the nonkernel streaming of DirectShow by providing a kernel connection. Streaming services are processed by the WDM Streaming Class Driver and other cross-process system software components. The WDM Streaming Class Driver is also responsible for calling a minidriver, which is a hardware-specific dynamic-link library (DLL) provided by IHVs to support device-specific controls. The minidriver and the Microsoft-provided WDM Streaming Class Driver work together to provide low-level services for the lowest latency streaming, and DirectShow provides the higher-level features specific for your application. Because the Stream class supports a uniform streaming model for standard and custom data types, and supports data transfer between kernel drivers without requiring a transition to user mode, it is a highly efficient mode to use.

Previously, DirectShow filters transmitted data to and from the kernel whenever necessary to achieve things like decompression or rendering. Unfortunately, each of these transitions of the data stream from user mode to kernel mode was time-consuming because of the transition itself, and because of parameter validation, security validation, and possibly data copying, that must occur.

Through kernel streaming, a stream makes fewer transitions between user and the kernel mode. It can be either partially or entirely produced and consumed in kernel mode. When streams are processed in kernel mode, the DirectShow filters merely expose control mechanisms to direct the streams. This greatly reduces the overhead associated with numerous transitions between modes.

Kernel streams can pass data to the filter graph at appropriate points, depending on the application. The following diagram illustrates the transition to user mode.

During video capture, the stream class passes uncompressed video data back to the video capture filter for writing or rendering. Also, because kernel streaming supports multiple streams, other types of data contained in the stream, such as timecode or closed captioning, could be passed up simultaneously.

WDM Video Capture Architecture

The following diagram shows the three basic components of the WDM capture architecture.

WDM capture architecture

Because the WDM capture architecture was designed to integrate smoothly with DirectShow, it is straightforward to build capture graphs in DirectShow by using WDM capture filters that send control messages from DirectShow into the streaming class. The Ksproxy.ax, Kstune.ax, and Ksxbar.ax filters, which are scheduled to ship in the Windows 98 Device Driver Kit (DDK), enable WDM streaming data, such as data from Universal Serial Bus (USB) conferencing cameras, 1394 DV devices, TV viewing, and desktop cameras, to be easily controlled and sent by the Stream class to the DirectShow capture graph. The following diagram demonstrates how these components are integrated into the basic architecture.

Components of WDM capture architecture

In this diagram, the Ksproxy.ax, Kstune.ax, Ksxbar.ax, and other DirectShow filters communicate directly with the Stream class. The Microsoft WDM Stream class, through its participation in CSA, transports high-bandwidth, time-stamped, latency-sensitive data streams between kernel mode components or between kernel mode drivers and user-mode components. Through CSA, the Stream class works well with DirectShow in that it shares media types, has similar streaming states (Stop, Pause, and Run), and shares the same concept of pins and connections. This provides an easy transition of data from the Stream class to the filters in the filter graph.

The Ksproxy.ax, Kstune.ax, and Ksxbar.ax filters also have supporting minidrivers (or one minidriver that supports all three). Video capture minidrivers are clients of the Stream class and control hardware devices that produce streams of video images and related data. These minidrivers provide the following functionality:

  • Capture of compressed and uncompressed video streams, vertical blanking interval data, timecode, and ancillary data streams.
  • Control of devices associated with video streams such as TV tuners, video routing devices, TV audio control, and video compressors.
  • Compatibility with WDM-CSA.

Stream class video capture drivers can support multiple, simultaneous streams of compressed and uncompressed video, timecode, closed caption, raw and decoded VBI data, as well as custom data formats. For each data type that can be produced simultaneously with other data types, the driver should create a new stream. The Stream class exposes each stream as a separate WDM-CSA pin. Each stream can be connected to another WDM-CSA kernel filter, or it can make the transition to user mode and flow on an output pin of a DirectShow user-mode filter. Each stream (or pin) can support a variety of different formats. For example, a single pin can provide RGB16, RGB24, YVU9, and JPEG digital video. For more information on minidrivers, see the Windows 98 DDK.

Filter Graph Configuration

The association between DirectShow filters and CSA makes DirectShow filters a powerful and relatively safe method for manipulating data from a kernel mode Stream class driver. The flexibility of DirectShow makes numerous configurations of filters possible. The following diagram shows one possible configuration of user-mode DirectShow filters for simultaneous preview and capture of video to disk.

Configuration of user-mode DirectShow filters

In this diagram, an incoming TV signal can be tuned in with the Tuner filter and routed with the Crossbar filter. The filter graph passes data in various streams to the video or audio capture filters to be saved on disk. This includes audio streams, video streams, and any other ancillary data in various streams such as SMPTE timecode or closed captioning data.

Conclusion

WDM video capture was designed to resolve the problems inherent in the Video for Windows architecture. The main advantages of WDM video capture are:

  • 32 bit drivers.
  • Synergy between DirectShow and CSA.
  • Single class driver architecture for hardware (such as video ports and chip sets) that is shared between video capture devices and DVD/MPEG devices.
  • Television tuner, input selection, and support for fields, VBI, and video port extensions (VPE).
  • One driver works on both Windows 98 and NT platforms.

Because of the large installed base of Video for Windows applications, Video for Windows drivers will continue to be used for devices that are primarily used for capturing movies. Version 1.1e of Video for Windows currently ships in Windows 98 to provide operating system support for these devices. However, the WDM video capture architecture provides optimal support for capture devices used primarily for TV viewing and video conferencing.

New WDM Capture Interfaces and Filters

Some of the new WDM capture interfaces exposed by the kernel streaming filters are IAMTVTuner, IAMCrossbar, IAMAnalogVideoEncoder, IAMAnalogVideoDecoder, IAMVideoProcAmp, and IAMCameraControl.

Some of the new Windows 98 video capture filters for WDM are Ksproxy.ax, Kstune.ax, Ksxbar.ax. See the Windows 98 DDK for more information on these filters.


Application Developer's Guide

If you are creating an application that uses DirectShow components, read the articles in this section. These articles pertain to writing applications in both C and Microsoft® Visual Basic®.

How to...

Clocks

Controlling Filter Graphs Using C

Creating a Capture Application

Filter Categories

About Cutlists

Using Cutlists

DVD for Title Vendors


How to...

This section gives step-by-step procedures for creating applications, adding features to applications, and registering DirectShow objects. Topics include how to play a movie from C++, how to build an application in Visual C++, how to display a filter's property page, and how to use multimedia streaming, control the video playback window, or enumerate hardware devices from an application.

Play a Movie from C++

Control the Video Playback Window from C++

Display a Filter's Property Page from C++

Use Multimedia Streaming in DirectShow Applications

Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming

Control an External Device in DirectShow

Build a Filter or Application with Visual C++ 5.x

Recompress an AVI File

Register DirectShow Objects

Enumerate and Access Hardware Devices in DirectShow Applications


Play a Movie from C++

This article walks through a simple C++ program designed to demonstrate one way to play movies. It is based on the PlayFile function code, taken from the Playfile.cpp file, which you can find in the Playfile sample in the Samples\ds\player directory.

The PlayFile function has no control over the filters selected by the filter graph manager to play the input media file or over the playback window created. This article contains the following sections.

  • Playing a Media File — the basic code to play back a media file.
  • Adding Media Seeking — shows the code needed to seek to a particular location in the media file.

See these related sections to add a particular feature to your playback code:

  • Control the Video Playback Window from C++ — demonstrates how to set the playback window's style and position.
  • Display a Filter's Property Page from C++ — demonstrates how to display a filter's property page, so that the user can change how media files are played back.

Playing a Media File

This section explains the code needed to play a media file from within C/C++. The Playfile sample contains Playfile.cpp and demonstrates how to create an application window, display a menu to open a media file, and call the PlayFile function to play the media file. You can examine the Playfile application in the Samples\ds\player\Playfile directory to see how to use the PlayFile function. To learn how to build the Playfile sample from Visual C++ 5.x, see Setting the Visual Studio Include and Lib Directories.

The PlayFile function plays a specified file in a playback window. This function uses the filter graph manager to automatically render the media clip. The filter graph manager selects the appropriate filters and constructs the filter graph.

PlayFile function code demonstrates:

  • Basic interfaces needed to play and control a media file.
  • Instantiating the filter graph manager.
  • Calling the filter graph manager to build the filter graph that renders the media file.
  • Playing the media file.
  • Accessing events to tell when the playback is finished (media file ended).

After any function call that retrieves an interface pointer (CoCreateInstance, RenderFile, and QueryInterface), you should insert error-checking code to make sure the interface pointer was successfully obtained; if it wasn't, release any interfaces pointers already obtained. An example of error-checking code is:

        if (FAILED(hr)) {
            goto ObjectRelease; // go to the clean-up section
        }

You can call the PlayFile function from an application with code such as the following:

  TCHAR *szFilename = "c:\\dxmedia\\movie\\movie.avi";
  PlayFile(szFilename);

Perform the following steps to play a media file from within C/C++. You don't necessarily have to perform the steps in the order presented.

  1. Include the necessary headers.

  #include <windows.h>
  #include <mmsystem.h>
  #include <streams.h>
  #include "playfile.h"
  2. Define a windows message constant and the HELPER_RELEASE macro, which will be used to release the interfaces from the WndMainProc callback (see the Playfile code for generic window code).

 #define WM_GRAPHNOTIFY  WM_USER+13
 #define HELPER_RELEASE(x) { if (x) x->Release(); x = NULL; }
  3. Declare variables.

 HWND      ghApp;
 HINSTANCE ghInst;
 HRESULT   hr;
 LONG      evCode;
 LONG      evParam1;
 LONG      evParam2;

    The ghApp variable is the handle of window to notify when the graph signals an event. The ghInst variable is the HINSTANCE of the window. The evCode variable will hold the event code, and the evParam1 and evParam2 variables will hold the event parameters.

  4. Declare and initialize the necessary interfaces. The reference count of the interfaces is automatically incremented on initialization, so you don't need to call the IUnknown::AddRef method on them. For this example, you need only the four interfaces shown in the following code. For more information, see the documentation for the IMediaEventEx, IGraphBuilder, IMediaControl, and IVideoWindow interfaces.

  IGraphBuilder *pigb  = NULL;
  IMediaControl *pimc  = NULL;
  IMediaEventEx *pimex = NULL;
  IVideoWindow  *pivw  = NULL;
  5. Define the function. The szFile parameter is the name of the media file that will be played.

    void PlayFile (LPSTR szFile)
    {
        HRESULT hr;
  6. Create a Unicode (wide character) string from the input file name.

        WCHAR wFile[MAX_PATH];
        MultiByteToWideChar( CP_ACP, 0, szFile, -1, wFile, MAX_PATH );
  7. Instantiate the filter graph manager, asking for the IGraphBuilder interface.

        hr = CoCreateInstance(CLSID_FilterGraph,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IGraphBuilder,
        (void **)&pigb);
  8. Query for the IMediaControl interface (provides the methods to run, pause, and stop the playback), the IMediaEventEx interface (so you can receive event notifications), and the IVideoWindow interface to hide the window when the movie is finished playing.

   pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);
   pigb->QueryInterface(IID_IMediaEventEx, (void **)&pimex);
   pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);
  9. Ask the filter graph manager to build the filter graph that renders the input file. This does not play the media file. (When you play the file with Run, the filter graph will automatically render the input file's media type. You do not have to specify a renderer filter.)

   hr = pigb->RenderFile(wFile, NULL);
  10. Use a window to capture graph signal events. This not only improves performance, but allows your application to run in any threading model.

   pimex->SetNotifyWindow((OAHWND)ghApp, WM_GRAPHNOTIFY, 0);

    The window specified by ghApp will handle messages in response to all events from the graph. If an event occurs, DirectShow posts a WM_GRAPHNOTIFY message to the window.

  11. Start playing the media file.

   hr = pimc->Run();

    Alternatively, if your playback had a pause or stop button (see, for example, the CPlay sample or Controlling Filter Graphs Using C), you can pause or stop the playback on the button event with the IMediaControl::Pause or IMediaControl::Stop method, as shown in the following code.

        hr = pimc->Pause();
        hr = pimc->Stop();

The WndMainProc callback function in Playfile handles the filter graph messages and releases the interfaces when necessary, using the HELPER_RELEASE macro. The GetClipFileName function gets the movie to be played, while the WinMain function creates the window. These are all generic windows functions.

This section showed how to play a media file from the beginning. The next section shows how to control where within a media file to start and stop playing.

Adding Media Seeking

You can use the IMediaPosition or IMediaSeeking interface to seek to a particular place in your media file. The IMediaPosition::put_CurrentPosition method enables you to specify a start time within the media file. For example, you can use the following code to rewind to the media file's beginning.

  IMediaPosition *pimp;
  hr = pigb->QueryInterface(&IID_IMediaPosition, (void **)&pimp);
  hr = pimp->put_CurrentPosition(0);

Time is specified in 100-nanosecond units. The following code seeks into the media file 1 second:

    hr = pimp->put_CurrentPosition(10000000);

You can use the IMediaPosition::put_StopTime method to set the time within the media file to stop playback.

However, with IMediaPosition you can seek only to times within a media file. With the IMediaSeeking interface, you can set your seeking time format to 100-nanosecond time units, frames, bytes of data, media samples, or interlaced video fields. You set the format you want to use with the IMediaSeeking::SetTimeFormat method. Make sure your media file is not playing when you the set the format.

The term media time refers to positions within a seekable medium. Media time can be expressed in a variety of units, and indicates a position within the data in the file. The following table shows the possible media time formats.
Value | Description
TIME_FORMAT_MEDIA_TIME | Seeks to the specified time in the media file, in 100-nanosecond units. This is the default.
TIME_FORMAT_BYTE | Seeks to the specified byte in the stream.
TIME_FORMAT_FIELD | Seeks to the specified interlaced video field.
TIME_FORMAT_FRAME | Seeks to the specified video frame.
TIME_FORMAT_SAMPLE | Seeks to the specified sample in the stream.

For example, the following code sets the format so that the application seeks for sample numbers.

   IMediaSeeking *pims;
   hr = pigb->QueryInterface(IID_IMediaSeeking, (void **)&pims);
   hr = pims->SetTimeFormat(&TIME_FORMAT_SAMPLE);

An application can use the various seeking modes to seek in a stream to a particular video frame or audio sample without doing time/rate conversions itself. This is useful for editing, which requires sample-accurate playback. The frame or sample number that the application specifies is passed through to the AVI or MPEG parser without the risk of rounding errors.

The following steps show how to set which frame in a media file to start playing at and which frame to stop playing at; for example, to start playing a movie at the fifth frame after its beginning. You can insert this code into the PlayFile function anywhere after the RenderFile function has built the filter graph.

  1. Access the IMediaSeeking interface.

   IMediaSeeking *pims;
   hr = pigb->QueryInterface(IID_IMediaSeeking, (void **)&pims);
  2. Set the time format. In the following example, the time format is set to seek to frames.

   hr = pims->SetTimeFormat(&TIME_FORMAT_FRAME);
  3. Declare and initialize the media-seeking variables. In this case, they are frames within the media file to start and stop playback. The following values set the start frame to 5 and the stop frame to 15.

   LONGLONG start = 5L;
   LONGLONG stop = 15L;
  4. Set the start and stop media time with the IMediaSeeking::SetPositions method. The AM_SEEKING_AbsolutePositioning flag means that the start and stop frames are absolute positions within the media file (not relative to the present position in the media file). In this example, the media file will start playing at frame 5 into the file and stop at frame 15, for a duration of 10 frames. The length of playing time depends on the video's frame rate.

   pims->SetPositions(&start, AM_SEEKING_AbsolutePositioning, &stop,
               AM_SEEKING_AbsolutePositioning);
  5. Release the IMediaSeeking interface.

   pims->Release();

By removing the SetTimeFormat call and setting the values of start and stop as follows, you can set the media file to start playing 5 seconds into the file and stop 7 seconds into the file, for a duration of 2 seconds.

   LONGLONG start = 50000000L;
   LONGLONG stop = 70000000L;

By setting other formats in the SetTimeFormat call, you can seek to frames, sample numbers, byte, and so on.


Control the Video Playback Window from C++

This article walks through a simple C++ program designed to demonstrate one way to play movies in a particular playback window. It is based on the PlayMovieInWindow function code taken from the InWindow.cpp file, which is available in the InWindow sample in the Samples\ds\player directory. This function is based on the Playfile sample, but has been expanded to show how an application can control the size and style of the video playback window.

See these related sections if you want to play back media files or display a property page:

  • Play a Movie from C++ — demonstrates the basic code for playing back a media file.
  • Adding Media Seeking — shows the code needed to seek to a particular location in the media file.
  • Display a Filter's Property Page from C++ — demonstrates how to display a filter's property page, so the user can change how media files are played back.

Perform the following steps to play a video file in a particular window from within C/C++. You don't necessarily have to perform the steps in the order presented.

  1. Include the necessary headers.

  #include <windows.h>
  #include <mmsystem.h>
  #include <streams.h>
  #include "inwindow.h"
  2. Define a windows message constant and the HELPER_RELEASE macro, which will be used to release the interfaces from the WndMainProc callback (see the InWindow code for generic window code).

 #define WM_GRAPHNOTIFY  WM_USER+13
 #define HELPER_RELEASE(x) { if (x) x->Release(); x = NULL; }
  3. Declare variables.

 HWND      ghApp;
 HINSTANCE ghInst;
 HRESULT   hr;
 LONG      evCode;
 LONG      evParam1;
 LONG      evParam2;
 RECT      grc;

    The ghApp variable is the handle of window to notify when the graph signals an event. The ghInst variable is the HINSTANCE of the window. The evCode variable will hold the event code, and the evParam1 and evParam2 variables will hold the event parameters. The grc variable will hold the coordinates of the parent window's client area.

  4. Declare and initialize the necessary interfaces. The reference count of the interfaces is automatically incremented on initialization, so you don't need to call the IUnknown::AddRef method on them. For this example, you need only the four interfaces shown in the following code. For more information, see the documentation for the IMediaEventEx, IGraphBuilder, IMediaControl, and IVideoWindow interfaces.

  IGraphBuilder *pigb  = NULL;
  IMediaControl *pimc  = NULL;
  IMediaEventEx *pimex = NULL;
  IVideoWindow  *pivw  = NULL;
  5. Define the function and declare variables. The szFile parameter is the name of the video file that will be played.

void PlayMovieInWindow (LPCTSTR szFile)
    {
  6. Create a Unicode (wide character) string from the input file name.

        WCHAR wFile[MAX_PATH];
        MultiByteToWideChar( CP_ACP, 0, szFile, -1, wFile, MAX_PATH );
  7. Instantiate the filter graph manager, asking for the IGraphBuilder interface.

        hr = CoCreateInstance(CLSID_FilterGraph,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IGraphBuilder,
        (void **)&pigb);
  8. Query for the IMediaControl interface (provides the methods to run, pause, and stop the playback), the IMediaEventEx interface (so you can receive event notifications), and the IVideoWindow interface to hide the window when the movie is finished playing.

   pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);
   pigb->QueryInterface(IID_IMediaEventEx, (void **)&pimex);
   pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);
  9. Ask the filter graph manager to build the filter graph that renders the input file. This does not play the media file. (When you play the file with Run, the filter graph will automatically render the input file's media type. You do not have to specify a renderer filter.)

   hr = pigb->RenderFile(wFile, NULL);
  10. Set the ownership of the playback window. This sets ghApp as the owning parent.

   pivw->put_Owner((OAHWND)ghApp);
  11. Set the style of the video window. This step is very important, and you must specify the WS_CHILD, WS_CLIPCHILDREN, and WS_CLIPSIBLINGS flags.

   pivw->put_WindowStyle(WS_CHILD | WS_CLIPCHILDREN | WS_CLIPSIBLINGS);
  12. Get the coordinates of the parent window's client area.

   GetClientRect(ghApp, &grc);
  13. Set the playback window's position within parent's client area. In this case, the playback window fills the client area. If the video being played is smaller than the playback window it will be stretched to fit the window. If the video is larger, it will be compressed to fit the window.

   pivw->SetWindowPosition(grc.left, grc.top, grc.right, grc.bottom);
  14. Start playing the media file.

   hr = pimc->Run();

The InWindow sample uses the same GetClipFileName function to get the movie to be played and the same the WinMain function to create the window as the Playfile sample.

The InWindow WndMainProc callback function is similar to the Playfile WndMainProc used to handle the filter graph messages and release the interfaces when necessary, with one important difference. The WndMainProc function in InWindow calls the IVideoWindow::put_Owner method with a NULL value for its parameter. You must do this before releasing the IGraphBuilder interface and before the video window is destroyed. Otherwise, messages will continue to be sent to the video playback window but it will have no parent to forward the messages to, so errors will likely occur.

pivw->put_Owner(NULL);


Display a Filter's Property Page from C++

This article walks through a simple C++ program designed to demonstrate how to request a filter to display its property page. It is based on the MPegProp function code in the MPegProp.cpp file, which you can find in the MPegProp sample in the Samples\ds\player directory.

This code displays the property page of the MPEG video decoder. This filter has a property page that enables you to play MPEG files in color or monochrome. You can see this filter's property page by opening the Filter Graph Editor, choosing the Insert Filters command from the Graph menu, selecting MPEG Video Decoder from the DirectShow Filters list, and clicking the Insert Filters button. After you've inserted the filter, right-click anywhere on it to display its property page.

See these related sections if you want to play back media files or specify the video playback window:

  • Play a Movie from C++ — demonstrates the basic code for playing back a media file.
  • Adding Media Seeking — shows the code needed to seek to a particular location in the media file.
  • Control the Video Playback Window from C++ — demonstrates how to display a filter's property page, so the user can change how media files are played back.

Perform the following steps to control the MPEG video decoder's property page in C/C++. You don't necessarily have to perform the steps in the order presented.

  1. Include the necessary headers.

  #include <windows.h>
  #include <mmsystem.h>
  #include <streams.h>
  #include "playfile.h"
  2. Define a windows message constant and the HELPER_RELEASE macro, which will be used to release the interfaces from the WndMainProc callback (see the MPegProp code for generic window code).

 #define WM_GRAPHNOTIFY  WM_USER+13
 #define HELPER_RELEASE(x) { if (x) x->Release(); x = NULL; }
  3. Declare variables.

 HWND      ghApp;
 HINSTANCE ghInst;
 HRESULT   hr;
 LONG      evCode;
 LONG      evParam1;
 LONG      evParam2;

    The ghApp variable is the handle of window to notify when the graph signals an event. The ghInst variable is the HINSTANCE of the window. The evCode variable will hold the event code, and the evParam1 and evParam2 variables will hold the event parameters.

  4. Declare and initialize the necessary interfaces. The reference count of the interfaces is automatically incremented on initialization, so you don't need to call the IUnknown::AddRef method on them. For this example, you need only the four interfaces shown in the following code. For more information, see the documentation for the IMediaEventEx, IGraphBuilder, IMediaControl, and IVideoWindow interfaces.

  IGraphBuilder *pigb  = NULL;
  IMediaControl *pimc  = NULL;
  IMediaEventEx *pimex = NULL;
  IVideoWindow  *pivw  = NULL;
  IFilterGraph  *pifg  = NULL;
  IBaseFilter   *pifPP = NULL;
  ISpecifyPropertyPages *pispp = NULL;
  5. Define the function and declare variables. The szFile parameter is the name of the MPEG video file that will be played.

   void MpegProp (LPSTR szFile)
   {
  6. Create a Unicode (wide character) string from the input file name.

        WCHAR wFile[MAX_PATH];
        MultiByteToWideChar( CP_ACP, 0, szFile, -1, wFile, MAX_PATH );
  7. Instantiate the filter graph manager, asking for the IGraphBuilder interface.

        hr = CoCreateInstance(CLSID_FilterGraph,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IGraphBuilder,
        (void **)&pigb);
  8. Query for the IMediaControl interface (provides the methods to run, pause, and stop the playback), the IMediaEventEx interface (so you can receive event notifications), and the IVideoWindow interface to hide the window when the movie is finished playing.

   pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);
   pigb->QueryInterface(IID_IMediaEventEx, (void **)&pimex);
   pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);
  9. Ask the filter graph manager to build the filter graph that renders the input file. This does not play the media file. (When you play the file with Run, the filter graph will automatically render the input file's media type. You do not have to specify a renderer filter.)

   hr = pigb->RenderFile(wFile, NULL);
  10. Use a window to capture graph signal events. This not only improves performance, but allows your application to run in any threading model.

   pimex->SetNotifyWindow((OAHWND)ghApp, WM_GRAPHNOTIFY, 0);

    The window specified by ghApp will handle messages in response to all events from the graph. If an event occurs, DirectShow posts a WM_GRAPHNOTIFY message to the window.

  11. Query for the IFilterGraph interface. Through IFilterGraph, you will retrieve a pointer to the IBaseFilter interface on the MPEG Video Codec filter. The easiest way to find the single MPEG video codec in the graph is through IFilterGraph::FindFilterByName.

  pigb->QueryInterface(IID_IFilterGraph, (void **)&pifg);
  12. Use FindFilterByName to find the MPEG Video Codec. This method returns a pointer (&pifPP) to the IBaseFilter interface on the MPEG Video Codec.

   hr = pifg->FindFilterByName(L"MPEG Video Codec", &pifPP);
  13. Retrieve the ISpecifyPropertyPages interface for the MPEG Video Codec. This filter has a property page that enables you to play MPEG files in color or monochrome.

   pif->QueryInterface(IID_ISpecifyPropertyPages, (void **)&pispp);
  14. Allocate a counted array of GUIDs for the property page. The ISpecifyPropertyPages::GetPages method uses the COM CAUUID structure to receive an array of CLSIDs from the filter for each of its property pages. The structure has two members, cElems, which holds the number of property pages, and pElems, which points to an array holding the property page CLSIDs.

   CAUUID caGUID;
  15. Using the pointer to the MPEG Video Decoder filter's property page, pispp, call the COM ISpecifyPropertyPages::GetPages method to fill the caGUID structure with a counted array of UUIDs, where each UUID specifies a property page CLSID.

   pispp->GetPages(&caGUID);
  16. Release the ISpecifyPropertyPages interface.

  HELPER_RELEASE(pispp);
  17. Create a modal dialog box to display the MPEG Video Decoder filter's property page. This dialog box appears before the video is played, enabling the user to choose to play back in color or monochrome.

   OleCreatePropertyFrame(NULL,
            0,
            0,
            L"Filter",          // Caption for the dialog box
            1,                  // Number of filters
            (IUnknown **)&pifPP,  // Pointer to the filter whose property
                                // Pages are being displayed. This can
                                // be an array of pointers if more than
                                // one filter's property pages are to
                                // be displayed. Note that only
                                // properties common to all the filters
                                // can be displayed on the same modal
                                // dialog.
            caGUID.cElems,      // Number of property pages
            caGUID.pElems,      // Pointer to property page CLSIDs
            0,
            0,
            NULL);
  18. Release the IBaseFilter interface.

  HELPER_RELEASE(pifPP);

The MPegProp sample uses the same WndMainProc callback function to handle the filter graph messages, the same GetClipFileName function to get the movie to be played, and the same the WinMain function to create the window as the Playfile sample. These are all generic windows functions.


DirectShow Animated Header -- Use Multimedia Streaming in DirectShow Applications DirectShow Animated Header -- Use Multimedia Streaming in DirectShow Applications * Microsoft DirectShow SDK
  * Previous Topic: Display a Filter's Property Page from C++
  * Next Topic: Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming

Use Multimedia Streaming in DirectShow Applications

This section describes and demonstrates how to support multimedia streaming in Microsoft® DirectShow™ applications. DirectShow applications typically use multimedia streaming to send audio and video data directly to a Microsoft DirectDraw® surface for rendering, instead of attaching playback to a specific window. This section has short conceptual explanations of windowless playback and multimedia streams, as well as additional detail on the multimedia streaming architecture and a minimal code demonstration of using streams to perform windowless playback of DirectShow-supported media files.

This section contains the following topics.

  • Windowless Playback
  • Multimedia Streams
  • Code Walk-through of a Simple Application

Programmers who want to use multimedia streaming in their applications should be familiar with COM programming concepts, DirectDraw and its associated objects, and DirectShow media playback. For information on DirectDraw, consult the Microsoft DirectX SDK documentation. The DirectShow SDK documentation includes many examples of media file playback using C/C++; see About DirectShow and the included samples for more information. If you need information on programming with COM and OLE, consult reference materials such as Inside OLE by Kraig Brockschmidt or Understanding ActiveX and OLE by David Chappell.

Windowless Playback

Typically, applications display their video output in a clearly bounded rectangle, — the window. Each window has certain properties in common with other windows, such as menus, close buttons, and so forth. This shared behavior is helpful because it provides a measure of consistency and reliability to programming procedures and the user interface. DirectShow typically uses windows for media playback, because of the low programming overhead and consistent interface. However, there are a number of situations where an application developer wants to divorce media playback from the window and gain complete control over its appearance. For example, if you were creating a three-dimensional computer model of a museum tour, complete with moving exhibits and an animated tour guide, it would not be appropriate (or lifelike) to show each element of the tour in a separate window; you would need to integrate all of the elements together into a single presentation. By attaching the media playback to a DirectDraw surface instead of a window, you gain complete control over its appearance and behavior.

DirectDraw surfaces represent a portion of a system's video memory. Once you designate a surface as the destination of a movie's video data, you can blit the data to the surface in the same way you would normally blit color and texture information. Because it is a normal DirectDraw surface, you can manipulate it in any manner supported by the DirectDraw interfaces; you can play it back as the background of a game, texture map it into a three-dimensional environment, and so forth. While this level of control adds some programming overhead to your application, these effects would be impossible to do in a normal window.

Multimedia Streams

Audio and video data is, at its most basic, a sequence of information that specifies characteristics like color, resolution, frequency, and volume. Because there are a large number of devices and data formats related to media, moving data from its origin to its destination is a very convoluted process; you must know exactly how the original device formats its information, what characteristics the display format has, and how to convert the device information from its original format to a format suitable for rendering or storage. Because the exact steps in this process are different for every device, it is often difficult to handle multiple devices (such as a video camera, movie data file, and Internet URL) in a single application. Applications can, however, avoid much of this difficulty by using multimedia streaming as the data source. The streaming architecture automatically handles the process of data conversion and formatting, producing a consistently formatted data source ready for rendering or file storage. Thus, applications only need to handle the presentation of the data and not the data conversion.

Code Walk-through of a Simple Application

Using multimedia streams in a DirectShow application is fairly straightforward; the following steps describe the process.

  1. Open a media file that DirectShow supports.
  2. Create a multimedia stream for each of the file's media types; typically, this will be one video and one audio stream.
  3. Create a DirectDraw surface and associate it with the video stream.
  4. Render the stream data, which will then play back on the surface.

The following code sample, which you can find in its entirety in the \Streams\Simple\Main.cpp file included with the DirectShow SDK, demonstrates these steps. The complete file comprises three functions: OpenMMStream, RenderStreamToSurface, and main. OpenMMStream creates the audio and video multimedia streams from the media file, RenderStreamToSurface does the actual surface rendering, and main calls the other two functions appropriately. Because this example is a command-line application, you must supply the name of the media file as a parameter when you run the program. In Main.cpp, the following macro handles error checking.

#define CHECK_ERROR(x)     \
   if (FAILED(hr = (x))) { \
       printf(#x "  failed with HRESULT(0x%8.8X)\n", hr); \
       goto Exit;          \
   }

Each application that uses multimedia streaming must include the correct header files. The following list contains the stream-related header files from Main.cpp; the DirectShow SDK includes all of these header files.

#include "ddraw.h"	// DirectDraw interfaces
#include "mmstream.h"	// Multimedia stream interfaces
#include "amstream.h"	// DirectShow multimedia stream interfaces
#include "ddstream.h"	// DirectDraw multimedia stream interfaces

The code in Main.cpp is intended to be the minimum amount of programming necessary to implement multimedia streams, so it is appropriate to read it as a series of required steps. The following instructions illustrate all of the important concepts from Main.cpp, but don't necessarily include every line of code. For the complete code, refer to Main.cpp.

Creating a Multimedia Stream Linked to a DirectShow File

To create a multimedia stream and link it to a media file, perform the following steps. You do not necessarily need to perform the steps in the given order.

1) The OpenMMStream function creates a multimedia stream and attaches the stream to a valid input media file. The pszFileName parameter specifies the name of the media file, whose type DirectShow must support. The pDD parameter specifies an IDirectDraw interface that points to the destination DirectDraw object. When this function creates the multimedia stream, it attaches the stream's video portion to the object by using this pointer. The ppMMStream parameter represents a global stream pointer. Once this function creates a valid local stream, it points this parameter to the stream so other functions can use the stream as needed.

HRESULT OpenMMStream(const char * pszFileName, IDirectDraw *pDD,
               IMultiMediaStream **ppMMStream) {

2) Declare a local IAMMultiMediaStream pointer, create a stream object, and initialize it. You should use the local pAMStream pointer during the stream's creation; don't use the global ppMMStream pointer until you are sure the stream and its media file are valid.

    *ppMMStream = NULL;	// Initialize global stream pointer to null
    IAMMultiMediaStream *pAMStream;
    HRESULT hr;		// Function's return value

    CHECK_ERROR(CoCreateInstance(CLSID_AMMultiMediaStream, NULL,
                       CLSCTX_INPROC_SERVER, IID_IAMMultiMediaStream,
                       (void **)&pAMStream));
    CHECK_ERROR(pAMStream->Initialize(STREAMTYPE_READ,
                       AMMSF_NOGRAPHTHREAD, NULL));

3) Now that you have a stream object, add a single audio and video stream to it; typically, you need only these two streams for media file playback. When the IAMMultiMediaStream::AddMediaStream method receives the MSPID_PrimaryVideo flag as its second parameter, it uses the pointer in the first parameter as the destination surface for video playback. The audio stream needs no such surface, however, so you pass NULL as the first parameter when you add audio streams. The AMMSF_ADDDEFAULTRENDERER flag automatically adds the default sound renderer to the current filter graph.

    CHECK_ERROR(pAMStream->AddMediaStream(pDD, MSPID_PrimaryVideo, 0, NULL));
    CHECK_ERROR(pAMStream->AddMediaStream(NULL, MSPID_PrimaryAudio,
                            AMMSF_ADDDEFAULTRENDERER, NULL));

4) Convert the provided file name to a wide (Unicode) string and open the file. If the file name specifies a valid media file, DirectShow attaches the audio and video tracks to the streams you created earlier in the function. Point the ppMMStream parameter to the stream and increment the pointer's reference count.

    WCHAR	wPath[MAX_PATH];		// Wide (32-bit) string name
    MultiByteToWideChar(CP_ACP, 0, pszFileName, -1, wPath,
                sizeof(wPath)/sizeof(wPath[0]));

    CHECK_ERROR(pAMStream->OpenFile(wPath, 0));
    *ppMMStream = pAMStream;		// Set global pointer to local pointer
    pAMStream->AddRef();		// Add a reference to the file

Now that you have valid streams and a pointer to them, this function is complete.

Render the Video Data to a DirectDraw Surface

To render the video portion of a multimedia stream to a DirectDraw surface, perform the following steps. You do not necessarily need to perform the steps in the given order.

1) The RenderStreamToSurface function handles the actual rendering; it creates and initializes the required DirectDraw surface, and blits the video stream's data to the surface. The pDD parameter points to a global DirectDraw object, which you later use to create the surface. The pPrimary parameter is the primary rendering surface; it sends all blitted video data from the video stream, which the pMMStream parameter points to.

HRESULT RenderStreamToSurface(IDirectDraw *pDD, IDirectDrawSurface *pPrimary,
                              IMultiMediaStream *pMMStream) {

2) Create local variables for the surface, media streams, and video sample. When you blit data to the DirectDraw surface, you will use these local variables to store the individual frame and video sample information.

    IMediaStream *pPrimaryVidStream = NULL;
    IDirectDrawMediaStream *pDDStream = NULL;
    IDirectDrawSurface *pSurface = NULL;
    IDirectDrawStreamSample *pSample = NULL;

3) Retrieve the video stream from the global stream, which the pMMStream pointer specifies; the IMultiMediaStream::GetMediaStream method associates the local IMediaStream pointer with the retrieved stream. You can then use that pointer to obtain a DirectDraw media stream pointer, which you will need to retrieve the video format.

    CHECK_ERROR(pMMStream->GetMediaStream(MSPID_PrimaryVideo,
            &pPrimaryVidStream));
    CHECK_ERROR(pPrimaryVidStream->QueryInterface(
            IID_IDirectDrawMediaStream, (void **)&pDDStream));

4) Create a DirectDraw surface and a bounding rectangle to use for playback. Call IDirectDrawMediaStream::GetFormat to retrieve the video format and set the dimensions of the rectangle to match the format dimensions.

    DDSURFACEDESC ddsd;			// Surface characteristics
    ddsd.dwSize = sizeof(ddsd);

    CHECK_ERROR(pDDStream->GetFormat(&ddsd, NULL, NULL));
    RECT rect;				// Playback rectangle
    rect.top = rect.left = 0;
    rect.bottom = ddsd.dwHeight;
    rect.right = ddsd.dwWidth;

    CHECK_ERROR(pDD->CreateSurface(&ddsd, &pSurface, NULL));

5) Create the first video sample and attach it to the desired playback surface. You can then blit all samples from the video stream directly to the surface by calling the DIrectDraw Surface's Update method in a loop. Each loop iteration throws out the previous video image and grabs the next image from the stream. The loop breaks once there is no remaining renderable video data.

    CHECK_ERROR(pDDStream->CreateSample(pSurface, NULL, 0, &pSample));

    while (true) {
        if (pSample->Update(0, NULL, NULL, 0) != S_OK) {
            break;
        }
        pPrimary->Blt(&rect, pSurface, &rect, DDBLT_WAIT, NULL);
    }

6) Release all local pointers.

    RELEASE(pPrimaryVidStream);
    RELEASE(pDDStream);
    RELEASE(pSample);
    RELEASE(pSurface);

    return hr;
}

Once DirectShow finishes rendering all available data, the function is complete.

Run the Program

To obtain a valid media filename and run the program, perform the following steps. You do not necessarily need to perform the steps in the given order.

1) Create a main function to obtain the file name and run the rendering process. The following example takes the media file name as a command-line parameter.

int main(int argc, char *argv[]) {

2) Create a global DirectDraw object; once you have a valid object, create a surface that you will later use for video playback. This example calls the Win32 GetDesktopWindow function to associate the surface with the desktop, reducing the amount of required configuration code.

    CoInitialize(NULL);		// Initialize the COM objects

    // Create the DirectDraw object and its interface pointer
    IDirectDraw *pDD;
    HRESULT hr = DirectDrawCreate(NULL, &pDD, NULL);

    if (SUCCEEDED(hr)) {	// The object is valid
        DDSURFACEDESC ddsd;	// Surface characteristics
        IDirectDrawSurface *pPrimarySurface;

        pDD->SetCooperativeLevel(GetDesktopWindow(), DDSCL_NORMAL);
        ddsd.dwSize = sizeof(ddsd);
        ddsd.dwFlags = DDSD_CAPS;
        ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
        hr = pDD->CreateSurface(&ddsd, &pPrimarySurface, NULL);

3) Create the multimedia stream and call the previously defined functions. Once the functions finish execution, make sure to release all pointers at the correct times. Once playback is complete, call the Win32 CoUninitialize function and return. Once DirectShow finishes playback of the file, it returns control to the command line.

        if (SUCCEEDED(hr)) {
            IMultiMediaStream *pMMStream;
            hr = OpenMMStream(argv[1], pDD, &pMMStream);
            if (SUCCEEDED(hr)) {
                RenderStreamToSurface(pDD, pPrimarySurface, pMMStream);
                pMMStream->Release();
            }
            pPrimarySurface->Release();
    }
    CoUninitialize();	// Release COM objects
    return 0;		// Success
}

Now that you know how to direct streamed video data to a DirectDraw surface, you can use this functionality any way you would normally use DirectDraw surfaces. A typical use would be to texture map the playback surface onto a Direct3D primitive object and incorporate it as part of a three-dimensional environment. For information on controlling any part of DirectDraw, consult the DirectX SDK documentation.


DirectShow Animated Header -- Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming DirectShow Animated Header -- Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming * Microsoft DirectShow SDK
  * Previous Topic: Use Multimedia Streaming in DirectShow Applications
  * Next Topic: Control an External Device in DirectShow

Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming

This article walks through the MovieWin C++ example code, which plays movies in a window by rendering to a Microsoft DirectDraw® surface. The MovieWin example code is a Microsoft® Windows® 95 application that is an extension of the ShowStrm Sample (Multimedia Streaming Application) sample. MovieWin uses multimedia streaming to render a video file to a DirectDraw surface created through DirectDrawEx. It implements a primary DirectDraw surface and an offscreen DirectDraw surface to optimize frame blitting. It also attaches a DirectDraw clipper to the window to process window overlapping.

Contents of this article:

  • Necessary Header files and Libraries
  • WinMain Function
  • Initialize DirectDraw Surfaces and Create the Clipper
  • Open a Movie File
  • Create the Multimedia Stream Object
  • Create the Stream Sample Object
  • Render the Multimedia Stream to the DirectDraw Surface
  • Release Objects
  • WndMainProc Function
  • Entire MovieWin Example Code

The example demonstrates a way to render a movie that differs from the traditional method of instantiating a filter graph directly in your application. The MovieWin example code uses the multimedia streaming interfaces to automatically negotiate the transfer and conversion of data from the source to the application, so you don't have to write code to handle the connection, transfer of data, data conversion, or actual data rendering.

Additionally, the example demonstrates how to create DirectDraw surfaces and how to add code for a DirectDrawClipper object through DirectDrawEx.

Note that all error checking has been left out of the code walk-through. The Entire MovieWin Example Code section provides all of the code with complete error checking.

Necessary Header files and Libraries

This section discusses necessary headers and libraries that need to be included and examines each function in the MovieWin example code in detail.

To compile the MovieWin example code you must have DirectX Media SDK 5.x or later installed and you will need to set your include path under Tools/Options/Directories/Include to c:\DXMedia\Include and your library path to c:\DXMedia\Lib. Also link with the Amstrmid.lib, the Quartz.lib, the Strmbase.lib, and the Ddraw.lib (DirectDrawEx does not provide its own library) libraries under Project/Settings/Link.

Include the necessary header files and define the window's name and the window class name.

#include <windows.h>
#include <mmstream.h>	// Multimedia stream interfaces
#include <amstream.h>	// DirectShow multimedia stream interfaces
#include <ddstream.h>	// DirectDraw multimedia stream interfaces
#include <initguid.h>   // Defines DEFINE_GUID macro and enables GUID initialization
#include <ddrawex.h>	// DirectDrawEx interfaces
#include "resource.h"   // Resources for the menu bar

#define APPLICATIONNAME "Multimedia Stream In Window"
#define CLASSNAME "MMSDDRAWEXWINDOW"

Then declare the following global variables:

HWND              ghWnd;
HINSTANCE         ghInst;
BOOL              g_bAppactive=FALSE,    // The window is active
                  g_bFileLoaded = FALSE, // There is a file loaded
                  g_bPaused=FALSE;       // The movie has been paused
RECT              rect, rect2;          // Rectangles for screen coordinates

The ghWnd variable is the handle of the window to send messages to. The ghInst variable is the handle of the instance of the window. The three Boolean values g_bAppactive, g_bFileLoaded, g_bPaused variables are used to determine the various states of the application and are used extensively by the WndMainProc function. They are declared as global variables to retain their TRUE or FALSE status. Finally, rect and rect2 are rectangle structures that will contain the original movie coordinates and the coordinates of the window to show the movie in, respectively.

Next, declare the DirectDrawEx and multimedia streaming interfaces. The reference count of the interfaces is automatically incremented on initialization, so you don't need to call the IUnknown::AddRef method to increment them. For more information on these interfaces, see DirectDrawEx, , and the Microsoft DirectX® SDK.

//DirectDrawEx Global interfaces
IDirectDraw            *g_pDD=NULL;
IDirectDraw3           *g_pDD3=NULL;
IDirectDrawFactory     *g_pDDF=NULL;
IDirectDrawSurface     *g_pPrimarySurface=NULL,
                       *g_pDDSOffscreen=NULL;
IDirectDrawClipper     *g_pDDClipper=NULL;

//Global MultiMedia streaming interfaces
IMultiMediaStream        *g_pMMStream=NULL;
IMediaStream             *g_pPrimaryVidStream=NULL;
IDirectDrawMediaStream   *g_pDDStream=NULL;
IDirectDrawStreamSample  *g_pSample=NULL;

Finally, declare the function prototypes.

//Function prototypes
int PASCAL WinMain(HINSTANCE hInstC, HINSTANCE hInstP, LPSTR lpCmdLine, int nCmdShow);
LRESULT CALLBACK WndMainProc (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);
HRESULT InitDDrawEx();
BOOL GetOpenMovieFile(LPSTR szName);
HRESULT RenderFileToMMStream(LPCTSTR szFilename);
HRESULT InitRenderToSurface();
void RenderToSurface();
void ExitCode();

WinMain Function

The WinMain function is a generic Windows function with a few exceptions.

Immediately after the Win32 CreateWindowEx function, the InitDDrawEx function is called to initialize the DirectDrawEx surfaces that the movie will play on and to create a clipper to attach to the window. The clipper can only be created after it has a global handle to the window (ghWnd), and so must be created after the call to the CreateWindowEx function has returned.

The message pump is a standard Windows message pump containing the TranslateMessage and the DispatchMessage functions with an interesting note. Before the code reaches these functions, it calls the PeekMessage function. The PeekMessage function checks a thread message queue for a message and places the message (if any) in the specified structure. If there are messages being passed to the window the code proceeds to the regular GetMessage, TranslateMessage, and DispatchMessage functions respectively. However if there are no messages in the message queue, the process will check for the g_bFileLoaded Boolean value, which specifies whether a file has been loaded. Initially, the value in g_bFileLoaded is FALSE so the code maintains its loop, waiting for new messages.

After a file has been loaded and rendered to a multimedia stream (see GetOpenMovieFile function and RenderFileToMMStream function) the g_bFileLoaded value and the g_bAppactive values are set to TRUE and the message pump will call the RenderToSurface function, which blits one frame of the movie to the window's coordinates. As the loop continues, the movie continues to render frame by frame until completion or until it is interrupted the PeekMessage function with an outside message to the window. If the movie is paused, stopped, or if it completes on its own, the g_bAppactive variable is set to FALSE, which causes the call to RenderToSurface to be skipped until g_bAppactive is set to TRUE again.

The following code shows how to create the message pump.

while(1){
        //The PeekMessage function checks a thread message queue
        //for a message and places the message (if any) in the specified structure.
        if(PeekMessage(&msg, NULL, 0,0,PM_NOREMOVE)){

            // Quit if WM_QUIT found
            if(!GetMessage(&msg,NULL, 0, 0)) return (msg.wParam);

            // Otherwise handle the messages
                TranslateMessage(&msg);		// Allow input
                DispatchMessage(&msg);		// Send to appropriate process.
        }
        else{
            // If there are no other windows messages...
            // Render frame by frame (but only if the App is the active
            // window and a file is actually loaded)
            if (g_bFileLoaded && g_bAppactive) {
                RenderToSurface();
                }
            }
        }
      return msg.wParam;

Initialize DirectDraw Surfaces and Create the Clipper

The InitDDrawEx function initializes a primary DirectDraw surface and an offscreen DirectDraw surface, as well as a clipper object that is attached to the window. The following code shows how to do this.

  1. Declare local variables and initialize the COM subsystem.
    HRESULT			hr=NOERROR;
DDSURFACEDESC	ddsd, ddsd2;

CoInitialize(NULL);
  2. Create the DirectDrawFactory object and expose the IDirectDrawFactory interface.

CoCreateInstance(CLSID_DirectDrawFactory, NULL, CLSCTX_INPROC_SERVER,
                            IID_IDirectDrawFactory, (void **)&g_pDDF);

    Use the pointer to the IDirectDrawFactory interface to call the IDirectDrawFactory::CreateDirectDraw method, which you use to create the DirectDraw object, set the cooperative level, and get the address of an IDirectDraw interface pointer.

g_pDDF->CreateDirectDraw(NULL, GetDesktopWindow(), DDSCL_NORMAL,
                NULL, NULL, &g_pDD);
  3. Query for the IDirectDraw3 interface, which you use to create the DirectDraw surfaces.
    g_pDD->QueryInterface(IID_IDirectDraw3, (LPVOID*)&g_pDD3);
  4. Initialize the DDSURFACEDESC structure for the primary surface. The following is the minimum code needed to accomplish this. You should also initialize other members of the structure here if your code must create more sophisticated applications.
    ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
  5. Call the IDirectDraw3::CreateSurface method to create the primary DirectDraw surface and return a pointer to IDirectDrawSurface interface.
    g_pDD3->CreateSurface(&ddsd, &g_pPrimarySurface, NULL);
  6. Create the offscreen surface where the IStreamSample::Update method will send the individual movie frames before they are blitted onto the screen. Using an offscreen surface optimizes the performance of the video and enables the blits to be processed at a faster rate. Also the video remains in memory and can be called upon in the event of a repaint notification.

    You must create the offscreen surface with the identical height, width, and pixel format to the primary surface in order to blit from one to the other. Do this by first getting the DDSURFACEDESC structure from the primary surface through a call to the IDirectDrawSurface::GetSurfaceDesc method.

    g_pPrimarySurface->GetSurfaceDesc(&ddsd);
  7. Now you can initialize the DDSURFACEDESC structure for the offscreen surface with the same parameters as the primary surface:

ZeroMemory(&ddsd2, sizeof(ddsd2));
ddsd2.dwSize = sizeof(ddsd2);
ddsd2.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
ddsd2.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd2.dwHeight = ddsd.dwHeight;	//set the height of the surfaces equal
ddsd2.dwWidth  = ddsd.dwWidth;	//set the width of the surfaces equal
ddsd2.ddpfPixelFormat = ddsd.ddpfPixelFormat; //set the pixel formats equal
  8. Call the IDirectDraw3::CreateSurface method to create the offscreen surface.
    g_pDD3->CreateSurface(&ddsd2, &g_pDDSOffscreen, NULL)

    At this point, you should have two identical DirectDraw surfaces: the offscreen surface that will be used to update the movie frames on, and the primary surface, which your user will see. The primary surface will contain the video after the data has been blitted from the offscreen surface to the primary surface.

  9. To give the window the look and feel of a regular window, you must add code for a clipper. The DirectDrawClipper object (casually referred to as a "clipper") helps you prevent blitting to certain portions of a surface or beyond the bounds of a surface. DirectDrawClipper objects expose their functionality through the IDirectDrawClipper interface. You can create a clipper by calling the IDirectDraw3::CreateClipper method.

    Use the following code to create the clipper object and retrieve a pointer to the IDirectDrawClipper interface.

    g_pDD3->CreateClipper(0, &g_pDDClipper, NULL);
  10. Use the IDirectDrawSurface interface to attach the clipper to the primary surface.
    g_pPrimarySurface->SetClipper(g_pDDClipper);
  11. Finally, associate the clipper with the window by calling the IDirectDrawClipper::SetHWnd method.
    g_pDDClipper->SetHWnd(0, ghWnd);

At this point, you should have two DirectDraw surfaces, and a clipper attached to the primary surface and to the applications window. The DirectDrawEx initialization is complete and all the objects are available to the process until the ExitCode function is called to release the objects.

For more information on DirectDrawEx, see DirectDrawEx.

Open a Movie File

The following code shows how to use the GetOpenMovieFile function to display the Open file dialog box. It initializes the OPENFILENAME structure and calls the GetOpenFileName API.

BOOL GetOpenMovieFile(LPSTR szName)
{
    OPENFILENAME	ofn;

    ofn.lStructSize       = sizeof(OPENFILENAME);
    ofn.hwndOwner         = ghWnd;
    ofn.lpstrFilter       = NULL;
    ofn.lpstrFilter       = "Video (*.avi;*.mpg;*.mpeg)\0*.avi;*.mpg;*.mpeg\0All Files (*.*)\0*.*\0";
    ofn.lpstrCustomFilter = NULL;
    ofn.nFilterIndex      = 1;
    *szName = 0;
    ofn.lpstrFile         = szName;
    ofn.nMaxFile          = MAX_PATH;
    ofn.lpstrInitialDir   = NULL;
    ofn.lpstrTitle        = NULL;
    ofn.lpstrFileTitle    = NULL;
    ofn.lpstrDefExt       = NULL;
    ofn.Flags             = OFN_FILEMUSTEXIST | OFN_READONLY | OFN_PATHMUSTEXIST;
    return GetOpenFileName((LPOPENFILENAME)&ofn);
}

Create the Multimedia Stream Object

The RenderFileToMMStream function creates a multimedia stream and attaches the stream to the file retrieved by the GetOpenMovieFile function. This function uses the IAMMultiMediaStream interface to expose DirectShow functionality to the application. After the address of a pointer to the IAMMultiMediaStream interface is retrieved, it will be used to initialize the stream, add specific media streams to the current filter graph, and open and automatically create a filter graph for the specified media file.

The following steps show how to do this.

  1. Declare the local variables hr and pAMStream, and convert the provided file name to a wide (Unicode) string.
    HRESULT hr;
IAMMultiMediaStream *pAMStream=NULL;
WCHAR wFile[MAX_PATH];
MultiByteToWideChar(CP_ACP, 0, szFilename, -1, wFile,
            sizeof(wFile)/sizeof(wFile[0]));
  2. Create the AMMultiMediaStream object and initialize it.
    hr =CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
                                      IID_IAMMultiMediaStream, (void **)&pAMStream);
hr = pAMStream->Initialize(STREAMTYPE_READ, 0, NULL);
  3. Now that you have a stream object, add a single audio and video stream to it; typically, you need only these two streams for media file playback. When the IAMMultiMediaStream::AddMediaStream method receives the MSPID_PrimaryVideo flag as its second parameter, it uses the pointer in the first parameter as the destination surface for video playback. The audio stream needs no such surface, however, so pass NULL as the first parameter when you add audio streams. The AMMSF_ADDDEFAULTRENDERER flag automatically adds the default sound renderer to the current filter graph.

hr = pAMStream->AddMediaStream(g_pDD3, &MSPID_PrimaryVideo, 0, NULL);
hr = pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, AMMSF_ADDDEFAULTRENDERER, NULL);
  4. Finally, open and create a filter graph for the specified media file and save the local stream to the global variable g_pMMStream. Don't forget to increase the reference count on the IAMMultiMediaStream object.
    //Opens and automatically creates a filter graph for the specified media file
hr = pAMStream->OpenFile(wFile, 0);
//save the local stream to the global variable
g_pMMStream = pAMStream;
// Add a reference to the file
pAMStream->AddRef();

Now that you have valid streams and a pointer to them, this function is complete. For more information on multimedia streams see and Use Multimedia Streaming in DirectShow Applications.

Create the Stream Sample Object

The InitRenderToSurface function creates the stream sample that will be associated with the offscreen DirectDrawSurface object. The stream sample will be used later by the RenderToSurface function to call the IStreamSample::Update method to perform frame-by-frame updates of the sample.

The following steps show how to do this.

  1. To create and initialize the stream sample, declare the local variables, and then get the primary video media stream by using the IMultiMediaStream::GetMediaStream method.
    HRESULT			hr;
DDSURFACEDESC	ddsd;

//Use the multimedia stream to get the primary video media stream
hr = g_pMMStream->GetMediaStream(MSPID_PrimaryVideo, &g_pPrimaryVidStream);
  2. After you obtain the primary video stream interface (IMediaStream), you can use it to query for the IDirectDrawMediaStream interface, which you'll use to create the stream sample.
    hr = g_pPrimaryVidStream->QueryInterface(IID_IDirectDrawMediaStream, (void **)&g_pDDStream);
  3. Before you can create the stream sample, you must call the IDirectDrawMediaStream::GetFormat method. The trick to watch on this call is that you must set the dwSize member of the DDSURFACEDESC structure. After the stream sample has retrieved the height and width of the movie file, you can set the rectangle that the offscreen surface will use to contain the video data.
    ddsd.dwSize = sizeof(ddsd);
hr = g_pDDStream->GetFormat(&ddsd, NULL, NULL, NULL);
rect.top = rect.left = 0;
rect.bottom = ddsd.dwHeight;
rect.right = ddsd.dwWidth;
  4. Create the stream sample by calling the IDirectDrawMediaStream::CreateSample method with the offscreen surface and the RECT structure, which was just initialized with the movie coordinates. This method will retrieve a pointer to the global IDirectDrawStreamSample interface g_pSample.
    hr = g_pDDStream->CreateSample(g_pDDSOffscreen, &rect, 0, &g_pSample);

At this point, the IDirectDrawMediaStream::CreateSample method has created a global IDirectDrawStreamSample stream sample and returned a pointer to g_pSample, its interface, which the RenderToSurface function can use.

Render the Multimedia Stream to the DirectDraw Surface

The RenderToSurface function handles the actual rendering and blits the video stream's data to the primary surface. The main message pump in the WinMain function calls this method. The RenderToSurface function performs one individual frame update at a time and one blit from the offscreen surface to the primary surface. When the movie is complete, it will set the stream state to STOP.

The following steps show how to do this.

  1. Declare the local variables.
    HRESULT		hr;
POINT		point;
  2. Call the IStreamSample::Update method. Each loop iteration throws out the previous video image and grabs the next image from the stream.

    If the update is successful, the Microsoft Win32® GetClientRect and the ClientToScreen functions are called to get the rectangle coordinates of the window into which the video will be displayed. These functions must be called after each update, in case a user has moved or resized the window.

  3. After the window's coordinates have been retrieved, call the IDirectDrawSurface3::Blt method to perform a bit block transfer of the movie's video data from the offscreen surface to the primary surface. The loop breaks and the stream state is set to STOP when no renderable video data remains.
    if (g_pSample->Update(0, NULL, NULL, 0) != S_OK) {
        g_bAppactive = FALSE;
        g_pMMStream->SetState(STREAMSTATE_STOP);
    }
    else {
    //get window coordinates to blit into
    GetClientRect(ghWnd, &rect2);
    point.x = rect2.top;
    point.y = rect2.left;
    ClientToScreen(ghWnd, &point);
    rect2.left = point.x;
    rect2.top = point.y;
    point.x = rect2.right;
    point.y = rect2.bottom;
    ClientToScreen(ghWnd, &point);
    rect2.right = point.x;
    rect2.bottom= point.y;

//Blit from the offscreen surface to the primary surface
    hr = g_pPrimarySurface->Blt(&rect2, g_pDDSOffscreen, &rect, DDBLT_WAIT, NULL);

    This function will be called repeatedly from the WinMain function's message pump as long as the g_bAppactive and g_bFileLoaded Boolean values are TRUE.

Release Objects

The ExitCode function releases all objects that the MovieWin application creates, destroys the window, and closes the COM library.

Call this function if the application fails or the user quits the program.

void ExitCode()
{
    //Release MultiMedia streaming Objects
    if (g_pMMStream != NULL) {
        g_pMMStream->Release();
        g_pMMStream= NULL;
    }
    if (g_pSample != NULL) {
        g_pSample->Release();
        g_pSample = NULL;
    }
    if (g_pDDStream != NULL) {
        g_pDDStream->Release();
        g_pDDStream= NULL;
    }
    if (g_pPrimaryVidStream != NULL) {
        g_pPrimaryVidStream->Release();
        g_pPrimaryVidStream= NULL;
    }
    //Release DirectDraw Objects
    if (g_pDDF !=NULL) {
        g_pDDF->Release();
        g_pDDF = NULL;
    }
    if (g_pPrimarySurface!=NULL) {
        g_pPrimarySurface->Release();
        g_pPrimarySurface=NULL;
    }
    if (g_pDDSOffscreen !=NULL) {
        g_pDDSOffscreen->Release();
        g_pDDSOffscreen= NULL;
    }
    if (g_pDDClipper !=NULL) {
        g_pDDClipper->Release();
        g_pDDClipper=NULL;
    }
    if (g_pDD3 != NULL) {
        g_pDD3->Release();
        g_pDD3 = NULL;
    }
    if (g_pDD != NULL) {
        g_pDD->Release();
        g_pDD = NULL;
    }

    PostQuitMessage(0);
    CoUninitialize();
}

WndMainProc Function

The WndMainProc callback function handles any messages sent to the window and calls the ExitCode function when the user quits the application. Users generate messages by selecting various items from the menu, including Open, Start, Stop, Pause, About, and Exit.

If the user chooses Open, an IDM_OPEN message is generated and the following code runs.

//If a file is already open - call STOP first
                    if (g_bAppactive && g_bFileLoaded) {
                        g_pMMStream->SetState(STREAMSTATE_STOP);
                    }

                    bOpen = GetOpenMovieFile(szFilename);
                    if (bOpen) {
                        hr = RenderFileToMMStream(szFilename);
                        hr = InitRenderToSurface();
                        g_bAppactive = g_bFileLoaded = TRUE;
                        g_bPaused = FALSE;		//Take care of any old pauses
                        //Now set the multimedia stream to RUN
                        hr = g_pMMStream->SetState(STREAMSTATE_RUN);
                    }
                    break;

This code first checks whether a file is loaded (g_bFileLoaded) and if it is in a running state (g_bAppactive). If this is the case, the IMultiMediaStream::SetState method is called to stop the stream before another one is loaded through a call to the GetOpenMovieFile function. After the call to GetOpenMovieFile has returned successfully, the RenderFileToMMStream function is called, followed by the InitRenderToSurface function. If both of these functions are successful, the g_bFileLoaded and g_bAppactive Boolean values are set to TRUE and g_bPaused is set to FALSE in case the old file was in a paused state. Finally, the IMultiMediaStream::SetState method is called to set the state to RUN and now the RenderToSurface function will automatically be called through the WinMain function's message pump.

If the user chooses Play from the application's menu, an IDM_START message is generated and the following code runs.

if (g_bAppactive && g_bFileLoaded)
                    {break;					// If its already playing get out of here
                    }
                    else {
                        if (g_bPaused) {	// If its in a paused state, seek and run
                            g_pMMStream->Seek(StreamTime);
                            g_pMMStream->SetState(STREAMSTATE_RUN);
                            g_bAppactive = TRUE;
                            g_bPaused = FALSE;
                            }
                        else {

                    if (g_bFileLoaded) {	// If a file is actually loaded
                        g_bAppactive = g_bFileLoaded = TRUE;
                        hr = g_pMMStream->SetState(STREAMSTATE_RUN);
                    }
                    else {
                        MessageBox(hWnd, "Please select a movie file first.", "Error", MB_OK);
                    }
                    }
                    }
                    break;

This code first checks if a file is loaded (g_bFileLoaded) and if it is in a running state (g_bAppactive). If this is the case, break is called to ignore the message. If the movie is in a paused state, the IMultiMediaStream::Seek method is called to seek to the correct location in the file, and then the IMultiMediaStream::SetState method is called to set the state to RUN again. The Boolean values g_bAppactive and g_bPaused are reset again to TRUE and FALSE respectively.

If a file is loaded but not in a paused state, it must be in a stopped state. Therefore, if this code succeeds on the if (g_bFileLoaded) call it must restart the movie from the beginning. This involves resetting the g_bAppactive Boolean value to TRUE and calling the IMultiMediaStream::SetState method to set the stream state to RUN.

If the user chooses Pause from MovieWin's menu, an IDM_PAUSE message is generated and the following code runs.

// Pause if not already in a paused state and you have a file loaded
                    if (!g_bPaused &&g_bFileLoaded) {
                        hr = g_pMMStream->GetTime(&StreamTime);
                        hr = g_pMMStream->SetState(STREAMSTATE_STOP);
                        g_bAppactive = FALSE;
                        g_bPaused	= TRUE;
                    }
                    break;				// If its already paused, just break

In order for the pause key to do anything, the application must not already be in a paused stated (!g_bPaused) and a file must be loaded (g_bFileLoaded). If these two conditions are both TRUE, the IMultiMediaStream::GetTime method is called to store the STREAM_TIME at which the application was paused in the static StreamTime variable, and then the IMultiMediaStream::SetState method set the stream state to STOP. Finally, the g_bAppactive and the g_bPaused global Boolean values must be set to FALSE and TRUE respectively.

If the user chooses Stop from the application's menu, an IDM_STOP message is generated and the following code executes.

if (g_bFileLoaded) {
                        g_pMMStream->SetState(STREAMSTATE_STOP);
                        StreamTime = 0;	// Reset the stream time to 0
                        g_pMMStream->Seek(StreamTime);	//Run one frame to reset video
                        g_pMMStream->SetState(STREAMSTATE_RUN);
                        RenderToSurface();
                        g_pMMStream->SetState(STREAMSTATE_STOP); // Stop for real this time
                        StreamTime = 0;
                    }
                    g_bAppactive = FALSE;

The preceding code runs if there is a file loaded (g_bFileLoaded). In such a case the IMultiMediaStream::SetState method sets the stream state to STOP and the global STREAM_TIME value is set to zero. Next, the IMultiMediaStream::Seek method and the IMultiMediaStream::SetState method are called to run one frame of the video before the true stop is called. After the RenderToSurface function renders the frame, the IMultiMediaStream::SetState method is called a final time to stop the video. This gives the user the visual experience of seeing the movie rewind to the beginning.

Finally, if the user chooses Exit from the application's menu, an IDM_EXIT message is generated and the following code runs.

response = MessageBox(hWnd, "Quit the Program?", "Quit", MB_YESNO);
                    if (response==IDYES) SendMessage(ghWnd, WM_DESTROY,0,0);
                    break;

When it runs, this code will prompt the user if he or she really wants to quit the application. If the user chooses Yes, a WM_DESTROY message is sent, which calls the ExitCode function.

Entire MovieWin Example Code

This is the entire code for the MovieWin example code. To compile this code in Microsoft Visual Studio™, create a new Win32 application project and add this code into the project. Follow the directions in the following code comments on how to set your project libraries and include paths.

// This application uses a Multimedia stream to render
// a video file to a DirectDrawEx surface contained in
// a window. It implements a primary DirectDraw surface
// and an offscreen DirectDraw surface to optimize individual
// frame blits. It also attaches a DirectDraw clipper to the
// window to process window overlapping.

//To compile this program you must have DXMedia SDK 5.1 installed
//and you will need set your include path under tools/options/directories/include
//to c:\DXMedia\include and your library path to c:\DXMedia\lib
//Also link with the following libraries under project/settings/link...
//amstrmid.lib quartz.lib strmbase.lib ddraw.lib

#include <windows.h>
#include <mmstream.h>	// Multimedia stream interfaces
#include <amstream.h>	// DirectShow multimedia stream interfaces
#include <ddstream.h>	// DirectDraw multimedia stream interfaces
#include <initguid.h>   // Defines DEFINE_GUID macro and enables GUID initialization
#include <ddrawex.h>	// DirectDrawEx interfaces
#include "resource.h"	// Resources for the menu bar

#define APPLICATIONNAME "Multimedia Stream In Window"
#define CLASSNAME "MMSDDRAWEXWINDOW"

//Global variables
HWND			  ghWnd;
HINSTANCE		ghInst;
BOOL			  g_bAppactive=FALSE,		// The window is active
                    g_bFileLoaded = FALSE,  // There is a file loaded
                    g_bPaused=FALSE;		// The movie has been paused
RECT			  rect, rect2;			// Rectangles for screen coordinates

//DirectDrawEx Global interfaces
IDirectDraw			*g_pDD=NULL;
IDirectDraw3		*g_pDD3=NULL;
IDirectDrawFactory	*g_pDDF=NULL;
IDirectDrawSurface	*g_pPrimarySurface=NULL,
                    *g_pDDSOffscreen=NULL;
IDirectDrawClipper	*g_pDDClipper=NULL;

//Global MultiMedia streaming interfaces
IMultiMediaStream		*g_pMMStream=NULL;
IMediaStream			*g_pPrimaryVidStream=NULL;
IDirectDrawMediaStream	*g_pDDStream=NULL;
IDirectDrawStreamSample *g_pSample=NULL;

//Function prototypes
int PASCAL WinMain(HINSTANCE hInstC, HINSTANCE hInstP, LPSTR lpCmdLine, int nCmdShow);
LRESULT CALLBACK WndMainProc (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);
HRESULT InitDDrawEx();
BOOL GetOpenMovieFile(LPSTR szName);
HRESULT RenderFileToMMStream(LPCTSTR szFilename);
HRESULT InitRenderToSurface();
void RenderToSurface();
void ExitCode();

void ExitCode()
{
    //Release MultiMedia streaming Objects
    if (g_pMMStream != NULL) {
        g_pMMStream->Release();
        g_pMMStream= NULL;
    }
    if (g_pSample != NULL) {
        g_pSample->Release();
        g_pSample = NULL;
    }
    if (g_pDDStream != NULL) {
        g_pDDStream->Release();
        g_pDDStream= NULL;
    }
    if (g_pPrimaryVidStream != NULL) {
        g_pPrimaryVidStream->Release();
        g_pPrimaryVidStream= NULL;
    }
    //Release DirectDraw Objects
    if (g_pDDF !=NULL) {
        g_pDDF->Release();
        g_pDDF = NULL;
    }
    if (g_pPrimarySurface!=NULL) {
        g_pPrimarySurface->Release();
        g_pPrimarySurface=NULL;
    }
    if (g_pDDSOffscreen !=NULL) {
        g_pDDSOffscreen->Release();
        g_pDDSOffscreen= NULL;
    }
    if (g_pDDClipper !=NULL) {
        g_pDDClipper->Release();
        g_pDDClipper=NULL;
    }
    if (g_pDD3 != NULL) {
        g_pDD3->Release();
        g_pDD3 = NULL;
    }
    if (g_pDD != NULL) {
        g_pDD->Release();
        g_pDD = NULL;
    }

    PostQuitMessage(0);
    CoUninitialize();
}

//Create the stream sample which will be used to call updates on the video
HRESULT InitRenderToSurface()
{
    HRESULT			hr;
    DDSURFACEDESC	ddsd;

    //Use the multimedia stream to get the primary video media stream
    hr = g_pMMStream->GetMediaStream(MSPID_PrimaryVideo, &g_pPrimaryVidStream);
    if (FAILED(hr))
    {   goto Exit;
    }
    //Use the media stream to get the IDirectDrawMediaStream
    hr = g_pPrimaryVidStream->QueryInterface(IID_IDirectDrawMediaStream, (void **)&g_pDDStream);
    if (FAILED(hr))
    {   goto Exit;
    }
    //Must set dwSize before calling GetFormat
    ddsd.dwSize = sizeof(ddsd);
    hr = g_pDDStream->GetFormat(&ddsd, NULL, NULL, NULL);
    if (FAILED(hr))
    {   goto Exit;
    }

      rect.top = rect.left = 0;
    rect.bottom = ddsd.dwHeight;
    rect.right = ddsd.dwWidth;

    //Create the stream sample
    hr = g_pDDStream->CreateSample(g_pDDSOffscreen, &rect, 0, &g_pSample);
    if (FAILED(hr))
    {   goto Exit;
    }
Exit:
    if (FAILED(hr))
    {	MessageBox(ghWnd, "Initialization failure in InitRenderToSurface", "Error", MB_OK);
        return E_FAIL;
    }
    return NOERROR;
}

//Perform frame by frame updates and blits. Set the stream
//state to STOP if there are no more frames to update.
void RenderToSurface()
{
    HRESULT		hr;
    POINT		point;

    //update each frame
    if (g_pSample->Update(0, NULL, NULL, 0) != S_OK) {
        g_bAppactive = FALSE;
        g_pMMStream->SetState(STREAMSTATE_STOP);
    }
    else {
    //get window coordinates to blit into
    GetClientRect(ghWnd, &rect2);
    point.x = rect2.top;
    point.y = rect2.left;
    ClientToScreen(ghWnd, &point);
    rect2.left = point.x;
    rect2.top = point.y;
    point.x = rect2.right;
    point.y = rect2.bottom;
    ClientToScreen(ghWnd, &point);
    rect2.right = point.x;
    rect2.bottom= point.y;

    //blit from the offscreen surface to the primary surface
    hr = g_pPrimarySurface->Blt(&rect2, g_pDDSOffscreen, &rect, DDBLT_WAIT, NULL);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Blt failed", "Error", MB_OK);
            ExitCode();
    }
    }
}

//Renders a file to a multimedia stream
HRESULT RenderFileToMMStream(LPCTSTR szFilename)		//IMultiMediaStream **ppMMStream
{
    HRESULT hr;
    IAMMultiMediaStream *pAMStream=NULL;

//Convert filename to Unicode
    WCHAR wFile[MAX_PATH];
    MultiByteToWideChar(CP_ACP, 0, szFilename, -1, wFile,
                                sizeof(wFile)/sizeof(wFile[0]));

    //Create the AMMultiMediaStream object
    hr =CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
                                      IID_IAMMultiMediaStream, (void **)&pAMStream);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "Could not create a CLSID_MultiMediaStream object\n"
        "Check you have run regsvr32 amstream.dll\n", "Error", MB_OK);
          return E_FAIL;
    }

    //Initialize stream
    hr = pAMStream->Initialize(STREAMTYPE_READ, 0, NULL);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "Initialize failed.", "Error", MB_OK);
          return E_FAIL;
    }
    //Add primary video stream
    hr = pAMStream->AddMediaStream(g_pDD3, &MSPID_PrimaryVideo, 0, NULL);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "AddMediaStream failed.", "Error", MB_OK);
          return E_FAIL;
    }
    //Add primary audio stream
    hr = pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, AMMSF_ADDDEFAULTRENDERER, NULL);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "AddMediaStream failed.", "Error", MB_OK);
          return E_FAIL;
    }
    //Opens and automatically creates a filter graph for the specified media file
    hr = pAMStream->OpenFile(wFile, 0);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "File format not supported.", "Error", MB_OK);
          return E_FAIL;
    }

    //save the local stream to the global variable
    g_pMMStream = pAMStream;
    // Add a reference to the file
    pAMStream->AddRef();

    return NOERROR;
}

HRESULT InitDDrawEx()
{
    HRESULT			hr=NOERROR;
    DDSURFACEDESC	ddsd, ddsd2;

    CoInitialize(NULL);

    //Create a DirectDrawFactory object
    hr = CoCreateInstance(CLSID_DirectDrawFactory, NULL, CLSCTX_INPROC_SERVER,
                            IID_IDirectDrawFactory, (void **)&g_pDDF);
    if (FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't create DirectDrawFactory", "Error", MB_OK);
          return E_FAIL;
    }

    //Call the IDirectDrawFactory::CreateDirectDraw method to create the
    //DirectDraw object, set the cooperative level, and get the address
    //of an IDirectDraw interface pointer
    hr = (g_pDDF->CreateDirectDraw(NULL, GetDesktopWindow(), DDSCL_NORMAL,
                NULL, NULL, &g_pDD));

    if (FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't create DirectDraw object", "Error", MB_OK);
          return E_FAIL;
    }

    //Now query for the new IDirectDraw3 interface
    hr =(g_pDD->QueryInterface(IID_IDirectDraw3, (LPVOID*)&g_pDD3));

    if (FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't get IDirectDraw3", "Error", MB_OK);
          return E_FAIL;
    }

    //Initialize the DDSURFACEDESC structure for the primary surface
      ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);
      ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    hr = g_pDD3->CreateSurface(&ddsd, &g_pPrimarySurface, NULL);

    if(FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't create Primary Surface", "Error", MB_OK);
          return E_FAIL;
    }

    // Now, do the same for the offscreen surface.

    // The offscreen surface needs to use the same pixel format as the primary.
    // Query the primary surface to for its pixel format.
    hr = g_pPrimarySurface->GetSurfaceDesc(&ddsd);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't GetSurfaceDesc", "Error", MB_OK);
            return E_FAIL;
    }

    // Now, set the info for the offscreen surface, using the primary's pixel format.
    ZeroMemory(&ddsd2, sizeof(ddsd2));
    ddsd2.dwSize = sizeof(ddsd2);
    ddsd2.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
    ddsd2.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
    ddsd2.dwHeight = ddsd.dwHeight;	//set the height of the surfaces equal
    ddsd2.dwWidth  = ddsd.dwWidth;	//set the width of the surfaces equal
    ddsd2.ddpfPixelFormat = ddsd.ddpfPixelFormat; //set the pixel formats equal

    // Now, create the offscreen surface and query for the latest interface.
    hr = g_pDD3->CreateSurface(&ddsd2, &g_pDDSOffscreen, NULL);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't create Offscreen Surface", "Error", MB_OK);
            return E_FAIL;
    }

    //Add code for Clipper
    hr = g_pDD3->CreateClipper(0, &g_pDDClipper, NULL);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Couldn't create Clipper", "Error", MB_OK);
            return E_FAIL;
    }

    hr = g_pPrimarySurface->SetClipper(g_pDDClipper);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Call to SetClipper failed", "Error", MB_OK);
            return E_FAIL;
    }

    hr = g_pDDClipper->SetHWnd(0, ghWnd);
    if(FAILED(hr))
    {   MessageBox(ghWnd, "Call to SetHWnd failed", "Error", MB_OK);
            return E_FAIL;
    }

    return NOERROR;
}

// Display the open dialog box to retrieve the user-selected movie file
BOOL GetOpenMovieFile(LPSTR szName)//LPSTR szName
{
    OPENFILENAME	ofn;

    ofn.lStructSize       = sizeof(OPENFILENAME);
    ofn.hwndOwner         = ghWnd;
    ofn.lpstrFilter       = NULL;
    ofn.lpstrFilter       = "Video (*.avi;*.mpg;*.mpeg)\0*.avi;*.mpg;*.mpeg\0All Files (*.*)\0*.*\0";
    ofn.lpstrCustomFilter = NULL;
    ofn.nFilterIndex      = 1;
    *szName = 0;
    ofn.lpstrFile         = szName;
    ofn.nMaxFile          = MAX_PATH;
    ofn.lpstrInitialDir   = NULL;
    ofn.lpstrTitle        = NULL;
    ofn.lpstrFileTitle    = NULL;
    ofn.lpstrDefExt       = NULL;
    ofn.Flags             = OFN_FILEMUSTEXIST | OFN_READONLY | OFN_PATHMUSTEXIST;
    return GetOpenFileName((LPOPENFILENAME)&ofn);
}

LRESULT CALLBACK WndMainProc (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)

   {  // WndMainProc //

    int						response;
    HRESULT					hr;
    BOOL					bOpen;
    static TCHAR			szFilename[MAX_PATH];
    static STREAM_TIME		StreamTime;		// Stream time of the movie file

    switch(message)
    {
        case WM_COMMAND:
            {
               switch(wParam)
               //Program menu option
               {
                case IDM_OPEN:
                    //If a file is already open - call STOP first
                    if (g_bAppactive && g_bFileLoaded) {
                        g_pMMStream->SetState(STREAMSTATE_STOP);
                    }

                    bOpen = GetOpenMovieFile(szFilename);
                    if (bOpen) {
                        hr = RenderFileToMMStream(szFilename);
                        if (FAILED(hr)) {
                            ExitCode();
                            break;
                            }
                        hr = InitRenderToSurface();
                        if (FAILED(hr)) {
                            ExitCode();
                            break;
                            }
                        g_bAppactive = g_bFileLoaded = TRUE;
                        g_bPaused = FALSE;		//Take care of any old pauses
                        //Now set the multimedia stream to RUN
                        hr = g_pMMStream->SetState(STREAMSTATE_RUN);
                        if (FAILED(hr))
                        {   ExitCode();
                        }
                    }
                    break;

                case IDM_START:
                    if (g_bAppactive && g_bFileLoaded)
                    {break;					// If its already playing get out of here
                    }
                    else {
                        if (g_bPaused) {	// If its in a paused state, seek and run
                            g_pMMStream->Seek(StreamTime);
                            g_pMMStream->SetState(STREAMSTATE_RUN);
                            g_bAppactive = TRUE;
                            g_bPaused = FALSE;
                            }
                        else {

                    if (g_bFileLoaded) {	// If a file is actually loaded
                        hr = RenderFileToMMStream(szFilename);	// Render file to stream
                        if (FAILED(hr)) {
                            ExitCode();
                            break;
                            }
                        hr = InitRenderToSurface();		// Render stream
                        if (FAILED(hr)) {
                            ExitCode();
                            break;
                            }
                        g_bAppactive = g_bFileLoaded = TRUE;
                        //Now set the multimedia stream to RUN
                        hr = g_pMMStream->SetState(STREAMSTATE_RUN);
                        if (FAILED(hr))
                        {   ExitCode();
                        }
                    }
                    else {
                        MessageBox(hWnd, "Please select a movie file first.", "Error", MB_OK);
                    }
                    }
                    }
                    break;

                case IDM_PAUSE:
                    // Pause if not already in a paused state and you have a file loaded
                    if (!g_bPaused &&g_bFileLoaded) {
                        hr = g_pMMStream->GetTime(&StreamTime);
                        hr = g_pMMStream->SetState(STREAMSTATE_STOP);
                        g_bAppactive = FALSE;
                        g_bPaused	= TRUE;
                    }
                    break;				// If its already paused, just break

                case IDM_STOP:
                    if (g_bFileLoaded) {
                        g_pMMStream->SetState(STREAMSTATE_STOP);
                        StreamTime = 0;	// Reset the stream time to 0
                        g_pMMStream->Seek(StreamTime);	//Run one frame to reset video
                        g_pMMStream->SetState(STREAMSTATE_RUN);
                        RenderToSurface();
                        g_pMMStream->SetState(STREAMSTATE_STOP); // Stop for real this time
                        StreamTime = 0;
                    }
                    g_bAppactive = FALSE;
                    break;

                case IDM_ABOUT:
                    MessageBox(hWnd, "This application uses multimedia streaming to"
                        " render a video file to a DirectDraw surface created through DirectDrawEx.",
                        "About", MB_OK);
                    break;

                case IDM_EXIT:
                    response = MessageBox(hWnd, "Quit the Program?", "Quit", MB_YESNO);
                    if (response==IDYES) SendMessage(ghWnd, WM_DESTROY,0,0);
                    break;
            }
           break;
            }
        break;

        case WM_DESTROY:
           ExitCode();
           break;

        case WM_ACTIVATE:
            if((BOOL)LOWORD(wParam) == WA_INACTIVE)
            {
                //App is not active
                g_bAppactive = FALSE;
            }
            else
            {
                //Set app to active if a file is loaded
                g_bAppactive = (g_bFileLoaded)?TRUE:FALSE;
            }
            break;

        default:
           return DefWindowProc(hWnd, message, wParam, lParam);

      }  // Window msgs handling

      return FALSE;

   }  // WndMainProc //

int PASCAL WinMain(HINSTANCE hInstC, HINSTANCE hInstP, LPSTR lpCmdLine, int nCmdShow)

   {  // WinMain //

      MSG		msg;
      WNDCLASS  wc;
        HRESULT	hr;

      ZeroMemory(&wc, sizeof wc);
      wc.lpfnWndProc = WndMainProc;
      ghInst = wc.hInstance = hInstC;
        wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
      wc.lpszClassName = CLASSNAME;
      wc.lpszMenuName = MAKEINTRESOURCE(IDR_MENU);
      wc.hCursor = LoadCursor(NULL, IDC_ARROW);
      RegisterClass(&wc);

      ghWnd = CreateWindowEx(WS_EX_WINDOWEDGE,
        CLASSNAME,
        APPLICATIONNAME,
        WS_VISIBLE |WS_POPUP |WS_OVERLAPPEDWINDOW,
        150,
        150,
        280,
        250,
        0,
        0,
        ghInst,
        0);
      if (ghWnd) {				// If the call to create window succeeds,
          hr = InitDDrawEx();	// initialize DirectDrawEx
          if (FAILED(hr)) {
              ExitCode();
          }
      }
      else {
          MessageBox(ghWnd, "Couldn't create window.", "Error", MB_OK);
          return 0;
      }

      ShowWindow(ghWnd, SW_NORMAL);
      UpdateWindow(ghWnd);

      while(1){
        //The PeekMessage function checks a thread message queue
        //for a message and places the message (if any) in the specified structure.
        if(PeekMessage(&msg, NULL, 0,0,PM_NOREMOVE)){

            // Quit if WM_QUIT found
            if(!GetMessage(&msg,NULL, 0, 0)) return (msg.wParam);

            // Otherwise handle the messages
                TranslateMessage(&msg);		// Allow input
                DispatchMessage(&msg);		// Send to appropriate process.
        }
        else{
            // If there are no other windows messages...
            // Render frame by frame (but only if the App is the active
            // window and a file is actually loaded)
            if (g_bFileLoaded && g_bAppactive) {
                RenderToSurface();
                }
            }
        }
      return msg.wParam;

}  // WinMain //


DirectShow Animated Header -- Control an External Device in DirectShow DirectShow Animated Header -- Control an External Device in DirectShow * Microsoft DirectShow SDK
  * Previous Topic: Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming
  * Next Topic: Build a Filter or Application with Visual C++ 5.x

Control an External Device in DirectShow

This article provides background for developers interested in adding external device control and timecode support to DirectShow applications. It also discusses how timecode is used in the production environment and lists some typical applications that rely on external devices. Finally, it describes how external device control is implemented and provides links to the interfaces available to build VCR control- and timecode-enabled filters in DirectShow.

Contents of this article:

  • Introduction
  • Understanding SMPTE Timecode
  • Typical Uses of Timecode
  • Capturing Timecode
  • External Device Control
  • References and Suggested Reading

Introduction

You can control an external device in DirectShow by implementing device control filters. These filters control devices or streams of data which are entirely external to the computer and expose interfaces such as IAMExtDevice, IAMExtTransport, IAMTimecodeGenerator, and IAMTimecodeReader. Generally, external device control filters do not need to expose pins. However, an example of a device control filter that does expose pins might be a filter representing a source of data such as a VCR. A pin-to-pin connection representing the data flowing from the VCR to the capture board allows the device control filter and the video capture filter to talk to each other and negotiate data types, athough they do not use the standard transport and no data would flow between the filters themselves other than control information. Applications can instantiate and directly control an external device filter, but it is strongly recommended that they are always instantiated within the context of a filtergraph, even if they are the only filter in the graph.

External devices can include VCRs, video editing stations, audio tape recorders (ATRs), mixers, or any other device used in the video capture and editing process. Capture and editing requires DirectShow external device control filters to provide audio and video synchronization and precise control. You can accomplish synchronization of audio and video during playback, edit, and capture with external clocks or Society of Motion Picture and Television Engineers (SMPTE) timecode. Understanding timecode is the key to understanding external device control.

Understanding SMPTE Timecode

SMPTE timecode is the glue that holds the post-production process together. It identifies video and audio sources, makes automatic track synchronization possible, and provides a container for ancillary data related to the production. You will need to understand this data stream and its application to media production, tool development, or system design.

SMPTE timecode, more properly known as SMPTE time and control code, is a series of digital frame address values, flags and additional data applied to a video or audio stream, and is defined in ANSI/SMPTE 12-1986. Its purpose is to provide a machine readable address for video and audio.

The most common form of a SMPTE timecode data structure an 80-bit frame that contains the following information:

  1. A time stamp in hh:mm:ss:ff (hours:minutes:seconds:frames) format.
  2. Eight 4-bit binary groups commonly known as userbits.
  3. Various flag bits.
  4. Synchronization sequence.
  5. Checksum.

The DirectShow TIMECODE_SAMPLE structure is an example of a timecode data structure that contains timecode information for video or audio data.

SMPTE timecode comes in one of two types. Timecode recorded on an analog audio track as a bi-phase mark encoded signal is known as LTC, or Linear TimeCode (formerly known as Longitudinal TimeCode). Each timecode frame is one video frame time in duration. The other common type of timecode is known as VITC, or Vertical TimeCode. VITC is usually stored on two lines of a video signal's vertical blanking interval, somewhere between lines 10 and 20.

LTC timecode is easy to add to a pre-recorded tape, since it is encoded in a separate audio signal. However, it cannot be read when the tape is paused, moving very slowly, or very quickly. In addition it consumes one audio channel on non-professional VCRs.

VITC timecode, on the other hand, can be read from speeds of zero to 15 times normal speed. It can contain field-dependent data and can be read from video capture cards. However, it is not easily added to a prerecorded tape and often requires expensive hardware.

SMPTE timecode also comes in one of two modes, non-drop frame and drop frame. Non-drop frame is timecode that is consistently increasing and sequential. It can act as a real-time clock and works fine for monochrome video that runs at a frame rate of exactly 30 frames per second.

However, NTSC color video actually runs at a frame rate of 29.97 Hz (frames per second) because of some compatibility issues with monochrome television. This causes a problem with non-drop frame timecode because it gets out of step with real-time at the rate of 108 frames (or 3.6 seconds) per hour. This means that after 1 hour of playback, the timecode would read 00:59:56:12, assuming a start point of 00:00:00:00. This causes problems when trying to calculate show duration or using "time-of-day" referencing.

A solution to this problem is to skip some frames in the count every so often so the error is reduced to something tolerable. This compensation method is called "drop frame" and is implemented by skipping the first two frames from the count at the start of each minute except minutes 00, 10, 20, 30, 40 and 50. The net result is an error of less than 1 frame per hour, or about 3 frames per 24 hour period.

Drop frame is used more commonly in today's productions, although any implementation should support mixing both modes.

Typical Uses of Timecode

Applications which provide video capture and editing functionality will typically require control of external devices. These applications need to identify and index video and audio frames through references to SMPTE timecode. Linear editing system computers generally control three or more tape machines, as well as a video switcher and possibly a digital disk recorder. The controlling computer must execute commands at precise times and therefore must get videotapes cued to specific places at specific points in time.

Applications typically use timecode in a number of different ways including, but not limited to the following:

  • Tracking of video and audio sources throughout the editorial process so an edit decision list, or EDL, may be generated for archival or export to another system. To create an EDL:
    1. Shoot the video.
    2. Capture into a nonlinear offline system that uses some form of intraframe-only compression (MJPEG, DV, etc.).
    3. Edit the material and generate an edit decision list (EDL) and offline edited master.
    4. Import the EDL to an online system and do an "auto-assembly" using the original source material to generate the final master, adding titles and effects where required.
  • Synchronizing audio to video. In feature film production, audio is usually recorded on a separate tape recorder along with timecode. Specially equipped film cameras can also record timecode on the film in between the sprocket holes. After the filmed image is electronically transferred to videotape, the timecode is used to align the audio with the picture in a process known as "synching the dailies". If the audio and video timecodes are different, VITC and LTC may sometimes be used together, one for video timecode and the other for audio timecode.
  • Synchronization and triggering of multiple devices such as ATRs, digital disk recorder or players, VCRs, or other similar devices. This is a much broader class of synchronization than described above, and is most commonly seen in linear editing and nonlinear editing systems, closed captioning systems, and subtitling systems.
  • Making use of the undefined bits in the timecode, called userbits. Often information such as dates, ASCII codes, or film industry information is contained in the userbits, however uses of userbits is limited only to the ingenuity of the user.

It quickly becomes obvious that timecode makes many things possible when properly handled. Unfortunately, there is also a lot that can go wrong, either because of poor technique or hardware malfunctions. Some things to look out for on timecoded tapes are:

  1. Unstable or drifting timecode relative to video or audio.
  2. Poor timecode field integrity. This means an LTC word begins in the middle of a frame rather than at the beginning, or VITC is not updated on a true frame boundary. The net result is an ambiguous reference.
  3. Unintentional VITC/LTC mismatch.
  4. Intermittent dropouts.
  5. Missing timecode.
  6. Poor timecode signal quality.
  7. Incremental frame offset from incorrectly made copies.

Capturing Timecode

Timecode can be generated either by an external timecode generator, by a capture card capable of generating timecode, by the device control filter itself, or by an external device such as a VCR that has a built-in timecode reader. An RS-422 connection is generally necessary if the timecode is sent to the host from an external device.

Once timecode is generated, it needs to be captured either in tabular or stream format concurrently with the video or audio so that it can later be accessed during editing. This is handled in one of two ways:

1 Build a table that lists the timecode discontinuities indexed to frame position within the stream, and write the table to the end of the file after capture is complete. The list might be an array of structures that look like this (NOTE, the following structure is a simplification of the DirectShow TIMECODE_SAMPLE structure and is intended as an example only):

struct	{
        DWORD dwOffset;	// offset into stream in frames
        char[11] szTC;		// timecode value at offset in hh:mm:ss:ff
                          //  for non drop, hh:mm:ss;ff for drop frame
        } TIMECODE;

For example, given a captured video stream with one timecode break in it, the list might look like this:

{0, 02:00:00:02},
{16305, 15:21:13:29}		// timecode jumps at frame 16305

Using this table, any frame's timecode can be easily calculated.

2 Treat the data as a stream and write it to the file just as video and audio are written. This is useful for rapidly changing data or even non-timecode data in the vertical blanking interval (VBI) such as closed captioning data.

Once the timecode data is properly stored with its associated frame data, applications that edit, composite, synchronize or trigger can access and use a familiar and standard indexing system.

External Device Control

To understand external device control, it is necessary to understand timecode. The key things to remember about timecode are:

  • SMPTE timecode is a frame addressing system that identifies video and audio frames. It comes in many types and modes: LTC, VITC, Drop Frame, Non-Drop Frame, and operates at various frame rates: 24, 25, 29.97, and 30 frames per second.
  • SMPTE timecode is used in edit decision lists (EDLs) which are generated for offline editing and online editing, as a timing reference for synchronizing hardware devices, and as a vehicle for additional data such as production source or film reference information.
  • SMPTE timecode can be stored as a stream or table of discontinuities.
  • Timelines are necessary for synchronization, and can be local to the controlling computer, external synchronizer, or the controlled device itself.

Given this background, two fundamental problems exist with device control. First, hundreds of different communication protocols exist for all the various devices from all the various manufacturers. Although some devices are more widely used than others, such as VCRs and Laserdiscs, almost all have a different remote control interface. As more sophisticated professional video and audio applications continue to move to the desktop, this problem gets worse. Due to this myriad of protocols, separate DirectShow filters must be implemented for each and every external device you want to control.

Second, the fundamental problem in the design of professional video and audio systems is that events must occur at precise points in time. Taking a systems view of this issue, consider the following timing diagram:

Basic Video Production System Timing Diagram

The horizontal axis denotes time in video fields, or roughly 1/60 of a second for NTSC video. The key point here is that all signals line up in time, that is, timecode starts at the beginning of a frame (System Frame Pulse). External devices such as tape machines are aligned with the system reference, as well as digital video playback such as an AVI file run from an AVI-enabled application.

Conformance to this timing requirement is achieved by various means, the most common of which is a master reference signal distributed to all components in the system. This reference is known as "blackburst" in the video world, so named because it is a composite video signal containing no active video above black level. The "burst" portion of the name refers to the color burst portion of the video signal. Each device connected to the reference is responsible for maintaining its own synchronization. This means for example, that a digital video player must switch frames during the vertical blanking interval, a tape machine must switch into record mode during the vertical blanking interval, commands sent to external devices via a serial port must be timed to the frame pulse, and all of these and other synchronized events must occur when the SMPTE timecode hits a predetermined value. Failure to conform to these rules results in tearing of a video image or edits occurring at the wrong point in time.

Accomplishing all this in the professional video world is relatively straightforward, but in the hybrid world of desktop video, it is very difficult.

Building on the concepts presented so far, the two design examples in the following diagrams illustrate a potential configuration of external devices.

Basic Single VCR Digital Video Editing System Block Diagram

Basic Multi-VCR Video Editing System Block Diagram

The block diagrams show that it is relatively simple to distribute the reference signal to all of the boxes. To deal with synchronization that takes place within the computer, for example, between the timecode reader and digital video player, it is recommended that either a "vertical drive" hardware interrupt, specialized operating system services, or some other custom solution be used.

Finally, if you intend to write an external device filter, you should implement the IAMExtDevice, IAMExtTransport, IAMTimecodeReader, IAMTimecodeGenerator, and IAMTimecodeDisplay interfaces provided by DirectShow. Additionally if you need to move binary messages to and from an external device, for example, to download executable code for the external device's microprocessor to execute, this should be accomplished by implementing the COM IDataObject interface, which has a complete set of methods for handling binary data transfers. Use this interface for whatever custom data transfer purposes your filter needs.

For sample code that demonstrates how to implement an external device control filter see the Samples\DS\Vcrctrl folder in the DirectX Media SDK.

References and Suggested Reading

For additional information on SMPTE timecode and external device control, refer to the following documentation.

  1. Proposed revision to ANSI/SMPTE 12M-1986, SMPTE Standard for Television, Audio and Film Time and Control Code, SMPTE Journal, February 1995.
  2. SMPTE RP 135-1990 "Use of Binary User Groups in Motion-Picture Time and Control Codes"
  3. SMPTE RP 169 "Television, Audio and Film Time and Control Code - Auxiliary Time Address Data in Binary Groups - Dialect Specification of Directory Index Locations"
  4. SMPTE RP 179-1994 "Dialect Specification of Page-Line Directory Index for Television, Audio and Film Time and Control Code for Video-Assisted Film Editing"
  5. "Touring the Vertical Interval", Warner Johnston, TV Technology, August 1991
  6. "Closed Captioning in Real Time", Marc Oakrand, SMPTE Journal, June 1991
  7. Timecode Handbook, 3rd. Edition, Cipher Digital, Inc. (available from Mix Bookshelf)
  8. Timecode: A Users Guide, John Ratcliffe (available from Mix Bookshelf)
  9. SMPTE RP 138 - Control Message Architecture
  10. SMPTE RP 139 - Tributary Interconnection
  11. SMPTE RP 163 - System Service Messages
  12. SMPTE RP 170 - Video Tape Recorder Type Specific Messages for Digital Control Interface
  13. SMPTE RP 171 - Type-Specific Messages for Digital Control Interface of Analog Audio Tape Recorders
  14. SMPTE RP 172 - Common Messages for Digital Control Interface
  15. SMPTE 275M - ESlan-1 Remote Control System

Note SMPTE standards and reprints available from SMPTE at (914)761-1100


Build a Filter or Application with Visual C++ 5.x

This article describes step-by-step procedures for building your Microsoft® DirectShow™ projects. You can either build your filter or application from the command line, or build it from within the Visual Studio environment that comes with Microsoft Visual C++®. If you choose to build a filter from within Microsoft Visual Studio™, you can use the VC5Kit set of files shipped with the DirectShow SDK, by default, in the dxmedia\tools\VC5Kit directory. This provides an easy way to configure Visual Studio project settings. You can also set the project settings within Visual Studio yourself.

The main difference between building a filter and building an application from within Visual Studio is that for a filter you select Win32 Dynamic-Link Library as the project type, while for an application you select Win32 Application or Win32 Console Application as the project type. (You choose the project type in the New Projects dialog box opened by choosing the New command from the File menu.)

This article includes the following topics.

  • Building a Filter or Application from the Command Line
  • Using VC5Kit to Build a Filter in Visual Studio
  • Setting DirectShow Project Settings in Visual Studio

Building a Filter or Application from the Command Line

Perform the following steps to build a DirectShow project from the command line.

  1. Go to the Visual C++ Bin directory.
  2. Type VCVARS32.
  3. Go to the directory containing the filter you want to build.
  4. If you are building a sample filter and the sample filter isn't in the default directory (the default is \dxmedia\Samples\ds\Samplename; for example, \dxmedia\Samples\ds\Gargle), set the AXSDK MAKEFILE variable to the top-level DirectShow directory. For example, at the command prompt, type:

set axsdk=c:\dxmedia
  5. At the command prompt, type:
    NMAKE

    For nondebug versions, type:

    NMAKE NODEBUG=1

Using VC5Kit to Build a Filter in Visual Studio

This section discusses building filters with Microsoft® Visual C++® version 5.x. The 5.x VC5Kit is installed by default in the dxmedia\tools\VC5Kit directory.

  • Setting the Visual Studio Include and Lib Directories
  • Creating a Project Directory and Adding Source Files
  • Building the Project in Visual Studio
  • Creating a GUID
  • Creating a Definition File

Setting the Visual Studio Include and Lib Directories

This topic describes how to set your Visual Studio Include and Lib directories. If you are building a DirectShow sample application, such as PlayFile, that comes with a makefile or .mak file, the steps in this topic are the only ones you must perform to build the sample. Once you set your directories, you can choose Open Workspace from the File menu and select the existing makefile or .mak file. Visual Studio will wrap the makefile. If you are building a filter, other steps will probably be necessary.

  1. Open Visual Studio.
  2. From the Tools menu, choose Options.
  3. Choose the Directories tab.
  4. In the Show directories for drop-down list, select Include files.
  5. Add the DirectShow include directories (by default: dxmedia\Include and dxmedia\Classes\Base) to the list.
  6. In the Show directories for drop-down list, select Library files.
  7. Add the DirectShow library directory (by default C:\dxmedia\Lib).

Creating a Project Directory and Adding Source Files

Follow these steps to create your project directory and add your source files to it:

  1. Create an empty directory for your project; for example, C:\Filter.
  2. Copy the VC5Kit Filter.def, Filter.dsp, Filter.dsw, and Filter.mak files into the directory.
  3. Copy your source files into the directory. This includes .h, .cpp and any other miscellaneous source files your project requires. If your project has its own .def and .rc files, you can use these rather than the .def and .rc files provided with VC5Kit.

Building the Project in Visual Studio

Follow these steps to build your project in Visual Studio:

  1. From the File menu in Visual Studio, choose Open Workspace.
  2. In the Open Workspace dialog box that appears, browse to the directory you created and select Filter.dsw.

    The project opens.

  3. To add your source files to the project, choose Add to Project from the Project menu, and then choose Files from the submenu that appears. Browse to the directory containing your source files, select the ones you want to add, and click the OK button.
  4. From the Project menu, choose Settings.
  5. Choose the Link tab and select General from the Category drop-down list.
  6. In the Output file name box, type the name of your filter; for example, Filter.ax.
  7. Choose OK to confirm the project settings you've selected.
  8. Choose Build Filter.ax from the Build menu. The name Filter.ax is the name you gave the output file in the Link tab.

Creating a GUID

If you are building your filter using source files from an existing filter, including any samples filter that ships with DirectShow, you must create a GUID for the new filter.

To create a GUID in Visual Studio:

  1. From the Tools menu, choose Create GUID. By default, the GUID is in DEFINE_GUID format, which is the format you want.
  2. Click the Copy button.
  3. Delete the old GUID from your source file.
  4. Put the cursor in your source file where the old GUID used to be, and choose Paste from the Edit menu.

Creating a Definition File

If your filter implements the DllGetClassObject, DllCanUnloadNow, DllRegisterServer, or DllUnregisterServer functions, you must include a definition file (.def file) that exports them. For example (where Filter.ax is the name you gave the output file):

LIBRARY FILTER.AX
DESCRIPTION 'Description of my filter'
PROTMODE
EXPORTS
    DllGetClassObject
    DllCanUnloadNow
    DllRegisterServer
    DllUnregisterServer

Setting DirectShow Project Settings in Visual Studio

This section describes how to set project settings in Visual Studio to build your own DirectShow applications and filters. If you are building samples supplied by DirectShow, you need only set your Include and Lib directories.

In some cases, you might need to add to these project settings for your particular application. For example, if you use DirectDraw functions, you must add Ddraw.lib to the list of Link libraries.

In all cases, you must set the Visual Studio Include and Lib directories as described in Setting the Visual Studio Include and Lib Directories.

This section contains the following topics.

  • Creating a Project
  • Adding Files to the Project
  • Setting Project Settings For Both Release and Debug Builds
  • Setting Project Settings for Debug Builds
  • Building a Release or Debug Version of Your Project

Creating a Project

To create a project, perform the following steps.

  1. From the File menu, choose New.
  2. Choose the Projects tab.
  3. If you are building an application, select Win32 Application as the type of project. If you are building a filter, select Win32 Dynamic-Link Library.
  4. Type a name for the project and a location for the project files.

Adding Files to the Project

To add files to the project, perform the following steps.

  1. From the Project menu, choose Add to Project. From the submenu that appears, choose Files.
  2. In the Insert Files into Project dialog box that appears, browse for the filter files you want to add to the project, such as the .cpp, .h, .rc, and .def files.
  3. Select the file or files you want to add and choose OK.

Setting Project Settings For Both Release and Debug Builds

To set project settings for both release and debug builds, perform the following steps.

  1. From the Project menu, choose Settings.
  2. In the dialog box that appears, select All Configurations in the Settings For drop-down list.

Follow these steps to set your project general settings:

  1. From the Project menu, choose Settings.
  2. Choose the General tab.
  3. From the Microsoft Foundation Classes drop-down list, select Not Using MFC.

Follow these steps to set your project compiler settings:

  1. From the Project menu, choose Settings.
  2. Choose the C/C++ tab.
  3. In the Category drop-down list, select General.
  4. In the Preprocessor definitions text box, insert the following:
    INC_OLE2,STRICT,WIN32,_MT,_DLL,_X86_=1,WINVER=0x0400
  5. Select the C++ Language category.
  6. Select the Enable exception handling check box.
  7. Choose the Code Generation category.
  8. In the Processor drop-down list, select Blend*.
  9. In the Calling convention drop-down list, select _stdcall.
  10. In the Use Run-time library drop-down list, select Multithreaded DLL.
  11. Select the Precompiled Headers category.
  12. Select the Not using precompiled headers option button.

Follow these steps to set your project link settings:

  1. From the Project menu, choose Settings.
  2. Choose the Link tab.
  3. In the Category drop-down list, select General.
  4. In the Output file name text box, type the filter's output file name; for example, Debug/Filter.ax.
  5. Add the following libraries to the beginning of the Object/Library modules text box.
    quartz.lib strmbase.lib msvcrt.lib

    These libraries must be the first libraries in the link list. Depending on the functions your application accesses, you might need to add other libraries to this list.

  6. Select the Ignore all default libraries check box.
  7. Select the Customize category.
  8. Clear the Use program database check box.
  9. Select the Output category.
  10. In the Base address text box, type:
    0x1c400000
  11. In the Entry-point symbol text box, type:
    DllEntryPoint@12

Setting Project Settings for Debug Builds

To set project settings for debug builds, perform the following steps.

  1. From the Project menu, choose Settings.
  2. Select Win32 Debug in the Settings For drop-down list in the Project Settings dialog box that appears.
  3. Choose the C/C++ tab.
  4. In the Category drop-down list, select General.
  5. Select the Generate browse info check box.
  6. In the Debug info drop-down list, select C7 Compatible.
  7. Select the Code Generation category.
  8. In the Use Run-time library drop-down list, select Debug Multithreaded DLL.
  9. Choose the Link tab.
  10. Select the Debug category.
  11. Select the Debug info check box.

Building a Release or Debug Version of Your Project

To build a release or debug version of your project:

  1. Choose Set Active Configuration from the Build menu, and select Win32 Release or Win32 Debug from the list that appears.
  2. Choose Build Filter.ax from the Build menu. The name Filter.ax is the name you gave the output file in the Link tab.


Recompress an AVI File

The following sample code shows how to recompress the file c:\Foo.avi to c:\Bar.avi, where the output file will use Cinepak compression and will include CD-quality audio. Recompression is useful to change the format of a file from one compression scheme to another. The exact benefits of recompression depend on the different compressors used to compress the source and output files and often include producing a smaller output file. In this example the source file, Foo.avi, might be in a format such as uncompressed RGB with 22 kilohertz (kHz) sound.

The AMCap Sample (DirectShow Capture Application) sample demonstrates a capture application and uses many of the same concepts as the following code.

Note This sample code fragment introduces concepts only and is not designed to compile. See the AMCap Sample (DirectShow Capture Application) sample for actual code. The code fragment does not perform error checking for the sake of brevity.

    // Create a graph builder object.
    hr = CoCreateInstance((REFCLSID)CLSID_CaptureGraphBuilder,
                  NULL, CLSCTX_INPROC, (REFIID)IID_ICaptureGraphBuilder,
                  (void **)&pBuild);

    // Create a filter graph, and tell the builder what it is.
    hr = CoCreateInstance((REFCLSID)CLSID_FilterGraph,
                  NULL, CLSCTX_INPROC, (REFIID)IID_IGraphBuilder,
                  (void **)&pFg);
    hr = pBuild->SetFiltergraph(pFg);

    // Obtain a source for c:\foo.avi.
    hr = CoCreateInstance((REFCLSID)CLSID_AsyncReader,
                  NULL, CLSCTX_INPROC, (REFIID)IID_IBaseFilter,
                  (void **)&pSrc);
    hr = pSrc->QueryInterface(IID_IFileSourceFilter, (void **)&pI);
    hr = pI->Load(L"c:\\foo.avi", NULL);
    pI->Release();
    hr = pFg->AddFilter(pSrc, NULL);

    // Create a rendering section to create the c:\bar.avi output file.
    hr = pBuild->SetOutputFileName(&MEDIASUBTYPE_Avi, L"c:\\bar.avi", &pRender,
                                   NULL);

// [...Enumerate the audio compressors with the category CLSID_AudioCompressorCategory
// and pick one. See the Amcap.cpp file in the capture sample directory for an example of
// how to enumerate a category...]

    // Render the recompressed audio stream
    hr = pBuild->RenderStream(NULL, pSrc, pCAud, pRender);

// [...Enumerate a video compressor using the CLSID_VideoCompressorCategory enum,
// as seen in Amcap.cpp...]

    pCVid = [...IBaseFilter pointer of the chosen Cinepak compressor...]
    hr = pFg->AddFilter(pCVid, NULL);

    // Tell it to compress at 100k/second data rate.
    // Use the current format to set the data rate, but change the data
    // rate item in the media type.
    hr = pBuild->FindInterface(NULL, pCVid, IID_IAMStreamConfig,
                               (void **)&pVSC);
    hr = pVSC->GetFormat(&cmt);
    ((VIDEOINFOHEADER)(cmt.Format()))->dwBitRate = 100000;
    hr = pVSC->SetFormat(&cmt);
    pVSC->Release();

    // Request key frames every 4 frames.
    hr = pBuild->FindInterface(NULL, pCVid, IID_IAMVideoCompression,
                               (void **)&pVC);
    hr = pVC->put_KeyFrameRate(4);
    pVC->Release();

    // Render the recompressed video stream.
    hr = pBuild->RenderStream(NULL, pSrc, pCVid, pRender);

    // All done with these objects now.
    pSrc->Release();
    pRender->Release();
    pCAud->Release();
    pCVid->Release();

    // Run the graph.
    hr = FG->QueryInterface(IID_IMediaControl, &MC);
    MC->Run();

    // Wait for EC_COMPLETE, and it's all done!
    // [...wait for EC_COMPLETE event... see AMCap sample...]

 pGraphBuilder->FindInterface(pRender, IID_IMediaSeeking, pMS);
// [...While waiting for complete, use IMediaSeeking methods to get
// the percentage complete... IMediaSeeking->GetCurrentPosition divided by
// GetDuration * 100 will tell you the percent complete at any time...]

    pFg->Release();
    pBuild->Release();


Register DirectShow Objects

This section describes the steps you must take to make your Microsoft® DirectShow™ objects self-registering. It describes the relationships between the registry entry points called by COM, the globally-defined CFactoryTemplate array elements, and the AMOVIESETUP_MEDIATYPE, AMOVIESETUP_PIN, and AMOVIESETUP_FILTER structures.

To enable objects in a dynamic-link library (DLL) to register themselves, two COM-defined entry points must be provided in the DLL and exported:

  • DllRegisterServer
  • DllUnregisterServer

With these entry points in your DLL, you can use the Regsvr32.exe tool to register and unregister your DLL or setup tools, or applications can register the filter programmatically.

Implementing Self-Registration

To implement a self-registering filter, carry out the following steps.

  1. Add DllRegisterServer and DllUnregisterServer to the export list in your filter's DEF file.
  2. Provide implementations for these functions, which call the DirectShow AMovieDllRegisterServer2 function with parameters of TRUE and FALSE, respectively. For example:

  STDAPI DllRegisterServer()
  {
    return AMovieDllRegisterServer2(TRUE);
  }

  HRESULT DllUnregisterServer()
  {
    return AMovieDllRegisterServer2(FALSE);
  }

    You can add code to these functions to set up custom registry entries.

  3. Define the setup data structures for each filter based on the AMOVIESETUP_MEDIATYPE, AMOVIESETUP_PIN, and AMOVIESETUP_FILTER structures.

    For example, here are the structures for the Ball.ax sample filter:

   // Setup data

  const AMOVIESETUP_MEDIATYPE sudOpPinTypes =
  { &MEDIATYPE_Video
  , &MEDIASUBTYPE_NULL };

  const AMOVIESETUP_PIN sudOpPin =
  { L"Output"
  , FALSE
  , TRUE
  , FALSE
  , FALSE
  , &CLSID_NULL
  , NULL
  , 1
  , &sudOpPinTypes };

  const AMOVIESETUP_FILTER sudBallax =
  { &CLSID_BouncingBall
  , L"Bouncing Ball"
  , MERIT_UNLIKELY
  , 1
  , &sudOpPin };
  4. In the CFactoryTemplate g_Templates array that instantiates your class, ensure that the first parameter has the name of the filter, (for example, "Bouncing Ball") and that the last parameter has the address of the AMOVIESETUP_FILTER structure you defined.

  CFactoryTemplate gTemplates[]={
   L"Bouncing Ball",                // Name of the filter
   &CLSID_BouncingBall,             // CLSID of the filter
   CBouncingBall::CreateInstance,   // Static function to be called by class factory
   NULL,                            //
   &sudBallax}                      // Address of the AMOVIESETUP_FILTER structure
  };
  5. Tag the DLL file as self-registering by adding the string "OLESelfRegistering" to its resource (defining AMOVIE_SELF_REGISTER in your resource file does this automatically if you are using Activex.rcv and Activex.ver). This string enables applications to determine whether the object is self-registering without loading the DLL.


DirectShow Animated Header -- Enumerate and Access Hardware Devices in DirectShow Applications DirectShow Animated Header -- Enumerate and Access Hardware Devices in DirectShow Applications * Microsoft DirectShow SDK
  * Previous Topic: Register DirectShow Objects
  * Next Topic: Clocks

Enumerate and Access Hardware Devices in DirectShow Applications

This article explains and demonstrates how to initialize and access system hardware devices by using interfaces and classes provided by Microsoft® DirectShow. Developers need this functionality to support many types of hardware in their applications. Typically, DirectShow applications use the following types of hardware.

  • Audio and video capture cards
  • Audio or video playback cards
  • Audio or video compressors or decompressors (such as an MPEG decoder)

Because developers support these devices in a similar manner (and for the sake of brevity), they will be referred to as AV devices for the remainder of this article; they will be distinguished only if a topic applies to a specific type of device.

Three interfaces apply to hardware device support: ICreateDevEnum (documented in the DirectShow SDK), and IPropertyBag and IPersistPropertyBag (both Microsoft Win32® interfaces). These interfaces handle hardware device enumeration and the loading and storage of AV device properties.

Contents of this article:

  • How to Enumerate Hardware Devices
  • Device Enumeration in the AMCap Sample
  • How to Store DirectShow Filter Properties Persistently

Application developers who want to control hardware devices should be familiar with the COM-based concepts of monikers, enumerators, and the initialization and creation of DirectShow objects.

How to Enumerate Hardware Devices

Microsoft provides audio and video capture and playback functionality through interfaces, classes, and samples included in the DirectShow SDK. Because the File Source filters and the filter graph manager handle the internal work of passing information from component to component, adding capture capabilities to an application requires a relatively small amount of additional code. The required additional code enumerates the system's hardware devices and compiles a list of the devices that can perform a specific task (a list of all video capture cards, for example). You can use the same enumeration process for any hardware device, past or present; DirectShow automatically instantiates filters for both Win32 and Video for Windows devices.

To work with AV devices, you must first detect what devices exist on the current system. The ICreateDevEnum interface, which creates enumerators for any specified type of object, provides the functionality you need to detect and set up the hardware. Accessing a specific device is a three-step process, detailed by the following instructions and code fragments.

  1. Create a system hardware device enumerator.

    First, set aside a pointer for the enumerator, and then create it by using the CoCreateInstance function; CLSID_SystemDeviceEnum is the type of object you want to create (a system hardware device enumerator, in this case) and IID_ICreateDevEnum is its interface GUID.

    ICreateDevEnum  *pCreateDevEnum ;
    CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
              IID_ICreateDevEnum, (void**)&pCreateDevEnum) ;
  2. Create an enumerator for a specific type of hardware device (such as a video capture card).

    Declare an IEnumMoniker interface pointer and pass it to the ICreateDevEnum::CreateClassEnumerator method, called on the system device enumerator. You can then use the IEnumMoniker interface pointer to access the newly created enumerator.

    IEnumMoniker *pEnumMon ;
    pCreateDevEnum->CreateClassEnumerator(
                [specify device GUID here]
                &pEnumMon, 0);
  3. Enumerate the list itself until you locate the desired device.

    If the previous call to CreateClassEnumerator succeeded, you can call the IEnumMoniker::Next method to step through the list of devices. To retrieve the device itself, call the IMoniker::BindToObject method on an enumerated device. BindToObject creates the filter associated with the selected device and loads the filter's properties (CLSID, FriendlyName, and DevicePath) from the registry. Don't be confused by the (1 == cFetched) portion of the if condition; the Next method will set it to the number of returned objects (1, if successful) before testing the statement's validity.

    ULONG cFetched = 0;
    IMoniker *pMon ;

    if (S_OK == (pEnumMon->Next(1, &pMon, &cFetched))  &&  (1 == cFetched))
    {
        pMon->BindToObject(0, 0, IID_IBaseFilter, (void **)&[desired interface here]) ;

    Now that you have the IMoniker pointer, you can add the device's filter to the filter graph. Once you've added the filter, you don't need the IMoniker pointer, device enumerator, or system device enumerator.

        pGraph->AddFilter([desired interface here], L"[filter name here]") ;
        pMon->Release() ;  // Release moniker
    }
    pEnumMon->Release() ;	// Release the class enumerator
    }
    pCreateDevEnum->Release();

Device Enumeration in the AMCap Sample

The DirectShow SDK includes an audio and video capture sample application called AMCap, as well as the sample's source code. Internally, AMCap uses the ICreateDevEnum interface to construct a list of a system's capture devices. In the application itself, you can access the list of devices from the Devices menu.

The code that builds AMCap's enumerated list of devices is its InitCapFilters function. This function demonstrates a typical way to enumerate filters, for both former and current hardware devices. For the sake of brevity, the following code walk-through contains no error-checking code; for the complete version, see the Amcap.cpp file in the \Samples\DS\Capture directory of the SDK. The AMCap sample uses a global variable, gcap, which is a structure from the Amcap.cpp file that stores a variety of information used by the filter graph. While you generally want to avoid using global variables, this structure does show the amount of information that the filter graph manager handles.

struct _capstuff {
    char szCaptureFile[_MAX_PATH];
    WORD wCapFileSize;
    ICaptureGraphBuilder *pBuilder;
    IVideoWindow *pVW;
    IMediaEventEx *pME;
    IAMDroppedFrames *pDF;
    IAMVideoCompression *pVC;
    IAMVfwCaptureDialogs *pDlg;
    IAMAudioStreamConfig *pASC;
    IAMVideoStreamConfig *pVSC;
    IBaseFilter *pRender;
    IBaseFilter *pVCap, *pACap;
    IGraphBuilder *pFg;
    IFileSinkFilter *pSink;
    BOOL fCaptureGraphBuilt;
    BOOL fPreviewGraphBuilt;
    BOOL fCaptureGraphRunning;
    BOOL fPreviewGraphRunning;
    BOOL fCapAudio;
    int  iVideoDevice;
    int  iAudioDevice;
    double FrameRate;
    BOOL fWantPreview;
    long lCapStartTime;
    long lCapStopTime;
} gcap;

InitCapFilters starts by defining some basic return and error-checking variables. AMCap uses the uIndex value to loop through the system's hardware devices later.

BOOL InitCapFilters()
{
    HRESULT hr;
    BOOL f;
    UINT uIndex = 0;

The MakeBuilder function call creates a filter graph builder. You can find the MakeBuilder function in Amcap.cpp.

    f = MakeBuilder();

The next section handles the video capture device enumeration; this code is very similar to the code description from the How to Enumerate Hardware Devices section. It first declares an ICreateDevEnum pointer, then uses CoCreateInstance to create an enumerator for system hardware devices.

    ICreateDevEnum *pCreateDevEnum;
    hr = CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
                          IID_ICreateDevEnum, (void**)&pCreateDevEnum);

After it has a device enumerator, AMCap creates an enumerator specifically for video capture devices by passing the CLSID_VideoInputDeviceCategory class identifier to ICreateDevEnum::CreateClassEnumerator. It can now use the IEnumMoniker pointer to access the enumerated list of capture devices.

    IEnumMoniker *pEm;
    hr = pCreateDevEnum->CreateClassEnumerator(CLSID_VideoInputDeviceCategory, &pEm, 0);
    pCreateDevEnum->Release();			// We don't need the device enumerator anymore
    pEm->Reset();						// Go to the start of the enumerated list

Now AMCap needs the actual device; it calls IEnumMoniker::Next to move through the device list, and then points pM to each device by calling IMoniker::BindToObject, which also loads the device's properties (CLSID, FriendlyName, and DevicePath) from the registry. If you do not want to automatically create the filter associated with the device, use IMoniker::BindToStorage instead of BindToObject.

    ULONG cFetched;
    IMoniker *pM;					// This will access the actual devices
    gcap.pVCap = NULL;
    while(hr = pEm->Next(1, &pM, &cFetched), hr==S_OK)
    {
if ((int)uIndex == gcap.iVideoDevice) {	// This is the one we want.  Instantiate it.
        hr = pM->BindToObject(0, 0, IID_IBaseFilter, (void**)&gcap.pVCap);
                    pM->Release();			// We don't need the moniker pointer anymore
        break;
    }
                pM->Release();
    uIndex++;
    }
    pEm->Release();				// We've got the device; don't need the enumerator anymore

After AMCap has a device, it retrieves the interface pointers to measure frames, get the driver name, and get the capture size. AMCap stores each pointer in the gcap global structure.

    // We use this interface to get the number of captured and dropped frames
    gcap.pBuilder->FindCaptureInterface(gcap.pVCap,
                IID_IAMDroppedFrames, (void **)&gcap.pDF);

    // We use this interface to get the name of the driver
    gcap.pBuilder->FindCaptureInterface(gcap.pVCap,
                IID_IAMVideoCompression, (void **)&gcap.pVC);

    // We use this interface to set the frame rate and get the capture size
    gcap.pBuilder->FindCaptureInterface(gcap.pVCap,
                IID_IAMVideoStreamConfig, (void **)&gcap.pVSC);

AMCap then gets the media type and sizes the display window to match the size of the video format.

  AM_MEDIA_TYPE *pmt;
    gcap.pVSC->GetFormat(&pmt);			// Current capture format

    ResizeWindow(HEADER(pmt->pbFormat)->biWidth,
                HEADER(pmt->pbFormat)->biHeight);
    DeleteMediaType(pmt);

This section applies only to earlier Video for Windows devices. Video for Windows devices support a specific set of dialog boxes, which set the video source, format, and display type. For additional information on these dialog boxes, see the IAMVfwCaptureDialogs interface documentation.

    hr = gcap.pBuilder->FindCaptureInterface(gcap.pVCap,
                IID_IAMVfwCaptureDialogs, (void **)&gcap.pDlg);
    if (hr != NOERROR) {
    ErrMsg("Error %x: Cannot find VCapture:IAMVfwCaptureDialogs", hr);
    }

Now that AMCap has the video capture device and its relevant information, it repeats the process with the audio devices and stores the information in the global structure. Note that it calls ICreateDevEnum::CreateClassEnumerator with the CLSID_AudioInputDeviceCategory CLSID to enumerate audio hardware devices.

    hr = CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
                          IID_ICreateDevEnum, (void**)&pCreateDevEnum);
    uIndex = 0;
    hr = pCreateDevEnum->CreateClassEnumerator(CLSID_AudioInputDeviceCategory,
                                &pEm, 0);
    pCreateDevEnum->Release();

    pEm->Reset();
    gcap.pACap = NULL;
    while(hr = pEm->Next(1, &pM, &cFetched), hr==S_OK)
    {
    if ((int)uIndex == gcap.iAudioDevice) {		        // this is the one we want
        hr = pM->BindToObject(0, 0, IID_IBaseFilter, (void**)&gcap.pACap);
                    pM->Release();
        break;
    }
                pM->Release();
    uIndex++;
    }
    pEm->Release();

AMCap also repeats the process of retrieving the format interface, this time for the audio device.

    hr = gcap.pBuilder->FindCaptureInterface(gcap.pACap,
                IID_IAMAudioStreamConfig, (void **)&gcap.pASC);
}

How to Store DirectShow Filter Properties Persistently

The Win32 IPropertyBag and IPersistPropertyBag interfaces store and retrieve groups ("bags") of properties for developer-specified objects. Properties stored by these interfaces are persistent; that is, they remain consistent between different instantiations of the same object. Filters can store their properties (CLSID, FriendlyName, and DevicePath) persistently. After a filter stores its properties, DirectShow automatically retrieves them whenever it instantiates the filter. To add this functionality to your filter, implement the IPersistPropertyBag interface and its Load method. Your implementation of the Load method should call the IPropertyBag::Read method to load the filter's properties into a Win32 VARIANT variable, and then initialize its input and output pins.

The following code sample demonstrates how the DirectShow VfWCapture filter implements the IPersistPropertyBag::Load method. Remember that your filter must supply a valid IPropertyBag pointer to hold the filter's properties during execution. You can specify an error log to trap errors generated by the filter's properties, although you can pass in a null value to ignore error reporting.

STDMETHODIMP CVfwCapture::Load(LPPROPERTYBAG pPropBag, LPERRORLOG pErrorLog)
{
    HRESULT hr;
    CAutoLock cObjectLock(m_pLock);		// Locks the object; automatically unlocks it in the destructor.

    if (m_pStream)				// If the filter already exists for this stream
    return E_UNEXPECTED;

    VARIANT var;				// VARIANT from Platform SDK
    var.vt = VT_I4;				// four-byte integer (long)
    hr = pPropBag->Read(L"VFWIndex", &var, 0);	// VFWIndex is the private name used by the Vidcap Class Manager to refer to the VFW Capture filter
    if(SUCCEEDED(hr))				// If it read the properties successfully
    {
        hr = S_OK;				// Defaults return value to S_OK
        m_iVideoId = var.lVal;			// Stores the specified hardware device number
        CreatePins(&hr);				// Inits the pins, replacing the return value if necessary
    }
    return hr;					// Returns S_OK or an error value, if CreatePins failed
}


Clocks

This section describes time and synchronization in DirectShow, how to implement a reference clock in a filter or application, and how to make a reference clock the master clock if a filter graph has more than one clock.

Synchronization

Understanding Time and Clocks in DirectShow


Synchronization

DirectShow accomplishes synchronization by using a reference clock. A reference clock is an object that implements the IReferenceClock interface. For example, because sound cards are often used for reference clocks, the audio renderer filter implements this interface, which essentially allows any caller to register for the receipt of time notifications.


Understanding Time and Clocks in DirectShow

This article describes the basic concepts of time used in the filter graph and then goes on to describe what a reference clock is, how it is implemented by a filter or as a stand-alone clock, how the filter graph manager decides which clock to use as the master reference clock, and how to ensure that a reference clock implemented by a filter is used as the master reference clock.

Contents of this article:

  • About Time
  • About Reference Clocks
    • Characteristics of a Reference Clock
    • Using a Reference Clock
    • DirectShow Clock Classes
    • Multiple Clocks in a Filter Graph

About Time

A few concepts of time come up often in discussions about DirectShow streams, synchronization to a common clock, and seeking to different places in the stream. Four terms are defined here:

  • Media time
  • Reference time
  • Stream time
  • Presentation time

In DirectShow, the term media time is used to refer to positions within a seekable medium such as a file on disk. Media time can be expressed in a variety of units, such as frames, seconds, bytes, or 100-nanosecond intervals, and indicates a position within the data in the file.

Reference time is an absolute time (sometimes called wall-clock time) that is established by a reference clock in the filter graph. It is a reference to some time value outside the filter graph (for example, perhaps the number of milliseconds since Windows was started).

Stream time is relevant only within a running filter graph, and represents the time since the graph was last started. When a filter graph is run, each filter is passed a notional start time (tStart) according to the reference clock, and the packets of data that a filter receives will normally be time-stamped with the stream time at which they should be presented. This is known as the presentation time. Stream time is often called "relative reference time" since, by definition, stream time is equivalent to reference time minus start time when the graph is running.

Since a filter graph can start playing a file at an arbitrary position and rate, file source filters and/or parsers must take these two factors into account when time-stamping the samples that they pass downstream to renderers. Such filters will calculate the presentation time and will place that value in the sample. The presentation time is calculated by subtracting the starting media time (the last time that was seeked to) from the media time of the sample, and dividing this by the playback rate. Expressed as a formula, this would be:

Presentation Time = (Media Time - Starting Media Time)  / playback rate.

For example, consider a media stream with a duration of six seconds that is set to be played at double speed. What happens when the filter graph is seeked to a sample with a media time of two seconds and then run? Each media sample read from the disk gets stamped with a presentation time equivalent to half of the difference of its media time and the start time (two seconds). Here is how the time stamps would appear at one-second media sample intervals:
Media time (sec) | Presentation time stamp (sec)
3 | 0.5
4 | 1.0
5 | 1.5
6 | 2.0

When finally presented in the renderer, the difference between the actual time the sample is rendered and the stamped presentation time that was expected can be calculated. In a perfect graph, this would always be zero. In reality, there is a margin of acceptable tolerance. If this difference is out of tolerance, then quality-control management will be initiated by the renderer.

About Reference Clocks

A reference clock is an object that implements the IReferenceClock interface. This interface supports querying for the current time and scheduling events according to time as counted by that clock. Event scheduling is achieved by submitting advise requests to the clock. These requests can be for single-shot or periodic events.

Many pieces of hardware can provide time signals. These time signals can be of particularly high accuracy, or might represent some clock signal significant only to the resolution of a particular application, such as sound playback.

Filters can expose a hardware time signal to other filters by implementing a reference clock in the filter graph. A filter graph manager will choose (or be assigned) one of these reference clocks to be the filter graph reference clock. (By definition, there is only one reference clock allowed in a filter graph.) If no such reference clocks exist, the filter graph manager can create a suitable reference clock and use that one instead. A reference clock can be appointed by calling the filter graph manager's IMediaFilter::SetSyncSource method. The reference clock is also called the sync source. A filter graph manager propagates this selection to the filters in its graph by calling their individual IMediaFilter::SetSyncSource methods.

Developers can provide a reference clock on a filter for purely altruistic reasons; the filter might simply be in a position to provide a high-accuracy clock. Alternatively, the overall performance of a filter graph might be determined by which reference clock, of all the possible reference clocks in the graph, is selected to provide its services to the filter graph. Because audio hardware cannot easily adjust the rate at which it delivers data, it is often the most appropriate source of time signals. Therefore, the reference clock of the audio renderer is often selected to be the filter graph's reference clock.

All clocks in DirectShow report a reference time; that is, a time which would be suitable to use for the filter graph reference time. The filter graph reference time for the filter graph is the time of the clock that has been selected as the current sync source.

Characteristics of a Reference Clock

Any reference clock must support the IReferenceClock interface. The time of the clock can be obtained by calling the IReferenceClock::GetTime method. The time returned by GetTime is defined as a REFERENCE_TIME type (LONGLONG) and loosely represents the number of 100-nanosecond units that have elapsed since some fixed start time. This is just a guideline. Specifically, IReferenceClock::GetTime must adhere to some conditions as follows.

A reference clock must return values that are monotonically increasing. That is, successive calls to GetTime must result in values that are greater than or equal to the previous value.

Also, the return value should generally increase at a rate of approximately one per 100 nanoseconds.

In exceptional circumstances, it is allowable for the clock to stop for a time. (This will effectively suspend any filter that was using the clock as a sync source.) Furthermore, it is allowable for the clock to jump forward in exceptional circumstances.

Finally, the reference clock must continue to count time even if its containing filter graph is stopped, and should normally continue to count time if it is paused. (A filter's reference clock implementation can optionally use a system-supplied clock to fill in during such times, but that is an implementation decision.)

The reference clock does not have to bear any permanent relationship to any real time. It is allowed to drift, it can drift at a changing rate, and it need not correct for such drift. In particular, it does not have to represent a count of the number of 100 nanoseconds that have passed since some arbitrary time in the past. It is important to remember that this loose description of a reference clock, though it can be helpful, is just a guideline. In some cases, a strict adherence to the guideline might actually result in a poorer overall look and feel when the filter graph is running. If you want your clock to adhere strictly to the guideline, you need to set the clock yourself.

Using a Reference Clock

A filter will always be told to use a specific clock (or, possibly, to use none) by a call to its IMediaFilter::SetSyncSource method. Filters that require timing information should use the clock that they are told to use. All filters in a particular filter graph should use the same reference clock. An application can use a reference clock by calling IMediaFilter::GetSyncSource on the filter graph manager to obtain a pointer to an IReferenceClock, and then invoke methods on that interface. If a null pointer is passed to SetSyncSource, it implies that the filter should not use any clock and should just run as quickly as possible without discarding any data. If no clock has been set as the reference clock for the filter graph, then when the filter graph manager's GetSyncSource is called, the filter graph manager chooses a clock in the filter graph or creates and appoints a clock of its own. This is the same logic that applies when the filter graph is first run.

If a new reference clock is appointed, the time as tracked by the old reference clock and the time as tracked by the new reference clock need bear no relation to each other. As a consequence, functions that call IReferenceClock::GetTime on the current sync source should not be surprised to see the reported time jump forward or backward. Reference clocks can be switched only if the filter graph is paused or stopped. When the filter graph next starts to run, the filters in the filter graph will be given their start times in terms of the new clock. (See IMediaFilter::Run for details.) Typically, only filters that use advise requests from the reference clock (that is, use its scheduling facilities) must specifically handle clock differences when then the filter graph is switched to an alternative sync source.

If a filter (or application) uses a reference clock's scheduling facilities, it is important to recognize that the advise requests are scheduled against that specific clock in the absolute time used by that clock. If a filter has set up advise requests against its sync source, and is then notified of a new sync source, then the filter is normally expected to cancel the advise requests on the first clock and set them up again on the new one. Applications that use advise requests should monitor for EC_CLOCK_CHANGED events. If an EC_CLOCK_CHANGED event notification is received, then the application should cancel any outstanding advise requests, call GetSyncSource on the filter graph manager to obtain an interface pointer to the new clock, and reschedule the advise requests on the new clock (also taking into account that the time on the old and new clock might be different).

Similarly, when a filter sets up advise requests in stream time (for example, 135 milliseconds into the media stream), then it is expected that the filter will set up an advise when it is told to run, cancel the advise if it is told to pause or stop, and recalculate and resubmit the advise request when it is told to run again.

DirectShow Clock Classes

DirectShow provides three class that are used to implement clocks:

  • CBaseReferenceClock, the main clock class that implements IReferenceClock.
  • CAMSchedule, which handles the mechanics of advise list processing and is inherited by CBaseReferenceClock.
  • CSystemClock, a stand-alone minimal clock class derived from CBaseReferenceClock.

CBaseReferenceClock provides the event notification functionality (mainly via CAMSchedule) and a rudimentary clock based on the Win32 timeGetTime function.

The most important aspect of CBaseReferenceClock is a virtual GetPrivateTime method. This method can be overridden in derived classes to return a time. The CBaseReferenceClock::GetTime method calls GetPrivateTime, caches the result, and ensures that the time it returns to its caller does not go backward. Thus, implementers of GetPrivateTime can code that method so that it returns a best estimate, and not worry about time going backward. CBaseReferenceClock::GetTime locks the clock before calling GetPrivateTime; therefore, implementations of GetPrivateTime need not worry about locking the clock. If methods in derived classes call GetPrivateTime, they should ensure that the clock is locked first and released afterward.

A derived clock can basically be implemented in one of two ways:

  • It can override GetPrivateTime (and SetTimeDelta if desired) and provide its own clock. This effectively abandons the clock in CBaseReferenceClock.
  • It can call SetTimeDelta from the derived clock to minimally adjust the time of the clock in CBaseReferenceClock.

CSystemClock is derived from CBaseReferenceClock and implements a stand-alone clock (not attached to a filter), which can be saved as part of a stored filter graph and used as the filter graph reference clock when the filter is restored. CSystemClock generates the default time base generated by CBaseReferenceClock (using the Win32 timeGetTime function).

Multiple Clocks in a Filter Graph

It sometimes happens that a filter graph will be built with more than one clock. Several filters in the graph might implement clocks or there might even be an independent system clock in the filter graph. Since only one clock can be the master clock, it is assumed that all other clocks, when notified of the sync source, will synchronize with it.

The filter graph manager has a default algorithm for choosing the master reference clock, and a filter uses this to ensure that its own reference clock becomes the master clock. Why would a filter want to insist on its own reference clock rather than letting the filter graph manager make the decision? There are several reasons to use a filter's own reference clock. For example, the filter's clock might:

  • Be tied to some external source that the filter graph must be synchronized with.
  • Be the most accurate.
  • Incur the lowest system overhead while being used.
  • Be the only clock that cannot be adjusted to be in sync with the other(s). (Although, it could be argued that this constitutes a badly designed clock.)

Here are the steps used by the filter graph manager for choosing the master reference clock in a filter graph:

  1. If a call to the filter graph manager's IMediaFilter::SetSyncSource method has been made, then that reference clock will be used (or no reference clock will be used if a null pointer was passed to IMediaFilter::SetSyncSource).
  2. If IMediaFilter::SetSyncSource has never been called for this graph, the sync source is provided by the first connected filter that exposes the IReferenceClock interface. In this case, the search for the first connected filter goes in roughly upstream order, starting with the renderers. Connected means the filter has an input pin connected to another filter. There is no check to see if that stream would actually be active. If more than one clock is found at the same level in this search, and both are connected, it is undefined which one will be used as the sync source for this filter graph. The filter graph manager will choose one of them.
  3. If neither of those steps result in a sync source being set, the filter graph manager will create a freestanding reference clock and use that as the sync source.

A filter can explicitly indicate which reference clock is to be the sync source by having the filter's IBaseFilter::JoinFilterGraph method call IMediaFilter::SetSyncSource on the filter graph manager when it joins the filter graph to set the desired clock. In fact, if the filter really needs its clock to be the reference clock, to the extent that the filter won't function properly if it isn't, then it should additionally fail the IBaseFilter::JoinFilterGraph call if the IMediaFilter::SetSyncSource call fails.

Having described how to force a filter's clock to be the system clock, it should be emphasized that this is not normally required.


Controlling Filter Graphs Using C

This article describes how to use the interfaces and methods exposed by the Microsoft® DirectShow™ dynamic-link library to communicate with the Filter Graph Manager and the filters in a graph. These interfaces and methods render a stream of time-stamped video data in applications that are based in Microsoft Windows®. This article provides an overview of the interfaces and methods to use, and then describes their use in the DirectShow CPlay sample application.

Contents of this article:

  • Interfaces that Access the Filter Graph Manager
  • CPlay Tutorial
  • Using the Filter Graph Manager

Interfaces that Access the Filter Graph Manager

The stream architecture enables applications to communicate with the filter graph manager, and the filter graph manager to communicate with individual filters to control the movement of data through the filter graph. It also enables filters to post events that an application can retrieve, so an application can, for example, retrieve status information about a special filter it has installed.

This section contains the following topics.

  • Implementing Dual Interfaces
  • Installing and Registering Quartz.dll
  • Instantiating the Filter Graph Manager
  • Invoking Methods on the Interfaces

An application communicates with the filter graph manager and the filters in a specific graph by using the interfaces exposed by either the filter graph manager or the filters. The following table identifies these interfaces.
Interface | Description
IAMCollection | Represents a collection of objects of type IFilterInfo, IRegFilterInfo, IMediaTypeInfo, and IPinInfo.
IBasicAudio | Controls and retrieves current volume setting.
IBasicVideo | Controls a generic video renderer.
IDeferredCommand | Used in conjunction with IQueueCommand methods to defer the execution of methods and properties.
IFilterInfo | Enables an Automation client to set and retrieve filter properties.
IGraphBuilder | Builds the filter graph manager.
IMediaControl | Instantiates the filter graph and controls media flow (runs, pauses, stops).
IMediaEvent | Enables customized event handling for events such as repainting, user termination, completion, and so on.
IMediaPosition and IMediaSeeking | Controls or retrieves start time, stop time, preroll rate, and current position.
IMediaTypeInfo | Enables an Automation client to retrieve a media type's major type and subtype.
IQueueCommand | Enables an application to queue methods and properties so that the filter invokes them during rendering of a video stream.
IPinInfo | Enables an Automation client to set and retrieve filter properties.
IRegFilterInfo | Enables an Automation client to retrieve the name of a registered filter and add a filter to the filter graph.
IVideoWindow | Controls window aspects of a video renderer, such as the window's position and size.

Of all the interfaces for the filter graph manager, C and C++ programmers use the following most effectively.

  • IBasicAudio
  • IBasicVideo
  • IDeferredCommand
  • IGraphBuilder
  • IMediaControl
  • IMediaEvent
  • IMediaSeeking
  • IQueueCommand
  • IVideoWindow

The remainder are collection interfaces, which enable Automation clients, such as Microsoft Visual Basic®, to access the properties of filters, pins, and media types that are not otherwise exposed to Automation clients.

Implementing Dual Interfaces

Most of the interfaces that communicate with the Filter Graph Manager are implemented as dual interfaces. This means that an application can call the methods in each interface directly or through Automation (by using the IDispatch::Invoke method). DirectShow provides Automation support for the developer using Visual Basic. The developer using C or C++ can avoid the indirection (and accompanying overhead) associated with Automation by calling the methods directly.

DirectShow doesn't implement all interfaces as dual interfaces. An application must call the methods in these interfaces directly. For example, the following interfaces are not dual interfaces: IQueueCommand, IDeferredCommand, and IGraphBuilder.

Installing and Registering Quartz.dll

Before you begin using the filter graph manager, you must install and register the Quartz.dll dynamic-link library. Currently, the DirectShow SDK setup program automates this process. Run Setup.exe and choose the Runtime option. This program copies Quartz.dll to your Windows\System directory and adds the appropriate entries to your system's registration database.

Instantiating the Filter Graph Manager

After you have registered Quartz.dll, you can begin using the filter graph manager in your Windows-based application. First, initialize the COM library by calling the COM CoInitialize function. The sample application calls CoInitialize within its InitApplication function in the Cplay.c file of the CPlay sample application.

Next, instantiate the filter graph manager. Most applications should use the CoCreateInstance function to instantiate the filter graph. Both CoCreateInstance and CoGetClassObject can instantiate an object; however, applications typically use the former to instantiate a single object and the latter to instantiate multiple instances of an object.

The complete call to CoCreateInstance appears as follows:

hr = CoCreateInstance( &CLSID_FilterGraph,          // Get this document's graph object.
              NULL,
              CLSCTX_INPROC_SERVER,
              & IID_IGraphBuilder,
              (void **) &media.pGraph);

The first parameter, CLSID_FilterGraph, is the class identifier (CLSID) for the filter graph manager. This CLSID is defined in the Uuids.h file, which is installed as part of the DirectShow SDK. The CLSID is a 128-bit value that the registration database uses to identify the dynamic-link library (DLL or in-process server). Using this value, COM can locate and then load the appropriate DLL.

The second parameter is a pointer to the outer IUnknown and is NULL because the Filter Graph object is not part of an aggregate.

The third parameter is the context in which the code that manages the Filter Graph will run, which is in the same process as the caller of the CoCreateInstance function.

The fourth parameter passed to the CoCreateInstance function identifies the interface that the application will use to communicate with the object. This interface identifier should be IID_IGraphBuilder; this value is defined internally in the DirectShow sources and then exposed in the Strmif.h file.

If the call to CoCreateInstance succeeds, this function returns a pointer to a filter graph manager object in the media.pGraph variable. After this pointer is returned, the application begins to call the methods in the IGraphBuilder interface. Typically, the application first calls the IGraphBuilder::RenderFile method. This method creates a filter graph for the type of file that was supplied as one of the parameters. In addition, the application can use the IGraphBuilder::QueryInterface method to retrieve pointers to any of the interfaces exposed by the filter graph manager. The IGraphBuilder interface derives from IUnknown.

If you are writing your application in C (rather than C++), you must use a vtable pointer to call the methods exposed by IGraphBuilder. The following example illustrates a call to the QueryInterface method on the IGraphBuilder interface from within an application written in C.

hr = media.pGraph->lpVtbl->QueryInterface(media.pGraph,
    &IID_IMediaEvent, (void **) &pME);

If you are writing your application in C++, the function is simpler; it requires less indirection and one less parameter:

hr = m_pGraph->QueryInterface(IID_IMediaEvent, (void **) &pME);

Invoking Methods on the Interfaces

An application can retrieve a pointer to any of the other interfaces exposed by the filter graph manager by calling the IGraphBuilder::QueryInterface method and supplying a REFIID for the corresponding interface. After retrieving this interface pointer, the application can begin calling the interface's methods by using the interface's vtable pointer (just as the IGraphBuilder's vtable pointer called the IGraphBuilder::QueryInterface method in the previous example). The application must release an acquired interface by calling the IUnknown::Release method on that interface.

CPlay Tutorial

This section's tutorial describes CPlay, a sample included in the DirectShow SDK that plays a media file. The source files for this application are in the Samples\DS\Player\CPlay subdirectory of the DirectShow SDK project.

This section contains the following topics.

  • CPlay Sample Application
  • Files in CPlay

This tutorial does not describe the Microsoft Windows® API code found in the source files. Instead, it focuses almost exclusively on the code that shows:

  • How to instantiate a filter graph for a particular file type.
  • How to process media events.
  • How to run, pause, and stop the media stream.
  • How to set a global variable to indicate the valid media state (running, paused, or stopped).
  • How to release the resources and clean up the variables used by the filter graph.

CPlay Sample Application

You can use the CPlay sample application to open a media file and then run, pause, or stop the corresponding media stream. The application's user interface consists of menus and a toolbar. The menus include File, Media, and Help. The toolbar includes Play, Pause, and Stop buttons.

CPlay sample application

After you open a file and click Play, the filter graph renders the video stream in its default window.

Files in CPlay

The sample application consists of six source files. Each file contains source code that accomplishes a specific set of tasks. For example, the About.c module contains the code that displays the About dialog box. The following table identifies each source file and describes its purpose.
File | Description
About.c | Displays the About dialog box.
Assert.c | Displays a message box with debugging information.
Cplay.c | Processes user input.
File.c | Displays the File Open dialog box.
Media.c | Instantiates the filter graph; invokes the filter graph methods to run, pause, and stop the video rendering.
Toolbar.c | Draws the toolbar buttons.

The remainder of this article focuses primarily on the code found in the Media.c file; however, references to other files appear when describing some of the tasks accomplished by this application.

Using the Filter Graph Manager

The Media.c file contains initialization, destruction and cleanup, command handling, and state change code. The initialization code instantiates a filter graph for a particular file type. The destruction code releases the resources and cleans up the variables used by the filter graph. The command handling code invokes the methods required to play, pause, or stop the video rendering. The state change code sets a global variable that indicates valid media states (that is, can stop, can pause, can play).

This section contains the following topics.

  • Initializing the Filter Graph Manager and the Filter Graph
  • Playing, Pausing, and Stopping the Video Stream
  • Handling Events

Initializing the Filter Graph Manager and the Filter Graph

The following code illustrates how to create the filter graph manager and the filter graph, including including how to enable event handling, and how to open the media file that the filter graph will render.

First, instantiate the filter graph manager. The CreateFilterGraph function in Media.c instantiates the filter graph manager by calling the COM CoCreateInstance function. It saves the pointer returned by CoCreateInstance in the pGraph member of a global media structure (defined in Media.h in the CPlay sample included in the SDK).

BOOL CreateFilterGraph()
{
    HRESULT hr;

    hr = CoCreateInstance(&CLSID_FilterGraph,  // CLSID of object
           NULL,                         // Outer unknown.
           CLSCTX_INPROC_SERVER,         // Type of server.
           &IID_IGraphBuilder,           // Interface wanted.
           (void **) &media.pGraph);     // Pointer to IGraphBuilder.
...
}

Next, enable event handling. Using the pointer returned by CoCreateInstance, the CreateFilterGraph function retrieves a pointer to the IMediaEvent interface by calling the IUnknown::QueryInterface method. The interface pointer retrieves an event notification handle by calling the IMediaEvent::GetEventHandle method. The main message loop uses this handle (the DoMainLoop function in CPlay.c). After GetEventHandle obtains the handle, CreateFilterGraph releases the pointer to the IMediaEvent interface by calling the IUnknown::Release method.

IMediaEvent *pME;

hr = media.pGraph->lpVtbl->QueryInterface(media.pGraph, &IID_IMediaEvent, (void **) &pME);
    if (FAILED(hr)) {
      DeleteContents(); //Releases the pointer media.pGraph.
      return FALSE;
    }

    hr = pME->lpVtbl->GetEventHandle(pME, (OAEVENT*) &media.hGraphNotifyEvent);
    pME->lpVtbl->Release( pME );

After instantiating the Filter Graph Manager and enabling event handling, open the media file to be rendered. In the CPlay sample application, a user opens a multimedia file. The file name extension (for example, .avi or .mpg) is unimportant, because the DirectShow filter graph examines the file header to ensure that the file is a multimedia file.

When the user opens a file by choosing Open from the File menu, this action calls the OpenMediaFile function in Media.c, which displays the File Open common dialog box.

 void OpenMediaFile( HWND hwnd, LPSTR szFile ){
// File..Open has been selected
    static char szFileName[ _MAX_PATH ];
    static char szTitleName[ _MAX_FNAME + _MAX_EXT ];
    // The user has already chosen a file.
    if( szFile!=NULL && RenderFile( szFile ) ){
        LPSTR szTitle;

        // Work out the full path name and the file name from the
        // specified file.
        GetFullPathName( szFile, _MAX_PATH, szFileName, &szTitle );
        strncpy( szTitleName, szTitle, _MAX_FNAME + _MAX_EXT );
        szTitleName[ _MAX_FNAME + _MAX_EXT -1 ] = '\0';

        // Set the main window title and update the state.
        SetTitle( hwnd, szTitleName );
        ChangeStateTo( Stopped );
// The user hasn't already chosen a file, so display the Open File
// dialog box. The DoFileOpenDialog function is in file.c in the CPlay
// sample.
    } else if( DoFileOpenDialog( hwnd, szFileName, szTitleName )
               && RenderFile( szFileName ) ){

        // Set the main window title and update the state.
        SetTitle( hwnd, szTitleName );
        ChangeStateTo( Stopped );
    }
}

After the file has been opened, render the file. The OpenMediaFile function passes the name of the user's chosen file to the RenderFile function in Media.c. The RenderFile function in turn calls the CreateFilterGraph function to instantiate the filter graph manager. After creating the filter graph manager, the RenderFile function calls the IGraphBuilder::RenderFile method to create the actual filter graph:

BOOL RenderFile( LPSTR szFileName )
{
    HRESULT hr;
    WCHAR wPath[MAX_PATH];
    DeleteContents(); // Release the pointer media.pGraph if it exists,
                      // because the call to CreateFilterGraph will
                      // retrieve a new pointer.

   //Create the filter graph manager
    if ( !CreateFilterGraph() ) {
      PlayerMessageBox( IDS_CANT_INIT_QUARTZ );
      return FALSE;
    }

    MultiByteToWideChar( CP_ACP, 0, szFileName, -1, wPath, MAX_PATH );
    SetCursor( LoadCursor( NULL, IDC_WAIT ) ); // Put up the hour-glass
                                               // while the media file
                                               // loads.
    // Create the actual filter graph
    hr = media.pGraph->lpVtbl->RenderFile(media.pGraph, wPath, NULL);
    SetCursor( LoadCursor( NULL, IDC_ARROW ) ); // Turn the cursor back
                                                // to an arrow.
    if (FAILED( hr )) {
      PlayerMessageBox( IDS_CANT_RENDER_FILE );
      return FALSE;
    }
    return TRUE;

}

Playing, Pausing, and Stopping the Video Stream

After the application creates the filter graph manager and the filter graph, it can expose the user interface, which enables the user to play, pause, and stop video rendering. In the case of CPlay, the toolbar buttons (Play, Pause, and Stop) are redrawn in color after the user chooses a valid file.

When the user clicks Play, the OnMediaPlay function is called. This function accomplishes the following tasks sequentially.

  1. Examines the global state variable in the media structure to ensure that the video can be rendered.
  2. Retrieves a pointer to the IMediaControl interface.
  3. Invokes the IMediaControl::Run method.
  4. Releases the IMediaControl interface.
  5. Sets the global state variable.

The OnMediaPlay function appears as follows:

void OnMediaPlay( void ){
    if( CanPlay() ){
        HRESULT   hr;
        IMediaControl *pMC;

        // Obtain the interface to our filter graph.
        hr = media.pGraph->lpVtbl->QueryInterface(media.pGraph,
            &IID_IMediaControl, (void **) &pMC);

        if( SUCCEEDED(hr) ){
            // Ask the filter graph to play and release the interface.
            hr = pMC->lpVtbl->Run( pMC );
            pMC->lpVtbl->Release( pMC );

            if( SUCCEEDED(hr) ){
                ChangeStateTo( Playing );
                return;
            }
        }

        // Inform the user that an error occurred.
        PlayerMessageBox( IDS_CANT_PLAY );

    }
}

The code that handles pausing and stopping the video stream is nearly identical to the code that plays the media stream. The actual functions that handle these tasks are OnMediaPause and OnMediaStop, respectively. You can find all this code in the Media.c file.

Handling Events

The IMediaEvent interface enables an application to receive events that the filter graph or individual filters within the graph raise. Following are some of the possible events and corresponding event notification messages.
Event notification message | Description
EC_COMPLETE | The video has finished rendering.
EC_USERABORT | A user forced the termination of a requested operation.
EC_ERRORABORT | An error forced the termination of a requested operation.
EC_PALETTE_CHANGED | The video palette changed.
EC_REPAINT | The display should be repainted.

The sample application tracks the EC_COMPLETE, EC_USERABORT, and EC_ERRORABORT events by using the IMediaEvent::GetEvent method. The application calls this method from within the OnGraphNotify function. The application calls the OnGraphNotify function (in Media.c) from within the application's main message loop function (DoMainLoop), which you can find in the Cplay.c file.

If any of these events are raised, OnGraphNotify immediately stops video rendering by calling the OnMediaStop function.

The OnGraphNotify function accomplishes the following tasks sequentially.

  1. Declares the IMediaEvent interface pointer and the variables for the event code and event parameters.
  2. Retrieves a pointer to the IMediaEvent interface by calling IUnknown::QueryInterface.
  3. Calls the IMediaEvent::GetEvent method to retrieve the next event notification. The retrieved event is stored in the lEventCode variable and the event parameters are stored in the lParam1 and lParam2 variables. The time-out value is set to zero, which means that GetEvent will not wait for an event to occur, but only return an already waiting event.
  4. Checks the event type stored in lEventCode and takes the appropriate action, if GetEvent retrieves an event. See Event Notification Codes for a list of the system-supplied events that DirectShow supports. Note that if the event parameters are declared as type BSTR instead of LONG, IMediaEvent::FreeEventParams should be called free the BSTRs.
void OnGraphNotify(void) {
    IMediaEvent *pME;

    long lEventCode, lParam1, lParam2;

    ASSERT( media.hGraphNotifyEvent != NULL );

    if( SUCCEEDED(media.pGraph->lpVtbl->QueryInterface(media.pGraph,
            &IID_IMediaEvent, (void **) &pME))){
        if( SUCCEEDED(pME->lpVtbl->GetEvent(pME, &lEventCode, &lParam1,
                &lParam2, 0))
            && ( lEventCode == EC_COMPLETE
                || lEventCode == EC_USERABORT
                || lEventCode == EC_ERRORABORT
                )
          )
            OnMediaStop();
              pME->lpVtbl->Release( pME );
              }
}


Creating a Capture Application

Microsoft® DirectShow™ provides the capability to capture and preview both video and audio data from an application, when combined with the appropriate capture hardware. The data source might include a VCR, camera, TV tuner, microphone, or other source. An application can display the captured data immediately (preview) or save it to a file for later viewing either inside or outside of the application.

DirectShow takes advantage of new capture drivers that are written as DirectShow filters, and also uses existing Video for Windows-style drivers.

Note This article relies heavily on the AMCap Sample (DirectShow Capture Application) sample application. See the AMCap sample code (Amcap.cpp) in the Samples\DS\Capture directory of the DirectShow SDK for complete sample code, because this article does not present AMCap Sample (DirectShow Capture Application) in its entirety.

The AMCap Sample (DirectShow Capture Application) sample application performs video and audio capture, similar to the VidCap sample from Video for Windows®. It uses the ICaptureGraphBuilder interface to handle the majority of the capture work. In your own capture application, you'll use the same methods and interfaces that AMCap uses. This article focuses on AMCap's use of ICaptureGraphBuilder to perform video and audio capture and presents relevant code excerpts from AMCap.

This article assumes you are familiar with the DirectShow filter graph architecture and the general layout of a capture filter graph. See Filter Graph Manager and Filter Graphs and About Capture Filter Graphs for more information.

Contents of this article:

  • Introduction to ICaptureGraphBuilder
  • Device Enumeration and Capture Interfaces
  • Building the Capture and Preview Filter Graph
  • Controlling the Capture Filter Graph
  • Obtaining Capture Statistics
  • Saving the Captured File
  • Displaying Property Pages
  • Additional Notes

Introduction to ICaptureGraphBuilder

The ICaptureGraphBuilder interface provides a filter graph builder object that applications use to handle some of the more tedious tasks involved in building a capture filter graph, which frees the application to focus on capture. You access the graph builder object by calling methods on ICaptureGraphBuilder. The variety of methods satisfies the basic requirements for capture and preview functionality.

The FindInterface method searches for a particular capture-related interface in the filter graph. The method handles the complexities of filter graph traversal for you, which enables you to access the functionality of a particular interface without having to enumerate pins and filters in the filter graph looking for the interface. The RenderStream method connects source filters to rendering filters, optionally adding other needed intermediate filters. The ControlStream method independently control sections of the graph for frame-accurate start and stop.

Additional methods deal with allocating space for the capture file (AllocCapFile), specifying a name for it and building up the file writer section of the graph, which consists of the multiplexer and file writer filters (SetOutputFileName), and saving the captured data to another file (CopyCaptureFile). Finally, SetFiltergraph and GetFiltergraph enable the application to provide a filter graph for the graph builder to use or retrieve the filter graph already in use.

Device Enumeration and Capture Interfaces

AMCap's InitCapFilters function enumerates the capture devices on the system by using the ICreateDevEnum::CreateClassEnumerator method. After enumerating a capture device and instantiating a DirectShow filter to use that device, the sample calls the ICaptureGraphBuilder::FindInterface method several times to obtain interface pointers for the IAMDroppedFrames, IAMVideoCompression, IAMStreamConfig, and IAMVfwCaptureDialogs capture-related interfaces. The AMCap code saves all of these interface pointers for later use in the gcap global structure and uses gcap structure members throughout the code.

Note: IAMVfwCaptureDialogs is designed for you to use only with the Microsoft-supplied video capture filter and only when using a former Video for Windows device.

For your convenience, the declaration of the gcap structure follows:

struct _capstuff {
    char szCaptureFile[_MAX_PATH];
    WORD wCapFileSize;  // size in Meg
    ICaptureGraphBuilder *pBuilder;
    IVideoWindow *pVW;
    IMediaEventEx *pME;
    IAMDroppedFrames *pDF;
    IAMVideoCompression *pVC;
    IAMVfwCaptureDialogs *pDlg;
    IAMStreamConfig *pASC;      // for audio cap
    IAMStreamConfig *pVSC;      // for video cap
    IBaseFilter *pRender;
    IBaseFilter *pVCap, *pACap;
    IGraphBuilder *pFg;
    IFileSinkFilter *pSink;
    IConfigAviMux *pConfigAviMux;
    int  iMasterStream;
    BOOL fCaptureGraphBuilt;
    BOOL fPreviewGraphBuilt;
    BOOL fCapturing;
    BOOL fPreviewing;
    BOOL fCapAudio;
    int  iVideoDevice;
    int  iAudioDevice;
    double FrameRate;
    BOOL fWantPreview;
    long lCapStartTime;
    long lCapStopTime;
    char achFriendlyName[120];
    BOOL fUseTimeLimit;
    DWORD dwTimeLimit;
} gcap;

AMCap's InitCapFilters function stores several interface pointers in the gcap structure. Be sure to properly release all interface pointers when they are no longer needed as shown in the following example.

    if (gcap.pBuilder)
      gcap.pBuilder->Release();
    gcap.pBuilder = NULL;
    if (gcap.pSink)
      gcap.pSink->Release();
    gcap.pSink = NULL;
    if (gcap.pConfigAviMux)
      gcap.pConfigAviMux->Release();
    gcap.pConfigAviMux = NULL;
    if (gcap.pRender)
      gcap.pRender->Release();
    gcap.pRender = NULL;
    if (gcap.pVW)
      gcap.pVW->Release();
    gcap.pVW = NULL;
    if (gcap.pME)
      gcap.pME->Release();
    gcap.pME = NULL;
    if (gcap.pFg)
      gcap.pFg->Release();
    gcap.pFg = NULL;

See Enumerate and Access Hardware Devices in DirectShow Applications for more information about device enumeration.

Building the Capture and Preview Filter Graph

AMCap includes a BuildCaptureGraph function that builds up a capture graph with both capture and preview components. Most applications will perform the same tasks sequentially as described in the following topics contained in this section.

  • Set the Capture File Name
  • Create a Graph Builder Object
  • Set the Output File Name
  • Retrieve the Current Filter Graph
  • Add the Capture Filters to the Filter Graph
  • Render the Capture Pins
  • Render the Video Preview Pin
  • Configure the Video Preview Window

These tasks are explained in greater detail later in this section.

AMCap also includes a BuildPreviewGraph function that is essentially a version of BuildCaptureGraph that deals only with preview. Another difference between BuildCaptureGraph and BuildPreviewGraph is that the latter uses ICaptureGraphBuilder::SetFiltergraph to provide a filter graph object (IGraphBuilder interface) for the capture graph builder object (ICaptureGraphBuilder interface) to use. You probably won't need to call SetFiltergraph as the graph builder object creates a filter graph to use by default. Use this method only if you have already created your own filter graph and want the graph builder to use your filter graph. If you call this method after the graph builder has created a filter graph, this method will fail. BuildPreviewGraph calls CoCreateInstance to create a new filter graph object, if necessary, as shown in the following example.

hr = CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
                      IID_IGraphBuilder, (LPVOID *)&gcap.pFg);

hr = gcap.pBuilder->SetFiltergraph(gcap.pFg);
    if (hr != NOERROR) {
      ErrMsg("Cannot give graph to builder");
      goto SetupPreviewFail;
    }

The details of each important task performed by BuildCaptureGraph follow.

Set the Capture File Name

AMCap's SetCaptureFile function displays the common Open File dialog box to enable the user to select a capture file. If the specified file is a new file, it calls the application-defined AllocCaptureFile function that prompts the user to allocate space for the capture file. This "preallocation" of file space is important, because it reserves a large block of space on disk. This speeds up the capture operation when it occurs, because the file space doesn't have to be allocated while capture takes place (it has been preallocated). The ICaptureGraphBuilder::AllocCapFile method performs the actual file allocation. IFileSinkFilter::SetFileName instructs the file writer filter to use the file name that the user chose. The code assumes you've called ICaptureGraphBuilder::SetOutputFileName to add the file writer to the filter graph. See Set the Output File Name for more information.

The AMCap-defined SetCaptureFile and AllocCaptureFile functions follow:

/*
 * Put up a dialog to allow the user to select a capture file.
 */
BOOL SetCaptureFile(HWND hWnd)
{
    if (OpenFileDialog(hWnd, gcap.szCaptureFile, _MAX_PATH)) {
        OFSTRUCT os;

      // We have a capture file name.

        /*
         * If this is a new file, then invite the user to
         * allocate some space.
         */
        if (OpenFile(gcap.szCaptureFile, &os, OF_EXIST) == HFILE_ERROR) {

          // Bring up dialog, and set new file size.
          BOOL f = AllocCaptureFile(hWnd);
          if (!f)
            return FALSE;
        }
    } else {
      return FALSE;
    }

    SetAppCaption();      // Need a new app caption.

    // Tell the file writer to use the new file name.
    if (gcap.pSink) {
        WCHAR wach[_MAX_PATH];
        MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, gcap.szCaptureFile, -1,
                            wach, _MAX_PATH);
        gcap.pSink->SetFileName(wach, NULL);
    }

    return TRUE;
}

// Preallocate the capture file.
//
BOOL AllocCaptureFile(HWND hWnd)
{
// We'll get into an infinite loop in the dlg proc setting a value.
    if (gcap.szCaptureFile[0] == 0)
      return FALSE;

    /*
     * Show the allocate file space dialog to encourage
     * the user to pre-allocate space.
     */
    if (DoDialog(hWnd, IDD_AllocCapFileSpace, AllocCapFileProc, 0)) {

      // Ensure repaint after dismissing dialog before
      // possibly lengthy operation.
      UpdateWindow(ghwndApp);

      // User has hit OK. Alloc requested capture file space.
      BOOL f = MakeBuilder();
      if (!f)
        return FALSE;
      WCHAR wach[_MAX_PATH];
      MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, gcap.szCaptureFile, -1,
                          wach, _MAX_PATH);
      if (gcap.pBuilder->AllocCapFile(wach,
                                gcap.wCapFileSize * 1024L * 1024L) != NOERROR) {
        MessageBoxA(ghwndApp, "Error",
                    "Failed to pre-allocate capture file space",
                    MB_OK | MB_ICONEXCLAMATION);
        return FALSE;
        }
    return TRUE;
    } else {
        return FALSE;
        }
}

Create a Graph Builder Object

AMCap's MakeBuilder function creates a capture graph builder object and obtains an ICaptureGraphBuilder interface pointer by calling CoCreateInstance. If you already have a capture graph builder object, you can call QueryInterface to obtain an interface pointer. AMCap stores the object pointer in the pBuilder member of the global gcap structure.

// Make a graph builder object we can use for capture graph building.
//
BOOL MakeBuilder()
{
    // We have one already.
    if (gcap.pBuilder)
      return TRUE;

    HRESULT hr = CoCreateInstance((REFCLSID)CLSID_CaptureGraphBuilder,
                    NULL, CLSCTX_INPROC, (REFIID)IID_ICaptureGraphBuilder,
                    (void **)&gcap.pBuilder);
    return (hr == NOERROR) ? TRUE : FALSE;
}

Set the Output File Name

AMCap creates the rendering section of the filter graph, consisting of the AVI MUX (multiplexer) and the File Writer. It also provides the filter graph with the previously specified file name to which to save the captured data. See About Capture Filter Graphs for more information about capture filter graph in general.

ICaptureGraphBuilder::SetOutputFileName signals to add the multiplexer and file writer to the filter graph, connects them, and sets the file name. The following example illustrates a call to SetOutputFileName.

//
// We need a rendering section that will write the capture file out in AVI
// file format.
//

    WCHAR wach[_MAX_PATH];
    MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, gcap.szCaptureFile, -1, wach,
                        _MAX_PATH);
    GUID guid = MEDIASUBTYPE_Avi;
    hr = gcap.pBuilder->SetOutputFileName(&guid, wach, &gcap.pRender,
                                          &gcap.pSink);
    if (hr != NOERROR) {
      ErrMsg("Error %x: Cannot set output file", hr);
      goto SetupCaptureFail;
    }

In the above code fragment the value of the first parameter, pType, in the call to SetOutputFileName is MEDIASUBTYPE_Avi, indicating that the capture graph builder object will insert an AVI multiplexer filter. Consequently, the file writer that is connected to the multiplexer will write the data to the capture file in AVI file format.

The second parameter, lpwstrFile, specifies the file name. The last two parameters contain pointers to the multiplexer filter and the file writer filter, respectively, and are initialized for you by the capture graph builder object upon return from SetOutputFileName. AMCap stores these pointers in the pRender and pSink members of its gcap structure. Internally, the capture graph builder object creates a filter graph object which exposes the IGraphBuilder interface and inserts these two filters into that filter graph. It tells the file writer to use the specified file when writing to disk.

Alternatively, if you want filters besides the multiplexer and file writer in the rendering section of your filter graph, call IFilterGraph::AddFilter to explicitly add the necessary filters. You might need to remember the pointer to the IBaseFilter interface of the first filter in your custom rendering chain so you can use it in calls such as RenderStream.

Retrieve the Current Filter Graph

Because the capture graph builder object created a filter graph in response to SetOutputFileName and you must put the necessary filters in the same filter graph, call the ICaptureGraphBuilder::GetFiltergraph method to retrieve the newly created filter graph. The pointer to the filter graph's IGraphBuilder interface is returned in the function's parameter.

//
// The graph builder created a filter graph to do that.  Find out what it is,
// and put the video capture filter in the graph too.
//

    hr = gcap.pBuilder->GetFiltergraph(&gcap.pFg);
    if (hr != NOERROR) {
      ErrMsg("Error %x: Cannot get filtergraph", hr);
      goto SetupCaptureFail;
    }

Add the Capture Filters to the Filter Graph

Call IFilterGraph::AddFilter to add the capture filters to the filter graph as shown in the following example.

    hr = gcap.pFg->AddFilter(gcap.pVCap, NULL);
    if (hr != NOERROR) {
      ErrMsg("Error %x: Cannot add vidcap to filtergraph", hr);
      goto SetupPreviewFail;
    }

    hr = gcap.pFg->AddFilter(gcap.pACap, NULL);
      if (hr != NOERROR) {
          ErrMsg("Error %x: Cannot add audcap to filtergraph", hr);
          goto SetupCaptureFail;
      }

Render the Capture Pins

The ICaptureGraphBuilder::RenderStream method connects the source filter's pin to the rendering filter. It connects intermediate filters if necessary. The pin category is optional, but typically specifies either a capture pin (PIN_CATEGORY_CAPTURE) or a preview pin (PIN_CATEGORY_PREVIEW). The following example connects the capture pin on the video capture filter (represented by the gcap.pVCap variable) to the renderer (represented by gcap.pRender).

//
// Render the video capture and preview pins - we may not have preview, so
// don't worry if it doesn't work.
//

    hr = gcap.pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, gcap.pVCap,
                                     NULL, gcap.pRender);
    // Error checking.

Call ICaptureGraphBuilder::RenderStream again to connect the audio capture filter (represented by gcap.pACap) to the audio renderer as in the following example.

//
// Render the audio capture pin?
//

    if (gcap.fCapAudio) {
      hr = gcap.pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, gcap.pACap, NULL, gcap.pRender);
    // Error checking.

Render the Video Preview Pin

Call ICaptureGraphBuilder::RenderStream again to render the graph from the capture filter's preview pin to a video renderer as in the following example.

    hr = gcap.pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, gcap.pVCap,
                                     NULL, NULL);

Configure the Video Preview Window

By default, the video preview window will be a separate window from your application window. If you want to change the default behavior, call ICaptureGraphBuilder::FindInterface to obtain a pointer to the IVideoWindow interface. The first parameter, pCategory specifies the output pin category to search for a connected filter that supports the desired interface. The code fragment below uses PIN_CATEGORY_PREVIEW to indicate a search beginning with all preview pins, and continuing to any pins and filters that connect to the preview pins. If that fails, the code then tries to call FindInterface again, with PIN_CATEGORY_CAPTURE, because some capture filters do not have a preview pin, only a capture pin, and the graph builder may have used a Smart Tee filter to provide a preview, which means the IVideoWindow interface will be found connected to the capture pin. See the documentation on the Smart Tee filter for more information.

The second parameter, specified by the gcap.pVCap variable below, represents the video capture filter. The third (riid) is the identifier for the desired interface (IID_IVideoWindow), and the last will be filled upon return from this function to give you the IVideoWindow interface. After you have the IVideoWindow interface, you can call IVideoWindow methods such as put_Owner, put_WindowStyle, or SetWindowPosition to take ownership of the video preview window, make it a child of your application, or to position it as desired.

// This will go through a possible decoder, find the video renderer it's
// connected to, and get the IVideoWindow interface on it.
   hr = gcap.pBuilder->FindInterface(&PIN_CATEGORY_PREVIEW, gcap.pVCap,
            IID_IVideoWindow, (void **)&gcap.pVW);
    if (hr != NOERROR) {
       hr = gcap.pBuilder->FindInterface(&PIN_CATEGORY_CAPTURE, gcap.pVCap,
            IID_IVideoWindow, (void **)&gcap.pVW);
    }
    if (hr != NOERROR) {

      ErrMsg("This graph cannot preview");
    } else {
      RECT rc;
      gcap.pVW->put_Owner((long)ghwndApp);    // We own the window now.
      gcap.pVW->put_WindowStyle(WS_CHILD);    // You are now a child.
      // Give the preview window all our space but where the status bar is.
      GetClientRect(ghwndApp, &rc);
      cyBorder = GetSystemMetrics(SM_CYBORDER);
      cy = statusGetHeight() + cyBorder;
      rc.bottom -= cy;
      gcap.pVW->SetWindowPosition(0, 0, rc.right, rc.bottom); // Be this big.
      gcap.pVW->put_Visible(OATRUE);
    }

Now that you've built the entire capture filter graph, you can preview video, audio, or actually capture data.

Controlling the Capture Filter Graph

Because a capture filter graph constructed by the ICaptureGraphBuilder interface is simply a specialized filter graph, controlling a capture filter graph is much like controlling any other kind of filter graph: you use the IMediaControl interface's Run, Pause, and Stop methods. You can use the CBaseFilter::Pause method to cue things up, but remember that capture and recompression only happen when the graph is running. In addition, ICaptureGraphBuilder provides the ControlStream method to control the start and stop times of the capture filter graph's streams. Internally, ControlStream calls the IAMStreamControl::StartAt and IAMStreamControl::StopAt methods to start and stop the capture and preview portions of the filter graph for frame-accurate control.

Note: This method might not work on every capture filter because not every capture filter supports IAMStreamControl on its pins.

The ICaptureGraphBuilder::ControlStream method's first parameter (pCategory) is a pointer to a GUID that specifies the output pin category. This value is normally either PIN_CATEGORY_CAPTURE or PIN_CATEGORY_PREVIEW. See the Pin Property Set for a complete list of categories. Specify NULL to control all capture filters in the graph.

The second parameter (pFilter) in ICaptureGraphBuilder::ControlStream indicates which filter to control. Specify NULL to control the whole filter graph as AMCap does.

To run only the preview portion of the capture filter graph, prevent capture by calling ICaptureGraphBuilder::ControlStream with the capture pin category and the value MAX_TIME as the start time (third parameter, pstart). Call the method again with preview as the pin category, and a NULL start value to start preview immediately. The fourth parameter indicates the desired stop time (pstop, as with start time, NULL means immediately). MAX_TIME is defined in the DirectShow base classes as the maximum reference time, and in this case means to ignore or cancel the specified operation.

The last two parameters, wStartCookie and wStopCookie are start and stop cookies respectively. These cookies are arbitrary values set by the application so that it can differentiate between start and stop times and tell when specific actions have been completed. AMCap doesn't use a specific time in ICaptureGraphBuilder::ControlStream, so it doesn't need any cookies. If you use a cookie, use IMediaEvent to get event notifications. See IAMStreamControl for more information.

The following code fragment sets preview to start immediately, but ignores capture.

    // Let the preview section run, but not the capture section.
    // (There might not be a capture section.)
    REFERENCE_TIME start = MAX_TIME, stop = MAX_TIME;
    // Show us a preview first? but don't capture quite yet...
    hr = gcap.pBuilder->ControlStream(&PIN_CATEGORY_PREVIEW, NULL,
                                      gcap.fWantPreview ? NULL : &start,
                                      gcap.fWantPreview ? &stop : NULL, 0, 0);
    if (SUCCEEDED(hr))
        hr = gcap.pBuilder->ControlStream(&PIN_CATEGORY_CAPTURE, NULL, &start,
                                          NULL, 0, 0);

The same concept applies if you want only to capture and not preview. Set the capture start time to NULL to capture immediately and set the capture stop time to MAX_TIME. Set the preview start time to MAX_TIME, with an immediate (NULL) stop time.

The following example tells the filter graph to start the preview stream now (the pstart (third) parameter is NULL). Specifying MAX_TIME for the stop time (pstop) means disregard the stop time.

    gcap.pBuilder->ControlStream(&PIN_CATEGORY_PREVIEW, NULL, NULL, MAX_TIME, 0, 0);

Calling IMediaControl::Run runs the graph.

// Run the graph.
    IMediaControl *pMC = NULL;
    HRESULT hr = gcap.pFg->QueryInterface(IID_IMediaControl, (void **)&pMC);
    if (SUCCEEDED(hr)) {
      hr = pMC->Run();
      if (FAILED(hr)) {
          // Stop parts that ran.
          pMC->Stop();
      }
      pMC->Release();
    }
    if (FAILED(hr)) {
      ErrMsg("Error %x: Cannot run preview graph", hr);
      return FALSE;

If the graph is already running, start capture immediately with another call to ICaptureGraphBuilder::ControlStream. For example, the following call controls the whole filter graph (NULL pFilter (second) parameter), starts now (NULL pstart (third) parameter), and never stops (pstop (fourth) parameter initialized to MAX_TIME).

    REFERENCE_TIME stop = MAX_TIME;

    // NOW!
    gcap.pBuilder->ControlStream(&PIN_CATEGORY_CAPTURE, NULL, NULL, &stop, 0, 0);

AMCap uses this approach to start capture in response to the user clicking a button.

To stop the capture or preview operation, call IMediaControl::Stop, much as you called IMediaControl::Run to run the filter graph.

// Stop the graph.
    IMediaControl *pMC = NULL;
    HRESULT hr = gcap.pFg->QueryInterface(IID_IMediaControl, (void **)&pMC);
    if (SUCCEEDED(hr)) {
      hr = pMC->Stop();
      pMC->Release();
    }

Obtaining Capture Statistics

AMCap calls methods on the IAMDroppedFrames interface to obtain capture statistics. It determines the number of frames dropped (IAMDroppedFrames::GetNumDropped) and captured (IAMDroppedFrames::GetNumNotDropped), and uses the Win32 timeGetTime function at the beginning and end of capture to determine the capture operation's duration. The IAMDroppedFrames::GetAverageFrameSize method provides the average size of captured frames in bytes. Use the information from IAMDroppedFrames::GetNumNotDropped, timeGetTime, and IAMDroppedFrames::GetAverageFrameSize to obtain the total bytes captured and calculate the sustained frames per second for the capture operation.

Saving the Captured File

The original preallocated capture file temporarily holds capture data so you can capture as quickly as possible. When you want to save the data you captured to a more permanent location, call ICaptureGraphBuilder::CopyCaptureFile. This method transfers the captured data out of the previously allocated capture file to another file you choose. The resulting new file size matches the size of the actual captured data rather than the preallocated file size, which is usually very large.

The ICaptureGraphBuilder::CopyCaptureFile method's first parameter, lpwstrOld, is the file you're copying from (typically the very large, preallocated file you always use for capture). The second parameter, lpwstrNew, is the file to which you want to save your captured data. Setting the third parameter, fAllowEscAbort, to TRUE indicates that the user is allowed to abort the copy operation by pressing ESC. The last parameter, pCallback, is optional and enables you to supply a progress indicator, if desired, by implementing the IAMCopyCaptureFileProgress interface. The following example demonstrates a call to CopyCaptureFile.

    hr = pBuilder->CopyCaptureFile(wachSrcFile, wachDstFile,TRUE,NULL);

The SaveCaptureFile function defined by AMCap prompts the to enter a new file name in the Open File common dialog box, uses the Win32 MultiByteToWideChar function to convert the file name to a wide string, and saves the captured data to the specified file using ICaptureGraphBuilder::CopyCaptureFile.

/*
 * Put up a dialog to allow the user to save the contents of the capture file
 * elsewhere.
 */
BOOL SaveCaptureFile(HWND hWnd)
{
    HRESULT hr;
    char achDstFile[_MAX_PATH];
    WCHAR wachDstFile[_MAX_PATH];
    WCHAR wachSrcFile[_MAX_PATH];

    if (gcap.pBuilder == NULL)
      return FALSE;

    if (OpenFileDialog(hWnd, achDstFile, _MAX_PATH)) {

      // We have a capture file name.
      MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, gcap.szCaptureFile, -1,
                          wachSrcFile, _MAX_PATH);
      MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, achDstFile, -1,
                          wachDstFile, _MAX_PATH);
      statusUpdateStatus(ghwndStatus, "Saving capture file - please wait...");

      // We need our own graph builder because the main one might not exist.
      ICaptureGraphBuilder *pBuilder;
      hr = CoCreateInstance((REFCLSID)CLSID_CaptureGraphBuilder,
                            NULL, CLSCTX_INPROC, (REFIID)IID_ICaptureGraphBuilder,
                            (void **)&pBuilder);
      if (hr == NOERROR) {
          // Allow the user to press ESC to abort... don't ask for progress.
          hr = pBuilder->CopyCaptureFile(wachSrcFile, wachDstFile,TRUE,NULL);
          pBuilder->Release();
      }
      if (hr == S_OK)
          statusUpdateStatus(ghwndStatus, "Capture file saved");
      else if (hr == S_FALSE)
          statusUpdateStatus(ghwndStatus, "Capture file save aborted");
      else
          statusUpdateStatus(ghwndStatus, "Capture file save ERROR");
      return (hr == NOERROR ? TRUE : FALSE);

    } else {
return TRUE;    // They canceled or something.
    }
}

See Amcap.cpp and Status.cpp from the AMCap sample for more details about capturing media files and obtaining capture statistics.

Displaying Property Pages

DirectShow provides a number of interfaces to customize the settings of a capture filter graph including: IAMStreamConfig, IAMVideoCompression, IAMCrossbar, IAMTVTuner, IAMTVAudio, IAMAnalogVideoDecoder, IAMCameraControl, IAMVideoProcAmp. Creating a property page is one way of allowing users to interact with these settings.

To bring up the settings associated with an object on a property page, use an interface on the object to query for the ISpecifyPropertyPages interface. Use this interface to obtain a list of property page CLSIDs that this object supports. The CLSID list can be later passed to OleCreatePropertyFrame or OleCreatePropertyFrameIndirect to invoke a property sheet. This will supply your application with the custom property pages a filter has in addition to the standard pages.

There are at least 9 objects that can have property pages in capture applications. Capture applications usually have 2 of these objects at least; the video capture filter and the audio capture filter (call them pVCap and pACap). These objects expose the IBaseFilter interface which can be used to query for the ISpecifyPropertyPages interface. You can obtain a pointer to the other 7 objects as follows:

  1. The video capture filter's capture pin. Get this by calling :
    FindInterface(&PIN_CATEGORY_CAPTURE, pVCap, IID_IPin, &pX);
  2. The video capture filter's preview pin. Get this by calling:
    FindInterface(&PIN_CATEGORY_PREVIEW, pVCap, IID_IPin, &pX);
  3. The audio capture filter's capture pin. Get this by calling:
    FindInterface(&PIN_CATEGORY_CAPTURE, pACap, IID_IPin, &pX);
  4. The crossbar connected to the video capture filter. Get this by calling:
    FindInterface(NULL, pVCap, IID_IAMCrossbar, &pX);
  5. A possible second crossbar, that controls both audio and video. This crossbar, if it exists, will be upstream of the crossbar found in #4. Get this by calling:

pX->QueryInterface(IID_IBaseFilter, (void **)&pBaseFilter);
FindInterface(&LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, &pX2);
pBaseFilter->Release();

    where pX is the interface obtained by #4.

  6. The TV Tuner connected to the video capture filter. Get this by calling:
    FindInterface(NULL, pVCap, IID_IAMTVTuner, &pX);
  7. The TV Audio connected to the audio capture filter. Get this by calling:
    FindInterface(NULL, pACap, IID_IAMTVAudio, &pX);

If you do not wish to create your property page using the ISpecifyPropertyPages interface and the OleCreatePropertyFrame function, you can create your own custom property pages and use the results of your page to call the interfaces programmatically.

Additional Notes

The following section provides some additional notes on using the ICaptureGraphBuilder::RenderStream method. It details specific examples of how to customize a capture graph from your application.

  1. The following example will render the preview pin of a video capture filter, connecting it to a default set of filters (usually a video renderer, possibly through a decompression filter), creating a graph that can be used to watch live video in a window (pCaptureFilter is the IBaseFilter interface of a video capture filter). Note that if the capture filter does not have a preview pin, this will still succeed and provide you with a preview by using a Smart Tee filter. See the Smart Tee documentation for more information.
    RenderStream(&PIN_CATEGORY_PREVIEW, pCaptureFilter, NULL, NULL);
  2. The following example will render the capture pin of a video capture filter to an AVI Mux filter, creating a graph that will create an AVI file out of live video data (pCaptureFilter is the IBaseFilter interface of a video capture filter and pAVIMuxFilter is the IBaseFilter interface of an AVI Mux filter created using the ICaptureGraphBuilder::SetOutputFileName method).
    RenderStream(&PIN_CATEGORY_CAPTURE, pCaptureFilter, NULL, pAVIMuxFilter);
  3. The following example will create a graph that will recompress the video of an AVI file into Cinepak format, and leave the audio as is, and create a new AVI file (pSourceFilter is the IBaseFilter interface of a File Source Filter that is reading from an AVI file, pCinepakCompressor is the IBaseFilter interface of a Cinepak Video Compressor filter, and pAVIMuxFilter is the IBaseFilter interface of an AVI Mux filter created using the ICaptureGraphBuilder::SetOutputFileName method).
    RenderStream(NULL, pSourceFilter, pCinepakCompressor, pAVIMuxFilter);
  4. Finally, in the last example, the source filter can provide (through an AVI splitter) two outputs; a video stream and an output stream.
    RenderStream(NULL, pSourceFilter, NULL, pAVIMuxFilter);

    Note With the RenderStream method it is impossible to specify which stream you want, since the category is NULL in both cases. Because of this, it is important to connect the stream that is going through a compressor first, because only the video stream will successfully connect through the cinepak compressor, ensuring the right stream is chosen. After that, the only stream left unconnected is the audio stream, so the second call to RenderStream will correctly connect the audio stream to the AVI Mux. If you are dealing with AVI files or other files with more than 2 streams, this method will be unreliable for connecting up the stream you want, and you will want to build your graph step by step.


Filter Categories

If you use the GraphEdt sample tool that comes with the DirectShow™ SDK, and choose Insert Filters from the Graph menu, you will notice that the DirectShow filters on the system are grouped into categories. The DirectShow Filters category is the generic category that most filters fall into. New filters will be registered in this category by default. Graphedt does not display empty categories.

However, if your filter is one of the following kinds of filters, you should make sure that your filter appears in the proper category:

  • Audio Capture Sources - generate audio data from an external device.
  • Audio Compressors - compress PCM audio.
  • Audio Renderers - play audio a data on a local set of speakers.
  • Midi Renderers - play MIDI data on a local set of speakers.
  • Video Capture Sources - generate video data from an external device.
  • Video Compressors - turn RGB video into compressed video.

How to register your filters by category is described in the AMovieDllRegisterServer2 topic, where sample code is shown for registering a Video Compressor filter. The AMCap sample shows how to enumerate a special category. The VidCap sample demonstrates registering a filter in a special category. See Register DirectShow Objects for additional information about registering.


About Cutlists

This article introduces cutlists and discusses interfaces that provide cutlist support. See Using Cutlists for information about the limitations of the current cutlist implementation and sample code for using cutlists in an application.

Contents of this article:

  • What Are Cutlists?
  • Cutlist Objects and Interfaces

What Are Cutlists?

A cutlist is a list of audio or video clips (cutlist elements) you want to play back sequentially. For each clip, the cutlist element contains the file name from which to create the clip, and details about the clip including start and stop time within that file. A cutlist is either video- or audio- specific, and that video or audio data must all be of the same media type. The beginning time for the clip, relative to the source file, is called the trimin position and the ending time for the clip is the trimout position.

You use cutlists to edit pieces of AVI and WAV files together. For instance a video cutlist could contain video clips (elements) with characteristics as follows:
Clip # | File Name | Start Time | Stop Time | Type | Stream #
1 | Venus.avi | 5 seconds | 10 seconds | video | 0
2 | Mars.avi | 15 seconds | 20 seconds | video | 0
3 | Venus.avi | 15 seconds | 30 seconds | video | 0

In the preceding example, the first and third clips are both taken from the same file. One clip is from seconds 5 through 10 of Venus.avi, while another is from seconds 15 through 30 of the same file. Between those clips, the cutlist contains seconds 15 through 20 of Mars.avi. All clips are taken from the first video stream (stream 0) in their respective files. The clips play back sequentially (1, 2, and then 3).

Cutlist Objects and Interfaces

Microsoft® DirectShow™ defines the following objects that implement the specified interfaces. Applications use these objects and interfaces to create, manipulate, and play cutlists.
Object | Supported interfaces | Description
CLSID_SimpleCutList | IStandardCutList | Cutlist object
CLSID_VideoFileClip | IFileClip | Cutlist element (individual clip) object for video
CLSID_AudioFileClip | IFileClip | Cutlist element (individual clip) object for audio
CLSID_CutListGraphBuilder | ICutListGraphBuilder | Cutlist graph builder object

These interfaces enable application writers to construct filter graphs without having to worry about the specifics of each cutlist object. They provide a simple way to create and manipulate cutlists, and to create a filter graph to play an edited movie in real time. In addition, a single cutlist filter calls these interfaces — the application must be aware of the different cutlist filters that are installed and generate the proper filter graph.

If you need cutlist functionality that the preceding interfaces don't provide, such as detailed cutlist or cutlist element information, see the following interfaces.

  • IAMAudioCutListElement
  • IAMCutListElement
  • IAMFileCutListElement
  • IAMVideoCutListElement


Using Cutlists

This article summarizes the steps necessary to create and play a cutlist. It also lists the limitations of the current cutlist implementation and provides sample code for using cutlists in an application. See What Are Cutlists? for an introduction to cutlists.

Contents of this article:

  • Cutlist Limitations
  • Creating a Video Cutlist
  • Creating Both Video and Audio Cutlists
  • Cutlist Sample Code (Simplecl)

To use cutlists, you must first explicitly include the cutlist.h header file in your project. Then you can create cutlist objects and use the interfaces they expose. The following list summarizes the steps for creating and playing back cutlists in your application. Creating a Video Cutlist presents the example code from this section as one unit rather than many separate fragments.

  1. Create a standard cutlist object (CLSID_SimpleCutList) for each cutlist. Each cutlist can contain only one media type, so if you want both audio and video you must create one standard cutlist for all of your video clips, and one standard cutlist for all of your audio clips.

CoCreateInstance((REFCLSID)CLSID_SimpleCutList, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IStandardCutList,(void**)&pVCutList);
  2. Create a video file clip object (CLSID_VideoFileClip) or an audio file clip object (CLSID_AudioFileClip), as appropriate, for each stream in each AVI or WAV file you will use as the source for clips. If you want to play back both video and audio from the same file, you must still create separate video and audio file clip objects because the file clip objects are based upon one stream (either a video stream or an audio stream) within a file.

CoCreateInstance((REFCLSID)CLSID_VideoFileClip, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IFileClip, (void**)&pVFileClip);
  3. Tell the file clip object what file and stream in that file to use by calling the IFileClip::SetFileAndStream method as follows. The first video and audio streams (stream 0) are the only streams that DirectShow supports.

hr = pVFileClip->SetFileAndStream(L"jupiter.avi", 0);
  4. Create one or more cutlist elements (individual clips) from each file clip by calling the IFileClip::CreateCut method. Each file clip represents a stream of data, and you can create more than one clip from each data stream. For instance, the example in What Are Cutlists? specifies two elements from Venus.avi, and one element from Mars.avi.
  5. Add each cutlist element to the cutlist by calling the IStandardCutList::AddElement method.

    The following example creates two cutlist elements from the file clip and adds them to the cutlist. The file clip is the first video stream (stream zero) of Jupiter.avi, as specified previously in IFileClip::SetFileAndStream. The first element plays seconds 5 through 10 of Jupiter.avi and the second element plays second 0 through 5 of the same file.

hr = pVFileClip->CreateCut(&pVElement1,5*SCALE,10*SCALE,0,5*SCALE,0);
hr = pVCutList->AddElement(pVElement1,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pVFileClip->CreateCut(&pVElement2,0,5*SCALE,0,5*SCALE,0);
hr = pVCutList->AddElement(pVElement2,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

    The first three parameters of IFileClip::CreateCut are the important ones. The first, ppElement, specifies the element, and is filled in for you. The second (mtTrimIn) and third (mtTrimOut) specify, respectively, the start and stop times for the clip relative to the original file (Jupiter.avi in this case). The last three parameters must always be zero, mtTrimOut minus mtTrimIn, and zero, respectively. A scale value of 10,000,000 scales the start and stop times to seconds.

    The first parameter in the IStandardCutList::AddElement call, pElement, is the element obtained from the call to IFileClip::CreateCut. The last two parameters must be CL_DEFAULT_TIME to indicate that the element should be added to the end of the current cutlist, and its duration is the same as its duration in the original file.

  6. Create a cutlist graph builder object (CLSID_CutListGraphBuilder) and use it to build a filter graph that will play your cutlists. Give it a standard cutlist object by using the ICutListGraphBuilder::AddCutList method, and then call the ICutListGraphBuilder::Render method to build a filter graph that can play the cutlist. The following code fragment illustrates these calls.

CoCreateInstance((REFCLSID)CLSID_CutListGraphBuilder,NULL,CLSCTX_INPROC,

                  (REFIID)IID_ICutListGraphBuilder,(void**)&pGraphBuilder);

.
.
.
// Give the cutlist to the graph builder
hr = pGraphBuilder->AddCutList(pVCutList, NULL);

// Tell the cutlist graph builder to build the graph
hr = pGraphBuilder->Render();
  7. Play the cutlist filter graph and clean up resources as in the following example. Be sure to stop the graph before you remove the cutlist from the graph using ICutListGraphBuilder::RemoveCutList.

// Get the filter graph the builder just made
hr = pGraphBuilder->GetFilterGraph(&pGraph);

// Now get some useful graph interfaces
pGraph->QueryInterface(IID_IMediaControl,(void**)&pControl);
pGraph->QueryInterface(IID_IMediaEvent, (void**)&pEvent);
pGraph->Release();

// Run the graph
pControl->Run();

// Arbitrarily assumes 10000 millisecond timeout
pEvent->WaitForCompletion(10000, &lEventCode);
pControl->Stop();
pEvent->Release();
pControl->Release();

// Cleanup
hr = pGraphBuilder->RemoveCutList(pVCutList);
pVElement1->Release();
pVElement2->Release();
pVCutList->Release();
pVFileClip->Release();
pGraphBuilder->Release();

See the cutlist examples later in this article for more complete sample code illustrating these steps.

Cutlist Limitations

The following list discusses limitations that you should be aware of when using DirectShow's current cutlist implementation.

  1. All clips in a cutlist must be the same format (media type).

    For video cutlists, this means that all the video clips must be of the same compression type, size, dimensions, bit depth, and so forth. In other words, all video clips in the cutlist must be represented by the same BITMAPINFOHEADER structure. For audio cutlists, this means they must all use the same compression format, sampling rate, bit depth, and number of channels. In other words all audio clips in the cutlist must be represented by the same WAVEFORMATEX structure.

    The first clip you add to a cutlist determines the cutlist's media type, and the media type required for all other clips you add to the cutlist. The IStandardCutList::AddElement method returns an invalid media type error (VFW_E_INVALIDMEDIATYPE) if you try to add a clip of a different media type to an existing cutlist.

  2. All cuts must begin on a keyframe. If not, there will be an unwanted "fade in" effect at the cut point, instead of a clean switch from one clip to the next. The biggest limitation is that the first frame of the entire cutlist must be a keyframe. Otherwise, the file will be corrupt if you write the resulting cutlist to a file.
  3. There is no way to save (persist) a cutlist. Every time your application runs, you must build the cutlist by hand. There is no file format for saving a cutlist you have previously constructed.
  4. Audio cuts not made during silence might cause an audible "click" sound at the cut point if there is low to moderate volume and sparse audio at the cut point.
  5. You can only create file clip objects from either the first video or audio stream of an AVI file. Extra streams in files with multiple video or audio streams are ignored.
  6. WAV files and AVI files are the only types of files that you can use as source material for a cutlist. DirectShow doesn't support other formats, such as MPEG.
  7. You can't identify WAV or AVI files used in cutlists by a universal network connection (UNC) network name. For example, the file name "x:\Venus.wav" is valid, but "\\Server\Share\Venus.wav" is not.
  8. Cutlists with audio NULL elements (gaps in the audio track) can't be written correctly to a file or played properly with the audio renderer included with DirectShow. Unless you have custom filters that can handle gaps in the audio stream, do not use audio NULL elements.
  9. Cutlists work only with PCM audio, not compressed audio.
  10. Cutlist support is currently not implemented for RLE compressed files.

Creating a Video Cutlist

The following code creates and plays a cutlist consisting of two video clips from one AVI file. It plays seconds 5 through 10 of the file followed by seconds 0 through 5. The code fragment contains no error checking for the sake of brevity. See Cutlist Sample Code (Simplecl) for an example that performs error checking.

HRESULT              hr;
ICutListGraphBuilder *pGraphBuilder;
IMediaControl        *pControl;
IMediaEvent          *pEvent;
IGraphBuilder        *pGraph;
IStandardCutList     *pVCutList;
IFileClip            *pVFileClip;
IAMCutListElement      *pVElement1, *pVElement2;
LONG                 lEventCode=0L;

CoInitialize(NULL);
// we need these 3 objects
CoCreateInstance((REFCLSID)CLSID_CutListGraphBuilder,NULL,CLSCTX_INPROC,
                  (REFIID)IID_ICutListGraphBuilder,(void**)&pGraphBuilder);
CoCreateInstance((REFCLSID)CLSID_VideoFileClip, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IFileClip, (void**)&pVFileClip);
CoCreateInstance((REFCLSID)CLSID_SimpleCutList, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IStandardCutList,(void**)&pVCutList);

// Tell the clip what file to use as a source file
hr = pVFileClip->SetFileAndStream(L"jupiter.avi", 0);

// Create some cutlist elements and add them to the standard cutlist
// from 5 to 10 seconds, then from 0 to 5 seconds
hr = pVFileClip->CreateCut(&pVElement1,5*SCALE,10*SCALE,0,5*SCALE,0);
hr = pVCutList->AddElement(pVElement1,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pVFileClip->CreateCut(&pVElement2,0,5*SCALE,0,5*SCALE,0);
hr = pVCutList->AddElement(pVElement2,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// Give the cutlist to the graph builder
hr = pGraphBuilder->AddCutList(pVCutList, NULL);

// Tell the cutlist graph builder to build the graph
hr = pGraphBuilder->Render();

// Get the filter graph the builder just made
hr = pGraphBuilder->GetFilterGraph(&pGraph);

// Now get some useful graph interfaces
pGraph->QueryInterface(IID_IMediaControl,(void**)&pControl);
pGraph->QueryInterface(IID_IMediaEvent, (void**)&pEvent);
pGraph->Release();

// Run the graph
pControl->Run();

// Arbitrarily assumes 10000 millisecond timeout
pEvent->WaitForCompletion(10000, &lEventCode);
pControl->Stop();
pEvent->Release();
pControl->Release();

// Cleanup
hr = pGraphBuilder->RemoveCutList(pVCutList);
pVElement1->Release();
pVElement2->Release();
pVCutList->Release();
pVFileClip->Release();
pGraphBuilder->Release();

CoUninitialize();

// Exit
PostMessage(WM_QUIT, 0, 0);

The preceding example uses video only. The example in the next section uses both audio and video.

Creating Both Video and Audio Cutlists

The following code takes a file name from the command line and plays five different pieces of that AVI file back to back, with both sound and video synchronized. The code fragment contains no error checking for the sake of brevity. See Cutlist Sample Code (Simplecl) for an example that performs error checking.

HRESULT              hr;
ICutListGraphBuilder *pGraphBuilder;
IMediaControl        *pControl;
IMediaEvent          *pEvent;
IGraphBuilder        *pGraph;
IStandardCutList     *pVCutList, *pACutList;
IFileClip            *pAFileClip1;
IFileClip            *pVFileClip1;
IAMCutListElement      *pVElement1;
IAMCutListElement      *pVElement2;
IAMCutListElement      *pVElement3;
IAMCutListElement      *pVElement4;
IAMCutListElement      *pVElement5;
IAMCutListElement      *pAElement1;
IAMCutListElement      *pAElement2;
IAMCutListElement      *pAElement3;
IAMCutListElement      *pAElement4;
IAMCutListElement      *pAElement5;
LONG                 lEventCode=0L;
WCHAR                lpwstr[256];

CoInitialize(NULL);

CoCreateInstance((REFCLSID)CLSID_CutListGraphBuilder,NULL,CLSCTX_INPROC,
                  (REFIID)IID_ICutListGraphBuilder,(void**)&pGraphBuilder);

CoCreateInstance((REFCLSID)CLSID_AudioFileClip, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IFileClip, (void**)&pAFileClip1);

CoCreateInstance((REFCLSID)CLSID_VideoFileClip, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IFileClip, (void**)&pVFileClip1);

CoCreateInstance((REFCLSID)CLSID_SimpleCutList, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IStandardCutList,(void**)&pVCutList);
CoCreateInstance((REFCLSID)CLSID_SimpleCutList, NULL, CLSCTX_INPROC,
                  (REFIID)IID_IStandardCutList,(void**)&pACutList);

// Get the Unicode file name to use from the command line
MultiByteToWideChar(CP_ACP, 0, m_lpCmdLine, strlen(m_lpCmdLine)+1,
                     lpwstr, sizeof(lpwstr)/sizeof(*lpwstr));

// tell the clips what file they are reading from
hr = pVFileClip1->SetFileAndStream(lpwstr, 0);
hr = pAFileClip1->SetFileAndStream(lpwstr, 0);

// Create some cuts and add them the cutlist

// from 2 to 6 seconds
hr = pVFileClip1->CreateCut(&pVElement1,2*SCALE,6*SCALE,0,4*SCALE,0);
hr = pVCutList->AddElement(pVElement1,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pAFileClip1->CreateCut(&pAElement1,2*SCALE,6*SCALE,0,4*SCALE,0);
hr = pACutList->AddElement(pAElement1,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// from 20 to 24 seconds
hr = pVFileClip1->CreateCut(&pVElement2,20*SCALE,24*SCALE,0,4*SCALE,0);
hr = pVCutList->AddElement(pVElement2,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pAFileClip1->CreateCut(&pAElement2,20*SCALE,24*SCALE,0,4*SCALE,0);
hr = pACutList->AddElement(pAElement2,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// from 65 to 69 seconds
hr = pVFileClip1->CreateCut(&pVElement3,65*SCALE,69*SCALE,0,4*SCALE,0);
hr = pVCutList->AddElement(pVElement3,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pAFileClip1->CreateCut(&pAElement3,65*SCALE,69*SCALE,0,4*SCALE,0);
hr = pACutList->AddElement(pAElement3,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// from 35 to 39 seconds
hr = pVFileClip1->CreateCut(&pVElement4,35*SCALE,39*SCALE,0,4*SCALE,0);
hr = pVCutList->AddElement(pVElement4,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pAFileClip1->CreateCut(&pAElement4,35*SCALE,39*SCALE,0,4*SCALE,0);
hr = pACutList->AddElement(pAElement4,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// from 12 to 16 seconds
hr = pVFileClip1->CreateCut(&pVElement5,12*SCALE,16*SCALE,0,4*SCALE,0);
hr = pVCutList->AddElement(pVElement5,CL_DEFAULT_TIME,CL_DEFAULT_TIME);
hr = pAFileClip1->CreateCut(&pAElement5,12*SCALE,16*SCALE,0,4*SCALE,0);
hr = pACutList->AddElement(pAElement5,CL_DEFAULT_TIME,CL_DEFAULT_TIME);

// Add the cutlists to the graph
hr = pGraphBuilder->AddCutList(pVCutList, NULL);
hr = pGraphBuilder->AddCutList(pACutList, NULL);

// Tell the cutlist graph builder to build the graph
hr = pGraphBuilder->Render();

// Get the filter graph the builder just made
hr = pGraphBuilder->GetFilterGraph(&pGraph);

// Now get some useful graph interfaces
pGraph->QueryInterface(IID_IMediaControl,(void**)&pControl);
pGraph->QueryInterface(IID_IMediaEvent, (void**)&pEvent);
pGraph->Release();

// Run the graph
pControl->Run();

// Arbitrarily assumes 10000 millisecond timeout
pEvent->WaitForCompletion(10000, &lEventCode);

pControl->Stop();

pEvent->Release();
pControl->Release();

// cleanup

// Remove the cutlist from the graph
hr = pGraphBuilder->RemoveCutList(pVCutList);
hr = pGraphBuilder->RemoveCutList(pACutList);

pVElement1->Release();
pVElement2->Release();
pVElement3->Release();
pVElement4->Release();
pVElement5->Release();
pAElement1->Release();
pAElement2->Release();
pAElement3->Release();
pAElement4->Release();
pAElement5->Release();

pACutList->Release();
pVCutList->Release();

pAFileClip1->Release();
pVFileClip1->Release();

pGraphBuilder->Release();

CoUninitialize();

// Exit
PostMessage(WM_QUIT, 0, 0);

The preceding example obtains video and audio clips from the same file. The next example adds a user interface and error checking, and it is available in the DirectShow SDK.

Cutlist Sample Code (Simplecl)

The Simplecl Sample (Cutlist Application) (Simplecl) from the DirectShow SDK demonstrates how to create and play back cutlists. By default, the DirectShow setup program installs Simplecl in the DXMedia\Samples\DS\cutlist\simplecl directory. Simplecl provides a File Open dialog box from which the user can chose a file to add to a cutlist. For each file, the user specifies a starting (trimin) position for the clip and an ending (trimout) position for the clip. For every AVI file specified, the sample tries to add the first video stream and the first audio stream to its respective cutlist. The user must add at least two files, and then can run the filter graph and see the clips played sequentially.

The DirectShow SDK also includes a sample that reads a list of cuts from a text file and plays them, much like Simplecl does. That sample, Cltext, is installed in the DXMedia\Samples\DS\cutlist\cltext directory by default.

The following code excerpts are from the Simplecl.h and Simplecl.cpp sample files. The sample includes error checking.

Simplecl.h declares a few global variables, including a ClipDetails structure to manage the user's file and clip start and stop time choices, and a ClipCollection structure to group the clip details. It also defines a SCALE constant to scale all user-specified times in one-second increments. The HELPER_RELEASE macro releases objects only if they exist, and then sets the object pointer to NULL to guard against releasing the same object multiple times. The following example contains fragments from Simplecl.h.

#define MAX_CLIPS 150
#define SCALE 10000000   // scale for 1 second of reference time

// Clip (element) details
struct ClipDetails
  {
    TCHAR szFilename[MAX_PATH];   // name of file containing clip
    REFERENCE_TIME start;         // Start (Trim In) position of clip within file
    REFERENCE_TIME stop;          // Stop (Trim Out) position of clip within file
  };

// Cutlist is a collection of clips (elements)
struct ClipCollection
  {
    int nNumClips;
    ClipDetails List[MAX_CLIPS];
  };

#define HELPER_RELEASE(x) { if (x) x->Release(); x = NULL; }

ClipCollection  gTheSet;            // Cutlist

The application initializes the user input structure as follows:

// ... in WinMain ...
ZeroMemory(&gTheSet, sizeof gTheSet);

Simplecl keeps track of the name of the media file that the user chooses as the source of a clip, tracks the number of files chosen, and displays a dialog box for the user to enter the start and stop times for each clip. The following code fragments relate to tracking the user input for clips:

// ... in WndMainProc ...

case IDM_ADDFILE:

  if (GetClipFileName(gTheSet.List[gTheSet.nNumClips].szFilename))

    { // Add file

      TCHAR szTitleBar[200];

      DialogBox(ghInst, MAKEINTRESOURCE(wDlgRes = IDD_MEDIATIMES),
                                        ghApp, (DLGPROC)DialogProc);
      gTheSet.nNumClips = gTheSet.nNumClips + 1;
      wsprintf(szTitleBar, "SimpleCutList - %d clips(s) added.",
               gTheSet.nNumClips);
      SetWindowText(ghApp, szTitleBar);

    } // Add file

.
.
.
// ... in DialogProc ...
case IDOKTIMES:

  gTheList.List[gTheSet.nNumClips].start = GetDlgItemInt(h,
                                           IDC_TRIMIN2, NULL, FALSE);
  gTheList.List[gTheSet.nNumClips].stop = GetDlgItemInt(h,
                                          IDC_TRIMOUT2, NULL, FALSE);

  EndDialog(h,1);
  break;

The real work of the Simplecl sample is in the SimpleCutList function. If the user has chosen more than one clip, and then chooses Run from the Cutlist menu, then Simplecl builds and plays the cutlist. The following code checks the number of clips chosen, and calls SimpleCutList if more than one clip was chosen.

case IDM_RUN:
  if (gTheSet.nNumClips > 1)
    SimpleCutList();
  else
    DialogBox(ghInst, MAKEINTRESOURCE(wDlgRes = IDD_LESSTHAN2),
              ghApp, (DLGPROC)DialogProc);
  break;

After the user has entered the file and clip choices, the SimpleCutList function creates and plays the cutlist as follows:

  void SimpleCutList ()

    { // SimpleCutList //

      WCHAR wFile[MAX_PATH];  // File name

      // Initialize video and audio file clips and elements to NULL
      // so we can easily free objects later.
      for (int x = 0; x < MAX_CLIPS; ++x)

        {
          pVidFileClip[x] = NULL;
          pAudFileClip[x] = NULL;
            pVidCLElem[x] = NULL;
            pAudCLElem[x] = NULL;
        };

      // Create cutlist graph builder object
      hr = CoCreateInstance(CLSID_CutListGraphBuilder, NULL,
                            CLSCTX_INPROC, IID_ICutListGraphBuilder,
                            (void**)&pCLGraphBuilder);

      if (FAILED(hr))
        { // CoCreateInstance of CutListGraphBuiler failed
          MessageBox(ghApp,
                     "CoCreateInstance of CutListGraphBuiler failed",
                     APPLICATIONNAME, MB_OK);
          TearDownTheGraph();
          return;
        } // CoCreateInstance of CutListGraphBuiler failed

      // Create simple (standard) cutlist object for video
      hr = CoCreateInstance(CLSID_SimpleCutList, NULL,
                            CLSCTX_INPROC, IID_IStandardCutList,
                            (void**)&pVideoCL);

      if (FAILED(hr))
        { // CoCreateInstance of video SimpleCutList failed
          MessageBox(ghApp,
                     "CoCreateInstance of video SimpleCutList failed",
                     APPLICATIONNAME, MB_OK);
          TearDownTheGraph();
          return;
        } // CoCreateInstance of video SimpleCutList failed

      // Create simple (standard) cutlist object for audio
      hr = CoCreateInstance(CLSID_SimpleCutList, NULL,
                            CLSCTX_INPROC, IID_IStandardCutList,
                            (void**)&pAudioCL);

      if (FAILED(hr))
        { // CoCreateInstance of audio SimpleCutList failed
          MessageBox(ghApp,
                     "CoCreateInstance of audio SimpleCutList failed",
                     APPLICATIONNAME, MB_OK);
          TearDownTheGraph();
          return;
        } // CoCreateInstance of audio SimpleCutList failed

      // Create the individual clips and add them to the cutlist
      nVidElems = nAudElems = 0;
      for (x = 0; x < gTheSet.nNumClips; ++x)

        { // Individual clips

          MultiByteToWideChar(CP_ACP, 0,
                              gTheSet.List[x].szFilename,
                              -1, wFile, MAX_PATH );

          // Create a video clip object and give it the file and stream
          // to read from.
          // SetFileAndStream will fail if we call it from a video clip
          // object and the clip is not a video clip.
          hr = CoCreateInstance(CLSID_VideoFileClip, NULL,
                                CLSCTX_INPROC, IID_IFileClip,
                                (void**)&pVidFileClip[nVidElems]);

          hr = pVidFileClip[nVidElems]->SetFileAndStream(wFile, 0);

          if (SUCCEEDED(hr))

            { // Create video cut and add the clip (element) to the cutlist

              hr = pVidFileClip[nVidElems]->CreateCut(&pVidCLElem[nVidElems],
                      gTheSet.List[x].start*SCALE,
                      gTheSet.List[x].stop*SCALE,
                      0,
                      (gTheSet.List[x].stop-gTheSet.List[x].start)*SCALE,
                      0);

              if (SUCCEEDED(hr))

                { // Add the element to the cutlist

                  hr = pVideoCL->AddElement(pVidCLElem[nVidElems], CL_DEFAULT_TIME, CL_DEFAULT_TIME);

                  if (SUCCEEDED(hr))
                    ++nVidElems;

                  else

                    { // AddElement failed so release associated objects

                      HELPER_RELEASE(pVidCLElem[nVidElems]);
                      HELPER_RELEASE(pVidFileClip[nVidElems]);
                      MessageBox(ghApp, "AddElement (video) failed!", APPLICATIONNAME, MB_OK);

                    } // AddElement failed so release associated objects
                } // Add the element to the cutlist

              else MessageBox(ghApp, "CreateCut (video) failed!", APPLICATIONNAME, MB_OK);

            } // Create video cut

          else

            { // Problems creating video stream

              HELPER_RELEASE(pVidFileClip[nVidElems]);
              MessageBox(ghApp, "SetFileAndStream (video) failed!", APPLICATIONNAME, MB_OK);

            } // Problems creating video stream

          // Create an audio clip object and give it the file and stream
          // to read from.
          // SetFileAndStream will fail if we call it from an audio clip
          // object and the clip is not an audio clip
          hr = CoCreateInstance(CLSID_AudioFileClip, NULL,
                                CLSCTX_INPROC, IID_IFileClip,
                                (void**)&pAudFileClip[nAudElems]);

          hr = pAudFileClip[nAudElems]->SetFileAndStream(wFile, 0);

          if (SUCCEEDED(hr))

            { // Create audio cut and add the clip (element) to the cutlist

              hr = pAudFileClip[nAudElems]->CreateCut(&pAudCLElem[nAudElems],
                      gTheSet.List[x].start*SCALE,
                      gTheSet.List[x].stop*SCALE,
                      0,
                      (gTheSet.List[x].stop-gTheSet.List[x].start)*SCALE,
                      0);

              if (SUCCEEDED(hr))

                { // Add the element to the cutlist

                  hr = pAudioCL->AddElement(pAudCLElem[nAudElems],
                                            CL_DEFAULT_TIME,
                                            CL_DEFAULT_TIME);

                  if (SUCCEEDED(hr))
                    ++nAudElems;

                  else

                   { // AddElement failed so release associated objects

                      HELPER_RELEASE(pAudCLElem[nAudElems]);
                      HELPER_RELEASE(pAudFileClip[nAudElems]);
                      MessageBox(ghApp, "AddElement (audio) failed!", APPLICATIONNAME, MB_OK);

                    } // AddElement failed so release associated objects

                } // Add the element to the cutlist

              else MessageBox(ghApp, "CreateCut (audio) failed!", APPLICATIONNAME, MB_OK);

            } // Create audio cut

          // Problems creating audio stream
          else

            { // Problems creating audio stream

              HELPER_RELEASE(pAudFileClip[nAudElems]);
              MessageBox(ghApp, "SetFileAndStream (audio) failed!", APPLICATIONNAME, MB_OK);

            } // Problems creating audio stream

        } // Individual clips

      // Add the video cutlist to the filter graph
      hr = pCLGraphBuilder->AddCutList(pVideoCL, NULL);

      if (FAILED(hr)) // AddCutList (video) failed
          MessageBox(ghApp, "AddCutList (video) failed", APPLICATIONNAME, MB_OK);

      // Add the audio cutlist to the filter graph
      hr = pCLGraphBuilder->AddCutList(pAudioCL, NULL);

      if (FAILED(hr)) // AddCutList (audio) failed
          MessageBox(ghApp, "AddCutList (audio) failed", APPLICATIONNAME, MB_OK);

      if ((!pVideoCL) && (!pAudioCL))

        { // Clean up

          TearDownTheGraph();
          return;

        } // Clean up

      // Let the filter graph manager construct the appropriate graph
      // automatically
      hr = pCLGraphBuilder->Render();

      if (FAILED(hr))
        { // Problems rendering the graph
          if (!AMGetErrorText(hr, gszScratch, 2048))
            MessageBox(ghApp, "Problems rendering the graph!", APPLICATIONNAME, MB_OK);
          else
            MessageBox(ghApp, gszScratch, APPLICATIONNAME, MB_OK);
          TearDownTheGraph();
          return;
        } // Problems rendering the graph

      // Retrieve the filter graph and useful interfaces
      hr = pCLGraphBuilder->GetFilterGraph(&pigb);

      if (FAILED(hr))
        { // Problems retrieving the graph pointer
          if (!AMGetErrorText(hr, gszScratch, 2048))
            MessageBox(ghApp, "Problems retrieving the graph pointer!", APPLICATIONNAME, MB_OK);
          else
            MessageBox(ghApp, gszScratch, APPLICATIONNAME, MB_OK);
          TearDownTheGraph();
          return;
        } // Problems retrieving the graph pointer

      // QueryInterface for some basic interfaces
      pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);
      pigb->QueryInterface(IID_IMediaEventEx, (void **)&pimex);
      pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);

      // Decrement the ref count on the filter graph
      pigb->Release();

      // Prepare to play in the main application window's client area

      RECT rc;
      GetClientRect(ghApp, &rc);
      hr = pivw->put_Owner((OAHWND)ghApp);
      hr = pivw->put_WindowStyle(WS_CHILD|WS_CLIPSIBLINGS);
      hr = pivw->SetWindowPosition(rc.left, rc.top, rc.right, rc.bottom);

      // Have the graph signal event via window callbacks for performance
      pimex->SetNotifyWindow((OAHWND)ghApp, WM_GRAPHNOTIFY, 0);

      // Run the graph if RenderFile succeeded
      pimc->Run();

    } // SimpleCutList //

Simplecl's TearDownTheGraph function releases all objects and cleans up as follows.

 void TearDownTheGraph (void)

    { // TearDownTheGraph //

      if (pimc)
        pimc->Stop();

      if (pivw)

        { // Hide the playback window first thing

          pivw->put_Visible(OAFALSE);
          pivw->put_Owner(NULL);

        } //

      HELPER_RELEASE(pimex);
      HELPER_RELEASE(pimc);
      HELPER_RELEASE(pivw);

      // Remove the video cutlist from the filter graph to free resources
      if (pCLGraphBuilder && pVideoCL)
        pCLGraphBuilder->RemoveCutList(pVideoCL);

      // Remove the audio cutlist from the filter graph to free resources
      if (pCLGraphBuilder && pAudioCL)
        pCLGraphBuilder->RemoveCutList(pAudioCL);

      for (int x = 0; x < nAudElems; ++x)

        { // Release audio objects

          HELPER_RELEASE(pAudCLElem[x]);
          HELPER_RELEASE(pAudFileClip[x]);

        } // Release audio objects

      for (x = 0; x < nVidElems; ++x)

        { // Release video objects

          HELPER_RELEASE(pVidCLElem[x]);
          HELPER_RELEASE(pVidFileClip[x]);

        } // Release video objects

      HELPER_RELEASE(pVideoCL);
      HELPER_RELEASE(pAudioCL);
      HELPER_RELEASE(pCLGraphBuilder);

    } // TearDownTheGraph //


DVD for Title Vendors

DVD-Video discs typically contain programs such as feature films, interactive games, or video reference materials like encyclopedias. The end user can play back those programs on a DVD-Video player or on a DVD-ROM-equipped computer. Some of the features of DVD-Video include support for multiple languages, parental control, different camera angles, and closed captioning.

This article discusses the unique features of DVD that are not available in pure MPEG-2 (its parent format) and outlines the interfaces and methods DirectShow provides in support of those features.

DVD-unique features include the following:

  • Better seeking
  • Subpictures
  • Multiple language support
  • Variable speed play (forward/backward scan)
  • Consumer DVD interactivity
  • Seamless video angle change
  • Parental control

Title vendors can create feature-rich applications by taking advantage of these DVD-Video features.

Note This release of DirectShow supports DVD-Video. It does not support pure MPEG-2.

See Additional DVD Resources on the Web for a list of DVD resources on the Web.

Contents of this article:

  • DVD Interfaces
  • DVD Control Data Structure
  • DVD Features
    • Seeking in DVD
    • Subpicture
    • Multiple Language Support
    • Variable Speed Play
    • Consumer DVD Interactivity
    • Seamless Video Angle Change
    • Parental Control
  • Additional DVD Resources on the Web

DVD Interfaces

DirectShow provides the following DVD-related interfaces.
Interface | Purpose
IDvdGraphBuilder | Allows the DVD application writer to easily build a filter graph for DVD-Video playback.
IDvdControl | Controls the playback and search mechanisms of a DVD-Video disc that contains one or more video movies.
IDvdInfo | Allows an application to query for attributes of available DVD-Video titles and the DVD player status. It also allows for control of a DVD player beyond Annex J in the DVD specification.

Later sections of this article group methods from these interfaces into functional categories.

DirectShow also provides a number of events. See DVD Events for more information.

DVD Control Data Structure

DVD-Video contains a nested hierarchy that provides search capabilities at several levels in the DVD data. This nested "control data" points to the real video and audio data. The following table outlines the structure of the control data for a DVD-Video volume. Each DVD volume can contain from one to 99 video title sets, which can contain one or more titles, which can contain one or more program chains. This nested structure continues to the smallest unit, which is the "pack." DirectShow provides seeking capabilities for DVD at three distinct levels, as outlined in Seeking in DVD.

DVD-Video Volume Structure
Control Data | Description
Video Title Set (VTS) | Collection of movies. A single volume can contain one to 99 video title sets.
Title | Individual movie. This may be a simple linear movie, consisting of one program chain, or it might consist of several program chains.
Program Chain (PGC) | A collection of programs (often chapters in a movie).
Chapter/Part of Title (PTT) | Collection of programs. Can delimit scenes or provide optional scenes from which to choose. Possible options include different ratings, camera angles, or a different storyline.
Program (PG) | Collection of cells, which normally make up a scene.
Cell | Collection of Video Object Units. Typically all the video and audio data from a certain number of Video Object Units.
Cell-Part | Stream of data (multi-angle only).
Video Object Unit (VOBU) | Usually half a second of video.
Pack | 2KB of data, consisting of only one media type (such as video or audio).

Pure MPEG-2 supports only the title and pack from the list above.

DVD Features

This section outlines features specific to DVD-Video and lists the DirectShow methods that provide these features.

Seeking in DVD

DirectShow enables you to seek at several different levels within the DVD content. Because pure MPEG-2 supports only title and pack control data, it does not provide the flexibility in seeking that DVD does.

The following table shows the DirectShow DVD methods for seeking at various levels.
Seeking level | Control data | IDvdControl methods
Title Seeks | Video Title Set (VTS), Title, Program Chain (PGC) | TitlePlay
Chapter Seeks | Chapter/Part of Title (PTT), Program (PG), Cell | ChapterPlay (specifying title and chapter number), ChapterSearch (search for a chapter within the same title), PrevPGSearch, TopPGSearch, NextPGSearch
Time Seeks | Cell-Part, Video Object Unit (VOBU), Pack | TimePlay (start playing specified title from specified time), TimeSearch (start playing from specified time within the same title)

Subpicture

Subpicture is an extra media type that is decoded and alpha blended. The data on the alpha channel could be text for closed-captioning, buttons to provide a user interface, menus, subtitles, credits, and so on.

Methods relating to subpicture include the following:

  • IDvdControl::SubpictureStreamChange
  • IDvdInfo::GetCurrentSubpicture
  • IDvdInfo::GetSubpictureLanguage
  • IDvdInfo::GetCurrentSubpictureAttributes

Multiple Language Support

DVD-Video provides support of up to eight audio tracks to accommodate various languages. It also supports text in different languages for statistics related to the DVD title such as cast, crew, or title.

Methods relating to language support include the following:

  • IDvdControl::MenuLanguageSelect
  • IDvdInfo::GetAudioLanguage
  • IDvdInfo::GetSubpictureLanguage

Variable Speed Play

DirectShow provides variable speed play through the IDvdControl::ForwardScan and IDvdControl::BackwardScan methods:

Consumer DVD Interactivity

The consumer of a DVD title can interact with the title by selecting and activating buttons, displaying menus, and using the mouse to select and activate buttons.

Methods relating to consumer interactivity include the following:

  • IDvdControl::MenuCall
  • IDvdControl::UpperButtonSelect
  • IDvdControl::LowerButtonSelect
  • IDvdControl::LeftButtonSelect
  • IDvdControl::RightButtonSelect
  • IDvdControl::ButtonActivate
  • IDvdControl::ButtonSelectAndActivate
  • IDvdControl::MouseActivate
  • IDvdControl::MouseSelect
  • IDvdInfo::GetCurrentButton

Seamless Video Angle Change

DVD-Video supports up to nine camera angles. These angles can be completely independent video streams, or different camera angles of the same scene. The fast seeking of the DVD disc allows switching angles seamlessly.

Methods relating to video angles include IDvdControl::AngleChange and IDvdInfo::GetCurrentAngle.

Parental Control

Parental control provides security for parents who want to prevent children from viewing certain types of content. Content might be authored at a particular level, or might contain the same scene shot at different rating levels to provide a viewing alternative for children.

Methods relating to parental control include the following:

  • IDvdControl::ParentalLevelSelect
  • IDvdControl::ParentalCountrySelect
  • IDvdInfo::GetPlayerParentalLevel
  • IDvdInfo::GetTitleParentalLevels

Additional DVD Resources on the Web

The following list contains links to a few of the Web sites that provide DVD information. Search the Web for other DVD resources. Note that most of these external links point to servers that are not under Microsoft's control. Please read Microsoft's official statement regarding other servers.

  • http: //www.microsoft.com/hwdev/devdes/dvdwp.htm contains a whitepaper titled "DVD and Microsoft Operating Systems" which outlines the planned support for DVD under future Windows operating systems.
  • external link http://www.unik.no/~robert/hifi/dvd/ includes links to many other DVD sites, news stories, and other resources.
  • external link http://reality.sgi.com/nemec/dvd.html contains notes from a DVD technical forum.
  • external link http://www.c-cube.com/technology/dvd.html contains a whitepaper on DVD.
  • external link http://www.icdia.org/dvdfaq02.html contains a DVD frequently asked questions list.
  • external link http://www.videodiscovery.com/vdyweb/dvd/dvdfaq.html contains a DVD frequently asked questions list which is also available from alt.video.dvd Usenet newsgroup.


Filter Developer's Guide

If you are developing a filter for use in a DirectShow filter graph, read the articles in this section.

How to...

Stream Architecture

Plug-in Distributors

DirectShow and COM

File Formats

Transform Filters

About Effect Filters

Video Renderers

Source and Target Rectangles in Video Renderers

Exposing Capture and Compression Formats


How to...

This section gives step-by-step procedures for writing and using different kinds of filters, including a video capture filter, an audio capture filter, and a transform filter.

Write a Video Capture Filter

Write an Audio Capture Filter

Write a Transform Filter in C/C++


Write a Video Capture Filter

This article outlines important points to consider when writing a video capture filter. The Microsoft® DirectShow™ SDK includes a standard VFW Video Capture filter.

Contents of this article:

  • Capture and Preview Pin Requirements
  • Optimizing Capture Versus Preview (Optional)
  • Registering a Video Capture Filter
  • Producing Data
  • Controlling Individual Streams
  • Time Stamping
  • Frame Rates
  • Necessary Interfaces

Capture and Preview Pin Requirements

The capture pin and preview pin (if there is one) of the capture filter must support the IKsPropertySet interface. Applications call this interface to ask "what category of pin are you?" by getting the AMPROPERTY_PIN_CATEGORY value of the AMPROPSETID_Pin property set. The value you return is typically either the PIN_CATEGORY_CAPTURE or PIN_CATEGORY_PREVIEW GUID. (See Pin Property Set for a complete list of pin categories.) A capture filter must support IKsPropertySet or an application can't tell how to connect the filter in a filter graph.

You can name the pin anything you want and you can have other output pins for any additional purposes that you want. If your pin name begins with the tilde (~) character, the filter graph will not automatically render that pin when an application calls IGraphBuilder::RenderFile. For instance, if you have a capture filter with both a capture pin and a preview pin, you might want to name the capture pin "~capture" and the preview pin "preview." Given those names, if an application renders that filter in a graph, the preview pin will be connected to a video renderer, and nothing will be connected to the capture filter, which is probably what you want to happen by default. This can also apply to pins that are just informational and are not meant to be rendered, or need to be enumerated so that their properties can be set.

The tilde (~) prefix only affects the behavior of RenderFile and intelligent connect (IGraphBuilder::Connect). Note that intelligent connect can still be used to connect pins with this property if they implement the IPin::Connect method. However, output pins of intermediate filters which are being used to complete the connection which have the tilde at the start of their name will not be connected as part of the intelligent connection attempt.

See Audio Capture Pin Requirements for more details about audio capture filters.

The following sample code demonstrates how to implement IKsPropertySet on a capture pin.

//
// PIN CATEGORIES - let the world know that we are a CAPTURE pin
//

HRESULT CMyCapturePin::Set(REFGUID guidPropSet, DWORD dwPropID, LPVOID pInstanceData, DWORD cbInstanceData, LPVOID pPropData, DWORD cbPropData)
{
    return E_NOTIMPL;
}

// To get a property, the caller allocates a buffer which the called
// function fills in. To determine necessary buffer size, call Get with
// pPropData=NULL and cbPropData=0.
HRESULT CMyCapturePin::Get(REFGUID guidPropSet, DWORD dwPropID, LPVOID pInstanceData, DWORD cbInstanceData, LPVOID pPropData, DWORD cbPropData, DWORD *pcbReturned)
{
    if (guidPropSet != AMPROPSETID_Pin)
    return E_PROP_SET_UNSUPPORTED;

    if (dwPropID != AMPROPERTY_PIN_CATEGORY)
    return E_PROP_ID_UNSUPPORTED;

    if (pPropData == NULL && pcbReturned == NULL)
    return E_POINTER;

    if (pcbReturned)
    *pcbReturned = sizeof(GUID);

    if (pPropData == NULL)
    return S_OK;

    if (cbPropData < sizeof(GUID))
    return E_UNEXPECTED;

    *(GUID *)pPropData = PIN_CATEGORY_CAPTURE;
    return S_OK;
}

// QuerySupported must either return E_NOTIMPL or correctly indicate
// if getting or setting the property set and property is supported.
// S_OK indicates the property set and property ID combination is
HRESULT CMyCapturePin::QuerySupported(REFGUID guidPropSet, DWORD dwPropID, DWORD *pTypeSupport)
{
    if (guidPropSet != AMPROPSETID_Pin)
    return E_PROP_SET_UNSUPPORTED;

    if (dwPropID != AMPROPERTY_PIN_CATEGORY)
    return E_PROP_ID_UNSUPPORTED;

    if (pTypeSupport)
    *pTypeSupport = KSPROPERTY_SUPPORT_GET;
    return S_OK;
}

Optimizing Capture Versus Preview (Optional)

When your filter is running and capturing data, you must send a copy of the frame from your preview pin as well as from your capture pin. If you can do hardware-assisted preview — through an overlay, for example — and if you have a preview pin, you can use the IOverlay interface transport for your preview pin instead of the IMemInputPin interface. Using IOverlay is optional. If you can't do hardware-assisted preview, only send a frame out the preview pin if you have some spare time. Don't do it if it will make you drop any frames — the capture pin has priority.

For example, you might deliver a frame from the preview pin only if you have nothing to send from the capture pin right now and the downstream filter has released all buffers previously delivered from the capture pin.

If you can capture only one format of data, and the preview and capture pins must therefore produce the same media type, or if you want information about how to properly reconnect pins, read on. Otherwise, skip this section.

Send data of the same format from the preview and capture pins. If the filter graph manager reconnects your capture pin with a different format, you must reconnect your preview pin with the same format to make it work. If your capture pin is connected but your preview pin is not, you must allow only your preview pin to connect with the same media type as the capture pin. They must match.

The following sample code shows how the reconnection should work.

// The capture pin cannot accept a media type if the preview pin is connected to a filter
// that won't accept the new media type. The preview pin must always output the same type as
// the capture pin.
//
CCapturePin::CheckMediaType(CMediaType *pmt)
{
    if (m_pMyPreviewPin->IsConnected()) {
        // Does the preview pin's connection like this type?
          if (m_pMyPreviewPin->GetConnected()->QueryAccept(pmt) != NOERROR) {
            // Sorry, the preview pin can't reconnect with this new type.
            return E_INVALIDARG;
        }
    }

    // You decide if you like this media type or not, maybe by
    // knowing what the capture pin will connect with. But don't
    // worry; when the capture pin is connected, you will be
    // reconnected to use the same format.

    return NOERROR;
}

// The preview pin can only accept the media type that the capture pin is using.
//
CPreviewPin::CheckMediaType(CMediaType *pmt)
{
    CMediaType cmt = m_pMyCapturePin->m_mt;
     if (m_pMyCapturePin->IsConnected() && *pmt != cmt)
        // Sorry, the preview pin is only allowed to connect with
        // the same format as the capture pin.
        return E_INVALIDARG;

    else if (!m_pMyCapturePin->IsConnected())
        // You decide if you like this media type or not, maybe by
        // knowing what the capture pin will connect with. But don't
        // worry; when the capture pin is connected, you will be
        // reconnected to use the same format.

    // If the capture pin is connected, and this is the same media type,
    // you are OK.
    return NOERROR;
}

// The capture pin is being told to use a certain media type. Now the preview pin
// must be made to use that same mediatype.
//
CCapturePin::SetMediaType(CMediaType *pmt);
{
    if (m_pMyPreviewPin->IsConnected()) {

    // You need to reconnect the preview pin with this media type.
      if (m_pMyPreviewPin->GetConnected()->QueryAccept(pmt) == NOERROR) {

        // The other filter that the preview pin is connected to
        // can accept this new media type, so simply reconnect.
        m_pFilter->m_pGraph->Reconnect(m_pMyPreviewPin);
    }
    }
}

Registering a Video Capture Filter

You must register your filter in the video capture filter category. See AMovieDllRegisterServer2 for more information.

Producing Data

Produce data on capture and preview pins only when the filter graph is in a running state. You do not send data from your pins when the filter graph is paused. This will confuse the filter graph unless you return VFW_S_CANT_CUE from the CBaseFilter::GetState function, warning the filter graph that you do not send data when paused. The following code shows you what to do.

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
    *State = m_State;
    if (m_State == State_Paused)
        return VFW_S_CANT_CUE;
    else
        return S_OK;
}

Controlling Individual Streams

All output pins should support the IAMStreamControl interface, so an application can turn each pin on or off individually (for instance, to preview without capturing). IAMStreamControl enables you to switch between preview and capture without rebuilding a different graph.

Time Stamping

When you capture a frame and are sending it, time stamp the frame with the time the graph's clock says it is when the frame is captured. The end time is the start time plus the duration. For example, if you are capturing at 10 frames per second, and the graph's clock says 200,000,000 units at the time the frame is captured, the sample is stamped (200000000, 201000000) (there are 10,000,000 units per second).

A preview frame should have no time stamp because of latency problems. The latency is due to the fact that, if the time of the sample is the graph's time when it leaves the preview pin, by the time the sample gets to the renderer, it will be late. Therefore the renderer may choose not to draw the sample in order to save time and "catch up", which can't happen for a live stream. Implementing IAMStreamControl requires time stamps, so you can choose not to implement stream control on the preview pin, only time stamp the preview pin sample when there are outstanding requests to start or stop, or live with the latency problem. See the source code for the VidCap Sample (Video Capture Filter) sample for details.

You should set the media time of the sample you deliver; also set the regular time stamp for your capture pin. The media time is the frame number of the sample. For example, if you are capturing and sending frames and frame 3 gets dropped, you would set the media time values to be (0,1) (1,2) (2,3) (4,5) (5,6) and so on. This informs the downstream filters if any video frames were dropped even when the regular time stamps are a little random because the clock being used is not the video digitizing clock.

Also, if you are in a running state, and then pause, and then run again, you must not send a sample with a time stamp less than the last one you sent before pausing. Time stamps can never go back in time, not even back to before a pause occurred.

Frame Rates

The frame rate at which your filter should produce data is determined by the AvgTimePerFrame field of the VIDEOINFOHEADER of the media type your output pin is connected with. You may not be able to capture at any arbitrary frame rate, but only certain rates. If your pin is connected with a media type that asks for a frame rate you can't provide, you should provide frames at the next lowest frame rate possible. For instance, if your media type has AvgTimePerFrame=333333 (approx 1/30 of a second, meaning 30 frames per second), and you can only capture 29.97 or 35 frames per second, you should provide frames at 29.97 frames per second, since that is the closest value lower than 30 that you can provide. You can provide a higher frame rate than asked if the frame rate you provide does not create frame durations more than 1 microsecond shorter than requested, since the AvgTimePerFrame may simply have rounding errors. If the AvgTimePerFrame field is 0, you can supply frames at any default frame rate that you like.

Necessary Interfaces

Read about the following interfaces and consider implementing them. You should implement these interfaces to provide functionality that applications might rely on, so these interfaces are strongly recommended.

  • Implement IAMDroppedFrames on your filter or on each output pin that sends data.
  • Implement IAMStreamConfig on each output pin that sends video data.
  • Implement IAMStreamControl on each output pin that sends data.
  • Implement IAMVideoCompression on each output pin that sends video data.


Write an Audio Capture Filter

This article outlines important points to consider when writing an audio capture filter. The Microsoft® DirectShow™ SDK includes a standard Audio Capture filter.

Contents of this article:

  • Audio Capture Pin Requirements
  • Registering an Audio Capture Filter
  • Producing Data
  • Controlling Individual Streams
  • Time Stamping
  • Necessary Interfaces

Audio Capture Pin Requirements

The capture filter's capture pin and preview pin (if there is one) must support the IKsPropertySet interface. See Capture and Preview Pin Requirements for more details and sample code for implementing IKsPropertySet on your capture pin.

You must have one input pin for every sound source the capture card can mix before it digitizes the audio. For instance, if your sound card has a line in, microphone in, and CD-ROM input, you would have three input pins. You don't typically connect these input pins to any other filters — you just support the IAMAudioInputMixer interface on each pin and an application will set recording levels, balance, treble, and so on, on each pin using that interface.

Registering an Audio Capture Filter

You must register your filter in the audio capture filter category. See the AMovieDllRegisterServer2 function for more information.

Producing Data

Produce data on the capture pin only when the filter graph is in a running state. Do not send data from your pins when the filter graph is paused. This will confuse the filter graph unless you return VFW_S_CANT_CUE from the CBaseFilter::GetState function, which warns the filter graph that you do not send data when paused. The following code sample shows how to do this.

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
    *State = m_State;
    if (m_State == State_Paused)
        return VFW_S_CANT_CUE;
    else
        return S_OK;
}

Controlling Individual Streams

All output pins should support the IAMStreamControl interface, so an application can turn each pin on or off individually (for instance, to preview without capturing). IAMStreamControl enables you to switch between preview and capture without rebuilding a different graph. See the source code for the VidCap Sample (Video Capture Filter) sample for details.

Time Stamping

When you send captured audio samples, the starting time stamp for each group equals the start time of the graph's clock when the first sample in the packet was captured. The ending time stamp equals the start time plus the duration that the audio packet represents. If your audio capture filter is not providing the clock, the time stamps won't match up exactly (where the end of one package is the same as the beginning time stamp of the next package), but that's okay. See Write a Video Capture Filter and the source code for the VidCap Sample (Video Capture Filter) sample for time stamping examples.

You should also set the media time of the sample you deliver, as well as the regular time stamp. The media time is the sample number in the packet. So if you are sending one-second packets of 44.1 kilohertz (kHz) audio, you would set media time values of (0, 44100) (44100, 88200), and so on. This enables the downstream filters to know if any audio samples were dropped, even when the regular time stamps are a little random because the clock being used is not the audio digitizing clock.

One other thing: If the filter graph is in a running state, and then paused, and then run again, you must not produce a sample with a time stamp less than the last one you produced before pausing. Time stamps can never go back in time, not even back to before a pause occurred.

Necessary Interfaces

Read about the following interfaces and consider implementing them. You should implement these interfaces to provide functionality that applications might rely on, so these interfaces are strongly recommended.

  • Implement IAMDroppedFrames on your filter or on each output pin that sends data.
  • Implement IAMStreamConfig on each output pin that sends data.
  • Implement IAMStreamControl on each output pin that sends data.
  • Implement IAMAudioInputMixer on your filter and on each input pin.


Write a Transform Filter in C/C++

A transform filter takes media input and alters it in some way. When you design a transform filter, your filter class derives from one of the transform base classes, CTransformFilter, CTransInPlaceFilter, or CVideoTransformFilter, or from the more generic CBaseFilter class. Which base class you choose depends on whether your filter must copy media samples or can transform them in place. See Determine Which Base Classes to Use for more information.

The filter graph manager can use the functions of the base classes your filter derives from to fit your filter into the filter graph and automatically create the connections between your filters. The filter mapper uses your filter's registry information to configure the filter graph.

For the simplest transform filter (for example, one that has only one input pin and one output pin), you can derive your filter class from CTransformFilter and override only the Transform and CheckInputType functions. If you need custom features, you can override additional functions to create your own connections, pins, and other filter features and capabilities. See Override the Base Class Member Functions for more information. You can also derive your filter class from CBaseFilter and override its methods.

This section discusses how to:

  • Define and Instantiate Your Filter Class
  • Override CheckInputType (does not apply to filter classes derived from CBaseFilter)
  • Override the Transform Function(does not apply to filter classes derived from CBaseFilter)
  • Access Additional Interfaces
  • Create Registry Information

Every transform filter must implement code to perform all the preceding steps except access additional interfaces.

For background information about transform filters, see:

  • Determine Which Base Classes to Use
  • Override the Base Class Member Functions

For information on building a filter, see Build a Filter or Application with Visual C++ 5.x. For information on registering a filter or making it self-registering, see Register DirectShow Objects.

Define and Instantiate Your Filter Class

The following steps show you how to define and instantiate your filter class.

  1. Determine the base classes from which to derive your filter class (and pin classes, if necessary). Typically, your transform filter class derives from the CTransformFilter, CTransInPlaceFilter, or CVideoTransformFilter transform base classes, or from the more generic CBaseFilter class. If you want to transform video media (especially AVI data), derive from CVideoTransformFilter. If your filter must copy the input media samples, derive from CTransformFilter. If you filter can transform the sampled media in place, derive from CTransInPlaceFilter. If you don't want the simple transform filter support provided in the transform base classes, but prefer to implement your own member functions, derive from CBaseFilter. See Determine Which Base Classes to Use for more information.

    In the following example, the filter class derives from CTransInPlaceFilter.

    class CMyFilter  : public CTransInPlaceFilter
  2. Implement the IUnknown interface for your object.

    In the public section of your filter class definition, create an instance of CUnknown, and then call the DECLARE_IUNKNOWN macro.

    public:
        static CUnknown *WINAPI CreateInstance(LPUNKNOWN punk, HRESULT
    *phr);
        DECLARE_IUNKNOWN;
  3. Define your constructor. Also, define your Transform and CheckInputType functions (this does not apply if your filter class is derived from CBaseFilter).

    In the private section of your filter class definition, define your constructor by calling the constructor of the transform filter class you derived from, and then add code to perform the transform and check the input type. For example:

    //Define your constructor by calling the constructor of
    //CTransInPlaceFilter
    CMyFilter(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
    : CTransInPlaceFilter (tszName, punk, CLSID_MyFilter, phr)
    { }

    //Add the transform code
    HRESULT Transform(IMediaSample *pSample){
    //Transform code here
    }

    //Add code to check the input type
    HRESULT CheckInputType(const CMediaType* mtIn) {
    //Input checking code here
    }
  4. Implement CreateInstance for your filter object. Typically, CreateInstance calls the constructor of your filter class. For example:

    CUnknown * WINAPI CMyFilter::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {
    CMyFilter *pNewObject = new CMyFilter(NAME("Description of My Filter"), punk, phr );
    if (pNewObject == NULL) {
        *phr = E_OUTOFMEMORY;
    }
    return pNewObject;
    }
  5. Declare a global array g_Templates of CFactoryTemplate objects to inform the default class factory code how to access the CreateInstance function:

    CFactoryTemplate g_Templates[]=
      {   { L"My Filter"
        , &CLSID_MyFilter
        , CMyFilter::CreateInstance //Function called by class factory
        , NULL
        , &sudMyFilter } //Address of the AMOVIESETUP_FILTER structure,
                     //or NULL if no structure exists
    };
    int g_cTemplates = sizeof(g_Templates)/sizeof(g_Templates[0]);

    The g_cTemplates variable defines the number of class factory templates for the filter. Each of these templates provides a link between COM and the filter and are used to create the base object for the filter. At a minimum, the filter has one template that provides the address of its own CreateInstance function, which, when called, creates the base object.

    You can add additional parameters to the CFactoryTemplate templates to add property pages. See the Gargle sample for example code. See Register DirectShow Objects for information about using CFactoryTemplate in registration.

  6. Generate a GUID for your filter object.

    For information about generating GUIDs in general, see "GUID Creation and Optimizations" and "The uuidgen Utility" in the Platform SDK.

    To generate a GUID in Microsoft® Visual C++® 5.x, choose Create GUID from the Tools menu. By default, the GUID is in DEFINE_GUID format, which is the format you want. Click the Copy button. Put the cursor in your source file beneath the include statements, and choose Paste from the Edit menu. The inserted code will look like the following example, except that it will have its own unique number and CLSID. Insert the code before your class definition in the header file or main file.

    // {3FA5D260-AF2F-11d0-AE9C-00A0C91F0841}
    DEFINE_GUID(CLSID_MyFilter,
    0x3fa5d260, 0xaf2f, 0x11d0, 0xae, 0x9c, 0x0, 0xa0, 0xc9, 0x1f, 0x8, 0x41);

Override CheckInputType

You must override the CheckInputType function to determine if the proposed input to your filter is valid. (This does not apply to filter classes derived from CBaseFilter.) Your implementation should return an error for media types it can't support. The media types your filter supports are listed in the AMOVIESETUP_MEDIATYPE structure. For example:

    HRESULT CMyFilter::CheckInputType(const CMediaType *pmt)
    {
       if (pmt->majortype != MEDIATYPE_Video) {
           return S_FALSE;
       }
           else return S_OK;
       }

Override the Transform Function

To perform the desired transformation on your input media, your must override the Transform function of your transform base class, or implement your own transformation functions. (This does not apply to filter classes derived from CBaseFilter.) Examples of transformations are MPEG audio/video decoders (see the MPGAudio and MPGVideo samples), visual effects (see the Contrast and EzRGB24 samples), and audio effects (see the Gargle sample).

For example, consider the following code from the Contrast sample. You override the CContrast::Transform function as follows:

    HRESULT CContrast::Transform(IMediaSample *pIn, IMediaSample *pOut)
    {
            HRESULT hr = Copy(pIn, pOut);
        if (FAILED(hr)) {
            return hr;
        }
            return Transform(pOut);

    }

The first CContrast::Transform function copies the media data, and then passes the copy (pointed to by the pOut parameter) to a second Transform function. The first Transform function in the Contrast sample is an overloaded function, and the second form of the Transform function performs an in-place transform on the copy of the input media, as shown in the following code fragment.

    HRESULT CContrast::Transform(IMediaSample *pMediaSample)
    {
        signed char ContrastLevel;
        ContrastLevel = m_ContrastLevel;
        AM_MEDIA_TYPE *pAdjustedType = NULL;

        pMediaSample->GetMediaType(&pAdjustedType);
      HRESULT hr = Transform(&AdjustedType, ContrastLevel);
        pMediaSample->SetMediaType(&AdjustedType);
        return NOERROR;
    }

Note that the second form of the overloaded Transform function calls a third form of the overloaded Transform function.

Access Additional Interfaces

If your filter implements any interfaces that aren't implemented in the base classes, you must override the NonDelegatingQueryInterface function and return pointers to the implemented interfaces.

  1. In the public section of your filter class definition, declare NonDelegatingQueryInterface:

    STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void ** ppv);
  2. In the implementation section of your class, implement the NonDelegatingQueryInterface function. For example:

    //Reveal persistent stream and property pages
    STDMETHODIMP CMyFilter::NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if (riid == IID_IPersistStream) {
          AddRef( );   // Add a reference count. Be sure to release when done.
         *ppv = (void *) (IPersistStream *) this;
          return NOERROR;
       }
       else if (riid == IID_ISpecifyPropertyPages) {
             return GetInterface((ISpecifyPropertyPages *) this, ppv);
       }
       else {
          return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
       }
    }

Create Registry Information

The filter graph manager uses your filter's registry entries to configure your filter and its connections. You provide your filter's registry information in the AMOVIESETUP_MEDIATYPE, AMOVIESETUP_PIN, and AMOVIESETUP_FILTER structures. Typically, these structures are at the beginning of your filter implementation code. See Register DirectShow Objects for more information about using these structures.

Perform the following steps to provide the three structures you need for filter registration.

  1. Provide the AMOVIESETUP_MEDIATYPEstructure. This structure holds registry information about the media types your filter supports. For example:

    const AMOVIESETUP_MEDIATYPE sudPinTypes =
                    { &MEDIATYPE_Video             // MajorType
                    , &MEDIASUBTYPE_NULL}  ;       // MinorType

    The possible major types are MEDIATYPE_Stream, MEDIATYPE_Video, and MEDIATYPE_Audio.

  2. Provide the AMOVIESETUP_PIN structure. This structure holds registry information about the pins your filter supports.
  3. Provide the AMOVIESETUP_FILTER structure. This structure holds registry information about your filter object: its CLSID, description, number of pins, the pin structure's name, and your filter's merit. The merit controls the order in which the filter graph manager accesses your filter. Possible merit values are MERIT_PREFERRED, MERIT_NORMAL, MERIT_UNLIKELY, and MERIT_DO_NOT_USE. See IFilterMapper::RegisterFilter for a description of merit values. The following code shows an example of an AMOVIESETUP_FILTER structure.

    const AMOVIESETUP_FILTER
    sudMyFilter = { &CLSID_MyFilter			// clsID
                , L"My Filter Description"		// strName
                , MERIT_UNLIKELY				// dwMerit
                , 2						// nPins
                , sudpPins };				// lpPin


Stream Architecture

This section describes the DirectShow stream architecture and connection model. Topics include connecting filters, using pins, and negotiating data types.

About Stream Architecture

Connection Model


About Stream Architecture

Stream architecture defines objects and interfaces that exchange streams of time-based data. In particular, it defines interfaces for the following requirements.

  • Connecting filters to other filters.
  • Negotiating data types.
  • Transporting data between filters.
  • Synchronizing presentation of data.
  • Graceful degradation of rendering in cases of insufficient resources (that is, quality-control management).

    See Filters and Pins for more information.


Connection Model

This article provides an overview of the filter connection architecture in a Microsoft® DirectShow™ filter graph by examining the behavior of the base classes that implement connection. Because filters connect to other filters using pins, the architecture describes pin connection. Consequently, the CBasePin, CBaseOutputPin, and CBaseInputPin base classes and the IPin interface are discussed. This article describes the connection process and the default functionality built into these classes.

Contents of this article:

  • Connection Process
  • How the Base Classes Implement Connection
    • The Filter Graph Manager Starts the Connection
    • Negotiating Media Types with CBasePin::AgreeMediaType
    • Determining a Media Type with CBasePin::TryMediaTypes
  • When a Reconnection Should Occur

Connection Process

When building a filter graph, the filter graph manager connects pins between filters. It also selects filters based on the media type in the file it has been given to render or selects a predetermined configuration for the filter graph it is assembling. The filter graph manager can be asked specifically to add a filter by using the IFilterGraph::AddFilter method. The filter graph manager calls the IBaseFilter::JoinFilterGraph method on the filter to notify it that it has joined the filter graph. The added filter can then be connected like any other filter. When connecting filters, the filter graph manager requests the filters to enumerate their pins and then, for each connection required, requests that an output pin connect to an input pin.

The base classes handle much of the connection mechanism. However, it is important to understand the connection process when writing a filter so that you can identify what to override and what is expected of your filter. Before two connected filters are prepared to pass media between them, the following connection and negotiation processes must occur in this order.

  1. The initial pin connection occurs.
  2. The output pin of one filter retrieves interfaces from the connected input pin.
  3. Both pins negotiate for a common media type.
  4. Both pins negotiate for an appropriate transport to pass the media.

In the first step, the filter graph manager informs the output pin of one filter to connect to a specified input pin of another filter. This results in an exchange of IPin interface pointers. Filters should never connect to other filters by themselves. The filter graph manager must always be the agent that initiates a connection, because deadlocks can occur otherwise. A filter or an application can instruct the filter graph manager to connect two pins (through the IGraphBuilder::Connect or IFilterGraph::ConnectDirect method), or the filter graph manager can determine to connect filters when rendering a filter by using the IGraphBuilder::Render or IGraphBuilder::RenderFile method.

In the second step, the output pin may request the IMemInputPin interface from the connected input pin. This is in preparation for the fourth step, where the output pin will use IMemInputPin to retrieve a memory allocator from the input pin. If the output pin already has a memory allocator (or some other transport in the case of hardware filters), it can skip this step or can request some other interface in a proprietary design.

In the third step, media types are tried until one is found that is acceptable to both pins or the pins run out of types to try (in which case the connection fails). First, the output pin asks the connected input pin to propose its list of media types. If none of these are acceptable to the output pin, the output pin proposes its own types.

In the fourth step, the output pin asks the connected input pin for an allocator interface. The output pin then either accepts the allocator, or proposes its own allocator and notifies the input pin of the selection. The output pin makes the final determination.

How the Base Classes Implement Connection

The CBasePin class and its derived base classes, CBaseOutputPin and CBaseInputPin, implement most of the mechanism for the most common connection scenarios, much of which can be overridden by the derived filter class for more control of the process.

The connection procedure relies on the implementation of four interfaces:

  1. IPin, which is implemented by the CBasePin class and inherited by the CBaseInputPin and CBaseOutputPin classes.
  2. IEnumMediaTypes, which is implemented by the CEnumMediaTypes class and passed out by the IPin::EnumMediaTypes method.
  3. IMemInputPin, which is implemented by the CBaseInputPin class.
  4. IMemAllocator, which is implemented by the CBaseAllocator class and passed out by the IMemInputPin::GetAllocator method.

The IMemInputPin and IMemAllocator interfaces are necessary only if the filter belonging to the connecting input pin (called the downstream filter) is expected to provide a shared memory allocator for transporting samples between the pins. However, the base class implementation in CBaseInputPin assumes this condition and implements IMemInputPin to provide an allocator object to a connected output pin that requests it.

In the connection scenario of the default base class, the pin classes derived from CBaseInputPin and CBaseOutputPin need only to override and implement a few member functions and can let the base classes do the remaining work. Base classes derived from these classes, such as CTransformInputPin and CTransformOutputPin, do much of the required implementation to provide a default connection scheme.

Pin classes derived from CBaseInputPin and CBaseOutputPin need only to override the following member functions to enable pin connection.

  • CBasePin::CheckMediaType, which is called for every media type proposed by the media type enumerator. The overriding member function must accept or reject the proposed media type.
  • CBasePin::GetMediaType, which is called by the media type of the output pin enumerator to suggest media types already agreed on by the input pin for transform filters. This member function also presents the type of media a source filter will produce.

Additionally, the output pin derived from the CBaseOutputPin class must override the CBaseOutputPin::DecideBufferSize member function. This is called by the base classes to let the output pin inform any acquired allocator of the size and type of media samples that the output pin will provide. This is done by the output pin of the filter because the derived filter class should know the type and size of the data it will send to the input pin of the connected filter.

To see the context of these overriding functions, it is helpful to step through the execution of the connection code in the class library. All connection takes place in the scope of one CBasePin::Connect member function.

The Filter Graph Manager Starts the Connection

The connection starts when the filter graph manager calls the IPin::Connect method on the output pin, passing it a pointer to the input pin to which it is connecting. The filter graph manager has previously retrieved pointers to the IPin interfaces of both filters, for example, by calling the IBaseFilter::EnumPins method on each connecting filter. The EnumPins method creates a CEnumPins object to enumerate the pins, which the enumerator does by repeatedly calling the CBaseFilter::GetPin member function of the derived filter, which the derived filter must implement.

The CBasePin::Connect implementation of IPin::Connect does much of the work in this case. It calls the following functions.

  • CheckConnect, which is overridden by CBaseOutputPin.
  • AgreeMediaType, which is implemented by CBasePin.

The CBasePin::CheckConnect implementation simply determines that the pin directions are different. The overriding CBaseOutputPin::CheckConnect member function calls the IUnknown::QueryInterface method of the connected input pin to retrieve a pointer to the IMemInputPin interface of that pin. This will be used later in the connection process to request an allocator from the connected input pin. (Your derived class can override CBaseOutputPin::CheckConnect and omit retrieving the IMemInputPin interface if the output pin already has an allocator; for example, it might want to use the allocator from an upstream filter to eliminate copying.)

Negotiating Media Types with CBasePin::AgreeMediaType

The CBasePin::AgreeMediaType member function is called next and attempts to negotiate a media type that both pins agree on. It does this by trying to find a media type presented by the connected input pin with which the output pin agrees. If that fails, it tries to find a media type preferred by the output pin that the connected input pin agrees with.

CBasePin::AgreeMediaType calls the following member functions and methods.

  • IPin::EnumMediaTypes on the connected pin.
  • CBasePin::TryMediaTypes in the derived output pin class.

The IPin::EnumMediaTypes method of the connected input pin is called to return a media type enumerator (IEnumMediaTypes). This allows the output pin to examine the list of preferred media types belonging to the input pin.

The IEnumMediaTypes::Next method of the enumerator calls the GetMediaType member function of the derived input pin to retrieve each media type. If GetMediaType is not implemented, the base class implementation returns an error but this does not necessarily break the connection. (Pins are not required to have a preferred media type if one pin or the other can propose a type that they both accept. If neither pin can propose types, the connection will fail.)

Determining a Media Type with CBasePin::TryMediaTypes

CBasePin::AgreeMediaType calls CBasePin::TryMediaTypes next. The TryMediaTypes member function cycles through the preferred media types of the connected input pin and calls the CBasePin::CheckMediaType member function of the derived output pin class for each one it finds. CheckMediaType must be implemented by your derived output pin class. If CheckMediaType accepts the media type, the IPin::ReceiveConnection method of the connected input pin is called with the media type to determine if the connected input pin accepts this media type. If so, TryMediaTypes calls the CBaseOutputPin::CompleteConnect member function to finish the connection to the input pin.

If the input pin has no media types that the output type can use, CBasePin::AgreeMediaType repeats the entire process, using the enumerator for the media types of the output pin. (That is, it gets its own enumerator and calls TryMediaTypes with each of its preferred media types.) Again, the enumerator calls GetMediaType for each media type in the list. In this case, GetMediaType should be implemented to provide a media type. If the filter is a source filter, it will have a definite media type to export. If the filter is a transform filter, the media type will be established between the filter's input pin and its connected pin; the transform filter should query for that media type or simply use the enumerator of the upstream filter (unless the transform filter changes the media type from input pin to output pin).

CheckMediaType is called by CBasePin::TryMediaTypes, even when TryMediaTypes enumerates the list of the preferred media types of the output pin. This is because the owning filter might be a transform-inplace filter that is simply using the media type (and enumerator) of an upstream filter; this is the point at which the filter determines if the media type is compatible. The input pin of this transform filter might defer selecting a media type when it is connected, in which case it would be up to the output pin of the transform filter to ensure the media type is compatible with its transform.

If a media type can be established, TryMediaTypes eventually calls the CBaseOutputPin::CompleteConnect member function to negotiate a memory allocator.

First, the CBaseOutputPin::CompleteConnect member function calls the CBaseOutputPin::DecideAllocator member function. This member function negotiates a shared memory allocator with the input pin. It does this by first calling the IMemInputPin::GetAllocator method of the connected input pin, which retrieves a pointer to an IMemAllocator interface provided by the input pin.

Then, CompleteConnect calls the pure virtual CBaseOutputPin::DecideBufferSize member function, which your derived output pin class must override and implement because only the derived class can determine the required buffer size for its media type.

Finally, CompleteConnect calls the IMemInputPin::NotifyAllocator method of the connected pin to inform the input pin of the allocator to use and to provide a pointer to it. The input pin can reject this allocator, in which case the output pin can retry with a different allocator or fail the connection. If your derived class is not using the allocator of the connected input pin, override CBaseOutputPin::DecideAllocator in your derived class to call the NotifyAllocator member function with an allocator.

When a Reconnection Should Occur

Reconnection is always performed through the IFilterGraph interface on the filter graph manager. Reconnect by calling the IFilterGraph2::ReconnectEx method or the IFilterGraph::Reconnect method, both of which pass the IPin interfaces of the two pins to be reconnected. The ReconnectEx method specifies a media type and thus removes the burden of remembering what type to reconnect with from the pins, which makes the reconnection more likely to succeed.

Filters are typically connected with the upstream filter first and the downstream filter second. Therefore, the filter negotiates the connection on its input pin before information is available about the filter being connected to its output pin. When the output pin of the filter connects, it may become clear that the media type or allocator that was established for the input pin of the filter are not appropriate. In this case, the input connection can be broken and reconnected.

For example, consider the following connection scenario. An audio effects filter (for example, a reverberation effect) is inserted between an MPEG-audio decompressor filter and another audio effects filter. During the upstream connection to the decompressor filter, a media type is chosen—for example, 22.05 kHz, 16-bit mono. However, in this scenario, when the reverberation filter connects its output pin, the downstream filter will accept only an 11.025 kHz, 16-bit mono media type. Therefore, after connecting with the downstream filter, the reverberation effects filter must then reconnect with the upstream filter and negotiate for an 11.025 kHz media type.

But media types are not the only reason for reconnection. In many cases, the filter is a transform-inplace filter; that is, a filter that does not require that it either alters the media type or copies the data. Such a filter can be designed to use an allocator of some other filter (upstream or downstream), and likewise use the media type of another filter. That is, the filter is doing its transform "in place" in the buffer of another filter (for example, in the file buffer of the source filter or the video buffer of the rendering filter).

The general rule is that filters of this type should offer the allocator of the downstream filter to the upstream filter, once the allocator has been established for the output pin. This requires a reconnection of the input pin so that, when the input pin is asked for an allocator (in IMemInputPin::GetAllocator) by the upstream output pin, it can offer the allocator retrieved from the downstream filter by the output pin of the transform filter. Therefore, in-place transforms always reconnect.

There are a couple of important rules to follow when requesting a reconnection.

First, a filter must never request a reconnection unless it is certain that the reconnection will succeed. If the reconnection fails, it causes an asynchronous error in the filter graph for which there is no obvious cleanup. Any error that occurs (for example, from incompatible media types) should occur when the pins are connected the first time, when there are ample retry options available at more than one level (by the filter graph manager or the application at least).

Second, a filter should request a reconnection on the same thread as the call to IPin::Connect. For example, the following scenario attempts reconnection on a separate thread and will cause problems.

  1. The filter graph manager calls Connect on a pin.
  2. The filter pin carries out the Connect method and creates a thread, which starts to determine whether everything is okay for the connection.
  3. Connect returns to the filter graph manager.
  4. The filter graph manager returns to the application.
  5. The application calls the IMediaControl::Run method of the filter graph manager to start the filter graph, and the filters start running.
  6. The thread from the initial connection calls the IFilterGraph2::ReconnectEx or IFilterGraph::Reconnect method and the filter graph manager attempts to carry out reconnection.
  7. Failure occurs because the filters cannot reconnect while in the running state.

The filter graph has code to prevent this failure as long as the IFilterGraph2::ReconnectEx or IFilterGraph::Reconnect method takes effect while the filter graph is still processing the IGraphBuilder::Connect method. Calling the filter graph to reconnect before returning from the IPin::Connect method is the best way to ensure this problem does not occur. The best way to achieve this is to perform all of this on the same thread.


Plug-in Distributors

This article describes the plug-in distributor architecture and provides some rules assumed by the default Microsoft® DirectShow™ control distributors.

Contents of this article:

  • Plug-in Distributors and Extensibility
  • Control Distributors

Plug-in Distributors and Extensibility

The filter graph manager exports control interfaces; it also distributes the actions of interface methods to the appropriate filters. For example, the IMediaControl::Run method on the filter graph manager is called by an application to run the filter graph; this command is distributed to the IMediaFilter::Run method of each filter method by the filter graph manager. This distribution allows applications to have a single point of control to perform the basic operations.

To allow the filter graph manager to be extensible, a mechanism known as a plug-in distributor (PID) is used. This is a Component Object Model (COM) object that exposes a particular control interface and implements it by calling the enumerator of the filter graph manager, finding which filters expose the control interface and communicating directly with those filters. PIDs are supplied for the standard control interfaces; independent software vendors (ISVs) can replace these supplied PIDs and also add others.

When the filter graph manager is asked for an interface that it does not recognize, it searches the registry for a PID. This is an unnamed value under the following key.

HKEY_CLASSES_ROOT\Interface\<IID>\Distributor

This value provides the class identifier (CLSID) of an object that can distribute the interface identifier (IID). The filter graph manager then instantiates that object as an aggregated object, specifying the IUnknown implementation of the filter graph manager as the outer IUnknown, and asking for the IID. The object will then be able to use its outer IUnknown pointer to obtain an IFilterGraph interface. With this interface, it can enumerate the filters to implement its control interface methods and properties; it will also be able to use the IMediaControl implementation of the filter graph manager for correctly ordered and synchronized state changes (run, pause, stop, and so on).

Control Distributors

A control distributor is a PID that is used to control the data flow in the filter graph; for example, starting or stopping playback of a media stream. The standard control distributors supplied with DirectShow directly implement their distribution. These distributors make the following assumptions:

  • Applications that connect filters directly without informing the filter graph manager will get unexpected results if they also use the distributors of the filter graph manager. For example, a deadlock might occur if an application calls a filter's IBaseFilter::Run method directly, because the filter graph manager contains a distributor that implements IMediaControl::Run and passes calls on to each filter's IBaseFilter::Run method.
  • Properties that can be aggregated directly can be read and written to through the control interface, even when exposed by multiple filters. For example, duration can be reported as the longest of all individual durations, with all streams treated as running in parallel.
  • Where a property is exposed by several different filters, applications will either use the filter graph manager to set and get the property or will communicate with the individual filters, but will not mix the two methods. An application that communicates with two audio renderers to reset the volume and then queries the IBasicAudio implementation of the filter graph manager for the volume, will get undefined results. (In practice, it will probably retrieve the Volume property of the first audio renderer with no attempt to combine this with the other stream.) If the application sets the property through the interface of the filter graph manager, the same value will be set to all the individual filters that expose it.
  • The filter graph manager will expose the IMediaControl interface (through a non-replaceable distributor) as the main application method for starting and stopping graphs. This is a slightly higher-level, more simplified interface than IMediaFilter and is suitable for Automation clients and applications. The IMediaFilter implementation on the filter graph manager should not be called by applications. IMediaControl is implemented by calling the IMediaFilter interface implemented by the filter graph manager and by individual filters. Individual filters expose IMediaFilter through the IBaseFilter interface, which inherits it.

PIDs must keep track of the filters in the filter graph. This is done by implementing the IDistributorNotify interface on the distributor. IDistributorNotify has the same Run, Pause, and Stop methods as IMediaFilter, all of which are called before the calling the filter. It also has a IDistributorNotify::NotifyGraphChange method, which notifies the distributor when any filters are added or removed from the filter graph, or connections change.


DirectShow and COM

Microsoft® DirectShow™ provides a framework that simplifies the creation of Component Object Model (COM) objects. This article describes this framework and most of what you need to know about COM to create a filter or plug-in distributor using the C++ class library. The article assumes the reader is familiar with C++. An understanding of COM would be helpful, but is not essential.

Contents of this article:

  • COM Objects in DirectShow
  • Reviewing the Instantiation Process
  • Creating Filters
  • Creating Plug-in Distributors
  • Implementing the Class Factory
  • Using an Object-Oriented Model

COM Objects in DirectShow

DirectShow filters, the filter graph manager, plug-in distributors, and enumerators are all COM objects. A general design has been adopted for the way in which DirectShow implements COM objects. This design is available to help you implement your own filters and plug-in distributors (or any COM object).

DirectShow components are supplied as in-process servers; that is, servers that run in the same address space as your application. They are packaged in a single dynamic-link library (DLL), Quartz.dll. Use the COM framework of DirectShow to build your own in-process COM servers, which you can package in your own DLL(s).

Typically, a single C++ class implements a single COM class. The DirectShow COM framework requires that C++ classes implementing COM objects conform to a few simple rules. One of these rules is that the developer provides a class factory template for each such class. The class factory template contains information about the class that is vital to the framework. Class factory templates are defined in the DLL using two global variables (g_Templates and g_cTemplates) as shown in the following example.

CFactoryTemplate g_Templates[]=
{   {L"My class name", &CLSID_MyClass,   CMyClass::CreateInstance,  CMyClass::Init},
{L"My class name2", &CLSID_MyClass2,   CMyClass2::CreateInstance}
};
int g_cTemplates = sizeof(g_Templates)/sizeof(g_Templates[0]);

The names and types of these variables must be as they appear in the previous example. Because any DLL might contain several COM classes, each of which will require a class factory template, the factory templates are defined in an array and the number of elements in the array is recorded in another variable. Each element of the array contains the following fields.

  • A textual description of the class (using wide characters, therefore the "L" prefix).
  • A pointer to the class identifier of the class (CLSID).
  • A pointer to a static method of the class that can create instances of the class (CFactoryTemplate::CreateInstance).
  • A pointer to a static method of the class. This method is called when the DLL is loading or unloading and can perform one-time initialization and termination. If this method is not required, this can be omitted, will default to NULL, and will be ignored.
  • A pointer to an AMOVIESETUP_FILTER structure. This is required when using filter self-registration services.

The DirectShow COM framework uses the information in these class factory templates to create instances of the specific class, and to register and unregister the COM classes.

The following example demonstrates a simple C++ class implementing a COM class using the DirectShow framework.

class CMyClass : public IMyInterface, public CUnknown
{
private:
    /* private attributes */
protected:
    ~CMyClass()
    { /* release private attributes */ }
    CMyClass(TCHAR *pName, LPUNKNOWN pUnk, HRESULT *phr)
    : CUnknown( pName, pUnk, phr )
    { /* set up private attributes */ }
public:
    DECLARE_IUNKNOWN
static CUnknown *CreateInstance(LPUNKNOWN pUnk, HRESULT *phr)
{
CUnknown * result = 0;
result = new CMyClass( NAME("CMyClass"), pUnk, phr );
if ( !result ) *phr = E_OUTOFMEMORY;
return result;
}

STDMETHODIMP NonDelegatingQueryInterface(REFIID iid, void ** ppv)
{
if ( iid == IID_IMyInterface )
{
return GetInterface(static_cast<IMyInterface *>(this), ppv );
}
       else
        {
            return CUnknown::NonDelegatingQueryInterface(iid, ppv);
        }
}

    /* My interface methods */
};

This is not a typical filter example, because filters will normally derive from more specialized base classes than CUnknown. However, because all base filter classes eventually derive from CUnknown, this example demonstrates what is essential in a more generic manner. (The example is probably more typical for a DirectShow plug-in distributor (PID), which extends the functionality of the filter graph manager, or for a framework for implementing an arbitrary COM object.)

In this example, the NonDelegatingQueryInterface method is implemented. The more specialized filter base classes that derive from CUnknown are responsible for implementing NonDelegatingQueryInterface for the required interfaces; this is only necessary in the derived filter class if it adds some interfaces that are not in the base classes. In this case, it adds its own interface, IMyInterface.

INonDelegatingUnknown::NonDelegatingQueryInterface is a method that allows other objects to access interfaces on the COM object. All COM objects support IUnknown::QueryInterface to do this, and the DirectShow class library supplies the DECLARE_IUNKNOWN macro to enable the IUnknown interface. The DirectShow framework goes one step further and makes it easy to aggregate objects (make them part of a larger COM object) by implementing an INonDelegatingUnknown interface. Even if your object is not aggregated, it uses the INonDelegatingUnknown interface, which is mapped to the IUnknown interface by the base classes.

Although aggregation is handled for all objects by the DirectShow class framework, it is typically not used by filters in current DirectShow filter graphs. Plug-in distributors do, however, require aggregation (as is described later in this article), and future filter graphs might incorporate filter objects that are composed of collections of aggregated filters.

With this in mind, it might be helpful to explore more of the details of the previous example. First, a brief review of some COM basics might be helpful. COM objects are created by their class factories, are reference counted during their lifetimes, and self-destruct when their reference counts drop to zero. COM objects can be created in isolation, or can be aggregated with an already existing COM object. In this second case, the existing object (referred to as the outer object) maintains the reference count. The created object (referred to as the inner object) is not reference counted, but will be destroyed by the outer object during the destruction of the outer object. The application cannot directly manipulate COM objects; an application can only invoke the methods, which the object chooses to expose through its interfaces. Typically, COM objects make several interfaces available. All COM objects must support the IUnknown interface.

All classes using the DirectShow framework must inherit from CUnknown either directly (as in the previous example) or indirectly, through one of the other supplied base classes. CUnknown, with the DECLARE_IUNKNOWN macro and the NonDelegatingQueryInterface method, provide the IUnknown interface with the required reference counting and support for COM aggregation.

NonDelegatingQueryInterface is a method on INonDelegatingUnknown, which is supported by CUnknown. NonDelegatingQueryInterface is overridden in derived classes that support new interfaces, such as IMyInterface in the previous example. The method should check for all the interfaces known to be implemented on the object and return appropriate pointers to these interfaces. Requests for unrecognized interfaces should be passed to the NonDelegatingQueryInterface of CUnknown. The call to the GetInterface method (of CUnknown) copies the interface into the ppv parameter and ensures that the correct reference count is incremented.

The methods in INonDelegatingUnknown mirror those in IUnknown. For more information about CUnknown, the INonDelegatingUnknown interface, and the NonDelegatingQueryInterface method, see the CUnknown section in the reference material. INonDelegatingUnknown is defined in Combase.h; CUnknown is implemented in Combase.cpp.

When an instance of the class is required, the framework, using the information in the class factory template, calls the derived class's CreateInstance member function. The framework passes a pointer to an outer unknown (if the object will be part of an aggregate object) through the pUnkparameter, and passes a pointer to an HRESULT value through the phr parameter. The constructor of an inherited class can set this value if an error occurs. The phr parameter should not be initialized; this is the calling application's responsibility. The CreateInstance member function constructs an instance of the class by calling the constructor. The name passed to the constructor is wrapped with the NAME macro supplied by DirectShow. When building debugging versions, NAME passes the textual name on to the constructor. When building nondebugging versions, NAME results in a null pointer, thus saving space in versions that are not for debugging purposes.

The class constructor and destructor are declared protected. This prohibits the creation of the object using C++ language constructs. Instances of this class can be created only by calling the CreateInstance member function.

The class constructor needs to construct the inherited CUnknown. The pName parameter points to a string that is available for debugging purposes. It is vital that the string referenced by pName is in static storage, because the constructor for CUnknown will not copy it.

Reviewing the Instantiation Process

It might be helpful at this point to consider the normal process of instantiating a COM object, and examine how the DirectShow COM framework supports this process. First, a look at the entry points required of an in-process server DLL (such as a filter or plug-in distributor) is in order.

In-process server DLLs must export certain standard functions so that COM can interact with them. The DirectShow framework provides these functions for you. The module definition file for the DLL must list these functions in its EXPORTS section, and link to Strmbase.lib. The functions are: DllGetClassObject and DllCanUnloadNow. (The source code for these functions is supplied in Dllentry.cpp.)

A DirectShow object can define DLL entry points that facilitate the automatic registration of COM classes. These entry points are DllRegisterServer and DllUnregisterServer. Although the framework does not directly provide these entry points, it does provide a function, called AMovieDllRegisterServer2, that can implement these entry point functions. These functions take care of registering and unregistering all COM objects for which you have provided class factory templates in the g_Templates array. You can add a DllRegisterServer function to your module that simply calls AMovieDllRegisterServer2, or you could do the same for DllUnregisterServer. For more information on self-registering DirectShow COM objects, see Register DirectShow Objects.

Registry entries are required to link the class identifier (CLSID) of the COM object to the DLL in which the class is implemented. The framework provides entry points in the DLL that support the automatic registration of class identifiers in the registry, using the information provided in the class factory templates.

Following are the steps that occur during initialization, which require the entry points mentioned previously.

  1. When the DLL is loaded, the DllMain entry point is called to perform any initialization. The framework provides this function. During its execution, any initialization routines referenced in the class factory templates will be called.
  2. When an application calls CoCreateInstance or CoGetClassObject, COM calls the DllGetClassObject function in the appropriate DLL to obtain a pointer to a class factory that can instantiate objects of the CLSID requested by the application. The framework supplies this function. Using the information in the class factory template, the framework creates a class factory. (If the requested CLSID cannot be found in the array of class factory templates, an error is returned to the application.)
  3. The class factory is called to instantiate an object that supports the interface identifier (IID) requested by the application. At this point, the class factory will call the static method referenced in the class factory template.
  4. During the DLL's lifetime, the QueryInterface method might be called on the IUnknown interface of the object (or owning object if aggregated), requesting some interface on that object. By deriving the object class from CUnknown, overriding NonDelegatingQueryInterface, and using the DEFINE_IUNKNOWN macro to declare the IUnknown interface, both COM aggregation and reference counting are addressed.
  5. During the life of the DLL, DllCanUnloadNow might be called to see if it is safe to unload the DLL. Typically, this returns S_FALSE if any class factory is locked, or if any of the objects that have been created still exist. The framework implements DllCanUnloadNow.

Creating Filters

When creating filters, you can take advantage of one of the richer classes that DirectShow provides, such as CTransformFilter or CBaseRenderer, instead of deriving from CUnknown. These supplied classes are derived from CUnknown, but provide additional functionality specific to various types of filters. However, building filters also requires an understanding of the DirectShow connection model (see Connection Model) and the pin classes. For more information about creating filters, see Creating a Transform Filter.

Creating Plug-in Distributors

The filter graph manager can perform operations at a high level, treating the filter graph as a single entity. These operations can be distributed across an entire filter graph, or perhaps confined to just a single filter in the filter graph. The filter graph manager, of itself, only exposes a few interfaces. A feature called a plug-in distributor allows the filter graph manager to be extended with additional interfaces. When the filter graph manager receives a request for an interface which it does not support, it tries to find a plug-in distributor (PID) that does support it. If it succeeds in finding such a PID, then that PID is instantiated as an aggregate object within the filter graph manager. By doing so, the filter graph manager appears to support many more interfaces. Plug-in distributors are aggregated with the filter graph manager, but all the aggregation logic is provided by CUnknown, allowing you to concentrate on the PID logic.

A PID is designed to be aggregated into a filter graph manager; it will call on the services of its owning filter graph manager. Because the PID is unlikely to function correctly without an owning filter graph, it checks for an outer unknown in the constructor of the PID. To make this determination, add the following line to the body of the constructor illustrated in the previous example.

if (!pUnk) *phr = VFW_E_NEED_OWNER;

To be even more defensive against being used without an owner, the PID could also request an IFilterGraph or IGraphBuilder interface from the outer unknown during construction, because these interfaces are known to be only on the filter graph manager.

If the PID obtains any interface pointers from the filter graph manager, the pointers should be released immediately. Because the PID is an aggregate object, its lifetime is within the lifetime of its containing object, the filter graph manager, so there is no need to maintain a lock on it. Furthermore, maintaining a lock introduces a circular reference count that would not allow the destruction of the filter graph manager.

Implementing the Class Factory

The concept of a class factory is not specific to DirectShow; it is a common design that appears when the underlying type of the object being created is not known to the client that requests its creation. With COM objects, clients request interface pointers but know little about the underlying objects that implement that interface.

In C++, there are two means of implementing a class factory. One is to implement it as a genuine class, the other is to implement it as a static method on the class that the class factory will manage. The first method provides better separation of responsibilities and data hiding, and is the approach adopted by COM. The second method allows for a simpler implementation.

The DirectShow COM framework provides the best of both worlds. It exposes a genuine COM factory class to its clients while allowing the developer to implement the body of the class factory as a static method of your class. The bridge between these two approaches is two global variables, g_Templates and g_cTemplates, which were described previously.

The DirectShow framework defines two classes for implementing the class factory: CFactoryTemplate and CClassFactory. A CFactoryTemplate object holds information regarding a specific class, including a pointer to the static factory method of the class. When CClassFactory is instantiated, it must be given reference to a CFactoryTemplate instance. The CClassFactory instance will then act as a class factory for the class described in its associated CFactoryTemplate instance. The following illustration demonstrates the relationship between these classes, their instances, and the objects they create.

Diagram showing CFactoryTemplate/CClassFactory relationship

The DirectShow SDK includes a module, DllEntry.cpp, which provides the DllGetClassObject function. This function uses the process described previously to create a class factory that can produce instances of a class.

Using an Object-Oriented Model

All components of the DirectShow filter graph architecture are implemented as COM objects. This includes the filters through which data is passed, and filter components that serve as a connection between filters or allocate memory. Each object implements one or more interfaces, each of which contains a predefined set of functions, called methods. An application calls a method, or other component objects, to communicate with the object exposing the interface. For example, the application calls methods on the IMediaControl interface on the object of the filter graph manager, such as the Run method, which starts a media stream. The filter graph manager, in turn, calls the Run method on the IBaseFilter interface exposed by each of the filters.

Filter graph architecture uses COM interfaces because they have the following properties.

  • COM interfaces are publicly defined. This means that any filter that implements the correct predefined interfaces will work in a filter graph without any knowledge about the other filters, because all filters are built with the same interface specifications.
  • COM interfaces do not change after definition. A base set of interfaces are guaranteed to work; additional interfaces can be introduced to cover additional services. This definition prevents version problems.
  • COM interfaces must have all methods implemented by any object that exposes them (even if the implemented method simply returns E_NOTIMPL). This assures that calling a method on the interface of an object will not generate an error.
  • COM interfaces are discoverable. All COM objects support a method called QueryInterface that allows an external component to discover if an interface is present and retrieve a pointer to it.
  • COM interfaces are implemented by the object that exposes the interface (they do not contain an implementation themselves). The interface is essentially a contract for the functionality. Objects like the filter graph manager, or Microsoft filters, have implemented interfaces that can be accessed. When you write a filter, you implement the interfaces.

To make filter development easier, DirectShow provides a set of C++ classes that help you implement the interfaces required by the objects you create.


File Formats

This section describes file formats in different files used in DirectShow, including the format of saved DirectShow graph files, DirectShow extensions to the AVI 2.0 file format, and how to register custom files so that the DirectShow file-reader filters can read them.

DirectShow Graph File Format

DV Data in the AVI File Format
AVI 2.0 File Format Extensions

Registering a Custom File Type


DirectShow Graph File Format

The format of a saved DirectShow™ graph file is as follows:

The docfile (storage file) contains a stream called ActiveMovieGraph. This single stream contains within it all the filters, filter names, file names, connections, and so on.

To load such a graph, either:

  • Pass the storage file name to RenderFile. It will recognize that this is not a media file but a saved graph, and will restore the graph.

or:

  1. Open the storage file (by using StgOpenStorage).
  2. Query the filter graph manager for IPersistStream.
  3. Open the L"ActiveMovieGraph" stream (by using IStorage::OpenStream).
  4. Pass the stream to the filter graph (by using IPersistStream::Load).

The syntax of the graph within the stream follows:

<graph> ::= <version3><filters><connections><clock>END | <version2><filters><connections>END
<version3> ::= 0003\r\n
<version2> ::= 0002\r\n
<clock> ::= CLOCK <b> <required><b><clockid>\r\n
<required> ::= 1|0
<clockid> ::= <n>|<class id>
<filters ::= FILTERS <b>[<filter list><b>]
<connections> ::= CONNECTIONS [<b> <connection list>]
<filter list> ::= [<filter> <b>] <filter list>
<connection list> ::= [<connection><b>]<connection list>
<filter> ::= <n><b>"<name>"<b><class id><b>[<file>]<length><b1><filter data>
<file> ::= SOURCE "<name>"<b> | SINK "<name>"<b>
<class id> ::= class id of the filter in standard string form
<name> ::= any sequence of characters NOT including "
<length> ::= character string representing unsigned decimal number, for example, 23
             this is the number of bytes of data that follow the following space.
<b> ::= any combination of space, \t, \r, or \n
<b1> ::= exactly one space character
<n> ::= an identifier that will in fact be an integer, 0001, 0002, 0003, etc.
<connection> ::= <n1><b>"<pin1 id>"<b><n2><b>"<pin2 id>" <media type>
<n1> ::= identifier of first filter
<n2> ::= identifier of second filter
<pin1 id> ::= <name>
<pin2 id> ::= <name>
<media type> ::= <major type><b><sub type><b><flags><length><b1><format>
<major type> ::= <class id>
<sub type> ::= <class id>
<flags> ::= <FixedSizeSamples><b><TemporalCompression><b>
<FixedSizeSamples> ::= 1|0
<TemporalCompression> ::= 1|0
<Format> ::= <SampleSize><b><FormatType><b><FormatLength><b1><FormatData>
<FormatType> ::= class id of the format in standard string form
<FormatLength> ::= character string representing unsigned decimal number
             this is the number of bytes of data that follow the following space.
<FormatData> ::= binary data

On output there will be a new line (\r\n) per filter, one per connection, and one for each of the keywords FILTERS and CONNECTIONS. Each other case of <B> will be a single space. The keywords FILTERS, CONNECTIONS, and END are not localizable. Note also that the filter data and the format data are binary, so they might contain incorrect line breaks, null values, and so on.

The following approximates what the output looks like (a connection line is long and so has been split for presentation here, <with comments enclosed like this>).

0002
<version 2 of the syntax>
FILTERS
0001 "Source" {00000000-0000-0000-0000-000000000001} SOURCE "MyFile.mpg" 0000000000
<id   name   guid of the filter (need this to load it)   source file name   no private data>
0002 "another filter" {00000000-0000-0000-0000-000000000002} 0000000008 XXXXXXXX
<id   name   guid   (this one is not a file source or sink)   8 bytes private data>
CONNECTIONS
0001 "Output pin" 0002 "In"   <no line break here>
<filter id pin id   filter id pin id  (output pin is first, then input pin)>
    0000000172 {00000000-0000-0000-0000-000000000003}   <no line break here>
<sample size,   media type major-type>
    {00000000-0000-0000-0000-000000000004} 1 0   <no line break here>
<media type sub-type, fixed size samples, no temporal compression>
    0000000093 {00000000-0000-0000-0000-000000000005} 18 YYYYYYYYYYYYYYYYYY
<length of format   format type   18 bytes of binary format data>
END

where:

  • XXX... represents filter data
  • YYY... represents format data

The strings and characters in the file are always in Unicode.


DV Data in the AVI File Format

Microsoft has specified the format for storage of digital video (DV) data in AVI files. Conforming to this specification will ensure that the AVI files authored in this format will be compatible with future versions of the Microsoft® DirectShow™ digital video architecture for the Microsoft Windows® platform.

This article provides background information to understand the format of audio-video interleaved (AVI) files containing DV audio and video data, or information for programmers who use DV-AVI files on other platforms. Applications that read or write AVI files should use the File Source (Async) filter with the AVI Splitter filter and the AVI MUX filter with the File Writer filter and their associated interfaces provided in the DirectShow architecture, rather than developing the routines to perform these services. These filters simplify the programming requirements for accessing these files.

This article also describes the format of AVI files containing DV data. Specific FOURCCs (four-character codes) for interleaved DV data streams and DV compressor/decompressor stream handlers are defined. The stream format structure for DV data is defined. Specifications for two methods of storing DV data in the AVI file format are specified.

It is assumed that the reader is familiar with the DV data format. (This format is defined in the Specification of Consumer-use Digital VCRs, also called the Blue Book).

Contents of this article:

  • Types of DV AVI Files
  • AVI RIFF File Reference
  • AVI 2.0 File Format Extensions

For more information about resource interchange file format (RIFF) files, see the Windows Software Development Kit (SDK) Multimedia Programmer's Guide and Multimedia Programmer's Reference.

For more information about AVI files, see Chapter 6 of the Microsoft Video for Windows Development Kit version 1.1 Programmer's Guide and version 1.02 of the OpenDML AVI File Format Extensions published by the OpenDML AVI M-JPEG File Format Subcommittee, February 28, 1996.

For more information on compressors and decompressors, see the Video Compression and Decompression Drivers section of the Windows DDK Documentation in the MSDN Library.

Types of DV AVI Files

There are two types of DV AVI files:

  • AVI Files Containing One DV Data Stream
  • AVI Files Containing DV Video as a 'vids' Stream and DV Audio as 'auds' Streams

AVI Files Containing One DV Data Stream

Interleaved DV data can be stored in its native format as a single stream within an AVI RIFF file. This has the advantage of using the minimum amount of data storage for DV. The primary disadvantage is that this file format is not backward-compatible with Video for Windows, because it doesn't contain either a video 'vids' or an audio 'auds' stream. Support is provided for the interleaved DV stream through the DV Muxer and DV Splitter filters provided with DirectShow.

DV data can be stored in a single stream within an AVI RIFF file by specifying the 'iavs' (interleaved audio and video stream) FOURCC (four-character code) in the fccType member and either of the 'dvsd', 'dvhd', or 'dvsl' FOURCCs in the fccHandler member of the 'strh' stream header chunk. The frames per second of the video stream must be specified in the dwRate and dwScale members and the total number of video blocks in the 'movi' chunk in the dwLength member.

The 'dvsd' stream handler FOURCC specifies that the DV data is as defined in Part 2 of the Specification of Consumer-use Digital VCRs. Video is in the format of 525 lines at 29.97 Hz (525-60) or 625 lines at 25.00 Hz (625-50).

The 'dvhd' stream handler FOURCC specifies that the DV data is as defined in Part 3 of the Specification of Consumer-use Digital VCRs. Video is in the format of 1125 lines at 30.00 Hz (1125-60) or 1250 lines at 25.00 Hz (1250-50).

The 'dvsl' stream handler FOURCC specifies that the DV data is as defined in Part 6 of Specification of Consumer-use Digital VCRs. Video is in the format of high-compression SD (SDL).

Note The remainder of this article provides definitions for 'dvsd' streams.

The stream header chunk must be followed by DVINFO stream format chunk. The DVINFO stream format has the following data structure defined for it:

typedef struct tag_DVINFO {
    DWORD dwDVAAuxSrc;
    DWORD dwDVAAuxCtl;
    DWORD dwDVAAuxSrc1;
    DWORD dwDVAAuxCtl1;
    DWORD dwDVVAuxSrc;
    DWORD dwDVVAuxCtl;
    DWORD dwDVReserved[2];
} DVINFO, *PDVINFO;
dwDVAAuxSrc | Specifies the Audio Auxiliary Data Source Pack for the first audio block (first 5 DV DIF sequences for 525-60 systems or 6 DV DIF sequences for 625-50 systems) of a frame. A DIF sequence is a data block that contains 150 DIF blocks. A DIF block consists of 80 bytes. The Audio Auxiliary Data Source Pack is defined in section D.7.1 of Part 2, Annex D, "The Pack Header Table and Contents of Packs" of the Specification of Consumer-use Digital VCRs.
dwDVAAuxCtl | Specifies the Audio Auxiliary Data Source Control Pack for the first audio block of a frame. The Audio Auxiliary Data Control Pack is defined in section D.7.2 of Part 2, Annex D, "The Pack Header Table and Contents of Packs" of the Specification of Consumer-use Digital VCRs.
dwDVAAuxSrc1 | Specifies the Audio Auxiliary Data Source Pack for the second audio block (second 5 DV DIF sequences for 525-60 systems or 6 DV DIF sequences for 625-50 systems) of a frame.
dwDVAAuxCtl1 | Specifies the Audio Auxiliary Data Source Control Pack for the second audio block of a frame.
dwDVVAuxSrc | Specifies the Video Auxiliary Data Source Pack as defined in section D.8.1 of Part 2, Annex D, "The Pack Header Table and Contents of Packs" of the Specification of Consumer-use Digital VCRs.
dwDVVAuxCtl | Specifies the Video Auxiliary Data Source Control Pack as defined in section D.8.2 of Part 2, Annex D, "The Pack Header Table and Contents of Packs" of the Specification of Consumer-use Digital VCRs.
DwDVReserved[2] | Reserved. Set this array to zero.

The actual DV data is stored as '##dc' chunks in the 'movi' chunk (the ## in the format represents the stream identifier). Each chunk contains one frame of data, either 10 or 12 DV DIF sequences for 525-60 or 625-50 systems, respectively. The DV SD ('dvsd') DIF sequence format is defined in Part 2 of the Specification of Consumer-use Digital VCRs.

The following diagram illustrates the playback of an AVI file with one DV data stream using a DirectShow filter graph (the DV Splitter and DV Video Decoder filters are included in DirectShow specifically to deal with DV data). The table that follows the diagram defines the media types.

Playback of an AVI file with one DV data stream

DV media types table
Media | Major type | Subtype | Format structure
A | MEDIATYPE_Stream | MEDIASUBTYPE_AVI | none
B | MEDIATYPE_iavs | MEDIASUBTYPE_dvsd, MEDIASUBTYPE_dvhd, or MEDIASUBTYPE_dvsl | DVINFO
C | MEDIATYPE_VIDEO | MEDIASUBTYPE_dvsd, MEDIASUBTYPE_dvhd, or MEDIASUBTYPE_dvsl | DVINFO
D | MEDIATYPE_AUDIO | NULL | WAVEFORMATEX
E | MEDIATYPE_VIDEO | standard video types | VIDEOINFO

The following diagram illustrates the creation of an AVI file with one DV data stream by using a DirectShow filter graph (the DV Video Encoder and DV Muxer filters are included in DirectShow specifically to deal with DV data). The preceding table defines the media types. Upstream filters (not shown) can be of any combination to produce the proper media types, D and E.

Creation of an AVI file with one DV data stream

The following diagram illustrates the creation of an AVI file with one DV data stream using a source filter that communicates through hardware device drivers with a DV device (such as a 1394-based DV camcorder) for DV data input, by using a DirectShow filter graph (the source filter is included in DirectShow specifically to deal with DV data). The preceding table defines the media types.

DV capture to an AVI file with one DV data stream

The following diagram illustrates the output of an AVI file with one DV data stream using a sink filter that communicates through hardware device drivers with a DV device (such as a 1394-based DV camcorder) for DV data output, by using a DirectShow filter graph (the sink filter is included in DirectShow specifically to deal with DV data). The preceding table defines the media types.

Output of an AVI file with one DV data stream

The following example shows the AIFF RIFF form for an AVI file with one DV data stream, expanded with completed header chunks:

00000000 RIFF (0FAE35D4) 'AVI '
0000000C     LIST (00000106) 'hdrl'
00000018         avih (00000038)
                     dwMicroSecPerFrame    : 33367
                     dwMaxBytesPerSec      : 3728000
                     dwPaddingGranularity  : 0
                     dwFlags               : 0x810 HASINDEX | TRUSTCKTYPE
                     dwTotalFrames         : 2192
                     dwInitialFrames       : 0
                     dwStreams             : 1
                     dwSuggestedBufferSize : 120000
                     dwWidth               : 720
                     dwHeight              : 480
                     dwReserved            : 0x0
00000058         LIST (0000006C) 'strl'
00000064             strh (00000038)
                         fccType               : 'iavs'
                         fccHandler            : 'dvsd'
                         dwFlags               : 0x0
                         wPriority             : 0
                         wLanguage             : 0x0 undefined
                         dwInitialFrames       : 0
                         dwScale               : 100 (29.970 Frames/Sec)
                         dwRate                : 2997
                         dwStart               : 0
                         dwLength              : 2192
                         dwSuggestedBufferSize : 120000
                         dwQuality             : 0
                         dwSampleSize          : 0
                         rcFrame               : 0,0,720,480
000000A4             strf (00000020)
                         dwDVAAuxSrc     : 0x........
                         dwDVAAuxCtl     : 0x........
                         dwDVAAuxSrc1    : 0x........
                         dwDVAAuxCtl1    : 0x........
                         dwDVVAuxSrc     : 0x........
                         dwDVVAuxCtl     : 0x........
                         dwDVReserved[2] : 0,0
000000CC     LIST (0FADAC00) 'movi'
0FADACD4     idx1 (00008900)

AVI Files Containing DV Video as a 'vids' Stream and DV Audio as 'auds' Streams

Interleaved DV data can be split into a video stream and one to four audio streams within an AVI RIFF file. This has the advantage of being backward-compatible with Video for Windows, because it contains a standard video 'vids' stream and at least one standard audio 'auds' stream The primary disadvantage is that this file format requires the audio data to be redundantly stored as audio streams. The "video" stream is actually the native interleaved DV data stream. However, as a standard 'vids' stream with a handler type of 'dvsd', the DV Video Decoder is used. This format also requires that "captured" files are split by using the DV Splitter filter before they are written as AVI files.

DV data can be stored as a video stream with a separate number of audio streams in an AVI RIFF file. The video stream is specified with a standard video stream header (the fccType member value is 'vids'). The fccHandler member is specified as 'dvsd', 'dvhd', or 'dvsl'. The frames per second of the video stream must be specified in the dwRate and dwScale members and the total number of video blocks in the 'movi' chunk in the dwLength member.

In this AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams form of DV, the video stream format chunk is a standard BITMAPINFOHEADER structure. The stream format chunk can be optionally extended to include the DVINFO structure, by increasing the stream format chunk size from 40 bytes (size of the BITMAPINFOHEADER structure) to 72 bytes (size of BITMAPINFOHEADER plus DVINFO structures) and immediately following the BITMAPINFOHEADER data structure with a DVINFO data structure.

The audio stream(s) is specified with a standard audio stream header (the fccType member value is 'auds'). The fccHandler member is not used for audio streams.

The DV video data is stored as '##dc' chunks, as defined in the preceding description of an AVI file with one DV data, and the audio data is stored as '##wb' chunks in the 'movi' chunk.

The following diagram illustrates the playback of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams, by using a DirectShow filter graph (the DV Video Decoder filter is included in DirectShow specifically to deal with DV data). The DV media types table defines the media types.

Creation of an AVI file with one DV data stream

The following diagram illustrates the creation of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams, using a DirectShow filter graph (the DV Video Decoder is included in DirectShow specifically to deal with DV data). The DV media types table defines the media types. Upstream filters (not shown) can be of any combination to produce the proper media types, D and E.

Creation of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams

The following diagram illustrates the creation of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams using a source filter that communicates through hardware device drivers with a DV device (such as a 1394-based DV camcorder) for DV data input, by using a DirectShow filter graph (the source and DV Splitter filters are included in DirectShow specifically to deal with DV data). The DV media types table defines the media types.

DV capture to an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams

The following diagram illustrates the output of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams using a sink filter that communicates through hardware device drivers with a DV device (such as a 1394-based DV camcorder) for DV data output, by using a DirectShow filter graph (the DV Muxer and sink filters are included in DirectShow specifically to deal with DV data). The DV media types table defines the media types.

Output of an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams

The following example shows the AIFF RIFF form for an AVI file containing DV video as a 'vids' stream and DV audio as 'auds' streams expanded with completed header chunks (including optional DVINFO data following the BITMAPINFO in the 'strf' sub-chunk for the 'vids' stream):

00000000 RIFF (103E2920) 'AVI '
0000000C     LIST (00000146) 'hdrl'
00000018         avih (00000038)
                     dwMicroSecPerFrame    : 33367
                     dwMaxBytesPerSec      : 3728000
                     dwPaddingGranularity  : 0
                     dwFlags               : 0x810 HASINDEX | TRUSTCKTYPE
                     dwTotalFrames         : 2192
                     dwInitialFrames       : 0
                     dwStreams             : 2
                     dwSuggestedBufferSize : 120000
                     dwWidth               : 720
                     dwHeight              : 480
                     dwReserved            : 0x0
00000058         LIST (00000094) 'strl'
00000064             strh (00000038)
                         fccType               : 'vids'
                         fccHandler            : 'dvsd'
                         dwFlags               : 0x0
                         wPriority             : 0
                         wLanguage             : 0x0 undefined
                         dwInitialFrames       : 0
                         dwScale               : 100 (29.970 Frames/Sec)
                         dwRate                : 2997
                         dwStart               : 0
                         dwLength              : 2192
                         dwSuggestedBufferSize : 120000
                         dwQuality             : 0
                         dwSampleSize          : 0
                         rcFrame               : 0,0,720,480
000000A4             strf (00000048)
                         biSize          : 40
                         biWidth         : 720
                         biHeight        : 480
                         biPlanes        : 1
                         biBitCount      : 24
                         biCompression   : 0x64737664 'dvsd'
                         biSizeImage     : 120000
                         biXPelsPerMeter : 0
                         biYPelsPerMeter : 0
                         biClrUsed       : 0
                         biClrImportant  : 0
                         dwDVAAuxSrc     : 0x........
                         dwDVAAuxCtl     : 0x........
                         dwDVAAuxSrc1    : 0x........
                         dwDVAAuxCtl1    : 0x........
                         dwDVVAuxSrc     : 0x........
                         dwDVVAuxCtl     : 0x........
                         dwDVReserved[2] : 0,0
000000F4         LIST (0000005E) 'strl'
00000100             strh (00000038)
                         fccType               : 'auds'
                         fccHandler            : '    '
                         dwFlags               : 0x0
                         wPriority             : 0
                         wLanguage             : 0x0 undefined
                         dwInitialFrames       : 0
                         dwScale               : 1 (32000.000 Samples/Sec)
                         dwRate                : 32000
                         dwStart               : 0
                         dwLength              : 2340474
                         dwSuggestedBufferSize : 4272
                         dwQuality             : 0
                         dwSampleSize          : 4
                         rcFrame               : 0,0,0,0
00000140             strf (00000012)
                         wFormatTag      : 1 PCM
                         nChannels       : 2
                         nSamplesPerSec  : 32000
                         nAvgBytesPerSec : 128000
                         nBlockAlign     : 4
                         wBitsPerSample  : 16
                         cbSize          : 0
00000814     LIST (103D0EF4) 'movi'
103D1710     idx1 (00011210)

AVI RIFF File Reference

The Microsoft audio-video interleaved (AVI) file format is a RIFF file specification used with applications that capture, edit, and play back audio-video sequences. In general, AVI files contain multiple streams of different types of data. Most AVI sequences use both audio and video streams. A simple variation for an AVI sequence uses video data and does not require an audio stream.

Modifications to the original AVI file specification made in the OpenDML AVI File Format Extensions are not discussed in this section. For further information on these extensions, see version 1.02 of the OpenDML AVI File Format Extensions published by the OpenDML AVI M-JPEG File Format Subcommittee, February 28, 1996.

This section contains the following topics:

  • AVI RIFF Form
  • AVI Main Header
  • AVI Stream Headers
  • Stream Data (LIST 'movi' Chunk)
  • BITMAPINFOHEADER Structure
  • WAVEFORMATEX Structure

AVI RIFF Form

AVI files use the AVI RIFF form. The AVI RIFF form is identified by the FOURCC (four-character code) 'AVI '. All AVI files include two mandatory LIST chunks. These chunks define the format of the stream and stream data. AVI files might also include an index chunk. This optional chunk specifies the location of data chunks within the file. An AVI file with these components has the following form:

RIFF ('AVI '
      LIST ('hdrl'
              .
              .
              .
           )
      LIST ('movi'
              .
              .
              .
           )
      ['idx1'<AVI Index>]
     )

The LIST chunks and the index chunk are subchunks of the RIFF 'AVI ' chunk. The 'AVI ' chunk identifies the file as an AVI RIFF file. The LIST 'hdrl' chunk defines the format of the data and is the first required LIST chunk. The LIST 'movi' chunk contains the data for the AVI sequence and is the second required LIST chunk. The 'idx1' chunk is the index chunk. AVI files must keep these three components in the proper sequence.

The LIST 'hdrl' and LIST 'movi' chunks use subchunks for their data. The following example shows the AVI RIFF form expanded with the chunks needed to complete the LIST 'hdrl' and LIST 'movi' chunks:

RIFF ('AVI '
      LIST ('hdrl'
            'avih'(<Main AVI Header>)
            LIST ('strl'
                  'strh'(<Stream header>)
                  'strf'(<Stream format>)
                  'strd'(<additional header data>)
                  'strn'(<Stream name>)
                  ...
                 )
             .
             .
             .
           )

      LIST ('movi'
            {SubChunk | LIST ('rec '
                              SubChunk1
                              SubChunk2
                                .
                                .
                                .
                             )
               .
               .
               .
            }
            .
            .
            .
           )

      ['idx1'<AVI Index>]
     )

AVI Main Header

This and following sections describe the chunks contained in the LIST 'hdrl' and LIST 'movi' chunks. The 'idx1' chunk is not described in this document. For more information on the 'idx1' chunk and indexes in AVI files, see version 1.02 of the OpenDML AVI File Format Extensions published by the OpenDML AVI M-JPEG File Format Subcommittee, February 28, 1996.

The file begins with the main header. In the AVI file, this header is identified by the 'avih' FOURCC (four-character code). The header contains global information for the entire AVI file, such as the number of streams within the file and the width and height of the AVI sequence. The AVI main header structure is defined as follows:

typedef struct {
    DWORD dwMicroSecPerFrame;
    DWORD dwMaxBytesPerSec;
    DWORD dwReserved1;
    DWORD dwFlags;
    DWORD dwTotalFrames;
    DWORD dwInitialFrames;
    DWORD dwStreams;
    DWORD dwSuggestedBufferSize;
    DWORD dwWidth;
    DWORD dwHeight;
    DWORD dwReserved[4];
} MainAVIHeader;
dwMicroSecPerFrame | Specifies the number of microseconds between frames. This value indicates the overall timing for the file.
dwMaxBytesPerSec | Specifies the approximate maximum data rate of the file. This value indicates the number of bytes per second the system must handle to present an AVI sequence as specified by the other parameters contained in the main header and stream header chunks.
dwReserved1 | Reserved. Set this to zero.
dwFlags | Contains any flags for the file. The following flags are defined:
AVIF_HASINDEX — Indicates the AVI file has an 'idx1' chunk containing an index at the end of the file. For good performance, all AVI files should contain an index.
AVIF_MUSTUSEINDEX — Indicates that the index, rather than the physical ordering of the chunks in the file, should be used to determine the order of presentation of the data. For example, you could use this to create a list of frames for editing.
AVIF_ISINTERLEAVED — Indicates the AVI file is interleaved.
AVIF_WASCAPTUREFILE — Indicates the AVI file is a specially allocated file used for capturing real-time video. Applications should warn the user before writing over a file with this flag set because the user probably defragmented this file.
AVIF_COPYRIGHTED — Indicates the AVI file contains copyrighted data and software. When this flag is used, software should not permit the data to be duplicated.
dwTotalFrames | Specifies the total number of frames of data in the file.
dwInitialFrames | Specifies the initial frame for interleaved files. Noninterleaved files should specify zero. If you are creating interleaved files, specify the number of frames in the file prior to the initial frame of the AVI sequence in this member. For more information about the contents of this member, see "Special Information for Interleaved Files" in the Video for Windows Programmer's Guide.
dwStreams | Specifies the number of streams in the file. For example, a file with audio and video has two streams.
dwSuggestedBufferSize | Specifies the suggested buffer size for reading the file. Generally, this size should be large enough to contain the largest chunk in the file. If set to zero, or if it is too small, the playback software will have to reallocate memory during playback, which will reduce performance. For an interleaved file, the buffer size should be large enough to read an entire record, and not just a chunk.
dwWidth | Specifies the width of the AVI file in pixels.
dwHeight | Specifies the height of the AVI file in pixels.
dwReserved[4] | Reserved. Set this array to zero.

AVI Stream Headers

The main header is followed by one or more 'strl' chunks. (A 'strl' chunk is required for each data stream.) These chunks contain information about the streams in the file. Each 'strl' chunk must contain a stream header and stream format chunk. Stream header chunks are identified by the FOURCC (four-character code) 'strh' and the stream format chunks are identified by the FOURCC 'strf'. In addition to the stream header and stream format chunks, the 'strl' chunk might also contain a stream-header data chunk and a stream name chunk. Stream-header data chunks are identified by the FOURCC 'strd'. Stream name chunks are identified by the FOURCC 'strn'.

The stream header structure contains header information for a single stream of a file.

typedef struct {
    FOURCC fccType;
    FOURCC fccHandler;
    DWORD  dwFlags;
    DWORD  dwPriority;
    DWORD  dwInitialFrames;
    DWORD  dwScale;
    DWORD  dwRate;
    DWORD  dwStart;
    DWORD  dwLength;
    DWORD  dwSuggestedBufferSize;
    DWORD  dwQuality;
    DWORD  dwSampleSize;
    RECT   rcFrame;
} AVIStreamHeader;

The stream header specifies the type of data the stream contains, such as audio or video, by means of a FOURCC.
fccType
Contains a FOURCC that specifies the type of the data contained in the stream. The following standard AVI values for video and audio are defined:
'vids' — Indicates the stream contains video data. The stream format chunk contains a BITMAPINFO structure that can include palette information.
'auds' — Indicates the stream contains audio data. The stream format chunk contains a WAVEFORMATEX or PCMWAVEFORMAT structure.
'txts' — Indicates the stream contains text data.
fccHandler | Optionally, contains a FOURCC that identifies a specific data handler. The data handler is the preferred handler for the stream. For audio and video streams, this specifies the installable compressor or decompressor.
dwFlags | Contains any flags for the data stream. The bits in the high-order word of these flags are specific to the type of data contained in the stream. The following standard flags are defined:
AVISF_DISABLED — Indicates this stream should not be enabled by default.
AVISF_VIDEO_PALCHANGES — Indicates this video stream contains palette changes. This flag warns the playback software that it will need to animate the palette.
dwPriority | Specifies priority of a stream type. For example, in a file with multiple audio streams, the one with the highest priority might be the default stream.
dwInitialFrames | Specifies how far audio data is skewed ahead of the video frames in interleaved files. Typically, this is about 0.75 seconds. If you are creating interleaved files, specify the number of frames in the file prior to the initial frame of the AVI sequence in this member. For more information about the contents of this member, see "Special Information for Interleaved Files" in the Video for Windows Programmer's Guide.
dwScale | Used with dwRate to specify the time scale that this stream will use. Dividing dwRate by dwScale gives the number of samples per second. For video streams, this rate should be the frame rate. For audio streams, this rate should correspond to the time needed for nBlockAlign bytes of audio, which for PCM audio simply reduces to the sample rate.
dwRate | See dwScale.
dwStart | Specifies the starting time of the AVI file. The units are defined by the dwRate and dwScale members in the main file header. Usually, this is zero, but it can specify a delay time for a stream that does not start concurrently with the file.
dwLength | Specifies the length of this stream. The units are defined by the dwRate and dwScale members of the stream's header.
dwSuggestedBufferSize | Specifies how large a buffer should be used to read this stream. Typically, this contains a value corresponding to the largest chunk present in the stream. Using the correct buffer size makes playback more efficient. Use zero if you do not know the correct buffer size.
dwQuality | Specifies an indicator of the quality of the data in the stream. Quality is represented as a number between 0 and 10,000. For compressed data, this typically represents the value of the quality parameter passed to the compression software. If set to –1, drivers use the default quality value.
dwSampleSize | Specifies the size of a single sample of data. This is set to zero if the samples can vary in size. If this number is nonzero, then multiple samples of data can be grouped into a single chunk within the file. If it is zero, each sample of data (such as a video frame) must be in a separate chunk. For video streams, this number is typically zero, although it can be nonzero if all video frames are the same size. For audio streams, this number should be the same as the nBlockAlign member of the WAVEFORMATEX structure describing the audio.
rcFrame | Specifies the destination rectangle for a text or video stream within the movie rectangle specified by the dwWidth and dwHeight members of the AVI main header structure. The rcFrame member is typically used in support of multiple video streams. Set this rectangle to the coordinates corresponding to the movie rectangle to update the whole movie rectangle. Units for this member are pixels. The upper-left corner of the destination rectangle is relative to the upper-left corner of the movie rectangle.

The last eight members describe the playback characteristics of the stream. These factors include the playback rate (dwScale and dwRate), the starting time of the sequence (dwStart), the length of the sequence (dwLength), the size of the playback buffer (dwSuggestedBuffer), an indicator of the data quality (dwQuality), and the sample size (dwSampleSize).

Some of the members in the stream header structure are also present in the main header structure. The data in the main header applies to the whole file, while the data in the stream header structure applies only to a stream.

A stream format ('strf') chunk must follow a stream header ('strh') chunk. The stream format chunk describes the format of the data in the stream. For video streams, the information in this chunk is a BITMAPINFO structure (including palette information if appropriate). For audio streams, the information in this chunk is a WAVEFORMATEX or PCMWAVEFORMAT structure. (The WAVEFORMATEX structure is an extended version of the WAVEFORMAT structure.) For more information about this structure and other stream types, see the New Multimedia Data Types and Data Techniques Standards Update.

The 'strl' chunk might also contain an additional stream-header data ('strd') chunk. If used, this chunk follows the stream format chunk. The format and content of this chunk is defined by installable compression or decompression drivers. Typically, drivers use this information for configuration. Applications that read and write RIFF files do not need to decode this information. They transfer this data to and from a driver as a memory block.

The optional 'strn' stream name chunk provides a zero-terminated text string describing the stream. (The AVI file functions can use this chunk to let applications identify the streams they want to access by their names.)

An AVI player associates the stream headers in the LIST 'hdrl' chunk with the stream data in the LIST 'movi' chunk by using the order of the 'strl' chunks. The first 'strl' chunk applies to stream 0, the second applies to stream 1, and so forth.

For example, if the first 'strl' chunk describes the wave audio data, the wave audio data is contained in stream 0. Similarly, if the second 'strl' chunk describes video data, then the video data is contained in stream 1.

Stream Data (LIST 'movi' Chunk)

Following the header information is a LIST 'movi' chunk that contains chunks of the actual data in the streams — that is, the pictures and sounds themselves. The data chunks can reside directly in the LIST 'movi' chunk or they might be grouped into 'rec' chunks. The 'rec' grouping implies that the grouped chunks should be read from disk all at once. This is used only for files specifically interleaved to play from CD-ROM.

Like any RIFF chunk, the data chunks contain a FOURCC (four-character code) to identify the chunk type. A FOURCC is a 32-bit quantity represented as a sequence of one to four ASCII alphanumeric characters, padded on the right with blank characters. The FOURCC that identifies each chunk consists of the stream number and a two-character code that defines the type of information encapsulated in the chunk. For example, a waveform chunk is identified by a two-character code of 'wb'. If a waveform chunk corresponded to the second LIST 'hdrl' stream description, it would have a FOURCC of '01wb'.

Note While two-character codes are a convenient way to describe a stream, do not expect them to be recognized by other applications. Use FOURCCs when creating a stream or transferring the information to other applications.

Because all the format information is in the header, the audio data contained in these data chunks does not contain any information about its format. An audio data chunk has the following format (the ## in the format represents the stream identifier):

WAVE Bytes '##wb'
     BYTE  abBytes[];

Video data can be compressed or uncompressed DIBs. An uncompressed DIB has BI_RGB specified for the biCompression member in its associated BITMAPINFO structure. A compressed DIB has a value other than BI_RGB specified in the biCompression member. For more information about compression formats, see the description of the BITMAPINFOHEADER data structure in the Microsoft Windows Programmer's Reference.

A data chunk for an uncompressed DIB contains RGB video data. These chunks are identified by a two-character code of 'db' (db is an abbreviation for DIB bits). Data chunks for a compressed DIB are identified by a two-character code of 'dc' (dc is an abbreviation for DIB compressed). Neither data chunk will contain any header information about the DIBs. The data chunk for an uncompressed DIB has the following form:

DIB  Bits  '##db'
     BYTE  abBits[];

The data chunk for a compressed DIB has the following form.

Compressed DIB  Bits  '##dc'
                BYTE  abBits[];

Video data chunks can also define new palette entries used to update the palette during an AVI sequence. For more information on specifying palette information, see Video for Windows Programmer's Guide.

Text streams can use arbitrary two-character codes.

BITMAPINFOHEADER Structure

The BITMAPINFOHEADER structure contains information for the video stream of an AVI RIFF file. This structure has the following members:

typedef struct tagBITMAPINFOHEADER {
    DWORD  biSize;
    LONG   biWidth;
    LONG   biHeight;
    WORD   biPlanes;
    WORD   biBitCount;
    DWORD  biCompression;
    DWORD  biSizeImage;
    LONG   biXPelsPerMeter;
    LONG   biYPelsPerMeter;
    DWORD  biClrUsed;
    DWORD  biClrImportant;
} BITMAPINFOHEADER;
biSize | Specifies the number of bytes required by the structure.
biWidth | Specifies the width of the bitmap, in pixels.
biHeight | Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB (device-independent bitmap) and its origin is the lower left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper left corner.
biPlanes | Specifies the number of planes for the target device. This value must be set to 1.
biBitCount | Specifies the number of bits per pixel. Some compression formats need this information to properly decode the colors in the pixel.
biCompression | Specifies the type of compression used or requested. Both existing and new compression formats use this member.
biSizeImage | Specifies the size, in bytes, of the image. This can be set to 0 for uncompressed RGB bitmaps.
biXPelsPerMeter | Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device.
biYPelsPerMeter | Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap.
biClrUsed | Specifies the number of color indices in the color table that are actually used by the bitmap. If this value is zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member for the compression mode specified by biCompression.
biClrImportant | Specifies the number of color indices that are considered important for displaying the bitmap. If this value is zero, all colors are important.

When the value in the biBitCount member is set to greater than eight, video drivers can assume bitmaps are true color and they do not use a color table.

When the value in the biBitCount member is set to less than or equal to eight, video drivers can assume the bitmap uses a palette or color table defined in the BITMAPINFO data structure. This data structure has the following members:

typedef struct tagBITMAPINFO {
    BITMAPINFOHEADER bmiHeader;
    RGBQUAD          bmiColors[1];
} BITMAPINFO;

The BITMAPINFO bmiheader member specifies a BITMAPINFOHEADER structure. The BITMAPINFO bmiColors member specifies an array of RGBQUAD data types that define the colors in the bitmap.

WAVEFORMATEX Structure

The WAVEFORMATEX structure contains information for the audio stream(s) of an AVI RIFF file. This structure has the following members:

typedef struct waveformat_extended_tag {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;
wFormatTag | Defines the audio waveform type of the audio stream. A complete list of format tags can be found in the MMREG.H header file included with Microsoft Visual C++ and other Microsoft products.
nChannels | Specifies the number of channels in the audio stream, 1 for mono, 2 for stereo.
nSamplesPerSec | Specifies the frequency of the sample rate of the audio stream in samples/second (Hz). Examples are 11,025, 22,050, or 44,100.
nAvgBytesPerSec | Specifies the average data rate. Playback software can estimate the buffer size by using this value.
nBlockAlign | Specifies the block alignment of the data, in bytes. Playback software must process a multiple of nBlockAlign bytes of data at a time, so that the value of nBlockAlign can be used for buffer alignment.
wBitsPerSample | Specifies the number of bits per sample per channel data. Each channel is assumed to have the same sample resolution. If this field is not needed, then you should set it to zero.
cbSize | Specifies the size, in bytes, of the extra information in the format header, not including the size of the WAVEFORMATEX structure. For example, in the wave format corresponding to the wFormatTag WAVE_FORMAT_IMA_ADPCM, cbSize is calculated as sizeof(IMAADPCMWAVEFORMAT) - sizeof(WAVEFORMATEX), which yields two.

AVI 2.0 File Format Extensions

DirectShow currently supports the following AVI 2.0 file format extensions:

  • Increased AVI file size (greater than 1 GB)
  • Hierarchical indexing

See the specification in version 1.02 of the OpenDML AVI File Format Extensions published by the OpenDML AVI M-JPEG File Format Subcommittee, February 28, 1996.


Registering a Custom File Type

This topic describes how to register a new file type so that file-reader source filters can recognize it. The mechanism used here is taken from the Microsoft® Win32® GetClassFile function, which is used to return the CLSID associated with the given file name. Microsoft DirectShow™ media types use the same quadruple set of values in the registry that are used for GetClassFile FileType registrations, but associate a file matching this criteria with a media type rather than a file type. Also, the registry entry for a DirectShow media type provides the CLSID of a source filter that can be used to read this media type.

For both FileType and MediaType registration, a pattern in the registry contains a series of entries of the form:

regdb key = offset, cb, mask, value

The media type is defined as a CLSID pair, {Majortype clsid, Subtype clsid}. If the data in the file at the specified offset or offsets matches a pattern in HKEY_CLASSES_ROOT\Media Type\{<major type>}\{<subtype>}, the media type CLSID pair associated with that pattern is the media type of the file.

The parameters of the registry key are interpreted as follows. The value of the offset item is an offset from the beginning or end of the file, and the cb item is a length in bytes. These two decimal values represent a particular byte range in the file. (A negative value for the offset item is interpreted from the end of the file.) The mask value is a hexadecimal bit mask that is used to perform a logical AND operation, with the byte range specified by offset and cb. The result of the logical AND operation is compared with the value item. If the mask is omitted, it is assumed to be all ones. The number of hexadecimal digits in mask and value must be twice the value of cb (because cb is in bytes).

Each pattern in the registry is compared to the file in the order of the patterns in the database. The first pattern where each of the value items matches the result of the AND operation determines the media type of the file.

Note that each entry can have multiple quadruples, all of which must match the data in the file for the media type to be associated with the file. An example of using multiple quadruples in a single entry might be to match the byte sequence at the beginning and at the end of the file. The following example shows a pattern of AB CD 12 34 as the first 4 bytes in the file and AB AB 00 AB as the last 4 bytes in the file (no masks applied here). All elements must match for the pattern to match a file with a media type.

0 = REG_SZ 0, 4, , ABCD1234,  -4, 4, , ABAB00AB

Additionally, there can be multiple entries specified under a single media type, a match to any one of which will associate the file with the media type.

For example, the pattern contained in the following entries of the registry requires that the first three bytes be AB CD 12, that the fourth byte be 32, 33, 34, or 35, and that the last 4 bytes be FE FE FE FE:

HKEY_CLASSES_ROOT
    Media Type
         {12345678-0000-0001-C000-000000000095}
                {87654321-0000-0001-C000-000000000095}
                    0 = REG_SZ 0, 4, FFFFFFFE, ABCD1234, -4, 4, , FEFEFEFE
                    1 = REG_SZ 0, 4, FFFFFFFE, ABCD1232, -4, 4, , FEFEFEFE
                    Source Filter = {56781234-0000-0001-C000-000000000095}

If a file contains such a pattern, the media type {12345678-0000-0001-C000-000000000095}{87654321-0000-0001-C000-000000000095} will be associated with this file. The file source filter for the media type is identified by the CLSID of the Source Filter value under the key for the media type.

The media type can be used to find filter handlers for the file in order to render it. A handler for a type performs a more exact test of the file to be sure of the type before attempting to render the data.

Note that this scheme allows for a set of alternative masks (for instance, .wav files) that might or might not have a RIFF header.


Transform Filters

This section describes how to create a transform filter, types of transform filters, how to use the transform base classes, which base class member functions to override and when, and how to connect transform filters.

Creating a Transform Filter

Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes

Connecting Transform Filters

About Compression Filters


Creating a Transform Filter

Transform filters transform the media data that comes into their input pins and send the transformed data out their output pins. Transform filters can be used to compress and decompress data, to split audio and visual data, or to apply effects, such as contrast or warbling, to media data. DirectShow contains several sample transform filters that perform different kinds of transformations. See DirectShow Filters for a description of the transform filters supplied by DirectShow. See Write a Transform Filter in C/C++ for instructions on how to write your own transform filters in C++. See Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes for a discussion of the CTransformFilter and CTransInPlaceFilter transform filter base classes. See Connecting Transform Filters for a discussion of connecting to a transform filter.

This article steps through the process of creating a transform filter for a Microsoft® DirectShow™ filter graph that uses the DirectShow C++ class library. It covers five basic steps, and in the last step shows how to override the required member functions in your derived class to implement the transform filter. It answers two common questions that arise when creating transform filters: Which base class do I use? and How do I override member functions?

Contents of this article:

  • Writing a Transform Filter
  • Determine if the Filter Must Copy Media Samples
  • Determine Which Base Classes to Use
  • Instantiate the Filter
  • Make Added Interfaces Available Through NonDelegatingQueryInterface
  • Override the Base Class Member Functions
    • Overriding the Transform Member Function
    • Overriding the CheckInputType Member Function
    • Overriding the CheckTransform Member Function
    • Overriding the DecideBufferSize Member Function
    • Overriding the GetMediaType Member Function
    • Overriding Pin Member Functions
    • Overriding the CBaseOutput::DecideAllocator Member Function

Writing a Transform Filter

Writing a transform filter can be broken into the following discrete steps.

  1. Determine if the filter must copy media samples or can handle them in place.

    The fewer copies in the media stream, the better. However, some filters require a copy operation; this influences the choice of base classes.

  2. Determine which base classes to use and derive the filter class (and pin classes, if necessary) from the base classes.

    In this step, create the header or headers for your filter. In many cases, you can use the transform base classes, derive your class from the correct transform filter class, and override a few member functions. In other cases, you can use the more generic base classes. These classes implement most of the connection and negotiation mechanism; but these classes also allow more flexibility at the cost of overriding more member functions.

  3. Add the code necessary to instantiate the filter.

    This step requires adding a static CreateInstance member function to your derived class and also a global array that contains the name of the filter, a CLSID, and a pointer to that member function.

  4. Add a NonDelegatingQueryInterface member function to pass out any unique interfaces in your filter.

    This step addresses the Component Object Model (COM) aspects of implementing interfaces, other than those in the base classes.

  5. Override the appropriate base class member functions.

    This includes writing the transform function that is unique to your filter and overriding a few member functions that are necessary for the connection process, such as setting the allocator size or providing media types.

Determine if the Filter Must Copy Media Samples

Because every copy operation uses valuable CPU cycles, filter developers are encouraged to avoid copying the media samples, if possible. It is best to write the filter to modify media samples in place on an allocator acquired from another filter. In some cases, this is not possible, and a copy operation must be performed.

Where no copy is needed, the run-time overhead of a transform-inplace filter is scarcely more than that of a function; however, by packaging the transform as a filter, you get the full flexibility of the filter graph architecture.

Some reasons that a filter might be written as a copy transform filter rather than a transform-inplace filter include the following:

  • If the transformation generates more data on output than space provided in the allocator of the input (for example, a decompressor filter), or if the transformation generates less data on output and must consolidate memory.
  • If the original media data must be preserved; this is the case with the splitter, where the transform filter splits off a stream of data.
  • If a decompressor filter is performing temporal compression, relying on adjacent frames for delta information. In this case, a separate copy must be made, primarily because the decompressor cannot allow another filter to have access to the original data to modify it.
  • If the filter relies on a queue; for example, a filter that creates a queue to help smooth the delivery of irregularly spaced video frames would need to copy the samples.

Determine Which Base Classes to Use

Before choosing a base class for your transform filter, you must first decide whether your filter needs more than one input and output pin. If it does, you should derive your filter class from CBaseFilter.

If your filter needs to perform a video transform, you should derive your filter class from CVideoTransformFilter.

Otherwise, you should derive your filter class from CTransformFilter or CTransInPlaceFilter. To determine which one to use, you must decide whether your filter must copy media samples or can transform them in place. Because every copy operation uses valuable CPU cycles, filter developers should avoid copying media samples, if possible. It is best to write a filter to modify media samples in place on an allocator acquired from another filter. In some cases, this isn't possible, and you must perform a copy operation.

Where no copy is needed, the run-time overhead of a transform-inplace filter isn't much more than that of a function. However, by packaging the transform as a filter, you get the full flexibility of the filter graph architecture.

Some reasons that you might write a filter as a copy transform filter rather than a transform-inplace filter are:

  • If the transformation generates more data on output than there is space already allocated for the input (for example, a decompressor filter), or if the transformation generates less data on output and must consolidate memory.
  • If the original media data must be preserved. This is the case with the splitter, where the transform filter splits off a stream of data.
  • If a decompressor filter is performing temporal compression, relying on adjacent frames for information about what has changed frame to frame. In this case, you must make a separate copy, primarily because the decompressor can't allow another filter to have access to the original data to modify it.
  • If the filter relies on a queue; for example, a filter that creates a queue to help smooth the delivery of irregularly spaced video frames would need to copy the samples.

Once you determine whether the transform filter will copy media samples or transform them in place, you must decide which base class or classes to use and which member functions you must override and implement. You can then define your derived classes.

Some member functions in the base classes must be overridden in your derived class because they are either declared as pure virtual in the base classes (they have no implementation), or have default implementations that do nothing but return an error value.

You derive your filter class from the transform base classes CTransformFilter, CTransInPlaceFilter, or CVideoTransformFilter, or from the more generic CBaseFilter filter class. Most of the connection, media type, and allocator negotiation code is handled in the base classes and inherited by the transform classes. The transform classes make it possible to create a filter by deriving just one filter class (no pin classes). The transform classes make assumptions about the workings of transform filters that make the process of creating a transform filter easier.

To learn more about CTransformFilter and CTransInPlaceFilter and which of their member functions are typically overridden by the derived class, see Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes.

Instantiate the Filter

All filters must add code to let the base classes instantiate the filter. To instantiate a filter, you must include two pieces of code in your filter: a static CreateInstance member function in the derived filter class, and a means of informing the class factory in the base classes how to access this function.

Typically, the CreateInstance member function calls the constructor for the derived filter class. The following is the CreateInstance member function from the Gargle sample filter.

CUnknown *CGargle::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {

    CGargle *pNewObject = new CGargle(NAME("Gargle Filter"), punk, phr);
    if (pNewObject == NULL) {
        *phr = E_OUTOFMEMORY;
    }

    return pNewObject;
} // CreateInstance

To communicate with the class factory, declare a global array of CFactoryTemplate objects as g_Templates and provide the name of your filter, the class identifier (CLSID) of your filter, and a pointer to the static CreateInstance member function that creates your filter object. The Gargle sample filter does this as follows:

// Needed for the CreateInstance mechanism
CFactoryTemplate g_Templates[2]=
    { { L"Gargle filter"              , &CLSID_Gargle , CGargle::CreateInstance          }
    , { L"Gargle filter Property Page", &CLSID_GargProp, CGargleProperties::CreateInstance}
    };

int g_cTemplates = sizeof(g_Templates)/sizeof(g_Templates[0]);

You can add additional parameters to the CFactoryTemplate templates if you want your filter to be self-registering. For more information on this, see Register DirectShow Objects.

Finally, link your filter to strmbase.lib and export DllGetClassObject and DllCanUnloadNow using a .def file.

Make Added Interfaces Available Through NonDelegatingQueryInterface

Only filters that add interfaces that are not in the base classes, such as those required for creating property pages, need implement the IUnknown member functions (called INonDelegatingUnknown in the base classes). The base classes provide default implementations of the IUnknown methods. IUnknown methods in any COM-based code retrieve interfaces from an object, and increment and decrement the reference counts of those interfaces. For example, the IUnknown::QueryInterface method retrieves interfaces from an object.

DirectShow defines a special IUnknown class called INonDelegatingUnknown, whose methods do the same thing as IUnknown. (The reason for the name change is so that objects can be aggregated.) The NonDelegatingQueryInterface method is called whenever some object or application wants to query a pin or filter for any interfaces it implements. If your filter implements any interface outside those listed in the base class implementation, you will need to override the NonDelegatingQueryInterface method to return a pointer to the implemented interface. For example, the following code example illustrates how the Gargle sample overrides the member function to distribute references to the ISpecifyPropertyPages and IPersistStream interfaces.

// Reveal our persistent stream, property pages, and IGargle interfaces
STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv) {

    if (riid == IID_IGargle) {
        return GetInterface((IGargle *) this, ppv);
    } else if (riid == IID_ISpecifyPropertyPages) {
        return GetInterface((ISpecifyPropertyPages *) this, ppv);
    } else if (riid == IID_IPersistStream) {
        AddRef();     // Add a reference count to ourselves
        *ppv = (void *)(IPersistStream *)this;
        return NOERROR;

    } else {
        return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
} // NonDelegatingQueryInterface

Note This sample calls the CTransInPlaceFilter implementation of the member function to finish up.

Override the Base Class Member Functions

When you determine which base class to use( see Determine Which Base Classes to Use), you write the header and define which member function to implement. You decide either to derive your filter class from the transform base classes (CTransformFilter or CTransInPlaceFilter), or from the more generic CBaseFilter filter class. In this section, you learn how to override the following member functions.

  • Overriding the Transform Member Function
  • Overriding the CheckInputType Member Function
  • Overriding the CheckTransform Member Function
  • Overriding the DecideBufferSize Member Function
  • Overriding the GetMediaType Member Function
  • Overriding Pin Member Functions
  • Overriding the CBaseOutput::DecideAllocator Member Function

Overriding the Transform Member Function

The Transform member function in your derived class is called each time the IMemInputPin::Receive method on the input pin of the filter is called to transfer another sample. Place the code that performs the actual purpose of the filter in this member function, or in the functions called from here. Copy transform filters will likely have a private Copy member function associated with the transform code, while transform-inplace functions will simply modify the code in one buffer.

Overriding the CheckInputType Member Function

During the pin connection, the CheckMediaType member function of the input pin is called to determine whether the proposed media type is acceptable. The CTransformInputPin::CheckMediaType member function is implemented to call the CheckInputType member function of the derived filter class with the media type. You must implement this to accommodate the media types your filter can handle. The following code sample outlines part of the CGargle::CheckInputType member function, which rejects any media type but MEDIATYPE_Audio.

HRESULT CGargle::CheckInputType(const CMediaType *pmt) {
    ...
    // reject non-Audio type
    if (pmt->majortype != MEDIATYPE_Audio) {
        return E_INVALIDARG;
    }

Overriding the CheckTransform Member Function

Copy transform filters can transform the media type from the input pin to output pin. Therefore, if the output pin is connected (so its media type is known), when the CTransformInputPin::CheckMediaType member function is called during connection, the CheckTransform member function of the derived class is called to verify that the transform from the input type to the output type is valid. It is also called when CTransformOutputPin::CheckMediaType is called.

In the CTransInPlaceFilter class, this member function is implemented in the base class header file to simply return S_OK, because the functions from CTransformFilter that call this member function are overridden in CTransInPlaceFilter to call CheckInputType instead. This assumes that the media type doesn't change in a transform-inplace filter, as it might in a copy transform filter.

Overriding the DecideBufferSize Member Function

Copy transform filters might be required to set the properties of the allocator into which they are copying. This is likely if the downstream filter has provided a newly created allocator (that is, one that hasn't passed an allocator from farther downstream), or if the output pin is forced to create its own allocator. In this case, the pure virtual CBaseOutputPin::DecideBufferSize member function is called from the CBaseOutputPin::DecideAllocator member function, and the derived class fills in the requirements for the buffer by calling the IMemAllocator::SetProperties method on the allocator object to which it has a reference.

The CTransInPlaceFilter::DecideBufferSize method is never called, because the allocator of another filter is always in use. It is implemented in the base class header file to return E_UNEXPECTED.

Overriding the GetMediaType Member Function

Pins provide enumerators to enable other objects to determine the pin's media type. A pin provides the media type enumerator (the IEnumMediaTypes interface), which the pin base classes implement to call the GetMediaType member function in the pin class. In the copy transform filter classes, each pin's CTransformOutputPin::GetMediaType member function simply calls the virtual CTransformFilter::GetMediaType member function in the filter class. Your derived class must implement this member function to provide each supported media type in a list of media types.

In the transform-inplace classes, the enumerators form a transparent channel between the filters upstream and downstream from the transform filter. If the transform filter's input pin must perform an enumeration, it obtains an enumerator from the downstream filter's input pin. If the output pin must perform an enumeration, it obtains an enumerator from the upstream filter's output pin. One consequence of this is that transform-inplace filters can't connect to each other unless at least one of them is connected to something else, because neither of the transform-inplace filters can propose any media type for the connection.

Overriding Pin Member Functions

If you derived your filter class from the transform classes and want more than one input or output pin, you must override the pin class (for example, CTransformInputPin or CTransformOutputPin). If you override the pin class, you must also override the GetPin member function of CTransformFilter or CTransInPlaceFilter, so that you can create pin objects from your derived classes. If you override one of the pin classes (for example, CTransformInputPin) and override GetPin to create the pin object, you must also override GetPin to create the other pin object of the same base class (for example, CTransformOutputPin).

If you want more than one input or output pin, it is often simpler to derive your filter from CBaseFilter rather than from one of the transform classes.

Overriding the CBaseOutput::DecideAllocator Member Function

The base classes implement CBaseOutputPin::DecideAllocator to let the output pin automatically use the downstream pin's allocator. One of the most common alterations in the derived class is to force the use of an object's own allocator (or one from an upstream filter). In the DirectShow model, for example, a source filter pushes media samples onto the next filter and requires its own allocator. For example, if you write a transform-inplace filter and insert it between a source filter and a decompressor filter, the transform filter must present the source filter's allocator to the decompressor. Therefore, you must override the CBaseOutputPin::DecideAllocator member function.


DirectShow Animated Header -- Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes DirectShow Animated Header -- Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes * Microsoft DirectShow SDK
  * Previous Topic: Creating a Transform Filter
  * Next Topic: Connecting Transform Filters

Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes

This article describes the classes provided for creating a transform filter. It is background information that you should read before reading the article Creating a Transform Filter, which walks through the steps of creating a transform filter.

Contents of this article:

  • Introducing the CTransformFilter and CTransInPlaceFilter Classes
  • What the Derived Class Must Provide
  • A Sample Transform Filter Declaration

Introducing the CTransformFilter and CTransInPlaceFilter Classes

The easiest solution for writing a transform filter is to use the transform filter classes, which work well for most types of transform filters. Typically, a noncopying transform filter is derived from the CTransInPlaceFilter class and its associated pin classes; a copy transform filter is derived from the CTransformFilter filter class and its associated pin classes.

Transform filter classes are hierarchical, with the transform-inplace classes at the bottom of the hierarchy tree. CTransInPlaceFilter is derived from CTransformFilter, which is derived from CBaseFilter, as shown in the following illustration.

CTransInPlaceFilter class hierarchy

The CTransInPlaceInputPin class is derived from the CTransformInputPin class. The CTransformInputPin class is derived from the CBaseInputPin class, as shown in the following illustration.

CTransInPlaceInputPin class hierarchy

The CTransInPlaceOutputPin class is derived from the CTransformOutputPin class. The CTransformOutputPin class is derived from the CBaseOutputPin class, as shown in the following illustration.

CTransInPlaceOutputPin class hierarchy

Copy transform and transform-inplace classes share many features, because the transform-inplace classes derive almost all member functions from the copy transform classes. The principal additions made by the transform classes over the base classes is that all required pin member functions are implemented—so for default implementation, you need only to derive a main filter class (from CTransInPlaceFilter or CTransformFilter).

What the Derived Class Must Provide

The derived filter class must provide a few member functions, typically to:

  • Determine if the filter accepts the media type.
  • Specify the count and size of any required allocators (for copy transforms only).
  • Provide the transform functionality of the filter.

All derived filter classes must implement a static CFactoryTemplate::CreateInstance function. You can also choose to override the CBaseFilter::GetSetupData member function to make your filter self-registering. Beyond this, your classes must override a few member functions in the transform base classes. For more information about instantiating the filter, see Creating a Transform Filter.

If your derived filter class is based on the CTransformFilter class, you must override the following member functions.
Member function | Description
Transform | Implement transform.
CheckInputType | Verify support of media type.
CheckTransform | Verify support for transforming this type (for debugging builds only).
DecideBufferSize | Set size and count when copying.
GetMediaType | Suggest media types for the output pin.

If your derived filter class is based on the CTransInPlaceFilter class, override the following member functions.
Member function | Description
Transform | Implement transform.
CheckInputType | Verify support of media type.

Beyond providing your transform filter with a default implementation by providing the minimum overrides, you can override other member functions to provide more specialized behavior. Which member functions you override, of course, depends on what you want your filter to do. For example, you must override the GetPin and GetPinCount member functions if you want to have more than one input pin and one output pin on the filter.

Also, several base class member functions, such as BreakConnect or CompleteConnect, are called as notifications to your filter through the pins. Typically, most of these member functions exist only on the pins. In the classes based on CTransformFilter, the pin functions are implemented to call similarly named functions in the filter class. This means that the member functions you most likely will want to override are all collected into one filter class, so you can leave the pin classes unchanged, making implementation smaller and easier. These member functions are as follows:
Member function | Reason to override
NonDelegatingQueryInterface | To distribute any interfaces added in the derived class.
GetPinCount | If adding more pins to the transform filter.
GetPin | If adding more pins to the transform filter.
CheckConnect | To obtain extra interfaces at connect time or for other reasons.
BreakConnect | To release extra interfaces when connection is broken or for other reasons.
CompleteConnect | To perform some action at the end of connection (such as reconnecting the input pin).
SetMediaType | To be notified when the media type has been set.
StartStreaming | To be notified when entering the streaming state.
StopStreaming | To be notified when exiting the streaming state.
AlterQuality | To do anything with quality-control messages other than passing them on.

A Sample Transform Filter Declaration

An example of a filter derived from a transform class is the NullNull sample filter. This sample illustrates a true minimalist filter, which does nothing except demonstrate the least you must implement for a filter. It uses the transform-inplace classes and derives its filter class from the CTransInPlaceFilter class. Following is the class declaration for the derived filter class CNullNull.

// CNullNull
//
class CNullNull
    : public CTransInPlaceFilter
{

public:

    static CUnknown *CreateInstance(LPUNKNOWN punk, HRESULT *phr);

    DECLARE_IUNKNOWN;

    LPAMOVIESETUP_FILTER GetSetupData()
    {
        return &sudNullNull;
    }

private:

    // Constructor - just calls the base class constructor
    CNullNull(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
        : CTransInPlaceFilter (tszName, punk, CLSID_NullNull, phr)
    { }

    // Overrides the PURE virtual Transform of CTransInPlaceFilter base class
    // This is where the "real work" is done by altering *pSample.
    // We do the Null transform by leaving it alone.
    HRESULT Transform(IMediaSample *pSample){ return NOERROR; }

    // We accept any input type.  We'd return S_FALSE for any we didn't like.
    HRESULT CheckInputType(const CMediaType* mtIn) { return S_OK; }
};

This example illustrates the basic member functions required in the base class:
CreateInstance | Needed by every filter so that it can be instantiated as a COM object.
GetSetupData | Overrides CBaseFilter::GetSetupData and is used to provide the class with information required to register this particular filter. In this case, it provides the address of a structure defined in the Nullnull.cpp file included in the SDK.
CNullNull | Class constructor, which typically just calls the base class constructor.
Transform | Overrides CTransInPlaceFilter::Transform and does the main work of CNullNull, which in this case is nothing.
CheckInputType | Overrides CTransInPlaceFilter::CheckInputType to verify the media type during connection, and in this case accepts any media type offered, since it will simply pass it along to the next filter in line.

Note that, strictly speaking, GetSetupData is required only if you want your filter to be self-registering. However, since the base classes implement this feature and it is easy to implement, it is a good idea to include this in your base class.


Connecting Transform Filters

This article describes some of the connection issues faced when creating a transform filter. Connecting any two filters requires negotiating which media types to use and deciding on a common allocator for passing samples. Since transform filters are connected on both sides, and since some transform filters use the media types and allocators of other filters in the graph, it is important to understand the concepts involved in transform filter connections.

Contents of this article:

  • How Allocator Negotiation Works
  • Establishing Media Type Connections

How Allocator Negotiation Works

For information about the connection process, including media type and allocator negotiation, see Connection Model. When you are determining your transform filter characteristics, it might help for you to understand the model of allocator negotiation for transform filters.

If your transform filter requires copying, then it will copy media samples from a buffer established by its input pin to a buffer established by its output pin. These buffers are provided by allocators that might actually be located in other filters, perhaps even several filters removed if the filters in between do not copy the data.

A copying transform filter typically tries to use the allocator of the upstream filter for its input pin, and the allocator of the downstream filter for its output pin. During the connection process, the output pin of the upstream filter determines which allocator to use for the upstream transport, so the input pin of the copy transform must be prepared to create an allocator for the upstream transport if its IMemInputPin::GetAllocator method is called by the connecting output pin. The base classes provide a way to create a new allocator from the input pin of any connection.

On the other hand, transform-inplace filters do not make copies, but rather modify the data in an existing buffer. These filters should always offer the allocator from the downstream filter to the upstream filter. This requires a reconnection, because the filter does not know about the downstream filter when its input pin is first connected. Also, because inplace-transforms do not change the media type, the media type from the downstream filter should be offered to the upstream filter upon reconnection.

Connecting Filter Graphs: An Example

To better understand the allocation model for a transform-inplace filter, the following illustration shows a simple and common example of a filter graph.

Filter graph example

This simple example demonstrates the model of the transform-inplace filter offering its downstream allocator to its upstream filter. Consider what happens when InPlace E is connected to VidRen F.

Upon connection, the video renderer filter (VidRen F) offers its allocator for use by the upstream inplace filter (InPlace E). Because it is a transform-inplace filter, InPlace E offers the allocator to the next filter upstream, InPlace D, and so on. This reconnection and renegotiation occurs until it encounters either the source filter or a copy transform filter. In this case it meets a decompressor, CopyDec C. (The copy transform filter cannot offer its allocator upstream, because it must perform a copy operation.) So the decompressor will be writing directly to the video renderer's buffer, which might be a DirectDraw® surface. This demonstrates why it is a good practice to write a transform filter as a transform-inplace filter and pass allocators from the renderer upstream, if possible.

On the other hand, consider filters InPlace B and CopyDec C. What if the downstream filter from a transform-inplace filter is a copy transform filter instead of a renderer? In this case, the copy transform filter will offer to create its own allocator on its input pin (the base classes handle this), and the transform-inplace filter can then offer that allocator downstream upon reconnection (the same as if it were connected to a renderer filter).

However, even though CopyDec C can create its own allocator (from its IMemInputPin::GetAllocator method), the source filter, Source A, uses its own buffer—say, a file. So when InPlace B connects to CopyDec C, InPlace B will have accepted the source filter's allocator already and will force that allocator to be used for the transport between itself and the decompressor filter. InPlace B can then provide the upstream filter, Source A, with the option of using the allocator offered by CopyDec C, but the source filter will refuse this allocator so that an extra copy does not have to be made from the file buffer to the decompressor's input buffer.

Therefore, any upstream filter can force the use of its allocator downstream but should have good reason to do so (such as if it already has a buffer). In this example, only one copy is being made (by the decompression filter) between the file buffer and the video memory.

Establishing Media Type Connections

When pins from different filters are connected, they must both agree on a common media type for the samples they will exchange. A quick review of the connection mechanism might help highlight how transform filters handle media type negotiations.

This section contains the following topics.

  • The Connection Process: A Summary
  • When Reconnections Occur

The Connection Process: A Summary

When one filter's output pin is called by the filter graph manager to connect to an input pin of a second filter, the IPin::Connect method is called. This, in turn, calls CBaseOutputPin::CheckConnect to obtain interfaces from the connected pin and CBasePin::AgreeMediaType to find a common media type.

AgreeMediaType calls CBasePin::TryMediaTypes, which uses media type enumerators to query the pins for preferred media types. IEnumMediaTypes is an interface on the connected input pin that TryMediaTypes uses first. The base classes use IEnumMediaTypes to repeatedly call a CBasePin member function called GetMediaType for each media type in the list. You use this member function in your input and output pin classes to return the media types that your pin prefers.

TryMediaTypes calls the output pin's CheckMediaType member function with each input type returned. You must use CheckMediaType to verify whether this type is acceptable. If no media types are found (for example GetMediaType may not even be used on the connected input pin, or may return an unacceptable media type), then AgreeMediaType obtains a media type enumerator for the output pin and tries each of these in turn. Again, the GetMediaType member function of the derived output pin is called for each type. In this case, it can determine media types by inquiring about any existing connection established by the filter's input pin.

When Reconnections Occur

For transform filters that do not modify the media type from input pin to output pin (such as most in-place transforms and many copy transforms), a reconnection scheme must be in place for offering the downstream filter's media type to the upstream filter. To understand this, consider the media type negotiation of the transform-inplace Filter B in the following illustration.

Diagram showing arrangement of filters and pins

The input pin of Filter B is connected first and establishes a media type with the upstream output pin (AOutPin). When the output pin of Filter B is connected next, it must use the enumerator from the output pin of the connected upstream filter (AOutPin), because it does not have one of its own.

If the pin of the downstream filter, CInPin, can accept this, then the connection is complete. However, assume that Filter C does not agree to this media type but proposes a media type that Filter B can handle.

Before deciding that it can handle the media type, Filter B calls the IPin::QueryAccept method on AOutPin to ensure that it is acceptable. If no media type can be found that is acceptable for all the filters, then the BOutPin to CInPin connection will fail. (It is possible to find that a transform-inplace filter will connect to either its upstream or its downstream neighbors, but not both simultaneously.)

If a suitable type is found, BOutPin must force a reconnection on the entire filter, and pass the established media type (the media type of CInPin) to AOutPin, when AOutPin and BInPin are connected again.


About Compression Filters

A compression filter is a specialized type of transform filter. Compression filters (compressors) accept data, use a compression scheme to transform the data, and pass the compressed data downstream.

Microsoft® DirectShow™ includes an AVI Compressor filter and an ACM Audio Compressor filter, which will use any Microsoft Video for Windows® video or audio codec to compress data. You can write your own compressor filter if you need to compress data in a format that isn't supported by the default filters that DirectShow provides.

To begin writing a compression filter, write a transform filter that includes one input pin and one output pin. See the following articles for more information about writing a transform filter.

  • Creating a Transform Filter
  • Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes
  • Connecting Transform Filters

After you've written a transform filter, you should review the following points when completing your compression filter:

  • Register your filter.

    Register your compression filter by using the AMovieDllRegisterServer2 function. This enables applications to enumerate your filter with all the other compression filters on the system. See Enumerate and Access Hardware Devices in DirectShow Applications for more information about device enumeration.

  • Implement the recommended compressor interfaces.

    It is strongly recommended that you implement the IAMStreamConfig interface on the output pin of all compression filters and IAMVideoCompression on the output pin of video compressors so that applications can access the compression features of your filter.

    IAMStreamConfig enables you to inform applications about the formats to which you can compress data, and enables the application to configure your compressor to compress to a particular data type.

    IAMVideoCompression enables an application set video-specific settings, like keyframe frequency, that do not appear in the AM_MEDIA_TYPE structure.

The VidCap Sample (Video Capture Filter) sample video capture filter included with the DirectShow SDK implements the IAMStreamConfig and IAMVideoCompression interfaces, and performs filter registration. Note that this sample code is for a capture filter, but the filter registration and implementation of these two interfaces is similar to that of a compression filter.


About Effect Filters

In DirectShow, effect filters are defined as filters that apply an effect to media data, but don't change the media type. DirectShow provides several effect filters, including Contrast, Gargle, and EzRGB24. Effect filters can apply a wide range of useful video and audio effects to media data.

Contents of this article:

  • Creating Effect Filters
  • List of DirectShow Effect Filters and Samples

Creating Effect Filters

Because the input and output media formats are the same, and the applied effect can't change the format, effect filters often contain a code that checks the media formatting. If the filter derives from one of the transform filter base classes, CTransformFilter or CTransInPlaceFilter, the filter typically checks the format with the CheckMediaType, CheckInputType, and CheckTransform methods. If the filter doesn't derive from one of the transform filter base classes, its pins typically check the format by calling the CBasePin::CheckMediaType member function. See Negotiating Media Types with CBasePin::AgreeMediaType for more information.

You should choose a base class for your effect filter class that provides the greatest amount of the functionality you need. Often, the base class will be one of the transform filter base classes. If none of the higher-level base classes support your required functionality, you can choose CBaseFilter or CBasePin as your base class.

Your effect filter must implement the IPersistStream interface if you want to save the state of your effects in the Filter Graph Editor. To access this interface, derive your effect filter class from CPersistStream and query for the IPersistStream interface. Saving the filter's state can be helpful during design, but it is often useful to have the effect filter return to a default state when the Filter Graph Editor closes it, in which case you don't need to implement IPersistStream.

If you want the user to be able to manipulate the effect, you must create and display your effect filter's property page and provide a mechanism for returning the user's input to the filter. To do this, implement a property page class, the ISpecifyPropertyPages interface (which exposes property pages), and a custom interface that changes property page values. Typically, property pages use controls such as a slider, button, or check box to receive user input. You also must provide the resource file that displays the controls on the property page.

To implement the property page class, create a class that derives from CBasePropertyPage and implement the OnReceiveMessage method, the CPersistStream::SetDirty method, and a data member for each effect parameter. To access the two interfaces, derive your effect filter class from ISpecifyPropertyPages and the custom interface, and then query for the interfaces. You can query for all the interfaces you need by overriding the NonDelegatingQueryInterface method as shown in the following code from the Gargle sample (IGargle is the custom interface):

STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    CheckPointer(ppv,E_POINTER);
    if (riid == IID_IGargle) {
        return GetInterface((IGargle *) this, ppv);
    } else if (riid == IID_ISpecifyPropertyPages) {
        return GetInterface((ISpecifyPropertyPages *) this, ppv);
    } else if (riid == IID_IPersistStream) {
        return GetInterface((IPersistStream *) this, ppv);
    } else {
        return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
}

The effect filter's custom interface typically supplies a put and a get method for each effect parameter. For example, the IGargle custom interface supplies put_GargleRate and get_GargleRate methods. The IContrast custom interface in the Contrast sample supplies put_ContrastLevel and get_ContrastLevel methods. When the user accesses one of the controls on the property page, the page generates a windows message. The property page class's OnReceiveMessage member function handles this message. The following code fragment from the Contrast sample demonstrates this message generation and handling. IDB_DEFAULT is the resource ID of the Default button. The user clicks this button to set the video contrast to its default state. The CContrastProperties class implements the property page and the IContrast::put_DefaultContrastLevel method sets the contrast level to its default value.

BOOL CContrastProperties::OnReceiveMessage(HWND hwnd, UINT uMsg,
                                WPARAM wParam, LPARAM lParam)
{
    switch (uMsg)
    {
       case WM_COMMAND:
        {
          if (LOWORD(wParam) == IDB_DEFAULT)
            {
            pIContrast()->put_DefaultContrastLevel();
            SendMessage(m_hwndSlider, TBM_SETPOS, TRUE, 0L);
              SetDirty();
        }
            return (LRESULT) 1;
        }
...

Effect filters use critical sections internally to protect the global filter state. Effect filters can lock a critical section to ensure that data flow through the filter graph is serialized and that the global filter state doesn't change while an effect is occurring. DirectShow locks a critical section by declaring a CAutoLock class object. Typically, effect filters lock the critical section as soon as they enter the function that applies the effect. For example, in the following code fragment from the Gargle sample, the function that applies the effect is MessItAbout:

CCritSec   m_GargleLock; // Declare the critical section data member in the effect filter class definition

void CGargle::MessItAbout(PBYTE pb, int cb)
{
    CAutoLock foo(&m_GargleLock);

The put and get methods of the effect properties (for example, put_GargleRate) typically lock the critical section so effect values can't change in the middle of an update.

List of DirectShow Effect Filters and Samples

The DirectShow SDK ships with the following effect filters. You can find these filters in the Samples directory. All the source code is included.

Contrast: This effect filter adjusts the contrast of the video images sent through it. The filter adjusts the contrast by using palettes, because an image's color palette effectively determines how the image is interpreted by the display device; that is, how the value 23 (for example) maps into an RGB triplet for display. By changing the palette, you can reduce and increase contrast without doing anything to the image pixels themselves. The Filter Graph Editor lists this filter as Video Contrast.

EzRGB24: This effect filter modifies decompressed video images sent through it. It creates color and image filtering effects through simple techniques such as adjusting the red, green, or blue levels (to change the playback color) and by averaging neighboring pixels (to achieve blur and embossed (raised) effects). The Filter Graph Editor lists this filter as Image Effects.

Gargle: This effect filter modifies audio data sent through it. A synthesized wave function modulates the audio data's amplitude. The secondary wave can be a triangular or square wave, and can have different frequencies. At low modulation frequencies it sounds like a tremolo. At high modulation frequencies it sounds like a distortion. The Filter Graph Editor lists this filter as Gargle.


Video Renderers

This section describes how to write and use video renderers, both full-screen and custom renderers. It discusses how and why to support a full-screen renderer, and how to handle notifications, state changes, and dynamic format changes in a custom renderer.

Full-Screen Video Renderer

Alternative Video Renderers


Full-Screen Video Renderer

This article explains the logic used by the default Microsoft® IVideoWindow plug-in distributor (PID), when an application instructs it to render the video in full-screen mode. Substitute renderer filters can use the IVideoWindow PID for communication with applications. Developers of substitute renderers should be aware of how this PID searches the filter graph for the best means of representing full-screen video, when requested to render in full-screen mode.

Contents of this article:

  • Using the IVideoWindow PID to Implement Full-Screen Support
  • Finding a Filter That Supports Full-Screen Mode
  • Finding a Filter That Can Be Stretched Full-Screen at No Cost
  • Supplying a Full-Screen Renderer Filter
  • Stretching the Output of a Renderer Full-Screen
  • Implications of Full-Screen Support for the Application

Using the IVideoWindow PID to Implement Full-Screen Support

Microsoft® DirectShow™ implements full-screen support in a number of ways that depend on what hardware resources are available. An application can support full-screen video playback through the IVideoWindow interface provided by the filter graph manager. An application can have its own implementation of full-screen playback, but it can probably make better use of resources by using the IVideoWindow implementation.

The IVideoWindow plug-in distributor (PID) tries three different options for implementing full-screen support when an application requests full-screen mode. The option is typically chosen the first time the filter graph enters full-screen mode. While in full-screen mode, no IVideoWindow methods can be called (apart from accessing the full-screen property). Any attempts to do so will return the VFW_E_IN_FULLSCREEN_MODE message. The PID searches in the following order for a filter that supports IVideoWindow and that has one of these characteristics:

  1. The filter supplies full-screen mode directly.
  2. The filter allows its window to be stretched to full screen without penalty.
  3. The filter can be replaced by a full-screen renderer.

If none of these three options are found, the default is to simply stretch the video of a filter that supports IVideoWindow to full-screen, ignoring the performance penalties.

Finding a Filter That Supports Full-Screen Mode

The first option is to search for a filter in the filter graph that supports full-screen mode directly. When asked to go into full-screen mode, the IVideoWindow PID first scans all filters supporting IVideoWindow in the filter graph. The PID calls IVideoWindow::get_FullScreenMode on each filter and, if the filter returns E_NOTIMP (the default), assumes that the filter has no inherent support for full-screen playback. If the filter returns anything else, then that filter becomes the nominated filter for full-screen playback. This means that any calls to the filter graph manager to set the full-screen mode on or off will be sent directly to that nominated filter. This mechanism allows filters to be extended to support full-screen support directly. Most normal window-based renderers do not need to support this feature.

Finding a Filter That Can Be Stretched Full-Screen at No Cost

If a full-screen rendering filter can't be found, then the PID tries to find a filter supporting the IVideoWindow interface that can have its window stretched full-screen without penalty. The PID does this by scanning the list of filters in the filter graph that support IVideoWindow. For each filter found, the PID calls IVideoWindow::GetMaxIdealImageSize. If a filter indicates that its window can be stretched full-screen at no cost, then that becomes the nominated filter.

If that nominated filter is then requested to render full-screen, the PID resets a number of the filter's IVideoWindow properties and stretches the window to full-screen. This typically means setting a null owner, changing the window styles to not show the border or the caption, and updating the window position to match the current display size. When full-screen mode is switched off, the properties on the filter will be reset to the state prior to the full-screen mode.

Most video renderers supporting IVideoWindow cannot return the maximum ideal image size until they have been activated (either paused or running), because that is when they allocate their resources. For this reason, when scanning the list of filters while the filter graph is in a stopped state, the PID pauses each filter before calling IVideoWindow::GetMaxIdealImageSize. After calling this method, the filter is stopped again.

Supplying a Full-Screen Renderer Filter

If neither of the previous options were successful, then the PID finds the first available filter in the filter graph that supports an IVideoWindow interface, and assumes that it is the current video renderer filter.

If no filters that support IVideoWindow are available, the call to change to full-screen mode will return VFW_E_NO_FULLSCREEN. When asked to change into full-screen mode, the PID stops the filter graph, if it is not already stopped, disconnects the current renderer, and reconnects the DirectShow full-screen renderer in its place. If the connection succeeds, then the filter graph is restored to its original state. When switching out of full-screen mode, the opposite occurs. That is, the full-screen renderer is disconnected and the original filter is reconnected. The state of the filter graph is likewise restored. The full-screen renderer is a specialized renderer that uses the display changing capabilities provided by DirectDraw®. For example, it might switch the full-screen display 320 × 240 when it might have been in, for example, 1024 × 768. By switching to lower resolution modes, it can cheaply implement full-screen rendering without having to stretch images.

The full-screen renderer currently implements 320 × 200 × 8/16 bits per pixel, 320 × 240 × 8/16, 640 × 400 × 8/16, 640 × 400 × 8/16, 640 × 480 × 8/16, 800 × 600 × 8/16, 1024 × 768 × 8/16, 1152 × 864 × 8/16, and 1280 × 1024 × 8/16 display modes. The Modex renderer supports the IFullScreenVideo interface. When the modex renderer is connected, it loads the display modes DirectDraw has made available. The number of modes available can be obtained through IFullScreenVideo::CountModes. Information on each mode is available by calling IFullScreenVideo::GetModeInfo and IFullScreenVideo::IsModeAvailable. An application can enable and disable any modes by calling the SetEnabled flag with OATRUE or OAFALSE. The current value can be queried for with IFullScreenVideo::IsModeEnabled.

Another way to set the modes enabled is to use the clip loss factor. This defines the amount of video that can be lost when deciding which display mode to use. Assuming the decoder cannot compress the video, then playing, for example, an MPEG file that is 352 × 288 pixels into a 320 × 200 display will lose over 40 percent of the image. The clip loss factor specifies the upper range of clipping loss that is permissible. To allow typical MPEG video to be played in 320 × 200 it defaults to 50 percent. You can set the clip loss factor with IFullScreenVideo::SetClipFactor.

Stretching the Output of a Renderer Full-Screen

After trying the first three options, the final option for implementing full-screen support is to pick any filter enabled by IVideoWindow and stretch its window full-screen, regardless of the resulting poor performance. Essentially, the first filter in the filter graph that is enabled by the IVideoWindow interface becomes the nominated filter. This filter is then used in the same manner as if it was a filter that could be stretched full-screen without sacrificing performance (that is, the owner is reset, the styles changed, and the window position changed to match the display extents).

The cost of stretching a window full-screen where there is an implicit performance penalty varies, depending on the resolution currently displayed. The worst scenario is one in which the user is using a relatively high resolution (for example, 1024 × 768) and the images must be stretched by the renderer using GDI. This is likely to provide very low frame throughput and is used only as a last resort.

Implications of Full-Screen Support for the Application

While the interface exposed to applications is relatively simple, the underlying implementation can be more complex. The full-screen renderer has some special properties that application developers should be aware of. In particular, the renderer changes display modes only when activated (either paused or running). Therefore, if the filter graph is stopped when switching to full-screen mode, no change might be obviously visible until the filter graph is started again. When the filter graph is subsequently run, the display mode will change and the full-screen rendering will start.

If a window is being stretched full-screen (that is, no full-screen renderer is being used), the change will be viewable when the full-screen mode is set, regardless of state. If full-screen playback is being supported directly by a filter in the filter graph, it might elect to copy the behavior of the full-screen renderer and switch to full-screen only when activated. The filter supporting full-screen playback might have to do this, because the resources they require to play full-screen might not be available until then. Therefore, an application should avoid setting full-screen mode when stopped.

This makes sense in a user interface context as well, because if full-screen mode is set when the filter graph is stopped, users are unlikely to be able to start the graph running without switching out of full-screen mode (that is, tabbing back to the original application).

All renderers that implement IVideoWindow send event codes to the filter graph manager when their windows are activated or deactivated. When in full-screen mode, the PID watches for these event codes. When it sees a window that it made full-screen being deactivated, it will automatically switch out of full-screen mode and send an EC_FULLSCREEN_LOST notification to the application event queue. This is the only interference caused by the PID; all other user interface is left open to the application as described in the remainder of this article.

One of the most important aspects of full-screen playback is that when in full-screen mode, no window can be displayed on top of the full-screen window. In fact, when the full-screen renderer switches display modes, it disables all GDI output for other applications, so displaying a window on top of a full-screen window is actually impossible. Any user interactions with the computer must be done through hot keys.

Whatever mechanism the PID ultimately uses to implement full-screen playback, it always ensures that the message drain property is set on the window executing the playback. (The message drain specifies a window that will be forwarded all Windows® messages sent to the renderer.) So, even if the full-screen renderer is used, as long as a message drain has previously been set on the filter graph manager's IVideoWindow interface, all messages will be passed on to that renderer.

Because the message drain is set on the appropriate window, an application can rely on receiving all mouse and keyboard messages when in full-screen mode, regardless of which filter is implementing it. An application can use this fact to implement hot-key support for seeking, for example. However, properties can be set only when not in full-screen mode, so if the only time an application is required to catch messages is when it is in full-screen mode, it must set the message drain before setting full-screen on. Likewise, the message drain can be reset only after setting full-screen mode off.

One other application consideration is that, when in full-screen mode, any source and destination rectangles set through IBasicVideo will not be adhered to. The PID resets these rectangles when switching to full-screen mode. It does this because not all filters implementing full-screen support can guarantee to support IBasicVideo as well.


Alternative Video Renderers

This article describes some of the more complicated implementation requirements of a renderer; these apply to most renderers, although some aspects are video-specific (such as EC_REPAINT and other notifications). In particular, it discusses how to handle various notifications, state changes, and format changes. It also provides a summary of the notifications that a renderer is responsible for sending to the filter graph manager.

Contents of this article:

  • Writing an Alternative Renderer
  • Handling End-of-stream and Flushing Notifications
  • Handling State Changes and Pause Completion
  • Handling Termination
  • Handling Dynamic Format Changes
  • Handling Persistent Properties
  • Handling EC_REPAINT Notifications
  • Handling Notifications in Full-Screen Mode
  • Summary of Notifications

Writing an Alternative Renderer

Microsoft® DirectShow™ provides a window-based video renderer; it also provides a full-screen renderer in the run-time installation. You can use the C++ classes in the DirectShow SDK to write alternative video renderers. For alternative renderers to interact correctly with DirectShow-based applications, the renderers must adhere to the guidelines outlined in this article. You can use the CBaseRenderer and CBaseVideoRenderer classes to help follow these guidelines when implementing an alternative video render. Consult the SampVid sample in the DirectShow SDK for an example of an alternative video renderer that uses these classes. Because of the ongoing development of DirectShow, review your implementation periodically to ensure that the renderers are compatible with the most recent version of DirectShow.

This article discusses many notifications that a renderer is responsible for handling. A brief review of DirectShow notifications might help to set the stage. There are essentially three kinds of notifications that occur in DirectShow:

  • Stream notifications, which are events that occur in the media stream and are passed from one filter to the next. These can be begin-flushing, end-flushing or end-of-stream notifications and are sent by calling the appropriate method on the downstream filter's input pin (for example IPin::BeginFlush).
  • Filter graph manager notifications, which are events sent from a filter to the filter graph manager such as EC_COMPLETE. This is accomplished by calling the IMediaEventSink::Notify method on the filter graph manager.
  • Application notifications, which are retrieved from the filter graph manager by the controlling application. An application calls the IMediaEvent::GetEvent method on the filter graph manager to retrieve these events. Often, the filter graph manager passes through the events it receives to the application.

This article discusses the responsibility of the renderer filter in handling stream notifications it receives and in sending appropriate filter graph manager notifications.

Handling End-of-stream and Flushing Notifications

An end-of-stream notification begins at an upstream filter (such as the source filter) when that filter detects that it can send no more data. It is passed through every filter in the graph and eventually ends at the renderer, which is responsible for subsequently sending an EC_COMPLETE notification to the filter graph manager. Renderers have special responsibilities when it comes to handling these notifications.

A renderer receives an end-of-stream notification when its input pin's IPin::EndOfStream method is called by the upstream filter. A renderer should note this notification and continue to render any data it has already received. Once all remaining data has been received, the renderer should send an EC_COMPLETE notification to the filter graph manager. The EC_COMPLETE notification should be sent only once by a renderer each time it reaches the end of a stream. Furthermore, EC_COMPLETE notifications must never be sent except when the filter graph is running. Therefore, if the filter graph is paused when a source filter sends an end-of-stream notification, then EC_COMPLETE should not be sent until the filter graph is finally run.

Any calls to the IMemInputPin::Receive or IMemInputPin::ReceiveMultiple methods after an end-of-stream notification is signaled should be rejected. E_UNEXPECTED is the most appropriate error message to return in this case.

When a filter graph is stopped, any cached end-of-stream notification should be cleared and not resent when next started. This is because the filter graph manager always pauses all filters just before running them so that proper flushing occurs. So, for example, if the filter graph is paused and an end-of-stream notification is received, and then the filter graph is stopped, the renderer should not send an EC_COMPLETE notification when it is subsequently run. If no seeks have occurred, the source filter will automatically send another end-of-stream notification during the pause state that precedes a run state. If, on the other hand, a seek has occurred while the filter graph is stopped, then the source filter might have data to send, so it won't send an end-of-stream notification.

Video renderers often depend on end-of-stream notifications for more than the sending of EC_COMPLETE notifications. For example, if a stream has finished playing (that is, an end-of-stream notification is sent) and another window is dragged over a video renderer window, a number of WM_PAINT window messages will be generated. The typical practice for running video renderers is to refrain from repainting the current frame upon receipt of WM_PAINT messages (based on the assumption that another frame to be drawn will be received). However, when the end-of-stream notification has been sent, the renderer is in a waiting state; it is still running but is aware that it will not receive any additional data. Under these circumstances, the renderer customarily draws the playback area black.

Handling flushing is an additional complication for renderers. Flushing is carried out through a pair of IPin methods called BeginFlush and EndFlush. Flushing is essentially an additional state that the renderer must handle. It is illegal for a source filter to call BeginFlush without calling EndFlush, so hopefully the state is short and discrete; however, the renderer must correctly handle data or notifications it receives during the flush transition.

Any data received after calling BeginFlush should be rejected immediately by returning E_UNEXPECTED. Furthermore, any cached end-of-stream notification should also be cleared when a renderer is flushed. A renderer will typically be flushed in response to a seek. The flush ensures that old data is cleared from the filter graph before fresh samples are sent. (Typically, the playing of two sections of a stream, one after another, is best handled through deferred commands rather than waiting for one section to finish and then issuing a seek command.)

Handling State Changes and Pause Completion

A renderer filter behaves the same as any other filter in the filter graph when its state is changed, with the following exception. After being paused, the renderer will have some data queued, ready to be rendered when subsequently run. When the video renderer is stopped, it holds on to this queued data. This is an exception to the DirectShow rule that no resources should be held by filters while the filter graph is stopped.

The reason for this exception is that by holding resources, the renderer will always have an image with which to repaint the window if it receives a WM_PAINT message. It also has an image to satisfy methods, such as CBaseControlVideo::GetStaticImage, that request a copy of the current image. Another effect of holding resources is that holding on to the image stops the allocator from being decommitted, which in turn makes the next state change occur much faster because the image buffers are already allocated.

A video renderer should render and release samples only while running. While paused, the filter might render them (for example, when drawing a static poster image in a window), but should not release them. Audio renderers will do no rendering while paused (although they may perform other activities, such as preparing the wave device, for example). The time at which the samples should be rendered is obtained by combining the stream time in the sample with the reference time passed as a parameter to the IMediaControl::Run method. Renderers should reject samples with start times less than or equal to end times.

When an application pauses a filter graph, the filter graph does not return from its IMediaControl::Pause method until there is data queued at the renderers. In order to ensure this, when a renderer is paused, it should return S_FALSE if there is no data waiting to be rendered. If it has data queued, then it can return S_OK.

The filter graph manager checks all return values when pausing a filter graph, to ensure that the renderers have data queued. If one or more filters are not ready, then the filter graph manager polls the filters in the graph by calling GetState. The GetState method takes a time-out parameter. A filter (typically a renderer) that is still waiting for data to arrive before completing the state change returns VFW_S_STATE_INTERMEDIATE if the GetState method expires. Once data arrives at the renderer, GetState should be returned immediately with S_OK.

In both the intermediate and completed state, the reported filter state will be State_Paused. Only the return value indicates whether the filter is really ready or not. If, while a renderer is waiting for data to arrive, its source filter sends an end-of-stream notification, then that should also complete the state change.

Once all filters actually have data waiting to be rendered, the filter graph will complete its pause state change.

Handling Termination

Video renderers must correctly handle termination events from the user. This implies correctly hiding the window and knowing what to do if a window is subsequently forced to be displayed. Also, video renderers must notify the filter graph manager when its window is destroyed (or more accurately, when the renderer is removed from the filter graph) to free resources.

If the user closes the video window (for instance by pressing ALT+F4), the convention is to hide the window immediately and send an EC_USERABORT notification to the filter graph manager. This notification is passed through to the application, which will stop the graph playing. After sending EC_USERABORT, a video renderer should reject any additional samples delivered to it.

The abort flag should be left on by the renderer until it is subsequently stopped, at which point it should be reset so that an application can override the user action and continue playing the graph if it desires. If ALT+F4 is pressed while the video is running, the window will be hidden and all further samples delivered will be rejected. If the window is subsequently shown (perhaps through IVideoWindow::put_Visible), then no EC_REPAINT notifications should be generated.

The video renderer should also send the EC_WINDOW_DESTROYED notification to the filter graph when the video renderer is terminating. In fact, it is best to handle this when the renderer's IBaseFilter::JoinFilterGraph method is called with a null parameter (indicating that the renderer is about to be removed from the filter graph), rather than waiting until the actual video window is destroyed. Sending this notification allows the plug-in distributor in the filter graph manager to pass on resources that depend on window focus to other filters (such as audio devices).

Handling Dynamic Format Changes

Video renderers in DirectShow accept only video formats that can be drawn efficiently. For example, the window-based run-time renderer will accept only the RGB format that matches the current display device mode (for example, RGB565 when the display is set to 65,536 colors). As a last resort, it also accepts 8-bit palettized formats, as most display cards can draw this format efficiently. When the renderer has Microsoft® DirectDraw® loaded, it might later ask the source filter to switch to something that can be written onto a DirectDraw surface and drawn directly through display hardware. In some cases, the renderer's upstream filter might try to change the video format while the video is playing. This often occurs when a video stream has a palette change. It is most often the video decompressor that initiates a dynamic format change.

An upstream filter attempting to change formats dynamically should always call the IPin::QueryAccept method on the renderer input pin (for filters based on CTransformFilter, this is implemented in CTransformFilter::CheckInputType). It is undefined as to which formats a renderer will allow an upstream filter to change dynamically. However, at a very minimum, it should allow the upstream filter to change palettes. When an upstream filter changes media types, it will attach the format to the first sample delivered in that new type. If the renderer holds many samples in a queue waiting to be rendered, it should delay changing the format until the sample with the type change is actually about to be rendered.

Whenever a format change is detected by the video renderer, it should send an EC_DISPLAY_CHANGED notification. Most video renderers pick a format during connection so that the format can be drawn efficiently through GDI. If the user changes the current display mode without restarting the computer, a renderer might find itself with a bad image format connection and should send this notification. The first parameter should be the pin that needs reconnecting. The filter graph manager will arrange for the filter graph to be stopped and the pin reconnected. During the subsequent reconnection, the renderer can accept a more appropriate format.

Whenever a video renderer detects a palette change in the stream it should send the EC_PALETTE_CHANGED notification to the filter graph manager. The DirectShow video renderers detect whether a palette has really changed in dynamic format or not. The video renderers do this not only to filter out the number of EC_PALETTE_CHANGED notifications sent but also to reduce the amount of palette creation, installation, and deletion required.

Finally, the video renderer might also detect that the size of the video has changed, in which case, it should send the EC_VIDEO_SIZE_CHANGED notification. An application might use this notification to negotiate space in a compound document. The actual video dimensions are available through the IBasicVideo control interface. The DirectShow renderers detect whether the video has actually changed size or not prior to sending these events.

Handling Persistent Properties

All properties set through the IBasicVideo and IVideoWindow interfaces are meant to be persistent across connections. Therefore, disconnecting and reconnecting a renderer should show no effects on the window size, position, or styles. However, if the video dimensions change between connections, the renderer should reset the source and destination rectangles to their defaults. The source and destination positions are set through the IBasicVideo interface.

Both IBasicVideo and IVideoWindow provide enough access to properties to allow an application to save and restore all the data in the interface in a persistent format. This will be useful to applications that must save the exact configuration and properties of filter graphs during an editing session and restore them later.

Handling EC_REPAINT Notifications

The EC_REPAINT notification is sent only when the renderer is either paused or stopped. This notification signals to the filter graph manager that the renderer needs data. If the filter graph is stopped when it receives one of these notifications, it will pause the filter graph, wait for all filters to receive data (by calling GetState), and then stop it again. When stopped, a video renderer should hold on to the image so that subsequent WM_PAINT messages can be handled.

Therefore, if a video renderer receives a WM_PAINT message when stopped or paused, and it has nothing with which to paint its window, then it should send EC_REPAINT to the filter graph manager. If an EC_REPAINT notification is received while paused, then the filter graph manager calls IMediaPosition::put_CurrentPosition with the current position (that is, seeks to the current position). This causes the source filters to flush the filter graph and causes new data to be sent through the filter graph.

A renderer must send only one of these notifications at a time. Therefore, once the renderer sends a notification, it should ensure no more are sent until some samples are delivered. The conventional way to do this is to have a flag to signify that a repaint can be sent, which is turned off after an EC_REPAINT notification is sent. This flag should be reset once data is delivered or when the input pin is flushed, but not if end-of-stream is signaled on the input pin.

If the renderer does not monitor its EC_REPAINT notifications, it will flood the filter graph manager with EC_REPAINT requests (which are relatively expensive to process). For example, if a renderer has no image to draw, and another window is dragged across the window of the renderer in a full-drag operation, the renderer receives multiple WM_PAINT messages. Only the first of these should generate an EC_REPAINT event notification from the renderer to the filter graph manager.

A renderer should send its input pin as the first parameter to the EC_REPAINT notification. By doing this, the attached output pin will be queried for IMediaEventSink, and if supported, the EC_REPAINT notification will be sent there first. This allows output pins to handle repaints before the filter graph must be touched. This will not be done if the filter graph is stopped, because no buffers would be available from the decommitted renderer allocator.

If the output pin cannot handle the request and the filter graph is running, then the EC_REPAINT notification is ignored. An output pin must return NOERROR (S_OK) from IMediaEventSink::Notify to signal that it processed the repaint request successfully. The output pin will be called on the filter graph manager worker thread, which avoids having the renderer call the output pin directly, and so sidesteps any deadlock issues. If the filter graph is stopped or paused and the output doesn't handle the request, then the default processing is done.

Handling Notifications in Full-Screen Mode

The IVideoWindow plug-in distributor (PID) in the filter graph manages full-screen playback. It will swap a video renderer out for a specialist full-screen renderer, stretch a window of a renderer to full screen, or have the renderer implement full-screen playback directly. To interact in full-screen protocols, a video renderer should send an EC_ACTIVATE notification whenever its window is either activated or deactivated. In other words, an EC_ACTIVATE notification should be sent for each WM_ACTIVATEAPP message a renderer receives.

When a renderer is being used in full-screen mode, these notifications manage the switching into and out of that full-screen mode. Window deactivation typically occurs when a user presses ALT+TAB to switch to another window, which the DirectShow full-screen renderer uses as a cue to return to typical rendering mode.

When the EC_ACTIVATE notification is sent to the filter graph manager upon switching out of full-screen mode, the filter graph manager sends an EC_FULLSCREEN_LOST notification to the controlling application. The application might use this notification to restore the state of a full-screen button, for example. The EC_ACTIVATE notifications are used internally by DirectShow to manage full-screen switching on cues from the video renderers.

Summary of Notifications

This section lists the filter graph notifications that a renderer can send.
Event notification | Description
EC_ACTIVATE | Sent by video renderers in full-screen rendering mode for each WM_ACTIVATEAPP message received.
EC_COMPLETE | Sent by renderers after all data has been rendered.
EC_DISPLAY_CHANGED | Sent by video renderers when a display format changes.
EC_PALETTE_CHANGED | Sent whenever a video renderer detects a palette change in the stream.
EC_REPAINT | Sent by stopped or paused video renderers when a WM_PAINT message is received and there is no data to display. This causes the filter graph manager to generate a frame to paint to the display.
EC_USERABORT | Sent by video renderers to signal a closure that the user requested (for example, a user closing the video window).
EC_VIDEO_SIZE_CHANGED | Sent by video renderers whenever a change in native video size is detected.
EC_WINDOW_DESTROYED | Sent by video renderers when the filter is removed or destroyed so that resources that depend on window focus can be passed to other filters.


Source and Target Rectangles in Video Renderers

There are three sizes found in the VIDEOINFO, VIDEOINFOHEADER, and VIDEOINFOHEADER2 format structures of video mediatypes. This article explains what they are and how they work.

First, there is a size in the bmiHeader member of these structures. The bmiHeader member is a BITMAPINFOHEADER structure with its own width and height members bmiHeader.biWidth and bmiHeader.biHeight.

Secondly, there is a rectangle in the rcSource member of these structures, and lastly there is a rectangle in the rcTarget member of these structures.

Assume you have two filters, A and B, and that these filters are connected to each other (A on the left, or upstream, and B on the right, or downstream) with a certain video mediatype.

The buffers that pass between filters A and B have the size (bmiHeader.biWidth, bmiHeader.biHeight). Filter A should take a portion of its input video determined by rcSource and stretch that video to fill the rcTarget portion of the buffer. The portion of the input video to use is based on how rcSource compares to the (biWidth, biHeight) size of the media type that filters A and B originally connected with. If rcSource is empty, filter A uses its entire input video. If rcTarget is empty, filter A fills the entire output buffer.

For example, assume filter A is receiving video data that is 160x120 pixels. Assume also that filter A is connected to filter B with the following mediatype:

(biWidth, biHeight): 320,240
rcSource: (0, 0, 0, 0)
rcTarget: (0, 0, 0, 0)

This means that filter A will stretch the video it receives by 2 in both x and y, and fill a 320x240 output buffer.

As another example, assume filter A is receiving 160x120 video data, and that it is connected to filter B with the following mediatype:

(biWidth, biHeight): 320,240
rcSource: (0, 0, 160, 240)
rcTarget: (0, 0, 0, 0)

The rcSource member is relative to the connected buffer size of 320,240. Since the specified rcSource (0, 0, 160, 240) is the left half of the buffer, filter A will take the left half of its input video, or the (0, 0, 80, 120) portion, and stretch the video to a size of (320,240) (by 4 in the x direction, and by 2 in the y direction) and filling the 320x240 output buffer.

Now assume that filter A calls GetBuffer, and the media sample returned has a media type attached to it, signifying that filter B wants filter A to provide a different size or kind of video than it has previously been providing. Assume the new media type is:

(biWidth, biHeight): 640,480
rcSource: (0, 0, 160, 120)
rcTarget: (0, 0, 80, 60)

This means that the media sample has a buffer that is 640x480 in size. The rcSource member is relative to the original connected media type (320,240) not to the new media type of (640,480), so rcSource specifies that the top left corner (25%) of the input video is to be used. This portion of the input video is placed in the top left (80,60) pixels of the 640x480 output buffer, as specified by rcTarget of (0, 0, 80, 60). Since filter A is receiving 160x120 video, the top left corner of the input video is an (80,60) piece, the same size of the output bitmap, and no stretching is required.

Filter A will place no data in the other pixels of the output buffer, and will leave those bits untouched. The rcSource member is bounded by the biWidth and biHeight of the original connected media type between filters A and B, and rcTarget is bounded by the new biWidth and biHeight of the media sample. In the example above rcSource could not go outside the boundaries of (0,0,320,240) and rcTarget could not go outside the boundaries of (0,0,640,480).


Exposing Capture and Compression Formats

This article describes how to return capture and compression formats by using the IAMStreamConfig::GetStreamCaps method. This method can get more information about accepted media types than the traditional way of enumerating a pin's media types, so it should typically be used instead. See Establishing Media Type Connections for information about traditional media type enumeration. IAMStreamConfig::GetStreamCaps can return information about the kinds of formats allowed for audio or video. Additionally, this article provides some sample code that demonstrates how to reconnect the input pin of a transform filter to ensure your filter can produce a particular output.

The IAMStreamConfig::GetStreamCaps method returns an array of pairs of media type and capabilities structures. The media type is an AM_MEDIA_TYPE structure and the capabilities are represented either by an AUDIO_STREAM_CONFIG_CAPS structure or a VIDEO_STREAM_CONFIG_CAPS structure. The first section in this article presents a video example and the second presents an audio example.

Contents of this article:

  • Video Capabilities
  • Audio Capabilities
  • Reconnecting Your Input to Ensure Specific Output Types

Video Capabilities

The IAMStreamConfig::GetStreamCaps method presents video capabilities in an array of pairs of AM_MEDIA_TYPE and VIDEO_STREAM_CONFIG_CAPS structures. You can use this to expose all the formats and resolutions supported on a pin as discussed below.

See Audio Capabilities for audio-related examples of IAMStreamConfig::GetStreamCaps.

Suppose your capture card supports JPEG format at all resolutions between 160 × 120 pixels and 320 × 240 pixels, inclusive. The difference between supported resolutions is one in this case because you add or subtract one pixel from each supported resolution to get the next supported resolution. This difference in supported resolutions is called granularity.

Suppose you card also supports the size 640 × 480. The following illustrates this single resolution and the above range of resolutions (all sizes between 160 × 120 pixels and 320 × 240 pixels).

Illustration of JPEG support at all sizes between 160 × 120 pixels and 320 × 240 pixels, and 640 × 480

Also, suppose it supports 24-bit color RGB format at resolutions between 160 × 120 and 320 × 240, but with a granularity of 8. The following illustration shows some of the valid sizes in this case.

Illustration of RGB support at sizes between 160 × 120 and 320 × 240 with a granularity of 8

To put it another way, and listing more resolutions, the following are all among the list of valid resolutions.

  • 160 × 120
  • 168 × 120
  • 168 × 128
  • 176 × 128
  • 176 × 136
  • ... additional resolutions ...
  • 312 × 232
  • 320 × 240

Use GetStreamCaps to expose these color format and dimension capabilities by offering a media type of 320 × 240 JPEG (if that is your default or preferred size) coupled with minimum capabilities of 160 × 120, maximum capabilities of 320 × 240, and a granularity of 1. The next pair you expose by using GetStreamCaps is a media type of 640 × 480 JPEG coupled with a minimum of 640 × 480 and a maximum of 640 × 480 and a granularity of 0. The third pair includes a media type of 320 × 240, 24-bit RGB with minimum capabilities of 160 × 120, maximum capabilities of 320 × 240, and a granularity of 8. In this way you can publish almost every format and capability your card might support. An application that must know what compression formats you provide can get all the pairs and make a list of all the unique subtypes of the media types.

A filter obtains its media type source and target rectangles from the VIDEOINFOHEADER structure's rcSource and rcTarget members, respectively. Filters do not have to support source and target rectangles.

The cropping rectangle described throughout the IAMStreamConfig documentation is the same as the VIDEOINFOHEADER structure's rcSource rectangle for the output pin.

The output rectangle described throughout the IAMStreamConfig documentation is the same as the biWidth and biHeight members of the output pin's BITMAPINFOHEADER structure.

If a filter's output pin is connected to a media type with nonempty source and target rectangles, then your filter is required to stretch the input format's source subrectangle into the output format's target subrectangle. The source subrectangle is stored in the VIDEO_STREAM_CONFIG_CAPS structure's InputSize member.

For example, consider the following video compressor scenario: The input image is in RGB format and has a size of 160 × 120 pixels. The source rectangle's upper-left corner is at coordinate (20,20), and its lower-right corner is at (30,30). The output image is in MPEG format with a size of 320 × 240. The target rectangle's upper-left corner is at (0,0) and its lower-right corner is at (100,100). In this case, the filter should take a 10 × 10 piece of the 160 × 120 RGB source bitmap, and make it fill the top 100 × 100 area of a 320 × 240 bitmap, leaving the rest of the 320 × 240 bitmap untouched. The following illustration shows this scenario.

Illustration of video compressor stretching subrectangle of image between source and target rectangles

A filter might not support this and can fail to connect with a media type where rcSource and rcTarget are not empty.

The VIDEOINFOHEADER structure exposes information about a filter's data rate capabilities. For example, suppose you connected your output pin to the next filter with a certain media type (either directly or by using the media type passed by the CMediaType::SetFormat function). Look at the dwBitRate member of that media type's VIDEOINFOHEADER format structure to see what data rate you should compress the video to. If you multiply the number of units of time per frame in the VIDEOINFOHEADER structure's AvgTimePerFrame member by the data rate in the dwBitRate member and divide by 10,000,000 (the number of units per second), you can figure out how many bytes each frame should be. You can produce a smaller sized frame, but never a larger one. To determine the frame rate for a video compressor or for a capture filter, use AvgTimePerFrame from your output pin's media type.

Audio Capabilities

For audio capabilities, IAMStreamConfig::GetStreamCaps returns an array of pairs of AM_MEDIA_TYPE and AUDIO_STREAM_CONFIG_CAPS structures. As with video, you can use this to expose all kinds of audio capabilities on the pin, such as data rate and whether it supports mono or stereo.

See Video Capabilities for video-related examples relating to IAMStreamConfig::GetStreamCaps.

Suppose you support pulse code modulation (PCM) wave format (as represented by the Microsoft® Win32® PCMWAVEFORMAT structure) at sampling rates of 11,025, 22,050, and 44,100 samples per second, all at 8- or 16-bit mono or stereo. In this case, you would offer two pairs of structures. The first pair would have an AUDIO_STREAM_CONFIG_CAPS capability structure saying you support a minimum of 11,025 to a maximum of 22,050 samples per second with a granularity of 11,025 samples per second (granularity is the difference between supported values); an 8-bit minimum to a 16-bit maximum bits per sample with a granularity of 8 bits per sample; and one-channel minimum and two-channel maximum. The first pair's media type would be your default PCM format in that range, perhaps 22 kilohertz (kHz), 16-bit stereo. Your second pair would be a capability showing 44,100 for both minimum and maximum samples per second; 8-bit (minimum) and 16-bit (maximum) bits per sample, with a granularity of 8 bits per sample; and one-channel minimum and two-channel maximum. The media type would be your default 44 kHz format, perhaps 44 kHz 16-bit stereo.

If you support non-PCM wave formats, the media type returned by this method can show which non-PCM formats you support (with a default sample rate, bit rate, and channels) and the capabilities structure accompanying that media type can describe which other sample rates, bit rates, and channels you support.

Reconnecting Your Input to Ensure Specific Output Types

Filters implement the IAMStreamConfig::SetFormat method to set the audio or video stream's format before pins are connected. Additionally, if your output pin is already connected and you can provide a new type, then reconnect your pin. If the other pin your filter is connected to can't accept the media type, fail this call and leave your connection alone.

Transform filters that do not know what output types their pins can provide should refuse any calls to IAMStreamConfig::SetFormat and IAMStreamConfig::GetStreamCaps with the error code VFW_E_NOT_CONNECTED until their input pin is connected.

If your pin knows what types it can provide even when your input is not connected, it is okay to offer and accept them as usual. See Connecting Transform Filters for more information.

In certain cases it is useful to reconnect pins when you are offering a format on an established connection. For example, if you can compress video into format X but only if you get 24-bit RGB input, and you can turn 8-bit RGB input into compressed format Y, you can either:

  1. Offer and accept both X and Y in IAMStreamConfig::GetStreamCaps and IAMStreamConfig::SetFormat all the time, or,
  2. Only offer format X if your input is connected as 24, and only offer Y if your input is connected as 8. Fail both IAMStreamConfig::GetStreamCaps and IAMStreamConfig::SetFormat if your input is not connected.

No matter which one you choose, you will need some reconnecting code that looks like this:

// Overridden to do fancy reconnecting footwork.
//
HRESULT MyOutputPin::CheckMediaType(const CMediaType *pmtOut)
{
    HRESULT hr;
    CMediaType *pmtEnum;
    BOOL fFound = FALSE;
    IEnumMediaTypes *pEnum;

    if (!m_pFilter->m_pInput->IsConnected()) {
           return VFW_E_NOT_CONNECTED;
    }

    // Quickly verify that the media type is not bogus here
    //

    // If somebody has previously called SetFormat, fail this call if the media type
    // isn't an exact match.

       // Accept this output type like normal; nothing fancy required.
    hr = m_pFilter->CheckTransform(&m_pFilter->m_pInput->CurrentMediaType(),
                    pmtOut);
    if (hr == NOERROR)
    return hr;

    DbgLog((LOG_TRACE,3,TEXT("Can't accept this output media type")));
    DbgLog((LOG_TRACE,3,TEXT(" But how about reconnecting our input...")));

    // Attempt to find an acceptable type by reconnecting our input pin.
    // The pin our input pin connects to might be able to provide a type
    // that our pin can convert into the necessary type.
    hr = m_pFilter->m_pInput->GetConnected()->EnumMediaTypes(&pEnum);
    if (hr != NOERROR)
    return E_FAIL;
    while (1) {
    hr = pEnum->Next(1, (AM_MEDIA_TYPE **)&pmtEnum, &j);

    // All out of enumerated types.
    if (hr == S_FALSE || j == 0) {
        break;
    }

    // Can our pin convert between these?
    hr = m_pFilter->CheckTransform(pmtEnum, pmtOut);

    if (hr != NOERROR) {
        DeleteMediaType(pmtEnum);
        continue;
    }

    // OK, it offers an acceptable type, but will it accept it now?
    hr = m_pFilter->m_pInput->GetConnected()->QueryAccept(pmtEnum);
    // Nope.
    if (hr != NOERROR) {
        DeleteMediaType(pmtEnum);
        continue;
    }
    // OK, I'm satisfied.
    fFound = TRUE;
    DbgLog((LOG_TRACE,2,TEXT("This output type is only acceptable after reconnecting our input.")));

    // All done with this.
    DeleteMediaType(pmtEnum);
    break;
    }
    pEnum->Release();

    if (!fFound)
        DbgLog((LOG_TRACE,3,TEXT("*NO! Reconnecting our input won't help")));

    return fFound ? NOERROR : VFW_E_INVALIDMEDIATYPE;
}

HRESULT MyOutputPin::SetFormat(AM_MEDIA_TYPE *pmt)
{
    HRESULT hr;
    LPWAVEFORMATEX lpwfx;
    DWORD dwSize;

    if (pmt == NULL)
    return E_POINTER;

    // To make sure streaming isn't in the middle of starting/stopping:
    CAutoLock cObjectLock(&m_pFilter->m_csFilter);

    if (m_pFilter->m_State != State_Stopped)
    return VFW_E_NOT_STOPPED;

    // Possible output formats depend on the input format.
    if (!m_pFilter->m_pInput->IsConnected())
    return VFW_E_NOT_CONNECTED;

    // Already using this format.
    if (IsConnected() && CurrentMediaType() == *pmt)
    return NOERROR;

    // See if this type is acceptable.
    if ((hr = CheckMediaType((CMediaType *)pmt)) != NOERROR) {
    DbgLog((LOG_TRACE,2,TEXT("IAMStreamConfig::SetFormat rejected")));
    return hr;
    }

    // If connecting to another filter, make sure they like it.
    if (IsConnected()) {
    hr = GetConnected()->QueryAccept(pmt);
    if (hr != NOERROR)
        return VFW_E_INVALIDMEDIATYPE;
    }

    // Now make a note that from now on, this is the only format allowed,
    // and refuse anything but this in the CheckMediaType code above.

    // Changing the format means reconnecting if necessary.
    if (IsConnected())
        m_pFilter->m_pGraph->Reconnect(this);

    return NOERROR;
}

// Overridden to complete our fancy reconnection footwork:
//
HRESULT MyWrapper::SetMediaType(PIN_DIRECTION direction,const CMediaType *pmt)
{
    HRESULT hr;

    // Set the OUTPUT type.
    if (direction == PINDIR_OUTPUT) {

    // Uh oh.  As part of our fancy reconnection, our input pin might be asked to
    // provide a media type it cannot provide without reconnection
    // to a different type.
    if (m_pInput && m_pInput->IsConnected()) {

        // If our pin can actually provide this type now, don't worry.
            hr = CheckTransform(&m_pInput->CurrentMediaType(),
                    &m_pOutput->CurrentMediaType());
        if (hr == NOERROR)
        return hr;

                DbgLog((LOG_TRACE,2,TEXT("*Set OUTPUT requires RECONNECT of INPUT!")));

        // Reconnect our input pin.
        return m_pGraph->Reconnect(m_pInput);

    }

    return NOERROR;
    }

    return NOERROR;
}


C/C++ Reference

This section contains all the Microsoft® DirectShow™ reference information, including reference entries for the DirectShow COM interfaces, the C++ base classes, the structures and data types, utility functions and debugging utilities, event notification codes, and error codes. See Hierarch.doc in your DirectX Media Help directory for a Microsoft Word file that contains a DirectShow base class and interface hierarchy chart. (The Help directory is the default directory created when you install the DirectX Media SDK.)

DirectShow COM Interfaces

Base Classes

Utility Functions

Debugging

Structures

Data Types

Property Sets

Event Notification Codes

DVD Event Notification Codes

Error and Success Codes


DirectShow COM Interfaces

This section contains reference entries for all the DirectShow COM interfaces and their methods.

Summary of DirectShow COM Interfaces

DirectShow Interfaces by Category

IAMAudioCutListElement Interface

IAMAudioInputMixer Interface

IAMBufferNegotiation Interface

IAMCollection Interface

IAMCopyCaptureFileProgress Interface

IAMCrossbar Interface

IAMCutListElement Interface

IAMDevMemoryAllocator Interface

IAMDevMemoryControl Interface

IAMDirectSound Interface

IAMDroppedFrames Interface

IAMExtDevice Interface

IAMExtTransport Interface

IAMFileCutListElement Interface

IAMLine21Decoder Interface

IAMovie Interface

IAMovieSetup Interface

IAMStreamConfig Interface

IAMStreamControl Interface

IAMStreamSelect Interface

IAMTimecodeDisplay Interface

IAMTimecodeGenerator Interface

IAMTimecodeReader Interface

IAMTVTuner Interface

IAMVfwCaptureDialogs Interface

IAMVfwCompressDialogs Interface

IAMVideoCompression Interface

IAMVideoControl Interface

IAMVideoCutListElement Interface

IAMVideoProcAmp Interface

IAsyncReader Interface

IBaseFilter Interface

IBasicAudio Interface

IBasicVideo Interface

ICaptureGraphBuilder Interface

IConfigAviMux Interface

IConfigInterleaving Interface

ICreateDevEnum Interface

ICutListGraphBuilder Interface

IDeferredCommand Interface

IDirectDrawVideo Interface

IDistributorNotify Interface

IDvdControl Interface

IDvdGraphBuilder Interface

IDvdInfo Interface

IEnumFilters Interface

IEnumMediaTypes Interface

IEnumPins Interface

IEnumRegFilters Interface

IFileClip Interface

IFileSinkFilter Interface

IFileSinkFilter2 Interface

IFileSourceFilter Interface

IFilterGraph Interface

IFilterGraph2 Interface

IFilterInfo Interface

IFilterMapper Interface

IFilterMapper2 Interface

IFullScreenVideo Interface

IGraphBuilder Interface

IGraphVersion Interface

IKsPropertySet Interface

IMediaControl Interface

IMediaEvent Interface

IMediaEventEx Interface

IMediaEventSink Interface

IMediaFilter Interface

IMediaPosition Interface

IMediaPropertyBag Interface

IMediaSample Interface

IMediaSample2 Interface

IMediaSeeking Interface

IMediaTypeInfo Interface

IMemAllocator Interface

IMemInputPin Interface

IMixerPinConfig Interface

IMixerPinConfig2 Interface

IOverlay Interface

IOverlayNotify Interface

IPin Interface

IPinInfo Interface

IQualityControl Interface

IQualProp Interface

IQueueCommand Interface

IReferenceClock Interface

IRegFilterInfo Interface

IResourceConsumer Interface

IResourceManager Interface

ISeekingPassThru Interface

IStandardCutList Interface

IUnknown Interface

IVideoWindow Interface

IVPBaseConfig Interface

IVPBaseNotify Interface

IVPConfig Interface

IVPNotify Interface

IVPNotify2 Interface


Summary of DirectShow COM Interfaces

This article groups the Microsoft® DirectShow™ interfaces according to the objects that expose them. It explains which object implements each interface and who is likely to call the interface methods implemented on each type of object. The information is presented as a series of tables of COM interfaces relating to each object, and so provides a summary and quick reference for understanding the DirectShow interfaces.

Contents of this article:

  • Introducing the DirectShow COM Interfaces
  • Interfaces on a Typical Filter Graph

Introducing the DirectShow COM Interfaces

The DirectShow COM interfaces comprise the schematic of an architecture for streaming time-stamped media. The filter graph, through which media flows, is composed of objects, such as filters, pins, media samples, allocators, and enumerators, that work together. COM interfaces are implemented on these objects and are called by other objects with which they interact. The filter is the only filter graph COM object that has a CLSID; all other objects in the filter graph support COM interfaces, and are created as needed by the filter. Filters and their supporting object must implement their COM interfaces and a class library is available for help in that task. The filter graph manager, on the other hand, has a CLSID and supports several fully implemented interfaces, as do plug-in distributors, which are aggregated by the filter graph manager. (Microsoft-provided plug-in distributors are referred to as the filter graph manager in this article.)

This section contains the following topics.

  • Filter Graph Manager Interfaces
  • Filter and Pin Interfaces
  • Media Sample and Enumerator Interfaces
  • Control Interfaces

The DirectShow COM interfaces can be categorized as follows:

  • Filter graph manager interfaces, which are fully implemented and used by applications to create, connect, and control filter graphs and by filters within the filter graph to post event notifications and to force reconnections when needed.
  • Filter and pin interfaces, which must be implemented by the filter. They comprise the methods exposed by filters for communicating with the filter graph manager, connecting with other filters, passing data downstream (from source filter to renderer filter) and passing quality control and media positioning information upstream (from renderer to source).
  • Enumerator and media sample interfaces, which are interfaces on objects created temporarily for passing information.
  • Control interfaces, which are exposed by filters and the filter graph manager to enable the starting, stopping, and positioning of media in the stream. The control interfaces on the filters must be implemented when writing a filter, whereas they are already implemented on the filter graph manager.

Filter Graph Manager Interfaces

Most filter graph manager interfaces fall in the category of control interfaces, also listed separately in this article; however, some are unique to the filter graph manager.
Interface | What calls methods | What methods do | Comments
IAMCollection | An Automation client such as Microsoft® Visual Basic®. | Retrieve the number of items in the collection and retrieve an indexed item. | Implemented by the filter graph manager. Not used by C or C++ applications.
IDeferredCommand | The application that sent a deferred command using IQueueCommand. | Retrieve confidence information, postpone or cancel a deferred command, and return HRESULT values from an invoked command. | Implemented by the filter graph manager and returned to any application that calls IQueueCommand methods.
IEnumFilters | Application or possibly a filter that needs to know what other filters are in the graph. | Retrieve filters, skip filters, or clone the enumerator. | Implemented in the filter graph manager.
IEnumRegFilters | Filter mapper. | Retrieve filters, skip items, or clone the enumerator. | Implemented by the filter graph manager.
IFilterGraph | Not usually called directly. | Add, connect, and reconnect filters in a filter graph. | Use IGraphBuilder instead, because it inherits from this interface.
IFilterGraph2 | C or C++ applications. | Extend filter graph functionality.
IFilterInfo | An Automation client such as Visual Basic. | Retrieve name, vendor information, IBaseFilter interface, file name (for source filters), specified pin object, or collection of associated pin objects. | Implemented by the filter graph manager. Not used by C or C++ applications.
IGraphBuilder | Application. | Create filter graphs dynamically from stream media type or re-create stored filter graph. | Inherits from IFilterGraph. Also uses a filter mapper object to look up filters in the registry.
IGraphVersion | Application and plug-in distributors in the filter graph manager. | Retrieve the current filter graph version and determine when a filter graph has had filters added, deleted, or reconnected.
IMediaControl | Application. | Run, pause, and stop the filter graph, and retrieve the state. | Has many of the same methods as the IMediaFilter interface, which is implemented on filters.
IMediaEvent | Applications that need to retrieve events passed to the filter graph manager from filters. | Get events, get event handles, block until completion, and block or unblock default handling of events by the filter graph manager. | Implemented by the filter graph manager.
IMediaEventSink | Filters that need to pass events to the application. | Receive event notifications from filters. | Implemented by the filter graph manager.
IMediaPosition | Applications. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Implemented on the filter graph manager and also on filters.
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Implemented on the filter graph manager and also on filters.
IMediaTypeInfo | An Automation client such as Visual Basic. | Retrieve the major and minor media types. | Implemented by the filter graph manager. Not used by C or C++ applications.
IPinInfo | An Automation client such as Visual Basic. | Retrieve pin information such as name, direction, connections, and collection of associated media type objects. Also includes methods to connect and disconnect pins. | Implemented by the filter graph manager. Not used by C or C++ applications.
IQueueCommand | Application needing to send a deferred command. | Cue commands to run at stream time (offset from start) or presentation time. | Implemented by the filter graph manager and used by applications. Filters can implement this.
IRegFilterInfo | An Automation client such as Visual Basic. | Retrieve a filter name and add it to the filter graph. | Implemented by the filter graph manager. Not used by C or C++ applications.
ISeekingPassThru | Applications. | Instantiate and initialize a CRendererPosPassThru object. You can use this object to keep track of reference times and stream times. | Implemented on video renderer filters that need to keep track of reference time and stream time.

Filter and Pin Interfaces

Filters are composed of one filter object and one or more pin objects. Although only the IUnknown and IBaseFilter interfaces are strictly required on a filter, filters can support other filter and pin interfaces, as discussed in Filter Interfaces.

This topic contains the following subtopics.

  • Filter Interfaces
  • Pin Interfaces

Filter Interfaces

The following interfaces are exposed by filter objects in order to be integrated with the filter graph manager. The filter is the main COM object and has a class ID (CLSID) and name registered in the registry. Filters must provide access to their pins and otherwise communicate with the filter graph. They must also allow the filter graph manager to manage the data flow by accepting state change messages.
Interface | What calls methods | What methods do | Comments
IAMovieSetup | Entry-point routines in Dllentry.cpp. | Register and unregister the object. | This is implemented by the base classes for most of what is required to make a filter self-registerable. Need to override one base member function to provide setup structures.
IBaseFilter | Filter graph manager. | Same as IMediaFilter plus enumerate pins, retrieve filter and vendor information, and locate pins when rebuilding a persistent filter graph. | Inherits methods from the IMediaFilter interface. Implemented by the CBaseFilter class.
IMediaFilter | Nothing directly. | Put the filter in run, stop, or pause state, get and set the reference clock, and retrieve the filter state. | Inherited by the IBaseFilter interface, which should be used instead of referencing this directly.
IPersist | Filter graph manager when loading preconfigured filter graph files. | Retrieve the filter's class identifier. | Inherited by IBaseFilter along with IMediaFilter.
IUnknown | Filter graph manager. | Retrieve a pointer to the interface, add and delete references to the interface. | Implemented by the CUnknown base class.

The following additional filter interfaces can be exposed by filters such as source filters, and by video and audio renderers. Source filters are notified by means of a quality control mechanism so that they can adjust the amount of data introduced to the stream according to the renderer's performance. Audio renderers are usually called upon to provide a reference clock, since audio hardware generates this. The video renderer filter supplied by Microsoft exposes interfaces to handle both the video window and the transferring of video frames into video buffers.
Interface | What calls methods | What methods do | Comments
IAMCrossbar | C or C++ applications. | Route messages from an analog or digital audio or video source to a video capture filter. | Exposed on analog video crossbar filters.
IAMExtDevice | C or C++ applications. | Control external devices.
IAMExtTransport | C or C++ applications. | Control specific behaviors of an external VCR.
IAMTimecodeDisplay | C or C++ applications. | Define behavior of an external SMPTE/MIDI timecode display device.
IAMTimecodeGenerator | C or C++ applications. | Specify how an external SMPTE/MIDI timecode generator should supply data to the filter graph, and the formats in which timecode should be supplied.
IAMTimecodeReader | C or C++ applications. | Specify the timecode format that an external device should read and how it is embedded in the media.
IAMTVTuner | C or C++ applications. | Enables applications to set TV transmission types.
IAMVideoProcAmp | C or C++ applications. | Control video quality settings. | Exposed on WDM video capture filters.
IAsyncReader | Downstream parser filter. | Perform synchronized reads, request data, request allocator, begin and end flushing, and retrieve file's total length. | Implemented on the Async Sample (Asynchronous Reader Filter), which reads media types with a major type of MEDIATYPE_Stream.
IBasicAudio | Applications and Automation clients such as Visual Basic. | Get and set the properties of the audio renderer filter. | Can be implemented on an audio renderer filter. Supports Automation.
IBasicVideo | Applications and Automation clients such as Visual Basic. | Get and set the source video rectangle, and retrieve video size, palette values, and the current image. | Usually implemented on a video renderer filter. Supports Automation.
ICreateDevEnum | C or C++ applications. | Enumerate hardware devices.
IDirectDrawVideo | C or C++ applications. | Set and retrieve DirectDraw® hardware and emulated capabilities and surface types. | Usually implemented on a video renderer filter.
IFileSinkFilter | Any application that needs to set the name of the file from which the file source filter will read. | Set or retrieve the file name. | Implemented on a file writer filter, as used in a video capture filter graph.
IFileSinkFilter2 | C or C++ applications. | Set or retrieve the file name, optionally overwriting an existing file.
IFileSourceFilter | Any application that needs to set the name of the file into which the file sink filter will write. | Set or retrieve the file name. | Implemented on any source filter that needs a file name from the user.
IFullScreenVideo | C or C++ applications. | Set and retrieve full-screen modes, message drain, icon caption, and other information. | Usually implemented on a video renderer filter.
IMediaPropertyBag | C or C++ applications. | Expose copyright information on filters.
IMediaSample2 | Filters. | Expose sample properties.
IOverlay | Filters upstream from the renderer that need to be notified of window changes. | Set and retrieve palette and color key information; get window handle, clip list, window position; set up advise link with upstream filter. | Usually implemented on a video renderer filter.
IQualityControl | Filter graph manager, upstream filter, or pin. | Receive a quality message and receive the quality sink location. | Normally implemented on filters that can affect the quality when they receive the message.
IQualProp | Property page objects. | Retrieve rendering quality properties of the video renderer, such as the number of frames drawn, jitter, and so on. | Supports Automation.
IReferenceClock | Filters that need to be synchronous with a reference clock. | Register for time notifications from the filter, convert real to reference time, and retrieve the current time. | Implemented on a filter that can generate a reference clock, typically an audio renderer. Provides services similar to the timeBeginPeriod and timeSetEvent Win32® functions.
IVideoWindow | Applications and Automation clients such as Visual Basic. | Control the window aspects of a video renderer. | Usually implemented on a video renderer filter.

DirectShow provides filters that implement particular interfaces for you. Applications typically use those interfaces, but filters do so as well.
Interface | What calls methods | What methods do | Comments
IAMDirectSound | DirectSound audio renderer. | Set and retrieve the window that will handle the sound playback. | DirectSound audio renderer implements and uses this interface.
IAMLine21Decoder | Applications or video mixer filter. | Provide access to closed caption settings. | Line21 decoder implements this interface.
IAMStreamSelect | Applications. | Control which logical streams are played and retrieve information about them. | The MPEG splitter implements this interface.
IAMVfwCaptureDialogs | Applications. | Provide access to dialog boxes exposed by Video for Windows capture drivers. | Video for Windows capture filter implements this interface.
IAMVfwCompressDialogs | Applications. | Provide access to dialog boxes exposed by Video for Windows compressors. | Video for Windows installable compression manager (ICM) filter implements this interface.
IAMAudioCutListElement | Applications and filters. | Provide support for a cutlist element for an audio file stream in a WAV or AVI file. | The CLSID_AudioFileClip object implements this interface.
ICaptureGraphBuilder | Applications. | Simplify building capture filter graphs. | Capture graph builder object implements this interface.
IConfigAviMux | Applications. | Control how the AVI multiplexer filter writes files to disk. | AVI multiplexer filter implements this interface on its property page.
IConfigInterleaving | Applications. | Control how the AVI multiplexer filter writes files to disk and set interleaving configuration information. | AVI multiplexer filter implements this interface on its property page.
IAMCutListElement | Filters. | Describe a base object, which represents an element in a cutlist. | DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects, which can create an object that implements it for you.
ICutListGraphBuilder | Applications. | Enable you to easily implement one or more cutlist filter graphs.
IDvdControl | Applications. | Control playback and searching on DVD discs. | DVD navigator filter implements this interface.
IDvdGraphBuilder | Applications. | Simplify building DVD filter graphs. | DVD graph builder object implements this interface.
IDvdInfo | Applications. | Query for DVD attributes and DVD player status. | DVD navigator filter implements this interface.
IFileClip | Applications. | Provide a simple way for an application to create one or more cuts from a single media file, or to create blank cuts.
IAMFileCutListElement | Filters. | Provide support for a cutlist element for a file stream. | DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects that implement it for you.
IStandardCutList | Applications. | Provide a simple way for an application to feed a cutlist into a cutlist provider (filter).
IAMVideoCutListElement | Filters. | Provide support for a cutlist element from an AVI video file stream. | DirectShow provides the CLSID_VideoFileClip object that implements it for you.
IVPBaseConfig | Video port mixer filter. | Enable a video port (VP) mixer filter to communicate with a VP driver. | Ksproxy filter implements this interface.
IVPBaseNotify | Applications. | Control properties of a filter that uses a video port. | Video port mixer filter implements this interface.
IVPConfig | Video port mixer filter. | Enable a video port (VP) mixer filter to communicate with a VP driver. | Ksproxy filter implements this interface.
IVPNotify, IVPNotify2 | Applications. | Control properties of a filter that uses a video port. | Video port mixer filter implements this interface.

Pin Interfaces

Pin objects expose these interfaces. Pins do not usually have registered class identifiers and are usually created by the filter object on which they reside. They are exposed externally by the filter, which includes a method (IBaseFilter::EnumPins) to hand out pointers to the IPin interfaces of its pins, usually to the filter graph manager. The filter graph manager is responsible for connecting pins by calling an IPin method on one of the pins with a pointer to the other pin. Once pins are connected, each pin holds a pointer to the pin to which it is connected.
Interface | What calls methods | What methods do | Comments
IAMAudioInputMixer | Applications. | Adjust audio input characteristics. | Input pin of an audio capture filter typically implements this interface.
IAMBufferNegotiation | Applications. | Set and retrieve buffer properties. | The IAMBufferNegotiation interface informs a pin what kind of buffer specifications it should use when connected.
IAMDevMemoryAllocator | Applications. | Provide creation of third-party memory allocators. | Makes use of on-board memory manager objects.
IAMDevMemoryControl | Applications. | Control and identify on-board codec memory. | This interface is supported by a device memory control object.
IAMDroppedFrames | Applications. | Provide information about the number of dropped frames, frame rate, and data rate. | Capture filter's video output pin should implement this interface.
IAMStreamConfig | Applications or filters. | Provide types of formats an output pin can connect with. | Output pins of capture and compression filters typically implement this interface.
IAMStreamControl | Applications. | Enable control of streams in a filter graph. | Implemented by any input or output pins.
IAMVideoCompression | Applications. | Control compression parameters that aren't part of the media type. | Output pin of a video capture or compression filter typically implements this interface.
IKsPropertySet | Applications or filters. | Sets and retrieves device properties. | Expose device properties and enable an application or filter to change the properties.
IMediaPosition | Filter graph manager or downstream filter. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Downstream filters call methods on output pins supporting this to pass a requested media position upstream. Implemented in CPosPassThru on pins.
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Downstream filters call methods on output pins supporting this to pass a requested media position upstream. Implemented in CPosPassThru on pins.
IMemAllocator | Owning filter and output pin of connected filter. | Allocate one or more buffers based on required size, retrieve a buffer for a media sample, commit memory when in use, and release it (decommit) when not in use. | Appears on allocator object usually created by IMemInputPin. Implemented by the CMemAllocator class.
IMemInputPin | Filter graph manager, output pin of a connected filter. | Retrieve a preferred allocator, receive the allocator provided by output pin, receive media samples, and tell whether the pin will block on receive. | Usually only on input pins. Implemented by the CBaseInputPin base class.
IPin | Filter graph manager, other pins, the owning filter. | Connect and disconnect the pin, retrieve information on external and internal pin connections, retrieve preferred media types enumerator, negotiate preferred media types, receive flush and end-of-stream notifications. | Implemented on all pins by the CBasePin base class.
IQualityControl | Downstream filter or pin on downstream filter. | Receive a quality message and receive the quality sink to send quality messages to. | Implemented on output pins by the CBaseOutputPin base class, where it is used to pass the message upstream.
IUnknown | Filter graph manager, other pins, the owning filter. | Retrieve a pointer to the interface, add and delete references to the interface. | Implemented on all pins by the CUnknown base class.

In addition, the Microsoft video renderer's input pin supports the IOverlay interface, which allows the connected upstream pin to effectively register its IOverlayNotify interface in order to receive notifications of video window changes. Replacement video renderers can also implement this if they are intended to connect to the same filters as the video renderer provided with DirectShow.

Media Sample and Enumerator Interfaces

Media sample and enumerator interfaces are temporary objects created to pass information or data between objects. They do not have class identifiers.

This topic contains the following subtopics.

  • Media Sample Interfaces
  • Enumerator Interfaces

Media Sample Interfaces

The media sample interface, IMediaSample, is created from the memory allocator, which uses the media sample object as its unit of exchange. It has no class identifier. It is the unit of media data that is passed from one filter to the next via the memory allocator shared by two connected pins.
Interface | What calls methods | What methods do | Comments
IMediaSample | Pins or filters that need to manipulate the media sample data or examine its properties. | Retrieve a pointer to data, and get and set properties on the media sample such as buffer size, time stamp, data length, type, synchronization point, preroll, and end-of-stream properties. | Implemented on media samples by the CMediaSample base class.
IUnknown | Pin or filter. | Retrieve pointer to the interface, add and delete references to the interface. | Implemented on media samples by the CUnknown base class.

Enumerator Interfaces

Enumerators in DirectShow are based on the COM IEnumXXXX interfaces. They include the Next and Prev methods, which tell the enumerator what item or items to return; the Skip method, which skips one or more items; and the Clone method, which makes a copy of the enumerator. Enumerators are used to present lists of items such as filters in a filter graph, pins on a filter, or media types that are preferred by a pin.
Interface | What calls methods | What methods do | Comments
IEnumFilters | Application or possibly a filter that needs to know what other filters are in the graph. | Retrieve filters, skip filters, or clone the enumerator. | Implemented in the filter graph manager.
IEnumMediaTypes | Filter graph manager or connected pin negotiating a media type. | Retrieve media types, skip media types, or clone the enumerator. | Implemented by the CEnumMediaTypes class.
IEnumPins | Filter graph manager. | Retrieve pins, skip pins, or clone the enumerator. | Implemented by the CEnumPins class.
IEnumRegFilters | Filter mapper. | Retrieve filters, skip items, or clone the enumerator. | Implemented by the filter graph manager.

Control Interfaces

Control interfaces allow the filter graph manager to coordinate the activities of the data stream with filters. Interfaces described previously in both the Filter Graph Manager Interfaces and Filter and Pin Interfaces sections are repeated here so that all control interfaces can be viewed together.
Interface | What calls methods | What methods do | Comments
IBaseFilter | Filter graph manager. | Same as IMediaFilter plus enumerate pins, retrieve filter and vendor information, and locate pins when rebuilding a persistent filter graph. | Inherits methods from the IMediaFilter interface. Implemented by the CBaseFilter class.
IMediaControl | Application. | Run, pause, and stop the filter graph, and retrieve the state. | Implemented by the filter graph manager.
IMediaFilter | Nothing directly. | Put the filter in run, stop, or pause state, get and set the reference clock and retrieve the filter state. | Inherited by IBaseFilter, which should be used instead of referencing this directly.
IMediaPosition | Application, when exposed on the filter graph manager; filter graph manager or downstream filter, when exposed on a filter. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Implemented on the filter graph manager and on filters.
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Implemented on the filter graph manager and on filters.

Because DirectShow objects are COM-based objects, it is a natural extension to use other COM interfaces published in the COM specifications to perform functions such as listing property pages or accessing files. Following are some of the COM interfaces that are commonly used in DirectShow filters.

  • IPersistFile
  • ISpecifyPropertyPages

Interfaces on a Typical Filter Graph

Perhaps the best way to put the DirectShow interfaces into perspective is to look at the interfaces exposed in a simple filter graph. The example chosen here is a filter graph that plays back audio data stored on a disk. It is composed of a source filter and an audio renderer filter (no transforms are done, so this is a very simple graph).

The basic source filter consists of an IBaseFilter interface, and one output pin that can be found by using the IBaseFilter::EnumPins method. The COM IPersist interface might also be present on the filter (not shown here) to enable the filter to be stored as part of a persistent filter graph.

The output pin supports IPin and IMediaPosition, since the source filter is a seekable filter (that is, it can be told to move to a particular position in the media stream). The following illustration shows the interfaces on the source filter and its output pin.

Note that quality management is not implemented in this example, but could be by including the IQualityControl interface on the output pin as well.

Basic source filter

The basic renderer filter consists of a COM driver supporting the IBaseFilter (and, again, IMediaFilter by inheritance) and IMediaPosition interfaces, as well as having one input pin through the EnumPins method of the IBaseFilter interface. The COM IPersistFile interface might also be present on the filter (not shown here) in order load the file. The renderer can support additional interfaces, such as IReferenceClock (as a master for synchronization) or IBasicAudio, for an audio renderer as shown here.

The input pin supports the IPin and IMemInputPin interfaces. Methods of the IMediaPosition interface on the renderer filter can call the IMediaPosition interface methods of the output pin that is connected to the renderer's input pin.

Basic renderer filter

A basic representation of the connection of a source filter to a renderer filter follows:

Source and renderer connection

Once the pins are enumerated and connected, it is the implementation of the output and input pins that defines the interactions of the two pins.

Once the filters are connected, the control available to the user (filter graph manager) is indicated through the bold interfaces. This continues with the example of connecting an audio source to an audio renderer.

Illustration of filter connection, showing some bold interfaces

The following interfaces are those that would likely be used during a transport.

  • IMediaPosition supports the ability to seek to a position and change the rate.
  • IBasicAudio supports the ability to set the volume.
  • IBaseFilter supports such methods as Run and Pause (methods on the filter graph manager's IMediaControl interface).

Special (custom) interfaces that the filters would support must be obtained directly from the filters. Usage of these interfaces implies that the user is aware of their identifiers.


DirectShow Interfaces by Category

The following lists group the Microsoft® DirectShow™ interfaces according to whether application or filter developers typically call them, or whether they are exposed at the filter graph level. Both application and filter developers can call some interfaces, while others have a typical use by one or the other, but both types of developers can still call them. See the documentation about each interface for more information. Each of the categories (Application-Level Interfaces, Graph-Level Interfaces, and Filter-Level Interfaces) is divided into functional groupings.

In addition, the Multimedia Streaming Reference contains documentation on interfaces specific to multimedia streaming.

Application-Level Interfaces

  • IAMCollection
  • IAMCopyCaptureFileProgress
  • IAMLine21Decoder
  • IAMVfwCaptureDialogs
  • IAMVfwCompressDialogs
  • ICaptureGraphBuilder
  • IDistributorNotify
  • IEnumPins
  • IFileSourceFilter
  • IGraphBuilder
  • IMediaStream
  • IMultiMediaStream
  • ISeekingPassThru
  • IStreamSample
  • IVPBaseNotify
  • IVPNotify
  • IVPNotify2

Digital Versatile Disc (DVD) Application-Level Interfaces

  • IDvdControl
  • IDvdGraphBuilder
  • IDvdInfo

Cutlist Application-Level Interfaces

  • ICutListGraphBuilder
  • IFileClip
  • IStandardCutList

Cutlist Application-Level or Filter-Level Interfaces

  • IAMAudioCutListElement
  • IAMCutListElement
  • IAMFileCutListElement
  • IAMVideoCutListElement

Capture, Compression, Device Enumeration, and Windows Driver Model (WDM) Capture Application-Level or Filter-Level Interfaces

  • IAMAudioInputMixer
  • IAMBufferNegotiation
  • IAMCrossbar
  • IAMTVTuner
  • IAMDroppedFrames
  • IAMStreamConfig
  • IAMStreamControl
  • IAMStreamSelect
  • IAMVideoCompression
  • IAMVideoProcAmp
  • IConfigAviMux
  • IConfigInterleaving
  • ICreateDevEnum
  • IFileSinkFilter
  • IFileSinkFilter2
  • IMediaPropertyBag
  • IMixerPinConfig
  • IMixerPinConfig2

Device Control, Timecode, and Property Set Application-Level or Filter-Level Interfaces

  • IAMExtDevice
  • IAMExtTransport
  • IAMTimecodeDisplay
  • IAMTimecodeGenerator
  • IAMTimecodeReader
  • IAMVideoControl
  • IKsPropertySet

Graph-Level Interfaces

  • IAMovie
  • IBasicAudio
  • IBasicVideo
  • IDeferredCommand
  • IDirectDrawVideo
  • IDistributorNotify
  • IEnumFilters
  • IEnumRegFilters
  • IFilterGraph
  • IFilterGraph2
  • IFilterInfo
  • IFilterMapper
  • IFullScreenVideo
  • IGraphVersion
  • IMediaControl
  • IMediaEvent
  • IMediaEventEx
  • IMediaEventSink
  • IMediaPosition
  • IMediaSeeking
  • IMediaTypeInfo
  • IQualityControl
  • IQualProp
  • IQueueCommand
  • IReferenceClock
  • IRegFilterInfo
  • IResourceConsumer
  • IResourceManager
  • IVideoWindow

Filter-Level Interfaces

  • IAMovieSetup
  • IAsyncReader
  • IBaseFilter
  • IBasicAudio
  • IBasicVideo
  • IEnumMediaTypes
  • IMediaFilter
  • IMemInputPin
  • IOverlay
  • IOverlayNotify
  • IPin
  • IPinInfo
  • IVPBaseConfig
  • IVPConfig

DirectSound Filter-Level Interface

  • IAMDirectSound

Memory Allocation and Media Sample Filter-Level Interfaces

  • IAMDevMemoryAllocator
  • IAMDevMemoryControl
  • IMediaSample
  • IMediaSample2
  • IMemAllocator

COM Interfaces

  • IUnknown


IAMAudioCutListElement Interface

The IAMAudioCutListElement interface provides support for a cutlist element for an audio file stream in a WAV or AVI file.

See About Cutlists and Using Cutlists for more information.

When to Implement

Usually, you don't need to implement this interface because DirectShow provides the CLSID_AudioFileClip object that implements it for you. Implement this interface in your application when you need to change the default behavior of this interface.

When to Use

Use this interface in your filter when you specify an audio-based media clip. Call QueryInterface on the IAMCutListElement interface to determine if the element is an audio type element.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMAudioCutListElement methods | Description
GetStreamIndex | Retrieves the index to the stream in the AVI file.
HasFadeIn | Determines if the element fades in automatically.
HasFadeOut | Determines if the element fades out automatically.

IAMAudioCutListElement::GetStreamIndex

IAMAudioCutListElement Interface

Retrieves the index to the stream in the AVI file.

HRESULT GetStreamIndex(
DWORD *piStream
);

Parameters
piStream
[out] Stream number to be opened.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

This method must always retrieve zero for the stream index. For AVI files, only the first audio stream is supported.

IAMAudioCutListElement::HasFadeIn

IAMAudioCutListElement Interface

Determines if the element fades in automatically.

HRESULT HasFadeIn(void);

Return Values

Returns S_OK if the element should be automatically faded in, or S_FALSE if not.

Remarks

This method always returns S_OK, but fading in and out is not currently supported.

IAMAudioCutListElement::HasFadeOut

IAMAudioCutListElement Interface

Determines if the element fades out automatically.

HRESULT HasFadeOut(void);

Return Values

Returns S_OK if the element should be automatically faded out, or S_FALSE if not.

Remarks

This method always returns S_OK, but fading in and out is not currently supported.


IAMAudioInputMixer Interface

The IAMAudioInputMixer interface tells an audio capture filter what level, panning, and equalizer to use for each input. The name of each pin, such as "Line input 1" or "Mic", reflects the type of input.

Implementation of the methods on this interface depends on the device. A device might not implement all methods depending on its capabilities.

When to Implement

Implement this interface on each input pin of an audio capture filter. You can also implement this interface on the audio capture filter itself to control the overall record level and panning after the audio mixing occurs.

When to Use

Use this interface when your application needs to adjust audio input characteristics such as mixing of a particular input, use of mono or stereo, mix level, pan level, loudness, treble, and bass settings. Use the pin names to decide how to set the recording levels for each type of input.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMAudioInputMixer methods | Description
put_Enable | Enables or disables an input in the mix.
get_Enable | Retrieves whether the input is enabled.
put_Mono | Combines all channels of an input into a mono signal.
get_Mono | Retrieves whether all channels of an input are combined into a mono signal.
put_MixLevel | Sets the record level for this input.
get_MixLevel | Retrieves the recording level for this input.
put_Pan | Sets the pan for this input.
get_Pan | Retrieves the pan for this input.
put_Loudness | Turns the loudness control for this input on or off.
get_Loudness | Retrieves the loudness control setting for this input.
put_Treble | Sets the treble equalization for this input.
get_Treble | Retrieves the treble equalization for this input.
get_TrebleRange | Retrieves the treble range for this input.
put_Bass | Sets the bass equalization for this input.
get_Bass | Retrieves the bass equalization for this input.
get_BassRange | Retrieves the bass range for this input.

IAMAudioInputMixer::get_Bass

IAMAudioInputMixer Interface

Retrieves the bass equalization for this input.

HRESULT get_Bass(
double *pBass
);

Parameters
pBass
[in] Pointer to the bass gain in decibels (a negative value means attenuate).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_BassRange

IAMAudioInputMixer Interface

Retrieves the bass range for this input.

HRESULT get_BassRange(
double *pRange
);

Parameters
pRange
[out, retval] Largest value allowed in the bass range specified in put_Bass. For example, 6.0 means any value between -6.0 and 6.0 is allowed.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_Enable

IAMAudioInputMixer Interface

Retrieves whether the input is enabled.

HRESULT get_Enable(
BOOL *pfEnable
);

Parameters
pfEnable
[in] Pointer to a value indicating whether mixing is enabled for the input. TRUE indicates the input is enabled, FALSE indicates the input is disabled.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Couldn't retrieve information.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_Loudness

IAMAudioInputMixer Interface

Retrieves the loudness control setting for this input.

HRESULT get_Loudness(
int *pfLoudness
);

Parameters
pfLoudness
[in] Pointer to value indicating whether loudness is on or off. TRUE indicates on, FALSE indicates off.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
E_OUTOFMEMORY | Out of memory.
NOERROR | Success.

IAMAudioInputMixer::get_MixLevel

IAMAudioInputMixer Interface

Retrieves the recording level for this input.

HRESULT get_MixLevel(
double *pLevel
);

Parameters
[out] pLevel
Pointer to the value of the recording level. Values range between 0 (off) and 1 (full volume). AMF_AUTOMATICGAIN (-0x0001), if supported, means automatic adjustment of level.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error retrieving recording level.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_Mono

IAMAudioInputMixer Interface

Retrieves whether all channels of an input are combined into a mono signal.

HRESULT get_Mono(
BOOL *pfMono
);

Parameters
pfMono
[in] Pointer to a value indicating whether mono is enabled. TRUE indicates mono is enabled, FALSE indicates mono is disabled.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error getting mono control.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_Pan

IAMAudioInputMixer Interface

Retrieves the pan level for this input.

HRESULT get_Pan(
double * pPan
);

Parameters
pPan
[in] Pointer to the value of the pan level. Possible levels are from -1 to 1, with specific values as follows:
Value | Meaning
-1 | Full left
0 | Center
1 | Full right
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error retrieving pan level.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Can't pan: not stereo.
NOERROR | Success.

IAMAudioInputMixer::get_Treble

IAMAudioInputMixer Interface

Retrieves the treble equalization for this input.

HRESULT get_Treble(
double *pTreble
);

Parameters
pTreble
[in] Pointer to the treble gain in decibels (a negative value means attenuate).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::get_TrebleRange

IAMAudioInputMixer Interface

Retrieves the treble range for this input.

HRESULT get_TrebleRange(
double *pRange
);

Parameters
pRange
[out, retval] Largest value allowed in the treble range. This is the maximum value allowed in put_Treble. For example, 6.0 means any value between -6.0 and 6.0 is allowed.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

IAMAudioInputMixer::put_Bass

IAMAudioInputMixer Interface

Sets the bass equalization for this input.

HRESULT put_Bass(
double Bass
);

Parameters
Bass
[in] Gain in decibels (a negative value means attenuate).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Argument is invalid. Must be in range given by get_BassRange.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

Remarks

Boosts or cuts the signal's bass before it is recorded by the number of decibels specified by Bass.

IAMAudioInputMixer::put_Enable

IAMAudioInputMixer Interface

Enables or disables an input in the mix.

HRESULT put_Enable(
BOOL fEnable
);

Parameters
fEnable
[in] Value to enable or disable an input. TRUE enables the input, FALSE disables it.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failed to enable or disable an input.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Successfully enabled or disabled an input.

Remarks

If disabled, this input will not be mixed in as part of the recorded signal.

IAMAudioInputMixer::put_Loudness

IAMAudioInputMixer Interface

Turns the loudness control for this input on or off.

HRESULT put_Loudness(
BOOL fLoudness
);

Parameters
fLoudness
[in] TRUE sets loudness on, FALSE sets loudness off.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Loudness control set.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

Remarks

IAMAudioInputMixer::put_Loudness boosts the bass of low volume signals before they are recorded to compensate for the fact that your ear doesn't hear quiet bass sounds as well as other sounds.

IAMAudioInputMixer::put_MixLevel

IAMAudioInputMixer Interface

Sets the record level for this input.

HRESULT put_MixLevel(
double Level
);

Parameters
Level
Recording level. Values range between 0 (off) and 1 (full volume). AMF_AUTOMATICGAIN (-0x0001), if supported, means automatic adjustment of level.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error setting volume.
E_POINTER | Null pointer argument.
E_INVALIDARG | Record level must be between 0 and 1.
E_NOTIMPL | Automatic gain currently not implemented.
NOERROR | Success.

IAMAudioInputMixer::put_Mono

IAMAudioInputMixer Interface

Combines all channels of an input into a mono signal.

HRESULT put_Mono(
BOOL fMono
);

Parameters
fMono
[in] TRUE indicates mono, FALSE indicates multichannel.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error setting mono control.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

Remarks

When set to mono mode, making a stereo recording of this input will have both channels contain the same data. The result will be a mixture of the left and right signals.

IAMAudioInputMixer::put_Pan

IAMAudioInputMixer Interface

Sets the pan for this input.

HRESULT put_Pan(
double Pan
);

Parameters
Pan
[in] Pan level. Possible values for Pan are from -1 to 1, with specific values as follows:
Value | Meaning
-1 | Full left
0 | Center
1 | Full right
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Error setting volume.
E_POINTER | Null pointer argument.
E_INVALIDARG | Pan level must be between -1 and 1.
E_NOTIMPL | Can't pan: not stereo.
NOERROR | Success.

Remarks

Setting the pan of an input to full left makes that input's signal go only into the left channel of a stereo recording. Panning has no effect for a mono recording.

IAMAudioInputMixer::put_Treble

IAMAudioInputMixer Interface

Sets the treble equalization for this input.

HRESULT put_Treble(
[in] double Treble
);

Parameters
Treble
[in] Gain in decibels (a negative value means attenuate).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Argument is invalid. Must be in range given by get_TrebleRange.
E_NOTIMPL | Method isn't supported.
NOERROR | Success.

Remarks

This method boosts or cuts the signal's treble by a specified number of decibels before it is recorded.


IAMBufferNegotiation Interface

The IAMBufferNegotiation interface tells a pin what kind of buffer specifications it should use when connected. Use this interface when an application requires control over allocating the number of buffers that pins will use when transporting media samples between filters.

The IAMBufferNegotiation::SuggestAllocatorProperties method accepts an ALLOCATOR_PROPERTIES structure that contains the allocator's count, size, alignment, and prefix properties that you want to use. Typically, you set only the cBuffers member of the ALLOCATOR_PROPERTIES structure, which refers to the number of buffers at the specified allocator. All other properties should indicate a negative number to enable your capture hardware to use its own default values.

If a negative value is specified for cBuffers, the allocator will try to allocate as many buffers as it needs, which depends on the available resources and capture frame rate. If you specify a higher value, the allocator will try to allocate more buffers, up to the system's available memory. Allocating a lower number of buffers can result in dropped frames. For teleconferencing applications, it may be desirable to set this number to a smaller value (for example, 2 is a reasonable setting if the network can only support transmission of 2 frames per second (fps) at a given video format and resolution).

Applications can call the IAMBufferNegotiation::GetAllocatorProperties method to retrieve the properties of the allocator being used.

When to Implement

Implement this interface when your pin will connect to another pin by using the IMemInputPin interface and you want to enable an application to allocate the buffer settings to be used for transporting media samples between filters. All capture filters should support this interface to enable applications to specify precise settings for buffers (see Vidcap.cpp and Vidcap.h in the \Samples\DS\Vidcap directory for a sample implementation).

When to Use

Teleconferencing applications should use this interface to specify a minimal number of buffers. This tells the capture filter not to waste resources buffering information in slower capture or disk-writing scenarios.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMBufferNegotiation methods | Description
SuggestAllocatorProperties | Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.
GetAllocatorProperties | Retrieves the properties of the allocator being used by a pin.

IAMBufferNegotiation::GetAllocatorProperties

IAMBufferNegotiation Interface

Retrieves the properties of the allocator that a pin is using.

HRESULT GetAllocatorProperties(
ALLOCATOR_PROPERTIES *pprop
);

Parameters
pprop
[out] Pointer to an ALLOCATOR_PROPERTIES structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Call this method only after the pins connect.

See Also

SuggestAllocatorProperties

IAMBufferNegotiation::SuggestAllocatorProperties

IAMBufferNegotiation Interface

Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.

HRESULT SuggestAllocatorProperties(
const ALLOCATOR_PROPERTIES *pprop
);

Parameters
pprop
[in] Pointer to an ALLOCATOR_PROPERTIES structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

An application must call this function before two pins are connected. If the pins are connected before you call this method, then the filter graph will have already negotiated the buffer and it will be too late for an application to preallocate them.

Applications must call this method on both pins being connected to ensure that the other pin doesn't overrule the application's request. However, if one pin doesn't support this interface, a single call will be sufficient.

Use a negative number for any element in the ALLOCATOR_PROPERTIES structure to set properties to default values.

See Also

IAMBufferNegotiation::GetAllocatorProperties

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMCollection Interface

The filter graph manager exposes IAMCollection, which allows access to collections of objects such as those exporting IPinInfo and IFilterInfo interfaces.

When to Implement

This interface is implemented by the filter graph manager for use by Automation client applications, such as Microsoft® Visual Basic®.

When to Use

Applications that use Automation use this interface indirectly when retrieving collections of objects. For example, the IFilterInfo::get_Pins method retrieves an IAMCollection interface that can be used to access the IPinInfo interfaces corresponding to the pins on the filter.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IAMCollection methods | Description
get_Count | Retrieves the number of items in the collection.
get_NewEnum | Retrieves an enumerator object that implements IEnumVARIANT on this collection.
Item | Retrieves the indexed item from the collection.

IAMCollection::get_Count

IAMCollection Interface

Retrieves the number of items in the collection.

HRESULT get_Count(
LONG *plCount
);

Parameters
plCount
[out, retval] Number of items in the collection.
Return Values

Returns an HRESULT value.

IAMCollection::get_NewEnum

IAMCollection Interface

Retrieves an enumerator object that implements IEnumVARIANT on this collection.

HRESULT get_NewEnum(
IUnknown **ppUnk
);

Parameters
ppUnk
[out, retval] IUnknown for an object that implements IEnumVARIANT on this collection.
Return Values

Returns an HRESULT value.

IAMCollection::Item

IAMCollection Interface

Retrieves the indexed item from the collection.

HRESULT Item(
long lItem,
IUnknown **ppUnk
);

Parameters
lItem
[in] Index into the collection.
ppUnk
[out] Returned IUnknown interface for the contained item.
Return Values

Returns an HRESULT value.

Remarks

The returned ppUnk parameter represents an object corresponding to the type of objects in the container. It can be an IFilterInfo, IPinInfo, or IMediaTypeInfo object. The index is zero-based.


IAMCopyCaptureFileProgress Interface

The IAMCopyCaptureFileProgress interface contains one method, Progress, which the ICaptureGraphBuilder::CopyCaptureFile method can call to receive information on the percentage complete of a copy operation.

When to Implement

Capture applications implement this method when they need to receive information on the percentage complete of a copy operation.

When to Use

Use this interface when applications need to check the copying progress of a captured file.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMCopyCaptureFileProgress methods | Description
Progress | Sends applications the progress (percentage complete) of a copy operation that the ICaptureGraphBuilder::CopyCaptureFile method is performing.

IAMCopyCaptureFileProgress::Progress

IAMCopyCaptureFileProgress Interface

Sends applications the progress (percentage complete) of a copy operation that the ICaptureGraphBuilder::CopyCaptureFile method is performing.

HRESULT Progress(
int iProgress
);

Parameters
iProgress
[in] Percentage of copy complete between 0 and 100.
Return Values

Returns S_OK if successful or S_FALSE if the operation is aborted.

Remarks

The ICaptureGraphBuilder::CopyCaptureFile can call this method to inform applications of the copy operation's progress.

This method is called periodically while ICaptureGraphBuilder::CopyCaptureFile is running.


IAMCrossbar Interface

The IAMCrossbar interface is exposed on analog video crossbar filters and is used to route messages from an analog or digital audio or video source to a video capture filter. The crossbar filter is modeled after a general switching matrix, with n inputs and m outputs. Any of the input signals can be routed to one or more of the outputs.

A single crossbar can route both video and audio signals. You can also use a video pin to route only the audio portion of a combined signal.

This filter is based on a simple multiplexer.

When to Implement

Implement this interface when your filter needs to route analog or digital signals to a capture filter.

When to Use

Use this interface when your application needs to route analog or digital video signals through a crossbar filter.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMCrossbar methods | Description
get_PinCounts | Retrieves the number of input and output pins.
CanRoute | Determines if the crossbar filter can route the analog or digital signal.
Route | Routes an input pin to an output pin.
get_IsRoutedTo | Retrieves the input pin connected to a given output pin.
get_CrossbarPinInfo | Retrieves a pin that has audio or video data relating to a given pin.

IAMCrossbar::CanRoute

IAMCrossbar Interface

Determines if routing is possible.

HRESULT CanRoute (
long OutputPinIndex,
long InputPinIndex
);

Parameters
OutputPinIndex
[in] Output pin.
InputPinIndex
[in] Input pin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMCrossbar::get_CrossbarPinInfo

IAMCrossbar Interface

Retrieves a pin that has audio or video data relating to a given pin.

HRESULT get_CrossbarPinInfo (
BOOL IsInputPin,
long PinIndex,
long * PinIndexRelated,
long * PhysicalType
);

Parameters
IsInputPin
[in] Specify TRUE for an input pin; FALSE for an output pin.
PinIndex
[in] Pin to find a related pin for.
PinIndexRelated
[out] Index value of the related pin.
PhysicalType
[out] Physical type of pin (audio or video).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method retrieves, for example, the audio pin related to a given video pin.

IAMCrossbar::get_IsRoutedTo

IAMCrossbar Interface

Retrieves the input pin connected to a given output pin.

HRESULT get_IsRoutedTo (
long OutputPinIndex,
long * InputPinIndex
);

Parameters
OutputPinIndex
[in] Output pin.
InputPinIndex
[out] Pointer to the connected input pin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMCrossbar::get_PinCounts

IAMCrossbar Interface

Retrieves the number of input and output pins.

HRESULT get_PinCounts(
long * OutputPinCount,
long * InputPinCount
);

Parameters
OutputPinCount
[out] Number of output pins.
InputPinCount
[out] Number of input pins.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMCrossbar::Route

IAMCrossbar Interface

Routes an input pin to an output pin.

HRESULT Route (
long OutputPinIndex,
long InputPinIndex
);

Parameters
OutputPinIndex
[in] Output pin.
InputPinIndex
[in] Input pin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Pin indexes are zero based.


IAMCutListElement Interface

The IAMCutListElement interface describes a base object, which represents an element in a cutlist. For a simpler interface that provides basic cutlist functionality, applications can use IFileClip to create an object that supports this interface.

See About Cutlists and Using Cutlists for more information.

When to Implement

Usually, you don't need to implement this interface because DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects, which can create an object that implements it for you. However, you can implement this interface in your application when you need to change this interface's default behavior.

When to Use

Use this interface in your filter when you need to get specific elements of a cutlist.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMCutListElement methods | Description
GetElementStartPosition | Retrieves the media time of the element's start in the time scale of the cutlist.
GetElementDuration | Retrieves the duration of the cutlist element.
IsFirstElement | Determines if the element is the first in the cutlist.
IsLastElement | Determines if the element is the last in the cutlist.
IsNull | Determines if the element is null.
ElementStatus | Determines the status of the element.

IAMCutListElement::ElementStatus

IAMCutListElement Interface

Determines the status of the element.

HRESULT ElementStatus(
DWORD *pdwStatus,
DWORD dwTimeoutMs
);

Parameters
pdwStatus
[in/out] Status. On input, if this parameter contains CL_WAIT_FOR_STATE and an additional state value from the CL_ELEM_STATUS enumerated data type, this method waits dwTimeoutMs milliseconds until the element is in that state before returning. On output, this is a logical combination of flags from the CL_ELEM_STATUS enumerated data type.
dwTimeoutMs
[in] Timeout value, in milliseconds.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
S_OK | Success. The element is null.

IAMCutListElement::GetElementDuration

IAMCutListElement Interface

Retrieves the duration of the cutlist element.

HRESULT GetElementDuration(
REFERENCE_TIME *pmtDuration
);

Parameters
pmtDuration
[out] Duration of the element in REFERENCE_TIME.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

When you call the IFileClip::CreateCut method to create the element, the difference between its mtTrimOut and mtTrimIn parameters determines the duration.

IAMCutListElement::GetElementStartPosition

IAMCutListElement Interface

Retrieves the media time of the element's start in the time scale of the cutlist.

HRESULT GetElementStartPosition(
REFERENCE_TIME *pmtStart
);

Parameters
pmtStart
[out] Pointer to the media time for the start of the element.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

Times retrieved by this method are relative to the time within the cutlist. For example, the first element in the cutlist starts at time zero.

IAMCutListElement::IsFirstElement

IAMCutListElement Interface

Determines if the element is the first in the cutlist.

HRESULT IsFirstElement(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
S_OK | Success. This is the first element in the cutlist.

IAMCutListElement::IsLastElement

IAMCutListElement Interface

Determines if the element is the last in the cutlist.

HRESULT IsLastElement(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
S_OK | Success. This is the last element in the cutlist.

IAMCutListElement::IsNull

IAMCutListElement Interface

Determines if the element is null.

HRESULT IsNull(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
S_FALSE | Element is not null.
S_OK | Success. The element is null.


IAMDevMemoryAllocator Interface

The IAMDevMemoryAllocator interface enables the creation of third-party memory allocators by using an on-board memory manager object. Many codec hardware manufacturers put on-board mapped memory for the codecs to improve the efficiency of buffer manipulation. This interface allocates that memory and provides the GetDevMemoryObject method to retrieve a device memory control object, which supports the IAMDevMemoryControl interface. Devices that share the same device ID can use the memory.

The global memory manager object exposes this interface to allocate memory from memory that is on a particular device.

When to Implement

Implement this interface when your pin must support the creation of on-board memory allocators. Source filters that are aware of on-board memory and need to create their own allocators should query for this interface, request an amount of memory and then create an allocator (aggregating the device memory control object). Source filters that don't need to create their own allocator could just use the allocator of the downstream pin (which also aggregates the device memory control object). The hardware-based filter can confirm the usage of its on-board memory by calling methods on the aggregated allocator.

When to Use

Use this interface when applications need to control the memory of codecs with on-board memory.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMDevMemoryAllocator methods | Description
GetInfo | Retrieves information about the memory capabilities.
CheckMemory | Tests whether a memory pointer was allocated by the specific instance (device) of the allocator.
Alloc | Allocates a memory buffer.
Free | Frees the previously allocated memory.
GetDevMemoryObject | Retrieves an IUnknown interface pointer to a device memory control object that can be aggregated with a custom allocator.

IAMDevMemoryAllocator::Alloc

IAMDevMemoryAllocator Interface

Allocates a memory buffer.

HRESULT Alloc(
BYTE **ppBuffer,
DWORD *pdwcbBuffer
);

Parameters
ppBuffer
[out] Address of a pointer to the allocated memory buffer.
pdwcbBuffer
[in, out] For input, the number of bytes to allocate. For output, the number of actual bytes allocated.
Return Values

Returns S_OK if the desired quantity of memory was allocated, S_FALSE if memory was unavailable.

Remarks

Call this method to allocate a block of memory from the available pool.

See Also

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator::CheckMemory

IAMDevMemoryAllocator Interface

Tests whether a memory pointer was allocated by the specific instance (device) of the allocator.

HRESULT CheckMemory(
const BYTE *pBuffer
);

Parameters
pBuffer
[in] Pointer to the allocated memory buffer's address.
Return Values

Returns S_OK if the on-board allocator allocated the memory, or S_FALSE if not. Memory that is on the particular device but not allocated will also return S_FALSE.

Remarks

The hardware filter typically uses this method to test whether the pointer actually points to on-board memory.

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator Interface

Frees the previously allocated memory.

HRESULT Free(
BYTE *pBuffer
);

Parameters
pBuffer
[in] Pointer to the allocated memory.
Return Values

Returns E_INVALIDARG if the specified allocator didn't allocate the memory (that is, CheckMemory fails).

Remarks

This method frees a block of memory from the pool.

IAMDevMemoryAllocator::GetDevMemoryObject

IAMDevMemoryAllocator Interface

Retrieves an IUnknown interface pointer to a device memory control object that can be aggregated with a custom allocator.

HRESULT GetDevMemoryObject(
IUnknown **ppUnkInnner,
IUnknown *pUnkOuter
);

Parameters
ppUnkInnner
[out] Address of a pointer to the newly created control object's own IUnknown. This inner IUnknown interface should be released when the outer object is destroyed. The custom allocator should call the QueryInterface method on this pointer to obtain the IAMDevMemoryControl interface.
pUnkOuter
[in] Pointer to the custom allocator's own IUnknown interface. This interface aggregates the device memory control object inside the custom allocator.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The device memory control object is necessary to aggregate with the custom allocator, because renderers that require the use of on-board memory will query for IAMDevMemoryControl when they receive a new allocator, to verify that the memory is from the same device. This occurs because the hardware filter will receive an IMemAllocator object, which might or might not use the on-board memory. To decide if it is a compatible allocator, the object would query for the IAMDevMemoryControl interface to access specific methods. The IAMDevMemoryControl creates an aggregated object that implements the methods of IAMDevMemoryControl (these are often hardware-specific).

See COM documentation for rules on how the outer object implements aggregation.

IAMDevMemoryAllocator::GetInfo

IAMDevMemoryAllocator Interface

Retrieves information about the memory capabilities.

HRESULT GetInfo(
DWORD *pdwcbTotalFree,
DWORD *pdwcbLargestFree,
DWORD *pdwcbTotalMemory,
DWORD *pdwcbMinimumChunk
);

Parameters
pdwcbTotalFree
[out] Total free memory size.
pdwcbLargestFree
[out] Retrieves the largest free memory size.
pdwcbTotalMemory
[out] Retrieves the total memory size.
pdwcbMinimumChunk
[out] Retrieves the minimum chunk size, giving granularity and alignment rules.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to find out the total amount of memory available. This method returns values for the entire on-board memory that is available on that device. If multiple filters (devices) share the memory, it will return the amount available to that specific device, which might be a portion of the total amount of on-board memory. This amount will be implementation-specific. For example, the on-board memory manager on the codec might be able to access all 32 megabytes (MB) of memory on the card. However, individual pin implementations of IAMDevMemoryAllocator only report a portion of this memory.


IAMDevMemoryControl Interface

The IAMDevMemoryControl interface controls and identify the on-board memory of codecs. A device memory control object supports this interface. This object is aggregated with an IMemAllocator object that is used in the connection. Typically, filters will call the IAMDevMemoryAllocator::GetDevMemoryObject method to obtain a pointer to this interface.

When to Implement

Implement this interface with the IAMDevMemoryAllocator interface when pins need to have greater control of memory allocation.

When to Use

Use this interface to synchronize the completed data write of a memory allocator, and to get the device ID of the on-board memory allocator.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMDevMemoryControl methods | Description
QueryWriteSync | Checks if the memory supported by the allocator requires the use of the WriteSync method.
WriteSync | Used to synchronize with the completed write. This method returns when any data being written to the specified allocator region is fully written into the memory.
GetDevId | Retrieves the device ID of the on-board memory allocator.

IAMDevMemoryControl::GetDevId

IAMDevMemoryControl Interface

Retrieves the device ID of the on-board memory allocator.

HRESULT GetDevId(
DWORD *pdwDevId
);

Parameters
pdwDevId
[out] Pointer to the device ID.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method retrieves a unique ID that the hardware filter can use to verify that the specified allocator passed uses its on-board memory (because there can be more than one). The ID will be the same one as used to create the allocator object (using CoCreateNamedInstance). For another filter to be able to use the on-board memory, it must have the same device ID as the on-board memory allocator.

IAMDevMemoryControl::QueryWriteSync

IAMDevMemoryControl Interface

Checks if the memory supported by the allocator requires the use of the IAMDevMemoryControl::WriteSync method.

HRESULT QueryWriteSync( );

Return Values

Returns S_OK if the method is required, or S_FALSE otherwise.

Remarks

Not all on-board memory needs to have WriteSync called to synchronize with the completed write. This method is used to check if the call is necessary.

IAMDevMemoryControl::WriteSync

IAMDevMemoryControl Interface

Used to synchronize with the completed write. This method returns when any data being written to the particular allocator region is fully written into the memory.

HRESULT WriteSync( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Common return values include:
Value | Meaning
E_FAIL | A time-out has occurred without confirming that data was written.
S_OK | Operation proceeded normally.
VFW_E_NOT_COMMITTED | The allocator hasn't called the IMemAllocator::Commit method.

Remarks

This method guarantees that all prior write operations to allocated memory have succeeded. Subsequent memory write operations require another call to WriteSync.

This method is implementation dependent, and is used (when necessary) to synchronize memory write operations to the memory. The driver of the on-board memory provides the implementation.

The IAMDevMemoryControl interface is typically found on memory that is accessed through a PCI-bridge. Memory behind a PCI bridge must be synchronized after a memory write operation completes if another device will access that memory from behind the PCI bridge. This is because the host access to the memory is buffered via the PCI bridge FIFO (first in first out), and the host will think the write is completed before the bridge actually writes the data. A subsequent action by a device behind the bridge, such as a SCSI controller, might read the memory before the write is completed if the IAMDevMemoryControl::WriteSync method is not called.


IAMDirectSound Interface

The IAMDirectSound interface provides access from Microsoft® DirectShow™ to Microsoft DirectX™ audio interfaces, such as IDirectSound and IDirectSoundBuffer. This enables you to play back the audio portions of DirectShow-compatible media files anywhere within the 3-D space of a DirectX application, making your applications much more absorbing and lifelike.

After you connect the media source file to a sound renderer on a filter graph, you can use DirectSound's functionality to position or manipulate the sound playback as needed. For more information on the relevant DirectSound interfaces and methods, see the DirectX SDK documentation. After you finish with an interface you obtained through IAMDirectSound, be sure to release it by calling the appropriate method. If you disconnect the sound renderer from the graph before releasing the interfaces, your application might fail.

The DSound Audio Renderer filter implements this interface.

Note Only the GetWindowFocus and SetWindowFocus methods are currently implemented for this interface.

When to Implement

This interface is implemented by the DSound Audio Renderer filter.

When to Use

The DSound Audio Renderer filter uses this interface; it is not intended for other uses.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMDirectSound methods | Description
GetDirectSoundInterface | Retrieves a handle to the current sound device's IDirectSound interface. Not currently implemented.
GetPrimaryBufferInterface | Retrieves a handle to the current sound device's primary sound buffer. Not currently implemented.
GetSecondaryBufferInterface | Retrieves a handle to the current sound device's secondary sound buffer. Not currently implemented.
ReleaseDirectSoundInterface | Releases the current sound device's IDirectSound interface. Not currently implemented.
ReleasePrimaryBufferInterface | Releases the current sound device's primary sound buffer. Not currently implemented.
ReleaseSecondaryBufferInterface | Releases the current sound device's secondary sound buffer. Not currently implemented.
SetWindowFocus | Sets the window that will handle sound playback for the current media file.
GetWindowFocus | Retrieves the window that is handling sound playback for the current media file.

IAMDirectSound::GetDirectSoundInterface

IAMDirectSound Interface

Retrieves a handle to the current sound device's IDirectSound interface. Not currently implemented.

HRESULT IAMDirectSound::GetDirectSoundInterface(
LPDIRECTSOUND *lplpds
);

Parameters
lplpds
Address of a pointer to an IDirectSound interface that will point to the current sound device's interface.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | No sound device is available.
E_INVALIDARG | The lplpds parameter is null.
E_NOTIMPL | DirectSound isn't installed.
NOERROR | The method succeeded.

IAMDirectSound::GetPrimaryBufferInterface

IAMDirectSound Interface

Retrieves a handle to the current sound device's primary sound buffer. Not currently implemented.

HRESULT IAMDirectSound::GetDirectSoundInterface(
LPDIRECTSOUNDBUFFER *lplpdsb
);

Parameters
lplpdsb
Address of a pointer to an IDirectSoundBuffer interface that will point to the current sound device's primary sound buffer.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | No sound device is available.
E_INVALIDARG | The lplpdsb parameter is null.
E_NOTIMPL | DirectSound isn't installed.
NOERROR | The method succeeded.

IAMDirectSound::GetSecondaryBufferInterface

IAMDirectSound Interface

Retrieves a handle to the current sound device's secondary sound buffer. Not currently implemented.

HRESULT IAMDirectSound::GetSecondaryBufferInterface(
LPDIRECTSOUNDBUFFER *lplpdsb
);

Parameters
lplpdsb
Address of a pointer to an IDirectSoundBuffer interface. On exit, it will point to the current sound device's secondary sound buffer.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | No sound device is available.
E_INVALIDARG | The lplpdsb parameter is null.
E_NOTIMPL | DirectSound isn't installed.
NOERROR | The method succeeded.

IAMDirectSound::GetWindowFocus

IAMDirectSound Interface

Retrieves the window that is handling sound playback for the current media file.

HRESULT IAMDirectSound::GetWindowFocus(
HWND* hWnd,
BOOL bMixingOnOrOff
);

Parameters
hWnd
Handle to the sound playback window. If this value is null, the sound isn't associated with a window; note that Windows NT 4.0 does not currently support windowless sound playback.
bMixingOnOrOff
Value indicating whether to mix the sound (TRUE) or not (FALSE).
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | No sound device is available.
E_INVALIDARG | The hWnd argument is invalid.
E_NOTIMPL | DirectSound isn't installed.
NOERROR | The method succeeded.

IAMDirectSound::ReleaseDirectSoundInterface

IAMDirectSound Interface

Releases the current sound device's IDirectSound interface. Not currently implemented.

HRESULT IAMDirectSound::ReleaseDirectSoundInterface(
LPDIRECTSOUND lpds
);

Parameters
lpds
Pointer to the IDirectSound interface to release.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | There are no references to the specified IDirectSound interface, so it can't be released.
E_INVALIDARG | The lpds parameter is null.
NOERROR | The method succeeded.

IAMDirectSound::ReleasePrimaryBufferInterface

IAMDirectSound Interface

Releases the current sound device's primary sound buffer. Not currently implemented.

HRESULT IAMDirectSound::ReleasePrimaryBufferInterface(
LPDIRECTSOUNDBUFFER lpdsb
);

Parameters
lpdsb
Pointer to the IDirectSoundBuffer interface to release.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | There are no references to the specified IDirectSoundBuffer interface, so it can't be released.
E_INVALIDARG | The lpdsb parameter is null.
NOERROR | The method succeeded.

IAMDirectSound::ReleaseSecondaryBufferInterface

IAMDirectSound Interface

Releases the current sound device's secondary sound buffer. Not currently implemented.

HRESULT IAMDirectSound::ReleaseSecondaryBufferInterface(
LPDIRECTSOUNDBUFFER lpdsb
);

Parameters
lpdsb
Pointer to the IDirectSoundBuffer interface to release.
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | There are no references to the specified IDirectSoundBuffer interface, so it can't be released.
E_INVALIDARG | The lpdsb parameter is null.
NOERROR | The method succeeded.

IAMDirectSound::SetWindowFocus

IAMDirectSound Interface

Sets the window that will handle sound playback for the current media file.

HRESULT IAMDirectSound::SetWindowFocus(
HWND hWnd,
BOOL bMixingOnOrOff
);

Parameters
hWnd
Handle to the sound playback window. If this value is null, the sound will not be associated with any window; note that Windows NT 4.0 does not currently support windowless sound playback.
bMixingOnOrOff
Value indicating whether to mix the sound (TRUE) or not (FALSE).
Return Values

Returns one of the following values.
Value | Meaning
E_FAIL | No sound device is available.
E_INVALIDARG | The hWnd argument is invalid.
E_NOTIMPL | DirectSound isn't installed.
NOERROR | The method succeeded.


IAMDroppedFrames Interface

The IAMDroppedFrames interface provides information to an application from a capture filter about frames that the filter dropped (that is, did not send), the frame rate achieved (the length of time the graph ran divided by the number of frames not dropped), and the data rate achieved (the length of time the graph ran divided by the average frame size). A high number of dropped frames can detract from the smoothness of the video clip.

If your application uses the IAMStreamControl interface or ICaptureGraphBuilder::ControlStream to turn a pin off, a video capture driver may still be counting dropped and non-dropped frames, whose counts probably don't interest you. If your application is interested in the number of dropped and non-dropped frames only while the pin is ON, you can ask for the dropped and non-dropped counts by calling IAMDroppedFrames::GetNumDropped and IAMDroppedFrames::GetNumNotDropped immediately after turning on a pin with IAMStreamControl::StartAt or ICaptureGraphBuilder::ControlStream, and then subtract those numbers from the numbers returned from subsequent calls to GetNumDropped or GetNumNotDropped to find out just the number dropped while the pin was on (which is probably the figure you are interested in). If your call to IAMStreamControl::StartAt or ICaptureGraphBuilder::ControlStream is not a call to turn the pin on immediately, but instead turns the pin on at some specified time in the future, then you should wait until you get the notification (EC_STREAM_CONTROL_STARTED) before calling GetNumDropped and GetNumNotDropped initially. See the documentation on IAMStreamControl for more information on this. See the CAPTURE sample for an example of a capture application that uses both interfaces correctly.

When to Implement

A capture filter's video output pin should always implement this interface.

When a capture filter runs, it sends frame numbers beginning with the sequence 0, 1, 2, 3 (numbers will be missing if frames were dropped). The time stamp of each frame sent corresponds to the filter graph clock's time when the image was digitized. The end time is the start time plus the video frame's duration.

Set the media time of each sample by using CMediaSample::SetMediaTime and using frame numbers for the start and end times. For example, the start-time and end-time sequence might appear as follows: (0,1) (1,2) (2,3). A downstream filter can easily tell that a frame was dropped by checking for gaps in the frame number sequence rather than by looking for gaps in the regular time stamps. The following start-time and end-time sequence reveals that frame number 3 was dropped: (1,2) (2,3) (4,5) (5,6).

Every time a capture filter goes from State_Stopped to State_Paused, it should reset all counts to zero.

If your filter runs, pauses, and then runs again, you must continue to deliver frames as if it never paused. The first frame after the second run can't be time stamped earlier than the last frame sent before the pause. That is, your filter must always increment the media time of each sample sent. Never send the same frame number twice, and never go back in time.

When to Use

Applications should use this interface all the time when capturing to update the current capture status. After capturing is done, applications should use this interface to determine the final capture results.

If you are using a WDM video capture filter, you can only query an output pin for this interface if the capture filter is connected to another filter in the graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMDroppedFrames methods | Description
GetNumDropped | Retrieves the total number of frames that the pin dropped since it last started streaming.
GetNumNotDropped | Retrieves the total number of frames that the pin delivered downstream (did not drop).
GetDroppedInfo | Retrieves an array of frame numbers that were dropped.
GetAverageFrameSize | Retrieves the average size of frames that were not dropped.

IAMDroppedFrames::GetAverageFrameSize

IAMDroppedFrames Interface

Retrieves the average size of frames that the pin dropped.

HRESULT GetAverageFrameSize(
long * plAverageSize );

Parameters
plAverageSize
[out, retval] Average size of frames sent out the pin since the pin started streaming, in bytes.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMDroppedFrames::GetDroppedInfo

IAMDroppedFrames Interface

Retrieves an array of frame numbers that the pin dropped.

HRESULT GetDroppedInfo(
long lSize,
long * plArray,
long * plNumCopied );

Parameters
lSize
[in] Requested number of elements in the array.
plArray
[out] Pointer to the array.
plNumCopied
[out, retval] Pointer to the number of array elements filled in. This number can differ from lSize because the filter determines an arbitrary number of elements to save and it might not save this information for as many frames as you requested.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The filter will fill the array with the frame numbers of up to the first lSize number of frames dropped, and it will set plNumCopied accordingly.

IAMDroppedFrames::GetNumDropped

IAMDroppedFrames Interface

Retrieves the total number of frames that the pin dropped since it last started streaming.

HRESULT GetNumDropped(
long * plDropped );

Parameters
plDropped
[out] Pointer to the total number of dropped frames.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMDroppedFrames::GetNumNotDropped

IAMDroppedFrames Interface

Retrieves the total number of frames that the pin delivered downstream (did not drop).

HRESULT GetNumNotDropped(
long * plNotDropped );

Parameters
plNotDropped
[out] Pointer to the total number of frames that weren't dropped.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.


IAMExtDevice Interface

The IAMExtDevice interface is the base interface for controlling external devices. Developers can implement this interface to control numerous types of devices; however, the current DirectShow implementation is specific to VCRs. The IAMExtDevice interface controls general settings of external hardware and is intended to be used in combination with the IAMExtTransport interface, which controls a VCR's more specific settings. You can also implement the IAMTimecodeReader, IAMTimecodeGenerator, and IAMTimecodeDisplay interfaces if your filter manages SMPTE (Society of Motion Picture and Television Engineers) timecode, and the external device has the appropriate features.

For a description of a sample filter which controls a VCR through DirectShow, see Vcrctrl Sample (VCR Control Filter).

When to Implement

Implement this interface when you want to build a filter or application that controls an external device, such as a VCR. Because this interface controls general information about a device, implement the IAMExtTransport interface in addition to control the external device's more specific properties.

An application can directly instantiate and control external devices, such as VCRs, but it is strongly recommended that you always instantiate these devices within the context of a filter graph, even if they are the only filters within the graph.

When to Use

Use this interface when you want to add external device control to your application.

Applications should use the filter graph to enumerate the filters and then get the IAMExtDevice interface directly from the appropriate filter.

Hardware Requirements

To control an external VCR, certain hardware requirements are recommended. VCRs with an RS-422 serial interface require a special serial port card or an external RS-232-to-RS-422 adapter. In addition, for best performance, your computer should have a serial port card built with a 16,550 high-performance UART (Universal Asynchronous Receiver/Transmitter) to sustain higher baud rates, such as 38.4 baud.

Methods in Vtable Order
IUnknown Methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMExtDevice Methods | Description
GetCapability | Retrieves the capabilities of the external device.
get_ExternalDeviceID | Retrieves the model number of the external device.
get_ExternalDeviceVersion | Retrieves the version number of the external device's operating software.
put_DevicePort | Specifies the communication port to which the external device is connected.
get_DevicePower | Retrieves whether the external device's power mode is on, off, or standby.
put_DevicePower | Sets the external device's power mode to on, off, or standby.
Calibrate | Calibrates the external device's transport mechanism.
get_DevicePort | Retrieves the communication port to which the external device is connected.

IAMExtDevice::Calibrate

IAMExtDevice Interface

Calibrates an external device's transport mechanism.

HRESULT Calibrate(
HEVENT hEvent,
long Mode,
long *pStatus );

Parameters
hEvent
[in] Event used to signal completion of this process.
Mode
[in] Value that activates or deactivates the calibration process. Specify one of the following:
Value | Meaning
ED_ACTIVE | Activates calibration process.
ED_INACTIVE | Deactivates calibration process.
NULL | Used to determine if current status is active or inactive.
pStatus
[out] Value indicating whether an event is active (OATRUE) or inactive (OAFALSE).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method on certain external devices that require calibration; for example, when rewinding a tape and resetting the counter, or computing the frame offset for a timecode reader or generator.

Filters for various external devices can implement this method differently, depending on the calibration that the device needs. This method assumes the IMediaEventSink interface has already established an event sink, or that another event signaling method has been established.

IAMExtDevice::GetCapability

IAMExtDevice Interface

Retrieves the capabilities of the external device.

HRESULT GetCapability(
long Capability,
long *pValue,
double *pdblValue );

Parameters
Capability
[in] Value that specifies which capability you want to check. This parameter must be one of the following values.
Value | Meaning
ED_DEVCAP_CAN_RECORD | Checks whether transport can record.
ED_DEVCAP_CAN_RECORD_STROBE | Checks whether transport can single-frame record.
ED_DEVCAP_CAN_SAVE | Checks whether transport can save data.
ED_DEVCAP_DEVICE_TYPE | Checks the external device type.
ED_DEVCAP_HAS_AUDIO | Checks whether transport has audio.
ED_DEVCAP_HAS_VIDEO | Checks whether the device has video.
ED_DEVCAP_USES_FILES | Checks whether transport has a built-in file system.
pValue
[out] Value indicating the capabilities of the property specified in the Capability parameter. Returns OATRUE if the property is supported or OAFALSE if the property is not supported for all properties except ED_DEVCAP_DEVICE_TYPE. In this case, returns one of the following:
Value | Meaning
ED_DEVTYPE_ATR | Audio Tape Recorder
ED_DEVTYPE_CG | Character Generator
ED_DEVTYPE_DDR | Digital Disc Recorder
ED_DEVTYPE_DVE | Digital video effects unit
ED_DEVTYPE_GPI | General purpose interface trigger
ED_DEVTYPE_KEYER | Video keyer
ED_DEVTYPE_LASERDISK | Laser disc
ED_DEVTYPE_MIXER_AUDIO | Audio mixer
ED_DEVTYPE_MIXER_VIDEO | Video mixer
ED_DEVTYPE_ROUTER | Video router
ED_DEVTYPE_TBC | Timebase corrector
ED_DEVTYPE_TCG | Timecode generator/reader
ED_DEVTYPE_VCR | VCR
ED_DEVTYPE_WIPEGEN | Video wipe generator
ED_DEVTYPE_JOYSTICK | Joystick
ED_DEVTYPE_KEYBOARD | Keyboard
pdblValue
[out] Value indicating the capabilities of the specified property (if it is a double value). Pass NULL if not in use.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

All return values are in pValue unless you have large or floating point values to return, in which case they are returned in the pdblValue parameter.

IAMExtDevice::get_DevicePort

IAMExtDevice Interface

Retrieves the communication port to which the external device is connected.

HRESULT get_DevicePort(
long *pDevicePort );

Parameters
pDevicePort
[in] Port to which the device is connected. Retrieves one of the following:
Value | Meaning
DEV_PORT_1394 | IEEE 1394 Bus
DEV_PORT_ARTI | ARTI driver
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest driver
DEV_PORT_SIM | Simulation port
DEV_PORT_USB | Universal Serial Bus
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::put_DevicePort

IAMExtDevice::get_DevicePower

IAMExtDevice Interface

Retrieves the external device's power mode: on, off, or standby.

HRESULT get_DevicePower(
long *pPowerMode );

Parameters
pPowerMode
[out] External device's power mode; can be one of the following values.
Value | Meaning
ED_POWER_OFF | Off
ED_POWER_ON | On
ED_POWER_STANDBY | Standby
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::put_DevicePower

IAMExtDevice::get_ExternalDeviceID

IAMExtDevice Interface

Retrieves the model number of the external device.

HRESULT get_ExternalDeviceID(
LPOLESTR *ppszData );

Parameters
ppszData
[out] Returns the manufacturer-specific identification number or text as a string.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtDevice::get_ExternalDeviceVersion

IAMExtDevice Interface

Retrieves the version number of the external device's operating software.

HRESULT get_ExternalDeviceVersion(
LPOLESTR *ppszData );

Parameters
ppszData
[out] Returns the manufacturer-specific operating software version number from the external device.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtDevice::put_DevicePort

IAMExtDevice Interface

Specifies the communication port to which the external device is connected.

HRESULT put_DevicePort(
long DevicePort
);

Parameters
DevicePort
[in] Port to which the device will connect. Specify one of the following:
Value | Meaning
DEV_PORT_1394 | IEEE 1394 Bus
DEV_PORT_ARTI | ARTI driver
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest driver
DEV_PORT_MIN | DEV_PORT_SIM
DEV_PORT_SIM | Simulation port (used for "no hardware" simulation)
DEV_PORT_USB | Universal serial bus
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::get_DevicePort

IAMExtDevice::put_DevicePower

IAMExtDevice Interface

Sets the external device's power mode to either on, off, or standby.

HRESULT put_DevicePower(
long PowerMode );

Parameters
PowerMode
[in] Value indicating which power mode the device will have. Set to one of the following:
Value | Meaning
ED_POWER_OFF | Off
ED_POWER_ON | On
ED_POWER_STANDBY | Standby
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtDevice::get_DevicePower

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMExtTransport Interface

The IAMExtTransport interface provides methods which control specific behaviors of an external VCR. These methods generally set and get the transport properties which relate to how the VCR and the computer exchange data. Since this interface controls specific behaviors of transport, it must be implemented in combination with the IAMExtDevice interface, which controls an external device's general behaviors. If you want to control an external device other than a VCR, two options are available. Either use the methods you need and return E_NOTIMPL for the rest, or design a new interface and aggregate it with IAMExtDevice.

This interface also provides methods that enable developers to define edit events which assist in the content authoring process. Edit events are made up of individual edit properties that are grouped together into edit property sets. These edit property sets can define an actual recording sequence on the transport or a simple positional command. They can, for example, specify certain modes of editing, record inpoints and outpoints, or memorize positions called bookmarks. The SetEditPropertySet method creates or registers a group of edit properties, called an edit property set, while the SetEditProperty enables the application to define parameters and values of individual edit properties. Since these are relatively sophisticated situations, their implementation is left to the advanced developer.

For a description of a sample filter which controls a VCR through DirectShow, see Vcrctrl Sample (VCR Control Filter).

When to Implement

Implement this interface if you want to build a filter or application that controls an external device, such as a VCR. Because this interface controls specific information about a device, you should implement it with the IAMExtDevice interface.

An application can directly instantiate and control external device control filters, such as those for VCRs, but it is strongly recommended that you always instantiated them within the context of a filter graph, even if they are the only filter within the graph.

Implementations can vary depending on the type of external device being controlled. With certain devices, methods can return E_NOTIMPL if they are not applicable.

When to Use

Use this interface if you want a filter to control video and audio tape machines that are external to the computer. Typical uses for this interface include the applications that implement "batch capture" and "print to tape" of audio and video.

Applications should use the filter graph to enumerate the filters and then get the IAMExtTransport interface directly from the appropriate filter.

Hardware Requirements

To control an external VCR, certain hardware requirements are recommended. VCRs with an RS-422 serial interface require a special serial port card or an external RS-232-to-RS-422 adapter. In addition, for best performance, your computer should have a serial port card built with a 16,550 high-performance UART to sustain higher baud rates, such as 38.4 baud.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMExtTransport methods | Description
GetCapability | Retrieves the general capabilities of an external transport.
put_MediaState | Sets the current state of the media.
get_MediaState | Retrieves the current state of the media.
put_LocalControl | Sets the state of the external device to local or remote control.
get_LocalControl | Retrieves the state of the external device.
GetStatus | Determines the status of the external transport.
GetTransportBasicParameters | Retrieves the external transport's basic parameter settings.
SetTransportBasicParameters | Sets the external transport's basic parameters.
GetTransportVideoParameters | Retrieves the external transport's video parameter settings.
SetTransportVideoParameters | Sets the video parameters for the external transport.
GetTransportAudioParameters | Retrieves the external transport's audio parameter settings.
SetTransportAudioParameters | Sets audio parameter setting for the external transport.
put_Mode | Sets the movement of the transport to a new mode (play, stop, record, edit, and so on).
get_Mode | Retrieves the mode of the transport (play, stop, record, edit, and so on).
put_Rate | Sets the playback rate for variable-speed external devices.
get_Rate | Retrieves the playback rate set in put_Rate for variable speed external devices.
GetChase | Retrieves the status of chase mode.
SetChase | Enables or disables chase mode.
GetBump | Retrieves status of bump mode.
SetBump | Temporarily changes the speed of playback for synchronization of multiple external devices.
get_AntiClogControl | Determines if the anti-headclog control is enabled or disabled.
put_AntiClogControl | Enables or disables the transport's anti-headclog control.
GetEditPropertySet | Retrieves the current state of an edit property set.
SetEditPropertySet | Registers an edit property set that describes a group of edit properties.
GetEditProperty | Retrieves individual parameters and values associated with a particular edit property set.
SetEditProperty | Defines individual parameters and values associated with a particular edit property set.
get_EditStart | Determines if the external transport's edit control is active.
put_EditStart | Activates edit control on a capable transport.

IAMExtTransport::get_AntiClogControl

IAMExtTransport Interface

Determines if the anti-headclog control is enabled or disabled.

HRESULT get_AntiClogControl(
long *pEnabled );

Parameters
pEnabled
[out] OATRUE indicates anti-headclog is enabled; OAFALSE indicates disabled.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::put_AntiClogControl

IAMExtTransport::GetBump

IAMExtTransport Interface

Retrieves the status of bump mode.

HRESULT GetBump(
long *pSpeed,
long *pDuration );

Parameters
pSpeed
[out] Temporary speed (a multiple of normal speed).
pDuration
[out] Pointer to the duration of a bump in current time format.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method will cause a temporary speed variation of transport used during the physical synchronization process. It will stay in effect until pDuration time has expired.

See "IAMExtTransport Basic Parms" in DXMedia\Include\Edevdefs.h for supported time formats.

See Also

IAMExtTransport::SetBump

IAMExtTransport::GetCapability

IAMExtTransport Interface

Retrieves the general capabilities of an external transport.

HRESULT GetCapability(
long Capability,
long *pValue,
double *pdblValue );

Parameters
Capability
[in] Capability to query for. Specify one of the following:
Value | Meaning
ED_TRANSCAP_CAN_BUMP_PLAY | Checks whether transport can vary speed for synchronizing.
ED_TRANSCAP_CAN_DELAY_AUDIO_IN | Checks whether transport does delayed-in audio edits.
ED_TRANSCAP_CAN_DELAY_AUDIO_OUT | Checks whether transport does delayed-out audio edits.
ED_TRANSCAP_CAN_DELAY_VIDEO_IN | Checks whether transport does delayed-in video edits.
ED_TRANSCAP_CAN_DELAY_VIDEO_OUT | Checks whether transport does delayed-out video edits.
ED_TRANSCAP_CAN_EJECT | Checks whether transport can eject its media.
ED_TRANSCAP_CAN_PLAY_BACKWARDS | Checks whether transport can play media in reverse (negative rate).
ED_TRANSCAP_CAN_SET_EE | Checks whether transport can show its input on its output.
ED_TRANSCAP_CAN_SET_PB | Checks whether transport can show media playback on its output.
ED_TRANSCAP_FWD_VARIABLE_MAX | Maximum forward speed (multiple of play speed) in pdblValue.
ED_TRANSCAP_LTC_TRACK | Track number of linear timecode (LTC) in pValue.
ED_TRANSCAP_NUM_AUDIO_TRACKS | Number of audio tracks in pValue.
ED_TRANSCAP_REV_VARIABLE_MAX | Maximum reverse speed (multiple of play speed) in pdblValue.
pValue
[out] Indicates whether the capability specified in Capability is supported or not. Returns either OATRUE if it is supported or OAFALSE if not.
pdblValue
[out] Indicates the capabilities of the property specified in Capability.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

All OATRUE and OAFALSE values are returned in pValue; numerical values are returned in pValue or pdblValue. Use the pdblValue parameter to return double values if the pValue parameter is insufficient. Return NULL if one of the parameters is not needed.

IAMExtTransport::GetChase

IAMExtTransport Interface

Retrieves the status of chase mode.

HRESULT GetChase(
long *pEnabled,
long *pOffset,
HEVENT *phEvent );

Parameters
pEnabled
[out] OATRUE specifies chase enabled; OAFALSE specifies chase disabled.
pOffset
[out] Offset from the present time to which the transport will maintain while playing.
phEvent
[out] Pointer to the completion notification that will signal chase offset is established.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The time for pOffset is given in the current time format (see "IAMExtTransport Basic Parms" in DXMedia\Include\Edevdefs.h for supported time formats).

See Also

IAMExtTransport::SetChase

IAMExtTransport::GetEditProperty

IAMExtTransport Interface

Retrieves the parameters and values associated with a particular edit event.

HRESULT GetEditProperty(
long EditID,
long Param,
long *pValue );

Parameters
EditID
[in] Identification number of the edit property set.
Param
[in] Edit event parameter to determine the value of.
pValue
[out] Returns the value of the parameter specified in Param: OATRUE, OAFALSE, or a specific value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::SetEditProperty

IAMExtTransport::GetEditPropertySet

IAMExtTransport Interface

Retrieves individual parameters and values associated with a particular edit property set.

HRESULT GetEditPropertySet(
long EditID,
long *pState );

Parameters
EditID
[in] Identification number of the edit property set.
pState
[out] State of the edit property set. Retrieves one of the following:
Value | Meaning
DC_SET_ACTIVE | Activates edit property set.
DC_SET_DELETE | Deletes edit property set.
DC_SET_INACTIVE | Deactivates edit property set.
DC_SET_REGISTER | Registers edit property set.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::SetEditPropertySet

IAMExtTransport::get_EditStart

IAMExtTransport Interface

Determines if the external transport's edit control is active.

HRESULT get_EditStart(
long *pValue );

Parameters
pValue
[out] Returns OATRUE if edit control is active; OAFALSE if inactive.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::put_EditStart

IAMExtTransport::get_LocalControl

IAMExtTransport Interface

Retrieves the state of the external device.

HRESULT get_LocalControl(
long *pState );

Parameters
pState
[out] Returns either OATRUE for local control or OAFALSE for remote.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To control an external device, it must be in remote mode.

See Also

IAMExtTransport::put_LocalControl

IAMExtTransport::get_MediaState

IAMExtTransport Interface

Retrieves the current state of the media set in put_MediaState.

HRESULT get_MediaState(
long *pState );

Parameters
pState
[out] Returns the current state or the media. Values will be device specific but can include the following:
Value | Meaning
ED_MEDIA_SPIN_DOWN | Stop spinning (for disk media); unthread the tape (for tape media).
ED_MEDIA_SPIN_UP | Start spinning (for disk media); thread the tape (for tape media).
ED_MEDIA_UNLOAD | Eject the media from the drive (if device supports it).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtTransport::get_Mode

IAMExtTransport Interface

Retrieves the mode of the transport (play, stop, record, edit, and so on).

HRESULT get_Mode(
long *pMode );

Parameters
pMode
[out] Current transport mode (see IAMExtTransport::put_Mode for possible modes).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtTransport::get_Rate

IAMExtTransport Interface

Retrieves the playback rate for variable-speed external devices.

HRESULT get_Rate(
double *pdblRate );

Parameters
pdblRate
[out] Pointer to the playback rate set in IAMExtTransport::put_Rate.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtTransport::GetStatus

IAMExtTransport Interface

Determines the external transport's status.

HRESULT GetStatus(
long StatusItem,
long *pValue );

Parameters
StatusItem
[in] Item you want to determine the status of; can include one of the following:
Value | Meaning
ED_MODE_EDIT_CUE | Checks if device is cueing for an active edit event.
ED_MODE_FF | Checks if device is fast forwarding.
ED_MODE_FREEZE | Checks if device is paused.
ED_MODE_LINK_OFF | Checks if transport control isn't linked to filter graph's run, stop, and pause controls.
ED_MODE_LINK_ON | Checks if transport control is linked to filter graph's run, stop, pause controls.
ED_MODE_PLAY | Checks if device is playing.
ED_MODE_RECORD | Checks if device is recording.
ED_MODE_RECORD_STROBE | Checks if device is recording single-frame.
ED_MODE_REW | Checks if device is rewinding.
ED_MODE_SHUTTLE | Checks if device is shuttling (high-speed movement with visible picture).
ED_MODE_STEP | Checks if device is single-stepping.
ED_MODE_STOP | Checks if device is stopped.
pValue
[out] Returns OATRUE if StatusItem is active or OAFALSE if not.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

When implementing this interface, be aware that transport StatusItem parameters are more extensive than most Microsoft® DirectShow™ interfaces and code should reflect this variety and feel free to check the transport status of appropriate parameters.

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport Interface

Retrieves audio parameter setting for external transport.

HRESULT GetTransportAudioParameters(
long Param,
long *pValue );

Parameters
Param
[in] Audio parameter whose value you want to get. Specify one of the following:
Value | Meaning
ED_TRANSAUDIO_ENABLE_OUTPUT | Audio output channel(s)
ED_TRANSAUDIO_ENABLE_RECORD | Audio recording channel(s)
ED_TRANSAUDIO_ENABLE_SELSYNC | Audio selsync recording channel(s)
ED_TRANSAUDIO_SET_MONITOR | Monitor output audio channel(s)
ED_TRANSAUDIO_SET_SOURCE | Audio source channel(s)
pValue
[out] Channel or channels set in the IAMExtTransport::SetTransportAudioParameters method.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport Interface

Retrieves the transport's basic parameter settings.

HRESULT GetTransportBasicParameters(
long Param,
long *pValue,
LPOLESTR *ppszData );

Parameters
Param
[in] Parameter you want to receive the setting for (see Edevdefs.h for possible parameters under "IAMExtTransport Basic Parms").
pValue
[out] Setting of the parameter if it is numeric.
ppszData
[out] Setting of the parameter if it is a string .
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport::GetTransportVideoParameters

IAMExtTransport Interface

Retrieves video parameter settings for external transport.

HRESULT GetTransportVideoParameters(
long Param,
long *pValue );

Parameters
Param
[in] Video parameter you want to receive the settings for. Can be either ED_TRANSVIDEO_SET_OUTPUT (video transport output parameters) or ED_TRANSVIDEO_SET_SOURCE (video transport source).
pValue
[out] Set the ED_TRANSVIDEO_SET_SOURCE flag to retrieve the active video input, or set the ED_TRANSVIDEO_SET_OUTPUT flag to retrieve one of the following values:
Value | Meaning
ED_E2E | Input video is visible on device's output regardless of transport mode.
ED_OFF | Video output is disabled.
ED_PLAYBACK | Video playing from media is displayed on the screen.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport::put_AntiClogControl

IAMExtTransport Interface

Enables or disables transport anti-headclog control.

HRESULT put_AntiClogControl(
long Enable );

Parameters
Enable
[in] Value indicating whether to enable anti-headclog control; set OATRUE to enable, OAFALSE to disable.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to unclog video heads on VCRs that have an automatic head-cleaning feature.

See Also

get_AntiClogControl

IAMExtTransport::put_EditStart

IAMExtTransport Interface

Activates the edit control on a capable transport.

HRESULT put_EditStart(
long Value );

Parameters
Value
[in] OATRUE activates the edit control; OAFALSE deactivates it.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to manually enable edit control. Edit control is defined as the precise enabling of individual, or a set of, record tracks on a VCR; for example, a video-only insert edit, where only the video record head is enabled and a new video signal is recorded — the audio signal is left as is. Use this method to control "on the fly" editing on machines that have this feature.

See Also

IAMExtTransport::get_EditStart

IAMExtTransport::put_LocalControl

IAMExtTransport Interface

Sets the state of the external device to local or remote control.

HRESULT put_LocalControl(
long State );

Parameters
State
[in] Current state; pass OATRUE for local, OAFALSE for remote.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::get_LocalControl

IAMExtTransport::put_MediaState

IAMExtTransport Interface

Sets the current state of the media.

HRESULT put_MediaState(
long State );

Parameters
State
[in] Value specifying the state. Use one of the following:
Value | Meaning
ED_MEDIA_SPIN_DOWN | Stop spinning (for disc media); unthread the tape (for tape media).
ED_MEDIA_SPIN_UP | Start spinning (for disc media); thread the tape (for tape media).
ED_MEDIA_UNLOAD | Eject the media from the drive (if device supports it).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use the preceding parameters for disk and tape media. For other devices, you might need to specify new parameters.

See Also

IAMExtTransport::get_MediaState

IAMExtTransport::put_Mode

IAMExtTransport Interface

Sets the movement of the transport to a new mode (play, stop, record, edit, and so on).

HRESULT put_Mode(
long Mode );

Parameters
Mode
[in] Transport mode. Specify one of the following:
Value | Meaning
ED_MODE_PLAY | Play
ED_MODE_STOP | Stop
ED_MODE_FREEZE | Freeze (pause)
ED_MODE_THAW | Resume
ED_MODE_FF | Fast forward
ED_MODE_REW | Rewind
ED_MODE_RECORD | Record
ED_MODE_RECORD_STROBE | Record single frame
ED_MODE_STEP | Single step
ED_MODE_SHUTTLE | Shuttle (high-speed movement with visible picture)
ED_MODE_EDIT_CUE | Cue for an edit event
ED_MODE_LINK_ON | Link this method to the graph's IMediaControl::Run, Stop, and Pause methods
ED_MODE_LINK_OFF | Disengage this method from the graph's IMediaControl::Run, Stop, Pause methods.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMExtTransport::get_Mode

IAMExtTransport::put_Rate

IAMExtTransport Interface

Sets the playback rate for variable-speed external devices.

HRESULT put_Rate(
double dblRate );

Parameters
dblRate
[in] Multiple of play speed where .5=half, 1=normal, 2=double, 3=triple and so forth.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method enables an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate.

You can also link this method to the IMediaPosition::put_Rate method as an alternate means of setting rates of playback relative to normal speed.

See Also

IAMExtTransport::get_Rate

IAMExtTransport::SetBump

IAMExtTransport Interface

Temporarily changes the speed of playback for synchronization of multiple external devices.

HRESULT SetBump(
long Speed,
long Duration );

Parameters
Speed
[in] Temporary speed (a multiple of normal speed).
Duration
[in] Duration of a bump in current time format.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method will stay in effect until Duration time has expired.

See "IAMExtTransport Basic Parms" in DXMedia\Include\Edevdefs.h for supported time formats.

See Also

IAMExtTransport::GetBump

IAMExtTransport::SetChase

IAMExtTransport Interface

Enables or disables chase mode.

HRESULT SetChase(
long Enable,
long Offset,
HEVENT hEvent );

Parameters
Enable
[in] Enables or disables chase. Specify OATRUE to enable chase; OAFALSE to disable.
Offset
[in] Offset from the time reference that the transport will maintain. Specify in current time format.
hEvent
[in] Event to signal offset established.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use the SetChase method when you want an external transport to continuously follow a timecode signal with a fixed offset. For example, if your computer is generating timecode, a VCR capable of chasing can be told by the computer to put itself in play mode and keep its media a fixed offset from the reference timecode. You determine the offset by comparing the timecode on the playback media to the reference (generated) timecode.

This method will stay in effect until canceled or complete and requires the filter to verify (by periodically reading the transport's timecode) that the transport is indeed maintaining the fixed offset.

Time for Offset is specified in current time format (see "IAMExtTransport Basic Parms" in DXMedia\Include\Edevdefs.h for supported time formats).

See Also

IAMExtTransport::GetChase

IAMExtTransport::SetEditProperty

IAMExtTransport Interface

Defines individual parameters and values associated with a particular edit property set.

HRESULT SetEditProperty(
long EditID,
long Param,
long Value );

Parameters
EditID
[in] Identification number of the edit property set.
Param
[in] Edit event parameter to define.
Value
[in] Value of the parameter specified in Param. Use OATRUE, OAFALSE, or a specific value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Edit events can either refer to a group of predefined properties that define an actual recording sequence, or they can refer to simple positional commands. They can, for example, specify certain modes of editing, record inpoints and outpoints, or memorize positions called bookmarks. The SetEditPropertySet method defines and registers a group of edit events, called an edit property set, while the SetEditProperty method enables the user to define parameters and values of individual edit events.

To define a set of edit properties, first register an edit property set and get an EditID with the SetEditPropertySet method. Then use the SetEditProperty method to define specific parameters and values of individual edit properties. Finally, use the SetEditPropertySet method to activate the edit property set.

For a complete listing of possible parameters and values for edit property sets see Edevdefs.h in the DirectShow SDK's DXMedia\Include folder.

See Also

IAMExtTransport::GetEditProperty

IAMExtTransport::SetEditPropertySet

IAMExtTransport Interface

Registers an edit property set that describes a group of edit properties.

HRESULT SetEditPropertySet(
long *pEditID,
long State );

Parameters
pEditID
[in, out] Identification number of the edit property set.
State
[in] State of the edit property set. Specify one of the following:
Value | Meaning
DC_SET_ACTIVE | Activates edit property set.
DC_SET_DELETE | Deletes edit property set.
DC_SET_INACTIVE | Inactivates edit property set.
DC_SET_REGISTER | Registers edit property set.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Edit events refer to a group of predefined properties that define an actual recording sequence on the transport or a simple positional command. They can, for example, specify certain modes of editing, record inpoints and outpoints, or memorize positions called bookmarks. The SetEditPropertySet method defines and registers a group of edit properties, called an edit property set, while the SetEditProperty enables the user to define parameters and values of individual edit event properties.

To define a set of edit properties, first register an edit property set and get an EditID with the SetEditPropertySet method. Then use the SetEditProperty method to define specific parameters and values of individual edit properties. Finally, use the SetEditPropertySet method to activate the edit property set.

For a complete listing of possible parameters and values for edit property sets see Edevdefs.h in the DirectShow SDK's DXMedia\Include folder.

See Also

IAMExtTransport::GetEditPropertySet

IAMExtTransport::SetTransportAudioParameters

IAMExtTransport Interface

Sets audio parameter setting for external transport.

HRESULT SetTransportAudioParameters(
long Param,
long Value );

Parameters
Param
[in] Audio parameter you want to set. Specify one of the following.
Value | Meaning
ED_TRANSAUDIO_ENABLE_OUTPUT | Enable audio channel(s) for output.
ED_TRANSAUDIO_ENABLE_RECORD | Enable audio channel(s) for recording.
ED_TRANSAUDIO_ENABLE_SELSYNC | Enable audio channel(s) for selsync recording.
ED_TRANSAUDIO_SET_MONITOR | Set the monitor output source.
ED_TRANSAUDIO_SET_SOURCE | Set the active audio input.
Value
[in] Audio channel or channels to set the parameter on.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Specify an exact channel or channels in Value by selecting ED_AUDIO_1 through ED_AUDIO_24 (use an or switch to combine), or all channels by selecting ED_AUDIO_ALL.

See Also

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport Interface

Sets basic parameters of external transport.

HRESULT SetTransportBasicParameters(
long Param,
long Value,
LPCOLESTR pszData );

Parameters
Param
[in] Parameter you want to set (see Edevdefs.h for possible parameters under "IAMExtTransport Basic Parms").
Value
[in] Setting of the parameter if it is numeric.
pszData
[in] Setting of the parameter if it is a string.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Basic settings include time formats, record formats, preroll setting, servo setting, and others (see Edevdefs.h).

See Also

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport Interface

Sets video parameters for external transport.

HRESULT SetTransportVideoParameters(
long Param,
long Value );

Parameters
Param
[in] Video parameter you want to set. Specify either ED_TRANSVIDEO_SET_OUTPUT (video transport output parameters) or ED_TRANSVIDEO_SET_SOURCE (video transport source).
Value
[in] Set the ED_TRANSVIDEO_SET_SOURCE flag to set the active video input, or set the ED_TRANSVIDEO_SET_OUTPUT flag to one of the following values.
Value | Meaning
ED_E2E | Input video is visible on device's output regardless of transport mode.
ED_OFF | Video output is disabled.
ED_PLAYBACK | Video playing from media is displayed on the screen.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For the ED_TRANSVIDEO_SET_SOURCE flag, an external device filter uses physical pins to describe its inputs. Calls to the filter's pin enumerator will return an index value. The value is passed to this method as its as its Value parameter.

See Also

IAMExtTransport::GetTransportVideoParameters

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMFileCutListElement Interface

The IAMFileCutListElement interface provides support for a cutlist element for a file stream.

See About Cutlists and Using Cutlists for more information.

When to Implement

Implement this interface in your application when you implement your own IAMCutListElement interface. Usually, you don't need to implement either interface because DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects that implement it for you. However, you can implement this interface in your application when you need to change the default behavior of this interface.

When to Use

Use this interface in your filter when you specify a media clip stored in a file. Call QueryInterface on IAMCutListElement to determine if the element is file-based.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMFileCutListElement methods | Description
GetFileName | Retrieves the file name of the cutlist element.
GetTrimInPosition | Retrieves the media time of the trimin point, based on the timeline of the cut's source file.
GetTrimOutPosition | Retrieves the media time of the trimout point, based on the timeline of the cut's source file.
GetOriginPosition | Retrieves the media time of the origin of the file or clip.
GetTrimLength | Retrieves the length of time between the trimin and trimout points.
GetElementSplitOffset | Retrieves the media time of the number of frames between the trimin point and the start of this element in output time.

IAMFileCutListElement::GetElementSplitOffset

IAMFileCutListElement Interface

Retrieves the media time of the number of frames between the trimin point and the start of this element in output time.

HRESULT GetElementSplitOffset(
REFERENCE_TIME *pmtOffset
);

Parameters
pmtOffset
[out] Pointer that will receive the offset in the element's length.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

This method must retrieve a zero offset. Other offsets are not supported.

IAMFileCutListElement::GetFileName

IAMFileCutListElement Interface

Retrieves the file name of the cutlist element.

HRESULT GetFileName(
LPWSTR *ppwstrFileName
);

Parameters
ppwstrFileName
[out] Pointer that will receive the file name (must be freed when no longer needed).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

IAMFileCutListElement::GetOriginPosition

IAMFileCutListElement Interface

Retrieves the media time of the origin of the file or clip.

HRESULT GetOriginPosition(
REFERENCE_TIME *pmtOrigin
);

Parameters
mtOrigin
[out] Pointer that will receive the origin. The origin is in media time.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

This method must return a zero origin. Clips with nonzero start times are not supported.

IAMFileCutListElement::GetTrimInPosition

IAMFileCutListElement Interface

Retrieves the media time of the trimin point, based on the timeline of the cut's source file.

HRESULT GetTrimInPosition(
REFERENCE_TIME *pmtTrimIn
);

Parameters
pmtTrimIn
[out] Pointer that will receive the trimin point.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

IAMFileCutListElement::GetTrimLength

IAMFileCutListElement Interface

Retrieves the length of time between the trimin and trimout points.

HRESULT GetTrimLength(
REFERENCE_TIME *pmtLength
);

Parameters
pmtLength
[out] Pointer that will receive the length in media time.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

This method retrieves the length of time between the in and out points specified by GetTrimInPosition and GetTrimOutPosition.

The value that GetTrimLength retrieves equals the value that GetElementDuration retrieves (trimout minus trimin). Other lengths are not supported.

IAMFileCutListElement::GetTrimOutPosition

IAMFileCutListElement Interface

Retrieves the media time of the trimout point, based on the timeline of the cut's source file.

HRESULT GetTrimOutPosition(
REFERENCE_TIME *pmtTrimOut
);

Parameters
pmtTrimOut
[out] Pointer that will receive the trimout point, in REFERENCE_TIME.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

The media time does not include the trimout point.


IAMLine21Decoder Interface

The IAMLine21Decoder interface provides access to closed-captioned information and settings. Closed-captioned information is transmitted in the vertical blanking interval (VBI) of television signals, specifically on line 21 (Line21) of field 1 in the VBI. Video cassette recorders record this information on video tape, and you can use Microsoft® DirectShow™ filters to capture the Line21 data and save it on disk in a media file format such as audio-video interleaved (AVI). The closed-captioned information appears as a separate stream within the media file.

Closed-captioned text is currently used mainly in digital versatile disc (DVD) movies. DVD movies contain Line21 data as part of the user data section of each Group of Pictures (GOP) in the video stream. Capture cards with Windows Driver Model (WDM) drivers will provide Line21 data.

When to Implement

Do not implement this interface. DirectShow provides the Line 21 Decoder in the DirectX Media 5.1 SDK, which implements it for you.

When to Use

Applications use this interface when they want to provide closed-captioned text, primarily to turn closed-captioned capabilities on and off. Use this interface in your application or in the filter immediately downstream of the Line21 Decoder filter (typically a mixer filter) to change closed-captioned options, such as the output video's size and whether to make the caption background opaque or transparent. Mixer filters can also change the physical color used for the background color key.

Applications can call the GetDrawBackgroundMode and SetDrawBackgroundMode methods so the user can select transparent or opaque captioning.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMLine21Decoder methods | Description
GetDecoderLevel | Retrieves the closed-captioned decoder level.
GetCurrentService | Retrieves the current closed captioning service selected by the user.
SetCurrentService | Sets the current closed captioning service.
GetServiceState | Retrieves the closed captioning service state (on or off).
SetServiceState | Sets the closed captioning service state.
GetOutputFormat | Retrieves information about output video characteristics such as size and bit depth.
SetOutputFormat | Sets information that describes output video characteristics such as size and bit depth.
GetBackgroundColor | Retrieves the physical color to use as background for overlays.
SetBackgroundColor | Sets the physical color to use as background for overlays.
GetRedrawAlways | Retrieves whether the renderer should redraw the whole output bitmap for each sample.
SetRedrawAlways | Sets whether the renderer should redraw the whole output bitmap for each sample.
GetDrawBackgroundMode | Retrieves whether the caption text background should be opaque or transparent.
SetDrawBackgroundMode | Sets whether to make the caption text background opaque or transparent.

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder Interface

Retrieves the physical color to use as background for overlays.

HRESULT GetBackgroundColor(
DWORD *pdwPhysColor
);

Parameters
pdwPhysColor
Pointer to the retrieved DWORD value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

Magenta is the default background color.

See Also

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder Interface

Retrieves the current closed captioning service selected by the user.

HRESULT GetCurrentService(
AM_LINE21_CCSERVICE *lpService
);

Parameters
lpService
Pointer to the current service. This value is a member of the AM_LINE21_CCSERVICE enumerated data type. The default service is AM_L21_CCSERVICE_Caption1.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

See Also

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder::GetDecoderLevel

IAMLine21Decoder Interface

Retrieves the closed-captioned decoder level.

HRESULT GetDecoderLevel(
AM_LINE21_CCLEVEL *lpLevel
);

Parameters
lpLevel
Pointer to the retrieved decoder level. AM_L21_CCLEVEL_TC2 (TC2) is the only supported operating channel level and is an enhanced and backward-compatible version of the original TC1 level.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

This method is for informational purposes only.

TC1 and TC2 are television set decoder levels that represent whether the television can handle some closed-captioned byte pairs and produce the desired captioning results. The Line21 Decoder is capable of TC2 level decoding, which includes all TC1 decoding. Only the first 100,000 television sets manufactured that included closed-captioned capability were TC1 compliant; the later TV sets are TC2 compliant.

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder Interface

Retrieves whether the caption text background should be opaque or transparent.

HRESULT GetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE *lpMode
);

Parameters
lpMode
Retrieved mode. Supported mode values are AM_L21_DRAWBGMODE_Opaque and AM_L21_DRAWBGMODE_Transparent.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

By default, the caption background is opaque.

See Also

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder Interface

Retrieves information about output video characteristics such as size and bit depth.

HRESULT GetOutputFormat(
LPBITMAPINFOHEADER lpbmih
);

Parameters
lpbmih
Pointer to the retrieved BITMAPINFOHEADER structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

If successful, the default implementation returns S_FALSE if downstream filters haven't defined an output format, or S_OK if an output format has been defined.

Remarks

The default video output size is 320 × 240 pixels.

See Also

IAMLine21Decoder::SetOutputFormat

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder Interface

Retrieves whether the renderer should redraw the whole output bitmap for each sample.

HRESULT GetRedrawAlways(
LPBOOL lpbOption
);

Parameters
lpbOption
Pointer to a value indicating whether the whole bitmap should be redrawn; FALSE by default, indicating don't always redraw. TRUE means always redraw.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

See Also

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder::GetServiceState

IAMLine21Decoder Interface

Retrieves the closed captioning service state (on or off).

HRESULT GetServiceState(
AM_LINE21_CCSTATE *lpState
);

Parameters
lpState
Pointer to the retrieved state. Supported state values are AM_L21_CCSTATE_On and AM_L21_CCSTATE_Off. Closed-captioned text is off by default.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

See Also

IAMLine21Decoder::SetServiceState

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder Interface

Sets the physical color to use as background for overlays.

HRESULT SetBackgroundColor(
DWORD dwPhysColor
);

Parameters
dwPhysColor
DWORD value that specifies the physical background color.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

Magenta is the default background color.

See Also

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder Interface

Sets the current closed captioning service.

HRESULT SetCurrentService(
AM_LINE21_CCSERVICE Service
);

Parameters
Service
Specified service. This value is a member of the AM_LINE21_CCSERVICE enumerated data type. The default service is AM_L21_CCSERVICE_Caption1.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

See Also

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder Interface

Sets whether to make the caption text background opaque or transparent.

HRESULT SetDrawBackgroundMode(
AM_LINE21_DRAWBGMODE Mode
);

Parameters
Mode
Mode to set. Supported mode values are AM_L21_DRAWBGMODE_Opaque and AM_L21_DRAWBGMODE_Transparent.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

By default, the caption background is opaque.

See Also

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder::SetOutputFormat

IAMLine21Decoder Interface

Sets information that describes output video characteristics such as size and bit depth.

HRESULT SetOutputFormat(
LPBITMAPINFO lpbmi
);

Parameters
lpbmi
Pointer to the specified BITMAPINFO structure containing the desired output format.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The default video output size is 320 × 240 pixels.

See Also

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder Interface

Sets whether the renderer should redraw the whole output bitmap for each sample.

HRESULT SetRedrawAlways(
BOOL bOption
);

Parameters
bOption
Value indicating whether the whole bitmap should be redrawn. TRUE indicates redraw always, FALSE means do not redraw always.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

Remarks

Call this method from your filter if it dirties the buffer that it provides to the Line21 Decoder filter. Typically, a mixer filter resides in the filter graph directly downstream from the Line21 Decoder filter. The mixer filter should call this method and set bOption to TRUE to ensure the entire bitmap is redrawn properly.

A downstream mixer (or any filter that needs to do so) should only call this method with bOption set to TRUE if it provides the same buffer to the Line21 decoder as it uses to mix secondary video streams(s).

Redrawing (setting bOption to TRUE) degrades performance and increases CPU load, because it negates any potential optimizations.

See Also

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder::SetServiceState

IAMLine21Decoder Interface

Sets the closed captioning service state.

HRESULT SetServiceState(
AM_LINE21_CCSTATE State
);

Parameters
State
Specified state. Supported state values are AM_L21_CCSTATE_On and AM_L21_CCSTATE_Off. Closed-captioned text is off by default.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if a parameter is invalid or NOERROR to indicate success.

See Also

IAMLine21Decoder::GetServiceState

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMovie Interface

The IAMovie interface is a plug-in distributor (PID) interface that you could use as a replacement for all other interfaces on the filter graph manager. It wraps the most commonly used methods of IGraphBuilder, IMediaControl, IMediaEvent, and IMediaPosition by providing the same methods as these interfaces and simply calling these interfaces on the filter graph manager for the implementation. It also adds several unique methods that simplify instantiating and running a filter graph.

When to Implement

This interface is implemented by the IAMovie sample plug-in distributor included in this SDK. It is not expected that anything else will implement this interface.

When to Use

Applications use plug-in distributors. If this interface is implemented through the IAMovie sample application, you can use the methods on this interface rather than the methods on the IGraphBuilder, IMediaControl, IMediaEvent, and IMediaPosition interfaces. You can also use specialized methods on this interface to render a filter graph and play it in one command, to enumerate filters in the filter graph that contain a specified interface, to enumerate all pins in the filter graph, and to perform other tasks.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterGraph methods | Description
AddFilter | Adds a filter to the graph and gives it a name.
RemoveFilter | Removes a filter from the graph.
Reconnect | Breaks the existing pin connection and reconnects it to the same pin.
EnumFilters | Provides an enumerator for all filters in the graph.
FindFilterByName | Finds a filter that was added with a specified name.
ConnectDirect | Connects the two IPin objects directly (without intervening filters).
Reconnect | Breaks the existing pin connection and reconnects it to the same pin.
Disconnect | Disconnects the pin, if connected.
SetDefaultSyncSource | Sets the default synchronization source (a clock).
IAMovie methods | Description
Connect | Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render | Adds a chain of filters to this output pin so as to render it.
Run | Switches the entire filter graph into running mode.
Pause | Pauses all filters in the filter graph.
Stop | Switches all filters in the filter graph to a stopped state.
GetState | Retrieves the state of the filter graph.
RenderFile | Adds and connects filters needed to play the specified file.
AddSourceFilter | Adds to the graph the source filter that can read the given file name, and returns an interface pointer to the filter object.
GetEventHandle | Retrieves a handle to a manual-reset event that will be signaled.
GetEvent | Retrieves the next notification event.
WaitForCompletion | Waits until the graph's operation has completed.
CancelDefaultHandling | Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling | Restores default handling for this event.
get_Duration | Retrieves the total duration of the media stream.
put_CurrentPosition | Sets the time that the media stream begins.
get_CurrentPosition | Retrieves the current position in terms of the total length of the media stream.
get_StopTime | Retrieves the position within the media stream at which playback should stop.
put_StopTime | Sets the position within the media stream at which playback should stop.
get_PrerollTime | Retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_PrerollTime | Sets the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_Rate | Sets the playback rate, relative to normal playback of the media stream.
get_Rate | Retrieves the playback rate, relative to normal playback of the media stream.
RemoveAllFilters | Removes all filters from the filter graph.
Play | Plays the media in the current filter graph.
PlayFile | Plays the media in a given file.
EnumFiltersByInterface | Retrieves a list of filters supporting a specified interface.
EnumPins | Retrieves a list of pins in the filter graph.
EnumPinsIn | Retrieves a list of input pins in the filter graph.
EnumPinsOut | Retrieves a list of output pins in the filter graph.
RenderAll | Renders all output pins in the filter graph.
RenderNewFile | Renders a filter graph for a file name, possibly reusing existing filters.
FreeEventParams | Frees the resources associated with an event's parameters.

IAMovie::AddSourceFilter

IAMovie Interface

Adds a source filter to the filter graph for this file. The IGraphBuilder::RenderFile method adds the same source filter.

HRESULT AddSourceFilter(
LPCWSTR lpwstrFileName,
IBaseFilter* * ppFilter
);

Parameters
lpwstrFileName
[in] Pointer to the file.
ppFilter
[out] Pointer to an IBaseFilter interface on the filter that was added.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::AddSourceFilter method. The lpwstrFileName file name is used as the filter name when IGraphBuilder::AddSourceFilter is called.

IAMovie::CancelDefaultHandling

IAMovie Interface

Cancels any default handling by the filter graph of the specified event and ensures that it is passed to the application.

HRESULT CancelDefaultHandling(
long lEvCode
);

Parameters
lEvCode
Event code for which to cancel default handling.
Return Values

Returns S_OK if successful, or S_FALSE if the event does not have any default handling.

Remarks

This method simply calls the IMediaEvent::CancelDefaultHandling method.

IAMovie::Connect

IAMovie Interface

Connects the two pins, using intermediates if necessary.

HRESULT Connect(
IPin * ppinOut,
IPin * ppinIn
);

Parameters
ppinOut
[in] Output pin.
ppinIn
[in] Input pin.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::Connect method.

IAMovie::EnumFiltersByInterface

IAMovie Interface

Retrieves a list of filters supporting a specified interface.

HRESULT EnumFiltersByInterface(
REFIID riid,
IEnumFilters ** ppEnum
);

Parameters
riid
[in] REFIID of the interface qualifying the search.
ppEnum
[out] Retrieved IEnumFilters enumerator containing the matching filters.
Return Values

Returns an HRESULT value.

Remarks

This method retrieves an IEnumFilters enumerator containing a list of pointers to filters in the filter graph that support a specified interface. Note that the pointers in the list (as returned by IEnumFilters::Next) actually point to the specified riid interface on each filter rather than to the IBaseFilter interface. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPins

IAMovie Interface

Retrieves a list of pins in the filter graph.

HRESULT EnumPins(
IEnumPins ** ppEnum
);

Parameters
ppEnum
[out] Enumerator containing the list of pins.
Return Values

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPinsIn

IAMovie Interface

Retrieves a list of input pins in the filter graph.

HRESULT EnumPinsIn(
IEnumPins ** ppEnum
);

Parameters
ppEnum
[out] Enumerator containing the list of input pins.
Return Values

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::EnumPinsOut

IAMovie Interface

Retrieves a list of output pins in the filter graph.

HRESULT EnumPinsOut(
IEnumPins ** ppEnum
);

Parameters
ppEnum
[out] Enumerator containing the list of output pins.
Return Values

Returns an HRESULT value.

Remarks

For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::FreeEventParams

IAMovie Interface

Frees the resources associated with an event's parameters.

HRESULT FreeEventParams(
long lEvCode,
long lParam1,
long lParam2
);

Parameters
lEvCode
Event code.
lParam1
Event's first parameter.
lParam2
Event's second parameter.
Return Values

Returns an HRESULT.

Remarks

The lParam1 and lParam2 parameters must be LONG values, BSTR values, or IUnknown interface pointers. If an argument is a LONG value, FreeEventParams does nothing to it. If it is an IUnknown interface pointer, its reference count has been incremented. Call its Release method to decrement its reference count after calling FreeEventParams. If the argument is a BSTR value, free it by calling the task allocator after FreeEventParams.

IAMovie::get_CurrentPosition

IAMovie Interface

Retrieves the current position in terms of the total length of the media stream.

HRESULT get_CurrentPosition(
REFTIME* pllTime
);

Parameters
pllTime
[out] Reference time of the current position.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_CurrentPosition method.

IAMovie::get_Duration

IAMovie Interface

Retrieves the total duration of the media stream.

HRESULT get_Duration(
REFTIME* plength
);

Parameters
plength
[out] Returned length of the media stream.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Duration method.

IAMovie::GetEvent

IAMovie Interface

Retrieves the next notification event.

HRESULT GetEvent(
long * lEventCode,
long * lParam1,
long * lParam2,
long msTimeout
);

Parameters
lEventCode
[out] Next event notification.
lParam1
[out] First parameter of the event.
lParam2
[out] Second parameter of the event.
msTimeout
[in] Time, in milliseconds, to wait before assuming that there are no events.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::GetEvent method.

IAMovie::GetEventHandle

IAMovie Interface

Retrieves a handle to a manual-reset event that will be signaled as long as there are event notifications to deliver.

HRESULT GetEventHandle(
OAEVENT * hEvent
);

Parameters
hEvent
[out] Handle for the event.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::GetEventHandle method.

IAMovie::get_PrerollTime

IAMovie Interface

Retrieves the time prior to the start position that devices should start rolling.

HRESULT get_PrerollTime(
REFTIME* pTime
);

Parameters
pTime
[out] Returned preroll time.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_PrerollTime method.

IAMovie::get_Rate

IAMovie Interface

Retrieves the rate of playback relative to normal playback speed.

HRESULT get_Rate(
double * pdRate
);

Parameters
pdRate
[out] Returned rate.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_Rate method.

IAMovie::GetState

IAMovie Interface

Determines the state of the filter.

HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);

Parameters
dwMilliSecsTimeout
[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
State
[out] Holder of the returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).
Return Values

Returns an HRESULT value, which will be VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it has been successfully completed.

Remarks

This method simply calls the IMediaControl::GetState method. Note that the state is returned in a FILTER_STATE structure rather than as an OAFilterState type.

IAMovie::get_StopTime

IAMovie Interface

Retrieves the time at which the media stream stops.

HRESULT get_StopTime(
REFTIME* pTime
);

Parameters
pTime
[out] Returned stop time.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::get_StopTime method.

IAMovie::Pause

IAMovie Interface

Pauses all the filters in the filter graph.

HRESULT Pause( );

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Pause method.

IAMovie::Play

IAMovie Interface

Plays the media in the current filter graph.

HRESULT Play( );

Return Values

Returns an HRESULT value.

Remarks

This method runs the filter graph to completion by calling IAMovie::Run, and waits for it to complete by calling IAMovie::WaitForCompletion. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::PlayFile

IAMovie Interface

Plays the media in a given file.

HRESULT PlayFile(
LPCWSTR strFilename
);

Parameters
strFilename
[in] Name of the file to play.
Return Values

Returns an HRESULT value.

Remarks

This method calls the IAMovie::RenderNewFile method to build a filter graph capable of rendering the file passed in strFilename and then plays the file by calling IAMovie::Play. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::put_CurrentPosition

IAMovie Interface

Sets the time that the media stream begins.

HRESULT put_CurrentPosition(
REFTIME Time
);

Parameters
Time
[in] Start time.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_CurrentPosition method.

IAMovie::put_PrerollTime

IAMovie Interface

Sets the time prior to the start position that devices should start rolling.

HRESULT put_PrerollTime(
REFTIME llTime
);

Parameters
llTime
[in] Preroll time to be set.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_PrerollTime method.

IAMovie::put_Rate

IAMovie Interface

Sets the rate of playback relative to normal speed.

HRESULT put_Rate(
double dRate
);

Parameters
dRate
[in] Rate to set.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_Rate method.

IAMovie::put_StopTime

IAMovie Interface

Sets the time at which the media stream will stop.

HRESULT put_StopTime(
REFTIME Time
);

Parameters
Time
[in] Stop time.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaPosition::put_StopTime method.

IAMovie::RemoveAllFilters

IAMovie Interface

Removes all filters from the filter graph.

HRESULT RemoveAllFilters( );

Return Values

Returns an HRESULT value.

Remarks

This method enumerates all filters in the filter graph and then removes each of them by calling RemoveFilter. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::Render

IAMovie Interface

Builds a filter graph that renders the data from this output pin.

HRESULT Render(
IPin * ppinOut
);

Parameters
ppinOut
[in] Output pin.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::Render method.

IAMovie::RenderAll

IAMovie Interface

Renders all output pins in the filter graph.

HRESULT RenderAll( );

Return Values

Returns an HRESULT value.

Remarks

This member function enumerates all output pins in the filter graph and renders each of them (builds a filter graph capable of rendering the media type) by calling IAMovie::Render for each output pin. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::RenderFile

IAMovie Interface

Adds and connects filters needed to play the specified file.

HRESULT RenderFile(
LPCWSTR strFilename
);

Parameters
strFilename
Name of the file to render.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IGraphBuilder::RenderFile method with the PlayList parameter of that method set to NULL.

IAMovie::RenderNewFile

IAMovie Interface

Renders a filter graph for a file name, possibly reusing existing filters.

HRESULT RenderNewFile(
LPCWSTR strFilename
);

Parameters
strFilename
[in] Name of the file to be rendered.
Return Values

Returns an HRESULT value.

Remarks

This method disconnects all filters in the filter graph, then renders the file in the strFilename parameter by calling IAMovie::RenderFile. This will use the disconnected filters if they can be used to render the file. It then removes any unconnected filters left in the filter graph. For implementation details of this method, see the IAMovie sample plug-in distributor included in this SDK.

IAMovie::RestoreDefaultHandling

IAMovie Interface

Reinstates the normal default handling by a filter graph for the specified event if there is one.

HRESULT RestoreDefaultHandling(
long lEvCode
);

Parameters
lEvCode
[in] Event to restore.
Return Values

Returns S_OK if successful, or S_FALSE if there is no default handling for this event.

Remarks

This method simply calls the IMediaEvent::RestoreDefaultHandling method.

IAMovie::Run

IAMovie Interface

Switches the entire filter graph into a running state.

HRESULT Run( );

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Run method.

IAMovie::Stop

IAMovie Interface

Switches all filters in the filter graph to the stopped state.

HRESULT Stop( );

Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaControl::Stop method.

IAMovie::WaitForCompletion

IAMovie Interface

Provides a simplified way for applications to wait until the filter graph's operation has completed. It is the equivalent of blocking until the event notification EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT is received.

HRESULT WaitForCompletion(
long msTimeout,
long * pEvCode
);

Parameters
msTimeout
[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
pEvCode
[out] Event to wait for.
Return Values

Returns an HRESULT value.

Remarks

This method simply calls the IMediaEvent::WaitForCompletion method.


IAMovieSetup Interface

The IAMovieSetup interface provides methods that allow objects in a dynamic-link library (DLL) to be self-registering. The IAMovieSetup interface works in conjunction with an overall registration architecture that COM requires; this architecture is partially implemented in the DirectShow™ base classes. The remainder of the implementation is described in the following sections.

When to Implement

Implement this interface if you want your filter or plug-in distributor to be able to register itself automatically as part of a setup routine on an end user system. The two methods in this interface, IAMovieSetup::Register and IAMovieSetup::Unregister, are implemented by the CBaseFilter base class for self-registering filters. For a complete list of steps showing how to use this interface with the DirectShow class library, see Register DirectShow Objects.

When to Use

Use implemented methods on this interface from an entry point on the filter that is called by a setup utility or installation utility. These are used automatically by the DirectShow architecture and normally should not need to be called by any other component.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMovieSetup methods | Description
Register | Adds the filter to the registry.
Unregister | Removes the filter from the registry.

IAMovieSetup::Register

IAMovieSetup Interface

Adds the filter to the registry.

HRESULT Register(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method registers the filter, its pins, and the media type associated with the pins. It should be implemented to use IFilterMapper methods to accomplish this. See the CBaseFilter::Register member function for a description of its implementation.

IAMovieSetup::Unregister

IAMovieSetup Interface

Removes the filter from the registry.

HRESULT Unregister(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method should be implemented to use the IFilterMapper::UnregisterFilter method to remove the filter from the registry. This effectively removes the pins and media types as well.


IAMStreamConfig Interface

The IAMStreamConfig interface enables you to find out what types of formats an output pin can be connected with. Additionally it can be used to set stream formats, to tell a pin to connect with a certain format the next time it's connected, or to make it reconnect with a new format if it's already connected. Audio/video capture and audio/video compression filters implement this interface on their output pins, but potentially any filter dealing with audio or video can implement this interface on its output pins.

Use this interface to set a pin's output format, rather than connecting the pin by using a specific media type. After setting an output format, the pin will try to use that format the next time it connects. This enables you to call the IGraphBuilder::Render method on that pin and get a desired format without connecting the pins and providing a CMediaType class object. Your pin should offer only the media type set in the CMediaType::SetFormat function in its enumeration of media types after SetFormat is called. Before then, offer media types as usual. This will ensure that the pin uses that format for connection. An application that needs to enumerate accepted media types using CBasePin::GetMediaType must do so before calling SetFormat.

The IAMStreamConfig::GetStreamCaps method can get more information about accepted media types than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. GetStreamCaps retrieves information about the kinds of audio and video formats allowed.

GetStreamCaps provides detailed information about the media types and capabilities supported by this pin. This method returns a set of structures that includes pairs of AM_MEDIA_TYPE and either a VIDEO_STREAM_CONFIG_CAPS or an AUDIO_STREAM_CONFIG_CAPS structures describing an accepted media type and how that media type can be altered to create other acceptable media types.

Note The cropping rectangle described throughout the IAMStreamConfig documentation is the same as the VIDEOINFOHEADER structure's rcSource rectangle for the output pin.

The output rectangle described throughout the IAMStreamConfig documentation is the same as the width and height members of the output pin's BITMAPINFOHEADER structure.

For more information on GetStreamCaps see Exposing Capture and Compression Formats.

When to Implement

Implement this interface on the video output pin when you are writing a video capture or video compression filter.

When to Use

Use this interface when your application or filter must get or set audio or video stream information.

WDM capture applications that wish to preview and then capture might have to set audio and video stream information on the preview pin and again on the capture pin.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMStreamConfig methods | Description
SetFormat | Sets the audio or video stream's format.
GetFormat | Retrieves the audio or video stream's format.
GetNumberOfCapabilities | Retrieves the number of stream capabilities structures for the compressor.
GetStreamCaps | Obtains audio or video capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter.

IAMStreamConfig::GetFormat

IAMStreamConfig Interface

Retrieves the audio or video stream's format.

HRESULT GetFormat(
AM_MEDIA_TYPE **pmt
);

Parameters
pmt
[out] Address of a pointer to an AM_MEDIA_TYPE structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Be sure to initialize the media type structure before using it. For example, the following code fragment calls the Win32® ZeroMemory function to initialize the structure.

AM_MEDIA_TYPE mt;
ZeroMemory(&mt, sizeof(mt))
GetFormat(&mt);

Call the FreeMediaType function to free the structure.

IAMStreamConfig::GetNumberOfCapabilities

IAMStreamConfig Interface

Retrieves the number of stream capabilities structures for the compressor.

HRESULT GetNumberOfCapabilities(
int *piCount,
int *piSize
);

Parameters
piCount
[out] Pointer to the number of VIDEO_STREAM_CONFIG_CAPS and/or AUDIO_STREAM_CONFIG_CAPS structures supported.
piSize
[out] Pointer to the size of the configuration structure (either AUDIO_STREAM_CONFIG_CAPS or VIDEO_STREAM_CONFIG_CAPS).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMStreamConfig::GetStreamCaps

IAMStreamConfig Interface

Obtains audio, video, or other capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter.

HRESULT GetStreamCaps(
int iIndex,
AM_MEDIA_TYPE **pmt,
BYTE *pSCC
);

Parameters
iIndex
[in] Index to the desired media type and capability pair. Use the GetNumberOfCapabilities method to retrieve the total number of these pairs. Possible index values range from zero to one less than the total number of pairs.
pmt
[out] Address of a pointer to an AM_MEDIA_TYPE structure.
pSCC
[out] Pointer to either a stream configuration structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method enables you to get more information about accepted media types rather than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. Information such as possible video capture rates, media types, and sizes is returned by the VIDEO_STREAM_CONFIG_CAPS structure. Audio capabilities of the filter's output pin, including the number of inputs, sampling rate, and bit rate granularity will be returned by an AUDIO_STREAM_CONFIG_CAPS structure.

Call DeleteMediaType to free the pmt media type.

For more information on GetStreamCaps, see Exposing Capture and Compression Formats.

IAMStreamConfig::SetFormat

IAMStreamConfig Interface

Sets the audio or video stream's format.

HRESULT SetFormat(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
[in] Pointer to an AM_MEDIA_TYPE structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

A call to this method will fail if the pin is streaming.

If your output pin isn't connected and you can connect it with this media type, return S_OK from this method and start enumerating the specified media type as follows: Specify this format as format number zero in the CTransformOutputPin::GetMediaType function's iPosition parameter. You can offer and accept only this type to ensure that the pins will use this format for the connection when it occurs.

If your output pin is already connected and you can provide this type, then reconnect your pin. If the other pin can't accept the media type, fail this call and leave your connection alone.

The frame rate at which your filter should produce data is determined by the AvgTimePerFrame field of the VIDEOINFOHEADER of the media type your output pin is connected with. You may not be able to capture at any arbitrary frame rate, but only certain rates. If your pin is connected with a media type that asks for a frame rate you can't provide, you should provide frames at the next lowest frame rate possible. For instance, if your media type has AvgTimePerFrame=333333 (approx 1/30 of a second, meaning 30 frames per second), and you can only capture 29.97 or 35 frames per second, you should provide frames at 29.97 frames per second, since that is the closest value lower than 30 that you can provide. You can provide a higher frame rate than asked if the frame rate you provide does not create frame durations more than 1 microsecond shorter than requested, since the AvgTimePerFrame may simply have rounding errors. If the AvgTimePerFrame field is 0, you can supply frames at any default frame rate that you like.


IAMStreamControl Interface

The IAMStreamControl interface is exposed on input and output pins on any filter in a filter graph. This interface exposes methods that allow applications to control individual stream components in a filter graph. You can turn various streams on or off without affecting the rest of the graph. For example, you can turn off an audio stream while a video stream continues, for muting. Or a capture stream can be turned off while preview continues to flow. This interface also assists in frame accuracy when exact capture start or stop times are important.

Currently, the CBaseStreamControl base class implements IAMStreamControl. CBaseStreamControl enables the user to specify start and stop times in the CBaseStreamControl::StartAt and CBaseStreamControl::StopAt member functions and provides stream information in the CBaseStreamControl::GetInfo member function. CBaseStreamControl uses the StreamControlState enumerated data type to describe the various states a stream is in. A flowing stream is indicated by the STREAM_FLOWING setting; otherwise it is in a discarding state indicated by the STREAM_DISCARDING setting. See StreamControlState for more details on stream states.

If you want to implement this interface on your own your class should typically inherit from CBaseStreamControl to obtain an implementation of the CBaseStreamControl::StartAt, CBaseStreamControl::StopAt, and CBaseStreamControl::GetInfo methods. The CBaseStreamControl class also maintains state information and makes decisions about what to do with the sample. Developers implementing their own filters with pins that support IAMStreamControl through the CBaseStreamControl base class must follow certain guidelines outlined in the CBaseStreamControl documentation.

Note that there must be a clock in the filter graph or the stream control methods might not function as expected.

This interface is not available on the preview pin of capture cards with hardware overlay. Calling QueryInterface for this interface will return the error E_NOINTERFACE (0x80004002).

When to Implement

Implement on input or output pins of filters when you want precise control of the data stream. This interface enables you to turn off portions of the filter graph's streams at specific times without affecting the rest of the graph. Although this interface can be used throughout the graph, the output pins of audio and video capture filters and input pins of multiplexer filters primarily use it.

If you are writing a filter that will implement IAMStreamControl on one of its pins, you should set the STREAM_DISCARDING state so that the pin discards media samples in a timely fashion, rather than as soon as they are received. This means that if your pin is discarding samples as soon as it determines they are outside the time that the pin is supposed to be on, it will discard samples as fast as possible and the whole file could potentially be pushed into your filter and discarded in mere moments. This causes problems if the pin tries to call IAMStreamControl::StartAt at a later point in time because the entire file will have already been discarded. To avoid pins from dumping media samples as fast possible, your code should check the media sample's timestamp and wait until the reference clock verifies that the end of the sample's time has actually occurred before discarding. This is known as discarding in a timely fashion (see CBaseStreamControl for an implementation that does this).

When to Use

Use this interface to turn on or off certain portions of the filter graph's streams while other portions continue to process data. For example, your application can tell a video capture filter's output pin precisely when to start or stop capturing, independent of what is happening in the rest of the graph. This assists in frame accuracy when exact capture start or stop times are important.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMStreamControl methods | Description
StartAt | Informs the pin when to start sending streaming data.
StopAt | Informs the pin when to suspend processing and supplying data.
GetInfo | Retrieves information about the current streaming settings.

IAMStreamControl::GetInfo

IAMStreamControl Interface

Retrieves information about the current streaming settings.

HRESULT GetInfo(
AM_STREAM_INFO *pInfo
);

Parameters
pInfo
[out] Pointer to an AM_STREAM_INFO structure that contains current stream settings.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Call this method to discover the state of the StreamControlState enumerated data type, which indicates the stream's state. Other values in the AM_STREAM_INFO structure include start time, stop time, start cookie, and stop cookie.

IAMStreamControl::StartAt

IAMStreamControl Interface

Informs the pin when to start sending streaming data.

HRESULT StartAt(
const REFERENCE_TIME * ptStart,
DWORD dwCookie );

Parameters
ptStart
[in] Time at which to start streaming as specified in the REFERENCE_TIME structure. If NULL, start immediately (no notification); if MAX_TIME, start canceled and will have no effect.
dwCookie
[in] Specifies a particular value to be sent with the notification when the start occurs. (Only used if ptStart is non-NULL or MAX_TIME).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Streams are enabled by default, so this method will have no effect unless a previous StopAt member function has been called.

If the pointer to the REFERENCE_TIME is not NULL or MAX_TIME, then pins should signal EC_STREAM_CONTROL_STARTED with an IPin pointer and the cookie specified in the dwCookie parameter. This enables applications to tie the events back to their requests. If the ptStart pointer is NULL or MAX_TIME, then the filter graph sends no event.

If start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this to capture a single frame.

IAMStreamControl::StopAt

IAMStreamControl Interface

Informs the pin when to suspend processing and supplying data.

HRESULT StopAt(
const REFERENCE_TIME * ptStop,
BOOL bSendExtra,
DWORD dwCookie );

Parameters
ptStop
[in] Time at which to stop streaming as specified in the REFERENCE_TIME structure. If you specify NULL for ptStop, it will stop immediately (no notification); if MAX_TIME, cancels stop.
bSendExtra
[in] Indicates whether to send an extra sample after scheduled ptStop time.
dwCookie
[in] Specifies a particular value to send with the notification when the stop occurs (used only if ptStart if not NULL or MAX_TIME).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is exposed by pins that support the stopping of streams. It sets the StreamControlState enumeration type to STREAM_DISCARDING.

In video capture, you would typically call StopAt on both the output pin of a capture filter and the input pin of a multiplexer, and pay attention only to the notification from the multiplexer. This ensures that the capture filter doesn't needlessly capture extra frames, while guaranteeing that the multiplexer has, in fact, saved the last frame to a file.

In addition, you should specify TRUE for the bSendExtra parameter on the capture pin, and specify FALSE to the multiplexer pin. If an extra frame is not sent, the multiplexer will wait for the stop time indefinitely and not realize it already has received all the capture information. The multiplexer will discard the extra sample sent by the capture pin, so it will not get written to the file. Do not set bSendExtra to TRUE unless you also use IAMStreamControl on another downstream pin too, like in the preceding case.

If you call StopAt with a time that is in the middle of a packet, the filter will deliver the whole packet before going into a discarding state. Also, if start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this effect to capture a single frame (see CBaseStreamControl for an implementation example).


IAMStreamSelect Interface

The IAMStreamSelect interface controls which logical streams are played and retrieves information about them.

When to Implement

Implement this interface on your filter when you want to enable selection of logical streams and provide information about them. An example of logical stream selection is selection from a set of audio streams that encode different national languages. Perhaps you could choose English from among a set of audio streams that include English, German, and French. The MPEG splitter implements this interface.

When to Use

Use this interface when you want to select between available streams; for example, when you want to select the streams for a particular locale.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMStreamSelect methods | Description
Count | Retrieves the total count of available streams.
Info | Retrieves information about a given stream.
Enable | Enables or disables a given stream.

IAMStreamSelect::Count

IAMStreamSelect Interface

Retrieves the total count of available streams.

HRESULT Count(
DWORD *pcStreams
);

Parameters
pcStreams
[out] Pointer to a value indicating the number of available streams.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_OK.

IAMStreamSelect::Enable

IAMStreamSelect Interface

Enables or disables a given stream.

HRESULT Enable(
long lIndex,
DWORD dwFlags
);

Parameters
lIndex
[in] Index number of desired stream. Zero-based.
dwFlags
[in] Flag indicating whether to enable or disable the stream. Valid values include the following:
Value | Meaning
Zero | Disable all streams in the group containing this stream.
AMSTREAMSELECTENABLE_ENABLE | Enable only this stream within the given group and disable all others.
AMSTREAMSELECTENABLE_ENABLEALL | Enable all streams in the group containing this stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_NOTIMPL if support for the specified flag has not been implemented, E_INVALIDARG if the stream ID is invalid, or S_OK otherwise.

IAMStreamSelect::Info

IAMStreamSelect Interface

Retrieves information about a given stream.

HRESULT Info(
long lIndex,
AM_MEDIA_TYPE **ppmt,
DWORD *pdwFlags,
LCID *plcid,
DWORD *pdwGroup,
WCHAR **ppszName,
IUnknown **ppObject,
IUnknown **ppUnk
);

Parameters
lIndex
[in] Index number of desired stream. Zero-based.
ppmt
[out] Address of a pointer to the stream's media type. Optional. Use the DeleteMediaType function to free the AM_MEDIA_TYPE structure when done.
pdwFlags
[out] Pointer to flags. Optional. Valid values include the following:
Value | Meaning
Zero | Disable this stream.
AMSTREAMSELECTINFO_ENABLED | Enable the stream.
AMSTREAMSELECTINFO_EXCLUSIVE | Turns off the other streams in the group when enabling this one.
plcid
[out] Pointer to the locale context (LCID) value. This parameter points to a zero value if there is no LCID. Optional.
pdwGroup
[out] Pointer to the logical group. Optional.
ppszName
[out] Pointer to the stream name. Optional. Free with the CoTaskMemFree function when done.
ppObject
[out] Pointer to the pin or filter object associated with this stream. Optional. The object can change if the IAMStreamSelect::Enable method is called. This parameter contains a null value upon return from this method if there is no associated object.
ppUnk
[out] Address of a pointer to a stream-specific interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_FALSE if lIndex is out of range, or S_OK otherwise.

Remarks

The first stream in each group is the default.


IAMTimecodeDisplay Interface

The IAMTimecodeDisplay interface contains properties and methods that define behavior of an external SMPTE/MIDI timecode display device. This interface should be implemented in combination with IAMExtDevice, IAMExtTransport, and the other timecode interfaces to control an external device, such as a VCR, which can read, generate and/or display timecode data. This interface controls the physical timecode character generator display that is either built into a VCR or is on some other similar external device.

For more information on SMPTE timecode see the Control an External Device in DirectShow overview article.

When to Implement

Implement this interface on an external device filter that will control the timecode display on an external timecode reader or generator. Timecode readers or generators can be built into a VCR or can be a separate external device. Do not try to implement this interface if your external device can't display timecode or if your timecode is being generated through an internal card with no integral or overlay hardware.

This interface is not intended for rendering in a DirectShow filter graph, it is purely for use on external device displays.

When to Use

Use this interface when applications need to control an external device and how it's timecode information is displayed.

Hardware Requirements

See the IAMExtTransport interface for hardware requirements.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMTimecodeDisplay methods | Description
GetTCDisplayEnable | Determines whether an external device's timecode character generator output is enabled or disabled.
SetTCDisplayEnable | Enables or disables an external device's timecode character output generator.
GetTCDisplay | Retrieves current settings of the timecode character generator output.
SetTCDisplay | Sets the timecode character generator output characteristics.

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay Interface

Retrieves current settings of the timecode character generator output.

HRESULT GetTCDisplay(
long Param,
long *pValue
);

Parameters
Param
[in] Timecode display characteristic. Specify one of the following items you want to get settings for.
Value | Meaning
ED_TCD_BORDER | White border for black characters, black border for white characters
ED_TCD_INTENSITY | Intensity (brightness) of characters
ED_TCD_INVERT | Black characters on white background or white characters on black background
ED_TCD_POSITION | Position of characters
ED_TCD_SIZE | Size of characters
ED_TCD_SOURCE | Source of display's data
ED_TCD_TRANSPARENCY | Transparency of characters
pValue
[out] Current setting of the parameter specified in Param. This parameter retrieves one of the following values:
Value | Meaning
If ED_TCD_SOURCE specified in Param, will return one of the following:
ED_TCG | TimeCode generator
ED_TCR | TimeCode reader
If , ED_TCD_SIZE specified in Param, will return one of the following:
ED_LARGE | Large
ED_MED | Medium
ED_SMALL | Small
If ED_TCD_POSITION specified in Param, will return one of the following:
ED_BOTTOM | Bottom
ED_MIDDLE | Middle
ED_TOP | Top
in combination with:
ED_CENTER | Center
ED_LEFT | Left
ED_RIGHT | Right
If ED_TCD_INTENSITY specified in Param, will return one of the following:
ED_HIGH | High
ED_LOW | Low
If ED_TCD_TRANSPARENCY is specified in Param, will return a value from 0 to 4, 0 being completely opaque.
If ED_TCD_INVERT specified in Param, will return one of the following:
OAFALSE | Black characters on white background
OATRUE | White characters on black background
If ED_TCD_BORDER specified in Param, will return one of the following:
OAFALSE | Black characters for white border
OATRUE | White border for black characters
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay::GetTCDisplayEnable

IAMTimecodeDisplay Interface

Determines whether an external device's timecode character generator output is enabled or disabled.

HRESULT GetTCDisplayEnable(
long *pState
);

Parameters
pState
[out] OATRUE specifies enabled; OAFALSE specifies disabled.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is not intended for character rendering inside a filter graph, it is purely intended for hardware displays. Ensure that your external timecode reader or generator has display capability before trying to use this method.

See Also

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay Interface

Sets the timecode character generator output characteristics.

HRESULT SetTCDisplay(
long Param,
long Value
);

Parameters
Param
[in] Timecode display characteristic. Specify one of the following properties you want to set properties for.
Value | Meaning
ED_TCD_BORDER | White border for black characters, black border for white characters
ED_TCD_INTENSITY | Intensity (brightness) of characters
ED_TCD_INVERT | Black characters on white background or white characters on black background
ED_TCD_POSITION | Position of characters
ED_TCD_SIZE | Size of characters
ED_TCD_SOURCE | Source of the display's data
ED_TCD_TRANSPARENCY | Transparency of characters
Value
[in] Setting of the parameter specified in Param. Must be one of the following:
Value | Meaning
If ED_TCD_SOURCE specified in Param, set one of the following:
ED_TCG | TimeCode generator
ED_TCR | TimeCode reader
If , ED_TCD_SIZE specified in Param, set one of the following:
ED_LARGE | Large
ED_MED | Medium
ED_SMALL | Small
If ED_TCD_POSITION specified in Param, set one of the following:
ED_BOTTOM | Bottom
ED_MIDDLE | Middle
ED_TOP | Top
In combination with:
ED_CENTER | Center
ED_LEFT | Left
ED_RIGHT | Right
If ED_TCD_INTENSITY specified in Param, set one of the following:
ED_HIGH | High
ED_LOW | Low
If ED_TCD_TRANSPARENCY specified in Param, set a value from 0 to 4, 0 being completely opaque, 4 being as dark as possible.
If ED_TCD_INVERT specified in Param, set one of the following:
OAFALSE | Black on white
OATRUE | White on black
If ED_TCD_BORDER specified in Param, set one of the following:
OAFALSE | Black characters for white border
OATRUE | White border for black characters
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay Interface

Enables or disables an external device's timecode character output generator.

HRESULT SetTCDisplayEnable(
long State
);

Parameters
State
[in] Specify OATRUE to enable; OAFALSE to disable.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is not intended for rendering characters inside a filter graph, it is purely intended for hardware displays. Ensure that your external timecode reader or generator has display capability before trying to use this method.

See Also

IAMTimecodeDisplay::GetTCDisplayEnable

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMTimecodeGenerator Interface

The IAMTimecodeGenerator interface contains properties and methods that specify how an external SMPTE/MIDI timecode generator should supply data to the filter graph and the formats in which timecode should be supplied. This interface should be implemented in combination with the IAMExtDevice and IAMExtTransport interfaces to control an external device, such as a VCR. This interface provides methods that enable applications to specify various SMPTE/MIDI timecode modes or formats that an external device should use in the generation of timecode, and methods that verify that the generator is working properly.

SMPTE timecode is a frame addressing system that identifies video and audio sources, makes automatic track synchronization possible, and provides a container for additional data related to the production. SMPTE timecode's main purpose is to provide a machine-readable address for video and audio. It is displayed in hh:mm:ss:ff format and is thoroughly defined in ANSI/SMPTE 12-1986.

For more information on SMPTE timecode see the Control an External Device in DirectShow overview article.

See the IAMTimecodeReader interface for more information on methods which access an external timecode reader.

When to Implement

Implement this interface on an external device filter when you want to control how SMPTE/MIDI timecode information is generated by an external timecode generator.

Expose the IMediaSeeking interface on your filter to enable applications to convert timecode to DirectShow reference time (by using IMediaSeeking::ConvertTimeFormat).

Your external device must be able to read timecode and send it to the computer over its control interface (see hardware requirements). If this is not the case, you must either have a timecode reader card in your computer, or you can write a software decoder that converts VITC embedded in captured video frames or LTC captured as an audio signal into DirectShow timecode samples.

When to Use

Use this interface when you want to generate SMPTE timecode in an external device.

Hardware Requirements

See the IAMExtTransport interface for hardware requirements.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMTimecodeGenerator methods | Description
GetTCGMode | Retrieves the SMPTE timecode generator properties.
SetTCGMode | Sets the SMPTE timecode generator properties.
put_VITCLine | Specifies which line(s) to insert the vertical interval timecode information into.
get_VITCLine | Retrieves which line(s) the vertical interval timecode information has been inserted into.
SetTimecode | Sets the timecode, userbit value, or both.
GetTimecode | Retrieves the most recent timecode and/or userbit value available in the stream.

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator Interface

Retrieves the SMPTE timecode generator properties.

HRESULT GetTCGMode(
long Param,
long *pValue
);

Parameters
Param
[in] Timecode generator mode. Specify one of the following modes you want to get settings for.
Value | Meaning
ED_TCG_FRAMERATE | Frame rate
ED_TCG_REFERENCE_SOURCE | Source of the count value
ED_TCG_SYNC_SOURCE | Source of the hardware clock reference
ED_TCG_TIMECODE_TYPE | SMPTE timecode format of the generator
pValue
[out] Current setting of the parameter specified in Param.

If you specify ED_TCG_TIMECODE_TYPE in Param, this parameter retrieves one of the following:
Value | Meaning
ED_TCG_MIDI_FULL | MIDI full frame timecode
ED_TCG_MIDI_QF | MIDI quarter frame timecode
ED_TCG_SMPTE_LTC | Linear timecode
ED_TCG_SMPTE_VITC | Vertical interval timeCode

If you specify ED_TCG_FRAMERATE in Param, this parameter retrieves one of the following:
Value | Meaning
ED_FORMAT_SMPTE_24 | 24 frames per second
ED_FORMAT_SMPTE_25 | 25 frames per second
ED_FORMAT_SMPTE_30 | 30 frames per second. Nondrop frame
ED_FORMAT_SMPTE_30DROP | 30 frames per second. Drop frame (actually 29.97 fps)

If you specify ED_TCG_SYNC_SOURCE in Param, this parameter retrieves one of the following:
Value | Meaning
ED_TCG_FREE | Lock to nothing (freerun)
ED_TCG_READER | Lock to timecode reader
ED_TCG_VIDEO | Lock to incoming video

If you specify ED_TCG_REFERENCE_SOURCE in Param, this parameter retrieves one of the following:
Value | Meaning
ED_TCG_FREE | No count reference source
ED_TCG_READER | Syncronize to reader value (jamsync)

Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method returns various settings of the timecode generator. For more information on ED_TCG_TIMECODE_TYPE, see IAMTimecodeReader::SetTCRMode.

IAMTimecodeGenerator::GetTimecode

IAMTimecodeGenerator Interface

Retrieves the most recent timecode and/or userbit value available in the stream.

HRESULT GetTimecode(
PTIMECODE_SAMPLE pTimecodeSample
);

Parameters
pTimecodeSample
[out] Pointer to a TIMECODE_SAMPLE timecode structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to obtain the most recent timecode value available in the stream. The application can use this to monitor the timecode and verify the generator is working properly.

See Also

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator Interface

Retrieves which line(s) the vertical interval timecode information has been inserted into.

HRESULT get_VITCLine(
long *pLine );

Parameters
pLine
[out] Pointer to the vertical line(s) containing the timecode information (valid lines are 11-20).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To get VITC information from multiple lines, make successive calls to this method, once for each line desired, with the hi bit set for each line.

See Also

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator Interface

Specifies which line to insert the vertical interval timecode information into.

HRESULT put_ VITCLine(
long Line );

Parameters
Line
[in] Vertical line to contain the timecode information (valid lines are 11-20; 0 means autoselect).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To generate VITC on specific multiple lines, make successive calls to this method, once for each line desired.

Set the hi bit to add to this line to any previously set lines.

See Also

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator::SetTCGMode

IAMTimecodeGenerator Interface

Sets the SMPTE timecode generator properties.

HRESULT SetTCGMode(
long Param,
long Value
);

Parameters
Param
[in] Timecode generator mode. Specify one of the following properties.
Value | Meaning
ED_TCG_FRAMERATE | Frame rate
ED_TCG_REFERENCE_SOURCE | Source of the count value
ED_TCG_SYNC_SOURCE | Source of the hardware clock reference
ED_TCG_TIMECODE_TYPE | SMPTE timecode format of the generator
Value
[in] Setting of the parameter specified in Param.
Value | Meaning
If ED_TCG_TIMECODE_TYPE specified in Param, set one of the following:
ED_TCG_MIDI_FULL | MIDI Full Frame timecode
ED_TCG_MIDI_QF | MIDI Quarter Frame timecode
ED_TCG_SMPTE_LTC | Linear TimeCode
ED_TCG_SMPTE_VITC | Vertical Interval TimeCode
If , ED_TCG_FRAMERATE specified in Param, this parameter is set to one of the following:
ED_FORMAT_SMPTE_24 | 24 frames per second
ED_FORMAT_SMPTE_25 | 25 frames per second
ED_FORMAT_SMPTE_30 | 30 frames per second. Nondrop frame
ED_FORMAT_SMPTE_30DROP | 30 frames per second. Drop frame (actually 29.97 fps)
If ED_TCG_SYNC_SOURCE specified in Param, set one of the following:
ED_TCG_FREE | Lock to nothing (freerun)
ED_TCG_READER | Lock to timecode reader
ED_TCG_VIDEO | Lock to incoming video
If ED_TCG_REFERENCE_SOURCE specified in Param, set one of the following:
ED_TCG_FREE | No count reference source
ED_TCG_READER | sync to reader value (jamsync)
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method sets various properties of the timecode generator. For more information on ED_TCG_TIMECODE_TYPE, see the IAMTimecodeReader::SetTCRMode method.

See Also

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator Interface

Sets the timecode, userbits value, or both.

HRESULT SetTimecode(
PTIMECODE_SAMPLE pTimecodeSample
);

Parameters
pTimecodeSample
[in] Pointer to a TIMECODE_SAMPLE timecode structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To set only timecode, set userbit value to NULL, and vice versa. If generator is running, these values will take effect immediately.

See Also

IAMTimecodeGenerator::GetTimecode

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMTimecodeReader Interface

IAMTimecodeReader is an interface that can be implemented to read SMPTE (Society of Motion Picture and Television Engineers) or MIDI timecode from an external device. It contains properties and methods that specify the timecode format that an external device should read and how it is embedded in the media. It is expected that you will use this interface with the IAMExtDevice and IAMExtTransport interfaces to control an external device, such as a VCR, which can read timecode data.

SMPTE timecode is a frame addressing system that identifies video and audio sources, makes automatic track synchronization possible, and provides a container for additional data related to the source material. SMPTE timecode's main purpose is to provide a machine-readable address for video and audio. It is displayed in hh:mm:ss:ff (hours, minutes, seconds, frames) format and is thoroughly defined in ANSI/SMPTE 12-1986.

For more information on SMPTE timecode see the Control an External Device in DirectShow overview article.

When to Implement

Implement this interface on an external device filter when you want to specify how an external device should read SMPTE/MIDI timecode information.

Expose the IMediaSeeking interface on your filter so that applications can convert timecode to DirectShow reference time (by using the IMediaSeeking::ConvertTimeFormat method).

Your external device must be able to read timecode and send it to the computer over its control interface. If this is not the case, you must either have a timecode reader card in your computer, or you can write a software decoder that converts VITC (Vertical Interval Timecode) in captured video frames or LTC (Linear Timecode) captured as an audio signal into DirectShow timecode samples.

When to Use

Use this interface when you need to read timecode information for controlling an external device, or when you want to use timecode information from an external device in applications that must refer to original program information.

Applications generally save timecode in one of two ways. It is either written to the capture file as an additional stream or as a discontinuity table stored in the extended AVI file index. It is commonly used to trigger capture or playback and to create edit decision lists that describes how source material is organized into a finished product.

If you intend to capture timecode, treat it as a separate stream that has its own media type. It can be consumed by an appropriate file-writing multiplexer filter. However, sometimes there are errors in reading the timecode off the tape because of dropouts and other mechanical tape problems. In such cases, the timecode source filter should simply drop samples and mark the next valid one with the discontinuity property.

If you intend to use timecodes to trigger capture or playback from a timecoded (or "striped") videotape, the sequence of events goes as follows:

  1. Build a capture graph, open a target AVI file, and preallocate disk space if necessary. If the captured material will be appended to an existing AVI file, seek to the end of the file before writing. The capture graph is paused at this point.
  2. Search the VCR to the capture start point and note the timecode. You can either enter this value manually into your program, or the application can automatically read it. Automatic reading requires that the graph is running but the stream control interfaces on the file multiplexer's input pins are discarding incoming samples, effectively gating the capture.
  3. Cue the VCR to preroll position, usually five seconds before the target point.
  4. Start the VCR and the graph. When the trigger point is reached (or the trigger point minus the file writer's preroll), the stream control interfaces release the file multiplexer and it begins streaming media samples to the file writer.
  5. You can stop the capture process manually or by setting a duration property on the stream control interface.

You must consider discontinuous timecode, both during preroll and during the capture process; it is reasonable to demand that the timecode be continuous and monotonically increasing throughout the preroll and capture start point. This prevents a potentially ambiguous calculation of relative stream times by the IMediaSeeking::ConvertTimeFormat method. Also, the timecode need not be the only gating signal for triggered capture. Any time-stamped data stored in the vertical blanking interval, such as Intercast or Closed Caption data (XDS), can be used to start the streaming of video and audio data to disk.

Hardware Requirements

See the IAMExtTransport interface for hardware requirements.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMTimecodeReader methods | Description
GetTCRMode | Retrieves properties of the timecode reader.
SetTCRMode | Sets the timecode reader properties.
put_VITCLine | Specifies the vertical interval line that the timecode reader will use to read timecode.
get_VITCLine | Retrieves the vertical interval line that the timecode reader is using to read timecode.
GetTimecode | Retrieves the most recent timecode, userbits, and flag values available in the stream.

IAMTimecodeReader::GetTCRMode

IAMTimecodeReader Interface

Retrieves the timecode reader's properties.

HRESULT GetTCRMode(
long Param,
long *pValue
);

Parameters
Param
[in] Timecode reader property to get (use ED_TCR_SOURCE).
pValue
[out] Value of the requested timecode reader property. Must be one of the following:
Value | Meaning
ED_TCR_CT | Control track
ED_TCR_LTC | Linear timecode
ED_TCR_VITC | Vertical interval timecode
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Linear TimeCode is recorded on an analog audio track as a bi-phase mark-encoded signal. Each timecode frame is one video frame time in duration.

Vertical TimeCode is usually stored in two lines of a video signal's vertical interval, somewhere between lines 11 and 20.

Control Track is a once-per-frame signal recorded on a special track on a tape. The head and drive servo mechanisms use it to keep everything locked. It is also used to drive the counter on machines without timecode capability, and can optionally be used on machines equipped with a timecode reader.

See Also

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader::GetTimecode

IAMTimecodeReader Interface

Retrieves the most recent timecode, userbit, and flag values available in the stream.

HRESULT GetTimecode(
PTIMECODE_SAMPLE pTimecodeSample
);

Parameters
pTimecodeSample
[out] Pointer to a TIMECODE_SAMPLE timecode structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Use this method to monitor the timecode and to parse duplicates and discontinuities. The source filter supplying the timecode, or possibly a downstream filter, might want to parse for discontinuities or errors since you have to look at every sample to be able to retrieve the most recent timecode.

Applications can fill undefined bits in the timecode word to store syncronization information, or to encode original film and audio tape information. These undefined bits, or userbits, are retrieved by calling this method.

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader Interface

Retrieves the vertical interval line that the timecode reader is using to read timecode.

HRESULT get_VITCLine(
long *pLine );

Parameters
pLine
[out] Vertical line containing timecode information (valid lines are 11-20).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The hi bit indicates that multiple lines are used and successive calls will cycle through the line numbers.

See Also

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader Interface

Specifies the vertical interval line that the timecode reader will use to read timecode.

HRESULT put_VITCLine(
long Line );

Parameters
Line
[in] Vertical line containing timecode information (valid lines are 11-20; 0 means autoselect).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If VITC mode is specified in the IAMTimecodeReader::SetTCRMode method, you must specify which line or lines will contain timecode information. To read VITC on specific multiple lines, the caller would make successive calls to put_VITCLine, once for each line desired.

Set the hi bit to add to the list of lines for readers that test across multiple lines.

See Also

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader Interface

Sets the timecode reader properties.

HRESULT SetTCRMode(
long Param,
long Value
);

Parameters
Param
[in] Property you want to set (use ED_TCR_SOURCE).
Value
[in] Value of the specified property; currently one of the following:
Value | Meaning
ED_TCR_CT | Control Track
ED_TCR_LTC | Linear TimeCode
ED_TCR_VITC | Vertical Interval TimeCode
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Linear TimeCode is recorded on an analog audio track as an NRZ bi-phase mark-encoded signal. Each timecode frame is one video frame time in duration.

Vertical TimeCode is usually stored in two lines of a video signal's vertical interval, somewhere between 10 and 20.

Control Track is a once-per-frame signal recorded on a special track on a tape. The head and drive servo mechanisms use it to keep everything locked. It is also used to drive the counter on machines without timecode capability, and can optionally be used on machines equipped with a timecode reader.

See Also

IAMTimecodeReader::GetTCRMode

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMTVTuner Interface

The IAMTVTuner interface is implemented on filters that provide TV tuning capabilities. A TV tuner filter is a device that selects an analog broadcast or cable channel to be viewed. The IAMTVTuner interface enables applications to set these transmission types through the TunerInputType enumerated data type.

Because Microsoft® Video for Windows® wasn't written with TV tuning capabilities in mind, you can implement TV tuner filters only on operating systems that can interpret TV tuning information. The Windows Driver Model implements a version that contains international channel to frequency mapping tables, found in the Country Codes and Channel to Frequency Mappings appendix, which you can use in a filter graph.

The IAMTVTuner interface supports multistandard analog decoders, which you can enumerate and select by using the get_AvailableTVFormats method. The AnalogVideoStandard data type contains these formats, which include NTSC, PAL, and SECAM, among others. IAMTVTuner also supports tuners with multiple input pins, to allow for multiple devices and multiple transmission types.

IAMTVTuner also maps TV channels to specific frequencies through the IAMTVTuner::put_Channel and IAMTVTuner::AutoTune methods. These methods handle the details of the conversion so that the hardware driver receives an exact frequency. Because channels in different countries map to different frequencies, worldwide mapping tables are provided in the Country Codes and Channel to Frequency Mappings appendix. Override the existing country code by selecting the new value from the appendix and passing it in as the parameter for the IAMTVTuner::put_CountryCode method. This is useful when a country wants to receive broadcast video from a different national source.

When to Implement

Implement this interface when you write a filter that can tune a TV.

When to Use

Use this interface when setting TV channels and to get or set information about their frequencies. This interface can also determine what analog video standards your TV supports.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMTVTuner methods | Description
get_AvailableTVFormats | Retrieves all the analog video TV standards that are supported by the tuner.
get_TVFormat | Retrieves the current analog video TV standard in use.
put_Channel | Sets the TV channel.
get_Channel | Retrieves the current TV channel set by put_Channel.
ChannelMinMax | Retrieves the highest and lowest channels available.
AutoTune | Scans for a precise signal on the channel's frequency.
StoreAutoTune | Saves the fine-tuning information for all channels.
put_CountryCode | Sets the country code to establish the frequency to use.
get_CountryCode | Retrieves the country code that establishes the current channel to frequency mapping.
put_TuningSpace | Sets a storage index for regional channel to frequency mappings.
get_TuningSpace | Retrieves the storage index for regional fine tuning set in put_TuningSpace.
get_NumInputConnections | Retrieves the number of TV sources plugged into the tuner filter.
put_InputType | Sets the tuner input type (cable or antenna).
get_InputType | Retrieves the input type (Cable or Antenna) set in put_InputType.
put_ConnectInput | Sets the hardware tuner input connection.
get_ConnectInput | Retrieves the hardware tuner input connection.
get_VideoFrequency | Retrieves the current video frequency.
get_AudioFrequency | Retrieves the current audio frequency.

IAMTVTuner::AutoTune

IAMTVTuner Interface

Scans for a precise signal on the channel's frequency.

HRESULT AutoTune(
long lChannel,
long * plFoundSignal
);

Parameters
lChannel
[in] TV channel number.
plFoundSignal
[out] Value indicating whether the channel's frequency was found; TRUE indicates found, FALSE indicates not found.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

TV channels generally map to a unique frequency depending on regional variances. To avoid interference between multiple transmitters that are assigned the same channel when they are in close geographic proximity, small frequency offsets are introduced at each transmitter. In the US, this offset ranges up to +/– 26.25 kilohertz (kHz).

This method handles the channel to frequency conversion and scans for the most precise frequency. Store these values by calling the IAMTVTuner::StoreAutoTune method. Base frequencies for channels can be found in the Country Codes and Channel to Frequency Mappings appendix.

IAMTVTuner::ChannelMinMax

IAMTVTuner Interface

Retrieves the highest and lowest channels available.

HRESULT ChannelMinMax(
long *lChannelMin,
long *lChannelMax
);

Parameters
lChannelMin
[out] Pointer to the lowest channel.
lChannelMax
[out] Pointer to the highest channel.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Frequencies for channels are found in the Country Codes and Channel to Frequency Mappings appendix.

IAMTVTuner::get_AudioFrequency

IAMTVTuner Interface

Retrieves the currently tuned audio frequency.

HRESULT get_ AudioFrequency(
long *lFreq
);

Parameters
lFreq
[out] Pointer to the audio frequency.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_AvailableTVFormats

IAMTVTuner Interface

Retrieves all the analog video TV standards that are supported by the tuner.

HRESULT get_ AvailableTVFormats(
long *lAnalogVideoStandard
);

Parameters
lAnalogVideoStandard
[out] Pointer to the combination of analog video standards supported.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

See the AnalogVideoStandard enumerated data type for supported formats.

IAMTVTuner::get_Channel

IAMTVTuner Interface

Retrieves the current TV channel set by put_Channel.

HRESULT get_Channel (
long * plChannel,
long *plVideoSubChannel,
long *plAudioSubChannel
);

Parameters
plChannel
[out] Pointer to the channel.
plVideoSubChannel
[out] Pointer to a predefined video subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.
plAudioSubChannel
[out] Pointer to a predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

See the Country Codes and Channel to Frequency Mappings appendix for frequencies for plChannel.

IAMTVTuner::get_ConnectInput

IAMTVTuner Interface

Retrieves the hardware tuner input connection.

HRESULT get_ConnectInput (
long *plIndex
);

Parameters
plIndex
[out] Pointer to the input pin to get the connection for.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_CountryCode

IAMTVTuner Interface

Retrieves the country code that establishes the current channel to frequency mapping.

HRESULT get_CountryCode (
long * plCountryCode
);

Parameters
plCountryCode
[in] Country code currently in use by the TV Tuner filter.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The IAMTVTuner::put_CountryCode method determines which channel to frequency mapping table to use. This establishes the base frequencies for the given country. Use the IAMTVTuner::AutoTune method to determine the exact frequencies for specific regions.

Override the country code when a country wants to receive broadcast video from a different national source. See the Country Codes and Channel to Frequency Mappings appendix for a list of country codes.

IAMTVTuner::get_InputType

IAMTVTuner Interface

Retrieves the input type set in put_InputType.

HRESULT get_InputType (
long lIndex,
TunerInputType * pInputType
);

Parameters
lIndex
[in] Index value that specifies the input pin that will be set.
pInputType
[out] Pointer to the TunerInputType connection type; either cable (TunerInputCable) or antenna (TunerInputAntenna).
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_NumInputConnections

IAMTVTuner Interface

Retrieves the number of TV sources plugged into the tuner filter.

HRESULT get_ NumInputConnections(
long * plNumInputConnections
);

Parameters
plNumInputConnections
[out] Number of TV sources plugged into the tuner filter.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_TuningSpace

IAMTVTuner Interface

Gets the storage index for regional fine tuning set in put_TuningSpace.

HRESULT get_TuningSpace(
long * plTuningSpace
);

Parameters
plTuningSpace
[out] Value specifying the current locale.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

As TV tuners move into portable systems, you must retain locale-specific mappings of available channels and their actual frequencies. Formulating different lTuningSpace values for each locale provides a way of switching the channel/frequency mappings when moving from region to region.

IAMTVTuner::get_TVFormat

IAMTVTuner Interface

Retrieves the current analog video TV standard in use.

HRESULT get_ TVFormat(
long * plAnalogVideoStandard );

Parameters
plAnalogVideoStandard
[out] Pointer to the analog video standard currently in use by the TV Tuner filter.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

See the AnalogVideoStandard enumerated data type for supported formats.

IAMTVTuner::get_VideoFrequency

IAMTVTuner Interface

Retrieves the current video frequency.

HRESULT get_VideoFrequency(
long *lFreq
);

Parameters
lFreq
[out] Pointer to the video frequency.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::put_Channel

IAMTVTuner Interface

Sets the TV channel.

HRESULT put_ Channel(
long lChannel,
long lVideoSubChannel,
long lAudioSubChannel
);

Parameters
lChannel
[in] TV channel number.
lVideoSubChannel
Predefined video subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.
lAudioSubChannel
Predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method handles the channel to frequency function call that converts the TV channel to a TV frequency. Frequencies for channels are found in the Country Codes and Channel to Frequency Mappings appendix.

IAMTVTuner::put_ConnectInput

IAMTVTuner Interface

Sets the hardware tuner input connection.

HRESULT put_ ConnectInput(
long lIndex
);

Parameters
lIndex
[in] Index value of the input pin to set connection for.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::put_CountryCode

IAMTVTuner Interface

Sets the country code to establish the frequency to use.

HRESULT put_ CountryCode(
long lCountryCode
);

Parameters
lCountryCode
[in] Value indicating the country code.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method establishes the base frequencies for the given country. Use the IAMTVTuner::AutoTune method to determine the exact frequencies for specific regions, unless there are previously cached settings for the new country.

Override the country code when a country wants to receive broadcast video from a different national source. See the Country Codes and Channel to Frequency Mappings appendix for a list of country codes.

IAMTVTuner::put_InputType

IAMTVTuner Interface

Sets the tuner input type (cable or antenna).

HRESULT put_ InputType(
long lIndex,
TunerInputType InputType
);

Parameters
lIndex
[in] Index value that specifies the input pin to be set.
InputType
[in] Indicates the connection type, as specified in the TunerInputType data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::put_TuningSpace

IAMTVTuner Interface

Sets a storage index for regional channel to frequency mappings.

HRESULT put_TuningSpace(
long lTuningSpace
);

Parameters
lTuningSpace
[in] Value indicating the current locale.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

As TV tuners move into portable systems, you must retain locale-specific mappings of available channels and their actual frequencies. Formulating different lTuningSpace values for each locale provides a way of switching the channel to frequency mappings when moving from region to region.

IAMTVTuner::StoreAutoTune

IAMTVTuner Interface

Saves the fine-tuning information for all channels.

HRESULT StoreAutoTune( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Override the channel to frequency information stored by this method by setting a new country code in the IAMTVTuner::put_CountryCode method. See the Country Codes and Channel to Frequency Mappings appendix for a listing of country codes.


IAMVfwCaptureDialogs Interface

The IAMVfwCaptureDialogs interface enables an application to display one of the three dialog boxes (Source, Format, or Display) provided by Microsoft® Video for Windows® capture drivers.

When to Implement

The Video for Windows VFW Video Capture filter implements this interface. It isn't expected that anything else will implement this interface.

When to Use

Any application that enables the user to change settings in a Video for Windows capture driver-supplied dialog box should use this interface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVfwCaptureDialogs methods | Description
HasDialog | Determines if the specified dialog box exists in the driver.
ShowDialog | Displays the specified dialog box.
SendDriverMessage | Sends a driver-specific message.

IAMVfwCaptureDialogs::HasDialog

IAMVfwCaptureDialogs Interface

Determines if the specified dialog box exists in the driver.

HRESULT HasDialog(
int iDialog );

Parameters
iDialog
[in] Desired dialog box. This is a member of the VfwCaptureDialogs enumerated data type.
Return Values

Returns S_OK if the driver contains the dialog box or S_FALSE otherwise.

Remarks

This method calls the Video for Windows videoDialog function to query for the existence of the appropriate dialog box.

IAMVfwCaptureDialogs::SendDriverMessage

IAMVfwCaptureDialogs Interface

Sends a driver-specific message.

HRESULT SendDriverMessage(
int iDialog,
int uMsg,
long dw1,
long dw2 );

Parameters
iDialog
[in] Handle of the driver dialog box. This is a member of the VfwCaptureDialogs enumerated data type.
uMsg
[in] Message to send to the driver.
dw1
[in] Message data.
dw2
[in] Message data.
Return Values

Return value varies depending on the implementation within each driver.

Remarks

You should never need to use this method. This method can send any private message to the capture driver. Behavior might be undetermined in response to arbitrary messages; use this method at your own risk.

This method calls the Video for Windows videoMessage function to send the driver message.

IAMVfwCaptureDialogs::ShowDialog

IAMVfwCaptureDialogs Interface

Displays the specified dialog box.

HRESULT ShowDialog(
int iDialog,
long hwnd );

Parameters
iDialog
[in] Dialog box to display. This is a member of the VfwCaptureDialogs enumerated data type.
hwnd
[in] Handle of the dialog box's parent window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

You can't use this method when the driver is streaming or displaying another dialog box. While the driver displays the dialog box you can't stream (pause or run) the filter.

IAMVfwCaptureDialogs::ShowDialog calls the Video for Windows® videoDialog function to display the appropriate dialog box.

Asking this method to bring up a VfwCaptureDialog_Format dialog box will return the VFW_E_CANNOT_CONNECT error code if a capture filter is already connected in a graph and the existing graph cannot accept the new format. Capture applications must rebuild the part of the filter graph that is downstream of the capture filter if this error occurs. See the AMCAP sample code for an example of how to do this.


IAMVfwCompressDialogs Interface

The IAMVfwCompressDialogs interface enables an application to display a Video for Windows codec (compressor/decompressor) Configure or About dialog box and to set and retrieve compressor status.

When to Implement

Microsoft's video compression manager (VCM) compressor filter (AVI Compressor) implements this interface. Other filters should not need to implement it.

When to Use

An application should use this interface when it must enable the user to change compression settings in an VCM compressor's Configure dialog box or to view the compressor's About dialog box. Applications also use this interface to set and retrieve compressor status.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVfwCompressDialogs methods | Description
ShowDialog | Displays the specified dialog box.
GetState | Retrieves the current configuration settings for the VCM codec currently being used.
SetState | Sets configuration for the ICM codec.
SendDriverMessage | Sends a driver-specific message.

IAMVfwCompressDialogs::GetState

IAMVfwCompressDialogs Interface

Retrieves the current configuration settings for the VCM codec currently being used.

HRESULT GetState(
LPVOID pState,
int *pcbState

Parameters
pState
[out] State of the VCM codec.
pcbState
[in, out] Size of the state.
Return Values

Return value varies depending on the implementation within each driver.

Remarks

This method calls the COM ICGetState macro.

IAMVfwCompressDialogs::SendDriverMessage

IAMVfwCompressDialogs Interface

Sends a driver-specific message.

HRESULT SendDriverMessage(
int uMsg,
long dw1,
long dw2 );

Parameters
uMsg
[in] Message to send to the driver.
dw1
[in] Message data.
dw2
[in] Message data.
Return Values

Return value varies depending on the implementation within each driver.

Remarks

You should never need to use this method. This method can send any private message to the video compressor (codec). Behavior might be undetermined in response to arbitrary messages; use this method at your own risk.

This method calls the Video for Windows video compression manager (VCM) ICSendMessage function to send the message.

IAMVfwCompressDialogs::SetState

IAMVfwCompressDialogs Interface

Sets configuration for the VCM codec.

HRESULT SetState(
LPVOID pState,
int cbState );

Parameters
pState
[in] State of the VCM codec.
cbState
[in] Size of the state.
Return Values

Return value varies depending on the implementation within each driver.

Remarks

This method calls the COM ICSetState macro, which notifies a video compression driver to set the state of the compressor.

IAMVfwCompressDialogs::ShowDialog

IAMVfwCompressDialogs Interface

Displays the specified dialog box.

HRESULT ShowDialog(
int iDialog,
long hwnd );

Parameters
iDialog
[in] Dialog box to display. This is a member of the VfwCompressDialogs enumerated data type.
hwnd
[in] Handle of the dialog box's parent window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method returns an error when asked to display a dialog box while the driver is streaming or displaying another dialog box. While the driver displays the dialog box you can't stream (pause or run) the filter.

IAMVfwCompressDialogs::ShowDialog calls the Video for Windows video compression manager (VCM) functions ICConfigure, ICAbout, ICQueryConfigure, and ICQueryAbout to display the appropriate dialog box or determine if one exists.

The VfwCompressDialog_QueryConfig and VfwCompressDialog_QueryAbout members of the VfwCompressDialogs enumerated data type tell you whether or not the configure dialog or about dialog is available. If passed one of these flags, the filter will return S_OK if the dialog exists, and S_FALSE if it does not. If a dialog is available, you should then call ShowDialog again with the value VfwCompressDialog_Config or VfwCompressDialog_About to bring up the dialog.


IAMVideoCompression Interface

The IAMVideoCompression pin interface enables you to control compression parameters that aren't part of the media type.

The put_PFramesPerKeyFrame and get_PFramesPerKeyFrame methods refer to predicted (P) frames and bidirectional (B) frames, which are MPEG concepts and not generally applicable to simpler types of compressors.

When to Implement

Implement this interface on the output pin of a video capture or video compressor filter that provides compressed video data.

When to Use

An application can use this interface to control how video is compressed, including characteristics such as the number of key frames and frame quality. Use it to retrieve a textual description of the compressor and other available information, including the compressor's capabilities.

If you are using a WDM video capture or compression filter, you can only query for this interface if the capture filter is connected to another filter in the graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVideoCompression methods | Description
put_KeyFrameRate | Sets the key frame rate.
get_KeyFrameRate | Retrieves the key frame rate.
put_PFramesPerKeyFrame | Sets the predicted (P) frame frequency.
get_PFramesPerKeyFrame | Retrieves the P frame frequency.
put_Quality | Sets the quality of the video image compression.
get_Quality | Retrieves the current image quality setting.
put_WindowSize | Sets the number of frames over which the compressor must maintain an average data rate.
get_WindowSize | Retrieves the number of frames over which the compressor must maintain an average data rate.
GetInfo | Retrieves compressor information.
OverrideKeyFrame | Forces a particular frame to be a key frame.
OverrideFrameSize | Overrides a particular frame's data rate.

IAMVideoCompression::GetInfo

IAMVideoCompression Interface

Retrieves compressor information.

HRESULT GetInfo(
WCHAR * pszVersion,
int *pcbVersion,
LPWSTR pszDescription,
int *pcbDescription,
long *pDefaultKeyFrameRate,
long *pDefaultPFramesPerKey,
double *pDefaultQuality,
long *pCapabilities
) PURE;

Parameters
pszVersion
[out] Pointer to a version string, such as "Version 2.1.0".
pcbVersion
[in,out] Size needed for a version string. Pointer to the number of bytes in the Unicode string, not the number of characters, so it must be twice the number of characters the string can hold. Call with this set to NULL to retrieve the current size.
pszDescription
[out] Pointer to a description string, such as "Awesome Video Compressor".
pcbDescription
[in,out] Size needed for a description string. Pointer to the number of bytes in the Unicode string, not the number of characters, so it must be twice the number of characters the string can hold. Call with this set to NULL to retrieve the current size.
pDefaultKeyFrameRate
[out] Pointer to receive the default key frame rate.
pDefaultPFramesPerKey
[out] Pointer to receive the default predicted (P) frames per key frame.
pDefaultQuality
[out] Pointer to receive the default quality.
pCapabilities
[out] Pointer to receive the compression capabilities, which are a combination of the CompressionCaps data type flags.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoCompression::get_KeyFrameRate

IAMVideoCompression Interface

Retrieves the current key frame rate.

get_KeyFrameRate(
long * pKeyFrameRate
) PURE;

Parameters
pKeyFrameRate
[out] Compressor's current key frame rate. A negative value means it is using the default frame rate for the video compressor. A zero value means only the first frame is a key frame.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanKeyFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

See Also

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_PFramesPerKeyFrame

IAMVideoCompression Interface

Retrieves the predicted (P) frame interval.

HRESULT get_PFramesPerKeyFrame(
long * pPFramesPerKeyFrame
) PURE;

Parameters
pPFramesPerKeyFrame
[out] Pointer to receive the number of P frames per key frame. A negative value means the compressor will use its default value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanBFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

As an example of the relationship between the types of frames, suppose a key frame occurs once in every 10 frames, and there are 3 P frames per key frame. The P frames will be spaced evenly between the key frames. The other 6 frames, which occur between the key frames and the P frames, will be bidirectional (B) frames.

See Also

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_Quality

IAMVideoCompression Interface

Retrieves the current image quality setting.

HRESULT get_Quality(
double * pQuality
) PURE;

Parameters
pQuality
[out] Current quality setting.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The quality is a value between 0 and 1. One indicates the highest (best) quality and 0 indicates the lowest (worst) quality. A negative number means it is using the compressor default. The compressor interprets this number; this interpretation varies from compressor to compressor. When the compressor is not compressing to a specific data rate, the value will roughly determine the image size or quality.

To determine if the compressor supports this method, check for the CompressionCaps_CanQuality flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

If you are compressing to a fixed data rate, a high quality value means use all of the data rate, and a low quality value means you can use much lower than the data rate.

IAMVideoCompression::get_WindowSize

IAMVideoCompression Interface

Retrieves the number of frames over which the compressor must maintain an average data rate.

HRESULT get_WindowSize(
DWORDLONG * pWindowSize
);

Parameters
pWindowSize
[out] Pointer to a DWORDLONG value that will receive the window size.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IAMVideoCompression::put_WindowSize

IAMVideoCompression::OverrideFrameSize

IAMVideoCompression Interface

Overrides a frame's data rate.

HRESULT OverrideFrameSize(
long FrameNumber,
long Size
) PURE;

Parameters
FrameNumber
[in] Frame number for which to change the size.
Size
[in] Desired size, in bytes, for the specified frame.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor might support this method, check for the CompressionCaps_CanCrunch flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method. The flag might also be set to indicate that the dwBitRate value can be set in the AM_MEDIA_TYPE's VIDEOINFOHEADER structure.

The frame number refers to which frame goes out of the filter after it is streaming. For example, frame 0 means the first frame this pin delivers. Frame 11 means the twelfth frame it delivers. Be sure to call this method before the filter delivers the frame for which you want to provide a different size.

Overriding the frame size (or "crunching" the frame) instructs the filter to make the frame size this many bytes or less instead of the originally planned size.

IAMVideoCompression::OverrideKeyFrame

IAMVideoCompression Interface

Forces a frame to be a key frame.

HRESULT OverrideKeyFrame(
long FrameNumber
) PURE;

Parameters
FrameNumber
[in] Number of the frame to be made a key frame when the graph runs, even if it wouldn't usually be a key frame.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

Once a compressor creates a key frame, it might reset its count to determine when the next key frame should occur. For example, assume a key frame typically occurs once every 10 frames. If you mark frame 5 as a key frame using OverrideKeyFrame, the compressor might wait 10 more frames until creating the next key frame.

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression Interface

Sets the key frame rate.

HRESULT put_KeyFrameRate(
long KeyFrameRate
) PURE;

Parameters
KeyFrameRate
[in] Desired key frame rate. A negative value means use the default frame rate for the video compressor. A zero value means that only the first frame is a key frame.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanKeyFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

IAMVideoCompression::put_PFramesPerKeyFrame

IAMVideoCompression Interface

Sets predicted (P) frame interval.

HRESULT put_PFramesPerKeyFrame(
long PFramesPerKeyFrame
) PURE;

Parameters
PFramesPerKeyFrame
[in] Desired P frame interval. A negative value means use the default frame rate for the video compressor.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The Video for Windows capture filter (VFW Video Capture) and the AVI compression filter (AVI Compressor) do not currently support this interface and return E_NOTIMPL.

Remarks

To determine if the compressor supports this method, check for the CompressionCaps_CanBFrame flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

As an example of the relationship between the types of frames, suppose a key frame occurs once in every 10 frames, and there are 3 P frames per key frame. The P frames will be spaced evenly between the key frames. The other 6 frames, which occur between the key frames and the P frames, will be bidirectional (B) frames.

IAMVideoCompression::put_Quality

IAMVideoCompression Interface

Sets the quality of the video image.

HRESULT put_Quality(
double Quality
) PURE;

Parameters
Quality
[in] Desired quality.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The quality is a value between 0 and 1, inclusive. One indicates the highest (best) quality and 0 indicates the lowest (worst) quality. A negative number means use the compressor default. The compressor (codec) interprets this number; interpretation varies from codec to codec. When the compressor is not compressing to a specific data rate, the value will roughly determine the image size or quality.

To determine if the compressor supports this method, check the CompressionCaps_CanQuality flag returned in the pCapabilities parameter of the IAMVideoCompression::GetInfo method.

If you are compressing to a fixed data rate, a high quality value means use all of the data rate, and a low quality value means you can use much lower than the data rate.

IAMVideoCompression::put_WindowSize

IAMVideoCompression Interface

Sets the number of frames over which the compressor must maintain an average data rate.

HRESULT put_WindowSize(
DWORDLONG WindowSize
);

Parameters
WindowSize
[in] Window size, or number of frames, whose average size cannot exceed the data rate that the compressor has been asked to provide.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For a window of size n, the average frame size of any consecutive n frames will not exceed the stream's specified data rate, although individual frames can be larger or smaller. For example, if you have set a data rate of 100 kilobytes (KB) per second on a 10 frames per second (fps) movie, that will usually mean each frame must be less than or equal to 10 KB. However, by setting a window size of n, you are specifying that as long as the average length of those n frames is less than or equal to 10 KB, it doesn't matter how large the individual frames are. For example, some could be smaller and some could actually be larger than 10 KB, as long as the average is less than or equal to 10 KB.

See Also

IAMVideoCompression::get_WindowSize

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMVideoControl Interface

The IAMVideoControl interface allows you to flip a picture horizontally and/or vertically, to set up a stream so it can capture from an external trigger, for example, a push button on a camera, to simulate an external trigger in software, and to list the available frame rates.

This interface uses the video control flags in the VideoControlFlags enumeration.

When to Implement

Implement this interface when your filter needs to control the video image or to list the frame rates.

When to Use

Use this interface when your application runs on hardware which is capable of flipping and external triggering.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVideoControl methods | Description
GetCaps | Retrieves the capabilities of the underlying hardware.
SetMode | Sets the video control mode of operation.
GetMode | Retrieves the video control mode of operation.
GetCurrentActualFrameRate | Retrieves the actual frame rate at which the device is streaming. For some devices, such as USB (Universal Serial Bus) and IEEE 1394 cameras, where the maximum framerate may be limited due to bandwidth availability. This is only available during video streaming.
GetMaxAvailableFrameRate | Retrieves the maximum frame rate currently available based on bus bandwidth usage, for connections such as USB and 1394 camera devices where the maximum framerate may be limited due to bandwidth availability.
GetFrameRateList | Retrieves a list of available frame rates.

IAMVideoControl::GetCaps

IAMVideoControl Interface

Retrieves the capabilities of the underlying hardware.

HRESULT GetCaps (
IPin *pPin,
long *pCapsFlags
);

Parameters
pPin
[in] Pointer to the pin to query capabilities from.
pCapsFlags
[out] Pointer to a value representing a combination of the flags from the VideoControlFlags enumeration.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible capabilities include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers.

IAMVideoControl::GetCurrentActualFrameRate

IAMVideoControl Interface

Retrieves the actual frame rate, expressed as a frame duration in 100 nS units. USB (Universal Serial Bus) and IEEE 1394 cameras may provide lower frame rates than requested, due to bandwidth availability. This is only available during video streaming.

HRESULT GetCurrentActualFrameRate (
IPin *pPin,
LONGLONG *ActualFrameRate
);

Parameters
pPin
[in] Pointer to the pin to retrieve the frame rate from.
ActualFrameRate
[out] Pointer to the frame rate in frame duration in 100 nS units.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoControl::GetFrameRateList

IAMVideoControl Interface

Retrieves a list of available frame rates.

HRESULT GetFrameRateList (
IPin *pPin,
long iIndex,
SIZE Dimensions,
long *ListSize,
LONGLONG ** FrameRates
);

Parameters
pPin
[in] Pointer to the pin to query list of frame rates from.
iIndex
[in] The index of the format to query for frame rates. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps. The value must range between 0 and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities) -1.
Dimensions
[in] The frame's image size (width and height) in pixels.
ListSize
[out] Pointer to the number of elements in the list of frame rates.
FrameRates
[out] An array of frame rates in 100 nSec units. Can be NULL if only ListSize is wanted.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

It is the responsibility of the caller to free the memory through a call to CoTaskMemFree.

IAMVideoControl::GetMaxAvailableFrameRate

IAMVideoControl Interface

Retrieves the maximum frame rate currently available, based on bus bandwidth usage for connections, such as USB (Universal Serial Bus) and IEEE 1394, where the maximum framerate may be limited due to bandwidth availability.

HRESULT GetMaxAvailableFrameRate(
IPin *pPin,
long iIndex,
SIZE Dimensions,
LONGLONG * MaxAvailableFrameRate
);

Parameters
pPin
[in] Pointer to the pin to maximum frame rate from.
iIndex
[in] The index of the format to query for maximum frame rate. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps. The value must range between 0 and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities) -1.
Dimensions
[in] The frame's image size (width and height) in pixels.
MaxAvailableFrameRate
[out] Pointer to the maximum available frame rate in frame duration in 100 nS units.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoControl::GetMode

IAMVideoControl Interface

Retrieves the video control mode of operation.

HRESULT GetMode (
IPin *pPin,
long *Mode
);

Parameters
pPin
[in] Pointer to the pin to retrieve the video control mode from.
Mode
[out] Pointer to a value representing a combination of the flags from the VideoControlFlags enumeration, which specify the video control mode.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible modes of operation include one or more of the following: flip the picture horizontally, flip the picture vertically, enable external triggers, and simulate external triggers.

IAMVideoControl::SetMode

IAMVideoControl Interface

Sets the video control mode of operation.

HRESULT SetMode (
IPin *pPin,
long *Mode
);

Parameters
pPin
[in] Pointer to the pin to set the video control mode on.
Mode
[in] Pointer to a value specifying a combination of the flags from the VideoControlFlags enumeration to set the video control mode.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible modes of operation include one or more of the following: flip the picture horizontally, flip the picture vertically, enable external triggers, and simulate external triggers.


IAMVideoCutListElement Interface

IAMVideoCutListElement provides support for a cutlist element from an AVI video file stream.

See About Cutlists and Using Cutlists for more information.

When to Implement

Usually, you don't need to implement this interface because DirectShow provides the CLSID_VideoFileClip object that implements it for you. Implement this interface in your application when you need to change the default behavior of this interface to include support for interlaced video.

When to Use

Use this interface in your filter when you specify a video-based media clip. Call QueryInterface on the IAMCutListElement interface to determine if the element is a video type element.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVideoCutListElement methods | Description
IsSingleFrame | Determines if the element is a single frame with repeating fields.
GetStreamIndex | Retrieves the index to the specified stream in the AVI file.

IAMVideoCutListElement::GetStreamIndex

IAMVideoCutListElement Interface

Retrieves the index to the specified stream in the AVI file.

HRESULT GetStreamIndex(
DWORD *piStream
);

Parameters
piStream
[out] Pointer to the stream number to open.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

The stream number must always be zero. The only supported video stream in an AVI file is the first video stream.

IAMVideoCutListElement::IsSingleFrame

IAMVideoCutListElement Interface

Determines if the element is a single frame with repeating fields.

HRESULT IsSingleFrame(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | Null pointer argument.
S_FALSE | No, element is not a single frame with repeating fields.
S_OK | Yes, element is a single frame with repeating fields.

Remarks

This method must always return S_FALSE because repeating fields are not supported.


IAMVideoProcAmp Interface

The IAMVideoProcAmp interface contains methods for controlling video quality such as brightness, contrast, hue, saturation, gamma, and sharpness. It defines a uniform range for these settings regardless of whether the adjustment is made in the analog or digital domain.

For analog video, this interface will typically be located on the same processing element as the IAMAnalogVideoDecoder interface.

When to Implement

Implement this interface when your filter needs to control video quality.

When to Use

Use this interface when your application needs to adjust video quality.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMVideoProcAmp methods | Description
GetRange | Retrieves minimum, maximum, and default values for setting properties.
Set | Sets video quality for a specified property.
Get | Retrieves video quality for a specified property.

IAMVideoProcAmp::Get

IAMVideoProcAmp Interface

Retrieves video quality for a specified property.

HRESULT Get(
long Property,
long * lValue,
long * Flags );

Parameters
Property
[in] Specific property to retrieve the setting of. Specify a member of the VideoProcAmpProperty enumerated type.
lValue
[out] Current value of the property.
Flags
[out] Pointer to a member of the VideoProcAmpFlags enumerated type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

IAMVideoProcAmp::GetRange

IAMVideoProcAmp Interface

Retrieves minimum, maximum, and default values for setting properties.

HRESULT GetRange(
long Property,
long * pMin,
long * pMax,
long * pSteppingDelta,
long * pDefault,
long * pCapsFlags );

Parameters
Property
[in] Specific property to determine the range of. Specify a member of the VideoProcAmpProperty enumerated type.
pMin
[out] Minimum setting range.
pMax
[out] Maximum setting range.
pSteppingDelta
[out] Step size.
pDefault
[out] Default value.
pCapsFlags
[out] Pointer to a member of the VideoProcAmpFlags enumerated type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

IAMVideoProcAmp::Set

IAMVideoProcAmp Interface

Sets video quality for a specified property.

HRESULT Set(
long Property,
long lValue,
long Flags );

Parameters
Property
[in] Specific property to set. Specify a member of the VideoProcAmpProperty enumerated type.
lValue
[in] Value indicating the setting of the property.
Flags
[in] Member of the VideoProcAmpFlags enumerated type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.


IAsyncReader Interface

The IAsyncReader interface allows multiple overlapped reads from different positions in the media stream. This interface is supported by source filters.

Note that during connection an output pin supporting the IAsyncReader should check whether its QueryInterface method is called asking for the IAsyncReader interface. If it is not, then the output pin should fail the connect unless it establishes some other transport to use during the connection.

When to Implement

Implement this interface on a pin if your filter reads data of media type MEDIATYPE_Stream from some source.

When to Use

A parser, such as an Apple® QuickTime® parser filter, can use this interface to read from a filter that reads from a file, the network, or memory.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAsyncReader methods | Description
RequestAllocator | Retrieves the actual allocator to be used.
Request | Queues a request for data.
WaitForNext | Blocks until the next sample is completed or the time-out occurs.
SyncReadAligned | Performs an aligned synchronized read.
SyncRead | Performs a synchronized read.
Length | Retrieves the total length of the stream, and the currently available length.
BeginFlush | Causes all outstanding reads to return.
EndFlush | Ends the flushing operation.

IAsyncReader::BeginFlush

IAsyncReader Interface

Starts the flushing operation.

HRESULT BeginFlush(void);

Return Values

Returns S_OK if successful, S_FALSE otherwise.

Remarks

Causes all outstanding reads to return, possibly with a failure code (VFW_E_TIMEOUT), indicating that the outstanding reads were canceled. Between IAsyncReader::BeginFlush and IAsyncReader::EndFlush calls, IAsyncReader::Request calls will fail and IAsyncReader::WaitForNext calls will always complete immediately.

IAsyncReader::EndFlush

IAsyncReader Interface

Completes the flushing operation.

HRESULT EndFlush(void);

Return Values

Returns S_OK if successful, S_FALSE otherwise.

Remarks

Between IAsyncReader::BeginFlush and IAsyncReader::EndFlush calls, IAsyncReader::Request calls will fail and IAsyncReader::WaitForNext calls will always complete immediately. This method is called so the source thread can wait in the IAsyncReader::WaitForNext method again.

IAsyncReader::Length

IAsyncReader Interface

Retrieves the stream's total length, and the currently available length.

HRESULT Length(
LONGLONG* pTotal,
LONGLONG* pAvailable
);

Parameters
pTotal
Total allocated length.
pAvailable
Available length.
Return Values

Returns S_OK if successful, E_UNEXPECTED if the file has not been opened.

Remarks

Read operations beyond the available length but within the total length will normally succeed, but they might block for a long period of time.

IAsyncReader::Request

IAsyncReader Interface

Queues a request for data.

HRESULT Request(
IMediaSample* pSample,
DWORD dwUser
);

Parameters
pSample
Media sample being requested.
dwUser
[in] User context.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
VFW_E_BADALIGN | An invalid alignment was specified.
VFW_E_MEDIA_TIME_NOT_SET | Time has not been set.
HRESULT_FROM_WIN32 | Request for data past end of file.
NOERROR | No error.
S_OK | Success.

Remarks

Media sample start and stop times contain the requested absolute byte position (start-inclusive and stop-exclusive). This method might fail if the sample is not obtained from an agreed allocator or if the start or stop position does not match the agreed alignment. The samples allocated from the source pin's allocator might fail IMediaSample::GetPointer until after returning from IAsyncReader::WaitForNext.

The stop position must be aligned, which means it might exceed duration. On completion, the stop position will be corrected to the unaligned actual data.

The dwUser parameter is used by the caller to identify the sample that returned from the IAsyncReader::WaitForNext method. It has no meaning within IAsyncReader but could be used to track individual sample information.

IAsyncReader::RequestAllocator

IAsyncReader Interface

Retrieves the actual allocator to be used.

HRESULT RequestAllocator(
IMemAllocator* pPreferred,
ALLOCATOR_PROPERTIES* pProps,
IMemAllocator ** ppActual
);

Parameters
pPreferred
[in] Preferred allocator.
pProps
[in] Preferred allocator properties (size, count, and alignment).
ppActual
[out] Actual allocator used.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_FAIL | Failure to initialize an allocator.
VFW_E_BADALIGN | An invalid alignment was specified.
S_OK | Allocator was returned.

Remarks

The preferred allocator and preferred allocator properties must be passed in. This method returns the actual allocator to be used.

IMemAllocator::GetProperties should be called on the returned allocator to learn the alignment and prefix chosen. This allocator will not be committed and decommitted by the asynchronous reader, only by the consumer. This method must be called before calling IAsyncReader::Request.

IAsyncReader::SyncRead

IAsyncReader Interface

Performs a synchronous read.

HRESULT SyncRead(
LONGLONG llPosition,
LONG lLength,
BYTE* pBuffer
);

Parameters
llPosition
[in] Absolute file position.
lLength
[in] Number of bytes required.
pBuffer
[out] Where the data is written.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
VFW_E_BADALIGN | An invalid alignment was specified.
HRESULT_FROM_WIN32 | Win32 error.
S_FALSE | Size changed (probably due to end of file).
S_OK | Success.

Remarks

The SyncRead method works in a stopped state as well as in a running state. The read is not necessarily aligned. This method fails if the read is beyond the actual total length.

IAsyncReader::SyncReadAligned

IAsyncReader Interface

Performs a synchronous read of the data.

HRESULT SyncReadAligned(
IMediaSample* pSample
);

Parameters
pSample
Sample to read.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
VFW_E_BADALIGN | An invalid alignment was specified.
HRESULT_FROM_WIN32 | Win32 error.
S_FALSE | Size changed (probably due to end of file).
S_OK | Success.

Remarks

The sample passed in must have been acquired from the agreed allocator. The start and stop positions must be aligned equivalent to an IAsyncReader::Request/IAsyncReader::WaitForNext pair, but may avoid the need for a thread on the source filter.

IAsyncReader::WaitForNext

IAsyncReader Interface

Blocks until the next read requested through IAsyncReader::Request completes or the time-out occurs.

HRESULT WaitForNext(
DWORD dwTimeout,
IMediaSample** ppSample,
DWORD * pdwUser
);

Parameters
dwTimeout
[in] Time-out in milliseconds; can be zero or INFINITE.
ppSample
[out] Completed sample.
pdwUser
User context.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
VFW_E_TIMEOUT | A time-out has expired.
VFW_E_WRONG_STATE | The operation could not be performed because the filter is in the wrong state.
E_FAIL | Failure.
S_OK | Success.

Remarks

Samples may not be returned in order. If there is a read error of any sort, a notification will already have been sent by the source filter, and HRESULT will be an error. If ppSample is not null, a request has been completed with the result code returned.

The pdwUser parameter returns the caller's context DWORD corresponding to the sample returned.


IBaseFilter Interface

The IBaseFilter interface abstracts an object that has typed input and output connections and can be aggregated dynamically. All DirectShow™ filters expose this interface.

Since the IBaseFilter interface derives from the IMediaFilter interface, it inherits IPersist.

When to Implement

Implement this interface on every DirectShow filter. It is recommended that you use the CBaseFilter class library to implement this interface.

When to Use

The filter graph manager is the primary user of this interface. Applications or other filters can use IBaseFilter methods directly to enumerate or retrieve pins or to get vendor information, but should not use any methods derived from IMediaFilter to control media streaming (use the IMediaControl methods on the filter graph manager instead).

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaFilter methods | Description
Stop | Informs the filter to transition to the new (stopped) state.
Pause | Informs the filter to transition to the new (paused) state.
Run | Informs the filter to transition to the new (running) state.
GetState | Determines the state of the filter.
SetSyncSource | Identifies the reference clock to which the filter should synchronize activity.
GetSyncSource | Retrieves the current reference clock (or NULL if there is no clock). Passes a time value to synchronize independent streams.
IBaseFilter methods | Description
EnumPins | Enumerates the specified pins available on this filter.
FindPin | Retrieves a pointer to the pin with the specified identifier.
QueryFilterInfo | Retrieves information about the specified filter.
JoinFilterGraph | Notifies a filter that it has joined a filter graph.
QueryVendorInfo | Retrieves optional information supplied by a vendor for the specified filter.

IBaseFilter::EnumPins

IBaseFilter Interface

Enumerates all the pins available on this filter.

HRESULT EnumPins(
IEnumPins ** ppEnum
);

Parameters
ppEnum
[out] Pointer to the IEnumPins interface to retrieve.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IBaseFilter::FindPin

IBaseFilter Interface

Retrieves the pin with the specified identifier.

HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);

Parameters
Id
[in] Identifier of the pin.
ppPin
[out] Pointer to the IPin interface for this pin after the filter has been restored. The returned IPin pointer has been reference counted. The caller should use the Release method on the pointer when finished with it.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method, along with the IPin::QueryId method, is used to implement persistent filter graphs. A filter must be able to translate the IPin interface pointers to its pins into identifiers that can be saved along with the configuration of the filter graph. It does this by using the IPin::QueryId method. It must then be able to convert those identifiers back into IPin interface pointers when the filter and its connections are restored as part of a persistent filter graph. This is accomplished by using the IBaseFilter::FindPin method.

The ppPin parameter is set to NULL if the identifier cannot be matched.

IBaseFilter::JoinFilterGraph

IBaseFilter Interface

Notifies a filter that it has joined a filter graph.

HRESULT JoinFilterGraph(
IFilterGraph * pGraph,
LPCWSTR pName
);

Parameters
pGraph
[in] Pointer to the filter graph to join.
pName
[in, string] Name of the filter being added.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The filter should store this interface for later use because it might need to notify the interface about events. The filter should not add a reference count to this interface. Doing so causes circular references and prevents the graph or the filter from ever being correctly released. The filter graph manager does hold a reference on the filter. The filter does not need to hold a reference to ensure that the interface does not disappear; it is notified of any such disappearance by a further call to IBaseFilter::JoinFilterGraph, with a null value for the pGraph parameter to indicate that the filter is no longer part of the graph.

IBaseFilter::QueryFilterInfo

IBaseFilter Interface

Returns information about the filter.

HRESULT QueryFilterInfo(
FILTER_INFO * pInfo
);

Parameters
pInfo
[out] Pointer to a FILTER_INFO structure.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The FILTER_INFO structure is defined as follows:

typedef struct _FilterInfo  {
    [string] WCHAR achName[MAX_FILTER_NAME]; // allowed to be null
    IFilterGraph * pGraph;                   // null if not part of graph
    } FILTER_INFO ;

Note that on return, if the pGraph member of the FILTER_INFO structure is non-NULL, it will have an outstanding reference count and should be released when the interface is no longer needed.

IBaseFilter::QueryVendorInfo

IBaseFilter Interface

Returns a vendor information string.

HRESULT QueryVendorInfo(
LPWSTR * pVendorInfo
);

Parameters
pVendorInfo
[out] Pointer to a string containing vendor information.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is optional and can return E_NOTIMPL. If implemented, memory returned should be freed using the Microsoft® Win32® CoTaskMemFree function when the application is done using it.


IBasicAudio Interface

IBasicAudio is an interface that supports the filter graph's audio component. It allows access to volume and balance functionality.

The Volume property is a value between –10,000 and 0 representing a set of logarithmic steps. This follows the DirectSound model. Not all devices support 10,000 distinguishable steps.

The Balance property is a value between –10,000 and 10,000. A value of –10,000 indicates that the right speaker has been disabled and only the left speaker is receiving an audio signal. A value of 0 indicates that both speakers are receiving equivalent audio signals. A value of 10,000 indicates that the left speaker has been disabled and only the right speaker is receiving an audio signal.

When to Implement

The audio renderer filter supplied with Microsoft® DirectShow™ implements this interface. It is also implemented by the filter graph manager (by means of a plug-in distributor) to pass method calls from the application to the audio renderer filter's implementation of the interface.

Implement this interface if you are writing a replacement audio renderer filter or a replacement DirectShow plug-in distributor. You can use the CBasicAudio class, which handles the IDispatch implementation for Automation, to help implement this interface.

When to Use

When the filter graph manager exposes this interface, it is used by applications that need to control the properties of the audio renderer filter. Applications should not use the interface exposed by the audio renderer directly. When the audio renderer filter exposes this interface, it is used by plug-in distributors, such as the DirectShow plug-in distributor, which pass calls from the application.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IBasicAudio methods | Description
put_Volume | Sets the volume (amplitude) of the audio signal.
get_Volume | Retrieves the volume (amplitude) of the audio signal.
put_Balance | Sets the balance for the audio signal.
get_Balance | Retrieves the balance for the audio signal.

IBasicAudio::get_Balance

IBasicAudio Interface

Retrieves the balance for the audio signal.

HRESULT get_Balance(
long * plBalance
);

Parameters
plBalance
[out] Returned value of the Balance property.
Return Values

Returns an HRESULT value.

Remarks

As with the Volume property, units correspond to .01 decibels (multiplied by –1 when plBalance is a positive value). For example, a value of 1000 indicates –10 dB on the right channel and –90 dB on the left channel.

IBasicAudio::get_Volume

IBasicAudio Interface

Retrieves the volume (amplitude) of the audio signal.

HRESULT get_Volume(
long * plVolume
);

Parameters
plVolume
[out] Returned value of the Volume property. Divide by 100 to get equivalent decibel value (for example –10,000 = –100 dB).
Return Values

Returns an HRESULT value.

IBasicAudio::put_Balance

IBasicAudio Interface

Sets the balance of the audio signal.

HRESULT put_Balance(
long lBalance
);

Parameters
lBalance
[in] Value to which to set the Balance property. The allowable input range is –10,000 to 10,000. A value of 0 sets a neutral balance—both left and right speakers will be given the same amplitude audio signal.
Return Values

Returns an HRESULT value. E_INVALIDARG is returned for values outside the allowable input range and E_FAIL is returned if the underlying device returns an error.

Remarks

As with the Volume property, units correspond to .01 decibels (multiplied by –1 when lBalance is a positive value). For example, a value of 1000 indicates –10 dB on the right channel and –90 dB on the left channel.

IBasicAudio::put_Volume

IBasicAudio Interface

Sets the volume (amplitude) of the audio signal.

HRESULT put_Volume(
long lVolume
);

Parameters
lVolume
[in] Value to which to set the Volume property. The allowable input range is –10,000 to 0.
Return Values

Returns an HRESULT value. E_INVALIDARG is returned for values outside the allowable input range and E_FAIL is returned if the underlying device returns an error.

Remarks

Full volume is 0, and –10,000 is silence; the scale is logarithmic. Multiply the desired decibel level by 100 (for example –10,000 = –100 dB).


IBasicVideo Interface

The IBasicVideo interface supports the video properties of a generic video window. Generally, this is a video renderer that draws video into a window on the display.

The IBasicVideo interface supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as the Microsoft® Visual Basic® programming system). However, some operations require several properties to be changed simultaneously; for this reason, methods are provided that allow a number of related properties to be changed.

The IBasicVideo interface methods require only that the video renderer be connected. If it is not connected, all the interface methods return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

When working with video, the application can select a portion of the video to use. This portion is the source rectangle that the IBasicVideo interface controls. IBasicVideo allows the source rectangle to be set and retrieved. All the rectangles that IBasicVideo uses employ top, left, width, and height rather than top, left, right, and bottom, which is favored in Microsoft Win32® programming. When no source rectangle has been set, the properties of the source rectangle return the full, native video size.

When to Implement

The video renderer filter supplied with Microsoft DirectShow™ implements this interface. It is also implemented by the filter graph manager (via a plug-in distributor) to pass method calls from the application to the video renderer filter's implementation of the interface. Implement this interface if you are writing a replacement video renderer filter or a replacement DirectShow plug-in distributor. You can use the CBaseBasicVideo class, which handles the IDispatch implementation for Automation, to help implement this interface.

When to Use

When the filter graph manager exposes this interface, it is used by applications that must control the properties of the video renderer filter.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IBasicVideo methods | Description
get_AvgTimePerFrame | Retrieves the average time between successive frames in 100-nanosecond units.
get_BitRate | Retrieves an approximate bit rate for the video stream.
get_BitErrorRate | Retrieves an approximate bit error rate for the video stream.
get_VideoWidth | Retrieves the current video width.
get_VideoHeight | Retrieves the current video height.
put_SourceLeft | Sets the x-axis coordinate for the source video rectangle.
get_SourceLeft | Retrieves the x-axis coordinate for the source video rectangle.
put_SourceWidth | Sets the width of the source video rectangle.
get_SourceWidth | Retrieves the width of the source video rectangle.
put_SourceTop | Sets the y-axis coordinate for the source video rectangle.
get_SourceTop | Retrieves the y-axis coordinate for the source video rectangle.
put_SourceHeight | Sets the height of the source video rectangle.
get_SourceHeight | Retrieves the height of the source video rectangle.
put_DestinationLeft | Sets the x-axis coordinate for the destination video rectangle.
get_DestinationLeft | Retrieves the x-axis coordinate for the destination video rectangle.
put_DestinationWidth | Sets the width of the destination video rectangle.
get_DestinationWidth | Retrieves the width of the destination video rectangle.
put_DestinationTop | Sets the y-axis coordinate for the destination video rectangle.
get_DestinationTop | Retrieves the y-axis coordinate for the destination video rectangle.
put_DestinationHeight | Sets the height of the destination video rectangle.
get_DestinationHeight | Retrieves the height of the destination video rectangle.
SetSourcePosition | Sets the source video rectangle.
GetSourcePosition | Retrieves the source video rectangle.
SetDefaultSourcePosition | Informs the renderer to use the default source rectangle.
SetDestinationPosition | Sets the destination rectangle for the window.
GetDestinationPosition | Retrieves the destination video rectangle for the window.
SetDefaultDestinationPosition | Sets the default destination position for the window.
GetVideoSize | Retrieves the native video dimensions.
GetVideoPaletteEntries | Retrieves the color palette entries required by the video.
GetCurrentImage | Returns a copy of the current image that is waiting at the renderer.
IsUsingDefaultSource | Determines if the renderer is using the default source rectangle.
IsUsingDefaultDestination | Determines if the renderer is using the default destination rectangle.

IBasicVideo::get_AvgTimePerFrame

IBasicVideo Interface

Retrieves the average time between successive frames in 100-nanosecond units.

HRESULT get_AvgTimePerFrame(
REFTIME *pAvgTimePerFrame
);

Parameters
pAvgTimePerFrame
[out] Time between frames.
Return Values

Returns an HRESULT value.

IBasicVideo::get_BitErrorRate

IBasicVideo Interface

Retrieves a bit error rate for the video stream (one error for approximately this many bits).

HRESULT get_BitErrorRate(
long *pBitErrorRate
);

Parameters
pBitErrorRate
[out] Approximate bit error rate.
Return Values

Returns an HRESULT value.

IBasicVideo::get_BitRate

IBasicVideo Interface

Retrieves an approximate bit rate for the video stream (in bits per second).

HRESULT get_BitRate(
long *pBitRate
);

Parameters
pBitRate
[out] Approximate bit rate.
Return Values

Returns an HRESULT value.

IBasicVideo::GetCurrentImage

IBasicVideo Interface

Retrieves the current image waiting at the renderer.

HRESULT GetCurrentImage(
long *pBufferSize,
long *pDIBImage
);

Parameters
pBufferSize
[in, out] Size of the buffer the caller is passing in.
pDIBImage
[out] Pointer to a buffer where the complete image will be stored in device-independent bitmap (DIB) format. The buffer must be cast to a long pointer for the function.
Return Values

Returns an HRESULT value.

Remarks

An application can use this method to get a copy of the current image the video renderer holds when paused. The size of the buffer required to hold the image can be obtained by calling the method with a null image pointer. In this case, the buffer size is filled out with the byte count required. The buffer size pointer must always be valid. If the application calls this method and the buffer size is too small to hold the complete image, the renderer returns E_OUTOFMEMORY.

Pause the video renderer before calling this method. Calling this method in any other state than paused returns VFW_E_NOT_PAUSED. Depending on what data the source filter has available, the video renderer is not guaranteed to service this request. If no image is available, it returns E_FAIL.

When called successfully, the output image pointer is filled with the entire DIB image, including the Microsoft Win32 BITMAPINFOHEADER structure, any required palette, and bit masks as defined in the Win32 BITMAPINFO structure. The format of the image that is returned depends on the type provided by the source filter, and cannot be explicitly defined in advance. Typically, the image will be a 24-bit, 16-bit, or 8-bit palettized image.

IBasicVideo::get_DestinationHeight

IBasicVideo Interface

Retrieves the height of the destination rectangle.

HRESULT get_DestinationHeight(
long *pDestinationHeight
);

Parameters
pDestinationHeight
[out] Current height.
Return Values

Returns an HRESULT value.

IBasicVideo::get_DestinationLeft

IBasicVideo Interface

Retrieves the destination x-axis origin coordinate.

HRESULT get_DestinationLeft(
long *pDestinationLeft
);

Parameters
pDestinationLeft
[out] Current x-axis origin.
Return Values

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle width.

IBasicVideo::GetDestinationPosition

IBasicVideo Interface

Retrieves the position of the destination rectangle in window coordinates.

HRESULT GetDestinationPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
[out] The x-axis origin of the destination window.
pTop
[out] The y-axis origin of the destination window.
pWidth
[out] Width of the destination window.
pHeight
[out] Height of the destination window.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::get_DestinationLeft, IBasicVideo::get_DestinationTop, IBasicVideo::get_DestinationWidth, and IBasicVideo::get_DestinationHeight methods.

IBasicVideo::get_DestinationTop

IBasicVideo Interface

Retrieves the destination y-axis origin coordinate.

HRESULT get_DestinationTop(
long *pDestinationTop
);

Parameters
pDestinationTop
[out] Current y-axis origin.
Return Values

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle height.

IBasicVideo::get_DestinationWidth

IBasicVideo Interface

Retrieves the width of the destination rectangle.

HRESULT get_DestinationWidth(
long *pDestinationWidth
);

Parameters
pDestinationWidth
[out] Current width.
Return Values

Returns an HRESULT value.

IBasicVideo::get_SourceHeight

IBasicVideo Interface

Retrieves the height of the source rectangle.

HRESULT get_SourceHeight(
long *pSourceHeight
);

Parameters
pSourceHeight
[out] Current rectangle height.
Return Values

Returns an HRESULT value.

IBasicVideo::get_SourceLeft

IBasicVideo Interface

Retrieves the source rectangle x-axis coordinate.

HRESULT get_SourceLeft(
long *pSourceLeft
);

Parameters
pSourceLeft
[out] The x-axis origin of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

This method has no effect on the source rectangle width.

IBasicVideo::GetSourcePosition

IBasicVideo Interface

Retrieves the source position rectangle, clipped to the available video.

HRESULT GetSourcePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
[out] The x-axis origin of the source window.
pTop
[out] The y-axis origin of the source window.
pWidth
[out] Width of the source window.
pHeight
[out] Height of the source window.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the
IBasicVideo::get_SourceLeft, IBasicVideo::get_SourceTop,
IBasicVideo::get_SourceWidth, and
IBasicVideo::get_SourceHeight methods.

IBasicVideo::get_SourceTop

IBasicVideo Interface

Retrieves the source rectangle y-axis origin coordinate.

HRESULT get_SourceTop(
long * pSourceTop
);

Parameters
pSourceTop
[out] New top coordinate.
Return Values

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle height.

IBasicVideo::get_SourceWidth

IBasicVideo Interface

Retrieves the source rectangle width.

HRESULT get_SourceWidth(
long *pSourceWidth
);

Parameters
pSourceWidth
[out] Current width.
Return Values

Returns an HRESULT value.

Remarks

This method has no effect on the source rectangle x-axis coordinate.

IBasicVideo::get_VideoHeight

IBasicVideo Interface

Retrieves the current video height.

HRESULT get_VideoHeight(
long *pVideoHeight
);

Parameters
pVideoHeight
[out] Native height of the video.
Return Values

Returns an HRESULT value.

Remarks

This method returns the actual height of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native vertical dimension. Applications can use this method to negotiate size requirements with in-place container documents.

IBasicVideo::GetVideoPaletteEntries

IBasicVideo Interface

Retrieves the palette colors for the video.

HRESULT GetVideoPaletteEntries(
long StartIndex,
long Entries,
long *pRetrieved,
long *pPalette
);

Parameters
StartIndex
[in] Start index for the palette.
Entries
[in] Number of palette entries required.
pRetrieved
[out] Number of entries actually returned.
pPalette
[out] Pointer to an array of Microsoft Win32 PALETTEENTRY structures.
Return Values

Returns an HRESULT value.

Remarks

An application can query the colors required by the video with this method. An application can pass in a null pPalette parameter, and the pRetrieved parameter is filled in with the number of colors in use. The pPalette parameter is a pointer to an array of PALETTEENTRY structures. With the StartIndex and Entries parameters, an application can request any contiguous section of the palette in a single method. The interface was modeled on the Win32 GetSystemPaletteEntries function.

IBasicVideo::GetVideoSize

IBasicVideo Interface

Retrieves the native video dimensions.

HRESULT GetVideoSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
[out] Width of the video window.
pHeight
[out] Height of the video window.
Return Values

Returns an HRESULT value.

Remarks

This method retrieves the native video width and height, disregarding any source rectangle that might have been set. ActiveX™ Controls or other applications can use this information to negotiate space in compound documents.

IBasicVideo::get_VideoWidth

IBasicVideo Interface

Retrieves the current video width.

HRESULT get_VideoWidth(
long *pVideoWidth
);

Parameters
pVideoWidth
[out] Native width of the video.
Return Values

Returns an HRESULT value.

Remarks

This method returns the actual width of the video supplied to the renderer. It does not address any set source rectangle, but simply returns the native horizontal dimension. Applications can use it to negotiate size requirements with in-place ActiveX documents.

IBasicVideo::IsUsingDefaultDestination

IBasicVideo Interface

Determines if the renderer is using the default destination rectangle.

HRESULT IsUsingDefaultDestination( );

Return Values

Returns an HRESULT value. Returns S_OK if using the default destination; otherwise, returns S_FALSE.

Remarks

The IBasicVideo::SetDefaultDestinationPosition method can be used to tell the filter to use the default settings for the destination rectangle. This method returns whether or not they are in use.

IBasicVideo::IsUsingDefaultSource

IBasicVideo Interface

Determines if the renderer is using the default source rectangle.

HRESULT IsUsingDefaultSource( );

Return Values

Returns an HRESULT value. Returns S_OK if using the default source; otherwise, returns S_FALSE.

Remarks

You can use the IBasicVideo::SetDefaultSourcePosition method to inform the filter to use the default settings for the source rectangle. This method returns whether or not the settings are in use.

IBasicVideo::put_DestinationHeight

IBasicVideo Interface

Sets the height of the destination rectangle.

HRESULT put_DestinationHeight(
long DestinationHeight
);

Parameters
DestinationHeight
[in] New height.
Return Values

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle y-axis origin.

IBasicVideo::put_DestinationLeft

IBasicVideo Interface

Sets the destination x-axis origin coordinate.

HRESULT put_DestinationLeft(
long DestinationLeft
);

Parameters
DestinationLeft
[in] New x-axis origin.
Return Values

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle width.

IBasicVideo::put_DestinationTop

IBasicVideo Interface

Sets the destination y-axis origin coordinate.

HRESULT put_DestinationTop(
long DestinationTop
);

Parameters
DestinationTop
[in] New y-axis origin.
Return Values

Returns an HRESULT value.

IBasicVideo::put_DestinationWidth

IBasicVideo Interface

Sets the width of the destination rectangle.

HRESULT put_DestinationWidth(
long DestinationWidth
);

Parameters
DestinationWidth
[in] New width.
Return Values

Returns an HRESULT value.

Remarks

Setting this coordinate does not affect the destination rectangle x-axis origin.

IBasicVideo::put_SourceHeight

IBasicVideo Interface

Sets the height of the source rectangle.

HRESULT put_SourceHeight(
long SourceHeight
);

Parameters
SourceHeight
[in] New rectangle height.
Return Values

Returns an HRESULT value.

Remarks

Setting the height of the source rectangle has no effect on the source y-axis coordinate.

IBasicVideo::put_SourceLeft

IBasicVideo Interface

Sets the source rectangle x-axis coordinate.

HRESULT put_SourceLeft(
long SourceLeft
);

Parameters
SourceLeft
[in] The x-axis origin of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle width.

IBasicVideo::put_SourceTop

IBasicVideo Interface

Sets the source rectangle y-axis origin coordinate.

HRESULT put_SourceTop(
long SourceTop
);

Parameters
SourceTop
[in] New top coordinate.
Return Values

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle height.

IBasicVideo::put_SourceWidth

IBasicVideo Interface

Sets the source rectangle width.

HRESULT put_SourceWidth(
long SourceWidth
);

Parameters
SourceWidth
[in] New width of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

Setting this method has no effect on the source rectangle x-axis coordinate.

IBasicVideo::SetDefaultDestinationPosition

IBasicVideo Interface

Sets the default destination position of the video window so that the renderer uses the entire window for playback.

HRESULT SetDefaultDestinationPosition( );

Return Values

Returns an HRESULT value.

IBasicVideo::SetDefaultSourcePosition

IBasicVideo Interface

Informs the renderer to use the default source rectangle.

HRESULT SetDefaultSourcePosition( );

Return Values

Returns an HRESULT value.

IBasicVideo::SetDestinationPosition

IBasicVideo Interface

Sets the destination rectangle in window coordinates.

HRESULT SetDestinationPosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
[in] The x-axis origin of the destination window.
Top
[in] The y-axis origin of the destination window.
Width
[in] Width of the destination window.
Height
[in] Height of the destination window.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::put_DestinationLeft, IBasicVideo::put_DestinationTop, IBasicVideo::put_DestinationWidth, and IBasicVideo::put_DestinationHeight methods.

IBasicVideo::SetSourcePosition

IBasicVideo Interface

Sets the source rectangle and is clipped against the available video.

HRESULT SetSourcePosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
[in] The x-axis origin of the source window.
Top
[in] The y-axis origin of the source window.
Width
[in] Width of the source window.
Height
[in] Height of the source window.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IBasicVideo::put_SourceLeft, IBasicVideo::put_SourceTop, IBasicVideo::put_SourceWidth, and IBasicVideo::put_SourceHeight methods.

Setting this coordinate does not affect the destination rectangle height.


ICaptureGraphBuilder Interface

The ICaptureGraphBuilder interface enables you to build capture graphs, preview graphs, file recompression graphs, or even unusual custom graphs easily. See Recompress an AVI File for more information.

When to Implement

Do not implement this interface. DirectShow already does so.

When to Use

Use this interface in your capture and recompression applications to make it easier to build filter graphs.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
ICaptureGraphBuilder methods | Description
SetFiltergraph | Tells the graph builder object which filter graph to use.
GetFiltergraph | Retrieves the filter graph that the builder is using.
SetOutputFileName | Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.
FindInterface | Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, only on the output pin of the given category.
RenderStream | Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.
ControlStream | Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.
AllocCapFile | Preallocates a capture file to a specified size.
CopyCaptureFile | Copies the valid media data from the preallocated capture file.

ICaptureGraphBuilder::AllocCapFile

ICaptureGraphBuilder Interface

Preallocates a capture file to a specified size.

HRESULT AllocCapFile(
LPCOLESTR lpwstr,
DWORDLONG dwlSize
);

Parameters
lpwstr
[in] Pointer to a Unicode string containing the name of the file to create or resize.
dwSize
[in] Size, in bytes, of the file to be allocated.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The call will fail if the file is read-only. For best capture results, always capture to a defragmented, preallocated capture file that is larger than the size of the capture data.

Note that under the current DirectShow implementation of this interface, a call to this method will be much quicker on a Windows 95 platform than it will be on a Windows NT platform.

ICaptureGraphBuilder::ControlStream

ICaptureGraphBuilder Interface

Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.

HRESULT ControlStream(
const GUID *pCategory,
IBaseFilter *pFilter,
REFERENCE_TIME *pstart,
REFERENCE_TIME *pstop,
WORD wStartCookie,
WORD wStopCookie
);

Parameters
pCategory
[in] Pointer to a GUID specifying the output pin category. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates control all capture filters in the graph.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pFilter
[in] Pointer to an IBaseFilter interface on the filter to control. Specifying NULL controls all capture filters in the graph. You will get one notification for each capture filter.
pstart
[in] Pointer to the start time for capture. NULL means start now. MAX_TIME means cancel previous request, or take no action if there is no previous request.
pstop
[in] Pointer to the stop time for capture. NULL means stop now. MAX_TIME means cancel previous request, or take no action if there is no previous request.
wStartCookie
[in] Specifies a particular value to be sent when the start occurs.
wStopCookie
[in] Specifies a particular value to be sent when the stop occurs.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_FALSE if the stop notification is sent before the last sample sent by the capture filter is rendered, otherwise returns S_OK.

If this method returns S_FALSE, the application might want to wait before destroying the filter graph to allow all samples to pass through the graph and be rendered. Otherwise, samples might be lost.

If a capture filter does not support the IAMStreamControl interface on its preview pin, the filter should return the failure code E_NOINTERFACE in response to a call to this method.

Remarks

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you could turn off writing of the captured image to disk if you only want to preview the captured image.

This method calls the IAMStreamControl interface on the pins.

This method sends one notification for each filter found with a pin of the specified category.

ICaptureGraphBuilder::CopyCaptureFile

ICaptureGraphBuilder Interface

Copies the valid media data from the preallocated capture file.

HRESULT CopyCaptureFile(
[in] LPOLESTR lpwstrOld,
[in] LPOLESTR lpwstrNew,
[in] int fAllowEscAbort,
[in] IAMCopyCaptureFileProgress *pCallback
);

Parameters
lpwstrOld
[in] Pointer to a Unicode string containing the source file name.
lpwstrNew
[in] Pointer to a Unicode string containing the destination file name. Valid data is copied to this file.
fAllowEscAbort
[in] TRUE indicates that pressing the ESC key aborts the copy operation, FALSE indicates that this method will ignore that keystroke.
pCallback
[in] Optional pointer to an IAMCopyCaptureFileProgress interface that you implement to show the progress (percentage complete) of the copy operation.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The new file will contain only valid data and therefore can be much shorter than the source file. Typically, you will always capture to the same huge preallocated file and use this method to copy the data you want to save from each capture to a new file.

If you specify pCallback, the Progress method on the IAMCopyCaptureFileProgress interface will be called periodically with an integer between 0 and 100 representing the percentage complete.

ICaptureGraphBuilder::FindInterface

ICaptureGraphBuilder Interface

Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, only on the output pin of the given category.

HRESULT FindInterface(
const GUID *pCategory,
IBaseFilter *pf,
REFIID riid,
void **ppint
);

Parameters
pCategory
[in] Pointer to a GUID specifying the output pin category. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates search all the output pins regardless of category.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pf
[in] Pointer to an IBaseFilter interface of the filter.
riid
[in] Reference ID of the desired interface.
ppint
[out] Address of a void pointer. If the interface was found, this method initializes ppint so that it contains the address of a pointer to the found interface. Call the Release method to decrement the reference count when you're done with the interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method looks for the interface on the filter, and upstream and downstream of the filter, unless a category is given. If a category is given, it only looks downstream of the output pin of that category. It can be used to find interfaces on renderers, multiplexers, TV tuners, crossbars, and so forth.

If pCategory == &LOOK_UPSTREAM_ONLY, then the graph builder will look upstream of the filter given in parameter pf, but not on the filter itself, nor downstream of the filter.

If pCategory == &LOOK_DOWNSTREAM_ONLY, then the graph builder will look downstream of the filter given in parameter pf, but not on the filter itself, nor upstream of the filter.

For example, capture graphs can have two crossbars in them, a video crossbar (upstream of the video capture filter) and an audio crossbar (upstream of the video crossbar). You can find the video crossbar filter that implements IAMCrossbar as shown in the following code:

IAMCrossbar *pVideoCrossbar;
FindInterface(NULL, pVideoCaptureFilter, IID_IAMCrossbar, (void **)&pVideoCrossbar);

You can then find the IAMCrossbar filter of the audio crossbar as shown in the following code:

IBaseFilter *pBaseFilter;
IAMCrossbar *pAudioCrossbar;
pVideoCrossbar->QueryInterface(IID_IBaseFilter, (void **)pBaseFilter);
FindInterface(&LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, (void **)&pAudioCrossbar);
pBaseFilter->Release();

See AMCAP, the capture sample in the SDK for an example of how to use interface.

ICaptureGraphBuilder::GetFiltergraph

ICaptureGraphBuilder Interface

Retrieves the filter graph that the builder is using.

HRESULT GetFiltergraph(
IGraphBuilder **ppfg
);

Parameters
ppfg
[out] Address of a pointer to an IGraphBuilder interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method increments the reference count on the IGraphBuilder interface; be sure to decrement the reference count on IGraphBuilder by calling the Release method.

ICaptureGraphBuilder::RenderStream

ICaptureGraphBuilder Interface

Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.

HRESULT RenderStream(
const GUID *pCategory,
IUnknown *pSource,
IBaseFilter *pfCompressor,
IBaseFilter *pfRenderer
);

Parameters
pCategory
[in] Pointer to a GUID specifying which output pin of the source filter to connect. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates render the only output pin, regardless of category.
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pSource
[in] Pointer to an IBaseFilter or an IPin interface representing either the source filter or an output pin. Source filters are typically a file source filter, such as an AVI file source filter or a capture filter.
pfCompressor
[in] Pointer to an IBaseFilter interface representing the optional compression filter.
pfRenderer
[in] Pointer to an IBaseFilter interface representing the renderer. You can use the ppf (multiplexer) parameter from ICaptureGraphBuilder::SetOutputFileName to supply this value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If you specify PIN_CATEGORY_CAPTURE for pCategory and a capture filter for pSource, this method instantiates and connects additional required upstream filters, such as TV tuners and crossbars. It then renders the capture pin of pSource.

If pSource is a pin, then specify NULL for pCategory and this method renders the stream from that pin.

If the source filter has only one output pin, specify NULL for pCategory.

All required filters must be present in the graph before the application calls this method.

Some capture filters that work with new WDM VPE (Video Port Extension) video capture hardware have VIDEO PORT pins instead of PREVIEW pins meant for previewing. These VIDEO PORT pins do not connect directly to a video renderer, but instead to a special filter called the Overlay Mixer. Your application does not need to worry about this. All you have to do is call RenderStream with &PIN_CATEGORY_PREVIEW and the capture graph builder will correctly render the VIDEO PORT pin through an overlay mixer if that is what is necessary.

When you render a capture or preview pin of a video capture filter (using RenderStream with the &PIN_CATEGORY_CAPTURE or &PIN_CATEGORY_PREVIEW category) and the capture filter only has a capture pin but no preview pin, the Smart Tee filter (QCAP.DLL) will be used automatically to allow simultaneous capture and preview. For example, calling RenderStream with the &PIN_CATEGORY_CAPTURE category will actually connect a Smart Tee filter to the capture pin of the filter, and then render the capture pin of the Smart Tee. If you then call RenderStream with the &PIN_CATEGORY_PREVIEW category on the capture pin, it will actually render the preview pin of the Smart Tee. If calling RenderStream with &PIN_CATEGORY_PREVIEW results in using the capture pin and a Smart Tee filter, RenderStream will return VFW_S_NOPREVIEWPIN to indicate this. Thus, if FindInterface fails to find a preview interface, you may need to call FindInterface with the &PIN_CATEGORY_PREVIEW category and with the &PIN_CATEGORY_CAPTURE category, since the preview interface may be found by looking downstream of the capture pin of the capture filter. See the AMCAP.cpp sample for an example of using this interface and writing a capture application.

ICaptureGraphBuilder::SetFiltergraph

ICaptureGraphBuilder Interface

Tells the graph builder object which filter graph to use.

HRESULT SetFiltergraph(
IGraphBuilder *pfg
);

Parameters
pfg
[in] Pointer to an IGraphBuilder interface that specifies the filter graph to use for subsequent calls to the IFilterGraph::AddFilter method.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The graph builder will automatically create a filter graph if you don't call this method. If you call this method after the graph builder has created its own filter graph, the call will fail.

ICaptureGraphBuilder::SetOutputFileName

ICaptureGraphBuilder Interface

Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.

HRESULT SetOutputFileName(
const GUID *pType,
LPCOLESTR lpwstrFile,
IBaseFilter **ppf,
IFileSinkFilter **pSink
);

Parameters
pType
[in] Pointer to a GUID representing the media subtype. Must be

&MEDIASUBTYPE_Avi

because AVI is currently the only supported output format.

lpwstrFile
[in] Pointer to a Unicode string containing the output file name.
ppf
[out] Address of a pointer to an IBaseFilter interface representing the multiplexer filter. This method increments the reference count on the IBaseFilter interface so you must decrement the reference count by using the Release method on this parameter when done using the filter.
pSink
[out] Address of a pointer to an IFileSinkFilter interface representing the file writer. This method increments the reference count on the IFileSinkFilter interface so you must decrement the reference count using Release when done using the filter.
Return Values

Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument. Audio-video interleaved (AVI) is the only supported output format.
E_OUTOFMEMORY | Out of memory.
E_POINTER | Null pointer argument.
E_UNEXPECTED | Unexpected error occurred.
NOERROR | Success.
S_OK | Instance of the AVI multiplexer filter was successfully created.

Remarks

This method inserts the multiplexer and the file writer into the filter graph and calls IFileSinkFilter::SetFileName to set the output file name.

You can use the ppf parameter returned by this method as the pfRenderer parameter in calls to RenderStream.

You can use the pSink parameter from this method in a call to SetFileName to change the file name set by ICaptureGraphBuilder::SetOutputFileName.


IConfigAviMux Interface

The IConfigAviMux interface controls how the AVI multiplexer filter writes files out to disk. Microsoft® DirectShow™ currently exposes this interface through the property page of the AVI multiplexer filter and you can use it to set the master stream and compatibility indexes.

IConfigAviMux provides backward compatibility with older Video for Windows® audio-video interleaved (AVI) index formats (idx1) as well as extended AVI 2.0 index formats (indx) to allow for file sizes greater than 1 gigabyte (GB). Set and retrieve the compatibility indexes by using the IConfigAviMux::SetOutputCompatibilityIndex and IConfigAviMux::GetOutputCompatibilityIndex methods. See AVI 2.0 File Format Extensions for more information on AVI 2.0.

When to Implement

DirectShow implements this interface and makes its functionality available to anyone through the property page of an AVI multiplexer filter. However, you can implement this interface yourself if you're writing a filter that takes audio and video streams from a capture graph and generates an AVI file.

When to Use

Use this interface when your application must control how a file is captured.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IConfigAviMux methods | Description
SetMasterStream | Sets the master stream that other streams must synchronize to after the file is saved to disk.
GetMasterStream | Retrieves the master stream that other streams must synchronize to after the file is written out.
SetOutputCompatibilityIndex | Sets the AVI index format for the file that the multiplexer saves to.
GetOutputCompatibilityIndex | Retrieves the AVI index format for the file that the multiplexer will write to.

IConfigAviMux::GetMasterStream

IConfigAviMux Interface

Retrieves the master stream that other streams must synchronize to after the file is written out.

HRESULT GetMasterStream(
LONG *pStream
);

Parameters
pStream
[out] Pointer to the master stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

To eliminate capture drifts that can occur between audio sampling rates and video frame rates, it is recommended that you use combined audio/video cards for capture of large files.

See Also

IConfigAviMux::SetMasterStream

IConfigAviMux::GetOutputCompatibilityIndex

IConfigAviMux Interface

Retrieves the AVI index format for the file that the multiplexer will write to.

HRESULT GetOutputCompatibilityIndex(
BOOL *pfOldIndex
);

Parameters
pfOldIndex
[out] Value indicating the index format. Returns TRUE if AVI 1.0 (idx1) index format or AVI 2.0 (indx) index format is set; returns FALSE if only AVI 2.0 (indx) index format is set.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

SetOutputCompatibilityIndex

IConfigAviMux::SetMasterStream

IConfigAviMux Interface

Sets the master stream that other streams must synchronize to after the file is saved to disk.

HRESULT SetMasterStream(
LONG iStream
);

Parameters
iStream
[in] Master input stream. Set to –1 to disable.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Different streams in the capture scenario can capture at different rates if you are using separate audio and video capture cards. By specifying a master stream that all others must synchronize to, this method adjusts the frame rate or audio sampling rate to account for drifts in the rates.

To eliminate capture drifts that can occur between audio sampling rates and video frame rates, it is recommended that you use combined audio/video cards for capture of large files.

See Also

IConfigAviMux::GetMasterStream

IConfigAviMux::SetOutputCompatibilityIndex

IConfigAviMux Interface

Sets the AVI index format for the file that the multiplexer saves to.

HRESULT SetOutputCompatibilityIndex(
BOOL fOldIndex
);

Parameters
fOldIndex
[in] TRUE indicates either AVI 1.0 (idx1) index format or AVI 2.0 (indx) index format; FALSE indicates only AVI 2.0 (indx) index format.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

In addition to backward compatibility with Video for Windows® AVI index formats (idx1), DirectShow also supports extended AVI 2.0 index format (indx), which this method can specify. AVI 2.0 index format allows for increased AVI file size (greater than 1 GB), hierarchical indexing, incremental growth of files, and minimal disk seeks. See AVI 2.0 File Format Extensions for more information on AVI 2.0.

See Also

IConfigAviMux::GetOutputCompatibilityIndex

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IConfigInterleaving Interface

The IConfigInterleaving interface controls how files are written out to disk and sets interleaving configuration information such as frequency and preroll parameters.

This interface uses the InterleavingMode enumerated data type, which specifies how audio samples and video frames will be saved on a disk. Capture interleaving settings can range from INTERLEAVE_NONE to INTERLEAVE_FULL, depending on whether you will author immediately or later.

DirectShow currently implements this interface on the AVI multiplexer filter; however, you can implement it to set interleaving preferences on other file formats.

When to Implement

DirectShow implements this interface and makes its functionality available to anyone through the property page of an AVI multiplexer filter. However, you can implement this interface yourself when you want to be able to write out other file formats.

When to Use

Video-authoring applications that handle capturing should use this interface when they need to control how audio samples and video frames will be saved on a disk. Applications also use this interface when they need to set interleaving configuration information such as frequency and preroll parameters. (see Amcap.exe for a sample implementation of this interface).

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IConfigInterleaving methods | Description
put_Mode | Sets how audio samples and video frames will be saved on disk by specifying quality of interleaving.
get_Mode | Retrieves the interleaving quality setting.
put_Interleaving | Sets the audio preroll time and the frequency of the interleaving.
get_Interleaving | Retrieves the audio preroll time and the frequency of the interleaving.

IConfigInterleaving::get_Interleaving

IConfigInterleaving Interface

Retrieves the audio preroll time and the frequency of the interleaving.

HRESULT get_ Interleaving(
REFERENCE_TIME *prtInterleave,
REFERENCE_TIME *prtPreroll );

Parameters
prtInterleave
[out] Frequency of the streams in the file, in 100-nanosecond units.
prtPreroll
[out] Audio preroll, in 100-nanosecond units.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IConfigInterleaving::put_Interleaving

IConfigInterleaving::get_Mode

IConfigInterleaving Interface

Retrieves the interleaving quality setting.

HRESULT get_ Mode(
InterleavingMode *pMode );

Parameters
mode
[out] Interleaving quality setting specified in the InterleavingMode enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The interleaving mode is specified in the InterleavingMode enumerated data type and is set in the IConfigInterleaving::put_Mode method.

See Also

IConfigInterleaving::put_Mode

IConfigInterleaving::put_Interleaving

IConfigInterleaving Interface

Sets the audio preroll time and the frequency of the interleaving.

HRESULT put_ Interleaving(
const REFERENCE_TIME *prtInterleave,
const REFERENCE_TIME *prtPreroll );

Parameters
prtInterleave
[in] Frequency of the streams in the file, in 100-nanosecond units.
prtPreroll
[in] Audio preroll, in 100-nanosecond units.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

An audio preroll of 750 milliseconds is recommended when authoring a file for distribution.

The default value for prtInterleave is 1000 milliseconds, however you can adjust this. The smaller the number, the larger the file overhead.

See Also

IConfigInterleaving::get_Interleaving

IConfigInterleaving::put_Mode

IConfigInterleaving Interface

Sets how audio samples and video frames are to be written to disk, by specifying quality of interleaving.

HRESULT put_ Mode(
InterleavingMode mode );

Parameters
mode
[in] Interleaving quality setting specified in the InterleavingMode enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Applications that require full interleaving authoring quality should specify INTERLEAVE_FULL, INTERLEAVE_CAPTURE, and INTERLEAVE_NONE settings when you will author at a later time.

See Also

IConfigInterleaving::get_Mode

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


ICreateDevEnum Interface

The ICreateDevEnum interface creates an enumerator for a list of objects; typically, these objects are instances of hardware devices. Use this enumerator to access the objects' interfaces, methods, and data. This enumerator supports the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone. For more information on using enumerators, see the Win32 IEnumXXXX interface documentation.

The ICreateDevEnum interface implements plug-and-play functionality to enumerate devices; DirectShow provides additional plug-and-play functionality through the Win32 IPropertyBag and IPersistPropertyBag interfaces; see the appropriate documentation for more details.

When to Implement

Implement this interface when you want to obtain lists of a specific category of objects. The object must have an internal structure that allows enumeration.

When to Use

Applications need a simple method of finding and creating instances of objects that represent the machine's devices. To obtain these instances, you should first create a system device enumerator object, and then use it to create an enumerator for the particular class of device that interests you. DirectShow typically uses this enumerator to create a list of the machine's video capture devices, which you can then use in your applications or present in some fashion to the user.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
ICreateDevEnum methods | Description
CreateClassEnumerator | Creates a class enumerator for the specified category.

ICreateDevEnum::CreateClassEnumerator

ICreateDevEnum Interface

Creates an enumerator for the specified type of object.

HRESULT CreateClassEnumerator(
REFCLSID clsidDeviceClass,
IEnumMoniker ** ppEnumMoniker,
DWORD dwFlags
);

Parameters
clsidDeviceClass
[in] REFCLSID value that specifies the type of object or device to enumerate.
ppEnumMoniker
[out] Address of a pointer to the Win32 IEnumMoniker (or derived) interface implemented by the new class enumerator.
dwFlags
[in] Combination of flags that modifies how DirectShow creates the enumerator; for example, an application can use a flag to skip devices that have already been enumerated or that do not support persistant storage of their device properties (CLSID, FriendlyName, and DevicePath).
Return Values

Return one of the following values.
Value | Meaning
NOERROR | Success.
E_OUTOFMEMORY | There is not enough memory available to create a class enumerator.
S_FALSE | The category specified by clsidDeviceClass does not exist.

Remarks

The new class enumerator is a nonaggregate object that will run in the same process as the class that called this method.


ICutListGraphBuilder Interface

The ICutListGraphBuilder interface enables you to easily implement one or more cutlist filter graphs. The simplest way to use this object is to add a cutlist by using the ICutListGraphBuilder::AddCutList method, and then use the ICutListGraphBuilder::Render method to create and connect the graph.

You can also use this interface to save your movie to a file. Use the ICutListGraphBuilder::SetOutputFileName method to specify the media subtype (such as MEDIASUBTYPE_Avi) and the file name. ICutListGraphBuilder attempts to connect the filters needed to write to this file, so that when you call ICutListGraphBuilder::Render, the filter graph manager creates a filter graph that writes to a file.

See About Cutlists and Using Cutlists for more information.

When to Implement

Do not implement this interface. DirectShow implements it for you.

When to Use

Use this interface in your application when you want to provide cutlist functionality to the user.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
ICutListGraphBuilder methods | Description
SetFilterGraph | Sets the filter graph that the cutlist graph builder will use
GetFilterGraph | Retrieves the filter graph the cutlist graph builder is using to implement playback of the cutlist.
AddCutList | Adds a cutlist to the filter graph.
RemoveCutList | Removes a cutlist from a filter graph.
SetOutputFileName | Specifies the output file and media subtype to use when writing the movie to a file.
Render | Creates the final cutlist filter graph.
GetElementFlags | Retrieves the flags of a given element.

ICutListGraphBuilder::AddCutList

ICutListGraphBuilder Interface

Adds a cutlist to the filter graph.

HRESULT AddCutList(
IStandardCutList *pCutList,
IPin **ppPin
);

Parameters
pCutList
[in] Pointer to the cutlist's IStandardCutList interface that the graph builder might query for more detailed information about the cutlist.
ppPin
[out] Address of a pointer to the output pin of the cutlist filter that this method added to the filter graph. Use this pin as a starting point to build custom cutlist filter graphs. Be sure to decrement the pin's reference count by calling the Release method on the pin before you call the ICutListGraphBuilder::RemoveCutList method. Specify NULL for ppPin if you don't need the pin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

When you call the ICutListGraphBuilder::Render method, the ICutListGraphBuilder interface attempts to create a graph that plays back all the cutlists you have added to the graph. You must follow calls to AddCutList with a call to ICutListGraphBuilder::Render to render the new cutlist in the graph, or your cutlist will not be used. You can wait and call Render once after adding all of your cutlists to the graph.

You can't call IStandardCutList::AddElement on this cutlist after you have given the cutlist to the graph builder by calling this method. The AddElement call will be ignored. Make sure you have called AddElement as many times as you need to before calling ICutListGraphBuilder::AddCutList.

If you call AddCutList to add the cutlist to the filter graph, you must later call ICutListGraphBuilder::RemoveCutList to remove the cutlist from the filter graph. You must do so before releasing the filter graph.

ICutListGraphBuilder::GetElementFlags

ICutListGraphBuilder Interface

Retrieves the flags of a given element.

HRESULT GetElementFlags(
IAMCutListElement *pElement,
LPDWORD lpdwFlags
);

Parameters
pElement
[in] Pointer to the element's IAMCutListElement interface.
lpdwFlags
[out] Retrieved element flags. The flags are a logical combination of members of the CL_ELEM_FLAGS enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

ICutListGraphBuilder::GetFilterGraph

ICutListGraphBuilder Interface

Retrieves the filter graph that the cutlist graph builder is using to implement playback of the cutlist.

HRESULT GetFilterGraph(
IGraphBuilder **ppFilterGraph
);

Parameters
ppFilterGraph
[out] Address of a pointer to the filter graph that the cutlist graph builder is using.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

This method is useful, for instance, to acquire the playback graph's IMediaControl and IMediaEvent interfaces.

This method increments the reference count on the filter graph interface pointed to by ppFilterGraph. Be sure to decrement the reference count on the filter graph object by calling its Release method when you're done.

See Also

IGraphBuilder

ICutListGraphBuilder::RemoveCutList

ICutListGraphBuilder Interface

Removes a cutlist from a filter graph.

HRESULT RemoveCutList(
IStandardCutList *pCutList
);

Parameters
pCutList
[in] Pointer to the cutlist's IStandardCutList interface that the graph builder might query for more detailed information about the cutlist.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

If you called the ICutListGraphBuilder::AddCutList method to add the cutlist to the filter graph, you must call this method before releasing the filter graph.

You should call this method only when the graph is stopped, otherwise resources will not be properly freed.

ICutListGraphBuilder::Render

ICutListGraphBuilder Interface

Creates the final cutlist filter graph.

HRESULT Render(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

Call this method to create the final filter graph containing all the previously specified cutlists and file writer filters.

If the graph contains a multiplexer (MUX) filter before you call this method, then this method connects all cutlist source filters to the MUX, and connects the MUX to a single renderer. Otherwise, each cutlist source filter renders through its own renderer. For example, rendering two separate video cutlists without a MUX would give you two video renderer windows for playback.

See Also

ICutListGraphBuilder::AddCutList

ICutListGraphBuilder::SetFilterGraph

ICutListGraphBuilder Interface

Sets the filter graph that the cutlist graph builder will use.

HRESULT SetFilterGraph(
IGraphBuilder *pFilterGraph
);

Parameters
pFilterGraph
[in] Pointer to the desired filter graph.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

The filter graph can contain filters that the cutlist graph builder will try to use in constructing the graph before adding other filters.

If you've already called this method to give a cutlist to the cutlist graph builder, you can't call this method again.

See Also

IGraphBuilder

ICutListGraphBuilder::SetOutputFileName

ICutListGraphBuilder Interface

Specifies the output file and media subtype to use when writing the movie to a file.

HRESULT SetOutputFileName(
const GUID *pType,
LPCOLESTR lpwstrFile,
IBaseFilter **ppf,
IFileSinkFilter **pSink
);

Parameters
pType
[in] Pointer to a GUID representing the media subtype. Must be &MEDIASUBTYPE_Avi because AVI is currently the only supported output format.
lpwstrFile
[in] Pointer to a Unicode string containing the output file name.
ppf
[in] Address of a pointer to an IBaseFilter interface representing the multiplexer filter. This method increments the reference count on the IBaseFilter interface, so you must decrement the reference count by using the Release method on this parameter when you're done using the filter.
pSink
[in] Address of a pointer to an IFileSinkFilter interface representing the file writer. This method increments the reference count on the IFileSinkFilter interface, so you must decrement the reference count by using Release when you're done using the filter.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

This method specifies to the cutlist graph builder that the output of this filter graph should be a file of media subtype pType. If you do not call this method, then the cutlist graph builder will attempt to render a graph to play the cutlist to the screen and through the system speakers.


IDeferredCommand Interface

The deferred command mechanism allows filters themselves to handle deferred commands. Where they do not, the filter graph manager queues the command until the requested time and then calls the method on the filter (this would result in coarse rather than accurate synchronization). Note that a filter that does handle deferred commands must make them apply to data appearing at that time. Thus a contrast filter asked to change the contrast at time x must ensure that it applies the change when processing data time-stamped to be rendered at time x; these samples will be processed by the filter somewhat before time x.

The IQueueCommand interface provides two methods, InvokeAtStreamTime, which queues commands at stream time, and InvokeAtPresentationTime, which queues commands at presentation time. Both return an IDeferredCommand interface to the queued command, by which the application can cancel the command, set a new presentation time for it, or get back an estimate of the likelihood of the filter graph manager being able to run the command on time (implementation of this last method is likely to be highly simplistic in the first release of Microsoft® DirectShow™).

Both the queue and the application will hold a reference count on the object (represented to the application by the IDeferredCommand interface), and the object will not be destroyed until both are released. Similarly, calling Release on the IDeferredCommand interface is not sufficient to cancel the command because the queue also holds a reference count.

When to Implement

This method is implemented by the filter graph manager to allow deferred processing of commands. It is implemented through a plug-in distributor to pass deferred commands from the application to the filters (through the plug-in distributor for the command that has been queued). You can implement it within your filter if your filter supports queued commands; in this case, applications will need to obtain an IQueueCommand interface directly from your filter. You can use the CDeferredCommand class to help implement this interface.

When to Use

Applications can use this interface to cancel, postpone, get return values from, or determine a confidence level for commands that have been queued for deferred execution by using the IQueueCommand interface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDeferredCommand methods | Description
Cancel | Cancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request.
Confidence | Returns a confidence value that describes the probability of the deferred command being run on time.
Postpone | Specifies a new invocation time for a previously queued command.
GetHResult | Retrieves the return value from the invoked command.

IDeferredCommand::Cancel

IDeferredCommand Interface

Cancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request.

HRESULT Cancel( );

Return Values

Returns an HRESULT value.

IDeferredCommand::Confidence

IDeferredCommand Interface

Returns a confidence value on a scale of 0 to 100 that describes the probability that the deferred command will be run on time.

HRESULT Confidence(
LONG *pConfidence
);

Parameters
pConfidence
Confidence level.
Return Values

Returns an HRESULT value.

Remarks

Higher confidence values indicate a greater probability of timely execution. For example, a command queued at a presentation time that has already passed will return a value of 0. A value of 100 would indicate, with absolute certainty, that the command can be run on time. Commands that are not directly supported by the filter but are queued by the filter graph manager will return a lower confidence value than commands queued directly by the filters that run them. Commands that are queued with times too close to other commands are likely to return lower confidence values. The initial implementation of this method relies mostly on the reporting of the individual filter commands rather than an attempt to estimate resource availability on a filter graph-wide basis.

IDeferredCommand::GetHResult

IDeferredCommand Interface

Retrieves the return value from the invoked command.

HRESULT GetHResult(
HRESULT* phrResult
);

Parameters
phrResult
Retrieved HRESULT value.

IDeferredCommand::Postpone

IDeferredCommand Interface

Specifies a new presentation time for a previously queued command.

HRESULT Postpone(
REFTIME newtime
);

Parameters
newtime
New presentation time.
Return Values

Return value is S_OK if completed. Also, if completed, the phrResult parameter is set to the result of the deferred command.


IDirectDrawVideo Interface

This interface is on the video renderer and provides information about Microsoft® DirectDraw® with respect to its use by the renderer. For example, the interface allows an application to get details of the surface and any available hardware capabilities. It also allows the application to adjust the surfaces that the renderer should use, and even to set the DirectDraw instance. There is some duplication in this interface with the IDirectDraw interface; however, this interface allows simple access to that information without calling the DirectDraw provider directly.

DirectDraw is not loaded by the renderer until it is connected, and likewise DirectDraw is unloaded only when the renderer is disconnected. When the renderer has allocated the DirectDraw surfaces it will use for video playback, an application can obtain a DDSURFACEDESC structure describing it. By passing in a pointer to a DDSURFACEDESC structure, the renderer will fill in the structure with the details of the current surface. If DirectDraw has not been loaded, the renderer will return E_FAIL. If the renderer is using DCI (the predecessor to DirectDraw), the DDSURFACEDESC structure is not filled in but the call will return S_FALSE. The only type of DCI surfaces the renderer uses are primary surfaces.

When to Implement

This interface is implemented by the Microsoft® DirectShow™ video renderer to provide information about DirectDraw surfaces and hardware capabilities.

When to Use

Applications can use this interface to get details of the surface and any available hardware capabilities, adjust the surfaces that the renderer should use, and set the IDirectDraw instance. Applications are allowed to set the IDirectDraw instance because DirectDraw can be opened only once per process; this helps resolve conflicts.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDirectDrawVideo methods | Description
GetCaps | Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.
GetEmulatedCaps | Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.
CanUseOverlayStretch | Determines whether the renderer will check overlay restrictions.
CanUseScanLine | Determines whether the renderer will check the current scan line when drawing.
GetDirectDraw | Retrieves the IDirectDraw interface.
GetFourCCCodes | Retrieves the multimedia format type FOURCC DWORD.
GetSurfaceDesc | Retrieves a description of the DirectDraw surface in use.
GetSurfaceType | Retrieves the actual surface type.
GetSwitches | Retrieves the surface types that the renderer is allowed to use.
SetDefault | Makes the current property settings the global default.
SetDirectDraw | Passes the IDirectDraw interface to a loaded driver.
SetSwitches | Sets the surface types that the renderer is allowed to use.
UseOverlayStretch | Determines whether the renderer should check overlay stretch limitations.
UseScanLine | Determines whether the renderer should check the current scan line when drawing a video.
UseWhenFullScreen | Determines whether DirectShow might change display mode when going to full-screen mode.
WillUseFullScreen | Determines whether DirectShow will change display mode when going to full-screen mode.

IDirectDrawVideo::CanUseOverlayStretch

IDirectDrawVideo Interface

Determines whether the renderer will check overlay restrictions.

HRESULT CanUseOverlayStretch(
long * UseOverlayStretch
);

Parameters
UseOverlayStretch
Set to OATRUE if the renderer can use overlay stretching; otherwise, set to OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

For a description of overlay stretching, see IDirectDrawVideo::UseOverlayStretch.

IDirectDrawVideo::CanUseScanLine

IDirectDrawVideo Interface

Determines whether the renderer will check the current scan line when drawing.

HRESULT CanUseScanLine(
long * UseScanLine
);

Parameters
UseScanLine
Set to OATRUE if the renderer can use scan line information; otherwise, set to OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

For a description of the use of scan line detection in the DirectShow video renderer, see IDirectDrawVideo::UseScanLine.

IDirectDrawVideo::GetCaps

IDirectDrawVideo Interface

Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.

HRESULT GetCaps(
DDCAPS *pCaps
);

Parameters
pCaps
DDCAPS structure containing the hardware capabilities.
Return Values

Returns an HRESULT value.

Remarks

If the renderer has not loaded DirectDraw, this method returns E_FAIL. DirectDraw is not loaded by the renderer until it is connected, and likewise is unloaded only when the renderer is disconnected.

IDirectDrawVideo::GetDirectDraw

IDirectDrawVideo Interface

Retrieves the IDirectDraw interface.

HRESULT GetDirectDraw(
LPDIRECTDRAW *ppDirectDraw
);

Parameters
ppDirectDraw
IDirectDraw interface.
Return Values

Returns an HRESULT value.

Remarks

If an application wants to load DirectDraw but allow the renderer to also allocate surfaces, it can let the renderer load DirectDraw and then obtain a reference-incremented interface to it through this method. The interface returned should be released by the application when it is finished with it.

IDirectDrawVideo::GetEmulatedCaps

IDirectDrawVideo Interface

Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.

HRESULT GetEmulatedCaps(
DDCAPS *pCaps
);

Parameters
pCaps
DDCAPS structure containing the emulated capabilities.
Return Values

Returns an HRESULT value.

Remarks

If the renderer has not loaded DirectDraw, this method returns E_FAIL.

IDirectDrawVideo::GetFourCCCodes

IDirectDrawVideo Interface

Retrieves the multimedia format type.

HRESULT GetFourCCCodes(
DWORD *pCount,
DWORD *pCodes
);

Parameters
pCount
Number of FOURCC codes in the pCodes array.
pCodes
Array of DWORD media tags formerly used for Microsoft multimedia types.
Return Values

Returns an HRESULT value.

Remarks

In the original Microsoft® Windows® multimedia APIs, media types were tagged with 32-bit values created from four 8-bit characters and were known as FOURCC codes. Because FOURCC codes are unique, a one-to-one mapping has been made possible by allocating a range of 4 billion GUIDs representing FOURCCs.

This method retrieves the FOURCC codes that the current display driver can support. The number available is obtained by calling the method with a valid pCount pointer, but with pCodes set to NULL. In this case, the pCount variable will be filled in with the number of FOURCC codes available. An application can then allocate enough DWORD values for this many FOURCC codes and call the method again with the array pointer in pCodes.

IDirectDrawVideo::GetSurfaceDesc

IDirectDrawVideo Interface

Retrieves a DDSURFACEDESC structure describing the current DirectDraw surface.

HRESULT GetSurfaceDesc(
DDSURFACEDESC *pSurfaceDesc
);

Parameters
pSurfaceDesc
DDSURFACEDESC structure describing the current DirectDraw surface.
Return Values

Returns an HRESULT value.

Remarks

If no surface has been allocated, this method will return E_FAIL. If a DCI primary surface is in use, the DDSURFACEDESC structure will not be filled in and the call will return S_FALSE. Surfaces are allocated only when the renderer is paused. Once the renderer has been paused, it cannot release the surfaces when stopped.

IDirectDrawVideo::GetSurfaceType

IDirectDrawVideo Interface

Retrieves the actual surface type as a DirectShow DirectDraw Surface (AMDDS) definition.

HRESULT GetSurfaceType(
DWORD *pSurfaceType
);

Parameters
pSurfaceType
Field filled in with one bit setting selected from the following list of AMDDS definitions.
AMDDS_NONE | No use for DCI/DirectDraw.
AMDDS_DCIPS | Use DCI primary surface.
AMDDS_PS | Use DirectDraw primary surface.
AMDDS_RGBOVR | RGB overlay surfaces.
AMDDS_YUVOVR | YUV overlay surfaces.
AMDDS_RGBOFF | RGB off-screen surfaces.
AMDDS_YUVOFF | YUV off-screen surfaces.
AMDDS_RGBFLP | RGB flipping surfaces.
AMDDS_YUVFLP | YUV flipping surfaces.
AMDDS_ALL | All the previous flags.
AMDDS_DEFAULT AMDDS_ALL | Use all available surfaces.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).
Return Values

Returns an HRESULT value.

Remarks

It is not always easy to discover which kind of surface is being used by looking at a DDSURFACEDESC structure. Therefore, an application can call GetSurfaceType to retrieve the surface type. The field will be filled in with one bit setting selected from the preceding list of AMDDS definitions.

IDirectDrawVideo::GetSwitches

IDirectDrawVideo Interface

Retrieves the surface types that the renderer is allowed to use.

HRESULT GetSwitches(
DWORD *pSwitches
);

Parameters
pSwitches
Bit mask containing one or more of the following DirectShow DirectDraw Surface (AMDDS) surface types.
AMDDS_NONE | No use for DCI/DirectDraw.
AMDDS_DCIPS | Use DCI primary surface.
AMDDS_PS | Use DirectDraw primary surface.
AMDDS_RGBOVR | RGB overlay surfaces.
AMDDS_YUVOVR | YUV overlay surfaces.
AMDDS_RGBOFF | RGB off-screen surfaces.
AMDDS_YUVOFF | YUV off-screen surfaces.
AMDDS_RGBFLP | RGB flipping surfaces.
AMDDS_YUVFLP | YUV flipping surfaces.
AMDDS_ALL | All the previous flags.
AMDDS_DEFAULT AMDDS_ALL | Use all available surfaces.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).
Return Values

Returns an HRESULT value.

IDirectDrawVideo::SetDefault

IDirectDrawVideo Interface

Makes the current property settings the global default.

HRESULT SetDefault( );

Return Values

Returns an HRESULT value.

Remarks

All properties set through IDirectDrawVideo are specific to that particular instance. Call this method to make properties set on this instance of IDirectDrawVideo the global default of all DirectShow instances of this interface. Once called, the current property settings will persist between the subsequent starting of other DirectShow filter graphs and between any computer restarts.

IDirectDrawVideo::SetDirectDraw

IDirectDrawVideo Interface

Passes the IDirectDraw interface to a loaded driver.

HRESULT SetDirectDraw(
LPDIRECTDRAW pDirectDraw
);

Parameters
pDirectDraw
IDirectDraw interface to be passed.
Return Values

Returns an HRESULT value.

Remarks

To have the renderer release a DirectDraw interface previously passed in through SetDirectDraw, an application can call SetDirectDraw, passing in NULL. However, the renderer will continue using that DirectDraw interface until it is disconnected. Therefore, calling SetDirectDraw with a null parameter does not make the renderer stop using it immediately.

This method was created because only one instance of IDirectDraw could be loaded per process in DirectDraw 1.0. If an application wanted to load IDirectDraw but allow the renderer to also allocate surfaces, the application could open IDirectDraw itself and then pass the interface to the loaded driver through IDirectDrawVideo::SetDirectDraw. Alternatively, the application could let the renderer load DirectDraw and then obtain a reference-incremented interface to it through IDirectDrawVideo::GetDirectDraw. Because DirectShow ships with the most recently shipped version of DirectDraw, however, this method is not required unless the application wants to change display modes itself and pass in a DirectDraw object, which the renderer can then use to allocate surfaces.

IDirectDrawVideo::SetSwitches

IDirectDrawVideo Interface

Sets the surface types that the renderer is allowed to use.

HRESULT SetSwitches(
DWORD pSwitches
);

Parameters
pSwitches
Bit mask containing one or more of the following DirectShow DirectDraw Surface (AMDDS) surface types.
AMDDS_NONE | No use for DCI/DirectDraw.
AMDDS_DCIPS | Use DCI primary surface.
AMDDS_PS | Use DirectDraw primary surface.
AMDDS_RGBOVR | RGB overlay surfaces.
AMDDS_YUVOVR | YUV overlay surfaces.
AMDDS_RGBOFF | RGB off-screen surfaces.
AMDDS_YUVOFF | YUV off-screen surfaces.
AMDDS_RGBFLP | RGB flipping surfaces.
AMDDS_YUVFLP | YUV flipping surfaces.
AMDDS_ALL | All the previous flags.
AMDDS_DEFAULT AMDDS_ALL | Use all available surfaces.
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS).
Return Values

Returns an HRESULT value.

IDirectDrawVideo::UseOverlayStretch

IDirectDrawVideo Interface

Determines whether the renderer should check overlay stretch limitations.

HRESULT UseOverlayStretch(
long UseOverlayStretch
);

Parameters
UseOverlayStretch
Set to OATRUE for the renderer to use overlay stretching; otherwise, set to OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

Some display cards provide the use of overlay surfaces through DirectDraw. An overlay surface is a block of video memory whose contents are overlaid onto the display during the monitor's vertical refresh. DirectShow uses all available overlay surfaces where possible because they typically offer higher-quality video and very fast performance. On some display cards set to relatively high bit depths, the overlay must be displayed on the screen larger than its real size (to accommodate certain display hardware bandwidth limitations). If the overlay is not displayed large enough, certain undesirable effects can be seen on the display (sometimes described as a "fleeting shimmering" effect).

If UseOverlayStretch is set to On (the default), DirectShow will ensure the overlay is adequately stretched before displaying it. If it is set to Off, DirectShow will not check that the overlay is adequately stretched, and the user is likely to experience artifacts on the screen (although it will also guarantee that the overlay will be used if possible).

IDirectDrawVideo::UseScanLine

IDirectDrawVideo Interface

Determines whether the renderer should check the current scan line when drawing a video.

HRESULT UseScanLine(
long UseScanLine
);

Parameters
UseScanLine
Long integer value that specifies whether or not to use the scan line information. Set to OATRUE to use scan line information or OAFALSE to ignore it.
Return Values

Returns E_INVALIDARG if the argument is invalid or NOERROR otherwise.

Remarks

If you blit a video image to the screen while the monitor's scan line is scanning over a visible portion of the screen, the complete image will be a composite of the old and new images. This composite is known as a torn video image. You can avoid torn images by waiting until the previous image is complete before blitting the new image. Some video cards can retrieve the scan line's current position; if this information is available, you can have DirectShow try to reduce tearing by waiting until the scan line is offscreen before blitting the new image. Note that checking the scan line location increases load on the processor and can reduce the amount of video frames delivered to the screen. If scan line information is available, DirectShow uses it by default. Set UseScanLine to OAFALSE if you want to save processing time at the expense of minor image degradation.

IDirectDrawVideo::UseWhenFullScreen

IDirectDrawVideo Interface

Determines whether DirectShow might change display mode when going to full-screen mode.

HRESULT UseWhenFullScreen(
long UseWhenFullScreen
);

Parameters
UseWhenFullScreen
Set to OATRUE to cause the renderer to use DirectX in full-screen mode; otherwise, set to OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

When asked to go to full-screen mode, DirectShow has a number of choices. The first choice is to determine if any filters in the graph can support full-screen playback directly; if one can, it will be asked to do so.

The second choice is to automatically add a special full-screen renderer to the filter graph that uses DirectDraw mode-changing services to play back the video. By changing display modes, the video effectively fills more (but not necessarily all) of the display. So, for example, if the current mode is 1024 x 768 pixels, a video might look relatively small, but when displayed in a 320 x 240 display mode it might look very presentable.

The third and final choice is to simply take any renderer supporting the IVideoWindow interface and have its window stretched full-screen. This will typically offer lower performance than the second option (swapping in a full-screen DirectDraw-enabled renderer). If the UseWhenFullScreen parameter is set to On (OATRUE), the window will always be stretched full-screen for full-screen playback; if set to Off (the default), the filter graph manager is free to swap in the DirectDraw-enabled full-screen renderer.

IDirectDrawVideo::WillUseFullScreen

IDirectDrawVideo Interface

Determines whether DirectShow will change display mode when going to full-screen mode.

HRESULT WillUseFullScreen(
long * UseWhenFullScreen
);

Parameters
UseWhenFullScreen
Set to OATRUE if DirectShow is set to use DirectX in full-screen mode; otherwise, set to OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

For a description of this feature, see IDirectDrawVideo::UseWhenFullScreen.


IDistributorNotify Interface

The IDistributorNotify interface is an optional interface for use by plug-in distributors to notify them of changes in the filter graph state.

When to Implement

Implement this interface when writing a plug-in distributor (PID) that is aggregated with the filter graph manager if you want the PID to receive notifications of control and changes in the composition of filter graphs.

PIDs may often use methods on the filter graph manager. During a call to an IDistributorNotify method, do not take any lock that may be held by another code path that calls the filter graph manager. To do so could result in a deadlock.

When to Use

The filter graph manager queries for this interface on any plug-in distributors that it aggregates. If found, it calls the appropriate Run, Pause, or SetSyncSource method before calling them on the IBaseFilter interface of each filter. It calls the NotifyGraphChange method whenever a filter is added or removed, or connections are changed.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDistributorNotify methods | Description
Stop | Called when the filter graph is entering a stopped state.
Pause | Called when the filter graph is entering a paused state.
Run | Called when the filter graph is entering a running state.
SetSyncSource | Called when a new clock is registered.
NotifyGraphChange | Called when the set of filters in the filter graph change or their connections change.

IDistributorNotify::NotifyGraphChange

IDistributorNotify Interface

Called when the set of filters in the filter graph change or their connections change.

HRESULT NotifyGraphChange(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is called whenever an IFilterGraph::AddFilter, IFilterGraph::RemoveFilter, or IFilterGraph::ConnectDirect method is called or a method is called that will lead to one of these being called (such as IGraphBuilder::RenderFile).

Make sure you use Release on any held filters that have been removed at this point. For performance reasons, PIDs might choose not to rescan the filters until the PIDs actually need the interfaces, because there might be several separate notifications sent. However, it is important to release any cached interfaces immediately.

IDistributorNotify::Pause

IDistributorNotify Interface

Called when the filter graph is entering a paused state.

HRESULT Pause(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value | Meaning
Error value | Transition failed.
S_FALSE | Transition is not complete, but no error has occurred.

Remarks

This method is called before the filters are notified.

IDistributorNotify::Run

IDistributorNotify Interface

Called when the filter graph is entering a running state.

HRESULT Run(
REFERENCE_TIME tStart
);

Parameters
tStart
Stream-time offset that will be passed to every filter's IBaseFilter::Run parameter.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is called before the filters are notified.

IDistributorNotify::SetSyncSource

IDistributorNotify Interface

Called when a new clock is registered.

HRESULT SetSyncSource(
IReferenceClock * pClock
);

Parameters
pClock
[in] Pointer to the IReferenceClock interface.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is called before the filters are notified. Make sure to use AddRef on the pClock parameter if the plug-in distributor intends to hold it beyond this method call.

IDistributorNotify::Stop

IDistributorNotify Interface

Called when the filter graph is entering a stopped state.

HRESULT Stop(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value | Meaning
Error value | Transition failed.
S_FALSE | Transition is not complete, but no error has occurred.

Remarks

This method is called before the filters are notified.


IDvdControl Interface

The IDvdControl interface controls the playback and search mechanisms of a DVD title that contains one or more video movies.

The DVD file system is very different from a format such as CD-ROM, which contains a linear series of tracks not easily customizable by the author. The author of DVD-formatted media files can control track layout and navigation much more precisely; the media file itself has many parts and control mechanisms, which enables the author to arrange and rearrange the playback order as needed. You can locate a specific portion of a file by time (in hours, minutes, seconds, and frames) or by chapter value.

A media file is made up of a list of program chains (PGCs), each of which is made up of a list of programs, each of which is made up of a list of cells, each of which is made up of a list of video object units (VOBUs), each of which is made up of a list of packs, and each of which is made up of actual MPEG data.

To obtain a copy of the DVD-Video specification, "DVD Specifications for Read-Only Disc, Part 3, Video Specifications," contact Toshiba Corporation at 1-1, Shibaura 1-Chrome, Minato-ku, Tokyo 105-01, Japan, Tel. +81-3-5444-9580, Fax. +81-3-5444-9430.

When to Implement

This interface is implemented by the Microsoft® DirectShow™ DVD Navigator to enable DVD playback.

When to Use

Use this interface to control playback (set root drive, play, stop, and so forth) or use DVD-specific functionality such as menus and buttons when playing DVD-Video files.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDvdControl methods | Description
TitlePlay | Finds the media file with the specified title index and plays it back.
ChapterPlay | Plays the media file with the specified title index and chapter value.
TimePlay | Plays the media file with the specified title index, starting at the specified time.
StopForResume | Transitions playback to the DVD_DOMAIN_Stop state after saving resume information.
GoUp | Halts playback of the current media file and starts playback of the designated previous program chain (PGC).
TimeSearch | Halts playback of the current chapter and starts playback from the specified time in the same media file.
ChapterSearch | Halts playback of the current chapter and starts playback from the specified chapter value in the same media file.
PrevPGSearch | Halts playback of the current chapter and starts playback from the previous chapter within the title.
TopPGSearch | Halts playback of the current chapter and restarts playback of the current chapter within the title.
NextPGSearch | Halts playback of the current chapter and starts playback from the next chapter within the title.
ForwardScan | Search forward through the current disc at the specified speed.
BackwardScan | Search backward through the current disc at the specified speed.
MenuCall | Displays the specified menu on the screen.
Resume | Returns to playing back a title from a menu.
UpperButtonSelect | Selects the upper directional button from the displayed menu.
LowerButtonSelect | Selects the lower directional button from the displayed menu.
LeftButtonSelect | Selects the left directional button from the displayed menu.
RightButtonSelect | Selects the right directional button from the displayed menu.
ButtonActivate | Activates the selected button.
ButtonSelectAndActivate | Selects and activates the specified button.
StillOff | Resumes playback, cancelling still mode.
PauseOn | Pauses the current media file playback.
PauseOff | Unpauses the current media file playback.
MenuLanguageSelect | Sets the displayed language for navigation menus.
AudioStreamChange | Sets the current audio stream.
SubpictureStreamChange | Enables or disables picture-in-picture mode and sets the subpicture to the specified source.
AngleChange | Sets the new display angle.
ParentalLevelSelect | Sets the parental access level for the current media file.
ParentalCountrySelect | Sets the current country for controlling parental access levels.
KaraokeAudioPresentationModeChange | Sets the audio playback mode to karaoke.
VideoModePreferrence | Sets the video display mode the user prefers.
SetRoot | Sets the root directory containing the DVD-Video volume.
MouseActivate | Selects and activates a DVD button in response to a mouse click.
MouseSelect | Selects a DVD button in response to mouse movement.
ChapterPlayAutoStop | Start playing at the specified chapter within the specified title and play the number of chapters specified.

IDvdControl::AngleChange

IDvdControl Interface

Sets the new display angle.

HRESULT AngleChange(
ULONG ulAngle
);

Parameters
ulAngle
[in] Value of the new angle, which must be between 1 and 9.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::AudioStreamChange

IDvdControl Interface

Sets the current audio stream.

HRESULT AudioStreamChange(
ULONG nAudio
);

Parameters
nAudio
[in] Value that specifies the audio track to use, which must be between 0 and 7.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::BackwardScan

IDvdControl Interface

Search backward through the current disc at the specified speed.

HRESULT BackwardScan(
double dwSpeed
);

Parameters
dwSpeed
[in] Value that specifies how quickly DirectShow will search through the media file. This value is a multiplier, where 1.0 is the authored speed, so a value of 2.5 would search backward at two and one-half times the authored speed.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::ButtonActivate

IDvdControl Interface

Activates the selected button.

HRESULT ButtonActivate(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.

See Also

IDvdControl::ButtonSelectAndActivate

IDvdControl::ButtonSelectAndActivate

IDvdControl Interface

Selects and activates the specified button.

HRESULT ButtonSelectAndActivate(
ULONG uiButton
);

Parameters
uiButton
[in] Value that specifies the button that will be selected and activated, which must be between 1 and 36.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

Electronic remote control devices typically have a number of buttons that activate various functions of a DVD playback unit. Typically, you call this method when a user clicks a button on the control device; DirectShow then indicates that the button was selected (by playing a sound or changing a graphic, for example) and calls methods appropriate to which button was selected, such as ButtonActivate.

IDvdControl::ChapterPlay

IDvdControl Interface

Plays the media file with the specified title index and chapter value.

HRESULT ChapterPlay(
ULONG uiTitle,
ULONG uiChapter
);

Parameters
uiTitle
[in] Value that specifies the title number DirectShow will play back; this value must be between 1 and 99.
uiChapter
[in] Value that specifies the chapter within the specified title where DirectShow will start playback; this value must be between 1 and 999.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::ChapterPlayAutoStop

IDvdControl Interface

Instructs the DVD player to start playing at the specified chapter within the specified title and play the number of chapters specified.

HRESULT ChapterPlayAutoStop(
ULONG ulTitle,
ULONG ulChapter,
ULONG ulChaptersToPlay
);

Parameters
ulTitle
[in] Title number for playback.
ulChapter
[in] Chapter number to start playback.
ulChaptersToPlay
[in] Number of chapters to play from the start chapter.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

Chapters range from 1 to 999. See EC_DVD_CHAPTER_AUTOSTOP for more information.

IDvdControl::ChapterSearch

IDvdControl Interface

Halts playback of the current chapter and starts playback from the specified chapter within the same title.

HRESULT ChapterSearch(
ULONG Chapter
);

Parameters
Chapter
Chapter value that specifies the point where playback will begin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::ForwardScan

IDvdControl Interface

Search forward through the current disc at the specified speed.

HRESULT ForwardScan(
double dwSpeed
);

Parameters
dwSpeed
[in] Value that specifies how quickly DirectShow will search through the media file. This value is a multiplier, where 1.0 is the authored speed, so a value of 2.5 would search forward at two and one-half times the authored speed.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::GoUp

IDvdControl Interface

Halts playback of the current media file and starts playback of the designated previous program chain (PGC).

HRESULT GoUp(void);

Return Values

Returns an HRESULT value.

Remarks

Each PGC is associated with a previous PGC at authoring time, which this method sets as the new playback file.

IDvdControl::KaraokeAudioPresentationModeChange

IDvdControl Interface

Sets the audio playback mode to karaoke.

HRESULT KaraokeAudioPresentationModeChange(
ULONG ulMode
);

Parameters
ulMode
[in] Requested audio playback mode.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

Karaoke support is currently not implemented.

IDvdControl::LeftButtonSelect

IDvdControl Interface

Selects the left directional button from the displayed menu.

HRESULT LeftButtonSelect(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the left directional button.

"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.

IDvdControl::LowerButtonSelect

IDvdControl Interface

Selects the lower directional button from the displayed menu.

HRESULT LowerButtonSelect(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the lower directional button.

"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.

IDvdControl::MenuCall

IDvdControl Interface

Displays the specified menu on the screen.

HRESULT MenuCall(
DVD_MENU_ID MenuID
);

Parameters
MenuID
[in] Value that specifies the menu to display. Member of the DVD_MENU_ID enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::MenuLanguageSelect

IDvdControl Interface

Sets the displayed language for navigation menus.

HRESULT MenuLanguageSelect(
LCID LanguageCode
);

Parameters
LanguageCode
Value that specifies the new language.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

This method selects the default language for menus. Call this method only from the DVD stop state (DVD_DOMAIN_Stop). Applications specify languages with Windows standard LCIDs. LCIDs can be created from ISO-639 codes with:

MAKELCID( MAKELANGID(wISO639LangID ,SUBLANG_DEFAULT ), SORT_DEFAULT )

You might have to use 'jp' instead of 'ja' for the ISO639 code for Japanese if authored content uses 'jp' instead of 'ja' for Japanese or if MAKELANGID uses the wrong code for Japanese.

IDvdControl::MouseActivate

IDvdControl Interface

Selects and activates a DVD button in response to a mouse click.

HRESULT MouseActivate(
POINT point );

Parameters
point
[in] Specified point within the display window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

This method checks the specified point within the display window to see if it is within a current DVD button's highlight rectangle. If it is, this method selects and then activates the button.

DVD buttons do not all necessarily have highlight rectangles. Button rectangles can overlap, and the rectangles do not always correspond to the visual representation of DVD buttons.

IDvdControl::MouseSelect

IDvdControl Interface

Selects a DVD button in response to mouse movement.

HRESULT MouseSelect(
POINT point );

Parameters
point
[in] Specified point within the display window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

This method checks the specified point within the display window to see if it is within a current DVD button's highlight rectangle. If it is, this method selects the button.

DVD buttons do not all necessarily have highlight rectangles. Button rectangles can overlap, and the rectangles do not always correspond to the visual representation of DVD buttons.

IDvdControl::NextPGSearch

IDvdControl Interface

Halts playback of the current chapter and starts playback from the next chapter within the title.

HRESULT NextPGSearch(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::ParentalCountrySelect

IDvdControl Interface

Sets the current country for controlling parental access levels.

HRESULT ParentalCountrySelect(
WORD wCountry
);

Parameters
wCountry
[in] Value that specifies the current country according to the Alpha-2 Code defined in ISO3166 (except the code 'zz').
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

See Also

ParentalLevelSelect

IDvdControl::ParentalLevelSelect

IDvdControl Interface

Sets the parental access level for the current media file.

HRESULT ParentalLevelSelect(
ULONG ulParentalLevel
);

Parameters
ulParentalLevel
Value that specifies the current media file parental access level. Should be a value from 1 to 8, inclusive. Predefined parental levels are as follows.
1 | The rating is G, General.
3 | The rating is PG, Parental Guidance Suggested.
4 | The rating is PG13, Parental Guidance Suggested, not recommended for those under 13.
6 | The rating is R, Restricted.
7 | The rating is NC17.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

This method sets the current user's access level; this access level determines what media files the user can play back. Higher levels can play lower level content; lower levels can't play higher-level content. For example, adults can watch child-safe content, but children can't watch adult content.

The DVD Navigator filter provides no restriction on setting the parental level. DVD player applications can enforce restrictions on the parental level setting, such as providing password protection for raising the current parental level. Parental management in the DVD Navigator is disabled by default.

To disable parental management, pass 0xffffffff for ulParentalLevel. If parental management is disabled, then the player will play the first program chain (PGC) in a parental block regardless of parental IDs.

See Also

ParentalCountrySelect

IDvdControl::PauseOff

IDvdControl Interface

Unpauses the current media file playback, which returns it to normal playback.

HRESULT PauseOff(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

If the media file wasn't paused in playback, this method does nothing.

See Also

IDvdControl::PauseOn

IDvdControl::PauseOn

IDvdControl Interface

Pauses the current media file playback.

HRESULT PauseOn( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

This method freezes playback and any internal timers, similar to IMediaControl::Pause.

If the media file wasn't running, this method does nothing.

See Also

IDvdControl::PauseOff

IDvdControl::PrevPGSearch

IDvdControl Interface

Halts playback of the current chapter and starts playback from the previous chapter within the title.

HRESULT PrevPGSearch(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::Resume

IDvdControl Interface

Returns to playing back a title from a menu.

HRESULT Resume( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

If the file is stopped or already running, this method does nothing.

This method returns to title playback in DVD_DOMAIN_Title. Applications typically call this method after MenuCall which puts the DVD Navigator in DVD_DOMAIN_VideoTitleSetMenu or DVD_DOMAIN_VideoManagerMenu.

IDvdControl::RightButtonSelect

IDvdControl Interface

Selects the right directional button from the displayed menu.

HRESULT RightButtonSelect( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the right directional button.

"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.

IDvdControl::SetRoot

IDvdControl Interface

Sets the root directory containing the DVD-Video volume.

HRESULT SetRoot(
LPCWSTR pszPath );

Parameters
pszPath
[in] Directory name to set as the root directory.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | NULL pointer argument.
S_OK | Success.

Remarks

The current state must be DVD_DOMAIN_Stop when you call this method.

If you haven't set the root directory before calling IDvdControl::TitlePlay, the first drive starting from C: that contains a VIDEO_TS directory in the top level directory will be used as the root.

IDvdControl::StillOff

IDvdControl Interface

Resumes playback, cancelling still mode.

HRESULT StillOff( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

If the display image wasn't in still-store mode, this method does nothing.

IDvdControl::StopForResume

IDvdControl Interface

Transitions playback to the DVD_DOMAIN_Stop state after saving resume information.

HRESULT StopForResume(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

Remarks

If no file is playing or paused, this method does nothing.

The DVD Navigator filter transfers to the stopped state, but the filter graph remains in DirectShow's Run state.

IDvdControl::SubpictureStreamChange

IDvdControl Interface

Enables or disables picture-in-picture mode and sets the subpicture to the specified source.

HRESULT SubpictureStreamChange(
ULONG nSubPicture,
BOOL bDisplay
);

Parameters
nSubPicture
Value that specifies the source of the subpicture, which must be between 0 and 31, or 63.
bDisplay
Boolean value that specifies whether the subpicture is enabled; TRUE makes the subpicture visible and FALSE hides it.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::TimePlay

IDvdControl Interface

Plays the media file with the specified title index, starting at the specified time.

HRESULT TimePlay(
ULONG uiTitle,
ULONG bcdTime
);

Parameters
uiTitle
Value that specifies the title number DirectShow will play back; this value must be between 1 and 99.
bcdTime
Pointer to the DVD_TIMECODE structure where DirectShow will start playback.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::TimeSearch

IDvdControl Interface

Halts playback of the current chapter and starts playback from the specified time in the same media file.

HRESULT TimeSearch(
ULONG bcdTime
);

Parameters
bcdTime
Pointer to the DVD_TIMECODE structure where DirectShow will start playback.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::TitlePlay

IDvdControl Interface

Finds the media file with the specified title index and plays it back.

HRESULT TitlePlay(
ULONG uiTitle
);

Parameters
uiTitle
Value that specifies the title number DirectShow will play back; this value must be between 1 and 99.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::TopPGSearch

IDvdControl Interface

Halts playback of the current chapter and restarts playback of the current chapter within the title.

HRESULT TopPGSearch( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
E_UNEXPECTED | DVD is not initialized.
S_OK | Success.

IDvdControl::UpperButtonSelect

IDvdControl Interface

Selects the upper directional button from the displayed menu.

HRESULT UpperButtonSelect( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
S_OK | Success.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). This method tells DirectShow that something (the user, probably) triggered the upper directional button.

"Selecting" a DVD button simply highlights the button but does not "activate" the button. Selecting is the Windows equivalent of tabbing to a button but not pressing the space bar or enter key. Activating is the Windows equivalent of pressing the space bar or enter key after tabbing to a button.

IDvdControl::VideoModePreferrence

IDvdControl Interface

Sets the video display mode the user prefers.

HRESULT VideoModePreferrence(
ULONG ulPreferredDisplayMode
);

Parameters
ulPreferredDisplayMode
[in] Value that specifies the new display mode for DVD content. Member of the DVD_PREFERRED_DISPLAY_MODE enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
S_OK | Success.

Remarks

This method changes the default video window's aspect ratio, and may also specify a default aspect ratio conversion mechanism.


IDvdGraphBuilder Interface

The IDvdGraphBuilder interface enables you to easily build a filter graph for DVD-Video playback. This interface is implemented by the CDvdGraphBuilder COM object, which is part of qdvd.dll. An application can instantiate this COM object by calling CoCreateInstance on CLSID_DvdGraphBuilder to get back a pointer to the IDvdGraphBuilder interface. The application can then build a DVD-Video playback graph by calling the RenderDvdVideoVolume method, and thus get access to DVD-specific DirectShow interfaces such as IDvdInfo and IDvdControl as well generic DirectShow interfaces such as IAMLine21Decoder, IBasicVideo, IVideoWindow, and IBasicAudio (you only need this interface if an audio renderer is used to render audio, which is not the case with most decoders). The application can also get a pointer to the filter graph created by calling the RenderDvdVideoVolume method and then calling play, stop, or pause on the title. At the end, the application should release all the interfaces acquired through IDvdGraphBuilder methods as well as the IDvdGraphBuilder interface pointer.

Generally, you should not add, remove, connect, disconnect or access individual filters in the graph created by IDvdGraphBuilder::RenderDvdVideoVolume, since doing so may confuse the cleanup code. This interface is intended to help develop DVD-Video playback applications easily. If you need a very specific type of graph built for a particular solution, you should build a custom graph rather than use this interface and then change the resulting filter graph.

When to Implement

Do not implement this interface. DirectShow's DVD-Video graph builder object implements it for you.

When to Use

Use this interface in your application to build a filter graph for DVD-Video playback.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDvdGraphBuilder methods | Description
GetFiltergraph | Retrieves the IGraphBuilder interface for the filter graph used by the DVD-Video graph builder object.
GetDvdInterface | Retrieves specific interface pointers in the DVD-Video playback graph to make DVD-Video playback development easier.
RenderDvdVideoVolume | Completes building a filter graph according to user specifications for playing back a DVD-Video volume.

IDvdGraphBuilder::GetDvdInterface

IDvdGraphBuilder Interface

Retrieves specific interface pointers in the DVD-Video playback graph to make DVD-Video playback development easier.

HRESULT GetDvdInterface(
REFIID riid,
void **ppvIF
);

Parameters
riid
[in] IID of the required interface.
ppvIF
[out] Address of a pointer to the retrieved interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The current DirectShow implementation return values include the following:
Value | Meaning
E_INVALIDARG | The ppvIF parameter is invalid.
E_NOINTERFACE | The riid parameter value is not supported.
VFW_E_DVD_GRAPHNOTREADY | Graph has not been built through the IDvdGraphBuilder::RenderDvdVideoVolume method.

Remarks

You'll typically use this method to get the IDvdControl interface to control playback of a DVD-Video volume, or to get the IAMLine21Decoder interface to turn closed captioning on and off. You also use this method to get the IDvdInfo, IBasicVideo, IVideoWindow, and IBasicAudio interfaces. You only need a pointer to IBasicAudio if an audio renderer is used to render audio, which is not the case with most decoders.

Remember to release the interface by using the following code when you're done with it:

*ppvIF->Release();

IDvdGraphBuilder::GetFiltergraph

IDvdGraphBuilder Interface

Retrieves the IGraphBuilder interface for the filter graph used by the DVD-Video graph builder object.

HRESULT GetFiltergraph(
IGraphBuilder **ppGB
);

Parameters
ppGB
[out] Address of a pointer to the IGraphBuilder interface that the DVD-Video graph builder object is using.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if ppGB is invalid.

Remarks

Remember to release the IGraphBuilder interface by using the following code when you're done with it:

*ppGB->Release();

IDvdGraphBuilder::RenderDvdVideoVolume

IDvdGraphBuilder Interface

Completes building a filter graph according to user specifications for playing back a DVD-Video volume.

HRESULT RenderDvdVideoVolume(
LPCWSTR lpcwszPathName,
DWORD dwFlags,
AM_DVD_RENDERSTATUS *pStatus
);

Parameters
lpcwszPathName
[in] Path name for the DVD-Video volume to play. Can be NULL.
dwFlags
[in] Member of the AM_DVD_GRAPH_FLAGS enumerated data type indicating the type of decoder (hardware or software or a mix of hardware and software) to include in the filter graph. Maximum hardware decoding (AM_DVD_HWDEC_PREFER) is the default.
pStatus
[out] Pointer to the retrieved AM_DVD_RENDERSTATUS structure, which returns indication of any failure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation return values include the following:
Value | Meaning
E_INVALIDARG | The dwFlags parameter specifies conflicting options or pStatus is a bad pointer.
S_FALSE | Graph has been built, but not perfectly. The pStatus parameter provides details of the problem(s).
S_OK | Success. Playback graph built successfully, all streams rendered, and the DVD-Video volume was specified or found.
VFW_E_DVDDEC_NOTENOUGH | AM_DVD_HWDEC_ONLY or AM_DVD_SWDEC_ONLY was specified and there weren't enough hardware or software decoders to decode all streams.
VFW_E_DVDGRAPH_RENDERFAIL | Some basic error occurred in building the graph. Possibilities include the DVD Navigator filter or the video or audio renderer not instantiating, a trivial connection or pin enumeration failing, or none of the streams rendering.

Remarks

The AM_DVD_RENDERSTATUS structure reflects failure codes for this method. Reasons for this method returning S_FALSE include the following:

  • The graph has been completely built, but one of the following is true.
    • VPE mixing doesn't work (application didn't use the AM_DVD_NOVPE flag). In this case, the application will have enough information to tell the user that the video won't be visible unless a TV is connected to the NTSC out port of the DVD-Video decoder (presumably hardware decoder in this case).
    • Video decoder doesn't produce Line21 data. The application can put up a warning or informative message that closed captioning is not available because of the decoder.
    • No volume path specified and DVD Navigator didn't locate any DVD-Video volume to be played. Application can ask the user to insert a DVD-Video disc, if none is available in the drive when playback is started.
  • Some streams didn't render or didn't render completely. Volume can be partially played back. The application can indicate to the user that some of the streams can't be played.

This method builds the graph without any knowledge of the DVD-Video file or volume to play back. The DVD-Video graph builder builds the graph even if lpwszPathName is NULL or if the DVD Navigator filter does not find a default DVD-Video volume to play back. An application can later specify the volume by using the IDvdControl::SetRoot method.


IDvdInfo Interface

The IDvdInfo interface enables an application to query for attributes of available DVD titles and the DVD player status. It also allows for control of a DVD player beyond Annex J in the DVD specification.

When to Implement

Do not implement this interface.

When to Use

Use this interface in your application to retrieve details about a DVD-Video or about the current state of the DVD player filter graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDvdInfo methods | Description
GetCurrentDomain | Retrieves the current DVD domain of the DVD player.
GetCurrentLocation | Retrieves the current playback location.
GetTotalTitleTime | Retrieves the total playback time for the current title.
GetCurrentButton | Retrieves the number of available buttons and the currently selected button number.
GetCurrentAngle | Retrieves the number of available angles and the currently selected angle number.
GetCurrentAudio | Retrieves the number of available audio streams and the number of the currently selected audio stream.
GetCurrentSubpicture | Retrieves the number of available subpicture streams, the currently selected subpicture stream number, and whether the subpicture display is disabled.
GetCurrentUOPS | Retrieves which IDvdControl methods are valid.
GetAllSPRMs | Retrieves the current contents of all system parameter registers (SPRMs).
GetAllGPRMs | Retrieves the current contents of all general parameter registers (GPRMs).
GetAudioLanguage | Retrieves the language of the specified audio stream within the current title.
GetSubpictureLanguage | Retrieves the language of the specified subpicture stream within the current title.
GetTitleAttributes | Retrieves attributes of all video, audio, and subpicture streams for the specified title, including menus.
GetVMGAttributes | Retrieves attributes of all video, audio, and subpicture streams for video manager (VMG) menus.
GetCurrentVideoAttributes | Retrieves the current video attributes for the current title or menu.
GetCurrentAudioAttributes | Retrieves the attributes for the current audio stream in the current title or menu.
GetCurrentSubpictureAttributes | Retrieves the attributes for the current subpicture stream in the current title or menu.
GetCurrentVolumeInfo | Retrieves the current DVD volume information.
GetDVDTextInfo | Retrieves the TXTDT_MG structure, which can contain text descriptions for title name, volume name, producer name, vocalist name, and so on, in various languages.
GetPlayerParentalLevel | Retrieves the current parental level and country code settings for the DVD player.
GetNumberOfChapters | Retrieves the number of chapters that are defined for a given title.
GetTitleParentalLevels | Retrieves the parental levels that are defined for a particular title.
GetRoot | Retrieves the root directory that is set in the player.

IDvdInfo::GetAllGPRMs

IDvdInfo Interface

Retrieves the current contents of all general parameter registers (GPRMs).

HRESULT GetAllGPRMs(
GPRMARRAY *pRegisterArray );

Parameters
pRegisterArray
[out] Pointer to the retrieved array of general parameter registers (GPRMARRAY).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

Use of GPRMs is title specific. GPRMs are general parameter registers. See the DVD specifications for an explanation of GPRMs.

IDvdInfo::GetAllSPRMs

IDvdInfo Interface

Retrieves the current contents of all system parameter registers (SPRMs).

HRESULT GetAllSPRMs(
SPRMARRAY *pRegisterArray );

Parameters
pRegisterArray
[out] Pointer to the retrieved array of system parameter registers (SPRMARRAY).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

See the DVD-Video specification for use of individual registers.

IDvdInfo::GetAudioLanguage

IDvdInfo Interface

Retrieves the language of the specified audio stream within the current title.

HRESULT GetAudioLanguage(
ULONG nStream,
LCID *pLanguage );

Parameters
nStream
[in] Stream number.
pLanguage
[out] Pointer to the retrieved language.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

This method does not return languages for menus. This method sets the value pointed to by pLanguage to zero if the stream does not include language. Call the Win32 GetLocaleInfo API as follows to create a human-readable string name from pLanguage:

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo::GetCurrentAngle

IDvdInfo Interface

Retrieves the number of available angles and the currently selected angle number.

HRESULT GetCurrentAngle(
ULONG *pnAnglesAvailable,
ULONG *pnCurrentAngle );

Parameters
pnAnglesAvailable
[out] Pointer to the retrieved number of available angles. If the value pointed to equals 1, then the current video does not contain multiple angles.
pnCurrentAngle
[out] Pointer to the retrieved current angle number.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

Angles are interleaved video streams that presumably contain the same scene shot from different camera angles.

This method returns an error unless the domain is DVD_DOMAIN_Title.

IDvdInfo::GetCurrentAudio

IDvdInfo Interface

Retrieves the number of available audio streams and the number of the currently selected audio stream.

HRESULT GetCurrentAudio(
ULONG *pnStreamsAvailable,
ULONG *pnCurrentStream );

Parameters
pnStreamsAvailable
[out] Pointer to the retrieved number of available audio streams
pnCurrentStream
[out] Pointer to the current stream number.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

This method returns an error unless the domain is DVD_DOMAIN_Title.

IDvdInfo::GetCurrentAudioAttributes

IDvdInfo Interface

Retrieves the attributes for the current audio stream in the current title or menu.

HRESULT GetCurrentAudioAttributes(
DVD_AudioATR *pATR );

Parameters
pATR
[out] Pointer to the retrieved audio attributes.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

See the DVD-Video specification for information about DVD_AudioATR.

IDvdInfo::GetCurrentButton

IDvdInfo Interface

Retrieves the number of available buttons and the currently selected button number.

HRESULT GetCurrentButton(
ULONG *pnButtonsAvailable,
ULONG *pnCurrentButton );

Parameters
pnButtonsAvailable
[out] Pointer to the number of buttons available.
pnCurrentButton
[out] Pointer to the number of the current button.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

If buttons are not present this method returns zero for both pnButtonsAvailable and pnCurrentButton.

IDvdInfo::GetCurrentDomain

IDvdInfo Interface

Retrieves the current DVD domain of the DVD player.

HRESULT GetCurrentDomain(
DVD_DOMAIN *pDomain );

Parameters
pDomain
[out] Pointer to the current domain which is a member of the DVD_DOMAIN enumerated type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Typical return values might include one of the following:
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Input argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Out of memory (insufficient buffer space).
E_POINTER | NULL pointer argument.
E_UNEXPECTED | DVD is not initialized or domain is not DVD_DOMAIN_Title.
VFW_E_DVD_OPERATION_INHIBITED | Requested action cannot occur at this point in the movie due to the authoring of the current DVD-Video disc.
S_OK | Success.
VFW_E_DVD_INVALIDDOMAIN | Requested action is not supported on this domain (DVD_DOMAIN).

IDvdInfo::GetCurrentLocation

IDvdInfo Interface

Retrieves the current playback location.

HRESULT GetCurrentLocation(
DVD_PLAYBACK_LOCATION *pLocation );

Parameters
pLocation
[out] Pointer to the retrieved playback location information in a DVD_PLAYBACK_LOCATION structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

The default implementation of this method returns E_UNEXPECTED if the current domain is not DVD_DOMAIN_Title.

Remarks

This method retrieves information sufficient to restart playback of a video from the current playback location in titles that don't explicitly disable seeking to the current location.

This method returns an error unless the domain is DVD_DOMAIN_Title.

IDvdInfo::GetCurrentSubpicture

IDvdInfo Interface

Retrieves the number of available subpicture streams, the currently selected subpicture stream number, and whether the subpicture display is disabled.

HRESULT GetCurrentSubpicture(
ULONG *pnStreamsAvailable,
ULONG *pnCurrentStream,
BOOL *pIsDisabled );

Parameters
pnStreamsAvailable
[out] Pointer to the retrieved number of available subpicture streams.
pnCurrentStream
[out] Pointer to the retrieved number of the currently selected subpicture stream.
pIsDisabled
[out] Pointer to a value indicating whether the subpicture display is disabled.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

Subpicture streams authored as forcedly activated streams will be displayed even if the application has disabled subpicture display with the IDvdControl::SubpictureStreamChange method.

This method returns an error unless the domain is DVD_DOMAIN_Title.

IDvdInfo::GetCurrentSubpictureAttributes

IDvdInfo Interface

Retrieves the attributes for the current subpicture stream in the current title or menu.

HRESULT GetCurrentSubpictureAttributes(
DVD_SubpictureATR *pATR );

Parameters
pATR
[out] Pointer to the retrieved subpicture attributes.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

See the DVD-Video specification for information about DVD_SubpictureATR.

IDvdInfo::GetCurrentUOPS

IDvdInfo Interface

Retrieves which IDvdControl methods are currently valid.

HRESULT GetCurrentUOPS(
VALID_UOP_SOMTHING_OR_OTHER *pUOP );

Parameters
pUOP
[out] Pointer to a DWORD containing the retrieved valid user operations (UOP).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

This method is useful because DVD titles can enable or disable individual user operations at almost any point during playback.

IDvdInfo::GetCurrentVideoAttributes

IDvdInfo Interface

Retrieves the current video attributes for the current title or menu.

HRESULT GetCurrentVideoAttributes(
DVD_VideoATR *pATR );

Parameters
pATR
[out] Pointer to the retrieved video attributes.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

See the DVD-Video specification for information about DVD_VideoATR.

IDvdInfo::GetCurrentVolumeInfo

IDvdInfo Interface

Retrieves the current DVD volume information.

HRESULT GetCurrentVolumeInfo(
ULONG *pNumOfVol,
ULONG *pThisVolNum,
DVD_DISC_SIDE *pSide,
ULONG *pNumOfTitles );

Parameters
pNumOfVol
[out] Pointer to the retrieved number of volumes in the volume set.
pThisVolNum
[out] Pointer to the retrieved volume number for this root directory.
pSide
[out] Pointer to the retrieved current disc side (DVD_DISC_SIDE).
pNumOfTitles
[out] Pointer to the retrieved number of titles available in this volume.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

IDvdInfo::GetDVDTextInfo

IDvdInfo Interface

Retrieves the TXTDT_MG structure, which can contain text descriptions for title name, volume name, producer name, vocalist name, and so on, in various languages.

HRESULT GetDVDTextInfo(
BYTE *pTextManager,
ULONG cbBufSize,
ULONG *pcbActualSize );

Parameters
pTextManager
[out, size_is(cbBufSize)] Pointer to the retrieved text manager.
cbBufSize
[in] Size of the buffer for pTextManager, in bytes.
pcbActualSize
[out] Pointer to a value containing the number of bytes of data returned.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

If the supplied buffer size in cbBufSize is too small for the data, (for example if cbBufSize equals zero), then this method returns E_OUTOFMEMORY and sets the value pointed to by pcbActualSize to the required size.

Refer to Section 4.1.6 and Annex A of the DVD-Video specification for more information.

IDvdInfo::GetNumberOfChapters

IDvdInfo Interface

Retrieves the number of chapters that are defined for a given title.

HRESULT GetNumberOfChapters(
ULONG ulTitle,
ULONG *pNumberOfChapters
);

Parameters
ulTitle
[in] Title for which to retrieve the number of chapters.
pNumberOfChapters
[out] Retrieved number of chapters for the specified title.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

IDvdInfo::GetPlayerParentalLevel

IDvdInfo Interface

Retrieves the current parental level and country code settings for the DVD player.

HRESULT GetPlayerParentalLevel(
ULONG *pParentalLevel,
ULONG *pCountryCode
);

Parameters
pParentalLevel
[out] Pointer to a value indicating the current parental level.
pCountryCode
[out] Pointer to a value indicating the current country code.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

See Table 3.3.4-1 of the DVD-Video specification for the defined parental levels.

See ISO3166 : Alpha-2 Code for the country codes.

Valid Parental Levels are 1 through 8 if parental management is enabled, 0xffffffff if parental management is disabled.

IDvdInfo::GetRoot

IDvdInfo Interface

Retrieves the root directory that is set in the player.

HRESULT GetRoot(
LPTSTR pRoot,
ULONG cbBufSize,
ULONG *pcbActualSize
);

Parameters
pRoot
[out, size_is(cbBufSize)] Pointer to the buffer to receive the root string.
cbBufSize
[in] Size of buffer passed in, in bytes.
pcbActualSize
[out] Pointer to a value containing the size of the actual data returned.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

If a valid root was found, this method returns the root string. Otherwise, it returns zero for pcbActualSize, indicating that a valid root directory has not been found or initialized.

IDvdInfo::GetSubpictureLanguage

IDvdInfo Interface

Retrieves the language of the specified subpicture stream within the current title.

HRESULT GetSubpictureLanguage(
ULONG nStream,
LCID *pLanguage );

Parameters
nStream
[in] Stream number.
pLanguage
[out] Pointer to the retrieved language.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

This method does not return languages for menus. This method sets the value pointed to by pLanguage to zero if the stream does not include language. Call the Win32 GetLocaleInfo API as follows to create a human-readable string name from pLanguage.

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

This method returns an error unless the domain is DVD_DOMAIN_Title.

IDvdInfo::GetTitleAttributes

IDvdInfo Interface

Retrieves attributes of all video, audio, and subpicture streams for the specified title, including menus.

HRESULT GetTitleAttributes(
ULONG nTitle,
DVD_ATR *pATR );

Parameters
nTitle
[in] Requested title number. Specify 0xFFFFFFFF for the current title.
pATR
[out] Pointer to the retrieved attributes structure (DVD_ATR).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

IDvdInfo::GetTitleParentalLevels

IDvdInfo Interface

Retrieves the parental levels that are defined for a particular title.

HRESULT GetTitleParentalLevels(
ULONG ulTitle,
ULONG *pParentalLevels
);

Parameters
ulTitle
[in] Title for which parental levels are requested.
pParentalLevels
[out] Logical OR combination of the parental levels defined for the title. Valid parental levels are DVD_PARENTAL_LEVEL_8, DVD_PARENTAL_LEVEL_6, and DVD_PARENTAL_LEVEL_1.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

IDvdInfo::GetTotalTitleTime

IDvdInfo Interface

Retrieves the total playback time for the current title.

HRESULT GetTotalTitleTime(
ULONG *pTotalTime );

Parameters
pTotalTime
[out] Pointer to the total time in DVD_TIMECODE format, which includes hours, minutes, seconds, and frames.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

The method is restricted to simple linear movies by design.

IDvdInfo::GetVMGAttributes

IDvdInfo Interface

Retrieves attributes of all video, audio, and subpicture streams for video manager (VMG) menus.

HRESULT GetVMGAttributes(
DVD_ATR *pATR );

Parameters
pATR
[out] Pointer to the retrieved attributes structure (DVD_ATR).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. See IDvdInfo::GetCurrentDomain for a list of typical return values for the methods exposed by this interface.

Remarks

The video manager contains a separate group of streams, such as the DVD_MENU_Title menus and are not associated with any particular title number.


IEnumFilters Interface

The IFilterGraph::EnumFilters method returns the enumerator interface. It is based on the COM IEnum style of enumerators.

When to Implement

This interface is implemented on the filter graph manager and is not intended for implementation by developers.

When to Use

This interface is used by applications or other filters to determine what filters exist in the filter graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IEnumFilters methods | Description
Next | Retrieves the specified number of filters in the enumeration sequence.
Skip | Skips a specified number of filters in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Clone | Retrieves a duplicate enumerator containing the same enumeration state as the current one.

IEnumFilters::Clone

IEnumFilters Interface

Retrieves a duplicate enumerator containing the same enumeration state as the current one.

HRESULT Clone(
IEnumFilters ** ppEnum
);

Parameters
ppEnum
[out] Duplicate of the enumerator.
Return Values

No return value.

Remarks

This method produces two enumerators (the original and the duplicate); both are set at the same filter. After they are created, however, they are independent; therefore, calling the IEnumFilters::Next method for one does not affect the other.

IEnumFilters::Next

IEnumFilters Interface

Retrieves the specified number of filters in the enumeration sequence.

HRESULT Next(
ULONG cFilters,
IBaseFilter ** ppFilter,
ULONG * pcFetched
);

Parameters
cFilters
[in] Number of filters to place.
ppFilter
[out] Array in which to place IBaseFilter pointers.
pcFetched
[out] Actual number of filters placed in the array.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IEnumFilters::Reset

IEnumFilters Interface

Resets the enumeration sequence to the beginning.

HRESULT Reset(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method affects the return value of the next call to the IEnumFilters::Next method.

IEnumFilters::Skip

IEnumFilters Interface

Skips a specified number of filters in the enumeration sequence.

HRESULT Skip(
ULONG cFilter
);

Parameters
cFilter
[in] Number of filters to skip.
Return Values

No return value.

Remarks

This method affects the return value of the next call to the IEnumFilters::Next method.


IEnumMediaTypes Interface

The IEnumMediaTypes interface enumerates the preferred formats for a pin.

When to Implement

This interface must be implemented and made available by the IPin::EnumMediaTypes method. The CBasePin::EnumMediaTypes member function automatically does this in the DirectShow™ class library and uses the CEnumMediaTypes class to create the enumerator object.

When to Use

This interface is normally used by a connecting pin to determine the media type when negotiating a connection. It can also be passed through to other pins, either upstream or downstream of the filter, when intervening filters do not have a list of preferred media types. For example, a transform-inplace filter might pass the IEnumMediaTypes interface of a downstream input pin to the connecting output pin of the upstream filter, instead of providing its own IEnumMediaTypes interface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IEnumMediaTypes methods | Description
Next | Retrieves the specified number of items in the enumeration sequence.
Skip | Skips a specified number of elements in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Clone | Returns another enumerator containing the same enumeration state as the current one.

IEnumMediaTypes::Clone

IEnumMediaTypes Interface

Returns another enumerator containing the same enumeration state as the current one.

HRESULT Clone(
IEnumMediaTypes ** ppEnum
);

Parameters
ppEnum
[out] New copy of the enumerator.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IEnumMediaTypes::Next

IEnumMediaTypes Interface

Retrieves the specified number of items in the enumeration sequence.

HRESULT Next(
ULONG cMediaTypes,
AM_MEDIA_TYPE ** ppMediaTypes,
ULONG * pcFetched
);

Parameters
cMediaTypes
[in] Number of media types to place.
ppMediaTypes
[out] Array in which to place the pointers to the next media type.
pcFetched
[out] Actual count passed.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

To use this method, pass an array of pointers to media types. (If you want only a single media type, you can pass a pointer to a media type pointer in place of an array of media type pointers.) The interface allocates the necessary AM_MEDIA_TYPE structures and initializes them with the variable format block. Free each media type by calling DeleteMediaType, which will free the format block and the media type itself.

IEnumMediaTypes::Reset

IEnumMediaTypes Interface

Resets the enumerator to the beginning so that the next call to the IEnumMediaTypes::Next method returns, at a minimum, the first media type (if any) in the enumeration.

HRESULT Reset(void);

Return Values

Returns S_OK if successful; otherwise, returns S_FALSE.

IEnumMediaTypes::Skip

IEnumMediaTypes Interface

Skips a specified number of elements in the enumeration sequence.

HRESULT Skip(
ULONG cMediaTypes
);

Parameters
cMediaTypes
[in] Number of media type elements to skip.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.


IEnumPins Interface

The IBaseFilter::EnumPins method returns this interface. It is based on the IEnumX protocol of the Component Object Model (COM).

Note that actions that cause the number of pins to change might cause the enumerator to fail.

When to Implement

This interface must be implemented and made available by the IBaseFilter::EnumPins method. The CBaseFilter::EnumPins member function automatically does this in the DirectShow™ class library and uses the CEnumPins class to create the enumerator object.

When to Use

This interface is normally used by the filter graph manager when connecting filters. It can, however, be used by an application that must find the pins associated with filters in the filter graph—for example, to add another filter to the graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IEnumPins methods | Description
Next | Puts pointers to IPin interfaces for the next pins into the specified array.
Skip | Skips the specified number of pins.
Reset | Resets the position to the beginning so that the next call to the IEnumPins::Next method returns, at a minimum, the first pin of the filter.
Clone | Provides another enumerator, which is a duplicate of the current one.

IEnumPins::Clone

IEnumPins Interface

Makes a copy of the enumerator. This allows the calling application to retain two positions in the list of pins.

HRESULT Clone(
IEnumPins ** ppEnum
);

Parameters
ppEnum
[out] New enumerator, which is a copy of this enumerator.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IEnumPins::Next

IEnumPins Interface

Places pointers to IPin interfaces into the specified array.

HRESULT Next(
ULONG cPins,
IPin ** ppPins,
ULONG * pcFetched
);

Parameters
cPins
[in] Number of pins to place.
ppPins
[out] Array in which to place the interface pointers.
pcFetched
[out] Actual number of pins placed in the array.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IEnumPins::Reset

IEnumPins Interface

Resets the enumerator to the beginning so that the next call to the IEnumPins::Next method returns, at a minimum, the first pin of the filter.

HRESULT Reset(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IEnumPins::Skip

IEnumPins Interface

Skips the specified number of pins.

HRESULT Skip(
ULONG cPins
);

Parameters
cPins
[in] Number of pins to skip.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method affects the next call to the IEnumPins::Next method.


IEnumRegFilters Interface

The purpose of the mapper is to help the filter graph manager avoid loading filters when attempting to build a filter graph to render a given media type. By looking at filter properties recorded in the registry, the number of filters that must be loaded and tried can be reduced.

The IFilterMapper::EnumMatchingFilters method returns the enumerator that enumerates the filters that match specific requirements. The enumerator returns descriptors of filters, including the globally unique identifiers (GUIDs) that the Microsoft® Win32® CoCreateInstance function can instantiate. The filters are not loaded. The IEnumRegFilters interface is a Component Object Model (COM) enumerator.

When to Implement

This interface is implemented by the filter mapper and need not be implemented elsewhere.

When to Use

Although the filter graph manager is the primary user of this interface, applications can also use it to determine available filters in the system — for example, to construct a unique filter graph by adding and connecting filters itself, or to allow users to choose from a list of available filters.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IEnumRegFilters methods | Description
Next | Fills an array with the next filters that meet the requirements.
Skip | Skips a specified number of elements in the enumeration sequence.
Reset | Makes the Next method start again, beginning at the first filter.
Clone | Returns another enumerator containing the same enumeration state as the current one.

IEnumRegFilters::Clone

IEnumRegFilters Interface

Creates another enumerator with the same enumeration state as the current one.

HRESULT Clone(
IEnumRegFilters **ppEnum
);

Parameters
ppEnum
[out] Pointer to the duplicate enumerator interface.
Return Values

Returns an HRESULT value. Currently returns E_NOTIMPL.

Remarks

Currently, this method is not implemented.

IEnumRegFilters::Next

IEnumRegFilters Interface

Fills the array with descriptions of the next set of filters (specified by the cFilters parameter) that meet the requirements specified upon creation of the enumerator.

HRESULT Next(
ULONG cFilters,
REGFILTER ** apRegFilter,
ULONG * pcFetched
);

Parameters
cFilters
[in] Number of filters.
apRegFilter
[out] Pointer to an array of REGFILTER pointers.
pcFetched
[out] Actual number of filters passed.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The calling application must use the Microsoft Win32 CoTaskMemFree function to free each REGFILTER pointer returned in the array. Do not free the Name member of the REGFILTER structure separately, because IEnumRegFilters::Next allocates memory for this string as part of the REGFILTER structure.

IEnumRegFilters::Reset

IEnumRegFilters Interface

Resets the enumerator so that the next call to the IEnumRegFilters::Next method begins again at the first filter, if any.

HRESULT Reset(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IEnumRegFilters::Skip

IEnumRegFilters Interface

Skips a specified number of items in the enumeration sequence.

HRESULT Skip(
ULONG celt
);

Parameters
celt
[in] Number of items to skip.
Return Values

Returns an HRESULT value. Currently returns E_NOTIMPL.

Remarks

Currently, this method is not implemented.


IFileClip Interface

The IFileClip interface provides a simple way for an application to create one or more cuts from a single media file, or to create blank cuts. Blank (empty or null) cuts are useful to either stop playback for a specified time, or to make a placeholder for a cut that the cutlist can't play.

See About Cutlists and Using Cutlists for more information.

When to Implement

Do not implement this interface. DirectShow implements it for you.

When to Use

Use this interface in your application when you want to provide cutlist functionality to the user.

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFileClip methods | Description
SetFileAndStream | Initializes the clip object with the specified media file and stream number or makes an empty clip for producing null elements.
CreateCut | Creates a cutlist element.
GetMediaType | Retrieves the clip's media type structure.

IFileClip::CreateCut

IFileClip Interface

Creates a cutlist element.

HRESULT CreateCut(
IAMCutListElement **ppElement,
REFERENCE_TIME mtTrimIn,
REFERENCE_TIME mtTrimOut,
REFERENCE_TIME mtOrigin,
REFERENCE_TIME mtLength,
REFERENCE_TIME mtOffset
);

Parameters
ppElement
[out] Address of a pointer to the IAMCutListElement interface of the created cutlist element.
mtTrimIn
[in] Trimin (beginning) position for the cut.
mtTrimOut
[in] Trimout (ending) position for the cut.
mtOrigin
[in] Clip origin. Must be zero.
mtLength
[in] Length of clip. Must be mtTrimOut minus mtTrimIn.
mtOffset
[in] Offset of clip. Must be zero.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

All of the times specified in this method are relative to the media clip rather than to the cutlist.

To make an empty cut, first create an empty (null) clip by calling the IFileClip::SetFileAndStream method as illustrated by the following code fragment. Then, create a cut of the desired duration (n) to indicate you want to do nothing for n units of time.

IAMCutListElement *pElement;

SetFileAndStream(NULL, -1);
CreteCut(&pElement, 0, n, 0, n, 0);

See Using Cutlists for more information about using cutlists and the cutlist interfaces from an application.

IFileClip::GetMediaType

IFileClip Interface

Retrieves the clip's media type structure.

HRESULT GetMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
[out] Pointer to the AM_MEDIA_TYPE structure describing the video clip.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

IFileClip::SetFileAndStream

IFileClip Interface

Initializes the clip object with the specified media file and stream number or makes an empty clip for producing null elements.

HRESULT SetFileAndStream(
LPWSTR wstrFileName,
DWORD streamNum
);

Parameters
wstrFileName
[in] Name of the file from which to initialize the clip. Must be an AVI or .wav file. Specify NULL to make an empty (null) clip.
streamNum
[in] Stream number (AVI files only) within the specified file from which to initialize the clip. Must be zero. AVI files with more than one stream of any type are not supported; clips must be from the first stream (stream 0). Specify –1 for empty elements.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

This method opens the file to verify the format and media type (which you can find by using the IFileClip::GetMediaType method).

Use the following call to make an empty clip.

SetFileAndStream(NULL, -1);


IFileSinkFilter Interface

The IFileSinkFilter interface is implemented on filters that write media streams to a file. A file sink filter in a video capture filter graph, for instance, writes the output of the video compression filter to a file. Typically, the application running this filter graph will want to allow the user to enter the name of the file to be written to. This interface enables the communication of this information.

IFileSinkFilter2 replaces this interface unless you need to maintain backward compatibility with ActiveMovie 1.0.

When to Implement

If a filter needs the name of an output file, it should expose this interface to allow an application to set the file name. Note that there is currently no base class implementation of this interface.

When to Use

Any application that must set the name of the file into which the file sink filter will write should use this interface to get and set the file name.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFileSinkFilter methods | Description
SetFileName | Sets the name of the file into which media samples will be written.
GetCurFile | Retrieves the name of the current file into which media samples will be written (the sink file).

IFileSinkFilter::GetCurFile

IFileSinkFilter Interface

Retrieves the name of the current file into which media samples will be written (the sink file).

HRESULT GetCurFile(
LPOLESTR *ppszFileName,
AM_MEDIA_TYPE *pmt
);

Parameters
ppszFileName
[out] Name of the file set to receive media samples.
pmt
Type of media samples to be written to the file.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

If a file name is not assigned, this method returns E_FAIL.

IFileSinkFilter::SetFileName

IFileSinkFilter Interface

Sets the name of the file into which media samples will be written.

HRESULT SetFileName(
LPCOLESTR pszFileName,
const AM_MEDIA_TYPE *pmt
);

Parameters
pszFileName
[in] Name of the file to receive the media samples.
pmt
[in] Type of media samples to be written to the file, and the media type of the sink filter's input pin.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

If the pszFileName parameter names a nonexistent file, the file will be created. If it names an existing file, the sink filter will overwrite the file without first deleting it.


IFileSinkFilter2 Interface

The IFileSinkFilter2 interface derives from the IFileSinkFilter interface and replaces it unless you need backward compatibility with ActiveMovie™ 1.0. Like IFileSinkFilter, filters that write media streams to a file implement this interface. A file sink filter in a video capture filter graph, for instance, saves the output of the video compression filter to a file. Typically, the application running this filter graph should allow the user to enter the name of the file to which to save the data. This interface enables you to communicate this information. IFileSinkFilter2 adds the option to determine whether the file it writes should destroy an existing file of the same name. In the video capture case, do not destroy a file you've already created, because preallocating file space takes valuable time. By default, the new file does not destroy the old one. Otherwise, destroy the original file to make sure the file you author doesn't contain garbage.

When to Implement

A filter should implement this interface when it needs the name of an output file or needs to set options for that file. Implement the older IFileSinkFilter interface if you need to make your filter compatible with ActiveMovie 1.0. Note that there is currently no base class implementation of this interface.

When to Use

When an application must set the name of the file into which the file sink filter will write, it should use this interface to get and set the file name or change options. Use the older IFileSinkFilter interface if you need to make your application compatible with ActiveMovie 1.0.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFileSinkFilter methods | Description
SetFileName | Sets the name of the file into which media samples will be written.
GetCurFile | Retrieves the name of the current file into which media samples will be written (the sink file).
IFileSinkFilter2 methods | Description
SetMode | Determines whether the file writer destroys the file when it creates the new one.
GetMode | Retrieves whether the file writer destroys the file when it creates the new one.

IFileSinkFilter2::GetMode

IFileSinkFilter2 Interface

Retrieves whether the file writer destroys the file when it creates the new one.

HRESULT GetMode(
DWORD *dwFlags
);

Parameters
dwFlags
[out] Pointer to the retrieved flags. Currently, the only defined flag is AM_FILE_OVERWRITE, which indicates that the file should be destroyed; zero indicates that the file will be left alone.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IFileSinkFilter2::SetMode

IFileSinkFilter2 Interface

Determines whether the file writer destroys the file when it creates the new one.

HRESULT SetMode(
DWORD dwFlags
);

Parameters
dwFlags
[in] Currently, the only defined flag is AM_FILE_OVERWRITE, which indicates that the file writer should destroy the file. Specify zero for dwFlags to leave the file alone.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.


IFileSourceFilter Interface

The IFileSourceFilter interface is exposed by source filters to set the file name and media type of the media file that they are to render. It is an abbreviated version of the COM IPersistFile interface. If the file has a type that can be determined by the algorithm described in Registering a Custom File Type, the recommended file source filter CLSID is used when the filter graph manager attempts to render the filter graph.

When to Implement

If a filter needs the name of a file to open, it should expose this interface to allow an application to set the file name. Note that there is no base class implementation of this interface.

When to Use

An application that inserts file source filters directly must query for this interface and set the file name. Normally, the filter graph manager uses this interface when an application calls IGraphBuilder::RenderFile. The Graphedt.exe tool queries for the IFileSourceFilter interface and prompts for a file name if it finds it.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFileSourceFilter methods | Description
Load | Loads the source filter with the file.
GetCurfile | Retrieves the current file.

IFileSourceFilter::GetCurfile

IFileSourceFilter Interface

Collects information about the file to open.

HRESULT GetCurfile(
LPOLESTR *ppszFileName,
AM_MEDIA_TYPE *pmt
);

Parameters
ppszFileName
[out] Path to the loaded file.
pmt
[out] Media type.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IFileSourceFilter::Load

IFileSourceFilter Interface

Loads a media file.

HRESULT Load(
LPCOLESTR pszFileName,
const AM_MEDIA_TYPE *pmt
);

Parameters
pszFileName
[in] Absolute path of the file to open.
pmt
[in] Media type of the file. This can be NULL.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This is an initialization method for the interface. It is not designed to load multiple files, and any calls to this method after the first call will fail.

You should implement this method to load the file specified by pszFileName.

Note that the name in pszFileName need not actually be a disk file name (that is, one you could pass to the Microsoft® Win32® CreateFile function, for example). It could also be a URL name. The URL moniker filter uses IFileSourceFilter to retrieve its URL name, and IGraphBuilder::AddSourceFilter (and hence IGraphBuilder::RenderFile) handles this correctly. IGraphBuilder::AddSourceFilter returns a specific error (ERROR_FILE_NOT_FOUND) upon not finding the file, which indicates that the file specified does not exist and not that the filter does not exist.


IFilterGraph Interface

The IFilterGraph interface is an abstraction representing a graph of filters. All filters in the graph share the same clock. They might or might not also be connected and stream data between them. This interface allows filters to be joined into a graph and operated as a unit. Unlike the IGraphBuilder interface, this interface does not use heuristics to connect and build the filter graph.

When to Implement

This interface is implemented on the filter graph manager and is not intended for implementation by developers.

When to Use

Applications should not use this interface directly but instead should use the IGraphBuilder interface, which inherits this interface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterGraph methods | Description
AddFilter | Adds a filter to the graph and gives it a name.
RemoveFilter | Removes a filter from the graph.
EnumFilters | Provides an enumerator for all filters in the graph.
FindFilterByName | Finds a filter that was added with a specified name.
ConnectDirect | Connects the two IPin objects directly (without intervening filters).
Reconnect | Breaks the existing pin connection and reconnects it to the same pin.
Disconnect | Disconnects this pin, if connected.
SetDefaultSyncSource | Sets the default synchronization source (a clock).

IFilterGraph::AddFilter

IFilterGraph Interface

Adds a filter to the graph and names it by using the pName parameter.

HRESULT AddFilter(
IBaseFilter * pFilter,
LPCWSTR pName
);

Parameters
pFilter
[in] Filter to add to the graph.
pName
[in] Name of the filter.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The name of the filter can be NULL, in which case the filter graph manager will generate a name. If the name is not NULL and is not unique, this method will modify the name in an attempt to generate a new unique name. If this is successful, this method returns VFW_S_DUPLICATE_NAME. If it cannot generate a unique name, it returns VFW_E_DUPLICATE_NAME.

AddFilter calls the filter's IBaseFilter::JoinFilterGraph method to inform the filter that it has been added. AddFilter must be called before attempting to use the IGraphBuilder::Connect, IFilterGraph::ConnectDirect, or IGraphBuilder::Render method to connect or render pins belonging to the added filter.

IFilterGraph::ConnectDirect

IFilterGraph Interface

Connects the two pins directly (without intervening filters).

HRESULT ConnectDirect(
IPin * ppinOut,
IPin * ppinIn,
const AM_MEDIA_TYPE * pmt
);

Parameters
ppinOut
[in] Output pin.
ppinIn
[in] Input pin.
pmt
[in] Media type to use for the connection (optional; that is, can be NULL).
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IFilterGraph::Disconnect

IFilterGraph Interface

Disconnects this pin.

HRESULT Disconnect(
IPin * ppin
);

Parameters
ppin
[in] Pin to disconnect.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method does not completely break the connection. To completely break the connection, both ends must be disconnected.

This method results in a successful no operation (no-op) if the pin is not connected.

IFilterGraph::EnumFilters

IFilterGraph Interface

Provides an enumerator for all filters in the graph.

HRESULT EnumFilters(
IEnumFilters ** ppEnum
);

Parameters
ppEnum
[out] Enumerator.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IFilterGraph::FindFilterByName

IFilterGraph Interface

Finds a filter that was added to the filter graph with a specific name.

HRESULT FindFilterByName(
LPCWSTR pName,
IBaseFilter ** ppFilter
);

Parameters
pName
[in, string] Name to search for.
ppFilter
[out] Pointer to an IBaseFilter interface on the found filter.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This function fails and sets pointers to the ppFilter parameter to NULL if the name is not in this graph.

IFilterGraph::Reconnect

IFilterGraph Interface

Disconnects this and the pin to which it connects and then reconnects it to the same pin. This allows the details of the connection, such as media type and allocator, to be renegotiated.

HRESULT Reconnect(
IPin * ppin
);

Parameters
ppin
[in] Pin to disconnect and reconnect.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method performs its operation on a separate thread that will not hold any relevant locks. It can be called by a pin or filter to allow renegotiation of the connection. When a transform filter has its input connected, it must agree upon some media type. When the output is connected, it might discover that, to please both its upstream and downstream connections, it would have been better to have chosen a different media type for the upstream connection. The solution is to reconnect the input pin. The caller of this method should ensure (for example, by calling IPin::QueryAccept) that the resulting renegotiation will succeed, because the reconnection process is performed asynchronously and there is no mechanism for reporting or correcting errors.

IFilterGraph::RemoveFilter

IFilterGraph Interface

Removes a filter from the graph.

HRESULT RemoveFilter(
IBaseFilter * pFilter
);

Parameters
pFilter
[in] Pointer to the filter to be removed from the graph.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The filter graph implementation informs the filter that it is being removed by calling the IBaseFilter::JoinFilterGraph method with a NULL argument.

IFilterGraph::SetDefaultSyncSource

IFilterGraph Interface

Sets the default source of synchronization.

HRESULT SetDefaultSyncSource(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is used when no clock has been given to the filter graph, and the filter graph manager consequently must find a clock to use as the synchronization source. The filter graph manager first tries all filters, starting with renderers, to see if any filter exports a clock (by providing an IReferenceClock interface). The filter graph manager will choose the first filter that it finds, providing that filter is connected to an upstream source. If no connected filters are found, the first filter if IReferenceClock is used. Typically, this will be the audio rendering filter. If no filter exports a clock, the filter graph manager uses a system clock.


IFilterGraph2 Interface

The IFilterGraph2 interface adds new functionality to the IGraphBuilder and IFilterGraph interfaces. It inherits from both interfaces and exposes all their methods. This interface also includes a method to add a source for a moniker, and an improved version of the IFilterGraph::Reconnect method. For this reason, you should usually use IFilterGraph2 instead of the other two.

When to Implement

The filter graph implements this interface so it isn't intended that you implement it.

When to Use

Use this interface in applications that previously called IFilterGraph::Reconnect and in applications that need a source filter for a moniker.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterGraph methods | Description
AddSourceFilterForMoniker | Adds a source for a moniker.
ReconnectEx | Specifies a pin and a media type to reconnect with.

IFilterGraph2::AddSourceFilterForMoniker

IFilterGraph2 Interface

Adds a source for a moniker.

HRESULT AddSourceFilterForMoniker(
IMoniker *pMoniker,
IBindCtx *pCtx,
LPCWSTR lpcwstrFilterName,
IBaseFilter **ppFilter );

Parameters
pMoniker
[in] Pointer to an IMoniker interface.
pCtx
[in] Pointer to an IBindCtx bind context interface.
lpcwstrFilterName
[in] Pointer to the filter's name.
ppFilter
[out] Address of a pointer to an IBaseFilter interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

When adding a source filter for the given moniker to the graph, the COM IMoniker::BindToStorage member function will query for an IStream interface. If this fails, IMoniker::BindToObject will try to retrieve an IBaseFilter interface.

IFilterGraph2::ReconnectEx

IFilterGraph2 Interface

Specifies a pin and a media type to reconnect with.

HRESULT ReconnectEx(
IPin * ppin,
const AM_MEDIA_TYPE *pmt );

Parameters
ppin
[in] Pin to disconnect and reconnect.
pmt
[in] Media type to reconnect with. Specify NULL to use the existing media type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Like the IFilterGraph::Reconnect method, the ReconnectEx method schedules a reconnection of the pin with the pin it is currently connected to. By specifying a media type when this method is called, the pins don't have to check what type they were originally connected with or enumerate possible new types. This makes the reconnection more likely to succeed.

See Also

IFilterGraph::Reconnect


IFilterInfo Interface

IFilterInfo is an interface that manages information about a filter and provides access to the filter and to the IPinInfo interfaces representing the pins on the filter. It is essentially an IBaseFilter interface that can be accessed through Automation. This was created to provide access to the IBaseFilter methods from Microsoft® Visual Basic® applications without incurring the overhead of Automation in the IBaseFilter interface itself.

When to Implement

This interface is implemented by the filter graph manager for use by Automation client applications, such as Microsoft Visual Basic.

When to Use

Use this interface from an application to retrieve information about a filter and to retrieve individual pin objects in the filter or a collection of all pin objects belonging to the filter. This can be used when adding filters to a filter graph and connecting pins together.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IFilterInfo methods | Description
FindPin | Locates a pin and returns an IPinInfo interface.
get_Name | Retrieves the filter name.
get_VendorInfo | Retrieves a string containing optional information supplied by a vendor about the specified filter.
get_Filter | Retrieves the IBaseFilter interface for the filter.
get_Pins | Retrieves an IAMCollection interface which provides access to the IPinInfo interfaces for this filter.
get_IsFileSource | Determines if the filter is a file source filter.
get_Filename | Retrieves the file name associated with the source filter.
put_Filename | Sets the file name containing the media source.

IFilterInfo::FindPin

IFilterInfo Interface

Locates a pin, given an identifier, and returns an IPinInfo interface.

HRESULT FindPin(
BSTR strPinID,
IDispatch **ppUnk
);

Parameters
strPinID
[in] String pin identifier.
ppUnk
[out] IPinInfo interface.
Return Values

Returns an HRESULT value.

Remarks

This method corresponds to the IBaseFilter::FindPin method. This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::get_Filename

IFilterInfo Interface

Retrieves the file name associated with the source filter.

HRESULT get_Filename(
BSTR *pstrFilename
);

Parameters
pstrFilename
[out, retval] File name containing the source media.
Return Values

Returns an HRESULT value.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::get_Filter

IFilterInfo Interface

Retrieves the IBaseFilter interface of the filter.

HRESULT get_Filter(
IUnknown **ppUnk
);

Parameters
ppUnk
[out, retval] IBaseFilter interface of the filter represented by IFilterInfo.
Return Values

Returns an HRESULT value.

Remarks

The object that implements IFilterInfo is a wrapper and is not the same COM object as the filter itself. Thus a call to IFilterInfo::QueryInterface for IBaseFilter will fail. The IFilterInfo::get_Filter method allows an application to obtain the filter object itself. This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::get_IsFileSource

IFilterInfo Interface

Determines if the filter is a file source filter.

HRESULT get_IsFileSource(
LONG *pbIsSource
);

Parameters
pbIsSource
[out, retval] Returned Boolean value.
Return Values

Returns an HRESULT value. Returns OATRUE if filter is a file source filter; otherwise, returns OAFALSE.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::get_Name

IFilterInfo Interface

Retrieves the filter name.

HRESULT get_Name(
BSTR *strName
);

Parameters
strName
[out, retval] Name of the filter.
Return Values

Returns an HRESULT value.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::get_Pins

IFilterInfo Interface

Retrieves an IAMCollection interface, which provides access to the IPinInfo interfaces for the pins on this filter.

HRESULT get_Pins(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] IAMCollection interface.
Return Values

Returns an HRESULT value.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations. Visual Basic applications can enumerate the IPinInfo interfaces in the returned IAMCollection object by using the For Each ...Next syntax.

IFilterInfo::get_VendorInfo

IFilterInfo Interface

Retrieves a string containing optional information supplied by a vendor about the specified filter.

HRESULT get_VendorInfo(
BSTR *strVendorInfo
);

Parameters
strVendorInfo
[out, retval] String containing vendor information.
Return Values

Returns an HRESULT value.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.

IFilterInfo::put_Filename

IFilterInfo Interface

Sets the file name containing the media source.

HRESULT put_Filename(
BSTR strFilename
);

Parameters
strFilename
[in] Name of the file for the source filter to read from.
Return Values

Returns an HRESULT value.

Remarks

This method is exposed for use by Automation clients and is not expected to be used by C or C++ applications because of performance limitations.


IFilterMapper Interface

The IFilterMapper interface is an abstraction that represents registered information about filters. This allows properties of filters to be looked up during loading.

When to Implement

This interface is implemented on the filter mapper and is not intended to be implemented by developers.

When to Use

This interface is used by filters to register and unregister themselves. This is handled in the base classes by the CBaseFilter::Register and CBaseFilter::Unregister member functions. It is also used by the filter graph manager to look up filters and determine their characteristics when building a filter graph to render a given media type.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterMapper methods | Description
RegisterFilter | Records the details of a filter in the registry.
RegisterFilterInstance | Registers an identifiable instance of a filter.
RegisterPin | Records the details of a pin in the registry.
RegisterPinType | Adds a type for the pin to the registry.
UnregisterFilter | Deletes a filter from the registry.
UnregisterFilterInstance | Deletes an identifiable instance of a filter.
UnregisterPin | Deletes a pin from the registry.
EnumMatchingFilters | Finds all filters matching specific requirements.

IFilterMapper::EnumMatchingFilters

IFilterMapper Interface

Provides an enumerator that enumerates registered filters that meet specified requirements.

HRESULT EnumMatchingFilters(
IEnumRegFilters ** ppEnum,
DWORD dwMerit,
BOOL bInputNeeded,
CLSID clsInMaj,
CLSID clsInSub,
BOOL bRender,
BOOL bOutputNeeded,
CLSID clsOutMaj,
CLSID clsOutSub
);

Parameters
ppEnum
[out] Enumerator returned.
dwMerit
[in] Enumerate only filters with at least this merit.
bInputNeeded
TRUE if there must be at least one input pin.
clsInMaj
[in] Input major type required. Set to GUID_NULL if you do not care.
clsInSub
[in] Input subtype required. Set to GUID_NULL if you do not care.
bRender
[in] Option that specifies if the input must be rendered by this filter.
bOutputNeeded
TRUE if there must be at least one output pin.
clsOutMaj
[in] Output major type required. Set to GUID_NULL if you do not care.
clsOutSub
[in] Output subtype required. Set to GUID_NULL if you do not care.
Return Values

Returns an HRESULT value.

Remarks

Set the ppEnum parameter to be an enumerator for filters matching the requirements. For a description of merit values for the dwMerit parameter, see the IFilterMapper::RegisterFilter method.

IFilterMapper::RegisterFilter

IFilterMapper Interface

Adds a filter to the registry; the filter can then be enumerated.

HRESULT RegisterFilter(
CLSID clsid,
LPCWSTR Name,
DWORD dwMerit
);

Parameters
clsid
[in] Globally unique identifier (GUID) of the filter.
Name
[in] Descriptive name for the filter.
dwMerit
[in] Position in the order of enumeration. Filters with higher merit are enumerated first.
Return Values

Returns an HRESULT value.

Remarks

The merit (as defined by the dwMerit parameter) controls the order in which the filter graph manager tries filters when performing an operation as a result of a call to IGraphBuilder::Connect, IGraphBuilder::Render, or IGraphBuilder::RenderFile. The filter graph manager finds all filters registered with the correct media type and then tries the one with the highest merit, using other criteria in the registration to choose between filters with equal merit.

The following predefined values exist for the dwMerit parameter. Other values, such as MERIT_NORMAL-1, can be used. Using the formula (MERIT_NORMAL+MERIT_UNLIKELY)/2 to calculate the merit value is advisable, because it leaves some low-order bits available for making even finer distinctions.
0x900000 | Hardware renderer filter. Filters with this merit value are tried first.
MERIT_PREFERRED (0x800000) | Filter, such as a renderer, that is likely to complete the operation directly.
0x680000 | MPEG decompression filter. These are tried before AVI decompressors because the latter require more time to determine if they work in the filter graph.
MERIT_NORMAL (0x600000) | Filter that may contribute to the completion of a connection. AVI decompression filters and splitter transform filters are registered to this value.
MERIT_UNLIKELY (0x400000) | Filter that may contribute to the completion of a connection (a color space conversion filter, for example). The filter graph manager uses this filter only if other options have failed. Register source filters with this value.
MERIT_DO_NOT_USE (0x200000) | Filter that will never contribute to the completion of a connection. Filters registered with this value (or less) will never be tried by the filter graph manager when automatically building a filter graph. Use this to register filters that must be added explicitly, either as part of a predefined filter graph or by adding them using IFilterGraph::AddFilter. Examples include tee filters or effects filters.
MERIT_HW_COMPRESSOR (0x100050) | Hardware compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.
MERIT_SW_COMPRESSOR (0x100000) | Software compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.

IFilterMapper::RegisterFilterInstance

IFilterMapper Interface

Registers an identifiable instance of a filter.

HRESULT RegisterFilterInstance(
CLSID clsid,
LPCWSTR Name,
CLSID *MRId
);

Parameters
clsid
[in] Globally unique identifier (GUID) of the filter.
Name
[in] Descriptive name of the instance.
MRId
[out] Returned media resource ID. This parameter is a locally unique identifier for this instance of this filter.
Return Values

Returns an HRESULT value.

Remarks

This method handles cases such as when two similar sound cards that are driven by the same driver are available, and it is necessary to choose which card will emit the sound. This is not needed if there is only one instance of the filter (such as when there is only one sound card in the computer), or if all instances of the filter are equivalent.

The filter itself must have already been registered.

IFilterMapper::RegisterPin

IFilterMapper Interface

Records the details of the pin in the registry.

HRESULT RegisterPin(
CLSID Filter,
LPCWSTR Name,
BOOL bRendered,
BOOL bOutput,
BOOL bZero,
BOOL bMany,
CLSID ConnectsToFilter,
LPWSTR ConnectsToPin
);

Parameters
Filter
[in] Globally unique identifier (GUID) of the filter.
Name
[in] Name of the pin. This should be unique within the filter. It has no significance other than to indicate type information. Note that pin names longer than 99 characters should not be used, because this causes filter enumeration problems.
bRendered
[in] Set to TRUE if the filter renders this input; otherwise, set to FALSE.
bOutput
[in] Set to TRUE if this is an output pin; otherwise, set to FALSE.
bZero
[in] If the filter can have zero instances of this pin, set to TRUE; otherwise, set to FALSE. For example, a decompression filter might choose to not create a sound output pin for a movie without a sound track.
bMany
[in] If the filter can have many instances of this pin, set to TRUE; otherwise, set to FALSE. For example, a mixer might have multiple instances of its input pin.
ConnectsToFilter
[in] Reserved. Must be NULL. (This is intended for filters such as system-wide mixers that have connections outside the filter graph. It is not yet implemented.)
ConnectsToPin
[in] Reserved. Must be NULL.
Return Values

Returns an HRESULT value.

IFilterMapper::RegisterPinType

IFilterMapper Interface

Registers this pin type.

HRESULT RegisterPinType(
CLSID clsFilter,
LPCWSTR strName,
CLSID clsMajorType,
CCLSID clsSubType
);

Parameters
clsFilter
Class identifier (CLSID) of the filter to which the pin belongs.
strName
Name by which it is known.
clsMajorType
Major type of the media sample supported by this pin class.
clsSubType
Subtype of the media sample supported by this pin class.
Return Values

Returns an HRESULT value.

Remarks

The clsMajorType and clsSubType parameters specify the media type of the pin and correspond to the AM_MEDIA_TYPE structure's majortype and subtype members, respectively.

IFilterMapper::UnregisterFilter

IFilterMapper Interface

Removes the registration of this filter from the registry.

HRESULT UnregisterFilter(
CLSID Filter
);

Parameters
Filter
[in] Globally unique identifier (GUID) of the filter.
Return Values

Returns an HRESULT value.

IFilterMapper::UnregisterFilterInstance

IFilterMapper Interface

Removes the registration of this filter instance from the registry.

HRESULT UnregisterFilterInstance(
CLSID MRId
);

Parameters
MRId
[in] Media resource identifier of this instance.
Return Values

Returns an HRESULT value.

IFilterMapper::UnregisterPin

IFilterMapper Interface

Removes the registration of this pin from the registry.

HRESULT UnregisterPin(
CLSID Filter,
LPCWSTR Name
);

Parameters
Filter
[in] Globally unique identifier (GUID) of the filter that this pin is part of.
Name
[in] Name of the pin.
Return Values

Returns an HRESULT value.


IFilterMapper2 Interface

IFilterMapper2 is an interface for registering and locating DirectShow filters with greater flexibility than IFilterMapper allowed. Applications and filters should use IFilterMapper2 instead of IFilterMapper, although both interfaces can find filters registered with the other interface.

One major change from IFilterMapper to IFilterMapper2 is that IFilterMapper2 provides support for filter categories. A filter can appear in one or more categories (for example, Video Compressors) to restrict the search space. The RegisterFilter method takes a category, and the EnumMatchingFilters method searches across categories.

Other changes include:

  1. Quicker and easier enumeration of hardware devices such as WDM/PnP
  2. Registration in one step (previously you had to register pins and media types with separate calls)
  3. Register and search by mediums (see Kernel Streaming in the NT DDK)

When to Implement

This interface is implemented on the filter graph and is not intended to be implemented by developers.

When to Use

Applications and filters should use IFilterMapper2 when they need to register or unregister filters. IFilterMapper2 should be used instead of IFilterMapper.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterMapper2 methods | Description
CreateCategory | Adds a new category to the list of filter categories (CLSID_ActiveMovieCategories).
UnregisterFilter | Removes the registration of the specified filter from the registry.
RegisterFilter | Registers a filter, pins, and media types under a category.
EnumMatchingFilters | Provides an enumerator that enumerates registered filters that meet specified requirements.

IFilterMapper2::CreateCategory

IFilterMapper2 Interface

Adds a new category to the list of filter categories (CLSID_ActiveMovieCategories).

HRESULT CreateCategory(
REFCLSID clsidCategory,
DWORD dwCategoryMerit,
LPCWSTR Description );

Parameters
clsidCategory
[in] Name of the new filter category.
dwCategoryMerit
[in] Merit value of the category. Categories with higher merit are enumerated first.
Description
[in] Descriptive name for the category.
Return Values

Returns S_OK on success; HRESULT_FROM_WIN32 on failure.

Remarks

The graph builder initially skips all categories with merit less than DO_NOT_USE to speed up the IGraphBuilder::RenderFile method. Categories of filters that should not be considered for playback should be marked DO_NOT_USE.

A filter can appear in one or more categories (for example, Video Compressors) to restrict the search space.

IFilterMapper2::EnumMatchingFilters

IFilterMapper2 Interface

Provides an enumerator that enumerates registered filters that meet specified requirements.

HRESULT EnumMatchingFilters(
IEnumMoniker **ppEnum,
DWORD dwFlags,
BOOL bExactMatch,
DWORD dwMerit,
BOOL bInputNeeded,
DWORD cInputTypes,
const GUID *pInputTypes,
const REGPINMEDIUM *pMedIn,
const CLSID *pPinCategoryIn,
BOOL bRender,
BOOL bOutputNeeded,
DWORD cOutputTypes,
const GUID *pOutputTypes,
const REGPINMEDIUM *pMedOut,
const CLSID *pPinCategoryOut,);

Parameters
ppEnum
[out] Enumerator returned.
dwFlags
[in] Currently reserved, specify zero.
bExactMatch
[in] Specify TRUE to indicate wildcards not allowed; FALSE indicates wildcards allowed.
dwMerit
[in] Enumerate only filters with at least the specified merit value.
bInputNeeded
[in] TRUE if there must be at least one input pin.
cInputTypes
[in] Number of input types to match.
pInputTypes
[in] Input major types and subtype required. Set to GUID_NULL if you do not care.
pMedIn
[in] Input medium. Set to NULL if not needed.
pPinCategoryIn
[in] Input pin category. Set to NULL if not needed.
bRender
[in] Option that indicates if the specified filter must render the input.
bOutputNeeded
[in] TRUE if there must be at least one output pin.
cOutputTypes
[in] Number of output types to match.
pOutputTypes
[in] Output major type and subtype required. Set to GUID_NULL if you do not care.
pMedOut
[in] Output medium. Set to NULL if not needed.
pPinCategoryOut
[in] Output pin category. Set to NULL if not needed.
Return Values

Returns S_OK if successful or E_FAIL upon failure.

Remarks

If a pin hasn't registered any media types, this method will not consider a match for the media type passed in for the pInputTypes or pOutputTypes parameters.

IFilterMapper2::RegisterFilter

IFilterMapper2 Interface

Registers a filter, pins, and media types under a category.

HRESULT RegisterFilter(
REFCLSID clsidFilter,
LPCWSTR Name,
IMoniker **ppMoniker,
const CLSID *pclsidCategory,
const OLECHAR *szInstance,
const REGFILTER2 *prf2 );

Parameters
clsidFilter
[in] GUID of the filter. CoCreateInstance will be called with this GUID when the filter is instantiated.
Name
[in] Descriptive name for the filter.
ppMoniker
[in, out] Address of a pointer to a device moniker that determines where this filter's data will be written. This parameter will be set to NULL upon return.
pclsidCategory
[in] Category of the filter to register.
szInstance
[in] Unique identifier for the filter (can be the friendly name or the filter CLSID).
prf2
[in] Pointer to a REGFILTER2 structure containing merit and pin information.
Return Values

Returns one of the following values:
Value | Meaning
VFW_E_BAD_KEY | Couldn't get registry key.
HRESULT_FROM_WIN32 | Failure.
NOERROR | Success.

Remarks

Specify the moniker in the ppMoniker parameter if you are registering a filter for a WDM/PnP (Windows Driver Model/Plug and Play) device. If ppMoniker is non-null, the moniker returned can be used to write additional private values in the property bag.

The pclsidCategory parameter defaults to CLSID_ActiveMovieFilters if NULL is passed in.

Set ppMoniker to NULL if you don't want to provide or receive the moniker.

IFilterMapper2::UnregisterFilter

IFilterMapper2 Interface

Removes the registration of the specified filter from the registry.

HRESULT UnregisterFilter(
const CLSID *pclsidCategory,
const OLECHAR *szInstance,
REFCLSID Filter );

Parameters
pclsidCategory
[in] Name of the category that the filter falls under.
szInstance
[in] Name of the filter you want to remove.
Filter
[in] Globally unique identifier (GUID) of the filter.
Return Values

Returns S_OK on success; HRESULT_FROM_WIN32 on failure.

Remarks

If szInstance is NULL, this method uses the filter GUID passed in Filter.

This method might return an error if the filter was not registered.


IFullScreenVideo Interface

This interface allows an application or plug-in distributor to control a full-screen renderer. The Microsoft® DirectShow™ full-screen renderer supports this interface. When connected, a renderer should load the display modes that are available. The number of modes available can be obtained through IFullScreenVideo::CountModes. Information on each individual mode is then available by calling IFullScreenVideo::GetModeInfo and IFullScreenVideo::IsModeAvailable. An application can enable and disable any mode by calling the IFullScreenVideo::SetEnabled method. The current value can be queried by calling IFullScreenVideo::IsModeEnabled. An application can enable or disable any mode by calling the IFullScreenVideo::SetEnabled flag with OATRUE or OAFALSE (not C/C++ TRUE and FALSE values).

The DirectShow full-screen renderer can function only when it is the foreground active window. If the user tries to switch to another application while in full-screen mode, the video will be hidden. The renderer does this by minimizing the window it is actually drawing the video in (although the use of a window is transparent to the user). Maximizing the window restores the video.

The filter graph manager uses the full-screen renderer to help implement the full-screen property that can be set through IVideoWindow::put_FullScreenMode. When used in this manner, the expected behavior is to switch seamlessly between full-screen mode and then back into normal window playback when the user presses ESC or other escape sequences. In this case, the renderer is required to hide its window rather than minimize it when switching away from it. The renderer can be made to hide rather than minimize (the default action) by calling IFullScreenVideo::HideOnDeactivate.

When to Implement

Implement this interface if you are writing an alternate full-screen video renderer. The Microsoft full-screen video renderer implements this interface by default.

When to Use

Use this interface from any application that must interact with the full-screen video renderer in order to set or determine video modes or other full-screen renderer properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFullScreenVideo methods | Description
CountModes | Retrieves the number of modes available on the full-screen renderer.
GetModeInfo | Retrieves information about a specified mode.
GetCurrentMode | Retrieves the video mode currently in effect.
IsModeAvailable | Determines if a specified video mode is available.
IsModeEnabled | Determines if a specified video mode is enabled.
SetEnabled | Enables and disables video modes.
GetClipFactor | Retrieves the current clip loss factor setting.
SetClipFactor | Specifies the video mode based on the maximum image area that will be lost.
SetMessageDrain | Specifies a window that will receive window messages sent to the renderer.
GetMessageDrain | Retrieves the window set to receive window messages sent to the renderer.
SetMonitor | Sets the monitor in use (for use with multiple-monitor implementations).
GetMonitor | Retrieves the monitor in use.
HideOnDeactivate | Hides the window when it is deactivated.
IsHideOnDeactivate | Retrieves the state of the HideOnDeactivate property.
SetCaption | Sets the caption associated with the full-screen window.
GetCaption | Retrieves the caption associated with the full-screen window.
SetDefault | Sets the default for all full-screen video renderer properties.

IFullScreenVideo::CountModes

IFullScreenVideo Interface

Retrieves the number of modes available on the full-screen renderer.

HRESULT CountModes(
long *pModes
);

Parameters
pModes
[out] Returned mode count.
Return Values

Returns an HRESULT value.

Remarks

The Microsoft DirectShow full-screen renderer supports eight modes (320 x 200 x 8/16 bit, 320 x 240 x 8/16, 640 x 400 x 8/16, and 640 x 480 x 8/16). The lower-resolution modes are always chosen over the higher modes. An application can enable and disable specific modes to more accurately specify which ones are available for use. A slightly less fine-grained mechanism to affect the selected mode is available through the clip loss factor.

IFullScreenVideo::GetCaption

IFullScreenVideo Interface

Retrieves the caption associated with the full-screen window.

HRESULT GetCaption(
BSTR *pstrCaption
);

Parameters
pstrCaption
[out] Retrieved caption.
Return Values

Returns an HRESULT value.

Remarks

The Microsoft DirectShow full-screen renderer will show itself as an icon when it is deactivated (you can deactivate it by pressing ALT+TAB to switch away from it). The text caption for the icon can be set through this method. If the renderer is supposed to hide itself when deactivated, this method will succeed, although it will have no use because the window will never be shown as an icon.

IFullScreenVideo::GetClipFactor

IFullScreenVideo Interface

Retrieves the current clip loss factor setting.

HRESULT GetClipFactor(
long *pClipFactor
);

Parameters
pClipFactor
[out] Maximum allowable amount of the image to lose.
Return Values

Returns an HRESULT value.

Remarks

For a description of the clip loss factor setting, see IFullScreenVideo::SetClipFactor.

IFullScreenVideo::GetCurrentMode

IFullScreenVideo Interface

Retrieves the video mode currently in effect.

HRESULT GetCurrentMode(
long *pMode
);

Parameters
pMode
[out] Retrieved full-screen video mode.
Return Values

Returns an HRESULT value.

Remarks

When the full-screen video renderer is connected, it chooses a display mode to use for video playback. The selected mode can be retrieved through this method. The details for that mode can then be retrieved by using IFullScreenVideo::GetModeInfo.

For a list of available modes for the Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

IFullScreenVideo::GetMessageDrain

IFullScreenVideo Interface

Retrieves the window set to receive window messages sent to the renderer.

HRESULT GetMessageDrain(
HWND *hwnd
);

Parameters
hwnd
[out] Window handle of the window specified as the message drain.
Return Values

Returns an HRESULT value.

Remarks

The full-screen video renderer posts all mouse and keyboard messages it receives to the window designated as a message drain, with the message parameters untranslated. The exact list of messages passed is the same as for IVideoWindow::put_MessageDrain. An application can use this to implement hot-key support for full-screen video. For example, it might watch for the CTRL+P key combination as a cue to pause the video.

IFullScreenVideo::GetModeInfo

IFullScreenVideo Interface

Retrieves information about a specified mode.

HRESULT GetModeInfo(
long Mode,
long *pWidth,
long *pHeight,
long *pDepth
);

Parameters
Mode
[in] Specified mode for which to retrieve information.
pWidth
[out] Width in pixels of the mode's image display.
pHeight
[out] Height in pixels of the mode's image display.
pDepth
[out] Number of color bits per pixel.
Return Values

Returns an HRESULT value.

Remarks

This method returns the height, width, and color depth for a given mode that the renderer has available. The number of display modes available can be retrieved through IFullScreenVideo::CountModes.

For a list of modes available to the Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

IFullScreenVideo::GetMonitor

IFullScreenVideo Interface

Retrieves the monitor type in use.

HRESULT GetMonitor(
long *Monitor
);

Parameters
Monitor
[out] Monitor currently in use.
Return Values

Returns NOERROR.

Remarks

The Microsoft DirectShow full-screen renderer always returns zero (the primary monitor).

IFullScreenVideo::HideOnDeactivate

IFullScreenVideo Interface

Hides the window icon when the full-screen window is deactivated.

HRESULT HideOnDeactivate(
long Hide
);

Parameters
Hide
[in] Set to OATRUE to hide the video window icon when deactivated; set to OAFALSE to display the icon.
Return Values

Returns NOERROR if successful and E_INVALIDARG if Hide is invalid.

Remarks

The default setting for the Microsoft DirectShow full-screen renderer is OATRUE.

The full-screen renderer can function only when it is the foreground active window. If the user tries to switch to another application while in full-screen mode, the video will be hidden. The renderer does this by minimizing the window it is actually drawing the video in (although the use of a window is transparent to the user). Maximizing the window restores the video. If this property is set, the window will be hidden rather than minimized.

IFullScreenVideo::IsHideOnDeactivate

IFullScreenVideo Interface

Retrieves the state of the IFullScreenVideo::HideOnDeactivate property.

HRESULT IsHideOnDeactivate(void);

Return Values

Returns S_OK if HideOnDeactivate is set to OATRUE or S_FALSE if it is set to OAFALSE.

IFullScreenVideo::IsModeAvailable

IFullScreenVideo Interface

Determines if a specified video mode is available.

HRESULT IsModeAvailable(
long Mode
);

Parameters
Mode
[in] Full-screen mode to check.
Return Values

Returns S_OK if the video mode is available or S_FALSE if it isn't.

Remarks

The display modes supported by the Microsoft DirectShow full-screen renderer are different than the actual modes available on any given display card. The application should call this method only when the renderer is connected, because until then the renderer might not have allocated the resources it needs to make this information available. Even if a mode is available, it will not necessarily be used for video playback; the mode must also be compatible with the filters in the filter graph.

IFullScreenVideo::IsModeEnabled

IFullScreenVideo Interface

Determines if a specified mode is enabled.

HRESULT IsModeEnabled(
long Mode
);

Parameters
Mode
[in] Full-screen video mode to check.
Return Values

Returns S_OK if the video mode is enabled or S_FALSE if it isn't.

Remarks

You can use this method to enable and disable specific display modes supported by the renderer. Even if a mode is enabled, it will not necessarily be used for video playback; the mode must also be compatible with the filters in the filter graph.

For a list of available modes for the Microsoft DirectShow full-screen video renderer, see IFullScreenVideo::SetEnabled.

See Also

IFullScreenVideo::IsModeAvailable

IFullScreenVideo::SetCaption

IFullScreenVideo Interface

Sets the title associated with the full-screen window.

HRESULT SetCaption(
BSTR strCaption
);

Parameters
strCaption
[in] String containing the caption.
Return Values

Returns an HRESULT value.

IFullScreenVideo::SetClipFactor

IFullScreenVideo Interface

Specifies the video mode based on the maximum data that will be lost.

HRESULT SetClipFactor(
long ClipFactor
);

Parameters
ClipFactor
[in] Maximum allowable amount of the image to lose.
Return Values

Returns an HRESULT value.

Remarks

Clip loss factor is a means of enabling full-screen modes that is more generic and easier for applications to use. This method defines the amount of video that can be lost when deciding which display mode to use. For example, assuming the decoder cannot compress the video, playing an MPEG file (say 352 x 288 pixels) into a 320 x 200 display will lose about 25 percent of the image. The clip loss factor specifies the upper range permissible. To allow typical QCIF-sized MPEG video (352 x 288 pixels) to be played in a 320 x 200 display mode, it defaults to 25 percent.

IFullScreenVideo::SetDefault

IFullScreenVideo Interface

Sets the default full-screen video renderer settings.

HRESULT SetDefault(void);

Return Values

Returns an HRESULT value.

Remarks

The properties set through this interface apply only to the current renderer instance. They can, however, be made the global default by calling this interface method.

IFullScreenVideo::SetEnabled

IFullScreenVideo Interface

Enables and disables video modes.

HRESULT SetEnabled(
long Mode,
long bEnabled
);

Parameters
Mode
[in] Mode to be enabled or disabled (see the following table).
bEnabled
[out] Can be set to one of the following values.
Value | Meaning
OATRUE | Enable mode.
OAFALSE | Disable mode.
Return Values

Returns an HRESULT value.

Remarks

Available DirectShow modes are defined as follows. The ordering of these modes is subject to change, so use IFullScreenVideo::CountModes and IFullScreenVideo::GetModeInfo interface methods to enumerate modes.
Mode | Width | Height | RGB depth (in bits)
0 | 320 | 200 | 16
1 | 320 | 200 | 8
2 | 320 | 240 | 16
3 | 320 | 240 | 8
4 | 640 | 400 | 16
5 | 640 | 400 | 8
6 | 640 | 480 | 16
7 | 640 | 480 | 8
8 | 800 | 600 | 16
9 | 800 | 600 | 8
10 | 1024 | 768 | 16
11 | 1024 | 768 | 8
12 | 1152 | 864 | 16
13 | 1152 | 864 | 8
14 | 1280 | 1024 | 16
15 | 1280 | 1024 | 8

IFullScreenVideo::SetMessageDrain

IFullScreenVideo Interface

Specifies a window that will receive window messages sent to the renderer.

HRESULT SetMessageDrain(
HWND hwnd
);

Parameters
hwnd
[in] Window handle of the message drain window.
Return Values

Returns an HRESULT value.

Remarks

The full-screen video renderer posts all mouse and keyboard messages it receives to the window designated as a message drain, with the message parameters untranslated. The exact list of messages passed is the same as for IVideoWindow::put_MessageDrain. An application can use this to implement hot-key support for full-screen video. For example, it might watch for the CTRL+P key combination as a cue to pause the video.

IFullScreenVideo::SetMonitor

IFullScreenVideo Interface

Sets the monitor type in use.

HRESULT SetMonitor(
long Monitor
);

Parameters
Monitor
[in] Monitor currently in use.
Return Values

Returns an HRESULT value.

Remarks

Setting this method to anything but the primary display (0) will return an error. In future versions of Microsoft DirectShow, the renderer might allow applications to select the monitor on which to play back the full-screen video.


IGraphBuilder Interface

The IGraphBuilder interface allows applications to call upon the filter graph manager to attempt to build a complete filter graph, or parts of a filter graph given only partial information, such as the name of a file or the interfaces of two separate pins. The filter mapper looks up filters in the registry to configure the filter graph in a meaningful way.

IGraphBuilder inherits from the IFilterGraph interface and exposes all its methods. For this reason, IFilterGraph should normally not be used directly.

When to Implement

This interface is implemented on the filter graph manager and is not intended for implementation by developers.

When to Use

Applications use this interface to create a filter graph, add filters to or remove filters from a filter graph, enumerate all the filters in a filter graph, and force connections when adding a filter. Filters typically use the interface to reconnect pins during the connection and negotiation process of building a filter graph.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IFilterGraph methods | Description
AddFilter | Adds a filter to the graph and gives it a name.
RemoveFilter | Removes a filter from the graph.
EnumFilters | Provides an enumerator for all filters in the graph.
FindFilterByName | Finds a filter that was added with a specified name.
ConnectDirect | Connects the two IPin objects directly (without intervening filters).
Reconnect | Breaks the existing pin connection and reconnects it to the same pin.
Disconnect | Disconnects this pin, if connected.
SetDefaultSyncSource | Sets the default synchronization source (a clock).
IGraphBuilder methods | Description
Connect | Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render | Adds a chain of filters to this output pin to render it.
RenderFile | Builds a filter graph that renders the specified file.
AddSourceFilter | Adds a source filter to the filter graph for a specific file. The IGraphBuilder::RenderFile method calls this to find the source filter.
SetLogFile | Sets the log file into which actions taken in attempting to perform an operation are logged.

IGraphBuilder::AddSourceFilter

IGraphBuilder Interface

Adds a source filter to the filter graph for a specific file.

HRESULT AddSourceFilter(
LPCWSTR lpwstrFileName,
LPCWSTR lpwstrFilterName,
IBaseFilter* * ppFilter
);

Parameters
lpwstrFileName
[in] Pointer to the file.
lpwstrFilterName
[in] Name to give the source filter when it is added.
ppFilter
[out] Pointer to an IBaseFilter interface on the filter that was added.
Return Values

Returns an HRESULT value.

Remarks

This method allows you to obtain and retain more control over building the rest of the graph. For example, you can use the IFilterGraph::AddFilter method to add a renderer of your choice, and then use the IGraphBuilder::Connect method to connect the two filters. The IBaseFilter interface exposed by the source filter is returned in the ppFilter parameter, and the reference is already added by the IUnknown::AddRef method. The lpwstrFilterName parameter is used to allow the filter to be identified by this name in this filter graph. For more information, see FindFilterByName.

It is the application's responsibility to find the output pin of the added source filter in order to build the rest of the filter graph, which can be done by calling IGraphBuilder::Render on the output pin, to build the entire filter graph automatically, or by adding and connecting filters individually. Note that, when adding filters individually, the asynchronous file reader source filter and the URL moniker source filter do not parse the data, so the output pins of these source filters can be connected only to a parser filter, such as the MPEG splitter filter.

Note that the IGraphBuilder::RenderFile method adds the same source filter.

IGraphBuilder::Connect

IGraphBuilder Interface

Connects the two pins, using intermediates if necessary.

HRESULT Connect(
IPin * ppinOut,
IPin * ppinIn
);

Parameters
ppinOut
[in] Output pin.
ppinIn
[in] Input pin.
Return Values

Returns an HRESULT value.

Remarks

This method connects these two pins directly or indirectly, using transform filters if necessary. The method either succeeds or leaves the filter graph unchanged. The filter graph manager attempts a direct connection. If that fails, it attempts to use any available transforms provided by filters that are already in the filter graph. (It enumerates these in an arbitrary order.) If that fails, it attempts to find filters from the registry to provide a transform. These will be tried in order of merit.

IGraphBuilder::Render

IGraphBuilder Interface

Builds a filter graph that renders the data from this output pin.

HRESULT Render(
IPin * ppinOut
);

Parameters
ppinOut
[in] Output pin.
Return Values

Returns an HRESULT value, which can include one of the following:
VFW_S_AUDIO_NOT_RENDERED
VFW_S_DUPLICATE_NAME
VFW_S_PARTIAL_RENDER
VFW_S_RPZA
VFW_S_VIDEO_NOT_RENDERED

Remarks

This method connects this output pin directly or indirectly to a filter or filters that will render it, using transform filters as intermediary filters if necessary. Filters are tried in the same order as for the IGraphBuilder::Connect method.

IGraphBuilder::RenderFile

IGraphBuilder Interface

Builds a filter graph that renders the specified file.

HRESULT RenderFile(
LPCWSTR lpwstrFile,
LPCWSTR lpwstrPlayList
);

Parameters
lpwstrFile
[in] Name of the file containing the data to be rendered.
lpwstrPlayList
[in] Playlist name. Reserved; must be NULL. (This parameter is currently unimplemented.)
Return Values

Returns an HRESULT value, which can include one of the following:
VFW_S_AUDIO_NOT_RENDERED
VFW_S_DUPLICATE_NAME
VFW_S_PARTIAL_RENDER
VFW_S_RPZA
VFW_S_VIDEO_NOT_RENDERED

Remarks

If the lpwstrPlayList parameter is NULL, this method would use the default playlist, which typically renders the entire file.

IGraphBuilder::SetLogFile

IGraphBuilder Interface

Sets the file into which actions taken in attempting to perform an operation are logged.

HRESULT SetLogFile(
HANDLE hFile
);

Parameters
hFile
Handle to the log file.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The hFile parameter must be an open file handle. After calling this method with a valid file handle, actions taken by IGraphBuilder methods when attempting to build a filter graph are logged to this file. This is intended to help you determine the cause of any failure to automatically build a filter graph.


IGraphVersion Interface

The IGraphVersion interface is provided by the filter graph manager to let other objects, especially plug-in distributors and the Graphedt.exe tool, know when the graph has changed.

When to Implement

This interface is implemented by the filter graph manager.

When to Use

Use this interface if your application or plug-in distributor must know when filters have been added, deleted, or reconnected.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IGraphVersion methods | Description
QueryVersion | Returns the current graph version number.

IGraphVersion::QueryVersion

IGraphVersion Interface

Returns the current graph version number.

HRESULT QueryVersion(
LONG* pVersion
);

Parameters
pVersion
Current graph version.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The version number is incremented every time there is a change in the set of filters in the graph or in their connections. If the version number has changed since the last enumeration, the graph must be re-enumerated.


IKsPropertySet Interface

The IKsPropertySet interface enables you to set and retrieve device properties.

When to Implement

Implement this interface on any pin to expose its properties and to enable its properties to be changed.

When to Use

Use this interface in your application or filter to access device properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IKsPropertySet methods | Description
Set | Sets a property identified by a property set GUID and a property ID.
Get | Retrieves a property identified by a property set GUID and a property ID.
QuerySupported | Determines whether an object supports a property set.

IKsPropertySet::Get

IKsPropertySet Interface

Retrieves a property identified by a property set GUID and a property ID.

HRESULT Get(
REFGUID guidPropSet,
DWORD dwPropID,
LPVOID pInstanceData,
DWORD cbInstanceData,
LPVOID pPropData,
DWORD cbPropData,
DWORD *pcbReturned
);

Parameters
guidPropSet
[in] Property set GUID.
dwPropID
[in] Identifier of the property within the property set.
pInstanceData
[out, size_is(cbInstanceData)] Pointer to instance data for the property.
cbInstanceData
[in] Number of bytes in the buffer to which pInstanceData points.
pPropData
[out, size_is(cbPropData)] Pointer to the retrieved buffer, which contains the value of the property.
cbPropData
[in] Number of bytes in the buffer to which pPropData points.
pcbReturned
[out] Pointer to the number of bytes returned in the buffer to which pPropData points.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The current DirectShow implementation returns E_PROP_SET_UNSUPPORTED if the property set is not supported or E_PROP_ID_UNSUPPORTED if the property ID is not supported for the specified property set.

Remarks

To retrieve a property, allocate a buffer which this method will then fill in. To determine the necessary buffer size, specify NULL for pPropData and zero (0) for cbPropData. This method returns the necessary buffer size in pcbReturned.

IKsPropertySet::QuerySupported

IKsPropertySet Interface

Determines whether an object supports a property set.

HRESULT QuerySupported(
REFGUID guidPropSet,
DWORD dwPropID,
DWORD *pTypeSupport
);

Parameters
guidPropSet
[in] Property set GUID.
dwPropID
[in] Identifier of the property within the property set.
pTypeSupport
[out] Pointer to a value in which to store flags indicating the support provided by the driver. Supported flags include the following:
Value | Meaning
KSPROPERTY_SUPPORT_GET | You can retrieve the property by calling the IKsPropertySet::Get method.
KSPROPERTY_SUPPORT_SET | You can change the property by calling IKsPropertySet::Set.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The return values for the current DirectShow implementation include the following:
Value | Meaning
E_NOTIMPL | Property set is not supported.
E_PROP_ID_UNSUPPORTED | Property ID is not supported for the specified property set.
E_PROP_SET_UNSUPPORTED | Property set is not supported.
S_OK | Specified property set and property ID combination is supported.

IKsPropertySet::Set

IKsPropertySet Interface

Sets a property identified by a property set GUID and a property ID.

HRESULT Set(
REFGUID guidPropSet,
DWORD dwPropID,
LPVOID pInstanceData,
DWORD cbInstanceData,
LPVOID pPropData,
DWORD cbPropData
);

Parameters
guidPropSet
[in] Property set GUID.
dwPropID
[in] Identifier of the property within the property set.
pInstanceData
[out, size_is(cbInstanceData)] Pointer to instance data for the property.
cbInstanceData
[in] Number of bytes in the buffer to which pInstanceData points.
pPropData
[out, size_is(cbPropData)] Pointer to the retrieved buffer, which contains the value of the property.
cbPropData
[in] Number of bytes in the buffer to which pPropData points.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The current DirectShow implementation returns E_PROP_SET_UNSUPPORTED if the property set is not supported or E_PROP_ID_UNSUPPORTED if the property ID is not supported for the specified property set.


IMediaControl Interface

The filter graph exposes the IMediaControl interface to allow applications to control the streaming of media through the filters in the graph. The interface provides methods for running, pausing, and stopping the streaming of data. It also provides applications with a simple method of building graphs to play back media files.

When to Implement

This interface is implemented by the filter graph manager. Implement this only if you are writing a plug-in distributor that needs to export the control methods. The CMediaControl base class implements this interface and handles the IDispatch interface.

When to Use

Use this interface from any application that wants to control the playing of media through Microsoft® DirectShow™ filter graphs. Applications can also use it to enumerate the filters in the filter graph and all the filters in the registry, to add a source filter to the filter graph, and to instruct the filter graph manager to build a filter graph capable of rendering the media type in a file.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaControl methods | Description
Run | Switches the entire filter graph into running mode.
Pause | Pauses all filters in the filter graph.
Stop | Switches all filters in the filter graph to a stopped state.
StopWhenReady | Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph.
GetState | Retrieves the state of the filter graph.
RenderFile | Adds and connects filters needed to play the specified file.
AddSourceFilter | Adds to the graph the source filter that can read the given file name, and returns an IDispatch interface pointer representing the filter object.
get_FilterCollection | Retrieves a collection of IFilterInfo interfaces representing the filters in the graph.
get_RegFilterCollection | Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry.

IMediaControl::AddSourceFilter

IMediaControl Interface

Adds to the graph the source filter that can read the given file name, and returns an IDispatch interface pointer representing the filter.

HRESULT AddSourceFilter(
BSTR strFilename,
IDispatch **ppUnk
);

Parameters
strFilename
[in] Name of the file containing the source video.
ppUnk
[out] Pointer to the IFilterInfo interface on the filter.
Return Values

Returns an HRESULT value.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IGraphBuilder::AddSourceFilter method to perform this operation for maximum efficiency.

IMediaControl::get_FilterCollection

IMediaControl Interface

Retrieves a collection of IFilterInfo interfaces representing the filters in the graph and returns IDispatch for an object that supports the IAMCollection interface.

HRESULT get_FilterCollection(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] The IAMCollection interface on a collection of IFilterInfo objects.
Return Values

Returns an HRESULT value.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IFilterGraph::EnumFilters method to perform this operation for maximum efficiency.

IMediaControl::get_RegFilterCollection

IMediaControl Interface

Retrieves a collection of IRegFilterInfo interfaces representing the filters available in the registry.

HRESULT get_RegFilterCollection(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] IDispatch interface of the IAMCollection object.
Return Values

Returns an HRESULT value.

Remarks

This method is primarily for use by Automation clients because it returns an IDispatch interface pointer. C and C++ applications should call the IFilterMapper::EnumMatchingFilters method to perform this operation for maximum efficiency.

IMediaControl::GetState

IMediaControl Interface

Retrieves the state of the filter graph.

HRESULT GetState(
LONG msTimeout,
OAFilterState* pfs
);

Parameters
msTimeout
[in] Duration of the time-out, in milliseconds.
pfs
[out] Holds the returned state of the filter graph.
Return Values

Returns VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it completed successfully. It can also return VFW_S_CANT_CUE if the state is paused, but the source filter does not push data during the paused state (only pushes during the run state). An example of this is a live video capture filter.

Remarks

Not all state transitions are synchronous. For example, even though the IMediaControl::Pause method returns immediately, the filter graph typically does not complete the transition into paused mode until data is ready at the renderer. This method will not return S_OK until the state transition has been completed.

If you specify a nonzero time-out, the method waits up to that number of milliseconds for the filter graph to leave the intermediate state. If the time-out expires before the state transition is complete, the return code will be VFW_S_STATE_INTERMEDIATE, and the returned state will be the state into which the graph is transitioning (either the State_Stopped, State_Paused, or State_Running members of the FILTER_STATE structure).

This method will return an error if there is a call on another thread to change the state while this method is blocked.

Avoid specifying a time-out of INFINITE. Threads cannot process messages while waiting in GetState. If you call GetState from the thread that processes Windows® messages, specify only small wait times on the call in order to remain responsive to user input. This is most important when streaming data from a source such as the Internet, because state transitions can take significantly more time to complete.

If you want to pause a filter graph completely before stopping it, call IMediaControl::Pause, and then IMediaControl::StopWhenReady (instead of calling GetState with an INFINITE time-out, and then IMediaControl::Stop).

Although pfs is declared as a pointer to an OAFilterState value in IMediaControl::GetState, DirectShow implements it as a pointer to a FILTER_STATE value in CBaseFilter::GetState and its derivatives. Since both OAFilterState and FILTER_STATE resolve to LONG values, this does not cause an error.

IMediaControl::Pause

IMediaControl Interface

Pauses all the filters in the filter graph.

HRESULT Pause( );

Return Values

Returns S_OK if the graph is actually paused.

Returns S_FALSE if the graph is in paused state but some filters have not completed the transition to pause. Call GetState to wait for the transition to the paused state to complete or to check if the transition has completed. If the method returns S_FALSE, subsequent calls to GetState will return a value of State_Paused when the graph is paused. If the transition to the paused state is not complete GetState can return a return code of VFW_S_STATE_INTERMEDIATE.

Returns an HRESULT error code if the graph could not transition to paused state and is now stopped.

Remarks

In the paused state, filters process data but do not render it. Data is pushed down the filter graph and is processed by transform filters as far as buffering permits. No data is rendered (except that media types capable of being rendered statically, such as video, have a static, poster frame rendered in paused mode). Therefore, putting a filter graph into a paused state cues the graph for immediate rendering when put into a running state.

IMediaControl::RenderFile

IMediaControl Interface

Adds and connects filters needed to play the specified file.

HRESULT RenderFile(
BSTR strFilename
);

Parameters
strFilename
Name of the file to render.
Return Values

Returns an HRESULT value.

Remarks

This method allows an application to pass the name of a media file that it wants rendered to the filter graph manager. The filter graph manager will build a graph of the filters needed to play back this file. This method is Automation-compatible and is equivalent to IGraphBuilder::RenderFile, which should be used by C and C++ applications.

IMediaControl::Run

IMediaControl Interface

Switches the entire filter graph into a running state.

HRESULT Run( );

Return Values

Returns S_OK if the graph is actually running.

Returns S_FALSE if the graph is preparing to run (the graph will run automatically when it's ready). Call GetState to wait for the transition to the running state to complete or to check if the transition has completed. If the method returns S_FALSE, subsequent calls to GetState will return a value of State_Running when the graph is actually running. If the transition to the running state is not complete GetState can return a return code of VFW_S_STATE_INTERMEDIATE.

Returns an HRESULT error code if the graph could not run and is now stopped.

Remarks

In a running state, data is pushed down the filter graph and rendered. The graph remains in a running state until it is stopped by the IMediaControl::Pause or IMediaControl::Stop method. The graph remains in a running state even after notifying the application of completion (that is, the EC_COMPLETE notification is sent to the application). This allows the application to determine whether to pause or stop after completion.

If the filter graph is in the stopped state, this method first pauses the graph before running.

If an error value is returned, some filters within the graph might have successfully entered the running state. In a multistream graph, entire streams might be playing successfully. The application must determine whether to stop running or not.

IMediaControl::Stop

IMediaControl Interface

Switches all filters in the filter graph to a stopped state.

HRESULT Stop( );

Return Values

Returns an HRESULT value.

Remarks

In this mode, filters release resources and no data is processed. If the filters are in a running state, this method pauses them before stopping them. This allows video renderers to make a copy of the current frame for poster frame display while stopped.

IMediaControl::StopWhenReady

IMediaControl Interface

Waits for an operation such as Pause to complete, allowing filters to queue up data, then stops the filter graph.

HRESULT StopWhenReady( );

Return Values

Returns an HRESULT value.

Remarks

Changing the current position when stopped will not normally repaint the video window with the new position. Applications will need to enter Pause mode to do this. Calling StopWhenReady instead of simply calling Stop after this pause ensures that the graph is fully paused, and that data has arrived at the video renderer and has been displayed before the graph is stopped.

This method is run asynchronously so that the application regains control immediately and can respond to user input. Use this method rather than calling IMediaControl::GetState with an INFINITE time-out, followed by IMediaControl::Stop.


IMediaEvent Interface

This interface supports event notification from the filter graph and filters within it to the application. It is decoupled by using a queuing scheme rather than callbacks, because events can be notified from worker threads that cannot safely call back into application code.

An event code and two DWORD values represent event notification information. Your application can use this for typical completion of asynchronous operations, errors that occur during asynchronous operation, or user-initiated events, such as when a user clicks a hot spot.

Filters within the filter graph and the filter graph itself raise event notifications. Possible events include playback completion or asynchronous playback errors. In addition, the filter graph provides a method to generate events at specific reference clock times. The filter graph exposes an IMediaEventSink interface that the filters within the graph can call to pass event notifications to the application.

Event notifications are placed in a queue. An application calls the IMediaEvent::GetEvent method to retrieve the next notification from the queue. This method blocks until there is an event to return. The GetEvent time-out parameter (msTimeout) allows the application to specify the time, in milliseconds, to wait for an event, including values of zero and INFINITE. After calling GetEvent, applications should always call FreeEventParams to release any resource associated with the event.

In addition, applications can retrieve the event handle. IMediaEvent::GetEventHandle returns a handle to a manual-reset event created by the Microsoft® Win32® CreateEvent function. This event is in a signaled state as long as there are event notifications to collect. The IMediaEvent::GetEvent method clears the event when there are no more event notifications to collect. This allows an application to use an application programming interface (API), such as MsgWaitForMultipleObjects, to wait for events and other occurrences at the same time. This event handle will be closed when the filter graph is released; therefore, applications should ensure that they are not using it after this point.

The filter graph manager handles some events raised by filters that are not passed to the application. One example of this is the EC_REPAINT event notification. By default the filter graph manager handles this event by pausing the filter graph and repainting the video renderer's static images. An application can override default handling for a specific event by calling the IMediaEvent::CancelDefaultHandling method with the event value as a parameter. The IMediaEvent::RestoreDefaultHandling method reinstates default handling for the specified event value. These methods have no effect on events that have no default handling.

If an error occurs during the transition to a running state on any filter, the IMediaControl::Run method returns an error value. In this case, some filters within the graph might be running successfully. The filter graph leaves it up to the application to determine whether to stop the graph in case of an error. After the IMediaControl::Run method has returned, event notifications report any additional errors. The EC_ERRORABORT and EC_USERABORT event notifications indicate that playback has probably stopped in the graph (certainly in the filter that reported it). Other errors and events indicate that it is still running. Note, however, that in all cases the graph remains in running mode until the application explicitly changes it to stopped or paused mode.

If the streams in the filter graph detect the end of the stream, the streams report this by using the EC_COMPLETE event notification. The filter graph manager asks filters if they can report EC_COMPLETE by means of seekable renderers.

A seekable renderer is one that supports the IMediaPosition interface from the filter and that has only input pins, or whose input pins report through IPin::QueryInternalConnections that they are rendered. The filter graph uses IPin::QueryInternalConnections and IMediaPosition to detect seekable renderers. A seekable renderer should report EC_COMPLETE when all seekable streams on that filter have reached the stream's end.

A renderer can produce EC_COMPLETE (and a regular filter produce EndOfStream) for one of four reasons as follows:

  • The typical case: Whether there is data arriving or not if it succeeds all calls to Receive it will eventually get EndOfStream. If the end of the media is reached and when all data and EndOfStream has been processed it will signal EC_COMPLETE.
  • The filter can never produce any data. In that case it just passes EC_COMPLETE immediately when a Run method is called. For example, a filter would pass EC_COMPLETE if none if its input pins is connected.
  • The complicated case, sometimes used by the wave renderer: It can't render data right now even though it's getting it but it may be able to later. In that case it fails the first Receive, schedules an EC_COMPLETE for a time tStop minus tStart in the future (based on the NewSegment parameters). If it finds it can start sending data it signals an EC_NEED_RESTART. A better approach could be to use stream control for this to avoid stopping and starting the graph.
  • It detects an unrecoverable error. Then, like any filter, it signals end of stream which for a renderer means signaling EC_COMPLETE.

The filter graph manager will not pass EC_COMPLETE to the application until an EC_COMPLETE event notification has been received from each stream. For example, if a live camera stream is playing as the background for a video playing from a file, the application will be notified about EC_COMPLETE when the video and audio streams from the file have come to the stream's end, even though the live source is still playing. In this case, too, the filter graph remains in running mode until the application explicitly calls the IMediaControl::Pause or IMediaControl::Stop method.

Your application can disable the aggregation of EC_COMPLETE messages by calling IMediaEvent::CancelDefaultHandling with EC_COMPLETE as the parameter. In this case, all EC_COMPLETE events raised by the filters will be passed directly to the application.

For a list of system-defined event notifications, see Event Notification Codes.

Note All events must be handled if a handle to an IMediaEvent interface is obtained otherwise events will pile up and cause the heap to be used up.

When to Implement

The filter graph manager implements this interface.

You can use the CMediaEvent class, which handles the IDispatch implementation for Automation, to help implement this interface.

When to Use

Applications use this interface to retrieve event notifications or event handles from the filter graph manager. For example, an application can retrieve the EC_COMPLETE notification to find out when a media stream has been rendered completely.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaEvent methods | Description
GetEventHandle | Retrieves a handle to a manual-reset event that will be signaled.
GetEvent | Retrieves the next notification event.
WaitForCompletion | Blocks execution of the application thread until the graph's operation finishes.
CancelDefaultHandling | Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling | Restores default handling for this event.
FreeEventParams | Frees resources associated with the parameters to an event.

IMediaEvent::CancelDefaultHandling

IMediaEvent Interface

Cancels any default handling by the filter graph of the specified event and ensures that it is passed to the application.

HRESULT CancelDefaultHandling(
long lEvCode
);

Parameters
lEvCode
Event code for which to cancel default handling.
Return Values

Returns S_OK if successful, or S_FALSE if the event does not have any default handling.

Remarks

Currently the filter graph manager applies default handling only to EC_COMPLETE and EC_REPAINT.

IMediaEvent::FreeEventParams

IMediaEvent Interface

Frees resources associated with the parameters of an event.

HRESULT FreeEventParams(
long lEventCode,
long lParam1,
long lParam2
);

Parameters
lEventCode
[in] Next event notification.
lParam1
[in] First parameter of the event.
lParam2
[in] Second parameter of the event.
Return Values

Returns an HRESULT value.

Remarks

Event parameters can be of type LONG or BSTR. If a BSTR is passed as an event, it will have been allocated by the task allocator and should be freed using this method. No reference-counted interfaces are passed to an application using IMediaEvent::GetEvent because these cannot be overridden by IMediaEvent::CancelDefaultHandling. Therefore, this method is not used to release interfaces.

IMediaEvent::GetEvent

IMediaEvent Interface

Retrieves the next notification event.

HRESULT GetEvent(
long * lEventCode,
long * lParam1,
long * lParam2,
long msTimeout
);

Parameters
IEventCode
[out] Next event notification.
lParam1
[out] First parameter of the event.
lParam2
[out] Second parameter of the event.
msTimeout
[in] Time, in milliseconds, to wait before assuming that there are no events.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. If the time-out is zero and no event is waiting, or if the time-out elapses before an event appears, this method returns E_ABORT.

Remarks

The application can pass a time-out value of INFINITE to indicate that the method should block until there is an event; however, applications should avoid using INFINITE. Threads cannot process any messages while waiting in GetEvent. If you call GetEvent from the thread that processes Windows messages, specify only small wait times on the call in order to remain responsive to user input. This is most important when streaming data from a source such as the Internet, because state transitions can take significantly more time to complete.

After calling GetEvent, applications should always call FreeEventParams to release any resource associated with the event.

For a list of notification codes and event parameter values, see Event Notification Codes.

IMediaEvent::GetEventHandle

IMediaEvent Interface

Retrieves a handle to a manual-reset event that will be signaled as long as there are event notifications to deliver.

HRESULT GetEventHandle(
OAEVENT * hEvent
);

Parameters
hEvent
[out] Handle for the event.
Return Values

Returns an HRESULT value.

Remarks

You can monitor events (including the retrieved event) and messages on a single thread; to do this, declare a HANDLE variable, cast it to an OAEVENT pointer, then pass it to GetEventHandle. You must cast the pointer to an OAEVENT pointer because HANDLE is not a valid OLE Automation type. The following code fragment demonstrates how to cast and use the HANDLE.

HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

You can pass the retrieved event handle to the Microsoft Win32 WaitForMultipleObjects or MsgWaitForMultipleObjects functions to wait for event notifications at the same time as other messages and events on a single thread. The implementation of GetEvent sets and resets the handle within the application, so applications should not reset the handle themselves.

IMediaEvent::RestoreDefaultHandling

IMediaEvent Interface

Reinstates the normal default handling by a filter graph for the specified event, if there is one.

HRESULT RestoreDefaultHandling(
long lEvCode
);

Parameters
lEvCode
[in] Event to restore.
Return Values

Returns S_OK if successful, or S_FALSE if there is no default handling for this event.

Remarks

Events that have default handling in place, such as EC_REPAINT, are not typically passed to the application.

IMediaEvent::WaitForCompletion

IMediaEvent Interface

Blocks execution of the application thread until the graph's operation finishes.

HRESULT WaitForCompletion(
long msTimeout,
long * pEvCode
);

Parameters
msTimeout
[in] Duration of the time-out, in milliseconds. Pass zero to return immediately. To block indefinitely, pass INFINITE.
pEvCode
[out] Event that terminated the wait. This value can be one of the following:
Value | Meaning
EC_COMPLETE | Operation completed.
EC_ERRORABORT | Error. Playback can't continue.
EC_USERABORT | User terminated the operation.
Zero (0) | Operation has not completed.
Return Values

Returns one of the following HRESULT values.
Value | Meaning
E_ABORT | Function timed out before the operation completed. This is equivalent to a zero pEvCode value.
S_OK | Operation completed.

Remarks

This method is the equivalent of blocking until the event notification EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT is received, or the time-out occurs.

When this method returns, the filter graph is still running. This method assumes that separate calls to the IMediaEvent interface are not being made. This method fails if the graph is not in or transitioning into a running state.

The time-out parameter (msTimeout) specifies the length of time to wait for completion. To test if the operation completed, specify a zero msTimeout value and check the event code value (pEvCode) for zero, indicating that the operation is not completed.


IMediaEventEx Interface

This interface derives from IMediaEvent and adds a method that allows registration of a window to receive messages when events occur.

When to Implement

This interface is implemented by the filter graph manager.

Unlike IMediaEvent, IMediaEventEx is not available through Automation, and therefore cannot be called directly from Visual Basic.

The CMediaEvent Class supports IMediaEventEx.

When to Use

This interface is used by applications to receive notification that an event has occurred. Applications can then avoid using a separate thread that waits until an event is set.

For a list of system-defined event notifications, see DirectShow Event Notification Codes.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaEvent methods | Description
GetEventHandle | Retrieves a handle to a manual-reset event that will be signaled.
GetEvent | Retrieves the next notification event.
WaitForCompletion | Waits until the graph's operation has completed.
CancelDefaultHandling | Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling | Restores default handling for this event.
FreeEventParams | Frees resources associated with the parameters to an event.
IMediaEventEx methods | Description
SetNotifyWindow | Registers a window that will handle messages when a specified event occurs.
SetNotifyFlags | Turns event notifications on or off.
GetNotifyFlags | Retrieves whether event notifications are on or off.

IMediaEventEx::GetNotifyFlags

IMediaEventEx Interface

Retrieves whether event notifications are on or off.

HRESULT GetNotifyFlags(
[out] long *lplNoNotifyFlags
);

Parameters
lplNoNotifyFlags
[out] Pointer to a value indicating whether event notifications should be on or off. 0x00 indicates notifications are on and 0x01 indicates notifications are off.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_OK if successful or E_POINTER if lplNoNotifyFlags is NULL.

Remarks

The handle returned by the GetEventHandle method will be signaled at end of stream.

IMediaEventEx::SetNotifyFlags

IMediaEventEx Interface

Turns event notifications on or off.

HRESULT SetNotifyFlags(
long lNoNotifyFlags
);

Parameters
lNoNotifyFlags
[in] Value indicating whether event notifications should be on or off. Specify 0x00 to turn notifications on or specify 0x01 to turn notification off.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_OK if successful or E_INVALIDARG if the argument is invalid.

Remarks

If notification has been turned off, the handle returned by the GetEventHandle method will be signaled at end of stream.

IMediaEventEx::SetNotifyWindow

IMediaEventEx Interface

Registers a window that will handle messages in response to all events from an object.

HRESULT SetNotifyWindow(
OAHWND hwnd,
long lMsg,
long lInstanceData
);

Parameters
hwnd
[in] Handle of window to notify. Pass NULL to stop notification.
lMsg
[in] The window message to be passed as the notification.
lInstanceData
[in] Value (instance data) to be passed as the lParam parameter for the lMsg message.
Return Values

Returns S_OK if successful or E_INVALIDARG if an argument is invalid.

Remarks

This method designates a window as the recipient of messages generated by or sent to the current DirectShow object. You can use this method to monitor the messages from multiple sources in a single window, which lowers processing overhead.

If an event occurs, DirectShow posts the notification message specified in lMsg to the window specified by hwnd. SetNotifyWindow sets the message's lParam parameter to lInstanceData and its wParam parameter to zero.

You can retrieve the event information by calling the GetEvent method when the destination window receives the message.

All event types post the message; when it arrives, any number of events, including zero, might actually be in the queue. If more than one event is in the queue when you call SetNotifyWindow, DirectShow posts only one message. If the application can receive the message after some other action has cleared events from the queue, there might be no events in the queue. For example, the Stop method clears all EC_COMPLETE events from the queue.


IMediaEventSink Interface

The filter graph manager exposes the IMediaEventSink interface; it is called from filters to notify events. Applications use the IMediaEvent interface on the filter graph manager to retrieve these events.

When to Implement

There is no need to implement this method because it is implemented by the filter graph manager.

When to Use

Filters use this interface to post event notifications.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaEventSink methods | Description
Notify | Notifies an event.

IMediaEventSink::Notify

IMediaEventSink Interface

Notifies an event.

HRESULT Notify(
long EventCode,
long EventParam1,
long EventParam2
);

Parameters
EventCode
[in] Identifier of the event.
EventParam1
[in] First event parameter.
EventParam2
[in] Second event parameter.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The event is queued but not delivered to the application on this thread. For a list of notification codes and event parameter values, see Event Notification Codes.


IMediaFilter Interface

Multimedia components that provide time-based data expose the IMediaFilter interface. This interface abstracts an object that processes time-based data streams and represents a multimedia device (possibly implemented in software). It controls the active or running state of the object and the synchronization of this state with other objects in the system.

This interface inherits the IPersist interface.

When to Implement

Methods on this interface should be implemented as part of any filter. This is typically done by using the base class CBaseFilter, which implements IBaseFilter and IMediaFilter.

When to Use

Because the IMediaFilter interface is inherited by the IBaseFilter interface, which adds other necessary methods required to be exported by filters, this interface is not normally used directly by the filter graph manager or other filters. It can, however, be of use to plug-in distributors. For example, the filter graph manager internally exports IMediaFilter; its plug-in distributor exports IMediaControl and calls the IMediaFilter methods to implement its own methods.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaFilter methods | Description
Stop | Informs the filter to transition to the new (stopped) state.
Pause | Informs the filter to transition to the new (paused) state.
Run | Informs the filter to transition to the new (running) state.
GetState | Determines the state of the filter.
SetSyncSource | Identifies the reference clock to which the filter should synchronize activity.
GetSyncSource | Retrieves the current reference clock (or NULL if there is no clock). Passes a time value to synchronize independent streams.

IMediaFilter::GetState

IMediaFilter Interface

Determines the filter's state.

HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);

Parameters
dwMilliSecsTimeout
[in] Duration of the time-out, in milliseconds. To block indefinitely, pass INFINITE.
State
[out] Returned state of the filter. States include stopped, paused, running, or intermediate (in the process of changing).
Return Values

Returns S_OK if the state is running, paused, or inactive; otherwise, returns VFW_S_STATE_INTERMEDIATE if the transition is not complete (the time-out expired). The state returned in the latter case is the one being changed to.

Remarks

Usually, renderer filters will return VFW_S_STATE_INTERMEDIATE until they receive enough data to render at least one sample. In some circumstances, a filter will find that it can supply data on all of its output streams. This condition usually occurs because of unusual or bad data. An example of unusual data might be an MPEG slide show, where video frames occur infrequently in the data but audio is continuous. In this case, a video frame in the video stream might not be found until a certain spot in the audio stream. If the filter discovers that it cannot complete the state change (for this or any other reason), it can return VFW_S_CANT_CUE.

When an application calls the filter graph manager's IMediaControl::GetState method, the filter graph manager calls GetState on the filter and continues to poll. If the filter graph manager receives VFW_S_CANT_CUE back from the filter, it returns this value to the application from its IMediaControl::GetState method.

IMediaFilter::GetSyncSource

IMediaFilter Interface

Retrieves the current reference clock in use by this filter.

HRESULT GetSyncSource(
IReferenceClock ** pClock
);

Parameters
pClock
[out] Pointer to a reference clock; it will be set to the IReferenceClock interface.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The returned interface (if it is non-NULL) will have a reference added by the IUnknown::AddRef method. The calling application should release the interface by calling the IUnknown::Release method when it has finished with the pointer.

IMediaFilter::Pause

IMediaFilter Interface

Informs the filter to transition to the new state.

HRESULT Pause(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value | Meaning
Error value | Transition failed.
S_FALSE | Transition is not complete, but no error has occurred.

Remarks

The state transition might not be immediate (external mechanical activity might be involved, for example). The state method might return before the transition has completed.

IMediaFilter::Run

IMediaFilter Interface

Informs the filter to transition to the new (running) state. Passes a time value to synchronize independent streams.

HRESULT Run(
REFERENCE_TIME tStart
);

Parameters
tStart
Time value of the reference clock.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The tStart parameter is the amount to be added to the IMediaSample time stamp to determine the time at which that sample should be rendered according to the reference clock. That is, it is the reference time at which a sample with a stream time of zero should be rendered.

For example, the time value for the beginning of the stream is the time at which the first sample should appear. If the application restarts from paused mode in midstream, tStart is the amount of time paused, plus the start time.

The filter graph provides this information to its filters. An application calling the filter graph may pass a start time of zero, in which case the filter graph calculates a time that will begin as soon as possible. Filter graphs accept zero to mean as soon as possible; most filters do not.

IMediaFilter::SetSyncSource

IMediaFilter Interface

Identifies the reference clock to which the filter should synchronize activity.

HRESULT SetSyncSource(
IReferenceClock * pClock
);

Parameters
pClock
[in] Pointer to the IReferenceClock interface.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is of most importance to rendering filters and might not apply to other filters. The pClock parameter can be NULL, meaning that the filter should run as fast as possible at its current quality settings without any attempt to synchronize. For example, a filter graph that is doing compression probably runs in this mode. Each filter takes as long as it needs.

IMediaFilter::Stop

IMediaFilter Interface

Informs the filter to transition to the new state.

HRESULT Stop(void);

Return Values

Returns S_OK if the transition is complete; otherwise, returns one of the following values.
Value | Meaning
Error value | Transition failed.
S_FALSE | Transition is not complete, but no error has occurred.

Remarks

The state transition might not be immediate (external mechanical activity might be involved, for example). The state functions might return before the transition has completed.


IMediaPosition Interface

Applications communicating with the filter graph can call methods on this interface to set or retrieve properties such as the duration of the stream, the start and stop times, the preroll time, the rate, and the current position. The filter graph uses these properties on seekable filters to control the playback of streams within the graph; where there are multiple streams, the filter graph sets them all to play in parallel, beginning at the same position, and will report the duration as being the duration of the longest stream. The REFTIME parameters used in this interface are double value, representing a fractional number of seconds. Internally, filters will store time to an accuracy of 100 nanoseconds.

When to Implement

The filter graph manager exposes the IMediaPosition interface if any of the filters within the graph are seekable (can seek to an arbitrary position in the stream). This normally means a seekable file source filter. Filters, such as a file source filter, will expose IMediaPosition if they can seek their data or if their output pin represents a seekable stream. The renderer filter should also expose this interface. Output pins of transform filters expose this interface to pass the positioning information upstream from the renderer through each intermediate filter to the seekable filter.

Use the CMediaPosition class to help implement this interface on a filter. Use the CPosPassThru base class to implement this interface on output pins of transform filters used to pass media positioning information upstream. This is enabled by default in the pin base classes.

When to Use

Applications can use this interface to set or retrieve media positioning properties. Most commonly, an application will use the methods on this interface to play a media stream for some duration starting at some set position in the stream (for example, 10 seconds from the start).

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaPosition methods | Description
get_Duration | Retrieves the total duration of the media stream.
put_CurrentPosition | Sets the time that the media stream begins.
get_CurrentPosition | Retrieves the current position in terms of the total length of the media stream.
get_StopTime | Retrieves the position within the media stream at which playback should stop.
put_StopTime | Sets the position within the media stream at which playback should stop.
get_PrerollTime | Retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_PrerollTime | Sets the time prior to the start position that the filter graph begins any nonrandom access device rolling.
put_Rate | Sets the playback rate, relative to normal playback of the media stream.
get_Rate | Retrieves the playback rate, relative to normal playback of the media stream.
CanSeekForward | Determines if the current position can be moved forward in the media stream.
CanSeekBackward | Determines if the current position can be moved backward in the media stream.

IMediaPosition::CanSeekBackward

IMediaPosition Interface

Determines if the current position can be moved backward in the media stream.

HRESULT CanSeekBackward(
LONG *pCanSeekBackward
);

Parameters
pCanSeekBackward
[out] Set to OATRUE if able to seek backward; otherwise set to OAFALSE.
Return Values

Returns an HRESULT value.

IMediaPosition::CanSeekForward

IMediaPosition Interface

Determines if the current position can be moved forward in the media stream.

HRESULT CanSeekForward(
LONG *pCanSeekForward
);

Parameters
pCanSeekForward
[out] Set to OATRUE if able to seek forward; otherwise set to OAFALSE.
Return Values

Returns an HRESULT value.

IMediaPosition::get_CurrentPosition

IMediaPosition Interface

Retrieves the current position in terms of the total length of the media stream.

HRESULT get_CurrentPosition(
REFTIME* pllTime
);

Parameters
pllTime
[out] Reference time of the current position.
Return Values

Returns an HRESULT value.

Remarks

This is the position that playback has reached. It is a value between zero and the total duration of the media (that is, it does not take into account the rate and start time). If the filter graph is paused, this is the position at which it will restart.

When the filter graph is stopped or paused, this method returns the position at which playback will recommence. When the filter graph is running, the filter graph manager returns the position according to the reference clock. If an individual filter implements this, it should return the stream time of the sample it is processing (that is, the offset time from the beginning) when paused or running. If you implement this using stream time or the reference clock, remember to adjust the value you return for start position and playback rate so that the value returned is in terms of the media's total duration.

After stopping or pausing, a run command causes playback to begin at the current position. This will be where playback stopped or paused, unless there has been an IMediaPosition::put_CurrentPosition call in the meantime.

IMediaPosition::get_Duration

IMediaPosition Interface

Retrieves the total duration of the media stream.

HRESULT get_Duration(
REFTIME* plength
);

Parameters
plength
[out] Returned length of the media stream.
Return Values

Returns an HRESULT value.

Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate.

IMediaPosition::get_PrerollTime

IMediaPosition Interface

Retrieves the time prior to the start position that any nonrandom access device should start rolling.

HRESULT get_PrerollTime(
REFTIME* pllTime
);

Parameters
pllTime
[out] Returned preroll time as a double pointer value.
Return Values

Returns an HRESULT value.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

IMediaPosition::get_Rate

IMediaPosition Interface

Retrieves the rate of playback relative to normal playback speed.

HRESULT get_Rate(
double * pdRate
);

Parameters
pdRate
[out] Returned rate.
Return Values

Returns an HRESULT value.

Remarks

A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.

IMediaPosition::get_StopTime

IMediaPosition Interface

Retrieves the time at which the media stream stops.

HRESULT get_StopTime(
REFTIME* pllTime
);

Parameters
pllTime
[out] Returned stop time as a double pointer value.
Return Values

Returns an HRESULT value.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

IMediaPosition::put_CurrentPosition

IMediaPosition Interface

Sets the time that the media stream begins.

HRESULT put_CurrentPosition(
REFTIME llTime
);

Parameters
llTime
[in] Start time expressed as a double value.
Return Values

Returns an HRESULT value.

Remarks

The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued.

If this method is called when the filter graph manager is running, the filter graph manager will pause the graph, run the method, and then issue a new run command.

If called when the filter graph is paused, this method must flush existing data by using IPin::BeginFlush and IPin::EndFlush before pushing the new data (at the new current position).

Setting the current position when paused or stopped causes playback to resume from the new start position when the run command is issued.

The current position is applied before the rate and therefore is the position at typical playback speed.

IMediaPosition::put_PrerollTime

IMediaPosition Interface

Sets the time prior to the start position that any nonrandom access device should start rolling.

HRESULT put_PrerollTime(
REFTIME llTime
);

Parameters
llTime
[in] Preroll time to be set.
Return Values

Returns an HRESULT value.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

IMediaPosition::put_Rate

IMediaPosition Interface

Sets the rate of playback relative to normal speed.

HRESULT put_Rate(
double dRate
);

Parameters
dRate
[in] Rate to set.
Return Values

Returns an HRESULT value.

Remarks

This method allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop samples.

IMediaPosition::put_StopTime

IMediaPosition Interface

Sets the time at which the media stream will stop.

HRESULT put_StopTime(
REFTIME llTime
);

Parameters
llTime
[in] Stop time as a double value.
Return Values

Returns an HRESULT value.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.


IMediaPropertyBag Interface

The IMediaPropertyBag interface is an interface that is exposed on filters that need to record copyright information. The interface inherits from the IPropertyBag interface and supports its Read and Write methods for properties. It includes one additional method, EnumProperty, which retrieves or sets a property and value pair.

You can find more information on the IMediaPropertyBag interface in the COM documentation of the Platform SDK.

When to Implement

Implement this interface when you need to expose copyright information on filters

When to Use

Applications should use this interface when they need to copyright the stream name of a multimedia file.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaPropertyBag methods | Description
EnumProperty | Retrieves or sets a property and value pair.

IMediaPropertyBag::EnumProperty

IMediaPropertyBag Interface

Retrieves or sets a property and value pair.

HRESULT EnumProperty(
ULONG iProperty,
VARIANT * pvarPropertyName,
VARIANT * pvarPropertyValue );

Parameters
iProperty
[in] Index value of the pair to get or set.
pvarPropertyName
[in, out] Property's name.
pvarPropertyValue
[in, out] Property's value.
Return Values

This method returns HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) if the iProperty parameter is larger than the number of properties there are (iProperty is zero-based). Otherwise, it will return an HRESULT value that depends on the implementation of the interface.

Remarks

The pvarPropertyName parameter is always a string; the caller should set the variant type to VT_EMPTY or VT_BSTR before calling this function. The pvarPropertyValue parameter can be any variant; the caller should set the variant type to VT_EMPTY or what is expected.


IMediaSample Interface

The IMediaSample interface provides shared memory buffer functionality, holds some properties about the data, and holds a pointer to the data itself. It is used by connected pins to transport media samples from one pin to another.

The IMediaSample2 interface extends the functionality of this interface to allow you to set and to retrieve media sample properties.

When to Implement

Implement this interface if you are providing an allocator (buffer) to be used for transporting media samples between filters. This interface is implemented by the CMediaSample class in the DirectShow™ class library.

When to Use

Filters use methods on this interface to set properties and pass data to another filter. Downstream filters use methods on this interface to read the media sample's data and properties. Filters can modify the data in a media sample in place or can make a copy of the sample, modify the copy, and pass it on.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaSample methods | Description
GetPointer | Retrieves a read/write pointer to this buffer's memory.
GetSize | Returns the size, in bytes, of the buffer data area.
GetTime | Retrieves the stream times at which this sample should begin and finish.
SetTime | Sets the stream times at which this sample should begin and finish.
IsSyncPoint | Determines if the beginning of a sample is a synchronization point.
SetSyncPoint | Sets the synchronization point.
IsPreroll | Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetPreroll | Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.
GetActualDataLength | Retrieves the data length of the sample.
SetActualDataLength | Sets the data length of the sample.
GetMediaType | Retrieves the media type of the sample.
SetMediaType | Sets the media type of the sample.
IsDiscontinuity | Indicates a discontinuity property. If S_OK is returned, sample is not contiguous with previous sample.
SetDiscontinuity | Sets the discontinuity property. Set to TRUE if sample is new after a seek or dropped sample.
GetMediaTime | Retrieves the media time stamps for the sample.
SetMediaTime | Sets the media time stamps for the sample.

IMediaSample::GetActualDataLength

IMediaSample Interface

Retrieves the data length of the sample.

HRESULT GetActualDataLength(void);

Return Values

Returns an HRESULT value that is the length.

Remarks

Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.

IMediaSample::GetMediaTime

IMediaSample Interface

Retrieves the media time stamps for this sample.

HRESULT GetMediaTime(
LONGLONG * pTimeStart,
LONGLONG * pTimeEnd
);

Parameters
pTimeStart
[out] Retrieved beginning media time.
pTimeEnd
[out] Retrieved ending media time.
Return Values

Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.

IMediaSample::GetMediaType

IMediaSample Interface

Retrieves the media type of the IMediaSample object.

HRESULT GetMediaType(
AM_MEDIA_TYPE ** ppMediaType
);

Parameters
ppMediaType
[in] Pointer to a pointer to the retrieved media type.
Return Values

Returns an HRESULT value. When a sample is received and there is no format change, this method returns S_FALSE.

Remarks

This method allows for limited in-band format changes. Free the format block with FreeMediaType, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.

IMediaSample::GetPointer

IMediaSample Interface

Retrieves a read/write pointer to this buffer's memory.

HRESULT GetPointer(
BYTE ** ppBuffer
);

Parameters
ppBuffer
[out] Retrieved pointer to the buffer.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IMediaSample::GetSize

IMediaSample Interface

Returns the size, in bytes, of the buffer data area.

HRESULT GetSize(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.

IMediaSample::GetTime

IMediaSample Interface

Retrieves the stream times at which this sample should begin and finish.

HRESULT GetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);

Parameters
pTimeStart
[out] Retrieved beginning stream time.
pTimeEnd
[out] Retrieved ending stream time.
Return Values

Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.

IMediaSample::IsDiscontinuity

IMediaSample Interface

Determines if there is discontinuity in the data stream.

HRESULT IsDiscontinuity(void);

Return Values

Returns S_OK if the sample is a discontinuous sample, or S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.

Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

IMediaSample::IsPreroll

IMediaSample Interface

Preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT IsPreroll(void);

Return Values

Returns S_OK if the sample is a preroll sample, or S_FALSE if not; otherwise, returns an HRESULT error value. Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

IMediaSample::IsSyncPoint

IMediaSample Interface

Determines if the beginning of a sample is a synchronization point.

HRESULT IsSyncPoint(void);

Return Values

Returns S_OK if the sample is a synchronization point and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

If the bTemporalCompression member of the AM_MEDIA_TYPE structure is FALSE, all samples are synchronization points. A filter can begin a stream at any synchronization point.

Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

IMediaSample::SetActualDataLength

IMediaSample Interface

Sets the sample's data length.

HRESULT SetActualDataLength(
long lLen
);

Parameters
lLen
Length of the data in the media sample, in bytes.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IMediaSample::SetDiscontinuity

IMediaSample Interface

Sets the discontinuity property.

HRESULT SetDiscontinuity(
BOOL bIsDiscontinuity
);

Parameters
bIsDiscontinuity
[in] Set to TRUE to specify the media sample as discontinuous with the previous sample.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Discontinuous samples occur when a source filter seeks to a different place in the media stream or when a filter drops samples for quality control.

Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

IMediaSample::SetMediaTime

IMediaSample Interface

Sets the media time stamps for this sample.

HRESULT SetMediaTime(
LONGLONG * pTimeStart,
LONGLONG * pTimeEnd
);

Parameters
pTimeStart
[in] Beginning media time.
pTimeEnd
[in] Ending media time.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetMediaTime to return an error.

IMediaSample::SetMediaType

IMediaSample Interface

Sets the media type for the IMediaSample object.

HRESULT SetMediaType(
AM_MEDIA_TYPE * pMediaType
);

Parameters
pMediaType
Pointer to a pointer to a media type structure to be set.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method allows for limited in-band format changes.

IMediaSample::SetPreroll

IMediaSample Interface

Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT SetPreroll(
BOOL bIsPreroll
);

Parameters
bIsPreroll
Set to TRUE to specify the media sample as a preroll sample; otherwise, set to FALSE.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.

Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

IMediaSample::SetSyncPoint

IMediaSample Interface

Property of a synchronization point.

HRESULT SetSyncPoint(
BOOL bIsSyncPoint
);

Parameters
bIsSyncPoint
[in] Set to TRUE to specify the sample as a synchronization point; otherwise, set to FALSE.
Return Values

Returns S_OK.

Remarks

A filter can begin a stream at any synchronization point. Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

IMediaSample::SetTime

IMediaSample Interface

Sets the stream time when this sample should begin and finish.

HRESULT SetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);

Parameters
pTimeStart
[in] Stream time at which the sample begins.
pTimeEnd
[in] Stream time at which the sample ends.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetTime to return VFW_S_NO_STOP_TIME.


IMediaSample2 Interface

The IMediaSample2 interface derives from the IMediaSample interface. It enables you to set and to retrieve sample properties such as start and stop time that are defined in AM_SAMPLE2_PROPERTIES, and sample flags defined in the AM_SAMPLE_PROPERTY_FLAGS structure.

When to Implement

Implement this interface when you implement an allocator that creates media samples. The CMediaSample class in the Microsoft® DirectShow™ class library implements this interface.

When to Use

Use this interface when you want to retrieve properties from a media sample that are available through this interface and through the IMediaSample interface or if you want to retrieve multiple sample properties in one call.

Not all media samples will support IMediaSample2, so use the IUnknown::QueryInterface method to get a pointer to the sample's IMediaSample2 interface and check for failure.

If an allocator generates samples, then either all of the media samples must support IMediaSample2 or none of them will.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaSample methods | Description
GetPointer | Retrieves a read/write pointer to this buffer's memory.
GetSize | Returns the size, in bytes, of the buffer data area.
GetTime | Retrieves the stream times at which this sample should begin and finish.
SetTime | Sets the stream times at which this sample should begin and finish.
IsSyncPoint | Determines if the beginning of a sample is a synchronization point.
SetSyncPoint | Sets the synchronization point.
IsPreroll | Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetPreroll | Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.
GetActualDataLength | Retrieves the data length of the sample.
SetActualDataLength | Sets the data length of the sample.
GetMediaType | Retrieves the media type of the sample.
SetMediaType | Sets the media type of the sample.
IsDiscontinuity | Indicates a discontinuity property. If S_OK is returned, sample is not contiguous with previous sample.
SetDiscontinuity | Sets the discontinuity property. Set to TRUE if sample is new after a seek or dropped sample.
GetMediaTime | Retrieves the media time stamps for the sample.
SetMediaTime | Sets the media time stamps for the sample.
IMediaSample2 methods | Description
GetProperties | Retrieves the properties of a media sample.
SetProperties | Sets the properties of a media sample.

IMediaSample2::GetProperties

IMediaSample2 Interface

Retrieves the properties of a media sample.

HRESULT GetProperties(
DWORD cbProperties,
BYTE * pbProperties
);

Parameters
cbProperties
[in] Length of property data to retrieve, in bytes.
pbProperties
[out] Pointer to a generic data buffer. cbProperties specifies the length of the data. This value can be NULL if cbProperties is NULL. Data conforms to the format of the AM_SAMPLE2_PROPERTIES structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default implementation returns S_OK.

Remarks

You can use this method to return only some of the sample properties by setting cbProperties to be less than the size of the AM_SAMPLE2_PROPERTIES structure.

For performance reasons, the pMediaType member returned in AM_SAMPLE2_PROPERTIES is merely a pointer to the data stored in the media sample. Therefore, the pointer will not necessarily be valid after the sample has been passed to another filter or after the Receive call to which it was passed has been completed. Also, you don't need to free the pointer as you do with the pointer returned from the IMediaSample::GetMediaType method.

IMediaSample2::SetProperties

IMediaSample2 Interface

Sets the properties of a media sample

HRESULT SetProperties(
DWORD cbProperties,
const BYTE * pbProperties
);

Parameters
cbProperties
[in] Length of property data to set, in bytes.
pbProperties
[in] Pointer to properties to set. cbProperties specifies the length of the data. This value can be NULL if cbProperties is NULL. Data conforms to the format of the AM_SAMPLE2_PROPERTIES structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.


IMediaSeeking Interface

Although IMediaPosition allows applications a simple seeking interface on a filter graph, it has a number of limitations. The IMediaPosition interface allows seeking only by using REFTIME time-based units; however, many filter graphs would prefer to seek on units of samples, video frames, or fields in a compressed stream. Also, the IMediaPosition interface uses separate methods to set and retrieve position properties, which can cause unnecessary filter flushing.

The IMediaSeeking interface improves on the IMediaPosition interface by allowing arbitrary formats for seekable units, such as frames, bytes, and 100-second units of time. It also offers the ability to start and stop times using a single method call, which is absent in IMediaPosition. When seeking to time units, IMediaSeeking expresses time as a 64-bit integer (LONGLONG), providing greater accuracy than IMediaPosition, which expresses time in decimal seconds stored as a double. However, because of this difference in time unit data types, only IMediaPosition supports Automation. IMediaPosition is maintained as an interface for this reason only. Applications not using Automation to seek the media stream should use the IMediaSeeking interface instead.

The IMediaSeeking interface is set by using a defined time format, such as TIME_FORMAT_MEDIA_TIME or TIME_FORMAT_SAMPLE, which then defines how parameters in other methods are interpreted. The format can be changed only when the filter graph is stopped (the default DirectShow plug-in distributor method for this method takes care of this automatically, effectively eliminating this restriction). Only one time format is available at any given time.

When a filter is seeked in media time, it must return a time at which the media seek positioned it. For example, if a source filter is seeked to frame 30, it might return 2 seconds if the video is 15 frames per second. With that position time (of 2 seconds), the filter graph manager can then seek all the other filters to that 2-second position so that the graph as a whole remains synchronized.

Time formats are globally unique identifiers (GUIDs), which are defined as follows:
GUID | Defined as
0L-0-0-0-0-0-0-0-0-0-0 | TIME_FORMAT_NONE
7b785570-8c82-11cf-bc0c-00aa00ac74f6 | TIME_FORMAT_FRAME
7b785571-8c82-11cf-bc0c-00aa00ac74f6 | TIME_FORMAT_BYTE
7b785572-8c82-11cf-bc0c-00aa00ac74f6 | TIME_FORMAT_SAMPLE
7b785573-8c82-11cf-bc0c-00aa00ac74f6 | TIME_FORMAT_FIELD
7b785574-8c82-11cf-bc0c-00aa00ac74f6 | TIME_FORMAT_MEDIA_TIME

When to Implement

The filter graph manager exposes the IMediaSeeking interface from the plug-in distributor (PID) that handles this interface. If none of the filters within the graph support this interface, the PID will return E_NOINTERFACE; if at least one filter supports the interface, but all such filters return E_NOTIMPL, the PID will return E_NOTIMPL. Otherwise, the filter graph manager will return either a success or the first failure it encounters.

A success normally means that a seekable file source filter was found. Filters, such as a file source filter, will expose IMediaSeeking if they can seek their data or if their output pin represents a seekable stream. The renderer filter also should expose this interface. Output pins of transform filters expose this interface to pass the positioning information upstream, from the renderer through each intermediate filter to the seekable filter.

Use the CPosPassThru base class to implement this interface on output pins of transform filters used to pass media positioning information upstream. This is enabled by default in the pin base classes. Renderers can use the same class, although in most cases they should use CRendererPosPassThru, which is derived from CPosPassThru, to implement this interface.

When to Use

Applications can use this interface to set or retrieve properties such as the duration of the stream, the current position, the stop time, and the media time format being used. Most commonly, an application will use the methods on this interface to play a media stream for some duration starting at some set position in the stream (for example, 10 seconds from the start).

A transform filter will call the IMediaSeeking methods on the connected upstream pin when passing media times upstream from the renderer.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaSeeking methods | Description
GetCapabilities | Returns the seeking capabilities of the media stream.
CheckCapabilities | Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.
IsFormatSupported | Determines if a specified time format is supported.
QueryPreferredFormat | Retrieves the preferred time format to be used by the interface.
GetTimeFormat | Retrieves the current time format.
IsUsingTimeFormat | Determines if the time format being used in the call is the same as the one currently in use by the interface.
SetTimeFormat | Sets the time format, which determines the format of units used during seeking.
GetDuration | Retrieves the length of time that the media stream will play.
GetStopPosition | Retrieves the position within the media stream at which playback should stop.
GetCurrentPosition | Retrieves the current position within the media stream.
ConvertTimeFormat | Converts a time from one time format to another.
SetPositions | Sets current and stop positions and applies flags to both.
GetPositions | Returns the current and stop position settings.
GetAvailable | Returns the range of times in which seeking is efficient.
SetRate | Sets a new playback rate.
GetRate | Returns the current rate.
GetPreroll | Retrieves the preroll settings.

IMediaSeeking::CheckCapabilities

IMediaSeeking Interface

Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.

HRESULT CheckCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
[in, out] Pointer to an AM_SEEKING_SEEKING_CAPABILITIES enum type containing the seeking capabilities flags to apply. These flags can be any combination of the following.
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekForwards
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanDoSegments
AM_SEEKING_Source
Return Values

Returns S_OK if all capabilities in pCapabilities are present, S_FALSE if some are present, or E_FAIL if none are present.

Remarks

This method determines which seeking capabilities are present on a media stream. It applies the pCapabilities flags using a bitwise-AND operation, and returns a value to indicate whether they match the capabilities of the media stream. The value of pCapabilities is accumulated between successive calls to this method so that the value of pCapabilities can be checked when an S_FALSE value is returned to find the capability that does not match.

IMediaSeeking::ConvertTimeFormat

IMediaSeeking Interface

Converts a time from one format to another.

HRESULT ConvertTimeFormat(
LONGLONG * pTarget,
const GUID * pTargetFormat,
LONGLONG Source,
const GUID * pSourceFormat
);

Parameters
pTarget
[out] Time in converted format.
pTargetFormat
[in] GUID of the format to convert to, or the currently selected format if NULL.
Source
[in] Time in original format.
pSourceFormat
[in] GUID of the format to be converted from, or the currently selected format if NULL.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns NOERROR for success and E_NOTIMPL if the method is not implemented.

Remarks

Time formats can be converted between any two of the following:
TIME_FORMAT_FIELD
TIME_FORMAT_FRAME
TIME_FORMAT_MEDIA_TIME
TIME_FORMAT_NONE
TIME_FORMAT_SAMPLE

IMediaSeeking::GetAvailable

IMediaSeeking Interface

Returns the range of times in which seeking is efficient.

HRESULT GetAvailable(
LONGLONG * pEarliest,
LONGLONG * pLatest
);

Parameters
pEarliest
[out] Earliest time that can be efficiently seeked to.
pLatest
[out] Latest time that can be efficiently seeked to.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success and E_NOTIMPL if the method is not implemented.

Remarks

This method is intended primarily for seeking in media streams that might have excessive latency, such as when playing back media "live" from an Internet server. The returned values indicate cached data that has already arrived, which can be easily seeked. It is assumed that seeking to values beyond these returned parameters will cause a delay while waiting for the data to arrive.

IMediaSeeking::GetCapabilities

IMediaSeeking Interface

Returns the seeking capabilities of the media stream.

HRESULT GetCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
[out] Seeking capability flags, which can be any combination of the following.
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekForwards
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanDoSegments
AM_SEEKING_Source
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK.

IMediaSeeking::GetCurrentPosition

IMediaSeeking Interface

Retrieves the current position in terms of the total length of the media stream.

HRESULT GetCurrentPosition(
LONGLONG* pCurrent
);

Parameters
pCurrent
[out] Current position in current time format units.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, or another COM return code otherwise.

Remarks

The current position is the position that playback has reached. It is a value between zero and the duration. If the filter graph is paused, this is the position at which it will restart.

Since IMediaSeeking uses media times for its time parameters, the current position value is independent of any rate or start position that might have been set.

When the filter graph is stopped or paused, this method returns the position at which playback will recommence. When the filter graph is running, the filter graph manager returns the position according to the data arriving at the renderer. If an individual filter implements this method, it should return the media time of the sample it is currently processing when paused or running.

After stopping or pausing, a run command causes playback to begin at the current position. This will be where playback stopped or paused, unless there has been an IMediaSeeking::SetPositions call in the meantime to reset the start position.

IMediaSeeking::GetDuration

IMediaSeeking Interface

Retrieves the length of time that the media stream will play.

HRESULT GetDuration(
LONGLONG* pDuration
);

Parameters
pDuration
[out] Returned length of the media stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, or another COM return code otherwise.

Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate. Although IMediaSeeking allows filters to be seeked in media time, it still requires that the media samples it sends downstream are time stamped appropriately.

IMediaSeeking::GetPositions

IMediaSeeking Interface

Returns the current and stop position settings.

HRESULT GetPositions(
LONGLONG * pCurrent,
LONGLONG * pStop
);

Parameters
pCurrent
[out] Start time in the current time format.
pStop
[out] Stop time in the current time format.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is provided for efficiency so that just one call will retrieve both the current and stop position.

IMediaSeeking::GetPreroll

IMediaSeeking Interface

Retrieves the preroll settings.

HRESULT GetPreroll(
LONGLONG * pllPreroll
);

Parameters
pllPreroll
[out] Returned preroll time.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success and E_NOTIMPL if the method is not implemented.

Remarks

This method retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.

IMediaSeeking::GetRate

IMediaSeeking Interface

Retrieves the current rate.

HRESULT GetRate(
double * dRate
);

Parameters
dRate
[out] Current rate, where 1 is the normal rate.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IMediaSeeking::GetStopPosition

IMediaSeeking Interface

Retrieves the time at which the media stream stops.

HRESULT GetStopPosition(
LONGLONG* pStop
);

Parameters
pStop
[out] Returned stop time.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, S_OK for success, or E_NOTIMPL if the method is not implemented.

Remarks

The stop position is a time between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

IMediaSeeking::GetTimeFormat

IMediaSeeking Interface

Retrieves the current time format, which determines the format of units used during seeking.

HRESULT GetTimeFormat(
GUID * pFormat
);

Parameters
pFormat
[out] Time format currently supported by this interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, or E_NOTIMPL if the method is not implemented.

Remarks

See the IsFormatSupported method for a list of time formats. Only one time format can be set on the filter graph at any one time.

IMediaSeeking::IsFormatSupported

IMediaSeeking Interface

Determines if a specified time format is supported.

HRESULT IsFormatSupported(
const GUID * pFormat
);

Parameters
pFormat
[in] Time format to compare.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK if the time format is supported; otherwise returns S_FALSE.

Remarks

Time formats are defined as follows:
GUID | Defined as
TIME_FORMAT_NONE | Seeking is not supported.
TIME_FORMAT_FRAME | Seeks to specific video frames.
TIME_FORMAT_SAMPLE | Seeks to samples in the stream.
TIME_FORMAT_FIELD | Seeks to interlaced video fields.
TIME_FORMAT_BYTE | Seeks to a byte in the stream.
TIME_FORMAT_MEDIA_TIME | Seeks to time stamps on the media samples.

Third-party vendors are encouraged to add their own time formats to this list.

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking Interface

Determines if the time format being used in the call is the same as the one currently in use by the interface.

HRESULT IsUsingTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
[in] Time format to check.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK if pFormat is the current time format; otherwise returns S_FALSE.

Remarks

This can be used in place of IMediaSeeking::GetTimeFormat to compare time formats, since it is faster and does not require copying the GUID.

IMediaSeeking::QueryPreferredFormat

IMediaSeeking Interface

Retrieves the preferred time format to be used by the interface.

HRESULT QueryPreferredFormat(
GUID * pFormat
);

Parameters
pFormat
[out] Time format preferred by the interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns NOERROR.

Remarks

See the description for IsFormatSupported for a list of available time formats. If the time format returned is not satisfactory, use the IsFormatSupported method to query for supported time formats that you can use.

IMediaSeeking::SetPositions

IMediaSeeking Interface

Sets current and stop positions and applies flags to both.

HRESULT SetPositions(
LONGLONG * pCurrent,
DWORD dwCurrentFlags,
LONGLONG * pStop,
DWORD dwStopFlags
);

Parameters
pCurrent
[in,out] Start position if stopped, or position from which to continue if paused.
dwCurrentFlags
[in] When seeking, one of these flags must be set to indicate the type of seek. The flags passed to this method should include one positioning value and (optionally) any of the nonpositioning values
Flag | Description
AM_SEEKING_NoPositioning | No change in positioning.
AM_SEEKING_AbsolutePositioning | Position supplied is absolute.
AM_SEEKING_RelativePositioning | Position supplied is relative to the current position.
AM_SEEKING_IncrementalPositioning | Stop position relative to current; useful for seeking when paused (only valid in conjunction with stop times).
AM_SEEKING_PositioningBitsMask | Mask flag; determine if seeking is required by performing a bitwise AND of the four flags listed above and this mask. If the resulting value is nonzero, some form of seeking is required. Check the value of the last two bits to determine which of the above flags are set.
AM_SEEKING_SeekToKeyFrame | Seek to the nearest key frame (not as accurate but quicker).
AM_SEEKING_ReturnTime | Return the media time equivalents for pCurrent and pStop (overwriting these values with the returned values).
AM_SEEKING_Segment | At the end of the segment call EC_ENDOFSEGMENT instead of EndOfStream.
AM_SEEKING_NoFlush | Do not flush.
pStop
[in,out] Position in the stream at which to quit.
dwStopFlags
[in] Stop position seeking options to be applied. These are the same as listed for dwCurrentFlags.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, NOERROR for success, E_INVALIDARG if a parameter is out of range, or another COM return code otherwise.

Remarks

The following code fragment checks for the type of seeking required.

switch ( dwFlags & AM_SEEKING_PositioningBitsMask )
{
    case AM_SEEKING_IncrementalPositioning:
        // Check this is on a stop time
        // Get Current, add this delta, apply result as new stop time
        break;
    case AM_SEEKING_RelativePositioning:
        // ...
        break;
    case AM_SEEKING_AbsolutePositioning:
        // ...
        break;
    case AM_SEEKING_NoPositioning:
        // Nothing to do.
        break;
}

IMediaSeeking::SetRate

IMediaSeeking Interface

Sets a new playback rate.

HRESULT SetRate(
double dRate
);

Parameters
dRate
[in] New rate, where 1 is the normal rate, 2 is twice as fast, and so on.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, E_INVALIDARG if the parameter is invalid, or E_NOTIMPL if the method is not implemented.

IMediaSeeking::SetTimeFormat

IMediaSeeking Interface

Sets the time format, which determines the format of units used during seeking.

HRESULT SetTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
[in] Time format to be supported by this interface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, E_FAIL for failure, or E_NOTIMPL if the method is not implemented.

Remarks

See the IsFormatSupported method for a list of time formats. Note that the filter graph must be stopped before calling this method or a VFW_E_WRONG_STATE error will be returned.


IMediaTypeInfo Interface

The filter graph manager exposes the IMediaTypeInfo interface to allow access by Automation client applications such as Microsoft® Visual Basic® to the media type information associated with pins on filters.

When to Implement

This interface is implemented by the filter graph manager for use by Automation client applications, such as Visual Basic.

When to Use

Automation-compatible applications retrieve an object supporting this interface by calling the IPinInfo::get_ConnectionMediaType method. This interface then presents the major and minor media types as properties on an IMediaTypeInfo object.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaTypeInfo methods | Description
get_Type | Retrieves the major type GUID as a string.
get_Subtype | Retrieves the subtype GUID as a string.

IMediaTypeInfo::get_Subtype

IMediaTypeInfo Interface

Retrieves the subtype GUID as a string.

HRESULT get_Subtype(
BSTR *strType
);

Parameters
strType
[out, retval] String containing the subtype GUID.
Return Values

Returns an HRESULT value.

IMediaTypeInfo::get_Type

IMediaTypeInfo Interface

Retrieves the major type GUID as a string.

HRESULT get_Type(
BSTR *strType
);

Parameters
strType
[out, retval] String containing the major type GUID.
Return Values

Returns an HRESULT value.


IMemAllocator Interface

The IMemAllocator interface allocates IMediaSample blocks to be used for data transfer between pins. The blocks can be provided by the input pin, output pin, or a third party. Release the IMediaSample object by calling the IUnknown::Release method.

When to Implement

Implement this interface if you are providing a buffer for media samples. This is typically done by filters that originate, copy, or provide a destination for the media stream. For example, a source filter provides an allocator corresponding to the incoming media, and a renderer filter provides an allocator corresponding to the hardware memory (DirectX®, for example). Intermediate transform filters can create their own allocator if copying samples and not writing directly to the renderer's allocator. Use the CBaseAllocator class to implement the IMemAllocator interface.

When to Use

Filters use this interface when retrieving or sending media samples. The allocator used might actually belong to a filter further upstream or downstream than the next filter, because many filters choose to pass the allocators through and simply modify the data in place.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMemAllocator methods | Description
SetProperties | Specifies a desired number of blocks, size of the blocks, and block alignment figure. This method returns the actual values for the same.
GetProperties | Determines the size, number, and alignment of blocks.
Commit | Commits the memory for the specified buffers.
Decommit | Releases the memory for the specified buffers.
GetBuffer | Retrieves a container for a sample.
ReleaseBuffer | Releases a container for a sample.

IMemAllocator::Commit

IMemAllocator Interface

Commits the memory for the specified buffers.

HRESULT Commit(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The IMemAllocator::SetProperties method must be called before calling this method. The IMemAllocator::GetBuffer method fails if it is called before this method.

IMemAllocator::Decommit

IMemAllocator Interface

Releases the memory for the specified buffers.

HRESULT Decommit(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Any threads waiting in the IMemAllocator::GetBuffer method return with an error after this method is called. The IMemAllocator::GetBuffer method fails if it is called before the IMemAllocator::Commit method or after this method.

IMemAllocator::GetBuffer

IMemAllocator Interface

Retrieves a container for a sample.

HRESULT GetBuffer(
IMediaSample ** ppBuffer,
REFERENCE_TIME * pStartTime,
REFERENCE_TIME * pEndTime,
DWORD dwFlags
);

Parameters
ppBuffer
[out] Pointer to a retrieved media sample buffer.
pStartTime
[in] Either NULL or set to the beginning time of the sample to retrieve. Only the video renderer uses this.
pEndTime
[in] Either NULL or set to the ending time of the sample to retrieve. Only the video renderer uses this.
dwFlags
[in] GetBuffer supports the following flags.
AM_GBF_NOTASYNCPOINT
Dynamic format changes are not allowed on this buffer because it is not a key frame.
AM_GBF_PREVFRAMESKIPPED
Set to TRUE if this sample is the first after a discontinuity. Only the video renderer uses this.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

IMemAllocator::GetBuffer is a locking, synchronous method to get the next free buffer. Upon return, the properties are invalid, but the buffer pointer and size are correct. This method succeeds only if memory has been committed. GetBuffer returns with an error value if it is blocked waiting for a buffer, and the IMemAllocator::Decommit method is called on another thread.

If the pStartTime and pEndTime parameters are not NULL, they specify the intended start and end time for the sample in stream time (reference clock time minus the stream time offset). The Video Renderer applies these parameters when using DirectDraw to schedule when to return a sample. If pStartTime and pEndTime are NULL the Video Renderer will not use DirectDraw.

IMemAllocator::GetProperties

IMemAllocator Interface

Returns the properties being used on this allocator.

HRESULT GetProperties(
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pProps
[out] Allocator properties.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Calls to this method need not succeed until the IMemAllocator::Commit method is called.

IMemAllocator::ReleaseBuffer

IMemAllocator Interface

Releases the CMediaSample object.

HRESULT ReleaseBuffer(
IMediaSample *pBuffer
);

Parameters
pBuffer
[in] Buffer to release.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IMemAllocator::SetProperties

IMemAllocator Interface

Specifies the size, number, and alignment of blocks.

HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);

Parameters
pRequest
[in] Requested allocator properties.
pActual
[out] Allocator properties actually set.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values that it can provide for the request. This method cannot be called unless the allocator has been decommitted using the IMemAllocator::Decommit method.

This method assumes that blocks are all the same size.


IMemInputPin Interface

The IMemInputPin interface provides methods on an input pin to facilitate passing data and flush notifications from a connected output pin of an upstream filter.

When to Implement

Implement this interface on the input pin of every filter. The CBaseInputPin class implements this interface.

When to Use

A connected output pin uses this interface to retrieve an IMemAllocator interface, to pass media samples to the input pin, and to flush pending buffers downstream.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMemInputPin methods | Description
GetAllocator | Returns the allocator interface that this input pin proposes as the interface for the output pin to use.
NotifyAllocator | Notifies the input pin as to which allocator the output pin is actually going to use.
GetAllocatorRequirements | Optional method to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.
Receive | Receives the next block of data from the stream.
ReceiveMultiple | Receives the next block of data from the stream. This method behaves similarly to the IMemInputPin::Receive method, but it works with multiple samples.
ReceiveCanBlock | Determines if sending the IMemInputPin::Receive method might block.

IMemInputPin::GetAllocator

IMemInputPin Interface

Returns the allocator interface that this input pin proposes as the interface for the output pin to use.

HRESULT GetAllocator(
IMemAllocator ** ppAllocator
);

Parameters
ppAllocator
[out] Pointer to an obtained IMemAllocator object.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IMemInputPin::GetAllocatorRequirements

IMemInputPin Interface

Optional method to suggest specific alignment or prefix requirements to an upstream filter.

HRESULT GetAllocatorRequirements(
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pProps
[in] ALLOCATOR_PROPERTIES structure containing the required size, count, and alignment of the allocator.
Return Values

Returns an HRESULT value. Returns E_NOTIMPL if not implemented.

Remarks

Source filters that insist on their own allocator may use this method downstream to accommodate downstream filters' memory requirements for performance benefits.

IMemInputPin::NotifyAllocator

IMemInputPin Interface

Notifies the input pin as to which allocator the output pin is actually going to use.

HRESULT NotifyAllocator(
IMemAllocator * pAllocator,
BOOL bReadOnly
);

Parameters
pAllocator
[in] Pointer to the IMemAllocator object to use. This might or might not be the same IMemAllocator object that the input pin provided in the IMemInputPin::GetAllocator method (the output pin could provide its own allocator).
bReadOnly
[out] Flag to indicate if the samples from this allocator are read-only.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is called by the connecting output pin to notify the pin on which this interface is implemented of the allocator it chooses to use for transporting media samples. If the bReadOnly parameter is TRUE, all samples in the allocator are read-only and a copy must be made before modifying any of them.

IMemInputPin::Receive

IMemInputPin Interface

Receives the next block of data from the stream.

HRESULT Receive(
IMediaSample * pSample
);

Parameters
pSample
[in] Pointer to a media sample.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This is a blocking synchronous call. Typically, no blocking occurs, but if a filter cannot process the sample immediately it may use the calling application's thread to wait until it can.

Use the IUnknown::AddRef method if you need to hold the returned data block beyond the completion of the IMemInputPin::Receive method. If you use AddRef, be sure to use IUnknown::Release when done with it.

IMemInputPin::ReceiveCanBlock

IMemInputPin Interface

Determines if the implementation of the IMemInputPin::Receive method might block on the connected output pin.

HRESULT ReceiveCanBlock(void);

Return Values

Can return any HRESULT value. The following specific success values can be returned.
Value | Meaning
S_FALSE | Input pin will not block on a Receive method.
S_OK | Input pin might block on a Receive method.

Remarks

An output pin from a filter might require notification if its thread might be blocked when it calls the Receive method on the connected input pin. For example, a source filter might prefer to keep reading and buffering data rather than to be blocked, and may choose to start another thread to wait on the blocking Receive method.

If your implementation of Receive calls a downstream filter's Receive method on the same thread, the application will block if that filter blocks, and this method must indicate that.

IMemInputPin::ReceiveMultiple

IMemInputPin Interface

Returns the next block of data from the stream. This method behaves much like the IMemInputPin::Receive method, but it works with multiple samples.

HRESULT ReceiveMultiple(
IMediaSample ** pSamples,
long nSamples,
long * nSamplesProcessed
);

Parameters
pSamples
[in] Pointer to an array of samples.
nSamples
[in] Number of samples to process.
nSamplesProcessed
[out] Number of samples processed.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method allows a connected output pin to deliver multiple samples at one time. Use it if, like COutputQueue, the output pin batches samples for delivery together. Implement this if your filter can handle batched samples more efficiently than individual samples. The base class implementation of this method simply calls IMemInputPin::Receive repeatedly. Override this implementation if you can do something more efficiently in your derived class.


IMixerPinConfig Interface

The IMixerPinConfig interface is exposed on the input pins of overlay mixer filters and contains methods that manipulate video streams in various ways. The overlay mixer filter contains multiple input pins that are dynamically created as video input streams are added. The video stream on the first pin is known as the primary stream and subsequent streams are known as secondary streams.

Use this interface to manipulate the parameters involved in mixing various video streams. These parameters include getting and setting position, z-order, blending and transparency levels, aspect ratio correction, and colorkeys of streams.

When to Implement

DirectShow implements this interface on the input pins of overlay mixer filters. Developers should implement this interface when they create filters that mix video streams.

When to Use

Applications use this interface to get and set attributes when mixing multiple video streams.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMixerPinConfig methods | Description
SetRelativePosition | Sets the position of the stream in the display window.
GetRelativePosition | Retrieves the position of the stream in the display window.
SetZOrder | Sets the z-order of a particular video stream.
GetZOrder | Retrieves the z-order of a particular video stream.
SetColorKey | Sets the colorkey being used by a video stream.
GetColorKey | Retrieves the colorkey being used by a video stream.
SetBlendingParameter | Sets the blending parameter that defines how a secondary stream is blended with a primary stream.
GetBlendingParameter | Retrieves the value of the blending parameter that defines how a secondary stream is blended with a primary stream.
SetAspectRatioMode | Sets the aspect ratio correction mode for window resizing.
GetAspectRatioMode | Retrieves the aspect ratio correction mode for window resizing.
SetStreamTransparent | Sets the stream to transparent.
SetStreamTransparent | Determines whether a stream is transparent.

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig Interface

Retrieves the aspect ratio correction mode for window resizing.

STDMETHOD GetAspectRatioMode(
AM_ASPECT_RATIO_MODE* pamAspectRatioMode
) PURE;

Parameters
pamAspectRatioMode
[out] Pointer to an AM_ASPECT_RATIO_MODE enumerated type member.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_NOTIMPL | Method called on secondary stream.
E_INVALIDARG | Value invalid or NULL.
NOERROR | No error.

See Also

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig Interface

Retrieves the value of the blending parameter that defines how a secondary stream is blended with a primary stream.

STDMETHOD GetBlendingParameter(
DWORD *pdwBlendingParameter
) PURE;

Parameters
pdwBlendingParameter
[out] Value between 0 and 255 that indicates the amount of blending between a primary stream and a secondary stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_UNEXPECTED | Method called on primary stream.
E_INVALIDARG | Value outside of possible range (0-255).
NOERROR | No error.

Remarks

A value of zero indicates that the secondary stream is invisible; a value of 255 indicates the primary stream is invisible in the area that the secondary stream occupies.

See Also

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig::GetColorKey

IMixerPinConfig Interface

Retrieves the colorkey being used by a video stream.

STDMETHOD GetColorKey(
COLORKEY *pColorKey,
DWORD *pColor ) PURE;

Parameters
pColorKey
[out] Pointer to a COLORKEY structure that contains the key type and a palette index.
pColor
[out] Value indicating the palette index of the COLORKEY structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_INVALIDARG | Invalid arguments, both parameters are NULL.
E_FAIL | GetColorKey failed because the colorkey isn't known.
NOERROR | No error.

Remarks

Getting the value on the primary stream will retrieve the destination colorkey being used by the overlay surface. Getting this value on the secondary pin returns the colorkey being used by that particular stream.

Current DirectShow implementation of this interface can return NULL for either the pColorKey or the pColor parameters; however, the method will fail and return E_INVALIDARG if both parameters are NULL.

Note The DWORD value returned by the pColor parameter is the actual color being used. So, if the bit depth of the display is 8, 16, 24, 32 the last 8, 16, 24 or 32 bits of the DWORD specify the actual value of the colorkey.

See Also

IMixerPinConfig::SetColorKey

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig Interface

Determines whether a stream is transparent.

STDMETHOD GetStreamTransparent(
BOOL *pbStreamTransparent
) PURE;

Parameters
pbStreamTransparent
[out] TRUE indicates transparent stream; FALSE indicates not a transparent stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

See Also

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig::GetRelativePosition

IMixerPinConfig Interface

Retrieves the position of the stream in the display window.

STDMETHOD GetRelativePosition(
DWORD *pdwLeft,
DWORD *pdwTop,
DWORD *pdwRight,
DWORD *pdwBottom ) PURE;

Parameters
pdwLeft
[out] Indicates the x-coordinate in the top-left corner of the display window.
pdwTop
[out] Indicates the y-coordinate in the top-left corner of the display window.
pdwRight
[out] Indicates the x-coordinate in the bottom-right corner of the display window.
pdwBottom
[out] Indicates the y-coordinate in the bottom-right corner of the display window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_INVALIDARG | Coordinates not in the {0, 0, 10,000, 10,000} range.
NOERROR | No error.

Remarks

This method assumes window coordinates of {0, 0, 10,000, 10,000}. If the video stream is being rendered in the bottom right quarter of the display window, this method would return {5,000, 5,000, 10,000, 10,000}.

See Also

IMixerPinConfig::SetRelativePosition

IMixerPinConfig::GetZOrder

IMixerPinConfig Interface

Retrieves the z-order of a particular video stream.

STDMETHOD GetZOrder(
DWORD *pdwZOrder ) PURE;

Parameters
pdwZOrder
[out] Value indicating the order in which streams will clip each other.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. This method is not currently implemented and returns E_NOTIMPL.

Remarks

Images with larger z-values are always in front of images with smaller z-values.

See Also

IMixerPinConfig::SetZOrder

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig Interface

Sets the aspect ratio correction mode for window resizing.

STDMETHOD SetAspectRatioMode(
AM_ASPECT_RATIO_MODE amAspectRatioMode
) PURE;

Parameters
amAspectRatioMode
[in] Specify one of the AM_ASPECT_RATIO_MODE enumerated type members.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_NOTIMPL | Method called on secondary stream.
E_INVALIDARG | Invalid argument.
NOERROR | No error.

Remarks

Currently this function is implemented only on the primary pin of the Overlay Mixer filter. Calling it on a secondary pin will result in an error.

See Also

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig Interface

Sets the blending parameter that defines how a secondary stream is blended with a primary stream.

STDMETHOD SetBlendingParameter(
DWORD dwBlendingParameter
) PURE;

Parameters
dwBlendingParameter
[in] Value between 0 and 255 that indicates the amount of blending between a primary stream and a secondary stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_UNEXPECTED | Method called on primary stream.
E_INVALIDARG | Value outside of possible range (0 to 255).
NOERROR | No error.

Remarks

The value of the dwBlendingParameter parameter must be between 0 and 255, where 0 makes the secondary stream invisible and 255 makes the primary stream invisible in the area that the secondary stream occupies. If no value is set the default is 255.

This method is not intended to be called on the primary stream.

Note Current DirectShow implementation of this interface allows only values of 0 or 255 for the dwBlendingParameter parameter. Any other values are invalid.

See Also

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig::SetColorKey

IMixerPinConfig Interface

Sets the colorkey being used by a video stream.

STDMETHOD SetColorKey(
COLORKEY *pColorKey ) PURE;

Parameters
pColorKey
[in] Pointer to a COLORKEY structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. This method is not currently implemented and returns E_NOTIMPL.

Remarks

The term colorkey has different meanings depending on which stream it is referring to. The colorkey of the primary stream refers to the destination colorkey being used by the overlay surface. The colorkey of the secondary stream refers to the source colorkey used, when blitting from an offscreen surface to the primary surface.

Applications should set the colorkey of the primary pin to an obscure color (some color which, in all probability, will not be present on the desktop). Overlay mixer filters will try to pick an obscure color, but if the application knows that the specified color is part of some other content, then the application should change it.

Setting the colorkey on the secondary stream can be used to make the stream transparent and enable nonrectangular images. For example, if the secondary stream is closed-captioned text, then the closed-captioned text decoder should paint a solid color in the background and then set the colorkey on the corresponding pin to that color. This ensures that all pixels are transferred except those specified by the colorkey. If possible, applications should set the colorkey of the secondary stream to the same as that of the primary stream to give a slight performance advantage.

Setting this value on the primary stream sets the destination colorkey being used by the overlay surface. By default, the destination colorkey is used as the colorkey for all transparent (secondary) streams.

See Also

IMixerPinConfig::GetColorKey

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig Interface

Sets the stream to transparent.

STDMETHOD SetStreamTransparent(
BOOL bStreamTransparent
) PURE;

Parameters
bStreamTransparent
[in] Pass in TRUE to indicate stream is transparent; FALSE to indicate not a transparent stream.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

See Also

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig::SetRelativePosition

IMixerPinConfig Interface

Sets the position of the stream in the display window.

STDMETHOD SetRelativePosition(
DWORD dwLeft,
DWORD dwTop,
DWORD dwRight,
DWORD dwBottom ) PURE;

Parameters
dwLeft
[in] Specifies the x-coordinate in the upper-left corner of the display window.
dwTop
[in] Specifies the y-coordinate in the upper-left corner of the display window.
dwRight
[in] Specifies the x-coordinate in the bottom-right corner of the display window.
dwBottom
[in] Specifies the y-coordinate in the bottom-right corner of the display window.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_INVALIDARG | Coordinates not in the {0, 0, 10,000, 10,000} range.
NOERROR | No error.

Remarks

This method assumes window coordinates of {0, 0, 10,000, 10,000}. Therefore, if you want your video stream to be rendered in the bottom right quarter of the display window, you would call this method with the parameters {5,000, 5,000, 10,000, 10,000}.

Note Values greater than 10,000 are invalid and will cause an error.

See Also

IMixerPinConfig::GetRelativePosition

IMixerPinConfig::SetZOrder

IMixerPinConfig Interface

Sets the z-order of a particular video stream.

STDMETHOD SetZOrder(
DWORD dwZOrder ) PURE;

Parameters
dwZOrder
[in] Value indicating the order in which streams will clip each other.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. This method is not currently implemented and returns E_NOTIMPL.

Remarks

The z-order indicates which streams can clip other streams. Images with larger z-values are always in front of images with smaller z-values.

The relative order of multiple streams is significant only if the video images overlap.

Specifying the same z-order for two overlapping streams can cause strange video artifacts.

See Also

IMixerPinConfig::GetZOrder

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IMixerPinConfig2 Interface

The IMixerPinConfig2 interface is exposed on the input pins of overlay mixer filters and contains methods that manipulate video color controls, if the VGA chip supports it.

This interface derives from the IMixerPinConfig interface.

Use this interface to manipulate the video color controls involved in mixing various video streams.

When to Implement

DirectShow implements this interface on the input pins of overlay mixer filters. Developers should implement this interface when they create filters that need to control video colors.

When to Use

Applications use this interface to get and set video color controls when mixing multiple video streams.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMixerPinConfig2 methods | Description
SetOverlaySurfaceColorControls | Sets the color control settings associated with the specified overlay surface.
GetOverlaySurfaceColorControls | Retrieves the color control settings currently associated with the specified overlay surface.

IMixerPinConfig2::GetOverlaySurfaceColorControls

IMixerPinConfig2 Interface

Retrieves the color control settings associated with the specified overlay surface.

HRESULT GetOverlaySurfaceColorControls(
LPDDCOLORCONTROL pColorControl
) PURE;

Parameters
pColorControl
[out] Address of the DDCOLORCONTROL structure containing the color values currently applied to the specified surface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. If the allocator on the pin is not using an overlay surface, E_FAIL is returned.

IMixerPinConfig2::SetOverlaySurfaceColorControls

IMixerPinConfig2 Interface

Sets the color control settings associated with the specified overlay surface.

HRESULT SetOverlaySurfaceColorControls(
LPDDCOLORCONTROL pColorControl
) PURE;

Parameters
pColorControl
[in] Address of the DDCOLORCONTROL structure containing the new values to be applied to the specified surface.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. If the allocator on the pin is not using an overlay surface, E_FAIL is returned.


IOverlay Interface

The IOverlay interface provides information so that a filter can write directly to video memory while placing the video in the correct window position. It is implemented on the input pin of the video renderer and communicates with an upstream filter (typically a video decompressor) by calling that filter's IOverlayNotify methods to notify it of changes to the video window.

This interface has no relationship to the DirectDraw® overlay capability. The Microsoft video renderer draws data it receives through the IMemInputPin interface, using DirectDraw overlays when available. This interface, used in place of IMemInputPin, is intended to provide notification support for any upstream filter that bypasses the renderer's drawing capabilities, but needs notifications of other display properties.

See the IOverlayNotify interface for more information on how the IOverlay and IOverlayNotify interfaces work together.

When to Implement

This interface is implemented on the Microsoft® DirectShow™ video renderer filter. It can also be implemented on replacement video renderer filters if desired. If doing so, implement this interface so that filters writing directly to the frame buffer or trying to position an overlay know where to display their video. To implement this interface, the renderer must be prepared to use methods on the IOverlayNotify interface of the filter doing the drawing, with notifications of video property changes.

The window-based renderer in DirectShow supports both IMemInputPin and IOverlay interfaces. These two interfaces are mutually exclusive. A filter chooses to use the IOverlay transport interface by providing a media type during connection that has a subtype of MEDIASUBTYPE_Overlay. After connection, it will be able to get and use successfully the IOverlay interface. If it connects with any other video formats (such as MEDIASUBTYPE_RGB8), trying to call through IOverlay returns VFW_E_NOT_OVERLAY_CONNECTION.

When to Use

Use the methods on this function from an upstream filter that must control video overlay properties and intends to handle the displaying of the video data itself. This typically is used by hardware video decoders that have an alternate connection to the video hardware.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IOverlay methods | Description
GetPalette | Retrieves the current palette.
SetPalette | Sets the palette.
GetDefaultColorKey | Retrieves the default color key.
GetColorKey | Returns the identifier of the currently active color key.
SetColorKey | Changes the color key.
GetWindowHandle | Returns the window handle.
GetClipList | Retrieves the clipping list.
GetVideoPosition | Retrieves the current video source and destination rectangles.
Advise | Sets up an advise link for the overlay events.
Unadvise | Terminates the advise link.

IOverlay::Advise

IOverlay Interface

Sets up an advise link for the overlay events specified by the dwInterests parameter.

HRESULT Advise(
IOverlayNotify * pOverlayNotify,
DWORD dwInterests
);

Parameters
pOverlayNotify
[in] Notification interface.
dwInterests
[in] Callbacks of interest, which can be any subset of the following events.
Event | Meaning
ADVISE_NONE | No changes.
ADVISE_CLIPPING | Change in clipping region (synchronized with the window).
ADVISE_PALETTE | Change in palette.
ADVISE_COLORKEY | Change of chroma key value.
ADVISE_POSITION | Change in position of video window (not synchronized with the window).
ADVISE_ALL | All of the above.
Return Values

No return value.

Remarks

This method sets up an advise link for the IOverlayNotify interface to receive notifications. If one of these events occurs, the appropriate entry point in the pOverlayNotify parameter passed in is called (IOverlayNotify::OnClipChange, IOverlayNotify::OnColorKeyChange, IOverlayNotify::OnPaletteChange, or IOverlayNotify::OnPositionChange).

Only one advise link can be set on any given IOverlay interface. Trying to set another notification interface on second and subsequent calls returns VFW_E_ADVISE_ALREADY_SET. You can cancel an advise link by using IOverlay::Unadvise.

IOverlay::GetClipList

IOverlay Interface

Retrieves the clipping list.

HRESULT GetClipList(
RECT * pSourceRect,
RECT * pDestinationRect,
RGNDATA ** ppRgnData
);

Parameters
pSourceRect
[out] Bounding client rectangle.
pDestinationRect
[in] Destination rectangle.
ppRgnData
[out] Header and data describing clipping. If successful, the Microsoft® Win32® CoTaskMemFree function should free memory.
Return Values

No return value.

Remarks

The IOverlay implementation allocates the memory for the clipping rectangles, because it can vary in length. The filter calling this method should free the memory (using CoTaskMemFree) when it is finished with it.

IOverlay::GetColorKey

IOverlay Interface

Retrieves the current color key used for chroma keying.

HRESULT GetColorKey(
COLORKEY * pColorKey
);

Parameters
pColorKey
[out] Pointer to where the current color key for chroma keying is copied.
Return Values

No return value.

Remarks

If you change the color key by using the IOverlay::SetColorKey method, all the advise links receive an IOverlayNotify::OnColorKeyChange callback method with the new color.

If no color key is currently being used, this method returns VFW_E_NO_COLOR_KEY_SET.

IOverlay::GetDefaultColorKey

IOverlay Interface

Retrieves the default color key used for a chroma key overlay.

HRESULT GetDefaultColorKey(
COLORKEY * pColorKey
);

Parameters
pColorKey
[out] Pointer to where the default color key is copied.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

A filter using color keys can get a default color from the video renderer. The default color key can then be installed into the window using IOverlay::SetColorKey. The colors returned through this method vary depending on the current display mode. If the colors are 8-bit palettized, they will be bright system colors (such as magenta). If the display is in a true-color mode, they will be shades of black.

The IOverlay interface ensures that separate instances of the renderer on the same computer get different color keys so that overlays do not conflict.

IOverlay::GetPalette

IOverlay Interface

Retrieves the current system palette.

HRESULT GetPalette(
DWORD * pdwColors,
PALETTEENTRY ** ppPalette
);

Parameters
pdwColors
[out] Number of colors present.
ppPalette
[out] Retrieved palette structure.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IOverlay::GetVideoPosition

IOverlay Interface

Retrieves the current video source and destination rectangles.

HRESULT GetVideoPosition(
[out] RECT *pSourceRect,
[out] RECT *pDestinationRect
);

Parameters
pSourceRect
[out] Bounding video client rectangle.
pDestinationRect
[in] Destination video rectangle.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IOverlay::GetWindowHandle

IOverlay Interface

Retrieves the current window handle.

HRESULT GetWindowHandle(
HWND *pHwnd
);

Parameters
pHwnd
[out] Window handle.
Return Values

Returns a pointer to the window handle.

IOverlay::SetColorKey

IOverlay Interface

Changes the color key.

HRESULT SetColorKey(
COLORKEY * pColorKey
);

Parameters
pColorKey
[out] Pointer to the color key value to be set. If successful, the actual color key value selected is copied to this parameter.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

If you change the color key by using the IOverlay::SetColorKey method, all the advise links will receive an IOverlayNotify::OnColorKeyChange callback method with the new color.

When using IOverlay on a palettized display, a filter can either install a color key (using IOverlay::SetColorKey) or install a palette (using IOverlay::SetPalette), but not both. This is because color keys in this mode require a palette to be realized that would conflict with SetPalette. Color keys can be uninstalled by requesting a color key with the CK_NOCOLORKEY flag. Likewise, any palette installed through SetPalette can be uninstalled by calling SetPalette and passing in null parameters (that is, SetPalette(0,NULL)).

Trying to set a palette when a color key is installed returns a VFW_E_PALETTE_SET error. Trying to set a color key when a palette is installed returns VFW_E_COLOR_KEY_SET.

IOverlay::SetPalette

IOverlay Interface

Sets the palette.

HRESULT SetPalette(
DWORD dwColors,
PALETTEENTRY * pPalette
);

Parameters
dwColors
[in] Number of colors present.
pPalette
[in] Colors to use for the palette.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method sets a logical palette for the window. The window is not guaranteed to always have the colors requested in the actual system device palette. The Microsoft® Windows® operating system only guarantees those colors when the window is the foreground active window. The current device palette can be obtained by calling IOverlay::GetPalette.

If the device does not have a palette, it returns VFW_E_NO_DISPLAY_PALETTE.

IOverlay::Unadvise

IOverlay Interface

Terminates the advise link established with the IOverlayNotify interface.

HRESULT Unadvise( );

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method terminates the advise link established by using the IOverlay::Advise method. Only one advise link can be maintained at any one time.


IOverlayNotify Interface

The IOverlayNotify interface provides an upstream filter, such as a decoder, with notifications of changes to the rendering window. This includes notifications of changes to the palette, color key, and window position, and visible region (clipping) changes.

Most software video decoders let the video renderer draw the decompressed images they produce by passing the media samples to the IMemInputPin interface on the renderer's input pin.

However, some video decoding filters (typically hardware decompression boards) handle the drawing of the images themselves, perhaps by using a VGA connector. These filters do not need to use IMemInputPin, but can instead use the IOverlay interface provided by the renderer input pin. Through this interface, the decoder can be notified when the window position or size changes, or when the current system palette changes in order to install and change color keys and palettes.

When to Implement

To get notifications of when the window size or position changes, when the current system palette changes, or when a different color key is used, decoders that do their own drawing should implement an IOverlayNotify interface. A pointer to this interface can then be passed to the IOverlay interface on the renderer's input pin, through the IOverlay::Advise method, to set up an advise link (essentially a callback mechanism). After the advise link is established, the renderer calls the decoder's IOverlayNotify methods when the appropriate events occur. An advise link can be canceled by calling IOverlay::Unadvise.

When to Use

The video renderer is the only filter that calls the methods on this interface. This is done automatically by the default video renderer. If you are writing a replacement video renderer, you will need to use the methods on this interface if your filter supports IOverlay and this interface is passed to your filter in an IOverlay::Advise call.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IOverlayNotify methods | Description
OnPaletteChange | Provides notification that the palette of the window has changed.
OnClipChange | Provides notification that the visible region of the window has changed.
OnColorKeyChange | Provides notification that the chroma key has changed.
OnPositionChange | Provides notification that the position has changed.

IOverlayNotify::OnClipChange

IOverlayNotify Interface

Provides notification that the window's visible region has changed. It is essential that any overlay hardware be updated to reflect the change to the visible region before returning from this method.

HRESULT OnClipChange(
RECT *pSourceRect,
RECT *pDestinationRect,
RGNDATA *pRgnData
);

Parameters
pSourceRect
[in] Region of the video to use.
pDestinationRect
[in] Video destination.
pRgnData
[in] Clipping information.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The calls to OnClipChange happen in synchronization with the window. It is called with an empty clip list to freeze the video before the window moves, and then called again when the window has stabilized with the new clip list.

If the window rectangle is all zeros, the window is invisible. The filter must take a copy of the information if it needs to store it.

IOverlayNotify::OnColorKeyChange

IOverlayNotify Interface

Provides notification that the window's color key has changed.

HRESULT OnColorKeyChange(
COLORKEY * pColorKey
);

Parameters
pColorKey
[in] Defines the new chroma key.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IOverlayNotify::OnPaletteChange

IOverlayNotify Interface

Provides notification that the palette of the window has changed.

HRESULT OnPaletteChange(
DWORD dwColors,
const PALETTEENTRY * pPalette
);

Parameters
dwColors
[in] Number of colors present.
pPalette
[in] Array of palette colors.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Before returning, the filter should copy the array of RGBQUAD values, if necessary.

IOverlayNotify::OnPositionChange

IOverlayNotify Interface

Provides notification that the position has changed.

HRESULT OnPositionChange(
const RECT *pSourceRect,
const RECT *pDestinationRect
);

Parameters
pSourceRect
[in] Source video rectangle.
pDestinationRect
[in] Destination video rectangle. Note that this is not clipped to the visible display area.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is a callback intended for use by hardware overlay cards that do not want the expense of synchronous clipping updates, and just want to know when the source or destination video positions change.

Unlike the IOverlayNotify::OnClipChange method, this method is not called in synchronization with the window changing but, rather, at some point after the window has changed (basically in time with WM_SIZE messages received). This is therefore suitable for overlay cards that do not inlay their data to the frame buffer.


IPin Interface

The IPin interface represents a single, unidirectional connection point on a filter. A pin connects to exactly one other pin on another filter. Other objects can use this interface on this pin. The interface between the filter and the pin is private to the implementation of a specific filter.

During the connection process, one pin takes the lead. The base classes assume that this is the output pin of the upstream connecting filter. The filter graph manager calls the IPin::Connect method on this pin's IPin interface, passing the IPin pointer for the connecting pin. This connecting pin then calls the IPin::ReceiveConnection method located on the other pin, in addition to its format-enumeration, IUnknown::QueryInterface, and possibly IPin::QueryAccept methods, to establish whether the connection is possible.

When to Implement

All filters must implement this interface on each of its pins. Which methods are implemented depends on whether the pin is an input pin or an output pin. Use the CBasePin, CBaseInputPin, or CBaseOutputPin class, or classes derived from these classes, to implement this interface.

When to Use

This interface is used by other connecting pins and by the filter graph manager. Applications should not use this interface directly but should go through the filter graph manager. Connecting pins use the IPin interface on the opposite pin to negotiate a common media type and an agreed allocator to use for passing samples.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IPin methods | Description
Connect | Makes a connection to another pin.
ReceiveConnection | Makes a connection to this pin and is called by a connecting pin.
Disconnect | Breaks a connection.
ConnectedTo | Returns a pointer to the connecting pin.
ConnectionMediaType | Returns the media type of this pin's connection.
QueryPinInfo | Retrieves information about this pin (for example, the name, owning filter, and direction).
QueryId | Retrieves an identifier for the pin.
QueryAccept | Queries whether a given media type is acceptable by the pin.
EnumMediaTypes | Provides an enumerator for this pin's preferred media types.
QueryInternalConnections | Provides an array of the pins to which this pin internally connects.
EndOfStream | Informs the pin that no additional data is expected until a new run command is issued.
BeginFlush | Informs the pin to begin a flush operation.
EndFlush | Informs the pin to end a flush operation.
NewSegment | Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryDirection | Retrieves the direction for this pin.

IPin::BeginFlush

IPin Interface

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

When this method is called, the pin is entering flush state. In this case, carry out the following steps.

  1. Set a flushing flag to prevent any more IMemInputPin::Receive methods from succeeding.
  2. Discard any queued data.
  3. Free the pin if it was blocked by the Receive method, if possible.
  4. Pass the IPin::BeginFlush method to any downstream pins.

The BeginFlush notification is passed downstream until it reaches the renderer, which must free any sample it holds. This unblocks other pins (usually in the IMemAllocator::GetBuffer or IMemInputPin::Receive methods).

After BeginFlush is called, all samples passed by the Receive method to the pin, or on another transport, are rejected with S_FALSE until the IPin::EndFlush method is called.

This method is implemented in the base classes by CBaseInputPin::BeginFlush.

IPin::Connect

IPin Interface

Initiates a connection from this pin to the other pin.

HRESULT Connect(
IPin * pReceivePin,
const AM_MEDIA_TYPE * pmt
);

Parameters
pReceivePin
[in] Other pin to connect to.
pmt
[in] Type to use for the connections (optional).
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method calls the IPin::ReceiveConnection method for the other pin. The IPin::Connect method verifies that the connection is possible and might reject it. This pin proposes a media type to the other pin.

This method is implemented in the base classes by CBasePin::Connect.

Applications should not use this method. Instead, use IFilterGraph::ConnectDirect, which will use this method. Changing connections underneath the filter graph manager can cause commands to be distributed incorrectly and can cause a deadlock.

IPin::ConnectedTo

IPin Interface

If this pin is connected to another pin, the IPin::ConnectedTo method returns a pointer to that pin.

HRESULT ConnectedTo(
IPin ** ppPin
);

Parameters
ppPin
[out] Pointer to an IPin pointer to the IPin interface of the other pin (if any) to which this pin is connected. If there is no connection, the other pin interface pointer will be NULL.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is implemented in the base classes by CBasePin::ConnectedTo. The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.

IPin::ConnectionMediaType

IPin Interface

Determines the media type associated with the current connection of the pin. This method fails if the pin is unconnected.

HRESULT ConnectionMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
[out] Pointer to an AM_MEDIA_TYPE structure. If the pin is connected, the media type is returned. Otherwise, the structure is initialized to a default state in which all elements are 0, with the exception of lSampleSize, which is set to 1, and bFixedSizeSamples, which is set to TRUE.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The returned structure can contain an allocated format block and a reference-counted IUnknown interface pointer. These resources should be released by calling the FreeMediaType utility function.

This method is implemented in the base classes by CBasePin::ConnectionMediaType.

IPin::Disconnect

IPin Interface

Breaks a connection.

HRESULT Disconnect(void);

Return Values

Returns NOERROR if there is no connection.

Remarks

There are no parameters because there is only one possible connection on this pin.

This method is implemented in the base classes by CBasePin::Disconnect.

A pin should never use this method to disconnect from its peer. An application should not use this method. Use IFilterGraph::Disconnect instead.

IPin::EndFlush

IPin Interface

Informs the pin to end a flush operation.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

When this method is called, the pin is beginning to end a flush operation. It should perform the following steps.

  1. Ensure that your filter will not push any additional data. (To do this, synchronize with a thread, stop it pushing, and discard any queued data.)
  2. Reenable the IMemInputPin::Receive method by clearing the internal flushing flag.
  3. Pass the EndFlush method downstream by calling the method on the connecting input pin.

This method is implemented in the base classes by CBaseInputPin::EndFlush.

IPin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns one of the following HRESULT values.
Value | Meaning
S_OK | No error occurred.
E_UNEXPECTED | Method was probably called on an output pin that does not support this.

Remarks

Calling this method notifies the pin that no additional data is expected until a new run command is issued. The end-of-stream notification should be queued and delivered after all queued data is delivered. It can be delivered immediately if there is no queued data.

The IPin::BeginFlush method flushes any queued end-of-stream notifications. This is intended for input pins only.

This method is implemented in the base classes by CBaseOutputPin::EndOfStream.

IPin::EnumMediaTypes

IPin Interface

Provides an enumerator for this pin's preferred media types.

HRESULT EnumMediaTypes(
IEnumMediaTypes ** ppEnum
);

Parameters
ppEnum
[out] Pointer to an enumerator for the media types.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

If an enumerator is received, it must be released when the operation is finished.

This method is implemented in the base classes by CBasePin::EnumMediaTypes.

IPin::NewSegment

IPin Interface

Specifies that samples following this method are grouped as a segment with a given start time, stop time, and rate.

HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
[in] Start time of the segment.
tStop
[in] Stop time of the segment.
dRate
[in] Rate of the segment.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method allows filters that process buffers containing more than one sample to delineate the rendering of the samples between start and stop time, as indicated by the tStart and tStop parameters.

This method is intended to be implemented on an input pin. A connected output pin on the upstream filter calls this method after completing delivery of previous data and before calling IMemInputPin::Receive with any new data. It indicates that all data arriving after this call is part of a segment delineated by the parameters.

IPin::QueryAccept

IPin Interface

Determines if the pin could accept the format type.

HRESULT QueryAccept(
const AM_MEDIA_TYPE * pmt
);

Parameters
pmt
[in] Pointer to a proposed media type.
Return Values

Returns S_OK if the format is acceptable; otherwise, returns S_FALSE.

Remarks

This method is implemented in the base classes by CBasePin::QueryAccept.

IPin::QueryDirection

IPin Interface

Retrieves the direction for this pin.

HRESULT QueryDirection(
PIN_DIRECTION * pPinDir
);

Parameters
pPinDir
[out] Pointer to a PIN_DIRECTION variable.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The returned pPinDir parameter will contain PINDIR_INPUT if the pin is an input pin or PINDIR_OUTPUT otherwise. The same information is available by using IPin::QueryPinInfo, but this method is more direct and more efficient.

IPin::QueryId

IPin Interface

Retrieves an identifier for the pin.

HRESULT QueryId(
LPWSTR * Id
);

Parameters
Id
[out] Pin identifier.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method and the IBaseFilter::FindPin method allow connections in a filter graph to be saved and restored. Because pins are identified only by their IPin interface pointers at run time, and pointer information cannot be reliably saved, an identifier is necessary to specify which pins belong to each filter. The implementation of this method by the pin provides a unique name that the filter graph manager can use to turn into an IPin interface pointer, by calling IBaseFilter::FindPin when the filter graph is restored.

The storage is allocated by the filter using the Microsoft® Win32® CoTaskMemAlloc function. The caller should free it by using CoTaskMemFree.

This method is implemented in the base classes by CBasePin::QueryId.

IPin::QueryInternalConnections

IPin Interface

Provides an array of pointers to the IPin interface of the pins to which this pin internally connects.

HRESULT QueryInternalConnections(
IPin ** apPin,
ULONG * nPin
);

Parameters
apPin
[out] Array of IPin pointers.
nPin
[out] Upon input, indicates the number of array elements; upon output, indicates the number of pins.
Return Values

Returns one of the following HRESULT values.
Value | Meaning
E_FAIL | Undetermined.
S_FALSE | Insufficient number of array elements to return all the results, in which case no pins are returned in the apPin array.
E_NOTIMPL | Filter graph manager interprets E_NOTIMPL as meaning that any input pin connects to all visible output pins, and vice versa.

Remarks

All pins put in the array are added by the IUnknown::AddRef method. The apPin parameter can be NULL if the nPin parameter equals zero. This allows the calling application to determine the number of required arrays.

This method is implemented in the base classes by CBasePin::QueryInternalConnections.

IPin::QueryPinInfo

IPin Interface

Retrieves information about the pin.

HRESULT QueryPinInfo(
PIN_INFO * pInfo
);

Parameters
pInfo
[out] Pointer to a PIN_INFO structure that specifies the name of the pin, a pointer to an IBaseFilter interface on its owning filter, and the direction of the pin.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Unlike the pin name in the IPin::QueryId method, which is used by the filter graph manager, the name in the PIN_INFO structure is intended to be read by users.

Note that on return, the pFilter member of PIN_INFO has an outstanding reference count if it is non-NULL, and therefore should be released when the interface is no longer needed.

IPin::ReceiveConnection

IPin Interface

Makes a connection to the calling pin.

HRESULT ReceiveConnection(
IPin * pConnector,
AM_MEDIA_TYPE *pmt
);

Parameters
pConnector
[in] Connecting pin.
pmt
[in] Media type of the samples to be streamed.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method is intended for input pins only. Output pins should implement this to return an error. The pin should verify that it accepts the media type passed to it and return S_OK if so.

This method is implemented in the base classes by CBasePin::ReceiveConnection.


IPinInfo Interface

The filter graph manager exposes the IPinInfo interface, which allows access to pin information such as the media type and the pin direction. It also allows control of pins; for example, connecting and disconnecting pins and rendering a filter graph for a pin's media type.

When to Implement

This interface is implemented by the filter graph manager for use by Automation client applications, such as Microsoft® Visual Basic®.

When to Use

Applications that do not have access to the IFilterGraph or IGraphBuilder interface use this interface to retrieve pin information, to connect and disconnect pins, and to have the filter graph manager automatically generate filter graphs given the output pin of a source filter.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IPinInfo methods | Description
get_Pin | Retrieves the pin object that supports the IPin interface.
get_ConnectedTo | Retrieves the IPinInfo object for the corresponding pin to which this pin is connected.
get_ConnectionMediaType | Retrieves the media type on this connection.
get_FilterInfo | Retrieves the IFilterInfo object for the filter to which this pin belongs.
get_Name | Retrieves the name of this pin.
get_Direction | Retrieves the pin direction.
get_PinID | Retrieves the pin identifier.
get_MediaTypes | Retrieves an IAMCollection interface providing access to the preferred media types supported by this pin.
Connect | Connects to the specified pin.
ConnectDirect | Connects directly to the specified pin.
ConnectWithType | Connects directly to the specified pin using only the specified media type.
Disconnect | Disconnects this pin from its connected pin.
Render | Creates a filter graph capable of rendering the pin's media type.

IPinInfo::Connect

IPinInfo Interface

Connects to the specified pin using other transform filters as necessary.

HRESULT Connect(
IUnknown *pPin
);

Parameters
pPin
[in] Pin to connect with.
Return Values

Returns an HRESULT value.

Remarks

The pPin parameter can be either an IPin or an IPinInfo object. This method uses the graph builder to determine the required transform filters to enable the connection of this pin with the specified pin. For example, if the pin is an output pin of a source filter, and the requested connection is the input pin of a video renderer, this method will insert a decompressor filter of the appropriate media type to make this a valid filter graph. This method is essentially an Automation wrapper for the IGraphBuilder::Connect method.

IPinInfo::ConnectDirect

IPinInfo Interface

Connects directly to the given pin, not using any intermediate filters.

HRESULT ConnectDirect(
IUnknown *pPin
);

Parameters
pPin
[in] Pin to connect directly to.
Return Values

Returns an HRESULT value.

Remarks

This method will return an error if a common media type for the connecting pins cannot be agreed on. This method is essentially an Automation wrapper for the IFilterGraph::ConnectDirect method.

IPinInfo::ConnectWithType

IPinInfo Interface

Connects directly to the specified pin by using the specified media type.

HRESULT ConnectWithType(
IUnknown *pPin,
IDispatch *pMediaType
);

Parameters
pPin
[in] Pin to connect to. pPin is an object that must support either the IPin or the IPinInfo interface.
pMediaType
[in] Media type the pin is connecting with. pMediaType must support the IMediaTypeInfo interface.
Return Values

Returns an HRESULT value.

Remarks

This method allows you to determine which media type you want the connection to be made with, rather than letting the pins decide the media type upon connection.

IPinInfo::Disconnect

IPinInfo Interface

Disconnects this pin from its connected pin.

HRESULT Disconnect(void);

Return Values

Returns an HRESULT value.

Remarks

This method calls IPin::Disconnect on both pins.

IPinInfo::get_ConnectedTo

IPinInfo Interface

Retrieves the IPinInfo interface for the connected pin.

HRESULT get_ConnectedTo(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] IPinInfo interface for the pin.
Return Values

Returns an HRESULT value.

Remarks

This method is essentially an Automation wrapper for the IPin::ConnectedTo method.

IPinInfo::get_ConnectionMediaType

IPinInfo Interface

Retrieves the IMediaTypeInfo object containing the connection information.

HRESULT get_ConnectionMediaType(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] Returned IMediaTypeInfo interface.
Return Values

Returns an HRESULT value.

Remarks

This method is essentially an Automation wrapper for the IPin::ConnectionMediaType method.

IPinInfo::get_Direction

IPinInfo Interface

Retrieves the pin direction.

HRESULT get_Direction(
LONG *ppDirection
);

Parameters
ppDirection
[out, retval] Pin direction; either PINDIR_INPUT or PINDIR_OUTPUT.
Return Values

Returns an HRESULT value.

IPinInfo::get_FilterInfo

IPinInfo Interface

Retrieves the IFilterInfo interface for the filter to which this pin belongs.

HRESULT get_FilterInfo(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] Retrieved IFilterInfo interface.
Return Values

Returns an HRESULT value.

IPinInfo::get_MediaTypes

IPinInfo Interface

Retrieves an IAMCollection interface providing access to the preferred media types supported by this pin.

HRESULT get_MediaTypes(
IDispatch **ppUnk
);

Parameters
ppUnk
[out, retval] IAMCollection interface containing the preferred media types as IMediaTypeInfo objects.
Return Values

Returns an HRESULT value.

Remarks

This method is essentially an Automation wrapper for the IPin::EnumMediaTypes method.

IPinInfo::get_Name

IPinInfo Interface

Retrieves the name of this pin.

HRESULT get_Name(
BSTR **ppUnk
);

Parameters
ppUnk
[out, retval] Name of the pin.
Return Values

Returns an HRESULT value.

IPinInfo::get_Pin

IPinInfo Interface

Retrieves the pin object that supports the IPin interface.

HRESULT get_Pin(
IUnknown **ppUnk
);

Parameters
ppUnk
[out, retval] IUnknown object that supports IPin.
Return Values

Returns an HRESULT value.

Remarks

The IPinInfo interface is implemented by a wrapper COM object, so QueryInterface for IPin on this object will fail. The IPinInfo::get_Pin method returns the pin object, on which the IPin interface is supported.

IPinInfo::get_PinID

IPinInfo Interface

Retrieves the pin identifier.

HRESULT get_PinID(
BSTR *strPinID
);

Parameters
strPinID
[out, retval] Pin identifier string.
Return Values

Returns an HRESULT value.

Remarks

The returned strPinID string can be passed to IFilterInfo::FindPin. This is often the same as the name of the pin, but might be some other value. This identifier can be written to persistent storage and used later to identify the same pin in a different instance of the filter.

IPinInfo::Render

IPinInfo Interface

Connects filters together as necessary in order to render the output of this pin, using any necessary transform and rendering filters.

HRESULT Render(void);

Return Values

Returns an HRESULT value.

Remarks

This method is essentially an Automation wrapper for the IGraphBuilder::Render method. This method is valid only on output pins.


IQualityControl Interface

The IQualityControl interface defines quality messages and allows a quality manager to install itself as the sink for these messages. The following structures are defined for quality management.

  • QualityMessageType
  • Quality

The IQualityControl::Notify method receives a Quality message. A filter may call IQualityControl::Notify to send a Quality message to another filter to ask for help in managing the graph quality (typically to achieve graceful degradation on a processor that is not powerful enough to handle all the data). Quality messages usually flow upstream.

The IQualityControl::SetSink method tells a filter where to send it. If no sink has been explicitly set or if the last SetSink set the sink to NULL, the message should go upstream. The filter sends a message upstream by calling QueryInterface on the output pin to which its input pin is connected, in order to retrieve an IQualityControl interface. Filters export the IQualityControl interface through their pins.

Messages start with rendering filters, because these must run in real time. Other filters must run to keep the renderers supplied; these do not originate messages, but they can pass them on.

If a filter receives a quality message, it returns S_OK if it agrees to act on the quality message to handle the situation, or S_FALSE if it cannot handle it. For example, if the video renderer receives S_FALSE (or failure codes), it will readily drop frames to try to maintain synchronization. If it receives S_OK, it will trust the upstream filter; it also will allow frames to be played much earlier than their due time and will allow frames to be played much later without dropping them. Usually, the video renderer causes early frames to be blocked until their due time. But if this is the first frame after a dropped frame, the video renderer will play the frame as soon as possible so as not to lose time.

A reasonable implementation for a filter that cannot handle a message is to pass the message upstream and to pass on the result. For example:

HRESULT Notify(IBaseFilter * pSelf, QualityMessage qm)
{
    if (m_QualitySink!=NULL)
        // note how pSelf has changed into Myself
        return m_QualitySink->ChangeQuality(pMyself, qm);
    else
        return  m_Upstream->Notify(pMyself, qm);
}

A quality managing component would typically set the sink for all filters to itself. It can identify filters by their IBaseFilter interface pointers in the Self parameters. A filter must always supply the same value for its IBaseFilter interface. (The official COM way of determining if two filters are the same is to use QueryInterface on them both for their IUnknown interfaces and compare those. However, because DirectShow™ is a real-time system, and because these calls are made during streaming, it is implemented this way for efficiency.)

A quality managing component (for example, an application) typically returns S_OK when called upon to help. However, it should be prepared to find that when it sends a message to a filter requesting help from that filter, it immediately gets a request from that filter for help, and that whatever return code it gives to that filter in response to the request immediately comes back from the filter as the reply to its original message. This happens if the filter uses the suggested default implementation of passing the messages upstream, but with the Quality managing component intercepting all the traffic.

The Quality message structure is:

typedef enum {
    Famine,
    Flood
} QualityMessageType;

typedef struct {
    QualityMessageType Type;
    long               Proportion;
    REFERENCE_TIME     Late;
} Quality;

The Type member of the structure indicates which filter appears to have the problem. If set to Famine, it indicates that the renderer is not getting enough samples and the receiver of the message should speed up by any means possible. If set to Flood, the sender of the message cannot keep up with the data being sent and the receiver must send less data. Other methods of degradation are not appropriate.

The Proportion member gives a rate (expressed in parts per thousand) to be used by a recipient that cannot seek (dropping frames is equivalent to seeking) but can only control its rate. For example, a proportion of 823 means that it should degrade enough to go faster by a factor of 1000/823. Likewise, a proportion of 1200 means that it can improve its quality by 20 percent, even if this results in going slower. The numbers are not cumulative. In particular, if a filter can degrade only in steps of, say, 20 percent, and if it receives a series of Quality messages all with Proportion equal to 990, it should ignore them all. It should not multiply them (for example, it should not deduce that a 20 percent reduction is called for after the twenty-third message in this case).

The Late member says how late the application is running at the moment. Negative values mean that there is some slack (probably the renderer is waiting for this time before rendering the samples). A positive value from an audio renderer does not necessarily mean that there is an audio break; it means that the audio renderer's buffer queue is running low and is heading for a break.

When to Implement

Pins that are required to pass quality control messages upstream must implement this interface. The CBasePin class inherits IQualityControl and provides a pass-through implementation for output pins. Any filter that can act on a quality control message to adjust the rate of data flow should implement this interface. Any quality management component external to the filter graph should implement this interface to receive quality control messages.

When to Use

The rendering filter (usually the video renderer) is the primary user of this interface because it originates the quality control messages. Because the messages pass from one filter to another upstream, each downstream filter calls the IQualityControl::Notify method on the upstream output pin and so is a user.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IQualityControl methods | Description
Notify | Notifies the recipient that a quality change is requested.
SetSink | Sets the IQualityControl object that will receive quality messages.

IQualityControl::Notify

IQualityControl Interface

Receives a notification that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

Parameters
pSelf
[in] Pointer to the filter that is sending the quality notification.
q
[in] Quality notification structure.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IQualityControl::SetSink

IQualityControl Interface

Sets the IQualityControl object that will receive quality messages.

HRESULT SetSink(
IQualityControl *piqc
);

Parameters
piqc
Pointer to the IQualityControl object to which the notifications should be sent.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

The filter that receives a call to this method should record the piqc but should not add a reference count to it. The object pointed to will be a quality manager and will be a part of the filter graph (for example, a plug-in distributor). Adding a reference count to this could cause circular reference problems.

The reference to the object specified in piqc is guaranteed to be valid until this method is called with a null value.


IQualProp Interface

This interface is exposed by renderers, typically a video renderer, to return information about the performance achieved — for example, the number of frames per second (fps). The values returned through the interface are reset each time the filter is stopped. The base classes of the Microsoft® DirectShow™ Software Development Kit (SDK) have a standard property page that displays the information available from this interface.

When to Implement

The IQualProp interface is implemented by the DirectShow video renderer. Other video renderers might want to implement this interface as well, although it is optional.

When to Use

Applications use this interface to retrieve video renderer performance information.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IQualProp methods | Description
get_AvgFrameRate | Retrieves the average frame rate achieved.
get_AvgSyncOffset | Retrieves the average time difference between when a frame was due for rendering and when rendering actually began (this is returned as a value in milliseconds).
get_DevSyncOffset | Retrieves the average time difference between when a frame was due for rendering and when rendering actually began (this is returned as a standard deviation).
get_FramesDrawn | Retrieves the number of frames drawn since streaming started.
get_FramesDroppedInRenderer | Retrieves the number of frames dropped by the renderer.
get_Jitter | Expresses the average time between successive frames delivered to the video renderer.

IQualProp::get_AvgFrameRate

IQualProp Interface

Retrieves the average frame rate since streaming started.

HRESULT get_AvgFrameRate(
int *piAvgFrameRate
) PURE;

Parameters
piAvgFrameRate
Number of frames per second (fps) since the streaming began.
Return Values

Returns an HRESULT value.

IQualProp::get_AvgSyncOffset

IQualProp Interface

Retrieves the average time difference between when the video frames should have been displayed and when they actually were.

HRESULT get_AvgSyncOffset(
int *piAvg
);

Parameters
piAvg
Time difference expressed in milliseconds.
Return Values

Returns an HRESULT value.

IQualProp::get_DevSyncOffset

IQualProp Interface

Retrieves the average time difference between when the video frames should have been displayed and when they actually were. This method is the same as the IQualProp::get_AvgSyncOffset method except that the value returned is calculated as a standard deviation rather than as a simple average.

HRESULT get_DevSyncOffset(
int *piDev
);

Parameters
piDev
Value denoting the accuracy of the video frames displayed.
Return Values

Returns an HRESULT value.

Remarks

When playing video from networks, the presentation can often be disrupted by network glitches. For this reason, expressing the accuracy of video frames by a simple average is inappropriate. Looking at a standard deviation provides a better idea of the overall accuracy.

IQualProp::get_FramesDrawn

IQualProp Interface

Retrieves the number of frames drawn since streaming started.

HRESULT get_FramesDrawn(
int *pcFramesDrawn
);

Parameters
pcFramesDrawn
Number of frames drawn since streaming started.
Return Values

Returns an HRESULT value.

IQualProp::get_FramesDroppedInRenderer

IQualProp Interface

Retrieves the number of frames dropped by the renderer.

HRESULT get_FramesDroppedInRenderer(
int *pcFrames
);

Parameters
pcFrames
Number of frames dropped by the renderer.
Return Values

Returns an HRESULT value.

Remarks

The property page uses this method to retrieve data from the renderer.

IQualProp::get_Jitter

IQualProp Interface

Expresses the average time between successive frames delivered to the video renderer.

HRESULT get_Jitter(
int *piJitter
);

Parameters
piJitter
Standard deviation, in milliseconds, of the interframe time.
Return Values

Returns an HRESULT value.


IQueueCommand Interface

The IQueueCommand interface provides a way to defer commands and property changes. The deferred command mechanism allows filters themselves to handle deferred commands. When they do not, the filter graph manager queues the command until the requested time and then calls the method on the filter (this would result in coarse rather than accurate synchronization). Note that a filter that does handle deferred commands must make them apply to data appearing at that time. Thus, a contrast filter asked to change the contrast at time x must ensure that it applies the change when processing data time-stamped to be rendered at time x; these samples will be processed by the filter somewhat before time x.

The IQueueCommand interface provides two methods, InvokeAtStreamTime, which queues commands at stream time, and InvokeAtPresentationTime, which queues commands at presentation time. Both return an IDeferredCommand interface to the queued command, by which the application can cancel the command, set a new presentation time for it, or get back an estimate of the likelihood of the filter graph manager being able to run the command on time.

Both presentation time and stream time commands will run once, and then be removed from the queue. Both the queue and the application will hold a reference count on the object (represented to the application by the IDeferredCommand interface), and the object will not be destroyed until both are released. Similarly, calling IUnknown::Release on the IDeferredCommand interface is not sufficient to cancel the command, because the queue also holds a reference count.

Rather than add optional stream time and presentation time constraints to every method and property on every control interface, the application uses IDispatch to provide a single interface where these time parameters can be specified. IQueueCommand provides InvokeAtStreamTime and InvokeAtPresentationTime methods that are similar in style to the IDispatch::Invoke method.

Filters can implement IQueueCommand themselves. In this case, they parse the command and queue it for action when the relevant samples arrive or when the reference clock reaches the correct point, as appropriate. For filters that do not support this, the filter graph manager will run the command when the reference clock reaches the specified time, regardless of the samples being processed at the filter.

When to Implement

This method is implemented by the filter graph manager to allow queuing of deferred commands.

When to Use

Applications can use this interface, along with the IDeferredCommand interface, to queue commands for deferred processing.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IQueueCommand methods | Description
InvokeAtStreamTime | Queues a method or property change for execution at a specified stream time (that is, presentation time relative to the current stream time offset).
InvokeAtPresentationTime | Queues a method or property change for execution at a specified presentation time.

IQueueCommand::InvokeAtPresentationTime

IQueueCommand Interface

Queues a method or property change for execution at a specified presentation time.

HRESULT InvokeAtPresentationTime(
IDeferredCommand * pCmd,
REFTIME time,
GUID* iid,
long dispidMember,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr
);

Parameters
pCmd
[out] Pointer to the place to return an interface on the deferred command if it is successfully created.
time
[in] Time at which to invoke the command.
iid
[in] Interface to be called.
dispidMember
[in] Method or property to call on the interface.
wFlags
[in] Method or property flag.
cArgs
[in] Number of arguments on pDispParams.
pDispParams
[in] Parameters to this method.
pvarResult
[in,out] Return value.
puArgErr
[out] Index to the arguments in error.
Return Values

Returns an HRESULT value.

IQueueCommand::InvokeAtStreamTime

IQueueCommand Interface

Queues a method or property change for execution at a specified stream time (that is, presentation time relative to the current stream time offset).

HRESULT InvokeAtStreamTime(
IDeferredCommand ** pCmd,
REFTIME time,
GUID *iid,
long dispidMember,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr
);

Parameters
pCmd
[out] Pointer to the place to return an interface on the deferred command if it is successfully created.
time
[in] Time at which to invoke the command.
iid
[in] Interface to be called.
dispidMember
[in] Method or property to call on the interface.
wFlags
[in] Method or property flag.
cArgs
[in] Number of arguments in pDispParams.
pDispParams
[in] Parameters to this method.
pvarResult
[in, out] Return value of the called method.
puArgErr
[out] Index to the arguments in error.
Return Values

Returns an HRESULT value.

Remarks

Run this command to affect the presentation that occurs after the specified stream time. The interface IID is an interface that can be obtained by calling IUnknown::QueryInterface on this same IQueueCommand interface.


IReferenceClock Interface

The IReferenceClock interface represents a system reference clock to be implemented by a filter in the filter graph and used by other filters.

When to Implement

Implement this interface if you are writing a filter that generates a system reference clock. Typically, this applies to audio renderer filters because audio sound boards usually contain a reference clock. Use the CBaseReferenceClock class to implement this interface.

When to Use

Use this interface on any filter to obtain reference clock notifications for a duration of elapsed time (both singular and repetitive), or to retrieve the current time.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IReferenceClock methods | Description
GetTime | Gets the current time.
AdviseTime | Requests an asynchronous notification that a duration has elapsed.
AdvisePeriodic | Requests an asynchronous, periodic notification that a duration has elapsed.
Unadvise | Cancels a request for notification.

IReferenceClock::AdvisePeriodic

IReferenceClock Interface

Requests an asynchronous, periodic notification that a duration has elapsed.

HRESULT AdvisePeriodic(
REFERENCE_TIME rtStartTime,
REFERENCE_TIME rtPeriodTime,
HSEMAPHORE hSemaphore,
DWORD * pdwAdviseCookie
);

Parameters
rtStartTime
[in] Time the notification should begin.
rtPeriodTime
[in] Duration between notifications.
hSemaphore
[in] Handle of a semaphore through which to advise.
pdwAdviseCookie
[out] Used to identify this call to AdvisePeriodic in the future; for example, to cancel it.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

When the time indicated by rtStartTime is reached, the semaphore whose handle is set as hSemaphore will be released. Thereafter, the semaphore will be released repetitively with a period of rtPeriodTime.

See Also

IReferenceClock::Unadvise, CBaseReferenceClock::AdvisePeriodic

IReferenceClock::AdviseTime

IReferenceClock Interface

Requests an asynchronous notification that a duration has elapsed.

HRESULT AdviseTime(
REFERENCE_TIME rtBaseTime,
REFERENCE_TIME rtStreamTime,
HEVENT hEvent,
DWORD * pdwAdviseCookie
);

Parameters
rtBaseTime
[in] Base reference time.
rtStreamTime
[in] Stream offset time.
hEvent
[in] Handle of an event through which to advise.
pdwAdviseCookie
[out] Destination of the token.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

When the time rtBaseTime+rtStreamTime is reached, the event whose handle is hEvent will be set. If the time has already passed, the event will be set immediately.

See Also

IReferenceClock::Unadvise

IReferenceClock::GetTime

IReferenceClock Interface

Retrieves the current time. REFERENCE_TIME is a LONGLONG type and loosely represents the number of 100-nanosecond units that have elapsed since some fixed start time. See Characteristics of a Reference Clock for other requirements on the reference clock.

HRESULT GetTime(
REFERENCE_TIME * pTime
);

Parameters
pTime
[out] Current time.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IReferenceClock::Unadvise

IReferenceClock Interface

Cancels a request for notification.

HRESULT Unadvise(
DWORD dwAdviseCookie
);

Parameters
dwAdviseCookie
[in] Request to cancel.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

See Also

IReferenceClock::AdviseTime, IReferenceClock::AdvisePeriodic


IRegFilterInfo Interface

The IRegFilterInfo interface provides access to filters in the registry and allows a registered filter to be added to the filter graph.

When to Implement

IRegFilterInfo is implemented by the filter graph manager for use by Automation client applications, such as Microsoft® Visual Basic®.

When to Use

Use this interface when it is exposed by an Automation client to query the names of filters in a collection of registry filters, and to add specific filters to the filter graph. A collection of IRegFilterInfo interfaces is returned by the IMediaControl::get_RegFilterCollection method.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IRegFilterInfo methods | Description
get_Name | Retrieves the name of the filter.
Filter | Creates an instance of this filter and adds it to the filter graph.

IRegFilterInfo::Filter

IRegFilterInfo Interface

Creates an instance of this filter and adds it to the filter graph.

HRESULT Filter(
IDispatch **ppUnk
);

Parameters
ppUnk
[out] IFilterInfo interface for the added filter.
Return Values

Returns an HRESULT value.

Remarks

Use the IRegFilterInfo::get_Name method (Name property in Visual Basic) to find the filter by comparing names in a collection of IRegFilterInfo interfaces.

IRegFilterInfo::get_Name

IRegFilterInfo Interface

Retrieves the name of the filter.

HRESULT get_Name(
BSTR * strName
);

Parameters
strName
[out, retval] Name of the filter.
Return Values

Returns an HRESULT value.

Remarks

Typically, a Visual Basic application will use the For Each...Next syntax on a collection of IRegFilterInfo interfaces and check the name of each filter in the registry until it finds the one it wants to add. It can then add the filter to the filter graph by using the IRegFilterInfo::Filter method.


IResourceConsumer Interface

The IResourceConsumer interface implements a resource consumer that requests resources from a resource manager that supports the IResourceManager interface.

When to Implement

Implement this interface on any object that requests resources from a resource manager. (The filter graph manager acts as a resource manager for Microsoft® DirectShow™.) After implementing this interface, the object can register resources that it wants to use. It passes a pointer to this interface when it does this so that the resource manager can use methods on this interface to inform the object that a resource is available, or to release a resource that it is using.

When to Use

A resource manager that implements the IResourceManager interface calls methods on this interface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IResourceManager methods | Description
AcquireResource | Notifies the resource consumer that a resource might be acquired.
ReleaseResource | Requests the resource consumer to release the specified resource.

IResourceConsumer::AcquireResource

IResourceConsumer Interface

Notifies the resource consumer that a resource might be acquired.

HRESULT AcquireResource(
LONG idResource
);

Parameters
idResource
[in] Resource identifier of the resource to be acquired.
Return Values

Returns one of the following values.
Value | Meaning
S_OK | Consumer has successfully acquired the resource.
S_FALSE | Consumer has not acquired the resource but will use IResourceManager::NotifyAcquire when it does.
VFW_S_RESOURCE_NOT_NEEDED | Consumer no longer needs the resource.
Error Value | Consumer tried to acquire the resource but failed.

IResourceConsumer::ReleaseResource

IResourceConsumer Interface

Requests the resource consumer to release the specified resource.

HRESULT ReleaseResource(
LONG idResource
);

Parameters
idResource
[in] Resource identifier to be released.
Return Values

Returns S_OK if the consumer has released it and requires it again when it becomes available, or S_FALSE if the consumer has not released it but will use IResourceManager::NotifyRelease when it does.


IResourceManager Interface

The IResourceManager interface implements a resource manager to resolve contentions for named resources.

When to Implement

Implement this interface on any object that performs the services of a resource manager. The filter graph manager acts as a resource manager for Microsoft® DirectShow™ and delegates to any existing system-wide resource manager. The filter graph manager implements the methods on this interface.

When to Use

Use this interface if your object requires resources that other objects are likely to use. The wave renderer uses this interface to resolve contentions for the wave-output device to enable sound to follow focus.

An object can use the resource manager supporting this interface to resolve possible contention between existing resources. This is carried out by registering the resource with the interface and then requesting it from this interface whenever needed.

Use this interface if your object detects user focus changes that might affect resource usage. Notifying the resource manager of a change of focus will cause the resource manager to switch contended resources to the objects that have the focus of the user.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IResourceManager methods | Description
Register | Registers a single named resource with the resource manager.
RegisterGroup | Registers a named resource group with the resource manager.
RequestResource | Requests the use of a given registered resource.
NotifyAcquire | Notifies the resource manager that an attempt to acquire a resource has completed.
NotifyRelease | Notifies the resource manager that a resource consumer has released a resource.
CancelRequest | Cancels the request for a resource.
SetFocus | Notifies the resource manager that a specified object has been given the focus of the user.
ReleaseFocus | Sets the focus object to NULL in the resource manager if the object of the current focus object is the one specified in this method.

IResourceManager::CancelRequest

IResourceManager Interface

Cancels the request for a resource.

HRESULT CancelRequest(
LONG idResource,
IResourceConsumer* pConsumer
);

Parameters
idResource
[in] Resource identifier of a pending request.
pConsumer
[in] IResourceConsumer interface that made the request.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method should be called when the IResourceConsumer object that requested the resource has not received it and no longer requires it. If it has already received the resource, it should use the IResourceManager::NotifyRelease method.

IResourceManager::NotifyAcquire

IResourceManager Interface

Notifies the resource manager that an attempt to acquire a resource has completed.

HRESULT NotifyAcquire(
LONG idResource,
IResourceConsumer* pConsumer,
HRESULT hr
);

Parameters
idResource
[in] Token for the registered resource.
pConsumer
[in] IResourceConsumer interface of the object requesting the resource.
hr
[in] Success of the acquisition; S_OK if the resource was acquired, or an error value if not.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Use this method after an IResourceConsumer::AcquireResource method returns an S_FALSE value, indicating that the acquisition will be asynchronous (that is, handled by a callback mechanism). If the hr parameter is S_OK, the resource manager will assume that the resource is now held by the caller. If the hr parameter is anything other than S_OK, the resource manager will assume that the attempt to acquire the resource failed and will reassign the resource elsewhere.

IResourceManager::NotifyRelease

IResourceManager Interface

Notifies the resource manager that IResourceConsumer has released a resource.

HRESULT NotifyRelease LONG idResource,

IResourceConsumer* pConsumer,
BOOL bStillWant
);

Parameters
idResource
[in] Resource token.
pConsumer
[in] Object releasing the resource.
bStillWant
[in] Flag specifying whether the resource is still required or not.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Use this method in response to an IResourceConsumer::ReleaseResource method, or when you have finished using the resource. The bStillWant parameter should be set TRUE if you still want the resource when it is next available, or FALSE if you no longer want the resource.

IResourceManager::Register

IResourceManager Interface

Registers a single named resource with the resource manager.

HRESULT Register(
LPCWSTR pName,
LONG cResource,
LONG* plToken
);

Parameters
pName
[in] Named resource.
cResource
[in] Number of resources.
plToken
[out] Returned token identifying the resource to be used in additional calls.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This method registers a named resource, which can contain a number of resources, and returns a token to be used when requesting this resource. It is not an error if the resource is already registered; if the number in the cResource parameter is less than what is already registered, resources will be deallocated to the new count. To unregister the resource, pass a count of zero in cResource.

IResourceManager::RegisterGroup

IResourceManager Interface

Registers a named resource group with the resource manager.

HRESULT RegisterGroup(
LPCWSTR pName,
LONG cResource,
LONG* palTokens,
LONG* plToken
);

Parameters
pName
[in] Named resource group.
cResource
[in] Number of resources in the group.
palTokens
[in, size_is(cResource)] Array of resources in the group.
plToken
[out] Returned group resource identifier.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

IResourceManager::ReleaseFocus

IResourceManager Interface

Sets the focus object to NULL in the resource manager if the current focus object is the one specified in this method.

HRESULT ReleaseFocus(
IUnknown* pFocusObject
);

Parameters
pFocusObject
[in] Focus object.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

Use this method when the object of focus is about to be destroyed to ensure that the focus is not still being referenced.

IResourceManager::RequestResource

IResourceManager Interface

Requests the use of a given registered resource.

HRESULT RequestResource(
LONG idResource,
IUnknown* pFocusObject,
IResourceConsumer* pConsumer
);

Parameters
idResource
[in] Resource token retrieved when the resource was registered.
pFocusObject
[in] IUnknown interface of a focus object associated with a request (normally the filter's IUnknown interface).
pConsumer
[in] IResourceConsumer interface on the object requesting the resource.
Return Values

Returns an HRESULT value. Returns S_OK if the requested resource is returned, or S_FALSE if the resource is not available, in which case the resource manager will call the requesting object back when the resource becomes available. Any other return is an error.

Remarks

When there is more than one request for the resource, the resource manager will decide the priority by using the object of focus passed with each request and comparing it to the object of focus passed in the most recent IResourceManager::SetFocus method.

Requests will be filled in the following order of priority.

  1. Requests made with exactly the same object of focus as the last SetFocus method.
  2. Requests whose object of focus shares a common source filter.
  3. Requests whose object of focus shares a common filter graph.
  4. Requests in the same process as the focus.

While checking this priority, the resource manager will use QueryInterface on the focus object for IID_IFilter. If found, the resource manager will use IBaseFilter methods to check the filter graph and look for common source filters with the current focus object.

A filter should pass the IUnknown interface of the filter in the pFocusObject parameter. The filter graph manager matches filters to the filter graph and will attempt to trace filters to common source filters when checking objects of focus.

The focus object must be valid for the entire lifetime of the request — until either the IResourceManager::CancelRequest method is called, or the IResourceManager::NotifyRelease method is called with the bStillWant parameter set to FALSE.

IResourceManager::SetFocus

IResourceManager Interface

Notifies the resource manager that a specified object has been given the focus of the user.

HRESULT SetFocus(
IUnknown* pFocusObject
);

Parameters
pFocusObject
[in] Object that has been given the focus of the user.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

In DirectShow, the object given the user's focus is typically a video renderer whose window has received the focus. The resource manager gives priority to requests for resources in the following order.

  1. Requests made with the focus object specified in the pFocusObject parameter.
  2. Requests whose focus object shares a common source filter.
  3. Requests whose focus object shares a common filter graph.
  4. Requests in the same process as the focus.

Once a focus has been set, the resource manager must maintain a focus object until ReleaseFocus is called. That is, after calling this method, you must use ReleaseFocus before the IUnknown interface of the focus object becomes invalid, unless you can guarantee that SetFocus is called by a different object in the meantime. No reference count is held on the focus object.

The resource manager will hold this pointer until replaced or canceled, and will use it to resolve resource contention. It will use QueryInterface for the IBaseFilter interface at least and, if found, will use methods on that interface. It calls methods on IBaseFilter to decide which audio renderer to use if there are two (it will choose the one with a source filter common to the focus object), and also to determine if the two objects are within the same filter graph.


ISeekingPassThru Interface

The ISeekingPassThru interface is exposed on video renderer filters. It has only one method, Init, which you use to instantiate and initialize a CRendererPosPassThru object. Use this object to keep track of reference times and stream times. The IMediaSeeking and IMediaPosition interfaces can use these times to seek to various places in multimedia files.

When to Implement

Implement this interface when you write a video renderer filter that needs to keep track of reference time and stream time.

When to Use

Use this interface in your application when you want to create a CRendererPosPassThru class object.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
ISeekingPassThru methods | Description
Init | Initializes a CRendererPosPassThru renderer-seeking object.

ISeekingPassThru::Init

ISeekingPassThru Interface

Initializes a CRendererPosPassThru renderer-seeking object.

HRESULT Init(
BOOL bSupportRendering,
IPin *pPin
);

Parameters
bSupportRendering
[in] TRUE indicates the pin specified in pPin is a renderer pin; FALSE indicates not a renderer pin.
pPin
[in] Pointer to the filter's input pin.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. Current DirectShow implementation return values include:
Value | Meaning
E_FAIL | Failed to create and initialize a CRendererPosPassThru object.
E_OUTOFMEMORY | Not enough memory to create the object.
NOERROR | Successfully created and initialized a CRendererPosPassThru object.

Remarks

This method instantiates and initializes a CRendererPosPassThru object.


IStandardCutList Interface

The IStandardCutList interface provides a simple way for an application to feed a cutlist into a cutlist provider (filter).

The IStandardCutList::AddElement method provides the primary functionality of this interface, by taking a pointer to a cutlist element and adding it to the list. The first clip added to a cutlist determines the media type. All other clips must be of the same media type. Removing clips from the cutlist is not supported.

The filter graph must be stopped when you call many of the methods on this interface.

See About Cutlists and Using Cutlists for more information.

When to Implement

Do not implement this interface. DirectShow implements it for you.

When to Use

Use this interface in your application when you need to create a whole cutlist out of individual cuts (elements).

When compiling a cutlist application you must explicitly include the cutlist header file as follows:

#include <cutlist.h>

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IStandardCutList methods | Description
AddElement | Accepts a cutlist element from the application and adds it to the cutlist.
RemoveElement | Removes an element from a cutlist. (Not currently implemented.)
GetFirstElement | Retrieves the first element you added to cutlist.
GetLastElement | Retrieves the last element you added to cutlist.
GetNextElement | Retrieves the next element in the cutlist.
GetPreviousElement | Retrieves the previous element in the cutlist.
GetMediaType | Retrieves the clip's media type structure.
SetMediaType | Sets the media type for all clips in the cutlist.

IStandardCutList::AddElement

IStandardCutList Interface

Accepts a cutlist element from the application and adds it to the cutlist.

HRESULT AddElement(
IAMCutListElement *pElement,
REFERENCE_TIME mtStart,
REFERENCE_TIME mtDuration
);

Parameters
pElement
[in] Pointer to the cutlist element to be added to the cutlist.
mtStart
[in] Relative position of the cut in the cutlist. Must be CL_DEFAULT_TIME (indicating that the relative position is the end of the current cutlist).
mtDuration
[in] Length of the cut. Must be CL_DEFAULT_TIME (indicating the duration is defined by the element).
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate the element descriptor.
S_OK | Success.

Remarks

This method adds a clip to the end of the clip list. The cutlist will play in the order you add the clips.

You can't call AddElement on this cutlist after you have given the cutlist to the graph builder by calling ICutListGraphBuilder::AddCutList. The AddElement call will be ignored. Make sure you have called AddElement as many times as you need to before calling ICutListGraphBuilder::AddCutList.

Removing clips from the cutlist is not supported.

The first clip added to a cutlist determines the media type. All other clips must be of the same media type.

See Also

IAMCutListElement

IStandardCutList::GetFirstElement

IStandardCutList Interface

Retrieves the first element you added to the cutlist.

HRESULT GetFirstElement(
IAMCutListElement **ppElement
);

Parameters
ppElement
[out] Address of a pointer to the first element in the cutlist.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();
See Also

GetLastElement, IAMCutListElement

IStandardCutList::GetLastElement

IStandardCutList Interface

Retrieves the last element you added to the cutlist.

HRESULT GetLastElement(
IAMCutListElement **ppElement
);

Parameters
ppElement
[out] Address of a pointer to the last element you added to the cutlist.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();
See Also

GetFirstElement, IAMCutListElement

IStandardCutList::GetMediaType

IStandardCutList Interface

Retrieves the clip's media type structure.

HRESULT GetMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
[in] Pointer to the AM_MEDIA_TYPE structure describing the clip.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_OK | Success.

Remarks

This method retrieves the media type of all clips in the cutlist.

The first clip added to a cutlist determines the media type. All other clips must be of the same media type.

IStandardCutList::GetNextElement

IStandardCutList Interface

Retrieves the next element in the cutlist.

HRESULT GetNextElement(
IAMCutListElement **ppElement
);

Parameters
ppElement
[out] Address of a pointer to the next cutlist element.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure. You must call GetFirstElement or GetLastElement.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_FALSE | There is no next element.
S_OK | Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

You must call GetFirstElement or GetLastElement before this method will succeed.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();
See Also

GetPreviousElement, IAMCutListElement

IStandardCutList::GetPreviousElement

IStandardCutList Interface

Retrieves the previous element in the cutlist.

HRESULT GetPreviousElement(
IAMCutListElement **ppElement
);

Parameters
ppElement
[out] Address of a pointer to the previous cutlist element.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure. You must call GetFirstElement or GetLastElement.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_OUTOFMEMORY | Could not allocate required memory.
S_FALSE | There is no previous element.
S_OK | Success.

Remarks

You can only call this method when the graph is stopped. If you call this method while the graph is playing or paused, unpredictable behavior will result, including corrupting the cutlist that is playing.

You must call GetFirstElement or GetLastElement before this method will succeed.

This method increments the reference count on the cutlist element object. Be sure to decrement the cutlist element's reference count by calling its Release method as follows.

   *ppElement->Release();
See Also

GetNextElement, IAMCutListElement

IStandardCutList::RemoveElement

IStandardCutList Interface

Removes an element from a cutlist. (Not currently implemented.)

HRESULT RemoveElement(
IAMCutListElement *pElement
);

Parameters
pElement
[in] Pointer to the element to be removed.

IStandardCutList::SetMediaType

IStandardCutList Interface

Sets the media type for all clips in the cutlist.

HRESULT SetMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
[in] Pointer to the AM_MEDIA_TYPE structure describing the clip.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_UNEXPECTED | Too late to set the media type.
S_OK | Success.

Remarks

This method tells a cutlist what media type all of the elements in the cutlist must have. If you do not call this method, the first non-NULL element given to the cutlist through IStandardCutList::AddElement will determine the media type of the cutlist. All subsequent calls to AddElement must be of the same media type.

If you call this method, you must do so before ever calling AddElement. This method limits the elements that can be added to elements of the specified media type.


IUnknown Interface

The IUnknown interface lets clients get pointers to other interfaces on a given object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other Component Object Model (COM) interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.

Note that this interface and its methods are fully described in the COM documentation and are only partially documented here for quick reference.

When to Implement

You must implement IUnknown as part of every interface. If you are using C++ multiple inheritance to implement multiple interfaces, the various interfaces can share one implementation of IUnknown. If you are using nested classes to implement multiple interfaces, you must implement IUnknown once for each interface you implement.

Note that the IUnknown interface is implemented by the CUnknown base class in the DirectShow™ class library and so is inherited by most other classes.

When to Use

Use IUnknown methods to switch between interfaces on an object, add references, and release objects.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IUnknown::AddRef

IUnknown Interface

Increments the reference count for the calling interface on an object. It should be called for every new copy of a pointer to an interface on a given object.

ULONG AddRef(void);

Return Values

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value might be unstable.

IUnknown::QueryInterface

IUnknown Interface

Returns a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must use IUnknown::AddRef on the pointer it returns.

HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);

Parameters
iid
[in] Specifies the IID of the interface being requested.
ppvObject
[out] Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.
Return Values

Returns S_OK if the interface is supported, S_FALSE if not.

IUnknown::Release

IUnknown Interface

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

ULONG Release(void);

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.


IVideoWindow Interface

The IVideoWindow interface supports the video window properties of a video renderer. It is a dual interface (accessible through Microsoft® Visual Basic® and Visual C++®) that controls a generic video window. Generally, this is a video renderer that draws video into a window on the display. The IVideoWindow interface supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as Microsoft Visual Basic). However, some operations require several properties to be changed simultaneously; for this reason, methods are provided that allow a number of related properties to be changed simultaneously. For example, setting the window's position and size can be done by four individual put_[property name] calls or by the single method SetWindowPosition.

The methods require only that the video renderer be connected. If it is not connected, all the interface functions return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

Because this interface is Automation-compatible, there are two important aspects to remember about parameters accepted by these methods. First, all Boolean returns are OAFALSE (0) or OATRUE (–1), which is different from the C or C++ definition. Second, all strings are defined as being of type BSTR. All strings sent to the interface should be allocated through the Automation SysAllocString function, and similarly all strings returned from the interface should be freed by using the Automation SysFreeString function.

When to Implement

The video renderer filter supplied with Microsoft DirectShow™ implements this interface. It is also implemented by the filter graph manager (via a plug-in distributor) to pass method calls from the application to the video renderer filter's implementation of the interface.

Implement this interface if you are writing a replacement video renderer filter. You can use the CBaseVideoWindow class, which handles the IDispatch implementation for Automation, to help implement this interface.

When to Use

This interface is used by applications or other filters that must control the video window's properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch methods | Description
GetTypeInfoCount | Determines whether there is type information available for this dispinterface.
GetTypeInfo | Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames | Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke | Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IVideoWindow methods | Description
put_Caption | Sets the text caption on the playback window.
get_Caption | Retrieves the text caption on the playback window.
put_WindowStyle | Sets the playback window style.
get_WindowStyle | Retrieves the playback window style.
put_WindowStyleEx | Sets the style of the control window.
get_WindowStyleEx | Retrieves the playback window's extended style bits.
put_AutoShow | Specifies if the window will be automatically shown on the first state change.
get_AutoShow | Returns if the window will be automatically shown on the first state change.
put_WindowState | Sets the current window state (such as visible or minimized).
get_WindowState | Retrieves the current window state (such as visible or minimized).
put_BackgroundPalette | Informs the renderer to realize its palette in the background.
get_BackgroundPalette | Returns whenever the renderer realizes its palette in the background.
put_Visible | Sets the visibility of the window.
get_Visible | Retrieves the visibility of the window.
put_Left | Sets the x-axis coordinate for the video window.
get_Left | Retrieves the x-axis coordinate for the video window.
put_Width | Sets the width of the video window.
get_Width | Retrieves the width of the video window.
put_Top | Sets the y-axis coordinates for the video window.
get_Top | Retrieves the y-axis coordinates for the video window.
put_Height | Sets the height of the video window.
get_Height | Retrieves the height of the video window.
put_Owner | Sets the owning parent window for the video playback window.
get_Owner | Retrieves the owning parent window for the video playback window.
put_MessageDrain | Specifies a window to which the video window will post messages.
get_MessageDrain | Retrieves the window set to receive messages from the video window.
get_BorderColor | Retrieves the border color for the video window.
put_BorderColor | Sets the border color for the video window.
get_FullScreenMode | Returns the full-screen rendering mode of the video renderer filter supporting this interface.
put_FullScreenMode | Sets the full-screen mode for the video renderer filter supporting this interface.
SetWindowForeground | Tells the renderer filter to become the foreground window.
NotifyOwnerMessage | Forwards messages that have been received by a parent window to a child window owned by a filter.
SetWindowPosition | Sets the video window position on the display.
GetWindowPosition | Retrieves the video window position.
GetMinIdealImageSize | Retrieves the ideal minimum image size for the video image playback (client) area.
GetMaxIdealImageSize | Retrieves the ideal maximum image size for the video image playback (client) area.
GetRestorePosition | Returns the normal restored window dimensions.
HideCursor | Hides the cursor.
IsCursorHidden | Determines if the cursor is hidden or showing.

IVideoWindow::get_AutoShow

IVideoWindow Interface

Retrieves information about whether the window will be automatically shown.

HRESULT get_AutoShow(
long *AutoShow
);

Parameters
AutoShow
[out] OATRUE indicates that the window will be made visible when the state is changed to the paused or running state.
Return Values

Returns an HRESULT value.

IVideoWindow::get_BackgroundPalette

IVideoWindow Interface

Retrieves information about whether any palette required will be realized in the background.

HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);

Parameters
pBackgroundPalette
[out] OATRUE indicates that the palette will be realized in the background.
Return Values

Returns an HRESULT value.

IVideoWindow::get_BorderColor

IVideoWindow Interface

Retrieves the border color for the video window.

HRESULT get_BorderColor(
long *pColor
);

Parameters
pColor
[out] Retrieved border color as a COLORREF value.
Return Values

Returns an HRESULT value.

IVideoWindow::get_Caption

IVideoWindow Interface

Retrieves the textual title string for the video window.

HRESULT get_Caption(
BSTR *strCaption
);

Parameters
strCaption
[out] Retrieved window title caption.
Return Values

Returns an HRESULT value.

IVideoWindow::get_FullScreenMode

IVideoWindow Interface

Returns the full-screen rendering capabilities of the renderer filter supporting this interface.

HRESULT get_FullScreenMode(
long *FullScreenMode
);

Parameters
FullScreenMode
[out] OATRUE if supporting full-screen video, or OAFALSE if not.
Return Values

Returns an HRESULT value.

Remarks

This method is called by the filter graph manager when asked to render the video to full-screen size. If the renderer does not have inherent support for full-screen playback, it should return E_NOTIMPL. Otherwise, it should return NOERROR. If the renderer does support full-screen playback, this method determines if it is currently switched on or off.

IVideoWindow::get_Height

IVideoWindow Interface

Sets the height of the video window.

HRESULT get_Height(
long *pHeight
);

Parameters
pHeight
[out] Retrieved vertical dimension of the video window.
Return Values

Returns an HRESULT value.

IVideoWindow::get_Left

IVideoWindow Interface

Retrieves the x-axis coordinate for the video window.

HRESULT get_Left(
long *pLeft
);

Parameters
pLeft
[out] The x-axis coordinate to be retrieved.
Return Values

Returns an HRESULT value.

IVideoWindow::GetMaxIdealImageSize

IVideoWindow Interface

Retrieves the ideal maximum image size for the video image playback (client) area.

HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
[out] Image width.
pHeight
[out] Image height.
Return Values

Returns an HRESULT value.

IVideoWindow::get_MessageDrain

IVideoWindow Interface

Retrieves the window set to receive messages from the video window.

HRESULT get_MessageDrain(
OAHWND *Drain
);

Parameters
Drain
[in] Window currently assigned to receive messages from the video window.
Return Values

Returns an HRESULT value.

Remarks

The IVideoWindow::put_MessageDrain description contains a list of the Microsoft Win32® messages passed to the window that is specified as a message drain.

IVideoWindow::GetMinIdealImageSize

IVideoWindow Interface

Retrieves the ideal minimum image size for the video image playback (client) area.

HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
[out] Image width.
pHeight
[out] Image height.
Return Values

Returns an HRESULT value.

IVideoWindow::get_Owner

IVideoWindow Interface

Retrieves the owning parent for the video window.

HRESULT get_Owner(
OAHWND * pOwner
);

Parameters
pOwner
[out] Retrieved window handle.
Return Values

Returns an HRESULT value.

IVideoWindow::GetRestorePosition

IVideoWindow Interface

Returns the normal restored window dimensions.

HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
[out] Left x-axis coordinate of the window.
pTop
[out] Top y-axis coordinate of the window.
pWidth
[out] Width of the window in pixels.
pHeight
[out] Height of the window in pixels.
Return Values

Returns an HRESULT value.

Remarks

When the window is maximized or minimized, the window position methods return the actual window size. This method returns the dimensions that the window would be when restored. It is useful for applications that want to save a window state while the window is maximized or minimized.

IVideoWindow::get_Top

IVideoWindow Interface

Retrieves the y-axis coordinate of the video window.

HRESULT get_Top(
long *pTop
);

Parameters
pTop
[out] The y-axis origin to be retrieved.
Return Values

Returns an HRESULT value.

IVideoWindow::get_Visible

IVideoWindow Interface

Retrieves the visibility of the video window.

HRESULT get_Visible(
long *pVisible
);

Parameters
pVisible
[out] OATRUE if the window is shown; otherwise, the window is hidden.
Return Values

Returns an HRESULT value.

IVideoWindow::get_Width

IVideoWindow Interface

Retrieves the width of the video window.

HRESULT get_Width(
long *pWidth
);

Parameters
pWidth
[out] Width to be retrieved.
Return Values

Returns an HRESULT value.

IVideoWindow::GetWindowPosition

IVideoWindow Interface

Retrieves the current window rectangle (not the client rectangle) in device coordinates.

HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
[out] The x-axis origin of the window.
pTop
[out] The y-axis origin of the window.
pWidth
[out] Width of the window in pixels.
pHeight
[out] Height of the window in pixels.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IVideoWindow::get_Left, IVideoWindow::get_Top, IVideoWindow::get_Width, and IVideoWindow::get_Height methods.

IVideoWindow::get_WindowState

IVideoWindow Interface

Returns the state of the video window.

HRESULT get_WindowState(
long *WindowState
);

Parameters
WindowState
[out] Flags indicating the state of the video window.
Return Values

Returns an HRESULT value.

Remarks

This method retrieves a subset of the properties of the window state, specifically SW_MINIMIZE, SW_MAXIMIZE, SW_SHOW, or SW_HIDE. These have the same definitions as the Microsoft Win32 ShowWindow function.

IVideoWindow::get_WindowStyle

IVideoWindow Interface

Changes the style parameters for the video window.

HRESULT get_WindowStyle(
long *pWindowStyle
);

Parameters
pWindowStyle
[out] Set of flags that matches a subset of the flags that can be set by the GWL_STYLE value of the Microsoft Win32 GetWindowLong function.
Return Values

Returns an HRESULT value.

Remarks

For a complete list of window styles, see the CreateWindow function in the Microsoft Win32 Software Development Kit (SDK).

IVideoWindow::get_WindowStyleEx

IVideoWindow Interface

Changes the style parameters for the video window.

HRESULT get_WindowStyleEx(
long * pWindowStyleEx
);

Parameters
pWindowStyleEx
[out] Set of flags that matches a subset of the flags that can be set by the GWL_STYLE value of the Microsoft Win32 GetWindowLong function.
Return Values

Returns an HRESULT value.

Remarks

This function uses extended window styles. For a complete list of window styles, see the CreateWindow function in the Microsoft Win32 Software Development Kit (SDK).

IVideoWindow::HideCursor

IVideoWindow Interface

Hides the cursor.

HRESULT HideCursor(
long HideCursor
);

Parameters
HideCursor
[in] If OATRUE, do not display the cursor; if OAFALSE, display the cursor.
Return Values

Returns an HRESULT value.

Remarks

This method is typically used when the video renderer is in full-screen mode, where cursor display might be unwanted.

IVideoWindow::IsCursorHidden

IVideoWindow Interface

Determines if the cursor is hidden or showing.

HRESULT IsCursorHidden(
long * CursorHidden
);

Parameters
CursorHidden
[out] If OATRUE, cursor is hidden; if OAFALSE, cursor is displayed.
Return Values

Returns an HRESULT value.

Remarks

This method is typically used when the video renderer is in full-screen mode, where cursor display might be unwanted.

IVideoWindow::NotifyOwnerMessage

IVideoWindow Interface

Forwards messages that have been received by a parent window to a child window owned by a filter.

HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);

Parameters
hwnd
[in] Window handle.
uMsg
[in] Message being sent.
wParam
[in] Message's wParam passed in.
lParam
[in] Message's lParam passed in.
Return Values

Returns an HRESULT value.

Remarks

This method should be used by windows that make a renderer window a child window. It forwards significant messages to the child window that the child window would not otherwise receive. This includes the following messages.
WM_ACTIVATEAPP
WM_DEVMODECHANGE
WM_DISPLAYCHANGE
WM_PALETTECHANGED
WM_PALETTEISCHANGING
WM_QUERYNEWPALETTE
WM_SYSCOLORCHANGE

IVideoWindow::put_AutoShow

IVideoWindow Interface

Determines whether or not the window will be automatically shown.

HRESULT put_AutoShow(
long AutoShow
);

Parameters
AutoShow
[in] OATRUE (–1) means the window will be visible when the state changes; OAFALSE (0) means the window remains hidden until explicitly shown.
Return Values

Returns an HRESULT value.

Remarks

Many simple applications require a displayed window when a filter graph is set to the running state. AutoShow defaults to OATRUE so that when the graph changes state to paused or running, the window is visible (it also is set as the foreground window). It will remain visible on all subsequent state changes to paused or running. If you close the window while the stream is running, the window will not automatically reappear. If you stop and restart the stream, however, the window will automatically reappear.

See Also

IVideoWindow::put_Visible

IVideoWindow::put_BackgroundPalette

IVideoWindow Interface

Determines whether any palette required will be realized in the background.

HRESULT put_BackgroundPalette(
long BackgroundPalette
);

Parameters
BackgroundPalette
[in] OATRUE to realize the palette in the background; otherwise, OAFALSE.
Return Values

Returns an HRESULT value.

Remarks

If this is OATRUE (–1), any palette required by the video is realized by the renderer in the background. This means that any colors the palette uses will change to their closest match in the display palette prior to drawing. This ensures that an application will not have its palette disturbed when playing a video. It does, however, impose severe performance penalties on the video and should not be used unless absolutely necessary. The default value for this property is OAFALSE.

IVideoWindow::put_BorderColor

IVideoWindow Interface

Sets the border color for the video window.

HRESULT put_BorderColor(
long Color
);

Parameters
Color
[in] New border color as a COLORREF type.
Return Values

Returns an HRESULT value.

Remarks

When a destination rectangle that is set differs from the visible client area of the window, a border is exposed around the edge. This method allows an application to change the border color. It is set to black by default. Any nonsystem color passed in is converted to its closest match according to the current palette before being used (this is not an issue on true color devices). Setting this causes the window border to be repainted in the new color automatically.

IVideoWindow::put_Caption

IVideoWindow Interface

Sets the textual title string for the video window.

HRESULT put_Caption(
BSTR strCaption
);

Parameters
strCaption
[in] Window title caption.
Return Values

Returns an HRESULT value.

IVideoWindow::put_FullScreenMode

IVideoWindow Interface

Sets the full-screen mode for the video renderer filter supporting this interface.

HRESULT put_FullScreenMode(
long FullScreenMode
);

Parameters
FullScreenMode
[in] OATRUE if supporting full-screen video, or OAFALSE if not.
Return Values

Returns E_NOTIMPL if the video renderer doesn't support full-screen mode or NOERROR if it does.

Remarks

This method allows an application to switch a full-screen renderer into and out of full-screen mode. The renderer's behavior when switched out of full-screen mode is implementation-dependent. The Microsoft full-screen renderer, for example, switches back to a window.

The IVideoWindow plug-in distributor in the filter graph manager implements full-screen renderer switching. It looks to see if any renderer in the graph supports a full-screen mode and, if not, will temporarily replace the renderer with the default DirectShow full-screen renderer. It calls IVideoWindow::GetMaxIdealImageSize to determine if a window can be made a topmost window and resized to the entire display. This is preferred to swapping renderers, because the filter graph might be using DirectDraw® overlays or a hardware decoder filter.

IVideoWindow::put_Height

IVideoWindow Interface

Sets the height of the video window.

HRESULT put_Height(
long Height
);

Parameters
Height
[in] New vertical dimension of the video window.
Return Values

Returns an HRESULT value.

Remarks

Calling this method does not affect the y-axis coordinate of the video window.

IVideoWindow::put_Left

IVideoWindow Interface

Sets the x-axis coordinate for the video window.

HRESULT put_Left(
long Left
);

Parameters
Left
[in] The x-axis coordinate to be set.
Return Values

Returns an HRESULT value.

Remarks

Calling this method does not affect the video window's width.

IVideoWindow::put_MessageDrain

IVideoWindow Interface

Specifies a window to which the video window will post messages.

HRESULT put_MessageDrain(
OAHWND Drain
);

Parameters
Drain
[in] Window to which messages will be posted.
Return Values

Returns an HRESULT value.

Remarks

The video renderer passes messages to the specified message drain by calling the Microsoft Win32 PostMessage function. These messages allow you to write applications that include user interaction, such as applications that require mouse clicks on specific areas of the video display. An application can have a close relationship with the video window and know at certain time points to look for user interaction. When the renderer passes a message to the drain, it sends the parameters, such as the client-area coordinates, exactly as generated.

DirectShow passes the following messages to the window specified by the Drain parameter, if and when the application generates them.
WM_KEYDOWN
WM_KEYUP
WM_LBUTTONDBLCLK
WM_LBUTTONDOWN
WM_LBUTTONUP
WM_MBUTTONDBLCLK
WM_MBUTTONDOWN
WM_MBUTTONUP
WM_MOUSEACTIVATE
WM_MOUSEMOVE
WM_NCLBUTTONDBLCLK
WM_NCLBUTTONDOWN
WM_NCLBUTTONUP
WM_NCMBUTTONDBLCLK
WM_NCMBUTTONDOWN
WM_NCMBUTTONUP
WM_NCMOUSEMOVE
WM_NCRBUTTONDBLCLK
WM_NCRBUTTONDOWN
WM_NCRBUTTONUP
WM_RBUTTONDBLCLK
WM_RBUTTONDOWN
WM_RBUTTONUP

Because this member function does not make the message drain window a child window, applications with full-screen capabilities can use it.

IVideoWindow::put_Owner

IVideoWindow Interface

Sets an owning parent for the video window.

HRESULT put_Owner(
OAHWND Owner
);

Parameters
Owner
[in] Handle of new owner window.
Return Values

Returns an HRESULT value.

Remarks

This method offers a way for applications to set the owner of the video window. This is often used when playing videos in compound documents. This method changes the parent of the renderer window and sets the WS_CHILD style for the video window.

To forward video window messages to the parent window, use the IVideoWindow::put_MessageDrain method, supplying the window handle of the parent window. This method does not post messages automatically.

After using this method to set the owner of a video window, you must reset the owner to NULL (by calling put_Owner(NULL)) before releasing the filter graph. Otherwise, messages will continue to be sent to this window and errors will likely occur when the application is terminated.

IVideoWindow::put_Top

IVideoWindow Interface

Sets the y-axis coordinate of the video window.

HRESULT put_Top(
long Top
);

Parameters
Top
[in] The y-axis origin of the video window.
Return Values

Returns an HRESULT value.

Remarks

Calling this method does not affect the height of the video window.

IVideoWindow::put_Visible

IVideoWindow Interface

Changes the visibility of the video window.

HRESULT put_Visible(
long Visible
);

Parameters
Visible
[in] Boolean flag that is compatible with Automation.
Return Values

Returns an HRESULT value.

Remarks

If the Visible parameter is set to OATRUE (–1), the window is shown. If it is set to OAFALSE (0), the window is hidden.

IVideoWindow::put_Width

IVideoWindow Interface

Sets the video window's width.

HRESULT put_Width(
long Width
);

Parameters
Width
[in] Width to be set.
Return Values

Returns an HRESULT value.

Remarks

Calling this method does not affect the video window's x-axis coordinate.

IVideoWindow::put_WindowState

IVideoWindow Interface

Sets the video window's state.

HRESULT put_WindowState(
long WindowState
);

Parameters
WindowState
[in] Describes the video window's state.
Return Values

Returns NOERROR.

Remarks

This method is a wrapper for the Microsoft Win32 ShowWindow function. IVideoWindow::put_WindowState passes the WindowState parameter on to CBaseWindow::DoShowWindow, which in turn passes it on to ShowWindow. Hence, WindowState can be any value that is valid for ShowWindow.

IVideoWindow::put_WindowStyle

IVideoWindow Interface

Changes the style parameters for the video window.

HRESULT put_WindowStyle(
long WindowStyle
);

Parameters
WindowStyle
[in] Set of flags that matches a subset of the flags that can be set by the GWL_STYLE value of the Microsoft Win32 GetWindowLong function.
Return Values

Returns an HRESULT value.

Remarks

Use this property to change the overall style of the video window; for example, to remove the border and caption areas of the video window. It is a fairly thin wrapper on top of setting the GWL_STYLE value of the Microsoft Win32 GetWindowLong function and therefore must be treated with care. In particular, ensure that the current styles are first retrieved, and then the necessary bit fields are added or removed. With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.

Do not use this method to affect the window size. For example, if the window is minimized, do not set the WS_MAXIMIZE style; doing so causes unpredictable results. Instead, use the IVideoWindow::put_WindowState method for maximizing or minimizing the window.

Any of the following styles return E_INVALIDARG.
WS_DISABLED
WS_HSCROLL
WS_ICONIC
WS_MAXIMIZE
WS_MINIMIZE
WS_VSCROLL

IVideoWindow::put_WindowStyleEx

IVideoWindow Interface

Sets the style of the control window.

HRESULT put_WindowStyleEx(
long pWindowStyleEx
);

Parameters
pWindowStyleEx
[in] Value that specifies the style of the control window.
Return Values

Returns NOERROR.

Remarks

This method uses EX window styles. For a complete list of extended window styles, see the CreateWindowEx function in the Microsoft Win32 Software Development Kit (SDK).

Use this property to change the overall style of the video window; for example, to remove the border and caption areas of the video window. It is a fairly thin wrapper on top of setting the GWL_STYLE value of the Microsoft Win32 GetWindowLong function and therefore must be treated with care. In particular, ensure that the current styles are first retrieved, and then the necessary bit fields are added or removed.

Note: Do not use the following window styles as they are not validated.
WS_DISABLED
WS_HSCROLL
WS_ICONIC
WS_MAXIMIZE
WS_MINIMIZE
WS_VSCROLL

With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.

IVideoWindow::SetWindowForeground

IVideoWindow Interface

Moves the video window to the foreground and optionally gives it focus.

HRESULT SetWindowForeground(
long Focus
);

Parameters
Focus
Long value that specifies whether the video window will get focus. A value of –1 gives the window focus and 0 does not.
Return Values

Returns one of the following values.
Value | Meaning
NOERROR | The method succeeded.
E_INVALIDARG | Focus doesn't equal –1 or 0.
VFW_E_NOT_CONNECTED | The current filter isn't connected to a complete filter graph.

IVideoWindow::SetWindowPosition

IVideoWindow Interface

Sets the position of the video window (not the client rectangle position) in device coordinates.

HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
[in] The x-axis origin of the window.
Top
[in] The y-axis origin of the window.
Width
[in] Width of the window.
Height
[in] Height of the window.
Return Values

Returns an HRESULT value.

Remarks

This method has the same effect as individually calling the IVideoWindow::put_Left, IVideoWindow::put_Top, IVideoWindow::put_Width, and IVideoWindow::put_Height methods.

Specify, in window coordinates, where the video should appear. For example, setting a destination of (100,50,200,400) positions the video playback at an origin of 100 pixels from the left of the client area and 50 pixels from the top, with an overall size of 200 x 400 pixels. If the video is smaller than this (or a source rectangle has been specified that is smaller than the video), it will be stretched appropriately. Similarly, if the video is larger than the destination rectangle, the video is compressed into the visible rectangle. There are fairly severe performance penalties if an application does not keep the source and destination rectangles the same size.

Under typical circumstances, when no destination rectangle has been set, the video fills the entire visible client window area (regardless of how much the user has stretched the window). Also, the destination rectangle properties correctly return the size of the video window client area.


IVPBaseConfig Interface

IVPBaseConfig enables a video port (VP) or overlay mixer filter to communicate with a VP driver (decoder), to set and retrieve configuration information. This interface assumes that the mixer filter creates the video port. The IVPConfig interface derives from this interface. See also IVPBaseNotify and IVPNotify.

When to Implement

The Windows Driver Model (WDM) Ksproxy filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need this functionality on a platform that does not support WDM, or when you need to alter the default behavior.

When to Use

The Overlay Mixer filter uses this interface so you won't need to use it in most cases. Use this interface when you implement your own overlay mixer filter.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IVPBaseConfig methods | Description
GetConnectInfo | Retrieves connection information structures.
SetConnectInfo | Sets the index for the current video port connection information.
GetVPDataInfo | Retrieves the current video port data information.
GetMaxPixelRate | Retrieves the maximum pixels per second rate for a given width and height.
InformVPInputFormats | Informs the device what video formats the video port supports.
GetVideoFormats | Retrieves the video formats the decoder supports.
SetVideoFormat | Sets the format that the video will use.
SetInvertPolarity | Reverses the current polarity the decoder uses.
GetOverlaySurface | Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.
SetDirectDrawKernelHandle | Sets the DirectDraw® kernel handle for the decoder's minidriver to use.
SetVideoPortID | Sets the port ID that the video will use.
SetDDSurfaceKernelHandle | Sets the kernel handle that the DirectDraw surface will use.
SetSurfaceParameters | Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.

IVPBaseConfig::GetConnectInfo

IVPBaseConfig Interface

Retrieves connection information structures.

HRESULT GetConnectInfo(
LPDWORD pdwNumConnectInfo,
LPDDVIDEOPORTCONNECT pddVPConnectInfo
);

Parameters
pdwNumConnectInfo
[in/out] Points to a buffer that contains the number of DDVIDEOPORTCONNECT structures provided by the pddVPConnectInfo parameter. Contains the actual number of structures returned on output. If pddVPConnectInfo is NULL, this method updates this parameter with the number of structures supported by the driver.
pddVPConnectInfo
[in/out] Points to an array of DDVIDEOPORTCONNECT structures that the driver fills in. Specify NULL to retrieve the total number of formats supported.
Return Values

Returns NOERROR if the count or structures were retrieved, or a driver error.

Remarks

This method retrieves the various connection information structures such as GUID and port width structures, in an array of structures specified by pddVPConnectInfo. The callee must allocate the correct amount of space for the number of structures requested.

Set the index for connection information by using the IVPBaseConfig::SetConnectInfo method.

IVPBaseConfig::GetMaxPixelRate

IVPBaseConfig Interface

Retrieves the maximum pixels per second rate for a given width and height.

HRESULT GetMaxPixelRate(
LPAMVPSIZE pamvpSize,
LPDWORD pdwMaxPixelsPerSecond
);

Parameters
pamvpSize
[in/out] Pointer to an AMVPSIZE structure containing the desired width and height. The structure receives the final dimensions upon return.
pdwMaxPixelsPerSecond
[out] Pointer to the retrieved maximum pixels per second rate.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | NULL pointer argument.
E_INVALIDARG | Invalid argument.
NOERROR | The maximum pixel rate was retrieved.

Remarks

This method retrieves the maximum pixels per second rate expected for a given format and a given scaling factor. If the decoder does not support those scaling factors, then it returns the rate and the nearest scaling factors it supports.

IVPBaseConfig::GetOverlaySurface

IVPBaseConfig Interface

Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.

HRESULT GetOverlaySurface(
LPDIRECTDRAWSURFACE *ppddOverlaySurface
);

Parameters
ppddOverlaySurface
[out] Address of a pointer to the retrieved DirectDraw® overlay surface object.
Return Values

Returns NOERROR if the overlay surface object was returned. (Default implementation sets the surface to NULL and returns NOERROR.)

Remarks

The Overlay Mixer uses this function to determine if the driver requires the Overlay Mixer to use its overlay surface and if so to get a pointer to it. If this function returns NULL, then the Overlay Mixer allocates its own surface.

IVPBaseConfig::GetVideoFormats

IVPBaseConfig Interface

Retrieves the video formats the decoder supports.

HRESULT GetVideoFormats(
LPDWORD pdwNumFormats,
LPDDPIXELFORMAT pddPixelFormats
);

Parameters
pdwNumFormats
[in/out] Pointer to the number of DDPIXELFORMAT structures provided by the pddPixelFormats parameter. When called, this method updates this parameter with the actual number of structures retrieved. If pddPixelFormats is NULL, this method updates this parameter with the total number of formats the driver supports.
pddPixelFormats
[in/out] Pointer to an array of DDPIXELFORMAT structures that the driver fills. Specify NULL to retrieve only the count of supported formats in pdwNumFormats.
Return Values

Returns NOERROR if the count or structures were returned, or a driver error otherwise.

Remarks

This method queries for either the number of DDPIXELFORMAT structures supported by the driver, or retrieves as many structures as can fit into the provided buffer space.

The callee must allocate the correct amount of space for the number of structures requested.

Set the video format by using IVPBaseConfig::SetVideoFormat.

IVPBaseConfig::GetVPDataInfo

IVPBaseConfig Interface

Retrieves the current video port data information.

HRESULT GetVPDataInfo(
LPAMVPDATAINFO pamvpDataInfo
);

Parameters
pamvpDataInfo
[in/out] Pointer to the AMVPDATAINFO data information structure.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | NULL pointer argument.
E_INVALIDARG | Invalid argument.
NOERROR | The video port data information was retrieved.

IVPBaseConfig::InformVPInputFormats

IVPBaseConfig Interface

Informs the device what video formats the video port supports.

HRESULT InformVPInputFormats(
DWORD dwNumFormats,
LPDDPIXELFORMAT pDDPixelFormats
);

Parameters
dwNumFormats
[in] Number of video formats contained in the pDDPixelFormats parameter.
pDDPixelFormats
[in] Array of pixel format structures (DDPIXELFORMAT) to send to the device.
Return Values

Returns S_FALSE if failure, or NOERROR otherwise.

Remarks

The supplied array of supported video port formats might determine what formats the device, in turn, proposes.

IVPBaseConfig::SetConnectInfo

IVPBaseConfig Interface

Sets the index for the current video port connection information.

HRESULT SetConnectInfo(
DWORD dwChosenEntry
);

Parameters
dwChosenEntry
[in] Index of new video port connect information (zero-based) to pass to the driver.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | The video port connect information was set.

Remarks

Retrieve connection information by using IVPBaseConfig::GetConnectInfo.

IVPBaseConfig::SetDDSurfaceKernelHandle

IVPBaseConfig Interface

Sets the kernel handle to be used by the DirectDraw surface.

HRESULT SetDDSurfaceKernelHandle(
DWORD dwDDKernelHandle
);

Parameters
dwDDKernelHandle
[in] DirectDraw surface handle for kernel mode, passed as a DWORD value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | The specified handle is set successfully.

Remarks

This method sets the DirectDraw handle on the mini driver to enable it to communicate with the video port directly.

IVPBaseConfig::SetDirectDrawKernelHandle

IVPBaseConfig Interface

Sets the DirectDraw® kernel handle for the decoder's minidriver to use.

HRESULT SetDirectDrawKernelHandle(
DWORD dwDDKernelHandle
);

Parameters
dwDDKernelHandle
[in] DirectDraw kernel level handle passed as a DWORD value.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | The specified handle was set successfully.

Remarks

Sets the DirectDraw kernel level handle on the minidriver to enable it to communicate with DirectDraw directly.

IVPBaseConfig::SetInvertPolarity

IVPBaseConfig Interface

Reverses the current polarity the decoder uses.

HRESULT SetInvertPolarity(void);

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
NOERROR | The polarity was reversed.

Remarks

Reversing polarity means asking the decoder to treat even fields like odd fields and vice versa.

IVPBaseConfig::SetSurfaceParameters

IVPBaseConfig Interface

Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.

HRESULT SetSurfaceParameters(
DWORD dwPitch,
DWORD dwXOrigin,
DWORD dwYOrigin ) PURE;

Parameters
dwPitch
[in] Pitch of the surface. Distance (or pitch) in pixels between the start pixels of two consecutive lines of the surface.
dwXOrigin
[in] X-value of the pixel at which valid data starts.
dwYOrigin
[in] Y-value of the pixel at which valid data starts.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. The current default implementation returns NOERROR if the call completed successfully, or E_NOTIMPL if the method is not implemented.

IVPBaseConfig::SetVideoFormat

IVPBaseConfig Interface

Sets the format to be used by the video.

HRESULT SetVideoFormat(
DWORD dwChosenEntry
);

Parameters
dwChosenEntry
[in] Specifies the index (zero-based) of the video pixel format to use.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | The new video format was set.

Remarks

Retrieve the video formats by using IVPBaseConfig::GetVideoFormats.

IVPBaseConfig::SetVideoPortID

IVPBaseConfig Interface

Sets the port ID which the video will use.

HRESULT SetVideoPortID (
DWORD dwVideoPortID
);

Parameters
dwVideoPortID
[in] DirectDraw video port ID.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | The specified port ID is set successfully.

Remarks

This method sets the DirectDraw video port ID on the mini driver to enable it to communicate with the video port directly.


IVPBaseNotify Interface

IVPBaseNotify enables you to control the properties of a filter that uses a video port. The IVPNotify interface derives from this interface. See also IVPBaseConfig and IVPConfig.

When to Implement

The Overlay Mixer filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need to alter the default behavior.

When to Use

Use this interface in your application when you need to access video port properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IVPBaseNotify methods | Description
RenegotiateVPParameters | Initializes the connection to the decoder.

IVPBaseNotify::RenegotiateVPParameters

IVPBaseNotify Interface

Initializes the connection to the decoder.

HRESULT RenegotiateVPParameters(void) PURE;

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | NULL pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

Remarks

The Overlay Mixer filter negotiates various parameters (by using the IVPBaseConfig interface) with the decoder or driver. Call this function if any of those parameters (such as the video format or size) change. Currently, the Overlay Mixer repeats the whole connection process. You can call this method even while the graph is playing.


IVPConfig Interface

IVPConfig enables a video port (VP) or overlay mixer filter to communicate with a VP driver (decoder), to set and retrieve configuration information. This interface assumes that the mixer filter creates the video port. This interface derives from IVPBaseConfig. See also IVPBaseNotify and IVPNotify.

When to Implement

The Windows Driver Model (WDM) Ksproxy filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need this functionality on a platform that does not support WDM, or when you need to alter the default behavior.

When to Use

The Overlay Mixer filter uses this interface so you won't need to use it in most cases. Use this interface when you implement your own overlay mixer filter.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IVPBaseConfig methods | Description
GetConnectInfo | Retrieves connection information structures.
SetConnectInfo | Sets the index for the current video port connection information.
GetVPDataInfo | Retrieves the current video port data information.
GetMaxPixelRate | Retrieves the maximum pixels per second rate for a given width and height.
InformVPInputFormats | Informs the device what video formats the video port supports.
GetVideoFormats | Retrieves the video formats the decoder supports.
SetVideoFormat | Sets the format that the video will use.
SetInvertPolarity | Reverses the current polarity the decoder uses.
GetOverlaySurface | Determines whether the overlay mixer should use the driver's overlay surface and if so retrieves a pointer to the surface.
SetDirectDrawKernelHandle | Sets the DirectDraw® kernel handle for the decoder's minidriver to use.
SetVideoPortID | Sets the port ID that the video will use.
SetDDSurfaceKernelHandle | Sets the kernel handle that the DirectDraw surface will use.
SetSurfaceParameters | Tells the capture driver about the surface created on its behalf by the Overlay Mixer or VBI surface filter.
IVPConfig methods | Description
IsVPDecimationAllowed | Given the context, retrieves whether scaling at the video port is possible.
SetScalingFactors | Sets the factors by which the decoder should scale the video stream.

IVPConfig::IsVPDecimationAllowed

IVPConfig Interface

Given the context, retrieves whether scaling at the video port is possible.

HRESULT IsVPDecimationAllowed(
AMVP_CONTEXT amvpContext,
LPBOOL pbIsDecimationAllowed
);

Parameters
amvpContext
[in] Context (video or VBI) in which to query the VP decimation capability.
pbIsDecimationAllowed
[out] Pointer to the retrieved value indicating whether decimation is allowed.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | NULL pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

Remarks

The Overlay Mixer filter uses this function to determine whether the driver needs the mixer to decimate video data at its own discretion. This function can be especially useful in a capture with preview situation in which you would not want the VP mixer filter to perform any scaling at the video port.

IVPConfig::SetScalingFactors

IVPConfig Interface

Sets the factors by which the decoder should scale the video stream.

HRESULT SetScalingFactors(
LPAMVPSIZE pamvpSize
);

Parameters
pamvpSize
[in] Pointer to the new scaling size structure (AMVPSIZE) to use to specify the width and height.
Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
NOERROR | The new scaling factors were set.

Remarks

If the decoder does not support the specified scaling factors, then it sets the values to the nearest factors it can support.


IVPNotify Interface

IVPNotify enables you to control the properties of a filter that uses a video port. This interface derives from the IVPBaseNotify interface. See also IVPBaseConfig and IVPConfig.

When to Implement

The Overlay Mixer filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need to alter the default behavior.

When to Use

Use this interface in your application when you need to access video port properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IVPNotify methods | Description
SetDeinterlaceMode | Sets the deinterlacing mode (such as bob or weave).
GetDeinterlaceMode | Retrieves the deinterlacing mode (such as bob or weave).

IVPNotify::GetDeinterlaceMode

IVPNotify Interface

Retrieves the mode (such as bob or weave).

HRESULT GetDeinterlaceMode(
AMVP_MODE *pmode
) PURE;

Parameters
pmode
[out] Pointer to the retrieved mode. This value is a member of the AMVP_MODE enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The current DirectShow implementation returns NOERROR for success or E_INVALIDARG if the argument is not valid.

Remarks

This method is not currently implemented and returns E_NOTIMPL.

IVPNotify::SetDeinterlaceMode

IVPNotify Interface

Sets the mode (such as bob or weave).

HRESULT SetDeinterlaceMode(
AMVP_MODE mode
) PURE;

Parameters
mode
[in] Specified mode. This value is a member of the AMVP_MODE enumerated data type.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

The current DirectShow™ implementation returns NOERROR for success or E_INVALIDARG if mode is not a member of the AMVP_MODE enumerated data type.

Remarks

This method is not currently implemented and returns E_NOTIMPL.


IVPNotify2 Interface

IVPNotify2 enables you to control the synchronization properties of a filter that uses a video port. This interface derives from the IVPNotify interface. See also IVPBaseNotify, IVPBaseConfig, and IVPConfig.

Use this interface to manipulate the video color controls involved in mixing various video streams.

When to Implement

The Overlay Mixer filter implements this interface so you won't need to implement it in most cases. Implement this interface when you need to alter the default behavior.

When to Use

Use this interface in your application when you need to access video port properties.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IVPNotify2 methods | Description
SetVPSyncMaster | Sets the VideoPort as a sync master of the VGA (the vsync of the VGA is controlled by the VideoPort).
GetVPSyncMaster | Checks whether the VideoPort is the sync master of the VGA.

IVPNotify2::GetVPSyncMaster

IVPNotify2 Interface

Retrieves the flag specifying whether the VideoPort is the sync master of the VGA (the vsync of the VGA is controlled by the VideoPort).

HRESULT GetVPSyncMaster(
BOOL bVPSyncMaster
) PURE;

Parameters
bVPSyncMaster
[out] A flag specifying whether the video port controls the vertical synchronization of the VGA. TRUE if the port controls the monitor's synchronization; otherwise, FALSE.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.

IVPNotify2::SetVPSyncMaster

IVPNotify2 Interface

Sets the flag specifying the VideoPort as a sync master of the VGA (the vsync of the VGA is controlled by the VideoPort).

HRESULT GetVPSyncMaster(
BOOL bVPSyncMaster
) PURE;

Parameters
bVPSyncMaster
[in] A flag specifying whether the video port controls the vertical synchronization of the VGA. TRUE if the port controls the monitor's synchronization; otherwise, FALSE.
Return Values

Returns an HRESULT value that depends on the implementation of the interface.


DirectShow C++ Class Library

This section contains reference entries for all the DirectShow C++ classes, their data members, and their methods.

Introduction to the DirectShow C++ Class Library

CAggDirectDraw Class

CAggDrawSurface Class

CAMEvent Class

CAMMsgEvent Class

CAMSchedule Class

CAMThread Class

CAutoLock Class

CBaseAllocator Class

CBaseBasicVideo Class

CBaseControlVideo Class

CBaseControlWindow Class

CBaseDispatch Class

CBaseFilter Class

CBaseInputPin Class

CBaseList Class

CBaseMediaFilter Class

CBaseObject Class

CBaseOutputPin Class

CBasePin Class

CBasePropertyPage Class

CBaseReferenceClock Class

CBaseRenderer Class

CBaseStreamControl Class

CBaseVideoRenderer Class

CBaseVideoWindow Class

CBaseWindow Class

CBasicAudio Class

CCmdQueue Class

CCritSec Class

CDeferredCommand Class

CDisp Class

CDispBasic

CDispParams Class

CDrawImage Class

CEnumMediaTypes Class

CEnumPins Class

CFactoryTemplate Class

CGenericList Class

CGuidNameList Class

CImageAllocator Class

CImageDisplay Class

CImagePalette Class

CImageSample Class

CLoadDirectDraw Class

CMediaControl Class

CMediaEvent Class

CMediaPosition Class

CMediaSample Class

CMediaType Class

CMemAllocator Class

CMsg Class

CMsgThread Class

COARefTime Class

COutputQueue Class

CPersistStream Class

CPosPassThru Class

CPullPin Class

CQueue Class

CRefTime Class

CRenderedInputPin Class

CRendererInputPin Class

CRendererPosPassThru Class

CSource Class

CSourcePosition Class

CSourceSeeking Class

CSourceStream Class

CSystemClock Class

CTransformFilter Class

CTransformInputPin Class

CTransformOutputPin Class

CTransInPlaceFilter Class

CTransInPlaceInputPin Class

CTransInPlaceOutputPin Class

CUnknown Class

CVideoTransformFilter Class

FOURCCMap Class


Introduction to the DirectShow C++ Class Library

This article provides a general description of the Microsoft® DirectShow™ class library, the relationship of the base classes to the DirectShow Component Object Model (COM) interfaces that they implement, and describes the utility classes that are not directly associated with interfaces. This article does not provide low-level descriptions of each class, nor does it provide specific instructions on how to use them to build a filter or run the filter graph manager.

The DirectShow C++ class library can help you implement the required interfaces on filters that you write. Most base classes correspond directly to interfaces, while other utility classes allow integration of Microsoft Win32® functionality, such as critical sections and thread management.

Contents of this article:

  • Base Classes
    • CBaseObject and CUnknown Classes
    • Base Classes that Implement Interfaces
      • Filter Base Classes
      • Pin Base Classes
      • Enumerator Base Classes
      • Transport Base Classes
      • Media Control and Positioning Classes
      • Clock Base Classes
  • Utility Classes
    • Win32 Classes
    • List and Queue Classes
    • Multimedia Data Type Classes
    • COM Classes
    • Debugging Classes

Base Classes

Most of the base classes in the DirectShow class library implement DirectShow COM interfaces. These classes produce C++ objects that provide an IUnknown interface so external components can access the interfaces the objects support.

CBaseObject and CUnknown Classes

The CBaseObject class is the root of all base classes. It exists primarily to provide debugging assistance by keeping a count of all DirectShow objects that are active. All derived base class constructors provide a debugging object name as the first parameter and call the CBaseObject constructor. You can view the debugging object name sent to this base class on a debugging monitor.

CUnknown class hierarchy

All DirectShow classes that implement interfaces derive from a base class called CUnknown, which is derived from CBaseObject. CUnknown implements the INonDelegatingUnknown interface which, like the IUnknown interface, provides methods to request an interface, and to add or release references to that interface.

Why are there two interfaces that implement the services of IUnknown? Because of aggregation. Aggregation is the COM term for the combining of more than one object into a single larger object. Although filter graph objects, such as filters and pins, are rarely aggregated, the design is available for future extensibility and also for implementing plug-in distributors (PID), which are objects that are aggregated with the filter graph manager. In an aggregated object, the outer object (the one containing the other objects) uses the IUnknown interface to communicate outside the object. The IUnknown interface on the outer object passes out references to the IUnknown interfaces of its internal objects. That is, when an application calls the IUnknown interface on the outer object and asks for the interface belonging to one of its internal objects, the outer object calls the IUnknown interface of the internal object to retrieve the requested interface.

Because the internal objects must delegate IUnknown interfaces to the IUnknown of the outer object, the IUnknown interface of the internal object should not be accessed privately (that is, without going through the outer object's IUnknown interface). The internal object's IUnknown is reserved exclusively for communicating through the outer object. However, it is possible that objects will want to connect to other objects privately, without knowledge of the outer object. For example, pins on filters are likely to need to query interfaces on pins of other objects privately.

The INonDelegatingUnknown interface provides direct, private access to interfaces, regardless of whether or not the object is aggregated. Direct access is important in most of the communication between the DirectShow objects such as pins, allocators, and filters, and is the default method of communication. In fact, the base classes implement the IUnknown interface on nonaggregated objects (which includes almost every object in the filter graph) to call the nondelegating interface directly.

Base Classes that Implement Interfaces

The majority of classes in the DirectShow class library implement COM interfaces and can be categorized as follows:

  • Filter base classes implement the IBaseFilter interface, and include CBaseFilter and classes derived from it.
  • Pin classes implement the IPin interface, and include CBasePin and derived classes.
  • Enumerator classes include CEnumPins and CEnumMediaTypes.
  • Memory classes include CMediaSample, CBaseAllocator, CMemAllocator, and their derived classes.
  • Control and position classes include CBaseFilter, CMediaPosition, CMediaControl, CBaseMediaFilter, CSourceSeeking, and CBaseStreamControl.

Filter Base Classes

The DirectShow stream architecture is based on filters and pins. Filters communicate with the filter graph manager and with the pins on the filter. Pins connect filters and handle transporting the data down the stream.

Hierarchy of filter base classes

CBaseFilter is the base class for all filter classes. It implements the IBaseFilter interface, which specifies methods that allow the filter graph manager to create and enumerate pins, retrieve filter information, and notify the filter that it has been added to a filter graph. CBaseFilter also implements the IMediaFilter interface (from which IBaseFilter derives) to allow the filter to receive run, pause, and stop commands from the filter graph manager. This base class adds member functions to retrieve the pin count, retrieve pointers to individual pins, and retrieve the pin version.

The CBaseMediaFilter class also implements the IMediaFilter interface. However, because IMediaFilter is also implemented by CBaseFilter, this class is seldom used except to write a plug-in distributor (PID).

Several classes are derived directly from CBaseFilter. Each of these classes provides a base class for implementing a specific type of filter. These include:

  • CSource, a base class for source filters.
  • CTransformFilter, a base class for transform filters.
  • CBaseRenderer, a base class for renderer filters.

The CSource filter class works in conjunction with the CSourceStream pin class to help create a source filter. Most of the work is done in the pin class, and CSource adds pin creation and deletion member functions. The CSourcePosition class implements a source filter.

The CTransformFilter class implements a transform filter. Derive your transform class from CTransformFilter if you want to make a copy of the data. The CTransInPlaceFilter class, derived from CTransformFilter, allows in-place transforms that do not copy the data. These transform filter classes work in conjunction with similarly named pin classes (for example, CTransformOutputPin and CTransformInputPin). Most member functions in the pin classes are implemented to call member functions in the transform filter class, so typically you need only to derive your filter from the filter class and override a few member functions to implement a transform filter.

CTransformFilter adds several member functions to those inherited from CBaseFilter. Some of these are pure virtual member functions that the derived class must override. One example is the CTransformFilter::Transform member function, which is called when the input pin receives a sample. This member function provides the core of the transform functionality. Other member functions to be overridden also involve implementations that are specific to the derived class, such as verifying media types on pins and allocating the correct amount of memory. Additionally, several CTransformFilter member functions are called at various points in the connection or streaming process; the derived class can override these to handle requirements such as adding or releasing references to interfaces.

The CVideoTransformFilter class derives from the CTransformFilter class and is used as a base class for filters that can affect the quality of a rendered video by dropping frames when the video renderer sends quality-control messages. This class is primarily used by video decompressors in the DirectShow run time.

The CBaseRenderer class and its derived class, CBaseVideoRenderer, are the base filter classes that implement a video renderer filter. The video renderer filter used in DirectShow is derived from CBaseVideoRenderer. There are other renderer classes that work in conjunction with these classes but are not derived from CBaseFilter. These classes are:

  • CRendererInputPin
  • CBaseControlVideo and its base class CBaseBasicVideo
  • CBaseControlWindow, and its base classes CBaseVideoWindow and CBaseWindow
  • CAggDirectDraw
  • CAggDrawSurface

The following illustration shows all the classes that support renderers that are not derived from either CBaseFilter or CBasePin.

Hierarchy of classes that support renderers that aren't derived from CBaseFilter or CBasePin

Pin Base Classes

Pins have a greater share of the work than filters. A pin must expose methods so that the filter graph manager can connect it with a pin on another filter. Pins also expose methods so that connected pins can negotiate what media type they will pass between them, and which pin will provide the shared memory allocator for transporting the media sample. Additionally, the output pin is responsible for passing each media sample to its connected input pin; the input pin is responsible for receiving it. Finally, pins must support interfaces so that quality-control messages and position information can be passed through the stream from pin to pin.

The following illustration shows the pin classes. All pin classes are derived from CBasePin, a base class derived from CUnknown.

Hierarchy of pin base classes

CBasePin implements the IPin interface. The IPin interface specifies methods for connecting to other pins, negotiating the media type to be used with the connected pin, querying internal connections on the pin, and informing the pin of stream activity.

Besides implementing the IPin methods, CBasePin also implements IQualityControl methods so that quality-control messages can be passed through the filter graph from one pin to the next. Quality-control messages allow a filter, such as a renderer, to request another filter to adjust its sample rate. Typically, quality-control messages travel upstream from renderer to source filter. However, in cases such as a video capture filter, the source filter (for example, a VCR reader) can send quality-control messages downstream to the renderer filter to adjust its rate.

The CBasePin class provides several virtual member functions that can be overridden to provide handling of the connection, media type negotiation, and disconnection processes. Two base classes derive from CBasePin to provide default handling for many of these tasks:

  • CBaseOutputPin implements an output pin.
  • CBaseInputPin implements an input pin.

CBaseOutputPin is the base class for the CTransformOutputPin and CSourceStream classes. Likewise, CBaseInputPin is the base class for the CTransformInputPin class. Before looking at these derived base pin classes, it is helpful to understand the basic model the CBaseOutputPin and CBaseInputPin classes use.

In the connection and transport model used by two pins, the input pin supports the IMemInputPin interface so that it can receive a media sample. The CBaseInputPin class implements the IMemInputPin interface. Also, one of the two pins must supply a shared memory allocator object, which is an object that contains the IMemAllocator interface that generates media sample objects passed between pins. An IMemInputPin method, implemented by the CBaseInputPin class, supplies this allocator object, implemented by the CMemAllocator class. The connected output pin also has the option of supplying its own allocator; if this is the case, it notifies the input pin (through another IMemInputPin method) of the final decision of which allocator is used.

The CBaseOutputPin class provides extra member functions to set the size and count of samples in the allocator, retrieve a media sample from the allocator, deliver that media sample to the connected input pin, and deliver end-of-stream and end-flush messages downstream. It also implements many of the IPin methods.

CPullPin is a class that is used on the input pin of a parser filter. It is derived from the CAMThread class as shown in the following illustration.

CPullPin class hierarchy

A parser filter pulls information from the disk, using the asynchronous file reader filter, or from the Internet, using the URL moniker filter. CPullPin works with the IAsyncReader interface, which is implemented on the source reader filter upstream. CPullPin starts the thread, pulls data from the upstream filter, and then pushes the data downstream. That is, it can simply call its own IMemInputPin::Receive method after pulling the sample from the source (or perform the equivalent routines elsewhere).

Enumerator Base Classes

An enumerator is an interface that provides methods for traversing a list of elements. Enumerators are used in COM programming, and the DirectShow model follows the COM model in enumerating objects. Two enumerator classes are provided in the class library: CEnumPins, which implements the IEnumPins interfaces, and CEnumMediaTypes, which implements the IEnumMediaTypes interface. Two other DirectShow enumerator interfaces, IEnumFilters and IEnumRegFilters, are not represented by base classes because they are implemented only by the filter graph manager.

Hierarchy of enumerator base classes

The CEnumPins class creates an enumerator when the IBaseFilter::EnumPins method is called. The enumerator returned by this method is a pointer to the IEnumPins interface, which is implemented by the CEnumPins class. The CEnumPins member functions can then be called to retrieve pointers to each of the pins on the filter, which this enumerator accomplishes by calling the CBaseFilter::GetPin member function on the filter. The filter must override the base class CBaseFilter::GetPin member function to supply the enumerator with the next pin in the list each time it is called.

The CEnumMediaTypes class creates an enumerator when the IPin::EnumMediaTypes method is called. Pins store a list of the media types that they support. During negotiation of the media type, one pin typically calls the EnumMediaTypes method on its connected pin, retrieves the enumerator, and uses it to select a media type. Both of these enumerator classes support the Next, Skip, Reset, and Clone methods familiar to COM programmers. The media type enumerators call the CBasePin::GetMediaType member function, which must be overridden by the derived pin class, to return the next media type in a list of media types accepted by the pin.

Enumerators operate as threads, and must have synchronized access to the pin media type list. For this reason, the classes that implement enumerators inherit (through multiple inheritance) from the CCritSec class, which provides critical section management. For more information about the CCritSec class, see Win32 Classes.

Transport Base Classes

Transport classes share memory between pins and pass media samples using that memory. DirectShow provides four classes to help implement shared memory transports:

  • CBaseAllocator
  • CMemAllocator
  • CMediaSample
  • CImageSample

CBaseAllocator is a class that provides member functions to implement the IMemAllocator interface, as shown in the following illustration.

Hierarchy of transport base classes

The IMemAllocator interface on the input pin specifies methods to set the number and size of the buffers to allocate, allocates that memory, frees that memory, and returns a single buffer that contains an IMediaSample interface. The output pin connected to the input pin calls the IMemAllocator methods. CBaseAllocator provides the member functions Alloc and Free that are called from the Commit and Decommit methods. Derived classes override the Alloc and Free member functions to provide their own routines to allocate and free memory.

Because CBaseAllocator performs very little implementation by itself, most pins use the CMemAllocator class, which is derived from CBaseAllocator. CMemAllocator overrides the CBaseAllocator::Free member function to provide allocation of media samples based on system memory. It provides its own member function, called ReallyFree, to be called when the allocator is finally released.

CMediaSample is a class that contains the media sample data and also provides member functions to access properties on the media sample, such as data type or beginning and ending time stamps. This class implements the IMediaSample interface, which provides the method specification. CImageSample derives from CMediaSample and is used by the video renderer when the renderer's allocator is being used. It uses all the CMediaSample interface methods and adds two methods to set and retrieve the DIBSECTION information. This makes it easy for the renderer to cast the CMediaSample pointer it receives from an upstream filter to a CImageSample pointer, and obtain a handle to the bitmap of the video frame.

Media Control and Positioning Classes

Media control interfaces pass commands such as Run, Stop, or Pause from an application through the filter graph manager to the individual filters. From the filter's perspective, the only control interface necessary is IMediaFilter, which exposes methods to accept and implement these commands. The CBaseFilter class implements this interface. All other interfaces that expose media control methods are handled by the filter graph manager and are therefore already implemented. Although a CMediaControl class exists and implements the IMediaControl interface, it is not often used because the filter graph manager is responsible for this functionality. The following illustration shows the relationship between these classes and interfaces.

Hierarchy of media control and positioning base classes

Media positioning interfaces start the media stream at a specified position, play the stream for a specified period of time, or change the rate of the media stream. The IMediaPosition interface is the primary interface supporting this functionality. The CMediaPosition class implements this interface and serves as a base class for two other classes: CPosPassThru and CSourcePosition.

Typically, the filter graph manager calls the IMediaPosition interface on the renderer filters when it wants to position the media stream. The renderer acknowledges the sample times that it will be expected to display and then passes the media positioning data upstream, destined for a seekable filter, such as a source file filter, that can provide the properly positioned source stream. To pass that information upstream, output pins must be able to receive the positioning information.

The CPosPassThru class implements the IMediaPosition interface and the IMediaSeeking interface on the output pins of filters and, for the most part, does nothing but call the corresponding interface on the output pin of the next upstream filter, thereby passing through the positioning data. IMediaSeeking is different than IMediaPosition in that it allows the media stream to be seeked to units other than time, such as frames, samples, or indexed fields in an MPEG format. The CRendererPosPassThru class, implemented on a video renderer, sets the start and end reference times on individual samples, so that samples can be queried at any time for this information. This is helpful when dealing with seeking using IMediaSeeking, which seeks to media time, and does not keep track of the sample's reference time.

The reason for serially informing every filter in the graph of the new position is to allow filters that might be concerned with media positioning to be prepared for the new position. Certain stream splitters, for example, might be splitting off streams with media positions relative to the main media stream. This is why the filter graph manager does not simply call the source filter's IMediaPosition or IMediaSeeking interface directly.

CSourcePosition is the class that helps the source filter implement its IMediaPosition interface.

The CSourceSeeking class helps the source filter implement its IMediaSeeking interface. This class enables a source filter to handle calls that change the start and stop positions in the media stream, and the playback rate.

The CBaseStreamControl class helps the source filter implement its IAMStreamControl interface. This class is used primarily by capture filters. The following illustration shows the relationship between CBaseStreamControl and the interfaces from which it inherits.

Hierarchy of CBaseStreamControl base class

Clock Base Classes

DirectShow provides two classes, CBaseReferenceClock and CSystemClock to help implement clocks in the filter graph. The following illustration shows the relationship between these classes and the interfaces they implement.

Hierarchy of clock base classes

CBaseReferenceClock implements IReferenceClock, and so provides the ability to return the correct reference time when requested, and to advise registered objects of specific times or time intervals through event notification and semaphores.

CSystemClock implements a system clock that provides time information and timing signals to an application. It uses the CBaseReferenceClock base class to provide most of that functionality, overriding the actual time calls.

Utility Classes

The DirectShow SDK includes several utility classes that provide C++ class encapsulation of many of the required Win32 functions, multimedia data structures, and object list and queue manipulation. These classes are briefly described in this section.

Win32 Classes

DirectShow implements several classes to handle Win32 threads, events, and critical sections. These include the following classes.
CAMEvent
CCritSec
CAutoLock
CAMThread
CMsgThread
CMsg

The following diagram illustrates these classes.

Hierarchy of Win32 utility classes

CAMEvent handles a Win32 event as a C++ object. The methods in this class allow events to be put into the signaled state or reset to a nonsignaled state, and also allow a caller to block until an event is signaled. Events can also be cast to handles and passed to the Win32 WaitForMultipleObjects function.

CCritSec handles a Win32 critical section as a C++ object to provide intraprocess synchronization. Methods of this class allow you to create, lock, and unlock a critical section.

CAutoLock holds a critical section (a CCritSec object) for the scope of a block or function. The critical section is locked in the constructor and unlocked in the destructor.

CAMThread provides an abstract worker thread class enabling creation, synchronization, and communication with a worker thread.

CMsgThread provides support for a worker thread to which requests can be posted asynchronously instead of being sent directly. Messages, in the form of a CMsg object, can be posted to a CMsgThread object.

CMsg creates an object containing a message to be passed to a CMsgThread object.

List and Queue Classes

DirectShow implements the CBaseList, CGenericList, and COutputQueue classes for handling lists and queues as illustrated in the following diagram.

Hierarchy of list and queue utility classes

CBaseList represents a linked list data structure of typeless pointers to objects derived from CBaseObject.

CGenericList implements a template class derived from CBaseList that calls CBaseList member functions and adds type checking for the type specified in the template.

COutputQueue supports the queuing of media samples from the output pin of a filter. The output pin calls member functions of this class instead of calling methods on the connected input pin to receive the media sample. The output pin is then free to continue without blocking, while the COutputQueue class handles the passing of the media samples downstream.

Multimedia Data Type Classes

DirectShow implements the CMediaType, CRefTime, and FOURCCMap multimedia data type classes as shown in the following illustration.

Hierarchy of multimedia data type classes

CMediaType provides a C++ class object containing the media type data structure and methods that provide access to each of the members of the structure.

CRefTime provides a C++ class object containing the methods used to access the reference time, and operators used to perform Boolean tests or arithmetical operations on two CRefTime objects.

FOURCCMap provides conversion between the older-style FOURCC media tags used to identify and register media types and the GUID media subtypes used by DirectShow.

COM Classes

COM interface classes in DirectShow fall into two groups: object creation and interface implementation. Class factory classes are provided for object creation, and other classes are provided to implement existing COM interfaces.

The COM utility classes include the following.
CClassFactory
CFactoryTemplate
CPersistStream
CBasePropertyPage

The following illustration shows the relationship between the COM classes and the interfaces they implement.

Hierarchy of COM utility classes CClassFactory and CFactoryTemplate are implemented by the base classes to handle automatic instantiation of filters, pins, and other DirectShow COM objects. These classes provide a scaffolding for object construction which wraps the actual COM elements required to construct an object. CPersistStream and CBasePropertyPage help with implementing COM persistent storage and property page interfaces.

CClassFactory, located in dllentry.cpp, inherits from CBaseObject and implements the COM IClassFactory interface. This interface is used by CoCreateInstance, which instantiates a COM object by calling IClassFactory::CreateInstance, which, in turn, calls the static CreateInstance member function in your derived class.

The base classes use CFactoryTemplate to provide CClassFactory with a template containing the CLSID of your object and a pointer to the static CreateInstance function for your object class.

CPersistStream implements COM IPersistStream for the storage and retrieval of filter properties in a saved filter graph. This enables a stored filter graph to have filters set to predefined property values. This class also provides a special member function to handle versioning of data in a stream.

CBasePropertyPage implements the COM IPropertyPage interface, which provides a framework for a property page associated with a filter.

Debugging Classes

DirectShow provides many debugging functions and macros as described in the Debugging reference section. It also includes three classes that aid in debugging filter development:
CDispBasic
CDisp
CGuidNameList

The following diagram illustrates these classes.

Hierarchy of debugging utility classes

CDispBasic converts the m_PString data member to the proper string size.

CDisp provides a constructor that sets the CDispBasic class's m_PString data member to a string describing some relevant debugging information about the object used as a parameter to the constructor. For example, when constructed with an IPin pointer, m_PString returns the name of the pin; when constructed with a CLSID, m_PString returns a string representation of it, and so on. The class also provides an LPCTSTR cast operator that returns the value of m_PString, so the class can simply be cast as an LPCTSTR value to return the string when constructed.

CGuidNameList implements an array of globally unique identifier (GUID) names in the Uuids.h include file. This enables you to retrieve the GUID name for a media type, for example.


CAggDirectDraw Class

CAggDirectDraw class hierarchy

This class aggregates an IDirectDraw interface. Although DirectDraw® interfaces (IDirectDraw and IDirectDrawSurface) potentially have the ability to be aggregated, this feature is not yet implemented. Various parts of Microsoft® DirectShow™ require aggregation of the DirectDraw interfaces. In particular, the video renderer passes out media samples that expose IDirectDraw and IDirectDrawSurface. This class and the CAggDrawSurface class republish the methods of the DirectDraw class so that they can be aggregated.

Each member function in this class, with the exception of the constructor, SetDirectDraw, and NonDelegatingQueryInterface, simply calls the corresponding method on the IDirectDraw interface with the parameters passed to it.

Protected Data Members
Name | Description
m_pDirectDraw | DirectDraw object.

Member Functions
Name | Description
CAggDirectDraw | Constructs a CAggDirectDraw object.
SetDirectDraw | Sets the DirectDraw object to be aggregated by this class.

Overridable Member Functions
Name | Description
NonDelegatingQueryInterface | Returns an interface and increments the reference count.

Implemented IDirectDraw Methods
Name | Description
Compact | Moves all the pieces of surface memory on the video card to a contiguous block to make the largest chunk of free memory available.
CreateClipper | Creates a DirectDrawClipper object.
CreatePalette | Creates a DirectDrawPalette object for this DirectDraw object.
CreateSurface | Creates a DirectDrawSurface object for this DirectDraw object.
DuplicateSurface | Duplicates a DirectDrawSurface object.
EnumDisplayModes | Enumerates all the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description.
EnumSurfaces | Enumerates all the existing or possible surfaces that meet the search criterion specified.
FlipToGDISurface | Makes the surface that GDI writes to the primary surface.
GetCaps | Fills in the raw (not remaining) capabilities of the device driver (the hardware) and/or the Hardware Emulation Layer (HEL).
GetDisplayMode | Returns the current display mode.
GetFourCCCodes | Gets the FOURCC codes supported by the DirectDraw object.
GetGDISurface | Returns the DirectDrawSurface object that currently represents the surface memory that GDI treats as the primary surface.
GetMonitorFrequency | Points to a DirectDrawSurface pointer that will be made to point to the DirectDrawSurface object currently controlling GDI's primary surface memory.
GetScanLine | Returns the scan line that the monitor is currently updating to the display.
GetVerticalBlankStatus | Returns the status of the vertical blank.
Initialize | Initializes the DirectDraw object.
RestoreDisplayMode | Resets the mode of the display device hardware for the primary surface to what it was before the CAggDirectDraw::SetDisplayMode member function was called.
SetCooperativeLevel | Determines the top-level behavior of the application.
SetDisplayMode | Sets the mode of the display device hardware.
WaitForVerticalBlank | Helps the caller synchronize itself with the vertical blank interval.

CAggDirectDraw::CAggDirectDraw

CAggDirectDraw Class

Constructs a CAggDirectDraw object.

CAggDirectDraw(
TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object; used for debugging purposes.
pUnk
Pointer to the owner of this object. If non-NULL, IUnknown calls are delegated to this object.
Return Values

No return value.

Remarks

This member function calls the CUnknown::CUnknown base class constructor and sets the m_pDirectDraw member variable to NULL.

CAggDirectDraw::NonDelegatingQueryInterface

CAggDirectDraw Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function provides an implementation of the INonDelegatingUnknown::NonDelegatingQueryInterface method. By default it passes out references to IDirectDraw and then calls the CUnknown::NonDelegatingQueryInterface member function for base class interface references. Override this class to return interfaces added in the derived class.

CAggDirectDraw::SetDirectDraw

CAggDirectDraw Class

Sets the DirectDraw object to be aggregated by this class.

void SetDirectDraw(
LPDIRECTDRAW pDirectDraw
);

Parameters
pDirectDraw
IDirectDraw object to be aggregated.
Return Values

No return value.

Remarks

This member function sets the m_pDirectDraw data member to the pDirectDraw parameter.


CAggDrawSurface Class

CAggDrawSurface class hierarchy

This class aggregates an IDirectDrawSurface interface. Although DirectDraw® interfaces (IDirectDraw and IDirectDrawSurface) potentially have the ability to be aggregated, this feature is not yet implemented. Various parts of Microsoft® DirectShow™ require aggregation of the DirectDraw interfaces. In particular, the video renderer passes out media samples that expose IDirectDraw and IDirectDrawSurface. This class and the CAggDirectDraw class republish the methods of the DirectDraw class so that they can be aggregated.

Each member function in this class, with the exception of the constructor, SetDirectDrawSurface, and NonDelegatingQueryInterface, simply calls the corresponding method on the IDirectDrawSurface interface with the parameters passed to it.

Protected Data Members
Name | Description
m_pDirectDrawSurface | DirectDraw surface.

Member Functions
Name | Description
CAggDrawSurface | Constructs a CAggDrawSurface object.
SetDirectDrawSurface | Sets the DirectDraw object to be aggregated by this class. This must be called before any of the IDirectDrawSurface interface methods can be called.

Overridable Member Functions
Name | Description
NonDelegatingQueryInterface | Returns an interface and increments the reference count.

Implemented IDirectDrawSurface Methods
Name | Description
AddAttachedSurface | Attaches a surface to another surface. Examples of possible attachments include z-buffers, alpha channels, and back buffers.
AddOverlayDirtyRect | Builds up the list of the rectangles that must be updated the next time the UpdateOverlayDisplay member function is called.
Blt | Performs a bit-block transfer.
BltBatch | Performs a sequence of CAggDrawSurface::Blt operations from several sources to a single destination.
BltFast | Performs a source copy bit-block transfer or transparent bit-block transfer using a source or destination color key.
DeleteAttachedSurface | Detaches two attached surfaces.
EnumAttachedSurfaces | Enumerates all the surfaces attached to a given surface.
EnumOverlayZOrders | Enumerates the overlays on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.
Flip | Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the FRONTBUFFER surface.
GetAttachedSurface | Finds the attached surface that has the specified capabilities.
GetBltStatus | Returns the status of a bit block transfer.
GetCaps | Returns the capabilities of the surface.
GetClipper | Returns the DirectDrawClipper object associated with this surface.
GetColorKey | Returns the color key value for the DirectDrawSurface object.
GetDC | Creates a GDI-compatible hDC for the surface.
GetFlipStatus | Returns OK if the surface that it is called on has finished its flipping process; otherwise, returns DDERR_WASSTILLDRAWING.
GetOverlayPosition | Returns the display coordinates of the surface, given a visible, active overlay surface (DDSCAPS_OVERLAY set).
GetPalette | Returns the DirectDrawPalette structure associated with this surface.
GetPixelFormat | Returns the color and pixel format of the surface.
GetSurfaceDesc | Returns a DDSURFACEDESC structure describing the surface in its current condition.
Initialize | Initializes a DirectDrawSurface object.
IsLost | Determines if the surface memory associated with a DirectDrawSurface object has been freed.
Lock | Obtains a valid pointer to the surface memory.
ReleaseDC | Releases a GDI-compatible hDC previously obtained through CAggDrawSurface::GetDC.
Restore | Restores a surface that has been "lost." The surface memory associated with the DirectDrawSurface object has been freed.
SetClipper | Attaches a DirectDrawClipper object to a DirectDrawSurface object.
SetColorKey | Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per-surface basis.
SetOverlayPosition | Changes the display coordinates of an overlay surface.
SetPalette | Attaches the DirectDrawPalette object specified to a DirectDrawSurface.
Unlock | Notifies DirectDraw that the direct surface manipulations are complete.
UpdateOverlay | Repositions and/or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY bit set.
UpdateOverlayDisplay | Repaints the rectangles in the dirty rectangle lists of all active overlays.
UpdateOverlayZOrder | Sets an overlay's z-order. The z-order determines which overlay should be occluded when multiple overlays are displayed simultaneously.

CAggDrawSurface::CAggDrawSurface

CAggDrawSurface Class

Creates a CAggDrawSurface object.

CAggDrawSurface(
TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object; used for debugging purposes.
pUnk
Pointer to the owner of this object. If non-NULL, IUnknown interface calls are delegated to this object.
Return Values

No return value.

Remarks

This member function calls the CUnknown::CUnknown base class constructor and sets the m_pDirectDrawSurface member variable to NULL.

CAggDrawSurface::NonDelegatingQueryInterface

CAggDrawSurface Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function provides an implementation of the INonDelegatingUnknown::NonDelegatingQueryInterface method. By default it passes out references to IDirectDrawSurface and then calls the CUnknown::NonDelegatingQueryInterface member function for base class interface references. Override this class to return interfaces added in the derived class.

CAggDrawSurface::SetDirectDrawSurface

CAggDrawSurface Class

Called by the owner of this aggregation object to set the actual DirectDraw surface it is aggregating upon.

void SetDirectDrawSurface(
LPDIRECTDRAWSURFACE pDirectDrawSurface
);

Parameters
pDirectDrawSurface
DirectDrawSurface to be set.
Return Values

No return value.

Remarks

This member function must be called before any of the IDirectDrawSurface interface methods can be called.


CAMEvent Class

CAMEvent class hierarchy

The CAMEvent class is an event object that can be set and waited on to provide interthread synchronization. This is currently implemented by using the Microsoft® Win32® Event application programming interfaces (APIs).

Events can be created as manual-reset or automatic-reset, and will always be created as not set (nonsignaled state). They can also be cast to handles so as to be passed to the Win32 WaitForMultipleObjects function.

Protected Data Members
Name | Description
m_hEvent | Microsoft Win32 event handle.

Member Functions
Name | Description
CAMEvent | Constructs a CAMEvent object.
Check | Returns TRUE if the event is currently set, but does not block.
Reset | Forces the event into a nonsignaled state.
Set | Puts the event into a signaled state.
Wait | Blocks until the event is signaled, or until an optional time-out occurs.
operator HANDLE | Gets the HANDLE object.

CAMEvent::CAMEvent

CAMEvent Class

Constructs a CAMEvent object.

CAMEvent(
BOOL fManualReset = FALSE
);

Parameters
fManualReset
If this value is FALSE, the event is reset when the CAMEvent::Wait member function completes. If this parameter is TRUE, you can set the event by calling the CAMEvent::Set member function and then reset it by calling the CAMEvent::Reset member function.
Return Values

No return value.

CAMEvent::Check

CAMEvent Class

Returns TRUE if the event is currently set, but does not block.

BOOL Check(void);

Remarks

For events that are not manual-reset events, this member function causes the event to enter a nonsignaled state.

CAMEvent::Reset

CAMEvent Class

Forces the event into a nonsignaled state.

void Reset(void);

Return Values

No return value.

CAMEvent::Set

CAMEvent Class

Puts the event into a signaled state.

void Set(void);

Return Values

No return value.

Remarks

If the event is not a manual-reset event and there is at least one thread blocked on this event, the thread is released and the event remains in a nonsignaled state. If the event is not a manual-reset event and no threads are blocked on the event, it is set to a signaled state.

If the event is not a manual-reset event, it is set to a signaled state and all the threads blocked on this event are released.

CAMEvent::Wait

CAMEvent Class

Blocks until the event is signaled, or until the indicated time-out occurs.

BOOL Wait(
DWORD dwTimeout
);

Parameters
dwTimeout
Optional time-out value, represented in milliseconds. The default is INFINITE.
Return Values

Returns TRUE if the event becomes signaled; otherwise, returns FALSE.

Remarks

For events that are not manual-reset events, the action completing the CAMEvent::Wait member function causes the event to enter a nonsignaled state until the CAMEvent::Set member function is called.

CAMEvent::operator HANDLE

CAMEvent Class

Gets the HANDLE object associated with this CAMEvent object.

operator HANDLE () const;
Return Values

Returns the Microsoft Win32 event HANDLE.


CAMMsgEvent Class

CAMMsgEvent class hierarchy

The CAMMsgEvent class is a wrapper for event objects that do message processing. This class adds one method to the CAMEvent object to allow sent messages to be processed while waiting.

Member Functions
Name | Description
WaitMsg | Allows sent messages to be processed while waiting for an event to be signaled or for the indicated time-out to occur.

CAMMsgEvent::WaitMsg

CAMMsgEvent Class

Allows sent messages to be processed while waiting for an event to be signaled or for the indicated time-out to occur.

BOOL WaitMsg(
DWORD dwTimeOut
);

Parameters
dwTimeOut
Optional time-out value, represented in milliseconds. The default is INFINITE.
Return Values

Returns TRUE if the event is signaled, or FALSE if the time-out occurred.

Remarks

Call CAMMsgEvent::WaitMsg rather than CAMEvent::Wait if you want to block on a time-out or a signaled event and continue to process sent messages. If you do not process messages and another thread sends you a message, deadlock could occur. For example, if you create a thread by way of the Win32 CreateThread function and then block until the thread can initialize, deadlock will occur if the thread sends a message to your window using the Win32 SendMessage function. This is because SendMessage does not return until the message has been processed. CAMMsgEvent::WaitMsg allows SendMessage to return to the caller by using a Win32 PeekMessage loop to do message processing.


CAMSchedule Class

CAMSchedule class hierarchy

The CAMSchedule class relieves clocks from the burden of managing the advise requests. A clock can delegate such management to this class, provided that it calls this class's Advise method when the earliest event should be fired. The application can fetch the time of the earliest event by calling GetNextAdviseTime, or the application can track events by a combination of the times returned by Advise and the event times that the clock adds.

Member Functions
Name | Description
AddAdvisePacket | Creates a new pending notification.
Advise | Requests the scheduler to dispatch all events up to and including the time specified.
CAMSchedule | Constructs a CAMSchedule object.
GetAdviseCount | Returns the number of outstanding events.
GetEvent | Returns the event handle to send if the advise time requires reevaluation.
GetNextAdviseTime | Returns the reference time at which the next advise should be set, or MAX_TIME if no events are scheduled.
Unadvise | Removes a previously established advise link.

CAMSchedule::AddAdvisePacket

CAMSchedule Class

Creates a new pending notification and adds it to the advise notification list.

DWORD AddAdvisePacket(
const REFERENCE_TIME & time1,
const REFERENCE_TIME & time2,
HANDLE hNotify,
BOOL bPeriodic
);

Parameters
time1
Time that the advise should take place.
time2
Period between notifications. (Ignored if bPeriodic is FALSE.)
hNotify
Notification mechanism. Either a semaphore handle (if bPeriodic is TRUE) or an event handle.
bPeriodic
Flag that specifies whether the notification is sent repeatedly, or whether the notification is sent once. This can be one of the following values:
Value | Meaning
TRUE | This is a periodic timer that will fire every time2 units until canceled.
FALSE | This is a one-shot timer.
Return Values

Returns the advise token if successful, or zero if an error occurred.

CAMSchedule::Advise

CAMSchedule Class

Requests the scheduler to dispatch all events up to and including the time specified. This method is expected to be called by a controlling clock specifying the current time, just in time to dispatch the next advise request.

REFERENCE_TIME Advise(
const REFERENCE_TIME & rtTime
);

Parameters
rtTime
Current reference time.
Return Values

Returns the reference time at which the next advise will expire, or MAX_TIME if there are no outstanding events.

Remarks

Clocks can call this method to advise the scheduler of the time. The scheduler will then signal all the events that have expired, and reschedule the periodic ones.

It is not intended that clocks should call this method all the time, rather that clocks will call Advise just one time. The time returned will be invalidated if you start adding extra advises.

CAMSchedule::CAMSchedule

CAMSchedule Class

Constructs a CAMSchedule object.

CAMSchedule(
HANDLE hEvent
);

Parameters
hEvent
Event that CAMSchedule should fire if the advise time needs reevaluating.
Return Values

No return value.

CAMSchedule::GetAdviseCount

CAMSchedule Class

Returns the number of outstanding events.

DWORD GetAdviseCount( );

Return Values

Returns the number of outstanding events.

CAMSchedule::GetEvent

CAMSchedule Class

Retrieves the event handle to set if the advise time requires reevaluation.

HANDLE GetEvent( );

Return Values

Returns a HANDLE to the event to set when this object's advise time requires reevaluation.

CAMSchedule::GetNextAdviseTime

CAMSchedule Class

Checks the time of the next advise.

REFERENCE_TIME GetNextAdviseTime( );

Return Values

Returns the reference time at which the next advise should be set, or MAX_TIME if there are no events scheduled.

CAMSchedule::Unadvise

CAMSchedule Class

Removes a previously established advise link.

HRESULT Unadvise(
DWORD dwAdviseCookie
);

Parameters
dwAdviseToken
Identifier (cookie) of the link that is being reset. This is the value returned by CAMSchedule::AddAdvisePacket.
Return Values

Returns S_OK if successful; otherwise, returns S_FALSE.

Remarks

This member function is modeled after the IReferenceClock::Unadvise method. Call Unadvise to remove the previously established clock advise links.

Unadvise should be called for unexpired single-shot advise requests. Calling Unadvise with the token of an already expired event causes no problems, so applications can choose to always call Unadvise on their single-shot events without fear of problems.


CAMThread Class

CAMThread class hierarchy

CAMThread is an abstract class, a worker thread class that provides creation, synchronization, and communication with a worker thread. The worker thread can be accessed from several client threads. The class provides member functions to create the thread, pass commands to it, and wait for it to exit.

Use a CCritSec object to ensure that only one thread can make a request at a time. Use two CAMEvent objects: one to signal to the worker that a request is outstanding, and the other to signal to the client thread that the request has been completed. A nonblocking CAMThread::CheckRequest member function allows the worker thread to check for new requests while working asynchronously.

Derive from this class to provide your own thread member function. You might also want to provide type-safe signaling member functions that package parameters and return values using the CAMThread::CallWorker member function.

Thread creation is independent of object creation. Create a member variable derived from CAMThread, and then use the member functions to start and stop the thread when needed.

Data Members
Name | Description
m_AccessLock | Critical section object that locks access by client threads.
m_WorkerLock | Critical section object that locks access to shared objects.

Member Functions
Name | Description
CallWorker | Makes a request to the worker thread.
CAMThread | Constructs a CAMThread object.
CheckRequest | Determines if there is an outstanding request. This is a nonblocking member function.
Close | Blocks until the thread has exited and released its resources.
Create | Starts the thread running.
GetRequest | Blocks until the next request is made and then returns a DWORD value.
GetRequestHandle | Returns an event handle.
GetRequestParam | Returns the latest request.
InitialThreadProc | Retrieves a this pointer. Carry out this member function before calling the CAMThread::ThreadProc member function.
Reply | Returns a DWORD value to the requesting thread and releases it, signaling completion of the request.
ThreadExists | Determines whether a thread exists or has exited.
ThreadProc | Indicates a pure virtual member function that is called on the worker thread.

CAMThread::CallWorker

CAMThread Class

Makes a request to the worker thread and blocks for a response.

DWORD CallWorker(
DWORD dw
);

Parameters
dw
Derived class defines the meaning of the parameter.
Return Values

Returns a value that is defined by the derived class.

Remarks

This member function uses a CCritSec object to ensure that only one request is made at a time. It is therefore not valid to call the CAMThread::CallWorker member function from the thread itself or from any member function that is executing in the context of the thread.

CAMThread::CAMThread

CAMThread Class

Constructs a CAMThread object.

CAMThread( );

Return Values

No return value.

Remarks

Creates a CAMThread object but does not create an actual thread. You call the CAMThread::Create member function to create a thread.

CAMThread::CheckRequest

CAMThread Class

Determines if there is an outstanding request. This is a nonblocking member function.

BOOL CheckRequest(
DWORD *pParam
);

Parameters
pParam
Parameter that assumes the value passed by the last call to the CAMThread::CallWorker member function.
Return Values

Returns TRUE if an outstanding request is still active, or FALSE is no request is active.

Remarks

If there is an outstanding request, the requesting thread will block until the CAMThread::GetRequest member function is called. The request remains outstanding (that is, this member function continues to return TRUE) until either the CAMThread::Reply or CAMThread::GetRequest member function is called.

CAMThread::Close

CAMThread Class

Blocks until the thread has exited and released its resources.

void Close(void);

Return Values

No return value.

Remarks

You must instruct the thread to exit by some other means; for example, call the CAMThread::CallWorker member function with a request that is interpreted by the derived class to mean complete and exit.

If the thread is still running when the CAMThread object is destroyed, the CAMThread::Close member function is called internally.

CAMThread::Create

CAMThread Class

Starts the thread running.

BOOL Create(void);

Return Values

Returns TRUE if the thread started successfully, or FALSE if the thread is already running.

Remarks

This member function creates the thread and calls the CAMThread::ThreadProc member function from the derived class.

CAMThread::GetRequest

CAMThread Class

Blocks until the next request is made.

DWORD GetRequest( );

Return Values

Returns a value that is defined by the derived class.

Remarks

This member function blocks the requesting thread until the CAMThread::Reply function is called.

CAMThread::GetRequestHandle

CAMThread Class

Returns an event handle for performance improvements.

HANDLE GetRequestHandle( ) const;

Return Values

Returns an event handle.

Remarks

To use the Microsoft Win32 WaitForMultipleObjects function, you will need this handle in the thread's wait list or the thread will not be responsive.

CAMThread::GetRequestParam

CAMThread Class

Returns the most recent request.

DWORD GetRequestParam( ) const;

Return Values

Returns a DWORD value that indicates the request made previously by the CAMThread::GetRequest member function.

CAMThread::InitialThreadProc

CAMThread Class

Receives a this pointer and calls the CAMThread::ThreadProc member function.

DWORD InitialThreadProc(
LPVOID pv
);

Parameters
pv
The this pointer.
Return Values

Returns the DWORD returned by CAMThread::ThreadProc. This DWORD is not defined by this class.

CAMThread::Reply

CAMThread Class

Returns a DWORD value to the requesting thread and releases it, signaling completion of the request.

void Reply(
DWORD dw
);

Parameters
dw
Value returned by the CAMThread::CallWorker member function on the client side.
Return Values

No return value.

CAMThread::ThreadExists

CAMThread Class

Determines whether the thread has been created and has not yet exited.

BOOL ThreadExists( );

Return Values

Returns TRUE if the thread exists and hasn't exited, or FALSE if the thread doesn't exist.

CAMThread::ThreadProc

CAMThread Class

Overridden member function in which to implement a thread.

virtual DWORD ThreadProc( );

Return Values

The meaning of this return value is not defined by the CAMThread class.

Remarks

The thread calls this member function upon startup. Derived classes must override this member function. When this member function returns, the thread terminates. This member function is protected.


CAutoLock Class

CAutoLock class hierarchy

The CAutoLock class holds a critical section for the scope of a block or function. The constructor locks the critical section and the destructor unlocks it. The object passed to the CAutoLock constructor must be derived from the CCritSec class. Thus, by declaring a CAutoLock object as a local variable in a function, a critical section can be locked without the danger of forgetting to unlock it in some of the code paths: the destructor ensures that upon exit from the function (or the scope of the declaration), the critical section will be unlocked. Member functions in this class are not designed for overriding.

/* Typical usage ensuring object is always unlocked correctly */

HRESULT MyFunc(IMediaSample *pSample)
{
   CAutoLock cObjectLock(m_pMyLock);

   /* Ignore samples passed when inactive */

   if (!m_bActive) {
      return NOERROR;
   }

   /* Add the sample to the pending queue */

   HRESULT hr = m_PendingList.AddTail(pSample);
   if (FAILED(hr)) {
      pSample->Release();
      return hr;
   }
   return NOERROR;
}

Protected Data Members
Name | Description
m_pLock | Critical section for this lock.

Member Functions
Name | Description
CAutoLock | Takes a pointer to a critical section object and locks it.

CAutoLock::CAutoLock

CAutoLock Class

Takes a pointer to a critical section object and locks it.

CAutoLock(
CCritSec * plock
);

Parameters
plock
Pointer to a critical section object.
Return Values

No return value.

Remarks

The critical section is unlocked when the CAutoLock object is destroyed.


CBaseAllocator Class

CBaseAllocator class hierarchy

CBaseAllocator is an abstract base class that implements the basic mechanisms for an allocator with a fixed number of fixed-size buffers. The number of buffers and their size can be changed using the CBaseAllocator::SetProperties member function when an input pin and an output pin negotiate the allocator between them.

The class provides the basic functionality for a memory allocator by implementing the IMemAllocator interface. It provides support for managing a list of CMediaSample objects (or objects derived from this class), including support for the IMemAllocator::Commit and IMemAllocator::Decommit methods, and blocking the IMemAllocator::GetBuffer method.

Any class derived from this class (such as CMemAllocator) must create CMediaSample objects, which this base class does not.

A signaling mechanism employing a semaphore is used so that if there are no samples, a thread can wait until there are samples or until the allocator is decommitted. The m_lFree and m_hSem member variables are used to implement this simple signaling mechanism as follows.

When a thread calls CBaseAllocator::GetBuffer and there are no samples available, m_lWaiting is incremented and the thread calls the Microsoft® Win32® WaitForSingleObject function on the semaphore indicated by m_hSem.

When a sample is freed (by the IUnknown::Release method returning the reference count to zero) or CBaseAllocator::Decommit is called and m_lWaiting is nonzero, the Win32 ReleaseSemaphore function is called on m_hSem with a release count of m_lWaiting, and m_lWaiting is reset to zero.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_bChanged | TRUE if the buffers have changed; otherwise, FALSE.
m_bCommitted | If TRUE, the allocator is in a state in which all IMemAllocator::GetBuffer methods fail. The IMemAllocator::SetProperties method is the only member function permitted to operate in this state.
m_bDecommitInProgress | If TRUE, the decommit process completes upon the return of all media samples. Until the decommit process has completed, any calls to IMemAllocator::GetBuffer return E_OUTOFMEMORY.
m_hSem | Semaphore for signaling.
m_lAlignment | Agreed alignment of the buffer.
m_lAllocated | Number of buffers actually allocated.
m_lCount | Established number of buffers to provide.
m_lFree | List of CMediaSample objects that are currently free (free list).
m_lPrefix | Agreed prefix of the buffer (precedes value returned by IMediaSample::GetPointer).
m_lSize | Size of each buffer.
m_lWaiting | Count of threads waiting for samples.

Member Functions
Name | Description
CBaseAllocator | Constructs a CBaseAllocator object.
NotifySample | Notifies a waiting thread that a sample is available on the free list.
SetWaiting | Increments the m_lWaiting data member to indicate that a thread is waiting for a sample.

Overridable Member Functions
Name | Description
Alloc | Allocates memory, instantiates CMediaSample objects, and adds them to the m_lAllocated and m_lFree data members.
Free | Decommits memory when the last buffer is freed.

Implemented IMemAllocator Methods
Name | Description
Commit | Allocates memory by calling the CBaseAllocator::Alloc member function, which you must override.
Decommit | Releases any resources and enters the inactive state. Any blocking calls to IMemAllocator::GetBuffer should return with an error value, and all further calls to GetBuffer fail when in the inactive state.
GetBuffer | Retrieves a container for a sample.
GetProperties | Determines the size, number, and alignment of blocks.
ReleaseBuffer | Releases the CMediaSample object.
SetProperties | Specifies a desired number of blocks, size of the blocks, and block alignment figure. This method returns the actual values for the same.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Passes out pointers to any interfaces added to the derived filter class.

CBaseAllocator::Alloc

CBaseAllocator Class

Allocates a media sample object.

HRESULT Alloc(void);

Return Values

Returns an HRESULT value.

Remarks

Override this member function to allocate memory, instantiate CMediaSample objects, and add them to the free list represented by the m_lFree data member. The CMemAllocator::Alloc member function is an example of an override of this member function. It calls this member function first to ensure that allocator properties have been set.

This member function is called from the CBaseAllocator::Commit member function when entering the active state. The default implementation returns an error value if the IMemAllocator::SetProperties method has not been called yet, and checks that there are no outstanding buffers.

CBaseAllocator::CBaseAllocator

CBaseAllocator Class

Constructs a CBaseAllocator object.

CBaseAllocator(
TCHAR * pName,
LPUNKNOWN lpUnk,
HRESULT * phr,
BOOL bListSemaphore = TRUE
);

Parameters
pName
Name of the allocator object.
lpUnk
Pointer to LPUNKNOWN.
phr
Pointer to an HRESULT for return values. This is not modified unless this member function fails.
bListSemaphore
If TRUE, the free list in the allocator has a semaphore associated with it. If FALSE, no semaphore is created for the list. Setting this to FALSE can be useful for subclassing CBaseAllocator when the semaphore is not required for blocking. The semaphore is used for the waiting and signaling mechanism.
Return Values

No return value.

CBaseAllocator::Commit

CBaseAllocator Class

Commits the memory for the specified buffers.

HRESULT Commit(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemAllocator::Commit method. The IMemAllocator::SetProperties method must be called before calling this member function. This member function sets m_bCommitted to TRUE and overrides any pending decommit operation. It then calls the CBaseAllocator::Alloc member function to allocate memory (which should be overridden in the derived class to call the base class member function and then allocate the memory). The IMemAllocator::GetBuffer method fails if it is called before calling this member function.

Call CBaseAllocator::Decommit to release memory when done with the buffers.

CBaseAllocator::Decommit

CBaseAllocator Class

Releases the memory for the specified buffers.

HRESULT Decommit(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemAllocator::Decommit method. Any threads waiting in the IMemAllocator::GetBuffer method return with an error after this method is called. The IMemAllocator::GetBuffer method fails if it is called before the IMemAllocator::Commit method or after this method.

See Also

CBaseAllocator::Commit

CBaseAllocator::Free

CBaseAllocator Class

Called to decommit the memory when the last buffer is freed.

virtual void Free(void) PURE;

Return Values

No return value.

Remarks

This member function must be implemented in the derived class. It is called from CBaseAllocator::ReleaseBuffer when a decommit is pending and the allocator has put its last buffer on the free list. It is also called from CBaseAllocator::Decommit.

The CMemAllocator::Free member function is an example of how this can be implemented in the derived class. In this case, it simply returns, because the CMemAllocator class releases memory from its destructor.

This member function is protected.

CBaseAllocator::GetBuffer

CBaseAllocator Class

Retrieves a container for a sample.

HRESULT GetBuffer(
IMediaSample ** ppBuffer,
REFERENCE_TIME * pStartTime,
REFERENCE_TIME * pEndTime,
DWORD dwFlags
);

Parameters
ppBuffer
Pointer to a retrieved media sample buffer.
pStartTime
Either NULL or set to the beginning time of the sample to retrieve.
pEndTime
Either NULL or set to the ending time of the sample to retrieve.
dwFlags
The following flags are supported.
Value | Meaning
AM_GBF_PREVFRAMESKIPPED | The buffer returned will not be filled with data contiguous to any previous data sent.
AM_GBF_NOTASYNCPOINT | Dynamic format changes are not allowed on this buffer because it is not a key frame.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemAllocator::GetBuffer method.

This is a blocking, synchronous call to access the next free buffer (as represented by an IMediaSample interface). Upon return, properties (such as the time and so on) are invalid, but the buffer pointer and size are correct.

If no buffers are available, CBaseAllocator::GetBuffer calls CBaseAllocator::SetWaiting and then calls the Microsoft® Win32® WaitForSingleObject function to wait for the list to signal that a sample is available. The list signals by calling CBaseAllocator::ReleaseBuffer, which in turn calls CBaseAllocator::NotifySample, which sets m_lWaiting to zero and calls the Win32 ReleaseSemaphore function.

This member function also takes two time parameters. These parameters are used in certain advanced buffering scenarios, when it is necessary to have an idea of the amount of time a buffer is required. The only place this is currently used is in the video renderer, when the time stamps are used as a guide to when the primary surfaces of Display Control Interface (DCI) and Microsoft® DirectDraw® should be returned (this is because filling a primary surface buffer corresponds directly to the actual rendering of the data). In all other cases, these parameters can be safely set to NULL. If one is non-NULL, both should be non-NULL; these times will not be set on the sample when it is subsequently returned.

CBaseAllocator::GetProperties

CBaseAllocator Class

Retrieves the size, number, and alignment of blocks.

HRESULT GetProperties(
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pProps
Structure to be filled in with allocator properties.
Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function implements the IMemAllocator::GetProperties method. The default implementation fills the ALLOCATOR_PROPERTIES structure passed in with the values of m_lSize, m_lCount, m_lAlignment, and m_lPrefix.

CBaseAllocator::NonDelegatingQueryInterface

CBaseAllocator Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMemAllocator and IUnknown interfaces. Override this member function to return other interfaces on the object in the derived class.

CBaseAllocator::NotifySample

CBaseAllocator Class

Notifies a waiting thread that a sample is available on the free list.

void NotifySample(void);

Return Values

No return value.

Remarks

If m_lWaiting has been incremented (is not zero), this indicates a thread is waiting. This member function checks for this condition and calls the Microsoft Win32 ReleaseSemaphore function with the semaphore value m_hSem to activate any waiting thread. It also sets m_lWaiting back to zero.

This member function is called from CBaseAllocator::ReleaseBuffer when putting a sample back on the free list and from CBaseAllocator::Decommit when decommitting the allocator (so that waiting threads can be denied).

CBaseAllocator::ReleaseBuffer

CBaseAllocator Class

Releases the object back to the list of free objects.

HRESULT ReleaseBuffer(
IMediaSample * pSample
);

Parameters
pSample
Pointer to the IMediaSample interface of the media sample object.
Return Values

No return value.

Remarks

This member function implements the IMemAllocator::ReleaseBuffer method. It adds the sample to the free list (represented by m_lFree) and calls CBaseAllocator::NotifySample to notify any blocked thread waiting for a free sample. If there is a pending CBaseAllocator::Decommit call (indicated by m_bDecommitInProgress), the pure virtual CBaseAllocator::Free member function is called to decommit memory when the last buffer is placed on the free list.

CBaseAllocator::SetProperties

CBaseAllocator Class

Determines the size, number, and alignment of blocks.

HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);

Parameters
pRequest
Allocator properties requested to be set.
pActual
Allocator properties actually set.
Return Values

Returns an HRESULT value.

Remarks

The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values that it can provide for the request. This method cannot be called unless the allocator has been decommitted using the IMemAllocator::Decommit method.

The values of data members m_lSize, m_lCount, m_lAlignment, and m_lPrefix are set to the corresponding members of the pActual parameter's ALLOCATOR_PROPERTIES structure.

CBaseAllocator::SetWaiting

CBaseAllocator Class

Increments the m_lWaiting data member to indicate that a thread is waiting for a sample.

void SetWaiting( );

Return Values

No return value.

Remarks

This member function is called from CBaseAllocator::GetBuffer if no samples are available on the free list. After calling this, CBaseAllocator::GetBuffer calls the Microsoft® Win32® WaitForSingleObject function to wait for the list to signal that a sample is available. The list signals by calling CBaseAllocator::ReleaseBuffer, which in turn calls CBaseAllocator::NotifySample, which sets m_lWaiting to zero and calls the Win32 ReleaseSemaphore function.


CBaseBasicVideo Class

CBaseBasicVideo class hierarchy

The CBaseBasicVideo class handles the IDispatch component of the IBasicVideo interface and leaves the properties and methods pure virtual.

The IDispatch::GetIDsOfNames, IDispatch::GetTypeInfo, IDispatch::GetTypeInfoCount, and IDispatch::Invoke methods are standard implementations of the IDispatch interface using the CBaseDispatch class (and a type library) to parse the commands and pass them to the pure virtual methods of the IBasicVideo interface.

Member Functions
Name | Description
CBaseBasicVideo | Constructs a CBaseBasicVideo object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used during subsequent calls to the IDispatch::Invoke method.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CBaseBasicVideo::CBaseBasicVideo

CBaseBasicVideo Class

Constructs a CBaseBasicVideo object.

CBaseBasicVideo(
const TCHAR * pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CBaseBasicVideo::GetIDsOfNames

CBaseBasicVideo Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the CBaseBasicVideo::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.

CBaseBasicVideo::GetTypeInfo

CBaseBasicVideo Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.

CBaseBasicVideo::GetTypeInfoCount

CBaseBasicVideo Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CBaseBasicVideo::Invoke

CBaseBasicVideo Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CBaseBasicVideo::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CBaseBasicVideo::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CBaseBasicVideo::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CBaseBasicVideo::NonDelegatingQueryInterface

CBaseBasicVideo Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IBasicVideo and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.


CBaseControlVideo Class

CBaseControlVideo class hierarchy

The CBaseControlVideo class implements the IBasicVideo dual interface and controls the video properties of a generic video window. Generally, a CBaseControlVideo object is a video renderer that draws video into a window on the display.

The CBaseControlVideo class supports both properties and methods. Properties are more easily accessible from many Automation controllers (such as the Microsoft® Visual Basic® programming system). However, some operations require applications to be able to change several properties simultaneously; for this reason, methods are provided that enable a number of related properties to be changed.

Many CBaseControlVideo member functions require only that the video renderer be connected to a filter graph. If it is not connected, member functions will return VFW_E_NOT_CONNECTED. Properties set on a video renderer persist between successive connections and disconnections. All applications should ensure that they reset the renderer properties before starting a presentation.

When working with video, the application can select a portion of the video to use. This portion is the source rectangle that the CBaseControlVideo object controls. CBaseControlVideo enables your application to set and retrieve the source rectangle. All the rectangles that CBaseControlVideo uses employ top, left, width, and height rather than top, left, right, and bottom, which is favored in Microsoft Win32® programming. When no source rectangle has been set, the properties of the source rectangle return the full, native video size.

Protected Data Members
Name | Description
m_pFilter | Pointer to an owning media filter.
m_pInterfaceLock | Externally defined critical section.
m_pPin | Control of the media types for connection.

Member Functions
Name | Description
CBaseControlVideo | Constructs a CBaseControlVideo object.
CopyImage | Creates a memory copy of a video image.
GetImageSize | Retrieves video image size information.
SetControlVideoPin | Sets the pin with which this object should synchronize.

Overridable Member Functions
Name | Description
CheckSourceRect | Determines if a source rectangle is valid.
CheckTargetRect | Determines if a target rectangle is valid.
GetSourceRect | Retrieves the current source video rectangle (pure virtual).
GetStaticImage | Returns the current image in a memory buffer (pure virtual).
GetTargetRect | Retrieves the current target video rectangle (pure virtual).
GetVideoFormat | Retrieves the VIDEOINFOHEADER structure containing the video format.
IsDefaultSourceRect | Determines if the renderer is using the default source rectangle (pure virtual).
IsDefaultTargetRect | Determines if the renderer is using the default target rectangle (pure virtual).
OnUpdateRectangles | Called when the source or target rectangle changes.
OnVideoSizeChange | Passes EC_VIDEO_SIZE_CHANGED to the application.
SetDefaultSourceRect | Sets the default source video rectangle (pure virtual).
SetDefaultTargetRect | Sets the default target video rectangle (pure virtual).
SetSourceRect | Sets the current source video rectangle (pure virtual).
SetTargetRect | Sets the current target rectangle (pure virtual).

Implemented IBasicVideo Methods
Name | Description
get_AvgTimePerFrame | Returns an approximate average time per frame.
get_BitErrorRate | Returns an approximate bit error rate.
get_BitRate | Returns an approximate bit rate for the video.
GetCurrentImage | Returns a memory rendering of the current image.
get_DestinationHeight | Retrieves the current destination rectangle's height.
get_DestinationLeft | Retrieves the current destination rectangle's left coordinate.
GetDestinationPosition | Retrieves the current destination position.
get_DestinationTop | Retrieves the current destination rectangle's top coordinate.
get_DestinationWidth | Retrieves the current destination rectangle's width.
get_SourceHeight | Retrieves the current source rectangle's height.
get_SourceLeft | Retrieves the current source rectangle's left coordinate.
GetSourcePosition | Retrieves the current source position.
get_SourceTop | Retrieves the current source rectangle's top coordinate.
get_SourceWidth | Retrieves the current source rectangle's width.
get_VideoHeight | Retrieves the native video height.
GetVideoPaletteEntries | Retrieves a range of palette entries for the video.
GetVideoSize | Retrieves the width and height of the native video.
get_VideoWidth | Retrieves the native video width.
IsUsingDefaultDestination | Determines if the renderer is using the default destination window.
IsUsingDefaultSource | Determines if the renderer is using the default source window.
put_DestinationHeight | Sets the destination rectangle's height.
put_DestinationLeft | Sets the destination rectangle's left coordinate.
put_DestinationTop | Sets the destination rectangle's top coordinate.
put_DestinationWidth | Sets the destination rectangle's width.
put_SourceHeight | Sets the source rectangle's height.
put_SourceLeft | Sets the source rectangle's left coordinate.
put_SourceTop | Sets the source rectangle's top coordinate.
put_SourceWidth | Sets the source rectangle's width.
SetDefaultDestinationPosition | Sets the default destination position again.
SetDefaultSourcePosition | Sets the default source position again.
SetDestinationPosition | Sets the destination rectangle position.
SetSourcePosition | Sets the source rectangle position.

CBaseControlVideo::CBaseControlVideo

CBaseControlVideo Class

Constructs a CBaseControlVideo object.

CBaseControlVideo(
CBaseFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pFilter
Owning media filter object.
pInterfaceLock
Critical section to use for locking.
pName
Object description.
pUnk
Typical COM ownership.
phr
COM return value.
Return Values

No return value.

Remarks

The object implements the IBasicVideo control interface.

All the interface methods from IBasicVideo that this class implements require that the filter be connected correctly. For this reason, the class is passed a pin with which it should synchronize with. Whenever an interface method is called, the object determines that the pin is still connected.

CBaseControlVideo::CheckSourceRect

CBaseControlVideo Class

Determines if a source rectangle is valid.

virtual HRESULT CheckSourceRect(
RECT *pSourceRect
);

Parameters
pSourceRect
Source rectangle to check.
Return Values

Returns E_INVALIDARG if not valid; otherwise, returns NOERROR (S_OK).

Remarks

This member function checks that the source rectangle requested does not exceed the available source video. The left and top coordinates cannot be negative, and the width and height cannot exceed the right and bottom of the video.

CBaseControlVideo::CheckTargetRect

CBaseControlVideo Class

Determines if a target rectangle is valid.

virtual HRESULT CheckTargetRect(
RECT *pTargetRect
);

Parameters
pTargetRect
Target rectangle to check.
Return Values

Returns E_INVALIDARG if not valid; otherwise, returns NOERROR (S_OK).

Remarks

This member function determines if the target rectangle requested is valid. Because the destination rectangle specifies a position in the logical client of the window, the coordinates can be negative, although the overall width and height cannot be zero or a negative value.

CBaseControlVideo::CopyImage

CBaseControlVideo Class

Creates a memory copy of an image.

HRESULT CopyImage(
IMediaSample *pMediaSample,
VIDEOINFOHEADER *pVideoInfo,
LONG *pBufferSize,
BYTE *pVideoImage,
RECT *pSourceRect
);

Parameters
pMediaSample
Sample containing the video image.
pVideoInfo
Format representing the video image.
pBufferSize
Size of the output buffer.
pVideoImage
Pointer to the output buffer.
pSourceRect
Source video rectangle.
Return Values

If the pVideoImage parameter is NULL, the pBufferSize parameter is filled in with the number of bytes the output buffer requires to store the image. If the buffer passed in is too small or the member function fails to allocate sufficient memory, the member function returns E_OUTOFMEMORY.

Remarks

The member function retrieves the image from the sample and copies it into the output buffer. The section of video copied into the output buffer reflects the source rectangle that is set through the IBasicVideo interface (although it does not reflect the destination rectangle).

CBaseControlVideo::get_AvgTimePerFrame

CBaseControlVideo Class

Retrieves the average time per frame.

HRESULT get_AvgTimePerFrame(
REFTIME *pAvgTimePerFrame
);

Parameters
pAvgTimePerFrame
Average time per frame.
Return Values

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_AvgTimePerFrame method. It calls the pure virtual CBaseControlVideo::GetVideoFormat member function to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::get_BitErrorRate

CBaseControlVideo Class

Returns an approximate bit error rate for the video.

HRESULT get_BitErrorRate(
long *pBitErrorRate
);

Parameters
pBitErrorRate
Bit error rate (one error for approximately this many bits).
Return Values

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_BitErrorRate method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::get_BitRate

CBaseControlVideo Class

Returns an approximate bit rate for the video.

HRESULT get_BitRate(
long *pBitRate
);

Parameters
pBitRate
Bit rate in bits per second.
Return Values

Returns NOERROR if successful or E_OUTOFMEMORY not enough memory is available.

Remarks

This member function implements the IBasicVideo::get_BitRate method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::GetCurrentImage

CBaseControlVideo Class

Returns a copy of the current image at the renderer.

HRESULT GetCurrentImage(
long *pBufferSize,
long *pVideoImage
);

Parameters
pBufferSize
Size of the output buffer.
pVideoImage
Pointer to the output buffer for the image.
Return Values

Returns an HRESULT value.

Remarks

This member function retrieves the image from the sample and copies it into the output buffer. The section of video copied into the output buffer reflects the source rectangle set through the IBasicVideo interface. It does not reflect the destination rectangle.

CBaseControlVideo::get_DestinationHeight

CBaseControlVideo Class

Retrieves the current destination rectangle height.

HRESULT get_DestinationHeight(
long *pDestinationHeight
);

Parameters
pDestinationHeight
Holds the destination height.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_DestinationHeight method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where it will be played. The destination rectangle is relative to the client area of the window that it is playing in. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationLeft

CBaseControlVideo Class

Retrieves the left coordinate of the current destination rectangle.

HRESULT get_DestinationLeft(
long *pDestinationLeft
);

Parameters
pDestinationLeft
Contains the left coordinate of the destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_DestinationLeft method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetDestinationPosition

CBaseControlVideo Class

Retrieves the destination rectangle.

HRESULT GetDestinationPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
Contains the left coordinate.
pTop
Contains the top coordinate.
pWidth
Contains the width.
pHeight
Contains the height.
Return Values

Returns an HRESULT value.

Remarks

This member function can be used in place of separate calls to the CBaseControlVideo::get_DestinationLeft, CBaseControlVideo::get_DestinationTop, CBaseControlVideo::get_DestinationWidth, and CBaseControlVideo::get_DestinationHeight member functions. An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationTop

CBaseControlVideo Class

Retrieves the top coordinate of the current destination rectangle.

HRESULT get_DestinationTop(
long *pDestinationTop
);

Parameters
pDestinationTop
Contains the top coordinate of the destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_DestinationTop method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_DestinationWidth

CBaseControlVideo Class

Retrieves the width of the current destination rectangle.

HRESULT get_DestinationWidth(
long *pDestinationWidth
);

Parameters
pDestinationWidth
Contains the destination width.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_DestinationWidth method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetImageSize

CBaseControlVideo Class

Retrieves video image size information.

HRESULT GetImageSize(
VIDEOINFOHEADER *pVideoInfo,
long *pBufferSize,
RECT *pSourceRect
);

Parameters
pVideoInfo
Contains a pointer to a VIDEOINFOHEADER structure to be filled in.
pBufferSize
Size of the video buffer.
pSourceRect
Rectangle dimensions of the source video.
Return Values

Returns an HRESULT value.

Remarks

This member function is a helper function used for creating memory image renderings of DIB images. It is called from the base class implementation of CBaseControlVideo::GetCurrentImage when a null pVideoImage parameter is passed to that member function. As a result, this member function constructs and returns a VIDEOINFOHEADER structure, using the information in pBufferSize and pSourceRect.

CBaseControlVideo::get_SourceHeight

CBaseControlVideo Class

Retrieves the height of the current source rectangle.

HRESULT get_SourceHeight(
long *pSourceHeight
);

Parameters
pSourceHeight
Contains the height of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_SourceHeight method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_SourceLeft

CBaseControlVideo Class

Retrieves the left coordinate of the current source rectangle.

HRESULT get_SourceLeft(
long *pSourceLeft
);

Parameters
pSourceLeft
Holds the left coordinate of the current source rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetSourcePosition

CBaseControlVideo Class

Retrieves the source rectangle in one atomic operation.

HRESULT GetSourcePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
Contains the left coordinate.
pTop
Contains the top coordinate.
pWidth
Contains the width.
pHeight
Contains the height.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetSourceRect

CBaseControlVideo Class

Returns the source rectangle. This is an internal method.

virtual HRESULT GetSourceRect(
RECT *pSourceRect
) PURE;

Parameters
pSourceRect
Contains the retrieved source rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function must be overridden in the derived class to return the source rectangle held by the video renderer. It is called from the following CBaseControlVideo member functions.

  • CBaseControlVideo::GetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::get_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::get_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::get_SourceTop
  • CBaseControlVideo::put_SourceHeight
  • CBaseControlVideo::get_SourceHeight

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// Return the current source rectangle

HRESULT CVideoText::GetSourceRect(RECT *pSourceRect)
{
    ASSERT(pSourceRect);
    m_pRenderer->m_DrawImage.GetSourceRect(pSourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::get_SourceTop

CBaseControlVideo Class

Retrieves the top coordinate of the current source rectangle.

HRESULT get_SourceTop(
long *pSourceTop
);

Parameters
pSourceTop
Contains the top coordinate of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_SourceTop method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::get_SourceWidth

CBaseControlVideo Class

Retrieves the width of the current source rectangle.

HRESULT get_SourceWidth(
long *pSourceWidth
);

Parameters
pSourceWidth
Contains the width of the current source rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBasicVideo::get_SourceWidth method.

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::GetStaticImage

CBaseControlVideo Class

Pure virtual method that derived classes override.

virtual HRESULT GetStaticImage(
long *pBufferSize,
long *pDIBImage
) PURE;

Parameters
pBufferSize
Size of the output buffer.
pDIBImage
Pointer to output buffer.
Return Values

Returns an HRESULT value.

Remarks

Through the IBasicVideo interface, an application can request that it be given a copy of the current image in a memory buffer (some renderers can return E_NOTIMPL to this if they do not support it). The derived class determines how to retrieve the image. When the application calls CBaseControlVideo::GetStaticImage, it calls this pure virtual method that the derived class should override to implement it. This is also called by the CBaseControlVideo::GetCurrentImage member function.

The class provides a helper member function, CBaseControlVideo::CopyImage, that can be given a sample that contains an image, and the member function will copy the relevant section of it (based on the current source rectangle) into the output buffer supplied by the application.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this member function in a derived class. In this example, m_pRenderer holds an object of a class derived from CBaseVideoRenderer.

// Return a copy of the current image in the video renderer

HRESULT CVideoText::GetStaticImage(long *pBufferSize,long *pDIBImage)
{
    // Get any sample the renderer may be holding

    IMediaSample *pMediaSample = m_pRenderer->GetCurrentSample();
    if (pMediaSample == NULL) {
        return E_UNEXPECTED;
    }

    // Call the base class helper method to do the work

    HRESULT hr = CopyImage(pMediaSample,          // Buffer containing image
                           &m_pRenderer->m_mtIn,                // Type representing bitmap
                           pBufferSize,                                     // Size of buffer for DIB
                           (BYTE*) pDIBImage);                   // Data buffer for output

    pMediaSample->Release();
    return hr;
}

CBaseControlVideo::GetTargetRect

CBaseControlVideo Class

Returns the destination rectangle. This is an internal helper member function.

virtual HRESULT GetTargetRect(
RECT *pTargetRect
) PURE;

Parameters
pTargetRect
Contains the destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

This member function must be overridden in the derived class to return the target rectangle held by the video renderer. It is called from the following CBaseControlVideo member functions.

  • CBaseControlVideo::GetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::get_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::get_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::get_DestinationTop
  • CBaseControlVideo::put_DestinationHeight
  • CBaseControlVideo::get_DestinationHeight

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// Return the current destination rectangle

HRESULT CVideoText::GetTargetRect(RECT *pTargetRect)
{
    ASSERT(pTargetRect);
    m_pRenderer->m_DrawImage.GetTargetRect(pTargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::GetVideoFormat

CBaseControlVideo Class

Retrieves a video sample that represents the current video format.

virtual VIDEOINFOHEADER * GetVideoFormat( ) PURE;

Return Values

Returns a pointer to a VIDEOINFOHEADER structure that contains the current video format.

Remarks

To return and check certain information through IBasicVideo, the object must know the current video format. It gets this information by calling this pure virtual method that derived classes must override. This member function is called by the following CBaseControlVideo member functions.

  • CBaseControlVideo::OnVideoSizeChange
  • CBaseControlVideo::get_AvgTimePerFrame
  • CBaseControlVideo::get_BitRate
  • CBaseControlVideo::get_BitErrorRate
  • CBaseControlVideo::get_VideoWidth
  • CBaseControlVideo::get_VideoHeight
  • CBaseControlVideo::GetVideoPaletteEntries
  • CBaseControlVideo::GetVideoSize

CBaseControlVideo::get_VideoHeight

CBaseControlVideo Class

Retrieves the height of the native video.

HRESULT get_VideoHeight(
long *pVideoHeight
);

Parameters
pVideoHeight
Contains the height of the native video, in pixels.
Return Values

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_VideoHeight method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::GetVideoPaletteEntries

CBaseControlVideo Class

Retrieves a range of palette entries for the video.

HRESULT GetVideoPaletteEntries(
long StartIndex,
long Entries,
long *pRetrieved,
long *pPalette
);

Parameters
StartIndex
Zero-based start palette entry.
Entries
Number of entries required.
pRetrieved
Number of colors obtained.
pPalette
Pointer to output buffer for colors.
Return Values

Returns NOERROR if successful, VFW_E_NO_PALETTE_AVAILABLE if the video samples has no color palette, E_OUTOFMEMORY if there is not enough memory available, E_INVALIDARG if StartIndex is invalid, or S_FALSE if there are no colors in the palette.

Remarks

This member function returns the current palette of the video as an array allocated by the user. To remain consistent, use the members in the Win32 PALETTEENTRY structure to return the colors, rather than the members in the RGBQUAD structure (although the parameter is a LONG). The memory is allocated by the caller, so simply copy each in turn. Determine that the number of entries requested and the start position offset are both valid. If the number of entries evaluates to zero, return an S_FALSE code.

CBaseControlVideo::GetVideoSize

CBaseControlVideo Class

Retrieves the native video's width and height.

HRESULT GetVideoSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
Contains the video width.
pHeight
Contains the video height.
Return Values

Returns an HRESULT value.

CBaseControlVideo::get_VideoWidth

CBaseControlVideo Class

Retrieves the width of the native video.

HRESULT get_VideoWidth(
long *pVideoWidth
);

Parameters
pVideoWidth
Contains the width of the native video, in pixels.
Return Values

Returns NOERROR if successful or E_OUTOFMEMORY if there is not enough memory available.

Remarks

This member function implements the IBasicVideo::get_VideoWidth method. It calls the pure virtual CBaseControlVideo::GetVideoFormat to retrieve the VIDEOINFOHEADER structure from the derived class.

CBaseControlVideo::IsDefaultSourceRect

CBaseControlVideo Class

Determines if the renderer is using the default source rectangle (pure virtual).

virtual HRESULT IsDefaultSourceRect(void) PURE;

Return Values

Returns an HRESULT value.

Remarks

This member function must be implemented in the derived class. It is called by the CBaseControlVideo::IsUsingDefaultSource member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// Return S_OK if using the default source otherwise S_FALSE

HRESULT CVideoText::IsDefaultSourceRect()
{
    RECT SourceRect;

    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    m_pRenderer->m_DrawImage.GetSourceRect(&SourceRect);

    // Check the coordinates that match the video dimensions

    if (SourceRect.left != 0 || SourceRect.top != 0 ||
            SourceRect.right != pHeader->biWidth ||
                SourceRect.bottom != pHeader->biHeight) {
                    return S_FALSE;
    }
    return S_OK;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with the media type of the input pin.

CBaseControlVideo::IsDefaultTargetRect

CBaseControlVideo Class

Determines if the renderer is using the default target rectangle (pure virtual).

virtual HRESULT IsDefaultTargetRect(void) PURE;

Return Values

Returns an HRESULT value.

Remarks

This member function must be implemented in the derived class. It is called by the CBaseControlVideo::IsUsingDefaultDestination member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// Return S_OK if using the default target; otherwise S_FALSE

HRESULT CVideoText::IsDefaultTargetRect()
{
    RECT TargetRect;

    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    m_pRenderer->m_DrawImage.GetTargetRect(&TargetRect);

    // Check the destination that matches the initial client area

    if (TargetRect.left != 0 || TargetRect.top != 0 ||
            TargetRect.right != m_Size.cx ||
                TargetRect.bottom != m_Size.cy) {
                    return S_FALSE;
    }
    return S_OK;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with media type of the input pin.

CBaseControlVideo::IsUsingDefaultSource

CBaseControlVideo Class

Determines if the renderer is using the default source window.

virtual HRESULT IsUsingDefaultSource(void);

Return Values

Returns an HRESULT value.

CBaseControlVideo::IsUsingDefaultDestination

CBaseControlVideo Class

Determines if the renderer is using the default destination window.

virtual HRESULT IsUsingDefaultDestination(void);

Return Values

Returns an HRESULT value. Returns S_OK if using the default destination; otherwise, returns S_FALSE.

CBaseControlVideo::OnUpdateRectangles

CBaseControlVideo Class

Called when either the source or destination rectangle changes.

virtual HRESULT OnUpdateRectangles( );

Return Values

Returns an HRESULT value.

CBaseControlVideo::OnVideoSizeChange

CBaseControlVideo Class

Passes an EC_VIDEO_SIZE_CHANGED message to the filter graph manager.

virtual HRESULT OnVideoSizeChange( );

Return Values

Returns an HRESULT value.

Remarks

A video renderer should call this member function each time the video size is changed; this will typically be called once after initial connection. If the renderer can support dynamic format changes (from 320x240 to 160x120), it should also call it after each change.

CBaseControlVideo::put_DestinationHeight

CBaseControlVideo Class

Sets the destination rectangle height.

HRESULT put_DestinationHeight(
long DestinationHeight
);

Parameters
DestinationHeight
New destination height.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationLeft

CBaseControlVideo Class

Sets the left coordinate of the destination rectangle.

HRESULT put_DestinationLeft(
long DestinationLeft
);

Parameters
DestinationLeft
New left coordinate of destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationTop

CBaseControlVideo Class

Sets the top coordinate of the destination rectangle.

HRESULT put_DestinationTop(
long DestinationTop
);

Parameters
DestinationTop
New top coordinate of the destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_DestinationWidth

CBaseControlVideo Class

Sets the width of the destination rectangle.

HRESULT put_DestinationWidth(
long DestinationWidth
);

Parameters
DestinationWidth
New destination width.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceHeight

CBaseControlVideo Class

Sets the source rectangle height.

HRESULT put_SourceHeight(
long SourceHeight
);

Parameters
SourceHeight
Contains the source height.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceLeft

CBaseControlVideo Class

Sets the source rectangle left coordinate.

HRESULT put_SourceLeft(
long SourceLeft
);

Parameters
SourceLeft
New left coordinate of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceTop

CBaseControlVideo Class

Sets the top coordinate of the source rectangle.

HRESULT put_SourceTop(
long SourceTop
);

Parameters
SourceTop
New top coordinate of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::put_SourceWidth

CBaseControlVideo Class

Sets the width of the source rectangle.

HRESULT put_SourceWidth(
long SourceWidth
);

Parameters
SourceWidth
New width of the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetControlVideoPin

CBaseControlVideo Class

Sets the pin used by the filter.

void SetControlVideoPin(
CBasePin *pPin
);

Parameters
pPin
Pin with which the interface is synchronized.
Return Values

No return value.

Remarks

The interface can be called only when the filter has been connected successfully. The object is passed through this method to the pin with which it is synchronized; in most cases it will determine if the pin is connected when it has an interface method called and will return VFW_E_NOT_CONNECTED if it fails.

CBaseControlVideo::SetDefaultDestinationPosition

CBaseControlVideo Class

Sets the renderer back to using the default destination position (typically the entire window client area).

HRESULT SetDefaultDestinationPosition( );

Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetDefaultSourcePosition

CBaseControlVideo Class

Sets the renderer back to using the default source position (typically all the native video).

HRESULT SetDefaultSourcePosition( );

Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetDefaultSourceRect

CBaseControlVideo Class

Sets the default source video rectangle (pure virtual). This in an internal member function that gets called when the source rectangle is reset.

virtual HRESULT SetDefaultSourceRect( ) PURE;

Return Values

Returns an HRESULT value.

Remarks

Derived classes should override this to reset the source rectangle. It is called from CBaseControlVideo::SetDefaultSourcePosition.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// This is called when we reset the default source rectangle

HRESULT CVideoText::SetDefaultSourceRect()
{
    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    RECT SourceRect = {0,0,pHeader->biWidth,pHeader->biHeight};
    m_pRenderer->m_DrawImage.SetSourceRect(&SourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with media type of the input pin.

CBaseControlVideo::SetDefaultTargetRect

CBaseControlVideo Class

Sets the default target video rectangle (pure virtual). This is an internal member function that gets called when the source rectangle is reset.

virtual HRESULT SetDefaultTargetRect( ) PURE;

Return Values

Returns an HRESULT value.

Remarks

Derived classes should override this to reset the destination video rectangle. It is called from the CBaseControlVideo::SetDefaultDestinationPosition member function.

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

// This is called when we reset the default target rectangle

HRESULT CVideoText::SetDefaultTargetRect()
{
    VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
    BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
    RECT TargetRect = {0,0,m_Size.cx,m_Size.cy};
    m_pRenderer->m_DrawImage.SetTargetRect(&TargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object. The m_mtIn data member, also defined in the derived class, holds a CMediaType object with the media type of the input pin.

CBaseControlVideo::SetDestinationPosition

CBaseControlVideo Class

Sets the destination rectangle for the video.

HRESULT SetDestinationPosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
New left coordinate.
Top
New top coordinate.
Width
New width.
Height
New height.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetSourcePosition

CBaseControlVideo Class

Sets a new source position for the video.

HRESULT SetSourcePosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
New left coordinate.
Top
New top coordinate.
Width
New width.
Height
New height.
Return Values

Returns an HRESULT value.

Remarks

An application can change the source and destination rectangles for the video through the IBasicVideo interface. The source rectangle affects which section of the native video source will appear on the display; the destination rectangle affects where the video will appear when played. The destination rectangle is relative to the client area of the window in which it is playing. The upper-left corner of the window is coordinate (0,0).

CBaseControlVideo::SetSourceRect

CBaseControlVideo Class

Sets the current source video rectangle (pure virtual). This is an internal member function that gets called when the source rectangle changes.

virtual HRESULT SetSourceRect(
RECT *pSourceRect
) PURE;

Parameters
pSourceRect
Contains the source rectangle.
Return Values

Returns an HRESULT value.

Remarks

Derived classes should override this member function to know when the source rectangle changes. It is called from the following member functions.

  • CBaseControlVideo::SetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::put_SourceHeight

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

HRESULT CVideoText::SetSourceRect(RECT *pSourceRect)
{
    m_pRenderer->m_DrawImage.SetSourceRect(pSourceRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.

CBaseControlVideo::SetTargetRect

CBaseControlVideo Class

Sets the current target rectangle (pure virtual). This is an internal member function that gets called when the destination rectangle changes.

virtual HRESULT SetTargetRect(
RECT *pTargetRect
) PURE;

Parameters
pTargetRect
Contains the destination rectangle.
Return Values

Returns an HRESULT value.

Remarks

Derived classes should override this to know when the destination rectangle changes. It is called from the following member functions.

  • CBaseControlVideo::SetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::put_DestinationHeight

The following example from the video renderer sample, SampVid, demonstrates an implementation of this function in a derived class.

HRESULT CVideoText::SetTargetRect(RECT *pTargetRect)
{
    m_pRenderer->m_DrawImage.SetTargetRect(pTargetRect);
    return NOERROR;
}

In this example, CVideoText is a class derived from CBaseControlVideo, m_pRenderer holds an object of a class derived from CBaseVideoRenderer, and the m_DrawImage data member, defined in the derived class, holds a CDrawImage object.


CBaseControlWindow Class

CBaseControlWindow class hierarchy

The CBaseControlWindow class implements the IVideoWindow interface and controls external access to its associated filter. You must synchronize the CBaseControlWindow object with the filter by passing it a pointer to a critical section synchronization object. For more information about critical section synchronization objects, see the Platform SDK. The CBaseControlWindow class provides a number of methods that return property settings without dealing with this critical section. For example, calling CBaseControlWindow::get_AutoShow to retrieve the value of the m_bAutoShow data member locks the critical section. The filter might already have a locked internal critical section, however, which could violate the filter's lock hierarchy. Instead, calling the CBaseControlWindow::IsAutoShowEnabled member function returns the required value without affecting the critical section.

All CBaseControlWindow implemented IVideoWindow methods require that the filter be connected correctly with its upstream filter. For this reason, class objects require a synchronization pin, which you set by calling the CBaseControlWindow::SetControlWindowPin method. Whenever you call an IVideoWindow method, the CBaseControlWindow object checks that the pin is still connected.

Protected Data Members
Name | Description
m_bAutoShow | Result when the state changes.
m_bCursorHidden | Determination of whether the cursor is displayed or hidden.
m_BorderColour | Color of the current window border.
m_hwndDrain | Window handle to which messages received are posted.
m_hwndOwner | Owning window.
m_pFilter | Pointer to the owning media filter.
m_pInterfaceLock | Externally defined critical section.
m_pPin | Control of the media types for connection.

Member Functions
Name | Description
CBaseControlWindow | Constructs a CBaseControlWindow object.
DoGetWindowStyle | Retrieves either the typical or extended window styles.
DoSetWindowStyle | Sets the typical or extended window styles.
GetBorderColour | Retrieves the current border color. This is a helper member function.
GetOwnerWindow | Retrieves the owning window. This is a helper member function.
IsAutoShowEnabled | Retrieves information about whether the video window automatically appears when the rendering filter pauses or runs.
IsCursorHidden | Retrieves the current state of the m_bCursorHidden data member without locking the critical section. This is a helper member function.
PossiblyEatMessage | Distributes messages to the parent window.
SetControlWindowPin | Notifies the object of the pin to which it applies.

Implemented IVideoWindow Methods
Name | Description
get_AutoShow | Retrieves the current AutoShow flag setting.
get_BackgroundPalette | Retrieves the realized palette in the background flag.
get_BorderColor | Retrieves the current border color.
get_Caption | Retrieves the current window caption.
get_FullScreenMode | Retrieves the current full-screen mode.
get_Height | Retrieves the current window height.
get_Left | Retrieves the current left window coordinate.
GetMaxIdealImageSize | Retrieves the maximum size of the ideal image.
get_MessageDrain | Returns the current message drain.
GetMinIdealImageSize | Retrieves the minimum size of the ideal image.
get_Owner | Retrieves the Microsoft® Win32® parent window handle.
GetRestorePosition | Retrieves the position to which the window will be restored when maximized or minimized.
get_Top | Retrieves the y-coordinate for the top of the window.
get_Visible | Retrieves the current visibility setting of the window.
get_Width | Retrieves the width of the window.
GetWindowPosition | Retrieves the current window coordinates.
get_WindowState | Retrieves the current state of the window.
get_WindowStyle | Retrieves the standard window styles.
get_WindowStyleEx | Retrieves the extended window styles.
HideCursor | Hides or displays the cursor.
IsCursorHidden | Retrieves the current state of the m_bCursorHidden data member.
NotifyOwnerMessage | Passes on messages that are sent to owning windows.
put_AutoShow | Sets the AutoShow property.
put_BackgroundPalette | Sets a flag to realize the palette in the background.
put_BorderColor | Sets the current border color.
put_Caption | Sets the current window caption.
put_FullScreenMode | Sets the full-screen mode.
put_Height | Sets the current window height.
put_Left | Sets the left coordinate for the window.
put_MessageDrain | Sets the message drain window.
put_Owner | Sets the Microsoft Win32 parent window handle.
put_Top | Sets the position for the top of the window.
put_Visible | Hides or shows the window.
put_Width | Sets the width of the window.
put_WindowState | Sets the state of the window.
put_WindowStyle | Sets the standard window styles.
put_WindowStyleEx | Sets the extended window styles.
SetWindowForeground | Sets the window in the foreground.
SetWindowPosition | Sets the window position.

CBaseControlWindow::CBaseControlWindow

CBaseControlWindow Class

Constructs a CBaseControlWindow object.

CBaseControlWindow(
CBaseMediaFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pFilter
Owning media filter object.
pInterfaceLock
Critical section to use for locking.
pName
Object description.
pUnk
Typical Component Object Model (COM) ownership.
phr
COM return value.
Return Values

No return value.

CBaseControlWindow::DoGetWindowStyle

CBaseControlWindow Class

Retrieves the current normal or extended window styles.

HRESULT DoGetWindowStyle(
long *pStyle,
long WindowLong
);

Parameters
pStyle
Contains the appropriate styles.
WindowLong
Either GWL_STYLE or GWL_EXSTYLE.
Return Values

Returns an HRESULT value.

Remarks

This member function calls the Win32 GetWindowLong function to retrieve the window style. It is called by the CBaseControlWindow::get_WindowStyle and CBaseControlWindow::get_WindowStyleEx member functions.

CBaseControlWindow::DoSetWindowStyle

CBaseControlWindow Class

Changes the typical or extended window styles.

HRESULT DoSetWindowStyle(
long Style,
long WindowLong
);

Parameters
Style
Contains the appropriate window styles.
WindowLong
Either GWL_STYLE or GWL_EXSTYLE.
Return Values

Returns an HRESULT value.

Remarks

This member function calls the Win32 SetWindowLong function to set the window style, and then redisplays the window in the current position. This member function is called by the CBaseControlWindow::put_WindowStyle and CBaseControlWindow::put_WindowStyleEx member functions.

CBaseControlWindow::get_AutoShow

CBaseControlWindow Class

Retrieves the current AutoShow state flag.

HRESULT get_AutoShow(
long *AutoShow
);

Parameters
AutoShow
Automation Boolean flag (0 is off, –1 is on).
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IVideoWindow::get_AutoShow method. This property simplifies window display access for applications. If this is set to –1 (on), the window, which is typically hidden after connection of the filter, will be displayed automatically when the filter pauses or runs. The window should not be hidden when the filter stops, however. If this parameter is set to 0 (off), the window is made visible only when the application calls CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState with the appropriate parameters.

This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::IsAutoShowEnabled member function to retrieve this property if you are not calling from an external object.

CBaseControlWindow::get_BackgroundPalette

CBaseControlWindow Class

Retrieves the realized palette in the background flag.

HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);

Parameters
pBackgroundPalette
Automation Boolean flag (0 is off, –1 is on).
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IVideoWindow::get_BackgroundPalette method. If a video will be played within another application or document, the application might want to use its own palette. It can ask that the video use the current foreground palette rather than its own by setting this flag to –1. If this is set to 0, the window will install and realize its own preferred palette. Note that asking the window to use a different palette will cause severe performance penalties.

CBaseControlWindow::get_BorderColor

CBaseControlWindow Class

Retrieves the current border color.

HRESULT get_BorderColor(
long *Color
);

Parameters
Color
Current border color.
Return Values

Returns an HRESULT value.

Remarks

An application can set a destination rectangle in which the video should be displayed. This rectangle is relative to the client area for the window. If this is done (the default is to always paint the entire window), there is a border surrounding the video. This property affects the color used by the border. Although the parameter is specified as a LONG type, it is actually a COLORREF value.

This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::GetBorderColour member function to retrieve this property if not calling from an external object.

CBaseControlWindow::GetBorderColour

CBaseControlWindow Class

Returns the current window border color, m_BorderColour.

COLORREF GetBorderColour( );

Return Values

Returns the color of the border.

Remarks

An application can set a destination rectangle to display the video. This rectangle should be relative to the client area for the window. If this is done (the default is to always paint the entire window), there is an area that surrounds the video; that is, the border. The border color can be set through the CBaseControlWindow::put_BorderColor member function. This property affects the color of the border. Use this member function instead of CBaseControlWindow::get_BorderColor, unless you are calling this externally through the IVideoWindow::get_BorderColor method.

CBaseControlWindow::get_Caption

CBaseControlWindow Class

Retrieves the current window caption.

HRESULT get_Caption(
BSTR *pstrCaption
);

Parameters
pstrCaption
Current window caption.
Return Values

Returns an HRESULT value.

Remarks

Most top-level windows on a Windows-based desktop have a title (caption) associated with them. This property can be queried and set through the IVideoWindow interface. Any caption set will be visible only if the window has the WS_CAPTION style applied. If it does not, the caption can still be set (and retrieved), although it will not be visible to the user.

CBaseControlWindow::get_FullScreenMode

CBaseControlWindow Class

Retrieves the current full-screen mode.

HRESULT get_FullScreenMode(
long *FullScreenMode
);

Parameters
FullScreenMode
Current full-screen mode.
Return Values

Returns an HRESULT value.

Remarks

This member function returns E_NOTIMPL by default. This informs the IVideoWindow plug-in distributor that this renderer does not implement a full-screen renderer.

CBaseControlWindow::get_Height

CBaseControlWindow Class

Retrieves the current window height.

HRESULT get_Height(
long *pHeight
);

Parameters
pHeight
Current window height, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow™. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::get_Left

CBaseControlWindow Class

Retrieves the current left window coordinate.

HRESULT get_Left(
long *pLeft
);

Parameters
pLeft
Contains the left coordinate, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This position is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left and up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height have no effect on the left and top coordinates.

CBaseControlWindow::GetMaxIdealImageSize

CBaseControlWindow Class

Retrieves the maximum ideal image size.

HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
Maximum ideal width, in pixels.
pHeight
Maximum ideal height, in pixels.
Return Values

Returns an HRESULT value.

Remarks

Various renderers have performance restrictions on the size of images they can display. Although they should still function properly when requested to display images larger than the specified maximum, renderers can nominate the minimum and maximum ideal sizes through the IVideoWindow interface. This interface can be called only when the filter graph is paused or running, because it is not until then that resources are allocated and the renderer can recognize its restrictions. If no restrictions exist, the renderer fills in the pWidth and pHeight parameters with the native video dimensions and returns S_FALSE. If restrictions do exist, the restricted width and height are entered, and the member function returns S_OK.

The dimensions apply to the size of the destination video and not to the overall window size. So, when calculating the size of the window to set, account for the current window styles (for example, WS_CAPTION and WS_BORDER).

CBaseControlWindow::get_MessageDrain

CBaseControlWindow Class

Returns the current message drain.

HRESULT get_MessageDrain(
OAHWND *Drain
);

Parameters
Drain
Current window receiving window messages.
Return Values

Returns an HRESULT value.

Remarks

Messages sent to the video renderer filter can be posted to another window. The window registered to receive these messages (using the CBaseControlWindow::get_MessageDrain member function) is the current message drain.

CBaseControlWindow::GetMinIdealImageSize

CBaseControlWindow Class

Retrieves the minimum ideal image size.

HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);

Parameters
pWidth
Minimum ideal width, in pixels.
pHeight
Minimum ideal height, in pixels.
Return Values

Returns an HRESULT value.

Remarks

Various renderers have performance restrictions on the size of images they can display. Although they should still function properly when requested to display images larger than the specified maximum, renderers can nominate the minimum and maximum ideal sizes through the IVideoWindow interface. This interface can be called only when the filter graph is paused or running, because it is not until then that resources are allocated and the renderer can recognize its restrictions. If no restrictions exist, the renderer fills in the pWidth and pHeight parameters with the native video dimensions and returns S_FALSE. If restrictions do exist, the restricted width and height are entered, and the member function returns S_OK.

The dimensions apply to the size of the destination video and not to the overall window size. So, when calculating the size of the window to set, account for the current window styles (for example, WS_CAPTION and WS_BORDER).

CBaseControlWindow::get_Owner

CBaseControlWindow Class

Retrieves the current window owner.

HRESULT get_Owner(
OAHWND *Owner
);

Parameters
Owner
Contains the window owner.
Return Values

Returns an HRESULT value.

Remarks

The video window can play back within a document environment. To do this, the window must be made a child of another window (so that it is clipped and moved appropriately). This property allows the owner of the window to be set and retrieved. When the window is owned by another window, it simply calls the Microsoft Win32 SetParent function. An application calling this function will change the window styles to set the WS_CHILD bit on.

When the window is owned by another window, it will automatically forward certain sets of messages (in particular, mouse and keyboard messages). This allows an application to do simple hot-spot editing and other interactions.

This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::GetOwnerWindow member function to retrieve this property if not calling from an external object.

CBaseControlWindow::GetOwnerWindow

CBaseControlWindow Class

Returns the owning window handle, m_hwndOwner.

HWND GetOwnerWindow( );

Return Values

Returns an internal method to return the owner window.

Remarks

Retrieves the owning window without calling the interface method. Use this member function instead of CBaseControlWindow::get_Owner, unless you are calling this externally through the IVideoWindow::get_Owner method.

CBaseControlWindow::GetRestorePosition

CBaseControlWindow Class

Retrieves the position to which the window will be restored when it is not maximized or minimized.

HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
Value for leftmost coordinate.
pTop
Value for top of the window.
pWidth
Value for width of the window.
pHeight
Value for height of window.
Return Values

Returns an HRESULT value.

Remarks

This is the same as the values returned by the CBaseControlWindow::GetWindowPosition function when the window is neither maximized nor minimized.

CBaseControlWindow::get_Top

CBaseControlWindow Class

Retrieves the top window coordinate.

HRESULT get_Top(
long *pTop
);

Parameters
pTop
Contains the top coordinate, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::get_Visible

CBaseControlWindow Class

Retrieves the current window visibility.

HRESULT get_Visible(
long *pVisible
);

Parameters
pVisible
Automation Boolean flag (0 is off, –1 is on).
Return Values

Returns an HRESULT value.

Remarks

This member function returns –1 if the window has the WS_VISIBLE style; 0 otherwise.

CBaseControlWindow::get_Width

CBaseControlWindow Class

Retrieves the current window width.

HRESULT get_Width(
long *pWidth
);

Parameters
pWidth
Contains the window width, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::GetWindowPosition

CBaseControlWindow Class

Retrieves the current coordinates for the window.

HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

Parameters
pLeft
Contains the left coordinate, in screen coordinates.
pTop
Contains the top coordinate, in screen coordinates.
pWidth
Contains the window width, in screen coordinates.
pHeight
Contains the window height, in screen coordinates.
Return Values

Returns an HRESULT value.

CBaseControlWindow::get_WindowState

CBaseControlWindow Class

Retrieves the current window state.

HRESULT get_WindowState(
long *pWindowState
);

Parameters
pWindowState
Contains the window state.
Return Values

Returns an HRESULT value.

Remarks

This member function returns a subset of the parameters of the Microsoft Win32 ShowWindow function. In particular, it returns SW_SHOW and SW_HIDE, depending on the current visibility of the window. It also returns SW_MINIMIZE and SW_MAXIMIZE, depending on whether the window is an icon or is expanded.

CBaseControlWindow::get_WindowStyle

CBaseControlWindow Class

Retrieves the standard window styles.

HRESULT get_WindowStyle(
long *pWindowStyle
);

Parameters
pWindowStyle
Contains the window styles.
Return Values

Returns an HRESULT value.

Remarks

This member function returns the standard window styles, such as WS_CHILD and WS_VISIBLE. It calls the CBaseControlWindow::DoGetWindowStyle member function.

CBaseControlWindow::get_WindowStyleEx

CBaseControlWindow Class

Retrieves the extended window styles.

HRESULT get_WindowStyleEx(
long *pWindowStyleEx
);

Parameters
pWindowStyleEx
Contains the extended window styles.
Return Values

Returns an HRESULT value.

Remarks

This member function retrieves the extended window styles. It calls the CBaseControlWindow::DoGetWindowStyle member function.

CBaseControlWindow::HideCursor

CBaseControlWindow Class

Hides or displays the cursor.

HRESULT HideCursor(
long HideCursor
);

Parameters
HideCursor
Set to OATRUE to hide the cursor, or OAFALSE to display the cursor.
Return Values

Returns an HRESULT value.

CBaseControlWindow::IsCursorHidden

CBaseControlWindow Class

Retrieves the current state of the m_bCursorHidden data member.

HRESULT IsCursorHidden(
long *CursorHidden
);

BOOL IsCursorHidden( );

Parameters
CursorHidden
Value of m_bCursorHidden.
Return Values

When called without a parameter, returns OATRUE if the cursor is hidden, or OAFALSE if the cursor is visible.

When called with a parameter, returns an HRESULT value.

Remarks

Internal objects should call this member function without the CursorHidden parameter to avoid locking the critical section. External objects access this member function with the CursorHidden parameter through the IVideoWindow::IsCursorHidden method.

CBaseControlWindow::IsAutoShowEnabled

CBaseControlWindow Class

Retrieves information about whether the video window automatically appears when the rendering filter pauses or runs.

BOOL IsAutoShowEnabled( );

Return Values

Returns TRUE if the m_bAutoShow member is set to –1 or FALSE if it is set to 0.

Remarks

If the m_bAutoShow member is set to –1 on a video window that is hidden, the window becomes visible when the filter pauses or runs. If this member is set to 0, the window will appear only if you use the CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState member function with the appropriate parameters.

This member function retrieves the m_bAutoShow member setting and has the same result as using the IVideoWindow::get_AutoShow method.

CBaseControlWindow::NotifyOwnerMessage

CBaseControlWindow Class

Passes along specific messages to the video window.

HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);

Parameters
hwnd
Handle to the video window.
uMsg
Message details.
wParam
Standard WPARAM parameter.
lParam
Standard LPARAM parameter.
Return Values

Returns NO_ERROR.

Remarks

When the video window is a child of another window, it does not receive certain top-level window messages. These messages can be valuable to a renderer, because they could affect its behavior. NotifyOwnerMessage passes any of the following messages to the video window.
WM_ACTIVATEAPP
WM_DEVMODECHANGE
WM_DISPLAYCHANGE
WM_PALETTECHANGED
WM_PALETTEISCHANGING
WM_QUERYNEWPALETTE
WM_SYSCOLORCHANGE

You can request that the IVideoWindow plug-in distributor (PID) make a window become a child of another window. When this occurs, the PID will look for certain messages that might be sent to the owning window. The PID will then forward those messages to the owned window. The default processing for the messages is to send them to the owned window procedure synchronously by calling the Win32 SendMessage function.

CBaseControlWindow::PossiblyEatMessage

CBaseControlWindow Class

Forwards keyboard and mouse messages to a specified window.

BOOL WINAPI PossiblyEatMessage(
HWND hwndDrain,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
)

Parameters
hwndDrain
Handle of the window to which messages will be forwarded.
uMsg
Message that was forwarded.
wParam
First message parameter.
lParam
Second message parameter.
Return Values

Returns TRUE if the message was posted or FALSE if it wasn't.

Remarks

When the window is owned, it will pass certain classes of messages to the owning window (such as keyboard and mouse events). In this case, the Win32 PostMessage function is used to post messages to any window specified by hwndDrain which is set in CBaseControlWindow::put_MessageDrain. If a certain message cannot be posted, this message will return FALSE.

The following is a list of messages that will get passed on untranslated and return TRUE.
WM_CHAR | WM_DEADCHAR
WM_KEYDOWN | WM_KEYUP
WM_LBUTTONDBLCLK | WM_LBUTTONDOWN
WM_LBUTTONUP | WM_MBUTTONDBLCLK
WM_MBUTTONDOWN | WM_MBUTTONUP
WM_MOUSEACTIVATE | WM_MOUSEMOVE
WM_NCHITTEST | WM_NCLBUTTONDBLCLK
WM_NCLBUTTONDOWN | WM_NCLBUTTONUP
WM_NCMBUTTONDBLCLK | WM_NCMBUTTONDOWN
WM_NCMBUTTONUP | WM_NCMOUSEMOVE
WM_NCRBUTTONDBLCLK | WM_NCRBUTTONDOWN
WM_NCRBUTTONUP | WM_RBUTTONDBLCLK
WM_RBUTTONDOWN | WM_RBUTTONUP
WM_SYSCHAR | WM_SYSDEADCHAR
WM_SYSKEYDOWN | WM_SYSKEYUP

CBaseControlWindow::put_AutoShow

CBaseControlWindow Class

Sets the AutoShow state flag.

HRESULT put_AutoShow(
long AutoShow
);

Parameters
AutoShow
Automation Boolean flag (0 is off, –1 is on).
Return Values

Returns an HRESULT value.

Remarks

This property simplifies window display access for applications. If this is set to –1 (on), the window, which is typically hidden after the filter is connected, will be displayed automatically when the filter pauses or runs. The window should not be hidden when the filter stops, however. If this is set to 0 (off), the window is made visible only when the application calls CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState with the appropriate parameters.

CBaseControlWindow::put_BackgroundPalette

CBaseControlWindow Class

Sets a flag to realize the palette in the background.

HRESULT put_BackgroundPalette(
long BackgroundPalette
);

Parameters
BackgroundPalette
Automation Boolean flag (0 is off, –1 is on).
Return Values

Returns an HRESULT value.

Remarks

To play a video within another application or document, the application might want to use its own palette. It can ask that the video use the current foreground palette rather than its own as the background palette by setting this flag to –1. If this is set to 0, the window will install and realize its own preferred palette. Asking the window to use a different palette will cause severe performance penalties.

CBaseControlWindow::put_BorderColor

CBaseControlWindow Class

Changes the border color.

HRESULT put_BorderColor(
long Color
);

Parameters
Color
Contains the new border color.
Return Values

Returns an HRESULT value.

Remarks

An application can establish a destination rectangle in which the video should be displayed. This rectangle is relative to the client area for the window. If this is done (the default is to always paint the entire window), there is a border surrounding the video. This property affects the color used by the border. Although the parameter is specified as a LONG type, it is actually a COLORREF value.

CBaseControlWindow::put_Caption

CBaseControlWindow Class

Sets the window title or caption.

HRESULT put_Caption(
BSTR strCaption
);

Parameters
strCaption
Contains the new window caption.
Return Values

Returns an HRESULT value.

Remarks

Most top-level windows on a Windows-based desktop have a title (caption) associated with them. This property can be queried and set through the IVideoWindow interface. Any caption set will be visible only if the window has the WS_CAPTION style applied. If it does not, the caption can still be set (and retrieved), although it will not be visible to the user.

CBaseControlWindow::put_FullScreenMode

CBaseControlWindow Class

Sets the full-screen mode of the renderer.

HRESULT put_FullScreenMode(
long FullScreenMode
);

Parameters
FullScreenMode
Full-screen mode to apply.
Return Values

Returns an HRESULT value.

Remarks

The current implementation returns E_NOTIMPL. A video renderer that implements a full-screen mode should override this member function and implement whatever modes it supports.

CBaseControlWindow::put_Height

CBaseControlWindow Class

Sets the window height.

HRESULT put_Height(
long Height
);

Parameters
Height
New window height, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::put_Left

CBaseControlWindow Class

Sets the left coordinate for the window.

HRESULT put_Left(
long Left
);

Parameters
Left
New left coordinate, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::put_MessageDrain

CBaseControlWindow Class

Sets the window to receive window messages sent to the video renderer.

HRESULT put_MessageDrain(
OAHWND Drain
);

Parameters
Drain
Window to post messages to.
Return Values

Returns an HRESULT value.

Remarks

Messages sent to the video renderer filter can be posted to another window. This member function registers the window to receive these messages. Unlike the CBaseControlWindow::put_Owner member function, this member function does not make the video window a child of another window. It is particularly useful for full-screen video renderers, which cannot be child windows.

CBaseControlWindow::put_Owner

CBaseControlWindow Class

Sets the video window's parent window; the parent window then forwards certain messages to the video window.

HRESULT put_Owner(
OAHWND Owner
);

Parameters
Owner
Handle to the parent window.
Return Values

Returns NOERROR.

Remarks

Internally, this method calls the Microsoft Win32 SetParent function to set the new owner and sets the parent window's style to WS_CHILD. The parent window will then forward certain sets of messages (in particular, mouse and keyboard messages) to the video window.

After you set the video window's owner, you must set the owner to NULL and the owner's window style to WS_OVERLAPPED and WS_CLIPCHILDREN before releasing the filter graph. When you set the owner to NULL, this method turns off the parent window's WS_CHILD bit. If you don't set the owner to NULL, the parent window will continue to pass messages to the video window and errors will likely occur when the application closes.

CBaseControlWindow::put_Top

CBaseControlWindow Class

Sets the top window coordinate.

HRESULT put_Top(
long Top
);

Parameters
Top
New top coordinate, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::put_Visible

CBaseControlWindow Class

Makes the window either visible or hidden.

HRESULT put_Visible(
long Visible
);

Parameters
Visible
Automation Boolean flag (0 means window is hidden, –1 means window is shown).
Return Values

Returns an HRESULT value.

CBaseControlWindow::put_Width

CBaseControlWindow Class

Sets the window width.

HRESULT put_Width(
long Width
);

Parameters
Width
New window width, in pixels.
Return Values

Returns an HRESULT value.

Remarks

The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels and changing any coordinate will update the window immediately.

Setting the left or top coordinates moves the window left or up respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.

CBaseControlWindow::put_WindowState

CBaseControlWindow Class

Sets the window state.

HRESULT put_WindowState(
long WindowState
);

Parameters
WindowState
New window state.
Return Values

Returns an HRESULT value.

Remarks

This member function takes the same parameters as the Microsoft Win32 ShowWindow function (for example, WS_SHOWNORMAL, WS_SHOWMINNOACTIVATE, and WS_SHOWMAXIMIZED).

CBaseControlWindow::put_WindowStyle

CBaseControlWindow Class

Sets the standard Windows-based styles.

HRESULT put_WindowStyle(
long WindowStyle
);

Parameters
WindowStyle
New window styles.
Return Values

Returns an HRESULT value.

Remarks

Take care when changing the window styles. In most cases, an application should retrieve the current style and then add or remove the inappropriate bits. This procedure allows various internal window styles used by Windows® to remain intact.

CBaseControlWindow::put_WindowStyleEx

CBaseControlWindow Class

Sets the style of the control window.

HRESULT put_WindowStyleEx(
long WindowStyleEx
);

Parameters
WindowStyleEx
[in] Value that specifies the style of the control window.
Return Values

Returns NOERROR.

Remarks

This method uses EX (extended) window styles. For a complete list of extended window styles, see the Microsoft Win32 CreateWindowEx function. To change the window style, retrieve the current window style, and then add or remove the necessary bit fields.

Note: Do not use the following window styles because they are not validated.
WS_DISABLED
WS_HSCROLL
WS_ICONIC
WS_MAXIMIZE
WS_MINIMIZE
WS_VSCROLL

With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.

CBaseControlWindow::SetControlWindowPin

CBaseControlWindow Class

Sets the pin with which to synchronize.

void SetControlWindowPin(
CBasePin *pPin
);

Parameters
pPin
Pin with which the interface is synchronized.
Return Values

No return value.

Remarks

This member function sets the m_pPin variable equal to the pPin parameter. As described in the constructor, the interface can be called only when the filter has been connected successfully. The object is passed in through this member function to the pin with which it should synchronize; in most cases, it will determine if the pin is connected whenever it has an interface method called and will return VFW_E_NOT_CONNECTED if it fails.

CBaseControlWindow::SetWindowForeground

CBaseControlWindow Class

Moves the video window to the foreground and optionally gives it focus.

HRESULT SetWindowForeground(
long Focus
);

Parameters
Focus
Long value that specifies whether the video window will get focus. A value of –1 gives the window focus and 0 does not.
Return Values

Returns one of the following values.
Value | Meaning
NOERROR | The method succeeded.
E_INVALIDARG | Focus doesn't equal –1 or 0.
VFW_E_NOT_CONNECTED | The current filter isn't connected to a complete filter graph.

CBaseControlWindow::SetWindowPosition

CBaseControlWindow Class

Sets the window position on the desktop.

HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);

Parameters
Left
New left coordinate.
Top
New top coordinate.
Width
Width of the window.
Height
Height of the window.
Return Values

Returns an HRESULT value.


CBaseDispatch Class

CBaseDispatch class hierarchy

The CBaseDispatch class is a base class that implements the IDispatch interface for use in a dual interface. A dual interface provides Automation and custom interface access to an interface.

CMediaControl and CMediaPosition (and other dual-interface support classes) are derived from this class or have members that are instances of this class.

For more information about the IDispatch methods, see the COM documentation included with the Microsoft® Platform Software Development Kit (SDK).

Member Functions
Name | Description
CBaseDispatch | Constructs a CBaseDispatch object.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the IDispatch::Invoke method.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.

CBaseDispatch::CBaseDispatch

CBaseDispatch Class

Constructs a CBaseDispatch object.

CBaseDispatch( );

Return Values

No return value.

CBaseDispatch::GetIDsOfNames

CBaseDispatch Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the IDispatch::Invoke method.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Local context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an identifier that corresponds to one of the names passed in the rgszNames parameter. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
S_OK | Success.
E_OUTOFMEMORY | Out of memory.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
DISP_E_UNKNOWN_CLSID | The class identifier was not recognized.

CBaseDispatch::GetTypeInfo

CBaseDispatch Class

Retrieves a type-information object, which can retrieve the type information about an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Local identifier for the type information. An object can return different type information for different languages. This capability is important for classes that support localized member names. For classes that do not support localized member names, ignore this parameter.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK or NOERROR | Success.

CBaseDispatch::GetTypeInfoCount

CBaseDispatch Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.


CBaseFilter Class

CBaseFilter class hierarchy

CBaseFilter is an abstract base class from which all filters are derived. It supports the Component Object Model (COM) IBaseFilter interface and is derived from the CUnknown class. This class supports the enumeration of pins by calling the pure virtual member functions CBaseFilter::GetPin and GetPinCount. These member functions must be overridden by any derived class.

The CBaseFilter class assumes that all the filter's pins are derived from the CBasePin class. CBaseFilter::GetPin must return a pointer to CBasePin.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_clsid | Class identifier (CLSID) used for serialization using IPersist.
m_pClock | Filter graph's reference clock.
m_pGraph | Pointer to a graph to which this filter belongs.
m_PinVersion | Current version of the pins used on the filter.
m_pLock | Pointer to the critical section used for locking.
m_pName | Filter name.
m_pSink | Pointer to the IMediaEventSink interface on the filter graph manager.
m_State | Current state: running or paused.
m_tStart | Offset from the stream time to the reference time.

Member Functions
Name | Description
CBaseFilter | Constructs a CBaseFilter object.
GetFilterGraph | Returns the filter graph associated with the filter. This is used in the implementation of CEnumPins.
IncrementPinVersion | Adds 1 to the pin version stored in m_PinVersion.
IsActive | Determines if the filter is currently active (running or paused) or stopped.
NotifyEvent | Sends an event notification to the filter graph.
ReconnectPin | Requests pin for a reconnect.

Overridable Member Functions
Name | Description
GetPin | Returns a pointer to the requested pin.
GetPinCount | Returns the number of pins currently available on this object.
GetPinVersion | Returns the current version of the base filter for comparison with the version with which the pin was initialized. This member function can be overridden if pins are being created dynamically.
GetSetupData | Retrieves the registration data associated with the filter.
StreamTime | Returns the current stream time.

Implemented IPersist Methods
Name | Description
GetClassID | Returns the class identifier of this filter.

Implemented IMediaFilter Methods
Name | Description
GetState | Retrieves the current state of the filter.
GetSyncSource | Retrieves the current reference clock in use by this filter.
Pause | Instructs the filter to transition to State_Paused state.
Run | Instructs the filter to transition to State_Running state. Passes a time value to synchronize independent streams.
SetSyncSource | Informs the filter of the reference clock with which it should synchronize activity.
Stop | Instructs the filter to transition to the State_Stopped state.

Implemented IBaseFilter Methods
Name | Description
EnumPins | Provides an enumerator for this pin's preferred media types (implemented by this class).
FindPin | Retrieves the pin with the specified identifier.
JoinFilterGraph | Notifies a filter that it has joined a filter graph (implemented by this class).
QueryFilterInfo | Gets information about the specified filter (implemented by this class).
QueryVendorInfo | Retrieves optional information supplied by a vendor for the specified filter.

Implemented IAMovieSetup Methods
Name | Description
Register | Adds the filter to the registry.
Unregister | Removes the filter from the registry.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Passes out pointers to any interfaces added to the derived filter class.

CBaseFilter::CBaseFilter

CBaseFilter Class

Constructs a CBaseFilter object.

CBaseFilter(
TCHAR *pName,
LPUNKNOWN pUnk,
CCritSec *pLock,
REFCLSID clsid
);

Parameters
pName
Pointer to an object description.
pUnk
IUnknown interface of the delegating object.
pLock
Pointer to an object that maintains the lock.
clsid
Class identifier to be used to serialize this filter.
Return Values

No return value.

CBaseFilter::EnumPins

CBaseFilter Class

Retrieves an IEnumPins pointer that can be used to enumerate all the pins available on this filter.

HRESULT EnumPins(
IEnumPins ** ppEnum
);

Parameters
ppEnum
Pointer to the IEnumPins interface to retrieve.
Return Values

Returns E_OUTOFMEMORY if a new enumerate could not be created or NOERROR if successful.

Remarks

This member function implements the IBaseFilter::EnumPins method. It uses the CEnumPins object to construct an enumerator and retrieves the IEnumPins interface from the CEnumPins object. The implementation of CEnumPins::Next calls the CBaseFilter::GetPin member function, which the derived class must provide. The IEnumPins interface is used by the filter graph manager when adding the filter to the filter graph.

CBaseFilter::FindPin

CBaseFilter Class

Retrieves the pin with the specified identifier.

HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);

Parameters
Id
Identifier of the pin.
ppPin
Pointer to the IPin interface for this pin after the filter has been restored.
Return Values

The default implementation by this member function returns S_OK if the pin name was found or VFW_E_NOT_FOUND otherwise.

Remarks

This member function provides a base class definition of the IBaseFilter::FindPin method that, along with the IPin::QueryId method, is used to implement persistent filter graphs. A filter must be able to translate the IPin interface pointers to its pins into identifiers that can be saved along with the configuration of the filter graph. It does this by using the IPin::QueryId method. It must then be able to convert those identifiers back into IPin interface pointers when the filter and its connections are restored as part of a persistent filter graph. This is accomplished using the IBaseFilter::FindPin method.

By default, the base classes use the pin name in the CBasePin::m_pName data member, so implementing this member function in your derived filter class is not normally required.

The ppPin parameter is set to NULL if the identifier cannot be matched.

CBaseFilter::GetClassID

CBaseFilter Class

Fills the pClsID parameter with the class identifier of this filter (from m_clsid).

HRESULT GetClassID(
CLSID *pClsID
);

Parameters
pClsID
Pointer to the class identifier to be filled out.
Return Values

Return NOERROR.

CBaseFilter::GetFilterGraph

CBaseFilter Class

Retrieves the filter graph associated with the filter.

IFilterGraph *GetFilterGraph( );

Return Values

Returns the value of m_pGraph.

CBaseFilter::GetPin

CBaseFilter Class

Retrieves a CBasePin object on the filter.

virtual CBasePin *GetPin(
int n
) PURE;

Parameters
n
Number of the specified pin.
Return Values

Returns a pointer to the pin specified by the n parameter.

Remarks

Override this member function to return a pointer to the nth pin on this filter. CBaseFilter adds a reference to it, when necessary, before passing it to any other object. This member function is called by the base class CEnumPins::Next member function to retrieve pins for the IEnumPins interface, which is used by the filter graph manager.

CBaseFilter::GetPinCount

CBaseFilter Class

Retrieves the number of supported pins.

virtual int GetPinCount( ) PURE;

Return Values

Returns the pin count.

Remarks

Override this member function to return the count of pins currently available on this object.

CBaseFilter::GetPinVersion

CBaseFilter Class

Retrieves the version number of the pin.

virtual long GetPinVersion( );

Return Values

By default, returns the value of m_PinVersion. If overridden, this member function should return the pin version number.

Remarks

Returns the current version of the filter that matches the version used to initialize the pin. The enumerator calling this member function performs the matching.

A filter provides an enumerator to gain access to the input and output pins it keeps. Each time a pin enumerator's method is called, the pin enumerator calls the CBaseFilter::GetPinVersion member function to ensure that the base filter's version matches the version with which the pin enumerator was initialized.

A filter class can override CBaseFilter::GetPinVersion if there is a need to increment the version by changing the available pins dynamically. Or, it can more easily call IncrementPinVersion.

GetPinVersion does not lock the filter because the enumerators are designed to be separate objects. The derived class's GetPinVersion will likely have to do some specialized locking with the part of the object responsible for creating and deleting pins.

CBaseFilter::GetSetupData

CBaseFilter Class

Retrieves the registration data associated with the filter.

virtual LPAMOVIESETUP_FILTER GetSetupData( );

Return Values

Returns a pointer to an AMOVIESETUP_FILTER structure containing registration information for the filter.

Remarks

You must override this member function and implement it to return an AMOVIESETUP_FILTER structure containing its associated AMOVIESETUP_PIN and AMOVIESETUP_MEDIATYPE structures for pin and media type information. This member function is called from the CBaseFilter::Register member function.

CBaseFilter::GetState

CBaseFilter Class

Retrieves the current state of the filter.

HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);

Parameters
dwMilliSecsTimeout
Duration of the time-out, in milliseconds.
State
Holds the returned state of the filter.
Return Values

Returns S_OK.

Remarks

This member function implements the IMediaFilter::GetState method. It returns the value of the m_State data member. Override this member function if the state changes in your filter are not synchronous.

CBaseFilter::GetSyncSource

CBaseFilter Class

Retrieves the current reference clock in use by this filter.

HRESULT GetSyncSource(
IReferenceClock ** pClock
);

Parameters
pClock
Pointer to a reference clock; will be set to the IReferenceClock interface.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaFilter::GetSyncSource method. It returns the value of m_pClock after adding a reference to it. Be sure to release the interface by calling the IUnknown::Release method when finished with the pointer.

CBaseFilter::IncrementPinVersion

CBaseFilter Class

Adds 1 to the version number of the pin.

void IncrementPinVersion( );

Return Values

No return value.

Remarks

By default, increments the value of m_PinVersion.

CBaseFilter::IsActive

CBaseFilter Class

Determines if the filter is currently active (running or paused) or stopped.

BOOL IsActive(void);

Return Values

Returns TRUE if the filter is paused or running, or FALSE if the filter is stopped.

CBaseFilter::JoinFilterGraph

CBaseFilter Class

Notifies a filter that it has joined a filter graph.

HRESULT JoinFilterGraph(
IFilterGraph * pGraph,
LPCWSTR pName
);

Parameters
pGraph
Pointer to the filter graph to join.
pName
[in, string] Name of the filter being added.
Return Values

No return value.

Remarks

This member function implements the IBaseFilter::JoinFilterGraph method. It assigns the pGraph filter graph pointer to the m_pGraph data member and obtains the IMediaEventSink interface from the filter graph manager to allow the filter to post event notifications to the filter graph manager.

The filter should store the IMediaEventSink interface for later use, because it might need to notify the interface about events, but it should not increase the reference count on the filter graph manager object. A null pointer indicates that the filter is no longer part of a graph.

CBaseFilter::NonDelegatingQueryInterface

CBaseFilter Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IBaseFilter, IMediaFilter, IPersist, IAMovieSetup, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CBaseFilter::NotifyEvent

CBaseFilter Class

Sends an event notification to the filter graph.

HRESULT NotifyEvent(
long EventCode,
long EventParam1,
long EventParam2
);

Parameters
EventCode
Identifier of the event.
EventParam1
First parameter of the event.
EventParam2
Second parameter of the event.
Return Values

Returns S_OK if delivered, S_FALSE if the filter graph does not sink events, or an error otherwise.

Remarks

For a list of notification codes and event parameter values, see Event Notification Codes.

CBaseFilter::Pause

CBaseFilter Class

Transitions the filter to State_Paused state if it is not in this state already.

HRESULT Pause (void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaFilter::Pause method. If the filter is in State_Stopped state, the CBasePin::Active member function is called for each of the filter's pins to which it is connected. If this member function succeeds, the filter's m_State member variable is set to State_Paused. If any pin returns a failure return value from its Active method, the function fails and the state is not changed.

This member function holds the filter's lock.

CBaseFilter::QueryFilterInfo

CBaseFilter Class

Retrieves information about the filter.

HRESULT QueryFilterInfo(
FILTER_INFO * pInfo
);

Parameters
pInfo
Pointer to a FILTER_INFO structure to fill in.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IBaseFilter::QueryFilterInfo method. It copies the filter's name from m_pName, and copies the pointer to the filter graph interface from m_pGraph into the FILTER_INFO structure before returning.

Note that the IFilterGraph interface passed out by this member function is reference counted, and so must be released when the caller has finished with it.

CBaseFilter::QueryVendorInfo

CBaseFilter Class

Retrieves a vendor information string.

HRESULT QueryVendorInfo(
LPWSTR * pVendorInfo
);

Parameters
pVendorInfo
Pointer to a string containing vendor information.
Return Values

Returns an HRESULT value (E_NOTIMPL by default).

Remarks

This member function implements the IBaseFilter::QueryVendorInfo method, but only to return E_NOTIMPL. Filters that want to expose vendor information must override this member function. If implemented in a derived class, callers should free memory when they are done using it by calling the Microsoft® Win32® CoTaskMemFree function.

CBaseFilter::ReconnectPin

CBaseFilter Class

Requests pin for a reconnect.

HRESULT ReconnectPin(
IPin *pPin,
AM_MEDIA_TYPE const *pmt
);

Parameters
pPin
Pointer to the pin to reconnect.
pmt
AM_MEDIA_TYPE media type to reconnect with. This can be NULL.
Return Values

Returns an HRESULT value.

Remarks

This function calls the IFilterGraph2::ReconnectEx method on the filter graph.

CBaseFilter::Register

CBaseFilter Class

Adds the filter to the registry.

HRESULT Register( );

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IAMovieSetup::Register method and registers the filter, its pins, and the media type associated with the pins. It does this by first calling GetSetupData to retrieve the setup data, and then calling the IFilterMapper::RegisterFilter, IFilterMapper::RegisterPin, and IFilterMapper::RegisterPinType methods.

CBaseFilter::Run

CBaseFilter Class

Transitions the filter from paused to running state if it is not in this state already.

HRESULT Run (
REFERENCE_TIME tStart
);

Parameters
tStart
Reference time value corresponding to stream time 0.
Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

If the filter is in State_Stopped state, the CBaseFilter::Pause method is called first to transition the filter to State_Paused state, which has the effect of activating any of the filter's connected pins. If any pin returns a failure return code from its Active method, the function fails and the state is not changed. If this member function succeeds, the filter's m_State member variable is set to State_Running.

This member function holds the filter's lock.

CBaseFilter::SetSyncSource

CBaseFilter Class

Identifies the reference clock to which the filter should synchronize activity.

HRESULT SetSyncSource (
IReferenceClock * pClock
);

Parameters
pClock
Pointer to the IReferenceClock interface.
Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function implements the IMediaFilter::SetSyncSource method. It sets the m_pClock data member to the pClock parameter and increments the reference count on the IReferenceClock interface passed in.

This member function is most important to rendering filters and might not apply to other filters.

CBaseFilter::Stop

CBaseFilter Class

Transitions the filter to State_Stopped state if it is not in this state already.

HRESULT Stop(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaFilter::Stop method. It first calls the CBasePin::Inactive member function on all its pins that have a connection, and then sets the filter's m_State member variable to State_Stopped.

This member function holds the filter's lock.

CBaseFilter::StreamTime

CBaseFilter Class

Retrieves the current stream time.

virtual HRESULT StreamTime(
CRefTime& rtStream
);

Parameters
rtStream
Current stream time.
Return Values

Returns an HRESULT value, which can include the following values.
Value | Meaning
E_FAIL | Unable to get time from clock.
S_OK | Stream time returned in the rtStream parameter.
VFW_E_NO_CLOCK | No reference clock is available.

Remarks

Current stream time is the reference clock time minus the stream time offset. All samples with time stamps less than or equal to this time should have been presented.

CBaseFilter::Unregister

CBaseFilter Class

Removes the filter from the registry.

HRESULT Unregister( );

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IAMovieSetup::Unregister method and calls the IFilterMapper::UnregisterFilter method to remove the filter from the registry. This effectively removes the pins and media types as well.


CBaseInputPin Class

CBaseInputPin class hierarchy

CBaseInputPin is an abstract base class derived from CBasePin that adds support for IMemInputPin in addition to the IPin interface support provided by CBasePin. Its IMemInputPin::GetAllocator method returns a CMemAllocator object. Derive your input pin from this class.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_bFlushing | In the state of flushing; if TRUE, all IMemInputPin::Receive methods are returned with S_FALSE.
m_bReadOnly | If TRUE, indicates that the allocator being used contains samples that are read-only.
m_pAllocator | Pointer to the default memory allocator.

Member Functions
Name | Description
CBaseInputPin | Constructs a CBaseInputPin object.
IsReadOnly | Checks the m_bReadOnly data member and returns its value.
IsFlushing | Checks the m_bFlushing data member and returns its value.
PassNotify | Passes a quality-control notification to the appropriate sink.

Overridable Member Functions
Name | Description
CheckStreaming | Verifies conditions for continuing with a streaming operation.
Inactive | Switches the pin to an inactive state.

Implemented IPin Methods
Name | Description
BeginFlush | Informs the pin to begin a flush operation.
Disconnect | Releases the stored allocator.
EndFlush | Informs the pin to end a flush operation.

Implemented IMemInputPin Methods
Name | Description
GetAllocator | Returns the allocator interface that this input pin would like the output pin to use.
GetAllocatorRequirements | Indicates an optional method to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.
NotifyAllocator | Tells the input pin which allocator the output pin is actually going to use.
Receive | Returns the next block of data from the stream. (Override this method to process a sample being passed in.)
ReceiveCanBlock | Determines if sending an IMemInputPin::Receive method might block.
ReceiveMultiple | Returns the next block of data from the stream. (Override this method to process samples being passed in.)

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Retrieves an interface from the subobject, not the aggregated object.

Implemented IQualityControl Methods
Name | Description
Notify | Notifies the recipient that a quality-control change is requested. (Override on the output pin only. This implementation returns NOERROR.)

CBaseInputPin::BeginFlush

CBaseInputPin Class

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::BeginFlush method. When this method is called, the pin is entering flush state. You must override this method in your derived class, but you should call this base class first in your implementation, because it sets m_bFlushing so that no more IMemInputPin::Receive calls will succeed.

The overriding member function should then carry out the following steps.

  1. Discard any queued data.
  2. Free any pin blocked by the Receive method.
  3. Pass the IPin::BeginFlush method to any downstream pins.

IPin::BeginFlush is not logically part of the media stream and can be optimized in the sense that if a pin has passed no data downstream before this method is called, there is no need to pass this notification on.

An example of an overriding implementation of this member function can be found in the CTransformInputPin::BeginFlush member function, which uses the CBaseOutputPin::DeliverBeginFlush member function to perform the last step.

CBaseInputPin::CBaseInputPin

CBaseInputPin Class

Constructs a CBaseInputPin object.

CBaseInputPin::CBaseInputPin(
TCHAR *pObjectName,
CBaseFilter *pFilter,
CCritSec *pLock,
HRESULT *phr,
LPCWSTR pPinName
);

Parameters
pObjectName
Name of the class object.
pFilter
Pointer to the filter that owns this pin.
pLock
Pointer to the CCritSec critical section object used to lock the pin.
phr
Pointer to the general COM return value. This value is changed only if this function fails.
pPinName
Name of the pin.
Return Values

No return value.

CBaseInputPin::CheckStreaming

CBaseInputPin Class

Verifies conditions for continuing with a streaming operation.

virtual HRESULT CheckStreaming( );

Return Values

Returns one of the following HRESULT values, depending on the state.
Value | Meaning
S_FALSE | Currently in flushing state.
S_OK | Receive or EndOfStream operations can safely proceed.
VFW_E_RUNTIME_ERROR | Run-time error occurred while processing a previous sample.
VFW_E_WRONG_STATE | Filter is in the State_Stopped state.

Remarks

Conditions checked in this member function include whether the filter is connected, if it is in an active state, if it is not currently flushing data, and if it has not just issued a run-time error. If all these conditions pass, it returns S_OK.

You can override this member function to add restrictions defined by your derived class. The overriding member function should call this base class implementation to check for conditions here as well.

This function member should be called from any override of the CBaseInputPin::Receive or CBasePin::EndOfStream member function (or they should do some equivalent check).

CBaseInputPin::Disconnect

CBaseInputPin Class

Releases the stored allocator.

HRESULT Disconnect( );

Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBasePin::Disconnect member function. It calls CBasePin::Disconnect first, and then releases the allocator held by m_pAllocator.

CBaseInputPin::EndFlush

CBaseInputPin Class

Informs the pin to end a flush operation and notifies the pin that it can start accepting data again.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndFlush method. When this method is called, the pin is beginning to end a flush operation. Your derived class must override this member function, but should call this member function at the end of your implementation to clear m_bFlushing so that IMemInputPin::Receive calls will succeed.

Before calling this base class implementation, your overriding member function should perform the following steps.

  1. Ensure that your filter will not push any additional data. (To do this, synchronize with a thread, stop it pushing, and discard any queued data.)
  2. Pass the EndFlush method downstream by calling the method on the downstream filter's input pin.

IPin::EndFlush is not logically part of the media stream. It can be optimized in the sense that if a pin has passed no data downstream before this method is called, there is no need to pass this notification on.

An example of an overriding implementation of this member function can be found in the CTransformInputPin::EndFlush member function, which uses the CBaseOutputPin::DeliverEndFlush member function to perform the last step.

CBaseInputPin::GetAllocator

CBaseInputPin Class

Retrieves the allocator interface that this input pin identifies as the interface for the output pin to use.

HRESULT GetAllocator(
IMemAllocator ** ppAllocator
);

Parameters
ppAllocator
Pointer to an obtained IMemAllocator object.
Return Values

Default implementation returns either E_OUTOFMEMORY, if an allocator cannot be created, or NOERROR upon success.

Remarks

This member function implements the IMemInputPin::GetAllocator method, which is called by the connected output pin to retrieve an allocator to use for transporting media samples. By default, this member function creates a CMemAllocator object and obtains the IMemAllocator interface, to which it adds a reference count for the pin when assigning it to the m_pAllocator data member, and adds another reference count before passing it back to the output pin.

Override this member function if your filter has another allocator, such as one from a downstream pin, or a specialized allocator to offer the connected output pin.

CBaseInputPin::GetAllocatorRequirements

CBaseInputPin Class

Optional member function to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.

HRESULT GetAllocatorRequirements(
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pProps
ALLOCATOR_PROPERTIES structure containing the required size, count, and alignment of the allocator.
Return Values

Returns an HRESULT value. Returns E_NOTIMPL by default.

Remarks

Override this member function if you have specific alignment or prefix requirements but could use an upstream allocator.

CBaseInputPin::Inactive

CBaseInputPin Class

Releases the allocator's memory.

HRESULT Inactive(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called through IMediaFilter, which is responsible for locking the object first.

CBaseInputPin::IsFlushing

CBaseInputPin Class

Checks the m_bFlushing data member and returns its value.

BOOL IsFlushing(void);

Return Values

Returns TRUE if the input pin is flushing data; otherwise, returns FALSE.

CBaseInputPin::IsReadOnly

CBaseInputPin Class

Checks the m_bReadOnly data member and returns its value.

BOOL IsReadOnly(void);

Return Values

Returns TRUE if the allocator has read-only samples; otherwise, returns FALSE.

CBaseInputPin::NonDelegatingQueryInterface

CBaseInputPin Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMemInputPin and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CBaseInputPin::Notify

CBaseInputPin Class

Notifies the recipient that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

Parameters
pSelf
Pointer to the filter that is sending the quality notification.
q
Quality notification structure.
Return Values

Returns NOERROR by default.

Remarks

The IQualityControl::Notify method is usually implemented on the output pin, because quality-control messages are passed upstream, and not on the input pin.

CBaseInputPin::NotifyAllocator

CBaseInputPin Class

Notifies the input pin as to which allocator the output pin is actually going to use.

HRESULT NotifyAllocator(
IMemAllocator * pAllocator,
BOOL bReadOnly
);

Parameters
pAllocator
Pointer to the IMemAllocator object to use. This might or might not be the same IMemAllocator object that the input pin provided in the IMemInputPin::GetAllocator method (the output pin could provide its own allocator).
bReadOnly
Flag to indicate if the samples from this allocator are read-only.
Return Values

Default implementation returns NOERROR.

Remarks

This member function implements the IMemInputPin::NotifyAllocator method, which is called by the connected output pin to inform the input pin of the chosen allocator for the memory transport. Override this member function if your filter cares about this information. By default, this sets the m_pAllocator data member to the allocator interface passed in after adding a reference count to that interface.

CBaseInputPin::PassNotify

CBaseInputPin Class

Passes a quality-control notification to the appropriate sink.

HRESULT PassNotify(
Quality q
);

Parameters
q
Quality-control notification object.
Return Values

Returns VFW_E_NOT_FOUND if no quality sink is set and the upstream filter does not support the IQualityControl interface. Otherwise, returns the HRESULT value resulting from notifying the sink or the upstream filter.

Remarks

Output pins receive quality-control notifications and, if possible, filters act on them to degrade appropriately. Often, filters cannot respond to the notifications; in this case the notification should be passed to the quality-control sink or, by default, upstream to the next filter. The PassNotify member function is called from the CTransformOutputPin::Notify member function when a notification requires passing. The Quality structure passed is the one that the output pin received.

CBaseInputPin::Receive

CBaseInputPin Class

Retrieves the next block of data from the stream.

HRESULT Receive(
IMediaSample * pSample
);

Parameters
pSample
Pointer to a media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::Receive method. It first checks that it can process the sample by calling CBaseInputPin::CheckStreaming; if that member function does not return S_OK, Receive returns immediately with the value returned by CBaseInputPin::CheckStreaming.

This base class member function checks to see if the format has changed with this media sample; if so, it checks that the filter will accept it, generating a run-time error if not. If a run-time error is raised, the m_bRunTimeError data member is set so that no more samples will be accepted.

The overriding member function does something with the passed-in sample, such as calling a member function to transform it or pass it downstream.

This is a blocking synchronous call. Typically no blocking occurs, but if a filter cannot process the sample immediately, it can use the calling application's thread to wait until it can.

Call the IUnknown::AddRef method if you must hold the returned data block beyond the completion of the IMemInputPin::Receive method. If you call AddRef, be sure to call IUnknown::Release when done with it.

CBaseInputPin::ReceiveCanBlock

CBaseInputPin Class

Determines if the implementation of the IMemInputPin::Receive method might block on the connected output pin.

HRESULT ReceiveCanBlock(void);

Return Values

Returns an HRESULT value, which can include one of the following values.
Value | Meaning
S_FALSE | Input pin will not block on a Receive method.
S_OK | Input pin might block on a Receive method.

Remarks

This member function implements the IMemInputPin::ReceiveCanBlock method. The base class implementation calls the IMemInputPin::ReceiveCanBlock method on the input pin connected to each of the filter's output pins.

This member function is useful because an output pin from a filter might require notification if its thread might be blocked when it calls the Receive method on the connected input pin. For example, a source filter might prefer to keep reading and buffering data rather than be blocked, and might choose to start another thread to wait on the blocking Receive method. See the COutputQueue base class for queuing samples to input pins that potentially block.

CBaseInputPin::ReceiveMultiple

CBaseInputPin Class

Retrieves the next block of data from the stream. This method behaves much like the IMemInputPin::Receive method, but it works with multiple samples. Override this function if you can usefully process samples in batches.

HRESULT ReceiveMultiple(
IMediaSample ** pSamples,
long nSamples,
long * nSamplesProcessed
);

Parameters
pSamples
Pointer to an array of samples.
nSamples
Number of samples to process.
nSamplesProcessed
Number of samples processed.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::ReceiveMultiple method. It is implemented to call the CBaseInputPin::Receive member function in a loop for nSamples number of iterations.


CBaseList Class

CBaseList class hierarchy

The CBaseList class represents a list of pointers to objects. No storage management or copying is done on the objects that are pointed to.

The implementation allows for objects to be on multiple lists simultaneously and does not require support in the objects themselves; therefore, it is particularly useful for holding variable-length lists of interface pointers.

The implementation is not multithread safe. External locks are required to maintain the integrity of the list when it is accessed from more than one thread simultaneously.

The POSITION structure represents a position in a linked list that is actually a void pointer. A position represents a cursor on the list that can be set to identify any element. NULL is a valid value, and several operations regard NULL as the position that is "one step off the end of the list." (In an n element list there are n+1 places to insert, and NULL is that n+1 value.) The position of an element in the list is only invalidated if that element is deleted. Move operations might indicate that what was a valid position in one list is now a valid position in a different list.

Some operations, which at first sight seem illegal, are allowed as harmless null operations (no-ops). For example, the CBaseList::RemoveHeadI member function is legal on an empty list, and it returns NULL. This allows an atomic way to test if there is an element there and, if so, to retrieve it.

Single-element operations return positions, where a non-NULL value indicates that it worked. Entire list operations return a Boolean value, where TRUE indicates success.

Protected Data Members
Name | Description
m_Count | Number of nodes in the list.
m_pFirst | Pointer to the first node in the list.
m_pLast | Pointer to the last node in the list.

Member Functions
Name | Description
AddAfter | Inserts a list of nodes after the specified node.
AddAfterI | Inserts a node after the specified node.
AddBefore | Inserts a list of nodes before the specified node.
AddBeforeI | Inserts a node before the specified node.
AddHead | Inserts a list of nodes at the front of the list.
AddHeadI | Inserts a node at the front of the list.
AddTail | Appends a list of nodes to the end of the list.
AddTailI | Appends a node to the end of the list.
CBaseList | Constructs a CBaseList object.
FindI | Returns the first position that holds the specified object.
GetCountI | Returns the number of objects in the list.
GetHeadPositionI | Returns a cursor identifying the first element of the list.
GetI | Returns the object at the specified position.
GetNextI | Returns the specified object and updates the position.
GetTailPositionI | Returns a cursor identifying the last element of the list.
MoveToHead | Moves the node or list of nodes to the beginning of a second list.
MoveToTail | Moves the node or list of nodes to the end of a second list.
Next | Returns the next position in the list.
Prev | Returns the previous position in the list.
RemoveAll | Removes all nodes from the list.
RemoveHeadI | Removes the first node in the list.
RemoveI | Removes the specified node from the list.
RemoveTailI | Removes the last node in the list.
Reverse | Reverses the order of the pointers to the objects in the list.

CBaseList::AddAfter

CBaseList Class

Inserts a list of nodes after the specified node.

BOOL AddAfter(
POSITION pos,
CBaseList *pList
);

Parameters
pos
Position after which to add the list of nodes.
pList
Pointer to the list of objects to add.
Return Values

Returns TRUE if successful; otherwise, returns FALSE.

CBaseList::AddAfterI

CBaseList Class

Inserts a node after the specified node.

POSITION AddAfterI(
POSITION pos,
void * pObj
);

Parameters
pos
Position after which to add the node.
pObj
Pointer to the object to add.
Return Values

Returns the position of the inserted object.

Remarks

The following member function adds x to the start, which is equivalent to calling the CBaseList::AddHeadI member function:

AddAfterI(NULL,x)

If the list insertion fails, some of the elements might have been added. Existing positions in the list, including the position specified in the pos parameter, remain valid. The following two member functions are equivalent even in cases where pos is NULL or the Next(p) parameter is NULL. (This is similar for the mirror case.)

AddAfterI (p,x)
AddBeforeI(Next(p),x)

CBaseList::AddBefore

CBaseList Class

Inserts a list of nodes before the specified node.

BOOL AddBefore(
POSITION pos,
CBaseList *pList
);

Parameters
pos
Position before which to add the list of nodes.
pList
Pointer to the list of objects to add.
Return Values

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

If the list insertion fails, some of the elements might have been added. Existing positions in the list, including the position specified in the pos parameter, remain valid.

CBaseList::AddBeforeI

CBaseList Class

Inserts a node before the specified node.

POSITION AddBeforeI(
POSITION pos,
void * pObj
);

Parameters
pos
Position before which to add the node or list of nodes.
pObj
Pointer to the object to add.
Return Values

Returns the position of the inserted object.

Remarks

The following member function adds the value specified in the x parameter to the end, which is equivalent to calling the CBaseList::AddTailI member function:

AddBeforeI(NULL,x)

The following two member functions are equivalent even in cases where pos is NULL or the Next(p) parameter is NULL. (This is similar for the mirror case.)

AddAfterI(p,x)
AddBeforeI(Next(p),x)

CBaseList::AddHead

CBaseList Class

Inserts a list of nodes at the front of the list.

BOOL AddHead(
CBaseList *pList
);

Parameters
pList
Pointer to the list of objects to add.
Return Values

No return value.

Remarks

If you are adding Component Object Model (COM) objects, you might want to add references to them (using the IUnknown::AddRef method) first. Other existing positions in the list remain valid.

This member function duplicates all the nodes in the pList parameter (that is, duplicates all its pointers to objects). It does not duplicate the objects.

CBaseList::AddHeadI

CBaseList Class

Inserts a node at the front of the list.

POSITION AddHeadI(
void * pObj
);

Parameters
pObj
Pointer to the object to add.
Return Values

Returns the new head position, or NULL if it fails. For list insertions, returns TRUE if successful; otherwise, returns FALSE.

Remarks

If you are adding Component Object Model (COM) objects, you might want to add references to them (using the IUnknown::AddRef method) first. Other existing positions in the list remain valid.

CBaseList::AddTail

CBaseList Class

Appends a list of nodes to the end of the list.

BOOL AddTail(
CBaseList *pList
);

Parameters
pList
Pointer to the list of objects to add.
Return Values

No return value.

Remarks

This member function duplicates all the nodes in pList (that is, duplicates all its pointers to objects). It does not duplicate the objects. Existing positions in the list remain valid.

CBaseList::AddTailI

CBaseList Class

Appends a single node to the end of the list.

POSITION AddTailI(
void * pObj
);

Parameters
pObj
Pointer to the object to add.
Return Values

Returns the new tail position, if successful; otherwise, returns NULL.

CBaseList::CBaseList

CBaseList Class

Constructs a CBaseList object.

CBaseList(
TCHAR *pName,
INT iItems
);

CBaseList(
TCHAR *pName
);

Parameters
pName
Name of the list.
iItems
Number of items in the list.
Return Values

No return value.

CBaseList::FindI

CBaseList Class

Retrieves the first position that holds the specified object.

POSITION FindI(
void * pObj
);

Parameters
pObj
Pointer to the object to find.
Return Values

Returns a position cursor.

Remarks

A position cursor identifies an element on the list. Use the CBaseList::GetI member function to return the object at this position.

CBaseList::GetCountI

CBaseList Class

Retrieves the number of objects (object count) in the list.

int GetCountI( );

Return Values

Returns the number of objects in the list.

CBaseList::GetHeadPositionI

CBaseList Class

Retrieves a cursor identifying the first element of the list.

POSITION GetHeadPositionI( );

Return Values

Returns a position cursor.

Remarks

A position cursor represents an element on the list. It is defined as a pointer to a void.

CBaseList::GetI

CBaseList Class

Retrieves the object at the specified position.

void *GetI(
POSITION pos
);

Parameters
pos
Position in the list from which to retrieve the object.
Return Values

Returns a pointer to the object as position pos.

Remarks

Use the CBaseList::Next, CBaseList::Prev, or CBaseList::FindI member function to obtain the position. Asking for the object at a NULL position returns NULL without generating an error.

CBaseList::GetNextI

CBaseList Class

Retrieves the specified object and updates the position.

void *GetNextI(
POSITION& rp
);

Parameters
rp
Returned pointer to the next object.
Return Values

Returns a pointer to an object at the next position.

Remarks

This member function updates the rp parameter to the next node in the list, but makes it NULL if it was at the end of the list.

This member function is retained only for backward compatibility. (GetPrev is not implemented.)

Use the CBaseList::Next and CBaseList::Prev member functions to access the next or previous object in the list.

CBaseList::GetTailPositionI

CBaseList Class

Retrieves a cursor identifying the last element of the list.

POSITION GetTailPositionI( );

Return Values

Returns a position cursor.

Remarks

A position cursor represents an element on the list. A position is defined as a pointer to a void.

CBaseList::MoveToHead

CBaseList Class

Moves the node or list of nodes to the beginning of a second list.

BOOL MoveToHead(
POSITION pos,
CBaseList *pList
);

Parameters
pos
Position that marks the split in the list.
pList
List in which to add the section of the list preceding the position passed in the pos parameter.
Return Values

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function splits the current list after the position specified in the pos parameter in the list and retains the head portion of the original list. It then adds the tail portion to the head of the second list, identified by the pList parameter.

CBaseList::MoveToTail

CBaseList Class

Moves the node or list of nodes to the end of a second list.

BOOL MoveToTail(
POSITION pos,
CBaseList *pList
);

Parameters
pos
Position that marks the split in the list.
pList
List in which to add the section of the list specified in the pos parameter.
Return Values

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function splits the current list after the position specified in the pos parameter in the list and retains the tail portion of the original list. It then adds the head portion to the tail end of the second list, using the pList parameter.

CBaseList::Next

CBaseList Class

Retrieves the next position in the list.

POSITION Next(
POSITION pos
);

Parameters
pos
Current position in the list.
Return Values

Returns a position cursor.

Remarks

This member function returns NULL when going past the beginning of the list. Calling the CBaseList::Next member function with a null value is similar to calling the CBaseList::GetHeadPositionI member function.

Use the CBaseList::GetI member function to return the object at the returned position.

CBaseList::Prev

CBaseList Class

Retrieves the previous position in the list.

POSITION Prev(
POSITION pos
);

Parameters
pos
Current position in the list.
Return Values

Returns a position cursor.

Remarks

This member function returns NULL when going past the end of the list. Calling the CBaseList::Prev member function with a null value is similar to calling the CBaseList::GetTailPositionI member function.

Use the CBaseList::GetI member function to return the object at the returned position.

CBaseList::RemoveAll

CBaseList Class

Removes all nodes from the list.

void RemoveAll( );

Return Values

No return value.

CBaseList::RemoveHeadI

CBaseList Class

Removes the first node in the list.

void *RemoveHeadI( );

Return Values

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object itself.

If the list was already empty, this member function harmlessly returns NULL.

CBaseList::RemoveI

CBaseList Class

Removes the specified node from the list.

void *RemoveI(
POSITION pos
);

Parameters
pos
Position in the list of the node to remove.
Return Values

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object itself.

If the list was already empty, this member function harmlessly returns NULL.

CBaseList::RemoveTailI

CBaseList Class

Removes the last node in the list.

void *RemoveTailI( );

Return Values

Returns the pointer to the object that was removed.

Remarks

This member function deletes the pointer to its object from the list, but does not free the object.

If the list was already empty, this member function harmlessly returns NULL.

CBaseList::Reverse

CBaseList Class

Reverses the order of the pointers to the objects in the list.

void Reverse( );

Return Values

No return value.


CBaseMediaFilter Class

CBaseMediaFilter class hierarchy

This is an abstract base class that provides support for the IMediaFilter interface. The CBaseMediaFilter class handles State_Stopped, State_Paused, and State_Running state transitions. Typically, this class is used for plug-in distributors rather than filters with pins. Derive your filter classes from the CBaseFilter class (or base classes derived from this) instead of from this class.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_clsid | Class identifier (CLSID) used for serialization using IPersist.
m_pClock | Pointer to a reference clock used for synchronization. The reference count of the clock object must be incremented using AddRef. Pass NULL if no reference clock is available.
m_State | Current state of the filter, which can be State_Stopped, State_Paused, or State_Running.
m_tStart | Offset from the stream time to the reference time.

Member Functions
Name | Description
CBaseMediaFilter | Constructs a CBaseMediaFilter object.
IsActive | Determines if the filter is currently active (running or paused) or stopped.

Overridable Member Functions
Name | Description
StreamTime | Returns the current stream time.

Implemented IPersist Methods
Name | Description
GetClassID | Returns the class identifier of this filter.

Implemented IMediaFilter Methods
Name | Description
GetState | Retrieves the current state of the filter.
GetSyncSource | Retrieves the current reference clock in use by this filter.
Pause | Instructs the filter to transition to the new (paused) state.
Run | Instructs the filter to transition to the new (running) state.
SetSyncSource | Informs the filter of the reference clock with which it should synchronize activity.
Stop | Instructs the filter to transition to the new (stopped) state.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Passes out references to interfaces supported by CBaseFilter. Override this to pass out pointers to interfaces supported in a derived filter class.

CBaseMediaFilter::CBaseMediaFilter

CBaseMediaFilter Class

Constructs a CBaseMediaFilter object.

CBaseMediaFilter(
TCHAR *pName,
LPUNKNOWN pUnk,
CCritSec *pLock,
REFCLSID clsid
);

Parameters
pName
Name of the CBaseMediaFilter class.
pUnk
IUnknown interface of the delegating object.
pLock
Pointer to the object that maintains the lock.
clsid
Class identifier used to serialize this filter.
Return Values

No return value.

CBaseMediaFilter::GetClassID

CBaseMediaFilter Class

Fills the pClsID parameter with the class identifier of this filter (from m_clsid).

HRESULT GetClassID(
CLSID *pClsID
);

Parameters
pClsID
Pointer to the class identifier to be filled out.
Return Values

Returns an HRESULT value.

CBaseMediaFilter::GetState

CBaseMediaFilter Class

Retrieves the current state of the filter.

HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);

Parameters
dwMilliSecsTimeout
Duration of the time-out, in milliseconds.
State
Returned state of the filter.
Return Values

Returns S_OK.

Remarks

This member function implements the IMediaFilter::GetState method. It returns the value of the m_State data member.

Filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so filters will not likely use this member function. Use CBaseFilter::GetState instead.

CBaseMediaFilter::GetSyncSource

CBaseMediaFilter Class

Retrieves the current reference clock in use by this filter.

HRESULT GetSyncSource(
IReferenceClock ** pClock
);

Parameters
pClock
Pointer to a reference clock; will be set to the IReferenceClock interface.
Return Values

Returns an HRESULT value

Remarks

This member function implements the IMediaFilter::GetSyncSource method. It returns the value of m_pClock after adding a reference to it. Be sure to release the interface by calling the IUnknown::Release method when finished with the pointer.

Filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so filters will not likely use this member function. Use CBaseFilter::GetSyncSource instead.

CBaseMediaFilter::IsActive

CBaseMediaFilter Class

Determines if the filter is currently active (running or paused) or stopped.

BOOL IsActive(void);

Return Values

Returns TRUE if the filter is paused or running, or FALSE if it is stopped.

CBaseMediaFilter::NonDelegatingQueryInterface

CBaseMediaFilter Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMediaFilter, IPersist, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CBaseMediaFilter::Pause

CBaseMediaFilter Class

Transitions the filter to State_Paused state if it is not in this state already.

HRESULT Pause (void);

Return Values

Returns an HRESULT return value (S_OK by default).

Remarks

This member function implements the IMediaFilter::Pause method. It sets the value of m_State to State_Paused.

Note that filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so this member function will not likely be used by filters. Use CBaseFilter::Pause instead.

CBaseMediaFilter::Run

CBaseMediaFilter Class

Transitions the filter to State_Running state if it is not in this state already.

HRESULT Run (
REFERENCE_TIME tStart
);

Parameters
tStart
Reference time value corresponding to stream time 0.
Return Values

Returns an HRESULT value.

Remarks

If the filter is in State_Stopped state, the CBaseMediaFilter::Pause member function is called first to transition the filter to State_Paused state, which has the effect of activating any of the filter's connected pins. If any pin returns a failure return code from its CBasePin::Active member function, the function fails and the state is not changed. If this member function succeeds, the filter's m_State member variable is set to State_Running. This member function holds the filter's lock.

Filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so filters will not likely use this member function. Use CBaseFilter::Run instead.

CBaseMediaFilter::SetSyncSource

CBaseMediaFilter Class

Identifies the reference clock to which the filter should synchronize activity.

HRESULT SetSyncSource(
IReferenceClock * pClock
);

Parameters
pClock
Pointer to the IReferenceClock interface.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaFilter::SetSyncSource method. It sets the m_pClock data member to the pClock parameter and increments the reference count on the IReferenceClock interface passed in.

This member function is most important to rendering filters and might not apply to other filters.

Filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so filters will not likely use this member function. Use CBaseFilter::SetSyncSource instead.

CBaseMediaFilter::Stop

CBaseMediaFilter Class

Transitions the filter to State_Stopped state if it is not in this state already.

HRESULT Stop(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaFilter::Stop method. It sets the m_State member variable to State_Stopped.

Note that filters should derive their filters from CBaseFilter and not from CBaseMediaFilter, so this member function will not likely be used by filters. Use CBaseFilter::Stop instead.

CBaseMediaFilter::StreamTime

CBaseMediaFilter Class

Retrieves the current stream time.

virtual HRESULT StreamTime(
CRefTime& rtStream
);

Parameters
rtStream
Current stream time.
Return Values

Returns an HRESULT value, which can include the following values.
Value | Meaning
E_FAIL | Unable to get time from clock.
S_OK | Stream time returned in the rtStream parameter.
VFW_E_NO_CLOCK | No reference clock is available.

Remarks

Current stream time is the reference clock time minus the stream time offset. All samples with time stamps less than or equal to this time should have been presented.


CBaseObject Class

CBaseObject class hierarchy

The CBaseObject class is an abstract base class that is the basis for all component objects. It maintains a process-wide count of active objects that can be queried from the DllCanUnloadNow entry point.

All Component Object Model (COM) objects are derived from the CUnknown class, which is derived from the CBaseObject class. Other objects can be derived from CBaseObject to assist in the detection of memory leaks, because CBaseObject maintains the count of created objects.

The constructor requires a character-string name that describes the object being created. This string can be displayed on the debugging screen to trace the creation of objects; the string will also be displayed upon deletion of the object. The string should be created in static storage rather than in local-function storage. The string can be enclosed by the NAME macro, which compiles to NULL in retail builds so that the static strings are optimized out during compilation.

/* Typical object creation method */
HRESULT CSomeClass::CreateMyObject(void)
{
   HRESULT hr = NOERROR;

   CMyObject *pObject = new CMyObject(NAME("My filter object"),NULL,&hr);
      if (FAILED(hr)) {
         return hr;
   }

   if (pObject == NULL) {
      return E_OUTOFMEMORY;
   }
   m_pObject = pObject;
   return NOERROR;
}

/* Incorrect object creation method */

HRESULT CSomeClass::ThisMayAccessViolate(void)
{
   HRESULT hr = NOERROR;

   TCHAR MyObjectName[] = TEXT("My GP faulting object");
   CMyObject *pObject = new CMyObject(MyObjectName,NULL,&hr);
}

Member Functions
Name | Description
CBaseObject | Constructs a CBaseObject object.
ObjectsActive | Retrieves the count of active objects.

CBaseObject::CBaseObject

CBaseObject Class

Constructs a CBaseObject object.

CBaseObject(
const TCHAR *pName
);

Parameters
pName
Name assigned to the object for debugging purposes.
Return Values

No return value.

Remarks

The pName parameter should be allocated in static memory. This name appears on the debugging screen when the object is created and deleted.

CBaseObject::ObjectsActive

CBaseObject Class

Retrieves the count of active objects.

static LONG ObjectsActive( );

Return Values

Returns the current number of active objects.


CBaseOutputPin Class

CBaseOutputPin class hierarchy

CBaseOutputPin is an abstract base class derived from the CBasePin class that provides support for the common memory transport. CBaseOutputPin connects only to an input pin that supplies an IMemInputPin interface (such as a pin class derived from the CBaseInputPin class), and provides methods for the filter to access that interface. Derive your output pins from this class for the easiest implementation.

An output pin must provide one or more media types when connected to an input pin. If the media type that returns an index size, for example, is not currently available, the output pin should return S_FALSE in the CBasePin::GetMediaType member function, and the base class will skip it.

Your output pin class methods (represented here with the class name CYourPin) should call CBaseOutputPin. For example, CYourPin::Active should call CBaseOutputPin::Active first, to see if it should proceed. CYourPin::Inactive should call CBaseOutputPin::Inactive first, to decommit the sample allocator and avoid deadlock problems with CBaseOutputPin::GetDeliveryBuffer.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

All IQualityControl method implementations are inherited from the CBasePin class and are not overridden by this class.

Protected Data Members
Name | Description
m_pAllocator | Pointer to the IMemAllocator interface for this pin.
m_pInputPin | Pointer to the input pin to which this pin is connected.

Member Functions
Name | Description
CBaseOutputPin | Constructs a CBaseOutputPin object.

Overridable Member Functions
Name | Description
Active | Switches the pin to the active (running) mode.
BreakConnect | Releases the allocator and the IMemInputPin interface.
CheckConnect | Calls QueryInterface to retrieve an IMemInputPin interface.
CompleteConnect | Completes the connection.
DecideAllocator | Negotiates the allocator.
DecideBufferSize | Retrieves the number and size of buffers required for the transfer.
Deliver | Delivers an IMediaSample buffer to the connecting pin.
DeliverBeginFlush | Calls the IPin::BeginFlush method on the connected pin.
DeliverEndFlush | Calls IPin::EndFlush on the connected input pin to pass an end-flushing notification.
DeliverEndOfStream | Calls IPin::EndOfStream on the connected input pin to pass an end-of-stream notification.
DeliverNewSegment | Calls IPin::NewSegment on the connected input pin to pass a segment.
GetDeliveryBuffer | Returns an IMediaSample buffer suitable for passing across the connection.
Inactive | Switches the pin to the inactive (stopped) mode.
InitAllocator | Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.

Implemented IPin Methods
Name | Description
BeginFlush | Informs the pin to begin a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndFlush | Informs the pin to end a flush operation. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.
EndOfStream | Informs the pin that no additional data is expected until a new run command is issued. Implemented to return E_UNEXPECTED because it is an error to call this on an output pin.

CBaseOutputPin::Active

CBaseOutputPin Class

Called by the CBaseFilter implementation when the state changes from stopped to either paused or running.

HRESULT Active(void);

Return Values

Returns VFW_E_NO_ALLOCATOR if there is no allocator.

Remarks

This member function calls CMemAllocator::Commit to commit memory required before becoming active.

CBaseOutputPin::BeginFlush

CBaseOutputPin Class

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::BeginFlush method. It returns E_UNEXPECTED because this should be called only on input pins.

CBaseOutputPin::BreakConnect

CBaseOutputPin Class

Releases IMemAllocator and IMemInputPin objects acquired by the pin.

HRESULT BreakConnect(void);

Return Values

Returns NOERROR by the default base class implementation.

Remarks

This member function releases the IMemAllocator and IPin interfaces used during the connection.

If you override this method, always call the base class BreakConnect or unexpected behavior will result, including reference count leaks.

CBaseOutputPin::CBaseOutputPin

CBaseOutputPin Class

Constructs a CBaseOutputPin object.

CBaseOutputPin(
TCHAR *pObjectName,
CBaseFilter *pFilter,
CCritSec *pLock,
HRESULT * phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the object used in the CBaseOutputPin constructor for debugging purposes.
pFilter
Filter to which the pin will be attached.
pLock
Pointer to a CBaseOutputPin object for locking.
phr
Pointer to the general COM return value. This value is changed only if this function fails.
pName
Pin name.
Return Values

No return value.

CBaseOutputPin::CheckConnect

CBaseOutputPin Class

Calls QueryInterface on the connected pin to retrieve an IMemInputPin interface.

HRESULT CheckConnect(
IPin *pPin
);

Parameters
pPin
Pointer to the IPin interface on the connecting pin.
Return Values

Returns NOERROR if successful; otherwise, returns an HRESULT error value.

CBaseOutputPin::CompleteConnect

CBaseOutputPin Class

Completes a connection to another filter.

virtual HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the connected (receiving) pin.
Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function overrides the CBasePin::CompleteConnect member function and calls the CBaseOutputPin::DecideAllocator member function to finish completing the connection.

CBaseOutputPin::DecideAllocator

CBaseOutputPin Class

Negotiates the allocator to use.

virtual HRESULT DecideAllocator(
IMemInputPin * pPin,
IMemAllocator ** pAlloc
);

Parameters
pPin
Pointer to the IPin interface of the connecting pin.
pAlloc
Pointer to the negotiated IMemAllocator interface.
Return Values

Returns NOERROR if successful; otherwise, returns an HRESULT value.

Remarks

This member function calls the CBaseOutputPin::DecideBufferSize member function, which is not implemented by this base class. Override DecideBufferSize to call IMemAllocator::SetProperties.

If the connected input pin fails a call to IMemInputPin::GetAllocator, this member function constructs a CMemAllocator object and calls CBaseOutputPin::DecideBufferSize on that object. If the call to DecideBufferSize is successful, this member function notifies the input pin of the selected allocator. This function is called by the base class implementation of the IPin::Connect method, which is responsible for locking the object's critical section.

Override this member function if you want to use your own allocator. The input pin gets the first choice for the allocator, and the output pin agrees or forces it to use another allocator.

CBaseOutputPin::DecideBufferSize

CBaseOutputPin Class

Retrieves the number and size of buffers required for the transfer.

virtual HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * ppropInputRequest
) PURE;

Parameters
pAlloc
Allocator assigned to the transfer.
ppropInputRequest
Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.
Return Values

Returns an HRESULT value.

Remarks

The CBaseOutputPin::DecideAllocator member function calls this member function. You must override this member function in your derived class and call IMemAllocator::SetProperties.

CBaseOutputPin::Deliver

CBaseOutputPin Class

Delivers the IMediaSample buffer to the connected pin.

virtual HRESULT Deliver(
IMediaSample *pSample
);

Parameters
pSample
Buffer to deliver.
Return Values

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns an HRESULT value.

Remarks

This member function delivers this buffer to the connected input pin by calling its IMemInputPin::Receive method.

CBaseOutputPin::DeliverBeginFlush

CBaseOutputPin Class

Calls the IPin::BeginFlush method on the connected input pin.

virtual HRESULT DeliverBeginFlush(void);

Return Values

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by the IPin::BeginFlush method.

Remarks

This member function delivers the BeginFlush notification downstream.

CBaseOutputPin::DeliverEndFlush

CBaseOutputPin Class

Calls the IPin::EndFlush method on the connected input pin.

virtual HRESULT DeliverEndFlush(void);

Return Values

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value that is returned by IPin::EndFlush.

Remarks

This member function delivers the EndFlush notification downstream.

CBaseOutputPin::DeliverEndOfStream

CBaseOutputPin Class

Calls the IPin::EndOfStream method on the connected input pin.

virtual HRESULT DeliverEndOfStream(void);

Return Values

Returns VFW_E_NOT_CONNECTED if no input pin is found; otherwise, returns the value returned by the IPin::EndOfStream call to the connected pin.

Remarks

This member function delivers the end-of-stream notification downstream by calling the IPin::EndOfStream method on the connected pin.

CBaseOutputPin::DeliverNewSegment

CBaseOutputPin Class

Calls the IPin::NewSegment method on the connected input pin.

virtual HRESULT DeliverNewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
Start time of the segment.
tStop
Stop time of the segment.
dRate
Rate of the segment.
Return Values

Returns an HRESULT value.

Remarks

You will need to override this member function in your derived output pin class if your filter queues any data in the output pin.

CBaseOutputPin::EndFlush

IPin Interface

Informs the pin to end a flush operation.

HRESULT EndFlush(void);

Return Values

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::EndFlush method. It returns E_UNEXPECTED because this should be called only on input pins.

CBaseOutputPin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns E_UNEXPECTED.

Remarks

This member function implements the IPin::EndOfStream method but isn't expected to be called on an output pin.

CBaseOutputPin::GetDeliveryBuffer

CBaseOutputPin Class

Retrieves an IMediaSample buffer suitable for passing across the connection.

virtual HRESULT GetDeliveryBuffer(
IMediaSample ** ppSample,
REFERENCE_TIME * pStartTime,
REFERENCE_TIME * pEndTime,
DWORD dwFlags
);

Parameters
ppSample
IMediaSample buffer to be provided.
pStartTime
Start time of the media sample (optional and can be NULL).
pEndTime
Stop time of the media sample (optional and can be NULL).
dwFlags
The following flags are supported.
AM_GBF_NOTASYNCPOINT | Dynamic format changes are not allowed on this buffer because it is not a key frame.
AM_GBF_PREVFRAMESKIPPED | Buffer returned will not be filled with data contiguous with any previous data sent.
Return Values

Returns E_NOINTERFACE if an allocator is not found; otherwise, returns the value returned from calling the IMemAllocator::GetBuffer method.

Remarks

The pin object must lock itself before calling this member function; otherwise, the filter graph could disconnect this pin from the input pin midway through the process. If the filter has no worker threads, the lock is best applied on the IMemInputPin::Receive call; otherwise, it should be done when the worker thread is ready to deliver the sample.

This call can block; therefore, to avoid deadlocking with an IMediaFilter::Stop command, a two-tier locking scheme (such as that implemented in CTransformFilter) is required. Only the second-level lock is acquired here. The IBaseFilter base class implementation of IMediaFilter::Stop first gets the first-level lock and then calls IMemAllocator::Decommit on the allocator. This has the effect of making GetDeliveryBuffer return with a failure code. The Stop member function then gets the second-level lock and completes the command by calling Inactive for this pin.

No lock is needed when calling CBaseOutputPin::GetDeliveryBuffer when passing on samples using a worker thread. In this case, the CBaseFilter::Stop base class implementation acquires its filter-level lock and just calls IMemAllocator::Decommit on the allocator, at which point the worker thread is freed up to listen for a command to stop.

You must release the sample yourself after this function. If the connected input pin needs to hold on to the sample beyond the function, it will add the reference for the sample itself through IUnknown::AddRef. You must release this one and call CBaseOutputPin::GetDeliveryBuffer for the next. (You cannot reuse it directly.)

CBaseOutputPin::Inactive

CBaseOutputPin Class

Called by the CBaseFilter implementation when the state changes from either paused or running to stopped.

HRESULT Inactive(void);

Return Values

Returns VFW_E_NO_ALLOCATOR if there is no allocator; otherwise, returns the value from calling the IMemAllocator::Decommit method.

Remarks

This member function calls IMemAllocator::Decommit to decommit memory before becoming inactive.

CBaseOutputPin::InitAllocator

CBaseOutputPin Class

Creates a default memory allocator. Override this to provide your own allocator or to provide no allocator.

virtual HRESULT InitAllocator(
IMemAllocator **ppAlloc
);

Parameters
ppAlloc
Returned memory allocator.
Return Values

Returns an HRESULT value.

Remarks

The allocator should be released after use. This is typically handled in the CBaseOutputPin::BreakConnect member function.


CBasePin Class

CBasePin class hierarchy

CBasePin is an abstract base class from which all pins are derived. CBasePin supports the IPin interface. You can derive from this if your pin does not supply or use the IMemInputPin interface; otherwise, derive from the CBaseInputPin class or the CBaseOutputPin class.

The connection process is crucial to the success of creating filter graphs. The filter graph finds two filters (and subsequently two pins) to connect. It calls the IPin::Connect method on the output pin (it can also call Connect on the input pin at the same time). The output pin then calls the virtual pin member function CBasePin::CheckConnect. Derived classes should override this member function to use QueryInterface to return any interfaces required. The base class implementation of CheckConnect queries the IMemInputPin interface to establish the default transport protocol.

After calling CheckConnect, the output pin calls CBasePin::AgreeMediaType; this is a worker member function not intended for overriding in derived classes. This gets the input pin's enumerator and calls CBasePin::TryMediaTypes with it. TryMediaTypes is another base pin worker member function that is not intended for derivation. It cycles through each media type provided by an enumerator to determine if a connection can be made with that type.

If that process fails, AgreeMediaType retrieves the output pin's media type enumerator and calls CBasePin::GetMediaType, which cycles through the media types to agree on a connection type. If there is agreement, a media type with the input and output pins becomes the type used in the connection.

If no media type can be agreed on, the connection between the pins cannot be made. The base pin calls CBasePin::SetMediaType to broadcast the format. The m_mt base pin variable is set during this process.

The IPin interface provides a method called QueryAccept. This method allows a connected filter to query whether the pin will accept a specified media type. The method is asynchronous so that a filter can call it at any time—even when another filter is calling it. For this reason, its implementation in any override of the base class should not lock the filter. The base class implementation of IPin::QueryAccept calls the overridden CBasePin::CheckMediaType member function on the derived pin class.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_bRunTimeError | Run-time error generated.
m_Connected | Pin to which this pin is connected.
m_dir | Direction of this pin.
m_dRate | Rate from the CBasePin::NewSegment call.
m_mt | Media type that this pin is using. This is established during the connection process.
m_pFilter | Filter that created the pin.
m_pLock | Object used for locking.
m_pQSink | Target for quality messages.
m_pName | Name of the pin.
m_tStart | Start time from the CBasePin::NewSegment call.
m_tStop | Stop time from the CBasePin::NewSegment call.
m_TypeVersion | Current media type version (see CBasePin::GetMediaTypeVersion).

Member Functions
Name | Description
AttemptConnection | Attempts to make a connection to another pin using a specified media type.
CBasePin | Constructs a CBasePin object.
CurrentRate | Returns the segment rate set by the CBasePin::NewSegment member function.
CurrentStartTime | Returns the segment start time set by the CBasePin::NewSegment member function.
CurrentStopTime | Returns the segment stop time set by the CBasePin::NewSegment member function.
DisplayPinInfo | Displays pin information on the debugging monitor.
DisplayTypeInfo | Displays media type information on the debugging monitor.
GetConnected | Returns the pin that is connected to this pin.
IncrementTypeVersion | Adds 1 to the current media type version.
IsConnected | Determines whether the pin is connected.
IsStopped | Determines whether the filter owning this pin is in the State_Stopped state.
Name | Returns the m_pName name of the pin.

Overridable Member Functions
Name | Description
Active | Switches the pin to the active (running) mode.
AgreeMediaType | Agrees on the media type to be used by the pin.
BreakConnect | Adds custom code when the connection quits. This is also called when a stage in the connection process fails, so this member function should also clean up partial connection states.
CheckConnect | Adds custom code when the connection is being made. This is called at the start of the connection process.
CheckMediaType | Checks if the pin can support a specific media type.
CompleteConnect | Completes the connection.
GetMediaType | Returns the media type used by the pin.
GetMediaTypeVersion | Returns the version of the pins that were created dynamically.
Inactive | Switches the pin to the inactive (stopped) mode.
SetMediaType | Sets the m_mt data member to the established media type.
TryMediaTypes | Tries to find an acceptable media type for a connection from the list returned by a media type enumerator.

Implemented IPin Methods
Name | Description
Connect | Initiates a connection to another pin.
ConnectedTo | Returns a pointer to the connecting pin.
ConnectionMediaType | Returns the media type of this pin's connection.
Disconnect | Breaks a connection.
EndOfStream | Informs the input pin that no additional data is expected until a new run command is issued. (returns S_FALSE by default).
EnumMediaTypes | Returns an enumerator for this pin's preferred media types.
NewSegment | Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryAccept | Determines whether this pin accepts the media type.
QueryDirection | Retrieves the pin direction of the pin.
QueryId | Retrieves an identifier for the pin.
QueryInternalConnections | Returns an array of the pins to which this pin connects internally.
QueryPinInfo | Retrieves information about the pin itself (the name, owning filter, or direction).
ReceiveConnection | Called by a connecting pin to make a connection to this pin. Usually this does not need to be overridden, because the default implementation calls CBasePin::CheckConnect, CBasePin::CheckMediaType, and CBasePin::BreakConnect.
Run | Notifies the pin that the filter has changed state from paused to running.

Implemented IQualityControl Methods
Name | Description
Notify | Notifies the recipient that a quality change is requested.
SetSink | Sets the IQualityControl object that will receive quality messages.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingAddRef | Increments the owning filter's reference count.
NonDelegatingQueryInterface | Retrieves CBasePin interfaces. Override this member function to pass out pointers to any interfaces added by the derived pin class.
NonDelegatingRelease | Decrements the owning filter's reference count.

CBasePin::Active

CBasePin Class

Called by the CBaseFilter implementation when the state changes from stopped to either paused or running.

virtual HRESULT Active(void);

Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

Any class that requires notification of a change of state should override this member function. This is called when the filter owning the pin exits the State_Stopped state.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

CBasePin::AgreeMediaType

CBasePin Class

Searches for a media type for the pin connection.

virtual HRESULT AgreeMediaType(
IPin *pReceivePin,
const CMediaType *pmt
);

Parameters
pReceivePin
Pointer to the receiving pin.
pmt
Pointer to a media type object to be returned.
Return Values

Returns an HRESULT value, which can include one of the following values.
Value | Meaning
NOERROR | A media type was found.
VFW_E_NO_ACCEPTABLE_TYPES | No agreement on a media type was reached.

Remarks

This member function is called during the connection process. It calls CBasePin::TryMediaTypes on both the owning pin and the pin connected to the owning pin; it enumerates the preferred data types on the pin. If one is found, TryMediaTypes tries the media type with the pin in a call to the CBasePin::ReceiveConnection member function. If this pin proposes a media type, its support is still verified by calling CBasePin::CheckMediaType. The enumerator can list all the media types, even if some of them are not currently available.

This member function is protected.

CBasePin::AttemptConnection

CBasePin Class

Attempts to make a connection to another pin using a specified media type.

virtual HRESULT AttemptConnection(
IPin * pReceivePin,
const CMediaType *pmt
);

Parameters
pReceivePin
Pointer to the receiving pin.
pmt
Pointer to a media type object containing the preferred media type for the connection.
Return Values

Returns an HRESULT value.

Remarks

This member function is used to attempt to connect with a given media type. Its main purpose is to call the IPin::ReceiveConnection method of the pin passed in the pReceivePin parameter. This member function is protected.

CBasePin::BreakConnect

CBasePin Class

Called when a connection is broken to allow for customization (intended for overriding).

virtual HRESULT BreakConnect( );

Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function is called when a connection to the pin cannot be made or when CBasePin::Disconnect is called. In this case, it is necessary to undo anything performed during the connection process. You can override this member function to release any references to interfaces that were made during the connection.

CBasePin::CBasePin

CBasePin Class

Constructs a CBasePin object.

CBasePin(
TCHAR *pObjectName,
CBaseFilter *pFilter,
CCritSec *pLock,
HRESULT *phr,
LPCWSTR pName,
PIN_DIRECTION dir
);

Parameters
pObjectName
Description of the object.
pFilter
Owning filter that knows about pins.
pLock
Object that implements the lock.
phr
Pointer to a general COM return value. This value is changed only if this function fails.
pName
Pin name.
dir
Either PINDIR_INPUT or PINDIR_OUTPUT.
Return Values

No return value.

Remarks

This is a standard class constructor.

CBasePin::CheckConnect

CBasePin Class

Allows for customization when the connection is first made (intended for overriding, if required).

virtual HRESULT CheckConnect(
IPin * pPin
);

Parameters
pPin
Pointer to the connecting pin.
Return Values

Returns one of the following arguments by default; if overridden, should return standard HRESULT values, including the following values.
Value | Meaning
E_INVALIDARG | Pin directions do not match between pins.
NOERROR | Connection verified successfully.

Remarks

This member function is called during a call to the IPin::Connect method to provide a virtual method that can do any specific check required for a connection, such as calling CBasePin::NonDelegatingQueryInterface. This base class method determines if the pin directions match.

CBasePin::CheckMediaType

CBasePin Class

Determines if the pin can support a specific media type.

virtual HRESULT CheckMediaType(
const CMediaType * pmt
)
PURE;

Parameters
pmt
Pointer to a media type object containing the proposed media type.
Return Values

The overriding member function should return S_OK if the proposed media type is accepted; otherwise, it should return an HRESULT failure value, such as S_FALSE.

Remarks

This member function is typically called before calling the CBasePin::SetMediaType member function. It is also called from several other member functions, including CBasePin::ReceiveConnection and CBasePin::QueryAccept.

CBasePin::CompleteConnect

CBasePin Class

Completes a connection to another filter (intended for overriding).

virtual HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the connected (receiving) pin.
Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

Override this member function to check for required connection interfaces on the pReceivePin parameter or its filter. Failing this member function fails the connection and disconnects the other pin. The CBaseOutputPin class overrides this member function to establish a local memory transport.

CBasePin::Connect

CBasePin Class

Initiates a connection from this pin to the other pin.

HRESULT Connect(
IPin * pReceivePin,
const AM_MEDIA_TYPE *pmt
);

Parameters
pReceivePin
Input pin to connect to.
pmt
Optional media type parameter.
Return Values

Returns one of the following arguments by default; if overridden, should return standard HRESULT values.
Value | Meaning
VFW_E_ALREADY_CONNECTED | This output pin is already connected to another pin.
VFW_E_NOT_STOPPED | The filter graph is not in a stopped state and connection can't be performed.
Other error value | Returned from CBasePin::AgreeMediaType or CBasePin::CheckConnect or overridden versions of these member functions.

Remarks

This member function implements the IPin::Connect method. IPin::Connect is implemented on the output pin and calls the IPin::ReceiveConnection method for the connected input pin (implemented in the base classes as CBasePin::ReceiveConnection). This member function calls the virtual CBasePin::CheckConnect member function, which can be overridden to verify that the connection is possible. CBasePin::CheckConnect then calls CBasePin::AgreeMediaType to negotiate a common media type with the connected pin.

CBasePin::AgreeMediaType calls CBasePin::TryMediaTypes twice; once for this pin's media type enumerator and once for the receiving pin's media type enumerator. For each media type found, CBasePin::AttemptConnection is called, which in turn calls the receiving pin's IPin::ReceiveConnection method, and finally CBasePin::CompleteConnect if successful.

CBasePin::ConnectedTo

CBasePin Class

Retrieves a pointer to the connected pin, if there is one.

HRESULT ConnectedTo(
IPin ** ppPin
);

Parameters
ppPin
IPin interface of the other pin (if any) to which this pin is connected.
Return Values

The base class returns S_OK if connected; otherwise, returns VFW_E_NOT_CONNECTED.

Remarks

This member function implements the IPin::ConnectedTo method. It adds a reference to the connected IPin interface by calling the IUnknown::AddRef method, because each copy of an interface pointer has its reference incremented. The calling application is responsible for calling IUnknown::Release on this interface when done with it.

CBasePin::ConnectionMediaType

CBasePin Class

Retrieves the media type associated with the current connection of the pin.

HRESULT ConnectionMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
Pointer to an AM_MEDIA_TYPE structure. If the pin isn't connected, this structure is initialized to zero. Otherwise, the media type is returned in this parameter.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::ConnectionMediaType method. It returns a copy of the AM_MEDIA_TYPE structure that was negotiated for the pin connection when the pin was connected.

This method fails if the pin is unconnected. The task allocator allocates the media type's format block. Use the task allocator to free the format block, for example by calling the Microsoft Win32 CoTaskMemFree function.

CBasePin::CurrentRate

CBasePin Class

Retrieves the segment rate set by the CBasePin::NewSegment member function.

double CurrentRate( );

Return Values

Returns the value of m_dRate.

CBasePin::CurrentStartTime

CBasePin Class

Retrieves the segment start time set by the CBasePin::NewSegment member function.

REFERENCE_TIME CurrentStartTime( );

Return Values

Returns the value of m_tStart.

CBasePin::CurrentStopTime

CBasePin Class

Retrieves the segment stop time set by the CBasePin::NewSegment member function.

REFERENCE_TIME CurrentStopTime( );

Return Values

Returns the value of m_tStop.

CBasePin::Disconnect

CBasePin Class

Breaks a connection.

HRESULT Disconnect(void);

Return Values

Returns NOERROR if there is no connection.

Remarks

This member function implements the IPin::Disconnect method. It calls the CBasePin::BreakConnect member function and releases the IPin interface of the connected pin (held by m_Connected). There are no parameters because there is only one possible connection on this pin.

CBasePin::DisplayPinInfo

CBasePin Class

Displays pin information during debugging.

void DisplayPinInfo(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the receiving pin.
Return Values

Returns an HRESULT value.

CBasePin::DisplayTypeInfo

CBasePin Class

Displays media type information during debugging.

void DisplayTypeInfo(
IPin *pPin,
const CMediaType *pmt
);

Parameters
pPin
Pointer to the pin's IPin interface.
pmt
Pointer to the media type object.
Return Values

No return value.

Remarks

This member function displays the major and minor media types of the specified media type object.

CBasePin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns S_FALSE.

Remarks

This member function implements the IPin::EndOfStream method. This is intended for input pins only.

CBasePin::EnumMediaTypes

CBasePin Class

Provides an enumerator for this pin's preferred media types.

HRESULT EnumMediaTypes(
IEnumMediaTypes ** ppEnum
);

Parameters
ppEnum
Pointer to an enumerator for the media types.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EnumMediaTypes method. It returns an enumerator object implemented by the CEnumMediaTypes class and obtains the IEnumMediaTypes interface, which adds a reference count to this enumerator. If an application receives an enumerator, the application must release this when done with it by calling IUnknown::Release on the enumerator.

CBasePin::GetConnected

CBasePin Class

Retrieves the pin that is connected to this pin.

IPin * GetConnected( );

Return Values

Returns a pointer to an IPin interface.

Remarks

The caller should call the CBasePin::IsConnected member function before calling CBasePin::GetConnected.

CBasePin::GetMediaType

CBasePin Class

Retrieves the current type version, which is used by enumerators.

virtual HRESULT GetMediaType(
int iPosition,
const CMediaType *pMediaType
);

Parameters
iPosition
Position in the media type list.
pMediaType
Returned pointer to the media type at this position.
Return Values

Returns E_UNEXPECTED by default implementation; the overriding member function should return one of the following values, or an HRESULT error value if the value could not be set.
Value | Meaning
S_FALSE | Media type exists but is not currently usable.
S_OK | Media type was set.
VFW_S_NO_MORE_ITEMS | End of the list of media types has been reached.

Remarks

This is a virtual member function that returns a media type corresponding to the position in the list specified by the iPosition parameter. This base class simply returns an error because no media types are supported by default. Derived classes should override this member function.

CBasePin::GetMediaTypeVersion

CBasePin Class

Retrieves the current type version, which is used by enumerators.

virtual LONG GetMediaTypeVersion( );

Return Values

Returns the value of m_TypeVersion by default. To return new media types, override this member function.

Remarks

This is a virtual member function that returns the current media type version. The base class initializes the media type enumerators to 1. A derived class can change the list of available media types. Each time it does, it should increment the version in the overriding member function. The media type enumerators call this member function when they are called to determine if they are out of date.

CBasePin::Inactive

CBasePin Class

Switches the pin to an inactive state.

virtual HRESULT Inactive(void);

Return Values

Returns NOERROR for a base class implementation. The overriding member function returns a standard HRESULT value and should not fail if the pin is already set as inactive.

Remarks

This member function is called by the IMediaFilter implementation when the state changes to inactive. This member function should be overridden to decommit allocators and free any hardware resources that were obtained in the CBasePin::Active call. The default implementation of the base class member function does nothing.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

CBasePin::IncrementTypeVersion

CBasePin Class

Adds 1 to the current media type version.

void IncrementTypeVersion(void);

Return Values

No return value.

Remarks

The media type version is used to ensure that the filter has not changed the media type. If it changes the media type, the filter should call this member function.

CBasePin::IsConnected

CBasePin Class

Determines if the pin is connected to another pin.

BOOL IsConnected(void);

Return Values

Returns TRUE if the pin is connected; otherwise, returns FALSE.

Remarks

This member function checks the value of the m_Connected protected data member.

CBasePin::IsStopped

CBasePin Class

Determines if the filter is stopped.

BOOL IsStopped( );

Return Values

Returns TRUE if the filter is stopped; otherwise, returns FALSE.

Remarks

Note that this member function must not be used in the constructor of the pin, because the filter that is passed is often not initialized properly at that time (due to the convention of using a this pointer during the construction of data members).

CBasePin::Name

CBasePin Class

Retrieves the name of the pin.

LPWSTR Name( );

Return Values

Returns the value of the m_pName data member.

CBasePin::NewSegment

CBasePin Class

Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.

HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
Start time of the segment.
tStop
Stop time of the segment.
dRate
Rate of the segment.
Return Values

Returns an HRESULT value (S_OK by default).

Remarks

This member function implements the IPin::NewSegment method. The default implementation sets the m_tStart, m_tStop, and m_dRate data members to the values passed in as parameters. Overriding member functions should pass this notification downstream.

CBasePin::NonDelegatingAddRef

CBasePin Class

Increments the reference count for an interface.

ULONG NonDelegatingAddRef( );

Return Values

Returns the reference count of the object.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingAddRef method. It increments the reference count of the owning filter.

CBasePin::NonDelegatingQueryInterface

CBasePin Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IPin, IQualityControl, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CBasePin::NonDelegatingRelease

CBasePin Class

Decrements the reference count for an interface.

ULONG NonDelegatingRelease( );

Return Values

Returns the reference count.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingRelease method. It releases a reference to the owning filter.

CBasePin::Notify

CBasePin Class

Notifies the recipient that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

Parameters
pSelf
Pointer to the filter that is sending the quality notification.
q
Quality notification structure.
Return Values

The default base class implementation returns E_FAIL.

Remarks

This member function must be overridden to accept notifications. It is typically overridden to implement this method on the output pin because quality-control messages are passed upstream. The CTransformOutputPin::Notify member function is one example of how this member function is overridden to pass quality-control messages to the next filter upstream.

CBasePin::QueryAccept

CBasePin Class

Determines whether the pin accepts the format type.

HRESULT QueryAccept(
const AM_MEDIA_TYPE* pmt
);

Parameters
pmt
Pointer to a proposed media type.
Return Values

Returns S_TRUE if the format is accepted; otherwise, returns S_FALSE.

Remarks

This member function implements the IPin::QueryAccept method. It simply calls the pure virtual CBasePin::CheckMediaType member function, which the derived class must implement, and maps any returned codes from CheckMediaType other than S_OK to S_FALSE.

CBasePin::QueryDirection

CBasePin Class

Retrieves the direction of the pin.

HRESULT QueryDirection(
PIN_DIRECTION* pPinDir
);

Parameters
pPinDir
Pointer to a PIN_DIRECTION structure to be filled in with the direction.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryDirection method. pPinDir will contain PINDIR_INPUT or PINDIR_OUTPUT. The same information is available through the CBasePin::QueryPinInfo member function, but this member function is more efficient.

CBasePin::QueryId

CBasePin Class

Retrieves an identifier for the pin.

HRESULT QueryId(
LPWSTR * Id
);

Parameters
Id
Pin identifier.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryId method. By default, this member function uses the pin name in the CBasePin::m_pName data member, so implementing this member function in your derived filter class is not normally required.

CBasePin::QueryInternalConnections

CBasePin Class

Provides an array of pointers to IPin objects. These are the pins to which this pin internally connects.

HRESULT QueryInternalConnections(
IPin ** apPin,
ULONG * nPin
);

Parameters
apPin
Array of IPin pointers.
nPin
Upon input, indicates the number of channels; upon output, indicates the number of pins.
Return Values

Returns one of the following HRESULT values.
Value | Meaning
E_FAIL | Undetermined failure.
E_NOTIMPL | The filter graph manager interprets E_NOTIMPL as meaning all input pins connect to all output pins.
S_FALSE | Insufficient number of channels; returns no pins in apPin.

Remarks

This member function implements the IPin::QueryInternalConnections method but only to return E_NOTIMPL. Override this if you want to provide mapping between specific input and output pins.

The default implementation to return E_NOTIMPL implies that the caller can assume that all input pins feed all output pins. Overriding this member function allows a filter to specify when it is a renderer for some of its input pins and not for others.

CBasePin::QueryPinInfo

CBasePin Class

Retrieves information about the pin.

HRESULT QueryPinInfo(
PIN_INFO * pInfo
);

Parameters
pInfo
Pointer to a PIN_INFO structure.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryPinInfo method. By default, the member function fills in the PIN_INFO structure with the IBaseFilter interface of its owning filter, the pin name from m_pName, and the pin direction from m_dir.

The IBaseFilter interface passed out by this member function is reference counted, and so must be released when the caller has finished with it.

CBasePin::ReceiveConnection

CBasePin Class

Makes a connection to the calling output pin.

HRESULT ReceiveConnection(
IPin * pConnector,
AM_MEDIA_TYPE *pmt
);

Parameters
pConnector
Connecting pin.
pmt
Media type of the samples to be streamed.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::ReceiveConnection method. It calls CheckConnect and, if successful, then calls CheckMediaType to verify if the media type is acceptable. If either of these calls fails, it calls BreakConnect and exits. To finish the connection process, it calls CompleteConnect, which is implemented in CBasePin to return NOERROR, but can be overridden in the derived class.

CBasePin::Run

CBasePin Class

Notifies the pin that the filter has changed state from paused to running.

HRESULT Run(
REFERENCE_TIME tStart
);

Parameters
tStart
Start time as passed to the filter's Run method.
Return Values

Returns an HRESULT value (NOERROR_OK by default).

Remarks

This member function can be overridden in the derived class to perform activities such as committing memory or obtaining resources. For an overriding implementation of this member function, see the CRenderedInputPin::Run member function.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

CBasePin::SetMediaType

CBasePin Class

Sets the m_mt data member to the established media type.

virtual HRESULT SetMediaType(
const CMediaType * pmt
);

Parameters
pmt
Pointer to a media type object that was previously agreed on.
Return Values

Returns NOERROR by default implementation. The overriding member functions return an HRESULT value.

Remarks

This member function is called to establish the format for a pin connection. The CBasePin::CheckMediaType member function will have been called to check the connection format and, if it did not return an error value, this virtual member function will be called. The default implementation sets the m_mt protected data member to the value passed to this member function. Override to inform the derived class when the media type is set.

CBasePin::SetSink

CBasePin Class

Sets the object containing the IQualityControl interface that will receive quality-control messages.

HRESULT SetSink(
IQualityControl *piqc
);

Parameters
piqc
Pointer to the IQualityControl interface to which the notifications should be sent.
Return Values

Base class returns NOERROR by default. The overriding member function should return an HRESULT value.

Remarks

This member function implements the IQualityControl::SetSink method. The default implementation sets the m_pQSink data member to the piqc parameter passed in.

The IQualityControl::SetSink method tells a filter where to send quality-control messages it receives. When no sink has been explicitly set or if the last call to CBasePin::SetSink set the sink to NULL, the message should go upstream. The derived output pin class typically overrides CBasePin::Notify to enable this.

CBasePin::TryMediaTypes

CBasePin Class

Determines a media type for a pin connection.

virtual HRESULT TryMediaTypes(
IPin *pReceivePin,
const CMediaType *pmt,
IEnumMediaTypes *pEnum
);

Parameters
pReceivePin
Pointer to the IPin interface of the receiving pin.
pmt
Pointer to a returned media type.
pEnum
Pointer to an IEnumMediaTypes enumerator interface.
Return Values

Returns an HRESULT value, which can include the following.
Value | Meaning
FAILED | Resetting of the enumerator failed.
NOERROR | Media type found.
VFW_E_NO_ACCEPTABLE_TYPES | No acceptable media types were found.

Remarks

Given an enumerator, this member function cycles through all the media types proposed by the enumerator. Each type is suggested to the derived pin class and, if acceptable, is tried with the connected pin in a call to the IPin::ReceiveConnection method. This means that if the owning pin proposes a media type, it is still checked to determine whether it is supported. This is deliberate so that, in simple cases, the enumerator can hold all the media types, even if some of them are not currently available.

This member function is protected.


CBasePropertyPage Class

CBasePropertyPage class hierarchy

Property pages can be implemented on filters to provide access to custom properties on the filter. This can be useful for developing and debugging the filter, because the Filter Graph Editor displays these property pages. Also, the Microsoft® ActiveMovie Control queries filters in its underlying filter graph for the property pages they support and exposes them to the user. A good example is the video renderer, which exposes quality management information (such as frame rate) through a property page.

This class provides the framework for a property page associated with a filter and implements the IPropertyPage interface. A property page is a Component Object Model (COM) object, which should be created with a resource ID for a dialog box that will be loaded when required. It should also be given a resource ID for a title string when created.

In addition to implementing the IPropertyPage interface methods, this class provides several virtual member functions that can be overridden and specialized by the derived class (they return NOERROR by default). These virtual member functions are called at specific events, such as when the property page is activated or deactivated, connected or disconnected, when the changes to properties are to be applied, or when messages to the dialog box are received.

A filter exposing custom property pages should also expose the same functionality to an application through a custom interface. Otherwise, an application has no way to control the filter without displaying the property page. For example, the video renderer supports the IQualProp interface to access the same quality management information. In fact, the renderer property page uses that interface to get the information for its property page. To make it easier for applications to access their custom interfaces, filters should also implement their custom interfaces in a plug-in distributor (PID), which is an object that is aggregated with the filter graph manager. Typically, the PID implements its associated filter's interface by simply passing calls through from the application to the filter interface.

Protected Data Members
Name | Description
m_bDirty | Flag to determine whether anything has changed.
m_DialogId | Resource identifier for the dialog box.
m_Dlg | Dialog box window handle for the property page.
m_hwnd | Window handle for the property page.
m_pPageSite | IPropertyPage interface pointer used to access the filter's property information.
m_TitleId | Resource identifier for the property page title.

Member Functions
Name | Description
CBasePropertyPage | Constructs a CBasePropertyPage object.

Overridable Member Functions
Name | Description
OnActivate | Called when the property page is activated.
OnApplyChanges | Called when the user applies changes to the property page.
OnConnect | Called when the property page is connected to the filter.
OnDeactivate | Called when the property page is dismissed.
OnDisconnect | Called when the property page is disconnected from the owning filter.
OnReceiveMessage | Called when a message is sent to the property page dialog box window.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingAddRef | Default implementation increments the owning filter's reference count.
NonDelegatingQueryInterface | Called to retrieve CBasePropertyPage interfaces. Override this member function to pass out pointers to any interfaces added by the derived class.
NonDelegatingRelease | Default implementation decrements the owning filter's reference count.

Implemented IPropertyPage Methods
Name | Description
Activate | Creates a dialog box window for the property page.
Apply | Applies current property page values to the underlying object.
Deactivate | Destroys the window created with CBasePropertyPage::Activate.
GetPageInfo | Returns information about the property page.
Help | Invokes Help in response to user request.
IsPageDirty | Indicates whether the property page has changed since activated or since the most recent call to CBasePropertyPage::Apply.
Move | Positions and resizes the property page dialog box within the frame.
SetObjects | Provides the property page with an array of IUnknown pointers for objects associated with this property page.
SetPageSite | Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.
Show | Makes the property page dialog box visible or invisible.
TranslateAccelerator | Provides a pointer to an MSG structure that specifies a keystroke to process.

CBasePropertyPage::Activate

CBasePropertyPage Class

Creates the property page dialog box.

HRESULT Activate(
HWND hwndParent,
LPCRECT prect,
BOOL fModal
);

Parameters
hwndParent
Handle to the parent window of the dialog box.
prect
Pointer to the RECT structure that contains the dialog box's screen position.
fModal
Value that specifies a modal dialog box if TRUE, or a modeless dialog box if FALSE.
Return Values

Returns E_OUTOFMEMORY if the dialog box creation fails, or E_UNEXPECTED if a property page already exists.

Remarks

This member function implements the COM IPropertyPage::Active method, which creates a dialog box for the property page (without a frame, caption, system menu, or controls) using hwndParent as the parent window and prect as the positioning rectangle.

The property page maintains the window handle created in this process, which it uses to destroy the dialog box within CBasePropertyPage::Deactivate.

CBasePropertyPage::Apply

CBasePropertyPage Class

Applies current property page values to the underlying object.

HRESULT Apply(void);

Return Values

Returns E_UNEXPECTED if CBasePropertyPage::SetObjects has not been called or if the m_pPageSite data member has not been initialized with a pointer to the filter's property page.

Remarks

This member function implements the COM IPropertyPage::Apply method. The object to be changed is provided through a previous call to CBasePropertyPage::SetObjects. This should be the filter's IUnknown interface. Therefore, this member function should not fail because of nonexistent interfaces.

This member function sets the m_bDirty data member to FALSE and calls the virtual CBasePropertyPage::OnApplyChanges member function, which should be overridden in the derived class to apply the changes to the properties.

CBasePropertyPage::CBasePropertyPage

CBasePropertyPage Class

Constructs a CBasePropertyPage object.

CBasePropertyPage(
TCHAR *pName,
LPUNKNOWN pUnk,
int DialogId,
int TitleId
);

Parameters
pName
Name of the property page object for debugging purposes.
pUnk
Pointer to the COM delegating object.
DialogId
Resource ID for the dialog box.
TitleId
Resource ID for the dialog box title.
Remarks

This constructor sets the CBasePropertyPage data members as follows:

  • m_DialogId is set to DialogId.
  • m_TitleId is set to TitleId.
  • m_hwnd is set to NULL.
  • m_Dlg is set to NULL.
  • m_pPageSite is set to NULL.
  • m_bDirty is set to FALSE.

CBasePropertyPage::Deactivate

CBasePropertyPage Class

Destroys the window created with CBasePropertyPage::Activate.

HRESULT Deactivate(void);

Return Values

Returns E_UNEXPECTED if the data member m_hwnd does not contain a Window handle for the property page.

Remarks

This member function implements the COM IPropertyPage::Deactivate method. It calls the virtual CBasePropertyPage::OnDeactivate member function and then destroys the property page dialog box.

CBasePropertyPage::GetPageInfo

CBasePropertyPage Class

Returns information about the property page.

HRESULT GetPageInfo(
LPPROPPAGEINFO pPageInfo
);

Parameters
pPageInfo
Pointer to the caller-allocated PROPPAGEINFO structure in which the property page stores its page information. All allocations stored in this structure become the caller's responsibility.
Return Values

Returns E_OUTOFMEMORY if the function cannot allocate memory for the property page title.

Remarks

This member function implements the COM IPropertyPage::GetPageInfo method. It calls the GetDialogSize function to obtain the dialog box size and sets it to a default value in case this call fails.

CBasePropertyPage::Help

CBasePropertyPage Class

Invokes Help in response to user request.

HRESULT Help(
LPCWSTR lpszHelpDir
);

Parameters
lpszHelpDir
Pointer to the string under the HelpDir key in the property page's CLSID information in the registry. If HelpDir does not exist, this will be the path found in the InProcServer32 entry minus the server file name.
Return Values

Returns E_NOTIMPL by default.

Remarks

This member function implements the COM IPropertyPage::Help method, but only as a placeholder. The function does nothing but return E_NOTIMPL.

Calls to this member function must occur between calls to CBasePropertyPage::Activate and CBasePropertyPage::Deactivate.

If the page fails this member function (such as E_NOTIMPL), the frame will attempt to use the pszHelpFile and dwHelpContext fields of the PROPPAGEINFO structure obtained through CBasePropertyPage::GetPageInfo. Therefore, the derived class should either implement CBasePropertyPage::Help or return Help information through CBasePropertyPage::GetPageInfo.

CBasePropertyPage::IsPageDirty

CBasePropertyPage Class

Indicates whether the property page has changed since activated or since the most recent call to CBasePropertyPage::Apply.

HRESULT IsPageDirty(void);

Return Values

Returns S_OK if the value state of the property page is dirty, that is, it has changed and is different from the state of the objects. Returns S_FALSE if the value state of the page has not changed and is current with that of the objects.

Remarks

This member function implements the COM IPropertyPage::IsPageDirty method. It returns the value of the m_bDirty data member.

CBasePropertyPage::Move

CBasePropertyPage Class

Positions and resizes the property page dialog box within the frame.

HRESULT Move(
LPCRECT prect
);

Parameters
prect
Pointer to the RECT structure containing the positioning information for the property page dialog box.
Return Values

Returns E_UNEXPECTED if the m_hwnd data member does not contain a Window handle for the property page.

Remarks

This member function implements the COM IPropertyPage::Move method by calling the Microsoft® Win32® MoveWindow function. This member function is called from the CBasePropertyPage::Activate member function to position the property page dialog box.

CBasePropertyPage::NonDelegatingAddRef

CBasePropertyPage Class

Increments the reference count for an interface.

ULONG NonDelegatingAddRef( );

Return Values

Returns the object's reference count.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingAddRef method. It increments the owning filter's reference count.

CBasePropertyPage::NonDelegatingQueryInterface

CBasePropertyPage Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IPropertyPage interface. It then calls the CUnknown::NonDelegatingQueryInterface base class member function. Override this class to return other interfaces on the object in the derived class.

CBasePropertyPage::NonDelegatingRelease

CBasePropertyPage Class

Decrements the reference count for an interface.

ULONG NonDelegatingRelease( );

Return Values

Returns the reference count.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingRelease method. It releases a reference count to the owning filter.

CBasePropertyPage::OnActivate

CBasePropertyPage Class

Called when the property page is activated.

virtual HRESULT OnActivate(void);

Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

Remarks

This member function is called from the CBasePropertyPage::Activate member function to notify the derived class when the property page is displayed. Override this member function to initialize values in the dialog box. This can be done by calling the Win32 SetDlgItemText function with data member values previously initialized when the property page was connected (in the overridden CBasePropertyPage::OnConnect member function).

For example, the Vidprop.cpp file in the sample video renderer, SampVid, does this as follows:

// Set the text fields in the property page

HRESULT CQualityProperties::OnActivate()
{
    SetEditFieldData();
    return NOERROR;
}

// Initialize the property page fields

void CQualityProperties::SetEditFieldData()
{
    ASSERT(m_pQualProp);
    TCHAR buffer[50];

    wsprintf(buffer,"%d", m_iDropped);
    SendDlgItemMessage(m_Dlg, IDD_QDROPPED, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    wsprintf(buffer,"%d", m_iDrawn);
    SendDlgItemMessage(m_Dlg, IDD_QDRAWN, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    wsprintf(buffer,"%d.%02d", m_iFrameRate/100, m_iFrameRate%100);
    SendDlgItemMessage(m_Dlg, IDD_QAVGFRM, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    wsprintf(buffer,"%d", m_iFrameJitter);
    SendDlgItemMessage(m_Dlg, IDD_QJITTER, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    wsprintf(buffer,"%d", m_iSyncAvg);
    SendDlgItemMessage(m_Dlg, IDD_QSYNCAVG, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    wsprintf(buffer,"%d", m_iSyncDev);
    SendDlgItemMessage(m_Dlg, IDD_QSYNCDEV, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
}

CBasePropertyPage::OnApplyChanges

CBasePropertyPage Class

Called when the user applies changes to the property page.

virtual HRESULT OnApplyChanges(void);

Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

Remarks

Override this member function if your property page allows users to set property values. When this member function is called, process the changed properties. For example, set appropriate data members in the derived class to the new values, or call methods in the filter to set the properties. The overriding member function is responsible for calling CBasePropertyPage::IsPageDirty to set the m_bDirty data member to TRUE if the properties in the object do not reflect those in the property page when this member function exits.

CBasePropertyPage::OnConnect

CBasePropertyPage Class

Called when the property page is connected to the filter.

virtual HRESULT OnConnect(
IUnknown *pUnknown
);

Parameters
pUnknown
IUnknown interface of the filter associated with the property page.
Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

Remarks

This member function is called from the CBasePropertyPage::SetObjects member function with the ppUnk parameter of that member function, which should be the filter's IUnknown interface. Override this member function to acquire property values to be sent to the property page dialog box later (in CBasePropertyPage::OnActivate).

The following excerpt from the sample video renderer (SampVid) Vidprop.cpp file illustrates the use of this member function.

// Give us the filter to communicate with

HRESULT CQualityProperties::OnConnect(IUnknown *pUnknown)
{
    ASSERT(m_pQualProp == NULL);

    // Ask the renderer for its IQualProp interface

    HRESULT hr = pUnknown->QueryInterface(IID_IQualProp,(void **)&m_pQualProp);
    if (FAILED(hr)) {
        return E_NOINTERFACE;
    }

    ASSERT(m_pQualProp);

    // Get quality data for the page

    m_pQualProp->get_FramesDroppedInRenderer(&m_iDropped);
    m_pQualProp->get_FramesDrawn(&m_iDrawn);
    m_pQualProp->get_AvgFrameRate(&m_iFrameRate);
    m_pQualProp->get_Jitter(&m_iFrameJitter);
    m_pQualProp->get_AvgSyncOffset(&m_iSyncAvg);
    m_pQualProp->get_DevSyncOffset(&m_iSyncDev);
    return NOERROR;
}

CBasePropertyPage::OnDeactivate

CBasePropertyPage Class

Called when the property page is dismissed.

virtual HRESULT OnDeactivate(void);

Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

Remarks

This member function is called from the CBasePropertyPage::Deactivate member function when the user closes the property page. Override this member function to handle any special requirements at that time.

CBasePropertyPage::OnDisconnect

CBasePropertyPage Class

Called when the property page is disconnected from the owning filter.

virtual HRESULT OnDisconnect(void);

Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

Remarks

This member function is called from the CBasePropertyPage::SetObjects member function when the property page is disconnected from the filter. Override this member function to handle any special requirements at that time, such as releasing reference counts on underlying property interfaces.

The following example, from the Vidprop.cpp file in the sample video renderer, SampVid, demonstrates an implementation of this member function in a derived class.

// Release any IQualProp interface we have

HRESULT CQualityProperties::OnDisconnect()
{
    // Release the interface

    if (m_pQualProp == NULL) {
        return E_UNEXPECTED;
    }

    m_pQualProp->Release();
    m_pQualProp = NULL;
    return NOERROR;
}

CBasePropertyPage::OnReceiveMessage

CBasePropertyPage Class

Called when a message is sent to the property page dialog box.

virtual BOOL OnReceiveMessage(
HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);

Parameters
hwnd
Window procedure that received the message.
uMsg
Message.
wParam
Additional message information. This parameter's content depends on the value of the uMsg parameter.
lParam
Additional message information. This parameter's content depends on the value of the uMsg parameter.
Return Values

By default, returns the value returned by the Win32 DefWindowProc function.

Remarks

The default implementation of this member function calls DefWindowProc with the supplied parameters. Override this member function for special handling of messages.

CBasePropertyPage::SetObjects

CBasePropertyPage Class

Provides the property page with an IUnknown pointer for objects associated with this property page.

HRESULT SetObjects(
ULONG cObjects,
LPUNKNOWN *ppUnk
);

Parameters
cObjects
Number of IUnknown pointers in the array pointed to by ppUnk. This number should be 1 or 0. If it is 0, the property page must release any pointers previously passed to this method.
ppUnk
Pointer to a single IUnknown interface pointer identifying a unique object affected by the property sheet in which this (and possibly other) property page is displayed. The property page must cache this pointer by calling IUnknown::AddRef.
Return Values

Returns E_POINTER if ppUnk is null, E_UNEXPECTED if cObjects is greater than 1, and otherwise returns the value returned by the CBasePropertyPage::OnConnect or CBasePropertyPage::OnDisconnect member function that it calls.

Remarks

This member function implements the COM IPropertyPage::SetObjects method. This member function calls the virtual CBasePropertyPage::OnConnect member function when the cObjects value is 1, or the virtual CBasePropertyPage::OnDisconnect member function when the cObjects value is 0. Override these virtual member functions to acquire (by calling IUnknown::AddRef) or release (by calling IUnknown::Release) interfaces to which the property page applies.

Note that the caller must provide the property page with this object before calling CBasePropertyPage::Activate, and should call CBasePropertyPage::SetObjects with 0-v as the parameter when deactivating the page or when releasing the object entirely.

This member function allows only one object to be associated with the property page.

CBasePropertyPage::SetPageSite

CBasePropertyPage Class

Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.

HRESULT SetPageSite(
LPPROPERTYPAGESITE pPageSite
);

Parameters
pPageSite
Pointer to the IPropertyPageSite interface of the page site that manages and provides services to this property page within the entire property sheet.
Return Values

Returns E_UNEXPECTED if if the m_pPageSite data member has not been initialized with a pointer to the filter's property page.

Remarks

This member function implements the COM IPropertyPage::SetPageSite method. When passed an IPropertyPageSite interface, it reference counts the interface and assigns it to m_pPageSite. When passed a null value, it releases the reference count on the IPropertyPageSite interface.

CBasePropertyPage::Show

CBasePropertyPage Class

Makes the property page dialog box visible or invisible.

HRESULT Show(
UINT nCmdShow
);

Parameters
nCmdShow
Command describing whether to become visible. Only SW_SHOWNORMAL, SW_SHOW, and SW_HIDE are accepted.
Return Values

Returns E_UNEXPECTED if the data member m_hwnd does not contain a Window handle for the property page. Returns E_INVALIDARG if the nCmdShow parameter is not equal to SW_SHOW or SW_SHOWNORMAL (show) or SW_HIDE (hide).

Remarks

If the page is made visible, the page should set the focus to itself, specifically to the first property on the page. This member function implements the COM IPropertyPage::Show method. This is called just before exiting the CBasePropertyPage::Activate member function with the nCmdShow SHOW_NORMAL value.

CBasePropertyPage::TranslateAccelerator

CBasePropertyPage Class

Provides a pointer to an MSG structure that specifies a keystroke to process.

HRESULT TranslateAccelerator(
LPMSG lpMsg
);

Parameters
lpMsg
Pointer to the MSG structure describing the keystroke to process.
Return Values

Returns E_NOTIMPL by default.

Remarks

This member function implements the COM IPropertyPage::TranslateAccelerator method. Calls to this member function must occur after a call to CBasePropertyPage::Activate and before the corresponding call to CBasePropertyPage::Deactivate. Override this member function to implement keyboard accelerators for the property page.


CBaseReferenceClock Class

CBaseReferenceClock class hierarchy

This base class implements the IReferenceClock interface.

The CBaseReferenceClock class provides a full implementation of IReferenceClock. It uses CCritSec locking support and CAMSchedule scheduler support.

Each advise call defines a point in time when the caller wants to be notified. A periodic advise is a regular series of such events. A list of these advise requests is maintained by the reference clock. The clock calculates the delay until the first requested advise, and signals an event at the due time.

Clients are not advised through callbacks. One-shot clients have an event set, while periodic clients have a semaphore released for each event notification. A semaphore allows a client to know exactly how many events were actually triggered, because multiple time periods might elapse before the client code executes.

During class construction, a worker thread is created. This thread executes a series of Microsoft® Win32® WaitForSingleObject calls, waking up when a command is given to the thread or the next wake-up point is reached. The wake-up points are determined by clients making advise calls.

Protected Data Members
m_pSchedule Pointer to the CAMSchedule object associated with this CBaseReferenceClock object.

Member Functions
Name | Description
CBaseReferenceClock | Constructs a CBaseReferenceClock object.
GetSchedule | Returns the CAMSchedule pointer stored in the CBaseReferenceClock::m_pSchedule data member.
SetTimeDelta | Adjusts the values returned from CBaseReferenceClock::GetPrivateTime by the amount specified in this member function.
TriggerThread | Triggers the advise thread's event. If you override CBaseReferenceClock::GetPrivateTime, you should either reuse or abandon this method.

Implemented IReferenceClock Methods
Name | Description
AdvisePeriodic | Requests an asynchronous periodic notification that a time has elapsed.
AdviseTime | Requests an asynchronous notification that a time has elapsed.
GetTime | Returns a reference time.
Unadvise | Removes a previously established advise link.

Overridable Member Functions
Name | Description
GetPrivateTime | Gets the current time from the real clock. Override this member function to implement your own clock.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a pointer to interfaces supported, that is, IReferenceClock.

CBaseReferenceClock::AdvisePeriodic

CBaseReferenceClock Class

Sets up a recurring advise with the reference clock.

HRESULT AdvisePeriodic(
REFERENCE_TIME StartTime,
REFERENCE_TIME PeriodTime,
HSEMAPHORE hSemaphore,
DWORD *pdwAdviseToken
);

Parameters
StartTime
Start at this time.
PeriodTime
Time between notifications.
hSemaphore
Advise through a semaphore.
pdwAdviseToken
Advise token that identifies the link with the clock.
Return Values

Returns one of the following HRESULT values:
Value | Meaning
E_OUTOFMEMORY | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | No error.

Remarks

This member function implements the IReferenceClock::AdvisePeriodic method. A semaphore is used, rather than an event, to ensure that multiple notifications can be seen by the user. Each time an amount of time specified in the PeriodTime parameter elapses, the semaphore will be released.

When no further notifications are required, call CBaseReferenceClock::Unadvise and pass the pdwAdviseToken value returned from this call.

For example, the following code extract sets up an advise link that fires its first advise five seconds from now and then signals every second until Unadvise is called. By using a semaphore with a count of 10, the clock is effectively able to cache 10 events.

HANDLE hSemaphore = CreateSemaphore(NULL, 0, 10, NULL);
    // assume pRefClock is an IReferenceClock* variable

    REFERENCE_TIME rtPeriodTime = 1000 * (UNITS / MILLISECONDS);
        // a one-second interval
    REFERENCE_TIME rtNow;
    DWORD    dwAdviseToken;
    pRefClock->GetTime(&rtNow);

    pRefClock->AdvisePeriodic(rtNow+(5*rtPeriodTime),
        PeriodTime, hSemaphore, &dwAdviseToken);

CBaseReferenceClock::AdviseTime

CBaseReferenceClock Class

Sets up a one-shot notification with the clock.

HRESULT AdviseTime(
REFERENCE_TIME baseTime,
REFERENCE_TIME streamTime,
HEVENT hEvent,
DWORD *pdwAdviseToken
);

Parameters
baseTime
Base reference time.
streamTime
Stream offset time.
hEvent
Advise through this event.
pdwAdviseToken
Where the advise token goes.
Return Values

Returns one of the following HRESULT values:
Value | Meaning
E_OUTOFMEMORY | Failure.
E_INVALIDARG | Invalid argument.
NOERROR | No error.

Remarks

This member function implements the IReferenceClock::AdviseTime method. At the time specified in the baseTime plus the streamTime parameters, the event specified in hEvent will be set. It is correct to call CBaseReferenceClock::Unadvise to remove the link after the event has occurred, but it is not necessary. One-shot notifications are automatically cleared by the clock once they have signaled.

To cancel a one-shot notification before the time is reached, call Unadvise and pass the pdwAdviseToken value returned from this call.

CBaseReferenceClock::CBaseReferenceClock

CBaseReferenceClock Class

Constructs a CBaseReferenceClock object.

CBaseReferenceClock(
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr,
CAMSchedule * pSched
);

Parameters
pName
Name of the CBaseReferenceClock object.
pUnk
IUnknown interface of the delegating object.
phr
Address of an HRESULT value.
pSched
Address of a CAMSchedule object that will be associated with this CBaseReferenceClock object. If pSched is NULL, the constructor creates a new CAMSchedule object and associates it with this CBaseReferenceClock object.
Return Values

No return value.

CBaseReferenceClock::GetPrivateTime

CBaseReferenceClock Class

Retrieves the current reference time.

virtual REFERENCE_TIME GetPrivateTime( );

Return Values

Returns the current reference time, in 100-nanosecond units.

Remarks

GetPrivateTime represents the actual clock. GetTime is the externally used member function. Derived classes will probably override this method, but not GetTime itself. The important point about GetPrivateTime is that it is allowed to go backward. This class's GetTime member function will keep returning the last time returned by GetTime until GetPrivateTime catches up.

CBaseReferenceClock::GetSchedule

CBaseReferenceClock Class

Retrieves the CAMSchedule pointer stored in the CBaseReferenceClock::m_pSchedule data member.

CAMSchedule * GetSchedule( );

CBaseReferenceClock::GetTime

CBaseReferenceClock Class

Retrieves the current reference time, in 100-nanosecond units.

HRESULT GetTime(
REFERENCE_TIME *pTime
);

Parameters
pTime
Where the current time is returned.
Return Values

Returns one of the following HRESULT values:
Value | Meaning
E_POINTER | NULL pointer argument.
S_FALSE | Failure.
S_OK | Success.

Remarks

This member function implements the IReferenceClock::GetTime method. It reads the time from the implemented clock and returns the current time.

CBaseReferenceClock::NonDelegatingQueryInterface

CBaseReferenceClock Class

Accesses supported interfaces.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
IID of the interface being requested. Only IID_IReferenceClock is supported by the clock interface.
ppv
Where the IReferenceClock pointer is returned.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

CBaseReferenceClock::SetTimeDelta

CBaseReferenceClock Class

Sets a delta on the time that CBaseReferenceClock::GetPrivateTime will return.

HRESULT SetTimeDelta(
const REFERENCE_TIME& TimeDelta
);

Parameters
TimeDelta
REFERENCE_TIME delta to be added.
Return Values

Returns NOERROR.

Remarks

Note that CBaseReferenceClock::GetTime will never return a time earlier than a previously returned time. Thus, if you set the clock to a time in the past, successive calls to CBaseReferenceClock::GetTime will return the current value until this new time is reached, and the clock will start to increment again.

CBaseReferenceClock::TriggerThread

CBaseReferenceClock Class

Triggers the advise thread's event.

void TriggerThread( );

Return Values

No return value.

Remarks

The clock uses a worker thread that should wake up and call CAMSchedule::Advise at the appropriate time. If the clock adds an event that should be fired earlier than any currently outstanding event, the worker thread needs to be awoken in order to reevaluate its wait time. The TriggerThread member function will wake up the worker thread so this can take place. If a derived clock causes time to jump forward for some reason, TriggerThread should be called so that the wait time can be reevaluated; otherwise, the events will fire late.

CBaseReferenceClock::Unadvise

CBaseReferenceClock Class

Removes a previously established advise link.

HRESULT Unadvise(
DWORD dwAdviseToken
);

Parameters
dwAdviseToken
Identifier (token) of the link that is being reset. This is the same value that was returned on CBaseReferenceClock::AdviseTime or CBaseReferenceClock::AdvisePeriodic.
Return Values

Returns S_OK if the successful, S_FALSE if not.

Remarks

This member function implements the IReferenceClock::Unadvise method. Call Unadvise to remove the previously established clock advise links. It is mandatory to call Unadvise on periodic advises in order to stop further calls. It is recommended to call Unadvise for single-shot advise links.


CBaseRenderer Class

CBaseRenderer class hierarchy

CBaseRenderer is the base renderer class for writing renderers. This class handles a single input pin, all state changes, and synchronization.

Protected Data Members
Name | Description
m_bAbort | Stop rendering data.
m_bEOS | Indicator for whether there are more samples in the stream.
m_bEOSDelivered | Indicator for whether an EC_COMPLETE event has been delivered.
m_bRepaintStatus | Flag to determine if an EC_REPAINT message can be signaled.
m_bStreaming | Indicator for whether the filter graph is currently streaming.
m_dwAdvise | Timer advise token returned by the clock.
m_EndOfStreamTimer | Time that specifies the end of the stream.
m_evComplete | Event signaled when the pause state is complete.
m_InterfaceLock | Critical section for interfaces.
m_pInputPin | Renderer input pin object.
m_pMediaSample | Current media sample about to be, or being rendered.
m_pPosition | CRendererPosPassThru object for passing positioning data upstream.
m_pQSink | Quality control sink.
m_RendererLock | Controller for access to current media sample.
m_RenderEvent | Used to signal timer events.
m_SignalTime | Amount of time that must elapse before CBaseRenderer returns EC_COMPLETE.
m_ThreadSignal | Event signaled to release the source filter thread.

Member Functions
Name | Description
Active | Called when the state is switched to paused or running. Override to add functionality.
CBaseRenderer | Constructs a CBaseRenderer object.
CheckReady | Determines if the event is set.
DisplayRendererState | Displays the status of the video renderer. This function is available only in debug mode.
GetRealState | Retrieves the actual state of the renderer.
GetRenderEvent | Retrieves the event to render.
IsEndOfStream | Determines if the end of the stream has been reached.
IsEndOfStreamDelivered | Determines if the end of the stream has been delivered to the filter graph manager.
IsStreaming | Determines if the filter is currently rendering data.
NotifyEndOfStream | Sends an EC_COMPLETE event to the filter graph manager.
NotReady | Forces the m_evComplete event into a nonsignaled state.
Ready | Puts the m_evComplete event into a signaled state.
ResetEndOfStreamTimer | Sets the end of stream timer to zero.
ScheduleSample | Sets up an advise link with the clock.
SendNotifyWindow | Passes the notification window handle to the upstream filter.
SendRepaint | Conditionally signals an EC_REPAINT message to the filter graph.
SetAbortSignal | Sets the abort signal flag.
SetRepaintStatus | Resets the repaint status flag.
SignalTimerFired | Resets the current advise time to zero after a timer fires.
TimerCallback | Checks if it is time to signal the end of the current data stream.

Overridable Member Functions
Name | Description
BeginFlush | Signals the start of flushing on the input pin.
BreakConnect | Breaks the input pin connection and resets the end-of-stream flags.
CancelNotification | Cancels any currently scheduled notification with the clock.
CheckMediaType | Determines if the renderer will accept a given media type.
ClearPendingSample | Called to release the pending sample after it has been rendered.
CompleteConnect | Called as part of the connection protocol. Override to add functionality.
CompleteStateChange | Ensures that a sample is waiting before allowing a pause.
DoRenderSample | Called when a sample is ready to render.
GetCurrentSample | Retrieves the current sample waiting at the video renderer.
GetPin | Returns a CBasePin object to the renderer.
GetPinCount | Returns the number of input pins supported.
EndFlush | Called when the input pin receives an end-flush notification.
EndOfStream | Called when the input pin receives an end-of-stream notification.
GetMediaPositionInterface | Retrieves IMediaPosition and IMediaSeeking interfaces for the video renderer.
GetSampleTimes | Retrieves sample time information for this sample.
HaveCurrentSample | Determines if a sample is waiting at the renderer.
Inactive | Called when going into a stopped state. Override to add functionality.
NonDelegatingQueryInterface | Returns an interface and increments the reference count.
OnReceiveFirstSample | Provides derived classes with an opportunity to render static data.
OnRenderEnd | Notifies the derived class that a sample has just finished rendering.
OnRenderStart | Notifies the derived class that a sample is about to be rendered.
OnStartStreaming | Notifies the derived class that rendering has started.
OnStopStreaming | Notifies the derived class that rendering has stopped.
OnWaitEnd | Notifies the derived class that a wait for a rendering time has just ended.
OnWaitStart | Notifies the derived class that a wait for a rendering time is about to start.
Pause | Tells the renderer to transition to the new (paused) state.
PrepareReceive | Called to schedule a clock time when the renderer receives a sample.
PrepareRender | Allows derived classes to set themselves just before a sample is rendered.
Receive | Called by the source filter when a sample is available to render.
Render | Asks the derived class to render the sample.
ResetEndOfStream | Resets the end-of-stream flag.
Run | Transitions the renderer to State_Running if it is not already in this state.
SendEndOfStream | Sets the end-of-stream flag.
SetMediaType | Informs the derived class of the selected media type.
ShouldDrawSampleNow | Determines if the sample should be drawn between the start and stop times given.
SourceThreadCanWait | Sets or resets the thread event.
StartStreaming | Called to schedule any pending sample with the clock, and to display any timing information.
Stop | Tells the renderer to transition to the new (stopped) state.
StopStreaming | Sets an internal flag to indicate not to schedule arrival of any more samples.
WaitForRenderTime | Waits for either the time to arrive or for rendering to be stopped.

Implemented IMediaFilter Methods
Name | Description
GetState | Determines the state of the renderer.

Implemented IBaseFilter Methods
Name | Description
FindPin | Retrieves a pointer to the pin with the specified identifier. (There is only one pin.)

Helper Function
Name | Description
WaitForReceiveToComplete | Waits for the CBaseRenderer::Receive method to complete.

CBaseRenderer::Active

CBaseRenderer Class

Called when the state is switched to paused or running.

virtual HRESULT Active(void);

Return Values

Returns an HRESULT value. Returns NOERROR by default.

Remarks

This member function does nothing by default. Derived classes can optionally override this member function to add functionality.

CBaseRenderer::BeginFlush

CBaseRenderer Class

Informs the renderer that flushing has started.

virtual HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called by CRendererInputPin::BeginFlush when informed of a flush from the upstream filter. It releases the source thread and signals the start of flushing on the input pin. Any samples received by the renderer when it is in a flushing state will be rejected.

CBaseRenderer::BreakConnect

CBaseRenderer Class

Called when a connection is broken.

virtual HRESULT BreakConnect(void);

Return Values

Returns an HRESULT value.

Remarks

This member function resets the end-of-stream flag and checks for a valid connection, or that the filter is in a stopped state. Override to customize.

CBaseRenderer::CancelNotification

CBaseRenderer Class

Cancels any currently scheduled notification.

virtual HRESULT CancelNotification(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called when the renderer is told to stop streaming. If there is no timer link outstanding, calling this member function does nothing; otherwise, this function stops the advise link and resets the render event. The normal process when running is to receive a sample, wait until it is time to render it and then render it. The clock is given an event to signal when the desired time arrives.

CBaseRenderer::CBaseRenderer

CBaseRenderer Class

Constructs a CBaseRenderer object.

CBaseRenderer(
REFCLSID RenderClass,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
RenderClass
Class identifier for this renderer.
pName
Name used for debugging purposes.
pUnk
Owner object.
phr
Pointer to the HRESULT return code.
Return Values

No return value.

CBaseRenderer::CheckMediaType

CBaseRenderer Class

Determines if the renderer will accept a given media type.

virtual HRESULT CheckMediaType(
const CMediaType * pmt
) PURE;

Parameters
pmt
Pointer to a media type object that contains the proposed media type.
Return Values

Returns an HRESULT value.

Remarks

This member function must be overridden and implemented, typically to return the media type of the display. It is called from the CRendererInputPin::CheckMediaType member function during the connection process.

CBaseRenderer::CheckReady

CBaseRenderer Class

Determines if the renderer is ready to process the next sample.

BOOL CheckReady(void);

Return Values

Returns TRUE if the m_evComplete event is currently set, but does not block.

Remarks

This member function calls the CAMEvent::Check member function. This is mainly used in transitioning to paused states. When a renderer is paused, it should not complete the state change until it has received some data. So although the call to IMediaFilter::Pause completes immediately, if the application calls IMediaFilter::GetState it will return VFW_S_STATE_INTERMEDIATE. When a sample arrives at the renderer, the event that is initially reset during the pause call will be signaled. At this point, an application calling IMediaFilter::GetState will return NOERROR. This process allows an application to pause a filter graph and then wait until data is actually queued and ready to be rendered.

CBaseRenderer::ClearPendingSample

CBaseRenderer Class

Called to clear the pending sample when in a stopped or inactivated state.

virtual HRESULT ClearPendingSample(void);

Return Values

Returns an HRESULT value.

Remarks

This member function releases the IMediaSample interface. This allows the allocator to reuse it and allocate it to the upstream filter again. If the state is being changed to inactive, IMemAllocator::GetBuffer will return an error. This function also resets the current media sample to NULL to indicate that no data is now available.

CBaseRenderer::CompleteConnect

CBaseRenderer Class

Called as part of the connection protocol.

virtual HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Connecting pin.
Return Values

Returns an HRESULT value (NOERROR by default).

Remarks

This member function calls the SetRepaintStatus member function to set the m_bRepaintStatus data member to TRUE so that EC_REPAINT notifications can be sent in the future. (To prevent unnecessary EC_REPAINT notifications from being sent, m_bRepaintStatus is set to FALSE when an end-of-stream notification arrives.)

CBaseRenderer::CompleteStateChange

CBaseRenderer Class

Ensures that a sample is waiting before allowing a pause.

virtual HRESULT CompleteStateChange(
FILTER_STATE OldState
);

Parameters
OldState
State prior to the transition.
Return Values

Returns S_OK if the filter can be paused; otherwise, returns S_FALSE.

Remarks

This member function is called from the CBaseRenderer::Pause member function. If the filter is being paused and there is no sample waiting, the transition is not completed and the function returns S_FALSE until the first sample arrives. However, if the m_bAbort flag has been set, all samples are rejected so there is no point waiting for one. If a sample is available, this member function returns NOERROR.

CBaseRenderer::DisplayRendererState

CBaseRenderer Class

Displays the status of the video renderer. This function is available only in debug mode.

void CBaseRenderer::DisplayRendererState( );

Return Values

No return value.

Remarks

Use this function to monitor the activity of the video renderer. The following is a sample output of this function.

Timed out in WaitForRenderTime
Signal sanity check 0
Filter state 1
Abort flag 0
Streaming flag 0
Clock advise link 0
Current media sample 0
EOS signalled 0
EOS delivered 0
Repaint status 1
End of stream timer 0
Deliver time 0x000000000
Flushing sanity check 0
Last run time 0x000000000
Clock time 0x22C2CD23430
Time difference 238875379ms

CBaseRenderer::DoRenderSample

CBaseRenderer Class

Called when a sample is ready to render.

virtual HRESULT DoRenderSample(
IMediaSample *pMediaSample
) PURE;

Parameters
pMediaSample
Media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function must be overridden in the derived class. It is called by CBaseRenderer::Render.

The derived class should render the object at this time. For example, the sample video renderer (SAMPVID) calls its drawing object (a CDrawImage object):

// Have the drawing object render the current image

HRESULT CVideoRenderer::DoRenderSample(IMediaSample *pMediaSample)
{
    return m_DrawImage.DrawImage(pMediaSample);
}

CBaseRenderer::EndFlush

CBaseRenderer Class

Called when the input pin receives an end-flush notification.

virtual HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called from the CRendererInputPin::EndFlush member function. It calls CBaseRenderer::SourceThreadCanWait with a TRUE value to allow the upstream filter's thread to wait in CBaseRenderer::Receive again.

CBaseRenderer::EndOfStream

CBaseRenderer Class

Called when the input pin receives an end-of-stream notification.

HRESULT EndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

If all received samples have been rendered, this member function notifies EC_COMPLETE. If samples have been received and not yet rendered, this function sets m_bEOS and checks for it on completing samples. If the filter is waiting to be paused, this function completes the transition to paused state by setting the state event.

CBaseRenderer::FindPin

CBaseRenderer Class

Retrieves a pointer to the pin with the specified identifier.

HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);

Parameters
Id
Identifier of the pin.
ppPin
Pointer to the IPin interface for this pin after the renderer has been restored.
Return Values

Returns NOERROR if successful; otherwise, returns VFW_E_NOT_FOUND.

Remarks

This member function implements the IBaseFilter::FindPin method. It assumes that the default pin name is "In" and checks for this. If the pin is found, its reference count is incremented. The ppPin parameter is set to NULL if the identifier cannot be matched.

CBaseRenderer::GetCurrentSample

CBaseRenderer Class

Retrieves the current sample waiting at the video renderer, or NULL if there is not one.

virtual IMediaSample *GetCurrentSample(void);

Return Values

Returns a pointer to the sample.

Remarks

The reference count for the sample is incremented before returning. This is so that if the sample comes due for rendering, it is not added back to the allocator free list until the caller of this member function releases it.

CBaseRenderer::GetMediaPositionInterface

CBaseRenderer Class

Retrieves IMediaPosition and IMediaSeeking interfaces for the video renderer.

virtual HRESULT GetMediaPositionInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns an HRESULT value.

Remarks

A CRendererPosPassThru helper object is created dynamically when this is called to support passing the IMediaPosition or IMediaSeeking interface calls from the filter graph manager to the upstream filter.

CBaseRenderer::GetPin

CBaseRenderer Class

Returns a CBasePin object on the renderer.

virtual CBasePin *GetPin(
int n
);

Parameters
n
Number of the specified pin, which is always zero in the case of the renderer.
Return Values

Returns a pointer to the pin specified by the n parameter.

Remarks

This member function overrides CBaseFilter::GetPin. Only one pin is supported on the renderer; it is numbered zero. A call to this member function with n equal to zero will result in an input pin of type CRendererInputPin being returned. It will be created if it does not yet exist.

CBaseRenderer::GetPinCount

CBaseRenderer Class

Retrieves the number of input pins supported.

virtual int GetPinCount(void);

Return Values

The default implementation returns one, since only one pin is supported. Override to support more than one pin. Because the base renderer class is specifically designed for single-pin operation, considerably more of the base class functionality would have to be changed to make a multipin renderer. Future versions of the SDK might provide this functionality.

Remarks

This member function overrides CBaseFilter::GetPinCount.

CBaseRenderer::GetRealState

CBaseRenderer Class

Retrieves the actual state of the renderer.

FILTER_STATE GetRealState(void);

Return Values

Returns m_State, the state flag for the renderer.

Remarks

This member function provides an internal way of getting the real state. Calling through the IBaseFilter interface to get the state would require the main filter critical section to be taken; this internal method does not do this.

CBaseRenderer::GetRenderEvent

CBaseRenderer Class

Retrieves the event to render.

CAMEvent *GetRenderEvent(void);

Return Values

Returns the value of m_RenderEvent.

CBaseRenderer::GetSampleTimes

CBaseRenderer Class

Retrieves sample time information for this sample.

virtual HRESULT GetSampleTimes(
IMediaSample *pMediaSample,
REFERENCE_TIME *pStartTime,
REFERENCE_TIME *pEndTime
);

Parameters
pMediaSample
Media sample.
pStartTime
Start time.
pEndTime
End time.
Return Values

Returns S_FALSE if the sample should be scheduled according to the times specified in the sample; returns S_OK to indicate that the sample should be rendered immediately.

Remarks

Note that the sample times are passed in by reference, not value.

CBaseRenderer::GetState

CBaseRenderer Class

Determines the state of the renderer.

HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);

Parameters
dwMilliSecsTimeout
Duration of the time-out, in milliseconds.
State
Returned state of the renderer.
Return Values

Returns an HRESULT value. Returns VFW_S_STATE_INTERMEDIATE if paused and waiting for a sample; otherwise, returns NOERROR.

Remarks

This member function overrides the CBaseFilter::GetState member function. It returns the value of m_State. Because the renderer does not complete the full transition to the paused state until it has a sample to render, if the state is requested while it is waiting for a sample, it will return VFW_S_STATE_INTERMEDIATE along with the state.

CBaseRenderer::HaveCurrentSample

CBaseRenderer Class

Determines if a sample is waiting at the renderer.

virtual BOOL HaveCurrentSample(void);

Return Values

Returns TRUE if a sample is ready to be rendered, or FALSE if no data is available.

CBaseRenderer::Inactive

CBaseRenderer Class

Called when going into a stopped state.

virtual HRESULT Inactive(void);

Return Values

Returns NOERROR by default; overriding member function should return a valid HRESULT value.

Remarks

This member function is a placeholder that derived classes can optionally override to add functionality when the filter is stopped.

CBaseRenderer::IsEndOfStream

CBaseRenderer Class

Determines if the end of the stream has been reached.

BOOL IsEndOfStream(void);

Return Values

Returns TRUE if the stream's end has been reached, or FALSE if it hasn't.

Remarks

The default implementation returns m_bEOS.

CBaseRenderer::IsEndOfStreamDelivered

CBaseRenderer Class

Determines if the end of the stream has been delivered to the filter graph manager.

BOOL IsEndOfStreamDelivered(void);

Return Values

Returns TRUE if the stream's end has been delivered, or FALSE if it hasn't.

Remarks

The default implementation returns m_bEOSDelivered. This is used by the base renderer class so that only one EC_COMPLETE message is sent to the filter graph manager each time it is run, regardless of the number of times EndOfStream is called.

CBaseRenderer::IsStreaming

CBaseRenderer Class

Determines if the filter is streaming data.

BOOL IsStreaming(void);

Return Values

Returns TRUE if the renderer is rendering, or FALSE if it isn't.

Remarks

The default implementation returns m_bStreaming. In the base renderer class, "streaming" and "rendering" are used in the same context as "running".

CBaseRenderer::NonDelegatingQueryInterface

CBaseRenderer Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function overrides CBaseFilter::NonDelegatingQueryInterface. It exposes the IMediaPosition and IMediaSeeking interfaces and then calls CBaseFilter::NonDelegatingQueryInterface for interfaces implemented in the base classes.

CBaseRenderer::NotReady

CBaseRenderer Class

Forces the m_evComplete event into a nonsignaled state.

void NotReady(void);

Return Values

No return value.

Remarks

This member function calls the CAMEvent::Reset member function of the m_evComplete event object.

CBaseRenderer::NotifyEndOfStream

CBaseRenderer Class

Sends an EC_COMPLETE event to the filter graph manager.

void NotifyEndOfStream(void);

Return Values

No return value.

CBaseRenderer::OnReceiveFirstSample

CBaseRenderer Class

Provides derived classes with an opportunity to render static data.

virtual void OnReceiveFirstSample(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

This member function is unimplemented. It is primarily used by video renderers. When they receive their first sample while paused, they typically draw the frame as a poster image. This virtual method is called by the base classes when the first sample arrives.

CBaseRenderer::OnRenderEnd

CBaseRenderer Class

Notifies the derived class that rendering has finished.

virtual void OnRenderEnd(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

This member function is available for quality management and performance measuring. It is called immediately after the sample is rendered.

Quality management implementations typically need to know how long it takes the renderer to render the data.

CBaseRenderer::OnRenderStart

CBaseRenderer Class

Notifies the derived class that rendering is about to start.

virtual void OnRenderStart(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

This member function is available for quality management and performance measuring. It is called immediately before the sample is rendered.

Quality management implementations typically need to know how long it takes the renderer to render the data.

CBaseRenderer::OnStartStreaming

CBaseRenderer Class

Notifies the derived class that streaming has started.

virtual HRESULT OnStartStreaming(void);

Return Values

Returns NOERROR in the default implementation.

Remarks

This member function is called from CBaseRenderer::StartStreaming. Override this in your derived class to provide special handling when streaming starts.

CBaseRenderer::OnStopStreaming

CBaseRenderer Class

Notifies the derived class that streaming has stopped.

virtual HRESULT OnStopStreaming(void);

Return Values

Returns NOERROR in the default implementation.

Remarks

This member function is called from CBaseRenderer::StopStreaming. Override this in your derived class to provide special handling when streaming stops.

CBaseRenderer::OnWaitEnd

CBaseRenderer Class

Notifies the derived class that a wait for a rendering time has just ended.

virtual void OnWaitEnd(void);

Return Values

No return value.

Remarks

This member function is available for quality control and is called from CBaseRenderer::WaitForRenderTime just after waiting for the presentation time for a sample. Override this member function to obtain performance measurements in a derived class.

CBaseRenderer::OnWaitStart

CBaseRenderer Class

Notifies the derived class that a wait for a rendering time is about to start.

virtual void OnWaitStart(void);

Return Values

No return value.

Remarks

This member function is available for quality control and is called from CBaseRenderer::WaitForRenderTime just before waiting for the presentation time for a sample. Override this member function to obtain performance measurements in a derived class.

CBaseRenderer::Pause

CBaseRenderer Class

Changes the renderer to State_Paused if it isn't already.

HRESULT Pause(void);

Return Values

Returns an HRESULT value.

Remarks

The following steps comprise a pause operation.

  1. Commit the allocator used for the connection.
  2. Allow the thread for the upstream filter to wait in Receive.
  3. Cancel any outstanding clock advise links.
  4. Check to see if the renderer is connected and allow a state change.
  5. If a sample is available, complete the state change to State_Paused.

If the member function succeeds, DirectShow sets the filter's m_State member variable to State_Paused. If the renderer is in the State_Stopped state, DirectShow calls the CBasePin::Active member function for each of the renderer's connected pins.

This member function overrides CBaseFilter::Pause.

CBaseRenderer::PrepareReceive

CBaseRenderer Class

Ensures that a sample can be rendered.

virtual HRESULT PrepareReceive(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns NOERROR if successful, VFW_E_SAMPLE_REJECTED if the delivered sample is later than the sample's timestamp, or E_UNEXPECTED if a renderable sample is already available.

Remarks

This member function is called when the upstream filter delivers a sample. If the upstream filter is running (streaming), the sample is scheduled with the reference clock. If the upstream filter is not streaming, a sample in paused mode has been received, so any state transition can be completed. On leaving this function, everything will be unlocked so an application thread can get in and change the state to stopped. In this case, it will also signal the thread event so that the wait call is stopped.

This function is typically called from the IMemInputPin::Receive method on the renderer's input pin. Although PrepareReceive returns VFW_E_SAMPLE_REJECTED if the sample was delivered too late to be useful, the IMemInputPin::Receive method should not pass the VFW_E_SAMPLE_REJECTED error on to the upstream filter in this case. Instead, IMemInputPin::Receive should return NOERROR, because no error occurred.

CBaseRenderer::PrepareRender

CBaseRenderer Class

Provides an opportunity for the derived class to prepare itself for rendering a sample.

virtual void PrepareRender(void);

Return Values

No return value.

Remarks

This member function is called from CBaseRenderer::Receive before rendering each frame. A derived class can take this opportunity to prepare itself for rendering. For example, a video renderer might realize its palette. This is not implemented in the base class.

CBaseRenderer::Ready

CBaseRenderer Class

Puts the m_evComplete event into a signaled state.

void Ready(void);

Return Values

No return value.

Remarks

This member function calls the m_evComplete CAMEvent object's Set member function.

CBaseRenderer::Receive

CBaseRenderer Class

Called by the upstream filter when a sample is available to render.

virtual HRESULT Receive(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function sets an advise link with the clock, waits for the time to arrive, and then renders the data by calling the pure virtual DoRenderSample member function that the derived class will have overridden. After rendering the sample, the end of stream can also be signaled if it was the last one sent before EndOfStream was called.

CBaseRenderer::Render

CBaseRenderer Class

Asks the derived class to render the sample.

virtual HRESULT Render(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function is called when the derived class should render the sample. The action taken is dependent on the nature of the renderer; a video renderer will typically draw the image in a window. This class calls the pure virtual DoRenderSample to be implemented by the derived class.

CBaseRenderer::ResetEndOfStream

CBaseRenderer Class

Resets the end-of-stream flag.

virtual HRESULT ResetEndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is typically called when changing to stopped states. A renderer must keep track of when it gets told that no more data is going to arrive (this is done when the sourcing filter calls IPin::EndOfStream). At this point the renderer finishes rendering any data it has and then sends an EC_COMPLETE event to the filter graph manager.

However, when the filter is stopped, the whole state is cleared. When the filter is subsequently run, the source filter will signal the end of stream again if it has no data to send. In this case, the renderer should signal another EC_COMPLETE event to the filter graph manager. This member function resets the state so that when next requested it will send an EC_COMPLETE event.

CBaseRenderer::ResetEndOfStreamTimer

CBaseRenderer Class

If the end-of-stream timer is nonzero, this function sets it to zero.

void ResetEndOfStreamTimer(void);

Return Values

No return value.

CBaseRenderer::Run

CBaseRenderer Class

Transitions the renderer to State_Running if it is not in this state already.

HRESULT Run(void);

Return Values

Returns an HRESULT value.

Remarks

If the renderer is in the State_Stopped state, the CBaseRenderer::Pause member function is called first to transition the renderer to the State_Paused state, which has the effect of activating any of the filter's connected pins. If this member function succeeds, the renderer's m_State member variable is set to State_Running.

This member function overrides CBaseFilter::Run.

CBaseRenderer::ScheduleSample

CBaseRenderer Class

Schedules the sample for rendering.

virtual BOOL ScheduleSample(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

One of the main purposes of the renderer base class is to manage the timing and synchronization of the samples it is sent; that is, the timely presentation of data. It also must look after quality management, which might involve dropping samples or rendering them earlier than indicated in the time stamps on the sample. This method and its overrides in derived classes manage the setting up of advise links with the clock, so that the samples can be rendered at the appropriate time.

CBaseRenderer::SendEndOfStream

CBaseRenderer Class

Signals an EC_COMPLETE event to the filter graph manager.

virtual HRESULT SendEndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

When the renderer receives an end-of-stream notification, it will finish rendering any data it currently has and then send an EC_COMPLETE event to the filter graph manager.

CBaseRenderer::SendNotifyWindow

CBaseRenderer Class

Passes the notification window handle to the upstream filter.

void SendNotifyWindow(
IPin *pPin,
HWND hwnd
);

Parameters
pPin
IPin interface of the upstream pin.
hwnd
Handle of the notification window.
Return Values

No return value.

Remarks

If the output pin of the upstream filter supports the IMediaEventSink interface, this member function sends it the EC_NOTIFY_WINDOW event code with the window handle in hwnd.

CBaseRenderer::SendRepaint

CBaseRenderer Class

Signals an EC_REPAINT message to the filter graph.

void SendRepaint(void);

Return Values

No return value.

Remarks

This should be used with some care. EC_REPAINT events are processed by the filter graph manager by setting the current position to the same position that the graph is currently in. This has the effect of sending the same data through the graph again, which is an expensive operation. Video renderers are the main users of this event, because they sometimes need the same image sent again to refresh the display.

CBaseRenderer::SetAbortSignal

CBaseRenderer Class

Sets the m_bAbort abort signal flag.

void SetAbortSignal(
BOOL bAbort
);

Parameters
bAbort
Abort value to be set.
Return Values

Returns an HRESULT value.

CBaseRenderer::SetMediaType

CBaseRenderer Class

Informs the derived class of the selected media type.

virtual HRESULT SetMediaType(
const CMediaType *pmt
);

Parameters
pmt
Media type to be set.
Return Values

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

This member function is called by the CRendererInputPin::SetMediaType member function and has no implementation in this class. Derived classes can optionally override to add functionality.

CBaseRenderer::SetRepaintStatus

CBaseRenderer Class

Resets the m_bRepaintStatus flag when EC_REPAINT has been signaled to the filter graph.

void SetRepaintStatus(
BOOL bRepaint
);

Parameters
bRepaint
Boolean value assigned to the m_bRepaintStatus flag.
Return Values

No return value.

Remarks

The m_bRepaintStatus flag ensures that the filter graph is not flooded with redundant calls. Once one EC_REPAINT message has been sent, no more will be sent until the renderer receives some data.

CBaseRenderer::ShouldDrawSampleNow

CBaseRenderer Class

Determines if the sample should be drawn between the start and stop times given.

virtual HRESULT ShouldDrawSampleNow(
IMediaSample *pMediaSample,
REFERENCE_TIME *pStartTime,
REFERENCE_TIME *pEndTime
);

Parameters
pMediaSample
Media sample.
pStartTime
Start time in question.
pEndTime
End time in question.
Return Values

Returns S_FALSE by default. The overriding member function can return S_OK to indicate that the sample should be drawn immediately instead of waiting for its scheduled time.

Remarks

This member function is used by the derived video renderer class for quality management.

CBaseRenderer::SignalTimerFired

CBaseRenderer Class

Resets the current advise time to zero after a timer fires.

virtual void SignalTimerFired(void);

Return Values

No return value.

CBaseRenderer::SourceThreadCanWait

CBaseRenderer Class

Sets or resets the thread event.

virtual HRESULT SourceThreadCanWait(
BOOL bCanWait
);

Parameters
bCanWait
TRUE or FALSE, depending on intent.
Return Values

Returns an HRESULT value.

Remarks

In some states, such as paused or running, it is expected that the upstream filter's thread will be blocked in the call to the renderer's input pin Receive method. In other cases, such as when the renderer is stopped, the upstream filter should not be required to wait. This member function represents a manual reset event that sets this TRUE to wait, or FALSE to keep the thread from waiting.

CBaseRenderer::StartStreaming

CBaseRenderer Class

Called to schedule any pending sample with the clock, and to display timing information.

virtual HRESULT StartStreaming(void);

Return Values

Returns an HRESULT value.

Remarks

If no sample is available but an end-of-stream flag is queued, this member function sends an EC_COMPLETE message to the filter graph manager. If a sample is available, the EC_COMPLETE message will not be sent until it has been rendered.

CBaseRenderer::Stop

CBaseRenderer Class

Transitions the renderer to State_Stopped if it is not in this state already.

HRESULT Stop(void);

Return Values

Returns an HRESULT value.

Remarks

If the renderer is not in the State_Stopped state, the CRendererInputPin::Inactive member function is called for each of the renderer's connected pins. If this member function succeeds, the filter's m_State member variable is set to State_Stopped.

This member function overrides CBaseFilter::Stop.

CBaseRenderer::StopStreaming

CBaseRenderer Class

Sets the internal flag to indicate not to schedule arrival of any more samples.

virtual HRESULT StopStreaming(void);

Return Values

Returns an HRESULT value.

Remarks

Call this member function when streaming stops. The state change methods in the filter implementation take care of canceling any clock advise link that has been set up and clearing any pending sample.

CBaseRenderer::TimerCallback

CBaseRenderer Class

Checks if it is time to signal the end of the current data stream.

void TimerCallback(void);

Return Values

No return value.

Remarks

If the m_EndOfStreamTimer data member is nonzero, this function sets it to zero and calls CBaseRenderer::SendEndOfStream to signal the end of the current data stream.

CBaseRenderer::WaitForReceiveToComplete

CBaseRenderer Class

Waits for the CBaseRenderer::Receive method to complete.

void WaitForReceiveToComplete( );

Return Values

No return value.

Remarks

Use this method when you wish to avoid deadlock which occurs when CBaseRenderer::Stop is called and the CBaseRenderer::Receive hasn't completed.

CBaseRenderer::WaitForRenderTime

CBaseRenderer Class

Waits for either the due time for the current sample to arrive or for rendering to be stopped.

virtual HRESULT WaitForRenderTime(void);

Return Values

Returns an HRESULT value.

Remarks

The member function is virtual because derived classes might have more events that they also want to wait on, which might interrupt the waiting process. The base class has two events: m_RenderEvent and m_ThreadSignal. The former is signaled by the clock when the sample is due for rendering. The latter is signaled by the filter when it should give up waiting and abort (making the assumption that the filter was stopped).


CBaseStreamControl Class

CBaseStreamControl class hierarchy

The CBaseStreamControl class implements the IAMStreamControl interface on input and output pins in a filter graph. This class provides control of the starting and stopping of various components of the stream. Various streams can be turned on or off without affecting the rest of the graph. For example, an audio stream can be turned off while a video stream continues, for muting. Or perhaps a capture stream can be turned off while preview continues to flow. This could be used to assist in frame accuracy when exact capture start or stop times are important.

CBaseStreamControl enables you to specify start and stop times in the StartAt and StopAt member functions and provides stream information in the GetInfo member function. CBaseStreamControl uses the StreamControlState enumerated data type to describe the various states a stream is in. If a stream is flowing it is indicated by the STREAM_FLOWING setting, otherwise it is in a discarding state indicated by the STREAM_DISCARDING setting.

Filters that need to implement the interface on their own should typically inherit from CBaseStreamControl to obtain an implementation of the StartAt, StopAt, and GetInfo methods. The CBaseStreamControl class also maintains state information and decides what to do with the sample. To implement your own filter with pins that support CBaseStreamControl you must:

  • Inform the filter object of all state changes through the NotifyFilterState member function.
  • Inform the filter object of all SetSyncSource calls to the filter.
  • Inform the filter object when in a flushing state. and when flushing has completed, in the CBaseStreamControl::Flushing member function.
  • Use the CheckStreamState function to make decisions about discarding or passing along samples.
  • Make sure output pins set discontinuity flags on the first sample flowed after samples have been discarded.
  • Tell your pin what the sink is when your filter joins a filter graph, as shown in the following example.
    STDMETHODIMP CMyFilter::JoinFilterGraph(IFilterGraph * pGraph, LPCWSTR pName)
{
   HRESULT hr = CBaseFilter::JoinFilterGraph(pGraph, pName);
   if (hr == S_OK)
      m_pMyPin->SetFilterGraph(m_pSink);
   return hr;
}

If you are implementing the IAMStreamControl interface without using CBaseStreamControl, the last two preceding points do not apply.

For sample code see the video capture sample at DXmedia\Samples\DS\vidcap.

Member Functions
Name | Description
CBaseStreamControl | Constructs a CBaseStreamControl object.
CheckStreamState | Retrieves a stream's current state.
Flushing | Notifies the pin when the filter is flushing.
GetInfo | Retrieves information about the current streaming settings.
NotifyFilterState | Notifies the pin of what state your filter is in.
SetFilterGraph | Sets the event sink notification that your filter graph is using.
SetSyncSource | Identifies the reference clock being used by the graph your filter is in.
StartAt | Informs the pin when to start sending streaming data.
StopAt | Informs the pin when to stop processing data and discard any new samples.

CBaseStreamControl::CBaseStreamControl

CBaseStreamControl Class

Constructs a CBaseStreamControl object.

CBaseStreamControl( );

Return Values

No return value.

Remarks

This method initializes start time and stop time to MAX_TIME, which implies that times are unspecified.

CBaseStreamControl::CheckStreamState

CBaseStreamControl Class

Retrieves a stream's current state.

enum StreamControlState CheckStreamState( IMediaSample * pSample );
Values
pSample
Pointer to an IMediaSample interface.
Return Values

Returns a StreamControlState enumeration type.

Remarks

Your filter calls this member function when your pin receives a sample that it is about to forward. The first sample you forward after throwing one or more away should be marked as a discontinuity.

If your filter implements the IAMDroppedFrames interface and is counting how many frames are dropped, it should not count a frame that is discarded as dropped.

The following example shows what you should include if your filter inherits from CBaseStreamControl.

//Pin has been given a sample to pass on, pSample
//m_fLastSampleDiscarded is initialized to TRUE when streaming starts

int iStreamState = CheckStreamState(pSample);
if (iStreamState == STREAM_FLOWING) {
   if (m_fLastSampleDiscarded)
      pSample->SetDiscontinuity(TRUE);
   m_fLastSampleDiscarded = FALSE;
   //now deliver it or put it o a queue to be delivered, or whatever.
} else {
   m_fLastSampleDiscarded = TRUE;     //next one is discontinuity
   //do NOT deliver this sample. Just throw it away
}

CBaseStreamControl::Flushing

CBaseStreamControl Class

Notifies the pin that the filter is flushing.

void Flushing(
BOOL bInProgress );

Parameters
bInProgress
TRUE indicates flushing in progress; FALSE indicates not flushing.
Return Values

No return value.

Remarks

If you are implementing your own filter, your pin must call this member function on BeginFlush and EndFlush (DeliverBeginFlush and DeliverEndFlush for output pins) to say when it is flushing, as shown in the following example.

HRESULT CMyPin::BeginFlush()
{
   Flushing(TRUE);
   //or CBaseInputPin for input pins
   return CBaseOutputPin::BeginFlush();
}

HRESULT CMyPin::EndFlush()
{
   Flushing(FALSE);
   //or CBaseInputPin for input pins
   return CBaseOutputPin::EndFlush();
}

Note that capture filters that do not support seeking do not call this method.

CBaseStreamControl::GetInfo

CBaseStreamControl Class

Retrieves information about the current streaming settings.

HRESULT GetInfo(
AM_STREAM_INFO *pInfo
);

Parameters
pInfo
Pointer to an AM_STREAM_INFO structure.
Return Values

Returns S_OK.

Remarks

This member function implements the IAMStreamControl interface and is called by the user to find out if a pin is streaming and to obtain the stream's attributes.

CBaseStreamControl::NotifyFilterState

CBaseStreamControl Class

Notifies the pin of your filter's state.

void NotifyFilterState(
FILTER_STATE new_state,
REFERENCE_TIME tStart = 0 );

Parameters
new_state
Filter's new state.
tStart
Time at which streaming starts (only valid when new_state is in State_Running).
Return Values

No return value.

Remarks

This member function notifies the pin of a filter's new state by setting a FILTER_STATE enumeration type variable.

If you are implementing your own filter, inform your pin's CBaseStreamControl::NotifyFilterState member function what state your filter is in every time your filter changes state, as shown in the following example.

STDMETHODIMP CMyFilter::Run(REFERENCE_TIME tStart)
{
   //once error check is successful
   m_pMyPin->NotifyFilterState(State_Running, tStart);

   //now continue with whatever should occur next, for example...
   return CBaseFilter::Run(tStart);
}

STDMETHODIMP CMyFilter::Pause()
{
   //once error check is successful
   m_pMyPin->NotifyFilterState(State_Paused, 0);

   //now continue with whatever should occur next, for example...
   return CBaseFilter::Pause();
}

STDMETHODIMP CMyFilter::Stop()
{
   //once error check is successful
   m_pMyPin->NotifyFilterState(State_Stopped, 0);

   //now continue with whatever should occur next, for example...
   return CBaseFilter::Stop(tStart);
}

CBaseStreamControl::SetFilterGraph

CBaseStreamControl Class

Sets the event sink notification your filter graph is using.

void SetFilterGraph(
IMediaEventSink *pSink )

Parameters
pSink
Pointer to an IMediaEventSink interface.
Return Values

No return value.

Remarks

A filter calls this member function in its JoinFilterGraph member function after it creates the IMediaEventSink.

CBaseStreamControl::SetSyncSource

CBaseStreamControl Class

Identifies the reference clock being used by the graph your filter is in.

void SetSyncSource(
IReferenceClock * pRefClock );

Parameters
pRefClock
Pointer to the IReferenceClock interface.
Return Values

No return value.

Remarks

Filters with pins that use this class should ensure that they pass sync source information to this member function, as shown in the following example.

STDMETHODIMP CMyFilter::SetSyncSource(IReferenceClock *pClock)
{
   m_pMyPin->SetSyncSource(pClock);
   return CBaseFilter::SetSyncSource(pClock);
}

CBaseStreamControl::StartAt

CBaseStreamControl Class

Tells the pin when to start sending streaming data.

HRESULT StartAt(
const REFERENCE_TIME * ptStart = NULL,
DWORD dwCookie = 0 );

Parameters
ptStart
REFERENCE_TIME at which to start streaming. If NULL, start immediately (no notification). If MAX_TIME, start canceled or will have no effect.
dwCookie
Specifies a particular value, other than 0, to be sent with the notification when the start occurs. (Only used if ptStart is non-NULL or MAX_TIME).
Return Values

Returns NOERROR.

Remarks

Streams are enabled by default, so this member function will have no effect unless you have previously called StopAt.

After the stream is in a STREAM_FLOWING state, the filter will send an EC_STREAM_CONTROL_STARTED event notification to the filter graph manager.

Note If start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this effect to capture a single frame.

CBaseStreamControl::StopAt

CBaseStreamControl Class

Informs the pin when to stop processing data and to discard any new samples.

HRESULT StopAt(
const REFERENCE_TIME * ptStop = NULL,
BOOL bSendExtra = FALSE,
DWORD dwCookie = 0 );

Parameters
ptStop
REFERENCE_TIME at which to stop streaming. If NULL, stop immediately (no notification). If MAX_TIME, cancels stop.
bSendExtra
Indicates whether to send an extra sample after scheduled ptStop time.
dwCookie
Specifies a particular value to be sent with the notification when the stop occurs. (Only used if ptStart if not NULL or MAX_TIME).
Return Values

Returns NOERROR.

Remarks

This member function implements the IAMStreamControl::StopAt method and is used by pins and filters that must support the stopping of streams. It sets the StreamControlState enumeration type to STREAM_DISCARDING.

In a video capture scenario, specify StopAt on both the output pin of a capture filter and an input pin of a multiplexer and have the multiplexer send notification of completion. This ensures that the capture filter doesn't needlessly capture extra frames, while also guaranteeing that the multiplexer has written the last frame to disk.

In addition, the capture output pin should specify TRUE for the bSendExtra variable while all other pins specify FALSE. If an extra frame is not sent the multiplexer will end up waiting for the stop time indefinitely and not realize it already has received all the capture information.

If you are using ICaptureGraphBuilder, the ICaptureGraphBuilder::ControlStream method will accomplish all this for you automatically.

Note If a stop time is given in the middle of a packet, the filter will deliver the whole packet before going into a discarding state. Also, if start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this effect to capture a single frame.


CBaseVideoRenderer Class

CBaseVideoRenderer class hierarchy

This base class is used for building video renderer filters.

Protected Data Members
Name | Description
m_bDrawLateFrames | Flag to signal that no frames are to be dropped. Debug only. This destroys synchronization.
m_bSupplierHandlingQuality | TRUE indicates quality control messages are being handled. This lets the renderer know to wait until as late as possible to drop frames itself, and to display the next frame very early after the supplier has dropped a frame.
m_cFramesDrawn | Total number of frames that have been drawn since streaming started.
m_cFramesDropped | Cumulative frames that have been dropped in the renderer since streaming started. Frames can also be dropped upstream without the renderer recognizing them.
m_idDecision | MSR_id for the decision code of ShouldDrawSampleNow.
m_idDuration | MSR_id for the duration of a frame.
m_idFrameAccuracy | Performance log identifier for the time in milliseconds that the frame was late.
m_idFrameAvg | Performance log identifier for the average frame time that is used for synchronization and quality control.
m_idQualityRate | MSR_id for the quality rate requested.
m_idQualityTime | MSR_id for the quality time requested.
m_idRenderAvg | Performance log identifier for the average renderer time recorded.
m_idSchLateTime | MSR_id for how late the frame was when scheduled.
m_idSendQuality | MSR_id for timing the notifications (unused).
m_idTimeStamp | MSR_id for a frame time stamp.
m_idWait | Performance log identifier for the recorded wait time (unused).
m_idWaitReal | Performance log identifier for the true wait time.
m_iSumFrameTime | Sum of the interframe times; needed for the property page.
m_iSumSqAcc | Sum of the squares of the accuracies (in milliseconds) needed for the property page.
m_iSumSqFrameTime | Sum of the squares of interframe times; needed for the property page.
m_iTotAcc | Sum of the accuracies (in milliseconds) needed for the property page.
m_nNormal | Number of consecutive frames drawn at their scheduled time. A negative number indicates that a frame has just been dropped by the renderer.
m_trDuration | Duration of the last frame (difference between the start and end times).
m_trEarliness | How early a frame is allowed to be played when a frame has just been dropped.
m_trFrame | Most recently recorded time between frames. Used in statistical measurements.
m_trFrameAvg | Average interframe time in reference time units.
m_trLastDraw | Time of previous frame. Used for interframe time references.
m_trLate | Amount of time that the current frame was late. Used in statistical measurements.
m_trRenderAvg | Time that frames are taking to perform the bit-block transfer.
m_trRenderLast | Time for the last frame bit-block transfer.
m_trRenderStart | Time the bit-block transfer started. Used to get m_trRenderLast.
m_trThrottle | Period to insert after rendering each frame, typically used when audio quality has been increased and video performance must be decreased to allow this.
m_trWaitAvg | Average wait time in reference time units.
m_tStreamingStart | Used for property page statistics. Represents the start time of the current streaming process or the previous streaming process if not currently streaming.

Member Functions
Name | Description
CBaseVideoRenderer | Constructs a CBaseVideoRenderer object.
GetStdDev | Estimates the standard deviation in milliseconds between when each frame is due and when it is actually rendered, for per-frame statistics.
PreparePerformanceData | Sets the m_trLate and m_trFrame values of the current frame.
ThrottleWait | Inserts a wait period after each frame.

Overridable Member Functions
Name | Description
JoinFilterGraph | Sends EC_WINDOW_DESTROYED event notification when filter is removed from the filter graph.
OnDirectRender | Collects timing information that controls synchronization and quality control.
OnRenderEnd | Records information for quality control and synchronization.
OnRenderStart | Records information for quality control and synchronization.
OnStartStreaming | Resets all times that control streaming.
OnStopStreaming | Called at the end of streaming to fix times for the property page report.
OnWaitEnd | Called when a wait time ends. Performance logging only.
OnWaitStart | Updates times spent waiting and not waiting. Performance logging only.
RecordFrameLateness | Records how timely the rendering occurred and gathers statistics for the property page.
ResetStreamingTimes | Resets all times that control the streaming.
ScheduleSample | Sets up an advise link with the clock.
SendQuality | Sends a quality message to indicate what the supplier should do about quality.
ShouldDrawSampleNow | Determines if the video should be drawn when it is due, without setting a timer advise link with the clock.

Implemented IQualProp Methods
Name | Description
get_AvgFrameRate | Retrieves the average frame rate since streaming started in frames per 100 seconds.
get_AvgSyncOffset | Retrieves the average of the time in milliseconds between when each frame was due and when it was actually rendered. This applies to all frames since streaming started.
get_DevSyncOffset | Retrieves the standard deviation of the time in milliseconds between when each frame was due and when it was actually rendered for all frames since streaming started.
get_FramesDrawn | Retrieves the number of frames drawn since streaming started.
get_FramesDroppedInRenderer | Retrieves the number of frames dropped by the renderer. Frames can also be dropped upstream.
get_Jitter | Retrieves the standard deviation of the time in milliseconds between each frame and the next. This applies to all frames since streaming started.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Provides access to other interfaces, particularly the property page.

Implemented IQualityControl Methods
Name | Description
Notify | Notifies the recipient that a quality change is requested.
SetSink | Sets the IQualityControl object that will receive quality messages.

CBaseVideoRenderer::CBaseVideoRenderer

CBaseVideoRenderer Class

Constructs a CBaseVideoRenderer object.

CBaseVideoRenderer(
REFCLSID RenderClass,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
RenderClass
Class identifier for this renderer.
pName
Description used for debugging purposes.
pUnk
Pointer to the aggregated owner object.
phr
Pointer to an HRESULT value.
Return Values

No return value.

CBaseVideoRenderer::get_AvgFrameRate

CBaseVideoRenderer Class

Calculates and retrieves the average frame rate achieved.

HRESULT get_AvgFrameRate(
int *piAvgFrameRate
);

Parameters
piAvgFrameRate
Number of frames per second since streaming began.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_AvgFrameRate method.

CBaseVideoRenderer::get_AvgSyncOffset

CBaseVideoRenderer Class

Retrieves the average of the time in milliseconds between when each frame was due and when it was actually rendered for all frames since streaming started.

HRESULT get_AvgSyncOffset(
int *piAvg
);

Parameters
piAvg
Pointer to the average of the time as previously described.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_AvgSyncOffset method.

CBaseVideoRenderer::get_DevSyncOffset

CBaseVideoRenderer Class

Retrieves the standard deviation of the time in milliseconds between when each frame was due and when it was actually rendered, for all frames since streaming started.

HRESULT get_DevSyncOffset(
int *piDev
);

Parameters
piDev
Pointer to the standard deviation of the time as previously described.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_DevSyncOffset method.

CBaseVideoRenderer::get_FramesDrawn

CBaseVideoRenderer Class

Retrieves the m_cFramesDrawn member variable, giving the number of frames drawn since streaming started.

HRESULT get_FramesDrawn(
int *pcFramesDrawn
);

Parameters
pcFramesDrawn
Number of frames drawn.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_FramesDrawn method.

CBaseVideoRenderer::get_FramesDroppedInRenderer

CBaseVideoRenderer Class

Retrieves the number of frames dropped by the renderer.

HRESULT get_FramesDroppedInRenderer(
int *pcFramesDropped
);

Parameters
pcFramesDropped
Number of frames dropped.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_FramesDroppedInRenderer method. This is how the property page retrieves the data from the scheduler. Note that frames can also be dropped upstream without the renderer even seeing them.

CBaseVideoRenderer::get_Jitter

CBaseVideoRenderer Class

Retrieves the standard deviation of time in milliseconds between each frame and the next for all frames since streaming started.

HRESULT get_Jitter(
int *piJitter
);

Parameters
piJitter
Standard deviation of the interframe time in milliseconds.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualProp::get_Jitter method.

CBaseVideoRenderer::GetStdDev

CBaseVideoRenderer Class

Estimates the standard deviation in milliseconds between when each frame is due and when it is actually rendered, for per-frame statistics.

HRESULT GetStdDev(
int nSamples,
int *piResult,
LONGLONG llSumSq,
LONGLONG iTot
);

Parameters
nSamples
Integer value that contains the number of video samples received by the video renderer.
piResult
Pointer to an integer value that will contain the standard deviation.
llSumSq
Value that represents the standard deviation, in milliseconds, of all rendered video samples. The lower the value, the more consistent the rendering.
iTot
Value that represents the mean value, in milliseconds, between the stamped time and rendered time for all rendered video samples.
Return Values

Returns NOERROR.

CBaseVideoRenderer::JoinFilterGraph

CBaseVideoRenderer Class

Sends EC_WINDOW_DESTROYED event notification when a filter is removed from the filter graph.

HRESULT JoinFilterGraph(
IBaseFilterGraph * pGraph,
LPCWSTR pName
);

Parameters
pGraph
Pointer to the filter graph to join.
pName
[in, string] Name of the filter being added.
Return Values

No return value.

Remarks

This member function overrides the CBaseFilter::JoinFilterGraph member function. If this function determines that the filter is being notified that it is leaving the filter graph (pGraph is null, but m_pGraph is not), it sends an EC_WINDOW_DESTROYED event notification so that the resource manager does not hold on to the renderer as a focus object.

CBaseVideoRenderer::NonDelegatingQueryInterface

CBaseVideoRenderer Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
VOID **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Override this member function to publish the interface.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method. It exposes the IQualProp interface and then calls CBaseRenderer::NonDelegatingQueryInterface to expose interfaces implemented in the base classes.

CBaseVideoRenderer::Notify

CBaseVideoRenderer Class

Receives a notification that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

Parameters
pSelf
[in] Pointer to the filter that is sending the quality notification.
q
[in] Quality notification structure.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualityControl::Notify method on the video renderer. This is called, typically by the filter graph manager, when the quality must be cut back. This might occur when the quality of audio playback has been increased to the point that the video playback quality must be decreased.

Notify sets the m_trThrottle data member to a delay value to be inserted between frames by ThrottleWait.

CBaseVideoRenderer::OnDirectRender

CBaseVideoRenderer Class

Collects timing information that controls synchronization and quality control.

virtual void OnDirectRender(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns an HRESULT value.

Remarks

Call this member function instead of OnRenderStart and OnRenderEnd. This is used by the Microsoft® DirectDraw® video renderer.

CBaseVideoRenderer::OnRenderEnd

CBaseVideoRenderer Class

Performs smoothing for cases where the rendering time varies due to interruptions.

void OnRenderEnd(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

This member function should be called just after drawing an image.

This member function overrides CBaseRenderer::OnRenderEnd.

CBaseVideoRenderer::OnRenderStart

CBaseVideoRenderer Class

Sets information for rendering.

void OnRenderStart(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

No return value.

Remarks

This member function retrieves the current clock time from the system and stores it in a member variable to be used when the drawing is complete. The function also performs performance logging. This member function should be called just before drawing starts.

This member function overrides CBaseRenderer::OnRenderStart.

CBaseVideoRenderer::OnStartStreaming

CBaseVideoRenderer Class

Resets all times that control streaming.

HRESULT OnStartStreaming(void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBaseRenderer::OnStartStreaming.

CBaseVideoRenderer::OnStopStreaming

CBaseVideoRenderer Class

Called at the end of streaming to fix times for the property page report.

HRESULT OnStopStreaming(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called twice, once when pausing and again when the stream is actually stopped.

This member function overrides CBaseRenderer::OnStopStreaming.

CBaseVideoRenderer::OnWaitEnd

CBaseVideoRenderer Class

Called when a wait time ends.

void OnWaitEnd(void);

Return Values

No return value.

Remarks

This member function does only performance logging. It is called when the thread is awoken from waiting in the window, or when the next sample is due to be rendered. It could eventually be used to gather information that controls synchronization.

CBaseVideoRenderer::OnWaitStart

CBaseVideoRenderer Class

Updates times spent waiting and not waiting.

void OnWaitStart(void);

Return Values

No return value.

Remarks

This member function is called when starting to wait for a rendering event. It is used only for performance measurements.

CBaseVideoRenderer::PreparePerformanceData

CBaseVideoRenderer Class

Sets the m_trLate and m_trFrame values of the current frame.

void PreparePerformanceData(
int trLate,
int trFrame
);

Parameters
trLate
How late the sample was beyond its due time, in reference time units.
trFrame
Interframe time, in reference time units.
Return Values

No return value.

Remarks

This member function sets m_trLate to the value of trLate and m_trFrame to the value of trFrame.

When the CBaseVideoRenderer::RecordFrameLateness member function is called from either CBaseVideoRenderer::OnRenderStart or CBaseVideoRenderer::OnDirectRender, it passes the values of m_trLate and m_trFrame for it to update the statistics. PreparePerformanceData is called from CBaseVideoRenderer::OnWaitEnd to set these data member values.

CBaseVideoRenderer::RecordFrameLateness

CBaseVideoRenderer Class

Records how timely the rendering occurred and gathers statistics for the property page.

virtual void RecordFrameLateness(
int trLate,
int trFrame
);

Parameters
trLate
How late the sample was beyond its due time, in reference time units.
trFrame
Interframe time, in reference time units.
Return Values

No return value.

CBaseVideoRenderer::ResetStreamingTimes

CBaseVideoRenderer Class

Resets all times that control the streaming.

virtual HRESULT ResetStreamingTimes(void);

Return Values

Returns an HRESULT value.

Remarks

The times are set so that frames will not be initially dropped and so that the first frame will be drawn.

CBaseVideoRenderer::ScheduleSample

CBaseVideoRenderer Class

Overrides the base class that does the main work to keep a count of samples drawn and dropped (which are used by the IQualProp implementation).

BOOL ScheduleSample(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns TRUE if the sample is scheduled; otherwise, returns FALSE.

CBaseVideoRenderer::SendQuality

CBaseVideoRenderer Class

Sends a quality message to indicate what the supplier should do about quality.

virtual HRESULT SendQuality(
REFERENCE_TIME trLate,
REFERENCE_TIME trRealStream
);

Parameters
trLate
Amount of time by which the frame is late.
trRealStream
Current stream time.
Return Values

Returns an HRESULT value.

Remarks

This member function sends a quality control message upstream to control quality management. The nature of the quality message (that is, whether to reduce or increase the number of samples) is determined in the quality management implementation in this derived class (see CBaseVideoRenderer::ShouldDrawSampleNow).

CBaseVideoRenderer::SetSink

CBaseVideoRenderer Class

Sets the IQualityControl object that will receive quality messages.

HRESULT SetSink(
IQualityControl *piqc
);

Parameters
piqc
Pointer to the IQualityControl object to which the notifications should be sent.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IQualityControl::SetSink method on the video renderer.

CBaseVideoRenderer::ShouldDrawSampleNow

CBaseVideoRenderer Class

Determines if the video should be drawn without setting a timer advise link with the clock.

virtual HRESULT ShouldDrawSampleNow(
IMediaSample *pMediaSample,
REFERENCE_TIME *ptrStart,
REFERENCE_TIME *ptrEnd
);

Parameters
pMediaSample
IMediaSample interface for the sample.
ptrStart
Time to begin rendering.
ptrEnd
Time to stop rendering.
Return Values

Returns an HRESULT value. Returns S_OK to mean draw at once without waiting, S_FALSE to mean draw at time ptrStart, or error to mean do not draw the sample; that is, skip it to save time.

Remarks

This member function overrides CBaseRenderer::ShouldDrawSampleNow.

CBaseVideoRenderer::ThrottleWait

CBaseVideoRenderer Class

Inserts a wait period after each frame.

void ThrottleWait(void);

Return Values

No return value.

Remarks

This member function waits for a time period obtained from the m_trThrottle data member.


CBaseVideoWindow Class

CBaseVideoWindow class hierarchy

The CBaseVideoWindow class handles the IDispatch component of the IVideoWindow interface and leaves the IVideoWindow properties and methods pure virtual.

Member Functions
Name | Description
CBaseVideoWindow | Constructs a CBaseVideoWindow object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used during subsequent calls to the IDispatch::Invoke method.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CBaseVideoWindow::CBaseVideoWindow

CBaseVideoWindow Class

Constructs a CBaseVideoWindow object.

CBaseVideoWindow(
const TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object used in the CBaseVideoWindow constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of an object.

CBaseVideoWindow::GetIDsOfNames

CBaseVideoWindow Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the CBaseVideoWindow::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
E_OUTOFMEMORY | Out of memory.
S_OK | Success.

CBaseVideoWindow::GetTypeInfo

CBaseVideoWindow Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.

CBaseVideoWindow::GetTypeInfoCount

CBaseVideoWindow Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CBaseVideoWindow::Invoke

CBaseVideoWindow Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CBaseVideoWindow::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CBaseVideoWindow::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CBaseVideoWindow::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CBaseVideoWindow::NonDelegatingQueryInterface

CBaseVideoWindow Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IVideoWindow and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.


CBaseWindow Class

CBaseWindow class hierarchy

The CBaseWindow class creates a window and a worker thread. The worker thread pulls messages from the window's input queue and dispatches them as appropriate. The window and its thread are created by the CBaseWindow::PrepareWindow member function and destroyed by the CBaseWindow::DoneWithWindow member function. The window should also be initialized by the CBaseWindow::InitialiseWindow member function and uninitialized by the CBaseWindow::UninitialiseWindow member function. After preparing and initializing a window, size it by using the CBaseWindow::ActivateWindow member function; hide the window using the CBaseWindow::InactivateWindow member function.

Protected Data Members
Name | Description
m_bActivated | Flag to indicate window activation status.
m_bBackground | Flag to indicate if palettes are to be realized in the background.
m_bDoGetDC | Flag to indicate if the window should get a DC.
m_ClassStyles | Class styles for the window.
m_hdc | Device context (DC) for the window.
m_Height | Client window height.
m_hInstance | Global module instance handle.
m_hPalette | Handle to a palette belonging to this object.
m_hThread | Worker thread for the window.
m_hwnd | Handle for this object's window.
m_MemoryDC | Memory DC used for fast bit-block transfer operations.
m_pClassName | Static string holding the class name.
m_RealizePalette | Message sent to indicate the window palette has changed.
m_ShowStageMessage | Message sent by IVideoWindow::SetWindowForeground that moves the current window to the foreground and optionally gives it focus.
m_ShowStageTop | Message sent to set the window to WS_EX_TOPMOST style.
m_SyncWorker | CAMEvent data member used to provide interthread synchronization.
m_SyncWorkerCreate | CAMMsgEvent data member used to signal the constructor for the window class when to create the window.
m_ThreadSignal | Data member used by the thread to signal errors.
m_Width | Client window width.
m_WindowLock | Data member used to serialize window object access.
m_WindowStyles | Data member used to serialize the initial window styles.
m_WindowStylesEx | Data member used to serialize the initial extended window styles.

Member Functions
Name | Description
CBaseWindow | Constructs a CBaseWindow object.
DoSetWindowForeground | Brings the window to the foreground.
DoShowWindow | Sets the show state of the specified window.
GetMemoryHDC | Retrieves the default offscreen memory device context (DC).
GetWindowHDC | Retrieves the default main window DC.
GetWindowHeight | Retrieves the current window height.
GetWindowHWND | Retrieves the window handle for the window.
GetWindowWidth | Retrieves the current window width.
PerformanceAlignWindow | Aligns the window to a DWORD boundary for maximum performance.
PaintWindow | Invalidates the window client area.

Overridable Member Functions
Name | Description
ActivateWindow | Sizes the window according to the requirements of the derived class.
DoneWithWindow | Closes, deletes, and frees the window resources.
DoRealisePalette | Maps palette entries from this window's palette to the system palette. The window's palette is set with CBaseWindow::SetPalette.
PossiblyEatMessage | Forwards keyboard and mouse messages to a specified window.
GetClassWindowStyles | Returns class and window information.
GetDefaultRect | Returns the default size for the window.
InactivateWindow | Hides the window.
InitialiseWindow | Creates the default device contexts.
OnClose | Handles the WM_CLOSE message for the base class.
OnPaletteChange | Handles WM_PALETTEISCHANGING and WM_PALETTECHANGED messages.
OnSize | Handles WM_SIZE messages for the base class.
OnReceiveMessage | Indicates a base class implementation of a window procedure.
PrepareWindow | Initializes the window along with a worker thread.
SetPalette | Changes the palette that the window should realize.
UninitialiseWindow | Destroys the device contexts created for the window.

CBaseWindow::ActivateWindow

CBaseWindow Class

Sizes the window according to the requirements of the derived class.

virtual HRESULT ActivateWindow( );

Return Values

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.
Value | Meaning
E_FAIL | Failure.
E_NOTIMPL | Method is not supported.
NOERROR | No error.

Remarks

This member function calls CBaseWindow::GetDefaultRect, which a derived class should override to return the size of the images that will be displayed. ActivateWindow then sizes the window so that the client area matches this size.

CBaseWindow::CBaseWindow

CBaseWindow Class

Constructs a CBaseWindow object.

CBaseWindow(
BOOL bDoGetDC = TRUE
);

Parameters
bDoGetDC
Specifies if the window should get a device context.
Return Values

No return value.

Remarks

The window and its worker thread are created by CBaseWindow::PrepareWindow and destroyed by CBaseWindow::DoneWithWindow.

CBaseWindow::DoneWithWindow

CBaseWindow Class

Destroys the window and its worker thread.

virtual HRESULT DoneWithWindow( );

Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed by CBaseWindow::DoneWithWindow. The window should also be initialized using CBaseWindow::InitialiseWindow and uninitialized using CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::DoRealisePalette

CBaseWindow Class

Maps palette entries from this window's palette to the system palette. The window's palette is set with CBaseWindow::SetPalette.

virtual HRESULT DoRealisePalette(
BOOL bForceBackground
);

Parameters
bForceBackground
Value that specifies whether the palette is forced to the background.
Return Values

Returns S_OK if successful or S_FALSE if the GdiFlush function could not flush the calling thread's current batch.

Remarks

The window class is given a palette handle to use with the CBaseWindow::SetPalette member function. After a palette has been installed, it can be realized by calling this member function. The class will also call this member function when it gets WM_QUERYNEWPALETTE and WM_PALETTECHANGED messages from the Microsoft® Windows® operating system.

Call this function with TRUE in response to WM_SETPALETTE and FALSE in response to WM_QUERYNEWPALETTE.

CBaseWindow::DoSetWindowForeground

CBaseWindow Class

Sets the video window to the foreground and optionally gives it focus.

void DoSetWindowForeground(
BOOL bFocus
);

Parameters
bFocus
Value that specifies whether the video window will have focus. A value of TRUE gives it focus and FALSE does not.
Return Values

No return value.

Remarks

DirectShow provides this method to make it easy for applications to move video windows to the foreground; usually, it is programatically complex for a thread associated with one window to affect a window associated with a different thread. This method passes the WM_SHOWWINDOW message to the video window's renderer, so the application's window procedure must handle this message and bring the appropriate window to the foreground and give it focus, if specified.

CBaseWindow::DoShowWindow

CBaseWindow Class

Sets the show state of the specified window.

HRESULT DoShowWindow(
LONG ShowCmd
);

Parameters
ShowCmd
Specifies how the window is to be shown.
Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

This member function simply calls the Microsoft Win32® ShowWindow function.

CBaseWindow::GetClassWindowStyles

CBaseWindow Class

Returns class and window information.

virtual LPTSTR GetClassWindowStyles(
DWORD *pClassStyles,
DWORD *pWindowStyles,
DWORD *pWindowStylesEx
) PURE;

Parameters
pClassStyles
Class styles.
pWindowStyles
Window styles.
pWindowStylesEx
Extended window styles.
Return Values

Returns a class name that is a static text string.

Remarks

A derived class must override this pure virtual member function to provide the default class and window styles for the window. The information the derived class returns is used in CBaseWindow::PrepareWindow when the window is first created. The class and window styles take the same parameters as their counterparts in the Microsoft Win32 CreateWindowEx function. The string that is returned should be allocated as a static string and should still be valid after the member function returns.

CBaseWindow::GetDefaultRect

CBaseWindow Class

Retrieves the default size for the window client area.

virtual RECT GetDefaultRect( );

Return Values

Returns the default rectangle.

Remarks

When the window is activated, it calls this member function to determine how large it should make the window's client area. A video renderer will typically return the size of the native video image.

CBaseWindow::GetMemoryHDC

CBaseWindow Class

Retrieves the default memory device context (DC).

virtual HDC GetMemoryHDC( );

Return Values

Returns the default memory DC.

Remarks

The base window class creates a window with a worker thread when it is prepared (in CBaseWindow::PrepareWindow). It also creates two DCs that can be used for drawing. The first is a normal window handle to a device context (HDC); the second is an offscreen HDC that can be used as a source HDC in bit-block transfer functions.

CBaseWindow::GetWindowHDC

CBaseWindow Class

Retrieves the default window device context (DC).

HDC GetWindowHDC( );

Return Values

Returns the default window DC.

Remarks

The base window class creates a window with a worker thread when it is prepared (in CBaseWindow::PrepareWindow). It also creates two DCs that can be used for drawing. The first is a normal window handle to a device context (HDC); the second is an offscreen HDC that can be used as a source HDC in bit-block transfer functions.

CBaseWindow::GetWindowHeight

CBaseWindow Class

Retrieves the current window height.

LONG GetWindowHeight( );

Return Values

Returns the window height in pixels.

Remarks

This member function is updated when the base class receives WM_SIZE messages.

CBaseWindow::GetWindowHWND

CBaseWindow Class

Retrieves the window handle associated with this object.

HWND GetWindowHWND( );

Return Values

Returns a window handle.

Remarks

If called before issuing a CBaseWindow::PrepareWindow call, this member function returns NULL.

CBaseWindow::GetWindowWidth

CBaseWindow Class

Retrieves the current window width.

LONG GetWindowWidth( );

Return Values

Returns the window width in pixels.

Remarks

This member function is updated when the base class receives WM_SIZE messages.

CBaseWindow::InactivateWindow

CBaseWindow Class

Effectively hides the window (if it was visible).

virtual HRESULT InactivateWindow( );

Return Values

Returns NOERROR if successful; S_FALSE if the window is not currently active.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should be initialized through CBaseWindow::InitialiseWindow and uninitialized through CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::InitialiseWindow

CBaseWindow Class

Creates default device contexts for the window.

virtual InitialiseWindow(
HWND hwnd
);

Parameters
hwnd
Window handle.
Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should be initialized through CBaseWindow::InitialiseWindow and uninitialized through CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

The base class creates two device contexts that can be used for drawing. The first is a standard handle to a device context (HDC) for the window; the second is an offscreen HDC. The offscreen HDC often is useful for selecting bitmaps before calling the Microsoft Win32 BitBlt or StretchBlt function to copy the bitmap to the main window. This member function also sets the default stretch mode to be COLORONCOLOR. The member function is virtual so that derived classes can change this default if desired.

CBaseWindow::OnClose

CBaseWindow Class

Handles the WM_CLOSE message.

virtual BOOL OnClose( );

Return Values

No return value.

Remarks

The default behavior for this member function is to simply hide the window. A derived class should not destroy the window when it receives a WM_CLOSE message but should send an EC_USERABORT notification to the filter graph manager. This will have the playback stopped, and in some cases will also have the filters disconnected and released. It is only when the filter that owns the window is finally released (that is, destroyed) that the derived class should actually destroy the window (using CBaseWindow::DoneWithWindow).

CBaseWindow::OnPaletteChange

CBaseWindow Class

Handles WM_PALETTEISCHANGING and WM_PALETTECHANGED messages.

virtual LRESULT OnPaletteChange(
HWND hwnd,
UINT Message
);

Parameters
hwnd
Handle of the window causing the message.
Message
Message details passed on from the window procedure.
Return Values

Returns one of the following values.
Value | Meaning
0 | Message was not handled.
1 | Message was processed.

Remarks

When the base class receives a WM_PALETTEISCHANGING message, it realizes its palette again. It must also do this when told, through WM_PALETTECHANGED, that the system palette has changed. In the latter case, however, the base class must be careful not to realize its palette if it was the window that caused the WM_PALETTECHANGED message (which is why the window that caused the message to be sent is passed into the member function).

This is a protected member function.

CBaseWindow::OnReceiveMessage

CBaseWindow Class

Indicates a base class implementation of a window procedure.

virtual LRESULT OnReceiveMessage(
HWND hwnd,
INT uMsg,
WPARAM wParam,
LPARAM lParam
);

Parameters
hwnd
Handle to the window.
uMsg
Message identifier.
wParam
Message's wParam parameter.
lParam
Message's lParam parameter.
Return Values

Returns an LRESULT value, based on the uMsg parameter. If uMsg is not one of the specified values, OnReceiveMessage passes the message to the Win32 DefWindowProc function and forwards the resulting return value to the caller.
Message | Action
m_RealizePalette | Returns 0
m_ShowStageMessage | Returns 1
m_ShowStageTop | Returns 1
WM_CLOSE | Returns 0
WM_PALETTECHANGED | Returns 0
WM_QUERYNEWPALETTE | Returns result of CBaseWindow::OnPaletteChange
WM_SIZE | Returns 0
WM_SYSCOLORCHANGE | Returns 1

CBaseWindow::OnSize

CBaseWindow Class

Handles the WM_SIZE message.

virtual BOOL OnSize(
LONG Width,
LONG Height
);

Parameters
Width
Window width.
Height
Window height.
Return Values

No return value.

Remarks

This member function stores the window width and height so that they can be returned from the CBaseWindow::GetWindowHeight and CBaseWindow::GetWindowWidth member functions.

CBaseWindow::PaintWindow

CBaseWindow Class

Invalidates the window client area.

void PaintWindow(
BOOL bErase
);

Parameters
bErase
Determines if the background should be erased.
Return Values

No return value.

CBaseWindow::PerformanceAlignWindow

CBaseWindow Class

Aligns the window to a DWORD boundary for maximum performance.

HRESULT PerformanceAlignWindow( );

Return Values

Returns an HRESULT value.

Remarks

This member function can be called, if the video is not owned by another window, to align the left edge and the top of the window for best display performance.

CBaseWindow::PossiblyEatMessage

CBaseWindow Class

Forwards keyboard and mouse messages to a specified window.

virtual BOOL PossiblyEatMessage(
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);

Parameters
uMsg
Message that was forwarded.
wParam
First message parameter.
lParam
Second message parameter.
Return Values

Returns FALSE.

See Also

CBaseControlWindow::PossiblyEatMessage

CBaseWindow::PrepareWindow

CBaseWindow Class

Creates a window and a worker thread.

virtual HRESULT PrepareWindow( );

Return Values

Returns NOERROR if successful; E_FAIL if unsuccessful.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should also be initialized and uninitialized through CBaseWindow::InitialiseWindow and CBaseWindow::UninitialiseWindow, respectively. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::SetPalette

CBaseWindow Class

Sets a palette for the window to use.

virtual HRESULT SetPalette(
HPALETTE hPalette
);

Parameters
hPalette
Handle to the new palette.
Return Values

Returns an HRESULT value.

Remarks

This member function allows a filter to install a palette in the window object. The palette handle passed in should be non-NULL. The palette is realized when it is installed. The window object does not delete any previous palette that it was using; the client using the window object should ensure it deletes the palette it creates at the appropriate time.

CBaseWindow::UninitialiseWindow

CBaseWindow Class

Flushes GDI and deletes the default device contexts.

virtual UninitialiseWindow( );

Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should also be initialized and uninitialized through CBaseWindow::InitialiseWindow and CBaseWindow::UninitialiseWindow, respectively. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.


CBasicAudio Class

CBasicAudio class hierarchy

The CBasicAudio class handles the IDispatch interface component of the IBasicAudio interface and leaves the properties and methods of IBasicAudio pure virtual to be implemented by a derived filter class.

The CBasicAudio::GetIDsOfNames, CBasicAudio::GetTypeInfo, CBasicAudio::GetTypeInfoCount, and CBasicAudio::Invoke member functions are standard implementations of the IDispatch interface using the CBaseDispatch class (and a type library) to parse the commands and pass them to the pure virtual IBasicAudio methods.

Microsoft® DirectShow™ uses units of 100th of a decibel for the volume scale. A value of 0 indicates maximum volume supported by the device. A value of –10,000 is the minimum volume (normally silence). Balance is expressed in the range –10,000 to 10,000, with 0 being neutral. A negative balance value means that the right channel is attenuated by this dB value (that is, it is quieter). Similarly, a positive balance value means that the right channel is louder than the left; that is, the left channel is attenuated by the corresponding negative decibel value.

Member Functions
Name | Description
CBasicAudio | Constructs a CBasicAudio object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used during subsequent calls to the CBasicAudio::Invoke member function.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CBasicAudio::CBasicAudio

CBasicAudio Class

Constructs a CBasicAudio object.

CBasicAudio(
const TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object used in the CBasicAudio constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal when the object is created and deleted.

CBasicAudio::GetIDsOfNames

CBasicAudio Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the CBasicAudio::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
E_OUTOFMEMORY | Out of memory.
S_OK | Success.

CBasicAudio::GetTypeInfo

CBasicAudio Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.

CBasicAudio::GetTypeInfoCount

CBasicAudio Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CBasicAudio::Invoke

CBasicAudio Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CBasicAudio::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CBasicAudio::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CBasicAudio::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CBasicAudio::NonDelegatingQueryInterface

CBasicAudio Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IBasicAudio and IUnknown interfaces by default. Override this member function to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.


CCmdQueue Class

CCmdQueue class hierarchy

The CCmdQueue class is a base class that provides a queue of CDeferredCommand objects and member functions to add, remove, check status, and invoke the queued commands. A CCmdQueue object is a part of an object that implements IQueueCommand methods. The filter graph manager implements IQueueCommand methods so that applications can queue commands to the filter graph. Filters that implement the IQueueCommand interface directly use this class. If you want to use CDeferredCommand objects, your queue must be derived from this class.

There are two modes of synchronization: coarse and accurate. In coarse mode, the application waits until a specified time arrives and then executes the command. In accurate mode, the application waits until processing begins on the sample that appears at the time, and then executes the command. The filter determines which one it will implement. The filter graph manager always implements coarse mode for commands that are queued at the filter graph manager.

If you want coarse synchronization, you probably want to wait until there is a command due, and then execute it. You can do this by calling CCmdQueue::GetDueCommand. If you have several things to wait for, get the event handle from CCmdQueue::GetDueHandle and then call CCmdQueue::GetDueCommand when this is signaled. Stream time will advance only between calls to the CCmdQueue::Run and CCmdQueue::EndRun member functions. There is no guarantee that if the handle is set, there will be a command ready. Each time the event is signaled, call the CCmdQueue::GetDueCommand member function (probably with a time-out of zero); this may return E_ABORT.

If you want accurate synchronization, call the CCmdQueue::GetCommandDueFor member function and pass the samples you are about to process as a parameter. This returns the following:

  • A stream-time command due at or before that stream time.
  • A presentation-time command due at or before the presentation of the stream time. Do this only between the CCmdQueue::Run and CCmdQueue::EndRun member functions, because outside of this, the mapping from stream time to presentation time is not known.
  • Any presentation-time command due now.

If you want accurate synchronization for samples that might be processed during paused mode, you must use stream-time commands.

In all cases, commands remain queued until called or canceled. The setting and resetting of the event handle is managed entirely by this queue object.

Protected Data Members
Name | Description
m_bRunning | Flag for running state; set TRUE when running.
m_dwAdvise | Advise identifier from the reference clock (zero if no outstanding advise).
m_evDue | Sets the time when any commands are due.
m_listPresentation | Stores commands queued in presentation time.
m_listStream | Stores commands queued in stream time.
m_Lock | Protects access to lists.
m_pClock | Current reference clock.
m_StreamTimeOffset | Contains the stream time offset when m_bRunning is true.
m_tCurrentAdvise | Advise time is for this presentation time.

Member Functions
Name | Description
CCmdQueue | Constructs a CCmdQueue object.
CheckTime | Determines if a given time is due.
GetDueHandle | Returns the event handle that will be signaled.

Overridable Member Functions
Name | Description
EndRun | Switches to stopped or paused mode.
GetCommandDueFor | Returns a pointer to a command that will be due for a given time.
GetDueCommand | Returns a pointer to the next command that is due.
Insert | Adds the CDeferredCommand object to the queue.
New | Initializes a command to be run and returns a new CDeferredCommand object.
Remove | Removes the CDeferredCommand object from the queue.
Run | Switches to running mode.
SetSyncSource | Sets the clock used for timing.
SetTimeAdvise | Creates an advise for the earliest time required.

CCmdQueue::CCmdQueue

CCmdQueue Class

Constructs a CCmdQueue object.

CCmdQueue( );

Return Values

No return value.

CCmdQueue::CheckTime

CCmdQueue Class

Determines if a specified time is due.

BOOL CheckTime(
CRefTime time,
BOOL bStream
);

Parameters
time
Time to check.
bStream
TRUE if the time parameter is a stream-time value; FALSE if time is a presentation-time value.
Return Values

Returns TRUE if the specified time has not yet passed.

CCmdQueue::EndRun

CCmdQueue Class

Switches to the stopped or paused mode.

virtual HRESULT EndRun( );

Return Values

Returns an HRESULT value that depends on the implementation. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK or NOERROR | Success.

Remarks

Time mapping between stream time and presentation time is not known after this member function has been called. Call the CCmdQueue::Run member function to carry out this mapping.

CCmdQueue::GetCommandDueFor

CCmdQueue Class

Returns a deferred command that is scheduled at a specified time.

virtual HRESULT GetCommandDueFor(
REFERENCE_TIME tStream,
CDeferredCommand **ppCmd
);

Parameters
tStream
Time for which the command is scheduled.
ppCmd
Deferred command to be carried out at the time specified in the tStream parameter.
Return Values

Returns VFW_E_NOT_FOUND if no commands are due; otherwise, returns S_OK.

Remarks

This member function takes a stream time and returns the deferred command scheduled at that time. The actual stream-time offset is calculated when the command queue is run. Commands remain queued until run or canceled. This member function will not block.

CCmdQueue::GetDueCommand

CCmdQueue Class

Returns a pointer to the next command that is due.

virtual HRESULT GetDueCommand(
CDeferredCommand ** ppCmd,
long msTimeout
);

Parameters
ppCmd
Pointer to the deferred command.
msTimeout
Amount of time to wait before carrying out the time-out.
Return Values

Returns E_ABORT if a time-out occurs. Returns S_OK if successful; otherwise, returns an error. Returns an object that has been incremented using IUnknown::AddRef.

Remarks

This member function blocks until a pending command is due. The member function blocks for the amount of time, in milliseconds, specified in the msTimeout parameter. Stream-time commands become due only between the CCmdQueue::Run and CCmdQueue::EndRun member functions. The command remains queued until run or canceled.

CCmdQueue::GetDueHandle

CCmdQueue Class

Returns the event handle to be signaled.

HANDLE GetDueHandle( );

Return Values

Returns the event handle.

Remarks

Return the event handle whenever there are deferred commands that are due for execution (when CCmdQueue::GetDueCommand will not block).

CCmdQueue::Insert

CCmdQueue Class

The CDeferredCommand object calls this member function to add itself to the queue.

virtual HRESULT Insert(
CDeferredCommand* pCmd
);

Parameters
pCmd
Pointer to the CDeferredCommand object to add to the queue.
Return Values

Returns S_OK in the default implementation.

CCmdQueue::New

CCmdQueue Class

Initializes a command to be run and returns a new CDeferredCommand object.

virtual HRESULT New(
CDeferredCommand **ppCmd,
LPUNKNOWN pUnk,
REFTIME time,
GUID* iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT* pDispParams,
VARIANT* pvarResult,
short* puArgErr,
BOOL bStream
);

Parameters
ppCmd
CDeferredCommand object by which an application can cancel the command, set a new presentation time for it, or retrieve estimate information.
pUnk
Pointer to the object that will run the command.
time
Time at which to run the queued command or commands.
iid
Globally unique identifier (GUID) of the interface to call.
dispidMethod
Method on the interface to be called.
wFlags
Flags describing the context of the call. This parameter supports the same flags as the OLE IDispatch::Invoke method.
cArgs
Number of arguments passed.
pDispParams
Pointer to the list of variant types associated with the dispatch parameters.
pvarResult
Pointer to the list where results, if any, are to be returned.
puArgErr
Index within the pDispParams parameter list where the last error occurred.
bStream
TRUE if the time parameter is a stream-time value; FALSE if time is a presentation-time value.
Return Values

Returns S_OK if successful. Returns E_OUTOFMEMORY if ppCmd returns from creating the new CDeferredCommand object with a value of NULL. Otherwise, returns an HRESULT that indicates an error from attempting to create a new CDeferredCommand object. If there is an error, no object has been queued.

Remarks

The new CDeferredCommand object will be initialized with the parameters and will be added to the queue during construction. This method is similar to the OLE IDispatch::Invoke method.

Values for the wFlags parameter include the following:
Value | Description
DISPATCH_METHOD | The member is being run as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag may be set.
DISPATCH_PROPERTYGET | The member is being retrieved as a property or data member.
DISPATCH_PROPERTYPUT | The member is being changed as a property or data member.
DISPATCH_PROPERTYPUTREF | The member is being changed via a reference assignment, rather than a value assignment. This value is valid only when the property accepts a reference to an object.

CCmdQueue::Remove

CCmdQueue Class

The CDeferredCommand object calls this member function to remove itself from the queue.

virtual HRESULT Remove(
CDeferredCommand* pCmd
);

Parameters
pCmd
Pointer to the CDeferredCommand object to remove from the queue.
Return Values

Returns VFW_E_NOT_FOUND if the object is not found in the queue. Otherwise, returns S_OK.

CCmdQueue::Run

CCmdQueue Class

Switches to running mode so that commands that are deferred by the stream time can be run.

virtual HRESULT Run(
REFERENCE_TIME tStreamTimeOffset
);

Parameters
tStreamTimeOffset
Offset time.
Return Values

Returns S_OK in the default implementation.

Remarks

During running mode, stream-time-to-presentation-time mapping is known.

CCmdQueue::SetSyncSource

CCmdQueue Class

Sets the clock used for timing.

virtual HRESULT SetSyncSource(
IReferenceClock* pIrc
);

Parameters
pIrc
Pointer to the IReferenceClock interface.
Return Values

Returns S_OK in the default implementation.

CCmdQueue::SetTimeAdvise

CCmdQueue Class

Sets up a timer event with the reference clock.

void SetTimeAdvise(void);

Return Values

No return value.

Remarks

This member function calls the IReferenceClock::AdviseTime method to set up a notification for the earliest time required in the queue. Presentation-time commands that are deferred are always checked. If the filter graph is in running mode, deferred commands using stream time are also checked.


CCritSec Class

CCritSec class hierarchy

The critical section object provides intraprocess synchronization. The current implementation uses the Microsoft® Win32® application programming interfaces (APIs) that use the CRITICAL_SECTION type.

The safest way to use CCritSec objects is to lock them with a CAutoLock object that guarantees to unlock the object when it goes out of scope and compiles to efficient inline code.

Member Functions
Name | Description
CCritSec | Constructs a CCritSec object.
Lock | Locks the critical section object.
Unlock | Unlocks the critical section object.

CCritSec::CCritSec

CCritSec Class

Constructs a CCritSec object.

CCritSec( );

Return Values

No return value.

Remarks

Calls the Microsoft® Win32® InitializeCriticalSection function to set the private critical section member variable. The destructor calls the Win32 DeleteCriticalSection function.

CCritSec::Lock

CCritSec Class

Locks the critical section object.

void Lock( );

Return Values

No return value.

Remarks

This member function locks the critical section object. You can make multiple lock calls on the same thread, but the CCritSec::Unlock member function must be called a corresponding number of times before the object is unlocked. If the object is locked by another thread, the CCritSec::Lock member function blocks until either the object is released or a "possible deadlock" exception occurs.

CCritSec::Unlock

CCritSec Class

Releases the lock on the object acquired by calling the CCritSec::Lock member function.

void Unlock( );

Return Values

No return value.

Remarks

You must call the CCritSec::Unlock member function once for each call to Lock.


CDeferredCommand Class

CDeferredCommand class hierarchy

Deferred commands are queued by calls to methods on the IQueueCommand interface and are exposed by the filter graph manager and by some filters. A successful call to one of these methods returns an IDeferredCommand interface representing the queued command.

A CDeferredCommand object represents a single deferred command and exposes the IDeferredCommand interface as well as other methods that permit time checks and actual execution. A CDeferredCommand object contains a reference to the CCmdQueue object on which it is queued.

Reference counts control the lifetime of the CDeferredCommand class. When calling the CDeferredCommand::Invoke member function, the calling application gets an interface pointer that is reference-counted, and the CCmdQueue object also holds a reference count on the deferred command. Calling the IDeferredCommand::Cancel member function takes the deferred command off the command queue and thus reduces the reference count by one. Once taken off the queue, the command cannot be put back on the queue.

Protected Data Members
Name | Description
m_bStream | Flag for stream time or presentation time. to be passed to the invoked method.
m_Dispatch | Accesses the ITypeInfo interface.
m_dispidMethod | Method on the interface to run.
m_DispParams | CDispParams object containing the DISPPARAMS parameter list
m_hrResult | Stores the returned HRESULT value.
m_iid | Globally unique identifier (GUID) of the interface.
m_pQueue | Pointer to the CCmdQueue object that exposes the IQueueCommand interface.
m_pUnk | IUnknown pointer to the interface on which the command will be run.
m_pvarResult | Resulting information, if any, from the invoked method.
m_time | Time at which the command will be run.
m_wFlags | Flags specifying the context of the invocation.

Member Functions
Name | Description
CDeferredCommand | Constructs a CDeferredCommand object.
GetFlags | Returns the context flags associated with the deferred command.
GetIID | Returns the interface identifier (IID) of the interface on which the method will be run.
GetMethod | Returns the dispatch identifier of the method to be run.
GetParams | Returns the DISPPARAMS argument list to the method.
GetResult | Returns the resulting argument list, if one exists.
GetTime | Returns the time when the method will be run.
Invoke | Provides access to methods and properties exposed by an object.
IsStreamTime | Specifies whether the command is to be run at stream time or presentation time.

Implemented IDeferredCommand Methods
Name | Description
Cancel | Cancels a previously queued CDeferredCommand::Invoke request.
Confidence | Not currently implemented.
Postpone | Specifies a new presentation time for a previously queued command.
GetHResult | Returns the HRESULT value of the invoked method.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

CDeferredCommand::Cancel

CDeferredCommand Class

Cancels a previously queued CDeferredCommand::Invoke request.

HRESULT Cancel( );

Return Values

Returns VFW_E_ALREADY_CANCELLED if m_pQueue is NULL. Returns an HRESULT from CCmdQueue::Remove if the call generates an error. Returns S_OK if successful.

Remarks

This member function implements the IDeferredCommand::Cancel method.

CDeferredCommand::CDeferredCommand

CDeferredCommand Class

Constructs a CDeferredCommand object.

CDeferredCommand(
CCmdQueue * pQ,
LPUNKNOWN pUnk,
HRESULT * phr,
LPUNKNOWN pUnkExecutor,
REFTIME time,
GUID* iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT* pDispParams,
VARIANT* pvarResult,
short* puArgErr,
BOOL bStream
);

Parameters
pQ
Object that exposes the IQueueCommand interface.
pUnk
Outer IUnknown interface for aggregation.
phr
Returning HRESULT value.
pUnkExecutor
Object that will carry out this command.
time
Time at which the command will be run.
iid
Globally unique identifier (GUID) of the interface that contains the method.
dispidMethod
Method on the interface to call.
wFlags
Context of the invocation.
cArgs
Number of arguments passed.
pDispParams
List of argument variant types.
pvarResult
Returned variant type list, if any.
puArgErr
Last argument in the pDispParams parameter list with an error.
bStream
TRUE if the deferred command time is in stream time; FALSE if in presentation time.
Return Values

No return value.

CDeferredCommand::Confidence

CDeferredCommand Class

This method is not currently implemented.

HRESULT Confidence(
LONG *pConfidence
);

Parameters
pConfidence
Confidence level.
Return Values

Returns E_NOTIMPL.

Remarks

See IDeferredCommand::Confidence for information about implementing this method.

CDeferredCommand::GetFlags

CDeferredCommand Class

Returns the context flags associated with the deferred command.

short GetFlags( );

Return Values

The value retrieved will be one of the following.
Value | Description
DISPATCH_METHOD | Run the member as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag may be set.
DISPATCH_PROPERTYGET | The member is being retrieved as a property or data member.
DISPATCH_PROPERTYPUT | The member is being changed as a property or data member.
DISPATCH_PROPERTYPUTREF | The member is being changed via a reference assignment, rather than a value assignment. This flag is valid only when the property accepts a reference to an object.

CDeferredCommand::GetHResult

CDeferredCommand Class

Returns the HRESULT value from the invoked command.

HRESULT GetHResult(
HRESULT* phrResult
);

Parameters
phrResult
HRESULT value.
Return Values

Returns E_ABORT if m_pQueue is NULL. Otherwise, returns S_OK.

Remarks

This member function implements the IDeferredCommand::GetHResult method.

CDeferredCommand::GetIID

CDeferredCommand Class

Retrieves the interface identifier (IID) of the interface on which the method will be run.

REFIID GetIID( );

CDeferredCommand::GetMethod

CDeferredCommand Class

Retrieves the dispatch identifier of the method to be run.

long GetMethod( );

CDeferredCommand::GetParams

CDeferredCommand Class

Retrieves the DISPPARAMS argument list to the method.

DISPPARAMS* GetParams( );

CDeferredCommand::GetResult

CDeferredCommand Class

Retrieves the resulting argument list, if one exists.

VARIANT* GetResult( );

CDeferredCommand::GetTime

CDeferredCommand Class

Returns the time at which the method will be run.

CRefTime GetTime( );

Return Values

Returns a CRefTime object containing a reference time.

CDeferredCommand::Invoke

CDeferredCommand Class

Provides access to methods and properties exposed by an object.

HRESULT Invoke( );

Return Values

Returns VFW_E_ALREADY_CANCELLED if m_pQueue is NULL. Otherwise, returns the HRESULT resulting from a call to IDispatch::GetTypeInfo or IUnknown::QueryInterface.

CDeferredCommand::IsStreamTime

CDeferredCommand Class

Specifies whether the command is to be run at stream time or presentation time.

BOOL IsStreamTime( );

Return Values

Returns TRUE if set to stream time; otherwise, returns FALSE.

CDeferredCommand::NonDelegatingQueryInterface

CDeferredCommand Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IDeferredCommand and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

CDeferredCommand::Postpone

CDeferredCommand Class

Specifies a new presentation time for a previously queued command.

HRESULT Postpone(
REFTIME newtime
);

Parameters
newtime
New presentation time.
Return Values

Returns VFW_E_TIME_ALREADY_PASSED if newtime is already passed. Otherwise, returns an HRESULT resulting from a call to CCmdQueue::Remove (when extracting from the list) or CCmdQueue::Insert (when reinserting with the changed time).

Remarks

This member function implements the IDeferredCommand::Postpone method.


CDisp Class

CDisp class hierarchy

The CDisp class provides methods for displaying a number of data types for debugging. It provides a constructor for each type, and can be cast to the LPCTSTR type for use as a string in a debug statement.

For example, the following code fragment:

int MyFunc(REFERENCE_TIME rt, IPin *pPin)
{
    DbgLog((LOG_TRACE, 2, TEXT("MyFunc(%s, %s)"),
        (LPCTSTR) CDisp(CRefTime(rt)),
        (LPCTSTR) CDisp(pPin)));
...
}

could output the following reference time and pin information onto the debug log:

Quartz.dll(tid d7) : MyFunc(1.003 sec,
    CLSID_AudioRender(Audio Input pin (rendered)))

Member Functions
Name | Description
CDisp | Constructs a CDisp object.

Operators
Name | Description
LPCTSTR | Casts to an LPCTSTR type for use in a debug string.

CDisp::CDisp

CDisp Class

Constructs a CDisp object.

CDisp(
LONGLONG ll,
int Format = CDISP_HEX
);
CDisp(
REFCLSID clsid
);
CDisp(
double d
);
CDisp(
CRefTime t
);
CDisp(
IPin *pPin
);

Parameters
ll
LONGLONG value for display.
Format
Whether the value should be displayed in decimal (CDISP_DEC) or (by default) hexadecimal (CDISP_HEX).
clsid
Class identifier to display.
d
The double value to display.
t
Reference time to display. Note that passing a value of type REFERENCE_TIME will use the LONGLONG constructor.
pPin
IPin interface to display a pin as "CLSID of the filter(Pin name)"; for example, CLSID_AudioRenderer(Audio Input Pin).
Return Values

No return value.

Remarks

Various constructors are provided, which allows information to be displayed in the most suitable way.

CDisp::LPCTSTR

CDisp Class

Casts the CDisp object to an LPCTSTR value for use in a debug string.

operator LPCTSTR();
Return Values

Returns the string representation of the variable used in the constructor.


CDispBasic

CDispBasic class hierarchy

An internal class used to implement the CDisp class.

Member Functions
CDispBasic Constructor for the CDispBasic class.

Protected Data Members
m_PString | Points to the string to be displayed. Initially, this points to m_String, but larger strings may cause this to be updated to point to dynamically-allocated storage instead.
m_String[50] | The initial buffer area for this object.

CDispBasic::CDispBasic

CDispBasic

Instantiates an object of this class.

CDispBasic( );


CDispParams Class

CDispParams class hierarchy

The CDispParams class implements the DISPPARAMS structure used in Automation as a C++ base class. The IDispatch::Invoke method uses the OLE DISPPARAMS structure to contain the arguments passed to any method or property.

The DISPPARAMS structure is defined as follows:

typedef struct FARSTRUCT tagDISPPARAMS{
VARIANTARG FAR* rgvarg;               // Array of arguments
   DISPID FAR* rgdispidNamedArgs;     // Dispatch IDs of named arguments
   unsigned int cArgs;                // Number of arguments
   unsigned int cNamedArgs;           // Number of named arguments
} DISPPARAMS;

Member Functions
Name | Description
CDispParams | Constructs a CDispParams object.

CDispParams::CDispParams

CDispParams Class

Constructs a CDispParams object.

CDispParams(
UINT nArgs,
VARIANT* pArgs
);

Parameters
nArgs
Number of arguments passed to the method or property.
pArgs
Pointer to the list of arguments. In the list, each argument is stored with its variant type.
Return Values

No return value.


CDrawImage Class

CDrawImage class hierarchy

This class is a worker class for the owning CBaseWindow object. It handles the actual drawing operation from that class. To use this class, be sure to call CDrawImage::NotifyAllocator when the allocator has been agreed upon, and call CDrawImage::NotifyMediaType with a pointer to a CMediaType object (which must not be stack-based, because a pointer is maintained by this class rather than making a copy) when that is agreed.

When the palette changes, call CDrawImage::IncrementPaletteVersion, and before rendering call CDrawImage::SetDrawContext so that the class can obtain the handle to a device context (HDC) handles from the owning CBaseWindow object.

Protected Data Members
Name | Description
m_bStretch | Flag to stretch the images.
m_bUsingImageAllocator | Flag to determine if samples share DIBSECTION structures.
m_EndSample | End time for the current sample.
m_hdc | Main window device context (DC).
m_MemoryDC | Offscreen draw DC.
m_pBaseWindow | Owning video window object.
m_PaletteVersion | Current palette version token.
m_perfidRenderNow | Moment when returned from draw (for performance logging).
m_perfidRenderTime | Time taken to render an image (for performance logging).
m_pMediaType | Pointer to the current media type format.
m_SourceRect | Source image rectangle.
m_StartSample | Start time for the current sample.
m_TargetRect | Destination rectangle.

Member Functions
Name | Description
CDrawImage | Constructs a CDrawImage object.
DisplaySampleTimes | Displays a time stamp of a sample on top of its image.
DrawImage | Looks after drawing an image to a window.
FastRender | Draws an image using BitBlt and StretchBlt.
GetPaletteVersion | Retrieves the currently installed palette version.
GetSourceRect | Retrieves the current source rectangle.
GetTargetRect | Retrieves the current target rectangle.
IncrementPaletteVersion | Increments the current palette version.
NotifyAllocator | Notifies the draw object which allocator is being used.
NotifyEndDraw | Indicates the conclusion of image rendering.
NotifyMediaType | Passes the media type established during connection.
NotifyStartDraw | Indicates the beginning of image rendering.
ResetPaletteVersion | Resets the current palette version.
ScaleSourceRect | Returns a scaled version of a provided source rectangle.
SetDrawContext | Sets the window and offscreen device contexts to draw with.
SetSourceRect | Sets the source rectangle for the video.
SetStretchMode | Determines whether it is necessary to stretch.
SetTargetRect | Sets the target rectangle for the window.
SlowRender | Uses the Microsoft® Win32® SetDIBitsToDevice and StretchDIBits functions to draw an image.
UpdateColourTable | Updates the palette held in a DIBSECTION structure.
UsingImageAllocator | Retrieves the type of samples to be drawn.

CDrawImage::CDrawImage

CDrawImage Class

Constructs a CDrawImage object.

CDrawImage(
CBaseWindow *pBaseWindow
);

Parameters
pBaseWindow
Window where drawing will occur.
Return Values

No return value.

Remarks

This class handles drawing of images through GDI. It works closely in conjunction with the CImageAllocator and CBaseWindow classes. It must know about the CImageAllocator class, because the draw code provides a faster drawing implementation if the buffers it is handed are created through the Microsoft® Win32® CreateDIBSection function. The image allocator creates this type of sample. It is told whether the buffers are allocated by a CImageAllocator object (or derived class) via the CDrawImage::NotifyAllocator member function.

If the buffers used to draw are not allocated by a compatible allocator, it will draw using the Win32 SetDIBitsToDevice family of APIs. The CBaseWindow class retrieves the window handle where the images are to be drawn. The device contexts that the drawing code should use are passed in through the CDrawImage::SetDrawContext member function.

The CImageAllocator, CImageSample, and CDrawImage classes are all tightly associated. The buffers that the image allocator creates are made using the Win32 CreateDIBSection function. The allocator then creates its own samples (based on the CImageSample class). The image samples are initialized with the buffer pointer and its length. The sample is also passed in a structure (a DIBDATA structure) that holds a number of pieces of information obtained from the CreateDIBSection function.

These samples can then be passed to the draw object. The draw object knows the private format of the samples, and how to get the DIBDATA structure back from them. Once the draw object has obtained that information, it can pass a bitmap handle, stored in the DIBDATA structure, down into GDI when it draws the image that the sample contains. By using the bitmap handle from the sample in the drawing, rather than just the buffer pointer (which is the alternative if the sample is not a CImageSample), it gets a modest performance improvement.

CDrawImage::DisplaySampleTimes

CDrawImage Class

Displays time stamp of a sample on top of the image.

void DisplaySampleTimes(
IMediaSample *pSample
);

Parameters
pSample
Sample containing time stamps.
Return Values

No return value.

Remarks

In debugging builds, it is often instructive to see the time stamps for images that the object is drawing. This member function gets the data pointer for the image the sample holds, along with its time stamps; then, using an offscreen device context, it draws the times approximately 80 percent of the way down the image (and centered horizontally).

This is a protected member function.

CDrawImage::DrawImage

CDrawImage Class

Entry point for drawing an image.

BOOL DrawImage(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Sample to draw.
Return Values

No return value.

Remarks

If the samples have been allocated by a CImageAllocator object (or a derived class), the images that the samples contain will be drawn using the Microsoft Win32 BitBlt or StretchBlt function. If not, they will be drawn using SetDIBitsToDevice or StretchDIBits. The client must call CDrawImage::NotifyAllocator prior to calling this member function to inform the CDrawImage object how the image buffers have been allocated. The object is informed each time the source or destination changes (through its CDrawImage::SetSourceRect and CDrawImage::SetTargetRect member functions). It uses this information to determine if it needs to stretch the image during the draw.

CDrawImage::FastRender

CDrawImage Class

Draws the sample image using the Microsoft Win32 BitBlt and StretchBlt functions.

void FastRender(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Sample to draw.
Return Values

No return value.

Remarks

This protected member function is called by CDrawImage with a sample that contains an image buffer. The image buffer must have been allocated through the Win32 CreateDIBSection function and by a CImageAllocator object (or derived class). There are some performance benefits from drawing images created through this mechanism.

CDrawImage::GetPaletteVersion

CDrawImage Class

Retrieves the current palette version.

LONG GetPaletteVersion( );

Return Values

Returns the palette version.

Remarks

This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.

CDrawImage::GetSourceRect

CDrawImage Class

Retrieves the current source rectangle the draw object is using.

void GetSourceRect(
RECT *pSourceRect
);

Parameters
pSourceRect
Holds the source rectangle.
Return Values

No return value.

CDrawImage::GetTargetRect

CDrawImage Class

Retrieves the current destination rectangle the draw object is using.

void GetTargetRect(
RECT *pTargetRect
);

Parameters
pTargetRect
Holds the target rectangle.
Return Values

No return value.

CDrawImage::IncrementPaletteVersion

CDrawImage Class

Increments the current palette version.

void IncrementPaletteVersion( );

Return Values

No return value.

Remarks

This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.

CDrawImage::NotifyAllocator

CDrawImage Class

Notifies the draw object which allocator the output pin is actually going to use.

void NotifyAllocator(
BOOL bUsingImageAllocator
);

Parameters
bUsingImageAllocator
Flag to indicate whether to use a CImageAllocator object allocator or not.
Return Values

No return value.

Remarks

This member function tells the draw object whose allocator to use. This should be called with TRUE if the filter agrees to use an allocator based around the DirectShow™ CImageAllocator base class. These image buffers are made through CreateDIBSection. Otherwise this should be called with FALSE, and the images will be drawn using SetDIBitsToDevice and StretchDIBits.

CDrawImage::NotifyEndDraw

CDrawImage Class

Indicates the conclusion of image rendering.

void NotifyEndDraw(void);

Return Values

No return value.

Remarks

This member function is used for performance measurements and just calls the MSR_STOP macro.

CDrawImage::NotifyMediaType

CDrawImage Class

Provides the image format for the draw object.

void NotifyMediaType(
CMediaType *pMediaType
);

Parameters
pMediaType
Media type.
Return Values

No return value.

Remarks

The draw object must know the format of the images it will be drawing. For the most part, this is so it can retrieve the palette when the images are 8-bit palettized. A filter using the draw class will usually call this just after completing a connection.

The method does not take a copy of the media type but just stores a pointer (for performance reasons). Therefore, the caller should ensure that the media type is not destroyed inadvertently.

CDrawImage::NotifyStartDraw

CDrawImage Class

Indicates the beginning of image rendering.

void NotifyStartDraw(void);

Return Values

No return value.

Remarks

This member function is used for performance measurements and just calls the MSR_START macro.

CDrawImage::ResetPaletteVersion

CDrawImage Class

Resets the current palette version.

void ResetPaletteVersion( );

Return Values

No return value.

Remarks

This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.

CDrawImage::ScaleSourceRect

CDrawImage Class

Returns a scaled version of a provided source rectangle.

virtual RECT ScaleSourceRect(
const RECT *pSource
);

Parameters
pSource
Unscaled source rectangle.
Return Values

Returns the scaled source rectangle (returns unscaled pSource by default).

Remarks

The base class implementation does not scale the source rectangle. Derived classes can override this to implement scaling, if required.

CDrawImage::SetDrawContext

CDrawImage Class

Sets the device contexts used for drawing.

void SetDrawContext( );

Return Values

No return value.

Remarks

The draw object always needs a device context for the window to draw images in. It might also need an offscreen device context to select bitmaps into when using DIBSECTION buffers (for more details on these and CreateDIBSection, see the Microsoft Platform SDK documentation). This member function will typically be called by a filter using this class, once it has initialized a window.

CDrawImage::SetSourceRect

CDrawImage Class

Sets the source rectangle for the video.

void SetSourceRect(
RECT *pSourceRect
);

Parameters
pSourceRect
New source rectangle.
Return Values

No return value.

Remarks

The source rectangle should already have been validated before calling this member function so that the source rectangle specified will not extend over the edges of the available video.

CDrawImage::SetStretchMode

CDrawImage Class

Decides whether the video is to be stretched.

void SetStretchMode( );

Return Values

No return value.

Remarks

When the object is asked to draw an image, the object must know whether the video is being stretched, because it affects the function it calls (BitBlt or StretchBlt, for example). Rather than calculate this for every frame, it works it out just once when the source or destination rectangle is updated. This member function is called by SetSourceRect and SetTargetRect to manage this calculation.

This is a protected member function.

CDrawImage::SetTargetRect

CDrawImage Class

Sets the target rectangle for the video.

void SetTargetRect(
RECT *pTargetRect
);

Parameters
pTargetRect
New target area.
Return Values

No return value.

Remarks

The destination rectangle should already have been validated before calling this member function, so that the destination specified will not define an empty playback area.

CDrawImage::SlowRender

CDrawImage Class

Draws the sample image using SetDIBitsToDevice and StretchDIBits.

void SlowRender(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Sample to draw.
Return Values

No return value.

Remarks

The sample provided should contain the image to draw and should match the format as specified to the draw object through NotifyMediaType.

This is a protected member function.

CDrawImage::UpdateColourTable

CDrawImage Class

Updates the palette associated with a sample.

void UpdateColourTable(
HDC hdc,
BITMAPINFOHEADER *pbmi
);

Parameters
hdc
Device context containing the sample image.
pbmi
BITMAPINFO structure containing the new palette.
Return Values

No return value.

Remarks

This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. CImageAllocator creates samples that are created with the Microsoft Win32 CreateDIBSection function. When a palettized buffer is allocated through CreateDIBSection, a palette is passed in that is associated with that buffer.

Should the palette be changed, the new palette must be associated with the buffer before drawing it (this is done through the Win32 SetDIBColorTable function and internally with the UpdateColourTable member function). The drawing code knows to update the palette because the palette version it stores in the sample will differ from the palette version it keeps internally.

In essence, the sample gets an initial palette version when created. When the palette is changed (probably by a filter), it tells the draw object to increment its palette version (through the IncrementPaletteVersion member function). When the draw object next comes to draw the sample, it will see that the sample has an old palette version and will know to call UpdateColourTable on it.

The draw object knows the type of buffer used for samples through the NotifyAllocator member function. If it is called with TRUE, the buffers passed to it must be allocated by a CImageAllocator (or derived class) object. If it is called with FALSE, the buffers should be allocated in standard system memory (or other memory accessible to GDI in the same manner).

When the allocator is decommitted, it will typically delete all the samples it holds on to. When it is subsequently committed, the samples will be created again with their initial palette versions. At this point, the allocator should also reset the palette version in the draw object so that they remain in sync. An allocator can do this by calling the ResetPaletteVersion member function.

This is a protected member function.

CDrawImage::UsingImageAllocator

CDrawImage Class

Retrieves the type of samples to be drawn.

BOOL UsingImageAllocator( );

Return Values

Returns one of the following values.
Value | Meaning
TRUE | Allocated through CreateDIBSection.
FALSE | Not allocated through CreateDIBSection.

Remarks

This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes and the image allocator, see the CDrawImage::UpdateColourTable member function.


CEnumMediaTypes Class

CEnumMediaTypes class hierarchy

This class provides the mechanism for enumerating the pin's preferred media types. Its constructor must be passed to an object from a class derived from CBasePin. It uses the virtual member function GetMediaType to retrieve each of the media types in turn. It also uses the pin's CBasePin::GetMediaTypeVersion member function to determine if the number or type of media types has changed.

The base pin class does not support dynamic media type changes. CBaseFilter::GetPinVersion always returns the same value, for example.

The media type enumerator must fill in a list of pointers to media type structures. The memory for those media type structures must be released by the callers when they have finished with it. However, the memory must not be allocated from any language-specific heap; otherwise, problems might occur between a filter written in C and another written in C++. For this reason, the base classes provide generic functions (not member functions of a class) to create and delete media types: CreateMediaType and DeleteMediaType. These manage memory allocation from the task allocator.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Member Functions
Name | Description
CEnumMediaTypes | Constructs a CEnumMediaTypes object.

Implemented IUnknown Methods
Name | Description
AddRef | Increments the reference count.
QueryInterface | Returns pointers to supported interfaces.
Release | Decrements the reference count.

Implemented IEnumMediaTypes Methods
Name | Description
Clone | Creates a duplicate CEnumMediaTypes object with the same state.
Next | Returns the next media type after the current position.
Reset | Sets the current position back to the beginning.
Skip | Skips over one or more entries in the enumerator.

CEnumMediaTypes::AddRef

CEnumMediaTypes Class

Increments the reference count for the calling interface on an object. It should be called for every new copy of a pointer to an interface on a given object.

ULONG AddRef(void);

Return Values

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value might be unstable.

Remarks

This member function implements the IUnknown::AddRef method.

CEnumMediaTypes::CEnumMediaTypes

CEnumMediaTypes Class

Constructs a CEnumMediaTypes object.

CEnumMediaTypes(
CBasePin *pPin,
CEnumMediaTypes *pEnumMediaTypes
);

Parameters
pPin
Pointer to the pin on which the enumeration is to be performed.
pEnumMediaTypes
Pointer to the instantiated CEnumMediaTypes object.
Return Values

No return value.

Remarks

This is a standard class constructor.

CEnumMediaTypes::Clone

CEnumMediaTypes Class

Retrieves another enumerator containing the same enumeration state as the current one.

HRESULT Clone(
IEnumMediaTypes ** ppEnum
);

Parameters
ppEnum
New copy of the enumerator.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Clone method.

CEnumMediaTypes::Next

CEnumMediaTypes Class

Retrieves the specified number of items in the enumeration sequence.

HRESULT Next(
ULONG cMediaTypes,
AM_MEDIA_TYPE** ppMediaTypes,
ULONG * pcFetched
);

Parameters
cMediaTypes
Number of media types to place.
ppMediaTypes
Array in which to place the next media type or types.
pcFetched
Actual count passed.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Next method. To call this method, pass a pointer's address to a media type. The base class implementation relies on the existence of an overridden CBasePin::GetMediaType member function in the derived class that will provide the next media type.

Free each media type acquired by calling DeleteMediaType, which will free the format block and the media type itself.

CEnumMediaTypes::QueryInterface

CEnumMediaTypes Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer.

HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);

Parameters
iid
Specifies the IID of the interface being requested.
ppvObject
Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.
Return Values

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method and passes out references to the IEnumMediaTypes interface. Override this class to return other interfaces on the object in the derived class.

CEnumMediaTypes::Release

CEnumMediaTypes Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

ULONG Release(void);

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

CEnumMediaTypes::Reset

CEnumMediaTypes Class

Resets the enumerator to the beginning so that the next call to the IEnumMediaTypes::Next method will return, at a minimum, the first media type in the enumeration.

HRESULT Reset(void);

Return Values

Returns S_OK if successful; otherwise, returns S_FALSE.

Remarks

This member function implements the IEnumMediaTypes::Reset method.

CEnumMediaTypes::Skip

CEnumMediaTypes Class

Skips a specified number of elements in the enumeration sequence.

HRESULT Skip(
ULONG cMediaTypes
);

Parameters
cMediaTypes
Number of media type elements to skip.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumMediaTypes::Skip method.


CEnumPins Class

CEnumPins class hierarchy

This class supports the IEnumPins enumeration interface by calling CBaseFilter methods. The CBaseFilter class supports the IBaseFilter::EnumPins method. Each time one of this interface's methods is called, the CBaseFilter class checks to see if the pins that it enumerates have changed; it does this by calling CBaseFilter::GetPinVersion and matching the version the filter is keeping with the version that it stores during construction.

If a pin enumerator becomes stale, there is no mechanism for resynchronizing it with the filter. The user must release the interface and retrieve another one.

Because the enumeration operation is likely to fail if the pin version changes (indicating that the filter might have added or removed pins), all member functions in this class check the version by calling a private member function, which calls the owning filter's CBaseFilter::GetPinVersion member function. These member functions then return VFW_E_ENUM_OUT_OF_SYNC if the version has changed. This should always work unless the filter has overridden CBaseFilter::GetPinVersion to do something unexpected.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Member Functions
Name | Description
CEnumPins | Constructs a CEnumPins object.

Implemented IUnknown Methods
Name | Description
AddRef | Increments the reference count.
QueryInterface | Returns pointers to supported interfaces.
Release | Decrements the reference count.

Implemented IEnumPins Methods
Name | Description
Clone | Creates a duplicate CEnumPins object with the same initial state.
Next | Returns the next pin after the current position.
Reset | Sets the current position back to the beginning.
Skip | Skips over one or more entries in the enumerator.

CEnumPins::AddRef

CEnumPins Class

Increments the reference count for the calling interface on an object.

ULONG AddRef(void);

Return Values

Returns an integer from 1 to n, the value of the new reference count.

Remarks

This member function implements the IUnknown::AddRef method.

CEnumPins::CEnumPins

CEnumPins Class

Constructor for the CEnumPins class.

CEnumPins(
CBaseFilter *pFilter,
CEnumPins *pEnumPins
);

Parameters
pFilter
Pointer to the filter on which to enumerate the pins.
pEnumPins
Returned pointer to an IEnumPins interface object.
Return Values

No return value.

CEnumPins::Clone

CEnumPins Class

Makes a copy of the enumerator. This allows the calling application to retain two positions in the list of pins.

HRESULT Clone(
IEnumPins ** ppEnum
);

Parameters
ppEnum
New enumerator that is a copy of this enumerator.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Clone method.

CEnumPins::Next

CEnumPins Class

Places pointers to IPin interfaces into the specified array.

HRESULT Next(
ULONG cPins,
IPin ** ppPins,
ULONG * pcFetched
);

Parameters
cPins
Number of pins to place.
ppPins
Array in which to place the interface pointers.
pcFetched
Actual number of pins placed in the array.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Next method. The derived class is responsible for implementing CBaseFilter::GetPin, which this member function calls to retrieve the next pin.

Because this member function returns one or more interfaces that have had their reference counts incremented, the caller of this member function must be sure to release the interfaces by calling IUnknown::Release on the interfaces when done with them.

CEnumPins::QueryInterface

CEnumPins Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);

Parameters
iid
Specifies the IID of the interface being requested.
ppvObject
Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.
Return Values

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method and passes out references to the IEnumPins interface.

CEnumPins::Release

CEnumPins Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

ULONG Release(void);

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

CEnumPins::Reset

CEnumPins Class

Resets the enumerator to the beginning so that the next call to the IEnumPins::Next method will return, at a minimum, the first pin of the filter.

HRESULT Reset(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Reset method.

CEnumPins::Skip

CEnumPins Class

Skips the next specified number of pins.

HRESULT Skip(
ULONG cPins
);

Parameters
cPins
Number of pins to skip.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IEnumPins::Skip method. This member function affects the next call to the IEnumPins::Next method.


CFactoryTemplate Class

CFactoryTemplate class hierarchy

This class provides a template used by the default class factory code.

Create one CFactoryTemplate object in an array for every object class so that the default class factory code can create new instances.

This class holds the name of the object, the object's class identifier (CLSID), and a pointer to the creation function for the corresponding object. Initialize one of these in an array called g_Templates for each CLSID the application's dynamic-link library (DLL) supports. The creation function should take an LPUNKNOWN parameter and an HRESULT pointer and return an object derived from the CBaseObject class. Set the HRESULT to a failed value if there is any error in construction. An example declaration (from the Gargle sample filter) follows:

// list of class ids and creator functions for class factory

CFactoryTemplate g_Templates[2]= { { L"Gargle filter"         // CFactoryTemplate.m_name
                                   , &CLSID_Gargle            // CFactoryTemplate.m_ClsID
                                   , CGargle::CreateInstance  // CFactoryTemplate.m_lpfnNew
                                   , NULL                     // CFactoryTemplate.m_lpfnInit
                                   , &sudGargle               // CFactoryTemplate.m_pAMovieSetup_Filter
                                   }
                                 , { L"Gargle filter property page"
                                   , &CLSID_GargProp
                                   , CGargleProperties::CreateInstance
                                   }
                                 };

int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

Note that the name of the object is strictly necessary only if you are using the DllRegisterServer setup routine to implement self-registering of your filter. If you are not using this feature, you can set the first element of the g_Templates instance (m_Name) to NULL or L"".

Protected Data Members
Name | Description
m_ClsID | Pointer to the CLSID of the object class.
m_lpfnNew | Pointer to a function that creates an instance of the object class.
m_lpfnInit | Pointer to a function that initializes a new instance of the object class.
m_Name | Name of the filter; required when using filter self-registration services.
m_pAMovieSetup_Filter | Pointer to an AMOVIESETUP_FILTER structure; required when using filter self-registration services.

Member Functions
Name | Description
CreateInstance | Calls the object-creation function for the class.
IsClassID | Determines whether a CLSID matches this class template.

CFactoryTemplate::CreateInstance

CFactoryTemplate Class

Calls the object-creation function for the class.

CUnknown *CreateInstance(
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pUnk
Pointer to the IUnknown interface.
phr
Pointer to the HRESULT value into which to place resulting information.
Return Values

Returns an instance of the class object.

Remarks

The implementer of the class code registered using this factory template class is responsible for providing the code that creates an instance of the class object and assigning it to the m_lpfnNew data member. This member function simply calls that function and returns a new object of that type.

CFactoryTemplate::IsClassID

CFactoryTemplate Class

Determines if the class identifier (CLSID) passed matches the CLSID assigned to this class template.

BOOL IsClassID(
REFCLSID rclsid
);

Parameters
rclsid
CLSID being tested.
Return Values

Returns TRUE if the CLSIDs are the same; otherwise, returns FALSE.


CGenericList Class

CGenericList class hierarchy

CGenericList is a template class that allows for a type-specific implementation of a list. It is derived from CBaseList and uses that class's typeless implementation. The constructor creates a CBaseList object, and all CGenericList member functions call CBaseList member functions but provide type-checking dependent on the template.

Member Functions
Name | Description
AddAfter | Inserts a node or list of nodes after the specified node.
AddBefore | Inserts a node or list of nodes before the specified node.
AddHead | Inserts a node or list of nodes at the front of the list.
AddTail | Appends a node or list of nodes to the end of the list.
CGenericList | Constructs a CGenericList object.
Find | Returns the first position that contains the specified object.
Get | Returns the object at the specified position.
GetCount | Returns the number of objects (object count) in the list.
GetHead | Returns the object at the head of the list.
GetHeadPosition | Returns a cursor identifying the first element of the list.
GetNext | Returns the specified object and update position.
GetTailPosition | Returns a cursor identifying the last element of the list.
Remove | Removes the specified node from the list.
RemoveHead | Removes the first node in the list.
RemoveTail | Removes the last node in the list.

CGenericList::AddAfter

CGenericList Class

Inserts a node or list of nodes after the specified node.

POSITION AddAfter(
POSITION p,
OBJECT * pObj
);
BOOL AddAfter(
POSITION pos,
CGenericList<OBJECT> *pList
);

Parameters
pos
Position after which to add the node or list of nodes.
pObj
Pointer to the object to add.
pList
Pointer to the list of objects to add.
Return Values

Returns the position of the inserted object in the case of single-object insertion. For list insertion, returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function calls the CBaseList::AddAfter member function when passed a list of nodes. CGenericList::AddAfter calls the CBaseList::AddAfterI member function when passed a single node.

CGenericList::AddBefore

CGenericList Class

Inserts a node or list of nodes before the specified node.

POSITION AddBefore(
POSITION p,
OBJECT * pObj
);
BOOL AddBefore(
POSITION pos,
CGenericList<OBJECT> *pList
);

Parameters
pos
Position before which to add the node or list of nodes.
pObj
Pointer to the object to add.
pList
Pointer to the list of objects to add.
Return Values

Returns the position of the inserted object in the case of single-object insertion. For list insertion, returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function calls the CBaseList::AddBefore member function when passed a list of nodes. CGenericList::AddBefore calls the CBaseList::AddBeforeI member function when passed a single node.

CGenericList::AddHead

CGenericList Class

Inserts a node or list of nodes at the front of the list.

POSITION AddHead(
OBJECT * pObj
);
BOOL AddHead(
CGenericList<OBJECT> *pList
);

Parameters
pObj
Pointer to the object to add.
pList
Pointer to the list of objects to add.
Return Values

Returns the new head position, or NULL if unsuccessful in the case of single-node additions. For list insertions, returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function calls the CBaseList::AddHead member function when passed a list of nodes. CGenericList::AddHead calls the CBaseList::AddHeadI member function when passed a single node.

CGenericList::AddTail

CGenericList Class

Appends a node or list of nodes to the end of the list.

POSITION AddTail(
OBJECT * pObj
);
BOOL AddTail(
CGenericList<OBJECT> *pList
);

Parameters
pObj
Pointer to the object to add.
pList
Pointer to the list of objects to add.
Return Values

Returns the new tail position, or NULL if unsuccessful in the case of single-node insertions. For list insertions, returns TRUE if successful; otherwise, returns FALSE.

Remarks

This member function calls the CBaseList::AddTail member function when passed a list of nodes. CGenericList::AddTail calls the CBaseList::AddTailI member function when passed a single node.

CGenericList::CGenericList

CGenericList Class

Constructs a CGenericList object.

CGenericList(
TCHAR *pName,
INT iItems,
BOOL bLock,
BOOL bAlert
);

CGenericList(
TCHAR *pName
);

Parameters
pName
Name of the list.
iItems
Number of items in the list.
bLock
TRUE if the list is locked and FALSE otherwise. This parameter defaults to TRUE.
bAlert
Not used.
Return Values

No return value.

Remarks

This constructor calls the CBaseList constructor.

CGenericList::Find

CGenericList Class

Retrieves the first position that contains the specified object.

POSITION Find(
OBJECT * pObj
);

Parameters
pObj
Pointer to the object to find.
Return Values

Returns a position cursor.

Remarks

This member function calls the CBaseList::FindI member function.

CGenericList::Get

CGenericList Class

Retrieves the object at the specified position.

OBJECT *Get(
POSITION pos
);

Parameters
pos
Position in the list from which to retrieve the object.
Return Values

Returns a pointer to an object.

Remarks

This member function calls the CBaseList::GetI member function.

CGenericList::GetCount

CGenericList Class

Retrieves the number of objects (object count) in the list.

int GetCount( );

Return Values

Returns the value of m_Count.

CGenericList::GetHead

CGenericList Class

Retrieves the object at the head of the list.

OBJECT GetHead( );

Return Values

Returns the head of the list by calling CGenericList::GetHeadPosition.

CGenericList::GetHeadPosition

CGenericList Class

Retrieves a cursor identifying the first element of the list.

POSITION GetHeadPosition( );

Return Values

Returns the position cursor held by m_pFirst.

CGenericList::GetNext

CGenericList Class

Retrieves the specified object and update position.

OBJECT *GetNext(
POSITION& rp
);

Parameters
rp
Returned pointer to the next object.
Return Values

Returns a pointer to an object at the next position.

Remarks

This member function calls the CBaseList::GetNextI member function.

CGenericList::GetTailPosition

CGenericList Class

Retrieves a cursor identifying the last element of the list.

POSITION GetTailPosition( );

Return Values

Returns the position cursor held by m_pLast.

CGenericList::Remove

CGenericList Class

Removes the specified node from the list.

OBJECT *Remove(
POSITION pos
);

Parameters
pos
Position in the list of nodes to remove.
Return Values

Returns the pointer to the object that was removed.

Remarks

This member function calls the CBaseList::RemoveI member function.

CGenericList::RemoveHead

CGenericList Class

Removes the first node in the list.

OBJECT *RemoveHead( );

Return Values

Returns the pointer to the object that was removed.

Remarks

This member function calls the CBaseList::RemoveHeadI member function.

CGenericList::RemoveTail

CGenericList Class

Removes the last node in the list.

OBJECT *RemoveTail( );

Return Values

Returns the pointer to the object that was removed.

Remarks

This member function calls the CBaseList::RemoveTailI member function.


CGuidNameList Class

CGuidNameList class hierarchy

This class implements an array of globally unique identifier (GUID) names based on the predefined names of GUIDs that come with Microsoft® DirectShow™. (This might or might not include user-defined GUIDs.) To get the name used for a GUID, look it up in the GuidNames array:

int MyFunc(AM_MEDIA_TYPE mt)
{
    DbgLog((LOG_TRACE, 2, TEXT("MyFunc: Type %s, Subtype %s"),
        GuidNames[mt.majortype],
        GuidNames[mt.subtype]
        ));
...
}

Operators
Name | Description
operator[ ] | Allows access to the GUID name for a given GUID.

Global Data
Name | Description
GuidNames | Array of CGuidNameList objects describing the predefined names of GUIDs that come with DirectShow. (This might or might not include user-defined GUIDs.)

CGuidNameList::operator[ ]

CGuidNameList Class

Allows access to the GUID name for a given GUID.

TCHAR *operator[ ](
const GUID& guid
);

Parameters
guid
Globally unique identifier.
Return Values

Returns the GUID name for the given entry in a GUID name list.


CImageAllocator Class

CImageAllocator class hierarchy

The CImageAllocator class is inherited from the CBaseAllocator class, which allocates sample buffers in shared memory. The number, size, and alignment of blocks are determined when the connected output pin calls CImageAllocator::SetProperties (which implements IMemAllocator::SetProperties). The shared memory blocks are used in subsequent calls to the Microsoft® Win32® CreateDIBSection function. The output pin can then fill these buffers with data, and the buffers will be handed to GDI using BitBlt.

Protected Data Members
Name | Description
m_pFilter | Owning filter of this object.
m_pMediaType | Current media type format.

Member Functions
Name | Description
Alloc | Allocates the samples through CreateDIBSection.
CheckSizes | Checks the allocator requirements.
CImageAllocator | Constructs a CImageAllocator object.
CreateDIB | Creates a device-independent bitmap (DIB).
Free | Releases and deletes the resources for any samples allocated.
NotifyMediaType | Notifies the allocator of the agreed media type.

Overridable Member Functions
Name | Description
CreateImageSample | Creates a sample.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingAddRef | Increments the reference count for an interface.
NonDelegatingRelease | Decrements the reference count for an interface.

Implemented IMemAllocator Methods
Name | Description
SetProperties | Specifies the buffering requirements for the allocator.

CImageAllocator::Alloc

CImageAllocator Class

Creates image samples based around CreateDIBSection.

HRESULT Alloc( );

Return Values

Returns an HRESULT value.

Remarks

A filter defines the size and number of buffers required through the CImageAllocator::SetProperties member function. The base allocator class that this allocator derives from calls this internal virtual member function when it wants the memory actually committed. For each sample it wants to create, this allocator will create a DIBSECTION object for it (through the Microsoft Win32 CreateDIBSection function). With the information it gets from that call, it will call the virtual CreateImageSample member function, passing in the buffer pointer and length. After successfully creating an image sample, it will then initialize it with the DIBSECTION structure, among other information.

This is a protected member function.

CImageAllocator::CheckSizes

CImageAllocator Class

Internal member function that checks the required buffering properties.

HRESULT CheckSizes(
ALLOCATOR_PROPERTIES *pRequest
);

Parameters
pRequest
Requested allocator properties.
Return Values

Returns an HRESULT value.

Remarks

The image allocator uses the Microsoft Win32 CreateDIBSection function to allocate its samples. That function accepts as input a pointer to a BITMAPINFO structure that describes the bitmap required. Because the size of the bitmap is therefore fixed according to the BITMAPINFO structure for the video, requests to the allocator for a buffer larger than that will not be granted. This member function, therefore, adjusts the requested size so that it is no larger than the size of the bitmap. If the requested size is smaller than the bitmap size, it returns E_INVALIDARG.

This is a protected member function.

CImageAllocator::CImageAllocator

CImageAllocator Class

Constructs a CImageAllocator object.

CImageAllocator(
CBaseFilter *pFilter,
TCHAR *pName,
HRESULT *phr
);

Parameters
pFilter
Owning filter object.
pName
Debug-only string description.
phr
COM return code.
Return Values

No return value.

Remarks

The CImageAllocator, CImageSample, and CDrawImage classes are all tightly associated. The buffers that the image allocator creates are made using the Microsoft Win32 CreateDIBSection function. The allocator then creates its own samples (based on the CImageSample class). The image samples are initialized with the buffer pointer and its length. The sample is also passed in a structure (a DIBDATA structure) that holds a number of pieces of information obtained from the CreateDIBSection call.

These samples can then be passed to the draw object. The draw object knows the private format of the samples and how to get back the DIBDATA structure from them. Once it has obtained that information, it can pass a bitmap handle that is stored in the DIBDATA structure down into GDI when it draws the image that the sample contains. By using the bitmap handle from the sample in the drawing, rather than just the buffer pointer (which is the alternative if the sample is not a CImageSample), it gets a modest performance improvement.

This is a protected member function.

CImageAllocator::CreateDIB

CImageAllocator Class

Calls the Win32 CreateDIBSection function to create a device-independent bitmap (DIB).

HRESULT CreateDIB(
LONG InSize,
DIBDATA &DibData
);

Parameters
InSize
Size of the bitmap required.
DibData
Structure to fill out with details.
Return Values

Returns an HRESULT value.

Remarks

This is a protected member function.

CImageAllocator::CreateImageSample

CImageAllocator Class

Creates a CImageSample object.

virtual CImageSample *CreateImageSample(
LPBYTE pData,
LONG Length
);

Parameters
pData
Pointer to the data buffer the sample looks after.
Length
Associated length of the buffer.
Return Values

Returns a new CImageSample sample object.

Remarks

This virtual member function creates the actual sample for the allocator. It is passed the data buffer and its length to store. When the sample is subsequently asked for the buffer (through IMediaSample::GetPointer), this is the pointer it will return. The primary reason for having this split out into a separate virtual member function is so that derived classes from CImageAllocator can also derive classes from CImageSample and have a place to create them.

This is a protected member function.

CImageAllocator::Free

CImageAllocator Class

Deletes the samples and frees their resources.

void Free( );

Return Values

No return value.

Remarks

The base allocator calls this internal virtual member function when it wants to decommit the allocator.

This is a protected member function.

CImageAllocator::NonDelegatingAddRef

CImageAllocator Class

Increments the reference count for the owning filter.

HRESULT NonDelegatingAddRef( );

Return Values

Returns an HRESULT value.

Remarks

An allocator is conceptually a separate object from the filter that creates it. However, the image allocator is dependent on the filter that created it to supply it with additional information (such as the media type that it connected with). Therefore, although the allocator looks after its own NonDelegatingQueryInterface function, it delegates all reference counting to the owning filter. So, when the allocator is subject to its NonDelegatingAddRef function, for example, it is the filter that owns the allocator that will actually be reference counted.

CImageAllocator::NonDelegatingRelease

CImageAllocator Class

Decrements the reference count for the owning filter.

HRESULT NonDelegatingRelease( );

Return Values

Returns an HRESULT value.

Remarks

An allocator is conceptually a separate object from the filter that creates it. However, the image allocator is dependent on the filter that created it to supply it with additional information (such as the media type that it connected with). Therefore, although the allocator looks after its own NonDelegatingQueryInterface function, it delegates all reference counting to the owning filter. So when the allocator is released, for example, it is the filter that owns the allocator that will actually be released by the NonDelegatingRelease function.

CImageAllocator::NotifyMediaType

CImageAllocator Class

Passes the media type from a filter to the allocator.

void NotifyMediaType(
CMediaType *pMediaType
);

Parameters
pMediaType
Media type the filter established.
Return Values

No return value.

Remarks

The buffers that the image allocator creates are based around CreateDIBSection, which must be told what sort of bitmap the filter requires it to create. The filter does this by calling this member function on the allocator. A filter will usually call this member function after agreeing on a media type during a pin connection. The media type passed to this member function is a pointer; the allocator stores this pointer (not a copy) of the media type it points to (for performance reasons, copying media types is relatively slow). Therefore, the filter that calls this member function should ensure that the media type is always valid until the media type is next set on the allocator (or is called with a NULL type).

CImageAllocator::SetProperties

CImageAllocator Class

Determines the size, number, and alignment of blocks.

HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);

Parameters
pRequest
Requested allocator properties.
pActual
Allocator properties actually set.
Return Values

Returns an HRESULT value.

Remarks

The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values that it can provide for the request. This member function cannot be called unless the allocator has been decommitted by using the IMemAllocator::Decommit method.


CImageDisplay Class

CImageDisplay class hierarchy

This class initializes itself with a display format so that other objects can query or reset the display type. It also provides member functions to check display formats and accept only those video formats that can be efficiently rendered by using GDI calls.

Protected Data Members
Name | Description
m_Display | VIDEOINFOHEADER structure corresponding to the current device display type.

Member Functions
Name | Description
CheckBitFields | Checks that the bit fields on a VIDEOINFOHEADER structure are correct.
CheckHeaderValidity | Determines if a BITMAPINFOHEADER structure is valid.
CheckMediaType | Determines if the filter can support the media type proposed by the output pin.
CheckPaletteHeader | Determines if the palette on a VIDEOINFOHEADER structure is correct.
CheckVideoType | Compares a video type to determine if it is compatible with the current display mode.
CImageDisplay | Constructs a CImageDisplay object.
CountPrefixBits | Counts the number of prefix bits.
CountSetBits | Counts the total number of bits set in a field.
GetBitMasks | Retrieves a set of color element bitmasks for the supplied VIDEOINFOHEADER structure.
GetColourMask | Retrieves a set of individual color element masks.
GetDisplayDepth | Retrieves the bit depth of the current display mode.
GetDisplayFormat | Retrieves a VIDEOINFOHEADER structure representing the current display mode.
IsPalettized | Determines if the display uses a palette.
RefreshDisplayType | Updates the CImageDisplay object with the current display type.
UpdateFormat | Updates the VIDEOINFOHEADER structure to remove implicit assumptions.

CImageDisplay::CheckBitFields

CImageDisplay Class

Checks that the bit fields in the VIDEOINFOHEADER structure are correct.

BOOL CheckBitFields(
const VIDEOINFO *pInput
);

Parameters
pInput
VIDEOINFOHEADER structure to check.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Bit fields are correct.
FALSE | Bit fields contain an error.

Remarks

The assumption throughout the object is that any bitmasks are allowed no more than 8 bits to store a color component. This member function checks that the bit count assumption is enforced, and also ensures that all the bits set are contiguous.

This is a protected member function.

CImageDisplay::CheckHeaderValidity

CImageDisplay Class

Determines if a BITMAPINFOHEADER structure is valid.

BOOL CheckHeaderValidity(
const VIDEOINFO *pInput
);

Parameters
pInput
VIDEOINFOHEADER structure that contains the bitmap details.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Format is valid.
FALSE | Format contains an error.

Remarks

The BITMAPINFOHEADER structure might be rejected for a number of reasons. These might include a number-of-planes entry greater or less than one, the size of the structure not being equal to the size of BITMAPINFOHEADER, or, perhaps, being asked to validate a YUV format (this member function only validates RGB formats; it will always return FALSE for YUV types).

CImageDisplay::CheckMediaType

CImageDisplay Class

Determines if the filter can support the media type proposed by the output pin.

HRESULT CheckMediaType(
const CMediaType *pmtIn
);

Parameters
pmtIn
Media type to check.
Return Values

Returns an HRESULT value.

Remarks

This helper member function can be used to validate a video media type. It examines the major and minor type GUIDs and verifies that the format GUID defines a VIDEOINFOHEADER structure.

CImageDisplay::CheckPaletteHeader

CImageDisplay Class

Determines if the palette on a VIDEOINFOHEADER structure is correct.

BOOL CheckPaletteHeader(
const VIDEOINFO *pInput
);

Parameters
pInput
VIDEOINFOHEADER structure to validate.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Palette is correct.
FALSE | No valid palette.

Remarks

This member function returns FALSE if the format specifies that no palette is available (it might be a true-color format). It also returns FALSE if the number of palette colors used (or those that are important) exceeds the number specified for the video format.

CImageDisplay::CheckVideoType

CImageDisplay Class

Compares a video type to determine if it is compatible with the current display mode.

HRESULT CheckVideoType(
const VIDEOINFO *pInput
);

Parameters
pInput
VIDEOINFOHEADER structure to validate.
Return Values

Returns NOERROR if successful or E_INVALIDARG if unsuccessful.

Remarks

Many video rendering filters want a function to determine if proposed formats are okay. This member function checks the VIDEOINFOHEADER structure passed as a media type and returns NOERROR if the media type is valid; otherwise, it returns E_INVALIDARG434. Note, however, that only formats that can be easily displayed on the current display device are accepted; so, for example, a 16-bit device will not accept 24-bit images. Because most displays draw 8-bit palettized images efficiently, this format is always accepted unless the display is 16-color VGA.

CImageDisplay::CImageDisplay

CImageDisplay Class

Constructs a CImageDisplay object.

CImageDisplay( );

Return Values

No return value.

Remarks

The CImageDisplay class helps renderers that want to determine the format of the current display mode. This member function retrieves the display mode and creates a VIDEOINFOHEADER structure that represents its format. The class supplies that format for clients through member functions such as IsPalettized and GetDisplayFormat. If a client detects the display format has changed (perhaps it receives a WM_DISPLAYCHANGED message), it should call RefreshDisplayType.

CImageDisplay::CountPrefixBits

CImageDisplay Class

Helper member function to count the number of prefix bits.

DWORD CountPrefixBits(
const DWORD Field
);

Parameters
Field
Input bitmask field.
Return Values

No return value.

Remarks

Given a bitmask, this member function counts the number of zero bits up to the least significant set bit. So, for a binary number 00000100, the member function returns 2 (decimal). The member function does, however, work on DWORD values, so it counts from the least significant bit up through the DWORD to the last bit (0x80000000). If no bits are found, this will return the (impossible) value 32 (decimal).

This is a protected member function.

CImageDisplay::CountSetBits

CImageDisplay Class

Counts the number of bit sets in the Field parameter.

DWORD CountSetBits(
const DWORD Field
);

Parameters
Field
Field in which to count bit sets.
Return Values

Returns the number of bit sets.

Remarks

This is a protected member function.

CImageDisplay::GetBitMasks

CImageDisplay Class

Retrieves a set of color element bitmasks for the supplied VIDEOINFOHEADER structure.

const DWORD *GetBitMasks(
const VIDEOINFO *pVideoInfo
);

Parameters
pVideoInfo
Input VIDEOINFOHEADER structure format.
Return Values

No return value.

Remarks

This member function should be called only with RGB formats. If the RGB format has a bit depth of 16/32 bits per pixel, it will return the bitmasks for the individual red, green, and blue color elements (for example, RGB565 is 0xF800, 0x07E0, and 0x001F). For RGB24, this will return 0xFF0000, 0xFF00, and 0xFF. For palettized formats, this will return all zeros.

CImageDisplay::GetColourMask

CImageDisplay Class

Retrieves a set of individual color element masks.

BOOL GetColourMask(
DWORD *pMaskRed,
DWORD *pMaskGreen,
DWORD *pMaskBlue
);

Parameters
pMaskRed
Holds red mask.
pMaskGreen
Holds green mask.
pMaskBlue
Holds blue mask.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Masks were filled out correctly.
FALSE | No masks were available for the display.

Remarks

Given a video format described by a VIDEOINFOHEADER structure, this member function returns the mask that is used to obtain the range of acceptable colors for this type (for example, the mask for a 24-bit true color format is 0xFF in all cases). A 16-bit 5:6:5 display format uses 0xF8, 0xFC, and 0xF8. Therefore, given any RGB triplets, this member function can find one that is compatible with the display format by using a bitwise-AND operation.

CImageDisplay::GetDisplayDepth

CImageDisplay Class

Retrieves the bit depth of the current display mode.

WORD GetDisplayDepth( );

Return Values

Returns the number of bits per pixel used on the display.

CImageDisplay::GetDisplayFormat

CImageDisplay Class

Retrieves a VIDEOINFOHEADER structure representing the current display mode.

const VIDEOINFO *GetDisplayFormat( );

Return Values

Returns a VIDEOINFOHEADER structure representing the display format.

CImageDisplay::IsPalettized

CImageDisplay Class

Determines if the display uses a palette.

BOOL IsPalettized( );

Return Values

Returns TRUE if the display uses a palette; otherwise, returns FALSE.

CImageDisplay::RefreshDisplayType

CImageDisplay Class

Updates the CImageDisplay object with the current display type.

HRESULT RefreshDisplayType(
LPSTR szDeviceName
);

Parameters
szDeviceName
LPSTR value that contains the name of the device to update. If omitted, this parameter defaults to the main device.
Return Values

Returns NOERROR if successful; E_FAIL if unsuccessful.

Remarks

This member function should be called when a WM_DISPLAYCHANGED message is received.

CImageDisplay::UpdateFormat

CImageDisplay Class

Updates the VIDEOINFOHEADER structure to remove implicit assumptions.

HRESULT UpdateFormat(
VIDEOINFO *pVideoInfo
);

Parameters
pVideoInfo
VIDEOINFOHEADER structure to update.
Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

This member function is probably suitable only for specific filters to use. The BITMAPINFO structure has certain fields that are not well specified. In particular, the number of colors specified for a palette can be zero, in which case it is defined to be the maximum for that format type. This member function updates these fields so that their contents are explicit.


CImagePalette Class

CImagePalette class hierarchy

The CImagePalette class is a specialized class for image renderers that must create and manage palettes. It can be used to create palette handles from a media format containing a VIDEOINFO structure in the format block. To maximize performance, the class attempts to create a palette that is an identity palette (that is, one that exactly matches the current system palette), and compares palettes before updating to ensure that palettes are changed only when actually required.

Protected Data Members
Name | Description
m_hPalette | Palette handle owned by this object.
m_pBaseWindow | Window in which to realize the palette.
m_pDrawImage | Object that will perform the drawing.
m_pMediaFilter | Media filter to send events to.

Member Functions
Name | Description
CImagePalette | Constructs a CImagePalette object.
CopyPalette | Copies the palette out of any YUV or true-color VIDEOINFOHEADER structure into a palettized VIDEOINFOHEADER structure.
MakeIdentityPalette | Ensures the palette entries will become an identity palette.
MakePalette | Retrieves the color palette from the specified video image.
PreparePalette | Specifies an entry point for updating and creating palettes.
RemovePalette | Releases any palette resources allocated.
ShouldUpdate | Specifies an internal helper member function for updating palettes dynamically.

CImagePalette::CImagePalette

CImagePalette Class

Constructs a CImagePalette object.

CImagePalette(
CBaseFilter *pBaseFilter,
CBaseWindow *pBaseWindow,
CDrawImage *pDrawImage
);

Parameters
pBaseFilter
Filter that this class is owned by.
pBaseWindow
Window to realize palette in.
pDrawImage
Object that draws using this palette.
Return Values

No return value.

Remarks

This class looks after the creation, management, and deletion of a window palette. It is passed in a number of other objects that might be interested in palettes. The class is optimized so that requested palette changes will be acted on only if the new set of colors differs from the current set. This is a performance optimization, because changing palettes is an expensive process.

This constructor is passed in the owning filter (pBaseFilter), which must be a valid pointer. When the class actually creates a palette, it tells the owning filter to send an EC_PALETTE_CHANGED message to the filter graph manager. The constructor might also be passed two further object pointers. If pBaseWindow is not null, when the renderer creates a new palette the class automatically installs it in this window. When told to remove a palette, the class also removes the palette from the base window and installs a standard VGA palette instead.

The constructor can also be passed a drawing object derived from the CDrawImage class. If this is non-NULL, when creating a new palette the class will inform the drawing object that the palette has changed (this is usually used in conjunction with a window object). This ensures that the drawing object is notified when the palette changes so that it can update any samples it has that were created using CreateDIBSection (because they might need their internal color tables updated).

CImagePalette::CopyPalette

CImagePalette Class

Copies the palette out of any YUV or true-color VIDEOINFOHEADER structure into a palettized VIDEOINFOHEADER structure.

HRESULT CopyPalette(
const CMediaType *pSrc,
const CMediaType *pDest
);

Parameters
pSrc
Source media type.
pDest
Destination media type.
Return Values

Returns NOERROR if successful or S_FALSE if no palette is available.

Remarks

This member function is used when changing palettes on DirectDraw® samples. A filter acting as a source to the renderer can attach a palette to any buffer and pass it to the renderer as a new VIDEOINFOHEADER format. The renderer can then call CopyPalette to make a new palette from that format, and copy the palette colors into the new connection type.

CImagePalette::MakeIdentityPalette

CImagePalette Class

Modifies the PALETTEENTRY structure to create an identity palette.

HRESULT MakeIdentityPalette(
PALETTEENTRY *pEntry,
INT iColours,
LPSTR szDevice
);

Parameters
pEntry
Array of prospective palette colors.
iColours
Number of colors in the array.
szDevice
LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.
Return Values

Returns NOERROR if successful or S_FALSE if unsuccessful.

Remarks

When a palette is installed in a window, GDI does a fair job of compressing the requested colors where possible. So, for example, if the array contains five entries of black, they will be compressed into one palette entry. This is useful for most applications; however, when drawing video it will force GDI to map the pixels in the supplied image to the compressed palette (which results in serious performance penalties).

Therefore, the PALETTEENTRY fields supplied must be adjusted so that they will never have colors compressed. This means that when the window displaying the image has the foreground focus, the palette created by this object will map directly to the palette selected in the display device: a so-called identity palette.

CImagePalette::MakePalette

CImagePalette Class

Retrieves the color palette from the specified video image.

HPALETTE MakePalette(
const VIDEOINFOHEADER *pVideoInfo,
LPSTR szDevice
);

Parameters
pVideoInfo
Container for the palette colors required.
szDevice
LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.
Return Values

Returns a handle to the new palette (NULL if it fails).

CImagePalette::PreparePalette

CImagePalette Class

Specifies an entry point for creating and installing palettes.

HRESULT PreparePalette(
const CMediaType *pmtNew,
const CMediaType *pmtOld,
LPSTR szDevice
);

Parameters
pmtNew
Media type holding new palette information.
pmtOld
Media type holding old palette information.
szDevice
LPSTR value that contains the name of the destination device. If omitted, this parameter defaults to the main device.
Return Values

Returns an HRESULT value.

Remarks

This is the main entry point for creating new palettes. It tries to detect situations where the palette colors requested have not changed (in which case it does not need to create a new palette). It uses the old media type to determine if the colors have changed. It also handles optionally installing the palette in a window (if supplied) and notifying the filter graph manager of a change in palettes (it uses the filter passed in to the constructor for this). Finally, it handles notifying the draw object of palette changes (also optional, depending on whether a draw object was passed in to the constructor).

CImagePalette::RemovePalette

CImagePalette Class

Removes and deletes any palette previously created.

HRESULT RemovePalette( );

Return Values

Returns an HRESULT value. Current implementation returns NOERROR.

CImagePalette::ShouldUpdate

CImagePalette Class

Help member function that checks if two sets of colors match.

BOOL ShouldUpdate(
const VIDEOINFOHEADER *pNewInfo,
const VIDEOINFOHEADER *pOldInfo
);

Parameters
pNewInfo
VIDEOINFOHEADER structure containing the new set of colors.
pOldInfo
VIDEOINFOHEADER structure containing the old set of colors.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | A new palette is required.
FALSE | The existing palette suffices.


CImageSample Class

CImageSample class hierarchy

This class inherits from CMediaSample and overrides the constructor to initialize itself with the DIBDATA structure. When the renderer is using its own allocator, it will use this class for its samples. It can therefore obtain the DIBSECTION structure information it requires to obtain the HBITMAP data it renders.

Protected Data Members
Name | Description
m_bInit | Flag to determine if the DIBSECTION structure information is initialized.
m_DibData | Information about the sample's DIBSECTION structure.

Member Functions
Name | Description
CImageSample | Constructs a CImageSample object.
GetDIBData | Retrieves the DIBSECTION structure information stored for the sample.
SetDIBData | Sets the DIBSECTION information stored for the sample.

CImageSample::CImageSample

CImageSample Class

Constructs a CImageSample object.

CImageSample(
CBaseAllocator *pAllocator,
TCHAR *pName,
HRESULT *phr,
LPBYTE pBuffer,
LONG length
);

Parameters
pAllocator
Base allocator to which the sample belongs.
pName
Debug-only string description.
phr
COM return code.
pBuffer
Pointer to the image buffer.
length
Length of the image buffer.
Return Values

No return value.

Remarks

The CImageAllocator, CImageSample, and CDrawImage classes are all tightly associated. The buffers that the image allocator creates are made by using the Microsoft® Win32® CreateDIBSection function. The allocator then creates its own samples (based on the CImageSample class). The image samples are initialized with the buffer pointer and its length. The sample is also passed in a structure (a DIBDATA structure) that holds a number of pieces of information obtained from the CreateDIBSection call.

These samples can then be passed to the draw object. The draw object knows the private format of the samples and how to get back the DIBDATA structure from them. Once it has obtained that information, it can pass a bitmap handle, which is stored in the DIBDATA structure, down into GDI when it draws the image that the sample contains. By using the bitmap handle from the sample in the drawing, rather than just the buffer pointer (which is the alternative if the sample is not a CImageSample), it achieves a modest performance improvement.

CImageSample::GetDIBData

CImageSample Class

Retrieves the DIBDATA structure held by the sample.

DIBDATA *GetDIBData( );

CImageSample::SetDIBData

CImageSample Class

Sets the DIBDATA structure that the sample should hold.

void SetDIBData(
DIBDATA *pDibData
);

Parameters
pDibData
New DIBDATA structure.
Return Values

No return value.


CLoadDirectDraw Class

CLoadDirectDraw class hierarchy

DirectShow™ must work on multiple platforms; in particular, it also runs on Microsoft® Windows NT® 3.51, which does not have DirectDraw® capabilities. The filters therefore cannot link statically to the DirectDraw library. To make the platform dependencies easier to handle, this class manages loading and unloading the library and creating the initial IDirectDraw interface.

Member Functions
Name | Description
CLoadDirectDraw | Constructs a CLoadDirectDraw object.
GetDirectDraw | Retrieves a pointer to the IDirectDraw interface.
IsDirectDrawLoaded | Verifies that DirectDraw is loaded.
IsDirectDrawVersion1 | Checks the version of DirectDraw installed on the current system.
LoadDirectDraw | Loads and initializes the DirectDraw library.
ReleaseDirectDraw | Releases the IDirectDraw interface.

CLoadDirectDraw::CLoadDirectDraw

CLoadDirectDraw Class

Constructs a CLoadDirectDraw object.

CLoadDirectDraw(void);

Return Values

No return value.

CLoadDirectDraw::GetDirectDraw

CLoadDirectDraw Class

Retrieves the DirectDraw interface.

LPDIRECTDRAW GetDirectDraw(void);

Return Values

Returns a pointer to the IDirectDraw interface.

Remarks

Call CLoadDirectDraw::LoadDirectDraw before calling this member function and call the CLoadDirectDraw::ReleaseDirectDraw member function to release the interface when you are done.

CLoadDirectDraw::IsDirectDrawLoaded

CLoadDirectDraw Class

Verifies that this object loaded DirectDraw.

HRESULT IsDirectDrawLoaded(void);

Return Values

Returns S_OK if loaded; otherwise, returns S_FALSE.

CLoadDirectDraw::IsDirectDrawVersion1

CLoadDirectDraw Class

Checks the version of DirectDraw installed on the current system.

BOOL IsDirectDrawVersion1(void);

Return Values

Returns TRUE if the installed version of DirectDraw doesn't support the IDirectDraw2 interface, or FALSE if the m_pDirectDraw data member is NULL or the installed version of DirectDraw supports IDirectDraw2.

Remarks

The video renderer must know what the installed version of DirectDraw is to perform certain tasks, such as full-screen playback, which the IDirectDraw2 interface supports.

CLoadDirectDraw::LoadDirectDraw

CLoadDirectDraw Class

Loads and initializes the DirectDraw library in the specified area.

HRESULT LoadDirectDraw(
LPSTR szDevice
);

Parameters
szDevice
This parameter is optional; if omitted, this method loads DirectDraw to the base drawing area.
Return Values

Returns S_OK if DirectDraw loaded correctly or E_NOINTERFACE otherwise.

Remarks

DirectDraw is not always available, so applications can't statically link to the library. Therefore, this member function loads the library, gets the function entry point addresses, and calls them to create the driver objects. Call this member function before calling CLoadDirectDraw::GetDirectDraw to retrieve the IDirectDraw interface.

CLoadDirectDraw::ReleaseDirectDraw

CLoadDirectDraw Class

Releases the IDirectDraw interface.

void ReleaseDirectDraw(void);

Return Values

No return value.

Remarks

This member function is called to release any IDirectDraw interface previously loaded. Call this only when all reference counts have been released.


CMediaControl Class

CMediaControl class hierarchy

The CMediaControl class provides base class handling of the IDispatch methods of the dual-interface IMediaControl. It leaves as pure virtual the properties and methods of the IMediaControl interface.

Typically, the filter graph manager is the only object that implements the IMediaControl interface. (Filters implement the IMediaFilter interface, inherited by IBaseFilter, to receive control commands from the filter graph manager.) Therefore, this class library is of limited use to filter developers.

The CMediaControl::GetIDsOfNames, CMediaControl::GetTypeInfo, CMediaControl::GetTypeInfoCount, and CMediaControl::Invoke member functions are standard implementations of the IDispatch methods using the CBaseDispatch class (and a type library) to parse the commands and pass them to the pure virtual methods of the IMediaControl interface.

The IMediaControl methods, defined in control.odl, are left as pure virtual.

Member Functions
Name | Description
CMediaControl | Constructs a CMediaControl object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers (DISPIDs), which can be used during subsequent calls to the CMediaControl::Invoke method.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CMediaControl::CMediaControl

CMediaControl Class

Constructs a CMediaControl object.

CMediaControl(
const TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CMediaControl::GetIDsOfNames

CMediaControl Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers (DISPIDs), which can be used upon subsequent calls to the CMediaControl::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
E_OUTOFMEMORY | Out of memory.
S_OK | Success.

CMediaControl::GetTypeInfo

CMediaControl Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK or NOERROR | Success.

CMediaControl::GetTypeInfoCount

CMediaControl Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CMediaControl::Invoke

CMediaControl Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CMediaControl::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CMediaControl::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CMediaControl::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CMediaControl::NonDelegatingQueryInterface

CMediaControl Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IMediaControl and IUnknown interfaces by default. Override this member function to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.


CMediaEvent Class

CMediaEvent class hierarchy

The CMediaEvent class provides base class implementation of the IDispatch methods of the dual-interface IMediaEvent. It leaves as pure virtual the properties and methods of the IMediaEvent interface.

The CMediaEvent class also provides base class implementation of the IMediaEventEx interface which derives from IMediaEvent.

The CMediaEvent::GetIDsOfNames, CMediaEvent::GetTypeInfo, CMediaEvent::GetTypeInfoCount, and CMediaEvent::Invoke member functions are standard implementations of the IDispatch interface using the CBaseDispatch class (and a type library) to parse the commands and pass them to the pure virtual methods of the IMediaEvent interface.

Member Functions
Name | Description
CMediaEvent | Constructs a CMediaEvent object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used during subsequent calls to the IDispatch::Invoke method.
GetTypeInfo | Retrieves a type-information object, which retrieves the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CMediaEvent::CMediaEvent

CMediaEvent Class

Constructs a CMediaEvent object.

CMediaEvent(
const TCHAR * pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CMediaEvent::GetIDsOfNames

CMediaEvent Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the CMediaEvent::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
E_OUTOFMEMORY | Out of memory.
S_OK | Success.

CMediaEvent::GetTypeInfo

CMediaEvent Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK or NOERROR | Success.

CMediaEvent::GetTypeInfoCount

CMediaEvent Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CMediaEvent::Invoke

CMediaEvent Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CMediaEvent::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CMediaEvent::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for the number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CMediaEvent::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CMediaEvent::NonDelegatingQueryInterface

CMediaEvent Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns a pointer to the IMediaEvent and IUnknown interfaces by default. Override this member function to publish any additional interfaces added by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.


CMediaPosition Class

CMediaPosition class hierarchy

The CMediaPosition class is a base class that handles the IDispatch methods of the dual-interface IMediaPosition. It leaves the properties and methods as pure virtual.

The CMediaPosition::GetIDsOfNames, CMediaPosition::GetTypeInfo, CMediaPosition::GetTypeInfoCount, and CMediaPosition::Invoke methods are standard implementations of the IDispatch interface using the CBaseDispatch class (and a type library) to parse the commands and pass them to the pure virtual IMediaPosition methods.

Member Functions
Name | Description
CMediaPosition | Constructs a CMediaPosition object.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

Implemented IDispatch Methods
Name | Description
GetIDsOfNames | Maps a single member and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used during subsequent calls to the CMediaPosition::Invoke member function.
GetTypeInfo | Retrieves a type-information object, which can retrieve the type information for an interface.
GetTypeInfoCount | Retrieves the number of type-information interfaces provided by an object.
Invoke | Provides access to properties and methods exposed by an object.

CMediaPosition::CMediaPosition

CMediaPosition Class

Constructs a CMediaPosition object.

CMediaPosition(
const TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object used in the CMediaPosition constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debug terminal upon creation and deletion of the object.

CMediaPosition::GetIDsOfNames

CMediaPosition Class

Maps a single member function and an optional set of parameters to a corresponding set of integer dispatch identifiers, which can be used upon subsequent calls to the CMediaPosition::Invoke member function.

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR ** rgszNames,
UINT cNames,
LCID lcid,
DISPID * rgdispid
);

Parameters
riid
Reference identifier. Reserved for future use. Must be NULL.
rgszNames
Passed-in array of names to be mapped.
cNames
Count of the names to be mapped.
lcid
Locale context in which to interpret the names.
rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.
Return Values

Returns one of the following values.
Value | Meaning
DISP_E_UNKNOWN_CLSID | The CLSID was not recognized.
DISP_E_UNKNOWNNAME | One or more of the names were not known. The returned DISPIDs contain DISPID_UNKNOWN for each entry that corresponds to an unknown name.
E_OUTOFMEMORY | Out of memory.
S_OK | Success.

CMediaPosition::GetTypeInfo

CMediaPosition Class

Retrieves a type-information object, which can retrieve the type information for an interface.

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo ** pptinfo
);

Parameters
itinfo
Type information to return. Pass zero to retrieve type information for the IDispatch implementation.
lcid
Locale ID for the type information. An object might be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
pptinfo
Pointer to the type-information object requested.
Return Values

Returns an E_POINTER if pptinfo is invalid. Returns TYPE_E_ELEMENTNOTFOUND if itinfo is not zero. Returns S_OK if is successful. Otherwise, returns an HRESULT from one of the calls to retrieve the type. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK or NOERROR | Success.

CMediaPosition::GetTypeInfoCount

CMediaPosition Class

Retrieves the number of type-information interfaces provided by an object.

HRESULT GetTypeInfoCount(
UINT * pctinfo
);

Parameters
pctinfo
Pointer to the location that receives the number of type-information interfaces that the object provides. If the object provides type information, this number is 1; otherwise, the number is 0.
Return Values

Returns E_POINTER if pctinfo is invalid; otherwise, returns S_OK.

CMediaPosition::Invoke

CMediaPosition Class

Provides access to properties and methods exposed by an object.

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS * pdispparams,
VARIANT * pvarResult,
EXCEPINFO * pexcepinfo,
UINT * puArgErr
);

Parameters
dispidMember
Identifier of the member. Use CMediaPosition::GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
Locale context in which to interpret arguments.
wFlags
Flags describing the context of the CMediaPosition::Invoke call.
pdispparams
Pointer to a structure containing an array of arguments, an array of argument dispatch IDs for named arguments, and counts for the number of elements in the arrays.
pvarResult
Pointer to where the result is to be stored, or NULL if the caller expects no result.
pexcepinfo
Pointer to a structure containing exception information.
puArgErr
Index of the first argument, within the rgvarg array, that has an error.
Return Values

Returns DISP_E_UNKNOWNINTERFACE if riid is not IID_NULL. Returns one of the error codes from CMediaPosition::GetTypeInfo if the call fails. Otherwise, returns the HRESULT from the call to IDispatch::Invoke.

CMediaPosition::NonDelegatingQueryInterface

CMediaPosition Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns a pointer to IMediaPosition and IUnknown interfaces by default. Override this member function to publish any additional interfaces implemented by the derived class.


CMediaSample Class

CMediaSample class hierarchy

This class represents a buffer object that supports the IMediaSample interface. It represents a buffer in memory, together with some associated properties stored as protected data members.

The constructor is passed as a pointer to the buffer with its length in bytes; other properties are normally set and accessed through implemented IMediaSample interface methods. These properties describe various attributes of the media sample, such as the sample's media type, start and end time, and options. The options can include whether the media sample is a sync point, a preroll sample, or discontinuous with other samples.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members
Name | Description
m_cbBuffer | Size of the buffer.
m_dwFlags | Sample property flags as follows:
Sample_Discontinuity: Set if start of a new segment.
Sample_MediaTimeValid: Set if the media time is valid.
Sample_Preroll: Set if sample is a preroll sample.
Sample_StopValid: Set if the stop time is valid.
Sample_SyncPoint: Set if sample is a synchronization point.
Sample_TimeValid: Set if the time is valid.
Sample_TypeChanged: Set if the type has changed.
m_End | Sample end time.
m_lActual | Actual length of data in this sample.
m_MediaEnd | Media end (offset from m_MediaStart).
m_MediaStart | Media start position.
m_pAllocator | Pointer to the IMemAllocator object associated with this object.
m_pBuffer | Pointer to the complete buffer.
m_pMediaType | Pointer to a structure containing the media type of the sample.
m_pNext | Pointer to the next CMediaSample object in the free list.
m_Start | Sample start time.

Member Functions
Name | Description
CMediaSample | Constructs a CMediaSample object.
SetPointer | Sets the buffer pointer and length.

Implemented IUnknown Methods
Name | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Implemented IMediaSample Methods
Name | Description
GetActualDataLength | Retrieves the data length of the sample.
GetMediaTime | Retrieves the media time extents of the sample.
GetMediaType | Retrieves the media type of the CMediaSample object.
GetPointer | Retrieves a read/write pointer to the memory of this buffer.
GetSize | Returns the size, in bytes, of the buffer data area.
GetTime | Sets the media time extents for this sample.
IsDiscontinuity | Determines if there is discontinuity in the data stream.
IsPreroll | Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
IsSyncPoint | Determines if the beginning of a sample is a synchronization point.
SetActualDataLength | Sets the data length of the sample.
SetDiscontinuity | Sets the discontinuity property.
SetMediaTime | Sets the media time of the CMediaSample object.
SetMediaType | Sets the media type of the CMediaSample object.
SetPreroll | Sets preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetSyncPoint | Sets sync-point property.
SetTime | Sets the stream time at which this sample should start and finish.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Passes out pointers to any interfaces added to the derived filter class.

CMediaSample::AddRef

CMediaSample Class

Increments the reference count for the calling interface on an object.

ULONG AddRef(void);

Return Values

Returns an integer from 1 to n, the value of the new reference count.

Remarks

This member function implements the IUnknown::AddRef method.

CMediaSample::CMediaSample

CMediaSample Class

Constructs a CMediaSample object.

CMediaSample(
TCHAR *pName,
CBaseAllocator *pAllocator,
HRESULT *phr,
LPBYTE pBuffer = NULL,
LONG length = 0
);

Parameters
pName
Name of the media sample.
pAllocator
Pointer to the CBaseAllocator object used for memory allocation.
phr
Pointer to the general COM return value. Note that this value is changed only if this function fails.
pBuffer
Pointer to a memory buffer (to be allocated by the pAllocator parameter).
length
Length of the allocated memory buffer.
Return Values

No return value.

Remarks

The constructor creates an object with the buffer and buffer length set to that of the CBaseAllocator object to which it points.

CMediaSample::GetActualDataLength

CMediaSample Class

Retrieves the data length of the sample.

HRESULT GetActualDataLength(void);

Return Values

Returns the value of m_lActual by default.

Remarks

This member function implements the IMediaSample::GetActualDataLength method.

CMediaSample::GetMediaTime

CMediaSample Class

Retrieves the starting and ending media time.

HRESULT GetMediaTime(
LONGLONG * pStart,
LONGLONG * pEnd
);

Parameters
pStart
Retrieved beginning media time.
pEnd
Retrieved ending media time.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::GetMediaTime method. It sets pStart to the current value of m_MediaStart and pEnd to the sum of m_MediaStart and m_MediaEnd. If the sample has not been set, this member function returns VFW_E_MEDIA_TIME_NOT_SET.

CMediaSample::GetMediaType

CMediaSample Class

Retrieves the media type of the CMediaSample object.

HRESULT GetMediaType(
AM_MEDIA_TYPE ** ppMediaType
);

Parameters
ppMediaType
Pointer to a pointer to the retrieved media type.
Return Values

Returns an HRESULT value. When a sample is received and there is no format change, this method returns S_FALSE.

Remarks

This member function implements the IMediaSample::GetMediaType method. The member function makes a copy of the AM_MEDIA_TYPE structure and creates a task memory block to maintain the reference. When you are done with the media type, free the memory block with the FreeMediaType utility function, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.

CMediaSample::GetPointer

CMediaSample Class

Retrieves a read/write pointer to the buffer's memory.

HRESULT GetPointer(
BYTE ** ppBuffer
);

Parameters
ppBuffer
Retrieved pointer to the buffer.
Return Values

Returns VFW_E_BUFFER_NOTSET if CMediaSample::SetPointer was not called before calling this function, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetPointer method. GetPointer returns the value of m_pBuffer, set using CMediaSample::SetPointer.

CMediaSample::GetSize

CMediaSample Class

Retrieves the size, in bytes, of the buffer data area.

HRESULT GetSize(void);

Return Values

Returns the value of m_cbBuffer by default.

Remarks

This member function implements the IMediaSample::GetSize method.

CMediaSample::GetTime

CMediaSample Class

Retrieves the stream time at which this sample should begin and finish.

HRESULT GetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);

Parameters
pTimeStart
Retrieved beginning stream time.
pTimeEnd
Retrieved ending stream time.
Return Values

Returns VFW_E_SAMPLE_TIME_NOT_SET if this sample doesn't have valid timestamps, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetTime method. It sets pTimeStart to the current value of m_Start and pTimeEnd to the current value of m_End.

CMediaSample::IsDiscontinuity

CMediaSample Class

Determines if there is discontinuity in the data stream.

HRESULT IsDiscontinuity(void);

Return Values

Returns S_OK if the sample is a discontinuous sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsDiscontinuity method. It returns the value of the m_dwFlags Sample_Discontinuity property flag. Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.

CMediaSample::IsPreroll

CMediaSample Class

Preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT IsPreroll(void);

Return Values

Returns S_OK if the sample is a preroll sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsPreroll method. It returns the value of the m_dwFlags Sample_Preroll property flag. Preroll samples are not meant to be rendered.

CMediaSample::IsSyncPoint

CMediaSample Class

Determines if the beginning of a sample is a synchronization point.

HRESULT IsSyncPoint(void);

Return Values

Returns S_OK if the sample is a synchronization point and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsSyncPoint method. It returns the value of the m_dwFlags Sample_SyncPoint property flag. If the bTemporalCompression member of the AM_MEDIA_TYPE structure is FALSE, all samples are synchronization points. A filter can begin a stream at any synchronization point.

CMediaSample::NonDelegatingQueryInterface

CMediaSample Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMediaSample and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CMediaSample::QueryInterface

CMediaSample Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);

Parameters
iid
Specifies the IID of the interface being requested.
ppvObject
Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.
Return Values

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method.

CMediaSample::Release

CMediaSample Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

ULONG Release(void);

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

CMediaSample::SetActualDataLength

CMediaSample Class

Sets the data length of the sample.

HRESULT SetActualDataLength(
long lLen
);

Parameters
lLen
Length of the data in the media sample, in bytes.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetActualDataLength method. It sets the value of m_lActual to the value of lLen.

CMediaSample::SetDiscontinuity

CMediaSample Class

Sets the discontinuity property.

HRESULT SetDiscontinuity(
BOOL bDiscont
);

Parameters
bDiscont
Set to TRUE to specify the media sample as discontinuous with the previous sample.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetDiscontinuity method. It sets the value of the m_dwFlags Sample_Discontinuity flag to the value of bDiscont. Discontinuous samples occur when a source filter seeks to a different place in the media stream or when a filter drops samples for quality control.

CMediaSample::SetMediaTime

CMediaSample Class

Sets the starting and ending media times.

HRESULT SetMediaTime(
LONGLONG * pStart,
LONGLONG * pEnd
);

Parameters
pStart
Beginning media time.
pEnd
Ending media time.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaTime method. It sets the m_MediaStart data member to the value of pStart and the m_MediaEnd data member to the value of pEnd minus pStart.

CMediaSample::SetMediaType

CMediaSample Class

Sets the media type for the CMediaSample object.

HRESULT SetMediaType(
AM_MEDIA_TYPE * pMediaType
);

Parameters
pMediaType
Pointer to a pointer to a media type structure to be set.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaType method. It deletes the previous media type if one exists, makes a copy of the media type passed in, sets m_pMediaType to the copy of the media type, and sets the value of the m_dwFlags Sample_TypeChanged flag to TRUE.

CMediaSample::SetPointer

CMediaSample Class

Sets the buffer pointer and length.

SetPointer(
BYTE * ptr,
LONG cBytes
);

Parameters
ptr
Pointer to a buffer.
cBytes
Length of the buffer, in bytes.
Return Values

No return value.

Remarks

Allocators that require variable-sized pointers or pointers into data that has already been read use this member function. This is available only through a CMediaSample class, not an IMediaSample interface, so only the filter that owns the allocator knows how to access this member function (not any filter or pin that is passed the object's IMediaSample interface pointer).

CMediaSample::SetPreroll

CMediaSample Class

Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT SetPreroll(
BOOL bIsPreroll
);

Parameters
bIsPreroll
Set to TRUE to specify the media sample as a preroll sample, or FALSE otherwise.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetPreroll method. It sets the value of the m_dwFlags Sample_Preroll flag to the value of bIsPreroll. Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.

CMediaSample::SetSyncPoint

CMediaSample Class

Property of a synchronization point.

HRESULT SetSyncPoint(
BOOL bIsSyncPoint
);

Parameters
bIsSyncPoint
Value specifying whether the synchronization point was set.
Return Values

Returns S_OK.

Remarks

This member function implements the IMediaSample::SetSyncPoint method. It sets the value of the m_dwFlags Sample_SyncPoint flag to the value of bIsSyncPoint. A filter can begin a stream at any synchronization point.

CMediaSample::SetTime

CMediaSample Class

Sets the media time extents for this sample.

HRESULT SetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);

Parameters
pTimeStart
Stream time at which the sample begins.
pTimeEnd
Stream time at which the sample ends.
Return Values

Returns NOERROR or an HRESULT value.

Remarks

This member function implements the IMediaSample::SetTime method. It sets the m_Start data member to the value of pTimeStart and the m_End data member to the value of pTimeEnd.

If pTimeStart and pTimeEnd are null, DirectShow turns off the m_dwFlags data member's Sample_TimeValid and Sample_StopValid bits.


CMediaType Class

CMediaType class hierarchy

When filters are connected, they typically negotiate a type between them. This type describes the format of the data to be exchanged; if the filters do not agree on a media type, they cannot connect. Microsoft® DirectShow™ describes types through the media type structure, which contains two conceptual parts. The first is a list of members that describes generic attributes of a data stream. An example of this is a member that declares whether the data will be passed in fixed-size buffers. The second part of the structure is a variable-length block of data. How large the block of data should be and what it will contain depend on the type of data stream. For example, if the data stream is digital video, the format block is a VIDEOINFOHEADER structure. If, on the other hand, it is digital audio, the format block is a Microsoft Win32® WAVEFORMATEX structure.

A data stream type (for example, digital video) is set with a combination of two globally unique identifiers (GUIDs), called a major type and a subtype. The major type describes the overall class of data, examples of which might be digital video, digital audio, MIDI, or text captions. The subtype should supply a more specific description of the data type. In the case of digital video, for example, the subtype could be RGB8, RGB16, or RGB32 (among others). By having these two types in a generic structure (AM_MEDIA_TYPE), a component, such as a filter graph, can connect filters without any knowledge that is type specific.

The distinction between what goes in the major type and the subtype is somewhat arbitrary. However, as a general rule, transformations between major types (for example, video to audio or video to MIDI) should be relatively rare. Such a rare exception might be a transformation between audio and MIDI. As for the subtype, the more information promoted from the type-specific format block into the subtype, the better the design.

As an example of promoting type-specific information to the subtype, video in DirectShow uses a VIDEOINFOHEADER structure for the type-specific format block. This contains a Win32 BITMAPINFOHEADER structure that defines the video stream. BITMAPINFOHEADER contains the bit depth of the video, such as 8-bit, 16-bit, or 24-bit. This information is duplicated in the subtype field, because a subtype of RGB8 directly infers a bit count of 8.

DirectShow defines a number of major types. The most important of these are a video type that uses VIDEOINFOHEADER for the variable-length format block, and an audio that uses WAVEFORMATEX. However, it is insufficient to have a major type (such as digital video) inferring the contents of the format block (in this case, VIDEOINFOHEADER). The principal reason for this is extensibility: the format block type must be able to be updated without changing the less-specific major type. Therefore, what the format block actually contains is inferred by another GUID called the format type. If the format block contains VIDEOINFOHEADER, the format type GUID will be FORMAT_VideoInfo.

The principal use of the CMediaType class is to manage a media type structure in a simple way. At the same time, the class provides some extra helper functions (such as format-block copying and allocation). The class can be cast to an AM_MEDIA_TYPE structure when an interface method requires one to be passed to it.

The CMediaType class contains a pointer to a block of memory. When copying a CMediaType object, it is insufficient to simply copy the pointer. In C++, a data copy is required, which actually allocates a new block of memory and copies the data into it. This is the purpose of the copy operator.

Similarly, when comparing two CMediaType objects, you must compare the blocks of variable-length data (actually using memcmp) when producing the final result. To make this possible, CMediaType overrides the equivalence operator.

Member Functions
Name | Description
AllocFormatBuffer | Allocates an uninitialized format block in the object.
CMediaType | Constructs a CMediaType object.
Format | Returns the format block for this media type.
FormatLength | Returns the length of the format block of this object.
FormatType | Returns a pointer to the format type.
GetSampleSize | Returns the size of the samples.
InitMediaType | Initializes the media type.
IsFixedSize | Queries whether the samples are fixed in length.
IsPartiallySpecified | Checks if the media type is not completely specified.
IsTemporalCompressed | Queries whether the data stream is compressed temporally.
IsValid | Queries whether the media type is currently valid.
MatchesPartial | Checks whether this media type matches another media type that is only partially specified.
ReallocFormatBuffer | Reallocates the format block, maintaining its current content where possible.
ResetFormatBuffer | Deletes any format block that is currently present.
SetFormat | Sets the format block.
SetFormatType | Sets the type of the format block in the object.
SetSampleSize | Sets the size of the samples.
SetSubtype | Sets the subtype.
SetTemporalCompression | Marks the media type to indicate that samples will be temporally compressed.
SetType | Sets the major type.
SetVariableSize | Marks the media type to indicate that samples will vary in length.
Subtype | Returns a pointer to the subtype.
Type | Returns a pointer to the major type.

Operators
Name | Description
operator = | Performs a copy operation.
operator == | Tests for equality between CMediaType objects.
operator != | Tests for inequality between CMediaType objects.

CMediaType::AllocFormatBuffer

CMediaType Class

Allocates a block of memory for the format block.

BYTE* AllocFormatBuffer(
ULONG length
);

Parameters
length
Size required for the format block.
Return Values

Returns a pointer to the new block if successful; otherwise, returns NULL.

Remarks

Any previous format block is deleted and a new block is allocated and installed. The size required must be nonzero.

CMediaType::CMediaType

CMediaType Class

Constructs a CMediaType object.

CMediaType( );
CMediaType(
const GUID * majortype
);
CMediaType(
const AM_MEDIA_TYPE& mtype
);
CMediaType(
const CMediaType& cmtype
);

Parameters
majortype
Major type GUID.
mtype
AM_MEDIA_TYPE structure.
cmtype
CMediaType object from which this object is constructed.
Return Values

No return value.

Remarks

A CMediaType object can be constructed in a number of different ways. The class provides a default constructor that takes no parameters. It can also be constructed based on an AM_MEDIA_TYPE structure or another CMediaType object. In both cases, it takes a data copy of the format block before returning.

CMediaType::Format

CMediaType Class

Returns a pointer to the variable-length format block of the object.

BYTE* Format( ) const;

Return Values

Returns the format block of the object whose content is type-specific.

Remarks

If no format block has been allocated, it might return NULL.

CMediaType::FormatLength

CMediaType Class

Returns the size, in bytes, of the format block that the object contains.

ULONG FormatLength( ) const;

Return Values

Returns the length of the format block, or NULL if no format block is present.

CMediaType::FormatType

CMediaType Class

Retrieves the format type.

const GUID *FormatType( ) const;

Return Values

Returns a pointer to the format type.

Remarks

The format GUID describes the content of the variable-length format block. Examples of format types are FORMAT_VideoInfo and FORMAT_WaveFormatEx.

CMediaType::GetSampleSize

CMediaType Class

Returns the maximum sample size for the data stream.

ULONG GetSampleSize( ) const;

Return Values

Returns the maximum size of any sample to be sent, or zero to indicate that the sample size is variable.

CMediaType::InitMediaType

CMediaType Class

Initializes the sample.

void InitMediaType( );

Return Values

No return value.

Remarks

This member function clears memory, sets the fixed sample size property, and sets the sample size to 1.

CMediaType::IsFixedSize

CMediaType Class

Determines if the samples for the stream will be fixed or variable size.

BOOL IsFixedSize( ) const;

Return Values

Returns one of the following values.
Value | Meaning
TRUE | Samples will be fixed size.
FALSE | Samples will be variable length.

CMediaType::IsPartiallySpecified

CMediaType Class

Determines if the media type is only partially defined. This is the case if the major type or format type is GUID_NULL.

BOOL IsPartiallySpecified( ) const;

Return Values

Returns one of the following values.
Value | Meaning
TRUE | Media type is partially specified.
FALSE | Media type is completely specified.

Remarks

This function does not check the sub type.

CMediaType::IsTemporalCompressed

CMediaType Class

Asks if the stream will be compressed temporally.

BOOL IsTemporalCompressed( ) const;

Return Values

Returns one of the following values.
Value | Meaning
TRUE | Stream will have temporal compression.
FALSE | Stream will have no temporal compression.

Remarks

Some data streams, such as compressed video, have temporal dependencies between successive samples. Other data streams do not have temporal dependencies between their samples; that is, each sample can be treated as an independent unit; for example, MIDI.

CMediaType::IsValid

CMediaType Class

Queries whether the object has a valid major type.

BOOL IsValid( ) const;

Return Values

Returns one of the following values.
Value | Meaning
TRUE | CMediaType object has a valid major type.
FALSE | CMediaType object does not have a valid major type.

Remarks

When CMediaType objects are constructed, their GUIDs are initialized with GUID_NULL (unless they are constructed based on another AM_MEDIA_TYPE structure or CMediaType object). This member function is useful for discovering if the object has been correctly initialized.

CMediaType::MatchesPartial

CMediaType Class

Determines if this media type matches the media type pointed to by the ppartial parameter.

BOOL MatchesPartial(
const CMediaType *ppartial
) const;

Parameters
ppartial
Pointer to the media type to match.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Media types match for the parts that are defined.
FALSE | Media types do not match.

Remarks

The matching applies only for the parts of ppartial that are defined. That is, this only matches the major type, subtype, or format type of the media type if these are not defined as GUID_NULL.

CMediaType::ReallocFormatBuffer

CMediaType Class

Reallocates the format block to a new size.

BYTE* ReallocFormatBuffer(
ULONG length
);

Parameters
length
New size required for the format block.
Return Values

Returns a pointer to the new block if successful; otherwise, returns NULL.

Remarks

Any current format block will be copied into the newly allocated block up to its maximum size. Any excess will be lost when the new block is smaller than the old one. When the new block is larger, the excess is not filled with zeros.

The size required must be nonzero.

CMediaType::ResetFormatBuffer

CMediaType Class

Deletes any format block currently held, sets it to NULL, and sets the size of the format block to zero.

void ResetFormatBuffer( );

Return Values

No return value.

CMediaType::SetFormat

CMediaType Class

Sets the variable-length format block.

BOOL SetFormat(
BYTE *pFormat,
ULONG length
);

Parameters
pFormat
Block of memory containing type-specific information.
length
Overall length of the format block.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Format block was set.
FALSE | An error occurred; most likely there was no memory available.

Remarks

The function takes a copy of the format block and stores that internally.

CMediaType::SetFormatType

CMediaType Class

Sets the GUID that describes the content of the format block.

void SetFormatType(
const GUID * pformattype
);

Parameters
pformattype
GUID describing the format type.
Return Values

No return value.

Remarks

The format GUID describes what can be expected to be found in the variable-length format block. For example, if the format type is FORMAT_VideoInfo, the format block should contain a VIDEOINFOHEADER structure. The creator of this object is responsible for making them consistent.

CMediaType::SetSampleSize

CMediaType Class

Sets the maximum sample size for the data stream.

void SetSampleSize(
ULONG sz
);

Parameters
sz
Size of the sample.
Return Values

No return value.

Remarks

If the sample size passed is zero, the object is set so that the data stream will send variable-length samples (the CMediaType::GetSampleSize member function will return zero). Otherwise, it will set the maximum size of the sample to the size specified in the sz parameter.

CMediaType::SetSubtype

CMediaType Class

Sets the subtype for the object.

void SetSubtype(
const GUID * psubtype
);

Parameters
psubtype
GUID defining the subtype for the object.
Return Values

No return value.

CMediaType::SetTemporalCompression

CMediaType Class

Marks the media type so that the data stream it describes might or might not contain temporal compression (according to the input Boolean flag).

void SetTemporalCompression(
BOOL bCompressed
);

Parameters
bCompressed
TRUE to indicate that the stream will contain temporal compression; otherwise, FALSE.
Return Values

No return value.

CMediaType::SetType

CMediaType Class

Sets the major type for the object.

void SetType(
const GUID * ptype
);

Parameters
ptype
GUID defining the major type for the object.
Return Values

No return value.

CMediaType::SetVariableSize

CMediaType Class

Sets the media type to indicate that the data stream will send variable-length samples.

void SetVariableSize( );

Return Values

No return value.

Remarks

Subsequent calls to CMediaType::GetSampleSize will return zero.

CMediaType::Subtype

CMediaType Class

Retrieves the subtype.

const GUID *Type( ) const;

Return Values

Returns a pointer to the subtype.

Remarks

The subtype GUID gives finer detail within the major type of data represented by this media type.

CMediaType::Type

CMediaType Class

Retrieves the major type.

const GUID *Type( ) const;

Return Values

Returns a pointer to the major type.

Remarks

The major type GUID describes the class of data represented by this media type.

CMediaType::operator =

CMediaType Class

The CMediaType variation of this operator is the copy constructor for a CMediaType object.

The AM_MEDIA_TYPE variation of this operator is the copy constructor for an AM_MEDIA_TYPE object.

CMediaType& operator=(
const CMediaType& rt
);
CMediaType& operator=(
const AM_MEDIA_TYPE& mrt
);

Parameters
rt
Object to copy during the assignment operation.
mrt
Object to copy during the assignment operation.
Return Values

Returns a reference to this object after the operation.

Remarks

Because the CMediaType class inherits publicly from AM_MEDIA_TYPE, the compiler could generate the copy constructor for the AM_MEDIA_TYPE object itself. However, this could introduce some memory conflicts and leaks in the process because the structure contains a dynamically allocated block (which the AM_MEDIA_TYPE pbFormat member points to), which the compiler's copy constructor will not copy correctly.

CMediaType::operator ==

CMediaType Class

Tests for equality between CMediaType objects.

inline BOOL operator==(const CMediaType& rt) const;
Parameters
rt
CMediaType object corresponding to the right side of the operator.
Return Values

Returns TRUE if the CMediaType object tested is equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

CMediaType::operator !=

CMediaType Class

Tests for inequality between CMediaType objects.

BOOL operator!=(
const CMediaType& rt
) const;

Parameters
rt
CMediaType object corresponding to the right side of the operator.
Return Values

Returns TRUE if the CMediaType object tested is not equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.


CMemAllocator Class

CMemAllocator class hierarchy

This class provides support for IMemAllocator by using the new operator to allocate memory. Derived from CBaseAllocator, it overrides the CBaseAllocator::Alloc member function to allocate a single block of memory large enough to hold all the requested data areas, and then allocates (using the new operator) a CMediaSample object for each requested buffer pointing into the data area.

The CBaseInputPin and CBaseOutputPin classes instantiate CMemAllocator objects as the default allocator if no other suitable allocator is provided.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Member Functions
Name | Description
Alloc | Allocates memory for a media sample (overrides CBaseAllocator::Alloc).
CMemAllocator | Constructs a CMemAllocator object.
ReallyFree | Frees memory when called from the destructor (or from Alloc when reallocating for new size or count).

Overridable Member Functions
Name | Description
Free | Indicates an overridden CBaseAllocator::Free member function, called when a decommit operation is complete to free memory.

Implemented IMemAllocator Methods
Name | Description
CreateInstance | Creates new instances of CMemAllocator in the factory template.
SetProperties | Sets the number of media samples and the size of each.

CMemAllocator::Alloc

CMemAllocator Class

Allocates a media sample object.

HRESULT Alloc(void);

Return Values

Returns an HRESULT value.

Remarks

This member function instantiates CMediaSample objects, adds them to the m_lFree data members, and updates the m_lAllocated count. This member function is called from IMemAllocator::Commit when becoming active.

CMemAllocator::CMemAllocator

CMemAllocator Class

Constructs a CMemAllocator object.

CMemAllocator(
TCHAR * pName,
LPUNKNOWN lpUnk,
HRESULT * phr
);

Parameters
pName
Name of the allocator object.
lpUnk
Pointer to LPUNKNOWN.
phr
Pointer to the general COM return value. Note that this value is changed only if this function fails.
Return Values

No return value.

Remarks

This constructor is passed to CBaseAllocator::CBaseAllocator, which initializes the data members.

CMemAllocator::CreateInstance

CMemAllocator Class

Creates new instances of CMemAllocator in the factory template.

static CUnknown *CreateInstance(
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pUnk
Pointer to the IUnknown interface.
phr
Pointer to the HRESULT value into which to place resulting information.
Return Values

Returns the pUnkRet parameter, which is a CUnknown class object.

CMemAllocator::Free

CMemAllocator Class

Frees memory for a media sample object.

HRESULT Free(void);

Return Values

No return value.

Remarks

This member function overrides the pure virtual CBaseAllocator::Free member function called when a decommit operation has completed. Memory is actually freed in ReallyFree, which is called from the destructor, so this function is not used in this class.

CMemAllocator::ReallyFree

CMemAllocator Class

Releases all media samples in the free list.

void ReallyFree (void);

Return Values

No return value.

Remarks

The CMemAllocator class holds memory until the object is actually deleted. This member function can be overridden to handle freeing media samples when a decommit occurs.

This member function is protected.

CMemAllocator::SetProperties

CMemAllocator Class

Determines the size, number, and alignment of blocks.

HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);

Parameters
pRequest
Requested allocator properties.
pActual
Allocator properties actually set.
Return Values

Returns an HRESULT value.

Remarks

The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values it can provide for the request. This member function cannot be called unless the allocator has been decommitted using the IMemAllocator::Decommit method.

This member function replaces SetCountAndSize in previous releases.


CMsg Class

CMsg class hierarchy

The CMsgThread class provides support for a worker thread to which requests can be posted asynchronously instead of sent directly. The CAMThread class provides a worker thread to which single requests can be sent. Only one client can make a request at a time, and the client blocks until the worker thread has completed the request. By contrast, the CMsgThread class provides a worker thread to which any number of requests can be posted. The requests (in the form of a CMsg object) are queued and executed in order, asynchronously. No reply or return value is received.

Data Members
Name | Description
dwFlags | Flag parameter to the request code.
lpParam | Data required by the worker thread as parameter or return values. This data should not be stack-based, as it will be referenced some time after completing the queuing operation.
pEvent | Event object that a worker thread can signal to indicate the completion of the operation.
uMsg | Request code that is defined by the client of the thread class and understood by the overridden worker thread function.

Member Functions
Name | Description
CMsg | Constructs a CMsg object.

CMsg::CMsg

CMsg Class

Constructs a CMsg object.

CMsg(
UINT u,
DWORD dw,
LPVOID lp,
CAMEvent *pEvent
);

Parameters
u
Request code, defined by the client of the thread class and understood by the overridden worker thread function.
dw
Flag parameter to the request code.
lp
Data required by the worker thread as parameter or return values. This data should not be stack-based, as it will be referenced some time after completing the queuing operation.
pEvent
Event object that a worker thread can signal to indicate the completion of the operation.
Return Values

No return value.

Remarks

This member function contains a request for a CMsgThread worker thread to act on. All the parameters are passed to the worker thread function as parameters when this message gets processed. The meanings of the parameters are defined by the client function that calls the worker thread and the derived class that supplies the worker thread's execution function.


CMsgThread Class

CMsgThread class hierarchy

This class is a worker thread class that queues requests to the queuing thread for completion asynchronously. To use this class, derive your class from it and override the CMsgThread::ThreadMessageProc member function. The ThreadMessageProc member function carries out each request. Your client functions and the ThreadMessageProc member function must share a common definition of the parameters in the CMsg object.

A negotiated mechanism tells the worker thread to exit. Typically, this will be one value of the CMsg class's uMsg message code.

It is a good idea to send this message from the destructor of your derived class, and call the CMsgThread::WaitForThreadExit member function before completing the destruction of the derived class.

Protected Data Members
Name | Description
m_hSem | Indicates a handle used for signaling.
m_Lock | Protects access to lists.
m_lWaiting | Indicates waiting for a free thread.
m_ThreadQueue | Overrides the CMsgThread::GetThreadMsg member function and blocks on things other than this queue.

Member Functions
Name | Description
CMsgThread | Constructs a CMsgThread object.
CreateThread | Creates a thread.
GetThreadHandle | Returns the thread handle.
GetThreadID | Returns the identifier of the thread.
GetThreadPriority | Retrieves the current thread priority.
PutThreadMsg | Queues a request for execution by the worker thread.
ResumeThread | Continues the operation of the worker thread.
SetThreadPriority | Sets the priority of the thread to a new value.
SuspendThread | Suspends the operation of a running thread.
WaitForThreadExit | Blocks until the thread has exited after a call to the CMsgThread::SuspendThread member function.

Overridable Member Functions
Name | Description
GetThreadMsg | Retrieves a queued CMsg object containing a request.
OnThreadInit | Provides initialization on a thread.
ThreadMessageProc | Processes requests. This is a pure virtual member function.

CMsgThread::CMsgThread

CMsgThread Class

Constructs a CMsgThread object.

CMsgThread( );

Return Values

No return value.

Remarks

Constructing a message thread object does not automatically create the thread. You must call the CMsgThread::CreateThread member function to create the thread.

CMsgThread::CreateThread

CMsgThread Class

Creates a thread.

BOOL CreateThread( );

Return Values

Returns one of the following values.
Value | Meaning
TRUE | Thread was successfully created.
FALSE | Thread was not successfully created.

Remarks

The thread will loop, blocking until a request is queued (through the CMsgThread::PutThreadMsg member function) and then calling the CMsgThread::ThreadMessageProc member function with each message.

CMsgThread::GetThreadHandle

CMsgThread Class

Retrieves the handle to the thread in the CMsgThread object.

HANDLE GetThreadHandle( );

Return Values

Returns the thread handle.

Remarks

The thread handle can be passed to Microsoft® Win32® application programming interface (API) functions, such as WaitForMultipleObjects. The thread handle is signaled when the thread has exited.

CMsgThread::GetThreadID

CMsgThread Class

Retrieves the thread's identifier.

DWORD GetThreadID( );

Return Values

Returns the m_ThreadId private data member.

Remarks

This function returns the Microsoft Win32 identifier for the worker thread. You can call this member function on either the worker thread or a client thread.

CMsgThread::GetThreadMsg

CMsgThread Class

Retrieves a queued CMsg object containing a request.

void virtual GetThreadMsg(
CMsg *msg
);

Parameters
msg
Pointer to an allocated CMsg object.
Remarks

This member function is called from the worker thread's private ThreadProc function to retrieve the next member function. The msg parameter should point to an allocated CMsg object that will be filled with the parameters to the next request in the queue. If there are no queued requests, this member function blocks until the next request is queued (by a call to the CMsgThread::PutThreadMsg member function).

CMsgThread::GetThreadPriority

CMsgThread Class

Uses the Microsoft Win32 GetThreadPriority function to retrieve the priority of the current worker thread.

int GetThreadPriority( );

Return Values

Returns the thread priority as an integer.

CMsgThread::OnThreadInit

CMsgThread Class

Provides initialization on a thread.

virtual void OnThreadInit( );

Return Values

No return value.

Remarks

Override this function if you want to do your own specific initialization on thread startup.

CMsgThread::PutThreadMsg

CMsgThread Class

Queues a request for execution by the worker thread.

void PutThreadMsg(
UINT uMsg,
DWORD dwMsgFlags,
LPVOID lpMsgParam,
CAMEvent *pEvent = NULL
);

Parameters
uMsg
Request code.
dwMsgFlags
Optional flags parameter.
lpMsgParam
Optional pointer to a data block containing additional parameters or return values. Must be statically or heap-allocated and not automatic.
pEvent
Optional pointer to an event object to be signaled upon completion.
Return Values

No return value.

Remarks

This member function queues a request for execution by the worker thread. The parameters of this member function will be queued (in a CMsg object) and passed to the CMsgThread::ThreadMessageProc member function of the worker thread. This member function returns immediately after queuing the request and does not wait for the thread to fulfill the request. The CMsgThread::ThreadMessageProc member function of the derived class defines the four parameters.

This member function uses a multithread safe list, so multiple calls to this member function from different threads can be made safely.

CMsgThread::ResumeThread

CMsgThread Class

Uses the Microsoft Win32 ResumeThread function to continue the operation of the worker thread after a previous call to the CMsgThread::SuspendThread member function.

DWORD ResumeThread( );

Return Values

If the member function succeeds, the return value is the previous suspend count of the thread. If the member function fails, the return value is 0xFFFFFFFF. To obtain extended error information, call the Microsoft Win32 GetLastError function.

CMsgThread::SetThreadPriority

CMsgThread Class

Uses the Microsoft Win32 SetThreadPriority function to set the priority of the thread to a new value.

BOOL SetThreadPriority(
int nPriority
);

Parameters
nPriority
Priority of the thread.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | Priority was successfully set.
FALSE | Priority was not set.

Remarks

The client and the worker thread can call this member function.

CMsgThread::SuspendThread

CMsgThread Class

Uses the Microsoft Win32 SuspendThread function to suspend the operation of a running thread.

DWORD SuspendThread( );

Return Values

If the member function succeeds, the return value is the previous suspend count of the thread. If the member function fails, the return value is 0xFFFFFFFF. To obtain extended error information, call the Microsoft Win32 GetLastError function.

Remarks

The client thread calls this member function to suspend the operation of the worker thread. The worker thread remains suspended and will not execute until an additional call to the CMsgThread::ResumeThread member function is made.

CMsgThread::ThreadMessageProc

CMsgThread Class

Processes requests. This is a pure virtual member function.

virtual LRESULT ThreadMessageProc(
UINT uMsg,
DWORD dwFlags,
LPVOID lpParam,
CAMEvent *pEvent
);

Parameters
uMsg
Request code.
dwFlags
Optional flag parameter to request.
lpParam
Optional pointer to extra data or a return data block.
pEvent
Optional pointer to an event object.
Return Values

Any nonzero return causes the thread to exit. Returns zero unless an exit request has been processed recently.

Remarks

This pure virtual function must be overridden in your derived class. It will be called once for each request queued by a call to the CMsgThread::PutThreadMsg member function.

The member function defines the four parameters. Typically, use the uMsg parameter to indicate the request, and the other three parameters will be optional additional parameters. The calling application can supply a pointer to a CAMEvent object in the pEvent parameter if your application requires it. You must set this event after processing the event by using an expression such as:

pEvent->SetEvent

One request code must be set aside to tell the worker thread to exit. Upon receiving this request, return 1 from this member function. Return 0 if you do not want the worker thread to exit.

CMsgThread::WaitForThreadExit

CMsgThread Class

Blocks until the thread exits.

BOOL WaitForThreadExit(
LPDWORD lpdwExitCode
);

Parameters
lpdwExitCode
Exit code returned by the thread.
Return Values

Returns either TRUE or FALSE, the meaning of which is determined by the class supplying the overridden CMsgThread::ThreadMessageProc member function and the calling member function.

Remarks

Ensure that the worker thread has exited completely before completing the destruction of your derived class; otherwise, the thread might still execute after your dynamic-link library (DLL) has been unloaded from the address space of the process. Even if the only instruction left to exit is a single-return instruction, this would cause an exception. The only reliable way to ensure that the thread has exited is to signal the thread to exit (using a privately negotiated CMsg object sent to the CMsgThread::PutThreadMsg member function) and then call this member function. You should do this in the destructor for your derived class.


COARefTime Class

COARefTime class hierarchy

This class converts between the Automation-compatible REFTIME type and the REFERENCE_TIME type used within and between filters.

Time parameters within the control interfaces are represented as double values, containing a fractional number of seconds. Interfaces supported between and within filters use a 64-bit LONGLONG type containing the time in 100-nanosecond units. Filters use this class to convert between the two formats. It is derived from CRefTime and thus is a LONGLONG, but it can be constructed from and assigned double values.

Member Functions
Name | Description
COARefTime | Constructs a COARefTime object.

Operators
Name | Description
double | Returns the reference time as a double value.
Operator = | Copy constructor for the COARefTime class.
Operator == | Tests for equality between COARefTime objects.
Operator != | Tests for inequality between COARefTime objects.
Operator < | Tests if one COARefTime object is less than another COARefTime object.
Operator > | Tests if one COARefTime object is greater than another COARefTime object.
Operator <= | Tests if one COARefTime object is less than or equal to another COARefTime object.
Operator >= | Tests if one COARefTime object is greater than or equal to another COARefTime object.
Operator + | Adds two COARefTime objects.
Operator – | Subtracts one COARefTime object from another COARefTime object.
Operator += | Adds two COARefTime objects and makes this object equal to the result.
Operator –= | Subtracts one COARefTime object from another COARefTime object and makes this object equal to the result.
Operator * | Multiplies two COARefTime objects.
Operator / | Divides one COARefTime object by another COARefTime object.

COARefTime::COARefTime

COARefTime Class

Constructs a COARefTime object.

COARefTime(
CRefTime t
);
COARefTime(
REFERENCE_TIME t
);
COARefTime(
double d
);

Parameters
t
CRefTime value or REFERENCE_TIME value passed through to the class. Units are 100 nanoseconds.
d
A double value that constructs the COARefTime class. Units in this case are (fractional) seconds.
Return Values

No return value.

COARefTime::double

COARefTime Class

Retrieves the reference time as a double value, converted from 100-nanosecond units to seconds.

operator double();

COARefTime::Operator =

COARefTime Class

Copy constructor for a COARefTime object.

COARefTime& operator=(
const double& rd
);

Parameters
rd
A double value that constructs a COARefTime object.
Return Values

No return value.

COARefTime::Operator ==

COARefTime Class

Tests for equality between COARefTime objects.

BOOL operator==(
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is equal to this object and FALSE otherwise.

Remarks

This object is on the left side of the operator.

COARefTime::Operator !=

COARefTime Class

Tests for inequality between COARefTime objects.

BOOL operator!=(
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is not equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

COARefTime::Operator <

COARefTime Class

Tests if one COARefTime object is less than another COARefTime object.

BOOL operator < (
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is less than this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

COARefTime::Operator >

COARefTime Class

Tests if one COARefTime object is greater than another COARefTime object.

BOOL operator > (
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is greater than this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

COARefTime::Operator >=

COARefTime Class

Tests if one COARefTime object is greater than or equal to another COARefTime object.

BOOL operator >= (
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is greater than or equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

COARefTime::Operator <=

COARefTime Class

Tests if one COARefTime object is less than or equal to another COARefTime object.

BOOL operator <= (
const COARefTime& rt
);

Parameters
rt
COARefTime object corresponding to the right side of the operator.
Return Values

Returns TRUE if the COARefTime object tested is less than or equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

COARefTime::Operator +

COARefTime Class

Adds two COARefTime objects.

COARefTime operator+(
const COARefTime& rt
);

Parameters
rt
COARefTime object to be added.
Return Values

Returns the result of the addition.

COARefTime::Operator –

COARefTime Class

Subtracts one COARefTime object from another COARefTime object.

COARefTime operator-(
const COARefTime& rt
);

Parameters
rt
COARefTime object to be subtracted.
Return Values

Returns the result of the subtraction.

Remarks

This object is the object subtracted from.

COARefTime::Operator +=

COARefTime Class

Adds two COARefTime objects and makes this object equal to the result.

COARefTime& operator+=(
const COARefTime& rt
);

Parameters
rt
COARefTime object to be added.
Return Values

Returns the result.

COARefTime::Operator –=

COARefTime Class

Subtracts one COARefTime object from another COARefTime object and makes this object equal to the result.

COARefTime& operator-=(
const COARefTime& rt
);

Parameters
rt
COARefTime object to be subtracted.
Return Values

Returns the result.

Remarks

This object is the object subtracted from.

COARefTime::Operator *

COARefTime Class

Multiplies the COARefTime object by a value.

COARefTime operator*(
LONG l
);

Parameters
l
Value to multiply by.
Return Values

Returns the result.

COARefTime::Operator /

COARefTime Class

Divides one COARefTime object by a value.

COARefTime operator/(
LONG l
);

Parameters
l
Value to divide by.
Return Values

Returns the result.


COutputQueue Class

COutputQueue class hierarchy

Output pins use the COutputQueue to send samples to another filter by using the local memory-based transport (that is, to input pins that support the IMemInputPin interface). COutputQueue uses IMemInputPin::ReceiveCanBlock to determine if the connected input pin has a blocking implementation of IMemInputPin::Receive. If so, all samples are queued in COutputQueue and a thread is created to pass samples from the queue to the connected input pin. If the input pin's IMemInputPin::Receive method does not block, samples are passed directly to IMemInputPin::Receive. COutputQueue can also batch samples to reduce the number of calls to the downstream pin.

COutputQueue is useful when the filter has other work to do while samples that it has already completed are being processed downstream. This occurs, for example, in a filter that can read more data off disk while data is being processed, or when it has more than one output pin and does not want to starve an output pin because IMemInputPin::Receive has no optional batching of samples.

To use this class, create one COutputQueue object for every output pin for which it will be used. This can either be created when the pin is created and deleted when the pin is disconnected, or it can be created when the pin goes active and deleted when the pin goes inactive.

The samples sent to this object by calling its COutputQueue::Receive or COutputQueue::ReceiveMultiple member function should have references added by means of IUnknown::AddRef (as they usually are if they were obtained directly from an allocator). This object then calls IUnknown::Release on all samples it receives, whether they were processed successfully or not. Note that Release is not called for special (control) samples.

Some control information, such as end of stream, needs to be queued with the data and processed once all the data has been delivered. This information is queued in the form of special control packets. COutputQueue implements a sticky HRESULT so it will not send any more data after it gets a return code that is not S_OK from the downstream ReceiveMultiple call. (A sticky state setting is one that persists even after execution of operations that would normally reset the setting.) This sticky state is reset by the EndFlush and EOS calls. However, if the sticky HRESULT is not S_OK, EOS itself is not sent downstream; the HRESULT is just reset. Because of this, if this object is not deleted when the pin goes inactive, BeginFlush and EndFlush should be called at that time to free the state.

In many ways this object acts as a proxy for the connected input pin, supporting a similar set of methods for stream control.

Protected Data Members
Name | Description
m_bBatchExact | TRUE if commands are batched; FALSE if commands are sent singly.
m_bFlushed | Flag to signify if samples have been flushed.
m_bFlushing | Flag for flushing state.
m_bSendAnyway | Flag to override batch processing.
m_bTerminate | Termination flag.
m_evFlushComplete | Event signaling that flushing has finished.
m_hSem | Handle used for signaling.
m_hr | HRESULT structure for return values; used to implement a sticky return value (one that persists even after operations that would normally change the value).
m_hThread | Worker thread handle.
m_lBatchSize | Work in batches of this batch size. Ignored if m_bBatchExact is not TRUE.
m_List Pointer to a CSampleList object. The class CSampleList is a generic list (CGenericList) of objects of IMediaSample type. It is defined as follows:
typedef CGenericList<IMediaSample> CSampleList;
m_lWaiting | Variable set to nonzero value when waiting for a free element.
m_nBatched | Number of samples currently batched awaiting processing.
m_pInputPin | Pointer to the connected input pin.
m_pPin | Pointer to the output pin.
m_ppSamples | Pointer to an array of batched samples.

Member Functions
Name | Description
BeginFlush | Causes all unsent samples to be discarded and sets flushing state.
COutputQueue | Constructs a COutputQueue object.
EndFlush | Finalizes flush of batched or queued samples and resets flushing state.
EOS | Queues an end-of-stream call to the connected input pin after all batched and queued samples have been passed to the input pin.
FreeSamples | Removes and releases batched and queued samples.
InitialThreadProc | Executed by the thread on thread creation.
IsIdle | Determines if the output queue is idle.
IsQueued | Determines if samples are being queued or being sent directly.
IsSpecialSample | Determines if the sample is a control sample.
NotifyThread | Notifies the thread that there is something to do.
NewSegment | Queues an IPin::NewSegment call to the connected input pin after all queued samples have been passed to the input pin.
QueueSample | Queues the prepared sample.
Receive | Passes in a single sample to send to the input pin.
ReceiveMultiple | Passes a set of samples to send to the input pin.
Reset | Resets the deferred return code m_hr to allow the output queue to be ready for more data.
SendAnyway | Frees any batches samples to be sent to the input pin.
ThreadProc | Implements the thread that sends samples downstream.

COutputQueue::BeginFlush

COutputQueue Class

Causes all unsent samples to be discarded and sets the flushing state.

void BeginFlush( );

Return Values

No return value.

Remarks

This member function calls BeginFlush on the connected input pin.

COutputQueue::COutputQueue

COutputQueue Class

Constructs a COutputQueue object.

COutputQueue(
IPin *pInputPin,
HRESULT *phr,
BOOL bAuto = TRUE,
BOOL bQueue = TRUE,
LONG lBatchSize,
BOOL bBatchExact,
LONG lListSize,
DWORD dwPriority
);

Parameters
pInputPin
Connected pin to which to send data.
phr
HRESULT return code.
bAuto
If TRUE, the queuing mode is determined by asking the connected input pin if the pin can block (by calling IMemInputPin::ReceiveCanBlock). If FALSE, queued or direct mode is set by the bQueue parameter.
bQueue
Determines if samples are queued for delivery by a worker thread or are being sent directly. Ignored if bAuto is TRUE.
lBatchSize
Size of the batch (1 for no batching).
bBatchExact
Batch exactly to lBatchSize (but use SendAnyway to override batching).
lListSize
Likely number in the list.
dwPriority
Priority given to the created thread.
Return Values

No return value.

Remarks

The phr parameter should be updated only to report errors. Usually bAuto will be TRUE. In that case, the constructor calls IMemInputPin::ReceiveCanBlock on the downstream pin to determine whether to create a thread, and so to send samples asynchronously. If bAuto is FALSE, a thread is created if, and only if, bQueue is TRUE.

If the batch size is not 1, data is not sent until lBatchSize samples have been received by the object. The exceptions are that, if fewer than lBatchSize samples are passed to COutputQueue::Receive or COutputQueue::ReceiveMultiple in this object and bBatchExact is FALSE, the samples will be sent anyway.

If bBatchExact is TRUE, the COutputQueue::SendAnyway member function will cause the samples to be sent to the thread (if the thread is created).

COutputQueue::EndFlush

COutputQueue Class

Finalizes flush of batched or queued samples and resets the flushing state.

void EndFlush( );

Return Values

No return value.

Remarks

The downstream pin is guaranteed not to block at this stage.

COutputQueue::EOS

COutputQueue Class

Queues an end-of-stream call to the connected input pin after all batched and queued samples have been passed to the input pin.

void EOS( );

Return Values

No return value.

Remarks

The end-of-stream call is queued as a special control packet when in a queued mode. This member function does not actually send an end-of-stream packet if the m_hr HRESULT value is not S_OK when it is time to make the call.

COutputQueue::FreeSamples

COutputQueue Class

Removes and releases batched and queued samples.

void FreeSamples( );

Return Values

No return value.

COutputQueue::InitialThreadProc

COutputQueue Class

Implements the static member function that the thread executes on thread creation.

static DWORD WINAPI InitialThreadProc(
LPVOID pv
);

Parameters
pv
The this pointer for the COutputQueue object.
Return Values

The derived class defines the meaning of the return value.

Remarks

On thread creation, the worker thread executes this static function with a pointer to the COutputQueue object as the parameter. This function simply calls the COutputQueue::ThreadProc member function of that object (that is, the function pointed to by pv).

COutputQueue::IsIdle

COutputQueue Class

Determines if the output pin is idle.

BOOL IsIdle( );

Return Values

Returns TRUE if no threads are in the queue, all data has been sent, and nothing is in the batch. Returns FALSE otherwise.

COutputQueue::IsQueued

COutputQueue Class

Determines if the COutputQueue object is in queued or direct mode.

BOOL IsQueued( );

Return Values

Returns one of the following values.
Value | Meaning
TRUE | In queued mode. Samples are delivered asynchronously by a worker thread.
FALSE | In direct mode. Receive calls are passed synchronously to the input pin.

COutputQueue::IsSpecialSample

COutputQueue Class

Determines if a sample is one of the special control samples (containing no data).

BOOL IsSpecialSample(
IMediaSample *pSample
);

Parameters
pSample
Pointer to the sample to be passed to the connected input pin.
Return Values

Returns one of the following values.
Value | Meaning
TRUE | pSample is a special control sample.
FALSE | pSample is an IMediaSample interface.

Remarks

Special control samples are queued in line with the data by methods (such as COutputQueue::EOS) that require processing once all queued data has been delivered. The COutputQueue::ThreadProc member function detects these special samples on the queue by using IsSpecialSample and processes them appropriately.

A special sample is one of following types and contains no media data.
EOS_PACKET
NEW_SEGMENT
RESET_PACKET
SEND_PACKET

Special control samples are relevant only if you plan to change or extend the default base class implementation of COutputQueue in a derived class. Normal use of the COutputQueue class does not require the use of control samples.

COutputQueue::NewSegment

COutputQueue Class

Queues an IPin::NewSegment call to the connected input pin after all queued samples have been passed to the input pin.

HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
[in] Start time of the segment.
tStop
[in] Stop time of the segment.
dRate
[in] Rate of the segment.
Return Values

Returns an HRESULT value.

Remarks

This member function calls the IPin::NewSegment method on the output pin once all previous data has been delivered. Like COutputQueue::EOS, the COutputQueue::NewSegment call and its parameters are queued as a special control sample if the COutputQueue object is in queued mode, and the IPin::NewSegment method is called from the worker thread in COutputQueue::ThreadProc.

Special control samples, as implemented by this member function, are only relevant if you plan to change or extend the default base class implementation of COutputQueue in a derived class. Normal use of the COutputQueue class does not require the use of control samples.

This member function allows filters that process buffers containing more than one sample to delineate the rendering of the samples between start and stop time, as indicated by the tStart and tStop parameters.

COutputQueue::NewSegment is intended to be implemented on an input pin. A connected output pin on the upstream filter calls this member function after completing delivery of previous data and before calling IMemInputPin::Receive with any new data. It indicates that all data arriving after this call is part of a segment delineated by the parameters.

COutputQueue::NotifyThread

COutputQueue Class

Notifies the thread that there is data on the queue to process.

void NotifyThread( );

Return Values

No return value.

Remarks

The critical section must be held when this is called.

COutputQueue::QueueSample

COutputQueue Class

Queues a sample.

void QueueSample(
IMediaSample *pSample
);

Parameters
pSample
Pointer to the sample to be passed to the connected input pin.
Return Values

No return value.

Remarks

The critical section must be held when this is called.

COutputQueue::Receive

COutputQueue Class

Passes in a single sample to send to the input pin.

HRESULT Receive(
IMediaSample *pSample
);

Parameters
pSample
Pointer to the sample to be passed to the connected input pin.
Return Values

Returns an HRESULT value, which can include the following values, or others.
Value | Meaning
S_FALSE | End of stream detected before or while processing sample; any further samples will be discarded and this value returned.
Other | An error occurred before or while processing sample; any further samples will be discarded and this value returned.
S_OK | Queued successfully or passed to the connected input pin if there is no queue.

Remarks

If the sticky return code (m_hr) is not S_OK, the sample is not sent and the sticky return code is returned. (A sticky return code is one that persists even after operations that would normally change its value.) The samples are all released (by means of Release) after processing, regardless of whether the processing was successful.

COutputQueue::ReceiveMultiple

COutputQueue Class

Passes a set of samples to send to the input pin.

HRESULT ReceiveMultiple (
IMediaSample **ppSamples,
long nSamples,
long *nSamplesProcessed
);

Parameters
ppSamples
Pointer to the set of samples to be passed to the connected input pin.
nSamples
Number of samples pointed to by ppSamples.
nSamplesProcessed
Updated to be the number of samples processed.
Return Values

Returns an HRESULT value, which can include the following values, or others.
Value | Meaning
Other | An error occurred before or while processing sample; any further samples will be discarded and this value returned.
S_FALSE | End of stream detected before or while processing sample; any further samples will be discarded and this value returned.
S_OK | Queued successfully or passed to the connected input pin if there is no queue.

Remarks

If the sticky return code is not S_OK, the sample is not sent and the sticky return code is returned. (A sticky return code is one that persists even after operations that would normally change its value.) The samples are all released (by means of Release) after processing, regardless of whether the processing was successful.

COutputQueue::Reset

COutputQueue Class

Resets the deferred return code m_hr to ready the output queue for more data.

void Reset( );

Return Values

No return value.

Remarks

The sticky return code m_hr is set to S_OK if data is queued; otherwise, this function queues the sample and notifies the thread. (A sticky return code is one that persists even after operations that would normally change its value.)

COutputQueue::SendAnyway

COutputQueue Class

If bBatchExact was specified on construction, frees batched samples so they can be sent to the input pin.

void SendAnyway( );

Return Values

No return value.

COutputQueue::ThreadProc

COutputQueue Class

Implements the thread that sends samples downstream.

DWORD ThreadProc( );

Return Values

Returns zero when DirectShow terminates the thread.

Remarks

This is the main thread procedure for the class, which is called from COutputQueue::InitialThreadProc. It sends a sample or a batch of samples to the connected input pin (depending on the m_bBatchExact, m_nBatched, and m_lBatchSize data members) when conditions are met. Otherwise, it increments the m_lWaiting data member, while holding the critical section and waits for m_hSem to be set (not holding the critical section) to continue.


CPersistStream Class

CPersistStream class hierarchy

CPersistStream is the base class for persistent properties of filters (that is, filter properties in saved graphs).

The simplest way to use CPersistStream is to:

  1. Arrange for your filter to inherit this class.
  2. Implement WriteToStream and ReadFromStream in your class. These will override the functions here, which do nothing but act as placeholders.
  3. Change your NonDelegatingQueryInterface to handle IPersistStream.
  4. Implement SizeMax to return an upper bound on the number of bytes of data you save.

    If you save Unicode data, remember that a WCHAR is 2 bytes.

  5. When your data changes, call SetDirty.

Version Numbers

At some point you might decide to alter or extend the format of your data. You will then wish you had a version number in all the old saved streams so you can tell, when you read them, whether they represent the old or new form. To assist you, this class writes and reads a version number. When it writes, it calls GetSoftwareVersion to inquire as to the version of the software being used at the moment. (In effect, this is a version number of the data layout in the file.) It writes this as the first thing in the data. If you want to change the version, implement (override) GetSoftwareVersion. It reads the version number from the file into mPS_dwFileVersion before calling ReadFromStream, so in ReadFromStream you can check mPS_dwFileVersion to see if you are reading an old version file. Usually you should accept files whose version is no newer than the software version that is reading them.

Protected Data Members
Name | Description
mPS_dwFileVersion | Version number of the file.
mPS_fDirty | Data for this stream must be saved.

Member Functions
Name | Description
CPersistStream | Constructs a CPersistStream object.
SetDirty | Indicates that the object must be saved to the stream.

Overridable Member Functions
Name | Description
GetClassID | Returns the class identifier of this stream.
GetSoftwareVersion | Returns the version number for this file format.
ReadFromStream | Reads the filter's data from the stream.
SizeMax | Returns the number of bytes needed for data (not including version number).
WriteToStream | Writes the filter's data to the stream.

CPersistStream implements IPersistStream. For more implementation information, see the COM Reference in the Microsoft Platform SDK.

Implemented IPersistStream Methods
Name | Description
GetSizeMax | Returns the number of bytes needed for data (including version number).
IsDirty | Checks if the object must be saved.
Load | Loads the data from the stream into memory.
Save | Saves the data from memory to the stream.

CPersistStream::CPersistStream

CPersistStream Class

Constructs a CPersistStream object.

CPersistStream(
IUnknown *pUnk,
HRESULT *phr
);

Parameters
pUnk
IUnknown interface of the delegating object.
phr
Pointer to the general COM return value. Note that this value is changed only if this function fails.
Return Values

No return value.

CPersistStream::GetClassID

CPersistStream Class

Retrieves the class identifier for this filter.

HRESULT GetClassID(
CLSID *pClsID
);

Parameters
pClsID
Pointer to a CLSID structure. Copy your class ID to here.
Return Values

Returns an HRESULT value.

CPersistStream::GetSizeMax

CPersistStream Class

Returns the maximum byte size needed for the current stream, including the version number.

HRESULT GetSizeMax(
ULARGE_INTEGER * pcbSize
);

Parameters
pcbSize
Size in bytes needed to save this stream, including the version number.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPersistStream::GetSizeMax method.

CPersistStream::GetSoftwareVersion

CPersistStream Class

Returns the software version for this stream.

virtual DWORD GetSoftwareVersion(void);

Return Values

Returns a DWORD containing the version number. Each time the format of the stream is changed, this function should be altered to return a larger number than before.

Remarks

See Version Numbers for an explanation as to why file format version numbers are useful.

CPersistStream::IsDirty

CPersistStream Class

Indicates whether the object has changed since it was last saved to its current stream.

HRESULT IsDirty( );

Return Values

Returns S_OK if the filter needs saving and S_FALSE if it does not need saving.

Remarks

This member function implements the IPersistStream::IsDirty method.

CPersistStream::Load

CPersistStream Class

Loads the filter's data from a given stream.

HRESULT Load(
LPSTREAM pStm
);

Parameters
pStm
Pointer to the stream from which to be loaded.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPersistStream::Load method.

CPersistStream::ReadFromStream

CPersistStream Class

Reads the filter's data from the given stream.

virtual HRESULT ReadFromStream(
IStream *pStream
);

Parameters
pStream
Pointer to an IStream interface from which data is to be read.
Return Values

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

The default version reads nothing; it can be overridden to read data specific to your class.

CPersistStream::Save

CPersistStream Class

Saves the filter's data to the given stream.

HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);

Parameters
pStm
Pointer to the stream to which data is to be saved.
fClearDirty
Flag that indicates whether to reset the current stream's dirty flag. When called as part of Save, the flag is normally reset; when called as part of Save As, the flag is normally not reset.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPersistStream::Save method. It calls WriteInt with the software version, calls CPersistStream::WriteToStream with the stream in pStm, and resets mPS_fDirty.

CPersistStream::SetDirty

CPersistStream Class

Changes the dirty flag for the current stream.

HRESULT SetDirty(
BOOL fDirty
);

Parameters
fDirty
New dirty flag for this stream. TRUE means that the data has not been saved.
Return Values

Returns an HRESULT value.

CPersistStream::SizeMax

CPersistStream Class

Retrieves the maximum byte size needed for the current stream, not including the version number.

virtual int SizeMax( );

Return Values

Returns the number of bytes needed for data, not including the version number.

Remarks

The default version returns zero; it should be overridden to provide some other appropriate value.

CPersistStream::WriteToStream

CPersistStream Class

Writes the filter's data to the given stream.

virtual HRESULT WriteToStream(
IStream *pStream
);

Parameters
pStream
Pointer to an IStream interface that specifies the filter data's destination stream.
Return Values

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

The default version writes nothing; it can be overridden to write data specific to your class.


CPosPassThru Class

CPosPassThru class hierarchy

The CPosPassThru class is a utility class that handles the IMediaPosition and IMediaSeeking interfaces for single-input pin renderers and transform filters.

IMediaPosition is the interface originally used for seeking in time-based media streams. IMediaSeeking is an interface intended to replace IMediaPosition in filter graphs that require seeking to units other than time, such as samples or fields, or that require more precise time-based seeking.

Renderers will use this class to implement IMediaPosition and IMediaSeeking from the filter; transform filters will use it to implement these two interfaces from the output pin. In both cases, the methods will be implemented by calls to the IMediaPosition or IMediaSeeking interface provided by the output pin of the connected upstream filter, effectively passing the position information through to the next filter.

Create a class derived from CPosPassThru, giving it the IPin pointer to your input pin, and delegate all IMediaPosition and IMediaSeeking methods to it. The class will find the output pin connected to the input pin, query this output pin for the IMediaPosition or IMediaSeeking interface, and respond appropriately.

Protected Data Members
Name | Description
m_Pin | Pointer to the input pin of the filter.

Member Functions
Name | Description
CPosPassThru | Constructs a CPosPassThru object.
ForceRefresh | Releases any cached interfaces held on the upstream pin.

Overridable Member Functions
Name | Description
GetMediaTime | Retrieves the starting and ending media times.

Implemented IMediaPosition Methods
Name | Description
CanSeekBackward | Determines if the current position can be moved backward in the media stream.
CanSeekForward | Determines if the current position can be moved forward in the media stream.
get_CurrentPosition | Retrieves the current position in terms of the total length of the media stream.
get_Duration | Retrieves the total duration of the media stream.
get_PrerollTime | Retrieves the time before the start position that the filter graph will start any nonrandom access device rolling.
get_Rate | Retrieves the playback rate, relative to normal playback of the media.
get_StopTime | Retrieves the position within the media at which playback should stop.
put_CurrentPosition | Sets the position within the media at which playback should start.
put_PrerollTime | Sets the time before the start position that the filter graph will start any nonrandom access device rolling.
put_Rate | Sets the playback rate, relative to normal playback of the media.
put_StopTime | Sets the position within the media at which playback should stop.

Implemented IMediaSeeking Methods
Name | Description
CheckCapabilities | Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.
ConvertTimeFormat | Converts a time from one time format to another.
GetAvailable | Returns the range of times in which seeking is efficient.
GetCapabilities | Retrieves the seeking capabilities of the media stream.
GetCurrentPosition | Retrieves the current position within the media stream.
GetDuration | Retrieves the length of time that the media stream will play.
GetPositions | Retrieves the current start and stop position settings.
GetPreroll | Retrieves the preroll settings.
GetRate | Retrieves the current rate.
GetStopPosition | Retrieves the position at which the media stream stops.
GetTimeFormat | Retrieves the current media time format.
IsFormatSupported | Determines if a specified time format is supported.
IsUsingTimeFormat | Determines if the time format being used in the call is the same as the one the interface currently uses.
QueryPreferredFormat | Retrieves the preferred time format the interface will use.
SetPositions | Sets current and stop positions and applies flags to both.
SetRate | Sets a new playback rate.
SetTimeFormat | Sets the time format, which determines the format of units used during seeking.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns a specified reference-counted interface.

CPosPassThru::CanSeekBackward

CPosPassThru Class

Determines if the current position can be moved backward in the media stream.

HRESULT CanSeekBackward(
LONG *pCanSeekBackward
);

Parameters
pCanSeekBackward
Set to OATRUE if able to seek backward; otherwise set to OAFALSE.
Return Values

Returns the HRESULT value returned from calling IMediaPosition::CanSeekBackward on the connected pin.

Remarks

This member function calls IMediaPosition::CanSeekBackward on the connected pin and returns the result.

CPosPassThru::CanSeekForward

CPosPassThru Class

Determines if the current position can be moved forward in the media stream.

HRESULT CanSeekForward(
LONG *pCanSeekForward
);

Parameters
pCanSeekForward
Set to OATRUE if able to seek forward; otherwise set to OAFALSE.
Return Values

Returns the HRESULT value returned from calling IMediaPosition::CanSeekForward on the connected pin.

Remarks

This member function calls IMediaPosition::CanSeekForward on the upstream output pin connected to the peer input pin and returns the result.

CPosPassThru::CheckCapabilities

CPosPassThru Class

Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.

HRESULT CheckCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
Pointer to an AM_SEEKING_SEEKING_CAPABILITIES enumerator containing the seeking capabilities flags to apply. These flags can be any combination of the following:
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanSeekForwards
Return Values

Returns S_OK if all capabilities in pCapabilities are present, S_FALSE if some are present, or E_FAIL if none are present.

Remarks

This member function implements IMediaSeeking::CheckCapabilities, by calling the IMediaSeeking::CheckCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return whether the flags presented in the pCapabilities parameter are present. This returned value will then, in turn, propagate to calls made from CPosPassThru::CheckCapabilities member functions in intervening filters.

CPosPassThru::ConvertTimeFormat

CPosPassThru Class

Converts a time from one format to another.

HRESULT ConvertTimeFormat(
LONGLONG * pTarget,
const GUID * pTargetFormat,
LONGLONG Source,
const GUID * pSourceFormat
);

Parameters
pTarget
Time in converted format.
pTargetFormat
GUID of the format to convert to, or the currently selected format if NULL.
Source
Time in original format.
pSourceFormat
GUID of the format to be converted from, or the currently selected format if NULL.
Return Values

Returns the HRESULT value returned from calling IMediaSeeking::ConvertTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::ConvertTimeFormat method by calling this same method on the upstream filter's output pin.

CPosPassThru::CPosPassThru

CPosPassThru Class

Constructs a CPosPassThru object.

CPosPassThru(
const TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT * phr,
IPin * pPin
);

Parameters
pName
Name of the object used in the CPosPassThru constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for resulting information.
pPin
Pointer to the input pin for the filter.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CPosPassThru::ForceRefresh

CPosPassThru Class

Releases any cached interfaces on the upstream pin.

HRESULT ForceRefresh( );

Return Values

Returns S_OK.

Remarks

For efficiency, the CPosPassThru class can cache the IMediaPosition interface of the connected upstream output pin. This method releases any cached interface pointers and forces them to be obtained again via QueryInterface if needed.

Presently, this class does not cache the upstream IMediaPosition so this member function is not necessary. It is left in for future flexibility.

CPosPassThru::GetAvailable

CPosPassThru Class

Returns the range of times in which seeking is efficient.

HRESULT GetAvailable(
LONGLONG * pEarliest,
LONGLONG * pLatest
);

Parameters
pEarliest
Earliest time that can be efficiently seeked to.
pLatest
Latest time that can be efficiently seeked to.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetAvailable on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetAvailable method by calling this same method on the upstream filter's output pin.

CPosPassThru::GetCapabilities

CPosPassThru Class

Returns the seeking capabilities of the media stream.

HRESULT GetCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
Seeking capability flags, which can be any combination of the following.
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanSeekForwards
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetCapabilities on the connected pin.

Remarks

This member function implements IMediaSeeking::GetCapabilities by calling the IMediaSeeking::GetCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return the capabilities present in the pCapabilities parameter. These returned capabilities will then, in turn, propagate to calls made from CPosPassThru::GetCapabilities member functions in intervening filters.

CPosPassThru::GetCurrentPosition

CPosPassThru Class

Retrieves the current position in terms of the media stream's total length.

HRESULT GetCurrentPosition(
LONGLONG* pCurrent
);

Parameters
pCurrent
Current position in current time format units.
Return Values

Returns NOERROR if successful. Otherwise, returns the HRESULT value returned from calling IMediaSeeking::GetCurrentPosition on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetCurrentPosition interface. It calls the CPosPassThru::GetMediaTime virtual member function, which you should override and implement in your derived class to return the current position. If this fails (which it does by default), the IMediaSeeking::GetCurrentPosition on the upstream filter's output pin is called.

CPosPassThru::get_CurrentPosition

CPosPassThru Class

Retrieves the current position in terms of the total length of the media stream.

HRESULT get_CurrentPosition(
REFTIME* pllTime
);

Parameters
pllTime
Returned start time as a double value in seconds.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaPosition::get_CurrentPosition on the connected pin.

Remarks

The start position is applied before the rate and therefore is the position at typical playback speed.

CPosPassThru::GetDuration

CPosPassThru Class

Retrieves the length of time that the media stream will play.

HRESULT GetDuration(
LONGLONG* pDuration
);

Parameters
pDuration
Returned length of the media stream.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetDuration on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetDuration method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_Duration

CPosPassThru Class

Retrieves the total duration of the media stream.

HRESULT get_Duration(
REFTIME * plength
);

Parameters
plength
Returned length of the media stream.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaPosition::get_Duration on the connected pin.

Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate.

CPosPassThru::GetMediaTime

CPosPassThru Class

Retrieves the starting and ending media times.

virtual HRESULT GetMediaTime(
LONGLONG* pStartTime,
LONGLONG* pEndTime
);

Parameters
pStartTime
Returned starting media time.
pEndTime
Returned ending media time.
Return Values

Returns an HRESULT value (E_FAIL by default).

Remarks

Override this virtual member function to return the current samples' media time. This represents the current position in terms of media time (for example, frame 20 of a total 130 frames).

CPosPassThru::GetPositions

CPosPassThru Class

Returns the current and stop position settings.

HRESULT GetPositions(
LONGLONG * pCurrent,
LONGLONG * pStop
);

Parameters
pCurrent
Start time in the current time format.
pStop
Stop time in the current time format.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetPositions on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.

CPosPassThru::GetPreroll

CPosPassThru Class

Retrieves the preroll settings.

HRESULT GetPreroll(
LONGLONG * pllPreroll
);

Parameters
pllPreroll
Returned preroll time.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetPreroll on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetPreroll method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_PrerollTime

CPosPassThru Class

Retrieves the time prior to the start position that devices should start rolling.

HRESULT get_PrerollTime(
REFTIME* pllTime
);

Parameters
pllTime
Returned preroll time as a double value in seconds.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaPosition::get_PrerollTime on the connected pin.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

CPosPassThru::GetRate

CPosPassThru Class

Retrieves the current rate.

HRESULT GetRate(
double * pdRate
);

Parameters
pdRate
Current rate, where 1 is the normal rate.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetRate on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetRate method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_Rate

CPosPassThru Class

Retrieves the rate of playback relative to normal playback speed.

HRESULT get_Rate(
double * pdRate
);

Parameters
pdRate
Returned rate.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaPosition::get_Rate on the connected pin.

Remarks

A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.

CPosPassThru::GetStopPosition

CPosPassThru Class

Retrieves the position at which the media stream stops.

HRESULT GetStopPosition(
LONGLONG* pStop
);

Parameters
pStop
Returned stop time.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetStopPosition on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetStopPosition method by calling this same method on the upstream filter's output pin. The stop position is a time between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

CPosPassThru::get_StopTime

CPosPassThru Class

Retrieves the time at which the media stream stops.

HRESULT get_StopTime(
REFTIME* pllTime
);

Parameters
pllTime
Returned stop time as a double value in seconds.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaPosition::get_StopTime on the connected pin.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

CPosPassThru::GetTimeFormat

CPosPassThru Class

Retrieves the current time format, which determines the format of units used during seeking.

HRESULT GetTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Media time format currently supported by this interface.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::GetTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetTimeFormat method by calling this same method on the upstream filter's output pin.

See the IMediaSeeking::IsFormatSupported method for a list of time formats.

CPosPassThru::IsFormatSupported

CPosPassThru Class

Determines if a specified time format is supported.

HRESULT IsFormatSupported(
const GUID * pFormat
);

Parameters
pFormat
Time format to compare.
Return Values

Return Values

Returns the HRESULT value returned from calling IMediaSeeking::IsFormatSupported on the connected pin.

Remarks

This member function implements the IMediaSeeking::IsFormatSupported method. See that method for a list of valid time formats.

CPosPassThru::IsUsingTimeFormat

CPosPassThru Class

Determines if the time format being used in the call is the same as the one currently in use by the interface.

HRESULT IsUsingTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Time format to check.
Return Values

Returns S_OK if pFormat is the current time format; otherwise returns S_FALSE.

Remarks

This member function implements the IMediaSeeking::IsUsingTimeFormat method by calling this same method on the upstream filter's output pin. This can be used in place of IMediaSeeking::GetTimeFormat to save copying the GUID.

CPosPassThru::NonDelegatingQueryInterface

CPosPassThru Class

Returns a specified reference-counted interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IMediaPosition, IMediaSeeking, and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

CPosPassThru::put_CurrentPosition

CPosPassThru Class

Sets the time that the media stream begins.

HRESULT put_CurrentPosition(
REFTIME llTime
);

Parameters
llTime
Start time expressed as a double value in seconds.
Return Values

Returns the HRESULT value returned from calling IMediaPosition::put_CurrentPosition on the connected pin.

Remarks

The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued. Do not call this method when the filter graph is running, only when it is paused or stopped.

Setting the start position when paused causes playback to resume from the new start position when the run command is issued.

The start position is applied before the rate and therefore is the position at typical playback speed.

CPosPassThru::put_PrerollTime

CPosPassThru Class

Sets the time prior to the start position that devices should start rolling.

HRESULT put_PrerollTime(
REFTIME llTime
);

Parameters
llTime
Preroll time to be set.
Return Values

Returns the HRESULT value returned from calling IMediaPosition::put_PrerollTime.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

Note that while this member function passes the call upstream, the IMediaPosition::put_PrerollTime method is not implemented on any Microsoft source filter.

CPosPassThru::put_Rate

CPosPassThru Class

Sets the rate of playback relative to normal speed.

HRESULT put_Rate(
double dRate
);

Parameters
dRate
Rate to set.
Return Values

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value returned from calling IMediaPosition::put_Rate on the connected pin.

Remarks

This property allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop frames.

Negative rates indicate reverse play. Not all media will support reverse play.

CPosPassThru::put_StopTime

CPosPassThru Class

Sets the time at which the media stream will stop.

HRESULT put_StopTime(
REFTIME llTime
);

Parameters
llTime
Stop time as a double value in seconds.
Return Values

Returns the HRESULT value returned from calling IMediaPosition::put_StopTime on the connected pin.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

CPosPassThru::QueryPreferredFormat

CPosPassThru Class

Retrieves the preferred time format to be used by the interface.

HRESULT QueryPreferredFormat(
GUID *pFormat
);

Parameters
pFormat
Time format preferred by the interface.
Return Values

Returns the HRESULT value returned from calling IMediaSeeking::QueryPreferredFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::QueryPreferredFormat method by calling this same method on the upstream filter's output pin.

See the description for IMediaSeeking::IsFormatSupported for a list of available time formats. If the time format returned is not satisfactory, use the IMediaSeeking::IsFormatSupported method to query for supported time formats that you can use.

CPosPassThru::SetPositions

CPosPassThru Class

Sets current and stop positions and applies flags to both.

HRESULT SetPositions(
LONGLONG * pCurrent,
DWORD dwCurrentFlags,
LONGLONG * pStop,
DWORD dwStopFlags
);

Parameters
pCurrent
Start position if stopped, or position to continue from if paused.
dwCurrentFlags
When seeking, one of these flags must be set to indicate the type of seek. See the IMediaSeeking::SetPositions method for a description of these flags.
pStop
Position in the stream at which to quit.
dwStopFlags
Stop position seeking options to be applied. These are the same as listed for dwCurrentFlags.
Return Values

Returns the HRESULT value returned from calling IMediaSeeking::SetPositions on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.

CPosPassThru::SetRate

CPosPassThru Class

Sets a new playback rate.

HRESULT SetRate(
double dRate
);

Parameters
dRate
New rate, where 1 is the normal rate, 2 is twice as fast, and so on.
Return Values

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value returned from calling IMediaSeeking::SetRate on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetRate method by calling this same method on the upstream filter's output pin. It is an error to set the rate to 0.

CPosPassThru::SetTimeFormat

CPosPassThru Class

Sets the time format, which determines the format of units used during seeking.

HRESULT SetTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Time format to be supported by this interface.
Return Values

Returns the HRESULT value returned from calling IMediaSeeking::SetTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetTimeFormat method by calling this same method on the upstream filter's output pin. See the IMediaSeeking::IsFormatSupported method for a list of time formats.


CPullPin Class

CPullPin class hierarchy

The CPullPin class is provided to allow a filter downstream from the source to create a thread and pull a media stream from an asynchronous source filter that supports the IAsyncReader interface. Typically this class is implemented on the input pin of a parser filter, since the Microsoft® DirectShow™ asynchronous reader filter just reads a media stream from a file and provides no parsing.

Protected Data Members
Name | Description
m_pAlloc | Pointer to the IMemAllocator interface used by the connection.

Member Functions
Name | Description
Active | Instructs the pin to start pulling data from the asynchronous reader.
AlignDown | Aligns a LONGLONG value down to the next LONG boundary.
AlignUp | Aligns a LONGLONG value up to the next LONG boundary.
Connect | Initiates a connection from this pin to the asynchronous reader.
CPullPin | Constructs a CPullPin object.
Disconnect | Breaks a connection to the asynchronous reader.
Duration | Retrieves the total duration of the media stream.
GetReader | Retrieves the asynchronous reader interface.
Inactive | Instructs the pin to stop pulling data from the asynchronous reader.
Seek | Sets the start and stop times of the media stream.

Overridable Member Functions
Name | Description
BeginFlush | Flushes this pin and all downstream pins.
DecideAllocator | Proposes an allocator for use by the asynchronous reader.
EndFlush | Signals end of flushing operation.
EndOfStream | Sends end-of-stream notification downstream.
OnError | Handles run-time errors that caused pulling to stop.
Receive | Handles the arrival of data from the asynchronous reader.

CPullPin::Active

CPullPin Class

Instructs the pin to start pulling data from the asynchronous reader.

HRESULT Active(void);

Return Values

Returns an HRESULT value.

Remarks

The reader interface must be retrieved and the allocator decided before calling this member function. This is handled by the CPullPin::Connect member function.

CPullPin::AlignDown

CPullPin Class

Aligns a LONGLONG value down to the next LONG boundary.

LONGLONG AlignDown(
LONGLONG ll,
LONG lAlign
);

Parameters
ll
Element to be aligned.
lAlign
Alignment boundary.
Return Values

Returns the ll value aligned to lAlign.

Remarks

Aligning downward is a truncation operation.

CPullPin::AlignUp

CPullPin Class

Aligns a LONGLONG value up to the next LONG boundary.

LONGLONG AlignUp(
LONGLONG ll,
LONG lAlign
);

Parameters
ll
Element to be aligned.
lAlign
Alignment boundary.
Return Values

Returns an HRESULT value.

CPullPin::BeginFlush

CPullPin Class

Override to flush this pin and all downstream pins.

virtual HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CPullPin::Seek member function before pausing the thread prior to a seeking operation. You must implement this member function to call the IPin::BeginFlush method on the connected downstream pin.

CPullPin::Connect

CPullPin Class

Initiates a connection from this pin to the asynchronous reader.

HRESULT Connect(
IUnknown* pUnk,
IMemAllocator* pAlloc,
BOOL bSync
);

Parameters
pUnk
Object to query for existence of asynchronous reader (IAsyncReader).
pAlloc
Optional allocator to propose as preferred allocator if necessary.
bSync
Set TRUE if the reader uses synchronous rather than asynchronous reads.
Return Values

Returns S_OK if successfully connected to the IAsyncReader interface from the object specified by pUnk.

CPullPin::CPullPin

CPullPin Class

Constructs a CPullPin object.

CPullPin(void);

Return Values

No return value.

CPullPin::DecideAllocator

CPullPin Class

Negotiates an allocator to use with the asynchronous reader.

virtual HRESULT DecideAllocator(
IMemAllocator* pAlloc,
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pAlloc
Allocator to propose as the preferred allocator (optional). Pass NULL if you aren't proposing an allocator.
pProps
Size, count, and alignment of the allocator (optional). Pass 0 if not requesting the allocator properties.
Return Values

Returns S_OK if successful, VFW_E_BADALIGN if eProps contains an invalid alignment property, E_OUTOFMEMORY if there is not enough memory available to create an allocator, and E_NOINTERFACE if the created IMemAllocator interface is invalid.

Remarks

This member function calls the IAsyncReader::RequestAllocator method to negotiate an allocator.

CPullPin::Disconnect

CPullPin Class

Breaks a connection to the asynchronous reader.

HRESULT Disconnect(void);

Return Values

Returns NOERROR if there is no connection.

Remarks

This member function disconnects any connection to an asynchronous file reader made in the CPullPin::Connect method.

CPullPin::Duration

CPullPin Class

Retrieves the total duration of the media stream.

HRESULT Duration(
REFERENCE_TIME* ptDuration
);

Parameters
ptDuration
Duration measured in bytes multiplied by UNIT (10,000,000).
Return Values

Returns an HRESULT value.

CPullPin::EndFlush

CPullPin Class

Override to signal the end of a flushing operation.

virtual HRESULT EndFlush(void) PURE;

Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CPullPin::Seek member function after pausing the thread prior to a seeking operation. You must implement this member function to call the IPin::EndFlush method on the connected downstream pin.

CPullPin::EndOfStream

CPullPin Class

Override to send an end-of-stream notification downstream.

virtual HRESULT EndOfStream(void) PURE;

Return Values

Returns an HRESULT value.

Remarks

This member function is called during processing of received samples when the end of the stream is reached. You must implement this member function to call the IPin::EndOfStream method on the connected downstream pin.

CPullPin::GetReader

CPullPin Class

Returns the asynchronous reader.

IAsyncReader* GetReader(void);

Return Values

Returns a reference-counted IAsyncReader interface.

CPullPin::Inactive

CPullPin Class

Instructs the pin to stop pulling data from the asynchronous reader.

HRESULT Inactive(void);

Return Values

Returns an HRESULT value.

Remarks

This member function calls the IAsyncReader::BeginFlush method, ends the thread, calls the IAsyncReader::EndFlush method and then decommits the allocator.

CPullPin::OnError

CPullPin Class

Override to handle run-time errors that caused pulling to stop.

virtual void OnError(
HRESULT hr
) PURE;

Parameters
hr
HRESULT value of the trapped error.
Return Values

No return value.

Remarks

These errors are returned from the upstream filter (the asynchronous reader), which will have already reported errors to the filter graph manager. This member function must be implemented since it is called by several CPullPin member functions when trapping errors.

CPullPin::Receive

CPullPin Class

Override this member function to handle the arrival of data from the asynchronous reader.

virtual HRESULT Receive(
IMediaSample * pSample
) PURE;

Parameters
pSample
[in] Pointer to a media sample.
Return Values

Returns an HRESULT value. Returning a value other than S_OK will stop the data.

Remarks

You must implement this member function in your derived class. This member function is called whenever a new sample arrives while processing the sample stream. It should be written in the same manner as the IMemInputPin::Receive method on an input pin.

CPullPin::Seek

CPullPin Class

Sets the start and stop times of the media stream.

HRESULT Seek(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop
);

Parameters
tStart
Start time (defaults to zero).
tStop
Stop time (defaults to the value of CPullPin::Duration).
Return Values

Returns an HRESULT value.

Remarks

If the filter graph is running (active), the media rendering will start immediately at the new position defined by tStart.


CQueue Class

CQueue class hierarchy

This class implements a simple Queue Abstract Data Type (ADT). The queue contains a finite number of objects, and a semaphore controls access to these objects. The semaphore is created with an initial count (N). Each time an object is added, a call to the Microsoft® Win32® WaitForSingleObject function is made on the handle of the semaphore. When this function returns, it reserves a slot in the queue for the new object. If no slots are available, the member function blocks until it becomes available. Each time an object is removed from the queue, the Win32 ReleaseSemaphore function is called on the handle of the semaphore, thus freeing a slot in the queue. If no objects are present in the queue, the function blocks until an object has been added.

Member Functions
Name | Description
CQueue | Constructs a CQueue object.
GetQueueObject | Retrieves an object from the queue.
PutQueueObject | Puts an object into the queue.

CQueue::CQueue

CQueue Class

Constructs a CQueue object.

CQueue(
int n
);
CQueue( );

Parameters
n
Size of the queue to create.
Return Values

No return value.

Remarks

If constructed with no parameters, the size of the queue is set to DEFAULT_QUEUESIZE.

CQueue::GetQueueObject

CQueue Class

Retrieves an object from the queue.

T GetQueueObject( );

Return Values

Returns an object of type T (template).

Remarks

This member function blocks until an object is available on the queue. It uses a CCritSec object for security.

CQueue::PutQueueObject

CQueue Class

Puts an object into the queue.

void PutQueueObject(
T object
);

Parameters
object
Template object to be inserted into the queue.
Return Values

No return value.

Remarks

This member function blocks if there is no open slot into which to put the object. It releases any blocking CQueue::GetQueueObject member function that is waiting for an object to retrieve.


CRefTime Class

CRefTime class hierarchy

This class is used to manage reference times. It shares the same data layout as the REFERENCE_TIME data type, but adds some (nonvirtual) functions that provide simple comparison, conversion, and arithmetic capabilities.

A reference time is a unit of time represented in 100-nanosecond units. This time unit is the same time unit used by the Microsoft® Win32® FILETIME structure, although the two types cannot be interchanged. Note that the time a REFERENCE_TIME represents is not the time elapsed since 1/1/1601. It is either stream time or reference time, depending on the context.

Data Members
Name | Description
m_time | REFERENCE_TIME value of this object.

Member Functions
Name | Description
CRefTime | Constructs a CRefTime object.
GetUnits | Returns the reference time in units of 100 nanoseconds.
Millisecs | Returns the reference time in milliseconds.

Operators
Name | Description
operator (REFERENCE_TIME) | Casts the CRefTime object to a REFERENCE_TIME data type. The result is the m_time value.
operator = | Implements the copy constructor for the CRefTime class.
operator += | Adds two CRefTime objects and makes this object equal to the result.
operator –= | Subtracts one CRefTime object from another CRefTime object and makes this object equal to the result.

CRefTime::CRefTime

CRefTime Class

Constructs a CRefTime object.

CRefTime( );
CRefTime(
LONG msecs
);
CRefTime(
REFERENCE_TIME rt
);

Parameters
msecs
CRefTime value in milliseconds.
rt
CRefTime object to copy.
Return Values

No return value.

Remarks

When constructed without parameters, the reference time value defaults to zero.

CRefTime::GetUnits

CRefTime Class

Returns the reference time in 100-nanosecond units.

LONGLONG GetUnits(void);

Return Values

Returns the reference time value.

CRefTime::Millisecs

CRefTime Class

Returns the reference time in milliseconds.

LONG Millisecs(void);

Return Values

Returns the reference time value.

CRefTime::operator (REFERENCE_TIME)

CRefTime Class

Cast operator that allows a CRefTime object to be used in place of a REFERENCE_TIME object.

operator REFERENCE_TIME() const;
Return Values

Returns the value of m_time.

Remarks

The following examples show how this cast operator can be used.

CRefTime cRT(1000);
REFERENCE_TIME rt = (REFERENCE_TIME)cRT;

CRefTime::operator =

CRefTime Class

Assigns a new value to the object from an existing value.

CRefTime& operator=(
const CRefTime& rt
);
CRefTime& operator=(
const LONGLONG ll
);

Parameters
rt
Object to copy during the assignment operation.
ll
LONGLONG reference time value.
Return Values

Returns a reference to this object after the operation.

CRefTime::operator +=

CRefTime Class

Adds the value of another CRefTime object to this CRefTime object.

CRefTime& operator+=(
const CRefTime& rt
);

Parameters
rt
CRefTime object to be added.
Return Values

Returns a reference to this object.

CRefTime::operator –=

CRefTime Class

Subtracts another CRefTime object from this CRefTime object.

CRefTime& operator-=(
const CRefTime& rt
);

Parameters
rt
CRefTime object to be subtracted.
Return Values

Returns the result.


CRenderedInputPin Class

CRenderedInputPin class hierarchy

This input pin class is provided for renderer filters that render the stream delivered from an input pin (that is, that do not have an output pin to pass the data on). It overrides CBaseInputPin to handle the end-of-stream notification and is implemented specifically so that more than one stream can be handled using this renderer (since each pin must handle the end-of-stream independently). For an example of a filter that uses this class, see Dump Sample (Dump Filter).

Protected Data Members
Name | Description
m_bAtEndOfStream | Set to TRUE when the end-of-stream notification has been received.
m_bCompleteNotified | Set to TRUE when the EC_COMPLETE notification has been sent to the filter graph manager.

Member Functions
Name | Description
CRenderedInputPin | Constructs a CRenderedInputPin object.

Overridable Member Functions
Name | Description
Active | Notifies the pin that the filter has changed state from stopped to paused.
EndFlush | Informs the pin to end a flush operation.
EndOfStream | Informs the pin that no additional data is expected until a new run command is issued.
Run | Notifies the pin that the filter has changed state from paused to running.

CRenderedInputPin::Active

CRenderedInputPin Class

Notifies the pin that the filter has changed state from stopped to paused or running.

HRESULT Active( );

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBasePin::Active. It sets both m_bAtEndOfStream and m_bCompleteNotified to FALSE before calling the base class implementation.

CRenderedInputPin::CRenderedInputPin

CRenderedInputPin Class

Constructs a CRenderedInputPin object.

CRenderedInputPin(
TCHAR *pObjectName,
CBaseFilter *pFilter,
CCritSec *pLock,
HRESULT *phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the object for debugging purposes.
pFilter
Pointer to the pin's owning filter.
pLock
Critical section for the pin.
phr
Pointer to an HRESULT value.
pName
Pin name.
Return Values

No return value.

CRenderedInputPin::EndFlush

CRenderedInputPin Class

Informs the pin to end a flush operation.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBaseInputPin::EndFlush. It sets both m_bAtEndOfStream and m_bCompleteNotified to FALSE before calling the base class implementation.

CRenderedInputPin::EndOfStream

CRenderedInputPin Class

Informs the pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndOfStream method. It calls CheckStreaming to see that the filter is in a streaming state, sets m_bAtEndOfStream to TRUE, and then sends the EC_COMPLETE notification to the filter graph manager.

The EC_COMPLETE filter graph notification should be issued only after all the data delivered to the pin prior to calling this member function has been processed. If the filter performs processing asynchronously, override CRenderedInputPin::EndOfStream to postpone sending the EC_COMPLETE notification until processing of all input data has completed.

CRenderedInputPin::Run

CRenderedInputPin Class

Notifies the pin that the filter has changed state from stopped to paused.

HRESULT Run(
REFERENCE_TIME tStart
);

Parameters
tStart
Start time. Unreferenced by this class; for possible use by the derived class.
Return Values

Returns an HRESULT value (S_OK by default).

Remarks

This member function overrides the CBasePin::Run member function. It sends the EC_COMPLETE notification to the filter graph manager if m_bAtEndOfStream is TRUE.


CRendererInputPin Class

CRendererInputPin class hierarchy

This input pin class channels calls to the rendering filter.

Protected Data Members
Name | Description
m_pRenderer | Pointer to the CBaseRenderer object.

Member Functions
Name | Description
Allocator | Retrieves a pointer to the default memory allocator.
CRendererInputPin | Constructs a CRendererInputPin object.

Overridable Member Functions
Name | Description
Active | Switches the pin to the active (paused or running) mode.
BeginFlush | Informs the pin to begin a flush operation.
BreakConnect | Adds customized code upon breaking a connection.
CheckMediaType | Determines if the pin can support a specific media type.
CompleteConnect | Completes the connection.
EndFlush | Informs the pin to end a flush operation.
EndOfStream | Informs the pin that no additional data is expected until a new run command is issued.
Inactive | Switches the pin to an inactive state and releases the memory of the allocator.
Receive | Returns the next block of data from the stream.
SetMediaType | Sets the media type of the pin.

Implemented IPin Methods
Name | Description
QueryId | Retrieves an identifier for the pin.

CRendererInputPin::Active

CRendererInputPin Class

Switches the pin to the active (paused or running) mode.

HRESULT Active( );

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBasePin::Active and calls the renderer filter's CBaseRenderer::Active member function.

CRendererInputPin::Allocator

CRendererInputPin Class

Retrieves a pointer to the default memory allocator inherited from CBaseInputPin.

IMemAllocator* Allocator( ) const;

Return Values

Returns a pointer to an IMemAllocator interface.

Remarks

The returned pointer is CBaseInputPin::m_pAllocator.

CRendererInputPin::BeginFlush

CRendererInputPin Class

Informs the pin to begin a flush operation.

HRESULT BeginFlush( );

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::BeginFlush method. It overrides CBaseInputPin::BeginFlush and calls the renderer filter's BeginFlush member function before calling the base class implementation.

CRendererInputPin::BreakConnect

CRendererInputPin Class

Override this member function to add customized code upon breaking a connection.

HRESULT BreakConnect( );

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBasePin::BreakConnect and calls the renderer filter's BreakConnect member function before calling the base class implementation.

CRendererInputPin::CheckMediaType

CRendererInputPin Class

Override this member function to determine if the pin can support this specific media type.

HRESULT CheckMediaType(
const CMediaType *pmt
);

Parameters
pmt
Pointer to a media type object that contains the proposed media type.
Return Values

Returns an HRESULT value.

Remarks

This member function is typically called before calling the CRendererInputPin::SetMediaType member function.

This member function overrides CBasePin::CheckMediaType and calls the pure virtual CBaseRenderer::CheckMediaType member function, which must be overridden.

CRendererInputPin::CompleteConnect

CRendererInputPin Class

Override this member function to inform the derived class when the connection process has completed.

HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the connected (receiving) pin.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBasePin::CompleteConnect and calls the renderer filter's CompleteConnect member function before calling the base class implementation.

CRendererInputPin::CRendererInputPin

CRendererInputPin Class

Constructs a CRendererInputPin object.

CRendererInputPin(
CBaseRenderer *pRenderer,
HRESULT *phr,
LPCWSTR Name
);

Parameters
pRenderer
Pointer to the rendering filter in the base class.
phr
Pointer to an HRESULT value.
Name
Pin name.
Return Values

No return value.

CRendererInputPin::EndFlush

CRendererInputPin Class

Informs the pin to end a flush operation.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBaseInputPin::EndFlush and calls the renderer filter's EndFlush member function before calling the base class implementation.

Note that because this is a renderer, it does not pass the flush on downstream.

CRendererInputPin::EndOfStream

CRendererInputPin Class

Informs the pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndOfStream method. It calls CheckStreaming to see that the filter is in a streaming state and then calls the CBaseRenderer::EndOfStream member function.

CRendererInputPin::Inactive

CRendererInputPin Class

Informs the pin that it is going into the inactive state.

HRESULT Inactive(void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBaseInputPin::Inactive. It calls the renderer filter's CBaseRenderer::Inactive member function, which returns NOERROR by default.

CRendererInputPin::QueryId

CRendererInputPin Class

Retrieves an identifier for the pin.

HRESULT QueryId(
LPWSTR *Id
);

Parameters
Id
Pin identifier.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryId method. It overrides the CBasePin::QueryId member function and assigns the string "In" to Id. Note that it uses the Microsoft® Win32® CoTaskMemAlloc function to initialize Id, so the user is responsible for freeing the format block by using CoTaskMemFree.

CRendererInputPin::Receive

CRendererInputPin Class

Returns the next block of data from the stream.

HRESULT Receive(
IMediaSample *pMediaSample
);

Parameters
pMediaSample
Media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::Receive method, and it overrides the CBaseInputPin::Receive member function, which it calls to verify formats.

This is a blocking synchronous member function. It blocks and waits until it is time for the sample to be rendered. (It calls CBaseRenderer::Receive, which actually does the blocking.) Because only one sample is ever outstanding, this member function checks the media type and calls CRendererInputPin::SetMediaType to change the pin's media type if the sample's type has changed.

Call the IUnknown::AddRef method if you must hold the returned data block beyond the completion of the CRendererInputPin::Receive member function. If you call AddRef, be sure to call the IUnknown::Release method upon completion of AddRef.

CRendererInputPin::SetMediaType

CRendererInputPin Class

Override this member function to set the media type of the pin.

HRESULT SetMediaType(
const CMediaType *pmt
);

Parameters
pmt
Pointer to a media type object that was previously agreed upon.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides CBasePin::SetMediaType and calls the renderer filter's SetMediaType member function, which returns NOERROR by default, after calling the base class implementation.


CRendererPosPassThru Class

CRendererPosPassThru class hierarchy

The IMediaSeeking interface is used to seek to a specific sample, frame, or indexed field. These values are indicated by a whole number, such as frame 20 of a sequence of 530. However, when asked for a reference start or end time (in seconds), the sample must have this information previously set. The CRendererPosPassThru class, implemented on the video renderer, performs this service because the renderer is responsible for keeping track of reference time and stream time.

Member Functions
Name | Description
CRendererPosPassThru | Constructs a CRendererPosPassThru object.
GetMediaTime | Returns the media start and end times registered in the object.
RegisterMediaTime | Registers the media start and end times with the object.
ResetMediaTime | Resets the object's media start and end times.

CRendererPosPassThru::CRendererPosPassThru

CRendererPosPassThru Class

Constructs a CRendererPosPassThru object.

CRendererPosPassThru(
const TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT * phr,
IPin * pPin
);

Parameters
pName
Name of the object used in the CRendererPosPassThru constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for resulting information.
pPin
Pointer to the input pin for the filter.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CRendererPosPassThru::GetMediaTime

CRendererPosPassThru Class

Retrieves the current media start and end times registered in the object.

HRESULT GetMediaTime(
LONGLONG* pStartTime,
LONGLONG* pEndTime
);

Parameters
pStartTime
Returned starting media time.
pEndTime
Returned ending media time.
Return Values

Returns an HRESULT value from the call to CPosPassThru::ConvertTimeFormat for the start and end times.

Remarks

This member function returns the media times set by the CRendererPosPassThru::RegisterMediaTime member function. The starting media time is always returned. Set pEndTime to a nonzero value to retrieve the ending media time.

CRendererPosPassThru::RegisterMediaTime

CRendererPosPassThru Class

Registers the media start and end times with the object.

HRESULT RegisterMediaTime(
IMediaSample *pMediaSample
),

HRESULT RegisterMediaTime(
LONGLONG pStartTime,
LONGLONG pEndTime
);

Parameters
pMediaSample
IMediaSample object containing the media times.
pStartTime
Returned starting media time.
pEndTime
Returned ending media time.
Return Values

Returns VFW_E_MEDIA_TIME_NOT_SET if the sample does not have its media times set. Otherwise, returns and HRESULT from the call to IMediaSample::GetTime.

CRendererPosPassThru::ResetMediaTime

CRendererPosPassThru Class

Resets the object's media start and end times.

HRESULT ResetMediaTime(void);

Return Values

Returns NOERROR.

Remarks

Sets the start and stop times to zero.


CSource Class

CSource class hierarchy

This class and its corresponding class, CSourceStream, simplify the construction of source filters that produce continuous streams of data comparable to the way the CTransformFilter class assists in the creation of transform filters.

The CSource class provides a wrapper for the CBaseFilter class that performs the pin management and works with the CSourceStream class to provide the pins.

To use the CSource class to build a filter:

  • Derive your filter-level class from the CSource class. Provide a CreateInstance member function in it to create a new object of the class.
  • Provide a means of adding objects that are derived from the CSourceStream class to support the output pins during construction of the class. You can either create them yourself during construction or provide the developer with a means of creating them later.

For an example of using the CSource class, see the Ball sample in the \Samples\DS\Ball directory of the Microsoft® DirectShow™ SDK Software Development Kit (SDK).

This class does not help build an asynchronous file reader source filter, which requires support of an IAsyncReader interface and a downstream parser filter that supports the CPullPin class.

Protected Data Members
Name | Description
m_cStateLock | Locks this data member to serialize access to the filter state.
m_iPins | Number of pins on this filter; updated by the CSource::AddPin and CSource::RemovePin member functions.
m_paStreams | Array of streams associated with this filter.

Member Functions
Name | Description
AddPin | Adds a pin to the source filter.
CSource | Constructs a CSource object.
FindPinNumber | Retrieves the number of the pin through the IPin parameter.
GetPin | Returns a pointer to a specified pin.
GetPinCount | Gets the number of pins contained by the filter.
pStateLock | Returns a pointer to the filter-critical section.
RemovePin | Removes a pin from the source filter.

Implemented IBaseFilter Methods
Name | Description
FindPin | Retrieves a pointer to the pin with the specified identifier.

CSource::AddPin

CSource Class

Adds a pin to the source filter.

HRESULT AddPin(
CSourceStream * pStream
);

Parameters
pStream
Pointer to the CSourceStream object associated with the pin.
Return Values

Returns S_OK if successful, or E_OUTOFMEMORY if no memory is available.

CSource::CSource

CSource Class

Initializes the CSource object.

CSource(
TCHAR *pName,
LPUNKNOWN lpunk,
CLSID clsid
);

Parameters
pName
Debugging name of this object.
lpunk
Controlling IUnknown passed to the derived class's CreateInstance function.
clsid
Class identifier of the filters.
Return Values

No return value.

Remarks

The derived class could create the pins here, unless it provides a means for the developer to do this.

CSource::FindPinNumber

CSource Class

Retrieves the number of the pin supporting a given IPin interface.

int FindPinNumber(
IPin *iPin
);

Parameters
iPin
IPin interface of the pin to retrieve.
Return Values

Returns the pin number or –1 if no matching pin number is found.

CSource::GetPin

CSource Class

Returns a pointer to the specified pin.

CBasePin *GetPin(
int n
);

Parameters
n
Pin number of the requested pin.
Return Values

Returns the pointer to the pin or NULL if the index is out of range.

Remarks

This member function is specified in CBaseFilter and is implemented here. Note that this pin interface will not have been reference counted when obtained.

CSource::GetPinCount

CSource Class

Retrieves the number of pins contained by the filter.

int GetPinCount(void);

Return Values

Returns the pin count.

Remarks

This member function is specified in CBaseFilter and is implemented here.

CSource::pStateLock

CSource Class

Retrieves a pointer to the filter-critical section.

CCritSec* pStateLock(void);

Return Values

Returns the critical section.

Remarks

Locking consists of holding the filter-critical section by calling the pStateLock member function and using the returned object to serialize access to functions. Typically, this lock can be held by a function when the worker thread might want to hold it. Therefore, to access a shared state from the worker thread, add another critical-section object. The exception occurs during the processing loop of the thread when it is safe to retrieve the filter-critical section from within CSourceStream::FillBuffer.

CSource::RemovePin

CSource Class

Removes a pin from the source filter.

HRESULT RemovePin(
CSourceStream * pStream
);

Parameters
pStream
CSourceStream object associated with the pin.
Return Values

Returns S_OK if successful or S_FALSE if unsuccessful.

Remarks

The pStream parameter is not deleted. This member function adjusts pin locations in the m_paStreams array.


CSourcePosition Class

CSourcePosition class hierarchy

CSourcePosition is an abstract class that assists source filters with the implementation of IMediaPosition methods.

Derive from this class and set the duration and default stop positions. This class supports IMediaPosition, and calls the pure virtual member functions CSourcePosition::ChangeStart, CSourcePosition::ChangeStop, and CSourcePosition::ChangeRate when CSourcePosition::put_CurrentPosition, CSourcePosition::put_StopTime, or CSourcePosition::put_Rate is called, to allow a source filter to handle these commands and start sending new data.

Override the CSourcePosition::ChangeStart, CSourcePosition::ChangeStop, and CSourcePosition::ChangeRate member functions to do something when the properties change.

Protected Data Members
Name | Description
m_Duration | Duration of the stream.
m_pLock | Pointer to a CCritSec object for locking.
m_Rate | Sample rate.
m_Start | Start time.
m_Stop | Stop time.

Member Functions
Name | Description
CSourcePosition | Constructs a CSourcePosition object.

Overridable Member Functions
Name | Description
ChangeRate | Override this pure virtual to handle notification that the rate property has changed.
ChangeStart | Override this pure virtual to handle notification that the start position property has changed.
ChangeStop | Override this pure virtual to handle notification that the stop position property has changed.

Implemented IMediaPosition Methods
Name | Description
get_CurrentPosition | Not currently implemented.
get_Duration | Retrieves the total duration of the media.
get_PrerollTime | Not currently implemented.
get_Rate | Retrieves the playback rate, relative to normal playback of the media.
get_StopTime | Retrieves the position within the media at which playback should stop.
put_CurrentPosition | Sets the position within the media at which playback should start.
put_PrerollTime | Not currently implemented.
put_Rate | Sets the playback rate, relative to normal playback of the media.
put_StopTime | Sets the position within the media at which playback should stop.

CSourcePosition::ChangeRate

CSourcePosition Class

Override this member function to handle notification of a change of sample rate.

virtual HRESULT ChangeRate( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a change to the rate has been made by a call to IMediaPosition::put_Rate. Override this and change the rate of data sent; typically, this will be by a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then sending samples marked with new time stamps.

CSourcePosition::ChangeStart

CSourcePosition Class

Override this member function to handle notification of a change of start time.

virtual HRESULT ChangeStart( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a new start position has been requested by a call to IMediaPosition::put_CurrentPosition. Override this and change the data sent; typically, this will be by a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then sending samples marked with new time stamps.

CSourcePosition::ChangeStop

CSourcePosition Class

Override this member function to handle notification of a change in stop time.

virtual HRESULT ChangeStop( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a change to the stop position has been made by a call to IMediaPosition::put_StopTime. Override this and ensure that the correct stop time is being observed; typically, this will be a call to CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then resending data.

CSourcePosition::CSourcePosition

CSourcePosition Class

Constructs a CSourcePosition object.

CSourcePosition(
const TCHAR * pName,
LPUNKNOWN pUnk,
HRESULT * phr,
CCritSec * pLock
);

Parameters
pName
Name of the object used in the CSourcePosition constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for resulting information.
pLock
Pointer to a CCritSec object used for locking.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CSourcePosition::get_CurrentPosition

CSourcePosition Class

Currently not implemented.

HRESULT get_CurrentPosition(
REFTIME* pllTime
);

Parameters
pllTime
Returned start time as a double value in seconds.
Return Values

Returns E_NOTIMPL.

Remarks

Override this method if you can return the data you are actually working on. The start position is applied before the rate and therefore is the position at typical playback speed.

CSourcePosition::get_Duration

CSourcePosition Class

Retrieves the total duration of the media stream.

HRESULT get_Duration(
REFTIME* plength
);

Parameters
plength
Returned length of the media stream.
Return Values

Returns E_POINTER if pLength is invalid. Otherwise, returns S_OK.

Remarks

The duration assumes normal playback speed; it is therefore unaffected by the rate.

CSourcePosition::get_PrerollTime

CSourcePosition Class

Validates the pointer, but the preroll retrieval is not currently implemented.

HRESULT get_PrerollTime(
REFTIME* pllTime
);

Parameters
pllTime
Returned preroll time as a double value in seconds.
Return Values

Returns E_POINTER if pllTime is invalid. Otherwise, returns E_NOTIMPL.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

CSourcePosition::get_Rate

CSourcePosition Class

Retrieves the rate of playback relative to normal playback speed.

HRESULT get_Rate(
double * pdRate
);

Parameters
pdRate
Returned rate.
Return Values

Returns E_POINTER if pdRate is invalid. Otherwise, returns S_OK.

Remarks

A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.

CSourcePosition::get_StopTime

CSourcePosition Class

Retrieves the time at which the media stream stops.

HRESULT get_StopTime(
REFTIME* pllTime
);

Parameters
pllTime
Returned stop time as a double value in seconds.
Return Values

Returns E_POINTER if pllTime is invalid. Otherwise, returns S_OK.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

CSourcePosition::put_CurrentPosition

CSourcePosition Class

Sets the time within the media stream that playback should begin.

HRESULT put_CurrentPosition(
REFTIME llTime
);

Parameters
llTime
Start time expressed as a double value in seconds.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeStart.

Remarks

The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued.

Setting the start position when paused causes playback to resume from the new start position when the run command is issued.

The start position is applied before the rate and therefore is the position at typical playback speed.

CSourcePosition::put_PrerollTime

CSourcePosition Class

Not currently implemented.

HRESULT put_PrerollTime(
REFTIME llTime
);

Parameters
llTime
Preroll time to be set.
Return Values

Returns E_NOTIMPL.

Remarks

Preroll time is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

CSourcePosition::put_Rate

CSourcePosition Class

Sets the rate of playback relative to normal speed.

HRESULT put_Rate(
double dRate
);

Parameters
dRate
Rate to set.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeRate.

Remarks

This property allows an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop frames.

Negative rates indicate reverse play. Not all media will support reverse play.

CSourcePosition::put_StopTime

CSourcePosition Class

Sets the time at which the media stream will stop.

HRESULT put_StopTime(
REFTIME llTime
);

Parameters
llTime
Stop time as a double value in seconds.
Return Values

Returns an HRESULT value from the call to CSourcePosition::ChangeStop.

Remarks

The stop time is a position between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.


CSourceSeeking Class

CSourceSeeking class hierarchy

CSourceSeeking is an abstract class that assists source filters with the implementation of IMediaSeeking interface methods. This class enables a source filter to handle calls that change the start and stop positions in the media stream and the playback rate.

Derive from this class and set the positions. This class supports IMediaSeeking, and calls the pure virtual member functions CSourceSeeking::ChangeStart, CSourceSeeking::ChangeStop, and CSourceSeeking::ChangeRate when CSourceSeeking::SetPositions or CSourceSeeking::SetRate is called, to enable a source filter to handle these commands and start sending new data.

Override the CSourceSeeking::ChangeStart, CSourceSeeking::ChangeStop, and CSourceSeeking::ChangeRate member functions to do something when the properties change.

Protected Data Members
Name | Description
m_dRateSeeking | Playback rate. Set to 1 by default.
m_dwSeekingCaps | Seeking capabilities returned in the GetCapabilities function. Can be one or more of the following values: AM_SEEKING_CanSeekForwards, AM_SEEKING_CanSeekBackwards, AM_SEEKING_CanSeekAbsolute, AM_SEEKING_CanGetStopPos, AM_SEEKING_CanGetDuration. Set to all of these by default.
m_pLock | Pointer to a CCritSec object for locking.
m_rtDuration | Duration of the stream. Set to m_rtStop by default.
m_rtStart | Start time. Set to zero by default.
m_rtStop | Stop time. Set to the largest positive 64-bit integer possible (9223372036854775807) by default.

Member Functions
Name | Description
CSourceSeeking | Constructs a CSourceSeeking object.

Overridable Member Functions
Name | Description
ChangeRate | Override this pure virtual to handle notification of a change of sample rate.
ChangeStart | Override this pure virtual to handle notification of a change of start time.
ChangeStop | Override this pure virtual to handle notification of a change in stop time.

Implemented IMediaSeeking Methods
Name | Description
CheckCapabilities | Checks that all requested capabilities are in m_dwSeekingCaps.
ConvertTimeFormat | Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently available.
GetAvailable | Retrieves the range of seeking times. Earliest is zero and latest is the media stream's duration.
GetCapabilities | Retrieves the current seeking capabilities in m_dwSeekingCaps.
GetCurrentPosition | Not currently implemented.
GetDuration | Retrieves the length of time the media stream will play.
GetPositions | Retrieves the current start and stop position settings.
GetPreroll | Sets the preroll time to zero.
GetRate | Retrieves the current playback rate.
GetStopPosition | Retrieves the position within the media stream at which playback should stop.
GetTimeFormat | Sets the time format to TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
IsFormatSupported | Determines if the requested format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
IsUsingTimeFormat | Determines if the requested format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
QueryPreferredFormat | Sets the preferred time format to TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
SetPositions | Sets current and stop positions, first checking that the seeking options are valid.
SetRate | Sets the playback rate.
SetTimeFormat | Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Retrieves an interface and increments the reference count on the interface.

CSourceSeeking::ChangeRate

CSourceSeeking Class

Override this member function to handle notification of a change of sample rate.

virtual HRESULT ChangeRate( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a change to the rate has been made by a call to the CSourceSeeking::SetRate function. Override this and change the rate of data sent. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new time stamps, for example, with an implementation NewSegment method.

CSourceSeeking::ChangeStart

CSourceSeeking Class

Override this member function to handle notification of a change of start time.

virtual HRESULT ChangeStart( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a new start position has been requested by a call to CSourceSeeking::SetPositions. Override this and change the data sent. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new start time, for example, with an implementation NewSegment method.

CSourceSeeking::ChangeStop

CSourceSeeking Class

Override this member function to handle notification of a change in stop time.

virtual HRESULT ChangeStop( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function is called when a change to the stop position has been made by a call to CSourceSeeking::SetPositions. Override this and ensure that the correct stop time is being observed. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new stop time, for example, with an implementation NewSegment method.

CSourceSeeking::CheckCapabilities

CSourceSeeking Class

Checks that all the requested capabilities are among the flags in m_dwSeekingCaps.

HRESULT CheckCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
Pointer to an AM_SEEKING_CAPABILITIES enumerator containing the desired seeking capabilities flags in m_dwSeekingCaps. This value can be any combination of the following flags:
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanSeekForwards
Return Values

Returns E_POINTER if pCapabilities is not a valid pointer, S_OK if all the requested capabilities in pCapabilities are supported, or S_FALSE if they are not.

CSourceSeeking::ConvertTimeFormat

CSourceSeeking Class

Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently available.

HRESULT ConvertTimeFormat(
LONGLONG * pTarget,
const GUID * pTargetFormat,
LONGLONG Source,
const GUID * pSourceFormat
);

Parameters
pTarget
Time set to Source time if the format is TIME_FORMAT_MEDIA_TIME or NULL.
pTargetFormat
GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.
Source
Time in original format.
pSourceFormat
GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.
Return Values

Returns E_POINTER if pTarget is not a valid pointer, or E_INVALIDARG if pTargetFormat and pSourceFormat are not equal to TIME_FORMAT_MEDIA_TIME or NULL; otherwise, returns S_OK.

CSourceSeeking::CSourceSeeking

CSourceSeeking Class

Constructs a CSourceSeeking object.

CSourceSeeking(
const TCHAR * pName,
LPUNKNOWN pUnk,
HRESULT * phr,
CCritSec * pLock
);

Parameters
pName
Name of the object used in the CSourceSeeking constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for information about the results of creating this object.
pLock
Pointer to a CCritSec object used for synchronization within a process.
Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

CSourceSeeking::GetAvailable

CSourceSeeking Class

Returns the range of seeking times.

HRESULT GetAvailable(
LONGLONG * pEarliest,
LONGLONG * pLatest
);

Parameters
pEarliest
Earliest time that can be seeked to. Set to zero.
pLatest
Latest time that can be seeked to. Set to m_rtDuration.
Return Values

Returns S_OK.

CSourceSeeking::GetCapabilities

CSourceSeeking Class

Retrieves the seeking capabilities of the media stream.

HRESULT GetCapabilities(
DWORD * pCapabilities
);

Parameters
pCapabilities
Set to the seeking capability flags in m_dwSeekingCaps, which can be any combination of the following:
AM_SEEKING_CanGetCurrentPos
AM_SEEKING_CanGetDuration
AM_SEEKING_CanGetStopPos
AM_SEEKING_CanPlayBackwards
AM_SEEKING_CanSeekAbsolute
AM_SEEKING_CanSeekBackwards
AM_SEEKING_CanSeekForwards
Return Values

Returns E_POINTER if pCapabilities is invalid; otherwise, returns S_OK.

CSourceSeeking::GetCurrentPosition

CSourceSeeking Class

Not currently implemented.

HRESULT GetCurrentPosition(
LONGLONG* pCurrent
);

Parameters
pCurrent
Current position in current time format units.
Return Values

Returns E_NOTIMPL.

Remarks

This function is typically supported only in renderers and not in source filters.

CSourceSeeking::GetDuration

CSourceSeeking Class

Retrieves the length of time that the media stream will play.

HRESULT GetDuration(
LONGLONG* pDuration
);

Parameters
pDuration
Duration of the media stream set to the value in m_rtDuration.
Return Values

Returns E_POINTER if pDuration is invalid; otherwise, returns S_OK.

Remarks

The duration in m_rtDuration is set to the stop time in m_rtStop. Set the stop time with the CSourceSeeking::SetPositions function.

CSourceSeeking::GetPositions

CSourceSeeking Class

Retrieves the current and stop position settings.

HRESULT GetPositions(
LONGLONG * pCurrent,
LONGLONG * pStop
);

Parameters
pCurrent
Current start time set to the value in m_rtStart.
pStop
Current stop time set to the value in m_rtStop.
Return Values

Returns S_OK.

Remarks

The start and stop times are set in the CSourceSeeking::SetPositions function.

CSourceSeeking::GetPreroll

CSourceSeeking Class

Sets the preroll time to zero.

HRESULT GetPreroll(
LONGLONG * pPreroll
);

Parameters
pPreroll
Returned preroll time of zero.
Return Values

Returns E_POINTER if pPreroll is invalid; otherwise, returns S_OK.

CSourceSeeking::GetRate

CSourceSeeking Class

Retrieves the current playback rate.

HRESULT GetRate(
double * pdRate
);

Parameters
pdRate
Returned playback rate set to the value in m_dRateSeeking, where 1 is the normal rate.
Return Values

Returns E_POINTER if pdRate is invalid; otherwise, returns S_OK.

Remarks

Set the rate in the CSourceSeeking::SetRate function.

CSourceSeeking::GetStopPosition

CSourceSeeking Class

Retrieves the position within the media stream at which playback should stop.

HRESULT GetStopPosition(
LONGLONG* pStop
);

Parameters
pStop
Returned stop time set to the value in m_rtStop.
Return Values

Returns E_POINTER if pStop is invalid; otherwise, returns S_OK.

Remarks

Set the stop time in the CSourceSeeking::SetPositions function.

CSourceSeeking::GetTimeFormat

CSourceSeeking Class

Sets the time format to TIME_FORMAT_MEDIA_TIME, which determines the format of units used during seeking.

HRESULT GetTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Media time format set to TIME_FORMAT_MEDIA_TIME.
Return Values

Returns E_POINTER if pFormat is invalid; otherwise, returns S_OK.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.

CSourceSeeking::IsFormatSupported

CSourceSeeking Class

Determines if the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT IsFormatSupported(
const GUID * pFormat
);

Parameters
pFormat
Time format to compare to TIME_FORMAT_MEDIA_TIME.
Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or S_FALSE if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported. As implemented, this function is the same as CSourceSeeking::IsUsingTimeFormat.

CSourceSeeking::IsUsingTimeFormat

CSourceSeeking Class

Determines if the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT IsUsingTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Time format to compare to TIME_FORMAT_MEDIA_TIME.
Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or S_FALSE if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported. As implemented, this method is the same as CSourceSeeking::IsFormatSupported.

CSourceSeeking::NonDelegatingQueryInterface

CSourceSeeking Class

Retrieves an interface and increments the reference count on the interface.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IMediaSeeking and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

CSourceSeeking::QueryPreferredFormat

CSourceSeeking Class

Sets the preferred time format to TIME_FORMAT_MEDIA_TIME.

HRESULT QueryPreferredFormat(
GUID *pFormat
);

Parameters
pFormat
Time format set to TIME_FORMAT_MEDIA_TIME.
Return Values

Returns E_POINTER if pFormat is invalid; otherwise, returns S_OK.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.

CSourceSeeking::SetPositions

CSourceSeeking Class

Sets current and stop positions, first checking that the seeking options are valid.

HRESULT SetPositions(
LONGLONG * pCurrent,
DWORD CurrentFlags,
LONGLONG * pStop,
DWORD StopFlags
);

Parameters
pCurrent
Start position if stopped, or position to continue from if paused.
CurrentFlags
Flags that indicate the type of seek. Valid values are AM_SEEKING_AbsolutePositioning and AM_SEEKING_RelativePositioning. See the IMediaSeeking::SetPositions method for a description of these flags.
pStop
Position in the stream at which to quit playback.
StopFlags
Flags that indicate stop position seeking options. Valid values are AM_SEEKING_AbsolutePositioning, AM_SEEKING_RelativePositioning, and AM_SEEKING_IncrementalPositioning. See the IMediaSeeking::SetPositions method for a description of these flags.
Return Values

Returns E_INVALIDARG if CurrentFlags and StopFlags are not one of the values listed, or E_POINTER if pCurrent or pStop is invalid; otherwise, returns the HRESULT returned by calls to the CSourceSeeking::ChangeStart and CSourceSeeking::ChangeStop functions.

Remarks

You must implement ChangeStart and ChangeStop to use this method.

See Also

CSourceSeeking::GetPositions, CSourceSeeking::GetStopPosition, CSourceSeeking::GetDuration

CSourceSeeking::SetRate

CSourceSeeking Class

Sets a new playback rate.

HRESULT SetRate(
double dRate
);

Parameters
dRate
New rate, where 1.0 is the normal normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop samples. A rate of 0.5 specifies half speed.
Return Values

Returns the HRESULT value returned by the call to the CSourceSeeking::ChangeRate function.

Remarks

You must implement ChangeRate to use this method. The m_dRateSeeking data member is set to the new rate. Setting the rate to zero causes an error.

See Also

CSourceSeeking::GetRate

CSourceSeeking::SetTimeFormat

CSourceSeeking Class

Checks that the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT SetTimeFormat(
const GUID * pFormat
);

Parameters
pFormat
Time format to compare to TIME_FORMAT_MEDIA_TIME.
Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or E_INVALIDARG if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.


CSourceStream Class

CSourceStream class hierarchy

Derive from this class to provide a class that creates the data stream from one of the output pins. It should be used with an object that is derived from the CSource class derived object to provide the filter-level object.

The CSourceStream class creates a worker thread to push data downstream when the filter enters a paused or running state. The thread first calls the CSourceStream::OnThreadCreate member function. If this succeeds, it will loop, calling the CSourceStream::FillBuffer member function until the CSourceStream::Inactive member function stops it. As the thread quits, it calls the CSourceStream::OnThreadDestroy member function. If OnThreadCreate fails, OnThreadDestroy is called, and the active member function will fail.

To use the CSourceStream class, supporting a single media type, carry out the following steps.

  1. Override the CSourceStream::GetMediaType member function to report the supported output format.
  2. Override the CSourceStream::FillBuffer member function with a means of filling out each IMediaSample object with data.

To use the CSourceStream class, supporting multiple media types, carry out the following.

  1. Override the CSourceStream::CheckMediaType and CSourceStream::GetMediaType member functions to report the supported media types (for more information, see the CBaseMediaFilter class).
  2. Override the CSourceStream::FillBuffer member function with a means of filling out each IMediaSample object with data.

See SAMPLES\DS\BALL in the Microsoft® DirectShow™ SDK Software Development Kit (SDK) for an example of a pin supporting multiple types.

If you want more complex management of your worker thread, you can override most of the associated member functions. See Samples\DS\Vidcap in the Microsoft DirectX Media Software Development Kit (SDK) for an example.

Member Functions
Name | Description
Active | Called by the CBaseMediaFilter class to start the worker thread.
CheckRequest | Determines if a command is waiting for the thread.
CSourceStream | Constructs a CSourceStream object.
Exit | Called by the CSourceStream::Inactive member function to exit the worker thread.
GetRequest | Retrieves the next command for the thread.
Inactive | Called by the CBaseMediaFilter member function to shut down the worker thread.
Init | Called by the CSourceStream::Active member function to initialize the worker thread.
Pause | Pauses the stream of the worker thread. This will acquire all necessary resources.
Run | Starts the worker thread generation of a media sample stream.
Stop | Stops the stream.

Overridable Member Functions
Name | Description
CheckMediaType | Determines if a specific media type is supported. Override this member function if you use multiple types.
DoBufferProcessingLoop | Loops, collecting a buffer and calling the CSourceStream::FillBuffer processing function.
FillBuffer | Override this member function to fill the stream buffer during the creation of a media sample.
GetMediaType | Retrieves the media type or types that this pin supports; override the appropriate version of this member function to support one or multiple media types.
OnThreadCreate | Called as the worker thread is created; override this member function for special processing.
OnThreadDestroy | Called during the destruction of a worker thread; override this member function for special processing.
OnThreadStartPlay | Called at the start of processing Pause or Run command; override this member function for special processing.
ThreadProc | Override this member function to create a custom thread procedure.

Implemented IPin Methods
Name | Description
QueryId | Retrieves an identifier for the pin.

CSourceStream::Active

CSourceStream Class

Starts the worker thread.

HRESULT Active(void);

Return Values

Returns an HRESULT, which can be one of the following:
Value | Meaning
E_FAIL | Thread could not start.
S_FALSE | Pin is already active.
S_OK | Thread was started successfully.

CSourceStream::CheckMediaType

CSourceStream Class

Determines if this pin supports the supplied media type.

virtual HRESULT CheckMediaType(
CMediaType *pMediaType
);

Parameters
pMediaType
Media type to check.
Return Values

Returns S_OK if the media type is supported, S_FALSE if it isn't, or E_INVALIDARG if pMediaType is invalid.

Remarks

Override this member function if you support multiple media types. Test explicitly for S_OK to determine if this function succeeded; do not use the SUCCEEDED macro.

CSourceStream::CheckRequest

CSourceStream Class

Determines if a command is waiting for the thread.

BOOL CheckRequest(
Command *pCom
);

Parameters
pCom
Pointer to the location to which to return a command, if any.
Return Values

Returns TRUE if the pCom parameter contains a command; otherwise, returns FALSE.

Remarks

This member function does not block. This is a type safe override of the method in the CAMThread class.

CSourceStream::CSourceStream

CSourceStream Class

Creates a CSourceStream object.

CSourceStream(
TCHAR *pObjectName,
HRESULT *phr,
CSource *pms,
LPCWSTR pName
);

Parameters
pObjectName
Name of the object.
phr
Resulting value for this constructor.
pms
Pointer for the CSource object.
pName
Name of the pin.
Return Values

No return value.

CSourceStream::DoBufferProcessingLoop

CSourceStream Class

Loops, collecting a buffer and calling the CSourceStream::FillBuffer processing function.

virtual HRESULT DoBufferProcessingLoop(void);

Return Values

Returns an HRESULT value.

CSourceStream::Exit

CSourceStream Class

Causes the thread to exit.

HRESULT Exit(void);

Return Values

Returns NOERROR if the member function was received.

Remarks

If the thread returns an error, it sets the return value of the CSourceStream::ThreadProc member function.

CSourceStream::FillBuffer

CSourceStream Class

Fills the stream buffer during the creation of a media sample that the current pin provides.

virtual HRESULT FillBuffer(
IMediaSample *pSample
) PURE;

Parameters
pSample
IMediaSample buffer to contain the data.
Return Values

Returns an HRESULT value.

Remarks

The CSourceStream::ThreadProc member function calls the CSourceStream::FillBuffer member function. The derived class must supply an implementation of this member function.

CSourceStream::GetMediaType

CSourceStream Class

Fills out the fields of the CMediaType object to the supported media type.

virtual HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
);

virtual HRESULT GetMediaType(
CMediaType *pMediaType
);

Parameters
iPosition
Position of the media type within a list of multiple media types. Range is zero through n.
pMediaType
Pointer to a CMediaType object to be set to the requested format.
Return Values

Returns one of the following HRESULT values.
Value | Meaning
Error Code | Media type could not be set.
S_FALSE | Media type exists but is not currently usable.
S_OK | Media type was set.
VFW_S_NO_MORE_ITEMS | End of the list of media types has been reached.

Remarks

This member function sets the requested media type. If only a single media type is supported, override this member function with the single-parameter definition. Only the default implementations of the CSourceStream::CheckMediaType and CSourceStream::GetMediaType member functions call the single media type member function.

Override the single-version GetMediaType or the two-parameter version, CheckMediaType.

CSourceStream::GetRequest

CSourceStream Class

Retrieves the next command for the thread.

Command GetRequest(void);

Return Values

Returns the next command.

Remarks

This member function blocks until a command is available. It is a type safe override of the member function in the CAMThread class.

CSourceStream::Inactive

CSourceStream Class

Identifies a pin as inactive and shuts down the worker thread.

HRESULT Inactive(void);

Return Values

Returns an HRESULT value, including the following values.
Value | Meaning
S_OK | Thread exited successfully.
S_FALSE | Pin is already inactive.

CSourceStream::Init

CSourceStream Class

Initializes the worker thread.

HRESULT Init(void);

Return Values

Returns an HRESULT value, including the following values.
Value | Meaning
S_OK | Thread was initialized successfully.
S_FALSE | Thread was already initialized.

Remarks

The CSourceStream::Active member function calls this member function.

CSourceStream::OnThreadCreate

CSourceStream Class

Starts or stops a process upon the creation of a thread.

virtual HRESULT OnThreadCreate(void);

Return Values

Returns an HRESULT value, including the following values.
Value | Meaning
NOERROR | No error occurred.
Error code | Thread should exit.

CSourceStream::OnThreadDestroy

CSourceStream Class

Starts or stops a process upon the destruction of a thread.

virtual HRESULT OnThreadDestroy(void);

Return Values

Returns either NOERROR or an HRESULT value (greater than zero) that indicates an error.

CSourceStream::OnThreadStartPlay

CSourceStream Class

Starts a process upon the beginning of the playing of the thread.

virtual HRESULT OnThreadStartPlay(void);

Return Values

Default implementation returns NOERROR.

CSourceStream::Pause

CSourceStream Class

Pauses a media sample stream.

HRESULT Pause(void);

Return Values

Returns an HRESULT value, including the following value.
Value | Meaning
S_OK | Thread paused successfully.

CSourceStream::Run

CSourceStream Class

Starts a media sample stream.

HRESULT Run(void);

Return Values

Returns S_OK if successful; otherwise, returns an HRESULT error value.

CSourceStream::Stop

CSourceStream Class

Stops a media sample stream.

HRESULT Stop(void);

Return Values

Returns S_OK if successful; otherwise, returns an HRESULT error value.

CSourceStream::ThreadProc

CSourceStream Class

Implements the thread procedure.

virtual DWORD ThreadProc(void);

Return Values

Returns 0 if the thread completed successfully and 1 otherwise. If 1, the thread's resources might still be allocated.

Remarks

When this member function returns, the thread exits. Override this member function if the provided version is not sophisticated enough.


CSystemClock Class

CSystemClock class hierarchy

The CSystemClock class implements a system clock that provides time information and timing signals to an application. It uses the CBaseReferenceClock base class to provide most of that functionality, adding persistence.

CSystemClock implements the IPersist interface. For more implementation information, see "OLE Programmers Reference (Vol. 1): Structured Storage Overview."

Member Functions
Name | Description
CreateInstance | Creates an instance of a system clock.
CSystemClock | Constructs a CSystemClock object.

Implemented IPersist Methods
Name | Description
GetClassID | Returns the class identifier for this clock (CLSID_SystemClock).

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Passes out pointers to IID_IPersist, and calls the base clock for other interface queries.

CSystemClock::CreateInstance

CSystemClock Class

Creates a new instance when placed in the factory template table.

static CUnknown * WINAPI CreateInstance(
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pUnk
Pointer to LPUNKNOWN.
phr
Pointer to an HRESULT value in which to return resulting information.
Return Values

Returns a pointer to a new Component Object Model (COM) object.

Remarks

This member function is required to create objects using the class factory. It calls the class constructor.

The phr parameter will be modified only if a failure occurs. If it is a failure code on input, construction can be terminated, but in any case the destructor will be called by the creator when the HRESULT error is detected.

CSystemClock::CSystemClock

CSystemClock Class

Constructs a CSystemClock object.

CSystemClock(
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

Parameters
pName
Name of this object (used for debugging only).
pUnk
Pointer to the controlling IUnknown interface.
phr
Pointer to the HRESULT value that will be set if an error occurs.
Return Values

No return value.

Remarks

If phr points to something other than S_OK upon entry, the object will not be constructed. If an error occurs during construction, this variable will be set; otherwise, its contents will not be altered.

CSystemClock::GetClassID

CSystemClock Class

Retrieves the class identifier for this clock.

HRESULT GetClassID(
CLSID *pClsID
);

Parameters
pClsID
Pointer to a CLSID structure which is filled with CLSID_SystemClock.
Return Values

Returns an HRESULT value.

CSystemClock::NonDelegatingQueryInterface

CSystemClock Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IReferenceClock, IPersist, and IUnknown interfaces.


CTransformFilter Class

CTransformFilter class hierarchy

CTransformFilter is an abstract base class that supports a simple transform filter with a single input and a single output. It is derived from the CUnknown class, and it supports the IBaseFilter interface. Each pin, declared as Friends in this class, supports the IPin interface and uses the shared memory transport based on the IMemInputPin interface. The filter uses classes derived from the CBaseFilter class to support IBaseFilter; the CTransformInputPin input pin class is derived from the CBaseInputPin class, and the CTransformOutputPin output pin class is derived from the CBaseOutputPin class.

Note that, while most member functions in this class are designed to be overridden, the following pure virtual member functions must be overridden.

  • CheckInputType
  • CheckTransform
  • DecideBufferSize
  • GetMediaType
  • Transform

For more information about using this class to create a transform filter, see Creating a Transform Filter.

Protected Data Members
Name | Description
m_bEOSDelivered | End-of-stream delivery status flag.
m_bQualityChanged | Status flag that indicates if the stream has degraded. This is set to TRUE in CTransformFilter::Receive if the call to the derived class's Transform member function fails (CTransformFilter::Receive returns NOERROR in this case because returning S_FALSE indicates that the end-of-stream has arrived).
m_bSampleSkipped | Status flag that indicates if a frame was skipped.
m_csFilter | Critical section that protects the filter state. This critical section is held whenever the state is currently changing or might change. It is passed to the CBaseMediaFilter constructor so that the base class uses it too.
m_csReceive | Critical section that is held when processing events that occur on the receiving thread (CTransformInputPin::Receive and CTransformInputPin::EndOfStream).
m_idTransform | Identifier used for performance measurement. Available only when PERF is defined.
m_pInput | Pointer to the input pin class object.
m_pOutput | Pointer to the output pin class object.

Member Functions
Name | Description
CTransformFilter | Constructs a CTransformFilter object.

Overridable Member Functions
Name | Description
AlterQuality | Receives a quality-control notification from the output pin and provides an opportunity to alter the media stream's quality.
BeginFlush | Receives notification of entering the flushing state and passes it downstream.
BreakConnect | Informs the derived class when the connection is broken.
CheckConnect | Informs the derived class when the connection process is starting.
CheckInputType | Verifies that the input pin supports the media type and proposes the media type of the output pin (pure virtual).
CheckTransform | Verifies that the input and output pins support the media type (pure virtual).
CompleteConnect | Informs the derived class when the connection process has completed.
DecideBufferSize | Sets the number and size of buffers required for the transfer (pure virtual).
EndFlush | Receives notification of leaving the flushing state and passes it downstream.
EndOfStream | Receives an end-of-stream notification and passes it downstream.
GetMediaType | Returns one of the media types that the output pin supports (pure virtual).
GetPin | Returns the pin for the index specified.
GetPinCount | Returns the number of pins on the filter.
NewSegment | Informs the derived class that a new segment has started and delivers it downstream.
Receive | Receives the media sample, calls the CTransformFilter::Transform member function, and then delivers the media sample.
RegisterPerfId | Registers a performance measurement identifier.
SetMediaType | Informs the derived class when the media type is established for the connection.
StartStreaming | Informs the derived class that streaming is starting.
StopStreaming | Informs the derived class that streaming is ending.
Transform | Performs transform operations, reading from the input IMediaSample interface and writing the data to the output IMediaSample interface (pure virtual).

Implemented IBaseFilter Methods
Name | Description
FindPin | Retrieves the pin with the specified identifier.
Pause | Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class.
Stop | Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class.

CTransformFilter::AlterQuality

CTransformFilter Class

Receives a quality-control notification and provides an opportunity to alter the media stream's quality.

virtual HRESULT AlterQuality(
Quality q
);

Parameters
q
Quality-control notification message.
Return Values

Returns an HRESULT value. S_FALSE means to pass the message to the upstream filter (whether or not any action has been taken). An overriding member function can return NOERROR to indicate that the message has been handled completely (or as completely as possible) and no further action should be taken.

Remarks

This member function returns S_FALSE by default. It is called by the CTransformOutputPin::Notify member function before calling the CBaseInputPin::PassNotify member function to pass the quality control message upstream. If the filter is responsible for affecting the quality of the media stream, override this member function and respond to the quality-notification message.

CTransformFilter::BeginFlush

CTransformFilter Class

Receives notification of entering the flushing state and passes it downstream.

virtual HRESULT BeginFlush( );

Return Values

Returns an HRESULT value.

Remarks

By default, this member function calls the CBaseOutputPin::DeliverEndFlush member function on the output pin to send the BeginFlush notification to the next filter. Override this member function if you are using queued data or a worker thread.

CTransformFilter::BreakConnect

CTransformFilter Class

Informs the derived class when the connection is broken.

virtual HRESULT BreakConnect(
PIN_DIRECTION dir
);

Parameters
dir
Direction of the pin.
Return Values

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

This member function is called by both CTransformInputPin::BreakConnect and CTransformOutputPin::BreakConnect. It returns NOERROR by default. Override this member function to handle special cases in both input and output pin connections. Special cases might typically be releasing interfaces obtained in the CTransformFilter::CheckConnect member function.

CTransformFilter::CheckConnect

CTransformFilter Class

Informs the derived class when the connection process is starting.

virtual HRESULT CheckConnect(
PIN_DIRECTION dir,
IPin *pPin
);

Parameters
dir
Direction of the pin.
pPin
Pointer to the pin making the connection.
Return Values

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

This member function is called by both CTransformInputPin::CheckConnect and CTransformOutputPin::CheckConnect. Override this member function to handle special cases in both input and output pin connections. Special cases might include querying (obtaining) other interfaces.

CTransformFilter::CheckInputType

CTransformFilter Class

Verifies that the input pin supports the media type, and proposes the output pin's media type.

virtual HRESULT CheckInputType(
const CMediaType* mtIn
)
PURE;

Parameters
mtIn
Pointer to an input media type object.
Return Values

The overriding member function returns an HRESULT value.

Remarks

You must override this member function to verify the media type. This member function must return an error if it cannot support the media type as an input. If it can, the overriding member function should propose the output media type supplied by the output pin.

CTransformFilter::CheckTransform

CTransformFilter Class

Verifies that the input and output pins support the media type.

virtual HRESULT CheckTransform(
const CMediaType* mtIn,
const CMediaType* mtOut
) PURE;

Parameters
mtIn
Pointer to the input media type object.
mtOut
Pointer to the output media type object.
Return Values

The overriding member function returns an HRESULT value.

Remarks

The derived class must implement this member function by overriding it. It should return an error if the filter cannot accept these types as its input and output types.

CTransformFilter::CompleteConnect

CTransformFilter Class

Informs the derived class when the connection process has completed.

virtual HRESULT CompleteConnect(
PIN_DIRECTION direction,
IPin *pReceivePin
);

Parameters
direction
Pin direction.
pReceivePin
Pointer to the output pin that is being connected to.
Return Values

Returns an HRESULT value.

Remarks

This member function is called by both CTransformInputPin::CompleteConnect and CTransformOutputPin::CompleteConnect. It returns NOERROR by default. Override this member function to handle special cases in both input and output pin connections.

CTransformFilter::CTransformFilter

CTransformFilter Class

Constructs a CTransformFilter object.

CTransformFilter(
TCHAR * pObjectName,
LPUNKNOWN lpUnk,
CLSID clsid
);

Parameters
pObjectName
Name given to the CTransformFilter object.
lpUnk
Pointer to LPUNKNOWN.
clsid
Class identifier of the CTransformFilter class.
Return Values

No return value.

Remarks

The constructor of the derived class calls this member function. The pin objects are not created at this time; they are created when calling the CTransformFilter::GetPin member function. Thus the pins (m_pInput and m_pOutput) cannot be referred to in the constructor unless GetPin is first called. (An external object can find pins only by enumerating them or by calling IBaseFilter::FindPin. These each call GetPin, so the pins are, in fact, created as soon as they are needed.)

CTransformFilter::DecideBufferSize

CTransformFilter Class

Sets the number and size of buffers required for the transfer.

virtual HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * ppropInputRequest
) PURE;

Parameters
pAlloc
Allocator assigned to the transfer.
ppropInputRequest
Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.
Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CTransformOutputPin::DecideBufferSize member function. Override and implement this member function to call the CMemAllocator::SetProperties member function with appropriate values for the output stream. This call might fail if the allocator cannot satisfy the request.

CTransformFilter::EndFlush

CTransformFilter Class

Receives notification of leaving the flushing state and passes it downstream.

virtual HRESULT EndFlush( );

Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CTransformInputPin::EndFlush member function. Override this member function if you are using queued data or a worker thread. It calls CBaseOutputPin::DeliverEndFlush to deliver the notification downstream.

CTransformFilter::EndOfStream

CTransformFilter Class

Receives an end-of-stream notification and passes it downstream.

virtual HRESULT EndOfStream( );

Return Values

Returns an HRESULT value.

Remarks

By default, this member function calls the CBaseOutputPin::DeliverEndOfStream member function on the output pin to send the end-of-stream notification to the next filter. Override this member function if you are using queued data or a worker thread. If you overrode CTransformFilter::Receive and have queued data, you must handle this condition and deliver EOS after all queued data is sent.

CTransformFilter::FindPin

CTransformFilter Class

Retrieves the pin with the specified identifier.

HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);

Parameters
Id
Identifier of the pin.
ppPin
Pointer to the IPin interface for this pin after the filter has been restored.
Return Values

Returns NOERROR if the pin name was found; otherwise, returns VFW_E_NOT_FOUND.

Remarks

This member function overrides the CBaseFilter::FindPin member function. If the Id parameter is "In", it retrieves the input pin's IPin pointer; if the Id parameter is "Out", it retrieves the output pin's IPin pointer.

The ppPin parameter is set to NULL if the identifier cannot be matched.

CTransformFilter::GetMediaType

CTransformFilter Class

Returns one of the media types that the output pin supports (pure virtual).

virtual HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
) PURE;

Parameters
iPosition
Position of the media type in the media type list.
pMediaType
Returned media type object.
Return Values

Returns an HRESULT value by the overriding member function. It returns VFW_S_NO_MORE_ITEMS when asked for a media type beyond the position list. It might return S_FALSE to indicate that the media type exists but is not currently usable. In this case, the IEnumMediaTypes::Next method skips this media type.

Remarks

The derived class is responsible for implementing this member function and maintaining the list of media types that it supports.

The base transform class assumes that only the output pin proposes media types, because the output pin depends on the type of connection of the input pin. For this reason, it is only the CTransformOutputPin::GetMediaType member function of the output pin that is routed to this function.

CTransformFilter::GetPin

CTransformFilter Class

Returns a pin for a specified index.

virtual CBasePin * GetPin(
int n
);

Parameters
n
Index of the pin to return.
Return Values

Returns a pointer to a CBasePin object.

Remarks

This member function overrides the CBaseFilter::GetPin member function and need not be overridden unless one or more of the transform pin classes (CTransformInputPin or CTransformOutputPin) are overridden. Upon successful return, both pins are valid.

CTransformFilter::GetPinCount

CTransformFilter Class

Returns the number of pins on the filter.

virtual int GetPinCount( );

Return Values

Returns 2. If you override this class to support more pins, this member function returns the total number of pins on the filter.

Remarks

This member function overrides the CBaseFilter::GetPinCount member function. The CTransformFilter class supports only one input pin and one output pin.

CTransformFilter::NewSegment

CTransformFilter Class

Informs the derived class that a new segment has started and delivers it downstream.

virtual HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
Start time of the segment.
tStop
Stop time of the segment.
dRate
Rate of the segment.
Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CTransformInputPin::NewSegment member function and calls the CBaseOutputPin::DeliverNewSegment member function.

CTransformFilter::Pause

CTransformFilter Class

Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class.

HRESULT Pause (void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBaseFilter::Pause member function and implements the IMediaFilter::Pause method. It checks the input and output pin connections, calls CTransformFilter::StartStreaming, and finally calls the base class implementation (CBaseFilter::Pause).

CTransformFilter::Receive

CTransformFilter Class

Receives the media sample, calls the CTransformFilter::Transform member function, and then delivers the media sample.

HRESULT Receive(
IMediaSample *pSample
);

Parameters
pSample
Media sample to receive.
Return Values

Returns an HRESULT value.

Remarks

This member function is called by the CTransformInputPin::Receive member function, which implements the IMemInputPin::Receive method. If you override this member function, you might must also override CTransformFilter::EndOfStream, CTransformFilter::BeginFlush, and CTransformFilter::EndFlush.

CTransformFilter::RegisterPerfId

CTransformFilter Class

Registers a performance measurement identifier.

virtual void RegisterPerfId( );

Return Values

No return value.

Remarks

By default, this member function registers the performance identifier (m_idTransform) with the string "Transform". Override this member function to register a performance measurement with a less generic string. This should be done to avoid confusion with other filters. This member function is enabled only when PERF is defined.

CTransformFilter::SetMediaType

CTransformFilter Class

Informs the derived class when the media type is established for the connection.

virtual HRESULT SetMediaType(
PIN_DIRECTION direction,
const CMediaType *pmt
) PURE;

Parameters
direction
Pin direction.
pmt
Pointer to the media type object.
Return Values

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

Override this member function to detect when the media type is set. The implementations of CTransformInputPin::SetMediaType and CTransformOutputPin::SetMediaType call this member function.

CTransformFilter::StartStreaming

CTransformFilter Class

Informs the derived class that streaming is starting.

virtual HRESULT StartStreaming( );

Return Values

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

The filter is in the process of switching to active mode (paused or running). Alternatively, you can override this member function to allocate any necessary resources.

CTransformFilter::Stop

CTransformFilter Class

Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class.

HRESULT Stop(void);

Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBaseFilter::Stop member function and implements the IMediaFilter::Stop method. It first decommits on the input and output pins by calling CBaseInputPin::Inactive and CBaseOutputPin::Inactive, and then calls CTransformFilter::StopStreaming to inform the derived class.

CTransformFilter::StopStreaming

CTransformFilter Class

Informs the derived class that streaming is ending.

virtual HRESULT StopStreaming( );

Return Values

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

The filter is in the process of leaving active mode and entering stopped mode. Override this member function to free any resources allocated in StartStreaming.

CTransformFilter::Transform

CTransformFilter Class

Performs transform operations of the filter.

virtual HRESULT Transform(
IMediaSample * pIn,
IMediaSample *pOut
) PURE;

Parameters
pIn
Pointer to the input IMediaSample interface.
pOut
Pointer to the output IMediaSample interface.
Return Values

The overriding member function returns an HRESULT value. If it returns S_FALSE, the default implementation of the sample will not be delivered by the default implementation of the CTransformFilter::Receive member function.

Remarks

The CTransformFilter::Receive member function calls this member function, which must be overridden with a member function that implements the transform intended for the filter.

Perform your transform operation in the implementation of this member function, reading the data from the input IMediaSample interface and writing the data to the output IMediaSample interface. The member function returns when the transform is complete, without releasing or delivering either of the samples. Change properties on the output sample if they are not the same as the input sample. For example, change the start and stop time IMediaSample::SetTime), sample status flags (IMediaSample::IsSyncPoint), and so on.


CTransformInputPin Class

CTransformInputPin class hierarchy

The CTransformInputPin class implements the input pin of a simple transform filter. It is the class assigned to the m_pInput data member of the CTransformFilter class. Typically, you can create objects derived from CTransformFilter without modifying the CTransformInputPin class. That is, you can usually override the member functions in CTransformFilter that are called by member functions of this class. This means that you need not derive your own classes for either of the pin classes.

However, if you want to override this class and have your filter class derived from CTransformFilter, you must override the CTransformFilter::GetPin member function to create pins of your derived class.

Protected Data Members
Name | Description
m_pTransformFilter | Pointer to the owning CTransformFilter object.

Member Functions
Name | Description
CTransformInputPin | Constructs a CTransformInputPin object.
CurrentMediaType | Retrieves the media type currently assigned to the filter.

Overridable Member Functions
Name | Description
BreakConnect | Informs the derived class when the connection is broken.
CheckConnect | Informs the derived class when the connection process is starting.
CheckMediaType | Determines if the pin can use a specified media type.
CheckStreaming | Verifies conditions for continuing with a streaming operation.
CompleteConnect | Informs the derived class when the connection process has completed.
SetMediaType | Informs the derived class when the media type is established for the connection.

Implemented IPin Methods
Name | Description
BeginFlush | Informs the pin to begin a flush operation.
EndFlush | Informs the pin to end a flush operation and notifies the pin that it can start accepting data again.
EndOfStream | Informs the input pin that no additional data is expected until a new run command is issued.
NewSegment | Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryId | Retrieves an identifier for the pin.

Implemented IMemInputPin Methods
Name | Description
Receive | Receives the next block of data from the stream.

CTransformInputPin::BeginFlush

CTransformInputPin Class

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::BeginFlush method and overrides the CBaseInputPin::BeginFlush member function. It checks to see if the pin is connected, and then calls CBaseInputPin::BeginFlush, and finally calls the CTransformFilter::BeginFlush member function.

CTransformInputPin::BreakConnect

CTransformInputPin Class

Informs the derived class when the connection is broken.

HRESULT BreakConnect( );

Return Values

Returns NOERROR in this implementation.

Remarks

This member function overrides the CBasePin::BreakConnect member function and calls the CTransformFilter::BreakConnect member function. Override CTransformFilter::BreakConnect to undo anything carried out in CTransformInputPin::CheckConnect (such as releasing extra interfaces).

CTransformInputPin::CheckConnect

CTransformInputPin Class

Informs the derived class when the connection process is starting.

HRESULT CheckConnect(
IPin *pPin
);

Parameters
pPin
Pointer to the IPin interface of the connecting pin.
Return Values

Returns NOERROR by default.

Remarks

This member function overrides the CBasePin::CheckConnect member function and calls the CTransformFilter::CheckConnect member function. Override CTransformFilter::CheckConnect to add additional interfaces.

CTransformInputPin::CheckMediaType

CTransformInputPin Class

Determines if the pin can use a specified media type.

HRESULT CheckMediaType(
const CMediaType* mtIn
);

Parameters
mtIn
Pointer to a media type object.
Return Values

No return value.

Remarks

This member function calls the pure-virtual CTransformFilter::CheckInputType member function, which must be overridden when deriving a class from the CTransformFilter class. The overridden CheckInputType member function is responsible for determining which media types the input pin supports.

CTransformInputPin::CheckStreaming

CTransformInputPin Class

Verifies conditions for continuing with a streaming operation.

HRESULT CheckStreaming( );

Return Values

Returns one of the following HRESULT values, depending on the state.
Value | Meaning
S_FALSE | Currently in flushing state.
S_OK | Receive or EndOfStream operations can safely proceed.
VFW_E_NOT_CONNECTED | The output pin either does not exist or isn't connected.
VFW_E_RUNTIME_ERROR | A run-time error occurred when processing a previous sample.
VFW_E_WRONG_STATE | The filter is in the State_Stopped state.

Remarks

This member function overrides the CBaseInputPin::CheckStreaming member function and calls that base class implementation for most of the condition checks. It determines if the pin is connected, if it is in a paused or running state, and if it is not currently flushing data or processing a run-time error.

CTransformInputPin::CompleteConnect

CTransformInputPin Class

Informs the derived class when the connection process has been completed.

HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the input pin being connected to.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBasePin::CompleteConnect member function. It calls the base class CBasePin::CompleteConnect member function and then calls CTransformFilter::CompleteConnect.

CTransformInputPin::CTransformInputPin

CTransformInputPin Class

Constructs a CTransformInputPin object.

CTransformInputPin(
TCHAR *pObjectName,
CTransformFilter *pTransformFilter,
HRESULT * phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the CTransformInputPin object.
pTransformFilter
Pointer to the CTransformFilter class.
phr
Pointer to an HRESULT value in which to return resulting information. This should be modified only if a failure occurs. If it is a failure code on input, construction can be terminated, but in any case the destructor will be called by the creator when the HRESULT error is detected.
pName
Name of the pin.
Return Values

No return value.

CTransformInputPin::CurrentMediaType

CTransformInputPin Class

Retrieves the media type currently assigned to the filter.

CMediaType& CurrentMediaType( );

Return Values

Returns the value of CBasePin::m_mt.

CTransformInputPin::EndFlush

CTransformInputPin Class

Informs the pin to end a flush operation and notifies the pin that it can start accepting data again.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndFlush method and overrides the CBaseInputPin::EndFlush member function. It checks to see if the pin is connected, calls the CBaseInputPin::EndFlush member function, and finally calls the CTransformFilter::EndFlush member function.

CTransformInputPin::EndOfStream

CTransformInputPin Class

Informs the input pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndOfStream method. It calls CTransformInputPin::CheckStreaming to see that the filter is in a streaming state and then calls the CTransformFilter::EndOfStream member function.

CTransformInputPin::NewSegment

CTransformInputPin Class

Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.

HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);

Parameters
tStart
Start time of the segment.
tStop
Stop time of the segment.
dRate
Rate of the segment.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::NewSegment method and overrides the CBasePin::NewSegment member function. It calls the base class implementation first (CBasePin::NewSegment), and then calls CTransformFilter::NewSegment to pass the notification on to the next filter downstream.

CTransformInputPin::QueryId

CTransformInputPin Class

Retrieves an identifier for the pin.

HRESULT QueryId(
LPWSTR * Id
);

Parameters
Id
Pin identifier.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryId method and overrides the CBasePin::QueryId member function. It returns the name "In". The caller is responsible for freeing the memory by using the Microsoft® Win32® CoTaskMemFree function.

CTransformInputPin::Receive

CTransformInputPin Class

Receives the next block of data from the stream.

HRESULT Receive(
IMediaSample * pSample
);

Parameters
pSample
Pointer to a media sample.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::Receive method. Add a reference to the block of data if access to it is required after the completion of this method. For instance, some decoder filters for temporal compression data streams require that the previous sample be kept in order to decode the current sample.

This member function calls the CTransformFilter::Receive member function, which does the work of calling the transform function and then passing the sample on.

CTransformInputPin::SetMediaType

CTransformInputPin Class

Informs the derived class when the media type is established for the connection.

HRESULT SetMediaType(
const CMediaType* mt
);

Parameters
mt
Pointer to an input media type to be used.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBasePin::SetMediaType member function. It calls the base class CBasePin::SetMediaType member function, which returns NOERROR, and then calls CTransformFilter::SetMediaType, which the derived class can override to be informed when the media type is set.


CTransformOutputPin Class

CTransformOutputPin class hierarchy

The CTransformOutputPin class implements the output pin of a simple transform filter. It is the class assigned to the m_pOutput data member of the CTransformFilter class. Typically, you can create objects of a class derived from CTransformFilter without modifying the CTransformOutputPin class. If you want to override this class and derive a class from CTransformFilter, use the class and then override the CTransformFilter::GetPin member function to create pins of your derived class.

Protected Data Members
Name | Description
m_pTransformFilter | Pointer to the owning CTransformFilter object.

Public Data Members
Name | Description
m_pPosition | Pointer to a CPosPassThru object that implements the IMediaPosition interface to pass media position commands on to the upstream filter.

Member Functions
Name | Description
CTransformOutputPin | Constructs a CTransformOutputPin object.
CurrentMediaType | Retrieves the media type currently assigned to the filter.

Overridable Member Functions
Name | Description
BreakConnect | Informs the derived class when the connection is broken.
CheckConnect | Informs the derived class when the connection process is starting.
CheckMediaType | Determines if the pin can use a specified media type.
CompleteConnect | Informs the derived class when the connection process has completed.
DecideBufferSize | Determines the number and size of buffers required.
GetMediaType | Returns the media type that the output pin uses.
SetMediaType | Informs the derived class when the media type is established for the connection.

Implemented IQualityControl Methods
Name | Description
Notify | Receives a quality-control notification, typically from a downstream filter. This method is inherited from the IQualityControl interface through the CBasePin class.

Implemented IPin Methods
Name | Description
QueryId | Retrieves an identifier for the pin.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingQueryInterface | Returns an interface and increments the reference count.

CTransformOutputPin::BreakConnect

CTransformOutputPin Class

Informs the derived class when the connection is broken.

HRESULT BreakConnect( );

Return Values

Returns NOERROR.

Remarks

This member function overrides the CBaseOutputPin::BreakConnect member function and calls the CTransformFilter::BreakConnect member function. It then calls the base class implementation in CBaseOutputPin::BreakConnect. Override CTransformFilter::BreakConnect to undo anything carried out in the CTransformOutputPin::CheckConnect member function (for example, releasing interfaces previously added to the reference count).

CTransformOutputPin::CheckConnect

CTransformOutputPin Class

Informs the derived class when the connection process is starting.

HRESULT CheckConnect(
IPin *pPin
);

Parameters
pPin
Pointer to the IPin interface of the connecting pin.
Return Values

Returns NOERROR by default.

Remarks

This member function overrides the CBasePin::CheckConnect member function and calls the CTransformFilter::CheckConnect member function. It then calls the base class implementation in CBaseOutputPin::CheckConnect. Override CTransformFilter::CheckConnect to add additional interfaces.

CTransformOutputPin::CheckMediaType

CTransformOutputPin Class

Determines if the input pin supports a specified media type.

HRESULT CheckMediaType(
const CMediaType* mtIn
);

Parameters
mtIn
Pointer to a media type object.
Return Values

No return value.

Remarks

This member function calls the pure-virtual CTransformFilter::CheckTransform member function, which must be overridden when deriving a class from the CTransformFilter class. The overridden CTransformFilter::CheckTransform member function determines which media types the output pin supports.

CTransformOutputPin::CompleteConnect

CTransformOutputPin Class

Informs the derived class when the connection process has completed.

HRESULT CompleteConnect(
IPin *pReceivePin
);

Parameters
pReceivePin
Pointer to the output pin that is being connected to.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBaseOutputPin::CompleteConnect member function and calls the CTransformFilter::CompleteConnect member function, which returns NOERROR by default. It then calls the base class implementation in CBaseOutputPin::CompleteConnect. Override the CTransformFilter::CompleteConnect member function to retrieve any additional interfaces not retrieved by the base class that your output pin might need from the connected pin.

CTransformOutputPin::CTransformOutputPin

CTransformOutputPin Class

Constructs a CTransformOutputPin object.

CTransformOutputPin(
TCHAR *pObjectName,
CTransformFilter *pTransformFilter,
HRESULT * phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the CTransformOutputPin object.
pTransformFilter
Pointer to the CTransformFilter class.
phr
Pointer to an HRESULT value in which to return resulting information. This should be modified only if a failure occurs. If it is a failure code on input, construction can be aborted, but in any case the destructor will be called by the creator when the HRESULT error is detected.
pName
Name of the pin.
Return Values

No return value.

CTransformOutputPin::CurrentMediaType

CTransformOutputPin Class

Retrieves the media type currently assigned to the filter.

CMediaType& CurrentMediaType( );

Return Values

Returns the value of CBasePin::m_mt.

CTransformOutputPin::DecideBufferSize

CTransformOutputPin Class

Determines the number and size of buffers required.

HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * ppropInputRequest
);

Parameters
pAlloc
Allocator assigned to the transfer.
ppropInputRequest
Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBaseOutputPin::DecideBufferSize member function and calls the pure virtual CTransformFilter::DecideBufferSize member function, which your derived class must override and implement. This member function is called from the CBaseOutputPin class during the connection process.

CTransformOutputPin::GetMediaType

CTransformOutputPin Class

Returns the media type for the output pin to use.

HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
);

Parameters
iPosition
Position of the media type in the media type list.
pMediaType
Returned media type object.
Return Values

Returns an HRESULT value that depends on the implementation of the pure virtual CTransformFilter::GetMediaType member function. HRESULT can include one of the following constants.
Value | Meaning
NOERROR | A media type is returned.
S_FALSE | Although the iPosition parameter typically is valid, it does not correspond to a media type that is currently valid.
VFW_S_NO_MORE_ITEMS | The iPosition parameter is beyond the valid range.

Use other standard error values, such as E_INVALIDARG, for error cases.

Remarks

This member function overrides the CBasePin::GetMediaType member function and calls the pure virtual CTransformFilter::GetMediaType member function, which must be overridden to return media types supported by your filter. This is part of the implementation of CBasePin::EnumMediaTypes.

CTransformOutputPin::NonDelegatingQueryInterface

CTransformOutputPin Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful. If the query is unsuccessful and the requested interface is IMediaPosition or IMediaSeeking, returns an HRESULT from a call to CreatePosPassThru. If the query is unsuccessful and the interface is not IMediaPosition or IMediaSeeking, returns E_NOINTERFACE.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method. It overrides the CBasePin::NonDelegatingQueryInterface member function and passes references to the IPin, IQualityControl, IMediaPosition, IMediaSeeking, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CTransformOutputPin::Notify

CTransformOutputPin Class

Notifies the recipient that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

Parameters
pSelf
Pointer to the filter that is sending the quality notification.
q
Quality notification structure.
Return Values

Default base class implementation returns E_FAIL.

Remarks

This member function implements the IQualityControl::Notify method and overrides the CBasePin::Notify member function. It calls the CTransformFilter::AlterQuality member function to determine if the filter can do something to adjust the quality of the media stream (such as discarding samples). If that member function returns S_FALSE, it calls the CBaseInputPin::PassNotify member function, which passes the notification to the upstream filter after verifying that it is connected upstream.

CTransformOutputPin::QueryId

CTransformOutputPin Class

Retrieves an identifier for the pin.

HRESULT QueryId(
LPWSTR * Id
);

Parameters
Id
Pin identifier.
Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryId method and overrides the CBasePin::QueryId member function. It returns the name "Out". The caller is responsible for freeing the memory by using the Microsoft® Win32® CoTaskMemFree function.

CTransformOutputPin::SetMediaType

CTransformOutputPin Class

Sets the media type for the connection to use.

HRESULT SetMediaType(
const CMediaType* mt
);

Parameters
mt
Pointer to an output media type to be used.
Return Values

Returns an HRESULT value (NOERROR by default).

Remarks

This member function overrides the CBasePin::SetMediaType member function and calls the CTransformFilter::SetMediaType member function with the direction set to output. Override CTransformFilter::SetMediaType to handle any conditions that you want handled at this time in the connection process.


CTransInPlaceFilter Class

CTransInPlaceFilter class hierarchy

CTransInPlaceFilter is an abstract base class that provides support for a simple transform filter with a single input and a single output. It is derived from the CUnknown class, and supports the IBaseFilter interface, the IMediaFilter interface, and two pins. Each pin supports the IPin interface and uses the shared memory transport based on the IMemInputPin interface. The filter uses classes derived from the CBaseMediaFilter class to support IBaseFilter and IMediaFilter. The input pin is derived from the CBaseInputPin class, and the output pin is derived from the CBaseOutputPin class.

For more information about using this class to create a transform filter, see Creating a Transform Filter.

Protected Data Members
Name | Description
m_idTransInPlace | Performance-measuring identifier.

Member Functions
Name | Description
Copy | Returns a pointer to an identical copy of a media sample.
CTransInPlaceFilter | Constructs a CTransInPlaceFilter object.
InputPin | Returns a pointer to the input pin associated with the filter.
OutputPin | Returns a pointer to the output pin associated with the filter.

Overridable Member Functions
Name | Description
CheckTransform | Verifies that the media type is supported by input and output pins.
CompleteConnect | Reconnects the input or output pin if necessary.
DecideBufferSize | Determines the size of the transport buffer.
GetMediaType | Returns the media type to be used by the output pin.
GetPin | Returns a pin if an index is specified.
Receive | Receives the sample, calls the derived class's Transform member function, and then delivers the sample.
RegisterPerfId | Registers a performance measurement identifier (if PERF is defined).
Transform | Performs transformation operations in place on the IMediaSample interface (pure virtual).

CTransInPlaceFilter::CheckTransform

CTransInPlaceFilter Class

Verifies that the media is supported by input and output pins.

HRESULT CheckTransform(
const CMediaType *mtIn,
const CMediaType *mtOut
);

Parameters
mtIn
Input pin media type.
mtOut
Output pin media type.
Return Values

Returns S_OK by default.

Remarks

This member function overrides the CTransformFilter::CheckTransform member function. The base class functions that call this member function are overridden in this class to call the CTransformFilter::CheckInputType member function that is overridden in the derived class, with the assumption that the type does not change. Usually there is no reason for this member function to be called. In debug builds some calls will be made, and returning S_OK ensures that these calls do not assert.

CTransInPlaceFilter::CompleteConnect

CTransInPlaceFilter Class

Reconnects the input or output pin if necessary.

HRESULT CompleteConnect(
PIN_DIRECTION direction,
IPin *pReceivePin
);

Parameters
direction
Pin direction.
pReceivePin
Pointer to the output pin to which to connect.
Return Values

Returns NOERROR if successful; otherwise, returns VFW_E_NOT_IN_GRAPH if the filter is not part of a graph, or returns an HRESULT that indicates the error. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.

Remarks

This member function overrides the CTransformFilter::CompleteConnect member function. It is called by one of the pin classes at the end of a successful connection. Because the input and output pins must both use the same allocator, this member function reconnects the opposite pin if necessary.

When the input pin is first connected, the output pin has not yet been connected and the downstream filter's allocator is unknown, so the allocator for the input pin is chosen to be the upstream pin's allocator. When the transform filter's output pin is connected, however, it has access to the downstream filter's allocator and should force a reconnect on the input pin and offer that allocator. When the input pin is reconnected, it forces a reconnect on the output pin if the allocator chosen for the input pin's connection differs from the output pin's connection. This member function supplies the reconnection for either output or input pins.

CTransInPlaceFilter::Copy

CTransInPlaceFilter Class

Creates a copy of the specified media sample.

IMediaSample * CTransInPlaceFilter::Copy(
IMediaSample *pSource
);

Parameters
pSource
Pointer to an object that implements the IMediaSample interface.
Return Values

Returns a pointer to the new sample.

CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter Class

Constructs a CTransInPlaceFilter object.

CTransInPlaceFilter(
TCHAR * pObjectName,
LPUNKNOWN lpUnk,
REFCLSID clsid,
HRESULT * phr
);

Parameters
pObjectName
Name given to the CTransInPlaceFilter object.
lpUnk
Pointer to LPUNKNOWN.
clsid
Class identifier of the CTransInPlaceFilter class.
phr
Pointer to the HRESULT value for resulting information.
Return Values

No return value.

CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter Class

Determines the size of the transport buffer.

HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * pProperties
);

Parameters
pAlloc
Pointer to the IMemAllocator object used by the output pin.
pProperties
Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.
Return Values

Returns NOERROR if successful; otherwise, returns an HRESULT value indicating the error. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.

Remarks

This member function overrides the CTransformFilter::DecideBufferSize member function. It is called when the filter must provide its own allocator. Allocator requirements are obtained from the filter's input pin and passed to the output pin.

CTransInPlaceFilter::GetMediaType

CTransInPlaceFilter Class

Returns the media type to be used by the output pin.

HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
);

Parameters
iPosition
Position of the media type in the media type list.
pMediaType
Returned media type object.
Return Values

Returns E_UNEXPECTED because it is not expected to be called.

Remarks

In the CTransformFilter class, this member function is called by the associated input or output pin class's GetMediaType member function to retrieve the next media type in the list and return it to the pin's CBasePin::EnumMediaTypes member function.

However, in the CTransInPlaceFilter class, the pin classes override the CBasePin::EnumMediaTypes member function so that it bypasses the filter and calls the enumerator of the opposite connected pin. (For example, the output pin enumerator uses the upstream filter's enumerator, and the input pin uses the connected downstream filter's enumerator.) Therefore, this member function should never be called by the inplace pin classes. It is implemented to prevent "undefined pure virtual" compiler warnings.

CTransInPlaceFilter::GetPin

CTransInPlaceFilter Class

Returns a pin if an index is specified.

virtual CBasePin * GetPin(
int n
);

Parameters
n
Index of the pin to return.
Return Values

Returns a pointer to a CBasePin object.

Remarks

This member function is implemented and need not be overridden unless one or more of the transform pin classes (CTransInPlaceInputPin or CTransInPlaceOutputPin) are being overridden.

CTransInPlaceFilter::InputPin

CTransInPlaceFilter Class

Retrieves a pointer to the input pin associated with the filter.

CTransInPlaceInputPin *InputPin( );

Return Values

Returns a pointer to a CTransInPlaceInputPin object.

Remarks

This member function is protected.

CTransInPlaceFilter::OutputPin

CTransInPlaceFilter Class

Retrieves a pointer to the output pin associated with the filter.

CTransInPlaceOutputPin *OutputPin( );

Return Values

Returns a pointer to a CTransInPlaceOutputPin object.

Remarks

This member function is protected.

CTransInPlaceFilter::Receive

CTransInPlaceFilter Class

Receives the media sample, calls the CTransInPlaceFilter::Transform member function, and then delivers the media sample.

HRESULT Receive(
IMediaSample *pSample
);

Parameters
pSample
Sample to deliver.
Return Values

Returns an HRESULT value that depends on the implementation of the derived class' Transform function. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function overrides the CTransformFilter::Receive member function. Override it only if you need more control of the process.

CTransInPlaceFilter::RegisterPerfId

CTransInPlaceFilter Class

Registers a performance measurement identifier.

virtual void RegisterPerfId( );

Return Values

No return value.

Remarks

By default, this member function registers the performance identifier (m_idTransform) with the string "TransinPlace". Override this member function to register a performance measurement with a less generic string. This should be done to avoid confusion with other filters. This member function is enabled only when PERF is defined.

CTransInPlaceFilter::Transform

CTransInPlaceFilter Class

Transforms the data in pSample in place.

virtual HRESULT Transform(
IMediaSample *pSample
) PURE;

Parameters
pSample
Pointer to the input IMediaSample interface.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

You must supply this member function in the derived class to perform the actual work of your filter. This member function is called by CTransInPlaceFilter::Receive before passing the sample on to the downstream filter. Transform can return S_FALSE to indicate that the sample should not be delivered downstream.


CTransInPlaceInputPin Class

CTransInPlaceInputPin class hierarchy

The CTransInPlaceInputPin class implements the input pin of a transform-inplace filter (CTransInPlaceFilter). This is part of a transform filter that transforms data in place rather than making a copy of it. The CTransInPlaceFilter::InputPin member function returns a pointer to CTransInPlaceInputPin object.

Typically, you can create objects of a class derived from CTransInPlaceInputPin without modifying this class. That is, you can usually override member functions in the CTransInPlaceFilter class that member functions of the CTransInPlaceInputPin class call, and not have to derive your own classes for either of the pin classes.

However, if you want to override this class and derive your filter class from CTransInPlaceFilter, you must override the CTransInPlaceFilter::GetPin member function to create pins of your derived class.

Protected Data Members
Name | Description
m_bReadOnly | Flag to indicate if the stream is read-only.
m_pTIPFilter | Pointer to the CTransInPlaceFilter object that owns this pin.

Member Functions
Name | Description
CTransInPlaceInputPin | Constructs a CTransInPlaceInputPin object.
PeekAllocator | Returns a pointer to the default allocator.
ReadOnly | Returns m_bReadOnly to indicate whether or not a stream is read-only.

Overridable Member Functions
Name | Description
CheckMediaType | Determines if the pin can use a specified media type.

Implemented IPin Methods
Name | Description
EnumMediaTypes | Provides a media type enumerator from the downstream filter.

Implemented IMemInputPin Methods
Name | Description
GetAllocator | Retrieves the upstream allocator.
GetAllocatorRequirements | Passes requests for allocator requirements downstream.
NotifyAllocator | Receives notification of which allocator the connected output pin will use.

CTransInPlaceInputPin::CheckMediaType

CTransInPlaceInputPin Class

Determines if the media type is acceptable.

HRESULT CheckMediaType(
const CMediaType* pmt
);

Parameters
pmt
Media type being checked.
Return Values

Returns an HRESULT value that depends on the implementation of the owning filter's CTransformFilter::CheckInputType member function. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function overrides the CTransformInputPin::CheckMediaType member function. It first calls the owning filter's CheckInputType member function. (This is a purely virtual function which must be overridden when deriving a class from the CTransformFilter class. The overridden CheckInputType member function determines which media types the input pin supports.) Then, if the filter's output pin is not connected, this member function agrees to any media type. If the output pin is connected, it asks the downstream connected input pin if it accepts this type and returns the result.

The CheckInputType member function must be overridden by the class of the owning filter.

CTransInPlaceInputPin::CTransInPlaceInputPin

CTransInPlaceInputPin Class

Constructs a CTransInPlaceInputPin object.

CTransInPlaceInputPin(
TCHAR *pObjectName,
CTransInPlaceFilter *pFilter,
HRESULT * phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the CTransInPlaceInputPin class object.
pFilter
Pointer to the CTransInPlaceFilter class.
phr
Pointer to an HRESULT value in which to return resulting information. This should be modified only if a failure occurs. If it is a failure code on input, construction can be terminated; but in any case the destructor will be called by the creator when the HRESULT error is detected.
pName
Name of the pin.
Return Values

No return value.

Remarks

This member function doesn't create the pins. The pins are created when they are first required. All external attempts to access pins (by enumeration or by CBaseFilter::FindPin) go through CTransInPlaceFilter::GetPin, which creates the pins initially.

CTransInPlaceInputPin::EnumMediaTypes

CTransInPlaceInputPin Class

Provides an enumerator for media types by retrieving one from downstream.

HRESULT EnumMediaTypes(
IEnumMediaTypes **ppEnum
);

Parameters
ppEnum
[out] Pointer to an enumerator for the media types.
Return Values

Returns NOERROR if successful, VFW_E_NOT_CONNECTED if there is no connection, or an HRESULT that indicates an error with the enumerator, such as E_POINTER or E_OUTOFMEMORY.

Remarks

This member function overrides the CBasePin::EnumMediaTypes member function and implements the IPin::EnumMediaTypes method. Transform-inplace filters use the media type enumerator from adjacent filters because they do not change the media type. When asked by a connected output pin of the upstream filter for this pin's media type enumerator, this member function simply retrieves the allocator from the input pin connected to its output pin (if it is connected).

CTransInPlaceInputPin::GetAllocator

CTransInPlaceInputPin Class

Retrieves the upstream allocator.

HRESULT GetAllocator(
IMemAllocator ** ppAllocator
);

Parameters
ppAllocator
Returned allocator.
Return Values

Returns a NOERROR if the method retrieves an allocator being used by the downstream filter. If no such allocator exists, returns S_OK if the method retrieves an allocator being used by the output pin of the in-place transform filter. If neither of these types of allocators can be retrieved, returns VFW_E_NO_ALLOCATOR.

Remarks

This member function overrides the CBaseInputPin::GetAllocator member function and implements the IMemInputPin::GetAllocator method. If an allocator has already been agreed upon, this member function supplies that allocator. Otherwise, if the downstream input pin can supply an allocator, it does so. If no allocator is available, this member function returns VFW_E_NO_ALLOCATOR.

CTransInPlaceInputPin::GetAllocatorRequirements

CTransInPlaceInputPin Class

Passes requests for allocator requirements downstream.

HRESULT GetAllocatorRequirements(
ALLOCATOR_PROPERTIES * pProps
);

Parameters
pProps
ALLOCATOR_PROPERTIES structure containing the required size, count, and alignment of the allocator.
Return Values

Returns E_NOTIMPL if the filter's output pin is not connected. Otherwise, returns an HRESULT that indicates whether the allocator properties were successfully received. HRESULT can be one of the following standard constants, or other values not listed:
Value | Meaning
E_FAIL | Failure.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
E_NOTIMPL | Method isn't supported.
S_OK or NOERROR | Success.

Remarks

This member function overrides the CBaseInputPin::GetAllocatorRequirements member function and implements the IMemInputPin::GetAllocatorRequirements method. If the downstream input pin can supply allocator requirements, it does so.

CTransInPlaceInputPin::NotifyAllocator

CTransInPlaceInputPin Class

Receives notification of which allocator will be used by the connected output pin.

HRESULT NotifyAllocator(
IMemAllocator * pAllocator,
BOOL bReadOnly
);

Parameters
pAllocator
Pointer to the IMemAllocator object to use. This might or might not be the same CTransInPlaceInputPin object that the input pin provided in the CTransInPlaceInputPin::GetAllocator member function (the output pin could provide its own allocator).
bReadOnly
Flag to indicate if the samples from this allocator are read-only.
Return Values

Returns NOERROR if successful. Returns E_POINTER if the pointer is invalid. Otherwise, returns an error due to calling CTransInPlaceOutputPin::ReceiveAllocator.

Remarks

This member function overrides the CBaseInputPin::NotifyAllocator member function and implements the IMemInputPin::NotifyAllocator method. This member function remembers the allocator and passes it to the output pin because they both must share the same allocator.

CTransInPlaceInputPin::PeekAllocator

CTransInPlaceInputPin Class

Returns a pointer to the default allocator.

IMemAllocator * PeekAllocator( )

Return Values

Returns the m_pAllocator data member inherited from CBaseInputPin.

Remarks

This method does not increment the reference count.

CTransInPlaceInputPin::ReadOnly

CTransInPlaceInputPin Class

Returns m_bReadOnly to indicate whether or not a stream is read-only.

const BOOL ReadOnly( )

Return Values

Returns TRUE if the stream is read-only. Returns FALSE otherwise.


CTransInPlaceOutputPin Class

CTransInPlaceOutputPin class hierarchy

The CTransInPlaceOutputPin class implements the output pin of a simple transform-inplace filter (CTransInPlaceFilter).

Protected Data Members
Name | Description
m_pTIPFilter | Pointer to the CTransInPlaceFilter object that owns this pin.

Member Functions
Name | Description
ConnectedIMemInputPin | Returns a pointer to the input pin to which this output pin is connected.
CTransInPlaceOutputPin | Construct a CTransInPlaceOutputPin object.
PeekAllocator | Returns a pointer to the default allocator.
ReceiveAllocator | Receives notification of which allocator will be used.

Overridable Member Functions
Name | Description
CheckMediaType | Determines if the media type is acceptable.
DecideAllocator | Negotiates the allocator to use (uses the allocator from the upstream output pin).

Implemented IPin Methods
Name | Description
EnumMediaTypes | Provides a media type enumerator from the upstream filter.

CTransInPlaceOutputPin::CheckMediaType

CTransInPlaceOutputPin Class

Determines if the media type is acceptable.

HRESULT CheckMediaType(
const CMediaType* pmt
);

Parameters
pmt
Pointer to a media type object containing the proposed media type.
Return Values

Returns S_OK if the pin is not connected. Otherwise, returns S_TRUE if the media type is accepted or S_FALSE if it is not.

Remarks

This member function overrides the CTransformOutputPin::CheckMediaType member function. It calls the pure virtual CTransformFilter::CheckInputType member function to verify the media type (which you must implement in your derived class) because it does not change the media type from input to output. If it is not connected, it returns S_OK, which agrees to any media type; otherwise, it calls QueryAccept on the output pin of the upstream filter and returns the result.

CTransInPlaceOutputPin::ConnectedIMemInputPin

CTransInPlaceOutputPin Class

Returns a pointer to the input pin to which this output pin is connected.

IMemInputPin * ConnectedIMemInputPin( )

Return Values

Returns the m_pInputPin data member inherited from CBaseOutputPin.

CTransInPlaceOutputPin::CTransInPlaceOutputPin

CTransInPlaceOutputPin Class

Constructs a CTransInPlaceOutputPin object.

CTransInPlaceOutputPin(
TCHAR *pObjectName,
CTransInPlaceFilter *pFilter,
HRESULT * phr,
LPCWSTR pName
);

Parameters
pObjectName
Name of the CTransInPlaceOutputPin object.
pFilter
Pointer to the owning CTransInPlaceFilter filter.
phr
Pointer to an HRESULT value in which to return resulting information.
pName
Name of the pin.
Return Values

No return value.

CTransInPlaceOutputPin::DecideAllocator

CTransInPlaceOutputPin Class

Negotiates the allocator to use (uses the allocator from the upstream output pin).

HRESULT DecideAllocator(
IMemInputPin * pPin,
IMemAllocator ** ppAlloc
);

Parameters
pPin
Pointer to the IMemInputPin interface of the downstream input pin.
ppAlloc
Returned allocator pointer.
Return Values

Returns NOERROR if successful. Otherwise, returns VFW_E_NO_ALLOCATOR if there is no allocator, or an error from calling GetAllocator, InitAllocator, GetAllocatorRequirements, DecideBufferSize, or NotifyAllocator.

Remarks

This member function overrides the CBaseOutputPin::DecideAllocator member function. This implementation uses the allocator that is negotiated by its input pin because a transform-inplace filter does not supply its own allocator. It then calls IMemInputPin::NotifyAllocator on the downstream input pin with that allocator.

If you want to use your own allocator, it is better to derive from CTransformFilter than from CTransInPlaceFilter, because the purpose of a transform-inplace filter is to use an existing allocator.

CTransInPlaceOutputPin::EnumMediaTypes

CTransInPlaceOutputPin Class

Provides a media type enumerator from the upstream filter.

HRESULT EnumMediaTypes(
IEnumMediaTypes **ppEnum
);

Parameters
ppEnum
Pointer to an enumerator for the media types.
Return Values

Returns NOERROR if successful, VFW_E_NOT_CONNECTED if there is no connection, or an HRESULT that indicates an error with the enumerator, such as E_POINTER or E_OUTOFMEMORY.

Remarks

This member function overrides the CBasePin::EnumMediaTypes member function and implements the IPin::EnumMediaTypes method. Transform-inplace filters use the media type enumerator from adjacent filters because they do not change the media type. This member function calls IPin::EnumMediaTypes on the output pin connected to the filter's input pin. If an application receives an enumerator, the application must release it when finished.

CTransInPlaceOutputPin::PeekAllocator

CTransInPlaceOutputPin Class

Returns a pointer to the default allocator.

IMemAllocator * PeekAllocator( )

Return Values

Returns the m_pAllocator data member inherited from CBaseOutputPin.

Remarks

This member function does not increment the reference count.

CTransInPlaceOutputPin::ReceiveAllocator

CTransInPlaceOutputPin Class

Receives notification of which allocator will be used.

HRESULT ReceiveAllocator(
IMemAllocator * pAllocator,
BOOL bReadOnly
);

Parameters
pAllocator
Pointer to the IMemAllocator object to use.
bReadOnly
Flag to indicate if the samples from this allocator are read-only.
Return Values

Returns NOERROR if the allocator has the correct properties and is not read-only. Returns S_OK if successful if the allocator has the correct properties but is read-only; otherwise, returns VFW_E_BADALIGN, VFW_E_ALREADY_COMMITTED, VFW_E_BUFFERS_OUTSTANDING, or E_FAIL if the allocator's properties don't match what is needed.

Remarks

This member function is called by the CTransInPlaceInputPin::NotifyAllocator member function to indicate to the output pin which allocator will be used. It is only called if the output pin is connected. The choice is propagated to input pins downstream if the allocator is not read-only. For read-only allocators, only the properties are passed downstream.


CUnknown Class

CUnknown class hierarchy

All Microsoft® DirectShow™ Component Object Model (COM) objects derive from the CUnknown abstract base class. This class facilitates the creation of simple COM objects that you can combine with other COM objects to support multiple interfaces. To use this class, derive your object from CUnknown and call the DECLARE_IUNKNOWN macro in the public section of your object class definition; this implements the IUnknown interface for your object. Note that if derive from an object that has already done this, such as CBaseFilter, you do not need to do it yourself.

The CUnknown class supports only one interface, IUnknown. To support interfaces in addition to those provided by the base class, override the NonDelegatingQueryInterface method. In the overriding function, call the GetInterface function to retrieve the interface pointer for any interfaces your object supports. If the derived class does not implement the specified interface, you must query the base class to retrieve the interface.

For example, CBaseFilter supports the following interfaces directly.

  • IBaseFilter
  • IPersist
  • IAMovieSetup

CBaseFilter also supports IUnknown by passing queries for this interface to CUnknown. The following code sample demonstrates this process.

/* Override this to say what interfaces are supported and where */

STDMETHODIMP CBaseFilter::NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    CheckPointer(ppv,E_POINTER);
    ValidateReadWritePtr(ppv,sizeof(PVOID));

    /* Do we have this interface */

    if (riid == IID_IFilter) {
         return GetInterface((IBaseFilter *) this, ppv);
    } else if (riid == IID_IMediaFilter) {
                   return GetInterface((IMediaFilter *) this, ppv);
    } else if (riid == IID_IPersist) {
                   return GetInterface((IPersist *) this, ppv);
    } else if (riid == IID_IAMovieSetup) {
                   return GetInterface((IAMovieSetup *) this, ppv);
    } else {
                   return CUnknown::NonDelegatingQueryInterface(riid, ppv);
    }
}

To build composite objects, the CUnknown constructor has an LPUNKNOWN parameter that is a pointer to the top-level IUnknown interface for the entire composite object (the object that includes all objects based on a class derived from CUnknown). If this value is non-NULL, CUnknown stores a pointer to the topmost object; if it is null, the topmost object is CUnknown itself. This way, the topmost object's IUnknown has the same implementation as the INonDelegatingUnknown interface.

A derived class will typically override the NonDelegatingQueryInterface method to return interfaces that it supports; however, it must delegate support for IUnknown to the CUnknown class implementation. Usually NonDelegatingAddRef and NonDelegatingRelease do not need to be overridden because the reference count for the whole object is managed inside the top-level object. However, NonDelegatingRelease might need to be overridden sometimes because its default action when the reference count goes to zero is to delete the object from inside itself.

CUnknown provides the CUnknown::GetOwner member function. GetOwner simply returns an LPUNKNOWN pointer to the controlling unknown. This is used in the DECLARE_IUNKNOWN macro when calling QueryInterface. It can also be used when creating a composite object to pass an LPUNKNOWN pointer to a component interface as an (equivalent) alternative to passing the LPUNKNOWN pointer that was passed to the composite object constructor.

When QueryInterface is called on an interface owned by a component interface, it is immediately passed to the NonDelegatingQueryInterface method of the top-level object's INonDelegatingUnknown::NonDelegatingQueryInterface method, which either returns an interface it implements itself or passes the call to the correct member or base class's INonDelegatingUnknown::NonDelegatingQueryInterface method. This then repeats the process until a component is found that implements the interface or calls CUnknown::NonDelegatingQueryInterface, which fails the call.

Note that the top-level object's CUnknown::NonDelegatingQueryInterface member function (as distinct from its own implementation) must be called to support IUnknown.

This design makes support for COM aggregation straightforward. The derived object's CreateInstance member function, which is called from the class factory (by CClassFactory::CreateInstance) passes the outer unknown (the pUnkOuter parameter from CoCreateInstance) on to CUnknown by calling the class constructor. So the object behaves as if it were part of a larger object by delegating its QueryInterface calls to the outer unknown.

Protected Data Members
Name | Description
m_cRef | Number of reference counts (so the INonDelegatingUnknown::NonDelegatingRelease method can be overridden).

Member Functions
Name | Description
CUnknown | Constructs a CUnknown object.
GetOwner | Returns an LPUNKNOWN pointer to the controlling unknown.

Implemented INonDelegatingUnknown Methods
Name | Description
NonDelegatingAddRef | Increments the reference count for an interface.
NonDelegatingQueryInterface | Returns an interface and increments the reference count.
NonDelegatingRelease | Decrements the reference count for an interface.

CUnknown::CUnknown

CUnknown Class

Constructs a CUnknown object.

CUnknown(
const TCHAR *pName,
LPUNKNOWN pUnk
);

Parameters
pName
Name of the object used in the CBaseObject constructor for debugging purposes.
pUnk
Pointer to the owner of this object. If non-NULL, IUnknown calls are delegated to this object.
Return Values

No return value.

Remarks

The object is initialized with a reference count of zero. This reference count can be incremented when the object is queried for its first interface, depending on whether the object is currently being aggregated.

CUnknown::GetOwner

CUnknown Class

Retrieves this object's Component Object Model (COM) class owner.

LPUNKNOWN GetOwner(void);

Return Values

Returns an LPUNKNOWN pointer to the controlling IUnknown interface.

CUnknown::NonDelegatingAddRef

CUnknown Class

Increments the reference count for an interface.

ULONG NonDelegatingAddRef( );

Return Values

Returns the reference count of the object.

Remarks

This member function provides a base class implementation of the INonDelegatingUnknown::NonDelegatingAddRef method. When the object derived from CUnknown is part of an aggregated object, this reference count modification is private to the embedded object.

CUnknown::NonDelegatingQueryInterface

CUnknown Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

Parameters
riid
Reference identifier.
ppv
Pointer to the interface.
Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function provides a base class implementation of the INonDelegatingUnknown::NonDelegatingQueryInterface method. Override this class to return interfaces on the object in the derived class.

CUnknown::NonDelegatingRelease

CUnknown Class

Decrements the reference count for an interface.

ULONG NonDelegatingRelease( );

Return Values

Returns the reference count.

Remarks

This member function provides a base class implementation of the INonDelegatingUnknown::NonDelegatingRelease method. When the object derived from CUnknown is part of an aggregated object, this reference count modification is private to the embedded object.


CVideoTransformFilter Class

CVideoTransformFilter class hierarchy

The CVideoTransformFilter class is designed primarily as a base class for AVI decompressor filters. It is based on a "copying" transform class and assumes that the output buffer will likely be a video buffer or Microsoft® DirectDraw® buffer, although this could be used as a base class for other types of transform filters. The main feature of this class is that it enables quality-control management in a transform filter. This means that it decides to drop frames based on receiving a quality notification from the renderer, and taking into account other factors about the media stream it is processing and the filter's own behavior.

Every time the CVideoTransformFilter::Receive member function is called, it calls CVideoTransformFilter::ShouldSkipFrame to determine whether to start, continue, or stop skipping frames. This member function starts skipping samples only if all the following conditions are true.

  • The average time to decode is more than one fourth of the frame time.
  • The filter is running at least one frame late.
  • The next anticipated key frame is estimated to be no more than one frame early.
  • The occurrence of key frames is sufficiently frequent.

Once the class starts to skip frames, it will skip all frames until a key frame appears, at which time it resets the m_bSkipping flag and processes the sample.

Key frames are defined as AVI key frames or MPEG I frames. These require no history to decode and, if they are skipped, no other frames can be decoded until the next key frame. Non-key frames include AVI non-key frames, MPEG P frames, and MPEG B frames. MPEG B frames are treated the same as other non-key frames by this class. (MPEG B frames can be dropped without the need to skip further frames; however, because this class is aimed primarily at AVI decompressors, it does not allow for this. Once any frame is skipped, all frames are skipped up to the next key frame.)

Protected Data Members
Name | Description
m_bNoSkip | Set to TRUE to prevent skipping to the next key frame (for debugging the filter).
m_bQualityChanged | Status flag that indicates if the stream has degraded. This is set to TRUE in CVideoTransformFilter::Receive if the call to the derived class Transform member function fails. (Receive returns NOERROR in this case because returning S_FALSE indicates that end-of-stream has arrived.)
m_bSkipping | Set to TRUE if the filter is skipping to the next key frame.
m_idFrameType | Performance-measuring frame type identifier (available if PERF is defined). Logs 1 for key frames; logs 2 for nonkey frames.
m_idLate | Performance identifier for measuring lateness (available if PERF is defined).
m_idSkip | Performance identifier for measuring frame skipping (available if PERF is defined).
m_idTimeTillKey | Performance identifier that represents an estimate of the time in milliseconds until the next key frame arrives (available if PERF is defined).
m_itrAvgDecode | Average time required to decode (transform) the sample. If this is less than one-fourth of the frame time, it is assumed the quality problems are not being generated by this filter and no frames are dropped.
m_itrLate | Amount of time that the current frame is late. This is originally set to the value of the Quality structure's Late member passed in the quality control message from the renderer filter. It is decremented by the frame time of each frame that is skipped.
m_nFramesSinceKeyFrame | Used to count frames since the last key frame.
m_nKeyFramePeriod | The largest observed interval between key frames.
m_nWaitForKey | Used to ensure output after a format change before getting the first key frame. When nonzero, frames are not passed to the renderer. Set to 30 when format is changed and decremented on each non-key frame.
m_tDecodeStart | Time since the start of the decoding.

Member Functions
Name | Description
AlterQuality | Receives a quality-control notification from the output pin and provides an opportunity to alter the quality of the media stream.
CVideoTransformFilter | Constructs a CVideoTransformFilter object.
ShouldSkipFrame | Determines if the filter should start, continue, or stop skipping frames.

Overridable Member Functions
Name | Description
EndFlush | Receives notification of leaving the flushing state and passes it downstream.
Receive | Receives the media sample and either skips the sample or transforms and delivers the media sample.
RegisterPerfId | Registers a performance measurement identifier.
StartStreaming | Overrides CTransformFilter::StartStreaming to reset the quality control information when streaming starts or flushing starts.

CVideoTransformFilter::AlterQuality

CVideoTransformFilter Class

Receives a quality-control notification and provides an opportunity to alter the quality of the media stream.

virtual HRESULT AlterQuality(
Quality q
);

Parameters
q
Quality-control notification message.
Return Values

This member function returns E_FAIL by default.

Remarks

This member function overrides the CTransformFilter::AlterQuality member function. It is called by the CTransformOutputPin::Notify member function before calling the CBaseInputPin::PassNotify member function to pass the quality control message upstream. This function sets the CVideoTransformFilter::m_itrLate data member to the value Quality structure's Late member so that the filter can determine whether to skip frames. It returns E_FAIL so that the renderer downstream will continue to handle quality control.

CVideoTransformFilter::CVideoTransformFilter

CVideoTransformFilter Class

Constructs a CVideoTransformFilter object.

CVideoTransformFilter(
TCHAR *pName,
LPUNKNOWN pUnk,
REFCLSID clsid
);

Parameters
pName
Name given to the CVideoTransformFilter object.
pUnk
Pointer to LPUNKNOWN.
clsid
Class identifier of the CVideoTransformFilter class.
Return Values

No return value.

CVideoTransformFilter::EndFlush

CVideoTransformFilter Class

Receives notification that the filter is leaving the flushing state and passes it downstream.

HRESULT EndFlush( );

Return Values

Returns VFW_E_NOT_CONNECTED if the filter finds no input pin; otherwise, returns the value that the IPin::EndFlush method returns.

Remarks

This member function overrides the CTransformFilter::EndFlush member function to reset quality management information.

CVideoTransformFilter::Receive

CVideoTransformFilter Class

Receives the media sample and either skips the sample or transforms and delivers the media sample.

HRESULT Receive(
IMediaSample *pSample
);

Parameters
pSample
Sample to deliver.
Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CTransformFilter::Receive member function. Override only if you need more control of the process.

CVideoTransformFilter::RegisterPerfId

CVideoTransformFilter Class

Registers performance measurement identifiers.

virtual void RegisterPerfId( );

Return Values

No return value.

Remarks

By default, this member function registers the following performance identifiers.
Performance identifier | Registered string
m_idSkip | Video transform skip frame
m_idFrameType | Video transform frame type
m_idLate | Video transform lateness
m_idTimeTillKey | Video transform estd. time to next key

This member function also calls CTransformFilter::RegisterPerfId for its performance identifier.

Override this member function if you want to register performance measurement identifiers in the derived class. If you do this, be sure to register these as well. This member function is enabled only when PERF is defined.

CVideoTransformFilter::ShouldSkipFrame

CVideoTransformFilter Class

Determines if the filter should start, continue, or stop skipping frames.

BOOL ShouldSkipFrame(
IMediaSample * pIn
);

Parameters
pIn
Received sample to be transformed or skipped.
Return Values

Returns TRUE if the filter should skip this sample; otherwise, returns FALSE.

Remarks

This member function sets the m_bSkipping member variable to FALSE if the sample is a key frame (sync point) and returns FALSE. This stops any skipping that has started. This member function starts skipping samples (sets m_bSkipping to TRUE and returns TRUE) only if all of the following conditions are true.

  • The average time to decode is more than one-fourth of the frame time.
  • The filter is running at least one frame late.
  • The next anticipated key frame is estimated to be no more than one frame early.
  • The occurrence of key frames is sufficiently frequent.

This member function sends an EC_QUALITY_CHANGE notification when sample skipping starts. Once skipping starts, all samples are skipped until the next key frame arrives.

CVideoTransformFilter::StartStreaming

CVideoTransformFilter Class

Overrides CTransformFilter::StartStreaming to reset the quality control information when streaming starts or flushing starts.

virtual HRESULT StartStreaming( );

Return Values

Returns NOERROR.

Remarks

This member function sets several quality control member variables to 0, including m_itrLate, m_nKeyFramePeriod, m_nFramesSinceKeyFrame, m_bSkipping, and m_tDecodeStart. It sets m_itrAvgDecode to 3000, and sets m_bQualityChanged and m_bSampleSkipped to FALSE.


FOURCCMap Class

FOURCCMap class hierarchy

This class provides conversion between GUID media subtypes and old-style FOURCC 32-bit media tags. In the original Microsoft® Windows® multimedia APIs, media types were tagged with 32-bit values created from four 8-bit characters and were known as FOURCCs. Microsoft DirectShow™ media types have GUIDs for the subtype, partly because these are simpler to create (creation of a new FOURCC requires its registration with Microsoft). Because FOURCCs are unique, a one-to-one mapping has been made possible by allocating a range of 4,000 million GUIDs representing FOURCCs. This range is all GUIDs of the form:

XXXXXXXX-0000-0010-8000-00AA00389B71

This class simplifies conversion between GUIDs and FOURCCs. This is for compatibility only. It is recommended that all new media subtypes be represented by GUIDs created by Guidgen.exe or a similar tool, and not by mapping FOURCCs.

The object is derived from a GUID, with no extra data members, and can be cast to a GUID. The object can be passed a FOURCC at construction time. The default constructor will initialize the FOURCC to zero.

The GetFOURCC and SetFOURCC methods do not check that the fixed portions of the GUID correspond to the FOURCC range. Thus, if you cast a pointer to a GUID into a pointer to a FOURCC and then set or get the FOURCC field, you also need to check separately that the GUID is within the FOURCC range.

Member Functions
Name | Description
FOURCCMap | Constructs a FOURCCMap object.
GetFOURCC | Returns the FOURCC from a FOURCCMap object.
SetFOURCC | Sets the FOURCC portion of the FOURCCMap object.

FOURCCMap::FOURCCMap

FOURCCMap Class

Constructs a FOURCCMap object. Provides a mapping between old-style multimedia format DWORD types and new-style GUID types.

FOURCCMap( );
FOURCCMap(
DWORD Fourcc
);
FOURCCMap(
const GUID * pguid
);

Parameters
Fourcc
DWORD media tag formerly used for Microsoft multimedia types.
pguid
Globally unique identifier (GUID).
Return Values

No return value.

Remarks

If this object is constructed with the FOURCC code, a GUID is created to match it. If this object is created with an existing GUID, the FOURCC value of the object is set to zero. Thereafter, the FOURCC value can be set or retrieved using the SetFOURCC and GetFOURCC member functions, respectively.

FOURCCMap::GetFOURCC

FOURCCMap Class

Retrieves the FOURCC DWORD from the FOURCCMap object.

DWORD GetFOURCC(void);

Return Values

Returns the FOURCC DWORD value. Note that if you construct a FOURCCMap object from a GUID that was not originally derived from FOURCC, the return value will be essentially random.

FOURCCMap::SetFOURCC

FOURCCMap Class

Sets the FOURCC portion of the FOURCCMap object.

void SetFOURCC(
const GUID * pguid
);

Parameters
pguid
Pointer to the returned globally unique identifier (GUID) part of the FOURCCMap object.
Return Values

No return value.


Utility Functions

This section contains reference entries for the DirectShow utility functions and macros. DirectShow provides utilities for conversion, setup, timers, retrieving interfaces and declaring IUnknown, helper functions for math operations, property pages, BSTR functions, and strings, and stream integer functions. Most utilities are contained in Wxutil.h, but others are contained in Combase.h, Errors.h, Pstream.h, Refclock.h, Renbase.h, Videoctl.h, and Wtype.h.

BSTR Functions

Bitmap Functions, Macros, and Data

CBaseRenderer Callback Function

CCritSec Debug Functions

Conversion Functions

CPosPassThru Helper Function

DLL and Setup Functions

Error Message Function

IUnknown Macro

INonDelegatingUnknown Interface

Math Helper Functions

Media Type Functions

Object and Pin Functions

Performance Macros

Property Page Helper Functions

Reference Time Function

Stream Integer Functions

String Functions

Message Function


BSTR Functions

The Wxutil.h header file in the Microsoft® DirectShow™ base classes provides helper functions for allocating and freeing task-allocated BSTR strings.
Function | Description
FreeBSTR | Frees the task-allocated BSTR string.
WriteBSTR | Creates a task-allocated BSTR string by allocating task-allocated memory and copying a wide string to it.

FreeBSTR

BSTR Functions

Frees a task-allocated BSTR string from memory.

STDAPI FreeBSTR(
BSTR* pstr
);

Parameters
pstr
Address of the BSTR to free.
Return Values

Returns S_OK if successful, or S_FALSE if pstr is null.

Remarks

Memory is allocated for passing between objects across interfaces by calling CoTaskMemAlloc. It is freed by calling CoTaskMemFree. You can allocate, pass, and free memory safely between objects created in different programming languages by using a central memory allocator.

WriteBSTR

BSTR Functions

Allocates and fills a task-allocated BSTR string.

STDAPI WriteBSTR(
BSTR* pstrDest,
LPCWSTR szSrc
);

Parameters
pstrDest
Pointer to where the address of the allocated BSTR will be stored.
szSrc
Wide (Unicode) string that will be copied to the newly allocated BSTR string.
Return Values

Returns an HRESULT value.

Remarks

Memory is allocated for passing between objects across interfaces by calling CoTaskMemAlloc. It is freed by calling CoTaskMemFree. By using a central memory allocator, memory can be allocated, passed, and freed safely between objects created in different programming languages.


Bitmap Functions, Macros, and Data

The Wxutil.h header file in the DirectShow base classes provides functions and macros to help convert between VIDEOINFOHEADER and BITMAPINFO structures.
Function | Description
BIT_MASKS_MATCH | Compares the masks of two video images.
BITMASKS | Retrieves a pointer to the array of bitmasks for the specified VIDEOINFOHEADER structure.
COLORS | Retrieves a pointer to an array of RGBQUAD structures that describes the color palette for the specified VIDEOINFOHEADER structure.
ContainsPalette | Checks if the video image contains a color palette.
DIBSIZE | Calculates the byte size of the specified bitmap
GetBitCount | Finds the number of bits per pixel.
GetBitmapFormatSize | Finds the size (in bytes) needed to build a VIDEOINFOHEADER structure and related data.
GetBitmapPalette | Finds the first palette entry in a VIDEOINFOHEADER structure.
GetBitmapSize | Finds the size (in bytes) needed to hold an image.
GetBitmapSubtype | Finds the GUID subtype for a given bitmap info header structure.
GetSubtypeName | Finds the (debug) name for a given GUID subtype.
GetTrueColorType | Finds the GUID subtype for a given bitmap header.
HEADER | Retrieves a pointer to the image data from the specified video image.
MPEG1_SEQUENCE_INFO | Retrieves the sequence header for the specified MPEG-1 video image.
PALETTISED | Checks if the video image's color palette is 8-bit or less.
PALETTE_ENTRIES | Returns the number of colors in the video image's palette.
RESET_MASKS | Clears the specified video image's bitmasks.
RESET_HEADER | Clears the specified video image.
RESET_PALETTE | Clears the specified video image's color palette.
SIZE_EGA_PALETTE | Calculates the size of the EGA (4-bit) color palette.
SIZE_MASKS | Calculates the size of the mask's color palette.
SIZE_MPEG1VIDEOINFO | Calculates the size of the specified MPEG-1 video image.
SIZE_PALETTE | Calculates the size of the 8-bit color palette.
SIZE_PREHEADER | Calculates the byte offset for the video image's bitmap information.
SIZE_VIDEOHEADER | Calculates the size of the video image.
TRUECOLORINFO | Retrieves a pointer to an array of TRUECOLORINFO structures that describes the bitmasks and color palette for the specified VIDEOINFOHEADER structure.

These functions are made available to help manage VIDEOINFOHEADER structures, which are used throughout DirectShow™ to describe video data streams. Although similar to the BITMAPINFO structure used in Microsoft® Win32® and existing multimedia, VIDEOINFOHEADER also adds some new video-specific fields.
Global Data | Description
bits555 | Array of color bitmasks for an RGB 555 bitmap.
bits565 | Array of color bitmasks for an RGB 565 bitmap.
bits888 | Array of color bitmasks for an RGB 24-bit bitmap.

BIT_MASKS_MATCH

Bitmap Functions, Macros, and Data

Retrieves the bitmasks for the specified video image.

BIT_MASKS_MATCH(
pbmi1,
pbmi2
)

Parameters
pbmi1
Pointer to a Win32 VIDEOINFOHEADER structure that contains the first video image.
pbmi2
Pointer to a Win32 VIDEOINFOHEADER structure that contains the second video image.
Return Values

Returns nonzero if the bitmasks for both video images are identical or zero otherwise.

BITMASKS

Bitmap Functions, Macros, and Data

Retrieves the bitmasks for the specified video image.

BITMASKS(
pbmi
)

Parameters
pbmi
Pointer to a Win32 VIDEOINFOHEADER structure that contains the video image.
Return Values

Returns a pointer to the array of bitmasks for the specified VIDEOINFOHEADER structure.

COLORS

Bitmap Functions, Macros, and Data

Retrieves the color palette for the specified video image.

COLORS(
pbmi
)

Parameters
pbmi
Pointer to a Win32 VIDEOINFOHEADER structure that contains the video image.
Return Values

Returns a pointer to an array of RGBQUAD structures that describes the color palette for the specified VIDEOINFOHEADER structure.

ContainsPalette

Bitmap Functions, Macros, and Data

Checks if the specified video image contains a color palette.

BOOL ContainsPalette(
const VIDEOINFOHEADER *pVideoInfo
);

Parameters
pVideoInfo
Pointer to a VIDEOINFOHEADER structure.
Return Values

Returns TRUE if the VIDEOINFOHEADER structure contains a color palette or FALSE otherwise.

DIBSIZE

Bitmap Functions, Macros, and Data

Calculates the byte size of the specified bitmap.

DIBSIZE(
bi
)

Parameters
bi
A Win32 BITMAPINFOHEADER structure that specifies the source bitmap.
Return Values

Returns the byte size of the bi parameter.

GetBitCount

Bitmap Functions, Macros, and Data

Finds the number of bits per pixel.

WORD GetBitCount(
const GUID *pSubtype
);

Parameters
pSubtype
Pointer to a GUID for a given video subtype.
Return Values

Returns the number of bits per pixel for this subtype, or USHRT_MAX if an error occurred.

GetBitmapFormatSize

Bitmap Functions, Macros, and Data

Finds the size (in bytes) needed to build a VIDEOINFOHEADER structure and related data.

LONG GetBitmapFormatSize(
const BITMAPINFOHEADER *pHeader
);

Parameters
pHeader
Pointer to a Win32 BITMAPINFOHEADER structure.
Return Values

Returns the number of bytes for the VIDEOINFOHEADER structure described by this BITMAPINFOHEADER, including prefix information, the BITMAPINFOHEADER field, and any other color information on the end.

GetBitmapPalette

Bitmap Functions, Macros, and Data

Finds the first palette for a VIDEOINFOHEADER structure.

const RGBQUAD * GetBitmapPalette(
const VIDEOINFOHEADER *pVideoInfo
);

Parameters
pVideoInfo
Pointer to a VIDEOINFOHEADER structure.
Return Values

Returns a pointer to the first entry in a palette.

GetBitmapSize

Bitmap Functions, Macros, and Data

Finds the number of bytes needed to hold an image.

DWORD GetBitmapSize(
const BITMAPINFOHEADER *pHeader
);

Parameters
pHeader
Pointer to a Win32 BITMAPINFOHEADER structure.
Return Values

Returns the number of bytes needed to hold an image.

GetBitmapSubtype

Bitmap Functions, Macros, and Data

Finds the subtype for the specified bitmap.

const GUID GetBitmapSubtype(
const BITMAPINFOHEADER *pHeader
);

Parameters
pHeader
Pointer to a Win32 BITMAPINFOHEADER structure.
Return Values

Returns the video subtype GUID of the bitmap specified by pHeader, or GUID_NULL if pHeader is NULL.

GetSubtypeName

Bitmap Functions, Macros, and Data

Retrieves the name for a given GUID subtype.

TCHAR * GetSubtypeName(
const GUID *pSubtype
);

Parameters
pSubtype
Pointer to a GUID for a given video subtype.
Return Values

Returns the debug name of this GUID, or UNKNOWN if the name is not known.

GetTrueColorType

Bitmap Functions, Macros, and Data

Finds the subtype for the specified 16-bit color bitmap.

const GUID GetTrueColorType(
const BITMAPINFOHEADER *pHeader
);

Parameters
pHeader
Pointer to a Win32 BITMAPINFOHEADER structure.
Return Values

Returns the video subtype GUID of the 16-bit color bitmap specified by pHeader, or GUID_NULL if pHeader is NULL.

HEADER

Bitmap Functions, Macros, and Data

Retrieves a pointer to the image data from the specified video image.

HEADER(
pVideoInfo
)

Parameters
pVideoInfo
Pointer to the VIDEOINFOHEADER structure that specifies the video image.
Return Values

Returns a pointer to the Win32 BITMAPINFOHEADER structure contained in the VIDEOINFOHEADER structure's bmiHeader data member.

MPEG1_SEQUENCE_INFO

Bitmap Functions, Macros, and Data

Retrieves the sequence header for the specified MPEG-1 video image.

MPEG1_SEQUENCE_INFO(
pv
)

Parameters
pv
Pointer to an MPEG1VIDEOINFO structure.
Return Values

Returns the bSequenceHeader data member of the specified MPEG1VIDEOINFO structure.

PALETTISED

Bitmap Functions, Macros, and Data

Checks if the video image's color palette is 8-bit or less.

PALETTISED(
pbmi
)

Parameters
pbmi
Pointer to the Win32 BITMAPINFOHEADER structure that specifies the video image.
Return Values

Returns nonzero if the video image's palette contains 256 or fewer colors, or zero otherwise.

PALETTE_ENTRIES

Bitmap Functions, Macros, and Data

Retrieves the number of colors in the video image's palette.

PALETTE_ENTRIES(
pbmi
)

Parameters
pbmi
Pointer to the Win32 BITMAPINFOHEADER structure that specifies the video image.
Return Values

Returns the number of colors in the video image's palette.

RESET_MASKS

Clears the specified video image's bitmasks.

RESET_MASKS(
pbmi
)

Parameters
pbmi
Pointer to the Win32 BITMAPINFOHEADER structure that specifies the video image.
Return Values

No return value.

RESET_HEADER

Bitmap Functions, Macros, and Data

Clears the specified video image.

RESET_HEADER(
pbmi
)

Parameters
pbmi
Pointer to the Win32 BITMAPINFOHEADER structure that specifies the video image.
Return Values

No return value.

RESET_PALETTE

Bitmap Functions, Macros, and Data

Clears the specified video image's color palette.

RESET_PALETTE(
pbmi
)

Parameters
pbmi
Pointer to the Win32 BITMAPINFOHEADER structure that specifies the video image.
Return Values

No return value.

SIZE_EGA_PALETTE

Bitmap Functions, Macros, and Data

Calculates the size of a 4-bit color palette.

SIZE_EGA_PALETTE

Return Values

Returns the size of a 16-color palette, in bytes.

SIZE_MASKS

Bitmap Functions, Macros, and Data

Calculates the size of a bitmask's color palette.

SIZE_MASKS

Return Values

Returns the size, in bytes, of a bitmap mask's color palette, which has three colors.

SIZE_MPEG1VIDEOINFO

Bitmap Functions, Macros, and Data

Calculates the size of the specified MPEG-1 video image.

SIZE_MPEG1VIDEOINFO(
pv
)

Parameters
pv
Pointer to the MPEG1VIDEOINFO structure that specifies the video image.
Return Values

Returns the byte size of the specified MPEG1VIDEOINFO structure.

SIZE_PALETTE

Bitmap Functions, Macros, and Data

Calculates the size of the 8-bit color palette.

SIZE_PALETTE

Return Values

Returns the size of the 256-color palette.

SIZE_PREHEADER

Bitmap Functions, Macros, and Data

Calculates the byte offset for the video image's bitmap information.

SIZE_PREHEADER

Return Values

Returns the byte offset of the VIDEOINFOHEADER structure's bmiHeader data member.

SIZE_VIDEOHEADER

Bitmap Functions, Macros, and Data

Calculates the size of the video image.

SIZE_VIDEOHEADER

Return Values

Returns the combined size of all of the VIDEOINFOHEADER structure's data members.

TRUECOLORINFO

Bitmap Functions, Macros, and Data

Retrieves the color palette and bitmasks for the specified video image.

TRUECOLORINFO(
pbmi
)

Parameters
pbmi
Pointer to a Win32 VIDEOINFOHEADER structure that contains the video image.
Return Values

Returns a pointer to an array of TRUECOLORINFO structures that describes the bitmasks and color palette for the specified VIDEOINFOHEADER structure.


CBaseRenderer Callback Function

The Renbase.h header file in the DirectShow base classes provides a function to signal the end of a stream in CBaseRenderer or its derived classes.
Name | Description
EndOfStreamTimer | Signals the end of the specified class's data stream.

EndOfStreamTimer

CBaseRenderer Callback Function

Signals the end of the specified class's data stream.

void CALLBACK EndOfStreamTimer(
UINT uID,
UINT uMsg,
DWORD dwUser,
DWORD dw1,
DWORD dw2
);

Parameters
uID
Integer value that specifies the timer value when the application called EndOfStreamTimer.
uMsg
Not used.
dwUser
DWORD value that contains the address of a class instance derived from CBaseRenderer.
dw1
Reserved.
dw2
Reserved.
Return Values

No return value.

Remarks

EndOfStreamTimer checks the m_EndOfStreamTimer data member of the class specified by dwUser. If m_EndOfStreamTimer is nonzero, EndOfStreamTimer sets it to zero and calls the class's SendEndOfStream method.


CCritSec Debug Functions

The Wxutil.h header file in the DirectShow base classes provides functions to make deadlocks easier to track. It is useful to insert an assertion in the code that says whether a critical section is owned or not. The routines that do the checking are global functions to avoid having different numbers of member functions in the debug and retail class implementations of CCritSec. In addition, Wxutil.h provides a routine that enables you to trace usage of specific critical sections. Because of the large number of critical sections, this assertion defaults to off.
Name | Description
CritCheckIn | Checks that the current thread is the owner of the given critical section.
CritCheckOut | Checks that the current thread is not the owner of the given critical section.
DbgLockTrace | Enables or disables debug logging of a given critical section.

CritCheckIn

CCritSec Debug Functions

Checks that the owner of pcCrit is the current thread.

BOOL WINAPI CritCheckIn(
CCritSec * pcCrit
);

Parameters
pcCrit
Pointer to a CCritSec critical section.
Return Values

Returns TRUE if the current thread is the owner of this critical section, or FALSE otherwise.

Remarks

If you call this function when DEBUG is not defined and you've included the DirectShow headers, it will always return TRUE.

CritCheckOut

CCritSec Debug Functions

Checks that the owner of pcCrit is not the current thread.

BOOL WINAPI CritCheckOut(
CCritSec * pcCrit
);

Parameters
pcCrit
Pointer to a CCritSec critical section.
Return Values

Returns TRUE if the current thread is not the owner of this critical section, or FALSE otherwise.

Remarks

If you call this function when DEBUG is not defined and you've included the DirectShow headers, it will always return TRUE.

DbgLockTrace

CCritSec Debug Functions

Enables or disables debug logging of a given critical section.

void WINAPI DbgLockTrace(
CCritSec * pcCrit,
BOOL fTrace
);

Parameters
pcCrit
Pointer to a CCritSec critical section.
fTrace
Set to TRUE to enable logging or FALSE to disable it.
Return Values

No return value.

Remarks

This function does nothing unless DEBUG is defined when the DirectShow headers are included.


Conversion Functions

The Wxutil.h header file in the DirectShow base classes provides functions for converting between integers and wide strings.
Function | Description
atoi | Converts a string to an integer.
IntToWstr | Converts an integer to a wide string.
WstrToInt | Converts a wide string to an integer.

atoi

Conversion Functions

Converts a given string to an integer.

int WINAPI atoi(
const TCHAR *sz
);

Parameters
sz
Source character string.
Return Values

Returns the string's integer value.

Remarks

This version of atoi supports only decimal digits, and does not allow leading white space or signs. It supports both Unicode and ANSI strings. Other versions can vary.

IntToWstr

Conversion Functions

Converts a given integer value to a wide string representation.

void IntToWstr(
int i,
LPWSTR wstrDest
);

Parameters
i
Integer value to be converted.
wstrDest
LPWSTR that will contain the resulting wide string.
Return Values

No return value.

WstrToInt

Conversion Functions

Converts a given wide string value to an integer.

int WstrToInt(
LPCWSTR wstrSrc
);

Parameters
wstrSrc
Source wide-character string.
Return Values

Returns the string's integer value.


CPosPassThru Helper Function

The CPosPassThru helper function creates a plug-in distributor (a CPosPassThru COM object) that supports IMediaSeeking and IMediaPosition.
Function | Description
CreatePosPassThru | Creates a CPosPassThru COM object.

CreatePosPassThru

CPosPassThru Helper Function

Creates a COM object that supports IMediaSeeking and IMediaPosition for single-input pin renderers and transform filters.

STDAPI CreatePosPassThru(
LPUNKNOWN pAgg,
BOOL bRenderer,
IPin *pPin,
IUnknown **ppPassThru
);

Parameters
pAgg
NULL if the object is not being created as part of an aggregate; otherwise, a pointer to the aggregate object's IUnknown interface (the controlling IUnknown).
bRenderer
TRUE if the filter supports rendering; otherwise, FALSE.
pPin
Pointer to the filter's input pin.
ppPassThru
ISeekingPassThru interface.
Return Values

Returns S_OK if successful; otherwise, returns an HRESULT indicating the error.

Remarks

You can use this function to create a CPosPassThru object in Quartz.dll rather than from your own .dll file. The CLSID of the object is CLSID_SeekingPassThru.


DLL and Setup Functions

The Combase.h header file provides the following function for creating a run-time dynamic link with a specific dynamic-link library (DLL). For more information, read the Run-Time Dynamic Linking section in the Platform SDK.
Function | Description
LoadOLEAut32 | Loads the Automation DLL (OleAut32.dll).

The Dllsetup.h header file provides the following functions for registering and unregistering DirectShow filters. You'll typically call AMovieDllRegisterServer2 to register your filter. The other functions are either helper functions or provide backwards compatibility.
Function | Description
AMovieDllRegisterServer | Registers filters. ActiveMovie 1.0 only.
AMovieDllRegisterServer2 | Registers and unregisters filters.
AMovieDllUnregisterServer | Unregisters filters. ActiveMovie 1.0 only.
AMovieSetupRegisterFilter | Registers a filter's merit, pins, and media types in the registry using the filter mapper. ActiveMovie 1.0 only.
AMovieSetupRegisterFilter2 | Registers a filter's merit, pins, and media types in the registry using IFilterMapper2.

LoadOLEAut32

DLL and Setup Functions

Loads the Automation dynamic-link library (OleAut32.dll).

HINSTANCE LoadOLEAut32( );

Return Values

Returns a handle to an Automation DLL instance.

Remarks

When the CBaseObject destructor destroys the object that loaded OleAut32.dll, it will unload the library if it is still loaded.

AMovieDllRegisterServer

DLL and Setup Functions

Registers filters. ActiveMovie 1.0 only.

HRESULT AMovieDllRegisterServer(void);

Return Values

Returns an HRESULT value.

Remarks

Use AMovieDllRegisterServer2 rather than this function to set up (register) your filters unless you need compatibility with ActiveMovie 1.0 filters. See Register DirectShow Objects and the sample filters included with the DirectShow SDK for more information about AMovieDllRegisterServer2.

AMovieDllRegisterServer2

DLL and Setup Functions

Registers and unregisters filters.

HRESULT AMovieDllRegisterServer2(
BOOL bRegister
);

Parameters
bRegister
TRUE indicates register the filter, FALSE indicates unregister it.
Return Values

Returns an HRESULT value.

Remarks

Use this function to set up your filters. See Register DirectShow Objects and the sample filters included with the DirectShow SDK for more information.

Note: The filter registration process is changing to allow filters to register by category. For example, capture filters and compression filters are enumerated together in their respective categories. The following functions demonstrate how filter registration and unregistration by category might work. The AMCap sample demonstrates this procedure. The following function uses the IFilterMapper2 interface.

// Register Sample Compressor Filter
STDAPI
DllRegisterServer( void )
{
 HRESULT hr = AMovieDllRegisterServer2( TRUE );
 if( FAILED(hr) )
     return hr;

 const WCHAR *wszUniq = L"Sample Compressor Filter" ;

 IFilterMapper2 *pFm2 = 0;

 hr = CoCreateInstance( CLSID_FilterMapper2
                         , NULL
                         , CLSCTX_INPROC_SERVER
                         , IID_IFilterMapper2
                         , (void **)&pFm2       );

 if(FAILED(hr))
     return hr;

 hr = pFm2->RegisterFilter(
      CLSID_SampleCompressorFilter,
      wszUniq,
      0,
      &CLSID_VideoCompressorCategory,
      wszUniq,
      MERIT_DO_NOT_USE,
      NULL,
      0);

 pFm2->Release();

 return hr;
}

// Unregister Sample Compressor Filter
STDAPI
DllUnregisterServer( void )
{

HRESULT hr = AMovieDllRegisterServer2( FALSE );
if( FAILED(hr) )
    return hr;

const WCHAR *wszUniq = L"Sample Compressor Filter" ;

IFilterMapper2 *pFm2 = 0;

hr = CoCreateInstance( CLSID_FilterMapper2
                        , NULL
                        , CLSCTX_INPROC_SERVER
                        , IID_IFilterMapper2
                        , (void **)&pFm2       );

if(FAILED(hr))
    return hr;

hr = pFm2->UnregisterFilter(
     &CLSID_VideoCompressorCategory,
     wszUniq,
     CLSID_SampleCompressorFilter);

pFm2->Release();

return hr;
}

AMovieDllUnregisterServer

DLL and Setup Functions

Unregisters filters. ActiveMovie 1.0 only.

HRESULT AMovieDllUnregisterServer(void);

Return Values

Returns an HRESULT value.

Remarks

Use AMovieDllRegisterServer2 rather than this function to uninstall (unregister) your filters unless you need compatibility with ActiveMovie 1.0 filters. See Register DirectShow Objects and the sample filters included with the DirectShow SDK for more information about AMovieDllRegisterServer2.

AMovieSetupRegisterFilter

DLL and Setup Functions

Registers a filter's merit, pins, and media types in the registry using the filter mapper. ActiveMovie 1.0 only.

HRESULT AMovieSetupRegisterFilter(
const AMOVIESETUP_FILTER *const psetupdata,
IFilterMapper *pIFM,
BOOL bRegister
);

Parameters
psetupdata
Pointer to the AMOVIESETUP_FILTER data.
pIFM
Pointer to IFilterMapper interface.
bRegister
TRUE indicates register the filter, FALSE indicates unregister it.
Return Values

Returns an HRESULT value.

Remarks

The CBaseFilter base class uses this helper function to register a filter if the 1.0 ActiveMovie runtime is installed. It is provided for compatibility with ActiveMovie version 1.0 only.

Typically a filter will use AMovieDllRegisterServer and will not call this function directly.

AMovieSetupRegisterFilter2

DLL and Setup Functions

Registers a filter's merit, pins, and media types in the registry using IFilterMapper2.

HRESULT AMovieSetupRegisterFilter2(
const AMOVIESETUP_FILTER *const psetupdata,
IFilterMapper2 *pIFM2,
BOOL bRegister
);

Parameters
psetupdata
Pointer to the AMOVIESETUP_FILTER data.
pIFM
Pointer to IFilterMapper2 interface.
bRegister
TRUE indicates register the filter, FALSE indicates unregister it.
Return Values

Returns an HRESULT value.

Remarks

AMovieDllRegisterServer2 uses this helper function to register a filter after the COM server has been registered.

Typically a filter will use AMovieDllRegisterServer2 and will not call this function directly.


Error Message Function

The Errors.h header file provides a function for getting an error message for a given message identifier in the current language. The same header also provides the MAX_ERROR_TEXT_LEN equate, which indicates the maximum number of characters allowed in a message.
Function | Description
AMGetErrorText | Gets the error message text for a given message ID.

AMGetErrorText

Error Message Function

Retrieves the error message text for a given message identifier in the appropriate language.

DWORD AMGetErrorText(
HRESULT hr,
TCHAR *pBuffer,
DWORD MaxLen
);

Parameters
hr
Message identifier for the message text to be returned.
pBuffer
Area into which the message text will be stored.
MaxLen
Number of characters that pBuffer points to.
Return Values

Returns the number of characters stored in the buffer, or zero if an error occurred.


IUnknown Macro

To simplify the creation of new interfaces, the Combase.h header file includes a macro that declares the three methods of the IUnknown interface.
Function | Description
DECLARE_IUNKNOWN | Declares the three methods of the base interface for a new interface.

DECLARE_IUNKNOWN

IUnknown Macro

Declares the three methods of the base interface for a new interface.

#define DECLARE_IUNKNOWN

Remarks

When you create a new interface, it must derive from IUnknown, which has three methods: QueryInterface, AddRef, and Release. This macro simplifies the declaration process by declaring each of these methods for the new interface.


INonDelegatingUnknown Interface

To enable a class to support both nondelegating and delegating IUnknown interfaces in the same COM object, the Combase.h header file declares the INonDelegatingUnknown interface. This interface is a version of IUnknown and has three methods:
INonDelegatingUnknown::NonDelegatingQueryInterface
INonDelegatingUnknown::NonDelegatingAddRef
INonDelegatingUnknown::NonDelegatingRelease

For sample implementations of these methods, see CUnknown::NonDelegatingQueryInterface, CUnknown::NonDelegatingAddRef, and CUnknown::NonDelegatingRelease.

INonDelegatingUnknown

INonDelegatingUnknown Interface

A version of IUnknown renamed to enable a class to support both nondelegating and delegating IUnknown interfaces in the same COM object. The interface supports the following three methods, in vtable order:

HRESULT NonDelegatingQueryInterface(
REFIID iid,
void** ppvObject );

ULONG NonDelegatingAddRef(void);

ULONG NonDelegatingRelease(void);

Remarks

To use INonDelegatingUnknown for multiple inheritance, perform the following steps:

  1. Derive your class from an interface, for example, IMyInterface.
  2. Include DECLARE_IUNKNOWN in your class definition to declare implementations of QueryInterface, AddRef, and Release that call the outer unknown.
  3. Override NonDelegatingQueryInterface to expose IMyInterface with code such as the following:

     if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. Declare and implement the member functions of IMyInterface.

To use INonDelegatingUnknown for nested interfaces, perform the following steps:

  1. Declare a class derived from CUnknown.
  2. Include DECLARE_IUNKNOWN in your class definition.
  3. Override NonDelegatingQueryInterface to expose IMyInterface with the code such as the following:

     if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. Implement the member functions of IMyInterface. Use CUnknown::GetOwner to access the COM object class.
  5. In your COM object class, make the nested class a friend of the COM object class, and declare an instance of the nested class as a member of the COM object class.

    Because you must always pass the outer unknown and an HRESULT to the CUnknown constructor, you can't use a default constructor. You have to make the member variable a pointer to the class and make a new call in your constructor to actually create it.

  6. Override the NonDelegatingQueryInterface with code such as the following:

     if (riid == IID_IMyInterface) {
         return m_pImplFilter->
            NonDelegatingQueryInterface(IID_IMyInterface, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }

You can have mixed classes that support some interfaces through multiple inheritance and some interfaces through nested classes.

See Also

GetInterface, CUnknown, IUnknown Macro


Math Helper Functions

The Wxutil.h header file in the DirectShow base classes provides some mathematical helper functions. These are intended to help with time format conversions.
Function | Description
llMulDiv | Implements ((a*b)+rnd)/c for 32-bit values of a.
Int64x32Div32 | Implements ((a*b)+rnd)/c for 64-bit values of a.

llMulDiv

Math Helper Functions

Multiplies a by b, adds rnd to the 128-bit result, then divides by c.

LONGLONG WINAPI llMulDiv(
LONGLONG a,
LONGLONG b,
LONGLONG c,
LONGLONG rnd
);

Return Values

Returns either the (a * b + rnd)/c calculation or one of the following values.
Value | Condition
0x7FFFFFFFFFFFFFFF | Overflow occurred because the result is too large (positive).
0x8000000000000000 | Overflow occurred because the result is too large (negative).

Remarks

Rounding on the division is toward zero. Division by zero is counted as an overflow condition.

Int64x32Div32

Math Helper Functions

Multiplies a by b, adds rnd to the 96-bit result, then divides by c.

LONGLONG WINAPI Int64x32Div32(
LONGLONG a,
LONG b,
LONG c,
LONG rnd
);

Return Values

Returns either the (a * b + rnd)/c calculation or one of the following values.
Value | Condition
0x7FFFFFFFFFFFFFFF | Overflow occurred because the result is too large (positive).
0x8000000000000000 | Overflow occurred because the result is too large (negative).

Remarks

Rounding on the division is toward zero. Division by zero is counted as an overflow condition.


Media Type Functions

The Mtype.h header file in the DirectShow base classes provides helper functions for handling media types. These general-purpose functions create, copy and delete a task-allocated AM_MEDIA_TYPE structure. This is useful when using the IEnumMediaTypes interface, because the implementation allocates the structures that must be deleted later.

The functions are paired as follows:

  • CreateMediaType is the opposite of DeleteMediaType.
  • FreeMediaType is the opposite of CopyMediaType.
Function | Description
AreEqualVideoTypes | Compares the format, height, and width of two video sources.
CopyMediaType | Copies a task-allocated AM_MEDIA_TYPE structure.
CreateAudioMediaType | Initializes a media type structure given a wave format structure.
CreateMediaType | Allocates and initializes an AM_MEDIA_TYPE structure.
DeleteMediaType | Deletes a task-allocated AM_MEDIA_TYPE structure.
FreeMediaType | Frees a task-allocated AM_MEDIA_TYPE structure from memory.

AreEqualVideoTypes

Media Type Functions

Determines if two media types have the same video format, width, and height.

BOOL WINAPI AreEqualVideoTypes (
CMediaType *pmt1,
CMediaType *pmt2
);

Parameters
pmt1
First media type to compare.
pmt2
Second media type to compare.
Return Values

Returns TRUE if pmt1 and pmt2 have the same video format, width, and height or FALSE otherwise.

CopyMediaType

Media Type Functions

Copies a task-allocated AM_MEDIA_TYPE structure.

void WINAPI CopyMediaType(
AM_MEDIA_TYPE *pmtTarget,
const AM_MEDIA_TYPE *pmtSource
);

Parameters
pmtTarget
Pointer to an area of memory in which to place the new copy of the structure.
pmtSource
Pointer to a source structure to copy.
Return Values

No return value.

Remarks

Free the resources in the pmtTarget structure by calling FreeMediaType when your code is done with the structure.

CreateAudioMediaType

Media Type Functions

Initializes a media type structure given a wave format structure.

STDAPI CreateAudioMediaType(
const WAVEFORMATEX *pwfx,
AM_MEDIA_TYPE *pmt,
BOOL bSetFormat
);

Parameters
pwfx
Pointer to the supplied WAVEFORMATEX structure.
pmt
Pointer to the AM_MEDIA_TYPE structure to initialize.
bSetFormat
Flag indicating whether to initialize the format section of the AM_MEDIA_TYPE structure, specifically the cbFormat and pbFormat members. Specify TRUE to initialize the format section, FALSE otherwise.
Return Values

Returns E_OUTOFMEMORY if memory could not be allocated for the format data; S_OK otherwise.

CreateMediaType

Media Type Functions

Creates a task-allocated AM_MEDIA_TYPE structure.

AM_MEDIA_TYPE * WINAPI CreateMediaType(
AM_MEDIA_TYPE const *pSrc
);

Parameters
pSrc
Pointer to an AM_MEDIA_TYPE source structure.
Return Values

Returns a new AM_MEDIA_TYPE structure, or NULL if there is an error.

Remarks

Free the structure and resources allocated by this routine by calling DeleteMediaType when your code is done with the structure.

DeleteMediaType

Media Type Functions

Deletes a task-allocated AM_MEDIA_TYPE structure.

void WINAPI DeleteMediaType(
AM_MEDIA_TYPE *pmt
);

Parameters
pmt
Pointer to an AM_MEDIA_TYPE structure.
Return Values

No return value.

Remarks

The structure should have been created by a call to CreateMediaType.

FreeMediaType

Media Type Functions

Frees a task-allocated AM_MEDIA_TYPE structure from memory.

void WINAPI FreeMediaType(
AM_MEDIA_TYPE& mt
);

Parameters
mt
Address of the structure.
Return Values

No return value.

Remarks

The structure should have been initialized by a call to CopyMediaType.


Object and Pin Functions

The Wxutil.h and Combase.h header files in the DirectShow base classes provides helper functions for comparing objects and pins and retrieving interfaces to objects.
Function | Description
EqualPins | Checks if two pins are on the same object.
GetInterface | Returns an interface pointer to the requested client.
IsEqualObject | Checks if two interfaces are on the same object.

EqualPins

Object and Pin Functions

Checks if two pins are on the same object.

BOOL EqualPins(
IUnknown * pPin1,
IUnknown * pPin2
);

Parameters
pPin1
Address of one pin.
pPin2
Address of the other pin.
Return Values

Returns TRUE if the pins are both on the same object, or FALSE otherwise.

GetInterface

Object and Pin Functions

Retrieves an interface pointer.

HRESULT GetInterface(
LPUNKNOWN pUnk,
void **ppv
);

Parameters
pUnk
Pointer to the IUnknown interface.
ppv
Retrieved interface.
Return Values

Returns an HRESULT value.

Remarks

This member function performs a thread-safe increment of the reference count. To retrieve the interface and add a reference, call this function from your overriding implementation of the INonDelegatingUnknown::NonDelegatingQueryInterface method.

IsEqualObject

Object and Pin Functions

Checks if two interfaces are on the same object.

BOOL WINAPI IsEqualObject(
IUnknown * pFirst,
IUnknown * pSecond
);

Parameters
pFirst
Address of one interface.
pSecond
Address of the other interface.
Return Values

Returns TRUE if the interfaces are both on the same object, or FALSE otherwise.


Performance Macros

The Measure.h header file in the DirectShow base classes provides macros that help record performance data by maintaining a circular log of the start and stop times of certain events.
Macro | Description
MSR_START | Records the start time of the event.
MSR_STOP | Records the stop time of the event.

MSR_START

Performance Macros

Records the start time of the event with the given registered ID by adding the start time to the circular log and recording the time in StatBuffer.

#define MSR_START(
int Id
)

Parameters
Id
Registered ID of the event whose start is to be recorded.
Remarks

This macro does not update the statistical information. That happens when MSR_STOP is called.

MSR_STOP

Performance Macros

Records the stop time of the event with the given registered ID by adding the stop time to the circular log, and adding a StopTime-StartTime entry to the statistical record StatBuffer.

#define MSR_STOP(
int Id
)

Parameters
Id
Registered ID of the event whose stop is to be recorded.


Property Page Helper Functions

The Videoctl.h header file in the DirectShow base classes provides functions to help with property page implementations.
Function | Description
GetDialogSize | Retrieves the size of a resource dialog box in screen pixels.
StringFromResource | Loads a string from a resource file with the given resource identifier.
WideStringFromResource | Loads a Unicode string from a resource file with the given resource identifier.

GetDialogSize

Property Page Helper Functions

Retrieves the size of a resource dialog box.

BOOL WINAPI GetDialogSize(
int iResourceID,
DLGPROC pDlgProc,
LPARAM lParam,
SIZE *pResult
);

Parameters
iResourceID
Dialog box resource identifier.
pDlgProc
Pointer to the dialog box procedure.
lParam
Any user data wanted in pDlgProc.
pResult
Size of the dialog box, in screen pixels.
Return Values

Returns TRUE if the dialog box resource was found, or FALSE otherwise.

Remarks

Property pages can use this function to return the actual display size they require. Most property pages are dialog boxes and, as such, have dialog box templates stored in resource files. Templates use dialog box units that do not map directly onto screen pixels. When a property page has its GetPageInfo function called, it must return the actual display size in pixels. This method is passed the resource ID for the dialog box and will return its size in pixels.

To make the calculation, the function creates an instance of the dialog box. To avoid the dialog box appearing on the screen temporarily, the dialog box's template in the resource file should not have a WS_VISIBLE property.

StringFromResource

Property Page Helper Functions

Loads a string from a resource file with the given resource identifier.

TCHAR * WINAPI StringFromResource(
TCHAR *pBuffer,
int iResourceID
);

Parameters
pBuffer
String corresponding to iResourceID.
iResourceID
Resource identifier of the string to retrieve.
Return Values

Returns the same string as pBuffer. If the function is not successful, returns a null string.

Remarks

The pBuffer buffer must be at least STR_MAX_LENGTH bytes.

WideStringFromResource

Property Page Helper Functions

Loads a Unicode string from a resource file with the given resource identifier.

WCHAR * WINAPI WideStringFromResource(
WCHAR *pBuffer,
int iResourceID
);

Parameters
pBuffer
String corresponding to iResourceID.
iResourceID
Resource identifier of the string to retrieve.
Return Values

Returns the same string as pBuffer. If the function is not successful, returns a null string.

Remarks

Property pages are typically called through their COM interfaces, which use Unicode strings regardless of how the binary is built. This function allows you to convert a resource string to a Unicode string. The function converts the resource to a Unicode string (if it is not already one) after loading it.


Reference Time Function

The Refclock.h header file in the DirectShow base classes provides a reference time conversion function.
Function | Description
ConvertToMilliseconds | Converts the reference time to milliseconds.

ConvertToMilliseconds

Reference Time Function

Converts the reference time to milliseconds.

LONGLONG WINAPI ConvertToMilliseconds(
const REFERENCE_TIME& RT
);

Parameters
RT
Reference time, in 100-nanosecond units.
Return Values

Returns the reference time converted to milliseconds.


Stream Integer Functions

The Pstream.h header file in the DirectShow base classes contains a set of stream integer functions. These functions encode an integer in a stream object as 11 Unicode characters followed by one Unicode space. The interface to these functions might truncate to 32 bits. Values such as (unsigned) 0x80000000 would be written as -2147483648, but would still load as 0x80000000 again through ReadInt.
Member Function | Description
WriteInt | Writes an integer to a stream encoded as a Unicode string.
ReadInt | Reads a Unicode string-encoded integer from a stream.

WriteInt

Stream Integer Functions

Writes an integer to an IStream, encoded as described in Stream Integer Functions.

STDAPI WriteInt(
IStream *pIStream,
int n
);

Parameters
pIStream
Pointer to an IStream to which the encoded integer is to be written.
n
Integer value to be written.
Return Values

Returns an HRESULT value.

Remarks

The ReadInt function can be used to read the value written by WriteInt.

ReadInt

Stream Integer Functions

Reads an integer from an IStream.

STDAPI_(
int
)ReadInt(
IStream *pIStream,
HRESULT &hr
);

Parameters
pIStream
Pointer to an IStream from which the encoded integer is to be read.
hr
Reference to an HRESULT value (output).
Return Values

Returns the integer value (truncated to 32 bits), or zero if an error occurred.

Remarks

This function is a stripped-down subset of what sscanf can do (without dragging in the C run time).

The ReadInt function can be used to read the value written by WriteInt.


String Functions

The Wxutil.h header file in the DirectShow base classes provides wide string functions, if they are not already provided by the Microsoft® Win32® environment.
Function | Description
AMGetWideString | Allocates and creates a wide string version of an existing nonwide string.
lstrcmpiW | Compares two wide strings, ignoring case.
lstrcmpW | Compares two wide strings.
lstrcpynW | Copies one wide string to another, with a maximum length.
lstrcpyW | Copies one wide string to another.
lstrlenW | Gets the length of a wide string in wide characters.

AMGetWideString

String Functions

Allocates and creates a Unicode version of an existing non-Unicode string.

STDAPI AMGetWideString(
LPCWSTR pszString,
LPWSTR *ppszReturn
);

Parameters
pszString
Non-Unicode source string.
ppszReturn
Address of a Unicode string that will contain pszString.
Return Values

Returns S_OK if successful, E_POINTER if ppszReturn is NULL, or E_OUTOFMEMORY if not enough memory is available.

lstrcmpiW

String Functions

Compares two wide-character strings. The comparison is not case sensitive.

int lstrcmpiW(
LPCWSTR lpszString1,
LPCWSTR lpszString2
);

Parameters
lpszString1
Pointer to the first null-terminated wide string to be compared.
lpszString2
Pointer to the second null-terminated wide string to be compared.
Return Values

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

Remarks

The lstrcmpiW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpiW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

lstrcmpW

String Functions

Compares two wide-character strings. The comparison is case sensitive.

int lstrcmpW(
LPCWSTR lpszString1,
LPCWSTR lpszString2
);

Parameters
lpszString1
Pointer to the first null-terminated wide string to be compared.
lpszString2
Pointer to the second null-terminated wide string to be compared.
Return Values

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

Remarks

The lstrcmpW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

lstrcpyW

String Functions

Copies a wide string to a buffer.

LPWSTR lstrcpyW(
LPWSTR lpszString1,
LPCWSTR lpszString2
);

Parameters
lpszString1
Pointer to a buffer to receive the contents of the string pointed to by the lpszString2 parameter. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
Pointer to the null-terminated wide string to be copied.
Return Values

Returns a pointer to the buffer.

lstrcpynW

String Functions

Copies a wide string to a buffer, up to a specified number of wide characters.

LPWSTR lstrcpynW(
LPWSTR lpszString1,
LPCWSTR lpszString2,
int iMaxLength
);

Parameters
lpszString1
Pointer to a buffer to receive the contents of the string that the lpszString2 parameter points to. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
Pointer to the null-terminated wide string to be copied.
iMaxLength
Maximum number of wide characters to copy, including a terminating null character.
Return Values

Returns a pointer to the buffer.

Remarks

If iMaxLength is nonzero, lstrcpynW always inserts a terminating null wide character in the destination string, which could result in the source string being truncated.

lstrlenW

String Functions

Retrieves the length of the specified wide string.

int lstrlenW(
LPCWSTR lpszString
);

Parameters
lpszString
Pointer to a null-terminated wide string.
Return Values

If the function succeeds, the return value specifies the length of the string, in wide characters.


Message Function

The Wxutil.h header file in the DirectShow base classes provides a helper function for processing messages.
Function | Description
WaitDispatchingMessages | Waits for a for the HANDLE hObject before dispatching messages. While waiting, messages sent to windows on the thread by SendMessage will be processed.

WaitDispatchingMessages

Message Function

Waits for a for the HANDLE hObject before dispatching messages. While waiting, messages sent to windows on the thread by SendMessage will be processed.

DWORD WINAPI WaitDispatchingMessages(
HANDLE hObject,
DWORD dwWait,
HWND hwnd = NULL,
UINT uMsg = 0
);

Parameters
hObject
Handle of object to wait for.
dwWait
Time-out interval in milliseconds.
hwnd
Handle to a window.
uMsg
Win32 message.
Return Values

If the function succeeds, the return value indicates the event that caused the function to return. If the function fails, the return value is WAIT_FAILED.

The return value on success is one of the following values:
Value | Meaning
WAIT_ABANDONED | The specified object is a mutex (mutual exclusion) object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_OBJECT_0 | The state of the specified object is signaled.
WAIT_TIMEOUT | The time-out interval elapsed, and the object's state is nonsignaled.

Remarks

This function enables sent messages to be processed while waiting for a handle to a window. Use this function to wait for an object to be processed and to perform mutually exclusive operations, consequently avoiding possible deadlocks in objects with windows.

This helper function is similar to the Win32 WaitForSingleObject function.


Debugging

This section describes how to debug DirectShow in C and C++. It also contains reference entries for the macros and functions that DirectShow supplies to assist debugging.

Debugging with DirectShow

Assert Macros and Functions

Breakpoint Macros and Function

Debug Output

Debug NOTE (Message) Macros

Pointer Validation Macros

Miscellaneous Macros

Debug Logging by Module Level

Object Register Debugging

Wait Debugging

Debug Output Location


Debugging with DirectShow

This article discusses debugging practices in Microsoft® DirectShow™ for the C and C++ languages. Many of these practices apply both to writing filters and to writing applications that use the DirectShow run time. The article provides some tips on writing code that can be easily debugged and some general debugging topics. This article also provides some hints about detecting memory leaks.

Contents of this article:

  • Writing Code You Can Test and Debug
  • Using Different Kinds of Builds
  • Debugging New Filters
  • Detecting Leaks

Writing Code You Can Test and Debug

Debugging code in the DirectShow environment can be easier if it's written to be easily tested and debugged in the first place. Some techniques that DirectShow supports include the following, which are discussed in this section.

  • Assertion Checking
  • Pass Debugging Names
  • Debug Logging
  • IOStream Sample Code
  • Critical Section Usage
  • Pointer Validation
  • DLL Base Address Conflicts

Assertion Checking

Use assertion checking liberally. If you're not familiar with asserts, they're a popular way to isolate potential programming errors. DirectShow provides a number of assertion macros and functions, including ASSERT. The Microsoft® Foundation Classes (MFC) have an equivalent ASSERT macro. For example the following displays a message box if the value of First does not equal NULL:

    ASSERT( First != NULL );

For more information about assertion, see Assert Macros and Functions.

Pass Debugging Names

Pass the debugging name to the constructors that support it. Tracking object creation and destruction is provided in debugging builds for the CBaseObject class and classes derived from it. The object register is the list of objects that have been created but not yet destroyed in those classes. The debugging name that is passed to the constructors of those classes is stored in the object register. For more information about debugging object registers and the DbgDumpObjectRegister function, see Object Register Debugging.

Debug Logging

Use the DirectShow DbgLog function to display debugging messages on a debugger as your program executes. Here's an example from the bouncing ball source filter:

    DbgLog(( LOG_TRACE, 1, TEXT("New time: %d, Proportion: %d"),
        m_iRepeatTime, q.Proportion));

See the Debug Logging by Module Level for more information on the following topics:

  • The macros and functions you can call to do debugging logging from code you write.
  • How to enable and disable debugging logging by module level at run time.
  • How to indicate the destination of the output of the debugging log.

IOStream Sample Code

The C and C++ helpers provided in the IOStream helper library, SampIOS.lib, provide text output of the IBaseFilter interface and other DirectShow objects. The output from these helpers might be useful during debugging, to help understand the details of a given pin or filter. You can use these helpers in your DirectShow filters and applications. For more information about this library, see SampIOS Sample (IOStream Helper Library).

Critical Section Usage

To make deadlocks easier to track, insert assertions in the code that determine whether a critical section is owned by the calling code. The CritCheckIn and CritCheckOut functions indicate whether the calling thread owns the given critical sections, and are generally called in ASSERT macros. For more information about these functions, see CCritSec Debug Functions.

For debug logging of each lock and unlock of a given critical section, you might want to use the DirectShow DbgLockTrace function.

Note Logging can affect performance.

Pointer Validation

Consider using the pointer validation macros. For example, you can call ValidateReadPtr to ensure that the given pointer actually points to readable memory. Note the performance cost of each of these calls. Currently, the DirectShow pointer validation macros are built on top of the Win32 pointer validation functions such as IsBadReadPtr. On some systems, the Win32 pointer validation functions swap in every page in the range specified. For more information about validation macros, see Pointer Validation Macros.

DLL Base Address Conflicts

If you copy any sample makefile to create any new DLL, including filters and plug-in distributors (PIDs), ensure you change the base address to avoid collisions with other DLLs. A collision of DLL load address results in one of the DLLs having to be relocated during the time of loading. This increases the load time for that DLL.

In the sample makefiles, the DLL base address is set in DLL_BASE, which is used in ActiveX.mak. Do not let ActiveX.mak use the default value for DLL_BASE, because this will cause collisions.

Using Different Kinds of Builds

DirectShow can be built for three kinds of builds: retail, debug, and performance. See Reserved Identifiers for information on the kinds of builds. Debugging has varying degrees of difficulty for the three kinds of builds, depending on the situation. For instance, the debug build can provide much more information, but it can run so slowly as to make real-time debugging impossible.

The binaries you create must match the kind of build you're using. The makefiles provided for each sample use ActiveX.mak, which comes with the DirectShow SDK. Comments at the head of ActiveX.mak explain the various nmake command-line parameters to use to obtain binaries compatible with the different DirectShow builds. Some of these parameters define identifiers like DEBUG and PERF when compiling the C or C++ code.

If you must have build-dependent code, you can conditionally compile with the same identifiers that the DirectShow headers use for that purpose. See Reserved Identifiers for a list of the identifiers reserved for that purpose.

For instance, in C or C++, you can conditionally compile code like this:

    ...   /* normal processing */
#ifdef DEBUG
    ...   /* debug only code */
#endif
    ...   /* resume normal processing */

Debugging New Filters

This section discusses the following points of which you should be aware when debugging new filters:

  • Avoid GUID Conflicts
  • Test With the Filter Graph Editor and Other Sample Filters
  • Add the Filter as an Additional DLL in Developer Studio

Avoid GUID Conflicts

DirectShow uses globally unique identifiers (GUIDs) to find each filter, pin, and property page. Avoid reusing any of the same GUIDs when copying from the DirectShow sample code. The Guidgen.exe and Uuidgen.exe utilities generate unique GUIDs.

Test With the Filter Graph Editor and Other Sample Filters

Register your new filter. See Register DirectShow Objects and AMovieDllRegisterServer2 for information about registering a filter.

After you have registered your filter, you can use a tool called the Filter Graph Editor (also called GraphEdit, or Graphedt.exe) to insert your filter into a filter graph and connect it to other filters. You can access GraphEdit from the DXMedia SDK program group. Run GraphEdit and choose Insert Filters from the Graph menu to insert your filter.

If you are debugging an audio filter, there are two sample filters you might consider connecting to your filter to make sure it behaves as expected. You can also look at the source code for those samples to see how they implement methods and member functions. For overviews of those code samples, see Synth Sample (Audio Synthesizer Filter) and Scope Sample (Oscilloscope Filter).

After you have the Filter Graph Editor successfully loading your new filter, you can use the File Dump Filter (Dump.ax) as a useful debugging tool. For instance, it can be used to verify, bit by bit, the results of a transform filter. Build a graph manually using the Filter Graph Editor and hook the File Dump Filter onto the output of a transform or any other pin. You can also hook up the Inftee Sample (Infinite-Pin Tee Filter) (InfTee.ax), and put the File Dump Filter on one leg of the tee and the "normal" output on another to monitor what happens in the real-time case. For more information, see Dump Sample (Dump Filter).

Add the Filter as an Additional DLL in Developer Studio

If you're going to debug your filter with Microsoft Developer Studio version 5.0, you must tell the debugger about your filter. Here are the steps you should follow in Developer Studio to identify your filter as being a debuggable DLL:

  1. From the Project menu, choose Settings....
  2. Select the Debug tab.
  3. Choose "Additional DLLs" from the Category drop-down list.
  4. Add "myfilter.ax" to the list, where "myfilter" is the name of your filter.

Detecting Leaks

Detecting and fixing memory leaks is another important debugging topic.

Visual C++ has an optional debug heap, which can be useful in tracking down memory leaks. (See the "Using the Debug Heap" section of the Visual C++ documentation for more information.) For example, the Visual C++ _CrtSetDbgFlag function enables you to turn on the memory-leak-checking flag bit.

Other providers of memory leak tools can be found in the Microsoft Enterprise Development Partners directory.

Another kind of leak is of COM object references. You can track down object reference leaks by performing the following steps.

  1. Put a break point on the NonDelegatingAddRef and NonDelegatingRelease methods of that object.
  2. Use Developer Studio (or another debugger) and step through every reference count change, trying to pair them up.
  3. Look at the call stack for each change.


Assert Macros and Functions

The Microsoft® DirectShow™ SDK has three assertion macros: ASSERT, EXECUTE_ASSERT, and KASSERT. The most commonly used assertion macro is ASSERT. If ASSERT fails, DirectShow displays a message box that lists the file and line number of the macro call. The EXECUTE_ASSERT macro is similar to ASSERT except that the condition will still be evaluated in a build of any kind. The third assertion macro is KASSERT, which is more suitable for pure filters, such as those in the kernel, where the condition is printed onto the debugger rather than to a message box.

There are also two assertion functions: DbgAssert and DbgKernelAssert. You should call the assertion functions from assertion macros, rather than from normal code.
Name | Description
ASSERT | Checks an assertion in a debug build.
DbgAssert | Handles an assertion failure in a debug build.
DbgKernelAssert | Handles a kernel assertion failure in a debug build.
EXECUTE_ASSERT | Always evaluates a condition; if it is not TRUE in a debug build, treat this as an assertion failure.
KASSERT | Checks a kernel assertion in a debug build.

ASSERT

Assert Macros and Functions

Evaluates the given condition in a debug build. If the resulting evaluation is false, then ASSERT calls DbgAssert to handle the assertion failure. DbgAssert can return to its caller later, if the user so desires.

ASSERT(
cond
);

Parameters
cond
Boolean expression that defines the condition to evaluate.
Remarks

If you use the ASSERT macro, DbgAssert might display a message box. If this is not acceptable in your environment, you can use KASSERT (kernel assert) instead.

Here are two examples of ASSERT calls:

ASSERT( First != NULL);
ASSERT( StartTime <= EndTime);

DbgAssert

Assert Macros and Functions

Handles an assertion failure in a debug build. DbgAssert will display a message box that includes the condition text, source file name, and source line number. The user will be given the choice to ignore the assertion failure, debug the assertion, or force the application to exit. Thus DbgAssert might return to the caller, depending on the user's actions.

void WINAPI DbgAssert(
const TCHAR *pCondition,
const TCHAR *pFileName,
INT iLine
);

Parameters
pCondition
Pointer to a string version of a Boolean expression.
pFileName
Pointer to a source file name.
iLine
Line number within the source file.
Remarks

This function is available only in a debug build. Usually, DbgAssert will be called by macros such as ASSERT, not directly from other code.

If you use the ASSERT macro, DbgAssert might display a message box. If this is not acceptable in your environment, you can use DbgKernelAssert instead.

DbgKernelAssert

Assert Macros and Functions

Called in a debug build to print the condition onto the kernel debugger, including the condition text, source file name, and source line number.

void WINAPI DbgKernelAssert(
const TCHAR *pCondition,
const TCHAR *pFileName,
INT iLine
);

Parameters
pCondition
Pointer to a string version of a Boolean expression.
pFileName
Pointer to a source file name.
iLine
Line number within the source file.
Remarks

This function is available only in a debug build. Usually, DbgKernelAssert is called by macros such as KASSERT, not directly from other code.

Unlike DbgAssert, when macros call DbgKernelAssert in a debug build, no message box appears.

EXECUTE_ASSERT

Assert Macros and Functions

Evaluates the condition. In a debug build, if the resulting value is not TRUE, then the EXECUTE_ASSERT macro will invoke DbgAssert to handle the assertion failure. DbgAssert might return to the caller, depending on the user's actions.

EXECUTE_ASSERT(
cond
);

Parameters
cond
Condition (a Boolean expression), which is always evaluated. This contrasts with ASSERT and many other traditional assertion macros, which do not evaluate the condition in nondebug builds.
Remarks

If you use the EXECUTE_ASSERT macro in a debug build, DbgAssert might display a message box. If this is not acceptable in your environment, you can use KASSERT (kernel assert) instead.

KASSERT

Assert Macros and Functions

In a debug build, if the condition evaluates to FALSE, the KASSERT macro prints the condition on the kernel debugger, including the file name and line number.

KASSERT(
cond
);

Parameters
cond
Condition (a Boolean expression).
Remarks

This macro is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

Unlike ASSERT and EXECUTE_ASSERT, if you use this macro in a debug build no message box will appear.


Breakpoint Macros and Function

You can use the breakpoint macros and function to break into the debugger (either the regular debugger or the kernel debugger). For example, DbgBreak causes a regular debugger breakpoint, whereas KDbgBreak causes a kernel debugger breakpoint.
Name | Description
DbgBreak | Breakpoint with message box.
DbgBreakPoint | Breakpoint with message box.
KDbgBreak | Breakpoint with message on kernel debugger.

DbgBreak

Breakpoint Macros and Function

Generates a message box in a debug build with the indicated string literal, the source file name, and the source line number. Buttons in the message box enable you to break into the debugger, kill the application, or ignore the message box.

DbgBreak(
strLiteral
);

Parameters
strLiteral
Text string, which must be in quotation marks.
Remarks

This macro is ignored unless DEBUG is defined when the Microsoft® DirectShow™ headers are included.

DbgBreakPoint

Breakpoint Macros and Function

Generates a message box in a debug build with the indicated string literal, the source file name, and the source line number. Buttons in the message box enable you to break into the debugger, kill the application, or ignore the message box.

void WINAPI DbgBreakPoint(
const TCHAR *pCondition,
const TCHAR *pFileName,
INT iLine
);

Parameters
pCondition
Pointer to a string indicating what happened.
pFileName
Pointer to a source file name.
iLine
Line number within the source file.
Remarks

This function is available only in a debug build.

KDbgBreak

Breakpoint Macros and Function

Generates a kernel debugger message in a debug build with the indicated string literal, the source file name, and the source line number.

KDbgBreak(
strLiteral
);

Parameters
strLiteral
Text string, which must be in quotation marks.
Remarks

This macro is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.


Debug Output

The debug output facility is just one of several facilities of debug logging available with Microsoft® DirectShow™. This facility is monolithic (that is, it is either on or off). For information about the facility with the most precise control enabling and disabling logging, see Debug Logging by Module Level. For information about the simplest facility, see Debug NOTE (Message) Macros.

For more information about how DbgOutString chooses the debug output location, see Debug Output Location. DbgInitialise opens the debug output location and DbgTerminate closes it.
Name | Description
DbgOutString | Sends a debug string to the debug output location.
DumpGraph | Sends debugging information from the filter graph to the debug output location.

DbgOutString

Debug Output

Outputs the given string to the debug output location.

void WINAPI DbgOutString(
LPCTSTR psz
);

Parameters
psz
Pointer to a string to be output.
Remarks

DbgOutString is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included. That is, it is a function in a debug build, and a macro that does nothing in other builds.

DumpGraph

Debug Output

Sends debugging information from the filter graph to the debug output location.

void WINAPI (
IFilterGraph *pGraph,
DWORD dwLevel
)

Parameters
pGraph
Pointer to the filter graph to get debugging information about.
dwLevel
Logging level for this message, where zero means always log.
Remarks

Call this helper function to send potential error messages after you instantiate a filter graph.


Debug NOTE (Message) Macros

The NOTE macros provide debug message abilities in the Microsoft® Foundation Class Library (MFC) style. For more information about how the NOTE macros are implemented, see Debug Logging by Module Level. The NOTE macros work like a call to DbgLog, with a message type of LOG_TRACE, and a logging level of 5. For more information about how NOTE macros choose the debug output location, see Debug Output Location.
Macro | Description
NOTE | Logs a debug message with zero additional parameters.
NOTE1 | Logs a debug message with one additional parameter.
NOTE2 | Logs a debug message with two additional parameters.
NOTE3 | Logs a debug message with three additional parameters.
NOTE4 | Logs a debug message with four additional parameters.
NOTE5 | Logs a debug message with five additional parameters.

NOTE through NOTE5 Macros

Will format and print their parameters on the debugger.

NOTE(
pFormat
);
NOTEx(
pFormat,
[a-e]
);

Parameters
pFormat
A printf-style format string, which must be in quotation marks.
a through e
Optional parameters, each of which must have a respective format string portion (such as "%d").
Remarks

These macros are ignored unless DEBUG is defined when the Microsoft DirectShow™ headers are included. The following example shows the syntax for the NOTE1 through NOTE5 macros.

NOTE1(pFormat, a);
NOTE2(pFormat, a, b);
NOTE3(pFormat, a, b, c);
NOTE4(pFormat, a, b, c, d);
NOTE5(pFormat, a, b, c, d, e);


Pointer Validation Macros

Microsoft® DirectShow™ provides some macros to make pointer usage more robust. These include a simple CheckPointer macro (which tests if a given pointer is NULL). These also include a number of ValidateXxxPtr macros, which ensure a given pointer actually refers to the correct kind of memory, although possibly with a significant performance hit for each test.
Name | Description
CheckPointer | Checks whether or not a given pointer is NULL.
ValidateReadPtr | Validates a read pointer.
ValidateReadWritePtr | Validates a read/write pointer.
ValidateStringPtr | Validates a string pointer.
ValidateStringPtrA | Validates an ANSI string pointer.
ValidateStringPtrW | Validates a wide (Unicode) string pointer.
ValidateWritePtr | Validates a write pointer.

CheckPointer

Pointer Validation Macros

Determines if a given pointer is NULL. If the pointer is NULL, CheckPointer returns a user-defined value.

CheckPointer(
p,
ret
);

Parameters
p
Pointer to check.
ret
Value your function will return if p is NULL.
Remarks

The following examples illustrate how to call this macro.

HRESULT OneFunction(VOID *pSomeParameter)
{
    CheckPointer(pSomeParameter, E_INVALIDARG)
}

BOOL AnotherFunction(VOID *pSomeParameter)
{
    CheckPointer(pSomeParameter, FALSE)
}

ValidateReadPtr

Pointer Validation Macros

Checks a read pointer. If the pointer is not valid, this macro calls DbgBreak.

ValidateReadPtr(
const void * p,
UINT cb
);

Parameters
p
Pointer value (of any type).
cb
Byte count to be checked.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.

ValidateReadWritePtr

Pointer Validation Macros

Checks a read/write pointer. If the pointer is not valid, this macro calls DbgBreak.

ValidateReadWritePtr(
const void * p,
UINT cb
);

Parameters
p
Pointer value (of any type).
cb
Byte count to be checked.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.

ValidateStringPtr

Pointer Validation Macros

Checks a string pointer and calls DbgBreak if the pointer is not valid.

ValidateStringPtr(
LPCTSTR p
);

Parameters
p
TCHAR string pointer value.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.

ValidateStringPtrA

Pointer Validation Macros

Checks an ANSI string pointer and calls DbgBreak if the pointer is not valid.

ValidateStringPtrA(
LPCSTR p
);

Parameters
p
ANSI string pointer value.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.

ValidateStringPtrW

Pointer Validation Macros

Checks a wide (Unicode) string pointer and calls DbgBreak if the pointer is not valid.

ValidateStringPtrW(
LPCWSTR p
);

Parameters
p
Wide string pointer value.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.

ValidateWritePtr

Pointer Validation Macros

Checks a write pointer and calls DbgBreak if the pointer is not valid.

ValidateWritePtr(
const void * p,
UINT cb
);

Parameters
p
Pointer value (of any type).
cb
Byte count to be checked.
Remarks

This macro is ignored unless DEBUG or VFWROBUST is defined when the Microsoft DirectShow headers are included.


Miscellaneous Macros

Some miscellaneous macros are provided, mainly for debug string processing. In particular, the NAME macro is used with many class constructors that support debug names. The REMIND macro is less useful; it just builds a reminder string (including the source file name and line number), which can be displayed at compile time.
Macro | Description
NAME | Generates a debug-only name.
REMIND | Generates a compile-time string.

NAME

Generates a debug-only string.

NAME(
strLiteral
);

Parameters
strLiteral
Text string, which must be in quotation marks.
Remarks

This macro is helpful for generating the debug name passed to many Microsoft® DirectShow™ class constructors. (See Object Register Debugging for more information about using that aspect of debugging.) For example:

x = new CVideoRenderer(NAME("Sample Video Renderer"),pUnk,phr);

The NAME macro generates NULL unless DEBUG is defined when the Microsoft DirectShow headers are included.

REMIND

Generates a compile-time string.

REMIND(
strLiteral
);

Parameters
strLiteral
Text string, which must be in quotation marks.
Remarks

This generated string includes the parameter string, the source file name, and the line number.

For example, to generate a compile-time warning, use the following syntax.

#pragma message (REMIND("Add automation support"))


Debug Logging by Module Level

Some of the more conventional debug logging techniques provided by Microsoft® DirectShow™ (like DbgOutString) are monolithic. That is, they are either all on (in a debug build) or all off (in other builds). DirectShow provides other debug logging techniques that give much finer control in turning logging on and off. These pinpoint techniques make it easy to isolate and debug individual modules without seeing other people's extraneous debug output, or suffering the possible performance hit when too much information is logged. You can control the pinpoint DirectShow debug routines by module, by type, and by level, as defined in the following list.

  • A module is used in the Win32 sense, as in a .dll or .exe file that the Win32 LoadLibrary API can read. Thus, you can specify that you want debug output from your filter (for example, NewFilter.ax) and not any other.
  • A type is a bitmask that defines the kind(s) of informational string being presented. For example, timing information, errors, and memory allocations are some of the types of logging that can be individually controlled. For the complete list of types, see Types of Logging Information. You can combine types by using a bitwise-OR of their bitmasks; for example, (LOG_TRACE | LOG_ERROR).
  • A level is a DWORD value indicating the relative importance of this output, where zero is the most important level. A debug level of zero means that output is always sent to the debugger. Using zero as the debug logging level is encouraged only for major errors or events; otherwise, the logging of too much information might slow down the system. A request to log at a nonzero logging level is checked with the current debug level for this module; if it is less than or equal to the current level, it will be logged.

You can set the initial debug levels for a given test run. For each module you want to control, you can store a debugging level for each of the types in the registry. For a list of the registry names to use, see Registry Setting of Debug Levels by Type.

You call the DbgLog macro to attempt to log some piece of data, which might or might not actually be logged, depending on the current debug levels. When you call DbgLog, you supply one or more type flags (possibly combined by bitwise-OR), the debug level, and the data to be logged in the form of a printf-style format string, which can refer to optional parameters. (By definition, C/C++ macros allow only a fixed number of parameters. In your call to DbgLog, you enclose all parameters in an extra set of parentheses. This is a common C/C++ idiom.)

Following are some examples of calling DbgLog. The first example is a simple call with one type and no optional parameters; the second call gives two types and no optional parameters; the third call has two types and includes an optional parameter.

DbgLog((LOG_TRACE, 1, TEXT("CVidCap created")));
DbgLog((LOG_ERROR|LOG_TRACE, 1, TEXT("Driver failed to connect") ) );
DbgLog(( LOG_ERROR|LOG_TRACE, 2
       , TEXT("Driver disconnect: %x"), bDriverDisconnected) );

Each module has its own current debug level for each type. These current levels are initialized from the registry by DbgInitialise. For dynamic-link libraries (DLLs) linking to strmbase.lib, the DbgInitialise function is called automatically when the DLL is loaded. Executables must call DbgInitialise explicitly, with the module instance handle given to them through the WinMain entry point. An executable must also call DbgTerminate when finished to clean up the resources the debug library uses. This cleanup is also done automatically for DLLs.

For more information about how the debug output location is chosen, see Debug Output Location.

Types of Logging Information

A DWORD value is used to indicate types of information to be logged, as indicated by the following bitmasks. Some operations can be performed on multiple types simultaneously, by using bitwise-OR to combine the bitmasks; for example, (LOG_TRACE | LOG_ERROR).
LOG_TIMING | Timing and performance measurements.
LOG_TRACE | General step and call tracing.
LOG_MEMORY | Memory and object allocation/destruction.
LOG_LOCKING | Locking/unlocking of critical sections.
LOG_ERROR | Debug error notification.

Registry Setting of Debug Levels by Type

For every module and executable, Microsoft DirectShow will load a debugging level key for each of the five types. The level keys are stored in the registry under the HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<KeyName> key values. The allowable values for <KeyName> in the registry are: "TIMING", "TRACE", "MEMORY", "LOCKING", and "ERROR". Note that the values read from the registry are all read during initialization; DirectShow does not look for update notifications while it runs. If the values change, you must restart the application to pick them up.
Name | Description
DbgCheckModuleLevel | Checks if given types and level are being logged.
DbgInitialise | Initializes the debug library with the module handle and sets the current logging levels accordingly.
DbgLog | Logs a message for given types and level. (Ignored except in debug builds.)
DbgLogInfo | Logs a message for given types and level. (Provided only in debug builds.)
DbgSetModuleLevel | Changes the logging level for given types.
DbgTerminate | Cleans up the debug library.
DisplayType | Displays the given media type.

DbgCheckModuleLevel

Debug Logging by Module Level

Checks whether logging is enabled for the given message types and level. If logging is enabled for any of the given types at the level given, DbgCheckModuleLevel indicates that the message should be logged.

BOOL WINAPI DbgCheckModuleLevel(
DWORD Types,
DWORD Level
);

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
Return Values

Returns TRUE if these module types and level are to be logged; otherwise, returns FALSE.

Remarks

DbgCheckModuleLevel is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

DbgInitialise

Debug Logging by Module Level

Initializes the debug library. Among other things, it sets the current logging levels to correspond to the levels that are appropriate for the indicated module.

void WINAPI DbgInitialise(
HINSTANCE hInst
);

Parameters
hInst
Module instance handle.
Remarks

DbgInitialise is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included. DbgInitialise also opens the debug output location, as described in Debug Output Location.

DbgLog

Debug Logging by Module Level

Invokes the DbgLogInfo function.

void WINAPI DbgLog(
DWORD Types,
DWORD Level,
const TCHAR *pFormat,
...
);

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.
Remarks

DbgLog is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

DbgLogInfo

Debug Logging by Module Level

Formats and sends a message to the debugger, if debug logging is enabled for the given message type and level.

void WINAPI DbgLogInfo(
DWORD Types,
DWORD Level,
const TCHAR *pFormat,
...
);

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.
Remarks

DbgLogInfo exists only in debug builds.

DbgSetModuleLevel

Debug Logging by Module Level

Changes the current logging level for message types whose bits are set in the Types parameter to Level. Other logging levels are unchanged.

void WINAPI DbgSetModuleLevel(
DWORD Types,
DWORD Level
);

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level that will be set for future messages. That is, future messages must have a level less than or equal to this value in order for the debug routines to log them.
Remarks

The DirectShow debug routines ignore DbgSetModuleLevel unless DEBUG is defined when the Microsoft DirectShow headers are included.

DbgTerminate

Debug Logging by Module Level

Cleans the debug library.

void WINAPI DbgTerminate( );

Remarks

This is called to clean up the resources the debug library uses. If you called DbgInitialise, then you should call DbgTerminate. For example, DbgTerminate deletes the object register list. (For more information about using that aspect of debugging, see Object Register Debugging.) DbgTerminate also closes the debug output location, as described in Debug Output Location. DbgTerminate is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

DisplayType

Debug Logging by Module Level

Displays the media type details on the debug log.

void WINAPI DisplayType(
LPSTR label,
const AM_MEDIA_TYPE *pmtIn
);

Parameters
label
Short message to be logged with the media type.
pmtIn
Pointer to the media type to be displayed.
Remarks

The major types and subtypes are converted into strings for display. DisplayType also asks the base classes for a string description of the subtype, so MEDIASUBTYPE_RGB565 becomes RGB 565 16-bit. In addition, it displays the fields in the BITMAPINFOHEADER structure; this should succeed because input types are not accepted unless the format is big enough.

DisplayType is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.


Object Register Debugging

The CBaseObject class is at the root of all Microsoft® DirectShow™ base classes. It maintains the object register, which is the list of objects (in those classes) that have been created but not yet destroyed. It exists primarily to provide debugging assistance by keeping a count of all active DirectShow objects. All base class constructors in derived base classes provide a debugging object name as the first parameter and call the CBaseObject constructor. You can view the debugging object name sent to this base class on a debugging monitor.

For more information about how the debug output location is chosen, see Debug Output Location.
Name | Description
DbgDumpObjectRegister | Displays details about all objects in the object register.

DbgDumpObjectRegister

Object Register Debugging

Displays details about all objects in the object register.

void WINAPI DbgDumpObjectRegister( );

Remarks

The DirectShow debug routines ignore DbgDumpObjectRegister unless DEBUG is defined when the Microsoft DirectShow headers are included.


Wait Debugging

DirectShow provides facilities for wait debugging. These facilities build on the Microsoft® Win32® HANDLE-based wait facilities, but you can expand them to debug specific wait conditions.

In the debug build, you can update the global current time-out with calls to DbgSetWaitTimeout. Updating the current time-out does not affect debug wait calls that are already waiting. If this is a debug build and a value named TIMEOUT exists in the registry under the HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL key, the TIMEOUT value is used as the initial current time-out. TIMEOUT must be a REG_DWORD value and is measured in milliseconds. If not, the initial time-out defaults to INFINITE.

Call the following functions to perform debuggable waiting.
Name | Description
DbgSetWaitTimeout | Updates the current time-out value.
DbgWaitForMultipleObjects | Waits for an array of handles to be signaled, or for the current time-out to expire.
DbgWaitForSingleObject | Waits for a handle to be signaled, or for the current time-out to expire.

DbgSetWaitTimeout

Wait Debugging

Updates the global current time-out value. (This update does not apply to debug wait calls that are already waiting.)

void WINAPI DbgSetWaitTimeout(
DWORD dwTimeout
);

Parameters
dwTimeout
New time-out value in milliseconds, or INFINITE.
Remarks

DbgSetWaitTimeout is ignored unless DEBUG is defined when the Microsoft® DirectShow™ headers are included.

DbgWaitForMultipleObjects

Wait Debugging

In a debug build, waits for the current time-out, or the array of handles to become signaled, whichever comes first. In other builds, this is treated as a call to the Microsoft Win32® WaitForMultipleObjects function, with an INFINITE time-out.

DWORD WINAPI DbgWaitForMultipleObjects(
DWORD nCount,
CONST HANDLE *lpHandles,
BOOL bWaitAll
);

Parameters
nCount
Number of entries in the lpHandles array.
lpHandles
Array of HANDLE values.
bWaitAll
TRUE if all handles in the array must become signaled to satisfy the wait. FALSE if any one handle can satisfy the wait.

DbgWaitForSingleObject

Wait Debugging

In a debug build, waits for the current time-out, or the given handle to become signaled. In other builds, this is treated as a call to the Microsoft Win32 WaitForSingleObject function, with an INFINITE time-out.

DWORD WINAPI DbgWaitForSingleObject(
HANDLE h
);

Parameters
h
HANDLE value.


Debug Output Location

Microsoft® DirectShow™ provides facilities for debug output, with a wide variety of options for the debug output location. Possible output locations include using the normal debugger output (the default), recording to a file with a given name, or using the Win32® standard output handle (creating a console if this handle is not already open). After the debug output location is specified, each of the following debug facilities uses the same location.
Debug Output
Debug NOTE (Message) Macros
Debug Logging by Module Level
Object Register Debugging

The debug output location is chosen (based on the registry) when DbgInitialise is called. DbgTerminate must be called when this process finishes using the debug output location. These macros are generally called automatically by other debug routines.

To specify the debug output location, set the LogToFile value in the registry (under the HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL key) to one of the following (case-insensitive) values.
LogToFile Value | Results
"Console" | Use the Microsoft Win32 standard output handle if it exists. If no standard output handle exists, allocate a console and use it for output.
"Deb", "Debug", or "Debugger" | Use the Win32 OutputDebugString function.
Any nonempty string other than the preceding | Write to file of that name.
An empty string (or the registry key does not exist) | Use the Win32 OutputDebugString function.


Structures

This section describes the Microsoft® DirectShow™ structures.
Structure | Description
ALLOCATOR_PROPERTIES | Contains the allocator's count, size, alignment, and prefix properties.
AM_DVD_RENDERSTATUS | Provides status (failure) codes for IDvdGraphBuilder::RenderDvdVideoVolume.
AM_MEDIA_TYPE | Describes a media sample type.
AM_SAMPLE2_PROPERTIES | Describes the properties of a generic media sample.
AMOVIESETUP_FILTER | Contains filter information for registering a filter.
AMOVIESETUP_MEDIATYPE | Contains media type information for registering a filter.
AMOVIESETUP_PIN | Contains pin information for registering a filter.
AM_STREAM_INFO | Contains start and stop information given to a pin.
AMVPDATAINFO | Specifies the data-specific characteristics of the VP input stream.
AMVPDIMINFO | Specifies the dimensional characteristics of the VP input stream.
AMVPSIZE | Specifies the width and height for a VP image.
DVD_ATR | Specifies DVD attributes.
DVD_TIMECODE | Contains DVD timecode in hours, minutes, seconds, and frames.
FILTER_INFO | Contains information about a filter.
PIN_INFO | Contains information about a pin.
POSITION | Placeholder for linked lists.
Quality | Describes a quality message by indicating Flood or Famine in the renderer and specifying the percentage of frames to drop or add to optimize the renderer's performance.
REGFILTER | Describes a filter in the registry.
REGFILTER2 | Describes a filter for registration through the IFilterMapper2 interface.
REGFILTERPINS2 | Contains information for registering a filter through the IFilterMapper2 interface.
REGPINMEDIUM | Describes a pin medium (as defined in the Windows NT DDK) for registration through the IFilterMapper2 interface.
REGFILTERPINS | Contains pin information for registering a filter.
REGPINTYPES | Contains media type information for registering a filter.

The following structure maintains information about graphics device interface (GDI) bitmaps and device-independent bitmaps (DIBs). This is used solely by the CImageAllocator, CImageSample, and CDrawImage window utility classes.
Structure | Description
DIBDATA | Contains information about each DIB.

The following structures maintain information about video, as well as video capture and compression.
Structure | Description
TRUECOLORINFO | Maintains color information.
ANALOGVIDEOINFO | Maintains information about the format of the analog video signal.
AUDIO_STREAM_CONFIG_CAPS | Contains information about all possible audio formats supported.
COLORKEY | Communicates color key information between the renderer and another filter.
MPEG1VIDEOINFO | Contains additional MPEG-1 video system information.
MPEG2VIDEOINFO | Contains additional MPEG-2 video system information.
TIMECODE | Contains basic timecode frame count information.
TIMECODE_SAMPLE | Contains complete timecode information.
VIDEO_STREAM_CONFIG_CAPS | Contains information about possible connections.
VIDEOINFO | Contains information that specifies a video image and its color palette and bitmasks.
VIDEOINFOHEADER | Describes the bitmap and color information for a video image.
VIDEOINFOHEADER2 | Describes the bitmap and color information for a video image, including interlace, copy protection, and pixel aspect ratio information.

ALLOCATOR_PROPERTIES

Structures

Contains the allocator's count, size, alignment, and prefix properties.

typedef struct _AllocatorProperties {
    long cBuffers;
    long cbBuffer;
    long cbAlign;
    long cbPrefix;
} ALLOCATOR_PROPERTIES;
Members
cBuffers
Count of buffers at this allocator.
cbBuffer
Size of each buffer in bytes, excluding any prefix.
cbAlign
Alignment of the buffer; buffer start will be aligned on a multiple of this value.
cbPrefix
Each buffer is preceded by a prefix of this many bytes.
Remarks

The CMediaSample::GetPointer member function points to the beginning of the buffer, not including the prefix bytes designated by cbPrefix.

The alignment is applied to the prefix data, if any. If a nonzero prefix is used, the beginning of the prefix is aligned according to cbAlign. Since the buffer pointer returned by IMediaSample::GetPointer points to the area immediately following the prefix, the cbPrefix address (the value returned by IMediaSample::GetPointer minus cbPrefix) should be aligned on an address that is a multiple of cbAlign bytes.

AM_DVD_RENDERSTATUS

Structures

Provides status (failure) codes for IDvdGraphBuilder::RenderDvdVideoVolume.

typedef struct {
HRESULT hrVPEStatus;
BOOL    bVPEFailed;
    BOOL    bDVDVolInvalid;
    BOOL    bDVDVolUnknown;
    BOOL    bNoLine21In;
    BOOL    bNoLine21Out;
    int     iNumStreams;
    int     iNumStreamsFailed;
    DWORD   dwFailedStreamsFlag;
} AM_DVD_RENDERSTATUS;
Members
hrVPEStatus
Video port extension (VPE) error code. Zero indicates success; any other value is failure.
bVPEFailed
TRUE if the caller didn't set the AM_DVD_NOVPE flag in the RenderDvdVideoVolume call and VPE mixing failed; FALSE otherwise.
bDVDVolInvalid
TRUE if the specified DVD volume to be played does not exist; FALSE otherwise.
bDVDVolUnknown
TRUE if no DVD volume is specified or if it isn't found; FALSE otherwise.
bNoLine21In
TRUE if the video decoder doesn't produce Line 21 (closed captioning) data; FALSE otherwise.
bNoLine21Out
TRUE if the video decoder can't show decoded Line 21 data as CC on video; FALSE otherwise.
iNumStreams
Number of DVD streams to render.
iNumStreamsFailed
Number of streams that failed to render.
dwFailedStreamsFlag
Combination of AM_DVD_STREAM_FLAGS flags indicating which streams failed.
See Also

IDvdGraphBuilder::RenderDvdVideoVolume

AM_MEDIA_TYPE

Structures

Describes a media sample type.

typedef struct  _MediaType
    {
    GUID      majortype;
    GUID      subtype;
    BOOL      bFixedSizeSamples;
    BOOL      bTemporalCompression;
    ULONG     lSampleSize;
    GUID      formattype;
    IUnknown  *pUnk;
    ULONG     cbFormat;
    /* [size_is] */ BYTE __RPC_FAR *pbFormat;
    } AM_MEDIA_TYPE;
Members
majortype
Major type of the media sample.
subtype
Subtype of the media sample.
bFixedSizeSamples
If TRUE, samples are of a fixed size.
bTemporalCompression
If TRUE, samples are compressed.
lSampleSize
Size of the sample in bytes.
formattype
Registered (GUID) format type.
pUnk
Pointer to the IUnknown interface.
cbFormat
Size of the format section of the media type.
pbFormat
Pointer to the format section of the media type. The layout of this is determined by the format type GUID. Format types include the following:
Format type | Structure pointed to
FORMAT_MPEGVideo | MPEG1VIDEOINFO
FORMAT_VideoInfo | VIDEOINFOHEADER
FORMAT_WaveFormatEx | WAVEFORMATEX
FORMAT_MPEG2Video | MPEG2VIDEOINFO
FORMAT_VideoInfo2 | VIDEOINFOHEADER2

AM_SAMPLE2_PROPERTIES

Structures

Describes the properties of a generic media sample.

typedef struct tagAM_SAMPLE2_PROPERTIES {
    DWORD    cbData;
    DWORD    dwTypeSpecificFlags;
    DWORD    dwSampleFlags;
    LONG     lActual;
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD    dwStreamId;
    AM_MEDIA_TYPE *pMediaType;
    BYTE    *pbBuffer;
    LONG     cbBuffer;
} AM_SAMPLE2_PROPERTIES;
Members
cbData
Length of property data for extensibility; number of bytes including this field.
dwTypeSpecificFlags
Type-specific flag data. These flags are defined separately for each media type. Default is zero.
dwSampleFlags
Flags bits defined by the AM_SAMPLE_PROPERTY_FLAGS enumerated data type. All undefined bits are reserved (set them to zero, and do not copy them).
lActual
Length of data in the buffer pointed to by the pbBuffer member.
tStart
Start time if valid.
tStop
Stop time if valid.
dwStreamId
Stream identifier. Stream 0 is the normal media transport. Stream 1 is control. Currently, only Stream 0 is used. Filters should pass any other stream ID directly to their output pins without processing.
pMediaType
Copy of the media type. It becomes invalid after the sample has been released.
pbBuffer
Pointer to the buffer. The pointer becomes invalid after the sample is released.
cbBuffer
Total length of the buffer pointed to by pbBuffer, in bytes.
Remarks

The IMediaSample2 interface uses this structure.

AMOVIESETUP_FILTER

Structures

Contains filter information for registering a filter.

typedef struct _AMOVIESETUP_FILTER
{
    const CLSID * clsID;
    LPWSTR     strName;
    DWORD      dwMerit;
    UINT       nPins;
    LPAMOVIESETUP_PIN lpPin;
}
AMOVIESETUP_FILTER
Members
clsID
Class identifier of the filter.
strName
Name of the filter.
dwMerit
Merit used by the GraphBuilder object when constructing a filter graph.
nPins
Number of pins on the filter.
lpPin
AMOVIESETUP_PIN structure providing pin information.

AMOVIESETUP_MEDIATYPE

Structures

Media type information for registering a filter.

typedef struct _AMOVIESETUP_MEDIATYPE
{
    const CLSID * clsMajorType;
    const CLSID * clsMinorType;
} AMOVIESETUP_MEDIATYPE;
Members
clsMajorType
Major media type supported by the filter.
clsMinorType
Minor media type supported by the filter.

AMOVIESETUP_PIN

Structures

Pin information for registering a filter.

typedef struct _AMOVIESETUP_PIN
{
    LPWSTR           strName;
    BOOL             bRendered;
    BOOL             bOutput;
    BOOL             bZero;
    BOOL             bMany;
    const CLSID *    clsConnectsToFilter;
    LPWSTR           strConnectsToPin;
    UINT             nMediaTypes;
    LPAMOVIESETUP_MEDIATYPE lpMediaType;
}
AMOVIESETUP_PIN;
Members
strName
Name of the pin.
bRendered
Set to TRUE if the filter renders this input; otherwise, set to FALSE.
bOutput
Flag to indicate if this pin is an output pin.
bZero
If the filter has zero instances of this pin, set this to TRUE; otherwise, set to FALSE. For example, a decompression filter might choose not to create a sound output pin for a movie without a sound track.
bMany
If the filter has many instances of this pin, set this to TRUE; otherwise, set to FALSE. For example, a mixer might have multiple instances of its input pin.
clsConnectsToFilter
CLSID of the filter to which this filter connects in a filter graph.
strConnectsToPin
Name of the pin to which this pin connects in a filter graph.
nMediaTypes
Number of media types supported by this pin.
lpMediaType
AMOVIESETUP_MEDIATYPE structure providing media type information.

AM_STREAM_INFO

Structures

Contains start and stop information given to a pin.

typedef struct {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD dwStartCookie;
    DWORD dwStopCookie;
    DWORD dwFlags;
} AM_STREAM_INFO;
Members
tStart
Time at which streaming will start.
tStop
Time at which streaming will stop.
dwStartCookie
Number that will be given to the application that ordered the start, when the event occurs.
dwStopCookie
Number that will be given to the application that ordered the stop, when the event occurs.
dwFlags
AM_STREAM_INFO_FLAGS enumeration type flag.
Remarks

Access this structure through the IAMStreamControl interface.

AMVPDATAINFO

Structures

Specifies the data-specific characteristics of the VP input stream.

typedef struct _AMVPDATAINFO{
DWORD dwSize;
DWORD dwMicrosecondsPerField;
AMVPDIMINFO amvpDimInfo;
DWORD dwPictAspectRatioX;
DWORD dwPictAspectRatioY;
BOOL bEnableDoubleClock;
BOOL bEnableVACT;
BOOL bDataIsInterlaced;
LONG lHalfLinesOdd;
BOOL bFieldPolarityInverted;
DWORD dwNumLinesInVREF;
LONG lHalfLinesEven;
DWORD dwReserved1;
} AMVPDATAINFO, *LPAMVPDATAINFO;
Members
dwSize
Size of the structure, in bytes.
dwMicrosecondsPerField
Time taken by each field.
amvpDimInfo
Dimensional information.
dwPictAspectRatioX
The X dimension of picture aspect ratio.
dwPictAspectRatioY
The Y dimension of picture aspect ratio.
bEnableDoubleClock
Video port should enable double clocking.
bEnableVACT
Video port should use an external VACT signal.
bDataIsInterlaced
Indicates that the signal is interlaced.
lHalfLinesOdd
Number of half lines in the odd field.
bFieldPolarityInverted
Video port should invert the field polarity.
dwNumLinesInVREF
Number of lines of data in VREF.
lHalfLinesEven
Number of half lines in the even field.
dwReserved1
Reserved for future use.

AMVPDIMINFO

Structures

Specifies the dimensional characteristics of the VP input stream.

typedef struct _AMVPDIMINFO{
DWORD dwFieldWidth;
DWORD dwFieldHeight;
DWORD dwVBIWidth;
DWORD dwVBIHeight;
RECT rcValidRegion;
} AMVPDIMINFO, *LPAMVPDIMINFO;
Members
dwFieldWidth
Field width of the data.
dwFieldHeight
Field height of the data.
dwVBIWidth
Width of the VBI data.
dwVBIHeight
Height of the VBI data.
rcValidRegion
Valid rectangle, used for cropping.

AMVPSIZE

Structures

Specifies the width and height for a VP image.

typedef struct _AMVPSIZE{
DWORD dwWidth;
DWORD dwHeight;
} AMVPSIZE, *LPAMVPSIZE;
Members
dwWidth
Width, in pixels.
dwHeight
Height.
Remarks

The context could be anything such as scaling, cropping, and so on.

ANALOGVIDEOINFO

Structures

Maintains information about the format of the analog video signal.

typedef struct tagAnalogVideoInfo {
    RECT            rcSource;
    RECT            rcTarget;
    DWORD           dwActiveWidth;
    DWORD           dwActiveHeight;
    REFERENCE_TIME  AvgTimePerFrame;
} ANALOGVIDEOINFO;
Members
rcSource
Source video rectangle.
rcTarget
Destination target rectangle.
dwActiveWidth
Source video width.
dwActiveHeight
Source video height (483 for NTSC, 575 for PAL/SECAM).
AvgTimePerFrame
Average time per frame in 100-nanosecond units.
Remarks

Filters using this format usually pass the video signal using a hardware-based connection rather than using memory-based transports.

An example of a definition of an analog video media type connection would be a connection of NTSC video using "M" color encoding. This would use a major media type of MEDIATYPE_AnalogVideo, a subtype of MEDIASUBTYPE_AnalogVideo_NTSC_M, and a format type of FORMAT_AnalogVideo.

AUDIO_STREAM_CONFIG_CAPS

Structures

Contains information about all possible audio formats supported.

typedef struct _AUDIO_STREAM_CONFIG_CAPS {
        GUID guid;
        ULONG MinimumChannels;
        ULONG MaximumChannels;
        ULONG ChannelsGranularity;
        ULONG MinimumBitsPerSample;
        ULONG MaximumBitsPerSample;
        ULONG BitsPerSampleGranularity;
        ULONG MinimumSampleFrequency;
        ULONG MaximumSampleFrequency;
        ULONG SampleFrequencyGranularity;
    } AUDIO_STREAM_CONFIG_CAPS;
Members
guid
Will be set to MEDIATYPE_Audio to indicate an audio sample.
MinimumChannels
Minimum number of channels this pin supports.
MaximumChannels
Maximum number of channels this pin supports (for example, 2 for stereo).
ChannelsGranularity
Granularity of the channels. For example, you could specify channels 2 through 4 in steps of 2.
MinimumBitsPerSample
Minimum bits per sample.
MaximumBitsPerSample
Maximum bits per sample.
BitsPerSampleGranularity
Granularity of the bits. For example, you could specify 8 bits or 32 bits in steps of 8.
MinimumSampleFrequency
Minimum frequency allowed.
MaximumSampleFrequency
Maximum frequency allowed.
SampleFrequencyGranularity
Granularity of the frequency. For example, you could specify 11025 to 44100Hz in steps of 11025
Remarks

This structure is returned by an audio capture or compression filter.

See Also

IAMStreamConfig::GetStreamCaps

COLORKEY

Structures

Communicates color key information between the renderer and another filter.

typedef struct tagCOLORKEY
    {
    DWORD           KeyType;
    DWORD           PaletteIndex;
    COLORREF        LowColorValue;
    COLORREF        HighColorValue;
    }    COLORKEY;
Members
KeyType
Key type. Can be CK_NOCOLORKEY, CK_INDEX, or CK_RGB. CK_INDEX and CK_RGB can be logically combined.
PaletteIndex
Palette index.
LowColorValue
Lowest RGB color value.
HighColorValue
Highest RGB color value.
Remarks

The video renderer supports a data transport accessed through the IOverlay interface. This will typically be used by hardware decoder filters that need the renderer to communicate where to put the data rather than requiring the renderer to draw the data. One mechanism for communicating where to put the images is by using a color key. This structure is used by a filter (typically a hardware decoder) to describe color key requirements to the video renderer.

DIBDATA

Structures

Maintains information about each GDI DIB.

typedef struct tagDIBDATA {
    LONG        PaletteVersion;
    DIBSECTION  DibSection;
    HBITMAP     hBitmap;
    HANDLE      hMapping;
    BYTE        *pBase;
} DIBDATA;
Members
PaletteVersion
Current palette version in use.
DibSection
Details of DIB section allocated.
hBitmap
Handle to bitmap for drawing.
hMapping
Handle to shared memory block.
pBase
Pointer to base memory address.
Remarks

When the allocator creates a sample, it allocates a DIBSECTION to the sample. When a window receives a sample, it can call the Win32 BitBlt function to pass the sample from one device context to another device context. This is a mechanism for the image allocator, an image sample, and the draw class to pass bitmap information to each other.

DVD_ATR

Structures

Specifies DVD attributes.

typedef struct tagDVD_ATR
{
    ULONG    ulCAT;
    BYTE    pbATRI[768];
} DVD_ATR;
Members
ulCAT
VMG_CAT if this is for a volume; or VTS_CAT if this is for a Video Title Set (VTS)
pbATRI
All stream attributes for menu and title from bytes 256 to 1023 of VMGI or VTSI.
Remarks

Refer to the DVD-Video specification to parse these structures.

DVD_TIMECODE

Structures

Contains DVD timecode in hours, minutes, seconds, and frames.

typedef struct tagDVD_TIMECODE")
{
   ULONG Hours1   :4;
   ULONG Hours10  :4;

   ULONG Minutes1 :4;
   ULONG Minutes10:4;

   ULONG Seconds1 :4;
   ULONG Seconds10:4;

   ULONG Frames1  :4;
   ULONG Frames10 :2;

   ULONG FrameRateCode:2;
} DVD_TIMECODE;
Members
Hours1
Hours.
Hours10
Tens of hours.
Minutes1
Minutes.
Minutes10
Tens of minutes.
Seconds1
Seconds.
Seconds10
Tens of seconds.
Frames1
Frames.
Frames10
Tens of frames.
FrameRateCode
Frames per second dropped and not dropped as indicated by DVD_FRAMERATE.
Remarks

DVD Timecode is binary coded decimal (BCD) encoded in the format 0xHhMmSsFf, where
H is tens of hours
h is hours
M is tens of minutes
m is minutes
S is tens of seconds
s is seconds
F is tens of frames
f is frames

FILTER_INFO

Structures

Contains information about a filter.

typedef struct  _FilterInfo
    {
    WCHAR achName[ 128 ];
    IFilterGraph __RPC_FAR *pGraph;
    }     FILTER_INFO;
Members
achName
Name of the filter.
pGraph
Pointer to the IFilterGraph interface to which the filter is connected.

MPEG1VIDEOINFO

Structures

Describes an MPEG-1 video stream.

typedef struct tagMPEG1VIDEOINFO {
    VIDEOINFOHEADER hdr;
    DWORD           dwStartTimeCode;
    DWORD           cbSequenceHeader;
    BYTE            bSequenceHeader[1];
} MPEG1VIDEOINFO;
Members
hdr
Compatible with VIDEOINFOHEADER.
dwStartTimeCode
25-bit "group-of-pictures" time code at start of data.
cbSequenceHeader
Length in bytes of bSequenceHeader.
bSequenceHeader
Sequence header including quantization matrices, if any.

MPEG2VIDEOINFO

Structures

Describes an MPEG-2 video stream.

typedef struct tagMPEG2VIDEOINFO {
    VIDEOINFOHEADER2    hdr;
    DWORD               dwStartTimeCode;
    DWORD               cbSequenceHeader;
    DWORD               dwProfile;
    DWORD               dwLevel;
    DWORD               dwFlags;
    DWORD               dwSequenceHeader[1];
} MPEG2VIDEOINFO;
Members
hdr
Compatible with VIDEOINFOHEADER2.
dwStartTimeCode
25-bit "group-of-pictures" time code at start of data (not used for DVD).
cbSequenceHeader
Length in bytes of dwSequenceHeader (zero for DVD).
dwProfile
MPEG2Profile enumerated type member.
dwLevel
MPEG2Level enumerated type member.
dwFlags
Flag indicating preferences. Set one or a combination of the following values:
Value | Description
AMMPEG2_DoPanScan | If set, the MPEG-2 video decoder should crop the output image based on pan-scan vectors in picture_display_extension and change the picture aspect ratio accordingly.
AMMPEG2_DVDLine21Field1 | If set, the MPEG-2 decoder must be able to produce an output pin for DVD style closed-captioned data found in the Group Of Pictures (GOP) layer of field 1.
AMMPEG2_DVDLine21Field2 | If set, the MPEG-2 decoder must be able to produce an output pin for DVD style closed-captioned data found in the GOP layer of field 2.
AMMPEG2_SourceIsLetterboxed | If set, indicates that black bars have been encoded in the top and bottom of the video.
AMMPEG2_FilmCameraMode | If set, indicates "film mode" used for 625/50 content. If cleared, indicates that "camera mode" was used.
Note, set undefined flags to zero or connection will be rejected.
dwSequenceHeader
Sequence header including quantization matrices, if any.

PIN_INFO

Structures

Contains information about a pin.

typedef struct  _PinInfo
    {
    IBaseFilter  *pFilter;
    PIN_DIRECTION dir;
    WCHAR achName[ 128 ];
    }        PIN_INFO;
Members
pFilter
Pointer to the IBaseFilter interface of the owning filter.
dir
Direction of the pin (input or output).
achName
Name of the pin.

POSITION

Structures

Placeholder for a linked list.

struct __POSITION { int unused; };
typedef __POSITION* POSITION;
Members
unused
Integer value that specifies the location of an item in a linked list.
Remarks

This structure can point to any element in a linked list, including null elements (such as an end-of-list marker). This structure will, however, become invalid if you delete the item it points to.

When you perform operations that return a POSITION pointer on a single list element, a successful operation sets it to an appropriate non-null value, while null indicates that the items position could not be found. When you perform operations on the entire list, the pointer represents a Win32 BOOLEAN value, where TRUE indicates success and FALSE indicates failure.

See Also

CBaseList::GetHeadPositionI, CBaseList::GetTailPositionI

Quality

Structures

Describes a quality message by indicating Flood or Famine in the renderer and specifying the percentage of frames to drop or add to optimize the renderer's performance.

typedef struct{
    QualityMessageType Type;
    long                Proportion;
    REFERENCE_TIME       Late;
    REFERENCE_TIME       TimeStamp;
                           } Quality;
Members
Type
Either Famine or Flood, indicating that a downstream filter needs more or less data.
Proportion
Value that specifies the rate at which DirectShow should continue to send media samples. The base value is 1000, which indicates there should be no change. A percentage increase or decrease from 1000 indicates the percentage of frames to add or drop. If this value is 800, for example, DirectShow will drop 20 percent of the incoming frames to match the renderer's speed.
Late
If a famine exists downstream, this is the amount of time by which the stream is lagging.
TimeStamp
Value that specifies the time when DirectShow created this structure, which is usually the start time on a video sample.

REGFILTER

Structures

Identifies a filter in the registry.

typedef struct {
    CLSID Clsid;
    LPWSTR Name;
} REGFILTER;
Members
Clsid
Class identifier of the filter.
Name
Name of the filter.

TIMECODE

Structures

Contains basic timecode frame count information.

typedef struct tagTIMECODE {
        WORD	wFrameRate;
        WORD	wFrameFract;
        DWORD	dwFrames;
}TIMECODE;
Members
wFrameRate
Number of frames per second. Specify with one of the following values:
Setting | Description
ED_FORMAT_SMPTE_30 | 30 frames per second.
ED_FORMAT_SMPTE_30DROP | 30 frames per second drop frame (actual rate 29.97 fps).
ED_FORMAT_SMPTE_25 | 25 frames per second.
ED_FORMAT_SMPTE_24 | 24 frames per second.
wFrameFract
Fractional frame. Full scale is 0x1000.
dwFrames
Timecode value as a binary framecount.
Remarks

Fractional frame can be used to indicate temporal offset into frame when timecode was actually read from an external device; for example, wFrameFract=0x7ff means the timecode value was read from the device at the end of the first video field.

Note Because timecode commonly enters or leaves computer systems as ASCII values, conversion helper methods that convert the ASCII values to and from binary framecounts are supplied in the sample filter.

TIMECODE_SAMPLE

Structures

Contains complete timecode information.

typedef struct tagTIMECODE_SAMPLE {
    LONGLONG	qwTick;
    TIMECODE	timecode;
    DWORD		dwUser;
    DWORD		dwFlags;
} TIMECODE_SAMPLE;
Members
qwTick
Reference time, in 100-nanosecond units.
timecode
TIMECODE structure.
dwUser
Packed SMPTE userbits.
dwFlags
Timecode flag masks. Specify one or more of the following:
Value | Meaning
AM_TIMECODE_FLAG_FCM | Frame code mode; 0 = nondrop; 1 = drop.
AM_TIMECODE_FLAG_CF | Color frame flag.
AM_TIMECODE_FLAG_FIELD | Field flag.
AM_TIMECODE_FLAG_DF | Drop frame flag (from flags in actual timecode on external media).
AM_TIMECODE_COLORFRAME | Which frame in color sequence.
AM_TIMECODE_COLORSEQUENCE | Duration in frames of complete sequence.
AM_TIMECODE_FILMSEQUENCE_TYPE | One of FILM_SEQUENCE_XXX defines.
Remarks

The upper 16 bits in dwFlags are reserved for future use — set to zero.

TRUECOLORINFO

Structures

Contains color palette and bitmask information for a video image.

typedef struct tag_TRUECOLORINFO {
    DWORD dwBitMasks[iMASK_COLORS];
    RGBQUAD bmiColors[iPALETTE_COLORS];
} TRUECOLORINFO;
Members
dwBitMasks[iMASK_COLORS]
Array of color masks (one per color element).
bmiColors[iPALETTE_COLORS]
Array of palette colors.
Remarks

This structure is not used for some RGB formats. For more information about which fields are valid under different circumstances, see the Microsoft Win32® documentation for BITMAPINFO.

See Also

VIDEOINFO

VIDEO_STREAM_CONFIG_CAPS

Structures

Contains information about possible connections.

typedef struct  _VIDEO_STREAM_CONFIG_CAPS
    {
    GUID guid;
    ULONG VideoStandard;
    SIZE InputSize;
    SIZE MinCroppingSize;
    SIZE MaxCroppingSize;
    int CropGranularityX;
    int CropGranularityY;
    int CropAlignX;
    int CropAlignY;
    SIZE MinOutputSize;
    SIZE MaxOutputSize;
    int OutputGranularityX;
    int OutputGranularityY;
    int StretchTapsX;
    int StretchTapsY;
    int ShrinkTapsX;
    int ShrinkTapsY;
    LONGLONG MinFrameInterval;
    LONGLONG MaxFrameInterval;
    LONG MinBitsPerSecond;
    LONG MaxBitsPerSecond;
    }	VIDEO_STREAM_CONFIG_CAPS;
Members
guid
Will set MEDIATYPE_Video to indicate a video sample.
VideoStandard
The analog video standard supported. Set in the AnalogVideoStandard enumeration type (0 if not supported).
InputSize
Size of the incoming signal, expressed through the Win32 SIZE structure as the image rectangle's width and height in pixels. For a compressor, the size is taken from the width and height members of the Win32 BITMAPINFOHEADER structure in the input pin's AM_MEDIA_TYPE structure. For a capture filter, the size is the largest signal the filter can digitize with every pixel remaining unique.
MinCroppingSize
Smallest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member.
MaxCroppingSize
Largest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member.
CropGranularityX
Granularity of the cropping size. For example, you could specify that the only valid widths are an even multiple of four.
CropGranularityY
Granularity of the cropping size. For example, you could specify that the only valid heights are an even multiple of four.
CropAlignX
Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four.
CropAlignY
Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four.
MinOutputSize
Smallest bitmap this pin can produce.
MaxOutputSize
Largest bitmap this pin can produce.
OutputGranularityX
Granularity of output bitmap width.
OutputGranularityY
Granularity of output bitmap height.
StretchTapsX
Value indicating how well the filter can stretch the image's width. A value of 0 means the filter can't stretch; 1 means it uses pixel doubling; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.
StretchTapsY
Value indicating how well the filter can stretch the image's height. A value of 0 means the filter can't stretch; 1 means it uses pixel doubling; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.
ShrinkTapsX
Value indicating how well the filter can shrink the image's width. A value of 0 means the filter can't shrink; 1 means it just eliminates some rows of pixels; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.
ShrinkTapsY
Value indicating how well the filter can shrink the image's height. A value of 0 means the filter can't shrink; 1 means it just eliminates some rows of pixels; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.
MinFrameInterval
Minimum frame rate allowed. This applies to the capture filter only.
MaxFrameInterval
Maximum frame rate allowed. This applies to the capture filter only.
MinBitsPerSecond
Minimum data rate this pin can produce.
MaxBitsPerSecond
Maximum data rate this pin can produce.
Remarks

For example, assume the following values for some of the structure members.

  • MinCroppingSize = (160, 120)
  • MaxCroppingSize = (320, 240)
  • CropGranularityX = 4
  • CropGranularityY = 8

These values indicate that valid cropping sizes begin at MinCroppingSize and increase in steps in the x-direction by CropGranularityX and in the y-direction by CropGranularityY. In this case the x-value can be anywhere from 160 to 320 pixels in steps of 4 and the y-value can be anywhere from 120 to 240 pixels in steps of 8.

In this scenario a few of the valid sizes are:

  • 160 × 120, 164 × 120, 168 × 120, 172 × 120, and so on
  • 160 × 128, 164 × 128, 168 × 128, 172 × 128, and so on
  • 160 × 136, 164 × 136, 168 × 136, 172 × 136, and so on

CropAlignX and CropAlignY indicate where the cropping rectangle can be inside the input size rectangle. Given a 160 × 120 sized cropping rectangle and the following:

  • CropAlignX = 2
  • CropAlignY = 4

Some of the valid values for the VIDEOINFOHEADER structure's rcSource member are:

  • (0, 0, 160, 120)
  • (2, 0, 162, 120)
  • (2, 4, 162, 124)
  • (2, 8, 162, 128)

For a 320 × 240 cropping rectangle and the same cropping alignment values, (2, 4, 322, 244) is one example of the many legal rectangles.

The structure members discussed in this section work together to specify what values of rcSource are valid for the VIDEOINFOHEADER structure that describes the output pin's media type. Of the remaining structure members, MinOutputSize, MaxOutputSize, OutputGranularityX, and OutputGranularityY describe the biWidth and biHeight members of the BITMAPINFOHEADER structure contained in the output pin's media type VIDEOINFOHEADER structure.

VIDEOINFO

Structures

Describes the bitmap and color information for a video image.

typedef struct tagVIDEOINFO {
    RECT            rcSource,
    RECT            rcTarget,
    DWORD           dwBitRate,
    DWORD           dwBitErrorRate,
    REFERENCE_TIME  AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
union {
        RGBQUAD     bmiColors[iPALETTE_COLORS];
        DWORD       dwBitMasks[iMASK_COLORS];
        TRUECOLORINFO   TrueColorInfo;
    };
} VIDEOINFO;
Members
rcSource
Portion of the input video to use. See Source and Target Rectangles in Video Renderers for examples of how this member works.
rcTarget
Where the video should be displayed. See Source and Target Rectangles in Video Renderers for examples of how this member works.
dwBitRate
Approximate bit data rate.
dwBitErrorRate
Bit error rate for this stream.
AvgTimePerFrame
Average time per frame, in 100-nanosecond units.
bmiHeader
Win32 BITMAPINFOHEADER structure that contains color and dimension information for a device-independent bitmap.
bmiColors
Array of Win32 RGBQUAD structures that specifies the video's color palette. Each structure represents a single color, which is a combination of red, green, and blue intensities.
dwBitMasks
Array of DWORD values that specify true color bitmasks.
TrueColorInfo
TRUECOLORINFO structure that contains both a color palette and an array of color bitmasks.
Remarks

Never use this structure unless you are sure that you will use it only to store standard RGB formats. If you store anything other than standard RGB, the variable size of the bmiHeader structure will almost certainly cause problems. You should use the VIDEOINFOHEADER structure instead. If for some reason you find it absolutely necessary to use the VIDEOINFO structure, do not access TrueColorInfo, dwBitMasks, and bmiColors directly; use the TRUECOLORINFO, COLORS, and BITMASKS macros to return the pointers to the color information.

The first five data members are equivalent to a VIDEOINFOHEADER structure. They are expanded in full simply to reduce the amount of dereferencing needed when dealing with a pointer to a VIDEOINFO structure.

Which of the TrueColorInfo, dwBitMasks, and bmiColors fields is valid depends on the contents of the BITMAPINFOHEADER structure.

See Also

Source and Target Rectangles in Video Renderers

VIDEOINFOHEADER

Structures

Describes the bitmap and color information for a video image.

typedef struct tagVIDEOINFOHEADER {
    RECT                rcSource,
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER;
Members
rcSource
RECT structure that specifies the source video window. This structure can be a clipping rectangle, to select a portion of the source video stream. See Source and Target Rectangles in Video Renderers for examples of how this member works.
rcTarget
RECT structure that specifies the destination video window. See Source and Target Rectangles in Video Renderers for examples of how this member works.
dwBitRate
DWORD value that specifies the video stream's approximate data rate, in bits per second.
dwBitErrorRate
DWORD value that specifies the video stream's data error rate, in bit errors per second.
AvgTimePerFrame
REFERENCE_TIME value that specifies the video frame's average display time, in 100-nanosecond units.
bmiHeader
Win32 BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap.
See Also

Source and Target Rectangles in Video Renderers

VIDEOINFOHEADER2

Structures

Describes the bitmap and color information for a video image, including interlace, copy protection, and pixel aspect ratio information.

typedef struct tagVIDEOINFOHEADER2 {
    RECT                rcSource;
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    DWORD               dwInterlaceFlags;   // use AMINTERLACE_* defines. Reject connection if undefined bits are not 0
    DWORD               dwCopyProtectFlags; // use AMCOPYPROTECT_* defines. Reject connection if undefined bits are not 0
    DWORD               dwPictAspectRatioX;
    DWORD               dwPictAspectRatioY;
    DWORD               dwReserved1;
    DWORD               dwReserved2;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER2;
Members
rcSource
RECT structure that specifies what part of the source stream should be used to fill the destination buffer. The renderers can use this field to ask the decoders to stretch or clip. See Source and Target Rectangles in Video Renderers for examples of how this member works.
rcTarget
RECT structure that specifies that specifies what part of the destination buffer should be used. See Source and Target Rectangles in Video Renderers for examples of how this member works.
dwBitRate
DWORD value that specifies the video stream's approximate data rate.
dwBitErrorRate
DWORD value that specifies the video stream's data error rate.
AvgTimePerFrame
REFERENCE_TIME value that specifies the video frame's average display time, in milliseconds.
dwInterlaceFlags
Flag set by one of the following values:
Setting | Description
AMINTERLACE_IsInterlaced | Indicates an interlace stream. If 0, other interlace bits are irrelevant.
AMINTERLACE_1FieldPerSample | Indicates one field per media sample. If 0, indicates 2 fields per media sample.
AMINTERLACE_Field1First | Indicates Field 1 is first. If 0, indicates Field 2 is first. Top field in PAL is field 1, top field in NTSC is field 2.
AMINTERLACE_UNUSED | Unused.
AMINTERLACE_FieldPatternMask | Bits used to indicate field pattern.
AMINTERLACE_FieldPatField1Only | Stream never contains a Field 2.
AMINTERLACE_FieldPatField2Only | Stream never contains a Field 1.
AMINTERLACE_FieldPatBothRegular | There will be a Field 2 for every Field 1.
AMINTERLACE_FieldPatBothIrregular | Random pattern of Field 1s and Field 2s.
AMINTERLACE_DisplayModeMask | Bits used to indicate display mode.
AMINTERLACE_DisplayModeBobOnly | Indicates Bob display mode only.
AMINTERLACE_DisplayModeWeaveOnly | Indicates Weave display mode only.
AMINTERLACE_DisplayModeBobOrWeave | Indicates either Bob or Weave display mode.
Set undefined flags to zero or connection should be rejected.
dwCopyProtectFlags
Flag set with the AMCOPYPROTECT_RestrictDuplication value to indicate duplication of stream should be restricted. If undefined, specify zero or connection should be rejected.
dwPictAspectRatioX
The X dimension of picture aspect ratio, for example, 16 for 16 × 9 display (inches by inches, not pixels by pixels).
dwPictAspectRatioY
The Y dimension of picture aspect ratio, for example, 9 for 16 × 9 display (inches by inches, not pixels by pixels).
dwReserved1
Reserved for future use. Must be zero; reject connection otherwise
dwReserved2
Reserved for future use. Must be zero; reject connection otherwise
bmiHeader
Win32 BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap.
See Also

Source and Target Rectangles in Video Renderers

REGPINTYPES

Structures

Contains media type information for registering a filter.

typedef struct
{
    const CLSID * clsMajorType;
    const CLSID * clsMinorType;
} REGPINTYPES;
Members
clsMajorType
Major media type supported by the filter.
clsMinorType
Minor media type supported by the filter.
Remarks

This structure is used by the IFilterMapper and IFilterMapper2 interfaces to identify media types a pin handles and to register filters.

This structure is equivalent to the AMOVIESETUP_MEDIATYPE structure.

REGFILTERPINS

Structures

Contains pin information for registering a filter.

typedef struct
{
    LPWSTR           strName;
    BOOL             bRendered;
    BOOL             bOutput;
    BOOL             bZero;
    BOOL             bMany;
    const CLSID *    clsConnectsToFilter;
    const WCHAR *    strConnectsToPin;
    UINT             nMediaTypes;
    const REGPINTYPES * lpMediaType;
} REGFILTERPINS;
Members
strName
Name of the pin.
bRendered
Set to TRUE if the filter renders this input; otherwise, set to FALSE.
bOutput
Set to TRUE if this pin is an output pin.
bZero
Set to TRUE if the filter has zero instances of this pin; otherwise, set to FALSE.
bMany
Set to TRUE if the filter has more than one instance of this pin; otherwise, set to FALSE.
clsConnectsToFilter
CLSID of the filter to which this filter connects in a filter graph.
strConnectsToPin
Name of the pin to which this pin connects in a filter graph.
nMediaTypes
Number of media types supported by this pin.
lpMediaType
REGPINTYPES structure providing media type information.
Remarks

This structure is used by the IFilterMapper and IFilterMapper2 interfaces for filter registration. It is used if the dwVersion member in REGFILTER2 is 1.

This structure is equivalent to the AMOVIESETUP_PIN structure.

REGPINMEDIUM

Structures

Describes a pin medium (as defined in the Windows NT DDK) for registration through the IFilterMapper2 interface.

typedef struct
{
    CLSID clsMedium;
    DWORD dw1;
    DWORD dw2;
} REGPINMEDIUM;
Members
clsMedium
Contains the globally unique set identifier.
dw1
Contains the set-specific identifier for an item within the set.
dw2
Used for various set flags. Zero when not used.
Remarks

A medium defines a method of communication (for example, the bus over which the communication occurs). Each ID within that set is used to represent the form of communication. Register mediums for your filter if you need to search for DirectShow filters built on kernel streaming pins, which can connect to each other.

REGFILTERPINS2

Structures

Contains information for registering a filter through the IFilterMapper2 interface.

typedef struct
{
    DWORD dwFlags;
    UINT             cInstances;
    UINT             nMediaTypes;
    [size_is(nMediaTypes)] const REGPINTYPES * lpMediaType;
    UINT             nMediums;
    [size_is(nMediums)] const REGPINMEDIUM *lpMedium;
    const CLSID      *clsPinCategory;
} REGFILTERPINS2;
Members
dwFlags
Combination of REG_PINFLAG flags.
cInstances
Number of instances of the pin, if known.
nMediaTypes
Number of media types supported by this pin.
lpMediaType
Array of nMediaTypes REGPINTYPES structures providing media type information.
nMediums
Number of mediums.
lpMedium
Array of REGPINMEDIUM structures containing medium information for each pin.
clsPinCategory
Pin category (for kernel streaming pins) as defined in the Windows NT DDK.

REGFILTER2

Structures

Describes a filter for registration through the IFilterMapper2 interface.

typedef struct
{
    DWORD dwVersion;            // 1 or 2
    DWORD dwMerit;

    /* unnamed union */
    [switch_is(dwVersion)] [switch_type(DWORD)] union
    {
        [case(1)]

            struct
            {
                ULONG cPins;
                [size_is(cPins)] const REGFILTERPINS *rgPins;
            };

        [case(2)]

            struct
            {
                ULONG cPins2;
                [size_is(cPins2)] const REGFILTERPINS2 *rgPins2;
            };

        [default]
            ;
    } ;

} REGFILTER2;
Members
dwVersion
Indicates the filter registration format to use.
dwMerit
Position in the order of enumeration. Filters or categories with higher merit are enumerated first.
cPins
Number of pins (if dwVersion = 1).
rgPins
Array of REGFILTERPINS structures representing each pin to be registered (if dwVersion = 1).
cPins2
Number of pins (if dwVersion = 2).
rgPins2
Array of REGFILTERPINS2 structures representing each pin to be registered (if dwVersion = 2).
Remarks

This structure is passed in to the IFilterMapper2::RegisterFilter method.

Set dwVersion to 1 if you are using the old format, or to 2 if you need mediums and pin categories.


Data Types

This section describes the Microsoft® DirectShow™ data types. Closed captioning, DVD, and VPE data types are grouped by functionality below the primary list.
Data type | Description
AM_ASPECT_RATIO_MODE | Specifies the aspect ratio of a video image in a display window.
AM_SAMPLE_PROPERTY_FLAGS | Specifies values for the dwSampleFlags member of the AM_SAMPLE2_PROPERTIES structure.
AM_STREAM_INFO_FLAGS | Indicates whether various components of the AM_STREAM_INFO structure have been set.
AMTunerModeType | Specifies the frequency of a TV tuner (cable or antenna).
AnalogVideoStandard | Specifies the format of the baseband analog video signal.
CameraControlProperty | Specifies what part of the camera DirectShow is controlling.
CL_ELEM_FLAGS | Specifies cutlist element flags.
CL_ELEM_STATUS | Specifies cutlist status flags.
CompressionCaps | Indicates video compression capabilities.
FILTER_STATE | Specifies a filter's state.
InterleavingMode | Specifies how video frames and audio samples will be written to disk.
MPEG2Level | Indicates the MPEG2 video level as specified in the MPEG2 video standard. (ISO13818-2)
MPEG2Profile | Indicates the MPEG2 video profile as specified in the MPEG2 video standard. (ISO13818-2)
PIN_DIRECTION | Indicates a pin's direction.
QualityMessageType | Describes a quality message type.
REG_PINFLAG | Indicates flags for the dwFlags member in the REGFILTERPINS2 structure.
StreamControlState | Specifies the state of the stream.
TunerInputType | Specifies the frequency of a TV tuner (cable or antenna).
VfwCaptureDialogs | Specifies a dialog box that might exist in a Microsoft Video for Windows® capture driver.
VfwCompressDialogs | Specifies a dialog box that might exist in a Video for Windows compression (codec) driver.
VideoControlFlags | Specifies video mode of operation (horizontal or vertical flip, external trigger enable, and trigger simulate) for a video device.
VideoProcAmpFlags | Specifies how to set video properties.
VideoProcAmpProperty | Specifies video properties.

The following data types are specific to closed captioning:
Closed captioning data type | Description
AM_LINE21_CCLEVEL | Indicates the closed captioning capability level.
AM_LINE21_CCSERVICE | Indicates the closed captioning decoder service.
AM_LINE21_CCSTATE | Indicates the closed captioning state (on or off).
AM_LINE21_DRAWBGMODE | Indicates the closed-captioned text background mode.

The following data types are specific to DVD:
DVD data type | Description
AM_DVD_GRAPH_FLAGS | Specifies the type of decoder to use in a DVD filter graph.
AM_DVD_STREAM_FLAGS | Describes a DVD stream type (video, audio, or subpicture).
DVD_DISC_SIDE | Indicates the sides of a DVD disc.
DVD_DOMAIN | Indicates the state of a DVD player.
DVD_ERROR | Specifies DVD error conditions.
DVD_FRAMERATE | Indicates DVD frame rates.
DVD_MENU_ID | DVD-Video Title Set (VTS) menu identifiers.
DVD_PLAYBACK_LOCATION | Indicates DVD playback location.
DVD_PREFERRED_DISPLAY_MODE | Indicates the user's preferred window aspect ratio and conversion method.
DVD_WARNING | Specifies DVD warning conditions.

The following lists data types specific to VPE.
VPE data type | Description
AMVP_MODE | Specifies the various modes for video ports (VP).
AMVP_SELECT_FORMAT_BY | Specifies the criteria that the VP mixer should use to select the video format.

AM_ASPECT_RATIO_MODE

Data Types

Specifies the aspect ratio of a video image in a display window.

typedef enum _AM_ASPECT_RATIO_MODE
{
    AM_ARMODE_NONE,
    AM_ARMODE_LETTER_BOX,
AM_ARMODE_CROP
} AM_ASPECT_RATIO_MODE;
Values
AM_ARMODE_NONE
No aspect ratio correction.
AM_ARMODE_LETTER_BOX
Put the video in letterbox format. Paint background color in the excess region so the video is not distorted.
AM_ARMODE_CROP
Crop the video to the correct aspect ratio.
Remarks

If the AM_ARMODE_NONE member is specified in this enumerated type, a video stream will always occupy the entire region of the display window when the window is resized. The AM_ARMODE_LETTER_BOX member eliminates video stretching and distortions by keeping the aspect ratio consistent and painting the excess areas of the window a background color.

AM_DVD_GRAPH_FLAGS

Data Types

Specifies the type of decoder to use in a DVD filter graph.

enum {
    AM_DVD_HWDEC_PREFER,
    AM_DVD_HWDEC_ONLY,
    AM_DVD_SWDEC_PREFER,
    AM_DVD_SWDEC_ONLY,
    AM_DVD_NOVPE
} AM_DVD_GRAPH_FLAGS;
Values
AM_DVD_HWDEC_PREFER
Maximum hardware decoding. Default.
AM_DVD_HWDEC_ONLY
Hardware decoding only.
AM_DVD_SWDEC_PREFER
Maximum software decoding.
AM_DVD_SWDEC_ONLY
Software decoding only
AM_DVD_NOVPE
Do not use video port extensions (VPE).
Remarks

Do not combine any of the hardware flags (AM_DVD_HWDEC_*) with any of the software flags (AM_DVD_SWDEC_*). However, you can combine AM_DVD_NOVPE with any of the hardware flags.

See Also

IDvdGraphBuilder::RenderDvdVideoVolume

AM_DVD_STREAM_FLAGS

Data Types

Describes a DVD stream type (video, audio, or subpicture).

enum {
    AM_DVD_STREAM_VIDEO,
    AM_DVD_STREAM_AUDIO,
    AM_DVD_STREAM_SUBPIC
} AM_DVD_STREAM_FLAGS;
Values
AM_DVD_STREAM_VIDEO
DVD video stream.
AM_DVD_STREAM_AUDIO
DVD audio stream.
AM_DVD_STREAM_SUBPIC
DVD subpicture stream.
See Also

AM_DVD_RENDERSTATUS

AM_LINE21_CCLEVEL

Data Types

Indicates the closed captioning capability level.

 typedef enum _AM_LINE21_CCLEVEL {
    AM_L21_CCLEVEL_TC2
} AM_LINE21_CCLEVEL, *PAM_LINE21_CCLEVEL ;
Values
AM_L21_CCLEVEL_TC2
Capability level 2.
See Also

IAMLine21Decoder::GetDecoderLevel

AM_LINE21_CCSERVICE

Data Types

Indicates the closed captioning decoder service.

 typedef enum _AM_LINE21_CCSERVICE {
    AM_L21_CCSERVICE_None,
    AM_L21_CCSERVICE_Caption1,
    AM_L21_CCSERVICE_Caption2,
    AM_L21_CCSERVICE_Text1,
    AM_L21_CCSERVICE_Text2,
    AM_L21_CCSERVICE_XDS,
} AM_LINE21_CCSERVICE, *PAM_LINE21_CCSERVICE ;
Values
AM_L21_CCSERVICE_None
No current service.
AM_L21_CCSERVICE_Caption1
True captioning, first field. Default service.
AM_L21_CCSERVICE_Caption2
Captioning for secondary language, second field. Generally not used.
AM_L21_CCSERVICE_Text1
First text field. Not currently implemented; provided for future compatibility.
AM_L21_CCSERVICE_Text2
Second text field. Not currently implemented; provided for future compatibility.
AM_L21_CCSERVICE_XDS
Extended Data Services (XDS or EDS). Not currently implemented; provided for future compatibility.
See Also

IAMLine21Decoder::GetCurrentService, IAMLine21Decoder::SetCurrentService

AM_LINE21_CCSTATE

Data Types

Indicates the closed captioning state (on or off).

 typedef enum _AM_LINE21_CCSTATE {
    AM_L21_CCSTATE_Off,
    AM_L21_CCSTATE_On
} AM_LINE21_CCSTATE, *PAM_LINE21_CCSTATE ;
Values
AM_L21_CCSTATE_Off
Closed captioning off.
AM_L21_CCSTATE_On
Closed captioning on.
See Also

IAMLine21Decoder::GetServiceState, IAMLine21Decoder::SetServiceState

AM_LINE21_DRAWBGMODE

Data Types

Indicates the closed captioning text background mode.

 typedef enum _AM_LINE21_DRAWBGMODE {
    AM_L21_DRAWBGMODE_Opaque,
    AM_L21_DRAWBGMODE_Transparent
} AM_LINE21_DRAWBGMODE, *PAM_LINE21_DRAWBGMODE ;
Values
AM_L21_DRAWBGMODE_Opaque
Opaque background.
AM_L21_DRAWBGMODE_Transparent
Transparent background.
See Also

IAMLine21Decoder::GetDrawBackgroundMode, IAMLine21Decoder::SetDrawBackgroundMode

AM_SAMPLE_PROPERTY_FLAGS

Data Types

Specifies values for the dwSampleFlags member of the AM_SAMPLE2_PROPERTIES structure.

enum tagAM_SAMPLE_PROPERTY_FLAGS
     { AM_SAMPLE_SPLICEPOINT        = 0x01,
       AM_SAMPLE_PREROLL            = 0x02,
       AM_SAMPLE_DATADISCONTINUITY  = 0x04,
       AM_SAMPLE_TYPECHANGED        = 0x08,
       AM_SAMPLE_TIMEVALID          = 0x10,
       AM_SAMPLE_TIMEDISCONTINUITY  = 0x40,
       AM_SAMPLE_FLUSH_ON_PAUSE     = 0x80,
       AM_SAMPLE_STOPVALID          = 0x100,
       AM_SAMPLE_ENDOFSTREAM        = 0x200,
       AM_STREAM_MEDIA              = 0,
       AM_STREAM_CONTROL            = 1
     };
Values
AM_SAMPLE_SPLICEPOINT
Sample is a splice point (it can be decoded without reference to previous data).
AM_SAMPLE_PREROLL
Sample is a preroll sample.
AM_SAMPLE_DATADISCONTINUITY
Indicates the start of a new segment.
AM_SAMPLE_TYPECHANGED
Sample type changed.
AM_SAMPLE_TIMEVALID
Time is valid.
AM_SAMPLE_TIMEDISCONTINUITY
A time gap in the data starts after this sample. The pbBuffer member of the AM_SAMPLE2_PROPERTIES structure can be NULL in this case.
AM_SAMPLE_FLUSH_ON_PAUSE
For live data only; indicates discard in the paused state.
AM_SAMPLE_STOPVALID
Stop time is valid.
AM_SAMPLE_ENDOFSTREAM
End of stream occurs after this sample. This is reserved for kernel streaming and DirectShow currently doesn't use it.
AM_STREAM_MEDIA
Normal data stream identifier.
AM_STREAM_CONTROL
Control stream identifier. A value greater than 0x7FFFFFFF indicates an application-defined stream.

AM_STREAM_INFO_FLAGS

Data Types

Indicates whether various components of the AM_STREAM_INFO structure have been set.

typedef enum {
    AM_STREAM_INFO_START_DEFINED = 0x00000001,
    AM_STREAM_INFO_STOP_DEFINED  = 0x00000002,
    AM_STREAM_INFO_DISCARDING    = 0x00000004,
    AM_STREAM_INFO_STOP_SEND_EXTRA = 0x00000010
} AM_STREAM_INFO_FLAGS;
Values
AM_STREAM_INFO_START_DEFINED
Indicates a valid stream start time has been set.
AM_STREAM_INFO_STOP_DEFINED
Indicates a valid stream stop time has been set.
AM_STREAM_INFO_DISCARDING
Indicates that stream discarding is currently active.
AM_STREAM_INFO_STOP_SEND_EXTRA
Indicates that the pin will send an extra stream sample upon completion.

AMTunerModeType

Data Types

Specifies the frequency of a TV tuner (cable or antenna).

typedef enum tagAMTunerModeType
    {
        AMTUNER_MODE_DEFAULT,
        AMTUNER_MODE_TV,
        AMTUNER_MODE_FM_RADIO,
        AMTUNER_MODE_AM_RADIO,
        AMTUNER_MODE_DSS
    } AMTunerModeType;
Values
AMTUNER_MODE_DEFAULT
Indicates default tuner mode.
AMTUNER_MODE_TV
Indicates TV tuner mode.
AMTUNER_MODE_FM_RADIO
Indicates FM radio tuner mode.
AMTUNER_MODE_AM_RADIO
Indicates AM radio tuner mode.
AMTUNER_MODE_DSS
Indicates Digital Satellite Service (DSS) tuner mode.

AMVP_MODE

Data Types

Specifies the various modes for video ports.

typedef enum _AMVP_MODE{
AMVP_MODE_WEAVE,
AMVP_MODE_BOBINTERLEAVED,
AMVP_MODE_BOBNONINTERLEAVED,
AMVP_MODE_SKIPEVEN,
AMVP_MODE_SKIPODD
} AMVP_MODE;
Values
AMVP_MODE_WEAVE
Weave.
AMVP_MODE_BOBINTERLEAVED
Interleaved bob. Bob mode in which resources are allocated to switch to weave mode, for example, on the next frame.
MODE_BOBNONINTERLEAVED
Noninterleaved bob. Bob mode in which resources are not allocated to switch to weave mode.
AMVP_MODE_SKIPEVEN
Skip even fields.
AMVP_MODE_SKIPODD
Skip odd fields.

AMVP_SELECT_FORMAT_BY

Data Types

Specifies the criteria that the VP mixer should use to select the video format.

typedef enum _AMVP_SELECT_FORMAT_BY{
AMVP_DO_NOT_CARE,
AMVP_BEST_BANDWIDTH,
AMVP_INPUT_SAME_AS_OUTPUT
} AMVP_SELECT_FORMAT_BY;
Values
AMVP_DO_NOT_CARE
Format doesn't matter.
AMVP_BEST_BANDWIDTH
Use the best bandwidth.
AMVP_INPUT_SAME_AS_OUTPUT
Use the same input format as output format.

AnalogVideoStandard

Data Types

Specifies the format of the baseband analog video signal.

 typedef enum
    {
        AnalogVideo_None       = 0x00000000
        AnalogVideo_NTSC_M     = 0x00000001,  //        75 IRE Setup
        AnalogVideo_NTSC_M_J   = 0x00000002,  // Japan,  0 IRE Setup
        AnalogVideo_NTSC_433   = 0x00000004

        AnalogVideo_PAL_B      = 0x00000010,
        AnalogVideo_PAL_D      = 0x00000020,
        AnalogVideo_PAL_H      = 0x00000080,
        AnalogVideo_PAL_I      = 0x00000100,
        AnalogVideo_PAL_M      = 0x00000200,
        AnalogVideo_PAL_N      = 0x00000400,
        AnalogVideo_PAL_60     = 0x00000800,
        AnalogVideo_SECAM_B    = 0x00001000,
        AnalogVideo_SECAM_D    = 0x00002000,
        AnalogVideo_SECAM_G    = 0x00004000,
        AnalogVideo_SECAM_H    = 0x00008000,
        AnalogVideo_SECAM_K    = 0x00010000,
        AnalogVideo_SECAM_K1   = 0x00020000,
        AnalogVideo_SECAM_L    = 0x00040000,
        AnalogVideo_SECAM_L1   = 0x00080000,
    } AnalogVideoStandard;
Values
AnalogVideo_None
Digital sensor
AnalogVideo_NTSC_M
NTSC_M
AnalogVideo_NTSC_M_J
NTSC_M_J
AnalogVideo_PAL_B
PAL_B
AnalogVideo_PAL_D
PAL_D
AnalogVideo_PAL_H
PAL_H
AnalogVideo_PAL_I
PAL_I
AnalogVideo_PAL_M
PAL_M
AnalogVideo_PAL_N
PAL_N
AnalogVideo_SECAM_B
SECAM_B
AnalogVideo_SECAM_D
SECAM_D
AnalogVideo_SECAM_G
SECAM_G
AnalogVideo_SECAM_H
SECAM_H
AnalogVideo_SECAM_K
SECAM_K
AnalogVideo_SECAM_K1
SECAM_K1
AnalogVideo_SECAM_L
SECAM_L

CameraControlProperty

Data Types

Specifies what part of the camera DirectShow is controlling.

typedef enum
    {
        CameraControl_Pan = 1,
        CameraControl_Tilt,
        CameraControl_Roll,
        CameraControl_Zoom,
        CameraControl_Exposure,
        CameraControl_Iris,
        CameraControl_Focus
    } CameraControlProperty;
Values
CameraControl_Pan
Control the camera's pan.
CameraControl_Tilt
Control the camera's tilt.
CameraControl_Roll
Control the camera's roll.
CameraControl_Zoom
Control the camera's zoom.
CameraControl_Exposure
Control the camera's exposure.
CameraControl_Iris
Control the camera's iris.
CameraControl_Focus
Control the camera's focus.

CL_ELEM_FLAGS

Data Types

Indicates cutlist element flags.

enum CL_ELEM_FLAGS{
    CL_ELEM_FIRST,
    CL_ELEM_LAST,
    CL_ELEM_NULL,
    CL_ELEM_ALL,
    CL_ELEM_NONE};
Values
CL_ELEM_FIRST
First element.
CL_ELEM_LAST
Last element.
CL_ELEM_NULL
Null element.
CL_ELEM_ALL
All elements.
CL_ELEM_NONE
No elements.

CL_ELEM_STATUS

Data Types

Indicates cutlist status flags.

enum CL_ELEM_STATUS{
    CL_NOT_PLAYED,
    CL_PLAYING,
    CL_FINISHED,
    CL_STATE_INVALID,
    CL_STATE_MASK,
    CL_WAIT_FOR_STATE};
Values
CL_NOT_PLAYED
Element has not played.
CL_PLAYING
Element is playing.
CL_FINISHED
Element finished playing.
CL_STATE_INVALID
Invalid state.
CL_STATE_MASK
Mask for invalid states (equals CL_STATE_INVALID).
CL_WAIT_FOR_STATE
Wait flag. For input parameter only.

CompressionCaps

Data Types

Indicates video compression capabilities.

typedef enum {
    CompressionCaps_CanQuality = 0x00000001,
    CompressionCaps_CanCrunch = 0x00000002,
    CompressionCaps_CanKeyFrame = 0x00000004,
    CompressionCaps_CanBFrame = 0x00000008,
    CompressionCaps_CanWindow = 0x0000000A
} CompressionCaps;
Values
CompressionCaps_CanQuality
Video compressor supports the IAMVideoCompression::put_Quality and IAMVideoCompression::get_Quality methods.
CompressionCaps_CanCrunch
Video compressor can compress video to a specified data rate. If the compressor has this capability then the output pin's media type will contain the data rate in the VIDEOINFOHEADER structure's dwBitRate member. The only way to set the data rate is to set dwBitRate.
CompressionCaps_CanKeyFrame
Video compressor supports the IAMVideoCompression::put_KeyFrameRate and IAMVideoCompression::get_KeyFrameRate methods.
CompressionCaps_CanBFrame
Video compressor supports the IAMVideoCompression::put_PFramesPerKeyFrame and IAMVideoCompression::get_PFramesPerKeyFrame methods.
CompressionCaps_CanWindow
Video compressor supports the IAMVideoCompression::put_WindowSize and IAMVideoCompression::get_WindowSize methods.
See Also

IAMVideoCompression

DVD_DISC_SIDE

Data Types

Indicates the sides of a DVD disc.

typedef enum tagDVD_DISC_SIDE {
    DVD_SIDE_A,
    DVD_SIDE_B
} DVD_DISC_SIDE;
Values
DVD_SIDE_A
Side A.
DVD_SIDE_B
Side B.

DVD_DOMAIN

Data Types

Indicates the state of a DVD player.

typedef enum tagDVD_DOMAIN {
    DVD_DOMAIN_FirstPlay,
    DVD_DOMAIN_VideoManagerMenu,
    DVD_DOMAIN_VideoTitleSetMenu,
    DVD_DOMAIN_Title,
    DVD_DOMAIN_Stop
} DVD_DOMAIN;
Values
DVD_DOMAIN_FirstPlay
Performing default initialization of a DVD disc.
DVD_DOMAIN_VideoManagerMenu
Displaying menus for whole disc.
DVD_DOMAIN_VideoTitleSetMenu
Displaying menus for current title set.
DVD_DOMAIN_Title
Displaying the current title.
DVD_DOMAIN_Stop
Player is in stopped state.

DVD_ERROR

Data Types

Specifies DVD error conditions.

typedef enum _tagDVD_ERROR {
    DVD_ERROR_Unexpected,
    DVD_ERROR_CopyProtectFail,
    DVD_ERROR_InvalidDVD1_0Disc,
    DVD_ERROR_InvalidDiscRegion,
    DVD_ERROR_LowParentalLevel
} DVD_ERROR;
Values
DVD_ERROR_Unexpected
Something unexpected happened; perhaps content is authored incorrectly. Playback is stopped.
DVD_ERROR_CopyProtectFail
Key exchange for DVD copy protection failed. Playback is stopped.
DVD_ERROR_InvalidDVD1_0Disc
DVD-Video disc is authored incorrectly for specification version 1.x. Playback is stopped.
DVD_ERROR_InvalidDiscRegion
DVD-Video disc is not approved for playback by decoders from this DVD region.
DVD_ERROR_LowParentalLevel
Player parental level is lower than the lowest parental level available in the DVD content. Playback is stopped.
See Also

EC_DVD_ERROR

DVD_FRAMERATE

Data Types

Indicates DVD frame rates.

typedef enum tagDVD_FRAMERATE
{
    DVD_FPS_25,
    DVD_FPS_30NonDrop
} DVD_FRAMERATE;
Values
DVD_FPS_25
25 frames per second.
DVD_FPS_30NonDrop
Exactly 30 frames per second.
Remarks

You must know the frame rate to interpret the frame count as time.

DVD_MENU_ID

Data Types

Specifies DVD Video Title Set (VTS) menu identifiers.

typedef enum tagDVD_MENU_ID {
    DVD_MENU_Title,
    DVD_MENU_Root,
    DVD_MENU_Subpicture,
    DVD_MENU_Audio,
    DVD_MENU_Angle,
    DVD_MENU_Chapter
} DVD_MENU_ID;
Values
DVD_MENU_Title
Choose a title from any VTS in a DVD-Video volume.
DVD_MENU_Root
Choose the main menu for a specific VTS.
DVD_MENU_Subpicture
Choose a subpicture stream in a VTS.
DVD_MENU_Audio
Choose an audio stream in a VTS.
DVD_MENU_Angle
Choose the angle number in a VTS.
DVD_MENU_Chapter
Choose a chapter in a VTS.
Remarks

The root menu always provides a means of getting to the subpicture, audio, angle and chapter menus if they exist.

DVD_PLAYBACK_LOCATION

Data Types

Indicates DVD playback location.

typedef struct tagDVD_PLAYBACK_LOCATION
{
ULONG   TitleNum;
    ULONG   ChapterNum;
    ULONG   TimeCode;
} DVD_PLAYBACK_LOCATION;
Members
TitleNum
Title number for the whole disc; Title Track Number (TTN) not Video Title Set_Title Track Number (VTS_TTN).
ChapterNum
Part-of-title number with title. 0xffffffff if not a simple linear movie.
TimeCode
Timecode. Use DVD_TIMECODE for current playback time. 0xffffffff if not a simple linear movie.
Remarks

TitleNum and ChapterNum or TitleNum and TimeCode are sufficient to save the playback location for simple linear movies.

DVD_PREFERRED_DISPLAY_MODE

Data Types

Indicates the user's preferred window aspect ratio and conversion method.

typedef enum tagDVD_PREFERRED_DISPLAY_MODE
{
    DISPLAY_CONTENT_DEFAULT,
    DISPLAY_16x9,
    DISPLAY_4x3_PANSCAN_PREFERRED,
    DISPLAY_4x3_LETTERBOX_PREFERRED
} DVD_PREFERRED_DISPLAY_MODE;
Values
DISPLAY_CONTENT_DEFAULT
Use the default window size and content type.
DISPLAY_16x9
Use a 16 × 9 window.
DISPLAY_4x3_PANSCAN_PREFERRED
Use a 4 × 3 window and convert to pan-scan, if possible.
DISPLAY_4x3_LETTERBOX_PREFERRED
Use a 4 × 3 window and convert to letterbox, if possible.
Remarks

DVD_PREFERRED_DISPLAY_MODE indicates the user's preferred window aspect ratio and preferred method of conversion of 16 × 9 content to a 4 × 3 window aspect ratio. Pan-scan and letterboxing are the two conversion methods. Displaying a video at the largest possible size inside the display window without any cropping or stretching is called displaying in letterbox format. Pan-scan is specifically cropping a 16 × 9 video for display in a 4 × 3 window using parameters defined by the video author.

This enumerated type indicates a preference of conversion mechanisms because some content can only be displayed using one of these methods. Content that is 4 × 3 is always converted to a 16 × 9 window by using "reverse" letterboxing, where black bars are added to the right and left sides of the display instead of the top and bottom of the display as in the 16 × 9 to 4 × 3 conversion using letterboxing.

The following table shows the conversion method used between the actual content type listed in the first column, and the user display preference setting, indicated by one of the other columns.
Actual content type | Content default | 16 × 9 | 4 × 3 pan-scan | 4 × 3 letterbox
4 × 3 | None | Reverse letterbox | None | None
16 × 9 letterbox only | None | None | Letterbox | Letterbox
16 × 9 pan-scan only | None | None | Pan-scan | Pan-scan
16 × 9 pan-scan or letterbox | None | None | Pan-scan | Letterbox

The native window size used is always the user's preferred size.

DVD_WARNING

Data Types

Specifies DVD warning conditions.

typedef enum _tagDVD_WARNING {
    DVD_WARNING_InvalidDVD1_0Disc=1,
    DVD_WARNING_FormatNotSupported=2,
    DVD_WARNING_IllegalNavCommand=3
} DVD_WARNING;
Values
DVD_WARNING_InvalidDVD1_0Disc
DVD-Video disc is authored incorrectly. Playback can continue, but unexpected behavior might occur.
DVD_WARNING_FormatNotSupported
A decoder would not support the current format. Playback of a stream might not function.
DVD_WARNING_IllegalNavCommand
The internal DVD navigation command processor attempted to process an illegal command.
See Also

EC_DVD_WARNING

FILTER_STATE

Data Types

Specifies a filter's state.

typedef enum _FilterState
   {   State_Stopped   = 0,
       State_Paused    = State_Stopped + 1,
       State_Running   = State_Paused + 1
    }  FILTER_STATE;
Values
State_Stopped
Equal to 0. The filter is not processing data.
State_Paused
Equal to 1. The filter is processing but not rendering data.
State_Running
Equal to 2. The filter is processing and rendering data.

InterleavingMode

Data Types

Specifies how video frames and audio samples will be written to disk.

  typedef enum
    {
        INTERLEAVE_NONE,
        INTERLEAVE_CAPTURE,
        INTERLEAVE_FULL
    } InterleavingMode;
Values
INTERLEAVE_NONE
Write out frames in the order they arrive (noninterleaved). Files must be turned into playback at a later time.
INTERLEAVE_CAPTURE
Approximate interleaving with less overhead than INTERLEAVE_FULL. Geared to video capture.
INTERLEAVE_FULL
Full, precise interleaving of audio samples and video frames. Geared to authoring and playback.

MPEG2Level

Data Types

Indicates the MPEG2 video level as specified in the MPEG2 video standard. (ISO13818-2)

enum MPEG2Level {
    MPEG2Level_Low = 1,
    MPEG2Level_Main,
    MPEG2Level_High1440,
    MPEG2Level_High
};
Values
MPEG2Level_Low
Low level.
MPEG2Level_Main
Main level.
MPEG2Level_High1440
High level.
MPEG2Level_High
Highest level.
Remarks

DVD MPEG-2 video decoders should support MPEG2Level_Low or MPEG2Level_Main.

MPEG2Profile

Data Types

Indicates the MPEG2 video profile as specified in the MPEG2 video standard. (ISO13818-2)

enum MPEG2Profile {
    MPEG2Profile_Simple = 1,
    MPEG2Profile_Main,
    MPEG2Profile_SNRScalable,
    MPEG2Profile_SpatiallyScalable,
    MPEG2Profile_High
};
Values
MPEG2Profile_Simple
Simple.
MPEG2Profile_Main
Main.
MPEG2Profile_SNRScalable
Signal to Noise Ratio (SNR) scalable.
MPEG2Profile_SpatiallyScalable
Spatially scalable.
MPEG2Profile_High
High.
Remarks

DVD video decoders should support MPEG2Profile_Simple or MPEG2Profile_Main.

PIN_DIRECTION

Data Types

Indicates a pin's direction.

typedef enum _PinDirection {
    PINDIR_INPUT,
    PINDIR_OUTPUT
} PIN_DIRECTION;
Values
PINDIR_INPUT
Input pin.
PINDIR_OUTPUT
Output pin.

REG_PINFLAG

Data Types

Indicates flags for the dwFlags member in the REGFILTERPINS2 structure.

enum
{
    REG_PINFLAG_B_ZERO = 0x1,
    REG_PINFLAG_B_RENDERER = 0x2,
    REG_PINFLAG_B_MANY = 0x4,
    REG_PINFLAG_B_OUTPUT = 0x8
} REG_PINFLAG;
Values
REG_PINFLAG_B_ZERO
Flag indicating that the filter has zero instances of this pin.
REG_PINFLAG_B_RENDERER
Flag indicating that the filter renders this input.
REG_PINFLAG_B_MANY
Flag indicating that the filter has more than one instance of this pin.
REG_PINFLAG_B_OUTPUT
Flag indicating that this pin is an output pin.

QualityMessageType

Data Types

Describes a quality message type.

typedef enum {
    Famine,
    Flood
} QualityMessageType;
Values
Famine
Downstream filter needs more data.
Flood
Downstream filter needs less data.

StreamControlState

Data Types

Specifies the state of the stream.

enum StreamControlState {
      STREAM_FLOWING,
      STREAM_DISCARDING
    };
Values
STREAM_FLOWING
Indicates the stream is currently transmitting data.
STREAM_DISCARDING
Discards the samples as they are received.

TunerInputType

Data Types

Specifies the frequency of a TV tuner (cable or antenna).

typedef enum
    {
        TunerInputCable,
        TunerInputAntenna
    } TunerInputType;
Values
TunerInputCable
Indicates cable frequency.
TunerInputAntenna
Indicates broadcast antenna frequency.

VfwCaptureDialogs

Data Types

Specifies a dialog box that might exist in a Video for Windows capture driver.

 typedef enum {
    VfwCaptureDialog_Source = 1,
    VfwCaptureDialog_Format = 2,
    VfwCaptureDialog_Display = 4
} VfwCaptureDialogs;
Values
VfwCaptureDialog_Source
Video source dialog box.
VfwCaptureDialog_Format
Video format dialog box.
VfwCaptureDialog_Display
Video display dialog box.
Remarks

The IAMVfwCaptureDialogs interface uses this enumerated data type.

VfwCompressDialogs

Data Types

Specifies a dialog box that might exist in a Video for Windows compression (codec) driver.

typedef enum {
    VfwCompressDialog_Config = 1,
    VfwCompressDialog_About = 2,
    VfwCompressDialog_QueryConfig = 4,
    VfwCompressDialog_QueryAbout = 8
} VfwCompressDialogs;
Values
VfwCompressDialog_Config
Configure dialog box.
VfwCompressDialog_About
About dialog box.
VfwCompressDialog_QueryConfig
Specifies whether the configure dialog is available.
VfwCompressDialog_QueryAbout
Specifies whether the about dialog is available.
Remarks

The IAMVfwCompressDialogs interface uses this enumerated data type.

VideoControlFlags

Data Types

Specifies the video mode of operation for a video device.

typedef enum tagVideoControlFlags
{
    VideoControlFlag_FlipHorizontal        = 0x0001,
    VideoControlFlag_FlipVertical          = 0x0002,
    VideoControlFlag_ExternalTriggerEnable = 0x0004,
    VideoControlFlag_Trigger               = 0x0008
} VideoControlFlags;
Values
VideoControlFlag_FlipHorizontal
Specifies that the picture is flipped horizontally.
VideoControlFlag_FlipVertical
Specifies that the picture is flipped vertically.
VideoControlFlag_ExternalTriggerEnable
Sets up a stream to capture a trigger from an external source, for example, a push button on a camera. Buffers can be queued to the driver but will not be passed up from the WDM capture driver (for compression, display, or writing to a file) until the external event happens. See Remarks.
VideoControlFlag_Trigger
In software, simulates an external trigger when the stream has the VideoControlFlag_ExternalTriggerEnable flag set.
Remarks

The IAMVideoControl interface uses this enumerated data type.

Multiple capture buffers are queued to a capture driver and are filled at a fixed rate once the stream is put into the "run" state. If the VideoControlFlag_ExternalTriggerEnable flag is set, a filled buffer is not passed up from the WDM capture driver for compression, display, or writing to a file until the external event happens.

VideoProcAmpFlags

Data Types

Specifies how to set video properties.

typedef enum tagVideoProcAmpFlags
    {
        VideoProcAmp_Flags_Manual = 0x0000,
        VideoProcAmp_Flags_Auto   = 0x0001,
    } VideoProcAmpFlags;
Values
VideoProcAmp_Flags_Manual
Set properties manually.
VideoProcAmp_Flags_Auto
Use auto setting.
Remarks

The IAMVideoProcAmp interface uses this enumerated data type.

VideoProcAmpProperty

Data Types

Specifies video properties.

typedef enum tagVideoProcAmpProperty
    {
        VideoProcAmp_Brightness,
        VideoProcAmp_Contrast,
        VideoProcAmp_Hue,
        VideoProcAmp_Saturation,
        VideoProcAmp_Sharpness,
        VideoProcAmp_Gamma,
        VideoProcAmp_ColorEnable,
        VideoProcAmp_WhiteBalance,
        VideoProcAmp_BacklightCompensation
    } VideoProcAmpProperty;
Values
VideoProcAmp_Brightness
Enables brightness.
VideoProcAmp_Contrast
Enables contrast.
VideoProcAmp_Hue
Enables hue.
VideoProcAmp_Saturation
Enables saturation.
VideoProcAmp_Sharpness
Enables sharpness.
VideoProcAmp_Gamma
Enables gamma.
VideoProcAmp_ColorEnable
Enables color.
VideoProcAmp_WhiteBalance
Enables white balance.
VideoProcAmp_BacklightCompensation
Enables backlight compensation.
Remarks

The IAMVideoProcAmp interface uses this enumerated data type.


Property Sets

DirectShow uses property sets to support extended services offered by hardware and its associated drivers and filters. Hardware and filter vendors can define new capabilities as properties, arrange them in property sets, and publish the specification for these property sets. As the application developer, you can use the methods of the IKsPropertySet interface to determine whether a driver or filter supports a particular set of properties, and retrieve or set those properties.

All the methods exposed by IKsPropertySet require a GUID that identifies the property set (the guidPropSet parameter) and a DWORD that identifies the property within the property set (the dwPropID parameter). The dwPropID parameter is typically a member of an enumerated data type.

Individual properties can also have associated data that you specify in the pPropData parameter in the IKsPropertySet::Set and IKsPropertySet::Get methods. IKsPropertySet intentionally leaves these parameters undefined (data type LPVOID), enabling the property set's designer to use them in a way most beneficial to the individual property. The definition of each property provides the purpose of the property data.

DirectShow provides property sets for DVD and capture. The following sections provide more information about these property sets.

  • DVD Subpicture Property Set
  • DVD Copy Protection Property Set
  • Pin Property Set
  • DVD Time Stamp Rate Change Property Set


DVD Subpicture Property Set

DVD Subpicture properties control the color, contrast, and output of the subpicture display.

The following information presents the necessary constants and data types to use for this property set in calls to IKsPropertySet methods. It provides values for the GUID (guidPropSet), property ID (dwPropID), and property data type (pPropData) parameters.

Property Set GUID: AM_KSPROPSETID_DvdSubPic
Property ID Data type used by the specified property
AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON AM_PROPERTY_COMPOSIT_ON
AM_PROPERTY_DVDSUBPIC_HLI AM_PROPERTY_SPHLI
AM_PROPERTY_DVDSUBPIC_PALETTE AM_PROPERTY_SPPAL

The following list provides the Subpicture property IDs and descriptions.

AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON
Set-only property that enables or disables subpicture display. DirectShow defines the AM_PROPERTY_COMPOSIT_ON Boolean data type for this property, as well as PAM_PROPERTY_COMPOSIT_ON as a pointer to this data type. TRUE indicates display the subpicture, FALSE indicates disable it. See the WDM portion of the Windows 98 DDK for more information.
AM_PROPERTY_DVDSUBPIC_HLI
Set-only property that specifies a rectangle of subpicture or screen whose color or contrast will be changed. Data type is AM_PROPERTY_SPHLI.

The AM_PROPERTY_DVDSUBPIC_HLI property is set-only. It specifies a rectangle of subpicture or screen whose color or contrast will be changed. This differs from the DVD-Video specification, in that the Microsoft DVD navigator parses all button and keyboard information and passes only one highlight rectangle to the subpicture decoder at any given time. As a result, highlight information is sent to the decoder more often than it is present in the DVD stream.

The highlight information arrives asynchronously to the data stream. The decoder uses the highlight Start and End time stamps to correlate the highlight information to the relevant subpicture information, if any. If the decoder has not received any subpicture stream information for the requested time stamps, the decoder assumes that the highlight information is stand-alone and does not apply to a subpicture. In this case, the decoder assumes the color and contrast information is all the same color.

The data is not entirely in DVD disc format. Microsoft provides an additional structure of type AM_PROPERTY_SPHLI that is passed as the parameter to this property. This structure describes the currently selected button from the DVD highlight information.

The DVD navigator processes all keystroke information and sends new highlight information each time a button state changes. The information describes only one mode of one button at a time. It includes a display rectangle in pixel coordinates of the screen, or a display of the subpicture, if present. The structure also contains color and contrast information, but only for the present state of the currently selected button. The format is defined in the DVD specification.

Highlight information contains Start and End time stamps. These are in the same units as other time stamps, with two exceptions: A Start time stamp of 0xFFFFFFFF means the highlight property is effective upon receipt, and an End time stamp of 0xFFFFFFFF means the highlight property is valid until next highlight received.

The HLISS field is as defined in the DVD specification. A value of zero indicates that all highlights are invalid and the decoder should disable all highlights.

AM_PROPERTY_DVDSUBPIC_PALETTE
Sets the palette for a subpicture. Data type is AM_PROPERTY_SPPAL.

Use the IKsPropertySet interface to set, retrieve, and query for support of these properties.

This property set uses the following data types.
Data type | Description
AM_COLCON | Specifies the color contrast. Substructure of the AM_PROPERTY_SPHLI structure.
AM_DVD_YUV | Specifies DVD YUV subpicture data. Substructure of the AM_PROPERTY_SPPAL structure.
AM_PROPERTY_COMPOSIT_ON | Boolean data used by the AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON property.
AM_PROPERTY_SPHLI | Describes the currently selected button from the DVD highlight information.
AM_PROPERTY_SPPAL | Specifies the DVD subpicture palette.

AM_COLCON

DVD Subpicture Property Set

Indicates the color contrast description from the DVD highlight (HLI) structure.

 typedef struct _AM_COLCON {
    UCHAR emph1col:4;
    UCHAR emph2col:4;
    UCHAR backcol:4;
    UCHAR patcol:4;
    UCHAR emph1con:4;
    UCHAR emph2con:4;
    UCHAR backcon:4;
    UCHAR patcon:4;
} AM_COLCON, *PAM_COLCON;
Members
emph1col
Emphasis color 1.
emph2col
Emphasis color 2.
backcol
Background color.
patcol
Pattern color.
emph1con
Emphasis contrast 1.
emph2con
Emphasis contrast 2.
backcon
Background contrast.
patcon
Pattern contrast.
Remarks

This structure is contained within the AM_PROPERTY_SPHLI structure.

AM_DVD_YUV

DVD Subpicture Property Set

DVD YUV subpicture data.

 typedef struct _AM_DVD_YUV {
    UCHAR   Reserved;
    UCHAR   Y;
    UCHAR   U;
    UCHAR   V;
} AM_DVD_YUV, *PAM_DVD_YUV;
Members
Reserved
Reserved.
Y
Y color data.
U
U color data.
V
V color data.
Remarks

This structure is contained within the AM_PROPERTY_SPPAL structure.

AM_PROPERTY_SPHLI

DVD Subpicture Property Set

Describes the currently selected button from the DVD highlight information.

 typedef struct _AM_PROPERTY_SPHLI {
    USHORT  HLISS;
    USHORT  Reserved;
    ULONG   StartPTM;
    ULONG   EndPTM;
    USHORT  StartX;
    USHORT  StartY;
    USHORT  StopX;
    USHORT  StopY;
    AM_COLCON  ColCon;
} AM_PROPERTY_SPHLI, *PAM_PROPERTY_SPHLI;
Members
HLISS
Highlight status of current selection.
Reserved
Reserved for internal use. Do not use or set.
StartPTM
Start presentation time divided by 90,000.
EndPTM
End presentation time divided by 90,000.
StartX
Start x-coordinate pixel of the current highlight button.
StartY
Start y-coordinate pixel of the current highlight button.
StopX
Ending x-coordinate pixel of the current highlight button.
StopY
Ending y-coordinate pixel of the current highlight button.
ColCon
Color contrast description of type AM_COLCON.
Remarks

The AM_PROPERTY_DVDSUBPIC_HLI property uses this structure.

AM_PROPERTY_SPPAL

DVD Subpicture Property Set

Specifies the DVD subpicture palette.

 typedef struct _AM_PROPERTY_SPPAL {
    AM_DVD_YUV sppal[16];
} AM_PROPERTY_SPPAL, *PAM_PROPERTY_SPPAL;
Members
sppal
Array of 16 YUV elements that correspond to the 4-bit color numbers requested within the subpicture command stream. The YUV elements are of type AM_DVD_YUV.
Remarks

The AM_PROPERTY_DVDSUBPIC_PALETTE property uses this structure.


DVD Copy Protection Property Set

The DVD Copy Protection property set provides authentication of copy protection information from hardware or software decrypters. Use this property set to prevent unauthorized copying from prerecorded DVD-Video.

Microsoft provides software that facilitates the authentication process required by the encryption scheme, thus enabling a DVD-ROM drive to authenticate and transfer keys with a DVD decrypter. Microsoft has no current plans to ship a DVD decrypter and, instead, is providing operating system code that will act as the agent to enable authentication of either hardware or software decrypters.

The DVD navigator initiates and controls the key exchange process. The DVD minidriver needs only to implement the following properties. Other components handle the rest.

Each DVD input stream will receive copy protection properties. This is true even if the same hardware controls all DVD streams.

The following information presents the necessary constants and data types to use for this property set in calls to IKsPropertySet methods. It provides values for the GUID (guidPropSet), property ID (dwPropID), and property data type (pPropData) parameters.

Property Set GUID: AM_KSPROPSETID_CopyProt
Property ID | Data type used by the specified property
AM_PROPERTY_COPY_MACROVISION AM_COPY_MACROVISION
AM_PROPERTY_DVDCOPY_CHLG_KEY AM_DVDCOPY_CHLGKEY
AM_PROPERTY_DVDCOPY_DEC_KEY2 AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_DISC_KEY AM_DVDCOPY_DISCKEY
AM_PROPERTY_DVDCOPY_DVD_KEY1 AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_REGION | The DVD_REGION structure.
AM_PROPERTY_DVDCOPY_SET_COPY_STATE AM_DVDCOPY_SET_COPY_STATE
AM_PROPERTY_DVDCOPY_TITLE_KEY AM_DVDCOPY_TITLEKEY

The following list provides the DVD Copy Protection property IDs and descriptions.

AM_PROPERTY_COPY_MACROVISION
This is a set-only property. This property sets the Macrovision level for the NTSC encoder on the output end of the receiving pin.
AM_PROPERTY_DVDCOPY_CHLG_KEY
Both get and set operations are supported on this property. A get operation requests the decoder to provide its bus challenge key. A set operation provides the decoder with the bus challenge key from the DVD drive. The data passed in this property will be a structure of type AM_DVDCOPY_CHLGKEY.
AM_PROPERTY_DVDCOPY_DEC_KEY2
This is a get-only property. This property requests that the decoder's bus key 2 be transferred to the DVD drive. The data passed will be a structure of type AM_DVDCOPY_BUSKEY.
AM_PROPERTY_DVDCOPY_DISC_KEY
Set-only property. This provides disc key. The key is a structure of type AM_DVDCOPY_DISCKEY.
AM_PROPERTY_DVDCOPY_DVD_KEY1
This is a set-only property. This property provides the DVD drive bus key 1 to the decoder. The data passed will be a structure of type AM_DVDCOPY_BUSKEY.
AM_PROPERTY_DVDCOPY_SET_COPY_STATE
Both get and set are supported on this property. Get is called first to determine if authentication is required. The set properties are indications as to which phase of copy protection negotiation the filter is entering. The data passed will be a structure of type AM_DVDCOPY_SET_COPY_STATE.
AM_PROPERTY_DVDCOPY_REGION
Region code requests the region definition that the decoder is allowed to play in as defined by the DVD consortium. This region is defined by the following structure:

typedef struct _DVD_REGION {
   UCHAR CopySystem;   //specifies whether or not the disk is copy protected
   UCHAR RegionData;    //information about the region from decoder
   UCHAR SystemRegion;  //information about region from DVD drive
   UCHAR Reserved; //reserved
} DVD_REGION, *PDVD_REGION;
AM_PROPERTY_DVDCOPY_TITLE_KEY
This is a set-only property. This provides title key from current content. The key is a structure of type AM_DVDCOPY_TITLEKEY.

Use the IKsPropertySet interface to set, retrieve, and query for support of these properties.

This property set uses the following data types.
Data type | Description
AM_COPY_MACROVISION | Macrovision level for the NTSC encoder.
AM_COPY_MACROVISION_LEVEL | Macrovision level. The AM_COPY_MACROVISION structure uses this data type.
AM_DVDCOPY_BUSKEY | DVD bus key.
AM_DVDCOPY_CHLGKEY | DVD challenge key.
AM_DVDCOPY_DISCKEY | DVD disc key.
AM_DVDCOPY_SET_COPY_STATE | Determines the copy protection state of the filter.
AM_DVDCOPYSTATE | Copy protection state. The AM_DVDCOPY_SET_COPY_STATE structure uses this data type.
AM_DVDCOPY_TITLEKEY | DVD title key from the current content.

AM_COPY_MACROVISION

DVD Copy Protection Property Set

Macrovision level for the NTSC encoder.

typedef struct _AM_COPY_MACROVISION {
    ULONG MACROVISIONLevel;
} AM_COPY_MACROVISION, *PAM_COPY_MACROVISION;
Members
MACROVISIONLevel
Macrovision level for the NTSC encoder. Member of the AM_COPY_MACROVISION_LEVEL enumerated data type.
Remarks

The AM_PROPERTY_COPY_MACROVISION property uses this structure.

AM_COPY_MACROVISION_LEVEL

DVD Copy Protection Property Set

Macrovision level.

typedef enum {
    AM_MACROVISION_DISABLED,
    AM_MACROVISION_LEVEL1,
    AM_MACROVISION_LEVEL2,
    AM_MACROVISION_LEVEL3
} AM_COPY_MACROVISION_LEVEL, *PAM_COPY_MACROVISION_LEVEL;
Values
AM_MACROVISION_DISABLED
Disabled.
AM_MACROVISION_LEVEL1
Level 1.
AM_MACROVISION_LEVEL2
Level 2.
AM_MACROVISION_LEVEL3
Level 3.
Remarks

The AM_COPY_MACROVISION structure uses this data type.

AM_DVDCOPY_BUSKEY

DVD Copy Protection Property Set

DVD bus key.

 typedef struct _AM_DVDCOPY_BUSKEY {
    BYTE BusKey[5];
    BYTE Reserved[1];
} AM_DVDCOPY_BUSKEY, *PAM_DVDCOPY_BUSKEY;
Members
BusKey
DVD drive bus key.
Reserved
Reserved.
Remarks

The AM_PROPERTY_DVDCOPY_DVD_KEY1 and AM_PROPERTY_DVDCOPY_DEC_KEY2 properties use this structure.

A bus key is used for the DVD CSS key exchange for decryption. Implementors should get a CSS license and further instructions from CSS. See DVD-Video specification for contact information.

AM_DVDCOPY_CHLGKEY

DVD Copy Protection Property Set

DVD challenge key.

 typedef struct _AM_DVDCOPY_CHLGKEY {
    BYTE ChlgKey[10];
    BYTE Reserved[2];
} AM_DVDCOPY_CHLGKEY, *PAM_DVDCOPY_CHLGKEY;
Members
ChlgKey
Challenge key.
Reserved
Reserved.
Remarks

The AM_PROPERTY_DVDCOPY_CHLG_KEY property uses this structure.

A challenge key is used for the DVD CSS key exchange for decryption. Implementors should get a CSS license and further instructions from CSS. See DVD-Video specification for contact information.

AM_DVDCOPY_DISCKEY

DVD Copy Protection Property Set

DVD disc key.

 typedef struct _AM_DVDCOPY_DISCKEY {
    BYTE DiscKey[2048];
} AM_DVDCOPY_DISCKEY, *PAM_DVDCOPY_DISCKEY;
Members
DiscKey
DVD disc key.
Remarks

The AM_PROPERTY_DVDCOPY_DISC_KEY property uses this structure.

A disc key is used for the DVD CSS key exchange for decryption. Implementors should get a CSS license and further instructions from CSS. See DVD-Video specification for contact information.

AM_DVDCOPY_SET_COPY_STATE

DVD Copy Protection Property Set

Determines the copy protection state of the filter.

typedef struct AM_DVDCOPY_SET_COPY_STATE {
    ULONG DVDCopyState;
} AM_DVDCOPY_SET_COPY_STATE, *PAM_DVDCOPY_SET_COPY_STATE;
Members
DVDCopyState
Copy protection state of the filter. Member of the AM_DVDCOPYSTATE enumerated data type.
Remarks

Both the IKsPropertySet::Get and IKsPropertySet::Set methods are supported on this property. The IKsPropertySet::Get method is called first to determine if authentication is required. If a filter provides multiple pins that use the same authenticator, such as a hardware DVD decoder, the decoder might respond with AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED on some pins to indicate that the key exchange algorithm only needs to be applied once. The filter should respond with AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED to get the copy protection state property on the first pin where this property is issued.

The IKsPropertySet::Set method is used to indicate which phase of copy protection negotiation the filter is entering. Specify these by setting the required flag in the AM_DVDCOPYSTATE enumerated type.

The AM_PROPERTY_DVDCOPY_SET_COPY_STATE property uses this structure.

AM_DVDCOPYSTATE

DVD Copy Protection Property Set

Copy protection state.

typedef enum {
    AM_DVDCOPYSTATE_INITIALIZE,
AM_DVDCOPYSTATE_INITIALIZE_TITLE,
    AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED,
    AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED,
    AM_DVDCOPYSTATE_DONE
} AM_DVDCOPYSTATE;
Values
AM_DVDCOPYSTATE_INITIALIZE
Starting a full key-exchange algorithm.
AM_DVDCOPYSTATE_INITIALIZE_TITLE
Starting a title key-exchange algorithm.
AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED
Authentication is not required.
AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED
Authentication required.
AM_DVDCOPYSTATE_DONE
Key exchange negotiation is complete.
Remarks

The AM_DVDCOPY_SET_COPY_STATE structure uses this data type.

AM_DVDCOPY_TITLEKEY

DVD Copy Protection Property Set

DVD title key from the current content.

 typedef struct AM_DVDCOPY_TITLEKEY {
    ULONG KeyFlags;
    UCHAR TitleKey[6];
    UCHAR Reserved[2];
} AM_DVDCOPY_TITLEKEY, *PAM_DVDCOPY_TITLEKEY;
Members
KeyFlags
Key flags.
TitleKey
Title key.
Reserved
Reserved.
Remarks

The AM_PROPERTY_DVDCOPY_TITLE_KEY property uses this structure.

A title key is used for the DVD CSS key exchange for decryption. Implementors should get a CSS license and further instructions from CSS. See DVD-Video specification for contact information.


Pin Property Set

The Pin property set enables you to set and retrieve the category to which a pin belongs, if any. The most commonly used categories are for the capture and preview pins on a capture filter.

The following information presents the necessary constants and data types to use for this property set in calls to IKsPropertySet methods. It provides values for the GUID (guidPropSet), property ID (dwPropID), and property data type (pPropData) parameters.

Property Set GUID: AMPROPSETID_Pin

The AMPROPERTY_PIN_CATEGORY pin category property is the only property in this property set. This property uses a GUID data type. DirectShow defines the following pin categories in Uuids.h, which you can find in the SDK Include directory.
Category | Description
PIN_CATEGORY_ANALOGVIDEOIN | Input pin of the capture filter that takes analog and digitizes it.
PIN_CATEGORY_CAPTURE | Capture pin.
PIN_CATEGORY_CC | Pin providing closed captioning data from Line 21.
PIN_CATEGORY_EDS | Pin providing Extended Data Services (Line 21, even fields).
PIN_CATEGORY_NABTS | Pin providing North American Videotext Standard data.
PIN_CATEGORY_PREVIEW | Preview pin.
PIN_CATEGORY_STILL | Pin providing a still image.
PIN_CATEGORY_TELETEXT | Pin providing teletext (a closed captioning variant).
PIN_CATEGORY_TIMECODE | Pin providing timecode data.
PIN_CATEGORY_VBI | Pin providing vertical blanking interval data.
PIN_CATEGORY_VIDEOPORT | Pin to be connected to a VPE filter.
PIN_CATEGORY_VIDEOPORT_VBI | Pin to be connected to a VPE filter that provides surfaces for capturing vertical blanking interval data.

Use the IKsPropertySet interface to set, retrieve, and query for support of these properties.


DVD Time Stamp Rate Change Property Set

The DVD Time Stamp Rate Change property set enables you to change DVD playback rate. DVD playback rates are changed by modifying time stamps between input and output pins on two filters.

Time stamp remapping is a linear relationship given by the equation y = r(x - xi), where y is the new time stamp, r is the rate (or slope), x is the original time stamp, and xi is the x-intercept. This can be represented graphically where the time stamps input to the filter are shown along the x-axis and the output time stamps are shown along the y-axis:

Graph illustrating time stamp remapping

Variable definitions for the time stamp conversion graph:
x = input time stamp
y = output time stamp
xi = current x-axis intercept
xs = start time of the current rate
xi2 = x-axis intercept for new rate
xs2 = start time of the new rate
r = current rate
r2 = new rate

The decoder filter handles DVD rate changes, by reading the original time stamp on the media sample (x). The remaining variables, r and xi, must either be supplied or internally calculated to determine the new time stamp for the sample. The Time Stamp Rate Change property set supports two mechanisms for setting these parameters:

  • The AM_RATE_ExactRateChange property accepts the OutputZeroTime parameter as the x-axis intercept for new rate, and the Rate parameter as the new rate (xi2 and r2). However, you must supply the upstream filter setting this property with the equation (y = r(x - xi)) that the downstream filter is using to do the rate change.
  • The AM_RATE_SimpleRateChange property specifies two parameters that an upstream filter already knows: the new rate (r2) and the start time of the new rate (xs2). This requires the filter doing the rate change to calculate the x-axis intercept (xi2). You can calculate the new x-axis intercept with the following formula: xi2 = (r/r2)(xi - xs2) + xs2. Now that you have the input time stamp (x), the new rate (r2), and x-axis intercept (xi2), you can plug these variables into the original equation y = r2(x - xi2) to calculate the new time stamp.

Specifiying the AM_RATE_SimpleRateChange property is the easiest way to change the rate, but requires the filter to do some additional calculation.

The AM_RATE_MaxFullDataRate property enables an upstream filter to query for the maximum rate at which it can process the data. It uses the AM_MaxFullDataRate data type, which is a LONG value.

Finally, the AM_RATE_Step property enables the filter to step forward one sample at a time. It uses the AM_Step data type, which is a DWORD value.

The following information presents the necessary constants and data types to use for this property set in calls to IKsPropertySet methods. It provides values for the GUID (guidPropSet), property ID (dwPropID), and property data type (pPropData) parameters.

Property Set GUID: AM_TS_RATE_CHANGE
Property ID Data type used by the specified property
AM_RATE_ExactRateChange AM_ExactRateChange
AM_RATE_MaxFullDataRate AM_MaxFullDataRate
AM_RATE_SimpleRateChange AM_SimpleRateChange
AM_RATE_Step AM_Step

The following list provides the Time Stamp Rate Change property set IDs and descriptions.

AM_RATE_ExactRateChange
Use the AM_ExactRateChange structure to change rate.
AM_RATE_MaxFullDataRate
Use the AM_MaxFullDataRate long value to process at maximum rate.
AM_RATE_SimpleRateChange
Use the AM_SimpleRateChange structure to change rate.
AM_RATE_Step
Indicates the number of frames to step over.

Use the IKsPropertySet interface to set, retrieve, and query for support of these properties.

This property set uses the following data types.
Data type | Description
AM_ExactRateChange | Changes the rate of DVD playback based on the new rate and the time at which the output time stamps are zero.
AM_SimpleRateChange | Changes the rate of DVD playback, based on starting time and the new rate.

AM_ExactRateChange

DVD Time Stamp Rate Change Property Set

Changes the rate of DVD playback based on the new rate and the time at which the output time stamps are zero.

typedef struct {
    REFERENCE_TIME  OutputZeroTime;
    LONG		Rate;
} AM_ExactRateChange;
Members
OutputZeroTime
Time at which the output time stamps are zero.
Rate
New rate of playback.
Remarks

The OutputZeroTime member variable represents the x-intercept in the graph shown in the DVD Time Stamp Rate Change Property Set section.

The AM_RATE_ExactRateChange property uses this structure.

AM_SimpleRateChange

DVD Time Stamp Rate Change Property Set

Changes the rate of DVD playback, based on starting time and the new rate.

typedef struct {REFERENCE_TIME	StartTime;
    LONG		Rate;
} AM_SimpleRateChange;
Members
StartTime
Time at which the new rate will take effect.
Rate
New rate of playback.
Remarks

Specify values for Rate member that are multiples of the normal rate, such as 2 for double time or .5 for half time.

The AM_RATE_SimpleRateChange property uses this structure.


DirectShow Animated Header -- Event Notification Codes DirectShow Animated Header -- Event Notification Codes * Microsoft DirectShow SDK
  * Previous Topic: DVD Time Stamp Rate Change Property Set
  * Next Topic: Event Notification Codes

Event Notification Codes

This section contains reference entries for the DirectShow event notification codes (events).

Event Notification Codes

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


Event Notification Codes

Microsoft® DirectShow™ supports system-defined events, which filters in the filter graph pass to the filter graph manager. Filters pass these events to the filter graph manager by using the IMediaEventSink::Notify method, and the application retrieves them with the IMediaEvent::GetEvent method.

When you retrieve an event by calling GetEvent, the event can contain interface pointers or pointers to allocated memory. Code that uses GetEvent should, therefore, call IMediaEvent::FreeEventParams to free any resources associated with the event's parameters after it handles the event.

The system-defined event notification codes are listed in the Evcode.h header file.

See DVD Event Notification Codes for event notification codes that are specific to DVD. The following list shows the available event notification codes in alphabetical order.
Event Notification Code | Description
EC_ACTIVATE | An audio or video renderer is losing or gaining activation.
EC_BUFFERING_DATA | The buffering status is changing.
EC_CLOCK_CHANGED | The filter graph has changed from one reference clock to another.
EC_COMPLETE | All data has been rendered.
EC_DISPLAY_CHANGED | The current display mode has been changed.
EC_END_OF_SEGMENT | Notifies that a segment end has been reached.
EC_ERROR_STILLPLAYING | At least one call to Run failed in an active filter graph. The current state of any underlying filter graph or graphs is indeterminate; they might be running, but some are almost certainly not.
EC_ERRORABORT | An error forced the termination of a requested operation.
EC_FULLSCREEN_LOST | The video renderer is switching out of full-screen mode.
EC_NEED_RESTART | The current graph must be stopped and restarted.
EC_NOTIFY_WINDOW | Pass the window handle around during pin connection.
EC_OLE_EVENT | A filter is passing a text string to the application.
EC_OPENING_FILE | The open file status is changing.
EC_PALETTE_CHANGED | The video palette has changed.
EC_QUALITY_CHANGE | The playback quality has changed.
EC_REPAINT | A repaint is required.
EC_SEGMENT_STARTED | Notifies that a new segment has been started.
EC_SHUTTING_DOWN | The filter graph is starting to shut down. DirectShow passes this notification to any plug-in distributors that support the IMediaEventSink interface.
EC_STARVATION | One of the filters (usually a parser or file source filter) isn't receiving enough data. By default, the filter graph manager will pause all running filters, and then return to normal operation when enough data is available.
EC_STREAM_CONTROL_STARTED | The starting reference time from an earlier call to IAMStreamControl::StartAt passed.
EC_STREAM_CONTROL_STOPPED | The stopping reference time from an earlier call to IAMStreamControl::StopAt passed.
EC_STREAM_ERROR_STILLPLAYING | The stream is still playing, but should not be playing.
EC_STREAM_ERROR_STOPPED | The stream has stopped, but should not have stopped.
EC_TIME | The requested reference time occurred.
EC_USERABORT | A user has forced the termination of a requested operation.
EC_VIDEO_SIZE_CHANGED | The size of the native video has changed.
EC_WINDOW_DESTROYED | The video renderer's filter is being removed or destroyed.

EC_ACTIVATE

An audio or video renderer is losing or gaining activation. The audio or video renderer sends this event notification.

EC_ACTIVATE

Parameters
lParam1
Set to 1 if activation gained, or 0 if lost.
lParam2
Pointer to the IBaseFilter interface that is sending the event notification.
Remarks

This event notification is not sent to the application. This notification is used for sound-follows-focus and full-screen switching. To interact in full-screen protocols, a video renderer should send an EC_ACTIVATE notification whenever its window is either activated or deactivated. In other words, an EC_ACTIVATE notification should be sent for each WM_ACTIVATEAPP message received by a renderer.

EC_BUFFERING_DATA

The buffering status is changing.

EC_BUFFERING_DATA

Parameters
lParam1
Set to 1 if starting to buffer data, or 0 if not buffering any more.
lParam2
Zero.
Remarks

This event notification is sent to the application. This notification is used to allow the user interface to indicate that some data (media) is being buffered (loaded) prior to being processed by DirectShow. This notification is also sent when the buffering has stopped.

EC_CLOCK_CHANGED

The filter graph has changed from one reference clock to another.

EC_CLOCK_CHANGED

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

One likely cause of this event notification is a call to the IMediaFilter::SetSyncSource method.

EC_COMPLETE

All data has been rendered. Renderers send this event notification.

EC_COMPLETE

Parameters
lParam1
HRESULT value of some operation. This can be S_OK.
lParam2
Zero.
Remarks

The default is not to send this event notification to the application, you can override the default by calling the IMediaEvent::CancelDefaultHandling method. No more data should be accepted after the EndOfStream method is called on the renderer's input pin. Exactly one EC_COMPLETE notification must be sent for each logical stream. Stopping a renderer resets any end-of-stream state that is cached.

Although individual EC_COMPLETE events aren't sent by default, the last individual EC_COMPLETE is sent to the application when all streams have sent one to the filter graph. If the default handling is turned off, the application gets them all (one per stream).

EC_DISPLAY_CHANGED

The current display mode has been changed. Renderers send this event notification when they detect a display change.

EC_DISPLAY_CHANGED

Parameters
lParam1
Pointer to the IPin interface that should be reconnected by the graph.
lParam2
Zero.
Remarks

This event notification is not sent to the application. Most video renderers pick a format during connection so that the format can be drawn efficiently through GDI. If the user changes the current display mode without restarting the machine, a renderer might find itself with a bad image format connection. In these situations, a renderer might send an EC_DISPLAY_CHANGED event code to the filter graph manager. The first parameter should be the pin that needs reconnecting. The filter graph manager will arrange for the filter graph to be stopped and the pin reconnected. During the subsequent reconnection, the renderer can accept a more appropriate format.

EC_END_OF_SEGMENT

Notifies that a segment end has been reached.

EC_END_OF_SEGMENT

Parameters
lParam1
Pointer to a REFERENCE_TIME value indicating accumulated stream clock time since the start of the segment. You can compute this time directly as the sum of the previous and current segment durations and the rate applied to each segment. The source adds this time to the time within each segment to get a total elapsed time.
lParam2
DWORD value indicating the segment number. Zero based.
Remarks

Notifies that a segment end has been reached when the AM_SEEKING_Segment flag was set for IMediaSeeking::SetPositions. Passes in an IMediaSeeking interface to allow the next segment to be defined by the application.

EC_ERROR_STILLPLAYING

A playback error has occurred, but the graph is still playing.

EC_ERROR_STILLPLAYING

Parameters
lParam1
HRESULT value of some operation that failed.
lParam2
Zero.

EC_ERRORABORT

An error forced the termination of a requested operation.

EC_ERRORABORT

Parameters
lParam1
HRESULT value of some operation that failed. For instance, this might be VFW_E_CANNOT_CONNECT if a reconnect failed.
lParam2
Zero.
Remarks

A filter or the filter graph manager generates this event notification and sends it to the application.

EC_FULLSCREEN_LOST

The video renderer is switching out of full-screen mode.

EC_FULLSCREEN_LOST

Parameters
lParam1
Zero.
lParam2
Pointer to the IBaseFilter interface that is sending the notification (the modex renderer in this case).
Remarks

The full-screen renderer sends this event notification to an application. When the EC_ACTIVATE notification is sent to the filter graph manager upon switching out of full-screen mode, the filter graph manager sends an EC_FULLSCREEN_LOST notification to the controlling application. The application might use this notification to restore the state of a full-screen button, for example. The EC_ACTIVATE notifications are used internally by DirectShow to manage full-screen switching on cues from the video renderers.

EC_NEED_RESTART

The current graph must be stopped and restarted.

EC_NEED_RESTART

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

Renderers send this notification when they regain a resource. For example, if a renderer loses contact with a device and rejects the next data sample, the stream must reconnect to the device and restart at the current position to start rendering data again. If the media stream is currently running, DirectShow calls IAMovie::Pause to pause the stream, IAMovie::put_CurrentPosition to set the current position, and IAMovie::Run to restart the stream.

EC_NOTIFY_WINDOW

Pass the window handle around during pin connection.

EC_NOTIFY_WINDOW

Parameters
lParam1
Handle to the window.
lParam2
Zero.

EC_OLE_EVENT

A filter is passing a text string to the application.

EC_OLE_EVENT

Parameters
lParam1
BSTR for the event notification. The application must free the BSTR by calling the IMediaEvent::FreeEventParams method.
lParam2
Zero.

EC_OPENING_FILE

The open file status is changing.

EC_OPENING_FILE

Parameters
lParam1
Set to 1 if starting to open file, or 0 if not opening any more.
lParam2
Zero.
Remarks

This event notification is sent to the application. This notification is used to allow the user interface to indicate that a media file is being opened prior to being processed by DirectShow. (Because the file might be on the Internet or some slow device, some opens might take longer.) This notification is also sent when the file has been opened.

EC_PALETTE_CHANGED

The video palette has changed.

EC_PALETTE_CHANGED

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

This event notification is sent to the application and the filter graph manager. Whenever a video renderer detects a palette change in the stream, it should send the EC_PALETTE_CHANGED notification to the filter graph manager. The DirectShow video renderers detect whether a palette has really changed in dynamic format or not. The video renderers do this not only to filter out the number of EC_PALETTE_CHANGED notifications sent, but also to reduce the amount of palette creation, installation, and deletion required.

EC_QUALITY_CHANGE

The playback quality has changed.

EC_QUALITY_CHANGE

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

This event notification is sent to the application from a filter. This notification occurs only once if degradation has occurred and a filter has responded to a quality event notification.

EC_REPAINT

A repaint is required. Paused or stopped video renderers send this message when they receive a WM_PAINT message and there is no data to display.

EC_REPAINT

Parameters
lParam1
Pointer to the IPin interface that needs the data to be sent again.
lParam2
Zero.
Remarks

The default is not to send this event notification to the application, although the default can be overridden by calling IMediaEvent::CancelDefaultHandling. A renderer should send its input pin as the first parameter to the event. By doing this, the attached output pin will be queried for IMediaEventSink, and if supported, the EC_REPAINT notification will be sent there first. This allows output pins to handle repaints before the filter graph must be touched.

EC_SEGMENT_STARTED

Notifies that a new segment has been started.

EC_SEGMENT_STARTED

Parameters
lParam1
Pointer to a REFERENCE_TIME value indicating accumulated stream clock time since the start of the segment. You can compute this time directly as the sum of the previous and current segment durations and the rate applied to each segment.
lParam2
DWORD value indicating the segment number. Zero based.
Remarks

This notification is sent synchronously by any entity that will issue EC_END_OF_SEGMENT when a new segment is started. See the AM_SEEKING_Segment flag from IMediaSeeking::SetPositions. This notification is used to compute how many EC_END_OF_SEGMENT notifications to expect at the end of a segment and as a consistency check.

EC_SHUTTING_DOWN

The shutdown of the filter graph is starting.

EC_SHUTTING_DOWN

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

This event notification is not sent to the application. This notification notifies plug-in distributors that the filter graph is shutting down.

EC_STARVATION

A filter has detected starvation.

EC_STARVATION

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

A filter sends this event notification. This notification is not sent to the application. The default handling of this notification (only when running) is for the graph to be paused until all filters enter the paused state, and then to wait for the pause to complete. The filter which signaled EC_STARVATION should not complete the pause until it has enough data to resume. Normally, this would be sent by a parser or source filter when too little data is arriving.

EC_STREAM_CONTROL_STARTED

A previous call to the IAMStreamControl::StartAt method has taken effect.

EC_STREAM_CONTROL_STARTED

Parameters
pSender
Address of an IPin interface that will contain the pin that called IAMStreamControl::StartAt.
dwCookie
DWORD value that you can use to mark the start.
Remarks

You can mark calls to this event with dwCookie, allowing applications to easily associate request and completion notifications.

After the completion of this event, pSender will point to the pin that called IAMStreamControl::StartAt. This is not necessarily the pin that received the IAMStreamControl::StartAt call.

EC_STREAM_CONTROL_STOPPED

A previous call to the IAMStreamControl::StopAt method has taken effect.

EC_STREAM_CONTROL_STOPPED

Parameters
pSender
Address of an IPin interface that will contain the pin that called IAMStreamControl::StopAt.
dwCookie
DWORD value that you can use to mark the stop.
Remarks

You can mark calls to this event with dwCookie, allowing applications to easily associate request and completion notifications.

After the completion of this event, pSender will point to the pin that called IAMStreamControl::StopAt. This is not necessarily the pin that received the IAMStreamControl::StopAt call.

EC_STREAM_ERROR_STILLPLAYING

The stream is still playing, but should not be playing.

EC_STREAM_ERROR_STILLPLAYING

Parameters
lParam1
Major code (HRESULT of some operation that failed).
lParam2
Minor code (generally zero).
Remarks

A filter send this event notification to the filter graph manager and the application.

EC_STREAM_ERROR_STOPPED

The stream has stopped, but should not have stopped.

EC_STREAM_ERROR_STOPPED

Parameters
lParam1
Major code (HRESULT of some operation that failed).
lParam2
Minor code (generally zero.).
Remarks

This event notification is sent from a filter to the filter graph manager and the application.

EC_TIME

The requested reference time occurred.

EC_TIME

Parameters
lParam1
Reference time, low-order DWORD.
lParam2
Reference time, high-order DWORD.

EC_USERABORT

A user has forced the termination of a requested operation.

EC_USERABORT

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

This event notification is sent by video renderers to the filter graph manager and the application. This notification signals a closure that the user requested. For example, this notification would be sent if the user closed the video window. After this notification has been sent, no more samples should be accepted until the renderer has gone through a stop transition. No EC_REPAINT notifications should be sent after an EC_USERABORT notification is sent unless the renderer is stopped and reset.

EC_VIDEO_SIZE_CHANGED

The size of the native video has changed.

EC_VIDEO_SIZE_CHANGED

Parameters
lParam1
Low-order WORD value is the width in pixels; high-order WORD is the height in pixels.
lParam2
Zero.
Remarks

This event notification is sent whenever a video renderer detects a change in native video size. An application might use this notification to negotiate space in a compound document. The actual video dimensions are available through the IBasicVideo control interface. The DirectShow renderers detect whether the video has changed size or not prior to sending these events.

EC_WINDOW_DESTROYED

The video renderer's filter is being removed or destroyed. Video renderers send this event notification so that resources that depend on window focus can be passed to other filters.

EC_WINDOW_DESTROYED

Parameters
lParam1
Pointer to the IBaseFilter interface whose window is being destroyed.
lParam2
Zero.
Remarks

This event notification is not sent to the application. A renderer should send this notification when its window is destroyed. The first parameter must be the renderer's IBaseFilter interface. In fact, sending this when the filter is being destroyed might be too late, because the filter graph manager might have already been destroyed. Therefore, it is best to handle this when the renderer's IBaseFilter::JoinFilterGraph method is called with a null filter graph (indicating that the renderer is about to be removed from the filter graph). Sending these event codes allows the plug-in distributor in the filter graph manager to pass on resources that depend on window focus to other filters (such as audio devices).


DVD Event Notification Codes

Microsoft® DirectShow™ supports system-defined events, which filters in the filter graph pass to the filter graph manager. Filters pass these events to the filter graph manager by using the IMediaEventSink::Notify method, and the application retrieves them with the IMediaEvent::GetEvent method.

When you retrieve an event by calling GetEvent, the event can contain interface pointers or pointers to allocated memory. Code that uses GetEvent should, therefore, call IMediaEvent::FreeEventParams to free any resources associated with the event's parameters after it handles the event.

The digital versatile disc (DVD) event notification codes are listed in Dvdevcod.h. See Event Notification Codes for non-DVD event notification codes. The following list shows the available DVD event notification codes in alphabetical order.
DVD event notification code | Description
EC_DVD_ANGLE_CHANGE | Signals that either the number of available angles changed or that the current user angle number changed.
EC_DVD_AUDIO_STREAM_CHANGE | Signals that the current user audio stream number changed for the main title.
EC_DVD_BUTTON_CHANGE | Signals that either the number of available buttons changed or that the currently selected button number changed.
EC_DVD_CHAPTER_AUTOSTOP | Indicates that playback stopped as the result of a call to the IDvdControl::ChapterPlayAutoStop method.
EC_DVD_CHAPTER_START | Signals that the DVD player started playback of a new program in the DVD_DOMAIN_Title domain.
EC_DVD_CURRENT_TIME | Signals the beginning of every video object unit (VOBU), which occurs every 0.4 to 1.0 seconds.
EC_DVD_DOMAIN_CHANGE | Indicates the DVD player's new domain.
EC_DVD_ERROR | Signals a DVD error condition.
EC_DVD_NO_FP_PGC | Indicates that the DVD disc does not have a FP_PGC (First Play Program Chain).
EC_DVD_PLAYBACK_RATE_CHANGE | Indicates that a playback rate change has been initiated and the new rate is in the parameter.
EC_DVD_STILL_OFF | Signals the end of any still (PGC, Cell, or VOBU).
EC_DVD_STILL_ON | Signals the beginning of any still (PGC, Cell, or VOBU).
EC_DVD_SUBPICTURE_STREAM_CHANGE | Signals that the current user subpicture stream number changed for the main title.
EC_DVD_TITLE_CHANGE | Indicates when the current title number changes.
EC_DVD_VALID_UOPS_CHANGE | Signals that the available set of IDvdControl interface methods has changed.
EC_DVD_WARNING | Signals a DVD warning condition.

EC_DVD_ANGLE_CHANGE

DVD Event Notification Codes

Signals that either the number of available angles changed or that the current user angle number changed.

EC_DVD_ANGLE_CHANGE

Parameters
lParam1
DWORD value indicating the number of available angles. When the number of available angles is 1, the current video is not multiangle.
lParam2
DWORD value indicating the current user angle number.
Remarks

Angle numbers range from 1 to 9.

The current angle number can change automatically with a navigation command authored on the disc as well as through application control by using the IDvdControl interface.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_AUDIO_STREAM_CHANGE

DVD Event Notification Codes

Signals that the current user audio stream number changed for the main title.

EC_DVD_AUDIO_STREAM_CHANGE

Parameters
lParam1
DWORD value indicating the new user audio stream number. Audio stream numbers range from 0 to 7. Stream 0xFFFFFFFF indicates that no stream is selected.
lParam2
Zero.
Remarks

The current user audio stream can change automatically with a navigation command authored on the disc as well as through application control by using the IDvdControl interface.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_BUTTON_CHANGE

DVD Event Notification Codes

Signals that either the number of available buttons changed or that the currently selected button number changed.

EC_DVD_BUTTON_CHANGE

Parameters
lParam1
DWORD value indicating the number of available buttons.
lParam2
DWORD value indicating the currently selected button number. Selected button number zero implies that no button is selected.
Remarks

Button numbers range from 1 to 36.

The currently selected button can change automatically with a navigation command authored on the disc as well as through application control by using IDvdControl interface.

This event can signal any of the available button numbers. These numbers do not always correspond to button numbers used for IDvdControl::ButtonSelectAndActivate because that method can activate only a subset of buttons.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_CHAPTER_AUTOSTOP

DVD Event Notification Codes

Indicates that playback stopped as the result of a call to the IDvdControl::ChapterPlayAutoStop method.

EC_DVD_CHAPTER_AUTOSTOP

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

The DVD_DOMAIN_Title domain raises this event.

EC_DVD_CHAPTER_START

DVD Event Notification Codes

Signals that the DVD player started playback of a new program in the DVD_DOMAIN_Title domain.

EC_DVD_CHAPTER_START

Parameters
lParam1
DWORD value indicating the new chapter (program) number.
lParam2
Zero.
Remarks

Only simple linear movies signal this event.

The DVD_DOMAIN_Title domain raises this event.

EC_DVD_CURRENT_TIME

DVD Event Notification Codes

Signals the beginning of every video object unit (VOBU), which occurs every 0.4 to 1.0 seconds.

EC_DVD_CURRENT_TIME

Parameters
lParam1
DWORD value indicating the current playback timecode in a binary coded decimal (BCD) hours, minutes, seconds, frames (HH:MM:SS:FF) format. Member of the DVD_TIMECODE structure.
lParam2
Boolean (BOOL) value indicating the timecode. Zero (0) indicates 25 frames per second while 1 indicates 30 frames per second (nondropped).
Remarks

Only simple linear movies signal this event.

The DVD_DOMAIN_Title domain raises this event.

EC_DVD_DOMAIN_CHANGE

DVD Event Notification Codes

Indicates the DVD player's new domain.

EC_DVD_DOMAIN_CHANGE

Parameters
lParam1
DWORD value indicating the new domain. Member of the DVD_DOMAIN enumerated data type.
lParam2
Zero.
Remarks

The DVD player signals this event whenever it changes domains.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_ERROR

DVD Event Notification Codes

Signals a DVD error condition.

EC_DVD_ERROR

Parameters
lParam1
DWORD value indicating the error condition. Member of the DVD_ERROR enumerated data type.
lParam2
Zero.
Remarks

All domains (DVD_DOMAIN) raise this event.

EC_DVD_NO_FP_PGC

DVD Event Notification Codes

Signals that the DVD disc does not have a FP_PGC (First Play Program Chain) and that the DVD Navigator will not automatically load any PGC and start playback.

Remarks

The FP_DOM domain raises this event.

EC_DVD_PLAYBACK_RATE_CHANGE

DVD Event Notification Codes

Signals that a rate change in the playback has been initiated and that the parameter lParam1 indicates the new playback rate being used.

EC_DVD_PLAYBACK_RATE_CHANGE

Parameters
lParam1
LONG indicating the new playback rate. lParam1 < 0 indicates reverse playback mode. lParam1 > 0 indicates forward playback mode. The value of lParam1 is the actual playback rate multiplied by 10,000, that is, lParam1 = playback_rate * 10000.
Remarks

The TT_DOM domain raises this event.

EC_DVD_STILL_OFF

DVD Event Notification Codes

Signals the end of any still (PGC, Cell, or VOBU).

EC_DVD_STILL_OFF

Parameters
lParam1
Zero.
lParam2
Zero.
Remarks

This event indicates that any currently active still has been released.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_STILL_ON

DVD Event Notification Codes

Signals the beginning of any still (PGC, Cell, or VOBU).

EC_DVD_STILL_ON

Parameters
lParam1
Boolean (BOOL) value indicating whether buttons are available. Zero (0) indicates buttons are available so the IDvdControl::StillOff method won't work. One (1) indicates no buttons are available, so IDvdControl::StillOff will work.
lParam2
DWORD value indicating the number of seconds the still will last. 0xFFFFFFFF indicates an infinite still, meaning wait until the user presses a button or until the application calls IDvdControl::StillOff.
Remarks

All combinations of buttons and still are possible (buttons on with still on, buttons on with still off, button off with still on, button off with still off).

All domains (DVD_DOMAIN) raise this event.

EC_DVD_SUBPICTURE_STREAM_CHANGE

DVD Event Notification Codes

Signals that the current user subpicture stream number changed for the main title.

EC_DVD_SUBPICTURE_STREAM_CHANGE

Parameters
lParam1
DWORD value indicating the new user subpicture stream number. Subpicture stream numbers range from 0 to 31. Stream 0xFFFFFFFF indicates that no stream is selected.
lParam2
Zero.
Remarks

The subpicture can change automatically with a navigation command authored on disc as well as through application control using IDvdControl.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_TITLE_CHANGE

DVD Event Notification Codes

Indicates when the current title number changes.

EC_DVD_TITLE_CHANGE

Parameters
lParam1
DWORD value indicating the new title number.
lParam2
Zero.
Remarks

Title numbers range from 1 to 99. This number indicates the TTN, which is the title number with respect to the whole disc, not the VTS_TTN which is the title number with respect to just a current VTS.

The DVD_DOMAIN_Title domain raises this event.

EC_DVD_VALID_UOPS_CHANGE

DVD Event Notification Codes

Signals that the available set of IDvdControl interface methods has changed.

EC_DVD_VALID_UOPS_CHANGE

Parameters
lParam1
DWORD value representing the VALID_UOP_SOMTHING_OR_OTHER bit-field structure that indicates which IDvdControl commands the DVD disc explicitly disabled.
lParam2
Zero.
Remarks

This event indicates only which operations are explicitly disabled by the content on the DVD disc, and does not guarantee that it is valid to call methods that are not disabled. For example, if no buttons are present, the IDvdControl::ButtonActivate method won't work, even though the buttons are not explicitly disabled.

All domains (DVD_DOMAIN) raise this event.

EC_DVD_WARNING

DVD Event Notification Codes

Signals a DVD warning condition.

EC_DVD_WARNING

Parameters
lParam1
DWORD value indicating the warning condition. Member of the DVD_WARNING enumerated data type.
lParam2
Zero.
Remarks

All domains (DVD_DOMAIN) raise this event.


Error and Success Codes

Microsoft® DirectShow™ returns error and success notifications (return codes) to applications in the form of HRESULT values. A return code's LOWORD portion is the return code itself, in hexadecimal format. After you obtain the return code, a call to the AMGetErrorText function returns the code's text description. The COM Win32 HRESULT documentation contains more information, including how to use the FAILED and SUCCEEDED macros to test return values.

The following list presents some of the typical COM error and success codes that DirectShow returns.
Value | Meaning
E_FAIL | Failure.
E_INVALIDARG | Argument is invalid.
E_NOTIMPL | Method is not supported.
E_POINTER | NULL pointer argument.
E_UNEXPECTED | Unexpected error.
NOERROR | No error. Numerically equivalent to S_OK.
S_FALSE | Success. Condition was FALSE.
S_OK | Success. Numerically equivalent to NOERROR.
S_TRUE | Success. Condition was TRUE.

The following table contains DirectShow-specific error and success codes in numerical order. Return codes beginning with VFW_S_ indicate success overall. An operation might partially succeed and still have a successful return value. For example, VFW_S_SOME_DATA_IGNORED indicates that a file was rendered by ignoring some of its property settings. Return codes beginning with VFW_E_ indicate an error, while those beginning with CTL_ pertain specifically to the ActiveMovie™ Control. This table does not contain all possible return values; the return codes shown apply specifically to DirectShow. DirectShow-specific return codes also appear in Vfwmsgs.h in the DirectShow SDK Include directory. If you encounter an error not listed here, the error code might appear in another source, such as a list of COM or Windows® 95 errors. For example, Microsoft Visual C++® users can find COM or Windows 95 errors in the Winerror.h include file.

C/C++ programmers receive error codes in complete (32-bit) hexadecimal format. Microsoft Visual Basic® programmers, on the other hand, will see only the decimal equivalent of the error code's first 16-bit portion. This value appears in an error notification dialog box or in the Err object as a run-time error. If the error is not in the following list, you must convert the decimal number to its hexadecimal equivalent, and then look for the error as described previously. Note that the error's hexadecimal version will be a maximum of four digits long; to find the error, match the last four digits of the hexadecimal code in the error code list to the converted run-time error.
Return Code | Hexadecimal Value | Decimal Value
CTL_E_ILLEGALFUNCTIONCALL | 0x800A0005 | 5
CTL_E_OVERFLOW | 0x800A0006 | 6
CTL_E_OUTOFMEMORY | 0x800A0007 | 7
CTL_E_DIVISIONBYZERO | 0x800A000B | 11
CTL_E_OUTOFSTRINGSPACE | 0x800A000E | 14
CTL_E_OUTOFSTACKSPACE | 0x800A001C | 28
CTL_E_BADFILENAMEORNUMBER | 0x800A0034 | 52
CTL_E_FILENOTFOUND | 0x800A0035 | 53
CTL_E_BADFILEMODE | 0x800A0036 | 54
CTL_E_FILEALREADYOPEN | 0x800A0037 | 55
CTL_E_DEVICEIOERROR | 0x800A0039 | 57
CTL_E_FILEALREADYEXISTS | 0x800A003A | 58
CTL_E_BADRECORDLENGTH | 0x800A003B | 59
CTL_E_DISKFULL | 0x800A003D | 61
CTL_E_BADRECORDNUMBER | 0x800A003F | 63
CTL_E_BADFILENAME | 0x800A0040 | 64
CTL_E_TOOMANYFILES | 0x800A0043 | 67
CTL_E_DEVICEUNAVAILABLE | 0x800A0044 | 68
CTL_E_PERMISSIONDENIED | 0x800A0046 | 70
CTL_E_DISKNOTREADY | 0x800A0047 | 71
CTL_E_PATHFILEACCESSERROR | 0x800A004B | 75
CTL_E_PATHNOTFOUND | 0x800A004C | 76
CTL_E_INVALIDPATTERNSTRING | 0x800A005D | 93
CTL_E_INVALIDUSEOFNULL | 0x800A005E | 94
VFW_S_NO_MORE_ITEMS | 0x00040103 | 259
There are no more items in the list.
CTL_E_INVALIDFILEFORMAT | 0x800A0141 | 321
CTL_E_INVALIDPROPERTYVALUE | 0x800A017C | 380
CTL_E_INVALIDPROPERTYARRAYINDEX | 0x800A017D | 381
CTL_E_SETNOTSUPPORTEDATRUNTIME | 0x800A017E | 382
CTL_E_SETNOTSUPPORTED | 0x800A017F | 383
CTL_E_NEEDPROPERTYARRAYINDEX | 0x800A0181 | 385
CTL_E_SETNOTPERMITTED | 0x800A0183 | 387
CTL_E_GETNOTSUPPORTEDATRUNTIME | 0x800A0189 | 393
CTL_E_GETNOTSUPPORTED | 0x800A018A | 394
CTL_E_PROPERTYNOTFOUND | 0x800A01A6 | 422
CTL_E_INVALIDCLIPBOARDFORMAT | 0x800A01CC | 460
CTL_E_INVALIDPICTURE | 0x800A01E1 | 481
CTL_E_PRINTERERROR | 0x800A01E2 | 482
VFW_E_INVALIDMEDIATYPE | 0x80040200 | 512
The specified media type is invalid.
VFW_E_INVALIDSUBTYPE | 0x80040201 | 513
The specified media subtype is invalid.
VFW_E_NEED_OWNER | 0x80040202 | 514
This object can only be created as an aggregated object.
VFW_E_ENUM_OUT_OF_SYNC | 0x80040203 | 515
The enumerator has become invalid.
VFW_E_ALREADY_CONNECTED | 0x80040204 | 516
At least one of the pins involved in the operation is already connected.
VFW_E_FILTER_ACTIVE | 0x80040205 | 517
This operation cannot be performed because the filter is active.
VFW_E_NO_TYPES | 0x80040206 | 518
One of the specified pins supports no media types.
VFW_E_NO_ACCEPTABLE_TYPES | 0x80040207 | 519
There is no common media type between these pins.
VFW_E_INVALID_DIRECTION | 0x80040208 | 520
Two pins of the same direction cannot be connected.
VFW_E_NOT_CONNECTED | 0x80040209 | 521
The operation cannot be performed because the pins are not connected.
VFW_E_NO_ALLOCATOR | 0x8004020A | 522
No sample buffer allocator is available.
VFW_E_RUNTIME_ERROR | 0x8004020B | 523
A run-time error occurred.
VFW_E_BUFFER_NOTSET | 0x8004020C | 524
No buffer space has been set.
VFW_E_BUFFER_OVERFLOW | 0x8004020D | 525
The buffer is not big enough.
VFW_E_BADALIGN | 0x8004020E | 526
An invalid alignment was specified.
VFW_E_ALREADY_COMMITTED | 0x8004020F | 527
Cannot change allocated memory while the filter is active.
VFW_E_BUFFERS_OUTSTANDING | 0x80040210 | 528
One or more buffers are still active.
VFW_E_NOT_COMMITTED | 0x80040211 | 529
Cannot allocate a sample when the allocator is not active.
VFW_E_SIZENOTSET | 0x80040212 | 530
Cannot allocate memory because no size has been set.
VFW_E_NO_CLOCK | 0x80040213 | 531
Cannot lock for synchronization because no clock has been defined.
VFW_E_NO_SINK | 0x80040214 | 532
Quality messages could not be sent because no quality sink has been defined.
VFW_E_NO_INTERFACE | 0x80040215 | 533
A required interface has not been implemented.
VFW_E_NOT_FOUND | 0x80040216 | 534
An object or name was not found.
VFW_E_CANNOT_CONNECT | 0x80040217 | 535
No combination of intermediate filters could be found to make the connection.
VFW_E_CANNOT_RENDER | 0x80040218 | 536
No combination of filters could be found to render the stream.
VFW_E_CHANGING_FORMAT | 0x80040219 | 537
Could not change formats dynamically.
VFW_E_NO_COLOR_KEY_SET | 0x8004021A | 538
No color key has been set.
VFW_E_NOT_OVERLAY_CONNECTION | 0x8004021B | 539
Current pin connection is not using the IOverlay transport.
VFW_E_NOT_SAMPLE_CONNECTION | 0x8004021C | 540
Current pin connection is not using the IMemInputPin transport.
VFW_E_PALETTE_SET | 0x8004021D | 541
Setting a color key would conflict with the palette already set.
VFW_E_COLOR_KEY_SET | 0x8004021E | 542
Setting a palette would conflict with the color key already set.
VFW_E_NO_COLOR_KEY_FOUND | 0x8004021F | 543
No matching color key is available.
VFW_E_NO_PALETTE_AVAILABLE | 0x80040220 | 544
No palette is available.
VFW_E_NO_DISPLAY_PALETTE | 0x80040221 | 545
Display does not use a palette.
VFW_E_TOO_MANY_COLORS | 0x80040222 | 546
Too many colors for the current display settings.
VFW_E_STATE_CHANGED | 0x80040223 | 547
The state changed while waiting to process the sample.
VFW_E_NOT_STOPPED | 0x80040224 | 548
The operation could not be performed because the filter is not stopped.
VFW_E_NOT_PAUSED | 0x80040225 | 549
The operation could not be performed because the filter is not paused.
VFW_E_NOT_RUNNING | 0x80040226 | 550
The operation could not be performed because the filter is not running.
VFW_E_WRONG_STATE | 0x80040227 | 551
The operation could not be performed because the filter is in the wrong state.
VFW_E_START_TIME_AFTER_END | 0x80040228 | 552
The sample start time is after the sample end time.
VFW_E_INVALID_RECT | 0x80040229 | 553
The supplied rectangle is invalid.
VFW_E_TYPE_NOT_ACCEPTED | 0x8004022A | 554
This pin cannot use the supplied media type.
VFW_E_SAMPLE_REJECTED | 0x8004022B | 555
This sample cannot be rendered.
VFW_E_SAMPLE_REJECTED_EOS | 0x8004022C | 556
This sample cannot be rendered because the end of the stream has been reached.
VFW_E_DUPLICATE_NAME | 0x8004022D | 557
An attempt to add a filter with a duplicate name failed.
VFW_S_DUPLICATE_NAME | 0x0004022D | 557
An attempt to add a filter with a duplicate name succeeded with a modified name.
VFW_E_TIMEOUT | 0x8004022E | 558
A time-out has expired.
VFW_E_INVALID_FILE_FORMAT | 0x8004022F | 559
The file format is invalid.
VFW_E_ENUM_OUT_OF_RANGE | 0x80040230 | 560
The list has already been exhausted.
VFW_E_CIRCULAR_GRAPH | 0x80040231 | 561
The filter graph is circular.
VFW_E_NOT_ALLOWED_TO_SAVE | 0x80040232 | 562
Updates are not allowed in this state.
VFW_E_TIME_ALREADY_PASSED | 0x80040233 | 563
An attempt was made to queue a command for a time in the past.
VFW_E_ALREADY_CANCELLED | 0x80040234 | 564
The queued command was already canceled.
VFW_E_CORRUPT_GRAPH_FILE | 0x80040235 | 565
Cannot render the file because it is corrupt.
VFW_E_ADVISE_ALREADY_SET | 0x80040236 | 566
An IOverlay advise link already exists.
VFW_S_STATE_INTERMEDIATE | 0x00040237 | 567
The state transition is not complete.
VFW_E_NO_MODEX_AVAILABLE | 0x80040238 | 568
No full-screen modes are available.
VFW_E_NO_ADVISE_SET | 0x80040239 | 569
This advise cannot be canceled because it was not successfully set.
VFW_E_NO_FULLSCREEN | 0x8004023A | 570
Full-screen mode is not available.
VFW_E_IN_FULLSCREEN_MODE | 0x8004023B | 571
Cannot call IVideoWindow methods while in full-screen mode.
VFW_E_UNKNOWN_FILE_TYPE | 0x80040240 | 576
The media type of this file is not recognized.
VFW_E_CANNOT_LOAD_SOURCE_FILTER | 0x80040241 | 577
The source filter for this file could not be loaded.
VFW_S_PARTIAL_RENDER | 0x00040242 | 578
Some of the streams in this movie are in an unsupported format.
VFW_E_FILE_TOO_SHORT | 0x80040243 | 579
A file appeared to be incomplete.
VFW_E_INVALID_FILE_VERSION | 0x80040244 | 580
The file's version number is invalid.
VFW_S_SOME_DATA_IGNORED | 0x00040245 | 581
The file contained some property settings that were not used.
VFW_S_CONNECTIONS_DEFERRED | 0x00040246 | 582
Some connections failed and were deferred.
VFW_E_INVALID_CLSID | 0x80040247 | 583
This file is corrupt: it contains an invalid class identifier.
VFW_E_INVALID_MEDIA_TYPE | 0x80040248 | 584
This file is corrupt: it contains an invalid media type.
VFW_E_SAMPLE_TIME_NOT_SET | 0x80040249 | 585
No time stamp has been set for this sample.
VFW_S_RESOURCE_NOT_NEEDED | 0x00040250 | 592
The resource specified is no longer needed.
VFW_E_MEDIA_TIME_NOT_SET | 0x80040251 | 593
No media time stamp was set for this sample.
VFW_E_NO_TIME_FORMAT_SET | 0x80040252 | 594
No media time format was selected.
VFW_E_MONO_AUDIO_HW | 0x80040253 | 595
Cannot change balance because audio device is mono only.
VFW_S_MEDIA_TYPE_IGNORED | 0x00040254 | 596
Could not connect with the media type in the persistent graph.
VFW_E_NO_DECOMPRESSOR | 0x80040255 | 597
Cannot play back the video stream: could not find a suitable decompressor.
VFW_E_NO_AUDIO_HARDWARE | 0x80040256 | 598
Cannot play back the audio stream: no audio hardware is available, or the hardware is not supported.
VFW_S_VIDEO_NOT_RENDERED | 0x00040257 | 599
Cannot play back the video stream: could not find a suitable renderer.
VFW_S_AUDIO_NOT_RENDERED | 0x00040258 | 600
Cannot play back the audio stream: could not find a suitable renderer.
VFW_E_RPZA | 0x80040259 | 601
Cannot play back the video stream: format 'RPZA' is not supported.
VFW_S_RPZA | 0x0004025A | 602
Cannot play back the video stream: format 'RPZA' is not supported.
VFW_E_PROCESSOR_NOT_SUITABLE | 0x8004025B | 603
DirectShow cannot play MPEG movies on this processor.
VFW_E_UNSUPPORTED_AUDIO | 0x8004025C | 604
Cannot play back the audio stream: the audio format is not supported.
VFW_E_UNSUPPORTED_VIDEO | 0x8004025D | 605
Cannot play back the video stream: the video format is not supported.
VFW_E_MPEG_NOT_CONSTRAINED | 0x8004025E | 606
DirectShow cannot play this video stream because it falls outside the constrained standard.
VFW_E_NOT_IN_GRAPH | 0x8004025F | 607
Cannot perform the requested function on an object that is not in the filter graph.
VFW_S_ESTIMATED | 0x00040260 | 608
The value returned had to be estimated. Its accuracy can't be guaranteed.
VFW_E_NO_TIME_FORMAT | 0x80040261 | 609
Cannot get or set time-related information on an object that is using a time format of
VFW_E_READ_ONLY | 0x80040262 | 610
Could not make the connection because the stream is read-only and the filter alters the data.
VFW_S_RESERVED | 0x00040263 | 611
This success code is reserved for internal purposes within DirectShow.
VFW_E_BUFFER_UNDERFLOW | 0x80040264 | 612
The buffer is not full enough.
VFW_E_UNSUPPORTED_STREAM | 0x80040265 | 613
Cannot play back the file: the format is not supported.
VFW_E_NO_TRANSPORT | 0x80040266 | 614
Pins cannot connect because they don't support the same transport.
VFW_S_STREAM_OFF | 0x00040267 | 615
The stream was turned off.
VFW_S_CANT_CUE | 0x00040268 | 616
The graph can't be cued because it lacks data or contains corrupt data.
VFW_E_BAD_VIDEOCD | 0x80040269 | 617
The Video CD can't be read correctly by the device or is the data is corrupt.
VFW_S_NO_STOP_TIME | 0x80040270 | 618
The sample had a start time but not a stop time. In this case, the stop time returned is set to the start time plus one. The IMediaSample::GetTime method can return this success code.
VFW_E_OUT_OF_VIDEO_MEMORY | 0x80040271 | 619
There is not enough video memory at this display resolution and number of colors. Reducing resolution might help.
VFW_E_VP_NEGOTIATION_FAILED | 0x80040272 | 620
The video port connection negotiation process has failed.
VFW_E_DDRAW_CAPS_NOT_SUITABLE | 0x80040273 | 621
Either Microsoft DirectDraw® has not been installed or the video card capabilities are not suitable. Make sure the display is not in 16-color mode.
VFW_E_NO_VP_HARDWARE | 0x80040274 | 622
No video port hardware is available, or the hardware is not responding.
VFW_E_NO_CAPTURE_HARDWARE | 0x80040275 | 623
No Capture hardware is available, or the hardware is not responding.
VFW_E_DVD_OPERATION_INHIBITED | 0x80040276 | 624
This user operation is inhibited by DVD content at this time.
VFW_E_DVD_INVALIDDOMAIN | 0x80040277 | 625
This operation is not permitted in the current domain.
VFW_E_DVD_NO_BUTTON | 0x80040278 | 626
Requested button is not available.
VFW_E_DVD_GRAPHNOTREADY | 0x80040279 | 627
DVD-Video playback graph has not been built yet.
VFW_E_DVD_RENDERFAIL | 0x8004027a | 628
DVD-Video playback graph building failed.
VFW_E_DVD_DECNOTENOUGH | 0x8004027b | 629
DVD-Video playback graph could not be built due to insufficient decoders.
CTL_E_CANTSAVEFILETOTEMP | 0x800A02DF | 735
CTL_E_SEARCHTEXTNOTFOUND | 0x800A02E8 | 744
CTL_E_REPLACEMENTSTOOLONG | 0x800A02EA | 746
VFW_E_BAD_KEY | 0x800403F2 | 1010
A registry entry is corrupt.


Filters and Samples

This topic contains a brief description of the filters and sample applications shipped with DirectShow. The filters are supplied as binary code only and are available through the Filter Graph Editor. The samples include source code and demonstrate how to write DirectShow filters and applications. You can use these filters and samples as they are or modify them for your own applications.

DirectShow Filters

DirectShow Samples


DirectShow Filters

Microsoft® DirectShow™ provides filters and samples as part of the DirectShow Software Development Kit (SDK). A filter is supplied as binary code only, and is one of the filters listed in the Filter Graph Editor when you choose Insert Filters from the Graph menu. Filters are described in this section.

Samples include source code. Some samples are filters and some are applications. Some of the sample filters are registered and appear in the Filter Graph Editor. Other sample filters must be built and registered before they will appear in the Filter Graph Editor. Sample filters (and sample applications) are described in DirectShow Samples.

The DirectShow SDK provides the following filters:

  • ACM Audio Compressor
  • Analog Video Crossbar
  • Audio Capture
  • Audio Renderer
  • AVI Compressor
  • AVI Decompressor
  • AVI Draw
  • AVI MUX
  • AVI Splitter
  • AVI/WAV File Source
  • Color Space Converter
  • Cutlist File Source
  • DSound Audio Renderer
  • DV Muxer
  • DV Splitter
  • DV Video Decoder
  • DV Video Encoder
  • DVD Navigator
  • File Source (Async)
  • File Source (URL)
  • File Stream Renderer
  • File Writer
  • Full Screen Renderer
  • Indeo 4.3 Video Compression
  • Indeo 4.3 Video Decompression
  • Indeo 5.0 Audio Decompression
  • Indeo 5.0 Video Compression
  • Indeo 5.0 Video Decompression
  • Indeo 5.0 Video Progressive Download Sources
  • Internal Script Command Renderer
  • Line 21 Decoder
  • Lyric Parser
  • MIDI Parser
  • MIDI Renderer
  • MPEG Audio Decoder
  • MPEG Video Decoder
  • MPEG-1 Stream Splitter
  • Multi-File Parser
  • Overlay Mixer
  • QuickTime Decompressor
  • QuickTime Movie Parser
  • SAMI (CC) Parser
  • Smart Tee Filter
  • TrueMotion 2.0 Decompressor
  • TV Audio
  • TV Tuner
  • VFW Video Capture
  • VGA 16 Color Ditherer
  • Video Renderer
  • WAVE Parser
  • WDM Video Capture


ACM Audio Compressor

The ACM Audio Compressor filter acts as a container for the Audio Compression Manager (ACM), integrating the ACM with the DirectShow architecture. It supports the IAMStreamConfig interface, which lets you control audio capture or compression information from a filter's output pin.


Analog Video Crossbar

The WDM-based Analog Video Crossbar filter can select or route analog video. The single output stream represents a hardware path for analog baseband video. One of the input pins comes from a TV Tuner (the TV Tuner Filter). Other input pins support video streams.

The Analog Video Crossbar filter exposes the IAMCrossbar interface, which is used for routine source selection.

This filter is available through Windows 98 and Windows NT 5.


Audio Capture

The Audio Capture (WaveIn) filter is installed with the DirectShow run time. If you have audio capture hardware, this filter is available in the Filter Graph Editor when you choose Insert Filters from the Graph menu, under the Audio Capture Source category.

Unlike ordinary DirectShow filters, special category filters, such as Audio Capture Source filters, can work with more than one device. When DirectShow is installed, it will look for devices installed on your computer that work with the special category filter and list the options in that category. For example, in the Audio Capture Source filter category, DirectShow will list all the audio capture cards (which includes sound cards with microphone inputs) installed on the system. You then need to choose which device to use.

The audio capture filter has one capture output pin and several input pins (one for each type of input on the card, such as LineIn, Mic, CD, and MIDI).

The filter and its input pins each support IAMAudioInputMixer.

The output pin supports IAMStreamConfig.

This filter enables your sound capture card(s). If you have a sound card, it will be listed under in the Filter Graph Editor's list of filters in the Audio Capture Source category, with a name indicating the sound card it is enabling.


Audio Renderer

The Audio Renderer filter is a generic audio rendering filter that you can connect to the output of any of the following filters, if they contain WAV audio: File Source (Async), File Source (URL), MPEG-1 Stream Splitter, AVI Splitter, WAVE Parser, or any audio transform filter. This filter does not check the audio stream's subtype; the WAVEFORMAT or WAVEFORMATEX structure passed in the format block contains the information needed to connect to this filter.

The filter's property sheet contains the following:
Tab | Property | Values
Audio Input Pin (rendered) | Preferred Media Types | Lists the major type, subtype, and format.
Audio Renderer | wFormatTag | Waveform-audio format type. Many compression algorithms have registered format tags; the Mmreg.h header file contains a complete list of these format tags.
nChannels | Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.
nSamplePerSec | Rate, in samples per second (hertz), at which each channel should play or record. If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplePerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, you must compute this member according to the manufacturer's format specification.
nAvgBytesPerSec | Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, then nAvgBytesPerSec should equal the product of nSamplesPerSec and nBlockAlign. For formats other than pulse code modulation (PCM), you must compute this member according to the manufacturer's format specification. Playback and record software can estimate buffer sizes by using the nAvgBytesPerSec member.
nBlockAlign Block alignment, in bytes. The block alignment is the smallest unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, then nBlockAlign should equal nChannels. For non-PCM formats, this member must be computed according to the manufacturer's format specification.

Playback and record software must process a multiple of nBlockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

Rate | Specifies the rendering rate for this file. This value acts as a multiplier; 1.0 represents the authored speed. Read-only.


AVI Compressor

The AVI compressor filter has one input pin and one output pin.

The filter supports the IAMVfwCompressDialogs interface.

The output pin supports the IAMStreamConfig and IAMVideoCompression interfaces.


AVI Decompressor

The AVI Decompressor filter decompresses AVI input and generates suitable output for a video rendering filter or an intervening video transform filter.


AVI Draw

This filter handles IOverlay interface support for an audio-video interleaved (AVI) video data stream. The AVI Draw filter's input pin connects to a video data output pin from the AVI Splitter filter. The AVI Draw output pin must connect to a filter that supports overlays; currently, the Video Renderer filter is the only such filter included with the DirectShow SDK.

DirectShow typically uses this filter to play back motion-JPEG (MJPEG) compressed AVI files on a computer with hardware support for MJPEG playback. In a general sense, this filter negotiates connections between specific hardware devices and AVI video streams that rely on those hardware devices, such as video capture and playback cards. This filter is not needed for playback or processing of streams that are hardware-independent.


AVI MUX

The AVI MUX filter takes the input from one or more media streams, converts the data if necessary, and combines it to produce a single output data stream in audio-video interleaved (AVI) format. This filter's output pin must be connected to the File Writer filter.

The AVI MUX's default behavior produces an AVI 1.0 format interleaved data stream. Use the IConfigAviMux interface to change the compatibility index.

The filter's property sheet contains the following:
Tab | Property | Values
Interleaving | Interleaving | Controls the level of interleaving between the source media files; you can specify the level of interleaving: none, capture, or full.
Interleaving Parameters | Sets the audio preroll and interleaving frequency (measured in milliseconds).
Throughput Statistics | Displays the number of dropped frames on the output data stream.
AVI Specific | Capture Drift: master stream | Enable and disable Capture Drift on the specified master stream.
AVI Out | Preferred Media Types | Displays the major type, subtype, and format of the output data stream.
Input 0X | Preferred Media Types | Displays the major type, subtype, and format of the specified input data stream.


AVI Splitter

The AVI Splitter filter parses AVI-compressed video data and splits it into the component data streams. It can be connected to the File Source (async), File Source (URL), or AVI/WAV File Source filter supplied with DirectShow, or a third-party filter that delivers a compressed AVI stream and can interface with an asynchronous parser.


AVI/WAV File Source

The AVI/WAV File Source filter reads AVI and WAV source files and generates the appropriate output pins for the file type.

For WAV files, the filter creates an audio output pin, which produces an audio stream that can be connected to an audio rendering filter or intervening audio transform filter.

For AVI files, the filter creates a video output pin, which produces a compressed AVI stream suitable for the AVI codec filter, and an audio output pin, which produces an audio stream suitable for an audio rendering filter or an intervening audio transform filter.


Color Space Converter

This transform filter converts from one RGB color type to another, such as between 24-bit and 8-bit RGB color. You can use this filter to convert to a color space used by the video rendering filter, such as from the AVI Decompressor filter to the Full Screen Renderer filter.


Cutlist File Source

This source filter can output different pieces of different .avi or .wav files seamlessly and efficiently. It can be used for nonlinear video editing and for audio editing.

Using the CutListGraphBuilder object, the SimpleCutList object, and the VideoFileClip and AudioFileClip objects, an application can build a cutlist out of pieces of .avi and .wav, and use the DirectShow Cutlist Source Filter to play it.


DSound Audio Renderer

The DSound Audio Renderer filter is a generic audio rendering filter that you can connect to the output of any of the following filters, if they contain WAV audio: File Source (Async), File Source (URL), MPEG-1 Stream Splitter, AVI Splitter, WAVE Parser, or any audio transform filter. In addition to its basic sound-rendering capabilities, this filter can process Microsoft DirectX® DirectSound® API calls; use the IAMDirectSound methods to set and retrieve the window that will handle the sound playback.

Note that this filter does not check the subtype of the audio stream; the WAVEFORMAT or WAVEFORMATEX structure passed in the format block contains the information needed to connect to this filter. The Audio Renderer is the default audio rendering filter for DirectShow; to use the DSound Audio Renderer filter instead, you must insert it into the filter graph before rendering the media file.

The filter's property sheet contains the following:
Tab | Property | Values
Audio Input pin (rendered) | Preferred Media Types | Lists the major type, subtype, and format
Audio Renderer | wFormatTag | Waveform-audio format type. There are many compression algorithms with registered format tags. You can find a complete list of format tags in the Mmreg.h header file.
nChannels | Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.
nSamplePerSec | Rate, in samples per second (hertz), at which each channel should play or record. If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplesPerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, you must compute this member according to the manufacturer's format specification.
nAvgBytesPerSec | Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, nAvgBytesPerSec should equal the product of nSamplesPerSec and nBlockAlign. For non-PCM formats, you must compute this member according to the manufacturer's format specification. Playback and record software can estimate buffer sizes by using the nAvgBytesPerSec member.
nBlockAlign Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM, nBlockAlign should equal the product of nChannels and wBitsPerSample divided by 8 (bits per byte). For non-PCM formats, you must compute this member according to the manufacturer's format specification.

Playback and record software must process a multiple of nBlockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

Rate | This value represents the rate of audio playback, where 1.0 is the authored speed. This value is a multiplier; a value of 2.0 is twice the authored speed and 0.5 is half.


DV Muxer

The DV Muxer filter multiplexes compressed DV video with compressed DV audio.

The DV Muxer filter accepts the following input media types:

From the video input pin:
MEDIATYPE_Video
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: VIDEOINFO

From the audio input pin:
MEDIATYPE_Audio
MEDIASUBTYPE_wave
FORMAT: WAVEFORMATEX/NULL

The DV Muxer filter sends the following output media type:

From the video output pin:
MEDIATYPE_Interleaved(iavs)
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: DVINFO

To see a diagram of how to use the DV Muxer filter with the DV Video Encoder filter, see DV Video Encoder.


DV Splitter

The DV Splitter filter passes a DV stream to a downstream filter (DV Video Decoder and converts DV audio to PCM audio.

The DV Splitter filter accepts the following input media type:
MEDIATYPE_Interleaved(iavs)
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: DVINFO

The DV Splitter filter outputs the following output media types:

From the video output pin:
MEDIATYPE_Video
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: VIDEOINFO

From the audio output pin:
MEDIATYPE_Audio
MEDIASUBTYPE_wave
FORMAT: WAVEFORMATEX

To see a diagram of how to use the DV Splitter filter with the DV Video Decoder filter, see DV Video Decoder.


DV Video Decoder

The DV Video Decoder filter decodes a DV stream to uncompressed video.

The DV Video Decoder filter accepts the following input media type:
MEDIATYPE_Video
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: VIDEOINFO

The DV Video Decoder filter outputs the following output media type:
MEDIATYPE_Interleaved
MEDIASUBTYPE_RGB/YUYV/and other RGB and FOURCC subtypes
FORMAT: VIDEOINFO

The following illustration gives an example of how to use DV Video Decoder and DV Splitter filters.

Example of how to use DV Video Decoder and DV Splitter filters


DV Video Encoder

The DV Video Encoder filter encodes uncompressed video into a compressed DV stream.

The DV Video Encoder filter accepts the following input media type:
MEDIATYPE_Video
MEDIASUBTYPE_RGB/YUYV/and other RGB and FOURCC subtypes
FORMAT: VIDEOINFO

The DV Video Encoder filter outputs the following output media type:
MEDIATYPE_Interleaved
MEDIASUBTYPE_dvsd/dvhd/dvsl
FORMAT: VIDEOINFO

The following illustration gives an example of how to use DV Video Encoder and DV Muxer filters.

Example of how to use DV Video Encoder and DV Muxer filters


DVD Navigator

The DVD Navigator filter is the source filter for a DVD-Video playback filter graph. It opens all necessary files in a DVD-Video volume, navigates through the linear DVD-Video .vob files, and parses the resulting MPEG-2 program stream, splitting the stream into three (video, audio, subpicture) output pins.

The DVD Navigator filter also implements the IDvdControl and IDvdInfo interfaces that enable a DVD playback application to control DVD-Video playback.


File Source (Async)

The File Source (async) filter is a generic asynchronous source filter that works with any source file whose media major type is stream. This includes AVI, MOV, MPEG, and WAV files. It requires the downstream filter to be a parser, such as the MPEG-1 Stream Splitter, the AVI Splitter, or the QuickTime Movie Parser.


File Source (URL)

The File Source (URL) filter is a generic asynchronous source filter that works with any source file that can be identified by a Uniform Resource Locator (URL) and whose media major type is stream. This includes AVI, MOV, MPEG, and WAV files. It requires the downstream filter to be a parser, such as the MPEG-1 Stream Splitter, the AVI Splitter, or the QuickTime Movie Parser.


File Stream Renderer

The File Stream Renderer filter renders streams with the major media type MEDIATYPE_File. The filter hooks up to output pins of type MEDIATYPE_File and renders a separate filename when the pin is rendered. The filename is contained in the pFormat field of the media type.


File Writer

The File Writer filter writes a stream of bits to disk. The output format matches the input format. The AVI MUX filter is currently the only filter to which the File Writer can connect, so it writes all data to the specified file in audio-video interleaved (AVI) format. You can create a new output file or specify an existing file; if the file already exists, it will be completely overwritten with the new data.

The time stamps on samples delivered to the file writer are byte offsets in the file. The input pin exposes the COM IStream interface and supports a subset of the interface. This enables the upstream filter to write data when the graph is stopped.


Full Screen Renderer

The Full Screen Renderer filter is a Mode X rendering filter that occupies the entire desktop when it displays video.

Full-screen rendering is enabled from the filter graph manager, which automatically switches between the filter graph's video renderer and the Full Screen Renderer when required; you need not include the Full Screen Renderer in the filter graph beforehand.

The filter's property sheet contains the following:
Tab | Property | Values
Quality | Frames played | Total frames in the video stream
Frames dropped in renderer | Number of frames dropped during playback
Average frame rate achieved | Average frames per second displayed during playback
Jitter (std dev frame time) (mSec) | Standard deviation frame rate, in milliseconds
Average sync offset (mSec) | Average synchronization offset, in milliseconds
Std dev sync offset (mSec) | Standard deviation synchronization offset, in milliseconds
Input | Preferred Media Types | Lists the major type, subtype, and format


Internal Script Command Renderer

The Internal Script Command Renderer filter accepts data in with a major media type of MEDIATYPE_Text or MEDIATYPE_ScriptCommand, and, when it is time to render a particular piece of data, files an EC_OLE_EVENT event with the text or command as the parameters.


Indeo 4.3 Video Compression

The Indeo® 4.3 Video Compression filter compresses video data into the Indeo 4.3 format. This is typically used when writing out a video file for playback in, for example, a capture filter graph.

For more information about Intel Indeo Video, see the Intel Web site at http://developer.intel.com/ial/indeo external link.


Indeo 4.3 Video Decompression

The Indeo® 4.3 Video Decompression filter will decompress Indeo 4.3, 4.2, and 4.1 videos. This filter can be used during playback of Indeo 4.0 video files.

For more information about Intel Indeo Video, see the Intel Web site at: http://developer.intel.com/ial/indeo external link


Indeo 5.0 Audio Decompression

The Indeo® 5.0 Audio Decompression filter decompresses Indeo 5.0 audio. This filter can be used during playback of Indeo 5.0 audio files.

For more information about Intel Indeo Audio, see the Intel Web site at http://developer.intel.com/ial/indeo external link.


Indeo 5.0 Video Compression

The Indeo® 5.0 Video Compression filter compresses video data using the Indeo 5.0 algorithm. This is typically used in a video editing filter graph.

For more information about Intel Indeo Video, see the Intel Web site at http://developer.intel.com/ial/indeo external link.


Indeo 5.0 Video Decompression

The Indeo® 5.0 Video Decompression filter decompresses video data using the Indeo 5.0 algorithm. This filter can be used during playback of Indeo 5.0 video files.


Indeo 5.0 Video Progressive Download Sources

Indeo® Progressive Download video files can be played as they download. The Indeo Video 5.0 Progressive Download Sources filter enables you to play these files. Lower resolution and lower-frame-rate video can be viewed almost immediately, while the display of the Progressive Download file continuously improves in both quality and frame. Indeo Audio Software works with the Indeo Video 5.0 Progressive Download Sources filter.

For more information about Intel Indeo Video, see the Intel Web site at http://developer.intel.com/ial/indeo external link.


Line 21 Decoder

The Line 21 Decoder filter takes Line 21 data (closed captions) and decodes it to produce a bitmap of media type MEDIATYPE_VIDEO. The output can then be rendered through a video renderer or mixed in a video mixer, such as the Overlay Mixer.

The Line 21 input data to the filter can be either of two forms: byte-pair data that comes on Line 21 of a video frame or feed, or DVD Line 21 data. For every group of pictures (GOP) in the DVD video stream, there can be a user data packet that has that particular GOP's header information and Line 21 data.

The Line 21 Decoder filter supports the IAMLine21Decoder and IBaseFilter interfaces externally, and the IAMovieSetup interface internally.


Lyric Parser

The Lyric Parser filter parses closed captioning information from simple text files. Also see SAMI (CC) Parser and the Multi-File Parser.

The Lyric Parser filter file format is as shown in the following example:

;LYRICS
0           Here's some text at the beginning
1000        This shows up after one second
5000        And this after four more seconds
10000       The end.


MIDI Parser

The MIDI Parser filter parses MIDI data from the File Source (Async) and File Source (URL) filters. The MIDI Renderer filter can render data from this filter.


DirectShow Animated Header -- MIDI Renderer DirectShow Animated Header -- MIDI Renderer * Microsoft DirectShow SDK
  * Previous Topic: MIDI Parser
  * Next Topic: MPEG Audio Decoder

MIDI Renderer

The MIDI Renderer filter renders MIDI data from the MIDI Parser filter.


MPEG Audio Decoder

The MPEG Audio Decoder filter decompresses MPEG-1 audio data. You usually connect it to the audio output of the MPEG-1 Stream Splitter filter. The MPEG Audio Decoder filter produces an audio stream suitable for input to an audio rendering filter or intervening audio transform filter.


MPEG Video Decoder

The MPEG Video Decoder filter decompresses MPEG-1 video data. Usually, its input comes from the MPEG-1 Stream Splitter filter and its output goes to a video rendering filter or an intervening video transform filter.


MPEG-1 Stream Splitter

The MPEG-1 Stream Splitter filter splits MPEG-1 data into separate audio and video streams. The upstream filter must be the File Source (Async) filter, File Source (URL) filter, or a compatible third-party asynchronous source filter. Its output is compressed video and audio data; you can connect the output to suitable decompressors, such as the MPEG Video Decoder filter and the MPEG Audio Decoder filter.


Multi-File Parser

The Multi-File Parser filter parses a simple file format that enables multiple actual file names to be specified as though they were one file. This assists you in combining video and text for closed captioning. Also see SAMI (CC) Parser and Lyric Parser.

Multi-File Parser files have the format shown in the following example:

   ;MULTI
   http://server/share/video.mpg
   http://server/share/captions.smi


Overlay Mixer

The Overlay Mixer filter provides video port playback support. The filter negotiates the parameters that control the video port with an upstream proxy filter that controls the video port driver. It then renders the video on the screen. It can also mix the video content with closed captions on a second pin, and can be extended to an arbitrary number of pins to add subpicture data and other video components.


QuickTime Decompressor

The QuickTime Decompressor filter decompresses files using the Apple® QuickTime® file format. This is typically used during play back of QuickTime files.


QuickTime Movie Parser

The QuickTime Movie Parser filter splits Apple® QuickTime® data into audio and video streams. The input pin connects to a source filter such as the File Source (Async) filter or the File Source (URL) filter. The Parser uses the Video For Windows (VFW) decompressor to decompress QuickTime files. If the Video for Windows compressor does not support the compression method, it cannot render the data. The filter creates one output pin for the video stream and one output pin for the audio stream.


SAMI (CC) Parser

The SAMI Closed-Caption Parser filter parses closed captioning information from SAMI-formatted files. Also see Lyric Parser.

The SAMI (Synchronized Accessible Media Interchange) interchange format is based on SGML/HTML. Every SAMI document should start with a <SAMI> tag and end with a </SAMI>tag. The document's class name is "Synchronized Accessible Media Interchange" and its file extension is .smi or .sami. At its most basic level, SAMI can be used as an intermediate interchange format for encoding closed captions in the Line-21 for NTSC, MPEG for DVDs, and IFE-ITV formats, and other similar formats.

The following is a sample SAMI document:

<SAMI>
<HEAD>
    <Title>President John F. Kennedy Speech</Title>
    <SAMIParam><!--
        Copyright="(C)Copyright 1997, Microsoft Corporation"
        Media="JF Kennedy.wav", none
        Length=73000
        CaptionMetrics=scaleable
        CaptionLineLength=180
        CaptionFontSize=12
        CaptionTextLines=3-->
      </SAMIParam>

    <STYLE TYPE="text/css"><!--
        P {margin-left: 29pt; margin-right: 29pt; font-size: 12pt;
        text-align: left; font-family: tahoma, arial, sans-serif;
        font-weight: normal; color: white; background-color: black;}

        TABLE {Width: "248pt" ;}

        .ENUSCC {Name: "English Captions"; lang: en-US-CC;}

        #Source {margin-bottom: -15pt; background-color: silver;
            color: black; vertical-align: normal; font-size: 12pt;
            font-family: tahoma, arial, sans-serif;
            font-weight: normal;}

        #Youth {color: greenyellow; font-size: 18pt;}

        #BigPrint-1 {color: yellow; font-size: 24pt;}-->
    </STYLE>
</HEAD>

<BODY><TABLE>

    <SYNC Start=0>
        <P Class=ENUSCC ID=Source>Pres. John F. Kennedy
    <SYNC Start=10>
        <P Class=ENUSCC>Let the word go forth,
            from this time and place to friend and foe
            alike that the torch
    <SYNC Start=8800>
        <P Class=ENUSCC>has been passed to a new generations of Americans,
            born in this century, tempered by war,
    <SYNC Start=19500>
        <P Class=ENUSCC>disciplined by a hard and bitter peace,
            proud of our ancient heritage, and unwilling to witness
    <SYNC Start=28000>
        <P Class=ENUSCC>or permit the slow undoing of those human rights
             to which this nation has always
    <SYNC Start=38000>
        <P Class=ENUSCC>been committed and to which we are
            committed today at home and around the world.
    <SYNC Start=46000>
        <P Class=ENUSCC>Let every nation know,
            whether it wishes us well or ill,
            that we shall pay any price, bare any burden,
    <SYNC Start=61000>
        <P Class=ENUSCC>meet any hardship, support any friend,
            oppose any foe, to ensure the survival and
            success of liberty.
    <SYNC Start=73000>
        <P Class=ENUSCC ID=Source>End of:
        <P Class=ENUSCC>President John F. Kennedy Speech
</TABLE></BODY>
</SAMI>


Smart Tee Filter

The Smart Tee filter has one input pin and two output pins (capture and preview). It should be connected to the output of a capture filter that only has a capture pin, not a preview pin. It will always provide the capture frame out of the first pin (capture pin) and it will also send the frame out of the second output pin (preview pin) if doing so will not hurt capture performance. Thus, the capture pin has high priority and always has data coming out of it, but the preview pin is lower priority and will only have data coming out of it if the system has the free cycles to provide a preview. Use this filter to preview while capturing on devices where you normally can only do one at a time.

See ICaptureGraphBuilder::RenderStream for additional information.


TrueMotion 2.0 Decompressor

The TrueMotion Decompressor filter decompresses TrueMotion video. This filter will be used during playback of TrueMotion video files.


TV Audio

The TV Audio filter provides control of television audio decoding, stereo or monoaural selection, and secondary audio program (SAP) selection.

This filter is available through the Windows 98 and Windows NT 5.


TV Tuner

The TV Tuner filter selects an analog broadcast or cable channel to be viewed. The single output stream is a hardware path for analog baseband video. This output should be an input to the Analog Video Crossbar filter. The input pins include an input for cable and an antenna input.

The TV Tuner filter exposes the IAMTVTuner interface, which is used for channel selection.

This filter is available through the Windows 98 and Windows NT 5.


VFW Video Capture

The Video Capture filter is installed with the DirectShow run time. If you have video capture hardware that uses Video For Windows, this filter is available in the Filter Graph Editor when you choose Insert Filters from the Graph menu, under the Video Capture Sources.

Unlike ordinary DirectShow filters, special category filters, such as Video Capture Source filters, can work with more than one device. When DirectShow is installed, it will look for devices installed on your computer that work with the special category filter and list the options in that category. For example, in the Video Capture Source filter category, DirectShow will list all the video capture cards installed on the system. You then need to choose which device to use.

The Video for Windows Video Capture filter has two output pins called Capture and Preview.

The filter supports the IAMVfwCaptureDialogs interface.

The capture output pin supports the IAMStreamConfig, IAMVideoCompression, and IAMDroppedFrames interfaces.


VGA 16 Color Ditherer

The VGA 16 Color Ditherer filter converts from an RGB color type to a 4-bit color display. You can use this filter to convert to the color space used by video rendering filter, such as from the AVI Decompressor filter to the Full Screen Renderer filter.


Video Renderer

The Video Renderer filter is a generic video renderer that you can connect to any video transform filter that produces decompressed video data. This filter has its own plug-in distributor in the filter graph manager, which enables applications to set and retrieve properties on the filter by calling the corresponding interface methods on the filter graph manager. Most other DirectShow™ filters are not visible to applications in this manner.

The Video Renderer filter uses DirectX® methods, if the video card supports them. Full-screen rendering is enabled from the filter graph manager, which automatically switches between the Video Renderer and the Full Screen Renderer when appropriate; you need not include the Full Screen Renderer in the filter graph beforehand.


WAVE Parser

The WAVE Parser filter parses WAV-format audio data. The upstream filter must be the File Source (Async) filter, File Source (URL) filter, or a compatible third-party asynchronous source filter that contains WAV audio data. The output stream is uncompressed audio data, which you can connect directly to an audio rendering filter or to an intervening audio transform filter.


WDM Video Capture

The Video Capture filter is installed with the DirectShow run time. If you have video capture hardware that uses WDM (Windows Driver Model) and you have Windows 98 or Windows NT 5 installed, this filter is available in the Filter Graph Editor when you choose Insert Filters from the Graph menu, under the Video Capture Source category.

Unlike ordinary DirectShow filters, special category filters, such as Video Capture Source filters, can work with more than one device. When DirectShow is installed, it will look for devices installed on your computer that work with the special category filter and list the options in that category. For example, in the Video Capture Source filter category, DirectShow will list all the video capture cards installed on the system. You then need to choose which device to use.

The WDM Video Capture filter supports the interfaces and property sets of the WDM capture drivers. It exposes the IAMAnalogVideoDecoder, IAMVideoProcAmp and IAMCameraControl interfaces to applications. Depending on the underlying hardware, the filter exposes one or more output pins that output compressed video, uncompressed video, timecode, and closed captioning data. The output pins expose the IAMStreamControl interface, and in the case of compressed video, the IAMVideoCompression interface as well.


DirectShow Samples

This article provides the descriptions of the Microsoft® DirectShow™ samples that are part of the DirectShow Software Development Kit (SDK). These samples demonstrate how to write DirectShow filters and applications that use them.

Microsoft® DirectShow™ provides filters and samples as part of the DirectShow Software Development Kit (SDK). A filter is supplied as binary code only. Samples include source code. Some samples are filters and some are applications. Some of the sample filters are registered and appear in the Filter Graph Editor when you choose Insert Filters from the Graph menu. Other sample filters must be built and registered before they will appear in the Filter Graph Editor.

The sample paths in this topic refer to the default sample directories created when you install the DirectX Media SDK.

The following sections describe the purpose and functionality of each sample filter or sample application.

Source Filters

  • Async Sample (Asynchronous Reader Filter)
  • Ball Sample (Bouncing Ball Filter)
  • Synth Sample (Audio Synthesizer Filter)
  • VidCap Sample (Video Capture Filter)

Transform Filters

  • Contrast Sample (Video Contrast Filter)
  • EzRGB24 Sample (Image Effect Filter)
  • Gargle Sample (Gargle Filter)
  • Inftee Sample (Infinite-Pin Tee Filter)
  • MPGAudio Sample (MPEG Audio Decoder Filter)
  • MPGVideo Sample (MPEG Video Decoder Filter)
  • Nullip Sample (Null In Place Filter)
  • Nullnull Sample (Minimal Null Filter)
  • Vcrctrl Sample (VCR Control Filter)

Renderer Filters

  • Dump Sample (Dump Filter)
  • SampVid Sample (Video Renderer Filter)
  • Scope Sample (Oscilloscope Filter)
  • TextOut Sample (Text Display Filter)

Cutlist Sample Applications

  • CLText Sample (Text Cutlist Application)
  • Simplecl Sample (Cutlist Application)

C/C++-based Sample Applications

  • AMCap Sample (DirectShow Capture Application)
  • CPlay Sample (C/COM-based Media Player Application)
  • Dvdsampl Sample (DVD Player Application)
  • InWindow Sample (Window Playback Application)
  • IPlay Sample (Indeo Player Application)
  • MFCPlay Sample (C++/COM-based Media Player Application)
  • MPEGProp Sample (MPEG Property Page Display Application)
  • PlayFile Sample (Simple Playback Application)
  • ShowStrm Sample (Multimedia Streaming Application)
  • VidClip Sample (Video Editing Application)

Visual Basic-based Sample Applications

  • Visual Basic-Based ActiveX Player
  • Visual Basic-Based Filter Graph Builder
  • Visual Basic-Based Filter Graph Player
  • Visual Basic-Based Player

Miscellaneous Samples

  • PID Sample (Plug-In Distributor Application)
  • SampIOS Sample (IOStream Helper Library)

Additional Sample Information

  • Structure of Comments in Sample Source Code
  • Build Information

Sample Locations

The following table shows the directory location of each sample, assuming the default installation directory.
Sample | Directory location
AMCap Sample (DirectShow Capture Application) | DXMedia\Samples\Ds\Capture\
Async Sample (Asynchronous Reader Filter) | DXMedia\Samples\Ds\Async\
Ball Sample (Bouncing Ball Filter) | DXMedia\Samples\Ds\Ball\
CLText Sample (Text Cutlist Application) | DXMedia\Samples\Ds\Cutlist\Cltext
Contrast Sample (Video Contrast Filter) | DXMedia\Samples\Ds\Contrast\
CPlay Sample (C/COM-based Media Player Application) | DXMedia\Samples\Ds\Player\Cplay\
Dump Sample (Dump Filter) | DXMedia\Samples\Ds\Dump\
Dvdsampl Sample (DVD Player Application) | DXMedia\Samples\Ds\Dvdsampl\
EzRGB24 Sample (Image Effect Filter) | DXMedia\Samples\Ds\Ezrgb24\
Gargle Sample (Gargle Filter) | DXMedia\Samples\Ds\Gargle\
Inftee Sample (Infinite-Pin Tee Filter) | DXMedia\Samples\Ds\Inftee\
InWindow Sample (Window Playback Application) | DXMedia\Samples\Ds\Player\Inwindow\
IPlay Sample (Indeo Player Application) | DXMedia\Samples\Ds\Iplay\
MFCPlay Sample (C++/COM-based Media Player Application) | DXMedia\Samples\Ds\Player\Mfcplay\
MPGAudio Sample (MPEG Audio Decoder Filter) | DXMedia\Samples\Ds\Mpgaudio\
MPGVideo Sample (MPEG Video Decoder Filter) | DXMedia\Samples\Ds\Mpgvideo\
MPEGProp Sample (MPEG Property Page Display Application) | DXMedia\Samples\Ds\Player\Mpegprop\
Nullip Sample (Null In Place Filter) | DXMedia\Samples\Ds\Nullip\
Nullnull Sample (Minimal Null Filter) | DXMedia\Samples\Ds\Nullnull\
PID Sample (Plug-In Distributor Application) | DXMedia\Samples\Ds\pids\Iamovie\
PlayFile Sample (Simple Playback Application) | DXMedia\Samples\Ds\Player\Playfile\
SampIOS Sample (IOStream Helper Library) | DXMedia\Samples\Ds\Iostream\
SampVid Sample (Video Renderer Filter) | DXMedia\Samples\Ds\Sampvid\
Scope Sample (Oscilloscope Filter) | DXMedia\Samples\Ds\Scope\
ShowStrm Sample (Multimedia Streaming Application) | DXMedia\Samples\Ds\Showstrm\
Simplecl Sample (Cutlist Application) | DXMedia\Samples\Ds\Cutlist\Simplecl
Synth Sample (Audio Synthesizer Filter) | DXMedia\Samples\Ds\Synth\
TextOut Sample (Text Display Filter) | DXMedia\Samples\Ds\Textout\
Vcrctrl Sample (VCR Control Filter) | DXMedia\Samples\Ds\Vcrctrl\
VidCap Sample (Video Capture Filter) | DXMedia\Samples\Ds\Vidcap\
VidClip Sample (Video Editing Application) | DXMedia\Samples\Ds\Vidclip\
Visual Basic-Based ActiveX Player | DXMedia\Samples\Ds\Vb\Ocx\
Visual Basic-Based Filter Graph Builder | DXMedia\Samples\Ds\Vb\Builder\
Visual Basic-Based Filter Graph Player | DXMedia\Samples\Ds\Vb\Vbdemo\
Visual Basic-Based Player | DXMedia\Samples\Ds\Vb\Player\


Structure of Comments in Sample Source Code

The source code for each sample generally includes a standard introduction in one of the source files. This introduction consists of a block of comments in one of the source files describing what the sample illustrates, what base classes it implements, and so on. To find the introduction to the sample, go to the .cpp file whose name matches the sample. (For samples written in C, the file name ends in .c instead.) The following template shows this introduction with standard headings illustrating the elements that might be included.

// What this sample illustrates
    [brief series of 1-line descriptions]
//
// Summary
    [paragraph on what's in the sample, what it does]
//
// Demonstration instructions
    [how to bring it up, for example under GraphEdt, and make it run]
//
// Implementation
    [introduction to the code, how it all works together]
//
// Known problems ("features not illustrated by this sample"):
    [optional]
//
// Files
    [file names and a half-line description of each]
//
// Base classes used (refer to the docs for a diagram of what they inherit):
    [list of base classes directly inherited from (summary of all files)]


Source Filters

This article details sample source filters. By definition, each of these source filter samples provides at least one output pin. (That is part of what makes them source filters as opposed to other kinds of filters.)

Contents of this article:

  • Async Sample (Asynchronous Reader Filter)
  • Ball Sample (Bouncing Ball Filter)
  • Synth Sample (Audio Synthesizer Filter)
  • VidCap Sample (Video Capture Filter)

Async Sample (Asynchronous Reader Filter)

The asynchronous reader sample filter, Async, shows how to implement "progressive download" in the DirectShow environment. Async implements the IAsyncReader interface, which is perhaps the most important aspect of asynchronous processing. It also implements the IFileSourceFilter interface and defines some helper classes to create filters that conform to the IAsyncReader interface.

The Memfile.exe application uses part of the Async sample code. This program reads a file into memory at a given rate (in kilobytes per second) and plays that file as it comes in.

This filter is not installed in the DirectShow run time and is not included in the list of DirectShow filters in the Filter Graph Editor. To use this filter, you must build and register it.

Sample Locations

Ball Sample (Bouncing Ball Filter)

The bouncing ball sample source filter, Ball, illustrates format negotiation. Ball also illustrates the use of the source filter base classes CSource and CSourceStream.

The code in Fball.h and Fball.cpp manages the filter interfaces. Those two files contain approximately the minimum code required for a source filter. The Ball.h and Ball.cpp files contain the code that bounces the ball.

This filter has a single output pin, which provides a video stream that shows a ball bouncing around in the frame. The Ball filter also accepts quality-management requests from the downstream graph, which illustrates a simple quality-management strategy. This filter implements the IQualityControl interface for that purpose.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Synth Sample (Audio Synthesizer Filter)

The audio synthesizer sample filter, Synth, demonstrates usage of the CSource and CSourceStream classes in an environment that derives its source from audio. You can use the Synth filter as a source filter to synthesize audio waveforms such as sine waveforms, square waveforms, sawtooth waveforms, and swept frequency waveforms.

The Synth source filter enables the user to set the waveform, frequency, number of channels, and other properties. The user can set these properties through the property page. To set either the upper or lower endpoint of the swept frequency range, hold down SHIFT while adjusting the frequency slider. The property page enables only the controls that affect the audio format — for example, channels, bits per sample, and sampling frequency — while the filter is in a stopped state.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

VidCap Sample (Video Capture Filter)

The VidCap sample video capture filter shows you how to handle special category filters, how to implement the COM interfaces for video capture, and how to implement miscellaneous other requirements for video capture.

The VidCap sample filter is not installed with the DirectShow run time. You must install it by calling Regsvr32.exe for VidCap.ax. The sample video capture filter is not part of the run time, but is part of the SDK.

A video capture filter with the same capability as VidCap is installed with the DirectShow run time and can be seen in the Filter Graph Editor when you choose Insert Filters from the Graph menu, under the Video Capture Sources category. The VidCap sample is included so that you can view the source code for a video capture filter and see how to write capture filters.

Unlike ordinary DirectShow filters, special category filters, such as Video Capture Source filters, can work with more than one device.

Sample Locations


Transform Filters

This article details sample transform filters (sometimes called effects). The sample transform filters include an audio effect, some video effects, some MPEG codecs, a VCR controller, and various "null" (pass-through) filters.

Contents of this article:

  • Contrast Sample (Video Contrast Filter)
  • EzRGB24 Sample (Image Effect Filter)
  • Gargle Sample (Gargle Filter)
  • Inftee Sample (Infinite-Pin Tee Filter)
  • MPGAudio Sample (MPEG Audio Decoder Filter)
  • MPGVideo Sample (MPEG Video Decoder Filter)
  • Nullip Sample (Null In Place Filter)
  • Nullnull Sample (Minimal Null Filter)
  • Vcrctrl Sample (VCR Control Filter)

Contrast Sample (Video Contrast Filter)

The video contrast sample filter, Contrast, illustrates how to define and implement a simple custom interface within the structure provided by the DirectShow™ base classes. This filter demonstrates how to use the CTransformFilter class to implement a simple effect filter.

The Contrast filter also provides a good example of the flexibility of the filter graph architecture. This flexibility is demonstrated when the filter is used in conjunction with a tee filter to produce "before and after" (side-by-side original and modified) video streams.

The Contrast filter is a simple transform filter that adjusts the contrast of the video stream that is passed through it. It provides a custom interface for adjusting the contrast. The Contrast filter also uses the CBasePropertyPage class to provide a property page for applications that do not provide a user interface.

Note The Contrast filter adjusts the contrast by using a trick with palettes. The color palette of an image effectively determines how the image is interpreted. By changing the palette, the filter can change the contrast without changing the image pixels themselves.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

EzRGB24 Sample (Image Effect Filter)

The RGB 24 image effect filter, EzRGB24, is a sample of an image processing filter. This shows usage of a number of DirectShow classes and interfaces, including CTransformFilter, CPersistStream, CBasePropertyPage, and ISpecifyPropertyPages.

This filter's purpose is to provide fast and single stream effects. The EzRGB24 filter also shows how to add image processing effects using DirectShow. You can use this filter as a component of an DirectShow video editor. Effects with fast execution were selected to help demonstrate the power of DirectShow in enabling real-time effects — the idea was to show something that could not have been built by using Microsoft Video for Windows®.

This filter performs a number of individual video effects. These include red, green, blue, darken, XOR, blur, gray, and emboss image-processing effects.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Gargle Sample (Gargle Filter)

The audio processing filter, Gargle, illustrates how to create a simple sound effect. More sophisticated effects such as echo, flanging, band-pass filtering, and other effects can be created in a way similar to that demonstrated by the Gargle filter. This sample demonstrates the CTransInPlaceFilter, CPersistStream, and CBasePropertyPage classes. It also shows use of the ASSERT, DbgBreak, DbgLog, and DbgBreakPoint debug macros.

The Gargle filter modulates the waveform passing through it by multiplying the waveform by another waveform that is mathematically generated within the filter. The modulating waveform is, by default, a triangular wave. The property sheet also offers the alternative of a square wave. You can set the frequency of the modulating wave through the filter's property sheet. At low frequencies (near 1 Hz), the sound grows and diminishes. At medium frequencies (5 to 15 Hz), the sound has a tremolo quality, which is why it is referred to as gargling. At higher frequencies (100 Hz and up), the filter generates extra frequencies in the original sound. If a 500 hertz (Hz) sound is played at 100 Hz, then it produces additional frequencies of 400 Hz, 600 Hz, 200 Hz, 800 Hz, and so on.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations


Inftee Sample (Infinite-Pin Tee Filter)

The Inftee sample infinite-pin tee filter has multiple output pins and passes through type enumerators from source filters. The filter uses the CAutoLock, CBaseFilter, CBaseInputPin, CBaseOutputPin, CCritSec, and COutputQueue base classes.

Inftee has one input pin and a variable number of output pins, typically two. It accepts data samples through the IMemInputPin transport, which it implements. All data samples sent to the filter are delivered down all paths simultaneously, therefore teeing the input into multiple separate output streams. The data samples are not type-specific, so the input, for example, can be text lyrics, video images, or audio buffers.

When considering two output pins, the tee filter sends the same data down both of the pins; therefore, the pins must have negotiated the same media type during connection. The infinite-pin tee filter handles this negotiation so that the input pin and both output pins converge when using the same media type. If a suitable media type cannot be found, then the connection is rejected.

The filter always uses the suggested allocator; the filter that provides the data suggests the allocator. The data arriving at the input pin is not copied before it is sent to the output pins. The filter also ensures that the data is delivered to the downstream filters, to guarantee that both outputs receive timely service. In particular, if one of the outputs can block in the COutputQueue::Receive member function, then the tee spins off a thread to deliver the sample. If there were no thread to deliver the sample, then the thread that delivers the sample to the tee input pin might pass the data to a downstream filter; at that point, it might block, keeping data from the other downstream filter for long periods of time.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

MPGAudio Sample (MPEG Audio Decoder Filter)

The sample MPEG audio codec, MPGAudio, provides a prototype for an MPEG audio decoder. It uses the CTransformFilter class.

As supplied, this framework just consumes the passed-in audio frames. That is, audio frames do not produce any output from this framework. You would need to expand the framework with code specific to the outputs desired.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

MPGVideo Sample (MPEG Video Decoder Filter)

The sample MPEG video codec, MPGVideo, provides a prototype for an MPEG video decoder. It uses the CTransformFilter class. The MPGVideo filter also shows the processing of quality-management messages.

As supplied, this framework just consumes the passed-in video frames. That is, video frames do not produce any output from this framework. You would need to expand the framework with code specific to the outputs desired.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Nullip Sample (Null In Place Filter)

The null in-place sample filter, Nullip, is an example of a transform-inplace filter. It illustrates how a transform filter can behave in a relatively transparent manner. Nullip is a simple filter that passes all data from its input pin to its output pin. No transformations are performed on the data.

The Nullip filter provides an example of using the CTransInPlaceInputPin class. It shows how to use the CAutoLock class to automatically release critical sections. Other classes used include CTransInPlaceFilter, CBasePropertyPage, CMediaType, and CTransInPlaceOutputPin. It also enables a user to select the media types that it can pass through itself. This filter has one input pin, one output pin, and performs its transform in place (without copying the data) in the push thread. In other words, the CTransInPlaceFilter::Receive method is called with a buffer, which it transforms and delivers to the next filter downstream. The Receive method is then blocked until that filter returns; it subsequently returns to its own calling member function.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Nullnull Sample (Minimal Null Filter)

The minimal null sample filter, Nullnull, illustrates a minimal filter. It does not support the media type selection that Nullip does. The Nullnull filter uses the CTransInPlaceFilter class.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Vcrctrl Sample (VCR Control Filter)

The VCR control sample filter, Vcrctrl, is a simple implementation of the external device control interfaces that DirectShow provides. Vcrctrl provides basic transport control and SMPTE timecode-reading capabilities for certain Betacam and SVHS videocassette recorders with RS-422 or RS-232 serial interfaces (see source code for specific machine types supported).

This sample is not intended to be a frame-accurate, system-ready implementation ready for professional applications. It is designed to show basic device control filter structure, and therefore does not implement several of the more sophisticated features of the interfaces, such as edit event control. Frame-accurate control is best achieved by writing a low-level, kernel-mode communications driver underneath the filter. Developers should refer to the Driver Development Kit (DDK) for the appropriate platform.

Using the Sample

With this sample, you can control a VCR through property pages. You should keep in mind the following:

  • The sample automatically links the transport to the graph's Run, Pause, and Stop methods. You can unlink the transport on the General property page by removing the selection from the Link to Graph check box. This is a persistent property, so if you save the graph the transport will remain unlinked.
  • The filter automatically detects the presence of a compatible VCR on COM2. If it can't find a VCR or if the port is in use, it switches to simulation mode. You can select the port to use on the General property page.
  • The timecode pin can connect either to the text renderer or the timecode renderer (Tcrender.ax), which accepts the media type MEDIATYPE_AuxData/MEDIASUBTYPE_Timecode.
  • The main property page shows the available video and audio inputs, although you can't select them. The hardware does not support this feature, and it was implemented to show physical pin property enumeration.
  • The device communications class (CDevCom, specified in Cdevcom.h and Cdevcom.cpp) is thread-safe and handles SMPTE timecodes. On some VCRs, timecode detection is not supported, so timecode values might not be accurate.

This sample contains the following files:

  • Vcrutil.h, .cpp — implementation of the device control interfaces
  • Fvcrctrl.h, .cpp — the filter implementation
  • Cdevcom.h, .cpp — the communications object that handles device-specific protocols and the serial port interface
  • Ctimecod.h, .cpp — the SMPTE timecode support
  • Trprop.h, .cpp — the transport properties
  • Vcrprop.h, .cpp — the general properties
  • Vcrprop.rc — the dialog resources
  • Vcrctrl.def — the module definition file
  • Vcruids.h — the CLSIDs used by the filter

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations


Renderer Filters

This article describes sample renderer filters. The filters render video output, audio output, text output, and raw file output.

Contents of this article:

  • Dump Sample (Dump Filter)
  • SampVid Sample (Video Renderer Filter)
  • Scope Sample (Oscilloscope Filter)
  • TextOut Sample (Text Display Filter)

Dump Sample (Dump Filter)

The sample file dump filter, Dump, illustrates the use of the base filter class CBaseFilter and the rendered input pin class CRenderedInputPin. This sample also uses the IFileSinkFilter interface. The Dump filter demonstrates how to override the Receive method of the rendered input pin class to process actual media samples. The filter is also a "renderer" of its input stream. (That is, this filter doesn't fit the traditional definition of rendering audibly or visibly, although it is a "renderer filter.") The Dump filter delivers the EC_COMPLETE notification to the filter graph when it receives a call to CDumpInputPin::EndOfStream on its input pin.

This filter is a useful debugging tool. For example, you can verify, bit by bit, the results of a transform filter. You can build a graph manually by using the Filter Graph Editor, and connect the Dump filter to the output of a transform filter or any other output pin. You can also connect a tee filter and put the Dump filter on one leg of the tee filter and the typical output on another leg to monitor the results in a real-time scenario.

The Dump filter has a single input pin, which is dumped to a file. The filter prompts the user for a file name when it is instantiated and closes the file when it is freed.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

SampVid Sample (Video Renderer Filter)

The sample video renderer filter, SampVid, displays video inside a window. SampVid demonstrates the implementation of a special memory allocator, the CImageAllocator class, which uses buffers based on the Microsoft Win32® DIBSECTION structure. This sample shows use of the CBaseVideoRenderer class, which handles all the seeking, synchronization and quality management necessary for video renderers. Other base classes used include, among others:

  • CBaseControlVideo
  • CBaseControlWindow
  • CDrawImage
  • CImageAllocator
  • CImageDisplay
  • CImagePalette
  • CMediaType

This sample also shows the use of the property page interface IQualProp, which addresses quality management.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

Scope Sample (Oscilloscope Filter)

The oscilloscope sample filter, Scope, illustrates the use of the base filter class CBaseFilter and the base input pin class CBaseInputPin.

Other than the video renderer sample, Scope is the only sample filter that has a constantly active window.

Note The Scope window is implemented as a dialog box, not as an actual window.

Developers creating control panels to alter filter parameters in real time might want to use a technique like this rather than property pages.

The Scope filter demonstrates setting up a separate thread to process data. In this case, the data is just copied to a separate buffer on the IMemInputPin::Receive method, and is then drawn on the Scope window on the separate thread.

The filter demonstrates how to apply DirectShow™ outside the rather narrow domain of multimedia playback. DirectShow has wide application in the diverse areas of:

  • Process control
  • Factory automation
  • Image processing and analysis
  • Virtual lab instrumentation

All of these areas have semi real-time requirements, but additionally emphasize user interaction and the display of gauges, monitors, signal generators, alarms, and other forms of graphical display of analyzed results.

The Scope filter also enables you to monitor audio output to determine if you are clipping, so you can adjust the gain.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

TextOut Sample (Text Display Filter)

The sample text renderer filter, TextOut, serves as an example of a renderer filter that is for a user-defined type. It can render text data found in an AVI file or other source. The TextOut filter demonstrates the use of the CBaseRenderer class, which handles all the synchronization and seeking although it doesn't have any quality management implementation. To get quality management, derive your classes from CBaseVideoRenderer instead. This sample also uses the CBaseWindow class.

This renderer creates and uses a simple window to display each piece of text it receives.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations


Cutlist Sample Applications

This article describes the cutlist sample applications included with the DirectShow SDK.

Contents of this article:

  • CLText Sample (Text Cutlist Application)
  • Simplecl Sample (Cutlist Application)

CLText Sample (Text Cutlist Application)

The text cutlist (CLText) sample reads a list of up to 150 cutlist elements (video or audio clips) from a text file and plays them.

This sample demonstrates how to use the ICutListGraphBuilder, IStandardCutList, and IFileClip interfaces.

Sample Locations

Simplecl Sample (Cutlist Application)

The simple cutlist (Simplecl) sample demonstrates how to use cutlists. Simplecl provides a File Open dialog box from which the user can choose a file to add to a cutlist. For each file, the user specifies a starting position and ending position for the clip. For every AVI file specified, the sample tries to add the first video stream and the first audio stream to its respective cutlist. The user must add at least two files, and then can run the filter graph and see the clips played sequentially.

This sample demonstrates how to use the ICutListGraphBuilder, IStandardCutList, and IFileClip interfaces.

Sample Locations


C/C++-based Sample Applications

This article details sample applications that are written in C++ or C. The sample applications implement media players or perform other application-related functions. The differences between them are mainly the different programming languages, API, or frameworks used.

Some of these samples use the Microsoft® Foundation Classes (MFC).

Contents of this article:

  • AMCap Sample (DirectShow Capture Application)
  • CPlay Sample (C/COM-based Media Player Application)
  • Dvdsampl Sample (DVD Player Application)
  • InWindow Sample (Window Playback Application)
  • IPlay Sample (Indeo Player Application)
  • MFCPlay Sample (C++/COM-based Media Player Application)
  • MPEGProp Sample (MPEG Property Page Display Application)
  • PlayFile Sample (Simple Playback Application)
  • ShowStrm Sample (Multimedia Streaming Application)
  • VidClip Sample (Video Editing Application)

AMCap Sample (DirectShow Capture Application)

The DirectShow capture sample, AMCap, demonstrates the basics of capturing audio and video from a hardware source to a specified output file or to a preview window.

To see a list of the hardware capture devices on your system, choose the Devices menu; DirectShow uses the ICreateDevEnum interface to create the list of devices that appears. After choosing a device, choose the Set Frame Rate command from the Capture menu and set the desired frame rate; the default value is 30 frames per second. To set an output file for your capture, pick the Set Capture File command from the File menu. DirectShow uses the File Writer filter to associate your specified file with the capture session.

If you want to turn audio capturing on or off, choose the Capture Audio command from the Capture menu. To turn capture previewing on or off, choose the Preview command from the Options menu. When you are ready to begin capturing, choose the Start Capture command from the Capture menu. If you want to save your captured data to a file other than the specified output file, choose the Save Captured Video As command from the File menu.

Note: Before you begin capturing for the first time, choose Allocate File Space from the File menu to preallocate the capture file. Preallocating the file improves capture performance. AMCap calls AllocCapFile to preallocate the capture file.

Sample Locations

CPlay Sample (C/COM-based Media Player Application)

This C/COM-based media player sample, CPlay, is a simple application that renders multimedia files using DirectShow™ from within the C language. The CPlay sample does not use Microsoft Foundation Classes (MFC). If you want to see a sample that uses MFC, see MFCPlay Sample (C++/COM-based Media Player Application). The CPlay sample shows how to utilize the DirectShow components without using the base classes provided with DirectShow. The sample creates a filter graph (by calling CoCreateInstance to get a pointer to the IGraphBuilder interface), and requests the filter graph to render a file. The filter graph is then controlled by using the IMediaControl interface. This sample also uses the IMediaEvent and IMediaPosition interfaces.

CPlay is a minimal application that implements the following menu commands: Open, Play, Pause, Stop, and Exit on the File menu, and About on the Help menu.

Sample Locations

Dvdsampl Sample (DVD Player Application)

The DirectShow DVD sample player, Dvdsampl, is a simple application that plays DVD Video content. It uses the IDvdGraphBuilder interface to build a DVD filter graph and to obtain interface pointers for IAMLine21Decoder, IDvdControl, and IDvdInfo. It uses those interfaces and enables you to turn closed captioning on and off, play in full screen mode, and display and select from DVD menus.

Note: Your system must include DVD playback hardware to run this sample.

Sample Locations

InWindow Sample (Window Playback Application)

The InWindow application is a simple sample that shows minimal code required to play back a media file into a specific window. It builds on the PlayFile sample. Like PlayFile, it provides a file Open dialog box that enables you to open media files. It also uses IGraphBuilder, IMediaEventEx, and IMediaControl as PlayFile does. InWindow expands on the PlayFile functionality by calling IVideoWindow::put_Owner, IVideoWindow::put_WindowStyle, and IVideoWindow::SetWindowPosition to direct playback into the main application window.

Sample Locations

IPlay Sample (Indeo Player Application)

The Intel® Indeo player sample, IPlay, uses DirectShow to render multimedia files and demonstrates the Indeo Video Interactive application programming interfaces (API). IPlay demonstrates how to access the advanced features of the Indeo Video Interactive (IVI) codec. It is a simple application written in C++ using Microsoft Foundation Classes (MFC). If the file is an IVI format file, it enables controls for the IVI advanced features. The advanced features include local decoding, a decoding time limit, and the ability to adjust brightness, saturation, and contrast.

The Ax_spec.h file defines the interfaces of the IVI codec. The CIPlayDoc::OnOpenDocument function demonstrates how to determine if a file is an IVI format file. The CIPlayDoc::Getxxx and CIPlayDoc::Setxxx functions demonstrate how to get and set the IVI playback parameters for the advanced features.

This sample uses the following interfaces:

  • IGraphBuilder — to create a filter graph and render a file
  • IFilterGraph — to enumerate the filters in the filter graph
  • IMediaControl — to play/pause/stop the playback
  • IMediaEvent — to be notified of EC_COMPLETE (playback complete) and other events
  • IMediaPosition — to set the time that the media stream begins
  • IVideoWindow — to set the window size/caption/position
  • IBasicVideo — to get the native window size.

IPlay also implements and uses the IIndeoDecode interface (not part of DirectShow).

Sample Locations

MFCPlay Sample (C++/COM-based Media Player Application)

The C++/COM-based media player sample, MFCPlay, is a simple application that renders multimedia files using DirectShow from within C++ and Microsoft Foundation Classes (MFC). It demonstrates how to connect the DirectShow components by using the interfaces provided with DirectShow and MFC. The sample creates a filter graph (by calling CoCreateInstance to get a pointer to the IGraphBuilder interface), and requests the filter graph to render a file. The filter graph is then controlled by using the IMediaControl interface. This sample also uses the IMediaEvent and IMediaPosition interfaces.

The MFCPlay application implements the following menu commands: Open, Play, Pause, Stop, and Exit on the File menu, and About on the Help menu.

Sample Locations

MPEGProp Sample (MPEG Property Page Display Application)

The MPEGProp sample application demonstrates how to display a filter's property page.

When you open MPEGProp, choose Open from the File menu and select an MPEG media file from the standard Open dialog box. After you select an appropriate file, MPEGProp calls CoCreateInstance to create a new filter graph and renders the chosen source file. MPEGProp calls IFilterGraph::FindFilterByName to locate the MPEG Video Codec filter, and then calls OleCreatePropertyFrame with the codec pointer to display the filter's property page.

Sample Locations

PlayFile Sample (Simple Playback Application)

The PlayFile application is a simple sample that shows minimal code required to play back a media file. It provides a file Open dialog box that enables you to open files including file types such as AVI, MPEG, MOV, and QT. PlayFile uses the IGraphBuilder::RenderFile method to render the filter graph for the chosen media file, IMediaEventEx to handle signaling of events, IMediaControl::Run to play the resulting filter graph, and IMediaControl::Stop to stop playback. The sample calls IVideoWindow to control whether the playback window is visible. Video follows the default behavior and plays back in a separate window rather than in the main application window.

See InWindow Sample (Window Playback Application) for a sample that builds on PlayFile and plays back video into the main application window.

Sample Locations

ShowStrm Sample (Multimedia Streaming Application)

The ShowStrm application demonstrates how to use a Microsoft® DirectDraw® surface to blit a multimedia stream. It is a console application that sends a movie out to the surface when invoked from the command line with the following syntax:

SHOWSTRM Name_of_Movie

For example, to play Angry.avi, you could use the command:

C:\>SHOWSTRM angry.avi

Sample Locations

VidClip Sample (Video Editing Application)

The VidClip application demonstrates how to use the multimedia streaming interfaces and how to support rudimentary video editing. The VidClip sample reads from multiple streams and writes to a single stream. For more information on the multimedia streaming interfaces, see List of Multimedia Streaming Interfaces.

On the Video menu in the VidClip application, choose the Add Clip command to add clips to your list; you can include start and stop times, if you want to add only a portion of a clip. Choose the Edit Clip command to edit existing clips in the list, and the Delete Clip command to delete clips. The Make a Movie command combines the clips into one stream.

On the File menu, choose the Settings command to set the height, width, depth, and compression for the stream data. Choose the Save command to save the settings to a file in your project.

Sample Locations


Visual Basic-based Sample Applications

This article describes the Microsoft® Visual Basic® version 5.0 samples in the Microsoft DirectShow™ Software Development Kit (SDK).

Contents of this article:

  • Visual Basic-Based ActiveX Player
  • Visual Basic-Based Filter Graph Builder
  • Visual Basic-Based Filter Graph Player
  • Visual Basic-Based Player

Visual Basic-Based ActiveX Player

This ActiveX sample, Ocxvb01, demonstrates an application that uses the ActiveMovie Control. It has a form that contains menus and controls to demonstrate the access of various properties of the video control. See Using the ActiveMovie Control in Visual Basic for a detailed description of this sample.

The sample has a menu command that enables you to create the control by opening a video file, and to use Run, Pause, and Stop commands to programmatically control the ActiveMovie Control. All of the ActiveMovie Control Panel features, such as selection controls, position controls, and the trackbar control, can be made visible selectively, and enabled or disabled from menu commands in the sample application. Other properties, such as the rate and current position, can also be changed from the application, and you can set the image in the video control to various sizes such as half, default, double, and full-screen.

Sample Locations

Visual Basic-Based Filter Graph Builder

The filter graph builder sample, Builder, demonstrates how a Visual Basic-based application uses the collection interfaces that the filter graph manager exposes to build and connect a custom filter graph. The collection interfaces are composed of the following interfaces.

  • IAMCollection
  • IRegFilterInfo
  • IFilterInfo
  • IPinInfo
  • IMediaTypeInfo

These interfaces appear as objects in the ActiveMovie Control type library in the Visual Basic development environment and enable the registry to be searched, filters to be added, and pins to be connected, among other things. See Constructing Filter Graphs Using Visual Basic for a detailed description of this sample.

The Builder sample presents a form that enables the user to see a list of filters in the registry and add filters to the filter graph. It also enables the user to examine the names and properties of pins on the filter, the media types on the pins, and to connect the pins. The sample has an additional sample routine, accessed by a menu, that automatically builds a filter graph. The filter graph is built using the collection interface objects, to better demonstrate the more typical use of these objects in a Visual Basic-based application. The sample also enables you run the constructed filter graph.

Sample Locations

Visual Basic-Based Filter Graph Player

The filter graph player, VBDemo, demonstrates how to use the DirectShow Visual Basic objects that control the playback of video and that adjust properties of various components. See Controlling Filter Graphs Using Visual Basic for a detailed description of this sample.

The VBDemo sample enables you to open a video file. Use the Play, Pause, and Stop buttons to control the video. It positions the video window as a child window of the main form and displays the movie's length and elapsed time. It also enables you to set the start position and rate. Use two sliders to adjust the audio renderer's volume and balance.

Sample Locations

Visual Basic-Based Player

The sample player, Player, is a short Visual Basic-based program that demonstrates the minimum requirements for playing back a DirectShow media file without using the ActiveMovie Control. It uses the same DirectShow object library as the VBDemo sample, but provides only three buttons (Open, Play, and Stop) and a slider for indicating position.

Sample Locations


PID Sample (Plug-In Distributor Application)

The IAMovie sample shows the implementation of the IAMovie interface for a plug-in distributor (PID). A PID is used to extend the filter graph manager. The filter graph manager distributes the actions of interface methods to the appropriate filters. This distribution enables applications to have a single point of control to perform the basic operations.

In the IAMovie sample, the PID exposes the IAMovie interface and implements it by calling the enumerator of the filter graph manager, finding which filters expose the interface (see EnumFiltersByInterface), and communicating directly with those filters. PIDs are supplied for the standard control interfaces. Independent software vendors (ISVs) can replace these supplied PIDs and add others.

See Plug-in Distributors for information on plug-in distributors.

Sample Locations

SampIOS Sample (IOStream Helper Library)

The IOStream helper library provides text output of the IBaseFilter interface and other DirectShow™ objects. This sample code is provided as a header file (SampIOS.h) and a source file (SampIOS.cpp) that can be built into a library (SampIOS.lib). You can use the library functions in your DirectShow filters and applications. The functions are designed to help retrieve information in text format about the objects in the filter graph. The text output is intended to aid in debugging.

SampIOS.h declares debug output functions that you can call from C. For example, DumpFilterInfo sends information on the given filter interface. See the header file (SampIOS.h) for the syntax of each call. The DumpXxx functions require the cout output stream to be valid in the environment in which you are working, as they implicitly output to cout. The DumpXxx functions are included in the following list.

  • DumpFilterInfo
  • DumpPinInfo
  • DumpAllPins
  • DumpAllFilters
  • DumpFilterGraph

Extensions to the C++ IOStream library are included, so you can write code like the following to dump information to cout.

   cout << piFilterGraph << endl;

The C++ callable functions declared by SampIOS.h include the following abilities to provide output to an ostream. (The standard C++ ostream class provides the basic capability for sequential and random-access output.) See the header file (SampIOS.h) for the syntax of each call.

  • Provide output of a wide string.
  • Build and provide output of a textual version of a GUID.
  • Provide output of filter information.
  • Provide output of filter information for all filters left in an enumerator.
  • Provide output of filter and connection details.
  • Provide output of pin details (including connection information).
  • Provide output of pin details (including connection information) for all pins left in the enumerator.
  • Provide output of the pin information for all pins on the supplied filter.

Sample Locations


Build Information

To use some of the filters and applications supplied as DirectShow samples, you need to build them into executable or DLL (.ax) files. To build, you need various tools. And after you build a filter, you need to register it with a unique identifier to make it appear in the Filter Graph Editor. This section contains the following topics:

  • Tools for Building the Samples
  • Building the Samples
  • Setting Up the Registry

Tools for Building the Samples

The tools you need to build the filters and applications supplied as DirectShow samples are included in the following list. This list contains both required and optional tools.

  • Microsoft® DirectShow™ Software Development Kit (required).
  • ANSI-compatible C/C++ compiler, such as Microsoft Visual C++® version 5.x or later (required).
  • Microsoft Win32® headers and libraries (required).
  • Microsoft NMAKE (supplied with Visual C++), if you want to use the supplied makefiles (optional).
  • Microsoft Foundation Classes (MFC), if you want to build the two sample applications that use MFC (optional).

Building the Samples

All samples in the SDK have been provided with a makefile that is compatible with NMAKE. In some cases, a Visual C++ project makefile is also included.

To build the samples using the standard makefiles, you must first set up your build tools (for example, Microsoft Visual C++), the Win32 headers and libraries, and the DirectShow SDK. The DirectShow SDK makefiles expect to locate the standard Windows® and Win32 include files and libraries on the INCLUDE and LIB paths. The makefiles handle all DirectShow-specific files on a project-by-project basis.

The makefiles provided for each individual sample use ActiveX.mak, which is provided with the DirectShow SDK. If you are using ActiveX.mak to build for any machine, other than the default x86, you must set the CPU environment variable to indicate which kind of machine. The allowable values for the CPU are i386, ALPHA, and PPC.

Performance Note If you copy any sample makefile to create a new dynamic-link library (DLL) (including filters and PIDs) make sure that you change the base address to avoid collisions with other DLLs. A collision of DLL load address results in one of the DLLs having to be relocated during load time, thereby increasing the duration of load time. In the sample makefiles, the base address is set in DLL_BASE, which is used in ActiveX.mak. Do not let ActiveX.mak use the default value for DLL_BASE, as this will almost certainly cause collisions.

A makefile that builds all the samples is provided in the Samples directory.

Setting Up the Registry

The source directory for each sample contains a registry file (.reg). Sample filters are registered by default. You can re-register all filters in the sample by opening this file. The samples also use the preferred self-registration capabilities provided by the IAMovieSetup interface. See Register DirectShow Objects for more information.

Caution: If you modify a registry file and then use it to update your registry, you will affect the sample filter that is already installed on your system. For example, if you modify Ball.reg, you might lose access to the Ball filter (Ball.ax) in the Filter Graph Editor.


Multimedia Streaming

This section describes the multimedia streaming interfaces, which automatically negotiate the transfer and conversion of data from a source to an application. It includes reference entries for the multimedia streaming data types, interfaces, and interface methods. It also includes sample code and a description of multimedia streaming component objects along with their CLSIDs and the interfaces they support.

About the Multimedia Streaming Architecture

List of Multimedia Streaming Interfaces

Multimedia Streaming Reference

Multimedia Streaming Component Objects

Multimedia Streaming Sample Code


About the Multimedia Streaming Architecture

This article describes the architecture of multimedia streaming and how software developers typically use streams in their tools and applications. It also covers the advantages of streaming as a base for data transfer and how to address multimedia programming issues, such as data transfer, performance optimization, and time stamping in streaming applications. Programmers who want to use multimedia streaming should be familiar with COM programming concepts.

Contents of this article:

  • Advantages of Multimedia Streaming
  • Object Hierarchy
  • Creating Multimedia Stream Objects and Stream Samples
  • Using Multimedia Streams in Applications
  • Sharing Data Between Streams

Advantages of Multimedia Streaming

When developers use multimedia streaming in their applications, it greatly reduces the amount of format-specific programming needed. Typically, an application that must obtain media data from a file or hardware source must know everything about the data format and the hardware device. The application must handle the connection, transfer of data, any necessary data conversion, and the actual data rendering or file storage. Because each format and device is slightly different, this process is often complex and cumbersome. Multimedia streaming, on the other hand, automatically negotiates the transfer and conversion of data from the source to the application. The streaming interfaces provide a uniform and predictable method of data access and control, which makes it easy for an application to play back the data, regardless of its original source or format.

The following steps show how to implement streaming, from hardware device to rendered playback.

  1. A source of video data, such as Microsoft® DirectShow™, exposes the streaming interfaces.
  2. The application developer uses the multimedia streaming interfaces to handle data format conversion.
  3. The application developer uses the Microsoft DirectDraw® interfaces to render the resulting data.

The specification for multimedia streams comprises several interfaces; each interface includes methods that control a certain aspect of the streaming process or handle a certain type of data. See List of Multimedia Streaming Interfaces for additional information.

Object Hierarchy

The following diagram shows the basic object hierarchy used in multimedia streaming.

There are three basic object types defined in the multimedia streaming architecture:

  1. A multimedia stream, which supports the IMultiMediaStream interface.
  2. Media streams support the IMediaStream interface and are data specific. Every multimedia stream contains one or more of these media streams.
  3. Stream samples support the IStreamSample interface and are created by a media stream. These objects represent a basic unit of work for the stream.

Creating Multimedia Stream Objects and Stream Samples

Objects that support the IMultiMediaStream interface are the basic containers for multimedia data streams. The IMultiMediaStream interface includes methods that enumerate the object's data streams; these streams are typically video and audio data, but can include data of any format, such as closed-captioning, plain text, or SMTPE timecode. The IMultiMediaStream interface is a generic container, however; developers can create other versions of the interface that support specific data formats. Objects that implement the IAMMultiMediaStream interface, for example, can enumerate and control streams of any DirectShow data format. Because individual data streams are format specific, they support at least two different interfaces: one generic and one data-specific. Every stream supports the IMediaStream interface, which provides methods to retrieve its format and a pointer to the stream itself. The IDirectDrawMediaStream interface, on the other hand, has methods that deal specifically with rendering video data. Any interface derived from IMultiMediaStream also supports the creation of stream samples, the basic units of streaming data.

A multimedia sample is a reference to an object containing the media data. For a video image, this is a DirectDraw surface. The sample's exact content varies, depending on the type of media (sound, text, and so on). Because a sample is only a reference to the data object, any number of stream samples can refer to the same object. The IStreamSample interface provides methods that get and set a sample's characteristics, such as its start and stop time, status, and stream association. The IStreamSample::Update method refreshes the sample's data in the case of readable streams. For writable streams, it will write the sample's data to the stream. Typically, you use the Update method in a loop that renders, transfers, or stores streaming data. See Use Multimedia Streaming in DirectShow Applications for a practical example of this method in source code.

Using Multimedia Streams in Applications

The multimedia streaming interfaces greatly simplify the process of manipulating multimedia data by removing the dependency on specific characteristics of the hardware or software source and providing support for all Microsoft DirectX® media formats. Streams abstract the data to a very high level; applications can even move data from one stream to another without knowing anything about the data's format.

Perform the following steps to create a multimedia stream:

  1. Create the multimedia stream. The method of creation and initialization of the stream is architecture specific. DirectShow supports the IAMMultiMediaStream interface, which is used to initialize the stream. Other in-process server implementations of IMultiMediaStream will be created and initialized using different mechanisms.
  2. After the multimedia stream object is initialized, the application will use QueryInterface to retrieve the IMultiMediaStream interface for the object. Use this interface to determine the stream's properties and enumerate the streams themselves. You can retrieve a specific stream by calling the IMultiMediaStream::GetMediaStream method with a specific purpose ID. MSPID_PrimaryVideo and MSPID_PrimaryAudio, which represent the primary video and audio streams, are the most commonly used purpose IDs.
  3. Call IUnknown::QueryInterface for an interface specific to the stream's media type. If you want to render a video stream, for example, retrieve its IDirectDrawMediaStream interface. Media-specific interfaces define additional methods necessary for taking full advantage of a format's capabilities.
  4. Create one or more samples from the stream data. Every media stream supports the IMediaStream::CreateSharedSample method for sample creation. The resulting sample supports the IStreamSample interface, which provides control over the sample and its characteristics. Typically, the media stream supports a format-specific method of sample creation that is more powerful than the aforementioned IStreamSample methods. IDirectDrawMediaStream, for example, can create samples attached to a desired DirectDraw surface and clipping rectangle. In some situations, however, you must handle data without knowing about its data format, such as when constructing a cutlist. If you want to stream data independent of its format, use the IMediaStream::CreateSharedSample method to create the data samples.
  5. After creating all desired stream samples, start the stream by calling the IMultiMediaStream::SetState method and pass in the STREAMSTATE_RUN flag as its parameter.
  6. Call IStreamSample::Update to update the stream sample. When the IStreamSample::Update method exits, you can access the sample's data. The code sample in Use Multimedia Streaming in DirectShow Applications uses the IStreamSample::Update method in a loop to render a stream of video data. If you want a trigger a specific event or function call when the update returns, pass the appropriate pointers to the IStreamSample::Update method.

For more information on the multimedia streaming interfaces, see .

Sharing Data Between Streams

Processing multimedia data typically requires a great deal of system resources; therefore, you should avoid copying data whenever possible. The streaming architecture supports shared stream samples, a mechanism that moves data from one stream to another without copying it. This buffer enables the efficient transportation of data between two streams even if the destination stream doesn't specifically support the underlying data format.

For example, assume that you have a multimedia stream with three data streams: video and audio, and URL data time-stamped to match the video content. You want to write an application that adds a copyright notice on every video frame and writes the data to another stream for storage, but your application doesn't understand any data formats except the video stream. For the video stream, you create a sample attached to the desired DirectDraw surface. You can then create an output stream by calling either the IDirectDrawMediaStream::CreateSample method with that pointer to the same surface, or IMediaStream::CreateSharedSample. In both cases, the input and output streams share the DirectDraw surface. Because you understand the video format, you can access this surface as needed.

To retrieve the other source stream pointers (audio and URL), enumerate the source container stream and grab pointers to the nonvideo streams. Each of these source streams has an associated output stream in the output stream container. Retrieve these output pointers by calling the IMultiMediaStream::GetMediaStream method on the output container with each of the source stream pointers. The following steps describe this process.

  1. Call IMultiMediaStream::EnumMediaStreams to retrieve a pointer to a source stream. Make sure that it's not the video stream, because your application already understands its format.
  2. Call IMultiMediaStream::GetMediaStream on the output container stream with the pointer from step 1. This returns a pointer to the desired output stream.
  3. Call AllocateSample on the source stream.
  4. Call CreateSharedSample on the output stream.
  5. Call Update on the source stream to read the data.
  6. Call Update on the output stream to write the data.

Repeat these steps for each stream whose format you don't support. When both samples finish updating, the output stream has all data from the source stream and you are done.


List of Multimedia Streaming Interfaces

Multimedia streaming comprises a number of interfaces; this article provides a brief description of each interface. For additional information about multimedia streaming, see About the Multimedia Streaming Architecture.

Contents of this article:

  • Base Multimedia Streaming Interfaces
  • DirectDraw Streaming Interfaces
  • Audio Streaming Interfaces
  • DirectShow Multimedia Streaming Interfaces

Base Multimedia Streaming Interfaces

The DirectX Media SDK includes reference documentation for the multimedia streaming interfaces; the interfaces and their methods provide a programatic way of access multimedia streams. However using a base interface to access a specific type of data can limit the amount of control you have over the data, so media developers should create derived versions of these interfaces that provide more powerful control over the unique capabilities of their media type.

IMultiMediaStream
This interface defines how to access the highest-level multimedia stream object; this object contains and provides access to other stream objects. IMultiMediaStream has methods that enumerate or retrieve specific streams, as well as checking the stream's total time duration and seeking within the stream.
IMediaStream
This interface defines a generic stream object. Use its methods to retrieve a pointer to the stream, get information about the stream, and create samples from the stream data. You can also create shared stream samples, which multiple streams can access without duplicating the sample's data.
IStreamSample
This interface controls the behavior of a specific stream sample. You can retrieve the stream that created the sample, check the sample's start and end times and completion status, and perform a user-defined function on the sample itself (through the Update method). Typically, the Update method processes the sample data in an appropriate manner, such as rendering video data or playing back audio data.

DirectDraw Streaming Interfaces

If you use Microsoft® DirectDraw-supported video formats in your streams, the following interfaces give you more powerful control over the data than the more generic base interfaces.

IDirectDrawMediaStream
This interface derives from IMediaStream; it sets and retrieves the stream format and the DirectDraw® object associated with the media stream. You can also use this interface to create video samples.
IDirectDrawStreamSample
This interface derives from the IStreamSample interface and enables you to attach video samples to DirectDraw surfaces. Each attached surface includes a clipping rectangle to make rendering easier.

Audio Streaming Interfaces

IAudioMediaStream
The IAudioMediaStream interface controls audio media streams. This interface inherits from the IMediaStream interface and is used to create one or more IAudioStreamSample objects. It is also used to set and retrieve the current format of the stream data.
IAudioStreamSample
The IAudioStreamSample interface retrieves information from the underlying IAudioData data objects.
IMemoryData
The IMemoryData interface contains methods which set and retrieve memory data on audio data objects. Audio data objects provide the underlying data which stream samples access. This interface provides a way to initialize memory buffers and to set actual amounts of audio data in the objects. Additionally, the IMemoryData::GetInfo method can be used to retrieve audio memory data.
IAudioData
The IAudioData interface provides methods which allow applications to set and get the underlying audio data that audio streams will reference. The audio data format is set in the WAVEFORMATEX structure.

DirectShow Multimedia Streaming Interfaces

The following interfaces expose Microsoft DirectShow™ functionality to multimedia stream developers. Application developers should implement only the IAMMultiMediaStream interface in their applications; DirectShow uses the other two interfaces internally.

IAMMultiMediaStream
This interface controls connections between streams and DirectShow filter graphs. It provides methods that instantiate filter graphs, open DirectShow-supported media files, and generate an appropriate filter graph for playback. The CLSID_ActiveMovieMMStream class identifier supports this interface.
IAMMediaStream
This interface is a DirectShow-specific derivation of the IMediaStream interface. It handles the internal negotiation of connections between multimedia streams and DirectShow filter graphs. Application developers should not use or implement this interface.


Multimedia Streaming Reference

This section contains reference entries for all the multimedia streaming interfaces and their methods, including those that DirectShow supports. It also includes a list of multimedia streaming data types that the interfaces use, and a list of error and success codes that the methods return.

IMultiMediaStream Interface

IMediaStream Interface

IStreamSample Interface

IDirectDrawMediaStream Interface

IDirectDrawStreamSample Interface

IAudioMediaStream Interface

IAudioStreamSample Interface

IMemoryData Interface

IAudioData Interface

IAMMultiMediaStream Interface

IAMMediaStream Interface

Multimedia Streaming Data Types

Error and Success Codes for Multimedia Streaming


IMultiMediaStream Interface

The IMultiMediaStream interface provides methods that control a multimedia stream and provide access to its underlying media streams. A multimedia stream is the highest-level streaming object and can contain one or more media streams. While each media stream is media-type specific (audio, video, and so on), multimedia streams are generic across all types because they must provide access to a number of streams that can have different media types. IMultiMediaStream interface methods enable you to enumerate and retrieve pointers to the specific streams; IMediaStream interface methods provide specific control over the media stream behavior.

For sample code which implements the multimedia streaming interfaces see Multimedia Streaming Sample Code.

When to Implement

Implement this interface when you want create containers for a specific type of media stream.

When to Use

Use this interface when your application must enumerate and control a multimedia stream's underlying, type-specific streams.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMultiMediaStream methods | Description
GetInformation | Retrieves the capabilities and stream type of a multimedia stream.
GetMediaStream | Retrieves a media stream that has the specified purpose ID.
EnumMediaStreams | Retrieves a media stream from a multimedia stream by zero-based index.
GetState | Retrieves the multimedia stream's current state.
SetState | Sets the media stream to either a running or stopped state.
GetTime | Retrieves the current time from the multimedia stream's clock, if it has a clock.
GetDuration | Retrieves the media stream's duration.
Seek | Sets the seek location of all derived media streams to the specified time.
GetEndOfStreamEventHandle | Retrieves the handle for the event triggered when the stream completes playback.

IMultiMediaStream::EnumMediaStreams

IMultiMediaStream Interface

Retrieves a media stream from a multimedia stream by zero-based index.

HRESULT EnumMediaStreams(
long Index,
IMediaStream** ppMediaStream )

Parameters
Index
[in] Index of the stream array to check.
ppMediaStream
[out] Address of a pointer to an IMediaStream interface object. On return, it contains a pointer to the stream at the specified index.
Return Values

Returns one of the following values.
Value | Meaning
E_POINTER | The ppMediaStream pointer is invalid.
S_FALSE | Index is out of range; no streams are left to enumerate. When the method returns this value, it also sets ppMediaStream to NULL.
S_OK | Success.

Remarks

You should call this method until it returns S_FALSE, which indicates that the stream enumeration is complete.

IMultiMediaStream::GetDuration

IMultiMediaStream Interface

Returns the media stream's duration.

HRESULT GetDuration(
STREAM_TIME *pDuration
)

Parameters
pDuration
[out] Pointer to a STREAM_TIME value that will contain the media duration.
Return Values

Returns one of the following values.
Value | Meaning
E_POINTER | The value of pDuration is invalid.
MS_E_WRITESTREAM | The media stream is writable and therefore has no duration.
S_FALSE | Stream contains live data or this method couldn't determine the duration. On return, this method sets pDuration to zero.
S_OK | Stream contains recorded media. On return, pDuration contains duration of media.

IMultiMediaStream::GetEndOfStreamEventHandle

IMultiMediaStream Interface

Retrieves the handle for the event triggered when the stream completes playback.

HRESULT GetEndOfStreamEventHandle(
HANDLE* phEOS
)

Parameters
phEOS
[out] Pointer to an event HANDLE returned by the current object when it completes playback. If no HANDLE is associated with the object, this value will be NULL.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

Remarks

The Microsoft® Win32® WaitForSingleObject and WaitForMultipleObjects functions use the retrieved handle to watch for completion of playback.

IMultiMediaStream::GetInformation

IMultiMediaStream Interface

Retrieves the capabilities of a media stream that matches the specified media type.

HRESULT GetInformation(
DWORD *pdwFlags,
STREAM_TYPE *pStreamType
);

Parameters
pwdFlags
[out] Pointer to a value that will contain a combination of one or more of the following flags. Can be NULL.
Value | Meaning
MMSSF_ASYNCHRONOUS | The stream supports asynchronous sample updates. All implementations of IMultiMediaStream will support the asynchronous updates; this flag confirms it.
MMSSF_HASCLOCK | The stream has a clock.
MMSSF_SUPPORTSEEK | The stream supports seeking.
pStreamType
[out] Pointer to a STREAM_TYPE enumeration type that will contain the media type information for the derived media streams. Can be NULL.
Return Values

Returns S_OK if successful.

Remarks

A stream's capabilities include whether it has a clock, if it supports seeking, and whether it supports asynchronous updating.

IMultiMediaStream::GetMediaStream

IMultiMediaStream Interface

Retrieves a media stream that has the specified purpose ID.

HRESULT GetMediaStream(
REFMSPID idPurpose,
IMediaStream **ppMediaStream
);

Parameters
idPurpose
Value that specifies the desired stream.
ppMediaStream
Address of a pointer to an IMediaStream interface that will point to the desired media stream.
Return Values

Returns one of the following values.
Value | Meaning
E_POINTER | The ppMediaStream pointer is invalid.
MS_E_NOSTREAM | No stream has the specified purpose ID.
S_OK | Success.

Remarks

If a stream exists that matches the purpose ID in idPurpose, the ppMediaStream parameter points to the stream and increments its reference count.

MSPID_PrimaryVideo and MSPID_PrimaryAudio, which represent the primary video and audio streams, are the most commonly used purpose IDs.

IMultiMediaStream::GetState

IMultiMediaStream Interface

Retrieves the multimedia stream's current state.

HRESULT GetState(
STREAM_STATE* pCurrentState
)

Parameters
pCurrentState
[out] Pointer to the STREAM_STATE enumerated type that will contain the current multimedia stream's state.
Return Values

Returns S_OK if successful or E_POINTER if pCurrentState is invalid.

IMultiMediaStream::GetTime

IMultiMediaStream Interface

Retrieves the current time from the multimedia stream's clock, if it has a clock.

HRESULT GetTime(
STREAM_TIME* pCurrentTime
)

Parameters
pCurrentTime
[out] Pointer to a STREAM_TIME value that will contain the current time, if the media stream has a clock.
Return Values

Returns one of the following values.
Value | Meaning
E_POINTER | The pCurrentTime pointer is invalid.
S_FALSE | Stream doesn't have a clock; *pCurrentTime is zero.
S_OK | Stream has a clock and the method succeeded; pCurrentTime contains the current time.

Remarks

If the stream doesn't have a clock, this method sets *pCurrentTime to zero and returns S_FALSE. If a stream has a clock, the stream sample times are relative to the stream's clock.

STREAM_TIME is defined as a LONGLONG value.

IMultiMediaStream::Seek

IMultiMediaStream Interface

Sets the seek location of all contained media streams to the specified time.

HRESULT Seek(
STREAM_TIME SeekTime
)

Parameters
SeekTime
[in] STREAM_TIME value that specifies the seek time.
Return Values

Returns one of the following values.
Value | Meaning
E_POINTER | One of the pointers is invalid.
MS_E_NOSEEKING | One or more media streams don't support seeking.
MS_E_WRITESTREAM | The streams are writable and therefore don't support seeking.
S_OK | Success.

Remarks

This method won't work on streams that don't support seeking. Before calling this method, retrieve the stream's capabilities by calling IMultiMediaStream::GetInformation; if the retrieved value includes the MMSSF_SUPPORTSEEK flag, you can call this method.

When seeking a stream that has a clock, the current time can change to an unpredictable value, including a time before the desired seek time. This causes the method to fail.

This method seeks to the specified time in all the media streams derived from the multimedia stream object.

IMultiMediaStream::SetState

IMultiMediaStream Interface

Sets the media stream to either a running or stopped state.

HRESULT SetState(
STREAM_STATE NewState
)

Parameters
NewState
[in] A STREAM_STATE enumeration value that specifies the new media stream state.
Return Values

Returns S_OK.

Remarks

When you set the stream to STREAMSTATE_STOP, this method deletes all data still pending.


IMediaStream Interface

The IMediaStream interface provides access to the characteristics of a media stream, such as the stream's media type and purpose ID. It also has methods that create data samples.

For sample code that implements the multimedia streaming interfaces, see Multimedia Streaming Sample Code.

When to Implement

Implement this interface when you want to add media type-specific functionality to your media stream. This interface is implemented on multimedia stream objects. IMediaStream provides generic sample-creation methods, but you usually want to write a more powerful version of these methods that will take advantage of your media type's specific characteristics.

When to Use

Use this interface when your application needs to access a stream's media type information and create data samples.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMediaStream methods | Description
GetMultiMediaStream | Retrieves a pointer to the multimedia stream that contains the specified media stream.
GetInformation | Retrieves the stream's purpose ID and media type.
SetSameFormat | Sets the media stream the same format as a previous stream.
AllocateSample | Allocates a new stream sample object for the current media stream.
CreateSharedSample | Creates a new stream sample that shares the same backing object as the existing sample.
SendEndOfStream | Forces the current stream to end. If the current stream isn't writable, this method does nothing.

IMediaStream::AllocateSample

IMediaStream Interface

Allocates a new stream sample object for the current media stream.

HRESULT AllocateSample(
DWORD dwFlags,
IStreamSample **ppSample
)

Parameters
dwFlags
[in] Flags. Must be zero.
ppSample
[out] Pointer to the newly created stream sample's IStreamSample interface.
Return Values

Returns one of the following values.
Value | Meaning
E_OUTOFMEMORY | There isn't enough memory available to create a stream sample.
E_POINTER | A parameter is invalid.
S_OK | Success.

Remarks

This method allocates the sample and its associated backing object or buffer. The backing object is either the DirectDraw surface for video or the IAudioData object for audio.

IMediaStream::CreateSharedSample

IMediaStream Interface

Creates a new stream sample that shares the same backing object as the existing sample.

HRESULT CreateSharedSample(
IStreamSample* pExistingSample,
DWORD dwFlags ,
IStreamSample** ppNewSample
)

Parameters
pExistingSample
[in] Pointer to the existing sample.
dwFlags
[in] Reserved for flag data. Must be zero.
ppNewSample
[out] Address of a pointer to an IStreamSample interface that will point to the newly created shared sample.
Return Values

Returns one of the following values.
Value | Meaning
E_OUTOFMEMORY | There isn't enough memory available to create the sample.
E_POINTER | One of the parameters is invalid.
MS_E_INCOMPATIBLE | The existing sample isn't compatible with the specified media stream.
S_OK | Success; ppNewSample points to the newly created sample.

Remarks

This method calls IUnknown::QueryInterface on the existing sample to retrieve the media type-specific information, which it uses to create the shared sample.

IMediaStream::GetInformation

IMediaStream Interface

Retrieves the stream's purpose ID and media type.

HRESULT GetInformation(
MSPID* pPurposeId,
STREAM_TYPE* pType
)

Parameters
pPurposeId
[out] Pointer to an MSPID value that will contain the stream's purpose ID. If this parameter is NULL on entry, the method won't retrieve the purpose ID.
pType
[out] Pointer to a STREAM_TYPE enumerated data type value that will contain the stream's media type. If this parameter is NULL on entry, the method won't retrieve the media type.
Return Values

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.

Remarks

The value retrieved in the pPurposeId parameter will usually be either MSPID_PrimaryVideo, which identifies the primary video stream, or MSPID_PrimaryAudio, which identifies the primary audio stream; however, you can define other values if necessary.

IMediaStream::GetMultiMediaStream

IMediaStream Interface

Retrieves a pointer to the multimedia stream that contains the specified media stream.

HRESULT GetMultiMediaStream(
IMultiMediaStream** ppMultiMediaStream
)

Parameters
ppMultiMediaStream
[out] Address of a pointer to an IMultiMediaStream interface object that will point to the multimedia stream from which the current media stream was created.
Return Values

Returns S_OK if successful or E_POINTER if ppMultiMediaStream is invalid.

Remarks

This method increments the reference count of the retrieved object pointer.

IMediaStream::SendEndOfStream

IMediaStream Interface

Forces the current stream to end. If the current stream isn't writable, this method does nothing.

HRESULT SendEndOfStream(
DWORD dwFlags
)

Parameters
dwFlags
[in] Reserved for flag data. Must be zero.
Return Values

Returns S_OK if successful or MS_E_INCOMPATIBLE if the existing sample isn't compatible with the current media stream.

Remarks

Applications do not call this internal method.

IMediaStream::SetSameFormat

IMediaStream Interface

Sets the media stream the same format as a previous stream.

HRESULT SetSameFormat(
IMediaStream *pStreamThatHasDesiredFormat,
DWORD dwFlags
);

Parameters
pStreamThatHasDesiredFormat
[in] Pointer to a media stream object that has the same format.
dwFlags
[in] Reserved for flag data. Must be zero.
Return Values

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.


IStreamSample Interface

The IStreamSample interface provides control over the behavior of stream samples. You can retrieve the media stream that created the sample, set or retrieve sample start and stop times, check the sample's completion status, and perform a developer-specified function on the sample itself.

When to Implement

Implement this interface when you implement a media stream for a new media type. The interface is exposed on sample objects created by media streams.

When to Use

Use this interface when you want to control data samples created by IMediaStream or its derived interfaces.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IStreamSample methods | Description
GetMediaStream | Retrieves a pointer to the media stream object that created the current sample.
GetSampleTimes | Retrieves the current sample's start and end times.
SetSampleTimes | Sets the current sample's start and end times.
Update | Performs a synchronous or an asynchronous update on the current sample.
CompletionStatus | Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.

IStreamSample::CompletionStatus

IStreamSample Interface

Retrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.

HRESULT CompletionStatus(
DWORD dwFlags,
DWORD dwMilliseconds
)

Parameters
dwFlags
[in] Value that specifies whether to forcibly complete the update. This value is a combination of one or more of the following flags.
Value | Meaning
COMPSTAT_NOUPDATEOK (0x01) | Force the update to complete as soon as possible, even if the sample update isn't yet complete. If the sample is updating and you didn't set the COMPSTAT_WAIT flag, the method returns MS_S_PENDING. If the sample is waiting to be updated, this method removes it from the queue and returns MS_S_NOTUPDATED.
COMPSTAT_WAIT (0x02) | Wait until the sample finishes updating before returning from this method.
COMPSTAT_ABORT (0x04) | Forces the update to complete, even if it's currently updating. This leaves the sample data in an undefined state. Combine this value with the COMPSTAT_WAITFORCOMPLETION flag to ensure that the update canceled.
dwMilliseconds
[in] If the dwFlags parameter is COMPSTAT_WAIT, this value is the number of milliseconds to wait for the update to complete. Specify INFINITE to indicate that you want to wait until the sample updates before this call returns.
Return Values

Returns one of the following values.
Value | Meaning
E_ABORT | The update aborted.
MS_S_ENDOFSTREAM | The sample wasn't updated because it reached the end of the stream.
MS_S_NOUPDATE | The update was forcibly completed; the sample was not updated by the stream.
MS_S_PENDING | An asynchronous update is pending.
S_OK | Success.

IStreamSample::GetMediaStream

IStreamSample Interface

Retrieves a pointer to the media stream object that created the current sample.

HRESULT GetMediaStream(
IMediaStream** ppMediaStream
)

Parameters
ppMediaStream
[in] Address of a pointer to an IMediaStream interface that will point to the media stream that created the current sample.
Return Values

Returns S_OK if successful or E_POINTER if ppMediaStream is invalid.

Remarks

If successful, this method increments the reference count of the media stream specified by ppMediaStream.

IStreamSample::GetSampleTimes

IStreamSample Interface

Retrieves the current sample's start and end times. If the sample is updating, this method returns the times after the update completes.

HRESULT GetSampleTimes(
STREAM_TIME* pStartTime,
STREAM_TIME* pEndTime,
STREAM_TIME* pCurrentTime
)

Parameters
pStartTime
[out] Pointer to a STREAM_TIME value that will contain the sample's start time.
pEndTime
[out] Pointer to a STREAM_TIME value that will contain the sample's end time.
pCurrentTime
[out] Pointer to a STREAM_TIME value that will contain the media stream's current media time.
Return Values

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.

Remarks

For streams that have a clock, the start and end times will be relative to the stream's current time. If the stream doesn't have a clock, the times are media-relative and the current time will be zero.

The pCurrentTime parameter enables you to conveniently track the media stream's current time, so you don't have to call IMultiMediaStream::GetTime. Unlike GetTime, however, this method returns S_OK if the stream doesn't have a clock; GetTime returns S_FALSE. The value assigned to pCurrentTime is the same as the value produced by the following code fragment.

pSample->GetMediaStream(&pMediaStream);
pMediaStream->GetMultiMediaStream(&pMultiMediaStream);
pMediaStream->Release();
pMultiMediaStream->GetTime(&pCurrentTime);
pMultiMediaStream->Release();

IStreamSample::SetSampleTimes

IStreamSample Interface

Sets the current sample's start and end times. You can call this method prior to updating the sample.

HRESULT SetSampleTimes(
const STREAM_TIME* pStartTime,
const STREAM_TIME* pEndTime
)

Parameters
pStartTime
[in] Pointer to a STREAM_TIME value that contains the sample's new start time.
pEndTime
[in] Pointer to a STREAM_TIME value that contains the sample's new end time.
Return Values

Returns S_OK if successful or E_POINTER if one of the parameters is NULL.

Remarks

For streams that have a clock, the times must be relative to the stream's current time. If the stream doesn't have a clock, the times should be relative to the media.

This method only applies to writable streams.

IStreamSample::Update

IStreamSample Interface

Performs a synchronous or an asynchronous update on the current sample.

HRESULT Update(
DWORD dwFlags,
HANDLE hEvent,
PAPCFUNC pfnAPC,
DWORD dwAPCData
)

Parameters
dwFlags
[in] Flag that specifies whether the update is synchronous or asynchronous. The SSUPDATE_ASYNC flag specifies an asynchronous update, which you can set if both hEvent and pfnAPC are NULL. Use SSUPDATE_CONTINUOUS to continuously update the sample until you call the IStreamSample::CompletionStatus method.
hEvent
[in] Handle to an event that this method will trigger when the update is complete.
pfnAPC
[in] Pointer to a Win32 asynchronous procedure call (APC) function that this method will call after it completes the sample update.
dwAPCData
[in] Value that this method passes to the function specified by the pfnAPC parameter.
Return Values

Returns one of the following values.
Value | Meaning
E_ABORT | The update aborted.
E_INVALIDARG | One of the parameters is invalid.
E_POINTER | One of the parameters is invalid.
MS_E_BUSY | This sample already has a pending update.
MS_S_ENDOFSTREAM | Reached the end of the stream; the sample wasn't updated.
MS_S_PENDING | The asynchronous update is pending.
S_OK | Success.

Remarks

This method can be used to perform a synchronous or asynchronous update of a sample. If both hEvent and pfnAPC are NULL then the update will be synchronous unless either of the SSUPDATE_ASYNC or SSUPDATE_CONTINUOUS flags is specified. When a synchronous update returns, the result of the function contains the I/O completion status.

You can't specify values for both hEvent and pfnAPC; the method will fail.

Asynchronous updates might complete before the update returns; in that case, the return value is S_OK. If you specify an event and the update returns S_OK, this method sets the event on return. If you specify an APC function and the update returns S_OK, the APC will not be queued and the function will not be called.

Asynchronous updates that don't complete prior to returning will return a value of MS_S_PENDING.

Applications that create multiple streams must read from each of them to avoid having their data blocked.


IDirectDrawMediaStream Interface

The IDirectDrawMediaStream interface controls media streams that appear on Microsoft DirectDraw® surfaces. To stream to a DirectDraw surface, DirectDraw must support the video stream format.

For sample code that implements the multimedia streaming interfaces see Multimedia Streaming Sample Code.

When to Implement

This interface isn't intended for implementation by application developers. It is exposed on DirectDraw media streams that can be added to a DirectShow multimedia stream.

When to Use

Use this interface when you want to output a video stream to a DirectDraw surface.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDirectDrawMediaStream methods | Description
GetFormat | Retrieves the current media stream's format and, optionally, its desired format.
SetFormat | Sets the current media stream's format. If the stream already has allocated samples and the sample format doesn't match the specified format, this method fails.
GetDirectDraw | Retrieves a pointer to the DirectDraw object used by the current media stream.
SetDirectDraw | Sets the current media stream's DirectDraw object.
CreateSample | Creates a stream sample using the specified DirectDraw surface object.
GetTimePerFrame | Retrieves the average frames per second from a video stream.

IDirectDrawMediaStream::CreateSample

IDirectDrawMediaStream Interface

Creates a stream sample using the specified DirectDraw surface object.

HRESULT CreateSample(
IDirectDrawSurface* pSurface,
const RECT *pRect,
DWORD dwFlags,
IDirectDrawStreamSample** ppSample
)

Parameters
pSurface
[in] Pointer to an existing DirectDraw surface.
pRect
[in] Pointer to the clipping rectangle you want to use with the specified surface. Set this parameter to NULL if you want to use the entire surface.
dwFlags
[in] Flag that specifies whether the render should be progressive. To perform a progressive render, set this value to DDSFF_PROGRESSIVERENDER. If you don't set this flag, sample updates will copy the sample data to the surface.
ppSample
[out] Address of a pointer to an IDirectDrawStreamSample interface that will point to the newly created sample.
Return Values

Returns one of the following values.
Value | Meaning
DDERR_INVALIDPIXELFORMAT | The specified pixel format is incompatible with the stream format.
DDERR_INVALIDRECT | The specified clipping rectangle is invalid.
DDERR_INVALIDSURFACETYPE | The specified surface is incompatible with the stream format.
E_POINTER | One or more of the required parameters is invalid.
MS_E_SAMPLEALLOC | The stream already has allocated samples and the surface doesn't match the sample format.
S_OK | Success.

Remarks

This method creates a sample from the current stream and attaches the sample to this surface.

If the stream doesn't have an allocated surface and the specified surface doesn't match the stream's format, this method calls the IDirectDrawMediaStream::SetFormat method on the stream so the two will match.

To perform a progressive render, create a single sample and repeatedly use that sample for successive frames of video. Video decompressors use this technique to do partial updates to the previous frame.

Note, the pRect parameter should match the format of the stream (see IDirectDrawMediaStream::GetFormat). If the wrong clip rectangle is set or no clip rectangle is set, and the surface size does not match the movie size, the movie may not play. If a primary surface is used it is advisable to use a clipping rectangle because the primary surface size may change if the user changes their display settings.

IDirectDrawMediaStream::GetDirectDraw

IDirectDrawMediaStream Interface

Retrieves a pointer to the DirectDraw object used by the current media stream.

HRESULT GetDirectDraw(
IDirectDraw** ppDirectDraw
)

Parameters
ppDirectDraw
[out] Address of a pointer to an IDirectDraw interface that will contain the current media stream's associated DirectDraw object.
Return Values

Returns S_OK if successful or E_POINTER if the parameter is invalid.

Remarks

If you haven't initialized the stream yet, the retrieved pointer will be NULL and the method will return S_OK. If you have initialized the stream, this method increments the retrieved pointer's reference count.

IDirectDrawMediaStream::GetFormat

IDirectDrawMediaStream Interface

Retrieves the current media stream's format and, optionally, its desired format.

HRESULT GetFormat(
DDSURFACEDESC *pDDSDCurrent,
IDirectDrawPalette **ppDirectDrawPalette,
DDSURFACEDESC *pDDSDDesired,
DWORD* pdwFlags
)

Parameters
pDDSDCurrent
[out] Pointer to a DirectDraw surface description that will contain the current media stream's format.
ppDirectDrawPalette
[out] Address of a pointer to an IDirectDrawPalette interface if one exists.
pDDSDDesired
[out] Pointer to a DirectDraw surface description that will contain the current media stream's desired format.
pdwFlags
[out] Pointer to the flags set in a DDSURFACEDESC structure. Fields of interest include.
Value | Meaning
DDSD_HEIGHT | Indicates that the height member of the structure is valid.
DDSD_WIDTH | Indicates that the width member of the structure is valid.
DDSD_PIXELFORMAT | Indicates that the pixel format member of the structure is valid.
DDSD_CAPS | Indicates that the surface capability member of the structure is valid.
Return Values

Returns one of the following values.
Value | Meaning
DDERR_INVALIDPARAMS | One of the DirectDraw surface parameters is invalid.
E_POINTER | One or more of the required parameters is invalid.
S_OK | Success.

Remarks

After you call this method, you can either conform to the current format or attempt to change the format by calling the IDirectDrawMediaStream::SetFormat method.

All of this method's parameters are optional; set any of them to NULL to indicate that you don't want to retrieve that information.

To perform a progressive render, create a single sample and repeatedly use that sample for successive frames of video. Video decompressors use this technique to do partial updates to the previous frame.

You must initialize the dwSize member of the DDSURFACEDESC structure before calling this method.

The DDSD_CAPS flag will return one of the values listed in the DDSCAPS structure or DDSCAPS_DATAEXCHANGE, which is defined as DDSCAPS_SYSTEMMEMORY|DDSCAPS_VIDEOMEMORY in Ddrawex.h.

IDirectDrawMediaStream::GetTimePerFrame

IDirectDrawMediaStream Interface

Retrieves the average frames per second from a video stream.

HRESULT GetTimePerFrame(
STREAM_TIME *pFrameTime
)

Parameters
pFrameTime
[out] STREAM_TIME value that indicates the average time per frame in 100-nanosecond units.
Return Values

Returns S_OK if successful or E_POINTER if the pointer is invalid.

IDirectDrawMediaStream::SetDirectDraw

IDirectDrawMediaStream Interface

Sets the current media stream's DirectDraw object.

HRESULT SetDirectDraw(
IDirectDraw* pDirectDraw
)

Parameters
pDirectDraw
[in] Address of a pointer to an IDirectDraw interface that contains the media stream's new DirectDraw object.
Return Values

Returns S_OK if successful.

Remarks

This method fails if the current stream already has allocated samples and its DirectDraw object differs from the specified one. It will always succeed if the specified DirectDraw object matches the stream's current object.

If this stream has no allocated samples, you can set pDirectDraw to NULL. This forces the stream to release its reference to the current DirectDraw object.

IDirectDrawMediaStream::SetFormat

IDirectDrawMediaStream Interface

Sets the format of the current media stream.

HRESULT SetFormat(
const DDSURFACEDESC *pDDSurfaceDesc,
IDirectDrawPalette *pDirectDrawPalette
)

Parameters
pDDSurfaceDesc
[in] Pointer to a DirectDraw surface description that contains the new format.
pDirectDrawPalette
[in] Optional parameter that is a pointer to an IDirectDrawPalette interface.
Return Values

Returns one of the following values.
Value | Meaning
S_OK | Success.
DDERR_INVALIDSURFACETYPE | The specified format is incompatible with the current stream.
MS_E_SAMPLEALLOC | Can't change the format because one or more stream samples are already allocated for this stream.

Remarks

If the stream already has allocated samples and the sample format doesn't match the specified format, this method fails. This method always succeeds if the specified format matches the current format.


IDirectDrawStreamSample Interface

The IDirectDrawStreamSample interface provides methods that set and retrieve pointers to the DirectDraw surface associated with the current stream sample.

When to Implement

This interface isn't intended for implementation by application developers. It is exposed by sample objects created by the DirectDraw stream.

When to Use

Use this interface when applications need to set clipping rectangles and retrieve the rendering surface for DirectDraw stream samples.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDirectDrawStreamSample methods | Description
GetSurface | Retrieves pointers to the current sample's DirectDraw surface and associated clipping rectangle.
SetRect | Changes the clipping rectangle for a sample.

IDirectDrawStreamSample::GetSurface

IDirectDrawStreamSample Interface

Retrieves pointers to the current sample's DirectDraw surface and associated clipping rectangle.

HRESULT GetSurface(
IDirectDrawSurface ** ppDirectDrawSurface,
RECT * pRect
);

Parameters
ppDirectDrawSurface
[out] Address of a pointer to an IDirectDrawSurface interface that specifies the sample's new surface. Set this parameter to NULL if you don't want to specify a new surface.
pRect
[out] Pointer to a RECT structure that will contain the current sample's clipping rectangle. Set this parameter to NULL if you don't want to retrieve the clipping rectangle.
Return Values

Returns S_OK if successful.

Remarks

Both parameters are optional. All implementations of this interface must support null values as valid parameters. If you retrieve a surface pointer, this method increments its reference count, so you must release the reference.

IDirectDrawStreamSample::SetRect

IDirectDrawStreamSample Interface

Changes the clipping rectangle for a sample.

HRESULT SetRect (
const RECT * pRect
)

Parameters
pRect
[in] Pointer to a RECT structure that specifies the stream's new clipping rectangle.
Return Values

Returns one of the following values.
Value | Meaning
DDERR_INVALIDPIXELFORMAT | The stream isn't compatible with the pixel format.
DDERR_INVALIDRECT | The specified rectangle is invalid.
DDERR_INVALIDSURFACETYPE | The stream isn't compatible with the surface.
E_POINTER | One of the pointers is invalid.
MS_E_SAMPLEALLOC | The stream format doesn't match the surface and samples are currently allocated to the stream.
S_OK | Success.

Remarks

Both parameters are optional; set either to NULL to avoid changing that value. If the surface format doesn't match the stream format, this method fails.

If the new rectangle's size isn't the same as the current rectangle, a call to this method will fail.


IAudioMediaStream Interface

The IAudioMediaStream interface controls audio media streams by providing methods that set and get the stream's format. This interface inherits from the IMediaStream interface and is used to create one or more IAudioStreamSample objects. You can also use it to set and retrieve the stream data's current format.

This interface is currently defined only for PCM format audio data.

For sample code that implements the audio streaming interfaces, see Multimedia Streaming Sample Code.

When to Implement

Like video, audio is contained in a self-describing container object. Implement this interface when an object needs to control streaming audio.

When to Use

Use this interface when you want to generate audio in your application.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAudioMediaStream methods | Description
GetFormat | Retrieves the stream data's current format.
SetFormat | Sets the format for the stream.
CreateSample | Creates an audio stream sample for use with this stream.

IAudioMediaStream::CreateSample

IAudioMediaStream Interface

Creates an audio stream sample for use with the specified stream.

HRESULT CreateSample(
IAudioData *pAudioData,
DWORD dwFlags,
IAudioStreamSample **ppSample
);

Parameters
pAudioData
[in] Pointer to an IAudioData container. IAudioData objects can be referenced by samples in more than one stream.
dwFlags
[in] Reserved for flag data. Must be zero.
ppSample
[out] Address of a pointer to the new IAudioStreamSample interface.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

Remarks

The pAudioData object defines the data's format.

IAudioMediaStream::GetFormat

IAudioMediaStream Interface

Retrieves the stream data's current format.

HRESULT GetFormat(
WAVEFORMATEX *pWaveFormatCurrent );

Parameters
pWaveFormatCurrent
[out] Pointer to a WAVEFORMATEX structure that contains the stream data's current format.
Return Values

Returns S_OK if successful or E_POINTER if the required parameter is NULL.

Remarks

Currently, DirectShow only supports PCM wave data.

IAudioMediaStream::SetFormat

IAudioMediaStream Interface

Sets the format for the stream.

HRESULT SetFormat(
const WAVEFORMATEX *lpWaveFormat
);

Parameters
lpWaveFormat
[in] Pointer to a WAVEFORMATEX structure that contains stream format information.
Return Values

Returns an HRESULT value, which can include the following values or others not listed.
Value | Meaning
MS_E_INCOMPATIBLE | Format of the IAudioData object is not compatible with stream.
E_POINTER | Null pointer argument.
E_INVALIDARG | Invalid argument.
S_OK | Success.


IAudioStreamSample Interface

The IAudioStreamSample interface retrieves information from the underlying IAudioData data objects.

For sample code that implements the audio streaming interfaces, see Multimedia Streaming Sample Code.

When to Implement

Implement this interface on audio stream sample objects when they need access to an IAudioData object's data .

When to Use

Use this interface when your application needs to access an IAudioData object's data for its audio stream.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAudioStreamSample methods | Description
GetAudioData | Retrieves the address of a pointer to the IAudioData object associated with the sample.

IAudioStreamSample::GetAudioData

IAudioStreamSample Interface

Retrieves the address of a pointer to the IAudioData object associated with the sample.

HRESULT GetAudioData(
IAudioData **ppAudio );

Parameters
ppAudio
[out] Address of a pointer to the IAudioData object.
Return Values

Returns S_OK if successful or E_POINTER if the parameter is NULL.


IMemoryData Interface

The IMemoryData interface contains methods that set and retrieve memory data on audio data objects. Audio data objects provide the underlying data which stream samples access. This interface provides a way to initialize memory buffers and to set actual amounts of audio data in the objects. Additionally, the GetInfo method can be used to retrieve audio memory data.

When to Implement

Implement this interface on underlying audio data objects that audio stream sample objects will access.

When to Use

Typically these methods are called by the IAudioMediaStream or IAudioStreamSample object, rather than by the application.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IMemoryData methods | Description
SetBuffer | Initializes a memory buffer with a pointer to memory and length.
GetInfo | Retrieves information describing an audio data object.
SetActual | Sets the amount of audio data currently in the object, in bytes.

IMemoryData::GetInfo

IMemoryData Interface

Retrieves information describing an audio data object.

HRESULT GetInfo(
DWORD *pdwLength,
BYTE **ppbData,
DWORD *pcbActualData );

Parameters
pdwLength
[out] Length of memory in bytes, if non-NULL.
ppbData
[out] Pointer to the memory, if non-NULL.
pcbActualData
[out] Length of data in bytes, if non-NULL.
Return Values

Returns S_OK if successful.

Remarks

This method determines how much data is actually in the object at the moment as last set by SetActual.

IMemoryData::SetActual

IMemoryData Interface

Sets the amount of audio data currently in the object.

HRESULT SetActual(
DWORD cbDataValid
);

Parameters
cbDataValid
[in] Amount of data, in bytes.
Return Values

Returns S_OK if successful or E_POINTER if the required parameter is NULL.

Remarks

This method is usually called by the IAudioMediaStream or IAudioStreamSample object, rather than by the application.

IMemoryData::SetBuffer

IMemoryData Interface

Initializes a memory buffer with a pointer to memory and length.

HRESULT SetBuffer(
DWORD cbSize,
BYTE *pbData,
DWORD dwFlags );

Parameters
cbSize
[in] Size of memory pointed to by pbData, in bytes.
pbData
[in] Pointer to memory that this object will use.
dwFlags
[in] Reserved for flag data. Must be zero.
Return Values

Returns S_OK if successful or E_INVALIDARG if cbSize is zero or pbData is NULL.

Remarks

This method can be called more than once.

Do not call this method when the IStreamSample::Update method is processing a sample.


IAudioData Interface

The IAudioData interface provides methods that enable applications to set and get the underlying audio data that audio streams will reference. The audio data format is set in the WAVEFORMATEX structure.

When to Implement

Implement this interface on underlying audio data objects that audio stream sample objects will access.

When to Use

Applications use this interface to set and retrieve information on underlying data objects that an audio stream will reference.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAudioData methods | Description
GetFormat | Retrieves the current data format.
SetFormat | Sets the current data format.

IAudioData::GetFormat

IAudioData Interface

Retrieves the current data format.

HRESULT GetFormat(
WAVEFORMATEX *pWaveFormatCurrent );

Parameters
pWaveFormatCurrent
[out] Pointer to a WAVEFORMATEX structure that contains the current data format.
Return Values

Returns S_OK if successful or E_POINTER if pointer is invalid.

Remarks

Currently, DirectShow only supports PCM wave data.

See Also

IAudioData::SetFormat

IAudioData::SetFormat

IAudioData Interface

Sets the current data format.

HRESULT SetFormat(
const WAVEFORMATEX *lpWaveFormat );

Parameters
lpWaveFormat
[in] Pointer to a WAVEFORMATEX structure that will contain the current data format.
Return Values

Returns an HRESULT value, which can include the following values.
Value | Meaning
E_POINTER | Invalid pointer argument.
E_INVALIDARG | Invalid format.
S_OK | Success.

See Also

IAudioData::GetFormat

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IAMMultiMediaStream Interface

The IAMMultiMediaStream interface exposes Microsoft® DirectShow™ functionality to multimedia stream developers. You can use its methods to automatically generate filter graphs, open files or monikers for playback or capture of incoming data, and render a given filter graph.

When to Implement

Implement this interface when you want to provide multimedia stream-based support for DirectShow media types in your applications.

When to Use

Use this interface when you want to control DirectShow-supported media playback in your multimedia streaming applications.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMMultiMediaStream methods | Description
Initialize | Sets the stream type. If the pFilterGraph parameter is non-NULL the filter graph passed in is used for the stream.
GetFilterGraph | Retrieves the associated filter graph's IGraphBuilder interface.
GetFilter | Retrieves the specified filter from the current filter graph.
AddMediaStream | Adds the specified media stream to the current filter graph.
OpenFile | Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.
OpenMoniker | Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the media type.
Render | Renders the current filter graph.

IAMMultiMediaStream::AddMediaStream

IAMMultiMediaStream Interface

Adds the specified media stream to the current filter graph.

HRESULT AddMediaStream(
IUnknown* pStreamObject,
const MSPID *pPurposeID,
DWORD dwFlags,
IMediaStream** ppNewStream
)

Parameters
pStreamObject
[in] Pointer to an IUnknown interface that points to either the media stream or underlying stream object you want to add to the current filter graph.
pPurposeID
[in] Pointer to the purpose ID for the newly added media stream.
dwFlags
[in] Value that modifies the media stream's behavior; it is a combination of one or more of the following values.
AMMSF_ADDDEFAULTRENDERER | Add a default renderer.
AMMSF_CREATEPEER | Create a peer stream based on the same object as a pStreamObject.
ppNewStream
[out] Address of a pointer to an IMediaStream interface that will point to the newly added media stream. This parameter is optional.
Return Values

Returns an HRESULT value, which can include the following values:
Value | Meaning
MS_E_PURPOSEID | Stream being added has a different purpose ID from the one specified or a stream with the specified purpose ID already exists.
E_POINTER | Null pointer argument.
S_OK | Success.

Remarks

If dwFlags specifies AMMSF_ADDDEFAULTRENDERER then the default renderer for the given purpose Id is created if possible. Currently the only default renderer supported is for audio using DirectSound. In this case the pStreamObject parameter must be NULL and any calls to the IMultiMediaStream::GetMediaStream or IMultiMediaStream::EnumMediaStreams methods will not recognize the stream.

If dwFlags specifies AMMSF_CREATEPEER then a Media Stream is created using pStreamObject and added to the current multimedia stream. pStreamObject varies depending on the stream type. In general pStreamObject can point to an IMediaStream object, in which case a stream with the sample purpose ID and format is created. For IDirectDraw streams it can also be a pointer to an IDirectDraw object.

If neither flag is set then pStreamObject can be one of the following:
An IAMMediaStream object | This stream is then added to the streams in the multimedia stream.
NULL | In this case a default IMediaStream object is added to the stream with a default underlying object if required.
A pointer to an underlying object | This is used to construct default streams. For video streams this can be an IDirectDraw pointer.

IAMMultiMediaStream::GetFilter

IAMMultiMediaStream Interface

Retrieves the specified filter from the current filter graph.

HRESULT GetFilter(
IMediaStreamFilter** ppFilter
)

Parameters
ppFilter
[out] Address of a pointer to an IMediaStreamFilter interface that will point to the current filter.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

IAMMultiMediaStream::GetFilterGraph

IAMMultiMediaStream Interface

Retrieves the associated filter graph's IGraphBuilder interface.

HRESULT GetFilterGraph(
IGraphBuilder **ppGraphBuilder
);

Parameters
ppGraphBuilder
[out] Address of a pointer to an IGraphBuilder interface that will point to the current filter graph.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

IAMMultiMediaStream::Initialize

IAMMultiMediaStream Interface

Sets the stream type. If the pFilterGraph parameter is non-NULL the filter graph passed in is used for the stream.

HRESULT Initialize(
STREAM_TYPE StreamType,
DWORD dwFlags,
IGraphBuilder * pFilterGraph
)

Parameters
StreamType
[in] STREAM_TYPE enumeration value that specifies the new filter graph's stream type.
dwFlags
[in] Either contains the AMMSF_NOGRAPHTHREAD flag, which creates a filter graph object on the current thread, or zero.
pFilterGraph
[in] [optional] Address of an IGraphBuilder interface that will point to the new filter graph. This parameter is optional; only pass in a valid pointer if you must access the filter graph at a later time.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

Remarks

Using the AMMSF_NOGRAPHTHREAD flag is safe provided the current thread does not exit before the stream object is released by the application and the current thread processes window messages.

IAMMultiMediaStream::OpenFile

IAMMultiMediaStream Interface

Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.

HRESULT OpenFile(
LPCWSTR pszFileName,
DWORD dwFlags
)

Parameters
pszFileName
[in] Name of the file you want to open.
dwFlags
[in] Value that modifies how the filter graph will render the specified file. This value is a combination of one or more of the following flags:
Value | Meaning
AMMSF_RENDERTOEXISTING | Only render to existing streams
AMMSF_RENDERALLSTREAMS | Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER | Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK | Run the stream with no clock.
AMMSF_RUN | Set the stream into the run state.
Return Values

Returns one of the following values.
Value | Meaning
E_INVALIDARG | The dwFlags parameter is invalid.
E_POINTER | This method tried to access an invalid pointer.
S_OK | Success.

Remarks

The AMMSF_RENDERALLSTREAMS flag will create default rendering filters for video and audio if they do not exist. However, these default filters cannot be accessed by the IStreamSample::GetMediaStream method.

IAMMultiMediaStream::OpenMoniker

IAMMultiMediaStream Interface

Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the moniker.

HRESULT OpenMoniker(
IBindCtx *pCtx,
IMoniker* pMoniker,
DWORD dwFlags
)

Parameters
pCtx
[in] Pointer to the bind context associated with the moniker.
pMoniker
[in] Pointer to an IMoniker interface that specifies the moniker you want to open.
dwFlags
[in] Value that modifies how the filter graph will render the specified file. This value is a combination of one or more of the following flags:
Value | Meaning
AMMSF_RENDERTOEXISTING | Only render to existing streams
AMMSF_RENDERALLSTREAMS | Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER | Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK | Run the stream with no clock.
AMMSF_RUN | Set the stream into the run state.
Return Values

Returns S_OK if successful or E_INVALIDARG if the dwFlags parameter is invalid.

IAMMultiMediaStream::Render

IAMMultiMediaStream Interface

Renders the current filter graph.

HRESULT Render(
DWORD dwFlags
)

Parameters
dwFlags
[in] Value that specifies how the filter graph renders the current multimedia stream. This value currently must be AMMSF_NOCLOCK.
Return Values

Returns S_OK if successful or E_INVALIDARG if the dwFlags parameter is invalid.

Remarks

This method renders each of the source streams for a stream of type STREAMTYPE_WRITE. This can be called several times, for instance, each time a source stream is added, the stream is not set into running mode. Use the IMultiMediaStream::SetState method to set the stream into running mode after calling this method.

The AMMSF_RENDERALLSTREAMS flag will create default rendering streams for video and audio if they do not exist.


IAMMediaStream Interface

The IAMMediaStream interface handles the internal connections between DirectShow filters and filter graphs in applications that use multimedia streaming. This enables applications to automatically negotiate the transfer and conversion of data from the source to the application without having to write code to handle the connection, transfer of data, data conversion, and actual data rendering or file storage. This provides a uniform and predictable method of data access and control.

When to Implement

This interface isn't intended for implementation by application developers.

When to Use

This interface isn't intended for use by application developers.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IAMMediaStream methods | Description
Initialize | Creates and initializes a new media stream with the specified stream type and purpose ID.
SetState | Sets the filter state.
JoinAMMultiMediaStream | The IAMMultiMediaStream::AddMediaStream method calls this method, which adds the specified media stream to the current multimedia stream.
JoinFilter | Connects a media stream to a media stream filter in the underlying filter graph.
JoinFilterGraph | Connects a media stream filter to a filter graph.

IAMMediaStream::Initialize

IAMMediaStream Interface

Creates and initializes a new media stream with the specified stream type and purpose ID.

HRESULT Initialize(
IUnknown *pSourceObject,
DWORD dwFlags,
REFMSPID PurposeID,
STREAM_TYPE StreamType
)

Parameters
pSourceObject
[in] Pointer to an IUnknown source object.
dwFlags
[in] Flags. Must be zero.
PurposeID
[in] Purpose ID for the new media stream.
StreamType
[in] A STREAM_TYPE enumeration value that specifies the new media stream's media type.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are invalid.

IAMMediaStream::JoinAMMultiMediaStream

IAMMediaStream Interface

The IAMMultiMediaStream::AddMediaStream method calls this method, which adds the specified media stream to the current multimedia stream.

HRESULT JoinAMMultiMediaStream(
IAMMultiMediaStream* pAMMultiMediaStream
)

Parameters
pAMMultiMediaStream
[in] Specifies the IAMMultiMediaStream object to add the current media stream to.
Return Values

Returns S_OK if successful or MS_E_SAMPLEALLOC if the media stream already has allocated stream samples.

Remarks

Don't increment the reference count of the supplied multimedia stream because it is already accounted for when created.

Applications should not call this method.

IAMMediaStream::JoinFilter

IAMMediaStream Interface

Connects a media stream to a media stream filter in the underlying filter graph.

HRESULT JoinFilter( )

Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

Remarks

Don't increment the reference count for the specified media stream filter.

Applications should not call this method.

IAMMediaStream::JoinFilterGraph

IAMMediaStream Interface

Connects a media stream filter to a filter graph.

HRESULT JoinFilterGraph(
IFilterGraph* pGraph
)

Parameters
pGraph
[in] Indicates the current media stream filter to add to the specified filter graph.
Return Values

Returns S_OK if successful or E_POINTER if one or more of the required parameters are NULL.

Remarks

Don't increment the reference count of the specified filter graph.

Applications should not call this method.

IAMMediaStream::SetState

IAMMediaStream Interface

Sets the filter state.

HRESULT SetState(
FILTER_STATE State
)

Parameters
State
[in] Sets the filter's state, as specified by the FILTER_STATE enumerated type.
Return Values

Returns S_OK if successful or E_INVALIDARG if the State parameter is invalid..

Remarks

Applications should not call this method.


Multimedia Streaming Data Types

This section describes the Microsoft® DirectShow™ multimedia streaming data types.
Data type | Description
MSPID | Media stream purpose IDs define the purpose of a media stream. A purpose ID is simply typedefed as a GUID.
STREAM_STATE | Describes the state of the stream.
STREAM_TIME | Stream time measured in 100-nanosecond increments. This type is defined to be a 64-bit integer (LONGLONG).
STREAM_TYPE | Defines the direction of data flow for the stream.

STREAM_STATE

Multimedia Streaming Data Types

Describes the state of the stream.

typedef enum {
    STREAMSTATE_STOP        = 0,
    STREAMSTATE_RUN         = 1
} STREAM_STATE;
Values
STREAMSTATE_STOP
Stop state.
STREAMSTATE_RUN
Run state.
Remarks

Change the state by calling the IMultiMediaStream::SetState method.

STREAM_TYPE

Multimedia Streaming Data Types

Defines the direction of data flow for the stream.

typedef enum {
    STREAMTYPE_READ         = 0,
    STREAMTYPE_WRITE        = 1,
    STREAMTYPE_TRANSFORM= 2
} STREAM_TYPE;
Values
STREAMTYPE_READ
Application can read the stream.
STREAMTYPE_WRITE
Application can write to the stream.
STREAMTYPE_TRANSFORM
Application reads and writes the stream.
Remarks

Transform streams are read/write where the sample is updated in place.


Error and Success Codes for Multimedia Streaming

The following list contains error messages and success notifications for applications that use the multimedia streaming interfaces. This list does not contain all possible errors; the errors shown apply specifically to DirectShow implementation of the multimedia streaming interfaces. Note that success codes start with MS_S and return TRUE from the SUCCEEDED COM macro and FALSE from the COM FAILED macro.
Message | Hexadecimal code | Meaning
MS_S_PENDING | 0x00040001 | Sample update is not yet complete.
MS_S_NOUPDATE | 0x00040002 | Sample was not updated after forced completion.
MS_S_ENDOFSTREAM | 0x00040003 | End of stream. Sample not updated.
MS_E_SAMPLEALLOC | 0x80040401 | An IMediaStream object could not be removed from an IMultiMediaStream object because it still contains at least one allocated sample.
MS_E_PURPOSEID | 0x80040402 | The specified purpose id cannot be used for the call.
MS_E_NOSTREAM | 0x80040403 | No stream can be found with the specified attributes.
MS_E_NOSEEKING | 0x80040404 | Seeking not supported for this IMultiMediaStream object.
MS_E_INCOMPATIBLE | 0x80040405 | The stream formats are not compatible.
MS_E_BUSY | 0x80040406 | The sample is busy.
MS_E_NOTINIT | 0x80040407 | The object cannot accept the call because its initialize function or equivalent has not been called.
MS_E_SOURCEALREADYDEFINED | 0x80040408 | Source already defined.
MS_E_INVALIDSTREAMTYPE | 0x80040409 | The stream type is not valid for this operation.
MS_E_NOTRUNNING | 0x8004040A | The IMultiMediaStream object is not in running state.


Multimedia Streaming Component Objects

This article provides a table that describes the various components that Microsoft® DirectShow™ supports. These objects support the multimedia streaming interfaces. This article also includes a diagram that shows the hierarchy of component objects.

Contents of this article:

  • Component Objects Table
  • Object References Diagram

Component Objects Table

This section describes the various components that are supported by DirectShow.
Object | Description | Interfaces supported
CLSID_AMMultiMediaStream | DirectShow implementation of multimedia stream. | IAMMultiMediaStream, IMultiMediaStream
CLSID_MediaStreamFilter | Provides multimedia streaming functionality for the CLSID_AMMultiMediaStream object through the IAMMultiMediaStream interface. | IBaseFilter
CLSID_AMDirectDrawStream | DirectDraw® media stream that can be added to a DirectShow multimedia stream. | IAMMediaStream, IMediaStream, IDirectDrawMediaStream, IPin, IMemInputPin
Samples created by the DirectDraw stream. | IStreamSample, IDirectDrawStreamSample, IMediaSample
CLSID_ AMMediaTypeStream | Can create media samples for any DirectShow-supported data type | IAMMediaStream, IMediaStream, IPin, IMemInputPin
Samples created by the CLSID_ AMMediaTypeStream object | IStreamSample, IMediaSample, IMediaSample2
CLSID_AMAudioData | Implementation of IAudioData audio container object | IAudioData

Object References Diagram

The hierarchy of objects creates some interesting circular references between the DirectShow objects. The following diagram shows all the objects and their references. Strong references (those that increment the referenced object) are indicated by solid lines. Weak references (those that do not AddRef the referenced object) are indicated by a dotted line.

Object references diagram

Samples hold strong references to the multimedia stream object, while the media streams do not.


Multimedia Streaming Sample Code

This article provides sample code that implements the Multimedia Streaming interfaces. The video streaming sample code demonstrates how to read a file and render it to a primary Microsoft® DirectDraw® surface. This code has no error checking; see Use Multimedia Streaming in DirectShow Applications for a more thorough, line by line, description of the video streaming code.

The second code sample demonstrates how to use the audio streaming interfaces to stream audio data.

Contents of this article:

  • Video Streaming Sample Code
  • Audio Streaming Sample Code

Video Streaming Sample Code

This sample code reads a file and renders it to a primary DirectDraw surface.

#include <stdio.h>
#include "ddraw.h"	// DirectDraw interfaces
#include "mmstream.h"	// Multimedia stream interfaces
#include "amstream.h"	// DirectShow multimedia stream interfaces
#include "ddstream.h"	// DirectDraw multimedia stream interfaces

void RenderStreamToSurface(IDirectDrawSurface *pSurface, IMultiMediaStream *pMMStream)
{
    IMediaStream *pPrimaryVidStream;
    IDirectDrawMediaStream *pDDStream;
     IDirectDrawStreamSample *pSample;
    RECT rect;
     DDSURFACEDESC ddsd;

     pMMStream->GetMediaStream(MSPID_PrimaryVideo, &pPrimaryVidStream);
     pPrimaryVidStream->QueryInterface(IID_IDirectDrawMediaStream, (void **)&pDDStream);
     ddsd.dwSize = sizeof(ddsd);
     pDDStream->GetFormat(&ddsd, NULL, NULL, NULL);
     rect.top = rect.left = 0;
     rect.bottom = ddsd.dwHeight;
     rect.right = ddsd.dwWidth;
     pDDStream->CreateSample(pSurface, &rect, 0, &pSample);

    pMMStream->SetState(STREAMSTATE_RUN);
    while (pSample->Update(0, NULL, NULL, NULL) == S_OK);
    pMMStream->SetState(STREAMSTATE_STOP);

    pSample->Release();
    pDDStream->Release();
     pPrimaryVidStream->Release();
}

void RenderFileToMMStream(const char * szFileName, IMultiMediaStream **ppMMStream, IDirectDraw *pDD)
{
    IAMMultiMediaStream *pAMStream;
     CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
                      IID_IAMMultiMediaStream, (void **)&pAMStream);
    WCHAR	wPath[MAX_PATH];		// Wide (32-bit) string name
    MultiByteToWideChar(CP_ACP, 0, szFileName, -1, wPath,
                sizeof(wPath)/sizeof(wPath[0]));

     pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
     pAMStream->AddMediaStream(pDD, &MSPID_PrimaryVideo, 0, NULL);
     pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, AMMSF_ADDDEFAULTRENDERER, NULL);
     pAMStream->OpenFile(wPath, 0);
    *ppMMStream = pAMStream;
}

int _CRTAPI1 main(int argc, char *argv[])
{
    if (argc < 2) {
    printf("Usage : showstrm movie.ext\n");
    exit(0);}

    DDSURFACEDESC ddsd;
     IDirectDraw *pDD;
    IDirectDrawSurface *pPrimarySurface;
     IMultiMediaStream *pMMStream;

    CoInitialize(NULL);

     DirectDrawCreate(NULL, &pDD, NULL);
     pDD->SetCooperativeLevel(GetDesktopWindow(), DDSCL_NORMAL);
     ddsd.dwSize = sizeof(ddsd);
  ddsd.dwFlags = DDSD_CAPS;
     ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
     pDD->CreateSurface(&ddsd, &pPrimarySurface, NULL);
    RenderFileToMMStream(argv[1], &pMMStream, pDD);
     RenderStreamToSurface(pPrimarySurface, pMMStream);
    pMMStream->Release();
    pPrimarySurface->Release();
    pDD->Release();

    CoUninitialize();
    return 0;
}

Audio Streaming Sample Code

The following code sample demonstrates how to stream audio data using the IAudioMediaStream, IAudioStreamSample, IMemoryData, and IAudioData interfaces.

#include <windows.h>
#include <mmsystem.h>
#include <amstream.h>

/********************************************************************

   Trivial wave player stuff

 ********************************************************************/

class CWaveBuffer;

class CWaveBuffer {
    public:
        CWaveBuffer();
        ~CWaveBuffer();
        BOOL Init(HWAVEOUT hWave, int Size);
        void Done();
        BOOL Write(PBYTE pData, int nBytes, int& BytesWritten);
        void Flush();

    private:
        WAVEHDR      m_Hdr;
        HWAVEOUT     m_hWave;
        int          m_nBytes;
};

class CWaveOut {
    public:
        CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize);
        ~CWaveOut();
        void Write(PBYTE Data, int nBytes);
        void Flush();
        void Wait();
        void Reset();
    private:
        const HANDLE       m_hSem;
        const int          m_nBuffers;
        int          m_CurrentBuffer;
        BOOL         m_NoBuffer;
        CWaveBuffer *m_Hdrs;
        HWAVEOUT     m_hWave;
};

/*
    CWaveBuffer
*/

CWaveBuffer::CWaveBuffer()
{
}

BOOL CWaveBuffer::Init(HWAVEOUT hWave, int Size)
{
    m_hWave  = hWave;
    m_nBytes = 0;

    /*  Allocate a buffer and initialize the header */
    m_Hdr.lpData = (LPSTR)LocalAlloc(LMEM_FIXED, Size);
    if (m_Hdr.lpData == NULL) {
        return FALSE;
    }
    m_Hdr.dwBufferLength  = Size;
    m_Hdr.dwBytesRecorded = 0;
    m_Hdr.dwUser = 0;
    m_Hdr.dwFlags = 0;
    m_Hdr.dwLoops = 0;
    m_Hdr.lpNext = 0;
    m_Hdr.reserved = 0;

    /*  Prepare it */
    waveOutPrepareHeader(hWave, &m_Hdr, sizeof(WAVEHDR));

    return TRUE;
}

CWaveBuffer::~CWaveBuffer() {
    if (m_Hdr.lpData) {
        waveOutUnprepareHeader(m_hWave, &m_Hdr, sizeof(WAVEHDR));
        LocalFree(m_Hdr.lpData);
    }
}

void CWaveBuffer::Flush()
{
    //ASSERT(m_nBytes != 0);
    m_nBytes = 0;
    waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
}

BOOL CWaveBuffer::Write(PBYTE pData, int nBytes, int& BytesWritten)
{
    //ASSERT((DWORD)m_nBytes != m_Hdr.dwBufferLength);
    BytesWritten = min((int)m_Hdr.dwBufferLength - m_nBytes, nBytes);
    CopyMemory((PVOID)(m_Hdr.lpData + m_nBytes), (PVOID)pData, BytesWritten);
    m_nBytes += BytesWritten;
    if (m_nBytes == (int)m_Hdr.dwBufferLength) {
        /*  Write it! */
        m_nBytes = 0;
        waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
        return TRUE;
    }
    return FALSE;
}

void CALLBACK WaveCallback(HWAVEOUT hWave, UINT uMsg, DWORD dwUser, DWORD dw1, DWORD dw2)
{
    if (uMsg == WOM_DONE) {
        ReleaseSemaphore((HANDLE)dwUser, 1, NULL);
    }
}

/*
    CWaveOut
*/

CWaveOut::CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize) :
    m_nBuffers(nBuffers),
    m_CurrentBuffer(0),
    m_NoBuffer(TRUE),
    m_hSem(CreateSemaphore(NULL, nBuffers, nBuffers, NULL)),
    m_Hdrs(new CWaveBuffer[nBuffers]),
    m_hWave(NULL)
{
    /*  Create wave device */
    waveOutOpen(&m_hWave,
                WAVE_MAPPER,
                Format,
                (DWORD)WaveCallback,
                (DWORD)m_hSem,
                CALLBACK_FUNCTION);

    /*  Initialize the wave buffers */
    for (int i = 0; i < nBuffers; i++) {
        m_Hdrs[i].Init(m_hWave, BufferSize);
    }
}

CWaveOut::~CWaveOut()
{
    /*  First get our buffers back */
    waveOutReset(m_hWave);

    /*  Free the buffers */
    delete [] m_Hdrs;

    /*  Close the wave device */
    waveOutClose(m_hWave);

    /*  Free our semaphore */
    CloseHandle(m_hSem);
}

void CWaveOut::Flush()
{
    if (!m_NoBuffer) {
        m_Hdrs[m_CurrentBuffer].Flush();
        m_NoBuffer = TRUE;
        m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
    }
}

void CWaveOut::Reset()
{
    waveOutReset(m_hWave);
}

void CWaveOut::Write(PBYTE pData, int nBytes)
{
    while (nBytes != 0) {
        /*  Get a buffer if necessary */
        if (m_NoBuffer) {
            WaitForSingleObject(m_hSem, INFINITE);
            m_NoBuffer = FALSE;
        }

        /*  Write into a buffer */
        int nWritten;
        if (m_Hdrs[m_CurrentBuffer].Write(pData, nBytes, nWritten)) {
            m_NoBuffer = TRUE;
            m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
            nBytes -= nWritten;
            pData += nWritten;
        } else {
            //ASSERT(nWritten == nBytes);
            break;
        }
    }
}

void CWaveOut::Wait()
{
    /*  Send any remaining buffers */
    Flush();

    /*  Wait for our buffers back */
    for (int i = 0; i < m_nBuffers; i++) {
        WaitForSingleObject(m_hSem, INFINITE);
    }
    LONG lPrevCount;
    ReleaseSemaphore(m_hSem, m_nBuffers, &lPrevCount);
}

/**************************************************************************

  End of wave player stuff

 **************************************************************************/

HRESULT RenderStreamToDevice(IMultiMediaStream *pMMStream)
{
    WAVEFORMATEX wfx;
    #define DATA_SIZE 5000
    PBYTE pBuffer = (PBYTE)LocalAlloc(LMEM_FIXED, DATA_SIZE);

    IMediaStream *pStream;
    IAudioStreamSample *pSample;
    IAudioMediaStream *pAudioStream;
    IAudioData *pAudioData;

    pMMStream->GetMediaStream(MSPID_PrimaryAudio, &pStream);
    pStream->QueryInterface(IID_IAudioMediaStream, (void **)&pAudioStream);
    pAudioStream->GetFormat(&wfx);
    CoCreateInstance(CLSID_AMAudioData, NULL, CLSCTX_INPROC_SERVER,
                                    IID_IAudioData, (void **)&pAudioData);
    pAudioData->SetBuffer(DATA_SIZE, pBuffer, 0);
    pAudioData->SetFormat(&wfx);
    pAudioStream->CreateSample(pAudioData, 0, &pSample);
    HANDLE hEvent = CreateEvent(FALSE, NULL, NULL, FALSE);
    CWaveOut WaveOut(&wfx, 4, 2048);
    int iTimes;
    for (iTimes = 0; iTimes < 3; iTimes++) {
        DWORD dwStart = timeGetTime();
        for (; ; ) {
            HRESULT hr = pSample->Update(0, hEvent, NULL, 0);
            if (FAILED(hr) || MS_S_ENDOFSTREAM == hr) {
                break;
            }
            WaitForSingleObject(hEvent, INFINITE);
            DWORD dwTimeDiff = timeGetTime() - dwStart;
            //  We'll get bored after about 10 seconds
            if (dwTimeDiff > 10000) {
                break;
            }
            DWORD dwLength;
            pAudioData->GetInfo(NULL, NULL, &dwLength);
            WaveOut.Write(pBuffer, dwLength);
        }
        pMMStream->Seek(0);
    }

    pAudioData->Release();
    pSample->Release();
    pStream->Release();
    pAudioStream->Release();
    LocalFree((HLOCAL)pBuffer);

    return S_OK;
}

HRESULT RenderFileToMMStream(WCHAR * pszFileName, IMultiMediaStream **ppMMStream)
{
    IAMMultiMediaStream *pAMStream;
    CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
              IID_IAMMultiMediaStream, (void **)&pAMStream);
    pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
    pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, 0, NULL);
    pAMStream->OpenFile(pszFileName, AMMSF_RUN);
    *ppMMStream = pAMStream;
    return S_OK;
}

int _CRTAPI1 main(int argc, char *argv[])
{
    IMultiMediaStream *pMMStream;
    CoInitialize(NULL);
    WCHAR wszName[1000];
    MultiByteToWideChar(CP_ACP, 0, argv[1], -1, wszName,
                        sizeof(wszName) / sizeof(wszName[0]));
    RenderFileToMMStream(wszName, &pMMStream);
    RenderStreamToDevice(pMMStream);
    pMMStream->Release();
    CoUninitialize();
    return 0;
}


DirectDrawEx

This section contains an overview of the DirectDrawEx dynamic-link library, which extends the current functionality of Microsoft® DirectDraw®. It also contains reference material for the DirectDrawEx interfaces, IDirectDrawFactory and IDirectDraw3.

Using DirectDrawEx

IDirectDrawFactory Interface

IDirectDraw3 Interface


Using DirectDrawEx

This article provides a brief overview of DirectDrawEx and how it extends the functionality of a DirectDraw object as described in the Microsoft DirectX® SDK.

Contents of this article:

  • What Is DirectDrawEx?
  • Advantages of Using DirectDrawEx
  • Creating DirectDraw Objects and Surfaces with DirectDrawEx
  • Distinctions Between DirectDraw and DirectDrawEx

What Is DirectDrawEx?

DirectDrawEx is a dynamic-link library (DLL) that extends current functionality of DirectDraw, enhancing existing features and providing new functionality. DirectDrawEx also exposes new interfaces that applications can use when you include the Ddrawex.h header file.

To create a DirectDraw object that can use the extended features provided by DirectDrawEx, you must create the object by using the IDirectDrawFactory interface. A DirectDraw object created with the IDirectDrawFactory interface will support the IDirectDraw3 interface, aggregation of DirectDraw surfaces, data exchange, and palette mapping, in addition to the features of DirectDraw objects described in the DirectX SDK.

Advantages of Using DirectDrawEx

The primary advantage of creating a DirectDraw object through the IDirectDrawFactory interface is that it exposes the IDirectDraw3 interface. The IDirectDraw3 interface inherits all the functionality of the IDirectDraw and the IDirectDraw2 interfaces and provides a new method that can retrieve a pointer to an IDirectDrawSurface interface, given a handle to a device context.

To obtain the IDirectDraw3 interface, you must call the IDirectDrawFactory::CreateDirectDraw method to create the DirectDraw object and expose the IUnknown and IDirectDraw interfaces. Applications can then call QueryInterface to obtain a pointer to the IDirectDraw3 interface. To view sample code that demonstrates this, see Creating DirectDraw Objects and Surfaces with DirectDrawEx.

Another advantage of using DirectDrawEx over using DirectDraw is that you can now aggregate inner objects with outer objects by using the IDirectDraw3::CreateSurface method. Formerly, IDirectDraw::CreateSurface and IDirectDraw2::CreateSurface did not provide COM aggregation features. For a thorough description of how IDirectDraw3 implements aggregation see, IDirectDraw3::CreateSurface.

Finally, DirectDrawEx now also provides the DDSCAPS_DATAEXCHANGE flag for the DDSCAPS structure's dwcaps member. When a surface is created using the DDSCAPS_DATAEXCHANGE flag, the surface will automatically be moved into video memory if there is enough video memory available, otherwise a system memory surface will be created. This stabilizes video memory surfaces and ensures that they will not be lost, even if system memory decides to move them into video memory in the future.

Creating DirectDraw Objects and Surfaces with DirectDrawEx

The following sample code demonstrates how to create a DirectDraw object by using DirectDrawEx, and get a pointer to the IDirectDraw3 interface. The code shows how to create and call DirectDraw objects.

#include ddrawex.h

void CreateDDEx()
{
    //Declarations
    HRESULT 	hr;
    IDirectDraw 	*pDD;
    IDirectDraw3 	*pDD3;
    IDirectDrawFactory *pDDF;

    //Initialize COM library
    CoInitialize(NULL);

    //Create a DirectDrawFactory object and get
    //an IDirectDrawFactory interface pointer.
    CoCreateInstance(CLSID_DirectDrawFactory, NULL, CLSCTX_INPROC_SERVER,
                            IID_IDirectDrawFactory, (void **)&pDDF);

    //Call the IDirectDrawFactory::CreateDirectDraw method to create the
    //DirectDraw surface, set the cooperative level, and get the address
    //of an IDirectDraw interface pointer.
    hr = (pDDF->CreateDirectDraw(NULL, GetDesktopWindow(), DDSCL_NORMAL,
                NULL, NULL, &pDD));

    if (hr !=DD_OK) {//error checking
    }

    //Now query for the new IDirectDraw3 interface, and release the old one.
    hr =(pDD->QueryInterface(IID_IDirectDraw3, (LPVOID*)&pDD3));

    if (hr !=S_OK) {//error checking
    }

    //Release IDirectDraw.
    pDD->Release();
    pDD= NULL;

    //Initialize the DDSURFACEDESC structure for the primary surface.
    ZeroMemory(&ddsd, sizeof(ddsd));
      ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS;
      ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
      hr = pDD3->CreateSurface(&ddsd, &pPrimarySurface, NULL);

    //Do whatever you need to do in your application here with your
    //DirectDraw surface.

    //Release IDirectDraw3, IDirectDrawFactory, and the DirectDraw surface.
    pDD3->Release();
    pDDF->Release();
    pPrimarySurface->Release();

    //Close the COM library
    CoUninitialize();
}

Distinctions Between DirectDraw and DirectDrawEx

One important distinction to note between DirectDrawEx and DirectDraw is that applications that have created multiple DirectDrawSurface objects through a DirectDrawEx surface must release every DirectDraw surface.

Also, calling the GetDDInterface method from any surface created under DirectDrawEx will return a pointer to the IUnknown interface instead of a pointer to an IDirectDraw interface. Applications must use the IUnknown::QueryInterface method to retrieve the IDirectDraw, IDirectDraw2, or IDirectDraw3 interfaces.

Finally, DirectDrawEx does not currently support blitting between surfaces created by DirectDrawEx and surfaces created by DirectDraw. Applications should blit only between similar surfaces.


IDirectDrawFactory Interface

The IDirectDrawFactory interface is used to create and enumerate DirectDraw objects that support the extended features of DirectDrawEx (see Using DirectDrawEx for more information).

When to Implement

Do not implement this interface; DirectDrawEx implements it for you.

When to Use

Use this interface in an application when you want to create a DirectDrawEx object.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDirectDrawFactory methods | Description
CreateDirectDraw | Creates a DirectDraw object and retrieves pointers to the IUnknown and the IDirectDraw interfaces.
DirectDrawEnumerate | Enumerates the DirectDraw surfaces installed on the system.

IDirectDrawFactory::CreateDirectDraw

IDirectDrawFactory Interface

Creates a DirectDraw object and retrieves a pointer to its IDirectDraw interface.

STDMETHOD CreateDirectDraw(
GUID * pGUID,
HWND hWnd,
DWORD dwCoopLevelFlags,
DWORD dwReserved,
IUnknown *pUnkOuter,
IDirectDraw **ppDirectDraw
) PURE;

Parameters
pGUID
[out] Pointer to the globally unique identifier (GUID) that represents the driver to be created. Set this to NULL to indicate the active display driver, or you can pass one of the following flags to restrict the active display driver's behavior for debugging purposes:
Value | Meaning
DDCREATE_EMULATIONONLY | The DirectDraw object will use emulation for all features; it will not take advantage of any hardware-supported features.
DDCREATE_HARDWAREONLY | The DirectDraw object will never emulate features not supported by the hardware. Attempts to call methods that require unsupported features will fail, returning DDERR_UNSUPPORTED (operation not supported).
hWnd
[in] Window handle to the application.
dwCoopLevelFlags
[in] Application's top-level behavior. Specify one or more of the following flags:
Value | Meaning
DDSCL_ALLOWMODEX | Enables the use of Mode X display modes. You must use this flag with the DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN flags.
DDSCL_ALLOWREBOOT | Enables the user to reboot by pressing CTRL+ALT+DEL while the application is in full-screen exclusive mode.
DDSCL_EXCLUSIVE | Requests the exclusive level. You must use this flag with the DDSCL_FULLSCREEN flag. At the full screen and exclusive cooperative level, you can use the hardware to its fullest. In this mode, you can set custom and dynamic palettes, change display resolutions, compact memory, and implement page flipping. The exclusive (full-screen) mode does not prevent other applications from allocating surfaces, nor does it exclude them from using DirectDraw or GDI. However, it does prevent applications other than the one currently with exclusive access from changing the display mode or palette.
DDSCL_FULLSCREEN | Indicates that the exclusive-mode owner will be in control of the entire primary surface. You must use this flag with the DDSCL_EXCLUSIVE flag.
DDSCL_NORMAL | Indicates that the application will function as a regular Windows® application. You can't use this flag with the DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, or DDSCL_FULLSCREEN flags.
DDSCL_NOWINDOWCHANGES | Indicates that DirectDraw can't minimize or restore the application window when the application is activated.
dwReserved
[in] Reserved for future use. Must be NULL.
pUnkOuter
[in] Must be NULL. Created for future compatibility with COM aggregation features. Currently, CreateDirectDraw returns an error if this parameter is anything but NULL.
ppDirectDraw
[out] Address of a pointer to an IDirectDraw interface.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:
Value | Meaning
E_OUTOFMEMORY | There isn't enough memory available to create a DirectDraw object.
DDERR_GENERIC | There is an undefined error condition.
DDERR_UNSUPPORTED | DirectDraw doesn't support the operation.
DDERR_DIRECTDRAWALREADYCREATED | A DirectDrawEx object representing this driver has already been created for this process.
DDERR_INVALIDDIRECTDRAWGUID | The GUID passed to this method is not a valid DirectDrawEx driver identifier.
DDERR_INVALIDPARAMS | One or more of the parameters passed to the method are incorrect.
DDERR_NODIRECTDRAWHW | Hardware-only DirectDrawEx object creation isn't possible; the driver doesn't support any hardware.

Remarks

This method creates DirectDraw objects in the same way that the DirectDrawCreate function is used to create DirectDraw objects, and sets cooperative levels the same way the IDirectDraw2::SetCooperativeLevel method sets cooperative levels. However, in addition to creating a DirectDraw object, successful calls to the IDirectDrawFactory::CreateDirectDraw method will obtain a pointer to the IUnknown and IDirectDraw interfaces, which are exposed on the DirectDraw object. Applications can now query the DirectDraw object to obtain the address of a pointer to an IDirectDraw3 interface.

IDirectDrawFactory::DirectDrawEnumerate

IDirectDrawFactory Interface

Enumerates the available DirectDraw compatible devices in the system.

STDMETHOD DirectDrawEnumerate(
LPDDENUMCALLBACK lpCallback,
LPVOID lpContext
) PURE;

Parameters
lpCallback
[in] Pointer to a DDEnumCallback function that will be called with a description of each DirectDrawEx-enabled hardware abstraction layer (HAL) installed in the system.
lpContext
[in] Address of an application-defined structure that the system will pass to the callback function each time the function is called.
Return Values

Returns DD_OK if successful, or DDERR_INVALIDPARAMS otherwise.

Remarks

This method functions in a similar manner to the DirectDrawEnumerate function, defined in the DirectX SDK. It is used to enumerate the available DirectDraw compatible devices in a system when an application starts, before choosing which one you're going to create with CreateDirectDraw.


IDirectDraw3 Interface

The IDirectDraw3 interface is available to applications that have created a DirectDraw object through the IDirectDrawFactory::CreateDirectDraw method. This method retrieves the address of a pointer to an IDirectDraw interface, which your application can use to query for the IDirectDraw3 interface.

The IDirectDraw3 interface extends the IDirectDraw and the IDirectDraw2 interfaces by adding the IDirectDraw3::GetSurfaceFromDC method and providing new behavior for the IDirectDraw3::CreateSurface method (formerly IDirectDraw2::CreateSurface). This section provides information on the new behavior of the CreateSurface method. See the DirectX SDK for information on the original behavior of this and all other IDirectDraw and IDirectDraw2 methods as they relate to DirectDraw objects.

For more information on additional functionality provided by DirectDrawEx, see Using DirectDrawEx.

When to Implement

Do not implement this interface; DirectDrawEx implements it for you.

When to Use

Applications use this interface when they have created a DirectDraw object through a successful call to the IDirectDrawFactory::CreateDirectDraw method. Applications can use this interface to get an IDirectDrawSurface interface pointer directly from a handle to a device context.

Methods in Vtable Order
IUnknown methods | Description
QueryInterface | Retrieves pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDirectDraw3 methods | Description
CreateSurface | Creates a DirectDrawSurface object from a DirectDraw object.
GetSurfaceFromDC | Retrieves a pointer to an IDirectDrawSurface interface from a handle to a device context.

IDirectDraw3::CreateSurface

IDirectDraw3 Interface

Creates a DirectDrawSurface object from a DirectDraw object.

STDMETHOD CreateSurface(
LPDDSURFACEDESC lpDDSurfaceDesc,
LPDIRECTDRAWSURFACE FAR *lpDDSurface,
IUnknown FAR *pUnkOuter
) PURE;

Parameters
lpDDSurfaceDesc
[in] Pointer to the DDSURFACEDESC structure that describes the requested surface. You should set any unused members of DDSURFACEDESC to zero before calling this method. A DDSCAPS structure is a member of DDSURFACEDESC.
lpDDSurface
[out] Address of a pointer to be initialized with a valid DirectDrawSurface pointer if the call succeeds.
pUnkOuter
[in] Pointer to an IUnknown interface on an outer object that will be aggregated with an inner object's IUnknown interface.
Return Values

Returns DD_OK if successful, or one of the following error values otherwise:
Value | Meaning
DDERR_INCOMPATIBLEPRIMARY | The primary surface creation request does not match the existing primary surface.
DDERR_INVALIDCAPS | One or more of the capability bits passed to the callback function are incorrect.
DDERR_INVALIDOBJECT | DirectDraw received a pointer to an invalid DirectDraw object.
DDERR_INVALIDPARAMS | One or more of the parameters passed to the method are incorrect.
DDERR_INVALIDPIXELFORMAT | The pixel format was invalid as specified.
DDERR_NOALPHAHW | No alpha acceleration hardware is present or available, which caused the requested operation to fail.
DDERR_NOCOOPERATIVELEVELSET | The IDirectDraw2::SetCooperativeLevel method was not called before the surface was created.
DDERR_NODIRECTDRAWHW | Hardware-only DirectDraw object creation isn't possible; the driver doesn't support any hardware.
DDERR_NOEMULATION | Software emulation isn't available.
DDERR_NOEXCLUSIVEMODE | The operation requires the application to have exclusive mode, but the application doesn't have exclusive mode.
DDERR_NOFLIPHW | Flipping visible surfaces isn't supported.
DDERR_NOMIPMAPHW | The operation can't be carried out because no mipmap texture mapping hardware is present or available.
DDERR_NOOVERLAYHW | The operation can't be carried out because no overlay hardware is present or available.
DDERR_NOZBUFFERHW | The operation to create a z-buffer in display memory or to perform a blit using a z-buffer can't be carried out because there is no hardware support for z-buffers.
DDERR_OUTOFMEMORY | DirectDraw doesn't have enough available memory to perform the operation.
DDERR_OUTOFVIDEOMEMORY | DirectDraw doesn't have enough display memory to perform the operation.
DDERR_PRIMARYSURFACEALREADYEXISTS | The application has already created a primary surface.
DDERR_UNSUPPORTEDMODE | The operation isn't supported.

Remarks

Passing in NULL for the pUnkOuter parameter will return the address of a DirectDraw surface in the lpDDSurface parameter. However, if you pass in a pointer to an outer interface you want to aggregate with an inner interface, you will get back an IUnknown pointer for the lpDDSurface parameter.

DirectDrawEx now also provides the DDSCAPS_DATAEXCHANGE flag for the dwcaps member of the DDSCAPS structure, which is defined as a combination of DDSCAPS_SYSTEMMEMORY and DDSCAPS_VIDEOMEMORY in Ddrawex.h. When a surface is created using the DDSCAPS_DATAEXCHANGE flag, the surface will be automatically moved into video memory if there is enough video memory available; otherwise, a system memory surface will be created. Also, setting this flag in conjunction with the DDSCAPS_OWNDC flag enables applications to call the IDirectDrawSurface::GetDC method to lock the device context for as long they require, without holding a lock on the surface.

This method calls the IDirectDraw::CreateSurface and IDirectDraw2::CreateSurface methods.

IDirectDraw3::GetSurfaceFromDC

IDirectDraw3 Interface

Retrieves a pointer to an IDirectDrawSurface interface from a handle to a device context.

STDMETHOD GetSurfaceFromDC(
HDC hdc,
IDirectDrawSurface **ppSurface
) PURE;

Parameters
hdc
[in] Handle of the device context (DC).
ppSurface
[out] Address of a pointer to an IDirectDrawSurface interface.
Return Values

Returns S_OK if successful, or one of the following values otherwise:
Value | Meaning
E_POINTER | Invalid pointer to IDirectDrawSurface.
DDERR_NOTFOUND | The requested item wasn't found.


Appendixes

This section contains lists of the media types supported by DirectShow, the various MPEG media types, reserved identifiers in DirectShow, DVD video formats, and further reading.

Media Types

MPEG-1 Media Types

Time Stamps

Sample Properties

CLSIDs in DirectShow

DirectShow DVD Support

Country Codes and Channel to Frequency Mappings

Reserved Identifiers

Further Reading


Media Types

Microsoft® DirectShow™ uses the AM_MEDIA_TYPE structure to describe media samples. This structure includes GUID fields for major type, subtype, and format type, as well as fields specifying other sample features, such as whether the samples are compressed. This article summarizes the major type and subtype options registered by DirectShow. These media types are defined in Uuids.h.

  • Media Types with No Subtype
  • Audio Media Types
  • Line21 Media Types
  • MPEG2 Media Types
  • Stream Media Types
  • Video Media Types
  • Analog Video Media Types

Media Types with No Subtype

The following table describes the media types with no subtype.
MEDIATYPEs with no MEDIASUBTYPEs
MEDIATYPE_AnalogAudio | Analog audio connection
MEDIATYPE_File | Media type is a file, used closed captions.
MEDIATYPE_Interleaved | Data is interleaved, used by Digital Video (DV).
MEDIATYPE_Midi | Data is MIDI format.
MEDIATYPE_ScriptCommand | Data is a script command, used by closed captions.
MEDIATYPE_Text | Data is text.
MEDIATYPE_Timecode | Data is timecode data.

Audio Media Types

The wFormatTag field in the WAVEFORMATEX structure specifies the audio format type. The format type is generally FORMAT_WaveFormatEx. Media samples are generally whole number of samples as specified in the wBitsPerSample field in the WAVEFORMATEX structure. This is not necessarily true for MPEG audio samples that can come from packetized streams and are therefore not necessarily packaged on sample / frame boundaries. For MPEG audio the time stamp in a media sample is the time stamp for the first frame whose first byte is contained in the media sample.

Media subtypes are defined for each wFormatTag as follows:

  • The Data1 subfield of the Media Subtype is the same as the wFormatTag value.
  • The Data 2 field is 0.
  • The Data 3 field is 0x0010.
  • The Data 4 field is 0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71.

Thus, for PCM audio the subtype GUID would be:

{00000001-0000-0010-8000-00AA00389B71}

Older filters may still use GUID_NULL as the subtype so this should be checked for. However, registration of a filter with the explicit subtype greatly improves the speed of graph loading, especially when the given filter is not required. The CreateAudioMediaType function supplied in the DirectShow SDK can be used to create an AM_MEDIA_TYPE structure from a WAVEFORMATEX Structure.

The following table describes the audio media subtypes.
MEDIATYPE_Audio | Data is audio
MEDIASUBTYPE_PCMAudio | PCM audio
MEDIASUBTYPE_MPEG1Packet | MPEG1 Audio packet
MEDIASUBTYPE_MPEG1Payload | MPEG1 Audio Payload

Line21 Media Types

The following table describes the Line21 closed captioning media subtypes.
MEDIATYPE_AUXLine21Data | Data is Line21 type, used by closed captions
MEDIASUBTYPE_Line21_BytePair | Line21 data as byte pairs
MEDIASUBTYPE_Line21_GOPPacket | Line21 data in DVD GOP Packet
MEDIASUBTYPE_Line21_VBIRawData | Line21 data in raw VBI format

MPEG2 Media Types

The following table describes the MPEG2 media subtypes.
MEDIATYPE_MPEG2_PES | Data is MPEG2 format, used by DVD
MEDIASUBTYPE_DVD_SUBPICTURE | Subpicture data
MEDIASUBTYPE_DOLBY_AC3 | Dolby data
MEDIASUBTYPE_MPEG2_AUDIO | MPEG2 audio data
MEDIASUBTYPE_DVD_LPCM_AUDIO | DVD audio data

Stream Media Types

Time stamps are byte positions * 10000000 (notionally 1 byte per second) rather than real times.

The following table describes the stream media subtypes.
MEDIATYPE_Stream | Data is a non-timestamped byte stream
MEDIASUBTYPE_Avi | Data from AVI file
MEDIASUBTYPE_WAVE | Data from WAV file
MEDIASUBTYPE_AU | Data from AU file
MEDIASUBTYPE_AIFF | Data from AIFF file
MEDIASUBTYPE_MPEG1Video | MPEG video
MEDIASUBTYPE_MPEG1System | MPEG system
MEDIASUBTYPE_MPEG1VideoCD | MPEG video CD
MEDIASUBTYPE_MPEG1Audio | MPEG audio
MEDIASUBTYPE_DssVideo | Dss Video
MEDIASUBTYPE_DssAudio | Dss Audio

Video Media Types

The following table describes the video media subtypes.
MEDIATYPE_Video | Data is video
MEDIASUBTYPE_YVU9 | Standard YVU9 format uncompressed data. A planar YUV format. A Y sample at every pixel, a U and V sample at every fourth pixel horizontally on each line; a Y sample on every vertical line, a U and V sample at every fourth vertical line. 9 bits per pixel.
MEDIASUBTYPE_Y411 | YUV 411 format data. Same as Y41P.
MEDIASUBTYPE_Y41P | Y41P format data. A packed YUV format. A Y sample at every pixel, a U and V sample at every fourth pixel horizontally on each line; every vertical line sampled. Byte ordering (lowest first) is U0, Y0, V0, Y1, U4, Y2, V4, Y3, Y4, Y5, Y6, Y7, where the suffix 0 is the leftmost pixel and increasing numbers are pixels increasing left to right. Each 12-byte block is 8 image pixels.
MEDIASUBTYPE_YUY2 | YUY2 format data. Same as UYVY but with different pixel ordering. Byte ordering (lowest first) is Y0, U0, Y1, V0, Y2, U2, Y3, V2, Y4, U4, Y5, V4, where the suffix 0 is the leftmost pixel and increasing numbers are pixels increasing left to right. Each 4-byte block is 2 image pixels.
MEDIASUBTYPE_YVYU | YVYU format data. A packed YUV format. Same as UYVY but with different pixel ordering. Byte ordering (lowest first) is Y0, V0, Y1, U0, Y2, V2, Y3, U2, Y4, V4, Y5, U4, where the suffix 0 is the leftmost pixel and increasing numbers are pixels increasing left to right. Each 4-byte block is 2 image pixels.
MEDIASUBTYPE_UYVY | UYVY format data. A packed YUV format. A Y sample at every pixel, a U and V sample at every second pixel horizontally on each line; every vertical line sampled. Probably the most popular of the various YUV 4:2:2 formats. Byte ordering (lowest first) is U0, Y0, V0, Y1, U2, Y2, V2, Y3, U4, Y4, V4, Y5, where the suffix 0 is the leftmost pixel and increasing numbers are pixels increasing left to right. Each 4-byte block is 2 image pixels.
MEDIASUBTYPE_Y211 | YUV 211 format data. A packed YUV format. A Y sample at every second pixel, a U and V sample at every fourth pixel horizontally on each line; every vertical line sampled. Byte ordering (lowest first) is Y0, U0, Y2, V0, Y4, U4, Y6, V4, Y8, U8, Y10, V8, where the suffix 0 is the leftmost pixel and increasing numbers are pixels increasing left to right. Each 4-byte block is 4 image pixels.
MEDIASUBTYPE_CLJR | Cirrus Logic Jr YUV 411 format with less than 8 bits per Y, U, and V sample. Cinepak can produce it and Cirrus 5440 can produce an overlay with it. A Y sample at every pixel, a U and V sample at every fourth pixel horizontally on each line; every vertical line sampled.
MEDIASUBTYPE_IF09 | Indeo produced YVU9 format with additional information about differences from the last frame. 9.5 bits per pixel but reported as 9.
MEDIASUBTYPE_CPLA | Cinepak UYVY format.
MEDIASUBTYPE_MJPG | Motion JPEG (MJPG) compressed video.
MEDIASUBTYPE_TVMJ | TrueVision MJPG format.
MEDIASUBTYPE_WAKE | MJPG format produced by some cards.
MEDIASUBTYPE_CFCC | MJPG format produced by some cards.
MEDIASUBTYPE_IJPG | Intergraph JPEG format.
MEDIASUBTYPE_Plum | Plum MJPG format.
MEDIASUBTYPE_RGB1 | RGB 1 bit per pixel. Palettized.
MEDIASUBTYPE_RGB4 | RGB 4 bits per pixel. Palettized.
MEDIASUBTYPE_RGB8 | RGB 8 bits per pixel. Palettized.
MEDIASUBTYPE_RGB565 | 565 format of RGB, 16 bits per pixel. Uncompressed RGB samples.
MEDIASUBTYPE_RGB555 | 555 format of RGB, 16 bits per pixel. Uncompressed RGB samples.
MEDIASUBTYPE_RGB24 | RGB 24 bits per pixel. Uncompressed RGB samples.
MEDIASUBTYPE_RGB32 | RGB 32 bits per pixel. Uncompressed RGB samples.
MEDIASUBTYPE_Overlay | Video delivered using hardware overlay.
MEDIASUBTYPE_QTMovie | QT Specific compressions.
MEDIASUBTYPE_QTRpza | QT RPZA compressed data.
MEDIASUBTYPE_QTSmc | QT SMC compressed data.
MEDIASUBTYPE_QTRle | QT RLE compressed data.
MEDIASUBTYPE_QTJpeg | QT JPEG compressed data.
MEDIASUBTYPE_dvsd | Standard DV format.
MEDIASUBTYPE_dvhd | High Definition DV format.
MEDIASUBTYPE_dvsl | Long Play DV format.
MEDIASUBTYPE_MPEG1Packet | MPEG1 Video Packet.
MEDIASUBTYPE_MPEG1Payload | MPEG1 Video Payload.
MEDIASUBTYPE_VideoPort | Data is video port data, used with DVD.

Analog Video Media Types

The following analog video formats were introduced in ActiveMovie™ 1.0 but are currently not used. Instead, the IAMAnalogVideoDecoder, IAMAnalogVideoEncoder and IAMTVTuner interfaces use an enumeration called AnalogVideoStandard defined in Axextend.idl.

The following table describes the analog video media subtypes.
MEDIATYPE_AnalogVideo — Data is various formats of analog video, including standard NTSC, PAL, and SECAM formats.
MEDIASUBTYPE_AnalogVideo_NTSC_M
MEDIASUBTYPE_AnalogVideo_PAL_B
MEDIASUBTYPE_AnalogVideo_PAL_D
MEDIASUBTYPE_AnalogVideo_PAL_G
MEDIASUBTYPE_AnalogVideo_PAL_H
MEDIASUBTYPE_AnalogVideo_PAL_I
MEDIASUBTYPE_AnalogVideo_PAL_M
MEDIASUBTYPE_AnalogVideo_PAL_N
MEDIASUBTYPE_AnalogVideo_SECAM_B
MEDIASUBTYPE_AnalogVideo_SECAM_D
MEDIASUBTYPE_AnalogVideo_SECAM_G
MEDIASUBTYPE_AnalogVideo_SECAM_H
MEDIASUBTYPE_AnalogVideo_SECAM_K
MEDIASUBTYPE_AnalogVideo_SECAM_K1
MEDIASUBTYPE_AnalogVideo_SECAM_L


MPEG-1 Media Types

The following information summarizes the media types used by Microsoft® DirectShow™ for MPEG data.

MPEG-1 System Stream
Major type: MEDIATYPE_Stream

Minor type: MEDIASUBTYPE_MPEG1System

Format: None

Sample contents: BYTE stream; no alignment

MPEG-1 System Stream off Video CD
Major type: MEDIATYPE_Stream

Minor type: MEDIASUBTYPE_MPEG1VideoCD

Format: None

Sample contents: BYTE stream; no alignment

MPEG-1 Audio Packet
Major type: MEDIATYPE_Audio

Minor type: MEDIASUBTYPE_MPEG1Packet

Format: MPEG1WAVEFORMAT

Sample contents: Single MPEG-1 packet including packet header

MPEG-1 Audio payload
Major type: MEDIATYPE_Audio

Minor type: MEDIASUBTYPE_MPEG1Payload

Format: MPEG1WAVEFORMAT

Sample contents: Byte-aligned MPEG-1 audio data

MPEG-1 Video Packet
Major type: MEDIATYPE_Video

Minor type: MEDIASUBTYPE_MPEG1Packet

Format: VIDEOINFO + Video sequence header

Sample contents: Single MPEG-1 packet including packet header

MPEG-1 Video payload
Major type: MEDIATYPE_Video

Minor type: MEDIASUBTYPE_MPEG1Payload

Format: VIDEOINFO + Video sequence header

Sample contents: Byte-aligned MPEG-1 video data

MPEG-1 Native Video Stream
Major type: MEDIATYPE_Stream

Minor type: MEDIASUBTYPE_ MPEG1Video

Format: None

Sample contents: Array of video stream bytes (no system layer)

MPEG-1 Native Audio Stream
Major type: MEDIATYPE_Stream

Minor type: MEDIASUBTYPE_ MPEG1Audio

Format: None

Sample contents: Array of audio stream bytes (no system layer)

The various filters will support pins as follows:
Filter | Direction | Media type(s)
System layer splitter Input MPEG-1 system stream

MPEG-1 system stream off Video CD

System layer splitter | Output | MPEG-1 Audio packet or MPEG-1 Audio data
System layer splitter | Output | MPEG-1 Video packet or MPEG-1 Video data
Software Audio CODEC | Input | MPEG-1 Audio data or MPEG-1 Audio packet
Software Video CODEC | Input | MPEG-1 Video data or MPEG-1 Video packet
Software Audio CODEC | Output | PCM audio mono or stereo, input sampling rate, input sampling rate divided by 2 or input sampling rate divided by 4
Software Video CODEC | Output | Uncompressed video in Y41P, YUY2, UYVY, RGB24, RGB32, RGB565, RGB555 and RGB8 formats

MPEG-1 Video packet and payload media types contain a complete sequence header so that data can be played from the middle of a file without needing a sequence header to initialize the video playback.

The video sequence header is appended to the video data type for MPEG video so that play can begin from the middle of a stream. The length of this field is up to 140 bytes (it includes the sequence header start code—0x000001B3—at the start and any quantization matrices found in the first sequence header encountered).


Time Stamps

For more information about time stamps, see section 2.4.1 of ISO1-11172: "The packet header may contain decoding and/or presentation time stamps (DTS and PTS) that refer to the first access unit in the packet."

For MPEG_Stream major types, the start time is the byte position of the first byte, rated at 1 byte per second. The stop time is the byte position of the last byte. Thus, consecutive samples should have the stop time of the first packet equal to the start time of the next packet. For Video CD data, the origin of the medium must match the format of a video-CD file exposed by CDFS with the standard RIFF chunk at the start.

For MPEG video packet and payload types, the time stamp is the presentation time for the first video frame whose picture start code begins in the sample.

For MPEG audio packet and payload types, the time stamp is the presentation time for the first audio frame whose sync code starts in the sample.

It is assumed that packet and payload data without time stamps can be successfully prerolled by the handling filters.


Sample Properties

MPEG samples have the following properties or notifications.
Time stamp | Not all samples have start and stop times. The sample stop time for packet and payload data is not useful; it is usually set to the start time plus one. MPEG packet or payload data samples will have a start and stop time set if the system layer packet they are generated from had a valid PTS.
Discontinuity | If there is a break in the stream (for example, a gap in the real-time data, or an error in the data or after a seek), the Discontinuity property is set. This property is propagated from the MPEG-1 splitter to the stream handlers in the first sample sent after this property is set in a sample received. This also allows for a time-stamp discontinuity.
End Of Stream | This is not a sample property but a separate notification. When this is received, any buffered data must be forced through the decoder. Logically, any new data must then start with the Discontinuity property.


CLSIDs in DirectShow

Microsoft® DirectShow™ defines CLSIDs for many of its most-used components, such as filters and plug-in distributors. The CLSIDs are defined in Uuids.h. This article gives a brief description of the most common CLSIDs.

  • Plug-in Distributor CLSIDs
  • Cutlist CLSIDs
  • Filter Category CLSIDs
  • Filter and Filter Property Page CLSIDs

Plug-in Distributor CLSIDs

This table lists the CLSIDs of the DirectShow plug-in distributors — COM objects that expose a control interface and implement it by calling the enumerator of the filter graph manager — finding which filters expose the control interface and communicating directly with those filters. The developer generally doesn't implement these interfaces.
CLSID | Description
CLSID_FilterGraph | An object that builds filter graphs. This object implements the IFilterGraph interface.
CLSID_CaptureGraphBuilder | An object that builds capture graphs, preview graphs, and file compression graphs. This object implements the ICaptureGraphBuilder interface.
CLSID_AMovie | An object that performs as the filter graph manager. This object implements the IAMovie interface.
CLSID_PersistMonikerPID | An object that implements the IPersistMoniker interface, a standard COM interface that gives objects more control over the way they bind to their persistent data.
CLSID_FilterMapper | An object used by the filter graph manager to look up the properties of filters when they are loaded. This object implements the IFilterMapper interface.
CLSID_SystemClock | An object that implements the system reference clock in a filter graph. This object implements the IReferenceClock interface.
CLSID_SeekingPassThru | An object that implements the functionality of the CPosPassThru class. This object implements the IMediaSeeking and IMediaPosition interfaces.

Cutlist CLSIDs

This table lists the CLSIDs related to creating DirectShow cutlists, a collection of audio and video clips from different sources. Using the CutListGraphBuilderObject, the SimpleCutList object, and the VideoFileClip and AudioFileClip objects, an application can build a cutlist out of pieces of AVI and WAV files, and use the DirectShow Cutlist File Source filter to play it.
CLSID | Description
CLSID_AudioFileClip | An object that represents an audio file clip in a cutlist. This object implements the IAMCutListElement interface.
CLSID_VideoFileClip | An object that represents a video file clip in a cutlist. This object implements IAMCutListElement.
CLSID_SimpleCutList | An object that represents a cutlist (a collection of cutlist elements, each with a relative time and duration). This object implements the IStandardCutList interface.
CLSID_CutListGraphBuilder | An object that represents a cutlist filter graph. This object implements the ICutListGraphBuilder interface.
CLSID_MTXRiffs Cutlist File Source filter.

Filter Category CLSIDs

This table lists the CLSIDs for the DirectShow filter categories, seen in the Filter Graph Editor when you choose Insert Filters from the Graph menu. These categories can be used to enumerate the filters in a certain category.
CLSID | Description
CLSID_AudioInputDeviceCategory or CLSID_CWaveinClassManager | Audio Capture Sources category
CLSID_AudioCompressorCategory or CLSID_CAcmCoClassManager | Audio Compressors category
CLSID_AudioRendererCategory or CLSID_CWaveOutClassManager | Audio Renderers category
CLSID_LegacyAmFilterCategory or CLSID_CQzFilterClassManager | DirectShow Filters category
CLSID_MidiRendererCategory or CLSID_CMidiOutClassManager | Midi Renderers category
CLSID_VideoInputDeviceCategory or CLSID_CVidCapClassManager | Video Capture Sources category
CLSID_VideoCompressorCategory or CLSID_CIcmCoClassManager | Video Compressors category
CLSID_ActiveMovieCategories | The seven categories of filters in DirectShow

Filter and Filter Property Page CLSIDs

This table lists the CLSIDs for the DirectShow filters, seen in the Filter Graph Editor when you choose Insert Filters from the Graph menu. It also contains the CLSIDs for the filter property pages.
CLSID | Description
CLSID_ACMWrapper ACM Audio Compressor filter
CLSID_AudioRender Audio Renderer filter
CLSID_AudioProperties | Audio Renderer filter's property page
CLSID_AVIDec AVI Decompressor filter
CLSID_AviDest AVI MUX filter
CLSID_AviMuxProptyPage | AVI MUX filter's first property page
CLSID_AviMUXProptyPage1 | AVI MUX filter's second property page
CLSID_AviSplitter AVI Splitter filter
CLSID_AviDoc AVI/WAV File Source filter
CLSID_Colour Color Space Converter filter
CLSID_MTXRiffs Cutlist File Source filter
CLSID_DSoundRender | DirectSound Audio Renderer filter, in the Audio Renderers category
CLSID_DVMUX DV Muxer filter
CLSID_DVMuxPropertyPage | DV Muxer filter property page
CLSID_DVSplitter DV Splitter filter
CLSID_DVVideoCodec DV Video Decoder filter
CLSID_DVDecPropertiesPage | DV Video Decoder filter's property page
CLSID_DVVideoEnc DV Video Encoder filter
CLSID_DVEncPropertiesPage | DV Video Encoder filter's property page
CLSID_DVDNavigator DVD Navigator filter
CLSID_AsyncReader File Source (Async) filter
CLSID_URLReader File Source (URL) filter
CLSID_FileWriter File Writer filter
CLSID_ModexRenderer Full Screen Renderer filter
CLSID_ModexProperties | Full Screen Renderer filter's property page
CLSID_InfTee Infinite Pin Tee filter
CLSID_Line21Decoder Line21 Decoder filter
CLSID_AVIMIDIRender MIDI Renderer filter
CLSID_CMpegAudioCodec MPEG Audio Decoder filter
CLSID_CMpegVideoCodec MPEG Video Decoder filter
CLSID_MPEG1Splitter MPEG-1 Stream Splitter filter
CLSID_OverlayMixer Overlay Mixer filter
CLSID_TextRender Text Display filter
CLSID_VfwCapture | VFW Capture filter, in the Video Capture Sources category
CLSID_CaptureProperties | VFW Capture filter's property page
CLSID_Dither VGA 16 Color Ditherer filter
CLSID_VideoRenderer Video Renderer filter
CLSID_AudioRecord | WaveIn Audio Capture filter, in the Audio Capture Sources category


DirectShow DVD Support

This article outlines the DVD media types and formats. For the definitions of DirectShow-supported interlaced media types and picture aspect ratios, see VIDEOINFOHEADER2. MPEG2VIDEOINFO also contains relevant information.

The following diagram and tables specify the digital versatile disc (DVD) media types and formats supported by DirectShow.

Diagram showing connections, with references to tables
Connection | Major type | Subtype
A | MEDIATYPE_DVD_ENCRYPTED_PACK | MEDIASUBTYPE_MPEG2_VIDEO
B | MEDIATYPE_DVD_ENCRYPTED_PACK | MEDIASUBTYPE_DVD_SUBPICTURE
C | MEDIATYPE_DVD_ENCRYPTED_PACK | MEDIASUBTYPE_DOLBY_AC3
C | MEDIATYPE_DVD_ENCRYPTED_PACK | MEDIASUBTYPE_DVD_LPCM_AUDIO
D | MEDIATYPE_AUDIO | NULL
E | MEDIATYPE_AUXLine21Data | MEDIASUBTYPE_Line21_GOPPacket
F | MEDIATYPE_VIDEO | MEDIASUBTYPE_VideoPort — see Note
G | MEDIATYPE_VIDEO | Standard video subtypes
H | MEDIATYPE_VIDEO | MEDIASUBTYPE_Overlay

Connection | Format block type | Format block structure
A | FORMAT_MPEG2Video | MPEG2VIDEOINFO
B | FORMAT_VideoInfo2 | MPEG2VIDEOINFO
C | FORMAT_WaveFormatEx | WAVEFORMATEX
C | FORMAT_WaveFormatEx | WAVEFORMATEX
D | FORMAT_WaveFormatEx | WAVEFORMATEX
E | FORMAT_VideoInfo2 | VIDEOINFOHEADER
F | FORMAT_VideoInfo2 | VIDEOINFOHEADER2
G | FORMAT_VideoInfo2 | VIDEOINFOHEADER
H | FORMAT_VideoInfo | VIDEOINFOHEADER

Note: DirectShow determines the appropriate video port pixel formats during transport phase negotiation with the IVPConfig interface.


Country/Region Codes and Channel to Frequency Mappings

The following information provides country/region codes, analog video standards, and channel to frequency mappings that are in use by most countries in the world. The IAMTVTuner interface uses this information to set and view analog broadcast or cable channels that will be viewed through a Microsoft® DirectShow™ TV Tuner filter.

Contents of this article:

  • Country/Region Codes
  • Channel to Frequency Mappings for the U.S.
  • Channel to Frequency Mappings for Eastern Europe, China, and Russia
  • Channel to Frequency Mappings for the French Overseas Territories
  • Channel to Frequency Mappings for France and CCIR L System Countries
  • Channel to Frequency Mappings for Ireland
  • Channel to Frequency Mappings for Italy
  • Channel to Frequency Mappings for Japan
  • Channel to Frequency Mappings for New Zealand
  • Channel to Frequency Mappings for Australia
  • Channel to Frequency Mappings for the U.K., Ireland, S. Africa, and Hong Kong SAR, China
  • Channel to Frequency Mappings for Western Europe

Country/Region Codes

The following table provides country/region code to integer mappings. These mappings are the same mappings used by the iCountry variable in Win.ini configuration file found in c:\Windows. The first column represents the actual country/region code. The second and third columns are cable and broadcast frequency lists, respectively, and the fourth column is the Analog Video Broadcast standard used in the country/region.

1,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,
                                         // United States of America
                                         // Anguilla
                                         // Antigua
                                         // Bahamas
                                         // Barbados
                                         // Bermuda
                                         // British Virgin Islands
                                         // Canada
                                         // Cayman Islands
                                         // Dominica
                                         // Dominican Republic
                                         // Grenada
                                         // Jamaica
                                         // Montserrat
                                         // Nevis
                                         // St. Kitts
                                         // St. Vincent and the Grenadines
                                         // Trinidad and Tobago
                                         // Turks and Caicos Islands
                                         // Barbuda
                                         // Puerto Rico
                                         // Saint Lucia
                                         // United States Virgin Islands

2,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Canada (WIN.INI is bogus for this one country)

20,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Egypt
212, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // Morocco
213, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Algeria
216, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Tunisia
218, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Libya
220, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Gambia
221, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Senegal Republic
222, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // Mauritania
223, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Mali
224, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Guinea
225, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // Ivory Coast
226, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Burkina Faso
227, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Niger
228, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Togo
229, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Benin
230, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Mauritius
231, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Liberia
232, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Sierra Leone
233, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Ghana
234, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Nigeria
235, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Chad
236, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Central African Republic
237, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Cameroon
238, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // Cape Verde Islands
239, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Sao Tome and Principe
240, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // Equatorial Guinea
241, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Gabon
242, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_D,     // Congo
243, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Zaire
244, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_PAL_I,       // Angola
245, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // Guinea-Bissau
246, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Diego Garcia
247, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Ascension Island
248, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Seychelle Islands
249, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Sudan
250, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,,      // Rwanda
251, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Ethiopia
252, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Somalia
253, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Djibouti
254, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Kenya
255, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Tanzania
256, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Uganda
257, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // Burundi
258, F_FIX_CABLE, F_FIX_BROAD, AnalogVideo_PAL_B,       // Mozambique
260, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Zambia
261, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Madagascar
262, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Reunion Island
263, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Zimbabwe
264, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // Namibia
265, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Malawi
266, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // Lesotho
267, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Botswana
268, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Swaziland
269, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Mayotte Island
269, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Comoros
27,  F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // South Africa
290, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // St. Helena
291, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Eritrea
297, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Aruba
298, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Faroe Islands
299, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Greenland
30,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Greece
31,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Netherlands
32,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Belgium
33,  F_FRA_CABLE, F_FRA_BROAD, AnalogVideo_SECAM_L,     // France
34,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Spain
350, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Gibraltar
351, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Portugal
352, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Luxembourg
353, F_IRE_CABLE, F_IRE_BROAD, AnalogVideo_PAL_I,       // Ireland
354, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Iceland
355, F_ITA_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // Albania
356, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Malta
357, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Cyprus
358, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Finland
359, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Bulgaria
36,  F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Hungary
370, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Lithuania
371, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_D,     // Latvia
372, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Estonia
373, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Moldova
374, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Armenia
375, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Belarus
376, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Andorra
377, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_G,     // Monaco
378, F_ITA_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // San Marino
39,  F_ITA_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // Vatican City
380, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Ukraine
381, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Yugoslavia
385, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Croatia
386, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Slovenia
387, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Bosnia and Herzegovina
389, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // F.Y.R.O.M. (Former Yugoslav Republic of Macedonia)
39,  F_ITA_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // Italy
40,  F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_PAL_D,       // Romania
41,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Switzerland
41,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Liechtenstein
42,  F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Czech Republic
42,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Slovak Republic
43,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Austria
44,  F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // United Kingdom
45,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Denmark
46,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Sweden
47,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Norway
48,  F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Poland
49,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Germany
500, F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // Falkland Islands
501, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Belize
502, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Guatemala
503, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // El Salvador
504, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Honduras
505, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Nicaragua
506, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Costa Rica
507, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Panama
508, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // St. Pierre and Miquelon
509, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Haiti
51,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Peru
52,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Mexico
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Cuba
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Guantanamo Bay
54,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // Argentina
55,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_M,       // Brazil
56,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Chile
57,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Colombia
58,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Venezuela
590, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Guadeloupe
590, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // French Antilles
591, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // Bolivia
592, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Guyana
593, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Ecuador
594, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // French Guiana
595, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // Paraguay
596, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // Martinique
597, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Suriname
598, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // Uruguay
599, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Netherlands Antilles
60,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Malaysia
61,  F_OZ__CABLE, F_OZ__BROAD, AnalogVideo_PAL_B,       // Australia
61,  F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Cocos-Keeling Islands
62,  F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Indonesia
63,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Philippines
64,  F_NZ__CABLE, F_NZ__BROAD, AnalogVideo_PAL_B,       // New Zealand
65,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Singapore
66,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Thailand
670, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Saipan Island
670, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Rota Island
670, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Tinian Island
671, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Guam
672, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Christmas Island
672, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Australian Antarctic Territory
672, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Norfolk Island
673, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Brunei
674, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Nauru
675, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Papua New Guinea
676, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Tonga
677, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Solomon Islands
678, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Vanuatu
679, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Fiji Islands
680, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Palau
681, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // Wallis and Futuna Islands
682, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Cook Islands
683, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Niue
684, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // American Samoa
685, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Western Samoa
686, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Kiribati Republic
687, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // New Caledonia
688, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Tuvalu
689, F_FOT_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // French Polynesia
690, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Tokelau
691, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Micronesia
692, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Marshall Islands
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Russia
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Kazakhstan
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Kyrgyzstan
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Tajikistan
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Turkmenistan
7,   F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Uzbekistan

81,  F_JAP_CABLE, F_JAP_BROAD, AnalogVideo_NTSC_J,     	// Japan

82,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Korea (South)
84,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Vietnam
850, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Korea (North)
852, F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // Hong Kong SAR, China
853, F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // Macau Region
855, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Cambodia
856, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Laos
86,  F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_PAL_D,       // China
871, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (Atlantic-East)
872, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (Pacific)
873, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (Indian)
874, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (Atlantic-West)
880, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Bangladesh
886, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Taiwan Region
90,  F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Turkey
91,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // India
92,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Pakistan
93,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Afghanistan
94,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Sri Lanka
95,  F_FIX_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // Myanmar
960, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Maldives
961, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Lebanon
962, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Jordan
963, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Syria
964, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Iraq
965, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Kuwait
966, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Saudi Arabia
967, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Yemen
968, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Oman
971, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // United Arab Emirates
972, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Israel
973, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Bahrain
974, F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // Qatar
975, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // Bhutan
976, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Mongolia
977, F_FIX_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // Nepal
98,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // Iran
994, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Azerbaijan
995, F_EEU_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // Georgia

Channel to Frequency Mappings for the U.S.

The following table provides the video carrier frequencies for the United States (U.S.) Broadcast is provided first, and then cable.

USA CABLE DATA

        1L,             // Lowest channel
        158L,           // Highest channel

        73250000L,      // 1    VHF-LO
        55250000L,      // 2    VHF-LO
        61250000L,      // 3
        67250000L,      // 4
        77250000L,      // 5
        83250000L,      // 6

       175250000L,      // 7    VHF-HI
       181250000L,      // 8
       187250000L,      // 9
       193250000L,      // 10
       199250000L,      // 11
       205250000L,      // 12
       211250000L,      // 13

       121250000L,      // 14   UHF
       127250000L,      // 15
       133250000L,      // 16
       139250000L,      // 17
       145250000L,      // 18
       151250000L,      // 19
       157250000L,      // 20
       163250000L,      // 21
       169250000L,      // 22
       217250000L,      // 23
       223250000L,      // 24
       229250000L,      // 25
       235250000L,      // 26
       241250000L,      // 27
       247250000L,      // 28
       253250000L,      // 29
       259250000L,      // 30
       265250000L,      // 31
       271250000L,      // 32
       277250000L,      // 33
       283250000L,      // 34
       289250000L,      // 35
       295250000L,      // 36
       301250000L,      // 37
       307250000L,      // 38
       313250000L,      // 39
       319250000L,      // 40
       325250000L,      // 41
       331250000L,      // 42
       337250000L,      // 43
       343250000L,      // 44
       349250000L,      // 45
       355250000L,      // 46
       361250000L,      // 47
       367250000L,      // 48
       373250000L,      // 49
       379250000L,      // 50
       385250000L,      // 51
       391250000L,      // 52
       397250000L,      // 53
       403250000L,      // 54
       409250000L,      // 55
       415250000L,      // 56
       421250000L,      // 57
       427250000L,      // 58
       433250000L,      // 59
       439250000L,      // 60
       445250000L,      // 61
       451250000L,      // 62
       457250000L,      // 63
       463250000L,      // 64
       469250000L,      // 65
       475250000L,      // 66
       481250000L,      // 67
       487250000L,      // 68
       493250000L,      // 69
       499250000L,      // 70
       505250000L,      // 71
       511250000L,      // 72
       517250000L,      // 73
       523250000L,      // 74
       529250000L,      // 75
       535250000L,      // 76
       541250000L,      // 77
       547250000L,      // 78
       553250000L,      // 79
       559250000L,      // 80
       565250000L,      // 81
       571250000L,      // 82
       577250000L,      // 83
       583250000L,      // 84
       589250000L,      // 85
       595250000L,      // 86
       601250000L,      // 87
       607250000L,      // 88
       613250000L,      // 89
       619250000L,      // 90
       625250000L,      // 91
       631250000L,      // 92
       637250000L,      // 93
       643250000L,      // 94
        91250000L,      // 95    Discontinuity
        97250000L,      // 96
       103250000L,      // 97
       109250000L,      // 98
       115250000L,      // 99
       649250000L,      // 100   Discontinuity
       655250000L,      // 101
       661250000L,      // 102
       667250000L,      // 103
       673250000L,      // 104
       679250000L,      // 105
       685250000L,      // 106
       691250000L,      // 107
       697250000L,      // 108
       703250000L,      // 109
       709250000L,      // 110
       715250000L,      // 111
       721250000L,      // 112
       727250000L,      // 113
       733250000L,      // 114
       739250000L,      // 115
       745250000L,      // 116
       751250000L,      // 117
       757250000L,      // 118
       763250000L,      // 119
       769250000L,      // 120
       775250000L,      // 121
       781250000L,      // 122
       787250000L,      // 123
       793250000L,      // 124
       799250000L,      // 125
       805250000L,      // 126
       811250000L,      // 127
       817250000L,      // 128
       823250000L,      // 129
       829250000L,      // 130
       835250000L,      // 131
       841250000L,      // 132
       847250000L,      // 133
       853250000L,      // 134
       859250000L,      // 135
       865250000L,      // 136
       871250000L,      // 137
       877250000L,      // 138
       883250000L,      // 139
       889250000L,      // 140
       895250000L,      // 141
       901250000L,      // 142
       907250000L,      // 143
       913250000L,      // 144
       919250000L,      // 145
       925250000L,      // 146
       931250000L,      // 147
       937250000L,      // 148
       943250000L,      // 149
       949250000L,      // 150
       955250000L,      // 151
       961250000L,      // 152
       967250000L,      // 153
       973250000L,      // 154
       979250000L,      // 155
       985250000L,      // 156
       991250000L,      // 157
       997250000L,      // 158

USA BROADCAST DATA

        2L,             // Lowest channel
        69L,            // Highest channel

        55250000L,      // 2    VHF-LO
        61250000L,      // 3
        67250000L,      // 4
        77250000L,      // 5
        83250000L,      // 6

       175250000L,      // 7    VHF-HI
       181250000L,      // 8
       187250000L,      // 9
       193250000L,      // 10
       199250000L,      // 11
       205250000L,      // 12
       211250000L,      // 13

       471250000L,      // 14   UHF
       477250000L,      // 15
       483250000L,      // 16
       489250000L,      // 17
       495250000L,      // 18
       501250000L,      // 19
       507250000L,      // 20
       513250000L,      // 21
       519250000L,      // 22
       525250000L,      // 23
       531250000L,      // 24
       537250000L,      // 25
       543250000L,      // 26
       549250000L,      // 27
       555250000L,      // 28
       561250000L,      // 29
       567250000L,      // 30
       573250000L,      // 31
       579250000L,      // 32
       585250000L,      // 33
       591250000L,      // 34
       597250000L,      // 35
       603250000L,      // 36
       609250000L,      // 37
       615250000L,      // 38
       621250000L,      // 39
       627250000L,      // 40
       633250000L,      // 41
       639250000L,      // 42
       645250000L,      // 43
       651250000L,      // 44
       657250000L,      // 45
       663250000L,      // 46
       669250000L,      // 47
       675250000L,      // 48
       681250000L,      // 49
       687250000L,      // 50
       693250000L,      // 51
       699250000L,      // 52
       705250000L,      // 53
       711250000L,      // 54
       717250000L,      // 55
       723250000L,      // 56
       729250000L,      // 57
       735250000L,      // 58
       741250000L,      // 59
       747250000L,      // 60
       753250000L,      // 61
       759250000L,      // 62
       765250000L,      // 63
       771250000L,      // 64
       777250000L,      // 65
       783250000L,      // 66
       789250000L,      // 67
       795250000L,      // 68
       801250000L,      // 69

Channel to Frequency Mappings for Eastern Europe, China, and Russia

The following table provides the video carrier frequencies for Eastern Europe, including China and Russia. Broadcast is provided first, and then cable.

EAST EUROPE/CHINA/RUSSIA CABLE DATA

        1L,             // Lowest channel
        57L,            // Highest channel

        49750000L,      // 1
        57250000L,      // 2
        65250000L,      // 3
        77250000L,      // 4
        85250000L,      // 5
       168250000L,      // 6
       176250000L,      // 7
       184250000L,      // 8
       192250000L,      // 9
       200250000L,      // 10
       208250000L,      // 11
       216250000L,      // 12
       471250000L,      // 13
       479250000L,      // 14
       487250000L,      // 15
       493250000L,      // 16
       503250000L,      // 17
       511250000L,      // 18
       519250000L,      // 19
       527250000L,      // 20
       535250000L,      // 21
       543250000L,      // 22
       551250000L,      // 23
       559250000L,      // 24
       607250000L,      // 25
       615250000L,      // 26
       623250000L,      // 27
       631250000L,      // 28
       639250000L,      // 29
       647250000L,      // 30
       655250000L,      // 31
       663250000L,      // 32
       671250000L,      // 33
       679250000L,      // 34
       687250000L,      // 35
       695250000L,      // 36
       703250000L,      // 37
       711250000L,      // 38
       719250000L,      // 39
       727250000L,      // 40
       735250000L,      // 41
       743250000L,      // 42
       751250000L,      // 43
       759250000L,      // 44
       767250000L,      // 45
       775250000L,      // 46
       783250000L,      // 47
       791250000L,      // 48
       799250000L,      // 49
       807250000L,      // 50
       815250000L,      // 51
       823250000L,      // 52
       831250000L,      // 53
       839250000L,      // 54
       847250000L,      // 55
       855250000L,      // 56
       863250000L,      // 57

EAST EUROPE/CHINA/RUSSIA BROADCAST DATA

        1L,             // Lowest channel
        57L,            // Highest channel

        49750000L,      // 1
        57250000L,      // 2
        65250000L,      // 3
        77250000L,      // 4
        85250000L,      // 5
       168250000L,      // 6
       176250000L,      // 7
       184250000L,      // 8
       192250000L,      // 9
       200250000L,      // 10
       208250000L,      // 11
       216250000L,      // 12
       471250000L,      // 13
       479250000L,      // 14
       487250000L,      // 15
       493250000L,      // 16
       503250000L,      // 17
       511250000L,      // 18
       519250000L,      // 19
       527250000L,      // 20
       535250000L,      // 21
       543250000L,      // 22
       551250000L,      // 23
       559250000L,      // 24
       607250000L,      // 25
       615250000L,      // 26
       623250000L,      // 27
       631250000L,      // 28
       639250000L,      // 29
       647250000L,      // 30
       655250000L,      // 31
       663250000L,      // 32
       671250000L,      // 33
       679250000L,      // 34
       687250000L,      // 35
       695250000L,      // 36
       703250000L,      // 37
       711250000L,      // 38
       719250000L,      // 39
       727250000L,      // 40
       735250000L,      // 41
       743250000L,      // 42
       751250000L,      // 43
       759250000L,      // 44
       767250000L,      // 45
       775250000L,      // 46
       783250000L,      // 47
       791250000L,      // 48
       799250000L,      // 49
       807250000L,      // 50
       815250000L,      // 51
       823250000L,      // 52
       831250000L,      // 53
       839250000L,      // 54
       847250000L,      // 55
       855250000L,      // 56
       863250000L,      // 57

Channel to Frequency Mappings for the French Overseas Territories

The following table provides the video carrier frequencies for the French Overseas Territories. Broadcast is provided first, and then cable.

FRENCH OVERSEAS TERRITORIES CABLE DATA
         1L,            // Lowest channel
         6L,            // Highest channel

       175250000L,      // 1
       183250000L,      // 2
       191250000L,      // 3
       199250000L,      // 4
       207250000L,      // 5
       215250000L,      // 6

FRENCH OVERSEAS TERRITORIES BROADCAST DATA
         1L,            // Lowest channel
         6L,            // Highest channel

       175250000L,      // 1
       183250000L,      // 2
       191250000L,      // 3
       199250000L,      // 4
       207250000L,      // 5
       215250000L,      // 6

Channel to Frequency Mappings for France and CCIR L System Countries

The following table provides the video carrier frequencies for France and CCIR L System Countries. Broadcast is provided first, and then cable.

FRANCE CABLE DATA

        1L,             // Lowest channel
        69L,            // Highest channel

        47750000L,      // 1
        55750000L,      // 2
        60500000L,      // 3
        63750000L,      // 4
       176000000L,      // 5
       184000000L,      // 6
       192000000L,      // 7
       200000000L,      // 8
       208000000L,      // 9
       216000000L,      // 10
               0L,      // 11  Not used
               0L,      // 12  Not used
               0L,      // 13  Not used
               0L,      // 14  Not used
               0L,      // 15  Not used
               0L,      // 16  Not used
               0L,      // 17  Not used
               0L,      // 18  Not used
               0L,      // 19  Not used
               0L,      // 20  Not used
       471250000L,      // 21
       479250000L,      // 22
       487250000L,      // 23
       495250000L,      // 24
       503250000L,      // 25
       511250000L,      // 26
       519250000L,      // 27
       527250000L,      // 28
       535250000L,      // 29
       543250000L,      // 30
       551250000L,      // 31
       559250000L,      // 32
       567250000L,      // 33
       575250000L,      // 34
       583250000L,      // 35
       591250000L,      // 36
       599250000L,      // 37
       607250000L,      // 38
       615250000L,      // 39
       623250000L,      // 40
       631250000L,      // 41
       639250000L,      // 42
       647250000L,      // 43
       655250000L,      // 44
       663250000L,      // 45
       671250000L,      // 46
       679250000L,      // 47
       687250000L,      // 48
       695250000L,      // 49
       703250000L,      // 50
       711250000L,      // 51
       719250000L,      // 52
       727250000L,      // 53
       735250000L,      // 54
       743250000L,      // 55
       751250000L,      // 56
       759250000L,      // 57
       767250000L,      // 58
       775250000L,      // 59
       783250000L,      // 60
       791250000L,      // 61
       799250000L,      // 62
       807250000L,      // 63
       815250000L,      // 64
       823250000L,      // 65
       831250000L,      // 66
       839250000L,      // 67
       847250000L,      // 68
       855250000L,      // 69

FRANCE BROADCAST DATA

        1L,             // Lowest channel
        69L,            // Highest channel

        47750000L,      // 1
        55750000L,      // 2
        60500000L,      // 3
        63750000L,      // 4
       176000000L,      // 5
       184000000L,      // 6
       192000000L,      // 7
       200000000L,      // 8
       208000000L,      // 9
       216000000L,      // 10
               0L,      // 11  Not used
               0L,      // 12  Not used
               0L,      // 13  Not used
               0L,      // 14  Not used
               0L,      // 15  Not used
               0L,      // 16  Not used
               0L,      // 17  Not used
               0L,      // 18  Not used
               0L,      // 19  Not used
               0L,      // 20  Not used
       471250000L,      // 21
       479250000L,      // 22
       487250000L,      // 23
       495250000L,      // 24
       503250000L,      // 25
       511250000L,      // 26
       519250000L,      // 27
       527250000L,      // 28
       535250000L,      // 29
       543250000L,      // 30
       551250000L,      // 31
       559250000L,      // 32
       567250000L,      // 33
       575250000L,      // 34
       583250000L,      // 35
       591250000L,      // 36
       599250000L,      // 37
       607250000L,      // 38
       615250000L,      // 39
       623250000L,      // 40
       631250000L,      // 41
       639250000L,      // 42
       647250000L,      // 43
       655250000L,      // 44
       663250000L,      // 45
       671250000L,      // 46
       679250000L,      // 47
       687250000L,      // 48
       695250000L,      // 49
       703250000L,      // 50
       711250000L,      // 51
       719250000L,      // 52
       727250000L,      // 53
       735250000L,      // 54
       743250000L,      // 55
       751250000L,      // 56
       759250000L,      // 57
       767250000L,      // 58
       775250000L,      // 59
       783250000L,      // 60
       791250000L,      // 61
       799250000L,      // 62
       807250000L,      // 63
       815250000L,      // 64
       823250000L,      // 65
       831250000L,      // 66
       839250000L,      // 67
       847250000L,      // 68
       855250000L,      // 69

Channel to Frequency Mappings for Ireland

The following table provides the video carrier frequencies for Ireland. Broadcast is provided first, and then cable.

IRELAND CABLE DATA

         1L,            // Lowest channel
         9L,            // Highest channel

        45750000L,      // 1
        53750000L,      // 2
        61750000L,      // 3
       175250000L,      // 4
       183250000L,      // 5
       191250000L,      // 6
       199250000L,      // 7
       207250000L,      // 8
       215250000L,      // 9

IRELAND BROADCAST DATA

         1L,            // Lowest channel
         9L,            // Highest channel

        45750000L,      // 1
        53750000L,      // 2
        61750000L,      // 3
       175250000L,      // 4
       183250000L,      // 5
       191250000L,      // 6
       199250000L,      // 7
       207250000L,      // 8
       215250000L,      // 9

Channel to Frequency Mappings for Italy

The following table provides the video carrier frequencies for Italy. Broadcast is provided first, and then cable.

ITALY CABLE DATA

         2L,            // Lowest channel
        11L,            // Highest channel

        53750000L,      // 2    A
        62250000L,      // 3    B
        82250000L,      // 4    C
       175250000L,      // 5    D
       183750000L,      // 6    E
       192250000L,      // 7    F
       201250000L,      // 8    G
       210250000L,      // 9    H
       217250000L,      // 10   H1
       224250000L,      // 11   H2

Channel to Frequency Mappings for Japan

The following table provides the video carrier frequencies for Japan. Broadcast is provided first, and then cable.

JAPAN CABLE DATA

        13L,            // Lowest channel
        63L,            // Highest channel

       109250000L,      // 13
       115250000L,      // 14
       121250000L,      // 15
       127250000L,      // 16
       133250000L,      // 17
       139250000L,      // 18
       145250000L,      // 19
       151250000L,      // 20
       157250000L,      // 21
       165250000L,      // 22
       223250000L,      // 23
       231250000L,      // 24
       237250000L,      // 25
       243250000L,      // 26
       249250000L,      // 27
       253250000L,      // 28
       259250000L,      // 29
       265250000L,      // 30
       271250000L,      // 31
       277250000L,      // 32
       283250000L,      // 33
       289250000L,      // 34
       295250000L,      // 35
       301250000L,      // 36
       307250000L,      // 37
       313250000L,      // 38
       319250000L,      // 39
       325250000L,      // 40
       331250000L,      // 41
       337250000L,      // 42
       343250000L,      // 43
       349250000L,      // 44
       355250000L,      // 45
       361250000L,      // 46
       367250000L,      // 47
       373250000L,      // 48
       379250000L,      // 49
       385250000L,      // 50
       391250000L,      // 51
       397250000L,      // 52
       403250000L,      // 53
       409250000L,      // 54
       415250000L,      // 55
       421250000L,      // 56
       427250000L,      // 57
       433250000L,      // 58
       439250000L,      // 59
       445250000L,      // 60
       451250000L,      // 61
       457250000L,      // 62
       463250000L,      // 63

JAPAN BROADCAST DATA

        1L,             // Lowest channel
        62L,            // Highest channel

        91250000L,      // 1
        97250000L,      // 2
       103250000L,      // 3
       171250000L,      // 4
       177250000L,      // 5
       183250000L,      // 6
       189250000L,      // 7
       193250000L,      // 8
       199250000L,      // 9
       205250000L,      // 10
       211250000L,      // 11
       217250000L,      // 12
       471250000L,      // 13
       477250000L,      // 14
       483250000L,      // 15
       489250000L,      // 16
       495250000L,      // 17
       501250000L,      // 18
       507250000L,      // 19
       513250000L,      // 20
       519250000L,      // 21
       525250000L,      // 22
       531250000L,      // 23
       537250000L,      // 24
       543250000L,      // 25
       549250000L,      // 26
       555250000L,      // 27
       561250000L,      // 28
       567250000L,      // 29
       573250000L,      // 30
       579250000L,      // 31
       585250000L,      // 32
       591250000L,      // 33
       597250000L,      // 34
       603250000L,      // 35
       609250000L,      // 36
       615250000L,      // 37
       621250000L,      // 38
       627250000L,      // 39
       633250000L,      // 40
       639250000L,      // 41
       645250000L,      // 42
       651250000L,      // 43
       657250000L,      // 44
       663250000L,      // 45
       669250000L,      // 46
       675250000L,      // 47
       681250000L,      // 48
       687250000L,      // 49
       693250000L,      // 50
       699250000L,      // 51
       705250000L,      // 52
       711250000L,      // 53
       717250000L,      // 54
       723250000L,      // 55
       729250000L,      // 56
       735250000L,      // 57
       741250000L,      // 58
       747250000L,      // 59
       753250000L,      // 60
       759250000L,      // 61
       765250000L,      // 62

Channel to Frequency Mappings for New Zealand

The following table provides the video carrier frequencies for New Zealand. Broadcast is provided first, and then cable.

NEW ZEALAND CABLE DATA

         1L,            // Lowest channel
         9L,            // Highest channel

        45250000L,      // 1
        55250000L,      // 2
        62250000L,      // 3
       175250000L,      // 4
       182250000L,      // 5
       189250000L,      // 6
       196250000L,      // 7
       203250000L,      // 8
       210250000L,      // 9

NEW ZEALAND BROADCAST DATA

         1L,            // Lowest channel
         9L,            // Highest channel

        45250000L,      // 1
        55250000L,      // 2
        62250000L,      // 3
       175250000L,      // 4
       182250000L,      // 5
       189250000L,      // 6
       196250000L,      // 7
       203250000L,      // 8
       210250000L,      // 9

Channel to Frequency Mappings for Australia

The following table provides the video carrier frequencies for Australia. Broadcast is provided first, and then cable.

AUSTRALIA CABLE DATA

         1L,            // Lowest channel
        14L,            // Highest channel

        46250000L,      // 0    (1)
        57250000L,      // 1    (2)
        64250000L,      // 2    (3)
        86250000L,      // 3    (4)
        95250000L,      // 4    (5)
       102250000L,      // 5    (6)
       138250000L,      // 5a   (7)
       175250000L,      // 6    (8)
       182250000L,      // 7    (9)
       189250000L,      // 8    (10)
       196250000L,      // 9    (11)
       209250000L,      // 10   (12)
       216250000L,      // 11   (13)
       223250000L,      // 12   (14)

AUSTRALIA BROADCAST DATA

         1L,            // Lowest channel
        14L,            // Highest channel

        46250000L,      // 0    (1)
        57250000L,      // 1    (2)
        64250000L,      // 2    (3)
        86250000L,      // 3    (4)
        95250000L,      // 4    (5)
       102250000L,      // 5    (6)
       138250000L,      // 5a   (7)
       175250000L,      // 6    (8)
       182250000L,      // 7    (9)
       189250000L,      // 8    (10)
       196250000L,      // 9    (11)
       209250000L,      // 10   (12)
       216250000L,      // 11   (13)
       223250000L,      // 12   (14)

Channel to Frequency Mappings for the U.K., Ireland, S. Africa, and Hong Kong SAR, China

The following table provides the video carrier frequencies for the United Kingdom (U.K.), Ireland, South Africa and Hong Kong SAR, China. Broadcast is provided first, and then cable.

UK CABLE DATA

         2L,            // Lowest channel
        56L,            // Highest channel

        48250000L,      // 2
        55250000L,      // 3
        62250000L,      // 4
        69250000L,      // 5    S01
        76250000L,      // 6    S02
        83250000L,      // 7    S03
       105250000L,      // 8    S1
       112250000L,      // 9    S2
       119250000L,      // 10   S3
       126250000L,      // 11   S4
       133250000L,      // 12   S5
       140250000L,      // 13   S6
       147250000L,      // 14   S7
       154250000L,      // 15   S8
       161250000L,      // 16   S9
       168250000L,      // 17   S10
       175250000L,      // 18   E5
       182250000L,      // 19   E6
       189250000L,      // 20   E7
       196250000L,      // 21   E8
       203250000L,      // 22   E9
       210250000L,      // 23   E10
       217250000L,      // 24   E11
       224250000L,      // 25   E12
       231250000L,      // 26   S11
       238250000L,      // 27   S12
       245250000L,      // 28   S13
       252250000L,      // 29   S14
       259250000L,      // 30   S15
       266250000L,      // 31   S16
       273250000L,      // 32   S17
       280250000L,      // 33   S18
       287250000L,      // 34   S19
       294250000L,      // 35   S20
       303250000L,      // 36   S21
       311250000L,      // 37   S22
       319250000L,      // 38   S23
       327250000L,      // 39   S24
       335250000L,      // 40   S25
       343250000L,      // 41   S26
       351250000L,      // 42   S27
       359250000L,      // 43   S28
       367250000L,      // 44   S29
       375250000L,      // 45   S30
       383250000L,      // 46   S31
       391250000L,      // 47   S32
       399250000L,      // 48   S33
       407250000L,      // 49   S34
       415250000L,      // 50   S35
       423250000L,      // 51   S36
       431250000L,      // 52   S37
       439250000L,      // 53   S38
       447250000L,      // 54   S39
       455250000L,      // 55   S40
       463250000L,      // 56   S41

UK BROADCAST DATA

        2L,             // Lowest channel
        69L,            // Highest channel

        45750000L,      // 2
        53750000L,      // 3
        61750000L,      // 4
       175250000L,      // 5
       183250000L,      // 6
       191250000L,      // 7
       199250000L,      // 8
       207250000L,      // 9
       215250000L,      // 10
               0L,      // 11  not used
               0L,      // 12  not used
               0L,      // 13  not used
               0L,      // 14  not used
               0L,      // 15  not used
               0L,      // 16  not used
               0L,      // 17  not used
               0L,      // 18  not used
               0L,      // 19  not used
               0L,      // 20  not used
       471250000L,      // 21
       479250000L,      // 22
       487250000L,      // 23
       495250000L,      // 24
       503250000L,      // 25
       511250000L,      // 26
       519250000L,      // 27
       527250000L,      // 28
       535250000L,      // 29
       543250000L,      // 30
       551250000L,      // 31
       559250000L,      // 32
       567250000L,      // 33
       575250000L,      // 34
       583250000L,      // 35
       591250000L,      // 36
       599250000L,      // 37
       607250000L,      // 38
       615250000L,      // 39
       623250000L,      // 40
       631250000L,      // 41
       639250000L,      // 42
       647250000L,      // 43
       655250000L,      // 44
       663250000L,      // 45
       671250000L,      // 46
       679250000L,      // 47
       687250000L,      // 48
       695250000L,      // 49
       703250000L,      // 50
       711250000L,      // 51
       719250000L,      // 52
       727250000L,      // 53
       735250000L,      // 54
       743250000L,      // 55
       751250000L,      // 56
       759250000L,      // 57
       767250000L,      // 58
       775250000L,      // 59
       783250000L,      // 60
       791250000L,      // 61
       799250000L,      // 62
       807250000L,      // 63
       815250000L,      // 64
       823250000L,      // 65
       831250000L,      // 66
       839250000L,      // 67
       847250000L,      // 68
       855250000L,      // 69

Channel to Frequency Mappings for Western Europe

The following table provides the video carrier frequencies for Western Europe. Broadcast is provided first, and then cable.

WESTERN EUROPE CABLE DATA

         2L,            // Lowest channel
        56L,            // Highest channel

        48250000L,      // 2
        55250000L,      // 3
        62250000L,      // 4
        69250000L,      // 5    S01
        76250000L,      // 6    S02
        83250000L,      // 7    S03
       105250000L,      // 8    S1
       112250000L,      // 9    S2
       119250000L,      // 10   S3
       126250000L,      // 11   S4
       133250000L,      // 12   S5
       140250000L,      // 13   S6
       147250000L,      // 14   S7
       154250000L,      // 15   S8
       161250000L,      // 16   S9
       168250000L,      // 17   S10
       175250000L,      // 18   E5
       182250000L,      // 19   E6
       189250000L,      // 20   E7
       196250000L,      // 21   E8
       203250000L,      // 22   E9
       210250000L,      // 23   E10
       217250000L,      // 24   E11
       224250000L,      // 25   E12
       231250000L,      // 26   S11
       238250000L,      // 27   S12
       245250000L,      // 28   S13
       252250000L,      // 29   S14
       259250000L,      // 30   S15
       266250000L,      // 31   S16
       273250000L,      // 32   S17
       280250000L,      // 33   S18
       287250000L,      // 34   S19
       294250000L,      // 35   S20
       303250000L,      // 36   S21
       311250000L,      // 37   S22
       319250000L,      // 38   S23
       327250000L,      // 39   S24
       335250000L,      // 40   S25
       343250000L,      // 41   S26
       351250000L,      // 42   S27
       359250000L,      // 43   S28
       367250000L,      // 44   S29
       375250000L,      // 45   S30
       383250000L,      // 46   S31
       391250000L,      // 47   S32
       399250000L,      // 48   S33
       407250000L,      // 49   S34
       415250000L,      // 50   S35
       423250000L,      // 51   S36
       431250000L,      // 52   S37
       439250000L,      // 53   S38
       447250000L,      // 54   S39
       455250000L,      // 55   S40
       463250000L,      // 56   S41

WESTERN EUROPE BROADCAST DATA

        2L,             // Lowest channel
        69L,            // Highest channel

        48250000L,      // 2 Note: 2A is at 49.75
        55250000L,      // 3
        62250000L,      // 4
       175250000L,      // 5
       182250000L,      // 6
       189250000L,      // 7
       196250000L,      // 8
       203250000L,      // 9
       210250000L,      // 10
       217250000L,      // 11
       224250000L,      // 12

               0L,      // 13 Not used
               0L,      // 14 Not used
               0L,      // 15 Not used
               0L,      // 16 Not used
               0L,      // 17 Not used
               0L,      // 18 Not used
               0L,      // 19 Not used
               0L,      // 20 Not used

       471250000L,      // 21
       479250000L,      // 22
       487250000L,      // 23
       495250000L,      // 24
       503250000L,      // 25
       511250000L,      // 26
       519250000L,      // 27
       527250000L,      // 28
       535250000L,      // 29
       543250000L,      // 30
       551250000L,      // 31
       559250000L,      // 32
       567250000L,      // 33
       575250000L,      // 34
       583250000L,      // 35
       591250000L,      // 36
       599250000L,      // 37
       607250000L,      // 38
       615250000L,      // 39
       623250000L,      // 40
       631250000L,      // 41
       639250000L,      // 42
       647250000L,      // 43
       655250000L,      // 44
       663250000L,      // 45
       671250000L,      // 46
       679250000L,      // 47
       687250000L,      // 48
       695250000L,      // 49
       703250000L,      // 50
       711250000L,      // 51
       719250000L,      // 52
       727250000L,      // 53
       735250000L,      // 54
       743250000L,      // 55
       751250000L,      // 56
       759250000L,      // 57
       767250000L,      // 58
       775250000L,      // 59
       783250000L,      // 60
       791250000L,      // 61
       799250000L,      // 62
       807250000L,      // 63
       815250000L,      // 64
       823250000L,      // 65
       831250000L,      // 66
       839250000L,      // 67
       847250000L,      // 68
       855250000L,      // 69


Reserved Identifiers

When compiling programs that include the Microsoft® DirectShow™ header files, it is important to be aware of the following identifiers and their meanings, if they are defined before the DirectShow headers are included.

These identifiers are, in effect, reserved except as described in the following list.
DEBUG | Indicates a debug build. This enables many debug facilities, including message logging and assertion checking.
PERF | Indicates a performance (measurement) build.
VFWROBUST | Enables some pointer validation macros in a build of any kind. See ValidateReadPtr and related macros for more specifics.

Build Types

A retail build is the smallest and fastest build, although perhaps not as robust as a debug build. A retail build is the default if neither a debug build nor a performance build is requested.

A debug build is generally the largest and slowest build. However, it provides better facilities for debugging new code and tracking problems. Defining the DEBUG identifier requests a debug build.

A performance build adds measurement capabilities to a retail build. Defining the PERF identifier requests a performance build. The performance build requires one additional file: Measure.dll.

Caveat: Mixing Build Types

If debug and retail binaries are mixed, the results are undefined. The results of mixing debug and retail object files in one binary are also undefined.


Further Reading

_CrtSetDbgFlag
Retrieves and/or modifies the state of the _crtDbgFlag flag to control the allocation behavior of the debug heap manager (debug version only). See the Microsoft® Visual C++® documentation for more information.
BitBlt
The BitBlt function performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context. See the Microsoft Platform SDK documentation for more information.
biHeight
A data member of the BITMAPINFOHEADER structure that specifies the height of a bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB (device-independent bitmap) and its origin is the lower left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper left corner.
biWidth
A data member of the BITMAPINFOHEADER structure that specifies the width of a bitmap, in pixels.
BSTR
A 32-bit character pointer. See the Platform SDK documentation for more information.
CAggDirectDraw::SetDisplayMode
Sets the mode of the display-device hardware. See IDirectDraw2::SetDisplayMode in the Microsoft DirectX® SDK for more information.
CAggDrawSurface::Blt
Performs a bit block transfer. See IDirectDrawSurface3::Blt in the DirectX SDK for more information.
CAggDrawSurface::GetDC
Creates a GDI-compatible handle of a device context for the surface. See IDirectDrawSurface3::GetDC in the DirectX SDK for more information.
CClassFactory
A class that implements the IClassFactory interface. The IClassFactory interface contains two methods intended to deal with an entire class of objects, and so it is implemented on the class object for a specific class of objects (identified by a CLSID). The first method, CreateInstance, creates an uninitialized object of a specified CLSID, and the second, LockServer, locks the object's server in memory, enabling quicker creation of new objects. See the IClassFactory interface documentation in the Platform SDK.
ClientToScreen
Converts the client coordinates of a specified point to screen coordinates. See the Platform SDK documentation for more information.
clipper
See DirectDrawClipper.
CoCreateInstance
Creates a single uninitialized object of the class associated with a specified CLSID. See the Platform SDK documentation for more information.
CoGetClassObject
Provides a pointer to an interface on a class object associated with a specified CLSID. CoGetClassObject locates, and if necessary, dynamically loads the executable code required to do this. See the Platform SDK documentation for more information.
CoInitialize
Initializes the Component Object Model (COM) library. See the Platform SDK documentation for more information.
COLORREF
A 32-bit value used to specify an RGB color. See the Platform SDK documentation for more information.
cooperative level
Determines the top-level behavior of the application. See IDirectDraw2::SetCooperativeLevel in the DirectX SDK for more information.
CoTaskMemAlloc
Allocates a block of task memory in the same way that IMalloc::Alloc does. See the Platform SDK documentation for more information.
CoTaskMemFree
Frees a block of task memory previously allocated through a call to the CoTaskMemAlloc or CoTaskMemRealloc function. See the Platform SDK documentation for more information.
cout
A C++ object that controls insertions to the standard output as a byte stream. For more information, see the Run-Time Library Reference included in the Visual C++ Developer Studio documentation, or see other books that discuss the C and C++ programming languages.
CreateDIBSection
Creates a device-independent bitmap (DIB) that applications can write to directly. The function gives you a pointer to the location of the bitmap's bit values. You can supply a handle to a file mapping object that the function will use to create the bitmap, or you can let the operating system allocate the memory for the bitmap. See the Platform SDK documentation for more information.
CreateEvent
Creates a named or unnamed event object. See the Platform SDK documentation for more information.
CreateFile
Creates or opens various objects and returns a handle that can be used to access the object. See the Platform SDK documentation for more information.
CreateWindow
Creates an overlapped, pop-up, or child window. See the Platform SDK documentation for more information.
CreateWindowEx
Creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CreateWindow function. See the Platform SDK documentation for more information.
CRITICAL_SECTION
A critical section object, an object used to synchronize the threads of a single process. Only one thread at a time can own a critical-section object. See the Platform SDK documentation for more information.
DDCAPS
A structure that represents the capabilities of the hardware exposed through the Microsoft DirectDraw® object. See the DirectDraw documentation in the DirectX SDK for more information.
DDCOLORCONTROL
A structure that defines the color controls associated with a DirectDrawVideoPort object, an overlay surface, or a primary surface. See the DirectX SDK documentation for more information.
DDEnumCallback
An application-defined callback function for the DirectDrawEnumerate function. See the DirectDraw documentation in the DirectX SDK for more information.
DDPIXELFORMAT
A structure that describes the pixel format of a DirectDrawSurface object for the IDirectDrawSurface3::GetPixelFormat method. See the DirectDraw documentation in the DirectX SDK for more information.
DDSCAPS
A structure that defines the capabilities of a DirectDrawSurface object. This structure is part of the DDCAPS structure that is used to describe the capabilities of the DirectDraw object. See the DirectDraw documentation in the DirectX SDK for more information.
DDSURFACEDESC
A structure that contains a description of the surface to be created. This structure is passed to the IDirectDraw2::CreateSurface method. The relevant members differ for each potential type of surface. See the DirectDraw documentation in the DirectX SDK for more information.
DDVIDEOPORTCONNECT
A structure that describes a video port connection. See the DirectX SDK documentation for more information.
DefWindowProc
A member function that calls the default window procedure to provide default processing for any window messages that an application does not process. See the Platform SDK documentation for more information.
DeleteCriticalSection
A function that releases all resources used by an unowned critical section object. See the Platform SDK documentation for more information.
DIBSECTION
A structure that contains information about a device-independent bitmap created by calling the CreateDIBSection function. See the Platform SDK documentation for more information.
DirectDraw
DirectDraw® is a DirectX® SDK component that enables you to directly manipulate display memory, the hardware blitter, hardware overlay support, and flipping surface support. See the DirectX SDK for more information.
DirectDrawClipper
The object that DirectDraw uses to manage clip lists. A clip list is a series of rectangles that describes the visible areas of the surface. A DirectDrawClipper object can be attached to any surface. A window handle can also be attached to a DirectDrawClipper object, and DirectDraw updates the DirectDrawClipper clip list with the clip list from the window as it changes. See the DirectX SDK for more information.
DirectDrawCreate
A function that creates an instance of a DirectDraw object. See the DirectX SDK for more information.
DirectDrawEnumerate
A function that enumerates the DirectDraw objects installed on the system. See the DirectX SDK for more information.
DirectDrawSurface
An object that represents an area in memory that holds data to be displayed on the monitor as images are moved to other surfaces. See "Surfaces" in the "DirectDraw Essentials" section of the DirectX SDK for more information.
DispatchMessage
A function that dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the GetMessage function. See the Platform SDK documentation for more information.
DISPPARAMS
A structure used by IDispatch::Invoke to contain the arguments passed to a method or property. See the Platform SDK documentation for more information.
DllCanUnloadNow
A function that determines whether the DLL that implements this function is in use. If not, the caller can safely unload the DLL from memory. See the Platform SDK documentation for more information.
DllGetClassObject
A function that is the entry point used by C++ file and stream handlers to create an instance of the handler. See the Platform SDK documentation for more information.
DllRegisterServer
A function that instructs an in-process server to create its registry entries for all classes supported in this server module. See the Platform SDK documentation for more information.
DllUnregisterServer
A function that instructs an in-process server to remove only those entries created through DllRegisterServer. See the Platform SDK documentation for more information.
double
The double keyword designates a 64-bit floating-point number. See the Platform SDK documentation for more information.
DWORD
A 32-bit unsigned integer or the address of a segment and its associated offset. See the Platform SDK documentation for more information.
enum
An enumerated type is a user-defined type consisting of a set of named constants called enumerators. See the Platform SDK documentation for more information.
Err object
A Visual Basic object that contains information about run-time errors. When a run-time error occurs, the Err object's properties are filled with information that identifies the error. To generate a run-time error in your Visual Basic code, use the Raise method. See Microsoft Visual Basic® documentation for more information.
FAILED
A function that provides a generic test for failure on any status value. Negative numbers indicate failure. See the Platform SDK for more information.
FILETIME
A structure that holds an unsigned 64-bit date and time value for a file. This value represents the number of 100-nanosecond units since the beginning of January 1, 1601. See the Platform SDK documentation for more information.
FOURCC
A Four-Character Code used to identify Resource Interchange File Format (RIFF) chunks. A FOURCC is a 32-bit quantity represented as a sequence of one to four ASCII alphanumeric characters, padded on the right with blank characters. RIFF (Resource Interchange File Format) is a specification used to define standard formats for multimedia files and to prevent compatibility problems that often occur when file-format definitions change over time. Because each piece of data in the file is identified by a standard header, an application that does not recognize a given data element can skip over the unknown information. See the Platform SDK documentation for more information.
GdiFlush
A function that flushes the calling thread's current batch. Batching enhances drawing performance by minimizing the amount of time needed to call GDI drawing functions that return Boolean values.
GetClassFile
A function that supplies the CLSID associated with the given file name. See the Platform SDK documentation for more information.
GetClientRect
A function that retrieves the coordinates of a window's client area. See the Platform SDK documentation for more information.
GetDDInterface
An IDirectDrawSurface3 method that retrieves an interface to the DirectDraw object that was used to create the surface. See the DirectX SDK for more information.
GetLastError
A function that returns the calling thread's last-error code value. See the Platform SDK documentation for more information.
GetMessage
The GetMessage function retrieves a message from the calling thread's message queue and places it in the specified structure.
GetOpenFileName
A function that creates an Open common dialog box that enables the user to specify the drive, directory, and the name of a file or set of files to open. See the Platform SDK documentation for more information.
GetSystemPaletteEntries
A function that retrieves a range of palette entries from the system palette that is associated with the specified device context. See the Platform SDK documentation for more information.
GetWindowLong
A function that retrieves information about the specified window. It also retrieves the 32-bit (long) value at the specified offset into a window's extra window memory. See the Platform SDK documentation for more information.
HANDLE
The handle of an object. See the Platform SDK documentation for more information.
HBITMAP
The handle of a bitmap. See the Platform SDK documentation for more information.
Win32 HRESULT
A value returned from a function call to an interface, consisting of a severity code, context information, a facility code, and a status code that describes the result. See the Platform SDK documentation for more information.
IBindCtx
An interface that provides access to a bind context, which is an object that stores information about a particular moniker binding operation. See the Platform SDK for more information.
ICAbout
A macro that notifies a video compression driver to display its About dialog box. See the Video for Windows Development Kit version 1.1 for more information.
ICConfigure
A macro that notifies a video compression driver to display its configuration dialog box. See the Video for Windows Development Kit version 1.1 for more information.
IClassFactory
An interface that contains two methods intended to deal with an entire class of objects, and so is implemented on the class object for a specific class of objects (identified by a CLSID). The first method, CreateInstance, creates an uninitialized object of a specified CLSID, and the second, LockServer, locks the object's server in memory, allowing new objects to be created more quickly. See the Platform SDK documentation for more information.
IClassFactory::CreateInstance
A method that creates an uninitialized object. See the Platform SDK documentation for more information.
ICSendMessage
A function that sends a message to a compressor. See the Video for Windows Development Kit version 1.1 for more information.
ICGetState
A macro that queries a video compression driver to return its current configuration in a block of memory. You can use this macro or explicitly call the ICM_GETSTATE message. See the Platform SDK for more information.
IDataObject
An interface that specifies methods that enable data transfer and notification of changes in data. See the Platform SDK for more information.
IDirectDraw
Applications use the methods of this interface to create DirectDraw objects and work with system-level variables. See the DirectX SDK for more information.
IDirectDraw::Compact
A method that moves all of the pieces of surface memory on the display card to a contiguous block to make the largest single amount of free memory available. See IDirectDraw2::Compact in the DirectX SDK for more information.
IDirectDraw::CreateClipper
A method that creates a DirectDrawClipper object. See IDirectDraw2::CreateClipper the DirectX SDK for more information.
IDirectDraw::CreatePalette
A method that creates a DirectDrawPalette object for this DirectDraw object. See IDirectDraw2::CreatePalette in the DirectX SDK for more information.
IDirectDraw::CreateSurface
A method that creates a DirectDrawSurface object for the DirectDraw object. See IDirectDraw2::CreateSurface in the DirectX SDK for more information.
IDirectDraw::DuplicateSurface
A method that duplicates a DirectDrawSurface object. See IDirectDraw2::DuplicateSurface in the DirectX SDK for more information.
IDirectDraw::EnumSurfaces
A method that enumerates all of the existing or possible surfaces that meet the search criterion specified. See IDirectDraw2::EnumSurfaces in the DirectX SDK for more information.
IDirectDraw::FlipToGDISurface
A method that makes the surface that GDI writes to the primary surface. See IDirectDraw2::FlipToGDISurface in the DirectX SDK for more information.
IDirectDraw::GetCaps
A method that fills in the capabilities of the device driver for the hardware and the hardware-emulation layer (HEL). See IDirectDraw2::GetCaps in the DirectX SDK for more information.
IDirectDraw::GetDisplayMode
A method that retrieves the current display mode. See IDirectDraw2::GetDisplayMode in the DirectX SDK for more information.
IDirectDraw::GetFourCCCodes
A method that retrieves the FOURCC codes supported by the DirectDraw object. This method can also retrieve the number of codes supported. See IDirectDraw2::GetFourCCCodes in the DirectX SDK for more information.
IDirectDraw::GetGDISurface
A method that retrieves the DirectDrawSurface object that currently represents the surface memory that GDI is treating as the primary surface. See IDirectDraw2::GetGDISurface in the DirectX SDK for more information.
IDirectDraw::GetMonitorFrequency
A method that retrieves the frequency of the monitor being driven by the DirectDraw object. See IDirectDraw2::GetMonitorFrequency in the DirectX SDK for more information.
IDirectDraw::EnumDisplayModes
A method that enumerates all the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description. See IDirectDraw2::EnumDisplayModes in the DirectX SDK for more information.
IDirectDraw::GetScanLine
A method that retrieves the scan line that is being drawn on the monitor. See IDirectDraw2::GetScanLine in the DirectX SDK for more information.
IDirectDraw::GetVerticalBlankStatus
A method that retrieves the status of the vertical blank. See IDirectDraw2::GetVerticalBlankStatus in the DirectX SDK for more information.
IDirectDraw::Initialize
A method that initializes the DirectDraw object that was created by using the COM CoCreateInstance function. See IDirectDraw2::Initialize in the DirectX SDK for more information.
IDirectDraw::RestoreDisplayMode
A method that resets the mode of the display device hardware for the primary surface to what it was before the IDirectDraw2::SetDisplayMode method was called. See IDirectDraw2::RestoreDisplayMode in the DirectX SDK for more information.
IDirectDraw::SetCooperativeLevel
A method that determines the application's top-level behavior. See IDirectDraw2::SetCooperativeLevel in the DirectX SDK for more information.
IDirectDraw::SetDisplayMode
A method that sets the mode of the display-device hardware. See IDirectDraw2::SetDisplayMode in the DirectX SDK for more information.
IDirectDraw::WaitForVerticalBlank
A method that helps the application synchronize itself with the vertical-blank interval. See IDirectDraw2::WaitForVerticalBlank in the DirectX SDK for more information.
IDirectDraw2
Applications use the methods of this interface to create DirectDraw objects and work with system-level variables. See the DirectX SDK for more information.
IDirectDraw2::CreateSurface
A method that creates a DirectDrawSurface object for the DirectDraw object. See the DirectX SDK for more information.
IDirectDraw2::SetCooperativeLevel
A method that determines the application's top-level behavior. See the DirectX SDK for more information.
IDirectDrawClipper
Applications use the methods of this interface to manage clip lists. See the DirectX SDK for more information.
IDirectDrawClipper::SetHWnd
A method that sets the window handle that will obtain the clipping information. See the DirectX SDK for more information.
IDirectDrawSurface
An interface used to create DirectDrawSurface objects and work with system-level variables. See IDirectDrawSurface3 in the DirectX SDK for more information.
IDirectDrawSurface::AddAttachedSurface
A method that attaches a surface to another surface. See IDirectDrawSurface3::AddAttachedSurface in the DirectX SDK for more information.
IDirectDrawSurface::Blt
A method that performs a bit block transfer. See IDirectDrawSurface3::Blt in the DirectX SDK for more information.
IDirectDrawSurface::BltBatch
A method that performs a sequence of IDirectDrawSurface3::Blt operations from several sources to a single destination. See IDirectDrawSurface3::BltBatch in the DirectX SDK for more information.
IDirectDrawSurface::BltFast
A method that performs a source copy blit or transparent blit by using a source color key or destination color key. See IDirectDrawSurface3::BltFast in the DirectX SDK for more information.
IDirectDrawSurface::DeleteAttachedSurface
A method that detaches two attached surfaces. The detached surface is not released. See IDirectDrawSurface3::DeleteAttachedSurface in the DirectX SDK for more information.
IDirectDraw3::CreateClipper
A method that creates a DirectDrawClipper object. See IDirectDraw2::CreateClipper in the DirectX SDK for more information.
IDirectDrawSurface::EnumAttachedSurfaces
A method that enumerates all the surfaces attached to a given surface. See IDirectDrawSurface3::EnumAttachedSurfaces in the DirectX SDK for more information.
IDirectDrawSurface::EnumOverlayZOrders
A method that enumerates the overlay surfaces on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order. See IDirectDrawSurface3::EnumOverlayZOrders in the DirectX SDK for more information.
IDirectDrawSurface::Flip
A method that makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface. See IDirectDrawSurface3::Flip in the DirectX SDK for more information.
IDirectDrawSurface::GetAttachedSurface
A method that obtains the attached surface that has the specified capabilities. See IDirectDrawSurface3::GetAttachedSurface in the DirectX SDK for more information.
IDirectDrawSurface::GetBltStatus
A method that obtains the blitter status. See IDirectDrawSurface3::GetBltStatus in the DirectX SDK for more information.
IDirectDrawSurface::GetCaps
A method that retrieves the capabilities of the surface. These capabilities are not necessarily related to the capabilities of the display device. See IDirectDrawSurface3::GetCaps in the DirectX SDK for more information.
IDirectDrawSurface::GetClipper
A method that retrieves the DirectDrawClipper object associated with this surface. See IDirectDrawSurface3::GetClipper in the DirectX SDK for more information.
IDirectDrawSurface::GetColorKey
A method that retrieves the color key value for the DirectDrawSurface object. See IDirectDrawSurface3::GetColorKey in the DirectX SDK for more information.
IDirectDrawSurface::GetDC
A method that creates a GDI-compatible handle of a device context for the surface. See IDirectDrawSurface3::GetDC in the DirectX SDK for more information.
IDirectDrawSurface::GetFlipStatus
A method that indicates whether the surface has finished its flipping process. See IDirectDrawSurface3::GetFlipStatus in the DirectX SDK for more information.
IDirectDrawSurface::GetOverlayPosition
A method that retrieves the display coordinates of the surface. See IDirectDrawSurface3::GetOverlayPosition in the DirectX SDK for more information.
IDirectDrawSurface::GetPalette
A method that retrieves the DirectDrawPalette object associated with this surface and increments the reference count of the returned palette. See IDirectDrawSurface3::GetPalette in the DirectX SDK for more information.
IDirectDrawSurface::GetPixelFormat
A method that retrieves the color and pixel format of the surface. See IDirectDrawSurface3::GetPixelFormat in the DirectX SDK for more information.
IDirectDrawSurface::GetSurfaceDesc
A method that retrieves a DDSURFACEDESC structure that describes the surface in its current condition. See IDirectDrawSurface3::GetSurfaceDesc in the DirectX SDK for more information.
IDirectDrawSurface::Initialize
A method that initializes a DirectDrawSurface object. See IDirectDrawSurface3::Initialize in the DirectX SDK for more information.
IDirectDrawSurface::IsLost
A method that determines if the surface memory associated with a DirectDrawSurface object has been freed. See IDirectDrawSurface3::IsLost in the DirectX SDK for more information.
IDirectDrawSurface::Lock
A method that obtains a pointer to the surface memory. See IDirectDrawSurface3::Lock in the DirectX SDK for more information.
IDirectDrawSurface::ReleaseDC
A method that releases the handle of a device context previously obtained by using the IDirectDrawSurface3::GetDC method. See IDirectDrawSurface3::ReleaseDC in the DirectX SDK for more information.
IDirectDrawSurface::Restore
A method that restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface object has been freed. See IDirectDrawSurface3::Restore in the DirectX SDK for more information.
IDirectDrawSurface::SetClipper
A method that attaches a DirectDrawClipper object to a DirectDrawSurface object. See IDirectDrawSurface3::SetClipper in the DirectX SDK for more information.
IDirectDrawSurface::SetColorKey
A method that sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per surface basis. See IDirectDrawSurface3::SetColorKey in the DirectX SDK for more information.
IDirectDrawSurface::SetOverlayPosition
A method that changes the display coordinates of an overlay surface. See IDirectDrawSurface3::SetOverlayPosition in the DirectX SDK for more information.
IDirectDrawSurface::SetPalette
A method that attaches the specified DirectDrawPalette object to a surface. The surface uses this palette for all subsequent operations. The palette change happens immediately, without regard to refresh timing. See IDirectDrawSurface3::SetPalette in the DirectX SDK for more information.
IDirectDrawSurface::Unlock
A method that notifies DirectDraw that the direct surface manipulations are complete. See IDirectDrawSurface3::Unlock in the DirectX SDK for more information.
IDirectDrawSurface::UpdateOverlay
A method that repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY value set. See IDirectDrawSurface3::UpdateOverlay in the DirectX SDK for more information.
IDirectDrawSurface::UpdateOverlayDisplay
A method that repaints the rectangles in the dirty rectangle list of all active overlays. See IDirectDrawSurface3::UpdateOverlayDisplay in the DirectX SDK for more information.
IDirectDrawSurface::UpdateOverlayZOrder
A method that sets the z-order of an overlay. See IDirectDrawSurface3::UpdateOverlayZOrder in the DirectX SDK for more information.
IDirectDrawSurface3::Blt
A method that performs a bit block transfer. See the DirectX SDK for more information.
IDirectSound
Applications use the methods of this interface to create DirectSound objects and set up the environment. See the DirectX SDK for more information.
IDirectSoundBuffer
Applications use the methods of this interface to create DirectSoundBuffer objects and set up the environment. See the DirectX SDK for more information.
IDispatch
An interface that exposes objects, methods, and properties to Automation programming tools and other applications. A dual interface derives from IDispatch and uses only Automation-compatible types. Like the IDispatch interface, a dual interface supports early and late binding. However, a dual interface differs in that it also supports vtable binding. See the Platform SDK documentation for more information.
IDispatch::GetIDsOfNames
A method that maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs (dispatch identifiers), which can be used on subsequent calls to IDispatch::Invoke. See the Platform SDK documentation for more information.
IDispatch::GetTypeInfo
A method that retrieves the type information for an object, which can then be used to get the type information for an interface. See the Platform SDK documentation for more information.
IDispatch::GetTypeInfoCount
A method that retrieves the number of type information interfaces that an object provides (either 0 or 1). See the Platform SDK documentation for more information.
IDispatch::Invoke
A method that provides access to properties and methods exposed by an object. See the Platform SDK documentation for more information.
IEnumMoniker
An interface used to enumerate the components of a moniker or to enumerate the monikers in a table of monikers. See the Platform SDK documentation for more information.
IEnumVARIANT
A dispatch interface that provides a way to iterate over collection objects. See the Platform SDK documentation for more information.
IEnumXXXX
A set of enumeration interfaces that enable you to enumerate the number of items of a given type that an object maintains. There is one interface for each type of item. To use these interfaces, the client asks an object that maintains a collection of items to create an enumerator object. The interface on the enumeration object is one of the enumeration interfaces, all of which have a name of the form IEnumItem_name. The only difference among the enumeration interfaces is what they enumerate. There must be a separate enumeration interface for each type of item enumerated. All have the same set of methods, and are used in the same way. See the Platform SDK documentation for more information.
IMoniker
An interface containing methods that enable you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object's IMoniker interface can locate, activate, and get access to the identified object without having any other specific information on where the object is actually located in a distributed system. See the COM documentation in the Platform SDK for more information.
IMoniker::BindToStorage
A method that retrieves an interface pointer to the storage that contains the object identified by the moniker. Unlike IMoniker::BindToObject, this method does not activate the object identified by the moniker. See the COM documentation in the Platform SDK for more information.
IMoniker::BindToObject
A method that uses the moniker to bind to the object it identifies. The binding process involves finding the object, putting it into the running state if necessary, and supplying the caller with a pointer to a specified interface on the identified object. See the COM documentation in the Platform SDK for more information.
InitializeCriticalSection
A function that initializes a critical section object, which is an object used to synchronize the threads of a single process. Only one thread at a time can own a critical-section object. See the Platform SDK documentation for more information.
IPersist
An interface with one method, GetClassID, which is designed to supply the CLSID of an object that can be stored persistently in the system. You must implement the single method of IPersist in implementing any one of the other persistence interfaces: IPersistStorage, IPersistStream, or IPersistFile. You can use IPersist when all that is required is to obtain the CLSID of a persistent object, as it is used in marshaling. See the Platform SDK documentation for more information.
IPersistFile
An interface that provides methods that permit an object to be loaded from or saved to a disk file, rather than a storage object or stream. Typically, for example, you would implement IPersistFile on a linked object. See the Platform SDK documentation for more information.
IPersistMediaPropertyBag
Documentation for this interface is identical to documentation for IPersistPropertyBag found in the COM documentation in the Platform SDK except for the following additions:

1.) The Load method can return STG_E_ACCESSDENIED to indicate that the object is read-only (the AVI parser, for example does this).

2.) The Save method can return E_NOTIMPL. IPersistPropetyBag::Save does not permit this.

IPersistPropertyBag
An interface that works in conjunction with IPropertyBag and IErrorLog to define an individual property-based persistence mechanism. See the COM documentation in the Platform SDK for more information.
IPersistPropertyBag::Load
A method called by the container to load the control's properties. See the COM documentation in the Platform SDK for more information.
IPersistStream
An interface that provides methods for saving and loading objects that use a simple serial stream for their storage needs. See the Platform SDK documentation for more information.
IPersistStream::GetSizeMax
A method that returns the size, in bytes, of the stream needed to save the object. See the Platform SDK documentation for more information.
IPersistStream::IsDirty
A method that checks the object for changes since it was last saved. See the Platform SDK documentation for more information.
IPersistStream::Load
A method that initializes an object from the stream where it was previously saved. See the Platform SDK documentation for more information.
IPersistStream::Save
A method that saves an object into the specified stream and indicates whether the object should reset its dirty flag. See the Platform SDK documentation for more information.
IPropertyBag
An interface that provides an object with a property bag in which the object can persistently save its properties. See the Platform SDK documentation for more information.
IPropertyPage
An interface that provides the main features of a property page object that manages a particular page within a property sheet. See the Platform SDK documentation for more information.
IPropertyPage::Active
A method that creates the dialog box window for the property page. See the Platform SDK documentation for more information.
IPropertyPage::Apply
A method that applies current property page values to underlying objects specified through the SetObjects method. See the Platform SDK documentation for more information.
IPropertyPage::Deactivate
A method that destroys the window created with the Activate method. See the Platform SDK documentation for more information.
IPropertyPage::GetPageInfo
A method that retrieves information about the property page. See the Platform SDK documentation for more information.
IPropertyPage::Help
A method that invokes Help in response to end-user request. See the Platform SDK documentation for more information.
IPropertyPage::IsPageDirty
A method that indicates whether the property page has changed since activated or since the most recent call to the Apply method. See the Platform SDK documentation for more information.
IPropertyPage::Move
A method that positions and resizes the property page dialog box within the frame. See the Platform SDK documentation for more information.
IPropertyPage::SetObjects
A method that provides the property page with an array of IUnknown pointers for objects associated with this property page. See the Platform SDK documentation for more information.
IPropertyPage::SetPageSite
A method that initializes a property page and provides the page with a pointer to the IPropertyPageSite interface, through which the property page communicates with the property frame. See the Platform SDK documentation for more information.
IPropertyPage::Show
A method that makes the property page dialog box visible or invisible. See the Platform SDK documentation for more information.
IPropertyPage::TranslateAccelerator
A method that provides a pointer to a MSG structure that specifies a keystroke to process. See the Platform SDK documentation for more information.
IPropertyPageSite
An interface that provides the main features for a property page site object. See the Platform SDK documentation for more information.
IsBadReadPtr
A Win32 function that verifies that the calling process has read access to the specified range of memory. See the Platform SDK documentation for more information.
ISpecifyPropertyPages
An interface that indicates that an object supports property pages. See the Platform SDK documentation for more information.
ISpecifyPropertyPages::GetPages
A method that fills an array of CLSIDs for each property page that can be displayed in this object's property sheet. See the Platform SDK COM documentation for more information.
IStorage::OpenStream
A method that opens an existing stream object within this storage object using the specified access permissions in the grfMode parameter. See the Platform SDK documentation for more information.
IStream
An interface that supports reading and writing data to stream objects. See the Platform SDK documentation for more information.
ITypeInfo
An interface typically used for reading information about objects. For example, an object browser tool can use ITypeInfo to extract information about the characteristics and capabilities of objects from type libraries. See the Platform SDK documentation for more information.
LoadLibrary
A function that maps the specified executable module into the address space of the calling process. See the Platform SDK documentation for more information.
long
A keyword that designates a 32-bit integer. See the Platform SDK documentation for more information.
Long
The Visual Basic 32-bit integer. See Visual Basic documentation for more information.
LONG
A 32-bit signed integer. See the Platform SDK documentation for more information.
LONGLONG
A 64-bit signed integer. See the Platform SDK documentation for more information.
LPCTSTR
A pointer to a constant null-terminated Unicode or Windows character string. See the Platform SDK documentation for more information.
LPDDSURFACEDESC
A LONG pointer to a DDSURFACEDESC structure that contains a description of the surface to be created. See the DirectDraw documentation in the DirectX SDK for more information.
LPSTR
A pointer to a null-terminated Windows character string. See the Platform SDK documentation for more information.
LPWSTR
A pointer to a null-terminated Unicode character string. See the Platform SDK documentation for more information.
LRESULT
A 32-bit value returned from a window procedure or callback function. See the Platform SDK documentation for more information.
memcmp
A C function that compares characters in two buffers. For more information, see the Run-Time Library Reference included in the Visual C++ Developer Studio documentation, or see other books that discuss the C and C++ programming languages.
MainAVIHeader
A structure that contains global information for the entire AVI file. See the Platform SDK documentation for more information.
MoveWindow
A function that changes the position and dimensions of the specified window. See the Platform SDK documentation for more information.
MSG
A structure that contains message information from a thread's message queue. See the Platform SDK documentation for more information.
MsgWaitForMultipleObjects
A function that determines whether the wait criteria have been met. See the Platform SDK documentation for more information.
MultiByteToWideChar
A function that maps a character string to a wide-character (Unicode) string. See the Platform SDK documentation for more information.
Number property
A property used to determine the nature of an error that occurred on a remote server or in the ODBC (Open Database Connectivity) interface. See Visual Basic documentation for more information.
OleCreatePropertyFrame
A function that invokes a new property frame; that is, a property sheet dialog box, whose parent is hwndOwner, where the dialog is positioned at the point (x,y) in the parent window and has the caption lpszCaption. See the Platform SDK documentation for more information.
OPENFILENAME
A structure that contains information that the GetOpenFileName and GetSaveFileName functions use to initialize an Open or Save As common dialog box. See the Platform SDK documentation for more information.
OutputDebugString
A function that sends a string to the debugger for the current application. See the Platform SDK documentation for more information.
PALETTEENTRY
A structure that specifies the color and usage of an entry in a logical color palette. A logical palette is defined by a LOGPALETTE structure. See the Platform SDK documentation for more information.
PCMWAVEFORMAT
A structure that describes the data format for PCM waveform-audio data. See the Platform SDK documentation for more information.
PeekMessage
A function that checks a thread message queue for a message and places the message (if any) in the specified structure. See the Platform SDK documentation for more information.
PostMessage
A function that places (posts) a message in the message queue associated with the thread that created the specified window, and then returns without waiting for the thread to process the message. See the Platform SDK documentation for more information.
printf
A C function that prints formatted output to the standard output stream. For more information, see the Run-Time Library Reference included in the Visual C++ Developer Studio documentation, or see other books that discuss the C and C++ programming languages.
PROPPAGEINFO
A structure that contains parameters used to describe a property page to a property frame. See the Platform SDK documentation for more information.
RECT
A structure that defines the coordinates of the upper-left and lower-right corners of a rectangle. See the Platform SDK documentation for more information.
ReleaseSemaphore
A function that increases the count of the specified semaphore object by a specified amount. See the Platform SDK documentation for more information.
RGBQUAD
A structure that describes a color consisting of relative intensities of red, green, and blue. See the Platform SDK documentation for more information.
ScaleHeight
A property that returns or sets the number of units for the vertical measurement of the interior of an object when using graphics methods or when positioning controls. See Visual Basic documentation for more information.
ScaleWidth
A property that retrieves or sets the number of units for the horizontal measurement of an object's interior when using graphics methods or when positioning controls. See Visual Basic documentation for more information.
SendMessage
A function that sends the specified message to a window or windows. See the Platform SDK documentation for more information.
SetDIBColorTable
A function that sets RGB (red, green, blue) color values in a range of entries in the color table of the device-independent bitmap (DIB) that is selected into a specified device context. See the Platform SDK documentation for more information.
SetDIBitsToDevice
A function that sets the pixels in the specified rectangle on the device that is associated with the destination device context using color data from a device-independent bitmap (DIB). See the Platform SDK documentation for more information.
SetDlgItemText
A function that sets the title or text of a control in a dialog box. See the Platform SDK documentation for more information.
SetParent
A function that changes the parent window of the specified child window. See the Platform SDK documentation for more information.
SetWindowLong
A function that changes an attribute of the specified window. The function also sets a 32-bit (long) value at the specified offset into the extra window memory of a window. See the Platform SDK documentation for more information.
ShowWindow
A function that sets the specified window's show state. See the Platform SDK documentation for more information.
SIZE
A structure that specifies the width and height of a rectangle. See the Platform SDK documentation for more information.
sscanf
A C function that reads formatted data from a string. For more information, see the Run-Time Library Reference included in the Visual C++ Developer Studio documentation, or other books that discuss the C and C++ programming languages.
StgOpenStorage
A function that opens an existing root storage object in the file system. You can use this function to open compound files, but you can't use it to open directories, files, or summary catalogs. See the Platform SDK documentation for more information.
StretchBlt
A function that copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary. Windows stretches or compresses the bitmap according to the stretching mode currently set in the destination device context. See the Platform SDK documentation for more information.
StretchDIBits
A function that copies the color data for a rectangle of pixels in a device-independent bitmap (DIB) to the specified destination rectangle. If the destination rectangle is larger than the source rectangle, this function stretches the rows and columns of color data to fit the destination rectangle. If the destination rectangle is smaller than the source rectangle, this function compresses the rows and columns by using the specified raster operation. See the Platform SDK documentation for more information.
SUCCEEDED
A function that provides a generic test for success on any status value. Non-negative numbers indicate success. See the Platform SDK documentation for more information.
SysAllocString
A function that allocates a new string and copies the passed string into it. See the Platform SDK documentation for more information.
SysFreeString
A function that frees a previously allocated string. See the Platform SDK documentation for more information.
timeBeginPeriod
A function that sets the minimum timer resolution for an application or device driver. See the Platform SDK documentation for more information.
timeGetTime
A function that retrieves the system time, in milliseconds. The system time is the time elapsed since Windows was started. See the Platform SDK documentation for more information.
timeSetEvent
A function that starts a specified timer event. The multimedia timer runs in its own thread. After the event is activated, it calls the specified callback function. See the Platform SDK documentation for more information.
TranslateMessage
A function that translates virtual-key messages into character messages. The character messages are posted to the calling thread's message queue, to be read the next time the thread calls the GetMessage or PeekMessage function. See the Platform SDK documentation for more information.
TXTDT_MG
A structure that can contain text descriptions of the video. See Section 4.1.6 and Annex A of the DVD-Video specification for more information. To obtain a copy of the specification, contact Toshiba Corporation at 1-1, Shibaura 1-Chrome, Minato-ku, Tokyo 105-01, Japan, Tel. +81-3-5444-9580, Fax. +81-3-5444-9430.
videoDialog
A function that displays a dialog box used to set configuration parameters for a video capture device driver. See the Video for Windows Development Kit version 1.1 for more information.
videoMessage
A function that sends messages to a video capture device driver. See the Video for Windows Development Kit version 1.1 for more information.
WaitForMultipleObjects
A Win32 function that determines whether wait criteria have been met. If the criteria have not been met, the calling thread enters a wait state. The function returns when any one or all of the specified objects are in the signaled state, or when the time-out interval elapses. See the Platform SDK documentation for more information.
WaitForSingleObject
A Win32 function that checks the current state of the specified object. If the object's state is nonsignaled, the calling thread enters a wait state. The function returns when returns when the specified object is in the signaled state, or when the time-out interval elapses. See the Platform SDK documentation for more information.
WAVEFORMAT
A structure that describes the format of waveform-audio data. See the Platform SDK documentation for more information.
WinMain
A function called by the system as the initial entry point for a Win32-based application. See the Platform SDK documentation for more information.
ZeroMemory
A function that fills a block of memory with zeros. See the Platform SDK documentation for more information.


Glossary

This glossary primarily defines terms related to Microsoft® DirectShow™. See the Microsoft Windows NT® or Microsoft Windows 95® online Help for additional information.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

advise
A call that defines a point in time when the caller wants to be notified. See also periodic advise.
application notification
An event that the controlling application retrieves from the filter graph manager.
asychronous reader filter
A file source filter that does no parsing on its own, but just reads data off the disk for playing back media files. This is the source filter used for most DirectShow™ filter graphs.
ATR
Audio tape recorder.


B

backing object
In multimedia streaming, the backing object is either the DirectDraw surface for video or the IAudioData object for audio.
bi-phase mark
A method of encoding digital data within an analog signal. Bi-phase mark code is self-clocking (signal alternates on entry and exit) and not polarity conscious (identical values can be on top or bottom). Because it can be read over a wide range of play speeds, it is used for LTC signals. (originally known as Manchester-1 code).

Bi-phase mark code diagram

blackburst
A video signal that can be used to synchronize multiple video sources. Blackburst contains the vertical sync, horizontal sync, and the chroma burst information, but no active picture information.
blit
Bit block transfer. Used to transfer all or part of a bitmap from a source such as memory or the screen, to a destination such as another memory or display surface.
bob
A method of displaying interlaced video fields on a progressive monitor. See field for a more detailed description. See also weave.


C

chroma burst
Provides color information about the active line of video to the color decoder.
class factory
A COM object that implements the IClassFactory interface and that creates one or more instances of an object identified by a given class identifier (CLSID).
class factory template
A template that contains information about a class that is vital to its framework. The DirectShow COM framework developers to provide a class factory template for each C++ class implementing a COM object. Class factory templates are defined using two global variables (g_Templates and g_cTemplates). For more information, see COM Objects in DirectShow.
codec
Compressor/decompressor. See compression filter.
compression filter
A specialized type of transform filter. Compression filters (compressors) accept data, use a compression scheme to transform the data, and pass the compressed data downstream.
cutlist
A collection of cutlist elements (clips). When you play a cutlist, it appears as if you're playing back one media file, but it is actually composed of clips from one or more media files. See About Cutlists for more information.
cutlist element
A piece (clip) from a media file. Cutlist elements make up a cutlist. See About Cutlists for more information.


D

debug build
The largest and slowest type of build, but one that provides better facilities for debugging new code and tracking problems.
debug level
A DWORD value indicating the relative importance of a debug output, where zero is the most important level.
downstream filter
The next filter in line to receive data from an upstream filter. An upstream filter sends data from its output pin to the connected input pin of the downstream filter.


E

edit decision list
Also known as an EDL. It is a list of items called events that describes a video sequence, audio sequence, or both, using SMPTE timecode to identify the video and audio source material. A sample event might look like this:

001 ABC123 V C 03:01:00:00 03:02:20:15 01:00:00:00 01:01:20:15

This means event 001 uses only video from reel ABC123, frames 03:01:00:00 up to but not including 03:02:20:15, and put it on a record tape as a straight cut starting at frame 01:00:00:00.

effect filter
A filter that applies an effect to media data, but doesn't change the media type.
end-of-stream protocol
A protocol that defines how filters generate and process end-of-stream information and how the filter graph manager is notified.
error detection and reporting protocol
A protocol that defines how errors are handled by filters and propagated to the filter graph manager.
event notification
A system-defined event sent from a filter to the filter graph manager. Filters pass these events to the filter graph manager by using the IMediaEventSink::Notify method, and the application retrieves them with the IMediaEvent::GetEvent method. For more information, see Event Notification Codes.


F

field
A portion of an interlaced video frame. NTSC provides a series of 59.94 interlaced fields per second, each separated by 1/59.94th of a second, with the scan lines of the even-numbered fields falling spatially halfway between the scan lines of the odd-numbered fields. No two fields are ever displayed on a television at the same time. You always look at either an even field or an odd field. Two interlaced video display methods are bob and weave.

Bob displays only one field at a time. In this mode, DirectDraw automatically shifts every other field by one half pixel vertically, and then stretches each field by a factor of two vertically.

Weave displays two successive fields at a time, where the resulting displayed image has horizontal scan lines that are alternately taken from the two fields. The fields are "woven" in a single frame. The top scan line of the displayed frame is the top scan line of the first field, the second displayed scan line is the top scan line of the second field, the third displayed scan line is the second scan line in the first field, and so forth.

The following diagram shows how fields are displayed in an interlaced source, using the bob and weave interlaced video display methods. In the diagram, top field refers to the odd, or first, field, and bottom field refers to the even, or second, field.

Field-based video diagram of interlaced source, bob, and weave

file writer
The section of a filter graph that consists of the multiplexer and file writer filters.
filter
A key component in the DirectShow architecture, a filter is a COM object that supports DirectShow interfaces or base classes. It might operate on streams of data in a variety of ways, such as reading, copying, modifying, or writing the data to a file. Sources, transform filters, and renderers are all particular types of filters. A filter contains pins that it uses to connect to other filters.
filter graph
A collection of filters. Typically, a filter graph contains filters that are connected to perform a particular operation, such as playing back a media file, or capturing video from a VCR to the hard disk.
Filter Graph Editor
A graphical tool included with the DirectShow SDK that creates and manages filter graphs. It enables you to easily create filter graphs by inserting filters, clicking, and dragging to form connections.
filter graph manager
A component that oversees the connection of filters in a filter graph, and controls the media stream's data flow. Filters must be connected in the proper order, and the data stream must be started and stopped in the proper order. The filter graph manager does this, and can also search for a set of filters that will render a particular media type and build its filter graph. When an application starts, pauses, or stops the media stream, plays for a particular duration or seeks to a particular point in the stream, the filter graph manager calls the appropriate methods on the filters to implement this stream control.
flushing protocol
A protocol that defines how filters flush data through the filter graph.
format type
A GUID value that indicates what a format block contains. DirectShow defines a number of major types, for example, the video type. These major types have a format block, such as VIDEOINFOHEADER, that describes the media data. The format block for a particular media type is specified by a GUID in the AM_MEDIA_TYPE structure. This GUID is called the format type. If the format block contains VIDEOINFOHEADER, the format type GUID will be FORMAT_VideoInfo.
frame blitting
Blitting (bit block transferring) media data to the client area of the application window on the primary surface.


G

GUID
A globally unique identifier used to uniquely identify objects, such as interfaces and plug-in distributors. Class identifiers (CLSIDs) and interface identifiers (IIDs) are GUIDs. You can generate GUIDs with the command-line utility program, UUIDGEN, provided with the Win32® SDK, or with the Microsoft Foundation Class Library (MFC) sample application, GUIDGEN, provided with Microsoft Visual C++®.


DirectShow Animated Header -- H DirectShow Animated Header -- H * Microsoft DirectShow SDK
  * Previous Topic: G
  * Next Topic: I

H

hue
Color produced by visible light.


I

input pin
A pin that accepts data into the filter.
interlace
Raster scan involving frames that are composed of two fields. See also bob and weave.
interleaving
The arrangement of corresponding video frames and audio samples in a file. Typically, one or more frames of video data are intermixed in the file with a certain number of samples of audio data. The data sequence is audio, followed by video, followed by audio, followed by video, and so on, rather than all audio data followed by all video data. The way a file is interleaved affects playback efficiency and the ability to stream the file.


K

kernel mode
The processor mode that allows full, unprotected access to the system. A driver or thread running in kernel mode has access to system memory and hardware.
keyframe
A frame of video data that contains all the data necessary to construct that frame. In contrast, delta frames contain data relating to changes from the last keyframe and do not contain enough information by themselves to construct a complete frame.


L

letterbox
DVD-Video display format in which the video is sized as large as possible inside the display window, without any cropping or stretching. See DVD_PREFERRED_DISPLAY_MODE.
Linear editing
A method of editing program material where the final product is built cut by cut in a sequential or linear fashion. Changes to any edit require re-recording all of the succeeding edits or using the recorded master as a source. These systems are found at the very low end and very high end of the editing equipment market. They are comprised of a control computer, video tape recorders and switchers, and generally do not provide random access disk-based storage of source material, although connection to a digital disk recorder will provide limited random access capability.
LTC
Linear Timecode (formerly known as Longitudinal Timecode). Timecode is stored on a separate audio track and is one video frame time in duration.


M

major type
A GUID value that describes the overall class of media data for a data stream. Typical values are MEDIATYPE_Video, MEDIATYPE_Audio, MEDIATYPE_Text, and MEDIATYPE_Midi.
merit
A value that controls the order in which the filter graph manager accesses your filter as a result of a call to IGraphBuilder::Connect, IGraphBuilder::Render, or IGraphBuilder::RenderFile. Possible merit values include MERIT_PREFERRED, MERIT_NORMAL, MERIT_UNLIKELY, and MERIT_DO_NOT_USE. See IFilterMapper::RegisterFilter for a description of merit values. When searching for a rendering configuration, the filter graph manager uses the filter mapper, which reads the registry and determines the types of filters available. The filter graph manager then attempts to link filters that accept that data type until it reaches a rendering filter. A merit value is registered with each filter and, of the filters that might be capable of handling the data, the filters with the highest merit are tried first. The filter graph manager uses other criteria in the registration to choose between filters with equal merit. AMovieSetupRegisterFilter2 registers a filter's merit, pins, and media types in the registry by using the IFilterMapper2 interface.
method
A predefined interface function.
media sample protocol
A protocol that defines the way that media samples are allocated and passed between filters.
media time
A term used to refer to positions within a seekable medium. Media time can be expressed in a variety of units, and indicates a position within the data in the file.
minidriver
A hardware-specific DLL that uses a Microsoft-provided class driver to accomplish most actions through function calls and provides only device-specific controls. Under the Windows Driver Model (WDM), the minidriver registers each adapter with the class driver, which creates the device object. The minidriver uses the class driver's device object to make system calls.
minor type
See subtype (media type).
moniker
An object that implements the IMoniker interface. A moniker acts as a name that uniquely identifies a COM object. In the same way that a path identifies a file in the file system, a moniker identifies a COM object in the directory namespace.


N

new segment protocol
A protocol that defines a way to present start and stop times and data rate information to the filter in advance of the data, so that a filter can adjust its processing accordingly.
nonlinear editing
A method of editing program material where the final output product is not generated until all editorial decisions are made. All edit decisions are maintained in an edit list that drives a real-time preview. No recording is made until the edit decisions are finalized. This necessitates a real-time, multievent playback mechanism using digital video and audio stored on disk drives. These systems are used primarily for offline editing, although higher-end systems with broadcast-quality video are now available.
NTSC
National TV Systems Committee analog composite color television standard. Uses a rate of 29.97 frames per second and 59.94 fields per second. North America, Japan, and many other countries use NTSC. See also PAL and SECAM.


O

object register
The list of objects in a debug build that have been created but not yet destroyed in the CBaseObject class and classes derived from it.
offline editing
The process of using low-cost, nonoutput quality video and audio equipment to make editorial and creative decisions. This process results in an edit decision list describing the edits, and it is usually stored on a floppy disk or transferred to other systems over a network.
online editing
The process of using high-quality mastering equipment to produce a finished program. When fed by an edit decision list generated by an offline system, the process can be largely automated, although some high-budget programs bypass the offline process.
output pin
A pin that provides data to other filters.


P

PAL
Analog composite color television standard, with a rate of 25 frames per second, and 50 fields per second. Much of Europe, Australia, and other parts of the world use PAL. See also NTSC and SECAM.
pan-scan
DVD-Video display format in which a 16 × 9 video is cropped for display in a 4 × 3 window, using parameters defined by the video author. See DVD_PREFERRED_DISPLAY_MODE.
parser filter
A filter that pulls information from a disk by using the asynchronous file reader filter, or from the Internet by using the URL moniker filter.
performance build
A build that adds performance measurement capabilities to a retail build.
periodic advise
A regular series of advise calls.
pin
A COM object created by the filter that represents a point of connection for a data stream on the filter. Pins provide interfaces to connect with other pins and transport data. Input pins accept data into the filter, and output pins provide data to other filters. An input pin typically exposes the IPin and IMemInputPin interfaces. An output pin typically exposes the IPin, IMediaSeeking, and IQualityControl interfaces. A source filter provides one output pin for each stream of data in the file. A typical transform filter, such as a compression/decompression (codec) filter, provides one input pin and one output pin.
plug-in distributor
A COM object that exposes a particular control interface and implements it by calling the enumerator of the filter graph manager, finding which filters expose the control interface and communicating directly with those filters. The developer generally doesn't implement these interfaces directly.
preroll
The queuing of data in advance of the desired playback time or position. Preroll improves the accuracy of playback and recording. For example, the initial audio data within AVI files is often loaded in advance of the first video data to help synchronize the video and audio data. DirectShow filters often preroll data so they are ready to play immediately. Prerolling is also important in video editing and device control, because VCRs typically position the tape to a given "preroll" distance from the point at which to record or playback so that the recording or playback occurs cleanly.
preroll time
Preroll time is the time prior to the start position at which nonrandom access devices should start rolling. See preroll.
presentation time
The stream time at which the packets of data that a filter receives should be presented downstream or rendered. When a filter graph runs, each filter is passed a start time according to the reference clock, and the packets of data that a filter receives will usually be time-stamped with the presentation time.
preview section
The portion of the filter graph from the capture filter's preview pin downstream to and including the video renderer.
primary surface
The area in memory containing the image being displayed on the monitor. In Microsoft DirectX®, the primary surface is represented by the primary DirectDrawSurface object.


Q

quality management protocol
A protocol that defines how the filter graph adapts dynamically to hardware and network conditions to increase or decrease the media data flow. The IQualityControl interface is used to send quality control notifications from a renderer to an upstream filter or directly to a designated quality control manager, if one exists. (See quality sink.) The base classes implement passing quality control notifications upstream by providing the IQualityControl interface on the output pins of filters. Quality control notification uses a Quality structure, which indicates whether the renderer is overloaded or underloaded.
quality sink
A filter object designated by the IQualityControl::SetSink method to receive quality messages. When IQualityControl::SetSink is called, the filter is instructed not to send quality control messages upstream, but rather to send them to the object passed to the SetSink method. This object is called a quality-control manager. See quality management protocol.


R

reference clock
An object that provides a clock and supports the scheduling of events according to time as counted by that clock. Any reference clock must support the IReferenceClock interface. The time of the clock can be obtained by calling the IReferenceClock::GetTime method. The time returned by GetTime is defined as a REFERENCE_TIME type and loosely represents the number of 100-nanosecond units that have elapsed since some fixed start time. The return value should generally increase at a rate of approximately one per 100 nanoseconds. In exceptional circumstances, the clock can stop for a time. (This will suspend any filter that was using the clock as a sync source.) The clock can also jump forward in exceptional circumstances.
reference time
An absolute time established by a reference clock in the filter graph. It refers to some time value outside the filter graph (for example, perhaps the time since Windows® was started). The reference time can be obtained by calling the IReferenceClock::GetTime method. The time returned is defined as a REFERENCE_TIME type and loosely represents the number of 100-nanosecond units that have elapsed since some fixed start time. Note that the reference time does not have to bear any permanent relationship to a real time. It can drift, it can drift at a changing rate, and it need not correct for such drift. In particular, it does not have to represent a count of the number of 100 nanoseconds that have passed since some arbitrary time in the past. See Understanding Time and Clocks in DirectShow for more information.
renderer
A filter that renders media data to any location that accepts media input. Most often, data is rendered to a computer monitor, sound card, or printer. Renderer filters have only input pins.
rendering filter
See renderer.
retail build
The smallest and fastest type of build, it is not as robust as a debug build.
run time
The control and a set of DLLs that enable you to play back the supported media types.


S

saturation
Color purity. For example, a color that is completely blue has a 100% saturation, while white, which is composed of all colors, has a zero saturation.
SECAM
Analog composite color television standard, with a rate of 25 frames per second, and 50 fields per second. Much of Europe, Australia, and other parts of the world use SECAM. See also NTSC and PAL.
seekable renderer
A renderer that reports EC_COMPLETE once when all seekable streams on that filter have reached the end of the stream. A seekable renderer is a renderer that supports the IMediaPosition object from the filter and has only input pins, or is a renderer whose input pins report that they are rendered. If the filters in a filter graph detect the end of the stream, the filters report it with the EC_COMPLETE event notification. The filter graph asks filters if they can report EC_COMPLETE through a seekable renderer.
servo
The electromechanical system that maintains the proper speed and phase of a VCR's video head and tape transport.
sink file
The current file into which media samples will be written.
source filter
A filter that takes data from some source such as the hard drive, network, or the Internet, and introduces it into the filter graph.
stream notification
An event that occurs in the media stream and is passed from one filter to the next.
stream time
A time that represents the time the since the filter graph was last started. By definition, stream time is equivalent to reference time minus start time when the graph is running. Stream time is relevant only within a running filter graph. When a filter graph is run, each filter is passed a start time based on the reference clock, and the packets of data that a filter receives will usually be time-stamped with the stream time.
subtype (media type)
A GUID value that describes the specific format of media data for a data stream. Typical values include MEDIASUBTYPE_MJPG, MEDIASUBTYPE_RGB8, MEDIASUBTYPE_RGB565, MEDIASUBTYPE_MPEGPacket, MEDIASUBTYPE_Avi, and MEDIASUBTYPE_WAVE. See AM_MEDIA_TYPE for more information.
sync source
See reference clock.


T

tearing
A visual rip effect that occurs when one displayed video frame contains parts of two different source video frames. It is usually caused by improper synchronization between video rendering and the graphics display. DirectShow uses double- or triple-buffered DirectDraw overlay surfaces when possible to prevent tearing.

In analog video terms, tearing occurs due to poor synchronization of a video signal at an edit point.

timecode
SMPTE timecode, more properly known as SMPTE time and control code, is a series of digital frame address values, flags, and additional data applied to a video or audio stream, and is defined in ANSI/SMPTE 12-1986. Its purpose is to provide a machine-readable address for video and audio.
time stamp
Time on a media sample indicating when it was recorded and when it should be scheduled for playback. Time stamps are measured in 100-nanosecond units (REFERENCE_TIME) and are normalized so that zero indicates when the graph is run. See Time Stamps for more information.
transform filter
A filter that takes data, processes it, and then passes it along to the next filter in the filter graph.
transform-inplace filter
A transform filter that can perform its operation in place (without copying data or altering the data's media type).
transport
The mechanism that channels audio data, video data, or both from an external device to the computer and from the computer to the external device.
trimin
The beginning time (starting position) of a cutlist element or clip within a media file. See About Cutlists for more information.
trimout
The ending time (position) of a cutlist element or clip within a media file. See About Cutlists for more information.


U

upstream filter
The filter that passes data from its output pin to the connected input pin of the next filter in the filter graph.
URL moniker filter
A source filter that reads from an Internet server.
userbits
Undefined bits in the SMPTE timecode. These bits can be used for a variety of purposes such as identifying shot and take numbers, calendar date, client code, or any other information the user wants to encode so that it travels with the source material throughout the post-production process. Often, userbits contain original film and audio tape information. This information is used to generate negative cut lists, so a theatrical film can be edited electronically.


V

VITC
Vertical Interval Timecode. Timecode information stored in a video signal's vertical blanking interval. It is usually located on one or two lines somewhere between lines 10 and 20.
vertical blanking interval
A synchronizing period in the video signal when no active picture information is transmitted.
VPE
Video port extensions. Extensions to the DirectDraw API to control the video stream from the video port, within the context of VGA memory.
VTR
Video tape recorder.


W

weave
A method of displaying interlaced video fields on a progressive monitor. See field for a more detailed description. See also bob.
wildcards
Character that is substituted to represent multiple strings. For example, "?" represents any single character, "*" represents zero or more characters, and "#" represents any single digit (0-9). Thus, Strmbas?.lib would match both Strmbasd.lib and Strmbase.lib. Strm*.lib would match Strmbasd.lib, Strmbase.lib, and Strmiids.lib.


Microsoft DirectPlay SDK

Welcome to the Microsoft® DirectPlay® Software Development Kit. DirectPlay is an API that simplifies application access to communication services. It provides a way for applications to communicate with each other independent of the underlying protocol, transport, or online service. This is especially useful for games. Real players, each on her or his own personal computer, can be gathered and launched into a game, without the game developer worrying about the connections.

For the most recent updates, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/.

Click here to go to the download page for DirectPlay.

Last Updated: March 27, 1998

About DirectPlay
Provides a brief description of the DirectPlay API.
What's New in DirectPlay 5?
Describes the new features in DirectPlay 5. These include security, improved connection, initialization, messaging, and asynchronous enumeration of sessions.
Writing a Network Application
Describes general requirements for successful network applications.
DirectPlay Overview
Describes the DirectPlay architecture, session management, player management, message management, and group management with DirectPlay. Also contains an overview of DirectPlay communications.
DirectPlay Lobby Overview
Describes the DirectPlay lobby architecture, lobby sessions, how players navigate in a lobby, and synchronized game launching. A lobby server's main use is to act as a central location where users can go to find and join sessions.
DirectPlay Providers
Describes how DirectPlay interacts with service providers and lobby providers.
Using DirectPlay
Describes how to use different aspects of DirectPlay, including working with globally unique identifiers (GUIDs), the DirectPlay interfaces, how to use callback functions, how to build lobby-aware applications, how to use messages, how to use security and authentication, how to use DirectPlay Addresses as connection shortcuts, and how to migrate from previous versions of DirectPlay. Also contains a description of the DirectPlay tools and samples.
DirectPlay Interface Overviews
Provides an overview of the IDirectPlay3 Interface and IDirectPlayLobby2 Interface interfaces, as well as previous versions of these interfaces. Also describes the difference between the Unicode and ANSI interfaces.
DirectPlay Tutorials
Contains four tutorials that provide step-by-step instructions about connecting applications with or without a lobby, overriding service provider dialog boxes, and creating a self-refreshing session list.
DirectPlay Reference
Provides detailed information about functions, callbacks, and the IDirectPlay3 Interface and IDirectPlayLobby2 Interface interface methods. Also describes the DirectPlay structures, system messages, lobby messages, defined properties, and error values.
DirectPlay Glossary
Defines basic DirectPlay terms.

Note The icon external link indicates that the link takes you to a URL that is outside the microsoft.com site; you can return to the DirectPlay site by using the Back button. Note that most of these external links point to servers that are not under Microsoft's control. Please read Microsoft's official statement regarding other servers.


About DirectPlay

The Microsoft® DirectPlay® application programming interface (API) for Microsoft Windows® 95 is a software interface that simplifies application access to communication services. DirectPlay has become a technology family that not only provides a way for applications to communicate with each other, independent of the underlying transport, protocol, or online service, but also provides this independence for matchmaking servers and game servers.

Applications (especially games) can be more compelling if they can be played against real players, and the personal computer has richer connectivity options than any game platform in history. Instead of forcing the developer to deal with the differences that each connectivity solution represents, DirectPlay provides well-defined, generalized communication capabilities. DirectPlay shields developers from the underlying complexities of diverse connectivity implementations, freeing them to concentrate on producing a great application.


What's New in DirectPlay 5?

This section discusses new features in DirectPlay® 5. For the most recent updates, including new features, additional samples, and further technical information, consult the Microsoft® DirectX® Web site at http://www.microsoft.com/DirectX/.

DirectPlay 5 has a new interface, IDirectPlay3. This interface inherits directly from IDirectPlay2 and by default behaves as IDirectPlay2. All new functionality is enabled through new methods or flags.

DirectPlay 5 supports the following new features and methods:

  • DirectPlay interface objects can be created directly by using the CoCreateInstance method. This eliminates the need to link directly to the Dplayx.dll dynamic-link library.
  • IDirectPlay3::EnumConnections enumerates the service providers and lobby providers available to the application. This method supersedes DirectPlayEnumerate.
  • IDirectPlay3::InitializeConnection initializes a DirectPlay connection. This method supersedes DirectPlayCreate.
  • The new IDirectPlayLobby2::CreateCompoundAddress method creates an address to pass to the InitializeConnection method.
  • IDirectPlay3::SecureOpen creates or joins a session on a server that requires security.
  • IDirectPlay3::CreateGroupInGroup, IDirectPlay3::AddGroupToGroup, IDirectPlay3::DeleteGroupFromGroup, and IDirectPlay3::EnumGroupsInGroup add richer group functionality and navigation. The new IDirectPlay3::GetGroupFlags and IDirectPlay3::GetGroupParent methods give ready access to additional group information.
  • IDirectPlay3::SendChatMessage enables players to chat with other players in a session or connected to a lobby server, using standardized messages.
  • IDirectPlay3::SetGroupConnectionSettings, IDirectPlay3::GetGroupConnectionSettings, and IDirectPlay3::StartSession enable synchronized application launching from a lobby server.
  • The new DPCREDENTIALS structure holds the user name, password, and domain to use when connecting to a secure server. The DPSECURITYDESC structure describes the security properties of a DirectPlay session instance.
  • The new DPCOMPOUNDADDRESSELEMENT structure describes a DirectPlay Address (Optional) data chunk that can be used to create longer DirectPlay Addresses.
  • A session host can use the new IDirectPlay3::GetPlayerAccount method and new DPACCOUNTDESC structure to obtain account information for a player logged into a secure session.
  • The new IDirectPlay3::GetPlayerFlags method gives access to a player's flag settings.

DirectPlay 5 also supports new functionality for existing DirectPlay 3 methods:

  • An application can create multiple DirectPlay objects.
  • The IDirectPlay3::SetSessionDesc method enables the host to change the session description.
  • The IDirectPlay3::EnumSessions method can now be called asynchronously and will maintain a constantly refreshing list of sessions available on the session.
  • Password protection of sessions has been improved. Specify the DPENUMSESSIONS_PASSWORDREQUIRED flag in EnumSessions to enumerate password-protected sessions (in addition to nonpassword-protected sessions). The DPSESSIONDESC2 structure will contain a flag indicating that the session needs a password. Put the password in the DPSESSIONDESC2 structure passed to the Open method to join the session.
  • Applications can override the service provider dialog boxes that prompt users for information. To prevent these dialog boxes from appearing, create a DirectPlay Address (Optional) by using the IDirectPlayLobby2::CreateAddress or IDirectPlayLobby2::CreateCompoundAddress methods and then call IDirectPlay3::InitializeConnection with this DirectPlay Address. A subsequent call to IDirectPlay3::EnumSessions will not display a dialog box prompting the user for address information.
  • A new multicast server option improves group messaging.
  • Support has been added for scalable client/server architecture applications.
  • Sessions can be hosted securely and require users to log in with a name and password.
  • Members of a secure session can send digitally signed or encrypted messages, by using the DPSEND_SIGNED and DPSEND_ENCRYPTED flags in the Send method.


Writing a Network Application

The fundamental concern when writing a networked, multiplayer application is how to propagate state information to all the computers in the session. The state of the session defines what users see on their computers and what actions they can perform. Generally, two things make up the session state: the environment and the individual users or players.

The environment consists of the objects that the players can manipulate or interact with. This can include a map of a dungeon, a racecourse, or even a document. The environment can also include computer-controlled players.

Within the environment, each player also has a state indicating the player's current properties. These can include position, velocity, energy, armor, and so on.

When a player first joins the session, the session's current state must be downloaded, including the environment and the state of the other players.

Actions performed by users or the natural progression of a game change the state of the session. When this happens, the change must be propagated to the other computers in the session through messages. There are many techniques for updating the session state, but they all depend on sending messages between computers.

When two players perform an action on the same object (like opening a door) or on each other (like swinging a sword) a conflict can arise. That is, two players are trying to do something where only one of them can succeed. In these cases, arbitration or conflict resolution is needed. There are several ways to resolve conflicts like this: The two players can communicate with each other and decide which one wins, or a special player can arbitrate all conflicts.

The actions of players change the state of a game, and conflicting actions must be resolved before the game's state can be updated. There are two fundamental ways of maintaining state in a session. The first way is called peer-to-peer. In peer-to-peer sessions, all the computers in the session have the complete state of the environment and all the players. Any change in state that happens on one computer must be propagated to all the other computers in the session. No one computer is really in charge.

The second way to maintain the session state is called client/server. In client/server sessions, one computer is designated the server, and it maintains the complete state of the game and performs conflict resolution. All the other computers in the session are clients, and they download some portion of the state from the server. When they need to change the state, they tell the server, and the server propagates the change to other clients as needed.

With DirectPlay, you can create and manage both peer-to-peer and client/server applications. DirectPlay provides all the tools needed to write a networked, multiplayer application by providing the services to manage players, send messages between players, and automatically propagate the state among all the computers.


DirectPlay Overview

This section contains general information about the DirectPlay® component. The following topics are discussed:

  • Architecture
  • Session Management
  • Player Management
  • Message Management
  • Group Management
  • Overview of DirectPlay Communications

Architecture

The DirectPlay API is a network abstraction and distributed object system that applications can be written to. The API defines the functionality of the abstract DirectPlay network, and all the functionality is available to your application regardless of whether the actual underlying network supports it. In cases where the underlying network does not support a method, DirectPlay contains all the code necessary to emulate it. Examples include group messaging and guaranteed messaging.

DirectPlay's service-provider architecture insulates the application from the underlying network it is running on. The application can query DirectPlay for specific capabilities of the underlying network, such as latency and bandwidth, and adjust its communications accordingly.

The following diagram illustrates the DirectPlay service-provider architecture.

DirectPlay service provider architecture

The first step in using DirectPlay is to select which service provider to use. The service provider determines what type of network or protocol will be used for communications. The protocol can range from TCP/IP over the Internet, to an IPX local area network, to a serial cable connection between two computers.

Use the service provider to make a connection to a point on the network. The user may need to provide additional information to make a connection, or the application can specify the connection parameters.

Connection Management Methods

DirectPlay provides two useful connection management methods:

  • IDirectPlay3::EnumConnections enumerates all the connections that are available to the application.
  • IDirectPlay3::InitializeConnection initializes a specific connection.

Session Management

A DirectPlay session is a communications channel between several computers. Before an application can start communicating with other computers, it must be part of a session. An application can do this in one of two ways: It can enumerate all the existing sessions on a network and join one of them, or it can create a new session and wait for other computers to join it. Once the application is part of a session, it can create a player and exchange messages with all the other players in the session.

Each session has one computer that is designated as the host. The host is the owner of the session and is the only computer that can change the session's properties.

The following diagram illustrates the DirectPlay session model:

DirectPlay session model

Session Management Methods

DirectPlay provides several session management methods:

  • IDirectPlay3::EnumSessions enumerates all the available sessions.
  • IDirectPlay3::Open joins one of the enumerated sessions or creates a new session.
  • IDirectPlay3::SecureOpen performs the same function as IDirectPlay3::Open, but enables the application to alter the default opening behavior.
  • IDirectPlay3::Close leaves the currently open session.
  • IDirectPlay3::GetSessionDesc gets the properties of the current session.
  • IDirectPlay3::SetSessionDesc changes the properties of the current session.
  • IDirectPlay3::GetCaps gets the communications capabilities of the underlying network.

Player Management

The most basic entity within a DirectPlay session is a player. A player represents a logical object within the session that can send and receive messages. DirectPlay does not have any representation of a physical computer in the session. Each player is identified as being either a local player (one that exists on your computer) or a remote player (one that exists on another computer). Each computer must have at least one local player before it can start sending and receiving messages. Individual computers can have more than one local player.

When an application sends a message, it is always directed to another player—not another computer. The destination player can be another local player (in which case the message will not go out over the network) or a remote player. Similarly, when an application receives messages, they are always addressed to a specific (local) player and marked as being from some other player (except system messages, which are always marked as being from DPID_SYSMSG).

DirectPlay provides some additional player management methods that an application can use. These methods can save the application from having to implement a list of players and data associated with each one. You do not need these methods to use DirectPlay successfully. They enable an application to associate a name with a player and automatically propagate that name to all the computers in the session. Similarly, the application can associate some arbitrary data with a player that will be propagated to all the other computers in the session. The application can also associate private local data with a player that is available only to the local computer.

Basic Player Management Methods

DirectPlay provides several basic player management methods:

  • IDirectPlay3::EnumPlayers enumerates all the players in the sessions.
  • IDirectPlay3::CreatePlayer creates a local player.
  • IDirectPlay3::DestroyPlayer destroys a local player.

Additional Player Management Methods

DirectPlay provides these additional methods to manage player information:

  • IDirectPlay3::GetPlayerCaps gets a player's communications capabilities.
  • IDirectPlay3::GetPlayerName gets a player's name.
  • IDirectPlay3::SetPlayerName changes a player's name.
  • IDirectPlay3::GetPlayerData gets the application-specific data associated with a player.
  • IDirectPlay3::SetPlayerData changes the application-specific data associated with a player.
  • IDirectPlay3::GetPlayerAddress gets a player's network-specific address.
  • IDirectPlay3::GetPlayerAccount gets a player's account information.
  • IDirectPlay3::GetPlayerFlags gets a player's flag settings.

Message Management

Once an application has created a player within a session, it can start exchanging messages with other players in the session. DirectPlay imposes no message format or extra bytes on the message. A message can be sent to an individual player, to all the players in the sessions, or to a subset of players that have been defined as a group (see Group Management). When sending a message, it must also be marked as being from a specific local player.

All the messages received by an application are put into a receive queue. The application must retrieve individual messages from the queue and act on them as appropriate. The application can either poll the receive queue for messages or use a separate thread that waits on a synchronization event for notification that a new message has arrived.

There are two types of messages. Player messages are messages that another player in the session sent. This type of message is directed to a specific player and is marked as being from the sending player. System messages are sent to all the players in a session, and are all marked as being from the system (DPID_SYSMSG). DirectPlay generates system messages to notify the application of some change in state of the session; for example, when a new player has been created. See Using System Messages for more information.

Basic Message Management Methods

DirectPlay provides several message management methods:

  • IDirectPlay3::Send sends a message from a local player to another player in the session.
  • IDirectPlay3::SendChatMessage enables players to chat with other players using standardized messages.
  • IDirectPlay3::Receive retrieves a message from the incoming message queue.
  • IDirectPlay3::GetMessageCount gets the number of messages currently in the incoming message queue.

Group Management

DirectPlay supports groups within a session. A group is a logical collection of players. By creating a group of players, an application can send a single message to the group, and all the players in the group will receive the message. A group is the means by which a network's multicast capabilities are exposed to the application.

Groups can also be used as a general means to organize players in a session. A player can belong to more than one group. DirectPlay provides methods for administering groups and their membership. Additional methods associate names and data with individual groups as a convenience, but you don't need them to use groups.

The following diagram shows a logical representation of the contents of a DirectPlay session:

A logical representation of the contents of a DirectPlay session

Basic Group Management Methods

DirectPlay provides several group management methods:

  • IDirectPlay3::EnumGroups enumerates all the groups in the session.
  • IDirectPlay3::CreateGroup creates a new group.
  • IDirectPlay3::DestroyGroup destroys a group.
  • IDirectPlay3::EnumGroupPlayers enumerates the players that are in a group.
  • IDirectPlay3::AddPlayerToGroup adds a player to a group.
  • IDirectPlay3::DeletePlayerFromGroup removes a player from a group.

Additional Group Management Methods

DirectPlay provides these additional methods to manage group information:

  • IDirectPlay3::GetGroupName gets the group's name.
  • IDirectPlay3::SetGroupName changes the name of a group created by this computer.
  • IDirectPlay3::GetGroupData gets the application-specific data associated with a group.
  • IDirectPlay3::SetGroupData changes the application-specific data associated with a group created by this computer.
  • IDirectPlay3::GetGroupFlags gets the flags describing a group.
  • IDirectPlay3::GetGroupParent gets the DPID of the parent of the group.

New Group Management Methods

DirectPlay 5 has added these methods that manage groups within groups and shortcuts to groups:

  • IDirectPlay3::CreateGroupInGroup creates a group within an existing group.
  • IDirectPlay3::EnumGroupsInGroup enumerates all the groups within another group.
  • IDirectPlay3::AddGroupToGroup adds a shortcut from a group to an already existing group.
  • IDirectPlay3::DeleteGroupFromGroup removes a group previously added to another group with AddGroupToGroup, but doesn't destroy the deleted group.
  • IDirectPlay3::GetGroupConnectionSettings retrieves a group's connection settings.
  • IDirectPlay3::SetGroupConnectionSettings sets a group's connection settings.

Overview of DirectPlay Communications

DirectPlay's default mode of communications is peer-to-peer. In this model, the session's complete state is replicated on all the computers in the session. This means that the session description data, the list of players and groups, and the names and remote data associated with each session are duplicated on every computer. When one computer changes something, it is immediately propagated to all the other computers.

DirectPlay's alternative mode of communications is client/server. In this model, only the server stores the session's complete state, and each client has only a subset of the session's state. Each client has only the information that is relevant to that computer and receives that information from the server. When one computer changes something, it propagates the change to the server. The server then determines which clients it must inform of the change.

An application can manage its own data using either a client/server model or peer-to-peer model, but this will not change how the underlying DirectPlay session state is managed.

The following sections discuss the two modes of communications within DirectPlay sessions:

  • Peer-to-Peer Session
  • Client/Server Session

Peer-to-Peer Session

In a peer-to-peer DirectPlay session, one computer is designated the name server. This computer responds to enumeration requests, regulates computers trying to join the session, downloads the session's state to new computers that have joined, and generates ID numbers as players and groups are created. Beyond that, the name server is just another peer in the session and runs the same application as all the other peers. Messages are not routed through the name server, and the name server does not generate all the system messages.

DirectPlay automatically performs the name server functions, which are not exposed to the application in any way. The DirectPlay application running on the name server is also the session's host. Only the host application can change the session description data. Each peer application in the session has access to the complete list of players and groups in the session (see Session Management) and can send and receive messages from any other player in the session or send a message to any group in the session. See Session Management for more details.

The session's network address corresponds to the name server's network address. When a computer needs to join the session, it sends the join request to the name server. In response, the name server downloads the session's state to the new computer. If the name server leaves the session, a new computer is elected name server. When the name server migrates, the session's network address also changes.

The following diagram illustrates joining a session. To join a session, a machine sends the join request to the name server of the session.

Joining a session

Peer-to-peer sessions generally have a limitation on the number of computers that can participate. Every change in state on every computer (such as player movements) must be broadcast to all the other computers in the session. Because of the limit on the amount of data a computer can receive (especially if connected through a phone line), there is a limit on how many computers can generate data. Minimizing the quantity and frequency of data exchanged can help increase the number of computers that can be in a session before performance degrades.

Computers in a peer-to-peer DirectPlay session communicate directly with each other. That is, messages are not sent through an intermediate computer to reach their destination (although they can go through a router). When DirectPlay needs to send the same message to a set of computers, it attempts to use any multicast capabilities in the service provider. If multicast is not supported, then individual unicast messages are sent to each destination computer.

The following diagram illustrates group messaging without multicast. To broadcast a message, individual messages are sent to each machine.

Group Messaging without Multicast

This can be a source of inefficiency in sessions with a large number of players (more than four). Adding a multicast server to the session can alleviate this. A multicast server is a computer that will forward a single message to multiple destinations. A computer needing to broadcast a message to all the other computers in the session can send one message to the multicast server, which in turn sends individual messages to all the other computers. This is more efficient because the multicast server is connected to the network through a high-speed link and can therefore pump out unicast messages faster than any individual computer. The assumption is that the server has a high-speed link to the network (such as a T1 line), while the other computers have slow-speed links (such as phone lines).

The following diagram illustrates group messaging using a multicast server. Player-to-player messages are sent directly to the destination machine. Group messages are sent to the multicast server, which forwards them to all the destination machines.

Group Messaging Using a Multicast Server

DirectPlay supports the creation of a multicast server in a session. If the name server is on a sufficiently high-speed link, it can choose to be a multicast server for the session as well. Adding a multicast server to a session only changes how group messages (including broadcast) are routed—the application's behavior does not change. Unicast player-to-player messages are still sent directly to the destination computers.

Client/Server Session

In a DirectPlay client/server session, one computer is designated the server. Like the peer-to-peer name server, this computer responds to enumeration requests, regulates computers trying to join the session, downloads the session's state to new computers that have joined, and generates ID numbers as players and groups are created. Unlike the peer-to-peer name server, all messages in the session are routed through the server.

The server computer runs a special version of the application (the application server) that can maintain the master state of the game, updating that state according to actions that the client computers take, and notifying individual clients of relevant events. The application server creates a special player called the server player. Any client computer can send a message directly to the server player or receive a message from the server player. When the server player receives a message, it can send messages to other client players to inform them of a change in state.

The following diagram illustrates client\server communications. Each machine communicates directly with the server only. The server can forward messages to other clients.

The client computers run client versions of the application that can maintain the local state, updating the state in response to messages from the server, and sending messages to the server when local action occurs.

You can implement a client/server application in two ways. One mode is a hybrid peer-to-peer and client/server session, where every client application has the complete player and group list available to it (including the server player). Any client player can send a message directly to any player in the session, and each player or group can have data associated with it (such as name or remote data) that will be updated on all the computers whenever it changes. All the benefits of peer-to-peer state propagation are available, and, in addition, a server player is available. However, you cannot control the propagation of the player-to-player data. Depending on the frequency with which players and groups are created and destroyed or their data changes, client computers could be overloaded with in-coming messages. This type of a session is not scalable beyond about 16 players. It is not very different from a peer-to-peer session, except: It has a server player; all messages are routed through the server; and the server player will receive a copy of all the messages that pass through the server.

The second mode is pure client/server. Each client application sees only the server player and its own local players in the session. A client player can send messages only to the server player and receive messages from only the server player. The application server can see all the players on all clients. When the server receives a message from a client, it can intelligently decide how to update the master application state and inform the clients that need to be notified of this update. In this mode, the client application must manage the player list and the data associated with each player.

The following diagram shows a logical representation of the contents of a DirectPlay client/server session.

A logical representation of the contents of a DirectPlay client/server session

Like a peer-to-peer session, the session's network address corresponds to the server's network address. When a computer needs to join the session, it sends the join request to the server. In response, the server downloads the session's state to the new computers. If the server leaves the session, the session is terminated.

Because all messages are routed through the server, it automatically behaves as a multicast server.

Security

Using DirectPlay security features, an application running on a server can create secure sessions. DirectPlay implements security through the Security Support Provider Interface (SSPI) on Windows. Key features supported by DirectPlay in a secure session are:

  • Authentication to verify the identity of the user. Once a user has been authenticated, communications between the client and server can be done securely either by digitally signing or encrypting the messages.
  • Digitally signed system messages to verify the identity of the sender.
  • Encryption of sensitive system messages.

For more information, including how to set up a secure server, start a secure session, and specify security packages, see Security and Authentication.


DirectPlay Lobby Overview

A DirectPlay lobby server is a common place on a network that (at a minimum) tracks DirectPlay application sessions in progress, and users that are connected to the server. Users can navigate around the lobby server to find areas of interest. At any location on the lobby server, the user can chat with other users, join sessions that are in progress, or gather a group of players to start a new session.

This section discusses the following topics.

  • DirectPlay Lobby Architecture
  • Lobby Sessions
  • Lobby Navigation
  • Synchronized Launching

A lobby server's main advantage is that it acts as a central, well-known location where users can go to find sessions and other people to interact with. The lobby server manages all the network addresses of the various players and sessions and can automatically manage launching applications and connecting them to the correct address without user intervention. The management of sessions, players, and their network addresses is especially useful on the Internet, where users generally can't find opponents or get applications connected in a session easily. It also has the advantage of launching application sessions for the user without the user having to enter any network configuration information.

Lobby servers can be greatly enhanced to provide more services to the user, such as tournaments, individual score tracking and high scores, personal profiles, avatars, message boards, news, a broader user interface, authenticated membership, software updates, and so on.

A lobby-aware application is one that has been specifically developed to operate with lobby servers. There are two types of lobbies that a user can experience. An external lobby is a client application whose sole purpose is to interact with a lobby server and the other users connected to it. When the time comes to start or join an application session, the lobby client launches the application in a separate process and gives it all the information necessary to establish a connection to the session. Adding support for external lobby launching to a DirectPlay application is quite straightforward and explained further in Supporting External Lobby Launching.

An internal lobby is a lobby user interface that is integrated into the application itself. This is more difficult to implement because the application must implement the user interface for the lobby as well as that for the game. However, it has the advantage that you can customize the lobby experience to match the application's theme.

DirectPlay Lobby Architecture

The DirectPlay lobby architecture consists of a client API that all applications, whether they are external lobby clients or applications that have a lobby client built in, use to connect to any DirectPlay-compliant lobby server. This is done through a lobby provider interface that, like a service provider, abstracts the interaction with the lobby server. The author of the lobby server application must write the lobby provider that resides on the client computer. The application calls the standard DirectPlay APIs, and the lobby provider's dynamic-link library (DLL) services these methods by communicating with the lobby server software.

The following diagram illustrates the DirectPlay lobby architecture. Different lobby client applications can connect to the same lobby server through the DirectPlay API.

DirectPlay lobby architecture

At the very least, the lobby server must be able to track all the users currently connected to it, organize those players by grouping them, and synchronize the launch of an application session.

The DirectPlay API defines a common level of functionality for all lobby servers. Any generic lobby client application can connect to any generic lobby server and, through the DirectPlay API and the lobby provider architecture, they can interoperate successfully. An application can extend the basic functionality with the Send and Receive methods. A lobby client designed to work with a specific lobby server can implement extended functionality that is not defined by the DirectPlay API.

There is no separate API to communicate with a DirectPlay lobby server. Interaction with a lobby server has been abstracted so that the same IDirectPlay3 interface used to communicate in an application session can be used to communicate with the lobby server. Additional methods and messages have been added to the interface to support the additional functionality that a lobby server requires.

By using the same DirectPlay methods to interact with the lobby server, it is simple to add a lobby client interface to an application, because the same APIs and concepts are being leveraged.

Lobby Sessions

A lobby session closely resembles a DirectPlay client/server session (see the illustration in Client/Server Session). The term lobby session refers to a connection to a lobby server where clients and the server have not been specifically written to interoperate. The term application session refers to a traditional DirectPlay session in which all the clients and the server (if any) have been specifically written to interoperate.

A DirectPlay lobby session is used to represent a connection to a lobby server. Like a DirectPlay application, the first step in using DirectPlay to communicate with a lobby server is to select which lobby provider to use and which lobby server to connect to. Like a DirectPlay application, the IDirectPlay3::EnumConnections and IDirectPlay3::InitializeConnection methods are used to do this.

The lobby client uses the same session management methods as an application client to locate and to join a lobby session; for example, EnumSessions, Open, SecureOpen, and Close. Joining a lobby session gives the client application access to all the information on the lobby server and enables the user to interact with other users on the lobby server.

Like a DirectPlay application session, the player is the basic entity in a lobby session. Each player represents a user on a client computer connected to the lobby server. There is also the server player representing the lobby server. After a lobby client connects to a lobby server (by joining the lobby session), it must establish the user's presence by creating a player and adding the player to an initial group before the player can start communicating with the server and other players. In fact, other users connected to the session won't even be aware of the new user's presence until this happens.

The same player management methods used by application sessions are used to manage players in a lobby session; for example, EnumPlayers, CreatePlayer, DestroyPlayer, GetPlayerName, SetPlayerName, and GetPlayerCaps.

Unlike a DirectPlay application session, Send and Receive generally cannot be used to exchange messages with other players. In the DirectPlay lobby architecture, any application that uses the DirectPlay API can connect to any lobby server. This means that many different lobby client applications might be present in the same lobby session, all of which were written by different developers. Simply sending a message to another client player or the server player does not guarantee that it will be interpreted correctly by the recipient application.

Common functions that require communications between clients and the server have new methods created for them. DirectPlay determines the message's format. The recipient receives a system message containing the content of the message in a well-defined data structure. For example, the IDirectPlay3::SendChatMessage method sends a text chat message to another player.

Groups take on more significance in a lobby session, because they are used to define the organization of the entire lobby server and for launching application sessions. You can create a complete hierarchy of groups to manage and organize all the players and sessions that the lobby server tracks.

For the purposes of the lobby server, groups are classified as one of two types. A standard group can contain players and other groups and is called a room. A room is primarily used as a meeting place for players to interact with other players in the context of the lobby. The room contains links to other rooms and links to the second type of group—a staging area.

A staging area group typically contains only players. A staging area is used to marshal players together in order to launch a new session. After the session has been launched, the staging area can remain in existence so that new players can join the session in progress.

Room groups are organized primarily in a hierarchical structure. A few top-level groups are created and other groups are created within existing groups. The lobby client can enumerate all the top-level groups as well as the groups contained within a group. The lobby server can also organize the groups in a web structure. Once a group is created, you can add it to another group, which creates a link between the two groups. When a lobby client enumerates groups within a group, all subgroups and linked groups are returned.

The following diagram illustrates the organization of a lobby session.

Organization of a lobby session

Players can be seen only in groups. They cannot be seen until they are part of a group. Players can belong to more than one group at once.

Lobby Navigation

Players can navigate through the lobby server space simply by deleting themselves from their current group and adding themselves to a new group. At any time, the IDirectPlay3::EnumGroupsInGroup method can be called to determine what groups are linked to the current group.

In general, the scope of the lobby session visible to a player is limited by the groups the player is part of. This is done to limit the amount of information that the server must download to the client.

Synchronized Launching

Application sessions are marshaled and launched from a staging area. One player creates a staging area and waits for other players to join it. A player can set the properties of the application session to be created through the IDirectPlay3::SetGroupConnectionSettings method. Other players who are considering joining the group can find out what the application session properties are by calling the IDirectPlay3::GetGroupConnectionSettings method. After enough players have joined the staging area, any player can call the IDirectPlay3::StartSession method to initiate the synchronized launch sequence. Every player in the staging area groups receives a DPMSG_STARTSESSION system message with a DPLCONNECTION structure. If the player is using an external lobby client, it can launch the application by using the IDirectPlayLobby2::RunApplication method. If the player is using an internal lobby, the application can use the information to establish a connection to the appropriate session by calling IDirectPlayLobby2::Connect.


DirectPlay Providers

This section describes the DirectPlay interface and the DirectPlay service providers and how they interact with each other. See:

  • Service Providers
  • Lobby Providers

The DirectPlay interface is a common interface to the application for simple send and receive type messaging, as well as higher-level services like player management, groups for multicast, data management and propagation, and lobby services for locating other players on a network.

The service providers furnish network-specific communications services as requested by DirectPlay. Online services and network operators can supply service providers to use specialized hardware, protocols, communications media, and network resources. A service provider can simply be a layer between DirectPlay and an existing transport like Winsock, or it can use specialized resources on an online service such as multicast servers, enhanced quality of service, or billing services. Microsoft includes four generic service providers with DirectPlay: head-to-head modem (TAPI), serial connection, Internet TCP/IP (using Winsock), and IPX (also using Winsock).

The DirectPlay interface hides the complexities and unique tasks required to establish an arbitrary communications link inside the DirectPlay provider implementation. An application using DirectPlay need only concern itself with the performance and capabilities of the virtual network presented by DirectPlay. It need not know whether a modem, network card, or online service is providing the medium.

DirectPlay will dynamically bind to any DirectPlay provider installed on the user's system. The application interacts with the DirectPlay object. The DirectPlay object interacts with one of the available DirectPlay service providers, and the selected service provider interacts with the transport, protocol, and other network resources.

The DirectPlay API is exposed to the application through several Component Object Model (COM) interfaces. (See DirectPlay Interfaces for a discussion of COM and DirectPlay.) Application sessions can talk to someone else on the network through the IDirectPlay3 and IDirectPlay3A interfaces. The first uses Unicode strings in all the DirectPlay structures, while the second uses ANSI strings. IDirectPlay, IDirectPlay2, and IDirectPlay2A still exist for backward compatibility with applications written to a previous version of the DirectPlay Software Development Kit (SDK).

Lobby clients can talk to another application on the same machine through the IDirectPlayLobby2 and IDirectPlayLobby2A interfaces. The first interface uses Unicode strings while the second uses ANSI strings. The IDirectPlayLobby interface still exists for backward compatibility.

Service Providers

The service provider furnishes network-specific communication services as requested by DirectPlay. Online services and network operators can supply service providers for specialized hardware and communications media. Microsoft includes the following service providers with DirectPlay:

  • TCP/IP
  • IPX
  • Modem-to-Modem
  • Serial Link

Individual service providers are identified using a globally unique identifier (GUID). GUIDs for the standard service providers are listed in the header file DPLAY.H. Third-party service providers will have their own GUIDs.

This section outlines what to expect from the default service providers that Microsoft provides. To obtain information about the behavior of third-party service providers, contact the network operator.

TCP/IP

The TCP/IP service provider uses Winsock to communicate over the Internet or local area network (LAN) using the TCP/IP protocol. It uses UDP (User Datagram Protocol) packets for nonguaranteed messaging and TCP for guaranteed messaging. A single computer can host multiple DirectPlay sessions using TCP/IP.

When the IDirectPlay3::EnumSessions method is called, TCP/IP displays a dialog box asking the user for the session's IP address. The user must enter the IP address of the computer hosting the session to be joined. If the computer has a name (such as microsoft.com), the name can be used instead of the IP address, and DirectPlay will use Domain Name System (DNS) lookup to find it. The IDirectPlay3::EnumSessions method will return the sessions that the computer is hosting. The user can also leave the address blank and select OK. In this case, DirectPlay will broadcast a message looking for sessions. This will generally only work on a LAN and only on the same subnet.

Note: A Windows® 95 user can determine his or her IP address by choosing Run from the Start menu and typing WINIPCFG as the program to run. A Windows® NT® user can determine his or her IP address by running IPConfig from the command line. If the user is connected to both a LAN and a dial-up Internet service provider (ISP), the computer can have two IP addresses, and the correct one must be selected. Most dial-up ISPs assign a dynamic IP address that changes each time the user logs on.

An application can call IDirectPlay3::InitializeConnection, or can call IDirectPlayLobby2::SetConnectionSettings followed by a call to Connect, to supply an IP address to the service provider in a DirectPlay Address. The address must be a null-terminated ANSI or Unicode string (each has a different data type GUID). If a broadcast enumeration of sessions is desired, the address must be a zero-length string; that is, a string only consisting of the null terminator.

The DirectPlay TCP/IP service provider does not generally work through firewalls.

Adding DirectPlay lobby support can eliminate the need for users to enter an IP address if they start the game from a lobby server.

This service provider can be identified using the symbol definition DPSPGUID_TCPIP.

Note: A Windows 95 user can configure his or her computer connections to display or not display a dialog box requesting connection information when DirectPlay tries to initiate a TCP/IP connection. To suppress the display of this dialog box, follow these steps:

  1. Open Control Panel.
  2. Double-click the Internet icon.
  3. Choose the Connection tab.
  4. Clear the checkbox next to Connect to the Internet as needed.

IPX

The IPX service provider uses Winsock to communicate over a local area network (LAN) using the Internet Packet Exchange (IPX) protocol. The service provider only supports nonguaranteed messaging. A single computer can host only one DirectPlay session using IPX.

IPX always uses a broadcast to find sessions on the network, so the IDirectPlay3::EnumSessions method will not display a dialog box requesting IP addresses.

IPX will not enumerate sessions on another subnet.

Once a session is established, packets are sent directly between computers (they are not broadcast).

This service provider can be identified using the symbol definition DPSPGUID_IPX.

Modem-to-Modem

Modem-to-modem communication uses Telephony Application Programming Interface (TAPI) to communicate with another modem.

Creating a session (by using the IDirectPlay3::Open method) causes a dialog box to appear, asking the user which modem to wait for a call on. The IDirectPlay3::EnumSessions method will also display a dialog box asking the user what phone number to call and which modem to use. Once the information is entered, DirectPlay will dial the modem and try to find sessions hosted by the computer on the other end. In both cases, dialogs are displayed to show the progress.

To enumerate the modem sessions without any dialogs, call IDirectPlay3::EnumSessions in a loop with the DPENUMSESSIONS_RETURNSTATUS flag (see EnumSessions for more details). When DP_OK is returned, the application should then call EnumSessions one more time to obtain the actual list of sessions.

When calling EnumSessions in a loop like this, the application must implement a windows message loop as follows:

while (lpDPLAY->EnumSessions(lpsd, 0, lpEnumSessionsCallback, lpContext, DPENUMSESSIONS_RETURNSTATUS) == DPERR_CONNECTING)
{
    MSG	msg;

    if (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
    {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    Sleep(500);
}

The current list of available modems can be obtained from the service provider by initializing it and calling IDirectPlay3::GetPlayerAddress with a player ID of zero. The DirectPlay Address returned will contain a data chunk with the ANSI modem names (DPAID_Modem) and the Unicode modem names (DPAID_ModemW). The list of modems is a series of NULL-terminated strings with a zero-length string at the end of the list.

If you insert too many delays into the message processing, you may lose packets; for example, if you print a lot of debug information.

This service provider can be identified using the symbol definition DPSPGUID_MODEM.

Serial Link

A serial link is used to communicate with another computer through the serial ports.

Creating a session (using the IDirectPlay3::Open method) causes a dialog box to appear asking the user to configure the serial port. The IDirectPlay3::EnumSessions method will also display a dialog box asking the user to configure the serial port. You must configure the serial port the same way on both computers.

If you insert too many delays into the message processing, you may lose packets; for example, if you print a lot of debug information.

This service provider can be identified using the symbol definition DPSPGUID_SERIAL.

Lobby Providers

The lobby provider is a client component dynamic-link library (DLL) supplied by the developer of a lobby server. It implements communications functions with the lobby server as requested by DirectPlay. A lobby client written using the DirectPlay API can interoperate with any lobby server for which a lobby provider DLL is present on the system.

The DirectX® SDK installs a lobby provider for use with the test lobby server (LSERVER.EXE) included with the SDK. This lobby provider is used by the BELLHOP sample lobby client, and together they can be used to test the lobby-aware functions your applications.


Using DirectPlay

This section contains the following topics that explain how to use different aspects of DirectPlay:

  • Debug versus Retail DLLs
  • Working with GUIDs
  • DirectPlay Interfaces
  • Using Callback Functions
  • Building Lobby-Aware Applications
  • DirectPlay Messages
  • DirectPlay Address (Optional)
  • Migrating from Previous Versions of DirectPlay
  • DirectPlay Tools and Samples
  • Security and Authentication

Debug versus Retail DLLs

The Software Development Kit (SDK) has the option to install debug or retail builds of the DirectPlay dynamic-link libraries (DLLs). When developing software, it is best to install the debug versions of the DLLs. The debug DLLs have additional code that will validate internal data structures and output debug error messages (using the Win32® OutputDebugString API) while your program is executing. When an error occurs, the debug output will give you a more detailed description of what the problem is. The debug DLLs will execute more slowly than the retail DLLs but are much more useful for debugging an application. Be sure to ship the retail version with your application.

In order to see the debug messages, it is necessary to configure your computer so that debug output will be displayed in a window or on a remote computer. An interactive development environment like Microsoft® Visual C++™ allows you to do this. Consult the environment's documentation for set-up instructions.

Working with GUIDs

Globally unique identifiers are 16-byte data structures that you can use to identify objects in a globally unique way. Whenever a GUID is required in an API, a symbol representing that GUID should be used. The symbols are either defined in one of the DirectPlay header files or the application developer must generate them. You can generate GUIDs by using the Guidgen.exe utility that comes with Microsoft Visual C++. For example, every application must define an application GUID that identifies the application that is running in a session.

Note If there are different versions of an application that cannot interoperate in the same session, they should have different application GUIDs to distinguish them.

To use DirectPlay-defined GUIDs successfully in your application, you must either define the INITGUID symbol prior to all other include and define statements, or you must link to the Dxguid.lib library. If you define INITGUID, you should define it in only one of your source modules.

DirectPlay Interfaces

All the functionality in DirectPlay is accessed through member functions on Component Object Model (COM) interfaces. To use them, an application must obtain the appropriate COM interface.

The standard method of obtaining COM interfaces is to use the Win32 CoCreateInstance API. To use it successfully, the application must first call the Win32 CoInitialize API to initialize COM and then call CoCreateInstance, specifying the GUID of the desired interface. For example, use the following code to obtain an IDirectPlay3A interface:

  // C++ example
  hr = CoCreateInstance( CLSID_DirectPlay, NULL, CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay3A, (LPVOID*)&lpDirectPlay3A);
  // C example
  hr = CoCreateInstance( &CLSID_DirectPlay, NULL, CLSCTX_INPROC_SERVER,
                         &IID_IDirectPlay3A, (LPVOID*)&lpDirectPlay3A);

When the program is finished, all the COM interfaces must be freed by calling the Release method on each interface. Finally, the Win32 CoUninitialize method should be called to uninitialize COM.

If you call CoCreateInstance without first calling CoInitialize you will get a CO_E_NOTINITIALIZED error, with the error text "CoInitialize has not been called."

DirectPlay has several COM interfaces. Each interface represents a revision of an earlier version of DirectPlay in which new methods are added. COM interfaces are numbered sequentially with each revision. The latest COM interface will have all the latest functionality of DirectPlay. To access the new functionality (for example, IDirectPlay3::SendChatMessage), you must use the latest COM interface. Source code written for an earlier COM interface will work.

Once a COM interface is obtained, an alternate interface can be used on the same object by calling the QueryInterface method on the interface. For example, DirectPlayCreate will create a DirectPlay object and return an IDirectPlay interface. If your application requires an IDirectPlay3 interface, it can call QueryInterface on the IDirectPlay interface. Be sure to release the original IDirectPlay interface if it is no longer needed.

Using Callback Functions

The enumeration methods in DirectPlay are used to return a list of items to the application. The application calls an enumeration method (such as IDirectPlay3::EnumPlayers) and supplies a pointer to a callback function that it has implemented. DirectPlay will call the callback function once for each item in the list. The enumeration method will not return until all the items in the list have been returned to the application through the callback function.

It is extremely important that all callbacks be declared correctly. For example:

BOOL FAR PASCAL EnumConnectionsCallback(LPCGUID lpguidSP, LPVOID lpConnection, DWORD dwConnectionSize,
LPCDPNAME lpName, DWORD dwFlags, LPVOID pContext);

The FAR PASCAL symbol will define the function as _stdcall. That means it will clean up the stack before returning to DirectPlay. Do not cast function pointers when passing them to a DirectPlay enumeration method. If there is a compiler warning about the function pointer, fix the function declaration.

Building Lobby-Aware Applications

A lobby-aware application is one that, at a minimum, supports being launched from a lobby. A matchmaking lobby is a site on the Internet where end users can find other people to play games with. Once a group of people has decided to start an application session, the lobby software can launch the application on each person's computer and have them all connect to a session. The main benefit for end users is the ease with which they can establish a session with other players. Not only does it allow a user to easily find opponents, but there is also no need for the user to:

  • Select a service provider. The lobby will specify which service provider to use.
  • Decide whether to host or join a session. The lobby will specify whether to create or join a session.
  • Enter a network address or configure the network. The lobby will supply this information if it is needed.
  • Enter the name of the player. The lobby will pass in the same name that the user connected to the lobby with.

Other benefits of the lobby are:

  • It can keep track of sessions in progress and enable users to join them.
  • It can receive status messages from the session and display the progress to other users on a scoreboard.
  • It can obtain final scores and maintain player rankings for tournament play.

For a DirectPlay application to be lobby-aware, at a minimum it must support being launched from a lobby. You can add other features to make it integrate better with the lobby. For additional information see the following topics within this section.

  • Registering Lobby-Aware Applications
  • Supporting External Lobby Launching
  • LobbyMessaging (Optional)

Registering Lobby-Aware Applications

To enable a lobby to launch a DirectPlay application, the application must add the following entries to the system registry. Once an application has been registered, it will be recognized as a lobby-aware application and lobbies can launch it. These registry entries must be deleted when the application is removed.

The following example shows the registry entries for the DPCHAT sample application included in the SDK.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DirectPlay\Applications\DPChat]
"Guid"="{5BFDB060-06A4-11D0-9C4F-00A0C905425E}"
"File"="dpchat.exe"
"CommandLine"=""
"Path"="C:\DXSDK\sdk\bin"
"CurrentDirectory"="C:\DXSDK\sdk\bin"

The keys and values are:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DirectPlay\Applications\
The key's name will be the name of the application that the IDirectPlayLobby2::EnumLocalApplications method returns. It is DPChat in the preceding example.
Guid
This is the 16-byte GUID that identifies the application. It is formatted as shown in the example. This should be the same GUID that is put in the guidApplication member of the DPSESSIONDESC2 structure when creating a session. A GUID can be generated using the Guidgen.exe utility.
File
This is the file name of the application executable.
CommandLine
This lists any command-line parameters that are to be specified when a lobby launches the application.
Path
This is the directory that the application executable resides in.
CurrentDirectory
This is the directory to set as the current directory after launching the application executable.

Supporting External Lobby Launching

Once the application has been registered, the DirectPlay application must be able to recognize whether a lobby launched it or not. If a lobby launched it, it must follow a slightly different code path to set up the network connection. Consult the DUEL (Lobby.c) and DPCHAT (Lobby.cpp) samples in the SDK for the code necessary to support external lobby launching. See Tutorial 1: Connecting by Using the Lobby for a demonstration on how to connect an application by using a DirectPlay lobby.

The necessary basic steps are:

  1. At startup, create an IDirectPlayLobby2 interface using the CoCreateInstance API.
  2. The application can examine the connection information that was passed in by the lobby and modify some of the connection settings if necessary. The IDirectPlayLobby2::GetConnectionSettings method returns a DPLCONNECTION structure with the connection settings. This method returns DPERR_NOTLOBBIED if a lobby did not launch the application. New settings can be set with IDirectPlayLobby2::SetConnectionSettings.
  3. IDirectPlayLobby2::Connect creates or joins the specified application session using the specified service provider, and returns an IDirectPlay2 interface. Connect returns an error if the session could not be created/joined, or if a lobby did not launch the application.
  4. Use QueryInterface to obtain an IDirectPlay3 interface and then call Release on the IDirectPlay2 interface.
  5. Create a player using the name information supplied in the DPLCONNECTION structure obtained in step two.

At this point, the application can continue on the same code path as if the user had manually selected a connection, joined or created a session, and entered the name of the player to create.

The IDirectPlayLobby2 interface can be saved if the game will pass information back to the lobby (see Lobby Messaging), or it can be discarded by using the Release method if no messages will be sent.

Many lobbies will launch the application and then go into a suspend mode, waiting for the application to terminate. DirectPlay will notify the lobby when the application that it launched has terminated. For this reason it is important that the application launched by the lobby not launch another application.

Lobby Messaging (Optional)

After registering a lobby-aware application and adding the code to support external lobby launching, the next step in integrating the application with the lobby is to send information back to the lobby or to request information from the lobby. This is done by exchanging messages with the lobby through the IDirectPlayLobby2::SendLobbyMessage and IDirectPlayLobby2::ReceiveLobbyMessage methods on the IDirectPlayLobby2 interface. Standard message structures have been defined by DirectPlay to facilitate this functionality.

Sending information to the lobby is done through setting properties. The application must create and fill in a DPLMSG_SETPROPERTY structure and send it to the lobby by using the SendLobbyMessage method. Each property identifies a distinct type of data. The application developer should generate GUIDs (using Guidgen.exe) for every property that will be set. The lobby operator needs to obtain this list of GUIDs from the application developer along with the description and data structure of each property.

Properties can take the form of:

  • Current individual player scores.
  • Final individual player scores.
  • Player configuration for later retrieval.
  • Current game status (level or mission).

The lobby can store this information or display it to other users in the lobby so they can monitor the game's progress. An application can request confirmation that the property was set correctly by supplying a nonzero request ID with the set property message.

Requesting information from the lobby is done through requesting properties. The application must create and fill in a DPLMSG_GETPROPERTY structure and send it to the lobby by using the SendLobbyMessage method. At some later time, the lobby will send a message back to the application—a DPLMSG_GETPROPERTYRESPONSE structure that contains the property data that was requested. The application can retrieve the message from the lobby message queue using the ReceiveLobbyMessage method. As before, the application developer generates the GUIDs for each property and the lobby operator must obtain them from the developer.

The following list shows examples of some properties that can be requested from the lobby:

  • Game configuration settings — enables players to configure the game in the lobby before launching the game.
  • Player configuration settings — enables players to configure their players in the lobby or to use a stored configuration from a previous session.
  • Other information stored from a previous session.

Not all lobbies will be able to support these standard lobby messages. The application can determine whether the lobby that it was launched from supports standard lobby messages by sending a DPLMSG_GETPROPERTY message requesting the DPLPROPERTY_MessagesSupported property.

DirectPlay Messages

The following sections describe how to use messages in DirectPlay.

  • Synchronization
  • Using System Messages
  • Using Lobby Messages

Synchronization

An application can use two methods to process DirectPlay messages. The first is to check the receive queue during the main loop of the application. Typically, this means the application is single threaded.

Alternatively, an application can have a separate thread to wait for messages and process them. In this case the application should supply a non-NULL auto-reset synchronization event handle (see the Win32 CreateEvent API) when it creates players. DirectPlay will set this event whenever a message arrives for that player. All the local players in an application can share the same event or each can have his or her own event.

The message processing thread should then use the Win32 WaitForSingleObject API to wait until the event is set. Continue calling Receive until there are no more messages in the message queue.

Using System Messages

Messages returned by the IDirectPlay3::Receive method from player ID DPID_SYSMSG are system messages. All system messages begin with a double-word value specified by the dwType DWORD value. You can cast the buffer returned by the IDirectPlay3::Receive method to a generic message (DPMSG_GENERIC) and switch on the dwType element, which will have a value equal to one of the messages with the DPSYS_ prefix. After the application has determined which system message it is, the buffer should be cast to the appropriate structure (beginning with the DPMSG_ prefix) to read the data.

Your application should be prepared to handle the following system messages:

Value of dwType | Message structure | Cause
DPSYS_ADDGROUPTOGROUP | DPMSG_ADDGROUPTOGROUP | An existing group has been added to an existing group.
DPSYS_ADDPLAYERTOGROUP | DPMSG_ADDPLAYERTOGROUP | An existing player has been added to an existing group.
DPSYS_CHAT | DPMSG_CHAT | A chat message has been received.
DPSYS_CREATEPLAYERORGROUP | DPMSG_CREATEPLAYERORGROUP | A new player or group has been created.
DPSYS_DELETEGROUPFROMGROUP | DPMSG_DELETEGROUPFROMGROUP | A group has been removed from a group.
DPSYS_DELETEPLAYERFROMGROUP | DPMSG_DELETEPLAYERFROMGROUP | A player has been removed from a group.
DPSYS_DESTROYPLAYERORGROUP | DPMSG_DESTROYPLAYERORGROUP | An existing player or group has been destroyed.
DPSYS_HOST | DPMSG_HOST | The current host has left the session and this application is the new host.
DPSYS_SECUREMESSAGE | DPMSG_SECUREMESSAGE | A digitally signed or encrypted message has been received.
DPSYS_SESSIONLOST | DPMSG_SESSIONLOST | The connection with the session has been lost.
DPSYS_SETPLAYERORGROUPDATA | DPMSG_SETPLAYERORGROUPDATA | Player or group data has changed.
DPSYS_SETPLAYERORGROUPNAME | DPMSG_SETPLAYERORGROUPNAME | Player or group name has changed.
DPSYS_SETSESSIONDESC | DPMSG_SETSESSIONDESC | The session description has changed.
DPSYS_STARTSESSION | DPMSG_STARTSESSION | The lobby server is requesting that a session be started.

Using Lobby Messages

Messages returned by the IDirectPlayLobby2::ReceiveLobbyMessage method fall into two categories: DirectPlay-defined messages and custom-defined messages. The message category can be identified by the lpdwMessageFlags parameter of ReceiveLobbyMessage. The flags indicate that the message is either a system message (the DPLMSG_SYSTEM flag) or a standard message (the DPLMSG_STANDARD flag). If neither of these flags is set, the message is custom-defined. System messages are generated automatically by DirectPlay and are sent to the lobby only to inform it of changes in the status of the application. Standard messages can be generated by either the lobby or the application and sent to the other.

The advantage of standard messages over custom-defined messages is that the receiver can positively interpret the message. It is not required that all applications or lobbies act on standard messages.

DirectPlay-defined messages all start with a DWORD value that identifies the type of the message. After retrieving a message using ReceiveLobbyMessage, the lpData pointer to the message data should be cast to the DPLMSG_GENERIC structure and the structure's dwType member examined. Based on the value of dwType, the lpData pointer should then be cast to the appropriate message structure for further processing.

Lobbies should be prepared to handle all the following message types. Applications need to handle the DPLMSG_GETPROPERTYRESPONSE message if they generate DPLMSG_GETPROPERTY messages.

Messages returned by the IDirectPlayLobby2::ReceiveLobbyMessage method that have a dwFlags parameter set to DPLMSG_SYSTEM are system messages. All system messages begin with a double-word value specified by dwType. You can cast the buffer returned by the IDirectPlayLobby2::ReceiveLobbyMessage method to a generic message (DPLMSG_GENERIC) and switch on the dwType element, which will have a value equal to one of the messages with the DPLSYS_ prefix.

The following list shows the possible values of the dwType data member, and the message structure and message cause associated with each value.

Value of dwType | Message structure | Cause
DPLSYS_APPTERMINATED | DPLMSG_GENERIC | The application has terminated.
DPLSYS_CONNECTIONSETTINGSREAD | DPLMSG_GENERIC | The application has read the connection settings.
DPLSYS_DPLAYCONNECTFAILED | DPLMSG_GENERIC | The application failed to connect to the DirectPlay session.
DPLSYS_DPLAYCONNECTSUCCEEDED | DPLMSG_GENERIC | The application successfully connected to the DirectPlay session.
DPLSYS_GETPROPERTY | DPLMSG_GETPROPERTY | The application is requesting a property from the lobby.
DPLSYS_GETPROPERTYRESPONSE | DPLMSG_GETPROPERTYRESPONSE | The lobby is responding to a prior DPLMSG_GETPROPERTY message.
DPLSYS_SETPROPERTY | DPLMSG_SETPROPERTY | The application is setting a property on the lobby.
DPLSYS_SETPROPERTYRESPONSE | DPLMSG_SETPROPERTYRESPONSE | The lobby is responding to a prior DPLMSG_SETPROPERTY message.

DirectPlay Address (Optional)

A DirectPlay Address is a data format that DirectPlay uses to pass addressing information between lobby servers, applications, DirectPlay, and service providers. The format is flexible enough to hold any number of variable-length data fields that make up a network address. It is not necessary to understand DirectPlay Addresses in order to use DirectPlay. In fact, it is possible to successfully write a DirectPlay application without understanding DirectPlay Addresses at all.

This section contains the following topics:

  • DirectPlay Address Data Types
  • Using DirectPlay Addresses
  • Examples of Using DirectPlay Addresses

It is only necessary to learn about DirectPlay Addresses if you want to do the following things:

  • Override the standard service provider dialog boxes. You need to create a DirectPlay Address that specifies which service provider to use and contains all the information the service provider needs to establish a connection. You then pass the DirectPlay Address to the IDirectPlay3::InitializeConnection method.
  • Write a lobby client that will launch an external DirectPlay application. The lobby client needs to create a DirectPlay Address that specifies which service provider to use and contains all the information the service provider needs to establish a connection and automatically connect the client to a session. You need to create a DirectPlay Address of the session to be joined and put it in the DPLCONNECTION structure before calling the IDirectPlayLobby2::RunApplication method.

A DirectPlay Address is a sequence of variable-length data chunks tagged with a GUID that supplies all the address information needed by DirectPlay. Examples are the network address of a server, the network address of a player, the e-mail name of a player, or the network address of a session.

DirectPlay Address Data Types

Microsoft has predefined the following general data types for each data chunk. Based on the data type, the data must be cast to the appropriate type or structure to interpret the data.

GUID | Type of Data
DPAID_ComPort | A DPCOMPORTADDRESS structure that contains all the settings for the COM port. The serial connection service provider will use this information to configure the serial port.
DPAID_INet A null-terminated ANSI string (LPSTR) containing an IP address ("137.55.100.173") or a domain net ("gameworld.com"). The length in bytes must include the terminator.

A blank address is a string that contains only the ANSI terminator (0x00) and has a length of 1 byte. If a blank address is supplied, the Internet TCP/IP connection service provider will use this information to enumerate sessions on the specified network address or to broadcast on the subnet.

DPAID_INetW A null-terminated Unicode string (LPWSTR) containing an IP address ("137.55.100.173") or a domain net ("gameworld.com"). The length in bytes must include the terminator.

A blank address is a string that contains only the Unicode terminator (0x0000) and has a length of 2 bytes. If a blank address is supplied, the Internet TCP/IP connection service provider will use this information to enumerate sessions on the specified network address or broadcast on the subnet.

DPAID_LobbyProvider | The 16-byte GUID that specifies the lobby provider this DirectPlay Address applies to.
DPAID_Modem | A variable-length null-terminated ANSI string (LPSTR) specifying which installed modem to use. The length in bytes must include the terminator. The modem service provider will use this modem without displaying a dialog box asking the user which modem to use. Use the IDirectPlay3::GetPlayerAddress method to determine which modems are available.
DPAID_ModemW | A variable-length null-terminated Unicode string (LPWSTR) specifying which installed modem to use. The length in bytes must include the terminator. The modem service provider will use this modem without displaying a dialog box asking the user which modem to use. Use the IDirectPlay3::GetPlayerAddress method to determine which modems are available.
DPAID_Phone | A variable-length null-terminated ANSI string (LPSTR) containing a phone number. The length in bytes must include the terminator. The modem service provider will call this phone number on the IDirectPlay3::EnumSessions method. If no modem is specified, the first modem will be used.
DPAID_PhoneW | A variable-length null-terminated Unicode string (LPWSTR) containing a phone number. The length in bytes must include the terminator. The modem service provider will call this phone number on the IDirectPlay3::EnumSessions method. If no modem is specified, the first modem will be used.
DPAID_ServiceProvider | The 16-byte GUID that specifies the service provider this DirectPlay Address applies to.
DPAID_TotalSize | A DWORD containing the size of entire DPADDRESS structure.

Using DirectPlay Addresses

You can use a DirectPlay Address to encapsulate all the information necessary to initialize a DirectPlay object. At a minimum, this is the GUID of a DirectPlay provider, but can also include the network address of an application or lobby server and even a specific session instance GUID.

A DirectPlay Address can be used to supply enough information to DirectPlay (and the DirectPlay provider) when it is initialized so that no dialog boxes appear later during the process of establishing a session or connecting to a session.

The DirectPlay Addresses returned by EnumConnections are simply registered DirectPlay providers that the user can choose from. When one of these is initialized, dialog boxes can appear, which ask the user for more information.

The application can create a DirectPlay Address directly using the IDirectPlayLobby2::CreateAddress and IDirectPlayLobby2::CreateCompoundAddress methods on the IDirectPlayLobby2 interface and pass the connection to the IDirectPlay3::InitializeConnection method to initialize the DirectPlay object. If enough valid information is supplied, then no DirectPlay dialog boxes will appear.

Examples of Using DirectPlay Addresses

This topic contains examples of DirectPlay Addresses and the data they contain for different connection types.

A DirectPlay Address describing an IPX connection

Initializing this connection will bind the DirectPlay object to the IPX service provider.
guidDataType | dwDataSize | Data
DPAID_ServiceProvider | 16 | {685BC400-9D2C-11cf-A9CD-00AA006886E3}

A DirectPlay Address describing a modem connection

Initializing this connection binds DirectPlay to the modem service provider and stores the phone number. A subsequent call the IDirectPlay3::EnumSessions will dial the number without asking the user for a phone number.
guidDataType | dwDataSize | Data
DPAID_ServiceProvider | 16 | {44EAA760-CB68-11cf-9C4E-00A0C905425E}
DPAID_Phone | 9 (including NULL terminator) | "555-8237"

A DirectPlay Address describing a TCP/IP connection

Initializing this connection binds DirectPlay to the TCP/IP service provider and stores the IP address. A subsequent call IDirectPlay3::EnumSessions will enumerate sessions on this server without asking the user for an IP address.
guidDataType | dwDataSize | Data
DPAID_ServiceProvider | 16 | {36E95EE0-8577-11cf-960C-0080C7534E82}
DPAID_INet | 10 (including NULL terminator) | "127.0.0.1"

Migrating from Previous Versions of DirectPlay

The DirectPlay version 5 API is fully compatible with applications written for any previous version of DirectPlay. That is, you can recompile your application by using DirectPlay on the DirectX 5 SDK without making any changes to the code. DirectPlay supplied with the DirectX 5 SDK supports all the APIs and behavior of earlier DirectPlay versions.

For specific information, see:

  • Migrating from DirectPlay 3
  • Migrating from DirectPlay 2 or Earlier

Migrating from DirectPlay 3

If you are migrating to DirectPlay version 5 from DirectPlay version 3, you do not have to make any changes. However, you should upgrade your application to use the new IDirectPlay3 Interface or IDirectPlay3A interfaces.

For a list of new features in version 5 of DirectPlay, see What's New in DirectPlay 5.

Some system messages have changed for DirectPlay 5, with new data members added to the end. Applications that need to be backward-compatible with older run times should either:

  • Compile with the DirectX 3 header files and libraries.
  • Not reference new data members.
  • Test with both the DirectX 3 and the DirectX 5 runtime.

The system message structures that have new members for DirectPlay 5 are:
Structure | New Members
DPMSG_CREATEPLAYERORGROUP | DPID dpIdParent
DWORD dwFlags
DPMSG_DESTROYPLAYERORGROUP | DPNAME dpnName
DPID dpIdParent
DWORD dwFlags

Migrating from DirectPlay 2 or Earlier

The names of the DirectPlay DLLs in version 3 and later are different from those in previous DirectPlay versions. Applications compiled with DirectX 2 or earlier do not use the new DirectPlay DLLs. To use the new DLLs, the application must be recompiled and linked to the Dplayx.lib import library.

It is also recommended that you add the code necessary to make the application lobby-aware. This means that an external lobby or matchmaking program can start the application and supply it with all the information necessary to connect to a session. The application need not ask the user to decide on a service provider, select a session, or supply any other information (such as a telephone number or network address).

In addition, several other new features were added in the DirectPlay version 5 API, including:

  • Internet support.
  • Direct serial connection.
  • More stability and robustness.
  • Support for Unicode to better support localization.
  • Host migration. If the host of a session drops out of the session, host responsibilities are passed on to another player. In DirectPlay version 2, if the host (name server) left a session, no new players could be created.
  • Ability of the application to communicate with the lobby program to update games status for spectators, as well as receive information about initial conditions.
  • Ability to host more than one application session on a computer.
  • Ability to determine when a remote computer loses its connection and to generate appropriate messages.

There are other features in DirectPlay 5 that you can use to reduce the amount of communication-management code in your application, including the following:

  • Ability to associate application-specific data with a DirectPlay group ID or player ID. This allows the application to leverage the player and group list-management code that is already part of DirectPlay. Local data is data that the local application uses directly, such as a bitmap that represents a player. Local data is not propagated over the network. Remote data is associated with the player or group. DirectPlay propagates any changes to remote data to all other applications in the session. Remote data must be shared among all the applications in a session, such as a player's position, orientation, and velocity. By using DirectPlay functions to propagate this data, the application need not manage it by using a series of methods that send and receive information.
  • Ability for the application to associate a name with a group. This is useful for team play.

Some of the new features added to DirectPlay 5 are not directly related to applications, including the following:

  • APIs that the lobby client software uses to start and connect a lobby-able DirectPlay application. Also included are APIs that allow an application and the lobby to exchange information during a session.
  • Service provider development kit that includes documentation and sample code for creating your own service provider.

Migrating to the IDirectPlay3 Interface

To migrate an application created with DirectPlay version 2 or earlier, carry out the following steps:

  1. Find out if your application was launched from a lobby client. For more information, see Step 2: Retrieving the Connection Settings.
  2. If your application is enumerating service providers, use the EnumConnections method to determine if a service provider is available. If so, call the InitializeConnection method on the service provider. If InitializeConnection returns an error, the service provider cannot run on the system, and you should not add that service provider to the list to show to the user. If the call succeeds, use the Release method to release the DirectPlay object and add the service provider to the list.
  3. Call the QueryInterface method on the IDirectPlay interface to obtain an IDirectPlay3 (Unicode) or IDirectPlay3A (ANSI) interface. The only difference between the two interfaces is how strings in the structures are read and written. For the Unicode interface, Unicode strings are read and written to the member of the structure that is of the LPWSTR type. For the ANSI interface, ANSI strings are read and written to the member of the structure that is of the LPSTR type.
  4. Make all the changes necessary to use the new structures in existing APIs. For example, instead of the following:
    lpDP->SetPlayerName(pidPlayer, lpszFriendlyName, lpszFormalName)

    where lpDP is an IDirectPlay interface, use the following:

    DPNAME PlayerName, *lpPlayerName;
PlayerName.dwSize = sizeof(DPNAME);
lpPlayerName = &PlayerName;

lpPayerName->lpszShortNameA = lpszFriendlyName;
lpPlayerName->lpszLongNameA = lpszFormalName;
lpDP3A->SetPlayerName(pidPlayer, lpPlayerName, 0)

    where lpDP3A is an IDirectPlay3A interface. If the application is using Unicode strings (and therefore instantiates an IDirectPlay3 interface), use the following:

    lpPayerName->lpszShortName = lpwszFriendlyName;
lpPlayerName->lpszLongName = lpwszFormalName;
lpDP3->SetPlayerName(pidPlayer, lpPlayerName, 0)

    where lpDP3 is an IDirectPlay3 interface.

  5. Update the following system messages:
    • DPSYS_ADDPLAYER has been replaced by DPSYS_CREATEPLAYERORGROUP.
    • DPSYS_DELETEPLAYER and DPSYS_DELETEGROUP have been combined in a single DPSYS_DESTROYPLAYERORGROUP message.
    • DPSYS_DELETEPLAYERFROMGRP has been changed to DPSYS_DELETEPLAYERFROMGROUP.
  6. Update your application to generate a DPSYS_SETPLAYERORGROUPNAME message when a player or group name changes, and a DPSYS_SETPLAYERORGROUPDATA message when the player or group data changes.
  7. Update the DPSESSIONDESC structure to DPSESSIONDESC2, and add the new members to the DPCAPS structure.
  8. Update the callback functions for IDirectPlay3::EnumSessions, IDirectPlay3::EnumGroups, IDirectPlay3::EnumGroupPlayers, and IDirectPlay3::EnumPlayers.
  9. Update the manner in which the hEvent parameter is supplied to the IDirectPlay3::CreatePlayer method. In previous versions of DirectPlay, this parameter was lpEvent. DirectPlay does not return an event; instead, the application must create it. This allows the application the flexibility of creating one event for all the players.
  10. Set the DPSESSION_KEEPALIVE flag in the DPSESSIONDESC2 structure if the application needs DirectPlay to detect when players drop out of the game abnormally.
  11. Update your application to create sessions with the DPSESSION_MIGRATEHOST flag. This enables another computer to become the host if the current host drops out of the session. If your application has any special code that only the host runs, then your application should set this flag when it creates a session. It should also add support for the DPSYS_HOST system message. For a list of system messages, see Using System Messages.
  12. Become familiar with the new methods of the IDirectPlay3 interface and use them in your application. Pay particular attention to the IDirectPlay3::SetPlayerData and IDirectPlay3::GetPlayerData methods. You might be able to substitute the code where you broadcast player state information to all the other players by using the IDirectPlay3::Send and IDirectPlay3::Receive methods.

DirectPlay Tools and Samples

The following samples show how to use DirectPlay. These DirectPlay samples are included on the DirectX 5 CD-ROM. The Control Panel tool can be used to find out about DirectPlay applications.

DirectX Control Panel Tool

  • Found in Control Panel. Double-click to open the DirectX Properties dialog box.
  • The DirectPlay tab displays all the registered DirectPlay service providers and applications.
  • Open the DirectX Properties dialog box before starting a DirectPlay application to see on-the-fly statistics about DirectPlay communications such as bytes/second and messages/second.

SDK/SAMPLES/BELLHOP

  • A lobby client program that uses the IDirectPlay3 interface to communicate with a lobby server.
  • Uses the LSERVER test lobby server so that a real lobby client/server environment can be set up.
  • BELLHOP can be used to test external lobby support in your application.
  • LSERVER can be used as a test server to write your own lobby client or integrate a lobby client into your application.

SDK/SAMPLES/DPCHAT

  • A simple Windows-based chat program that uses IDirectPlay3.
  • Uses IDirectPlayLobby to make it lobby-able.

SDK/SAMPLES/DPLAUNCH

  • A stand-alone application that demonstrates how a DirectPlay 5 application can be launched from an external source using the IDirectPlayLobby2 interface.
  • Can also be used to test the lobby support in your application.

SDK/SAMPLES/DPSLOTS

  • A DirectPlay client/server application that uses security.
  • The server controls all the slot machines and tracks how much money each player has.
  • The client securely logs in to the server.

SDK/SAMPLES/DUEL

  • A multiplayer game that uses the IDirectPlay interface.
  • Uses IDirectPlayLobby to make it lobby-able.

SDK/SAMPLES/DXVIEW

  • An application that shows all the available service providers and their capabilities.
  • Shows all the registered lobby-aware applications installed on the system.
  • Uses asynchronous EnumSessions to monitor the active sessions on the service provider.

SDK/SAMPLES/OVERRIDE

  • A simple demonstration of how to override the DirectPlay service provider dialogs.

Security and Authentication

DirectPlay security allows an application running on a server to authenticate users against a database of known users before allowing them to join a session. Once a user has been authenticated, all communications between the client and server can be done securely either by digitally signing messages (to verify the identity of the sender) or by encrypting the messages.

The following diagram shows DirectPlay security architecture. (SSPI = Security Support Provider Interface, CAPI = CryptoAPI, MS RSA Base CP = Microsoft RSA Base Cryptographic Provider, NTLM = NT LAN Manager.)

DirectPlay security architecture

User and Message Authentication

DirectPlay provides user and message authentication (digital signing) support through the Windows® Security Support Provider Interface (SSPI). This is a standard interface that gives software access to various security packages under the Windows operating system. A security package is an implementation of a protocol between a client and server that establishes the identity of the client and provides other security services, such as digital signing. The default security package that DirectPlay uses is called NTLM (Windows® NT® LAN Manager) Security Support Provider.

This security package is based on the NTLM authentication protocol. NTLM is a shared-secret, user challenge-response authentication protocol that supports pass-through authentication to a domain controller in the server's domain or in a domain trusted by the current domain's domain controller. This protocol provides a high level of security because passwords are never sent out on the network. NTLMSSP ships with the Windows 95 and Windows NT operating systems.

A DirectPlay application can choose to use a different SSPI security package when it creates a session by calling the SecureOpen method. For example, DPA (Distributed Password Authentication) Security Support Provider is another security package that organizations can use to provide membership services to a large customer base (hundreds of thousands). This security package is available through the Microsoft Commercial Internet Services (MCIS) Membership Server.

Message Privacy (encryption/decryption)

DirectPlay provides message encryption support through the Windows Cryptography Application Programming Interface (CAPI). This is a standard interface similar to SSPI that gives software access to various cryptographic packages under the Windows operating system. This architecture allows DirectPlay applications to plug in cryptographic packages that provide the desired level of encryption (40 bit, 128 bit, and so on) legally allowed in the locale of use.

The default CryptoAPI (CAPI) provider for DirectPlay cryptography services is the Microsoft RSA Base Cryptographic Provider version 1.0. The default CAPI provider type is PROV_RSA_FULL. The default encryption algorithm is the CALG_RC4 stream cipher. This provider is supplied by Microsoft and is included with Microsoft Internet Explorer for Windows 95, Windows 95 OSR-2 Update, and Windows NT 4.0 operating system.

A DirectPlay application can choose to use a different cryptographic provider when it creates a session by using the SecureOpen method. Please note that DirectPlay only supports stream ciphers.

For more information about SSPI, NTLM, DPA, MCIS, CAPI, and the RSA Base Cryptographic Provider, see http://www.microsoft.com.

Secure Sessions

User authentication should not be confused with password protection of a session. Authentication is used to verify that the user is allowed access to the server by virtue of having been added to the membership database by the administrator of the server. Only users that are part of the membership database are permitted to join the session. A password can be added to a session, so that only those members who know the password can join a particular session. Additionally, authentication requires a server that supports authentication, while any computer can put a password on a session.

For example, a server on the Internet might have a membership of a thousand users. Anybody can enumerate the sessions that are available on the server, but only members will be able to join sessions on the server. Users who want only their friends (who are members) to be able to join can put a password on their session.

Once a secure server has been set up and an initial membership list has been established, a secure DirectPlay session can be started. Creating a secure DirectPlay session simply requires the server to create a session using IDirectPlay3::Open or IDirectPlay3::SecureOpen and to specify the DPSESSION_SECURESERVER flag in the DPSESSIONDESC2 structure.

A DirectPlay application can choose to use alternate providers when it creates a session by calling the SecureOpen method and specifying the providers to use in the DPSECURITYDESC structure. For a different SSPI provider (for user and message authentication), an application needs to specify the provider name in the lpszSSPIProvider member of the DPSECURITYDESC structure. For a different CryptoAPI provider (for message privacy), an application needs to specify the provider name, provider type, and encryption algorithm in the lpszCAPIProvider, dwCAPIProviderType, and dwEncryptionAlgorithm members, respectively.

When a client enumerates this session, the DPSESSIONDESC2 structure returned by IDirectPlay3::EnumSessions will have the DPSESSION_SECURESERVER flag set. This tells the client that authentication credentials will be required to join the session. If the client attempts to join the session using IDirectPlay3::Open, the security package may allow the user in if the user's credentials were already established through a system log on (for example, through NT LAN Manager). Otherwise, a DPERR_LOGONDENIED error is returned. The application must then collect credentials from the user, put them in a DPCREDENTIALS structure, and try to join the session again by calling SecureOpen, passing in the DPCREDENTIALS structure. SecureOpen is recommended for security.

Within a secure session, all DirectPlay system messages are digitally signed to verify the identity of the sender. Certain system messages that carry sensitive information are encrypted. System messages that originate from one player and need to be broadcast to all the other players in the session are first sent to the server. The server then puts its signature on the message and forwards the message to all the other computers in the session. Player to player messages are not signed by default and are not routed through the server.

An application can choose to sign or encrypt specific player-to-player messages using the DPSEND_SIGNED and DPSEND_ENCRYPTED flags in the IDirectPlay3::Send method. Signed and encrypted player messages are routed through the server and delivered as secure system messages. When a secure message is received by a player, the message will contain flags indicating whether the message came in signed or encrypted. Messages that do not pass the verification are dropped.


DirectPlay Interface Overviews

DirectPlay is composed of objects and interfaces based on the component object model (COM). COM is a foundation for an object-based system that focuses on the reuse of interfaces, and it is the model at the heart of OLE programming. It is also an interface specification from which any number of interfaces can be built.

New methods and functionality are exposed in COM through the use of new interfaces that are sequentially numbered. The current DirectPlay interface is called IDirectPlay3. The old interfaces, IDirectPlay and IDirectPlay2, still exist for backward compatibility with applications written to those interfaces.

This section contains general information about the following DirectPlay COM interfaces:

  • Unicode vs. ANSI Interfaces
  • IDirectPlay Interface
  • IDirectPlay2 Interface
  • IDirectPlay3 Interface
  • IDirectPlayLobby Interface
  • IDirectPlayLobby2 Interface

Unicode vs. ANSI Interfaces

DirectPlay supports both Unicode and ANSI strings by defining string pointers in a structure as the union of a Unicode string pointer (LPWSTR) and an ANSI string pointer (LPSTR). The two string pointers have different names. Typically, the ANSI member ends with the letter "A". Depending on which IDirectPlay interface is chosen (IDirectPlay3 Interface for Unicode or IDirectPlay3A for ANSI), or which IDirectPlayLobby2 interface is chosen (IDirectPlayLobby2 Interface for Unicode or IDirectPlayLobby2A for ANSI), the application should read and write the appropriate strings from the structure and ignore the other one.

IDirectPlay Interface

The IDirectPlay COM interface remains part of DirectPlay version 5. It contains the methods required to run applications that were written for the DirectX SDK versions 1 and 2. Although you could use this interface to create new applications, it is recommended that you use the newer DirectPlay interfaces, IDirectPlay3 Interface and IDirectPlay3A, to take advantage of their increased functionality.

IDirectPlay2 Interface

The IDirectPlay2 COM interface remains part of DirectPlay version 5. It contains the methods required to run applications that were written for the DirectX SDK version 3. Although you could use this interface to create new applications, it is recommended that you use the newer DirectPlay interfaces, IDirectPlay3 Interface and IDirectPlay3A, to take advantage of their increased functionality.

IDirectPlay3 Interface

IDirectPlay3 is the latest interface. It directly inherits from IDirectPlay2, so any code written for IDirectPlay2 will work with IDirectPlay3 with no modification.

The new methods in IDirectPlay3 are:

  • AddGroupToGroup
  • CreateGroupInGroup
  • DeleteGroupFromGroup
  • EnumConnections
  • EnumGroupsInGroup
  • GetGroupConnectionSettings
  • GetGroupFlags
  • GetGroupParent
  • GetPlayerAccount
  • GetPlayerFlags
  • InitializeConnection
  • SecureOpen
  • SendChatMessage
  • SetGroupConnectionSettings
  • StartSession

IDirectPlayLobby Interface

The IDirectPlayLobby COM interface remains part of DirectPlay version 5. It contains the methods required to run applications that were written for the DirectX SDK versions 1 and 2. Although you could use this interface to create new applications, it is recommended that you use the newer DirectPlay interface, IDirectPlayLobby2 Interface, to take advantage of its increased functionality.

IDirectPlayLobby2 Interface

The IDirectPlayLobby2 Interface interface lets game developers launch external applications, enable communication between an application and a lobby client, and manipulate DirectPlay Addresses.

IDirectPlayLobby2 supports all the methods of IDirectPlayLobby. See Building Lobby-Aware Applications for information about detecting a launch by an external lobby and registering lobby-aware applications. See DirectPlay Lobby Overview for general information about lobby sessions.

The new method in IDirectPlayLobby2 is:

  • CreateCompoundAddress


DirectPlay Tutorials

This section contains four tutorials that provide step-by-step instructions about how to connect an application with or without a lobby, how to override service provider dialog boxes, and how to create a self-refreshing session list.

The first tutorial demonstrates how to connect an application by using a DirectPlay lobby.

The second tutorial demonstrates how to connect an application by using a dialog box that queries the user for connection information. You should write your application so that it can start by using either method. The code is available in the DPCHAT sample in the LOBBY.CPP and DIALOG.CPP files.

The third tutorial demonstrates the calls you need to supply the service provider with all the information it needs so that it doesn't display dialog boxes to the user requesting information.

The fourth tutorial demonstrates how to create a self-refreshing session list.

  • Tutorial 1: Connecting by Using the Lobby (DPCHAT)
  • Tutorial 2: Connecting by Using a Dialog Box (DPCHAT)
  • Tutorial 3: Overriding the Service Provider Dialogs
  • Tutorial 4: Creating Self-Refreshing Session Lists

Note The sample files in these tutorials are written in C++. If you are using a C compiler, you must make the appropriate changes to the files for them to successfully compile. At the very least, you must add the vtables and this pointers to the interface methods. For more information, see Accessing COM in the DirectX Foundation Software Development Kit.

Tutorial 1: Connecting by Using the Lobby

An application written to use the IDirectPlayLobby2 Interface interface can be connected to a session without requiring the user to manually enter connection information in a dialog box. To demonstrate how to create a lobbied application, the DPCHAT sample performs the following steps:

  • Step 1: Creating a DirectPlayLobby Object
  • Step 2: Retrieving the Connection Settings
  • Step 3: Configuring the Session Description
  • Step 4: Connecting to a Session
  • Step 5: Creating a Player

Step 1: Creating a DirectPlayLobby Object

To use a DirectPlay lobby, you first create an instance of a DirectPlayLobby object by calling the DirectPlayLobbyCreate function. This function contains five parameters. The first, third, and fourth parameters are always set to NULL and are included for future expansion. The second parameter contains the address of a pointer that identifies the location of the DirectPlayLobby object if it is created. The fifth parameter is always set to 0, and is also included for future expansion.

The following example shows one way to create a DirectPlayLobby object:

// Get an ANSI DirectPlay lobby interface.
hr = DirectPlayLobbyCreate(NULL, &lpDirectPlayLobbyA, NULL, NULL, 0);
if FAILED(hr)
    goto FAILURE;

Step 2: Retrieving the Connection Settings

After the DirectPlayLobby object has been created, use the IDirectPlayLobby2::GetConnectionSettings method to retrieve the connection settings returned from the lobby. If this method returns DPERR_NOTLOBBIED, the lobby did not start this application, and the user will have to configure the connection manually. If any other error occurs, your application should report an error that indicates that lobbying the application failed.

The following example shows how to retrieve the connection settings:

// Retrieve the connection settings from the lobby.
// If this routine returns DPERR_NOTLOBBIED, then a lobby did not
// start this application and the user needs to configure the
// connection.

// Pass a NULL pointer to retrieve only the size of the
// connection settings
hr = lpDirectPlayLobbyA->GetConnectionSettings(0, NULL, &dwSize);
if (DPERR_BUFFERTOOSMALL != hr)
    goto FAILURE;

// Allocate memory for the connection settings.
lpConnectionSettings = (LPDPLCONNECTION) GlobalAllocPtr(GHND, dwSize);
    if (NULL == lpConnectionSettings)
    {
        hr = DPERR_OUTOFMEMORY;
        goto FAILURE;
    }

    // Retrieve the connection settings.
    hr = lpDirectPlayLobbyA->GetConnectionSettings(0,
        lpConnectionSettings, &dwSize);
    if FAILED(hr)
        goto FAILURE;

Step 3: Configuring the Session Description

You should examine the DPSESSIONDESC2 structure to ensure that all the flags and properties that your application needs are set properly. If modifications are necessary, store the modified connection settings by using the IDirectPlayLobby2::SetConnectionSettings method.

The following example shows how to configure the session description and set the connection settings:

// Before the game connects, it should configure the session
// description with any settings it needs.

// Set the flags and maximum players used by the game.
lpConnectionSettings->lpSessionDesc->dwFlags = DPSESSION_MIGRATEHOST |
    DPSESSION_KEEPALIVE;
lpConnectionSettings->lpSessionDesc->dwMaxPlayers = MAXPLAYERS;

// Store the updated connection settings.
hr = lpDirectPlayLobbyA->SetConnectionSettings(0, 0,
        lpConnectionSettings);
if FAILED(hr)
    goto FAILURE;

Step 4: Connecting to a Session

After the session description is properly configured, your application can use the IDirectPlayLobby2::Connect method to start and connect itself to a session. If this method returns DP_OK, you can create one or more players. If it returns DPERR_NOTLOBBIED, the user will have to manually select a communication medium for your application. (You can identify the service providers installed on the system by using the IDirectPlay3::EnumConnections function.) If any other error value is returned, your application should report an error that indicates that lobbying the application failed.

The following example shows how to connect to a session:

// Connect to the session. Returns an ANSI IDirectPlay2A interface.
hr = lpDirectPlayLobbyA->Connect(0, &lpDirectPlay2A, NULL);
if FAILED(hr)
    goto FAILURE;
// Obtain an IDriectPlay3A interface
hr= lpDirectPlay2A->QueryInterface(IID_IDirectPlay3A, (LPVOID*)&lpDirectPlay3A);
if FAILED(hr)
    goto FAILURE;

Step 5: Creating a Player

If the application was successfully started by using the IDirectPlayLobby2::Connect method, it can now create one or more players. It can use the IDirectPlay3::CreatePlayer method to create a player with the name specified in the DPNAME structure (which was filled in by the IDirectPlayLobby2::GetConnectionSettings method).

The following example shows how to create a player:

// create a player with the name returned in the connection settings
hr = lpDirectPlay3A->CreatePlayer(&dpidPlayer,
    lpConnectionSettings->lpPlayerName,
    lpDPInfo->hPlayerEvent, NULL, 0, 0);
if FAILED(hr)
    goto FAILURE;

Now your application is connected and you are ready to play.

Tutorial 2: Connecting by Using a Dialog Box

If a lobby did not start your application, you should include code that allows the user to manually enter the connection information. To demonstrate how to manually connect to the session and create one or more players, the DPCHAT sample performs the following steps:

  • Step 1: Creating the DirectPlay Object
  • Step 2: Enumerating and Initializing the Service Providers
  • Step 3: Joining a Session
  • Step 4: Creating a Session
  • Step 5: Creating a Player

Step 1: Creating the DirectPlay Object

Before any methods can be called, the application must create an interface to a DirectPlay object.

The following example shows how the create the IDirectPlay3A interface:

HRESULT CreateDirectPlayInterface( LPDIRECTPLAY3A *lplpDirectPlay3A )
{
   HRESULT         hr;
   LPDIRECTPLAY3A  lpDirectPlay3A = NULL;

   // Create an IDirectPlay3 interface
   hr = CoCreateInstance( CLSID_DirectPlay, NULL, CLSCTX_INPROC_SERVER,
                            IID_IDirectPlay3A, (LPVOID*)&lpDirectPlay3A);

   // Return interface created
   *lplpDirectPlay3A = lpDirectPlay3A;

   return (hr);
}

Step 2: Enumerating and Initializing the Service Providers

The next step in creating a manual connection is to request that the user select a communication medium for the application. Your application can identify the service providers installed on a personal computer by using the EnumConnections method.

The following example shows how to enumerate the service providers:

lpDirectPlay3A->EnumConnections(&DPCHAT_GUID, DirectPlayEnumConnectionsCallback, hWnd, 0);

The second parameter in the EnumConnections method is a callback that enumerates service providers registered with DirectPlay. The following example shows one possible way of implementing this callback function:

BOOL FAR PASCAL DirectPlayEnumConnectionsCallback(
     LPCGUID lpguidSP, LPVOID lpConnection, DWORD dwConnectionSize,
     LPCDPNAME lpName, DWORD dwFlags, LPVOID lpContext)
{
   HWND     hWnd = (HWND) lpContext;
   LRESULT	iIndex;
   LPVOID   lpConnectionBuffer;

   // Store service provider name in combo box
   iIndex = SendDlgItemMessage(hWnd, IDC_SPCOMBO, CB_ADDSTRING, 0,
       (LPARAM) lpName->lpszShortNameA);
   if (iIndex == CB_ERR)
     goto FAILURE;

   // make space for connection
   lpConnectionBuffer = GlobalAllocPtr(GHND, dwConnectionSize);
   if (lpConnectionBuffer == NULL)
     goto FAILURE;

   // Store pointer to connection  in combo box
   memcpy(lpConnectionBuffer, lpConnection, dwConnectionSize);
   SendDlgItemMessage(hWnd, IDC_SPCOMBO, CB_SETITEMDATA, (WPARAM) iIndex,
       (LPARAM) lpConnectionBuffer);

FAILURE:
    return (TRUE);
}

Once the user selects which connection to use, the DirectPlay object must be initialized with the connection buffer associated with it.

hr = lpDirectPlay3A->InitializeConnection(lpConnection, 0);

Step 3: Joining a Session

If the user wants to join an existing session, enumerate the available sessions by using the IDirectPlay3::EnumSessions method, present the choices to the user, and then connect to that session by using the IDirectPlay3::Open method, specifying the DPOPEN_JOIN flag. The service provider might display a dialog box requesting some information from the user before it can enumerate the sessions.

See Tutorial 4 for details on the asynchronous EnumSessions functionality.

The following example shows how to enumerate the available sessions:

// Search for this kind of session.
ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));
sessionDesc.dwSize = sizeof(DPSESSIONDESC2);
sessionDesc.guidApplication = DPCHAT_GUID;

hr = lpDirectPlay3A->EnumSessions(&sessionDesc, 0, EnumSessionsCallback,
    hWnd, DPENUMSESSIONS_AVAILABLE);
if FAILED(hr)
    goto FAILURE;

In the previous example, the third parameter in the IDirectPlay3A::EnumSessions method is a callback that enumerates the available sessions. The following example shows one way to implement this callback function:

BOOL FAR PASCAL EnumSessionsCallback(
    LPCDPSESSIONDESC2 lpSessionDesc, LPDWORD lpdwTimeOut,
    DWORD dwFlags, LPVOID lpContext)
{
HWND   hWnd = lpContext;
LPGUID lpGuid;
LONG   iIndex;

// Determine if the enumeration has timed out.
if (dwFlags & DPESC_TIMEDOUT)
    return (FALSE);            // Do not try again

// Store the session name in the list.
iIndex = SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_ADDSTRING,
    (WPARAM) 0, (LPARAM) lpSessionDesc->lpszSessionNameA);
if (iIndex == CB_ERR)
    goto FAILURE;

// Make space for the session instance GUID.
lpGuid = (LPGUID) GlobalAllocPtr(GHND, sizeof(GUID));
if (lpGuid == NULL)
    goto FAILURE;

// Store the pointer to the GUID in the list.
*lpGuid = lpSessionDesc->guidInstance;
SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_SETITEMDATA,
    (WPARAM) iIndex, (LPARAM) lpGuid);

FAILURE:
    return (TRUE);
}

After the user has selected a session, your application can allow the user to join an existing session. The following example shows how to join an existing session:

// Join an existing session.
ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));
sessionDesc.dwSize = sizeof(DPSESSIONDESC2);
sessionDesc.guidInstance = *lpguidSessionInstance;

hr = lpDirectPlay3A->Open(&sessionDesc, DPOPEN_JOIN);
if FAILED(hr)
    goto OPEN_FAILURE;

Step 4: Creating a Session

If the user wants to create a new session, your application can create it by using the IDirectPlay3::Open method and specifying the DPOPEN_CREATE flag. Again, the service provider might display a dialog box requesting information from the user before it can create the session.

The following example shows how to create a new session:

// Host a new session.
ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));
sessionDesc.dwSize = sizeof(DPSESSIONDESC2);
sessionDesc.dwFlags = DPSESSION_MIGRATEHOST | DPSESSION_KEEPALIVE;
sessionDesc.guidApplication = DPCHAT_GUID;
sessionDesc.dwMaxPlayers = MAXPLAYERS;
sessionDesc.lpszSessionNameA = lpszSessionName;

hr = lpDirectPlay3A->Open(&sessionDesc, DPOPEN_CREATE);
if FAILED(hr)
    goto OPEN_FAILURE;

Step 5: Creating a Player

After a session has been created or joined, your application can create one or more players by using the IDirectPlay3::CreatePlayer method. The following example shows one way to create a player:

// Fill out the name structure.
ZeroMemory(&dpName, sizeof(DPNAME));
dpName.dwSize = sizeof(DPNAME);
dpName.lpszShortNameA = lpszPlayerName;
dpName.lpszLongNameA = NULL;

// Create a player with this name.
hr = lpDirectPlay3A->CreatePlayer(&dpidPlayer, &dpName,
    lpDPInfo->hPlayerEvent, NULL, 0, 0);
if FAILED(hr)
    goto CREATEPLAYER_FAILURE;

Your application can determine a player's communication capabilities by using the IDirectPlay3::GetCaps and IDirectPlay3::GetPlayerCaps methods. Your application can find other players by using the IDirectPlay3::EnumPlayers method.

Now your application is connected and you are ready to play.

Tutorial 3: Overriding the Service Provider Dialogs

DirectPlay now gives applications the ability to suppress the standard service provider dialogs. Below is a brief outline of how this is done. A code example can be found in the OVERRIDE sample application.

It is generally not possible to suppress all service provider dialogs. The standard TCP/IP, modem, and serial service provider dialogs can be suppressed (IPX has no dialog box). However, there is the possibility that third party service providers might require fairly complex information from the user which cannot be overridden in any general way. The solution is to simply allow these dialog boxes to appear over your application user interface. If the application is a DirectDraw® full-screen application, be sure to turn off page flipping before calling IDirectPlay3::EnumSessions or IDirectPlay3::Open to create a session.

Another way to suppress service provider dialog boxes is to make your application lobby-aware. Most third party service providers will also have a lobby from which to launch games, and games launched from a lobby do not display a connection dialog box.

An application first calls IDirectPlay3::EnumConnections to see which connections are available, presents the list to the user, and allows the user to select one. Once the user has selected one, the application can attempt to override the dialog box before calling IDirectPlay3::EnumSessions or IDirectPlay3::Open.

These are the steps you should follow to suppress service provider dialog boxes:

  1. Examine the service provider GUID of the selected service provider to see if it matches one of the known service providers that the application knows how to override. If the service provider GUID is unknown, then skip the remaining steps and be prepared to allow a dialog box to appear.
  2. Display the appropriate user interface to collect the information needed from the user for that specific service provider. IPX requires no information. TCP/IP requires an IP address for EnumSessions (DPAID_Inet or DPAID_InetW), but requires nothing to create a session using Open. Modem-to-modem requires the user to select a modem (DPAID_Modem or DPAID_ModemW) and also needs a phone number (DPAID_Phone or DPAID_PhoneW) when calling EnumSessions. Serial link needs the DPCOMPORTADDRESS structure (DPAID_ComPort) filled in to configure the COM port for both EnumSessions and Open.
  3. Build a DirectPlay Address using the IDirectPlayLobby2::CreateCompoundAddress method. The address elements that must be passed in are the service provider GUID (DPAID_ServiceProvider) and the individual address components for the selected service provider.
  4. Initialize the DirectPlay object by calling InitializeConnection with the DirectPlay Address.
  5. Call EnumSessions with the DPENUMSESSIONS_RETURNSTATUS flag. This will prevent any status dialog boxes from appearing and, if the connection cannot be made immediately, EnumSessions will return with a DPERR_CONNECTING error. Your application must periodically call EnumSessions until DP_OK is returned (meaning the enumeration was successful) or some other error is returned (meaning it failed).
  6. If a session is to be created using the Open method with DPOPEN_CREATE, specify the DPOPEN_RETURNSTATUS flag as well. Like DPENUMSESSIONS_RETURNSTATUS, this will suppress status dialog boxes and return DPERR_CONNECTING until the function is complete.

Note: In some cases, the application will need to query the service provider at run time to obtain a list of valid choices for a particular DirectPlay Address element. For example, to obtain a list of the modems installed in the system. The application must create a separate DirectPlay object, initialize the modem service provider, and then call IDirectPlay3::GetPlayerAddress with a DPID of zero to obtain a DirectPlay Address that will contain the list of modems. After releasing the DirectPlay object, the application must parse the address using IDirectPlayLobby2::EnumAddress and extract the modem list to present to the user.

Tutorial 4: Creating Self-Refreshing Session Lists

IDirectPlay3::EnumSessions can now be called asynchronously. This gives an application the ability to maintain a self-refreshing session list. A code example can be found in the DUEL and DXVIEW sample applications.

The steps you need to follow to create a self-refreshing session list are:

  1. Call IDirectPlay3::EnumSessions with the DPENUMSESSIONS_ASYNC flag and a time-out of zero (which will use the service provider default). The method will not enumerate any sessions and will return immediately. However, DirectPlay is enumerating sessions in the background.
  2. Display the user interface in which all the sessions will appear. Set a timer to go off at whatever interval you want to refresh your session list. The application can find out what the default time-out interval of the enumeration is by calling IDirectPlay3::GetCaps.
  3. Each time the timer goes off, call EnumSessions to obtain the current session list. This is a complete active session list with stale sessions deleted, new sessions added, and existing sessions updated. Delete all the items from the list before calling EnumSessions and add the sessions back to the list in the EnumSessionsCallback2 function.


DirectPlay Reference

The DirectPlay Reference provides detailed information about functions, callbacks, and the IDirectPlay3 and IDirectPlayLobby2 interface methods, with syntax, parameter descriptions, flag descriptions, return values, and comments about how they are used. It also describes the members of DirectPlay structures, system messages, lobby messages, and defined properties, and the possible error values that can be returned.

Functions

Callback Functions

IDirectPlay3 Interface

IDirectPlayLobby2 Interface

Structures

System Messages

Standard Lobby Messages

DirectPlay Defined Properties

Return Values

Further Reading


Functions

The DirectPlay functions are:

  • DirectPlayCreate - note that this function is obsolete. It is recommended that you use CoCreateInstance instead.
  • DirectPlayEnumerate - note that this function is obsolete. It is recommended that you use IDirectPlay3::EnumConnections instead.
  • DirectPlayLobbyCreate


DirectPlayCreate

This function is obsolete and remains for compatibility with applications written using DirectX 3. It is recommended that applications create the desired DirectPlay interface directly using CoCreateInstance. By using CoCreateInstance you can obtain an IDirectPlay3 interface directly rather than getting an IDirectPlay interface, having to use QueryInterface to access an IDirectPlay3 interface, and releasing the IDirectPlay interface.

Creates a new DirectPlay object and obtains an IDirectPlay interface pointer. If the application supplies GUID_NULL for the lpGUIDSP parameter, this function creates a DirectPlay object but does not initialize a service provider. The application can then call the IDirectPlay3::InitializeConnection method to initialize the service provider or lobby provider.

The application can supply a service provider GUID (see DirectPlayEnumerate) to indicate which service provider to bind.

In order to use the latest DirectPlay functionality, the application must obtain an IDirectPlay3 or IDirectPlay3A interface pointer using the QueryInterface method.

HRESULT WINAPI DirectPlayCreate(
LPGUID lpGUIDSP,
LPDIRECTPLAY FAR *lplpDP,
IUnknown *lpUnk
);

Parameters
lpGUIDSP
Pointer to the GUID of the service provider that the DirectPlay object should be initialized with. Pass in a pointer to GUID_NULL to create an uninitialized DirectPlay object.
lplpDP
Pointer to an interface pointer to be initialized with a valid IDirectPlay interface. The application will need to use the QueryInterface method to obtain an IDirectPlay2, IDirectPlay3 Interface (UNICODE strings) or IDirectPlay2A, IDirectPlay3A (ANSI strings) interface.
lpUnk
Pointer to the containing IUnknown. This parameter is provided for future compatibility with COM aggregation features. Presently, however, the DirectPlayCreate function returns an error if this parameter is anything but NULL.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

CLASS_E_NOAGGREGATION
DPERR_EXCEPTION
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

DPERR_UNAVAILABLE is returned if a DirectPlay object could not be created. DPERR_INVALIDPARAMS is returned if the GUID provided is invalid.

Remarks

This function attempts to initialize a DirectPlay object and sets a pointer to it if successful. Your application should call the DirectPlayEnumerate function immediately before initialization to determine what types of service providers are available (the DirectPlayEnumerate function fills in the lpGUIDSP parameter of DirectPlayCreate).

This function returns a pointer to an IDirectPlay interface. The current interfaces for DirectX 5 are IDirectPlay3 and IDirectPlay3A, which need to be obtained through a call to the QueryInterface method on the IDirectPlay interface returned by DirectPlayCreate.

See Also

IDirectPlay3::InitializeConnection, DirectPlayEnumerate


DirectPlayEnumerate

Enumerates the DirectPlay service providers installed on the system.

This function is obsolete and remains for compatibility with applications written using DirectX 3. It will only enumerate service providers, not DirectPlay Addresses (connections). It is recommended that applications use the IDirectPlay3::EnumConnections method to enumerate all the connections available to the application after creating an IDirectPlay3 interface.

This function will not enumerate service providers that have the Enumerate value in the registry set to zero. For backward compatibility, this function will only return simple service providers registered under the "Service Providers" registry key.

HRESULT WINAPI DirectPlayEnumerate(
LPDPENUMDPCALLBACK lpEnumCallback,
LPVOID lpContext
);

Parameters
lpEnumCallback
Pointer to a callback function that will be called with a description of each DirectPlay service provider installed in the system. Depending on whether UNICODE is defined or not, the prototype for the callback function will have the service provider name lpSPName defined as a LPWSTR (for Unicode) or LPSTR (for ANSI).
lpContext
Pointer to an application-defined structure that will be passed to the callback function each time the function is called.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDPARAMS

DPERR_INVALIDPARAMS is returned if an invalid enumeration callback was supplied.

Remarks

This function will enumerate service providers installed in the system even though the system might not be capable of using those service providers. For example, a TAPI service provider will be part of the enumeration even though the system might not have a modem installed.

See Also

IDirectPlay3::EnumConnections, DirectPlayCreate


DirectPlayLobbyCreate

Creates an instance of a DirectPlayLobby object. This function attempts to initialize a DirectPlayLobby object and set a pointer to it.

HRESULT WINAPI DirectPlayLobbyCreate(
LPGUID lpGUIDSP,
LPDIRECTPLAYLOBBY *lplpDPL,
IUnknown *lpUnk,
LPVOID lpData,
DWORD dwDataSize
);

Parameters
lpGUIDSP
Reserved for future use; must be set to NULL.
lplpDPL
Pointer to a pointer to be initialized with a valid IDirectPlayLobby interface. To get an IDirectPlayLobby2 interface, use this function to get an IDirectPlayLobby interface, then call:
  IDirectPlayLobby->QueryInterface( IID_IDirectPlayLobby2, (LPVOID*) &lpDP2 );
lpUnk
Pointer to the containing IUnknown interface. This parameter is provided for future compatibility with COM aggregation features. Presently, however, DirectPlayLobbyCreate returns an error if this parameter is anything but NULL.
lpData
Extra data needed to create the DirectPlayLobby object. This parameter must be set to NULL.
dwDataSize
This parameter must be set to zero.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

CLASS_E_NOAGGREGATION
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY


Callback Functions

The DirectPlay callback functions are:

  • EnumAddressCallback
  • EnumAddressTypeCallback
  • EnumConnectionsCallback
  • EnumDPCallback
  • EnumLocalApplicationsCallback
  • EnumPlayersCallback2
  • EnumSessionsCallback2


EnumAddressCallback

Application-defined callback function for the IDirectPlayLobby2::EnumAddress method.

BOOL FAR PASCAL EnumAddressCallback(
REFGUID guidDataType,
DWORD dwDataSize,
LPCVOID lpData,
LPVOID lpContext
);

Parameters
guidDataType
Pointer to a globally unique identifier (GUID) indicating the type of this data chunk. For example, this parameter might be &DPAID_Phone or &DPAID_INet. (In C++, it is a reference to the GUID.)
dwDataSize
Size, in bytes, of the data chunk.
lpData
Pointer to the constant data.
lpContext
Context passed to the callback function.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

The service provider should examine the GUID in the guidDataType parameter and process or store the value specified in lpData. Unrecognized values in guidDataType can be ignored.

Any pointers returned in a callback function are temporary and are valid only in the body of the callback function. If the application needs to save pointer information, it must allocate memory to hold the data, copy the data, and then store the pointer to this new data. In this function, lpData is temporary.


EnumAddressTypeCallback

Application-defined callback function for the IDirectPlayLobby2::EnumAddressTypes method.

BOOL FAR PASCAL EnumAddressTypeCallback(
REFGUID guidDataType,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
guidDataType
Pointer to a globally unique identifier (GUID) indicating the address type. (In C++, it is a reference to the GUID.) Predefined address types are DPAID_Phone, DPAID_INet, and DPAID_ComPort. For more information about these address types, see DirectPlay Address.
lpContext
Context passed to the callback function.
dwFlags
Reserved; do not use.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.


EnumConnectionsCallback

Application-defined callback function for the IDirectPlay3::EnumConnections method.

BOOL FAR PASCAL EnumConnectionsCallback(
LPCGUID lpguidSP,
LPVOID lpConnection,
DWORD dwConnectionSize,
LPCDPNAME lpName,
DWORD dwFlags,
LPVOID lpContext
);

Parameters
lpguidSP
The GUID of the DirectPlay service provider or lobby provider associated with the connection. Use this GUID to uniquely identify the service or lobby provider, rather than using the order in the enumeration or the name.
lpConnection
A read-only pointer to a buffer that contains the connection. This parameter is passed to the IDirectPlay3::InitializeConnection method to initialize the DirectPlay object. This buffer contains a DirectPlay Address.
dwConnectionSize
The size, in bytes, of the lpConnection buffer.
lpName
A read-only pointer to a DPNAME structure. The structure contains the short name of the connection that should appear to the user.
If IDirectPlay3::EnumConnections was called on an ANSI interface, reference the strings as ANSI. If EnumConnections was called on a Unicode interface, reference the strings as Unicode.
dwFlags
Flags to indicate the type of connection. Not used at this time.
lpContext
Pointer to an application-defined context.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

The application must implement this function in order to use the IDirectPlay3::EnumConnections method. It is called once for each connection that is enumerated.

The application should allocate memory and copy each of the connections for presentation to the user and for use in the IDirectPlay3::InitializeConnection method.

See Also

IDirectPlay3::EnumConnections, IDirectPlay3::InitializeConnection, Using DirectPlay Addresses


EnumDPCallback

Application-defined callback function for the DirectPlayEnumerate function. Depending on whether UNICODE is defined or not, the prototype for the callback function will have lpSPName defined as either the LPWSTR type (for Unicode) or the LPSTR type (for ANSI).

BOOL FAR PASCAL EnumDPCallback(
LPGUID lpguidSP,
LPSTR/LPWSTR lpSPName,
DWORD dwMajorVersion,
DWORD dwMinorVersion,
LPVOID lpContext
);

Parameters
lpguidSP
Pointer to the unique identifier of the DirectPlay service provider.
lpSPName
Pointer to a string containing the driver description. Depending on whether the UNICODE symbol is defined or not, the parameter will be of the LPWSTR type (Unicode) or the LPSTR type (ANSI).
dwMajorVersion and dwMinorVersion
Major and minor version numbers of the driver.
lpContext
Pointer to an application-defined context.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

Any pointers returned in a callback function are temporary and are valid only in the body of the callback function. If the application needs to save pointer information, it must allocate memory to hold the data, copy the data, and then store the pointer to this new data. In this function, lpGUIDSP and lpSPName are temporary.


EnumLocalApplicationsCallback

Application-defined callback function for the IDirectPlayLobby2::EnumLocalApplications method.

BOOL FAR PASCAL EnumLocalApplicationsCallback(
LPCDPLAPPINFO lpAppInfo,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpAppInfo
Pointer to a read-only DPLAPPINFO structure containing information about the application being enumerated.
lpContext
Context passed from the IDirectPlayLobby2::EnumLocalApplications call.
dwFlags
Reserved; do not use.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

Any pointers returned in a callback function are temporary and are valid only in the body of the callback function. If the application needs to save pointer information, it must allocate memory to hold the data, copy the data, and then store the pointer to this new data. In this function, lpAppInfo is temporary. Also note that the pointers inside the structure specified in the lpAppInfo parameter—lpszAppNameA and lpszAppName—are also temporary.


EnumPlayersCallback2

Application-defined callback function. The application must implement this function and pass a pointer to it in the IDirectPlay3::EnumGroups, IDirectPlay3::EnumGroupPlayers, IDirectPlay3::EnumPlayers, and IDirectPlay3::EnumGroupsInGroup methods. The callback is called once for each player/group that is enumerated.

BOOL FAR PASCAL EnumPlayersCallback2(
DPID dpId,
DWORD dwPlayerType,
LPCDPNAME lpName,
DWORD dwFlags,
LPVOID lpContext
);

Parameters
dpId
The DPID of the player or group being enumerated.
dwPlayerType
Type of entity, either DPPLAYERTYPE_GROUP or DPPLAYERTYPE_PLAYER.
lpName
Read only pointer to a DPNAME structure containing the name of the player or group. This pointer is only valid for the duration of the callback function. Any data that is to be saved for future reference must be copied to some application owned memory.
dwFlags
Flags describing the group or player being enumerated.
DPENUMGROUPS_SHORTCUT — the group is a shortcut.
DPENUMGROUPS_STAGINGAREA — the group is a staging area.
DPENUMPLAYERS_GROUP — both players and groups are being enumerated. This flag is returned only if it was specified in the enumeration method calling this callback.
DPENUMPLAYERS_LOCAL — the player or group exists on a local computer. This flag is returned only if it was specified in the enumeration method calling this callback.
DPENUMPLAYERS_REMOTE — the player or group exists on a remote computer. This flag is returned only if it was specified in the enumeration method calling this callback.
DPENUMPLAYERS_SESSION — the player or group exists in the session identified by lpguidInstance in the enumeration method. This flag is returned only if it was specified in the enumeration method calling this callback.
DPENUMPLAYERS_SERVERPLAYER — the player is the server player in an application/server session. Only one server player exists in each session.
DPENUMPLAYERS_SPECTATOR — the player is a spectator (applies to players only).
lpContext
Pointer to an application-defined context.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

Any pointers returned in a callback function are temporary and are valid only in the body of the callback function. If the application needs to save pointer information, it must allocate memory to hold the data, copy the data, and then store the pointer to this new data.

See Also

DPNAME, IDirectPlay3::EnumGroups, IDirectPlay3::EnumPlayers, IDirectPlay3::EnumGroupPlayers, IDirectPlay3::EnumGroupsInGroup


EnumSessionsCallback2

Application-defined callback function for the IDirectPlay3::EnumSessions method.

BOOL FAR PASCAL EnumSessionsCallback2(
LPCDPSESSIONDESC2 lpThisSD,
LPDWORD lpdwTimeOut,
DWORD dwFlags,
LPVOID lpContext
);

Parameters
lpThisSD
Pointer to a DPSESSIONDESC2 structure describing the enumerated session. This parameter will be set to NULL if the enumeration has timed out.
lpdwTimeOut
Pointer to a variable containing the current time-out value. This parameter can be reset when the DPESC_TIMEDOUT flag is returned if you want to wait longer for sessions to reply.
dwFlags
Typically, this flag is set to zero.
DPESC_TIMEDOUT
The enumeration has timed out. Reset lpdwTimeOut and return TRUE to continue, or FALSE to stop the enumeration.
lpContext
Pointer to an application-defined context.
Return Values

Returns TRUE to continue the enumeration or FALSE to stop it.

Remarks

The application must implement this function in order to use the IDirectPlay3::EnumSessions method. This callback function will be called once for each session that is enumerated. Once all the session are enumerated, the callback function will be called one additional time with the DPESC_TIMEDOUT flag.

Applications should look at the flags of the DPSESSIONDESC2 to determine the nature of the session.

Any pointers returned in a callback function are temporary and are valid only in the body of the callback function. If the application needs to save pointer information, it must allocate memory to hold the data, copy the data, and then store the pointer to this new data. In this function, lpThisSD is temporary. Also note that the pointers inside the structure specified in the lpThisSD parameter—lpszSessionName / lpszSessionNameA and lpszPassword / lpszPasswordA—are also temporary.


IDirectPlay3 Interface

Applications use the methods of the IDirectPlay3 interface to create DirectPlay objects and work with system-level variables. (The IDirectPlay3A interface is the same as the IDirectPlay3 interface, except that IDirectPlay3A uses ANSI characters, and IDirectPlay3 uses Unicode.) This section is a reference to the methods of this interface.

The methods of the IDirectPlay3 interface can be organized into the following groups:
Session Management | Close
EnumConnections
EnumSessions
GetCaps
GetGroupConnectionSettings
GetSessionDesc
InitializeConnection
Open
SetGroupConnectionSettings
SetSessionDesc
StartSession
Player management | CreatePlayer
DestroyPlayer
EnumPlayers
GetPlayerAddress
GetPlayerCaps
GetPlayerData
GetPlayerName
SetPlayerData
SetPlayerName
Message Management | GetMessageCount
Receive
Send
SendChatMessage
Group management | AddGroupToGroup
AddPlayerToGroup
CreateGroup
CreateGroupInGroup
DeleteGroupFromGroup
DeletePlayerFromGroup
DestroyGroup
EnumGroupPlayers
EnumGroups
EnumGroupsInGroup
GetGroupData
GetGroupName
SetGroupData
SetGroupName
Initialization | Initialize
Security and Authentication | SecureOpen

The IDirectPlay3 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release


IDirectPlay3::AddGroupToGroup

IDirectPlay3 Interface

Adds a shortcut to a group to an already existing group. This allows the linked group to be enumerated by the IDirectPlay3::EnumGroupsInGroup method. To remove a group's shortcut from another group, call DeleteGroupFromGroup.

HRESULT AddGroupToGroup(
DPID idParentGroup,
DPID idGroup
);

Parameters
idParentGroup
ID of the group to which the shortcut will be added. Can be any valid group ID.
idGroup
The group ID of the group whose shortcut will be added. Can be any valid group ID.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDGROUP
Remarks

This method can be used to place a group "inside" more than one group.

A DPMSG_ADDGROUPTOGROUP system message is generated to inform players of this change.

See Also

IDirectPlay3::CreateGroupInGroup, IDirectPlay3::DeleteGroupFromGroup, IDirectPlay3::EnumGroupsInGroup, DPMSG_ADDGROUPTOGROUP


IDirectPlay3::AddPlayerToGroup

IDirectPlay3 Interface

Add a player to an existing group. A player can be a member of multiple groups. Groups cannot be added to other groups using this API (see IDirectPlay3::AddGroupToGroup). An application can add any player to any group (including players and groups that weren't created locally).

HRESULT AddPlayerToGroup(
DPID idGroup,
DPID idPlayer
);

Parameters
idGroup
Group ID of the group to be augmented.
idPlayer
Player ID of the player to be added to the group.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_NOSESSIONS

This method returns DPERR_INVALIDPLAYER if the player DPID is not a player id or if the id is not for a local player.

Remarks

A DPMSG_ADDPLAYERTOGROUP system message will be generated and sent to all the other players.

See Also

IDirectPlay3::CreateGroup, IDirectPlay3::DeletePlayerFromGroup, DPMSG_ADDPLAYERTOGROUP


IDirectPlay3::Close

IDirectPlay3 Interface

Closes a previously opened session. Any locally created groups will migrate to be owned by the host of the session.

HRESULT Close( );

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
Remarks

All locally created players will be destroyed and appropriate DPMSG_DELETEPLAYERFROMGROUP and DPMSG_DESTROYPLAYERORGROUP system messages will be sent to other session participants.

See Also

IDirectPlay3::DestroyPlayer, DPMSG_DESTROYPLAYERORGROUP, IDirectPlay3::Open


IDirectPlay3::CreateGroup

IDirectPlay3 Interface

Creates a group in the current session. A group is a logical collection of players or other groups.

HRESULT CreateGroup(
LPDPID lpidGroup,
LPDPNAME lpGroupName,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);

Parameters
lpidGroup
Pointer to a variable that will be filled with the DirectPlay group ID. This value is defined by DirectPlay.
lpGroupName
Pointer to a DPNAME structure that holds the name of the group. NULL indicates that the group has no initial name. The name in lpGroupName is provided for human use only; it is not used internally and need not be unique.
lpData
Pointer to a block of application-defined remote data to associate initially with the Group ID. NULL indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if IDirectPlay3::SetGroupData were called.
dwDataSize
Size, in bytes, of the data block that lpData points to.
dwFlags
Flag indicating what type of group to create. By default (dwFlags = 0), ownership of the group will migrate to the host when the owner leaves the session, and the group persists until it is explicitly destroyed.
DPGROUP_STAGINGAREA – the group is created as a staging area. A staging area is used to marshal players together in order to launch a new session.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
Remarks

This method will generate a DPMSG_CREATEPLAYERORGROUP system message that will be sent to all the other players. The application can use IDirectPlay3::Send to send a message to all the players in a group by sending one message to the group ID. DirectPlay will either use multicast to send the message (if the service provider supports it) or send individual messages to each player in the group.

The group ID returned to the application should be used to identify the group for message passing and data association. Player and group IDs assigned by DirectPlay will always be unique within the session.

Groups created with CreateGroup are top-level groups in the session. They are enumerated with IDirectPlay3::EnumGroups. In contrast, the IDirectPlay3::CreateGroupInGroup method creates a group that is a sub-group of a parent group.

Groups can also be used by the application for general organization. In a lobby session, a staging area is used as the mechanism for collecting players for the purpose of starting a new application session using IDirectPlay3::StartSession.

The player that creates a group is the default owner of it. Only the owner can change group properties such as the name and remote data. If the owner leaves the session, ownership is transferred to the host of the session.

Any player in the session can change the membership of the group or delete the group.

Groups will persist in the session until they are explicitly destroyed.

See Also

DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay3::DestroyGroup, IDirectPlay3::EnumGroups, IDirectPlay3::EnumGroupPlayers, IDirectPlay3::Send, IDirectPlay3::SetGroupData, IDirectPlay3::SetGroupName, IDirectPlay3::CreateGroupInGroup, IDirectPlay3::GetGroupFlags


IDirectPlay3::CreateGroupInGroup

IDirectPlay3 Interface

Creates a group within an existing group. A group created within another group can only be enumerated using the IDirectPlay3::EnumGroupsInGroup method. A group created this way can be destroyed by calling the IDirectPlay3::DestroyGroup method.

HRESULT CreateGroupInGroup(
DPID idParentGroup,
LPDPID lpidGroup,
LPDPNAME lpGroupName,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);

Parameters
idParentGroup
The DPID of the group within which a group will be created. Must be an already existing group.
lpidGroup
Pointer to the DPID that will be filled in with the DirectPlay group ID of the created group.
lpGroupName
Pointer to a DPNAME structure that holds the name of the group to be created. NULL indicates that the group has no initial name.
lpData
Pointer to a block of application-defined remote data to associate initially with the group ID. NULL indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if the IDirectPlay3::SetGroupData method had been called.
dwDataSize
Size, in bytes, of the data block that the lpData parameter points to.
dwFlags
Flag indicating what type of group to create. Default (dwFlags = 0) is a normal group.
DPGROUP_STAGINGAREA – the group can be used to launch DirectPlay sessions using the IDirectPlay3::StartSession method.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

This method returns DPERR_CANTADDPLAYER if the group could not be created. It returns DPERR_INVALIDGROUP if the parent group ID is invalid.

Remarks

A DPMSG_CREATEPLAYERORGROUP system message is generated to inform players of this change.

If you destroy a top level group, any member groups it contains are destroyed as well, and the appropriate destruction messages are sent.

See Also

IDirectPlay3::DestroyGroup, IDirectPlay3::EnumGroupsInGroup, DPMSG_CREATEPLAYERORGROUP


IDirectPlay3::CreatePlayer

IDirectPlay3 Interface

Creates a local player for the current session.

HRESULT CreatePlayer(
LPDPID lpidPlayer,
LPDPNAME lpPlayerName,
HANDLE hEvent,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);

Parameters
lpidPlayer
Pointer to a variable that will be filled with the DirectPlay player ID. This value is defined by DirectPlay.
lpPlayerName
Pointer to a DPNAME structure that holds the name of the player. NULL indicates that the player has no initial name information. The name in lpPlayerName is provided for human use only. It is not used internally and need not be unique.
hEvent
An event object created by the application that will be signaled by DirectPlay when a message addressed to this player is received.
lpData
Pointer to a block of application-defined data to associate with the player ID. NULL indicates that the player has no initial data. The data specified in this parameter is assumed to be remote data that will be propagated to all the other applications in the session, as if IDirectPlay3::SetPlayerData were called.
dwDataSize
Size, in bytes, of the data block that lpData points to.
dwFlags
Flags indicating what type of player this is. Default (dwFlags = 0) is a nonspectator, nonserver player.
DPPLAYER_SERVERPLAYER – the player is a server player for client/server communications. Only the host can create a server player. There can only be one server player in a session. CreatePlayer will always return a player ID of DPID_SERVERPLAYER if this flag is specified.
DPPLAYER_SPECTATOR – the player is created as a spectator. A spectator player behaves exactly as a normal player except the player is flagged as a spectator. The application can then limit what a spectator player can do. The behavior of a spectator player is completely defined by the application. DirectPlay simply propagates this flag.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTADDPLAYER
DPERR_CANTCREATEPLAYER
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
Remarks

A single process can have multiple local players that communicate through a DirectPlay object with other players on the same computer or players on remote computers.

Upon successful completion, this method sends a DPMSG_CREATEPLAYERORGROUP system message to all the other players in the session announcing that a new player has joined the session. By default, all local players receive copies of all the system messages.

Your application should use the player ID returned to the application to identify the player for message passing and data association. Player and group IDs assigned by DirectPlay will always be unique within the session.

If the application closes the session, any local players created will be automatically destroyed. Only the application that created the player can:

  • destroy the player.
  • change the player's name or remote data.
  • send messages from the player.

If the application uses a separate thread to retrieve DirectPlay messages, it is highly recommended that a non-NULL hEvent be supplied and used for synchronization. This event will be set when this player receives a message. Within the message receive thread, use the Win32 API WaitForSingleObject (or use WaitForMultipleObjects if more than one event is used) within the thread to determine if a player has messages. It is inefficient to loop on IDirectPlay3::Receive inside a separate thread waiting for a message. The same event can be used for all the local players, or the application can supply different events for each player. The application is responsible for creating and destroying the event. See Synchronization for more information.

See Also

DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay3::DestroyPlayer, IDirectPlay3::EnumPlayers, IDirectPlay3::Receive, IDirectPlay3::Send, IDirectPlay3::SetPlayerData, IDirectPlay3::SetPlayerName, IDirectPlay3::GetPlayerFlags


IDirectPlay3::DeleteGroupFromGroup

IDirectPlay3 Interface

Removes a shortcut to a group previously added with the IDirectPlay3::AddGroupToGroup method from a group. Deleting the shortcut does not destroy the group.

HRESULT DeleteGroupFromGroup(
DPID idParentGroup,
DPID idGroup
);

Parameters
idParentGroup
The group DPID of the group containing the shortcut to be deleted. Can be any valid group DPID.
idGroup
The group DPID of the group to delete. Can be any valid group DPID.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDGROUP
Remarks

A DPMSG_DELETEGROUPFROMGROUP system message is generated to inform players of this change.

See Also

IDirectPlay3::AddGroupToGroup, DPMSG_DELETEGROUPFROMGROUP


IDirectPlay3::DeletePlayerFromGroup

IDirectPlay3 Interface

Removes a player from a group.

HRESULT DeletePlayerFromGroup(
DPID idGroup,
DPID idPlayer
);

Parameters
idGroup
Group ID of the group to be adjusted.
idPlayer
Player ID of the player to be removed from the group.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
Remarks

A DPSYS_DELETEPLAYERFROMGROUP system message is generated to inform the other players of this change. For a list of system messages, see Using System Messages.

A player can delete any player from a group, even if that group was created by some other computer.

See Also

IDirectPlay3::AddPlayerToGroup, DPMSG_DELETEPLAYERFROMGROUP


IDirectPlay3::DestroyGroup

IDirectPlay3 Interface

Deletes a group from the session. The ID belonging to this group will not be reused during the current session.

HRESULT DestroyGroup(
DPID idGroup
);

Parameters
idGroup
The ID of the group being removed from the game.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

It is not necessary to empty a group before deleting it. The individual players belonging to the group are not destroyed. This method will generate a DPMSG_DELETEPLAYERFROMGROUP system message for each player in the group, and then a DPMSG_DESTROYPLAYERORGROUP system message. For a list of system messages, see Using System Messages.

Any application can destroy any group even if the group was not created locally.

See Also

IDirectPlay3::CreateGroup, DPMSG_DESTROYPLAYERORGROUP


IDirectPlay3::DestroyPlayer

IDirectPlay3 Interface

Deletes a local player from the session, removes any pending messages destined for that player from the message queue, and removes the player from any groups to which it belonged. The player ID will not be reused during the current session.

HRESULT DestroyPlayer(
DPID idPlayer
);

Parameters
idPlayer
Player ID of the player that is being removed from the session.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
Remarks

This method will generate a DPMSG_DELETEPLAYERFROMGROUP system message for each group that the player belongs to, and then a DPMSG_DESTROYPLAYERORGROUP system message.

Only the application that created the player can destroy it.

See Also

IDirectPlay3::CreatePlayer, DPMSG_DESTROYPLAYERORGROUP


IDirectPlay3::EnumConnections

IDirectPlay3 Interface

Enumerates all the registered service providers and lobby providers that are available to the application. These should be presented to the user to make a selection. The connection that the user selects should be passed to the IDirectPlay3::InitializeConnection method.

HRESULT EnumConnections(
LPCGUID lpguidApplication,
LPDPENUMCONNECTIONSCALLBACK lpEnumCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpguidApplication
Pointer to an application GUID. Only service providers and lobby providers that are usable by this application will be returned. If set to a NULL pointer, a list of all the connections is enumerated regardless of the application GUID.
lpEnumCallback
Pointer to a user-supplied EnumConnectionsCallback function that will be called for each available connection.
lpContext
Pointer to a user-defined context that is passed to the callback function.
dwFlags
Flags that specify the type of connections to be enumerated. The default (dwFlags = 0) will enumerate DirectPlay service providers only. Possible values are:
DPCONNECTION_DIRECTPLAY – enumerate DirectPlay service providers to communicate in an application session.
DPCONNECTION_DIRECTPLAYLOBBY – enumerate DirectPlay lobby providers to communicate with a lobby server.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
Remarks

This method replaces the DirectPlayEnumerate function. DirectPlayEnumerate still works, but only returns registered service providers.

The order in which the service and lobby providers are returned is not guaranteed to be the same in subsequent calls to EnumConnections

Not all the enumerated connections are available for use. For example, this method will return the Modem service provider even if the user has no modem installed. The application can call the IDirectPlay3::InitializeConnection method on each connection and check for an error code to determine if the service provider can be used.

See Also

IDirectPlay3::InitializeConnection, EnumConnectionsCallback, DirectPlay Address


IDirectPlay3::EnumGroupPlayers

IDirectPlay3 Interface

Enumerates the players belonging to a specific group in the currently open session. If there is no open session, players in a remote session can be enumerated by specifying the DPENUMPLAYERS_SESSION flag and the guidInstance of the session. Password protected remote sessions cannot be enumerated.

A pointer to an application-implemented callback function must be supplied, and DirectPlay calls it once for each player in the group that matches the criteria specified in dwFlags.

You can't use EnumGroupPlayers in a lobby session you're not connected to.

HRESULT EnumGroupPlayers(
DPID idGroup,
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
idGroup
DPID of the group whose players are to be enumerated.
lpguidInstance
Pointer to a GUID identifying the session to be enumerated. This parameter is ignored unless the DPENUMPLAYERS_SESSION flag is specified. The GUID must be equal to one of the sessions enumerated by IDirectPlay3::EnumSessions.
lpEnumPlayersCallback2
Pointer to the EnumPlayersCallback2 function that will be called for every player in the group that matches the criteria specified in dwFlags.
lpContext
Pointer to an application-defined context that is passed to each enumeration callback.
dwFlags
Flags specifying how the enumeration is to be done. The default (dwFlags = 0) enumerates players in a group in the current active session. You should OR together the flags that you want to specify. Only players that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR) only players in the group that are local and are spectator players will be enumerated. If you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE), no players will be enumerated because no player can be both local and remote.
Can be one or more of the following values:
DPENUMPLAYERS_LOCAL
Enumerates players created locally by this DirectPlay object.
DPENUMPLAYERS_REMOTE
Enumerates players created by remote DirectPlay objects.
DPENUMPLAYERS_SERVERPLAYER
Enumerates the server player.
DPENUMPLAYERS_SESSION
Enumerates the players for the session identified by lpguidInstance. This flag can only be used if there is no current open session. This flag can't be used in a lobby session.
DPENUMPLAYERS_SPECTATOR
Enumerates players who are spectator players.
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDPARAMS
DPERR_INVALIDGROUP
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

This method returns DPERR_ACCESSDENIED if the session is a lobby session you're not connected to. It returns DPERR_INVALIDPARAMS if an invalid callback, an invalid guidInstance, or invalid flags were supplied. It returns DPERR_NOSESSIONS if there is no active session. It returns DPERR_UNAVAILABLE if the session could not be enumerated.

Remarks

By default, this method will enumerate all players in the current session. The DPENUMPLAYERS_SESSION flag can be used, along with a session instance GUID, to request that a session's host provide its list for enumeration. Use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay3::EnumSessions method has been called, and before any calls to the IDirectPlay3::Close or IDirectPlay3::Open methods.

See Also

IDirectPlay3::CreatePlayer, IDirectPlay3::DestroyPlayer, IDirectPlay3::AddPlayerToGroup, IDirectPlay3::DeletePlayerFromGroup


IDirectPlay3::EnumGroups

IDirectPlay3 Interface

Enumerates all the top-level groups in the current session. Top-level groups are groups that were created with the IDirectPlay3::CreateGroup method. If there is no open session, groups in a remote session can be enumerated by specifying the DPENUMGROUPS_SESSION flag and the guidInstance of the session. Password protected remote sessions cannot be enumerated.

A pointer to an application-implemented callback function must be supplied, and DirectPlay calls it once for each group in the session that matches the criteria specified in dwFlags.

You can't use EnumGroups in a lobby session you're not connected to.

HRESULT EnumGroups(
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpguidInstance
This parameter should be NULL to enumerate groups in the currently open session. If there is no open session, this parameter can be a pointer to a GUID identifying the session to be enumerated. The GUID must be equal to one of the sessions enumerated by IDirectPlay3::EnumSessions. This parameter is ignored unless the DPENUMGROUPS_SESSION flag is specified.
lpEnumPlayersCallback2
Pointer to the EnumPlayersCallback2 function that will be called for every group in the session that matches the criteria specified in dwFlags.
lpContext
Pointer to an application-defined context that is passed to each enumeration callback.
dwFlags
Flags specifying how the enumeration is to be done. Default (dwFlags = 0) enumerates all groups in the current active session. You should OR together the flags that you want to specify. Only groups that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA) only groups that are local and are staging areas will be enumerated. If you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE), no groups will be enumerated because no group can be both local and remote.
Can be one or more of the following values:
DPENUMGROUPS_ALL
Enumerates all groups in this session.
DPENUMGROUPS_LOCAL
Enumerates groups created locally by this DirectPlay object.
DPENUMGROUPS_REMOTE
Enumerates groups created by remote DirectPlay objects.
DPENUMGROUPS_SESSION
Performs enumeration in the session identified by the lpguidInstance parameter. This flag can only be used if there is no current active session. You can't use this flag in a lobby session.
DPENUMGROUPS_STAGINGAREA
Enumerates groups that are staging areas. (Staging areas are used to marshal players together in order to launch a new session.)
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

This method returns DPERR_INVALIDPARAMS if an invalid callback, an invalid guidInstance, or invalid flags were supplied. It returns DPERR_NOSESSIONS if there is no open session. It returns DPERR_UNAVAILABLE if the remote session could not be enumerated.

Remarks

To enumerate the subgroups in a group, use IDirectPlay3::EnumGroupsInGroup.

See Also

EnumPlayersCallback2, IDirectPlay3::CreateGroup, IDirectPlay3::DestroyGroup, IDirectPlay3::EnumSessions


IDirectPlay3::EnumGroupsInGroup

IDirectPlay3 Interface

Enumerates all groups and shortcuts to groups that are contained within another group. Groups are placed inside other groups by creating them with the IDirectPlay3::CreateGroupInGroup method or by adding them to a group with the IDirectPlay3::AddGroupToGroup method. This method is not recursive.

You can't use EnumGroupsInGroup in a lobby session you're not connected to.

HRESULT EnumGroupsInGroup(
DPID idGroup,
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
idGroup
DPID of the group whose subgroups are to be enumerated.
lpguidInstance
Pointer to a GUID identifying the session to be enumerated. This parameter is ignored unless the DPENUMPLAYERS_SESSION flag is specified. The GUID must equal one of the sessions enumerated by the IDirectPlay3::EnumSessions method.
lpEnumCallback
Pointer to the EnumPlayersCallback2 function that will be called for every group in the group that matches the criteria specified in dwFlags.
lpContext
Pointer to an application-defined context that is passed to each enumeration callback.
dwFlags
Flags specifying how the enumeration will be done. The default (dwFlags = 0) enumerates all groups in the current active session. You should OR together the flags that you want to specify. Only groups that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA) only groups that are local and are staging areas will be enumerated. If you specify (DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE), no groups will be enumerated because no group can be both local and remote.
Can be one or more of the following values:
DPENUMGROUPS_ALL
Enumerates all groups in the group.
DPENUMGROUPS_LOCAL
Enumerates groups in the group created locally by this DirectPlay object.
DPENUMGROUPS_REMOTE
Enumerates groups in the group created by remote DirectPlay objects.
DPENUMGROUPS_SESSION
Performs enumeration in the session identified by the lpguidInstance parameter. This flag can only be used if there is no current active session. This flag can't be used in lobby sessions.
DPENUMGROUPS_SHORTCUT
Enumerates groups that are shortcuts added to the group using IDirectPlay3::AddGroupToGroup. (A shortcut is a link to another group.)
DPENUMGROUPS_STAGINGAREA
Enumerates groups in the group that are staging areas. (Staging areas are used to marshal players together in order to launch a new session.)
Return Values

Returns DP_OK if successful, or one of the following error messages otherwise:

DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNSUPPORTED

This method returns DPERR_INVALIDPARAMS if an invalid callback or an invalid guidInstance is supplied. It returns DPERR_NOSESSIONS if there is no active session. It returns DPERR_UNSUPPORTED if the session could not be enumerated.

See Also

IDirectPlay3::CreateGroupInGroup, IDirectPlay3::DestroyGroup, IDirectPlay3::AddGroupToGroup, IDirectPlay3::DeleteGroupFromGroup


IDirectPlay3::EnumPlayers

IDirectPlay3 Interface

Enumerates the players in the current open session. If there is no open session, players in a remote session can be enumerated by specifying the DPENUMPLAYERS_SESSION flag and the guidInstance of the session. Password protected remote sessions cannot be enumerated.

A pointer to an application-implemented callback function must be supplied and DirectPlay calls it once for each player in the session that matches the criteria specified in dwFlags.

Within a lobby session, this method will always return DPERR_ACCESSDENIED.

HRESULT EnumPlayers(
LPGUID lpguidInstance,
LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpguidInstance
This parameter should be NULL to enumerate players in the currently open session. If there is no open session, this parameter can be a pointer to a GUID identifying the session to be enumerated. The GUID must be equal to one of the sessions enumerated by IDirectPlay3::EnumSessions. This parameter is ignored unless the DPENUMPLAYERS_SESSION flag is specified.
lpEnumPlayersCallback2
Pointer to the EnumPlayersCallback2 function that will be called for every player in the session that matches the criteria specified in dwFlags.
lpContext
Pointer to an application-defined context that is passed to each enumeration callback.
dwFlags
Flags specifying how the enumeration is to be done. Default (dwFlags = 0) enumerates all players in the current active session. You should OR together the flags that you want to specify. Only players that meet all the criteria of the combined flags will be enumerated. For example, if you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR) only players that are local and are spectator players will be enumerated. If you specify (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE), no players will be enumerated because no player can be both local and remote.
Can be one or more of the following values:
DPENUMPLAYERS_ALL
Enumerates all players in this session.
DPENUMPLAYERS_GROUP
Includes groups in the enumeration of players.
DPENUMPLAYERS_LOCAL
Enumerates players created locally by this DirectPlay object.
DPENUMPLAYERS_REMOTE
Enumerates players created by remote DirectPlay objects.
DPENUMPLAYERS_SERVERPLAYER
Enumerates the server player.
DPENUMPLAYERS_SESSION
Enumerates the players for the session identified by lpguidInstance. This flag can only be used if there is no current open session.
DPENUMPLAYERS_SPECTATOR
Enumerates players who are spectator players.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

This method returns DPERR_INVALIDPARAMS if an invalid callback, an invalid guidInstance, or invalid flags were supplied. It returns DPERR_NOSESSIONS if there is no open session. It returns DPERR_UNAVAILABLE if the remote session could not be enumerated.

Remarks

By default, this method will enumerate players in the current open session. Groups can also be included in the enumeration by using the DPENUMPLAYERS_GROUP flag. The DPENUMPLAYERS_SESSION flag can be used, along with a session instance GUID, to request that a session's host provide its list for enumeration. This method cannot be called from within an IDirectPlay3::EnumSessions enumeration. Furthermore, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the IDirectPlay3::EnumSessions method has been called, and before any calls to the IDirectPlay3::Close or IDirectPlay3::Open methods.

See Also

IDirectPlay3::CreatePlayer, IDirectPlay3::DestroyPlayer, IDirectPlay3::EnumSessions


IDirectPlay3::EnumSessions

IDirectPlay3 Interface

Enumerates all the active sessions for a particular application and/or all the active lobby sessions that serve a particular application. This method can be called after a DirectPlay object has been created and initialized either by DirectPlayCreate or IDirectPlay3::InitializeConnection.

This method returns an error if called while a session is already open.

HRESULT EnumSessions(
LPDPSESSIONDESC2 lpsd,
DWORD dwTimeout,
LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpsd
Pointer to the DPSESSIONDESC2 structure describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. The guidApplication member can be set to the globally unique identifier (GUID) of an application of interest if it is known, or to GUID_NULL to obtain all sessions. The lpszPassword member is only needed if you want private sessions. All data members besides guidApplication and lpszPassword are ignored.
dwTimeout
In the synchronous case, the total amount of time, in milliseconds, that DirectPlay will wait for replies to the enumeration request (not the time between each enumeration). Any replies received after this time-out will be ignored. The application will be blocked until the time-out expires.
In the asynchronous case, this is the interval, in milliseconds, that enumeration requests will be broadcast by DirectPlay in order to update the internal sessions list.
If the time-out is set to zero, a default time-out appropriate for the service provider and connection type will be used. It is recommended that you set this value to zero. The application can determine this time-out by calling IDirectPlay3::GetCaps and examining the dwTimeout data member of the DPCAPS structure.
lpEnumSessionsCallback2
Pointer to the application-supplied EnumSessionsCallback2 function to be called for each DirectPlay session responding.
lpContext
Pointer to a user-defined context that is passed to each enumeration callback.
dwFlags
The default is 0, which is equivalent to DPENUMSESSIONS_AVAILABLE. When enumerating sessions with DPENUMSESSIONS_ALL or DPENUMSESSIONS_PASSWORDREQUIRED it is important for the application to know which sessions cannot be joined and which sessions are password-protected so the user can be warned or prompted for a password.
DPENUMSESSIONS_ALL
Enumerate all active sessions, whether they are accepting new players or not. Sessions in which the player limit has been reached, new players have been disabled, or joining has been disabled will be enumerated.
Password protected sessions will not be enumerated unless the DPENUMSESSIONS_PASSWORDREQUIRED flag is also specified.
If DPENUMSESSIONS_ALL is not specified, DPENUMSESSIONS_AVAILABLE is assumed.
DPENUMSESSIONS_ASYNC
Enumerates all the current sessions in the session cache and returns immediately. Starts the asynchronous enumeration process if not already started. Updates to the session list continue until canceled by calling EnumSessions with the DPENUMSESSIONS_STOPASYNC flag, or by calling Open, or by calling Release.
If this flag is not specified, the enumeration is done synchronously.
DPENUMSESSIONS_AVAILABLE
Enumerate all sessions that are accepting new players to join. Sessions which have reached their maximum number of players, or have disabled new players, or have disabled joining will not be enumerated.
Password protected sessions will not be enumerated unless the DPENUMSESSIONS_PASSWORDREQUIRED flag is also specified.
DPENUMSESSIONS_PASSWORDREQUIRED
When used in combination with one of the two flags DPENUMSESSIONS_AVAILABLE or DPENUMSESSIONS_ALL, enables password-protected sessions to be enumerated in addition to sessions without password protection.
If this flag is not specified, no password protected sessions will be returned.
DPENUMSESSIONS_RETURNSTATUS
If this flag is specified, the enumeration will not display any dialog boxes showing the connection progress status. If the connection cannot be made immediately, the method will return with the DPERR_CONNECTING error. The application must keep calling EnumSessions until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.
DPENUMSESSIONS_STOPASYNC
Enumerates all the current sessions in the session cache and cancels the asynchronous enumeration process.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CONNECTING
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
DPERR_UNINITIALIZED
DPERR_USERCANCEL

This method returns DPERR_GENERIC if the session is already open. It returns DPERR_UNINITIALIZED if the DirectPlay object has not been initialized. It returns DPERR_USERCANCEL if the user canceled the enumeration process (usually by canceling a service provider dialog box). It returns DPERR_CONNECTING if the method is in the process of connecting to the network.

Remarks

EnumSessions works by requesting that the service provider locate one or more hosts on the network and send them an enumeration request. The replies that are received make up the sessions that are enumerated.

EnumSessions can be called synchronously (default) or asynchronously. When called synchronously, DirectPlay will clear the internal session cache, send out an enumeration request, and collect replies until the specified time-out expires. Each session will then be returned to the application through the callback function. The application will be blocked until all the sessions have been returned through the callback function.

When called asynchronously (DPENUMSESSIONS_ASYNC), all the current sessions (if any) in the session cache will be returned to the application through the callback function and then the method will return. DirectPlay will then automatically send out enumeration requests with the period of the time-out parameter and listen for replies. Each reply will be used to update the session cache:

  • Sessions already in the cache will be updated
  • Sessions that haven't been updated for a set period of time (and thus have expired) will be deleted
  • New sessions will be added

The application must call EnumSessions (with the DPENUMSESSIONS_ASYNC flag) again to obtain the most up-to-date session list with all the expired sessions deleted, new sessions added, and updated sessions. Subsequent calls to EnumSessions will not generate an enumeration request. Enumeration requests will be generated periodically by DirectPlay until the process is either canceled by calling EnumSessions with the DPENUMSESSIONS_STOPASYNC flag, a session is opened using the IDirectPlay3::Open method, or the DirectPlay object is released.

Once enumeration of the available sessions is complete, the application can join one of the sessions using the IDirectPlay3::Open method. Only sessions in the session cache can be opened. It is possible for the application to attempt to open a session that has expired since the last time EnumSessions was called in which case an error will be returned.

No authentication is performed when enumerating sessions on a secure server. All sessions that meet the enumeration criteria will be returned. Authentication will be done when the application attempts to open one of these sessions with IDirectPlay3::Open or IDirectPlay3::SecureOpen.

If the application was not started by a lobby, the service provider can display a dialog box asking the user for information (such as a phone number or IP address) in order to perform the enumeration on the network, if that information was not provided in IDirectPlay3::InitializeConnection. If the service provider can do a broadcast enumeration and requires no extra information from the user, no dialog box will appear. If the user cancels a service provider dialog box, EnumSessions returns DPERR_USERCANCEL.

See Also

DPSESSIONDESC2, IDirectPlay3::Open, IDirectPlay3::SecureOpen


IDirectPlay3::GetCaps

IDirectPlay3 Interface

Obtains the capabilities of this DirectPlay object.

HRESULT GetCaps(
LPDPCAPS lpDPCaps,
DWORD dwFlags
);

Parameters
lpDPCaps
Pointer to a DPCAPS structure that will be filled with the capabilities of the DirectPlay object. The dwSize member of the DPCAPS structure must be filled in before using IDirectPlay3::GetCaps.
dwFlags
If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging.
DPGETCAPS_GUARANTEED
Retrieves the capabilities for a guaranteed message delivery.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
Remarks

This method returns the capabilities of the current session, while the IDirectPlay3::GetPlayerCaps method returns the capabilities of the requested player.

See Also

DPCAPS, IDirectPlay3::GetPlayerCaps, IDirectPlay3::Send


IDirectPlay3::GetGroupConnectionSettings

IDirectPlay3 Interface

Retrieves the connection settings for a group from the DPLCONNECTION structure. Any sessions launched from this group will use these settings. This method can only be used in a lobby session.

HRESULT GetGroupConnectionSettings(
DWORD dwFlags,
DPID idGroup,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
dwFlags
Not used. Must be zero.
idGroup
The DPID of the group to get the connection settings for.
lpData
Pointer to a buffer into which the DPLCONNECTION structure and all its data will be copied. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the minimum size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the minimum buffer size required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED
Remarks

Group connection settings are only relevant for staging area groups.

You can see if a game has been launched by looking at the guidInstance data member of the DPSESSIONDESC2 structure, whose pointer is contained in the lpSessionDesc data member of the DPLCONNECTION structure returned by this method. The guidInstance will be GUID_NULL until a game has been launched.

See Also

DPLCONNECTION, IDirectPlayLobby2::RunApplication, IDirectPlay3::SetGroupConnectionSettings, DPGROUP_STAGINGAREA


IDirectPlay3::GetGroupData

IDirectPlay3 Interface

Retrieves an application-specific data block that was associated with a group ID by using IDirectPlay3::SetGroupData.

HRESULT GetGroupData(
DPID idGroup,
LPVOID lpData,
LPDWORD lpdwDataSize,
DWORD dwFlags
);

Parameters
idGroup
Group ID for which data is being requested.
lpData
Pointer to a buffer where the application-specific group data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling the method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required.
dwFlags
If this parameter is set to 0, the remote data will be retrieved.
DPGET_LOCAL
Retrieves the local data set by this application
DPGET_REMOTE
Retrieves the current data from the remote shared data space.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

DirectPlay can maintain two types of group data: local and remote. The application must specify which type of data to retrieve. Local data was set by this DirectPlay object by using the DPSET_LOCAL flag. Remote data might have been set by any application in the session by using the DPSET_REMOTE flag.

See Also

IDirectPlay3::SetGroupData


IDirectPlay3::GetGroupFlags

IDirectPlay3 Interface

Returns the flags describing the group.

HRESULT GetGroupFlags(
DPID idGroup,
LPDWORD lpdwFlags
);

Parameters
idGroup
The DPID of the group whose flag settings are to be retrieved.
lpdwFlags
Pointer to a DWORD to be set to the group flag settings. Can be one or more of the following:
DPGROUP_LOCAL – the group was created by this application. If this flag is not specified, the group is a remote group.
DPGROUP_STAGINGAREA – the group is a staging area.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
See Also

IDirectPlay3::CreateGroup


IDirectPlay3::GetGroupName

IDirectPlay3 Interface

Returns the name associated with a group.

HRESULT GetGroupName(
DPID idGroup,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
idGroup
ID of the group whose name is being requested.
lpData
Pointer to a buffer where the name data is to be written. Set this parameter to NULL to request only the size of data. lpdwDataSize will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling the method. After the method returns, this parameter will be set to the size, in bytes, of the name data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size that is required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

After the method returns, the pointer lpData should be cast to the DPNAME structure to read the group name data.

See Also

DPNAME, IDirectPlay3::SetGroupName


IDirectPlay3::GetGroupParent

IDirectPlay3 Interface

Returns the DPID of the parent of the group.

HRESULT GetGroupParent(
DPID idGroup,
LPDPID lpidParent
);

Parameters
idGroup
ID of the group whose parent is being requested.
lpidParent
Pointer to a DPID to be set to the ID of the parent group. If this method returns a parent ID of zero, the group is a root group.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
See Also

IDirectPlay3::CreateGroupInGroup


IDirectPlay3::GetMessageCount

IDirectPlay3 Interface

Queries for the number of messages in the receive queue for a specific local player.

HRESULT GetMessageCount(
DPID idPlayer,
LPDWORD lpdwCount
);

Parameters
idPlayer
ID of the player whose message count is requested. The player must be local.
lpdwCount
Pointer to a variable that will be set to the message count when this method returns.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
See Also

IDirectPlay3::Receive


IDirectPlay3::GetPlayerAccount

IDirectPlay3 Interface

In a secure session, can be called by the session host to obtain account information about the specified player.

HRESULT GetPlayerAccount(
DPID idPlayer,
DWORD dwFlags,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
idPlayer
The DPID of the player whose account information is to be retrieved.
dwFlags
Not used. Must be zero.
lpData
A pointer to a buffer (allocated by the application) where the account data is to be written. A DPACCOUNTDESC structure will be copied as well as any data referenced by the members of the structure; therefore, the number of bytes copied is variable. Cast the lpData parameter to LPDPACCOUNTDESC in order to read the name. By passing NULL, the application can request the number of bytes required be put in the lpdwDataSize parameter. The application can then allocate the space and call this method again.
lpdwDataSize
A pointer to a DWORD that is initialized with the size of the buffer. After the method returns, lpdwDataSize will be set to the number of bytes that were actually copied into the buffer. If the buffer was too small the method returns DPERR_BUFFERTOOSMALL, and lpdwDataSize is set to the minimum required buffer size.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

The information returned by GetPlayerAccount uniquely identifies an account. This information can be used to record the transactions or other activities of a logged-in player.

See Also

IDirectPlay3::SecureOpen


IDirectPlay3::GetPlayerAddress

IDirectPlay3 Interface

Retrieves the DirectPlay Address for a player.

The DirectPlay Address is a network address for a player using a specific service provider. You should call the IDirectPlayLobby2::EnumAddress method to parse the DirectPlay Address buffer retrieved by IDirectPlay3::GetPlayerAddress.

HRESULT GetPlayerAddress(
DPID idPlayer,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
idPlayer
Player ID that the address is being requested for. Pass in zero to obtain a list of valid address options for a service provider (for example, a list of valid modem choices for the modem-to-modem service provider).
lpData
Pointer to a buffer where the DirectPlay Address is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small, then this parameter will be set to the buffer size that is required and the method will return DPERR_BUFFERTOOSMALL.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

To get a list of valid modem choices, pass in zero for the idPlayer parameter. A list of modem choices will be returned as a list of ANSI or Unicode strings with a zero-length string at the end.

For more information about the DirectPlay Address, DirectPlay Address.

See Also

IDirectPlayLobby2::EnumAddress


IDirectPlay3::GetPlayerCaps

IDirectPlay3 Interface

Retrieves the current capabilities of a specified player.

HRESULT GetPlayerCaps(
DPID idPlayer,
LPDPCAPS lpPlayerCaps,
DWORD dwFlags
);

Parameters
idPlayer
Player ID for which the capabilities should be computed.
lpPlayerCaps
Pointer to a DPCAPS structure that will be filled with the capabilities. The dwSize member of the DPCAPS structure must be filled in before using IDirectPlay3::GetPlayerCaps.
dwFlags
If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging.
DPGETCAPS_GUARANTEED
Retrieves the capabilities for a guaranteed message delivery.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

This method returns the capabilities of the requested player, while the IDirectPlay3::GetCaps method returns the capabilities of the current session.

See Also

DPCAPS, IDirectPlay3::GetCaps, IDirectPlay3::Send


IDirectPlay3::GetPlayerData

IDirectPlay3 Interface

Retrieves an application-specific data block that was associated with a player ID by using IDirectPlay3::SetPlayerData.

HRESULT GetPlayerData(
DPID idPlayer,
LPVOID lpData,
LPDWORD lpdwDataSize,
DWORD dwFlags
);

Parameters
idPlayer
ID of the player for which data is being requested.
lpData
Pointer to a buffer where the application-specific player data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required.
dwFlags
If this parameter is set to 0, the remote data will be retrieved.
DPGET_LOCAL
Retrieves the local data set by this application.
DPGET_REMOTE
Retrieves the current data from the remote shared data space.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
Remarks

DirectPlay can maintain two types of player data: local and remote. The application must specify which type of data to retrieve. Local data was set by this DirectPlay object by using the DPSET_LOCAL flag. Remote data might have been set by any application in the session by using the DPSET_REMOTE flag.

See Also

IDirectPlay3::SetPlayerData


IDirectPlay3::GetPlayerFlags

IDirectPlay3 Interface

Returns the flags describing the player.

HRESULT GetPlayerFlags(
DPID idPlayer,
LPDWORD lpdwFlags
);

Parameters
idPlayer
The DPID of the player whose flag settings are to be retrieved.
lpdwFlags
Pointer to a DWORD to be set to the player's flag settings. Can be one or more of the following:
DPPLAYER_LOCAL – the player was created by this application. If this flag is not specified, the player is a remote player.
DPPLAYER_SERVERPLAYER – the player is a server player for client/server communications.
DPPLAYER_SPECTATOR – the player was created as a spectator.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
See Also

IDirectPlay3::CreatePlayer


IDirectPlay3::GetPlayerName

IDirectPlay3 Interface

Retrieves the name associated with a player.

HRESULT GetPlayerName(
DPID idPlayer,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
idPlayer
ID of the player whose name is requested.
lpData
Pointer to a buffer where the name data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the name data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
Remarks

After this method returns, the pointer lpData should be cast to the DPNAME structure to read the group name data.

See Also

DPNAME, IDirectPlay3::SetPlayerName


IDirectPlay3::GetSessionDesc

IDirectPlay3 Interface

Retrieves the properties of the current open session.

HRESULT GetSessionDesc(
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
lpData
Pointer to a buffer where the session description data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required. If this parameter is NULL, the method returns DPERR_INVALIDPARAM.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
Remarks

After this method returns, the pointer lpData should be cast to the DPSESSIONDESC2 structure to read the session description data.

See Also

DPSESSIONDESC2, IDirectPlay3::EnumSessions, IDirectPlay3::Open


IDirectPlay3::Initialize

IDirectPlay3 Interface

This method is provided for compliance with the COM protocol.

HRESULT Initialize(
LPGUID lpGUID
);

Parameters
lpGUID
Pointer to the globally unique identifier (GUID) used as the interface identifier.
Return Values

Returns DPERR_ALREADYINITIALIZED.

Remarks

Because the DirectPlay object is initialized when it is created, this method always returns the DPERR_ALREADYINITIALIZED return value.

See Also

IUnknown::AddRef, IUnknown::QueryInterface


IDirectPlay3::InitializeConnection

IDirectPlay3 Interface

Initializes a DirectPlay connection. All the information about the connection, including the service provider to use, the network address of the server, and the GUID of the session, is passed in through the lpConnection parameter.

HRESULT InitializeConnection(
LPVOID lpConnection,
DWORD dwFlags
);

Parameters
lpConnection
Pointer to a buffer that contains all the information about the connection to be initialized as a DirectPlay Address.
dwFlags
Not used. Must be zero.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ALREADYINITIALIZED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

This method returns DPERR_ALREADYINITIALIZED if InitializeConnection has previously been called on this object. It returns DPERR_UNAVAILABLE if the service provider could not be initialized. This can be because the resources necessary to operate this service provider are not present (for example, TCP/IP stack not present).

Remarks

The lpConnection parameter supplied to this method can be obtained from the IDirectPlay3::EnumConnections method, or the application can create one directly using the IDirectPlayLobby2::CreateCompoundAddress method.

This method loads and initializes the appropriate service provider. The lpConnection parameter is passed on to the service provider, which extracts and saves any relevant information. This information is used when the IDirectPlay3::EnumSessions or IDirectPlay3::Open method is called so that the service provider does not pop up a dialog box asking for that information.

This method replaces DirectPlayCreate as the means of binding a service provider to a DirectPlay object. The primary benefits of InitializeConnection are that you can override the service provider dialogs, and you can initialize a lobby provider.

See Also

IDirectPlay3::EnumConnections, IDirectPlayLobby2::CreateCompoundAddress, DirectPlay Address


IDirectPlay3::Open

IDirectPlay3 Interface

Used to join a session that has been enumerated by a previous call to IDirectPlay3::EnumSessions or to create a new session that other users can enumerate and join.

HRESULT Open(
LPDPSESSIONDESC2 lpsd,
DWORD dwFlags
);

Parameters
lpsd
Pointer to the DPSESSIONDESC2 structure describing the session to be created or joined. If a session is being joined, then only the dwSize, guidInstance, and lpszPassword data members need to be specified. A password need only be supplied if the enumerated session had the DPSESSION_PASSWORD flag set.
If a session is being created, then the application must completely fill out the DPSESSIONDESC2 structure with the properties of the sessions to be created. The guidInstance will be generated by DirectPlay.
dwFlags
One and only one of the following flags:
DPOPEN_CREATE
Create a new instance of an application session. The local computer will be the name server and host of the session.
DPOPEN_JOIN
Join an existing instance of an application session for the purpose of participating. The application will be able to create players and send and receive messages.
DPOPEN_RETURNSTATUS
If this flag is specified, the method will not display any dialog boxes showing the connection progress status. If the connection cannot be made immediately, the method will return with the DPERR_CONNECTING error. The application must keep calling Open until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDCREDENTIALS
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

This method returns DPERR_ALREADYINITIALIZED if there is already an open session on this DirectPlay object. It returns DPERR_TIMEOUT if the session did not respond to the Open request. It returns DPERR_USERCANCEL if the user canceled the enumeration process(usually by canceling a service provider dialog box).

Remarks

Once an application has joined a session, it can create a player and start communicating with other players in the session. The application will not receive any messages nor can it send any messages on this DirectPlay object until it creates a local player using IDirectPlay3::CreatePlayer.

In order to have two sessions open simultaneously, the application must create two DirectPlay objects and open a session on each one.

To join a session, it is only necessary to fill in the dwSize and guidInstance members of the DPSESSIONDESC2 structure. The lpszPassword member must also be filled in if the session was marked as password protected. An enumerated session will have the DPSESSION_PASSWORDREQUIRED flag set if it requires a password.

If joining a secure session, you must use SecureOpen to provide login credentials. The enumerated session will have the DPSESSION_SECURESERVER flag set if it requires credentials.

If you specify the DPSESSION_SECURESERVER flag in the DPSESSIONDESC2 structure, the session will be opened with the default security package, NTLM (NT LAN Manager). To specify an alternate security package, use SecureOpen.

When an application attempts to join a session, the server can reject the Open request or ignore it (in which case Open will time-out). Attempting to join a session where new players are disabled, joining is disabled, the player limit has been reached, or an incorrect password is supplied will result in a DPERR_NONEWPLAYERS or DPERR_INVALIDPASSWORD error.

See Also

DPSESSIONDESC2, IDirectPlay3::Close, IDirectPlay3::SecureOpen, IDirectPlay3::EnumSessions


IDirectPlay3::Receive

IDirectPlay3 Interface

Retrieves a message from the message queue.

HRESULT Receive(
LPDPID lpidFrom,
LPDPID lpidTo,
DWORD dwFlags,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
lpidFrom
Pointer to a DPID that will be set to the sender's player ID when this method returns. If the DPRECEIVE_FROMPLAYER flag is specified, this variable must be initialized with the player ID before calling this method.
lpidTo
Pointer to a DPID that will be set to the receiver's player ID when this method returns. If the DPRECEIVE_TOPLAYER flag is specified, this variable must be initialized with the player ID before calling this method.
dwFlags
One or more of the following control flags can be set. By default (dwFlags = 0), the first available message will be retrieved.
DPRECEIVE_ALL
Returns the first available message. This is the default.
DPRECEIVE_PEEK
Returns a message as specified by the other flags, but does not remove it from the message queue. This flag must be specified if lpData is NULL.
DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER
If both DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER are specified, Receive will only return messages that are 1) sent to the player specified by lpidTo and 2) sent from the player specified by lpidFrom. Note that both conditions must be met.
If only DPRECEIVE_TOPLAYER is specified, Receive will only return messages sent to the player specified by lpidTo.
If only DPRECEIVE_FROMPLAYER is specified, Receive will only return messages sent from the player specified by lpidFrom.
If neither DPRECEIVE_TOPLAYER nor DPRECEIVE_FROMPLAYER is set, Receive will return the first available message.
lpData
Pointer to a buffer where the message data is to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the size required to hold the data. If the message came from player ID DPID_SYSMSG, the application should cast lpData to DPMSG_GENERIC and check the dwType member to see what type of system message it is before processing it.
lpdwDataSize
Pointer to a DWORD that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the number of bytes copied into the buffer. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size required. The message order in the receive queue can change between calls to IDirectPlay3::Receive. Therefore, it is possible to get a DPERR_BUFFERTOOSMALL error again even after the application has allocated the memory requested from the previous call to IDirectPlay3::Receive. It is best to keep reallocating memory until a DPERR_BUFFERTOOSMALL error is not received.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOMESSAGES
Remarks

Any message received from a player ID defined as DPID_SYSMSG is a system message used to notify the application of a change in the session. In those cases, the lpData of system messages should be cast to DPMSG_GENERIC and the dwType member should be examined to see what specific system message it is.

Messages that were sent to a player ID defined as DPID_ALLPLAYERS or to a Group ID still appear to come from the sending player ID. An application will only receive messages directed to a local player. A player cannot receive a message in which the values pointed to by lpidFrom and lpidTo are equal.

If DPSESSION_NOMESSAGEID is specified in the session description, the lpidFrom will always be 0xFFFFFFFF and the lpidTo value is arbitrary.

All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message retrieved using Receive is guaranteed to be free from corruption.

See Also

DPMSG_GENERIC, IDirectPlay3::Send


IDirectPlay3::SecureOpen

IDirectPlay3 Interface

Creates or joins a secure session. When joining a secure session, use this method to supply login credentials.

When creating a new session, the host computer can specify an alternate security package to use. When joining a session, a computer can specify a user name and password.

HRESULT IDirectPlay3::SecureOpen(
LPCDPSESSIONDESC2 lpsd,
DWORD dwFlags,
LPCDPSECURITYDESC lpSecurity,
LPCDPCREDENTIALS lpCredentials
)

Parameters
lpsd
Pointer to the DPSESSIONDESC2 structure describing the session to be created or joined. If a session is to be joined, then only the guidInstance and lpszPassword members need to be specified. The password need only be supplied if the enumerated session had the DPSESSION_PASSWORDREQUIRED flag set.
If a session is to be created, then the application must completely fill out the DPSESSIONDESC2 structure with the properties of the sessions to be created. The guidInstance will be generated by DirectPlay. NOTE: The DPSESSION_SECURESERVER flag must be set to indicate that all computers attempting to open the session must be authenticated.

If you don't specify the DPSESSION_SECURESERVER flag when filling out the DPSESSIONDESC2 structure, SecureOpen will open an unsecure session, just as if you had called Open.

dwFlags
One of the following flags:
DPOPEN_CREATE
Creates a new instance of a secured session.
DPOPEN_JOIN
Joins an existing instance of a secured session.
DPOPEN_RETURNSTATUS
If this flag is specified, the method will not display any dialog boxes showing the connection progress status. If the connection cannot be made immediately, the method will return with the DPERR_CONNECTING error. The application must keep calling SecureOpen until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.
lpSecurity
Pointer to a DPSECURITYDESC structure containing the security package to use. Set this parameter to NULL to use the default security package (NT LAN Manager) and CryptoAPI package (Microsoft RSA Base Cryptographic Provider). Relevant only when creating a session. Must be set to NULL when joining a session.
lpCredentials
Pointer to a DPCREDENTIALS structure containing the logon name, password, and domain to be authenticated on the server. NULL if there are no credentials. Credentials are ignored when creating a session.
Return Values

Returns DP_OK if successful or one of the following error values:

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDCREDENTIALS
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

This method DPERR_LOGONDENIED after being called with invalid creadentials or without credentials when credentials are required. The application must collect the user's credentials and call SecureOpen again.

Remarks

When joining a session, first call SecureOpen with no credentials. If the method returns DPERR_LOGONDENIED, then the application must collect the user name and password from the user and call SecureOpen again, passing in the user's credentials through the lpCredentials parameter. If the method returns DP_OK, then the player was able to login with the credentials he or she had specified earlier during system logon (network logon in NTLM).

See Also

IDirectPlay3::Open


IDirectPlay3::Send

IDirectPlay3 Interface

Sends a message to another player, to a group of players, or to all players in the session. To send a message to another player, specify the target player's player ID. To send a message to a group of players, send the message to the group ID assigned to the group. To send a message to the entire session, send the message to the player ID DPID_ALLPLAYERS. Messages can be sent using either a guaranteed or nonguaranteed protocol on a per message basis. If the session is being hosted on a secure server, messages can be sent encrypted (to ensure privacy) or digitally signed (to ensure authenticity) on a per message basis.

HRESULT Send(
DPID idFrom,
DPID idTo,
DWORD dwFlags,
LPVOID lpData,
DWORD dwDataSize
);

Parameters
idFrom
ID of the sending player. The player ID must correspond to one of the local players on this computer.
idTo
The destination ID of the message. To send a message to another player, specify the ID of the player. To send a message to all the players in a group, specify the ID of the group. To send a message to all the players in the session, use the constant symbol DPID_ALLPLAYERS. To send a message to the server player, specify the constant symbol DPID_SERVERPLAYER. A player cannot send a message to itself.
dwFlags
Indicates how the message should be sent. By default (dwFlags = 0), the message is sent nonguaranteed.
DPSEND_ENCRYPTED
Sends the messages encrypted. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.
DPSEND_GUARANTEED
Sends the message by using a guaranteed method of delivery if it is available.
DPSEND_SIGNED
Sends the message with a digital signature. This can only be done in a secure session. This flag can only be used if the DPSEND_GUARANTEED flag is also set. The message will be sent as a DPMSG_SECUREMESSAGE system message.
lpData
Pointer to the data being sent.
dwDataSize
Length of the data being sent.
Return Values

Returns DP_OK if successful or one of the following error values:

DPERR_BUSY
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

This method returns DPERR_INVALIDPARAMS if the encrypted or signed flag is specified for a message that is not also specified as guaranteed. It returns DPERR_NOTLOGGEDIN when the client application tries to send a secure message without first logging in.

Remarks

Messages can be sent guaranteed or nonguaranteed. By default, messages are sent nonguaranteed which means that DirectPlay does no verification that the message reached the intended recipient. Sending a guaranteed message takes much longer; a minimum of 2 to 3 times longer than nonguaranteed messages. Applications should try to minimize sending guaranteed messages as much as possible and design the application to tolerate lost messages. All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message retrieved using this method is guaranteed to be free from corruption.

A player cannot send a message to itself. If a player sends a message to a group that it is part of or to DPID_ALLPLAYERS, it will not receive a copy of that message. The exception to this rule is if the DPSESSION_NOMESSAGEID was specified in the session description (DPSESSIONDESC2). Then it is possible for a player to receive a message that it sent to a group. Because there is no DirectPlay message ID header on the message (indicating who sent the message), it cannot filter out messages based on the message ID.

When DPSESSION_NOMESSAGEID is used, the idFrom parameter has no meaning and the idTo parameter is used simply to direct the message to the correct target computer. If the target computer has more than one player on it, it cannot be determined whose receive queue the message will appear in. When the message is received, it will appear to have come from player DPID_UNKNOWN.

There is no limit to the size of messages that can be transmitted using the Send method. DirectPlay will automatically break up large messages into packets (packetize) and reassemble them on the receiving end. Beware of sending large messages nonguaranteed—if even one of the packets fails to reach the receiver then the entire message will be ignored. The application can determine the maximum size of a message before it starts packetizing by calling GetCaps and examining the dwMaxBufferSize member of the DPCAPS structure.

When you send an encryted or signed message, it is not delivered as an application message, but as a system message, DPMSG_SECUREMESSAGE.

See Also

IDirectPlay3::Receive, IDirectPlay3::SendChatMessage, DPMSG_SECUREMESSAGE


IDirectPlay3::SendChatMessage

IDirectPlay3 Interface

Sends a text message to another player, a group of players, or all players. This method supports both Unicode (the IDirectPlay3 interface) and ANSI strings (the IDirectPlay3A interface). The player receiving the chat message is informed through a DPMSG_CHAT system message in the player's receive queue. This method must be used in a lobby session.

HRESULT SendChatMessage(
DPID idFrom,
DPID idTo,
DWORD dwFlags,
LPDPCHAT lpChatMessage
);

Parameters
idFrom
ID of the sending player. The player ID must correspond to one of the local players on this computer.
idTo
ID of the player to send the message to, the group ID of the group of players to send the message to, or DPID_ALLPLAYERS to send the message to all players in the session.
dwFlags
Indicates how the message should be sent. If this parameter is set to 0, the message is sent nonguaranteed.
DPSEND_GUARANTEED
Sends the message by using a guaranteed method of delivery if it is available.
lpChatMessage
Pointer to a DPCHAT structure containing the message to be sent.
Return Values

Returns DP_OK if successful or one of the following error values:

DPERR_ACCESSDENIED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

This method returns DPERR_INVALIDPARAMS if the idTo ID is not a valid player or group. It returns DPERR_INVALIDPLAYER if the idFrom ID is not a valid player. It returns DPERR_ACCESSDENIED if the idFrom ID is not a local player.

Remarks

This method facilitates player to player chatting within a lobby session where it is possible for different client applications to be connected. You must use this method in a lobby session. Use is optional in an application seession.

The receiving player will receive a system message (idFrom = DPID_SYSTEM). The DPCHAT structure will specify which player the chat message came from.

See Also

DPCHAT, DPMSG_CHAT, IDirectPlay3::Send


IDirectPlay3::SetGroupConnectionSettings

IDirectPlay3 Interface

Sets the connection settings for a session that will be launched from this group. This method can only be used in a lobby session.

HRESULT SetGroupConnectionSettings(
DWORD dwFlags,
DPID idGroup,
LPDPLCONNECTION lpConnection
);

Parameters
dwFlags
Not used. Must be zero.
idGroup
The DPID of the group to set the connection settings on.
lpConnection
Pointer to a DPLCONNECTION structure describing the application to be launched, the service provider to use, and the session description of the session to be created.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED
Remarks

Call IDirectPlay3::GetGroupConnectionSettings before calling SetGroupConnectionSettings to see if any of the DPLCONNECTION structure members already have default values (non-NULL or non-zero). If so, you may get an error if you try to change these default values.

You do not have to set the lpAddress and dwAddressSize data members of the DPLCONNECTION structure with SetGroupConnectionSettings. In the DPSESSIONDESC2 structure within the DPLCONNECTION structure, you do not have to fill in the guidInstance member.

See Also

DPLCONNECTION, IDirectPlayLobby2::RunApplication, IDirectPlay3::GetGroupConnectionSettings


IDirectPlay3::SetGroupData

IDirectPlay3 Interface

Associates an application-specific data block with a group ID. Only the computer that created the group can change the remote data associated with it.

HRESULT SetGroupData(
DPID idGroup,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);

Parameters
idGroup
Group ID for which data is being set.
lpData
Pointer to the data to be set. Set to NULL to clear any existing group data.
dwDataSize
Size of the data buffer. If lpData is NULL and this parameter does not equal zero, the method returns DPERR_INVALIDPARAMS.
dwFlags
If this parameter is set to 0, the remote group data will be set and propagated using nonguaranteed messaging.
DPSET_GUARANTEED
Propagates the data by using guaranteed messaging (if available). This flag can only be used with DPSET_REMOTE.
DPSET_LOCAL
This data is for local use only and will not be propagated.
DPSET_REMOTE
This data is for use by all the applications, and will be propagated to all the other applications in the session. This flag can only be used on groups owned by the local session.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

DirectPlay can maintain two types of group data: local and remote. Local data is available only to the application on the local computer. Remote data is propagated to all the other applications in the session. A DPSYS_SETPLAYERORGROUPDATA system message will be sent to all players (including the sender) notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description. It is safe to store pointers to resources in the local data; the local data block is available (in the DPMSG_DESTROYPLAYERORGROUP system message) when the group is being destroyed, so the application can free those resources. For a list of system messages, see Using System Messages.

This method should not be used for updating real-time information (such as position updates) due to the overhead introduced. It is much more efficient to use IDirectPlay3::Send for this. IDirectPlay3::SetGroupData is more appropriate for shared state information that doesn't change very often and is not time critical (such as a team color).

See Also

DPMSG_SETPLAYERORGROUPDATA, IDirectPlay3::GetGroupData, IDirectPlay3::Send


IDirectPlay3::SetGroupName

IDirectPlay3 Interface

Sets the name of a group after it has been created. Only the computer that created the group can set the name of the group. A DPMSG_SETPLAYERORGROUPNAME system message will be sent to all the other players notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description.

HRESULT SetGroupName(
DPID idGroup,
LPDPNAME lpGroupName,
DWORD dwFlags
);

Parameters
idGroup
ID of the group for which the name is being set.
lpGroupName
Pointer to a DPNAME structure containing the name information for the group. Set this parameter to NULL if the group has no name information.
dwFlags
If this parameter is set to 0, the name will be propagated to all the remote systems by using nonguaranteed message passing. This value can only be used on groups owned by the local session.
DPSET_GUARANTEED
Propagates the data using guaranteed messaging (if available).
DPSET_LOCAL
This data is for local use only and will not be propagated.
DPSET_REMOTE
This data is for use by all the applications, and will be propagated to all the other applications in the session. This flag can only be used on groups owned by the local session.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
See Also

DPNAME, DPMSG_SETPLAYERORGROUPNAME, IDirectPlay3::GetGroupName, IDirectPlay3::Send


IDirectPlay3::SetPlayerData

IDirectPlay3 Interface

Associates an application-specific data block with a player ID.

HRESULT SetPlayerData(
DPID idPlayer,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);

Parameters
idPlayer
ID of the player for which data is being set.
lpData
Pointer to the data to be set. Set this parameter to NULL and dwDataSize to zero to clear out any existing player data.
dwDataSize
Size of the data buffer. If lpData is NULL and this parameter does not equal zero, the method returns DPERR_INVALIDPARAMS.
dwFlags
If this parameter is set to 0, the remote player data will be set and propagated by using nonguaranteed messaging.
DPSET_GUARANTEED
Propagates the data by using guaranteed messaging (if available). This flag can only be used with DPSET_REMOTE.
DPSET_LOCAL
This data is for local use only and will not be propagated.
DPSET_REMOTE
This data is for use by all the applications, and will be propagated to all the other applications in the session.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
Remarks

SetPlayerData should not be used for updating real-time information (such as position updates) due to the overhead introduced. It is much more efficient to use Send for this. SetPlayerData is more appropriate for shared state information that doesn't change very often and is not time critical (such as a player's name).

DirectPlay can maintain two types of player data: local and remote. Local data is available only to the application on the local computer. Remote data is propagated to all the other applications in the session. This method returns DPERR_ACCESSDENIED if you try to set player data for a remote player. A DPMSG_SETPLAYERORGROUPDATA system message will be sent to all players (including the sender) notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description. It is safe to store pointers to resources in the local data; the local data block is available (in the DPMSG_DESTROYPLAYERORGROUP system message) when the player is being destroyed, so the application can free those resources. For a list of system messages, see Using System Messages.

See Also

DPMSG_SETPLAYERORGROUPDATA, IDirectPlay3::GetPlayerData, IDirectPlay3::Send


IDirectPlay3::SetPlayerName

IDirectPlay3 Interface

Sets the name of a local player after it has been changed. Only the computer that created the player can change the name. A DPMSG_SETPLAYERORGROUPNAME system message will be sent to all the other players notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description.

HRESULT SetPlayerName(
DPID idPlayer,
LPDPNAME lpPlayerName,
DWORD dwFlags
);

Parameters
idPlayer
ID of the local player for which data is being sent.
lpPlayerName
Pointer to a DPNAME structure containing the name information for the player. Set this parameter to NULL if the player has no name information.
dwFlags
Flags indicating how the name will be propagated. It can be one of the following values:
DPSET_GUARANTEED
Propagates the data by using guaranteed messaging (if available).
DPSET_LOCAL
Data is not propagated to other players.
DPSET_REMOTE
Propagates the data to all players in the session using nonguaranteed message passing. This is the default value.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
See Also

DPNAME, DPMSG_SETPLAYERORGROUPNAME, IDirectPlay3::GetPlayerName, IDirectPlay3::Send


IDirectPlay3::SetSessionDesc

IDirectPlay3 Interface

Changes the properties of the current session. Only the host of the session can change the session properties. If a nonhost attempts to call it, the method returns DPERR_ACCESSDENIED.

The updated session description will be propagated to all the other computers in the session. Each player will receive a DPMSG_SETSESSIONDESC system message.

You can't use SetSessionDesc in a lobby session.

HRESULT SetSessionDesc(
LPDPSESSIONDESC2 lpSessDesc,
DWORD dwFlags
);

Parameters
lpSessDesc
Pointer to the DPSESSIONDESC2 structure containing the new settings.
dwFlags
No flags are currently used by this method.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_ACCESSDENIED
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

This method returns DPERR_ACCESSDENIED if this computer does not have permission to change the session. Only the host can change the session properties. It returns DPERR_INVALIDPARAMS if the application attempts to change a property in the session description that cannot be changed or tries to give a property an invalid value.

Remarks

Changing the session description will cause a DPSYS_SETSESSIONDESC system message to be generated on all the other computers in the session.

The following members and flags of the DPSESSIONDESC2 structure can be changed using IDirectPlay3::SetSessionDesc:

dwFlags
DPSESSION_JOINDISABLED
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_PRIVATE
dwMaxPlayers
If you set the maximum players to a value less than the current number of players, the method returns DPERR_INVALIDPARAMS.
lpszSessionName / lpszSessionNameA
lpszPassword / lpszPasswordA
dwUser1
dwUser2
dwUser3
dwUser4

If the following members and flags of the DPSESSIONDESC2 structure are changed, an error will occur (for example, if the DPSESSION_KEEPALIVE flag is currently set and you try to set this bit, you will not get an error, but if you try to clear this bit, you will get an error and IDirectPlay3::SetSessionDesc will fail):

dwSize
dwFlags
DPSESSION_NOMESSAGEID
DPSESSION_KEEPALIVE

The following members of the DPSESSIONDESC2 structure are ignored (that is, it does not matter what you pass in these members—DirectPlay will always use the values passed when IDirectPlay3::Open was called):
guidInstance
guidApplication
dwCurrentPlayers
dwReserved1
dwReserved2

See Also

DPSESSIONDESC2, IDirectPlay3::GetSessionDesc


IDirectPlay3::StartSession

IDirectPlay3 Interface

Use this method to initiate the launch of a DirectPlay session. Call SetGroupConnectionSettings first to specify what application to launch, which service provider to use, and what session description to use.

When StartSession is called, each player in the group receives a DPMSG_STARTSESSION instructing the player to launch the session.

HRESULT StartSession(
DWORD dwFlags,
DPID idGroup
);

Parameters
dwFlags
Not used. Must be zero.
idGroup
The DPID of the group to send start session commands to. The group must be a staging area.
Return Values

Returns DP_OK if successful or one of the following error values:

DPERR_ACCESSDENIED
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

This method returns DPERR_INVALIDGROUP if the given group ID is not a valid staging area.

Remarks

A player joining a staging area group for which the session has already started can call this method to join the session. The player will receive a DPMSG_STARTSESSION message instructing it how to join the session.

You can determine if a session is already in progress by calling IDirectPlay3::GetGroupConnectionSettings and examining the guidInstance parameter it returns through a pointer in the DPLCONNECTION structure to the DPSESSIONDESC2 structure. If guidInstance is GUID_NULL, no session is in progress. If it is any other value, a session is already in progress.

See Also

DPMSG_STARTSESSION


IDirectPlayLobby2 Interface

Applications use the methods of the IDirectPlayLobby2 interface to manage applications and their associated data. This section is a reference to the methods of this interface. For a conceptual overview, see IDirectPlayLobby2 Interface.
Address management | CreateAddress
CreateCompoundAddress
EnumAddress
EnumAddressTypes
Application management | Connect
EnumLocalApplications
RunApplication
Data management | GetConnectionSettings
ReceiveLobbyMessage
SendLobbyMessage
SetConnectionSettings
SetLobbyMessageEvent


IDirectPlayLobby2::Connect

IDirectPlayLobby2 Interface

Connects an application to the session specified by the DPLCONNECTION structure currently stored with the DirectPlayLobby object.

Note This method will return an IDirectPlay2 or IDirectPlay2A interface. Use the standard COM QueryInterface method to obtain an IDirectPlay3 or IDirectPlay3A method.

HRESULT Connect(
DWORD dwFlags,
LPDIRECTPLAY2 *lplpDP,
IUnknown FAR *pUnk
);

Parameters
dwFlags
Reserved; must be zero.
lplpDP
Pointer to a pointer to be initialized with a valid interface—either IDirectPlay2 (if called on IDirectPlayLobby2) or IDirectPlay2A (if called on IDirectPlayLobby2A).
pUnk
Pointer to the containing IUnknown interface. This parameter is provided for future compatibility with COM aggregation features. Presently, however, IDirectPlayLobby2::Connect returns an error if this parameter is anything but NULL.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

CLASS_E_NOAGGREGATION
DPERR_INVALIDFLAGS
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY
Remarks

After this method is successfully completed, the application can skip the process of calling IDirectPlay3::InitializeConnection, IDirectPlay3::EnumSessions, and IDirectPlay3::Open. The application should not ask the user a name but instead create a player using the player name information in the DPLCONNECTION structure.

Before calling this method, the application can examine the connection settings that will be used to start the application by using the IDirectPlayLobby2::GetConnectionSettings method. The application then can modify these settings and set them by using the IDirectPlayLobby2::SetConnectionSettings method. The application should pay particular attention to the DPSESSIONDESC2 structure to ensure that the proper session properties are set, especially dwFlags, dwMaxPlayers, and the dwUser members.


IDirectPlayLobby2::CreateAddress

IDirectPlayLobby2 Interface

Creates a DirectPlay Address, given a service provider-specific network address. The resulting address contains the globally unique identifier (GUID) of the service provider and data that the service provider can interpret as a network address.

For more information about the DirectPlay Address, see DirectPlay Address. For a list of predefined Microsoft data types, see DirectPlay Address Data Types.

HRESULT CreateAddress(
REFGUID guidSP,
REFGUID guidDataType,
LPCVOID lpData,
DWORD dwDataSize,
LPVOID lpAddress,
LPDWORD lpdwAddressSize
);

Parameters
guidSP
Pointer to the GUID of the service provider. (In C++, it is a reference to the GUID.)
guidDataType
Pointer to the GUID identifying the specific network address type being used. (In C++, it is a reference to the GUID.) For information about predefined network address types, see DirectPlay Address.
lpData
Pointer to a buffer containing the specific network address.
dwDataSize
Size, in bytes, of the network address in lpData.
lpAddress
Pointer to a buffer in which the constructed DirectPlay Address is to be written.
lpdwAddressSize
Pointer to a variable containing the size of the DirectPlay Address buffer. Before calling this method, the service provider must initialize lpdwAddressSize to the size of the buffer. After the method has returned, this parameter will contain the number of bytes written to lpAddress. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the size required to store the DirectPlay Address.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDPARAMS
Remarks

The IDirectPlayLobby2::CreateCompoundAddress method can be used to create longer DirectPlay Addresses than CreateAddress allows.

See Also

IDirectPlayLobby2::EnumAddress, IDirectPlayLobby2::CreateCompoundAddress


IDirectPlayLobby2::CreateCompoundAddress

IDirectPlayLobby2 Interface

Creates a DirectPlay Address from a list of individual data chunks. This method can be used to create longer DirectPlay Addresses than IDirectPlayLobby2::CreateAddress allows. For a list of predefined Microsoft data types, see DirectPlay Address Data Types.

HRESULT CreateCompoundAddress(
LPDPCOMPOUNDADDRESSELEMENT lpElements,
DWORD dwElementCount,
LPVOID lpAddress,
LPDWORD lpdwAddressSize
);

Parameters
lpElements
Pointer to the first element in an array of DPCOMPOUNDADDRESSELEMENT structures that will be used to generate the DirectPlay Address.
dwElementCount
The number of address elements in the array pointed to by the lpElements parameter.
lpData
Pointer to a buffer that the complete DirectPlay Address is to be written to. Pass NULL if only the required size of the buffer is desired.
lpdwDataSize
Pointer to a DWORD with the size of the lpData buffer. The DWORD will be modified to reflect the actual number of bytes copied into the buffer. If the buffer was too small, it will contain the number of bytes required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
See Also

IDirectPlayLobby2::CreateAddress, IDirectPlayLobby2::EnumAddress, DPCOMPOUNDADDRESSELEMENT


IDirectPlayLobby2::EnumAddress

IDirectPlayLobby2 Interface

Parses out chunks from the DirectPlay Address buffer.

HRESULT EnumAddress(
LPDPENUMADDRESSCALLBACK lpEnumAddressCallback,
LPCVOID lpAddress,
DWORD dwAddressSize,
LPVOID lpContext
);

Parameters
lpEnumAddressCallback
Pointer to a EnumAddressCallback function that will be called for each information chunk in the DirectPlay Address.
lpAddress
Pointer to the start of the DirectPlay Address buffer.
dwAddressSize
Size of the DirectPlay Address.
lpContext
Context that will be passed to the callback function.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
Remarks

For more information about the DirectPlay Address, see DirectPlay Address.

See Also

IDirectPlayLobby2::CreateAddress


IDirectPlayLobby2::EnumAddressTypes

IDirectPlayLobby2 Interface

Enumerates all the address types that a given service provider needs to build the DirectPlay Address. The application or lobby can use this information to obtain the correct information from the user and create a DirectPlay Address.

HRESULT EnumAddressTypes(
LPDPLENUMADDRESSTYPESCALLBACK lpEnumAddressTypeCallback,
REFGUID guidSP,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpEnumAddressTypeCallback
Pointer to the EnumAddressTypeCallback function that will be called for each address type for a service provider. If the service provider takes no address type, the callback will not be called.
guidSP
Pointer to the GUID of the service provider whose address types are to be enumerated. (In C++, it is a reference to the GUID.)
lpContext
Context that will be passed to the callback function.
dwFlags
Reserved; must be zero.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
Remarks

For more information about the DirectPlay Address, DirectPlay Address. You can use EnumAddressTypes to determine if a service provider displays dialog boxes prompting the user for information; for example, a dialog box that asks for an IP address. If the service provider takes no address types, then it needs no information and will not display the dialog boxes.

An application can call IDirectPlay3::GetPlayerAddress to obtain a list of valid choices for an address type. This is only available for the modem-to-modem service providers. DirectPlay Address data types that are null-terminated Unicode strings end in W (for example, DPAID_INetW), while DirectPlay Address data types that are null-terminated ANSI strings do not (for example, DPAID_INet). For a list of predefined Microsoft data types, see DirectPlay Address Data Types.

See Also

DirectPlay Address, IDirectPlayLobby2::CreateAddress


IDirectPlayLobby2::EnumLocalApplications

IDirectPlayLobby2 Interface

Enumerates what applications are registered with DirectPlay.

HRESULT EnumLocalApplications(
LPDPENUMLOCALAPPLICATIONSCALLBACK lpEnumLocalAppCallback,
LPVOID lpContext,
DWORD dwFlags
);

Parameters
lpEnumLocalAppCallback
Pointer to the EnumLocalApplicationsCallback function that will be called for each enumerated application.
lpContext
Context passed to the callback function.
dwFlags
Reserved; must be zero.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
See Also

DPLAPPINFO


IDirectPlayLobby2::GetConnectionSettings

IDirectPlayLobby2 Interface

Retrieves the DPLCONNECTION structure that contains all the information needed to start and connect an application. The data returned is the same data that was passed to the IDirectPlayLobby2::RunApplication method by the lobby client, or set by calling the IDirectPlayLobby2::SetConnectionSettings method.

HRESULT GetConnectionSettings(
DWORD dwAppID,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
dwAppID
Identifies which application's connection settings to retrieve when called from a lobby client (that communicates with several applications). When called from an application (that only communicates with one lobby client), this parameter must be zero. This ID number is obtained from IDirectPlayLobby2::RunApplication.
lpData
Pointer to a buffer in which the connection settings are to be written. Set this parameter to NULL to request only the size of data. The lpdwDataSize parameter will be set to the minimum size required to hold the data.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the minimum buffer size required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY
Remarks

The lpData member should be cast to the DPLCONNECTION structure when the function returns to read the data from it.

See Also

DPLCONNECTION, IDirectPlayLobby2::RunApplication, IDirectPlayLobby2::SetConnectionSettings


IDirectPlayLobby2::ReceiveLobbyMessage

IDirectPlayLobby2 Interface

Retrieves the message sent between a lobby client application and a DirectPlay application. Messages are queued, so there is no danger of losing data if it is not read in time.

HRESULT ReceiveLobbyMessage(
DWORD dwFlags,
DWORD dwAppID,
LPDWORD lpdwMessageFlags,
LPVOID lpData,
LPDWORD lpdwDataSize
);

Parameters
dwFlags
Reserved; must be zero.
dwAppID
Identifies which application's message to retrieve when called from a lobby client (that communicates with several applications). When called from an application (that communicates only with one lobby client), this parameter must be set to zero. This ID number is obtained by using the IDirectPlayLobby2::RunApplication method.
lpdwMessageFlags
Flags indicating what type of message is being returned. The default (lpdwMessageFlags = 0) indicates that the message is custom-defined by the sender. Processing of this type of message is optional. The receiver must interpret this message based on the identity of the sending application. A lobby can identify the sending application based on the GUID of the application that was launched. An application will need to identify the lobby by sending the lobby a standard message requesting an identifying GUID.
DPLMSG_STANDARD
Indicates that this is a DirectPlay-defined message. Processing of this type of message is optional.
DPLMSG_SYSTEM
Indicates that this is a DirectPlay generated system message used to inform the lobby of changes in the status of the application it launched.
lpData
Pointer to a buffer in which the message is to be written. Set this parameter to NULL to request only the size of message. The lpdwDataSize parameter will be set to the minimum size required to hold the message.
lpdwDataSize
Pointer to a variable that is initialized to the size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the message. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the minimum buffer size required.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOMESSAGES
DPERR_OUTOFMEMORY
See Also

IDirectPlayLobby2::RunApplication, IDirectPlayLobby2::SendLobbyMessage


IDirectPlayLobby2::RunApplication

IDirectPlayLobby2 Interface

Starts an application and passes to it all the information necessary to connect it to a session. This method is used by a lobby client.

HRESULT RunApplication(
DWORD dwFlags,
LPDWORD lpdwAppID,
LPDPLCONNECTION lpConn,
HANDLE hReceiveEvent
);

Parameters
dwFlags
Reserved; must be zero.
lpdwAppId
Pointer to a variable that will be filled with an ID identifying the application that was started. The lobby client must save this application ID for use on with any calls to the IDirectPlayLobby2::SendLobbyMessage and IDirectPlayLobby2::ReceiveLobbyMessage methods.
lpConn
Pointer to a DPLCONNECTION structure that contains all the information necessary to specify which application to start and how to get it connected to a session instance without displaying any user dialog boxes.
hReceiveEvent
Specifies a synchronization event that will be set when a lobby message is received. This event can be changed later by using the IDirectPlayLobby2::SetLobbyMessageEvent method.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_CANTCREATEPROCESS
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_UNKNOWNAPPLICATION
Remarks

This method will return after the application process has been created. The lobby client will receive a system message indicating the status of the application. If the lobby client is starting an application that will be hosting a session, it should wait until it receives a DPLSYS_DPLAYCONNECTSUCCEEDED system message before starting the other applications that will be joining the session. If the application was unable to create or join a session, a DPLSYS_DPLAYCONNECTFAILED message will be generated. The lobby client will also receive a DPLSYS_CONNECTIONSETTINGSREAD system message when the application has read the connection settings and a DPLSYS_APPTERMINATED system message when the application terminates.

It is important that the lobby client not release its IDirectPlayLobby2 Interface interface before it receives a DPLSYS_CONNECTIONSETTINGSREAD system message. The lobby client can either check IDirectPlayLobby2::ReceiveLobbyMessage in a loop until it is received, or supply a synchronization event.

See Also

IDirectPlayLobby2::ReceiveLobbyMessage, IDirectPlayLobby2::GetConnectionSettings, IDirectPlayLobby2::SetLobbyMessageEvent


IDirectPlayLobby2::SendLobbyMessage

IDirectPlayLobby2 Interface

Sends a message between the application and the lobby client.

HRESULT SendLobbyMessage(
DWORD dwFlags,
DWORD dwAppID,
LPVOID lpData,
DWORD dwDataSize
);

Parameters
dwFlags
Flags indicating the type of message being sent. The default (dwFlags = 0) is a custom message defined by the application sending it. Other possible values are:
DPLMSG_STANDARD – this is a standard message defined by DirectPlay.
dwAppID
Identifies which application to send a message to when called from a lobby client (that communicates with several applications). When called from an application (that communicates with only one lobby client), this parameter must be zero. This ID is obtained by using the IDirectPlayLobby2::RunApplication method.
lpData
Pointer to the buffer containing the message to send.
dwDataSize
Size, in bytes, of the buffer.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOLARGE
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_TIMEOUT
See Also

IDirectPlayLobby2::RunApplication, IDirectPlayLobby2::ReceiveLobbyMessage, DPLMSG_SETPROPERTY, DPLMSG_SETPROPERTYRESPONSE, DPLMSG_GETPROPERTY, DPLMSG_GETPROPERTYRESPONSE,


IDirectPlayLobby2::SetConnectionSettings

IDirectPlayLobby2 Interface

Modifies the DPLCONNECTION structure, which contains all the information needed to start and connect an application.

HRESULT SetConnectionSettings(
DWORD dwFlags,
DWORD dwAppID,
LPDPLCONNECTION lpConn
);

Parameters
dwFlags
Reserved; must be zero.
dwAppID
When called from a lobby client (that communicates with several applications), this parameter identifies which application's connection settings to retrieve. When called from an application (that communicates with only one lobby client), this parameter must be zero. This ID is obtained by using the IDirectPlayLobby2::RunApplication method.
lpConn
Pointer to a DPLCONNECTION structure that contains all the information necessary to specify which application to start and how to get it connected to a session instance without displaying any user dialog boxes.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
See Also

IDirectPlayLobby2::GetConnectionSettings


IDirectPlayLobby2::SetLobbyMessageEvent

IDirectPlayLobby2 Interface

Registers an event that will be set when a lobby message is received. The application must call this method if it needs to synchronize with messages. The lobby client can call this method to change the events specified in the call to the IDirectPlayLobby2::RunApplication method.

HRESULT SetLobbyMessageEvent(
DWORD dwFlags,
DWORD dwAppID,
HANDLE hReceiveEvent
);

Parameters
dwFlags
Reserved; must be zero.
dwAppID
Identifies which application the event is associated with when called from a lobby client (that communicates with several applications). When called from an application (that communicates with only one lobby client), this parameter must be zero. This ID number is obtained from IDirectPlayLobby2::RunApplication.
hReceiveEvent
Event handle to be set when a message is received.
Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
See Also

IDirectPlayLobby2::ReceiveLobbyMessage, IDirectPlayLobby2::SendLobbyMessage


Structures

Some structures have changed for DirectPlay 5, with new data members added to the end. Applications that use the IDirectPlay2 interface but are compiled using the DirectX 5 header files can have problems. An application might crash if it is run on a computer that has the DirectX 3 run time installed and the application references data members that were added for DirectX 5.

Applications that need to be backward compatible with older run times should either:

  • use the structures that existed in the DirectX 3 header files
  • check the dwSize member in each structure before attempting to access to members of the structure

The structures that have new members for DirectPlay 5 are:
Structure | New Members
DPCREDENTIALS | union of
LPWSTR lpszDomain
LPSTR lpszDomainA

The DirectPlay structures are:

  • DPACCOUNTDESC
  • DPCAPS
  • DPCHAT
  • DPCOMPORTADDRESS
  • DPCOMPOUNDADDRESSELEMENT
  • DPCREDENTIALS
  • DPLAPPINFO
  • DPLCONNECTION
  • DPNAME
  • DPSECURITYDESC
  • DPSESSIONDESC2


DPACCOUNTDESC

Describes the account information for a specific player.

typedef struct {
  DWORD  dwSize;
  DWORD  dwFlags;
  union {
    LPWSTR  lpszAccountID;
    LPSTR   lpszAccountIDA;
  };
} DPACCOUNTDESC, FAR *LPDPACCOUNTDESC;
Members
dwSize
The size of the DPACCOUNTDESC structure, dwsize = sizeof(DPACCOUNTDESC).
dwFlags
Not used. Must be zero.
lpszAccountID
Pointer to a Unicode string containing the account identifier. This is a unique identifier that describes a player who is securely logged in. The format of the identifier depends on the Security Support Provider Interface (SSPI) package being used.
lpszAccountIDA
Pointer to an ANSI string containing the account identifier. This is a unique identifier that describes a player who is securely logged in. The format of the identifier depends on the SSPI package being used.
See Also

IDirectPlay3::GetPlayerAccount


DPCAPS

Contains the capabilities of a DirectPlay object after a call to the IDirectPlay3::GetCaps or IDirectPlay3::GetPlayerCaps methods. Any of these capabilities can differ depending on whether guaranteed or nonguaranteed capabilities are requested. This structure is read-only.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMaxBufferSize;
    DWORD dwMaxQueueSize;
    DWORD dwMaxPlayers;
    DWORD dwHundredBaud;
    DWORD dwLatency;
    DWORD dwMaxLocalPlayers;
    DWORD dwHeaderLength;
    DWORD dwTimeout;
} DPCAPS, FAR *LPDPCAPS;
Members
dwSize
The size of the DPCAPS structure, dwsize = sizeof(DPCAPS). Your application must set this member before it uses this structure; otherwise, an error will result.
dwFlags
Indicates the properties of the DirectPlay object.
DPCAPS_ENCRYPTIONSUPPORTED
Indicates that message encryption is supported by this DirectPlay object, either because it is a secure session or because the service provider can encrypt messages.
DPCAPS_GROUPOPTIMIZED
Indicates that the service provider bound to this DirectPlay object can optimize group (multicast) messaging.
DPCAPS_GUARANTEEDOPTIMIZED
Indicates that the service provider bound to this DirectPlay object supports guaranteed message delivery.
DPCAPS_GUARANTEEDSUPPORTED
Indicates that the DirectPlay object supports guaranteed message delivery, either because the service provider supports it or because DirectPlay implements it on a nonguaranteed service provider.
DPCAPS_ISHOST
Indicates that the DirectPlay object created by the calling application is the session host.
DPCAPS_KEEPALIVEOPTIMIZED
The service provider can detect when the connection to the session has been lost.
DPCAPS_SIGNINGSUPPORTED
Indicates that message authentication is supported by this DirectPlay object , either because it is a secure session or because the service provider can sign messages.
dwMaxBufferSize
Maximum number of bytes that can be sent in a single packet by this service provider. Larger messages will be sent by using more than one packet.
dwMaxQueueSize
This member is no longer used.
dwMaxPlayers
Maximum number of local and remote players supported in a session by this DirectPlay object.
dwHundredBaud
Bandwidth specified in multiples of 100 bits per second. For example, a value of 24 specifies 2400 bits per second.
dwLatency
Estimate of latency by the service provider, in milliseconds. If this value is 0, DirectPlay cannot provide an estimate. Accuracy for some service providers rests on application-to-application testing, taking into consideration the average message size. Latency can differ depending on whether the application uses guaranteed or nonguaranteed message delivery.
dwMaxLocalPlayers
Maximum number of local players supported in a session.
dwHeaderLength
Size, in bytes, of the header that will be added to player messages by this DirectPlay object. Note that the header size depends on which service provider is in use.
dwTimeout
Service provider's suggested time-out value. By default, DirectPlay will use this time-out value when waiting for replies to messages.
See Also

IDirectPlay3::Send


DPCHAT

Contains a DirectPlay chat message. Chat messages are sent with the IDirectPlay3::SendChatMessage method.

typedef struct {
    DWORD	dwSize;
    DWORD	dwFlags;
    union{
      LPWSTR lpszMessage;
      LPSTR  lpszMessageA;
    };
} DPCHAT, FAR *LPDPCHAT;
Members
dwSize
The size of the DPCHAT structure, dwsize = sizeof(DPCHAT).
dwFlags
Not used. Must be 0.
lpszMessage
Pointer to a Unicode string containing the message to be sent. Can only be used with a Unicode interface (IDirectPlay3).
lpszMessageA
Pointer to an ANSI string containing the message to be sent. Can only be used with an ANSI interface (IDirectPlay3A).
See Also

IDirectPlay3::SendChatMessage


DPCOMPORTADDRESS

Contains information about the configuration of the COM port.

typedef struct DPCOMPORTADDRESS{
    DWORD dwComPort;
    DWORD dwBaudRate;
    DWORD dwStopBits;
    DWORD dwParity;
    DWORD dwFlowControl;
} DPCOMPORTADDRESS;

typedef DPCOMPORTADDRESS FAR* LPDPCOMPORTADDRESS;
Members
dwComPort
Indicates the number of the COM port to use. The value for this member can be 1, 2, 3, or 4.
dwBaudRate
Indicates the baud of the COM port. The value for this member can be one of the following:
CBR_110 | CBR_300 | CBR_600
CBR_1200 | CBR_2400 | CBR_4800
CBR_9600 | CBR_14400 | CBR_19200
CBR_38400 | CBR_56000 | CBR_57600
CBR_115200 | CBR_128000 | CBR_256000
dwStopBits
Indicates the number of stop bits. The value for this member can be ONESTOPBIT, ONE5STOPBITS, or TWOSTOPBITS.
dwParity
Indicates the parity used on the COM port. The value for this member can be NOPARITY, ODDPARITY, EVENPARITY, or MARKPARITY.
dwFlowControl
Indicates the method of flow control used on the COM port. The following values can be used for this member:
DPCPA_DTRFLOW | Indicates hardware flow control with DTR.
DPCPA_NOFLOW | Indicates no flow control.
DPCPA_RTSDTRFLOW | Indicates hardware flow control with RTS and DTR.
DPCPA_RTSFLOW | Indicates hardware flow control with RTS.
DPCPA_XONXOFFFLOW | Indicates software flow control (xon/xoff).
Remarks

The constants that define baud, stop bits, and parity are defined in Winbase.h.


DPCOMPOUNDADDRESSELEMENT

Describes a DirectPlay Address data chunk. See DirectPlay Address Data Types for a list of predefined Microsoft data types.

typedef struct {
    GUID    guidDataType;
    DWORD   dwDataSize;
    LPVOID  lpData;
} DPCOMPOUNDADDRESSELEMENT, FAR *LPDPCOMPOUNDADDRESSELEMENT;
Members
guidDataType
GUID identifying the type of data contained in this structure.
dwDataSize
Size of the data in bytes.
lpData
Pointer to a buffer containing the data.
See Also

IDirectPlayLobby2::CreateCompoundAddress


DPCREDENTIALS

Holds the user name, password, and domain to connect to a secure server.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
           LPWSTR lpszUsername;
           LPSTR  lpszUsernameA;
          };
    union {
           LPWSTR lpszPassword;
           LPSTR  lpszPasswordA;
          };
    union {
           LPWSTR lpszDomain;
           LPSTR  lpszDomainA;
          };

} DPCREDENTIALS, FAR *LPDPCREDENTIALS;
Members
dwSize
The size of the DPCREDENTIALS structure, dwsize = sizeof(DPCREDENTIALS).
dwFlags
Not used. Must be zero.
lpszUsername, lpszPassword, lpszDomain
Pointers to Unicode strings containing the user name, password, and domain name. Can only be used with a Unicode interface.
lpszUsernameA, lpszPasswordA, lpszDomainA
Pointers to ANSI strings containing the user name, password, and domain name. Can only be used with an ANSI interface.
See Also

IDirectPlay3::SecureOpen


DPLAPPINFO

Contains information about the application from the registry and is passed to the IDirectPlayLobby2::EnumLocalApplications callback function.

typedef struct {
    DWORD  dwSize;
    GUID   guidApplication;
    union {
           LPSTR  lpszAppNameA;
           LPWSTR lpszAppName;
          };
} DPLAPPINFO, FAR *LPDPLAPPINFO;
Members
dwSize
The size of the DPLAPPINFO structure, dwsize = sizeof(DPLAPPINFO). Your application must set this member before it uses this structure; otherwise, an error will result.
guidApplication
Globally unique identifier (GUID) of the application.
lpszAppNameA, lpszAppName
Name of the application in ANSI or Unicode, depending on what interface is in use.


DPLCONNECTION

Contains the information needed to connect an application to a session.

typedef struct {
    DWORD            dwSize;
    DWORD            dwFlags;
    LPDPSESSIONDESC2 lpSessionDesc;
    LPDPNAME         lpPlayerName;
    GUID             guidSP;
    LPVOID           lpAddress;
    DWORD            dwAddressSize;
} DPLCONNECTION, FAR *LPDPLCONNECTION;
Members
dwSize
The size of the DPLCONNECTION structure, dwsize = sizeof(DPLCONNECTION). Your application must set this member before it uses this structure; otherwise, an error will result. Examine this member to determine if the fields added in DirectPlay version 5 are available.
dwFlags
Indicates how to open a session.
DPLCONNECTION_CREATESESSION
Create a new session as described in the session description.
DPLCONNECTION_JOINSESSION
Join the existing session as described in the session description.
lpSessionDesc
Pointer to a DPSESSIONDESC2 structure describing the session to be created or the session to join.
lpPlayerName
Pointer to a DPNAME structure holding the name the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
guidSP
Globally unique identifier (GUID) of the service provider to use to connect to the session.
lpAddress
Pointer to a DirectPlay Address that contains the information that the service provider needs to connect to a session. For more information about the DirectPlay Address, see DirectPlay Address. For a list of Microsoft predefined address data types, see DirectPlay Address Data Types.
dwAddressSize
Size, in bytes, of the address data.
See Also

IDirectPlayLobby2::RunApplication, IDirectPlayLobby2::GetConnectionSettings, IDirectPlayLobby2::SetConnectionSettings


DPNAME

Contains name information for a DirectPlay entity, such as a player or group.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    union {
        LPWSTR lpszShortName;
        LPSTR  lpszShortNameA;
    };
    union {
        LPWSTR lpszLongName;
        LPSTR  lpszLongNameA;
    };
} DPNAME, FAR *LPDPNAME;
Members
dwSize
The size of the DPNAME structure, dwsize = sizeof(DPNAME). Your application must set this member before it uses this structure; otherwise, an error will result.
dwFlags
Structure-specific flags. Currently set to zero.
lpszShortName and lpszLongName
Pointers to Unicode strings containing the short (friendly) and long (formal) names of a player or group. Use these members only if the IDirectPlay3 Interface interface is in use.
lpszShortNameA and lpszLongNameA
Pointers to ANSI strings containing the short (friendly) and long (formal) names of a player or group. Use these members only if the IDirectPlay3A interface is in use.
See Also

IDirectPlay3::CreateGroup, IDirectPlay3::CreatePlayer, IDirectPlay3::GetGroupName, IDirectPlay3::GetPlayerName, IDirectPlay3::SetGroupName, IDirectPlay3::SetPlayerName


DPSECURITYDESC

Describes the security properties of a DirectPlay session instance.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
           LPWSTR  lpszSSPIProvider;
           LPSTR   lpszSSPIProviderA;
    };
    union {
           LPWSTR lpszCAPIProvider;
           LPSTR  lpszCAPIProviderA;
    };
    DWORD  dwCAPIProviderType;
    DWORD  dwEncryptionAlgorithm;
} DPSECURITYDESC, FAR *LPDPSECURITYDESC;
Members
dwSize
The size of the DPSECURITYDESC structure, dwsize = sizeof(DPSECURITYDESC).
dwFlags
Not used. Must be zero.
lpszSSPIProvider, lpszSSPIProviderA
Pointer to a Unicode or ANSI string describing the Security Support Provider Interface (SSPI) package to use for authenticated logins. Pass NULL to use the default, the NTLM (NT LAN Manager) security provider.
lpszCAPIProvider, lpszCAPIProviderA
Pointer to a Unicode or ANSI string describing the CryptoAPI package to use for cryptography services. Pass NULL to use the default, the Microsoft RSA Base Cryptographic Provider v. 1.0.
dwCAPIProviderType
CryptoAPI service provider type. Pass zero to use the default type, PROV_RSA_FULL.
dwEncryptionAlgorithm
Encryption algorithm to use. DirectPlay only supports stream ciphers. Pass zero to use the default, the CALG_RC4 stream cipher.
Remarks

For more information about the CryptoAPI, see the CrpytoAPI and Cryptography topics at http://www.microsoft.com. The Microsoft RSA Base Cryptographic Provider is supplied by Microsoft and is included with the Windows 95 and Windows NT operating systems.

DirectPlay does not support block encryption.

See Also

IDirectPlay3::SecureOpen


DPSESSIONDESC2

Contains a description of an IDirectPlay3 Interface session's capabilities. (The DPSESSIONDESC structure is no longer used in the IDirectPlay3 interface.)

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidInstance;
    GUID  guidApplication;
    DWORD dwMaxPlayers;
    DWORD dwCurrentPlayers;
    union  {
        LPWSTR lpszSessionName;
        LPSTR  lpszSessionNameA;
    };
    union  {
        LPWSTR lpszPassword;
        LPSTR  lpszPasswordA;
    };
    DWORD dwReserved1;
    DWORD dwReserved2;
    DWORD dwUser1;
    DWORD dwUser2;
    DWORD dwUser3;
    DWORD dwUser4;
} DPSESSIONDESC2, FAR *LPDPSESSIONDESC2;
Members
dwSize
The size of the DPSESSIONDESC2 structure, dwsize = sizeof(DPSESSIONDESC2). Your application must set this member before it uses this structure; otherwise, an error will result.
dwFlags
A combination of the following flags. These flags can be changed after a session has started by using IDirectPlay3::SetSessionDesc.
DPSESSION_CLIENTSERVER
This is a client/server session that is being hosted by an application server process. This flag must be specified at the time the session is created. Any clients that join this session will only be able to enumerate the server player and any local players. The host of the session will see all the players. If this flag is not set, the session is a peer-to-peer session. If this flag is set, the host can only create a server player. This flag cannot be used with DPSESSION_MIGRATEHOST.
DPSESSION_JOINDISABLED
No new applications can join this session. Any call to the IDirectPlay3::Open method with the DPOPEN_JOIN flag and the globally unique identifier (GUID) of this session instance will cause an error. If this flag is not specified, new remote applications can join the session until the session player limit is reached.
DPSESSION_KEEPALIVE
Automatically detect when remote players drop out of the game abnormally. Those players will be deleted from the session. If a temporary network outage caused the loss of the players, they will be informed when they return that they were dropped from the session through the DPMSG_SESSIONLOST system message. This flag must be specified at the time the session is created. If this flag is not specified, DirectPlay will not automatically keep the session alive if players are abnormally terminated.
DPSESSION_MIGRATEHOST
If the current host exits, another computer in the session will become the host. The players on the new host computer will receive a DPMSG_HOST system message. This flag must be specified at the time the session is created. If this flag is not specified, the host will not migrate, new computers cannot join the session, and new players cannot be created if the current host leaves. Note that the DPSESSION_MIGRATEHOST flag cannot be used with the DPSESSION_CLIENTSERVER, DPSESSION_MULTICASTSERVER, or DPSESSION_SECURESERVER flags.
DPSESSION_MULTICASTSERVER
In a peer-to-peer session, broadcast and group messages are routed through the host which acts like a multicast server. This flag must be specified at the time the session is created. The flag is only useful if the host has a high bandwidth connection to the network. If this flag is not specified, broadcast and group messages are sent directly between peers. This flag cannot be used with DPSESSION_MIGRATEHOST.
DPSESSION_NEWPLAYERSDISABLED
Indicates that new players cannot be created in the session. Any call to the IDirectPlay3::CreatePlayer method by an application in the session will result in an error. Also, new applications cannot join the session. If this flag is not specified, players can be created until the session player limit is reached.
DPSESSION_NODATAMESSAGES
Do not send system messages when remote player data, group data, or session data is changed with the IDirectPlay3::SetPlayerData, IDirectPlay3::SetGroupData, IDirectPlay3::SetPlayerName, IDirectPlay3::SetGroupName, or IDirectPlay3::SetSessionDesc method. If this flag is not specified, messages will be generated indicating that the data changed.

Note that setting this flag also suppresses the DPMSG_SETSESSIONDESC message.

DPSESSION_NOMESSAGEID
Do not attach data to messages indicating what player the message is from and to whom it is sent. Saves message overhead if this information is not relevant. (For more information, see the IDirectPlay3::Receive method.) If this flag is not specified, the message ID will be added. This flag must be specified at the time the session is created.
DPSESSION_PASSWORDREQUIRED
This session is password protected. Any applications wishing to join the session must supply the password in the IDirectPlay3::Open call. This is a read-only flag. It will be set automatically by DirectPlay when the host of the session specifies a non-NULL password.
DPSESSION_PRIVATE
This is a private session. It can not respond to enumeration requests unless the request contains a non-NULL, matching password. If this flag is not specified, the session will respond to enumeration requests.
DPSESSION_SECURESERVER
This session is being hosted on a secure server which will require authentication credentials before it can be opened. The host must specify this flag when the session is created. It cannot be changed later through IDirectPlay3::SetSessionDesc. This flag can only be used if the DPSESSION_CLIENTSERVER flag is also specified. This flag cannot be used with the DPSESSION_MIGRATEHOST flag.
guidInstance
GUID of the session instance.
guidApplication
GUID for the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
dwMaxPlayers
Maximum number of players allowed in this session. A value of zero means there is no maximum.
dwCurrentPlayers
Number of players currently in the session.
lpszSessionName
Pointer to a Unicode string containing the name of the session. Use only if a Unicode DirectPlay interface (IDirectPlay3 Interface) is being used.
lpszSessionNameA
Pointer to an ANSI string containing the name of the session. Use only if an ANSI DirectPlay interface (IDirectPlay3A) is being used.
lpszPassword
Pointer to a Unicode string containing the password used to join the session for participation. Use only if a Unicode DirectPlay interface (IDirectPlay3 Interface) is being used.
lpszPasswordA
Pointer to an ANSI string containing the password used to join the session for participation. Use only if an ANSI DirectPlay interface (IDirectPlay3A) is being used.
dwReserved1 and dwReserved2
Must be zero.
dwUser1, dwUser2, dwUser3, and dwUser4
Application-specific data for the session.
See Also

IDirectPlay3::EnumSessions, IDirectPlay3::GetSessionDesc, IDirectPlay3::Open, IDirectPlay3::SecureOpen, IDirectPlay3::SetSessionDesc, IDirectPlay3::CreatePlayer, DPPLAYER_SERVERPLAYER


System Messages

Some system message structures have changed for DirectPlay 5, with new data members added to the end. Make sure you only reference these new members if you are using the IDirectPlay3 interface.

The system message structures that have new members for DirectPlay 5 are:
Structure | New Members
DPMSG_CREATEPLAYERORGROUP | DPID dpIdParent
DWORD dwFlags
DPMSG_DESTROYPLAYERORGROUP | DPNAME dpnName
DPID dpIdParent
DWORD dwFlags


DPMSG_ADDGROUPTOGROUP

DirectPlay generates this message and sends it to every player when a group is added to a group.

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
Members
dwType
Identifies the message. This member is DPSYS_ADDGROUPTOGROUP.
dpIdParentGroup
ID of the group to which the group was added.
dpIdGroup
ID of the group that was added to the group.
See Also

IDirectPlay3::AddGroupToGroup


DPMSG_ADDPLAYERTOGROUP

Contains information for the DPSYS_ADDPLAYERTOGROUP system message. DirectPlay generates this message and sends it to every player when a player is added to a group.

The application can use IDirectPlay3::GetPlayerCaps, IDirectPlay3::GetPlayerName, and IDirectPlay3::GetPlayerData for information about the player involved int his message, or IDirectPlay3::GetGroupName and IDirectPlay3::GetGroupData to get more information about the group involved in this message.

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
Members
dwType
Identifies the message. This member is DPSYS_ADDPLAYERTOGROUP.
dpIdGroup
ID of the group to which the player was added.
dpIdPlayer
ID of the player that was added to the group.
See Also

IDirectPlay3::AddPlayerToGroup


DPMSG_CHAT

Contains information for the DPSYS_CHAT system message. The system message is generated for a local player receiving a chat message from another player.

typedef struct{
    DWORD dwType;
    DWORD dwFlags;
    DPID  idFromPlayer;
    DPID  idToPlayer;
    DPID  idToGroup;
    LPDPCHAT  lpChat;
} DPMSG_CHAT, FAR *LPDPMSG_CHAT;
Members
dwType
Identifies the message. This member has the value DPSYS_CHAT.
dwFlags
Not used.
idFromPlayer
The DPID of the player from whom the message originated. DPID_SERVERPLAYER indicates the message originated from the server.
idToPlayer
The DPID of the player to whom the message was directed. If this DPID is zero, then the message was sent to a group or broadcast to everyone.
idToGroup
The DPID of the group to whom the message was directed. If this DPID is zero and idToPlayer is also zero, then the message was broadcast to everyone.
lpChat
Pointer to a DPCHAT structure containing the content of the chat message received.
Remarks

Use the idFromPlayer value to determine who sent the message. The value of lpidFrom available through Receive will always be zero, so you must retrieve the value of idFromPlayer in the DPMSG_CHAT structure.

See Also

IDirectPlay3::SendChatMessage, DPCHAT, IDirectPlay3::Receive


DPMSG_CREATEPLAYERORGROUP

Contains information for the DPSYS_CREATEPLAYERORGROUP system message. The system sends this message when players and groups are created in a session.

DirectPlay generates this message and sends it to each player when a new player or group is created in a session.

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DWORD  dwCurrentPlayers;
    LPVOID lpData;
    DWORD  dwDataSize;
    DPNAME dpnName;
    DPID   dpIDParent;
    DWORD  dwFlags;
} DPMSG_CREATEPLAYERORGROUP, FAR *LPDPMSG_CREATEPLAYERORGROUP;
Members
dwType
Identifies the message. This member must be set to DPSYS_CREATEPLAYERORGROUP.
dwPlayerType
Indicates whether the message applies to a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP).
dpId
The ID of a player or group created.
dwCurrentPlayers
Current number of players in the session before this player was created.
lpData
Pointer to any application-specific remote data associated with this player or group. If this member is NULL, there is no remote data.
dwDataSize
Size of the data contained in the buffer referenced by lpData.
dpnName
Structure containing the name of the player or group.
dpIdParent
The ID of the parent group if this message is caused by a call to IDirectPlay3::CreateGroupInGroup; otherwise, the value is 0.
dwFlags
The player or group flags.
Remarks

The DirectPlay 5 version of this structure has two members added to the end, dpIdParent and dwFlags.

See Also

IDirectPlay3::CreateGroup, IDirectPlay3::CreatePlayer, IDirectPlay3::CreateGroupInGroup


DPMSG_DELETEGROUPFROMGROUP

DirectPlay generates this message and sends it to every player when a group is removed from a group. Note that this structure is identical to DPMSG_ADDGROUPTOGROUP.

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
typedef DPMSG_ADDGROUPTOGROUP  DPMSG_DELETEGROUPFROMGROUP;
Members
dwType
Identifies the message. This member is DPSYS_DELETEGROUPFROMGROUP.
dpIdParentGroup
ID of the group from which the group was removed.
dpIdGroup
ID of the group that was removed from the group.
See Also

IDirectPlay3::DeleteGroupFromGroup


DPMSG_DELETEPLAYERFROMGROUP

Contains information for the DPSYS_DELETEPLAYERFROMGROUP system message. DirectPlay generates this message and sends it to each local player on the computer when a player is deleted from a group.

For a description of the structure members, see the DPMSG_ADDPLAYERTOGROUP structure.

The application can use IDirectPlay3::GetPlayerCaps, IDirectPlay3::GetPlayerName, and IDirectPlay3::GetPlayerData for information about the player involved int his message, or IDirectPlay3::GetGroupName and IDirectPlay3::GetGroupData to get more information about the group involved in this message.

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
typedef DPMSG_ADDPLAYERTOGROUP DPMSG_DELETEPLAYERFROMGROUP;
Members
dwType
Identifies the message. This member is DPSYS_DELETEPLAYERFROMGROUP.
dpIdGroup
ID of the group from which the player was removed.
dpIdPlayer
ID of the player that was removed from the group.
See Also

IDirectPlay3::DeletePlayerFromGroup


DPMSG_DESTROYPLAYERORGROUP

Contains information for the DPSYS_DESTROYPLAYERORGROUP system message. DirectPlay generates this message and sends it to each player when a player or group is destroyed in a session.

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpLocalData;
    DWORD  dwLocalDataSize;
    LPVOID lpRemoteData;
    DWORD  dwRemoteDataSize;
    DPNAME dpnName;
    DPID   dpIdParent;
    DWORD  dwFlags;
} DPMSG_DESTROYPLAYERORGROUP, FAR *LPDPMSG_DESTROYPLAYERORGROUP;
Members
dwType
Identifies the message. This member is DPSYS_DESTROYPLAYERORGROUP.
dwPlayerType
Identifies whether the message applies to a player (DPPLAYERTYPE_PLAYER) or group (DPPLAYERTYPE_GROUP).
dpId
ID of a player or group that has been destroyed.
lpLocalData
Pointer to the local data associated with this player/group.
dwLocalDataSize
Size, in bytes, of the local data.
lpRemoteData
Pointer to the remote data associated with this player/group.
dwRemoteDataSize
Size, in bytes, of the remote data.
dpnName
Structure containing the name of the player/group.
dpIdParent
The ID of the parent group if the group being destroyed is a subgroup of the parent group (the group being destroyed was created by a call to IDirectPlay3::CreateGroupInGroup; otherwise, the value is 0.
dwFlags
The player or group flags.
Remarks

The DirectPlay 5 version of this structure has three members added to the end, dpnName, dpIdParent and dwFlags.

See Also

IDirectPlay3::DestroyGroup, IDirectPlay3::DestroyPlayer


DPMSG_GENERIC

This structure is provided for message processing.

typedef struct{
    DWORD dwType;
} DPMSG_GENERIC, FAR *LPDPMSG_GENERIC;
Members
dwType
Identifies the system message type.
Remarks

When a system message is received (that is, the value pointed to by the lpidFrom parameter equals DPID_SYSMSG), first cast the unknown message data to the DPMSG_GENERIC type, and then perform further processing based on the value of dwType. After the message type has been determined, the message can cast to one of the known types of system messages for further processing.


DPMSG_HOST

When the current session host exits the session, this message is sent to all the players on the computer that inherits the host duties.

typedef DPMSG_GENERIC    DPMSG_HOST;
typedef DPMSG_HOST  FAR *LPDPMSG_HOST;


DPMSG_SECUREMESSAGE

DirectPlay generates this message when it receives a signed or encrypted message from another player.

typedef struct {
    DWORD   dwType;
    DWORD   dwFlags;
    DPID    dpIdFrom;
    LPVOID  lpData;
    DWORD   dwDataSize;
} DPMSG_SECUREMESSAGE, FAR *LPDPMSG_SECUREMESSAGE;
Members
dwType
Identifies the system message type. This is DPSYS_SECUREMESSAGE.
dwFlags
Flags indicating how the message was secured by the sender. One of the following values:
DPSEND_SIGNED - the message was signed by the sender and the signature was successfully verified.
DPSEND_ENCRYPTED - the messages was encrypted by the sender and successfully decrypted.
dpIdFrom
The DPID of the player that sent the secure message.
lpData
Pointer to a buffer containing the fully verified message.
dwDataSize
Size of the buffer containing the message.
See Also

IDirectPlay3::Send


DPMSG_SESSIONLOST

This message is generated by DirectPlay when the connection to all the other players in the session is lost. After the session is lost, messages cannot be sent to remote players, but all data at the time the session was lost is still available. Your applications should try to recover gracefully and exit if this message is received.

typedef DPMSG_GENERIC    DPMSG_SESSIONLOST;
typedef DPMSG_SESSIONLOST  FAR  *LPDPMSG_SESSIONLOST;


DPMSG_SETPLAYERORGROUPDATA

Contains information for the DPSYS_SETPLAYERORGROUPDATA system message. DirectPlay generates this message and sends it to each player when the remote data of a player or group changes. This message will not be generated if the DPSESSION_ NODATAMESSAGES flag is specified in the session description.

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpData;
    DWORD  dwDataSize;
} DPMSG_SETPLAYERORGROUPDATA, FAR *LPDPMSG_SETPLAYERORGROUPDATA;
Members
dwType
Identifies the message. This member is always DPSYS_SETPLAYERORGROUPDATA.
dwPlayerType
Identifies whether the message applies to a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP).
dpId
ID of the player or group whose data changed.
lpData
Pointer to an application-specific block of data.
dwDataSize
Size of the data contained in the buffer referenced by lpData.
Remarks

It is not necessary for the application to save the data from this message because it can be retrieved at any time using IDirectPlay3::GetPlayerData or IDirectPlay3::GetGroupData.

See Also

IDirectPlay3::GetPlayerData, IDirectPlay3::GetGroupData, IDirectPlay3::SetPlayerData, IDirectPlay3::SetGroupData


DPMSG_SETPLAYERORGROUPNAME

Contains information for the DPSYS_SETPLAYERORGROUPNAME system message. DirectPlay generates this message and sends it to each local player on the computer when the name of a player or group changes. This message will not be generated if the DPSESSION_ NODATAMESSAGES flag is specified in the session description.

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DPNAME dpnName;
} DPMSG_SETPLAYERORGROUPNAME, FAR *LPDPMSG_SETPLAYERORGROUPNAME;
Members
dwType
Identifies the message. This member is always DPSYS_SETPLAYERORGROUPNAME.
dwPlayerType
Identifies whether the message applies to a player (DPPLAYERTYPE_PLAYER) or a group (DPPLAYERTYPE_GROUP).
dpId
ID of the player or group whose name changed.
dpnName
Structure containing the new name information for the player or group.
Remarks

It is not necessary for the application to save the dpnName from this message because it can be retrieved at any time using IDirectPlay3::GetPlayerName or IDirectPlay3::GetGroupName.

See Also

IDirectPlay3::GetPlayerName, IDirectPlay3::GetGroupName, IDirectPlay3::SetPlayerName, IDirectPlay3::SetGroupName


DPMSG_SETSESSIONDESC

Contains information for the DPSYS_SETSESSIONDESC system message. Every player will receive this system message when the session description changes.

This messages will not be generated if the DPSESSION_NODATAMESSAGES flag is specified in the session description.

typedef struct
{
    DWORD           dwType;
    DPSESSIONDESC2  dpDesc;
} DPMSG_SETSESSIONDESC, FAR *LPDPMSG_SETSESSIONDESC;
Members
dwType
Identifies the message. This member is always DPSYS_SETSESSIONDESC.
dpDesc
Pointer to a DPSESSIONDESC2 structure containing the updated session description.
See Also

IDirectPlay3::GetSessionDesc, IDirectPlay3::SetSessionDesc


DPMSG_STARTSESSION

Contains information for the DPSYS_STARTSESSION system message. The lobby server sends this message to each player in a group when it is time for that player to join an application session.

typedef struct {
   DWORD            dwType;
   LPDPLCONNECTION  lpConn;
} DPMSG_STARTSESSION, FAR *LPDPMSG_STARTSESSION;
Members
dwType
Identifies the message. This member is always DPSYS_STARTSESSION.
lpConn
Pointer to a DPLCONNECTION structure that contains all the information needed to launch an application into a session. This structure can be passed into IDirectPlayLobby2::RunApplication (if an external application is to be launched) or passed into IDirectPlayLobby2::SetConnectionSettings and then followed by a call to IDirectPlayLobby2::Connect (to connect the current application to the session).
Remarks

Upon receipt of this message by a stand-alone lobby client, the client must launch the application by calling the IDirectPlayLobby2::RunApplication method with the DPLCONNECTION structure.

Upon receipt of this message by an application with an internal lobby, the application must set the connection settings by calling IDirectPlayLobby2::SetConnectionSettings and then connect to the session using the IDirectPlayLobby2::Connect method.

See Also

IDirectPlay3::StartSession, IDirectPlayLobby2::RunApplication, IDirectPlayLobby2::SetConnectionSettings, IDirectPlayLobby2::Connect


Standard Lobby Messages

To determine whether the lobby that launched your application supports standard lobby messages, it is necessary to send the lobby an initial DPLMSG_GETPROPERTY request and see whether it responds or not. The property that should be requested is DPLPROPERTY_MessagesSupported.

If the lobby responds with TRUE, then you can assume that it will respond to all further messages. If it responds with FALSE or doesn't respond at all within a specified timeout, then you can assume that messages are not supported.

If the application supports spectator players, then the application should also request DPLPROPERTY_PlayerGuid before creating players to determine if they should be created as spectators or not.


DPLMSG_GENERIC

Generic structure of system messages passed between the lobby client and an application.

typedef struct {
    DWORD dwType;
} DPL_GENERIC, FAR *LPDPLMSG_GENERIC;
Members
dwType
Identifies what type of system message has been received.
DPLSYS_APPTERMINATED
Indicates the application started by IDirectPlayLobby2::RunApplication has terminated.
DPLSYS_CONNECTIONSETTINGSREAD
Indicates the application started by the IDirectPlayLobby2::RunApplication method has read the connection settings.
DPLSYS_DPLAYCONNECTFAILED
Indicates the application started by IDirectPlayLobby2::RunApplication failed to connect to a session.
DPLSYS_DPLAYCONNECTSUCCEEDED
Indicates the application started by IDirectPlayLobby2::RunApplication has created a session and is ready for other applications to join or has successfully joined a session.


DPLMSG_GETPROPERTY

Message sent by an application to the lobby to request the current value of a property. These properties can be information such as the ranking of a player, a bitmap representing a player, or initial configuration information for the game or players that was done inside the lobby.

typedef struct {
    DWORD   dwType;
    DWORD   dwRequestID;
    GUID    guidPlayer;
    GUID    guidPropertyTag;
} DPLMSG_GETPROPERTY, FAR *LPDPLMSG_GETPROPERTY;
Members
dwType
Identifies the message. This value is DPLSYS_ GETPROPERTY.
dwRequestID
An application generated ID to identify the request. When the lobby responds, it will be tagged with this request ID. The application can use the request ID to match responses to pending requests.
guidPlayer
GUID identifying the player that this property applies to (if applicable). If the property is not player-specific, this member should be set to GUID_NULL. The GUID for the player or players created by this application can be obtained from the lobby by requesting the DPLPROPERTY_PlayerGuid property.
guidPropertyTag
A GUID identifying the property that is being requested. The property can one of the predefined ones listed in the section DirectPlay Defined Properties or the application/lobby can define its own GUIDs for additional properties.
Remarks

Each property is identified by a GUID (defined by the application developer or the lobby developer). When a request for a property is made, the lobby responds with a DPLMSG_GETPROPERTYRESPONSE message. Even if the lobby cannot supply the information, it should respond with an error indicating the information is unavailable.

The application should not block waiting for a response and should have a way to time-out pending requests that haven't been fulfilled.

See Also

DPLMSG_GETPROPERTYRESPONSE


DPLMSG_GETPROPERTYRESPONSE

Message sent by a lobby to an application in response to a DPLMSG_GETPROPERTY message. The request that is being filled is identified by the dwRequestID parameter.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_GETPROPERTYRESPONSE, FAR *LPDPLMSG_GETPROPERTYRESPONSE;
Members
dwType
Identifies the message. This value is DPLSYS_ GETPROPERTYRESPONSE.
dwRequestID
The ID that identifies the DPLMSG_GETPROPERTY message that this message is in response to.
guidPlayer
GUID identifying the player that this property applies to (if applicable). If the property is not player-specific, this member will be set to GUID_NULL. This will be the same as the GUID from the DPLMSG_GETPROPERTY message.
guidPropertyTag
A GUID identifying the property that is being requested. This will be the same as the GUID from the DPLMSG_GETPROPERTY message.
hr
Return code for the get property request. One of the following values:
DP_OK - successfully returned the property.
DPERR_UNKNOWN - the requested property is unknown to the lobby.
DPERR_UNAVAILABLE - the requested property is unavailable.
dwDataSize
The size, in bytes, of the property data.
dwPropertyData
A variable-size buffer that contains the property data. The property tag will define how to interpret this data.
Remarks

A lobby must either respond to all DPLMSG_GETPROPERTY requests or none of them.

When constructing this message, the lobby needs to allocate enough memory to hold the DPLMSG_GETPROPERTYRESPONSE structure and the complete property data. For example, if the property data requires 52 bytes, the lobby will allocate (sizeof(DPLMSG_GETPROPERTYRESPONSE) + 52) bytes and assign it to a DPLMSG_GETPROPERTYRESPONSE pointer.

See Also

DPLMSG_GETPROPERTY


DPLMSG_SETPROPERTY

Message sent by an application to the lobby to inform it that a property of a specific player or a property of the session has changed. These properties can range from the score or status of a player to the current level of a game or the current status of the session.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_SETPROPERTY, FAR *LPDPLMSG_SETPROPERTY;
Members
dwType
Identifies the message. This value is DPLSYS_ SETPROPERTY.
dwRequestID
A nonzero request ID supplied by the application if it would like confirmation that the data was recognized and set appropriately. If no confirmation is required, set this to DPL_NOCONFIRMATION.
guidPlayer
GUID identifying the player that this property applies to (if applicable). If the property is not player-specific, this member should be set to GUID_NULL. The GUID for the player or players created by this application can be obtained from the lobby by requesting the DPLPROPERTY_PlayerGuid property.
guidPropertyTag
A GUID identifying the property that is being set. The property can be one of the predefined GUIDs listed in the section DirectPlay Defined Properties or the application/lobby can define its own GUIDs for additional properties.
dwDataSize
The size, in bytes, of the property data.
dwPropertyData
A variable size buffer that contains the property data. The property tag will define how to interpret this data.
Remarks

Each property is identified by a GUID (defined by the application developer or the lobby developer), and it is the responsibility of the lobby to maintain a mapping of property GUIDs of the various applications to their descriptions and data types. The lobby server can choose to act on the information or ignore it.

When constructing this message, the application needs to allocate enough memory to hold the DPLMSG_ SETPROPERTY structure and the complete property data. For example, if the property data requires 52 bytes, the application will allocate (sizeof(DPLMSG_SETPROPERTY) + 52) bytes and assign it to a LPDPLMSG_SETPROPERTY pointer.

See Also

DPLMSG_SETPROPERTYRESPONSE


DPLMSG_SETPROPERTYRESPONSE

Message sent by a lobby to an application as confirmation of a DPLMSG_SETPROPERTY message. The message that is being confirmed is identified by the dwRequestID parameter.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
} DPLMSG_SETPROPERTYRESPONSE, FAR *LPDPLMSG_SETPROPERTYRESPONSE;
Members
dwType
Identifies the message. This value is DPLSYS_ SETPROPERTYRESPONSE.
dwRequestID
The ID that identifies the DPLMSG_SETPROPERTY message being confirmed.
guidPlayer
GUID identifying the player that this property was set for (if applicable). If the property is not player-specific, this member is GUID_NULL. This must be the same as the GUID from the DPLMSG_SETPROPERTY message.
guidPropertyTag
A GUID identifying the property that was set. This must be the same as the GUID from the DPLMSG_SETPROPERTY message.
hr
Result of the confirmation. One of the following values:
DP_OK - the property was set correctly.
DPERR_ACCESSDENIED - an attempt was made to set a property the lobby will not allow to be changed.
DPERR_UNKNOWN - the property is unknown to the lobby.
See Also

DPLMSG_SETPROPERTY


DirectPlay Defined Properties

This section describes the defined properties that can be set and retrieved by applications from a lobby.

When a DPLMSG_GETPROPERTYRESPONSE message is received, its guidPropertyTag field identifies the property and its dwPropertyData field contains the property information. To extract this information, cast the dwPropertyData field to the appropriate value. For example, the following routine retrieves the DPLDATA_PLAYERGUID structure from the given message:

BOOL GetPlayerGuid(LPDPLMSG_GETPROPERTYRESPONSE  lpPropertyResponseMsg,
                       LPDPLDATA_PLAYERGUID lpPlayerGuid)
{
   if (IsEqualGUID(lpPropertyResponseMsg->guidPropertyTag, DPLPROPERTY_PlayerGuid))
   {
      *lpPlayerGuid = *((LPDPLDATA_PLAYERGUID) lpPropertyResponseMsg->dwPropertyData);
      return (TRUE);
   }
   else
   {
      return (FALSE);
   }
}

See the following descriptions of defined properties.

  • DPLPROPERTY_LobbyGuid
  • DPLPROPERTY_MessagesSupported
  • DPLPROPERTY_PlayerGuid
  • DPLPROPERTY_PlayerScore


DPLPROPERTY_LobbyGuid

A GUID used to identify the lobby software. If an application was designed to interoperate with a specific lobby using custom messages, this property can be used to identify the lobby.

However, an application should attempt to use standard messages whenever possible to be able to interoperate with as many lobbies as possible.

For this property, the dwPropertyData field of the DPLMSG_GETPROPERTYRESPONSE structure will contain the following:

GUID  guidLobby;


DPLPROPERTY_MessagesSupported

A boolean value indicating whether the lobby supports standard messages or not. An application can request this property from the lobby to determine if it supports standard messages. If the lobby does not respond to this message or if it responds with FALSE, then the application should assume that it does not support standard lobby messages and not send any further messages. If the lobby returns TRUE, then the application should freely send standard messages to the lobby and query for further properties of the lobby.

For this property, the dwPropertyData field of the DPLMSG_GETPROPERTYRESPONSE structure will contain the following:

BOOL  fMessagesSupported;


DPLPROPERTY_PlayerGuid

A GUID used to uniquely identify the application's local players. Any further DPLMSG_SETPROPERTY or DPLMSG_GETPROPERTY messages that require a player GUID will need to use this value to communicate with the lobby.

An application can manipulate properties for remote players on another computer. The application only needs to obtain the player GUID from the remote player (not from the lobby).

If an application supports spectator players, it should request this property before creating any players in order to determine what flags (if any) to use when creating the players; for example, DPPLAYER_SPECTATOR and DPPLAYER_SERVERPLAYER.

For this property, the dwPropertyData field of the DPLMSG_GETPROPERTYRESPONSE structure will contain the following:

typedef struct {
    GUID  guidPlayer;
    DWORD dwPlayerFlags;
} DPLDATA_PLAYERGUID, FAR *LPDPLDATA_PLAYERGUID;


DPLPROPERTY_PlayerScore

A generic structure that can be used by an application to report a composite score value to the lobby. The guidPlayer GUID of the player the score applies to must be provided when setting or getting this property. This structure can handle an arbitrary list of long integer values that collectively represent the score of a player. The application must allocate enough memory to hold all the scores. For example, if the score was passed as N integers, the application must allocate ( sizeof(DPLDATA_PLAYERSCORE) + N*sizeof(LONG) ) bytes and cast the pointer to LPDPLDATA_PLAYERSCORE.

For this property, the dwPropertyData field of the DPLMSG_GETPROPERTYRESPONSE structure will contain the following:

typedef struct {
    DWORD   dwScoreCount;
    LONG    Score[1];
} DPLDATA_PLAYERSCORE, FAR *LPDPLDATA_PLAYERSCORE;


Return Values

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all IDirectPlay3 Interface and IDirectPlayLobby2 Interface methods. For a list of the error values each method can return, see the individual method descriptions.

CLASS_E_NOAGGREGATION
A non-NULL value was passed for the pUnkOuter parameter in DirectPlayCreate, DirectPlayLobbyCreate, or IDirectPlayLobby2::Connect.
DP_OK
The request completed successfully.
DPERR_ACCESSDENIED
The session is full or an incorrect password was supplied.
DPERR_ACTIVEPLAYERS
The requested operation cannot be performed because there are existing active players.
DPERR_ALREADYINITIALIZED
This object is already initialized.
DPERR_APPNOTSTARTED
The application has not been started yet.
DPERR_AUTHENTICATIONFAILED
The password or credentials supplied could not be authenticated.
DPERR_BUFFERTOOLARGE
The data buffer is too large to store.
DPERR_BUSY
A message cannot be sent because the transmission medium is busy.
DPERR_BUFFERTOOSMALL
The supplied buffer is not large enough to contain the requested data.
DPERR_CANTADDPLAYER
The player cannot be added to the session.
DPERR_CANTCREATEGROUP
A new group cannot be created.
DPERR_CANTCREATEPLAYER
A new player cannot be created.
DPERR_CANTCREATEPROCESS
Cannot start the application.
DPERR_CANTCREATESESSION
A new session cannot be created.
DPERR_CANTLOADCAPI
No credentials were supplied and the CryptoAPI package (CAPI) to use for cryptography services cannot be loaded.
DPERR_CANTLOADSECURITYPACKAGE
The software security package cannot be loaded.
DPERR_CANTLOADSSPI
No credentials were supplied and the software security package (SSPI) that will prompt for credentials cannot be loaded.
DPERR_CAPSNOTAVAILABLEYET
The capabilities of the DirectPlay object have not been determined yet. This error will occur if the DirectPlay object is implemented on a connectivity solution that requires polling to determine available bandwidth and latency.
DPERR_CONNECTING
The method is in the process of connecting to the network. The application should keep calling the method until it returns DP_OK, indicating successful completion, or it returns a different error.
DPERR_ENCRYPTIONFAILED
The requested information could not be digitally encrypted. Encryption is used for message privacy. This error is only relevant in a secure session.
DPERR_EXCEPTION
An exception occurred when processing the request.
DPERR_GENERIC
An undefined error condition occurred.
DPERR_INVALIDCREDENTIALS
The credentials supplied (as to IDirectPlay3::SecureOpen) were not valid.
DPERR_INVALIDFLAGS
The flags passed to this method are invalid.
DPERR_INVALIDGROUP
The group ID is not recognized as a valid group ID for this game session.
DPERR_INVALIDINTERFACE
The interface parameter is invalid.
DPERR_INVALIDOBJECT
The DirectPlay object pointer is invalid.
DPERR_INVALIDPARAMS
One or more of the parameters passed to the method are invalid.
DPERR_INVALIDPASSWORD
An invalid password was supplied when attempting to join a session that requires a password.
DPERR_INVALIDPLAYER
The player ID is not recognized as a valid player ID for this game session.
DPERR_LOGONDENIED
The session could not be opened because credentials are required and either no credentials were supplied or the credentials were invalid.
DPERR_NOCAPS
The communication link that DirectPlay is attempting to use is not capable of this function.
DPERR_NOCONNECTION
No communication link was established.
DPERR_NOINTERFACE
The interface is not supported.
DPERR_NOMESSAGES
There are no messages in the receive queue.
DPERR_NONAMESERVERFOUND
No name server (host) could be found or created. A host must exist to create a player.
DPERR_NONEWPLAYERS
The session is not accepting any new players.
DPERR_NOPLAYERS
There are no active players in the session.
DPERR_NOSESSIONS
There are no existing sessions for this game.
DPERR_NOTLOBBIED
Returned by the IDirectPlayLobby2::Connect method if the application was not started by using the IDirectPlayLobby2::RunApplication method or if there is no DPLCONNECTION structure currently initialized for this DirectPlayLobby object.
DPERR_NOTLOGGEDIN
An action cannot be performed because a player or client application is not logged in. Returned by the IDirectPlay3::Send method when the client application tries to send a secure message without being logged in.
DPERR_OUTOFMEMORY
There is insufficient memory to perform the requested operation.
DPERR_PLAYERLOST
A player has lost the connection to the session.
DPERR_SENDTOOBIG
The message being sent by the IDirectPlay3::Send method is too large.
DPERR_SESSIONLOST
The connection to the session has been lost.
DPERR_SIGNFAILED
The requested information could not be digitally signed. Digital signatures are used to establish the authenticity of messages.
DPERR_TIMEOUT
The operation could not be completed in the specified time.
DPERR_UNAVAILABLE
The requested function is not available at this time.
DPERR_UNINITIALIZED
The requested object has not been initialized.
DPERR_UNKNOWNAPPLICATION
An unknown application was specified.
DPERR_UNSUPPORTED
The function is not available in this implementation. Returned from IDirectPlay3::GetGroupConnectionSettings and IDirectPlay3::SetGroupConnectionSettings if they are called from a session that is not a lobby session.
DPERR_USERCANCEL
Can be returned in two ways. 1) The user canceled the connection process during a call to the IDirectPlay3::Open method. 2) The user clicked Cancel in one of the DirectPlay service provider dialog boxes during a call to IDirectPlay3::EnumSessions.


Further Reading

Accessing COM
A section in the Microsoft® DirectX® 5 documentation, under the heading "Introducing DirectX 5," within the topic "DirectX and the Component Object Model." This topic describes how COM implements DirectX objects and interfaces.
IUnknown Interface
All COM interfaces are derived from the IUnknown interface. This interface provides control of the object's lifetime and the ability to navigate multiple interfaces. IUnknown has three methods: AddRef, which increments the object's reference count by 1 when an interface or another application binds itself to the object; QueryInterface, which queries the object about the features it supports by requesting pointers to a specific interface; and Release, which decrements the object's reference count by 1. When the count reaches 0, the object is deallocated. See also AddRef and QueryInterface
IUnknown::AddRef and IUnknown::Release
These IUnknown methods maintain an object's reference count. For example, if you create a DirectPlay object (with CoCreateInstance, for example), the object's reference count is set to 1. Every time a function returns a pointer to an interface for that object, the function must call AddRef through that pointer to increment the reference count. You must match each AddRef call with a call to Release. Before the pointer can be destroyed, you must call Release through that pointer. After an object's reference count reaches 0, the object is destroyed and all interfaces to it become invalid.
IUnknown::QueryInterface
This IUnknown method determines whether an object supports a specific interface. If an object supports the interface, QueryInterface returns a pointer to that interface. You then can use the methods contained in that interface to communicate with the object. If QueryInterface successfully returns a pointer to an interface, it implicitly calls AddRef to increment the reference count, so your application must call Release to decrement the reference count before destroying the pointer to the interface.


DirectPlay Glossary

This glossary primarily defines terms related to Microsoft® DirectPlay®. Entries are grouped by letter in alphabetical order. See the Microsoft Windows® NT® or Microsoft Windows® 95 online Help for additional information.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


C

client/server session
A DirectPlay session in which only the server stores the session's complete state, and each client has only a subset of the session's state. Each client has only the information that is relevant to that computer and receives that information from the server. When one computer changes something, it propagates the change to the server. The server then determines which clients it must inform of the change. Also see peer-to-peer session.


D

DirectPlay address
A data format that DirectPlay uses to pass addressing information between lobby servers, applications, DirectPlay, and service providers. A DirectPlay address is a sequence of variable-length data chunks tagged with a globally unique identifier (GUID) that supplies all the address information needed by DirectPlay. Examples of address information are: the network address of a server, the network address of a player, the e-mail name of a player, and the network address of a session.
DirectPlay defined property
A property that can be set and retrieved by applications from a lobby. When a DPLMSG_GETPROPERTYRESPONSE message is received, its guidPropertyTag field identifies the property, and its dwPropertyData field contains the property information.


G

group
A logical collection of players. DirectPlay supports groups within a session. By creating a group of players, an application can send a single message to the group, and all the players in the group will receive the message. A group is the means by which a network's multicast capabilities are exposed to the application.
Groups can be used as a general means to organize players in a session. A player can belong to more than one group. DirectPlay provides methods for administering groups and their membership.


H

host
In DirectPlay, a virtual player whose ID is DPID_SYSMSG. The host manages system messages and messages sent to all players in a session.


I

IPX service provider
A service provider that uses Winsock to communicate over a local area network (LAN) using the Internet Packet Exchange (IPX) protocol. The service provider only supports nonguaranteed messaging. A single computer can host only one DirectPlay session using IPX.


L

latency
The time in milliseconds it takes for a small packet to reach a given destination. You can use IDirectPlay3::GetCaps to retrieve the latency of the service provider. The dwlatency member of the DPCAPS structure represents the service provider's estimate of typical net latency; for example, the latency on the Internet is typically about 500 ms.
lobby client
An application that has joined a lobby session. Joining a lobby session gives the client application access to all the information on the lobby server, and enables the user to interact with other users on the lobby server. The lobby client uses lobby management routines to locate and join sessions.
lobby-aware application
An application that, at a minimum, supports being launched from a lobby.
lobby provider
A client component (DLL) supplied by the developer of a lobby server. It implements communications functions with the lobby server as requested by DirectPlay. The DirectX Software Development Kit (SDK) installs a lobby provider for use with the test lobby server (LSERVER.EXE) that is included with the SDK.
lobby server
A common place on a network that (at a minimum) tracks DirectPlay application sessions in progress and also tracks users that are connected to the server. The lobby server coordinates all the information about the users connected to a specific application. Users can navigate around the lobby server to find areas of interest. At any location on the lobby server, the user can chat with other users, join sessions that are in progress, or gather a group of players to start a new session.
lobby session
A connection to a lobby server where clients and the server have not been specifically written to interoperate.


P

peer-to-peer session
A DirectPlay session in which the session's complete state is replicated on all the computers in the session. The session description data—the list of players and groups, and the names and remote data associated with each session — are duplicated on every computer. When one computer changes something, it is immediately propagated to all the other computers. This is DirectPlay's default mode of communications. Also see client/server session.


S

secure session
A session in which all the users have been authenticated against a database of known users before being allowed to join a session. In a secure session, all DirectPlay system messages are digitally signed to verify the identity of the sender. Certain system messages that carry sensitive information are encrypted. System messages that originate from one player and need to be broadcast to all the other players in the session are first sent to the server. The server then puts its signature on the message and forwards the message to all the other computers in the session. Player to player messages are not signed by default and are not routed through the server.
service provider
A dynamic-link library (DLL) used by DirectPlay to communicate over a network. The service provider contains all the network-specific code required to send and receive messages. Online services and network operators can supply service providers to use specialized hardware, protocols, communications media, and network resources. Microsoft includes four generic service providers with DirectPlay: head-to-head modem (TAPI), serial connection, Internet TCP/IP (using Winsock), and IPX (also using Winsock).
session
An instance of several applications on remote machines communicating with each other. Before an application can start communicating with other computers, it must be part of a session. An application can enumerate all the existing sessions on a network and join one of them, or it can create a new session and wait for other computers to join it. Once the application is part of a session, it can create a player and exchange messages with all the other players in the session.
system message
A message from the player ID DPID_SYSMSG. All system messages begin with a double-word value. You can cast the buffer returned by the IDirectPlay3::Receive method to a generic message (DPMSG_GENERIC) and switch on this DWORD value. The DWORD value is equal to one of the messages with a DPSYS_ prefix, for example, DPSYS_SESSIONLOST. After the application has determined which system message it is, the buffer should be cast to the appropriate structure (beginning with the DPMSG_ prefix), for example, DPMSG_SESSIONLOST, to read the data.


T

TCP/IP service provider
A service provider that uses Winsock to communicate over the Internet or local area network (LAN) using the TCP/IP protocol. It uses UDP (User Datagram Protocol) packets for nonguaranteed messaging and TCP for guaranteed messaging. A single computer can host multiple DirectPlay sessions using TCP/IP.


U

user authentication
Authentication is used to verify that the user is allowed access to the server by virtue of having been added to the membership database by the administrator of the server. Only users that are part of the membership database are permitted to join the session. User authentication should not be confused with password protection of a session. A password can be added to a session so that only those members who know the password can join a particular session. Authentication requires a server that supports authentication, while any computer can put a password on a session.


Microsoft Direct3D Retained Mode SDK

Welcome to the Microsoft® Direct3D® Retained Mode Software Development Kit. With Direct3D Retained Mode, you can create a 3-D graphics environment on a personal computer and manipulate it in real time.

Click here to go to the download page for Direct3D Retained Mode.

Last Updated: March 27, 1998

About Retained Mode
Provides a brief description of Direct3D Retained Mode.
Getting Started
Describes some of the technical background you need to manipulate points in three dimensions. Includes a general discussion of coordinate systems, transformations, polygons, triangle strips and fans, vectors, vertices, and quaternions.
Direct3D Retained Mode Architecture
Describes Direct3D Retained Mode objects and the interfaces they support. Also provides tips on reference counting and z-buffers.
Direct3D Retained Mode Interface Overviews
Provides an overview of each Direct3D Retained Mode interface and information on use and things to be aware of.
Direct3D Retained Mode Tutorial
Provides a walk-through of the code in a simple Retained Mode application.
Direct3D Retained Mode Reference
Provides detailed information about the interface methods, functions, and callbacks with syntax, parameter descriptions, flag descriptions, and comments about use. Also describes the members of Direct3D structures, enumerated types, other defined types, and the possible error values that can be returned.
DirectX File Format
Describes the file format of DirectX (.x) files, which provide support for reading predefined objects into applications and writing mesh information constructed by applications in real time. Also includes information about templates, examples, the binary format of the files, and the Conv3ds.exe utility, which converts 3-D models from other packages into .x files.
Direct3D Retained Mode Glossary
Defines basic graphics terms used in Direct3D Retained Mode.

Note: The icon external link indicates that the link takes you to a URL that is outside the microsoft.com site; you can return to the Direct3D Retained Mode site by using the Back button. Most of these external links point to servers that are not under Microsoft's control. Please read Microsoft's official statement regarding other servers.


About Retained Mode

This section describes Microsoft® Direct3D® Retained Mode, the Microsoft solution for real-time 3-D graphics on the personal computer. If you need to create a 3-D environment and manipulate it in real time, you should use the Direct3D Retained Mode API.

Direct3D is tightly integrated with Microsoft DirectDraw®. A DirectDraw object encapsulates both the DirectDraw and Direct3D Retained Mode states—your application can use the IDirectDraw::QueryInterface method to retrieve an IDirect3D interface to a DirectDraw object.

If you have written code before that uses 3-D graphics, many of the concepts underlying Direct3D Retained Mode will be familiar to you. If, however, you are new to 3-D programming, you should pay close attention to Direct3D Retained Mode Architecture, and you should read Getting Started. Whether you are an experienced 3-D programmer or just beginning, you should look carefully at the sample code included with this Software Development Kit; it illustrates how to put Direct3D Retained Mode to work in real-world applications.

For an introduction to programming with Direct3D Retained Mode, see Direct3D Retained Mode Tutorial.


Getting Started

The following topics describe some of the technical concepts you need to understand before you write programs that incorporate 3-D graphics. In these sections, you will find a general discussion of coordinate systems and transformations. This is not a discussion of broad architectural details, such as setting up models, lights, and viewing parameters. For more information about these topics, see Direct3D Retained Mode Architecture.

If you are already experienced in producing 3-D graphics, simply scan the following topics for information that is unique to Microsoft® Direct3D® Retained Mode:

  • 3-D Coordinate Systems
  • 3-D Transformations
  • Polygons
  • Triangle Strips and Fans
  • Vectors, Vertices, and Quaternions
  • Floating-Point Precision

3-D Coordinate Systems

There are two varieties of Cartesian coordinate systems in 3-D graphics: left-handed and right-handed. In both coordinate systems, the positive x-axis points to the right and the positive y-axis points up. You can remember which direction the positive z-axis points by pointing the fingers of either your left or right hand in the positive x-direction and curling them into the positive y-direction. The direction your thumb points, either toward or away from you, is the direction the positive z-axis points for that coordinate system.

This section describes the Direct3D coordinate system and coordinate types that your application can use.

  • Direct3D Coordinate System
  • U- and V-Coordinates

Direct3D Coordinate System

Direct3D uses the left-handed coordinate system. This means the positive z-axis points away from the viewer, as shown in the following illustration:

Direct3D coordinate system

In a left-handed coordinate system, rotations occur clockwise around any axis that is pointed at the viewer.

If you need to work in a right-handed coordinate system—for example, if you are porting an application that relies on right-handedness—you can do so by making two simple changes to the data passed to Direct3D.

  • Flip the order of triangle vertices so that the system traverses them clockwise from the front. In other words, if the vertices are v0, v1, v2, pass them to Direct3D as v0, v2, v1.
  • Scale the projection matrix by –1 in the z-direction. To do this, flip the signs of the _13, _23, _33, and _43 members of the D3DMATRIX structure.

U- and V-Coordinates

Direct3D also uses texture coordinates. These coordinates (u and v) are used when mapping textures onto an object. The v-vector describes the direction or orientation of the texture and lies along the z-axis. The u-vector (or the up vector) typically lies along the y-axis, with its origin at [0,0,0]. For more information about u- and v-coordinates, see IDirect3DRMWrap Interface.

3-D Transformations

In programs that work with 3-D graphics, you can use geometrical transformations to:

  • Express the location of an object relative to another object.
  • Rotate, shear, and size objects.
  • Change viewing positions, directions, and perspective.

You can transform any point into another point by using a 4×4 matrix. In the following example, a matrix is used to reinterpret the point (x, y, z), producing the new point (x', y', z'):

Transformation of a point with a 4×4 matrix

You perform the following operations on (x, y, z) and the matrix to produce the point (x', y', z'):

Operations within the matrix transformation

The most common transformations are translation, rotation, and scaling. You can combine the matrices that produce these effects into a single matrix to calculate several transformations at once. For example, you can build a single matrix to translate and rotate a series of points.

Matrices are specified in row order. For example, the following matrix could be represented by an array:

Sample matrix that is represented by the array below

The array for this matrix would look like the following:

D3DMATRIX scale = {
    D3DVAL(s),    0,            0,            0,
    0,            D3DVAL(s),    D3DVAL(t),    0,
    0,            0,            D3DVAL(s),    D3DVAL(v),
    0,            0,            0,            D3DVAL(1)
};

This section describes the 3-D transformations available to your applications through Direct3D.

  • Translation
  • Rotation
  • Scaling

Other parts of this documentation also discuss transformations. You can find a general discussion of transformations in the section devoted to viewports in Retained Mode, Transformations. For a discussion of transformations in frames, see Transformations. Although each of these sections discusses Retained Mode API, the architecture and mathematics of the transformations apply to both Retained Mode and Immediate Mode.

Translation

The following transformation translates the point (x, y, z) to a new point (x', y', z'):

Matrix that translates a point

Rotation

The transformations described in this section are for left-handed coordinate systems, and so they may be different from transformation matrices you have seen elsewhere.

The following transformation rotates the point (x, y, z) around the x-axis, producing a new point (x', y', z'):

Matrix that rotates a point around the x-axis

The following transformation rotates the point around the y-axis:

Matrix that rotates a point around the y-axis

The following transformation rotates the point around the z-axis:

Matrix that rotates a point around the z-axis

Note that in these example matrices, the Greek letter theta stands for the angle of rotation, specified in radians. Angles are measured clockwise when looking along the rotation axis toward the origin.

Scaling

The following transformation scales the point (x, y, z) by arbitrary values in the x-, y-, and z-directions to a new point (x', y', z'):

Matrix that scales a point

Polygons

Three-dimensional objects in Direct3D are made up of meshes. A mesh is a set of faces, each of which is described by a simple polygon. The fundamental polygon type is the triangle. Although Retained Mode applications can specify polygons with more than three vertices, the system translates these into triangles before the objects are rendered. Immediate Mode applications must use triangles.

This section describes how your applications can use Direct3D polygons.

  • Geometry Requirements
  • Face and Vertex Normals
  • Shade Modes
  • Interpolated Triangle Characteristics

Geometry Requirements

Triangles are the preferred polygon type because they are always convex, and they are always planar—two conditions that are required of polygons by the renderer. A polygon is convex if a line drawn between any two points of the polygon is also inside the polygon.

Diagram of concave and convex polygons

The three vertices of a triangle always describe a plane, but it is easy to accidentally create a nonplanar polygon by adding another vertex.

Diagram of nonplanar polygon

Face and Vertex Normals

Each face in a mesh has a perpendicular face normal vector whose direction is determined by the order in which the vertices are defined and by whether the coordinate system is right- or left-handed. If the normal vector of a face is oriented toward the viewer, that side of the face is its front. In Direct3D, only the front side of a face is visible, and a front face is one in which vertices are defined in clockwise order.

Diagram of a polygon face's vertices and normal vector

Direct3D applications do not need to specify face normals; the system calculates them automatically when they are needed. The system uses face normals in the flat shade mode. For Phong and Gouraud shade modes, and for controlling lighting and texturing effects, the system uses vertex normals.

Diagram of vertex normals and face normals

Shade Modes

In the flat shade mode, the system duplicates the color of one vertex across all the other faces of the primitive. In the Gouraud and Phong shade modes, vertex normals are used to give a smooth look to a polygonal object. In Gouraud shading, the color and intensity of adjacent vertices is interpolated across the space that separates them. In Phong shading, the system calculates the appropriate shade value for each pixel on a face.

Note Phong shading is not currently supported.

Most applications use Gouraud shading because it allows objects to appear smooth and is computationally efficient. However, Gouraud shading can miss details that Phong shading will not. For example, Gouraud and Phong shading would produce very different results as shown by the following illustration, in which a spotlight is completely contained within a face.

Diagram of a spotlight on a face for comparison of Gouraud and Phong shading

In this case, the Phong shade mode would calculate the value for each pixel and display the spotlight. The Gouraud shade mode, which interpolates between vertices, would miss the spotlight altogether; the face would be rendered as though the spotlight did not exist.

In the flat shade mode, the following pyramid would be displayed with a sharp edge between adjoining faces; the system would generate automatic face normals. In the Gouraud or Phong shade modes, however, shading values would be interpolated across the edge, and the final appearance would be of a curved surface.

A pyramid in the flat shade mode

If you want to use the Gouraud or Phong shade mode to display curved surfaces, and you also want to include some objects with sharp edges, your application would need to duplicate the vertex normals at any intersection of faces where a sharp edge was required, as shown in the following illustration.

Vertex normals needed to retain sharp edge in shading other than flat

In addition to allowing a single object to have both curved and flat surfaces, the Gouraud shade mode lights flat surfaces more realistically than the flat shade mode. A face in the flat shade mode is a uniform color, but Gouraud shading allows light to fall across a face correctly. This effect is particularly obvious if there is a nearby point source. Gouraud shading is the preferred shade mode for most Direct3D applications.

Interpolated Triangle Characteristics

The system interpolates the characteristics of a triangle's vertices across the triangle when it renders a face. The following triangle characteristics are interpolated:

  • Color
  • Specular
  • Fog
  • Alpha

All of the triangle's interpolated characteristics are modified by the current shade mode:

Flat | No interpolation is done. Instead, the color of the first vertex in the triangle is applied across the entire face.
Gouraud | Linear interpolation is performed between all three vertices.
Phong | Vertex parameters are re-evaluated for each pixel in the face, using the current lighting. The Phong shade mode is not currently supported.

The interpolated color and specular characteristics are treated differently, depending on the color model. In the RGB color model (D3DCOLOR_RGB), the system uses the red, green, and blue color components in the interpolation. In the monochromatic model (D3DCOLOR_MONO), the system uses only the blue component of the vertex color.

For example, if the red component of the color of vertex 1 were 0.8 and the red component of vertex 2 were 0.4, in the Gouraud shade mode and RGB color model the system would use interpolation to assign a red component of 0.6 to the pixel at the midpoint of the line between these vertices.

The alpha component of a color is treated as a separate interpolated characteristic because device drivers can implement transparency in two different ways: by using texture blending or by using stippling.

An application can use the dwShadeCaps member of the D3DPRIMCAPS structure to determine what forms of interpolation the current device driver supports.

Triangle Strips and Fans

You can use triangle strips and triangle fans to specify an entire surface without having to provide all three vertices for each of the triangles. For example, only seven vertices are required to define the following triangle strip.

Sample triangle strip and its vertices

The system uses vertices v1, v2, and v3 to draw the first triangle; v2, v4, and v3 to draw the second triangle; v3, v4, and v5 to draw the third; v4, v6, and v5 to draw the fourth; and so on. Notice that the vertices of the second and fourth triangles are out of order. This is required to make sure that all of the triangles are drawn in a clockwise orientation.

A triangle fan is similar to a triangle strip, except that all of the triangles share one vertex.

Diagram of a triangle fan

The system uses vertices v1, v2, and v3 to draw the first triangle; v3, v4, and v1 to draw the second triangle; v1, v4, and v5 to draw the third triangle; and so on.

You can use the wFlags member of the D3DTRIANGLE structure to specify the flags that build triangle strips and fans.

Vectors, Vertices, and Quaternions

Throughout Direct3D, vertices describe position and orientation. Each vertex in a primitive is described by a vector that gives its position, a normal vector that gives its orientation, texture coordinates, and a color. (In Retained Mode, the D3DRMVERTEX structure contains these values.)

Quaternions add a fourth element to the [x, y, z] values that define a vector. Quaternions are an alternative to the matrix methods that are typically used for 3-D rotations. A quaternion represents an axis in 3-D space and a rotation around that axis. For example, a quaternion could represent a (1,1,2) axis and a rotation of 1 radian. Quaternions carry valuable information, but their true power comes from the two operations that you can perform on them: composition and interpolation.

Performing composition on quaternions is similar to combining them. The composition of two quaternions is notated as follows:

Equation showing composition of two quaternions

The composition of two quaternions applied to a geometry means "rotate the geometry around axis2 by rotation2, then rotate it around axis1 by rotation1." In this case, Q represents a rotation around a single axis that is the result of applying q2, then q1 to the geometry.

Using quaternion interpolation, an application can calculate a smooth and reasonable path from one axis and orientation to another. Therefore, interpolation between q1 and q2 provides a simple way to animate from one orientation to another.

When you use composition and interpolation together, they provide you with a simple way to manipulate a geometry in a manner that appears complex. For example, imagine that you have a geometry that you want to rotate to a given orientation. You know that you want to rotate it r2 degrees around axis2, then rotate it r1 degrees around axis1, but you don't know the final quaternion. By using composition, you could combine the two rotations on the geometry to get a single quaternion that is the result. Then, you could interpolate from the original to the composed quaternion to achieve a smooth transition from one to the other.

Direct3D Retained Mode includes some functions that help you work with quaternions. For example, the D3DRMQuaternionFromRotation function adds a rotation value to a vector that defines an axis of rotation, and returns the result in a quaternion defined by a D3DRMQUATERNION structure. Additionally, the D3DRMQuaternionMultiply function composes quaternions and the D3DRMQuaternionSlerp performs spherical linear interpolation between two quaternions.

Retained Mode applications can use the following functions to simplify the task of working with vectors and quaternions:

  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract

Floating-Point Precision

Direct3D, like the rest of the DirectX architecture, uses a floating-point precision of 53 bits. If your application needs to change this precision, it must change it back to 53 when the calculations are finished. Otherwise, system components that depend on the default value will stop working.


Direct3D Retained Mode Architecture

This section gives an overview of the Microsoft® Direct3D® Retained Mode interfaces. The following topics are discussed:

  • Objects gives a brief description of the Direct3D Retained Mode objects.
  • Objects and Interfaces lists the interfaces supported by each object, as well as information on creating interfaces to both single objects and array objects.
  • Objects and Reference Counting gives tips on reference counting in Direct3D Retained Mode.
  • Z-Buffers in Retained Mode describes how Direct3D Retained Mode handles overlays.

Direct3D Retained Mode Objects

All access to Direct3D Retained Mode is through a small set of objects. The following table lists these objects and a brief description of each:

Object | Description
Direct3DRMAnimation | Defines how a transformation will be modified—often in reference to a Direct3DRMFrame or Direct3DRMFrame2 object. You can use it to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.
Direct3DRMAnimationSet | Allows Direct3DRMAnimation objects to be grouped together.
Direct3DRMDevice | Represents the visual display destination for the renderer.
Direct3DRMDevice2 | Represents the visual display destination for the renderer. Same as the Direct3DRMDevice object but with enhanced control of transparency.
Direct3DRMFace | Represents a single polygon in a mesh.
Direct3DRMFrame | Positions objects within a scene and defines the positions and orientations of visual objects.
Direct3DRMFrame2 | Extends the Direct3DRMFrame object by enabling access to the frame axes, bounding boxes, and materials. Also supports ray picking.
Direct3DRMInterpolator | Stores actions and applies the actions to objects with automatic calculation of in-between values.
Direct3DRMLight | Defines one of five types of lights that are used to illuminate the visual objects in a scene.
Direct3DRMMaterial | Defines how a surface reflects light.
Direct3DRMMesh | Consists of a set of polygonal faces. You can use this object to manipulate groups of faces and vertices.
Direct3DRMMeshBuilder | Allows you to work with individual vertices and faces in a mesh.
Direct3DRMMeshBuilder2 | Allows you to work with individual vertices and faces in a mesh. Same as the Direct3DRMMeshBuilder object but with than the Direct3DRMMeshBuilder object.
Direct3DRMObject | Used as a base class by all other Direct3D Retained Mode objects. It has characteristics that are common to all objects.
Direct3DRMPickedArray | Identifies a visual object that corresponds to a given 2-D point.
Direct3DRMPicked2Array | Identifies a visual object that corresponds to a given ray intersection.
Direct3DRMProgressiveMesh | Consists of a coarse base mesh together with records describing how to incrementally refine the mesh. This allows a generalized level of detail to be set on the mesh, as well as progressive download of the mesh from a remote source.
Direct3DRMShadow | Defines a shadow.
Direct3DRMTexture | Represents a rectangular array of colored pixels.
Direct3DRMTexture2 | Represents a rectangular array of colored pixels. Same as the Direct3DRMTexture object except that resources can be loaded from files other than the currently executing file, textures can be created from images in memory, and you can generate mipmaps.
Direct3DRMUserVisual | Provides functionality not otherwise available in the system. It is defined by an application.
Direct3DRMViewport | Defines how the 3-D scene is rendered into a 2-D window.
Direct3DRMVisual | Represents anything that can be rendered in a scene. Visual objects need not be visible; for example, a frame can be added as a visual object.
Direct3DRMWrap | Calculates texture coordinates for a face or mesh.

Many objects can be grouped into arrays, called array objects. Array objects make it simpler to apply operations to the entire group. The Component Object Model (COM) interfaces that allow you to work with array objects contain the GetElement and GetSize methods. These methods retrieve a pointer to an element in the array and the size of the array, respectively. For more information about array interfaces, see IDirect3DRM Array Interfaces.

Objects and Interfaces

Using the IObjectName::QueryInterface method retrieves a valid interface pointer only if the object supports that interface; therefore, you could use the IDirect3DRMDevice::QueryInterface method to retrieve the IDirect3DRMWinDevice interface, but not to retrieve the IDirect3DRMVisual interface.

Object name | Supported interfaces
Direct3DRMAnimation | IDirect3DRMAnimation
Direct3DRMAnimationSet | IDirect3DRMAnimationSet
Direct3DRMDevice | IDirect3DRMDevice, IDirect3DRMWinDevice
Direct3DRMDevice2 | IDirect3DRMDevice2, IDirect3DRMWinDevice
Direct3DRMFace | IDirect3DRMFace
Direct3DRMFrame | IDirect3DRMFrame, IDirect3DRMVisual
Direct3DRMFrame2 | IDirect3DRMFrame2, IDirect3DRMVisual
Direct3DRMInterpolator | IDirect3DRInterpolator
Direct3DRMLight | IDirect3DRMLight
Direct3DRMMaterial | IDirect3DRMMaterial
Direct3DRMMesh | IDirect3DRMMesh, IDirect3DRMVisual
Direct3DRMMeshBuilder | IDirect3DRMMeshBuilder, IDirect3DRMVisual
Direct3DRMMeshBuilder2 | IDirect3DRMMeshBuilder2, IDirect3DRMVisual
Direct3DRMProgressiveMesh | IDirect3DRMProgressiveMesh, IDirect3DRMVisual
Direct3DRMShadow | IDirect3DRMShadow, IDirect3DRMVisual
Direct3DRMTexture | IDirect3DRMTexture, IDirect3DRMTexture2, IDirect3DRMVisual
Direct3DRMUserVisual | IDirect3DRMUserVisual, IDirect3DRMVisual
Direct3DRMViewport | IDirect3DRMViewport
Direct3DRMWrap | IDirect3DRMWrap

The following example illustrates how to create two interfaces to a single Direct3DRMDevice object. The IDirect3DRM::CreateObject method creates an uninitialized Direct3DRMDevice object. The IDirect3DRMDevice::InitFromClipper method initializes the object. The call to the IDirect3DRMDevice::QueryInterface method creates a second interface to the Direct3DRMDevice object—an IDirect3DRMWinDevice interface that the application will use to handle WM_PAINT and WM_ACTIVATE messages.

d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,
    IID_IDirect3DRMDevice,(LPVOID FAR*)&dev1);
dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice,
    r.right, r.bottom);
dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);

To determine whether two interfaces refer to the same object, use the QueryInterface method of each interface, and compare the values of the pointers they return. If the pointer values are the same, the interfaces refer to the same object.

All Direct3D Retained Mode objects support the IDirect3DRMObject and IUnknown interfaces in addition to the interfaces in the preceding list. Array objects are not derived from IDirect3DRMObject. Array objects have no class identifiers (CLSIDs) because they are not needed. Applications cannot create array objects in a call to the IDirect3DRM::CreateObject method; instead, they should use the creation methods listed below for each interface:

Array interface | Creation method
IDirect3DRMDeviceArray IDirect3DRM::GetDevices
IDirect3DRMFaceArray | IDirect3DRMMeshBuilder::GetFaces or IDirect3DRMMeshBuilder2::GetFaces
IDirect3DRMFrameArray | IDirect3DRMPickedArray::GetPick, IDirect3DRMPicked2Array::GetPick, or IDirect3DRMFrame::GetChildren
IDirect3DRMLightArray IDirect3DRMFrame::GetLights
IDirect3DRMObjectArray IDirect3DRMInterpolator::GetAttachedObjects
IDirect3DRMPickedArray IDirect3DRMViewport::Pick
IDirect3DRMPicked2Array IDirect3DRMFrame2::RayPick
IDirect3DRMViewportArray IDirect3DRM::CreateFrame
IDirect3DRMVisualArray IDirect3DRMFrame::GetVisuals

Objects and Reference Counting

When an object is created, its reference count is increased. Each time an application creates a child of an object or a method returns a pointer to an object, the system increases the reference count for that object. The object is not deleted until its reference count reaches zero.

Applications need to keep track of the reference count for a single object only—the root of the scene. The system keeps track of the other reference counts automatically. Applications should be able to simply release the scene, the viewport, and the device when they clean up before exiting. (When your application releases the viewport, the system automatically takes care of the camera's references.) Theoretically, an application could release a viewport without releasing the device (if it needed to add a new viewport to the device, for example), but when an application releases a device, it should release the viewport as well.

The reference count of a child or visual object increases when it is added to a frame. When you use the IDirect3DRMFrame::AddChild method to move a child from one parent to another, the system handles the reference counting automatically.

After your application loads a visual object into a scene, the scene handles the reference counting for the visual object. The application no longer needs the visual object and can release it.

Creating and applying a wrap does not increase the reference count of any objects because wrapping is really just a convenient method of calculating texture coordinates.

Z-Buffers in Retained Mode

The order in the z-buffer determines the order in which overlays clip each other. Overlays are assumed to be on top of all other screen components. Overlays that do not have a specified z-order behave in unpredictable ways when overlaying the same area on the primary surface. Direct3D Retained Mode does not sort overlays if you do not have a z-buffer. Overlays without a specified z-order are assumed to have a z-order of 0, and will appear in the order they are rendered. The possible z-order of overlays ranges from 0, which is just on top of the primary surface, to 4 billion, which is as close to the viewer as possible. An overlay with a z-order of 2 would obscure an overlay with a z-order of 1. No two overlays can have the same z-order.


Direct3D Retained Mode Animated Header --Direct3D Retained Mode Interface Overviews Direct3D Retained Mode Animated Header --Direct3D Retained Mode Interface Overviews * Microsoft Direct3D Retained Mode SDK
  * Previous Topic: Direct3D Retained Mode Architecture
  * Next Topic: Direct3D Retained Mode Tutorial

Direct3D Retained Mode Interface Overviews

This section contains overviews of the Microsoft® Direct3D® Retained Mode interfaces and includes information on what they do, how to use them, and things to be aware of. For a description of each interface's methods, see the appropriate entry in the Direct3D Retained Mode Reference.

  • IDirect3DRMAnimation and IDirect3DRMAnimationSet Interfaces
  • IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces
  • Direct3DRMFace
  • IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces
  • IDirect3DRMInterpolator Interface
  • IDirect3DRMLight and IDirect3DRMLightArray Interfaces
  • IDirect3DRMMaterial Interface
  • IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces
  • Direct3DRMObject
  • IDirect3DRMPickedArray and IDirect3DRMPicked2Array Interfaces
  • IDirect3DRMProgressiveMesh Interface
  • IDirect3DRMShadow Interface
  • IDirect3DRMTexture and IDirect3DRMTexture2 Interfaces
  • IDirect3DRMUserVisual Interface
  • IDirect3DRMViewport and IDirect3DRMViewportArray Interface
  • IDirect3DRMVisual and IDirect3DRMVisualArray Interfaces
  • IDirect3DRMWrap Interface

IDirect3DRM and IDirect3DRM2 Interfaces

Applications use the methods of the IDirect3DRM interface to create Direct3D Retained Mode objects and to work with system-level variables. For a reference to the methods of this interface, see IDirect3DRM or IDirect3DRM2.

Applications use the methods of the IDirect3DRMDevice and IDirect3DRMDevice2 interfaces to interact with the output device. An IDirect3DRMDevice created from the IDirect3DRM interface works with an IDirect3DDevice Immediate Mode device. An IDirect3DRMDevice2 created from the IDirect3DRM2 interface, or initialized by the IDirect3DRMDevice2::InitFromClipper, IDirect3DRMDevice::InitFromD3D, or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as executes buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRM2 supports all the methods in IDirect3DRM. An additional method is included: IDirect3DRM2::CreateProgressiveMesh. The IDirect3DRM2::CreateDeviceFromSurface, IDirect3DRM2::CreateDeviceFromD3D, and IDirect3DRM2::CreateDeviceFromClipper methods all create a DIRECT3DRMDEVICE2 object. The IDirect3DRM2::CreateViewport method creates a viewport on a DIRECT3DRMDEVICE2 object. The IDirect3DRM2::LoadTexture and IDirect3DRM2::LoadTextureFromResource methods load a DIRECT3DRMTEXTURE2 object.

The IDirect3DRM Component Object Model (COM) interface is created by calling the Direct3DRMCreate function. To access the IDirect3DRM2 COM interface, create an IDirect3DRM object with Direct3DRMCreate, then query for IDirect3DRM2 from IDirect3DRM.

The methods of the IDirect3DRM and IDirect3DRM2 interfaces create the following objects:

  • Animations and animation sets
  • Devices
  • Faces
  • Frames
  • Generic uninitialized objects
  • Lights
  • Materials
  • Meshes and mesh builders
  • Shadows
  • Textures
  • UserVisuals
  • Viewports
  • Wraps

In addition, the IDirect3DRM2::CreateProgressiveMesh creates a DIRECT3DRMPROGRESSIVEMESH object.

IDirect3DRMAnimation and IDirect3DRMAnimationSet Interfaces

An animation in Retained Mode is defined by a set of keys. A key is a time value associated with a scaling operation, an orientation, or a position. A Direct3DRMAnimation object defines how a transformation is modified according to the time value. The animation can be set to operate on a Direct3DRMFrame object, so it could be used to animate the position, orientation, and scaling of Direct3DRMVisual, Direct3DRMLight, and Direct3DRMViewport objects.

The IDirect3DRMAnimation::AddPositionKey, IDirect3DRMAnimation::AddRotateKey, and IDirect3DRMAnimation::AddScaleKey methods each specify a time value whose units are arbitrary. If an application adds a position key with a time value of 99, for example, a new position key with a time value of 49 would occur exactly halfway between the (zero-based) beginning of the animation and the first position key.

The animation is driven by calling the IDirect3DRMAnimation::SetTime method. This sets the visual object's transformation to the interpolated position, orientation, and scale of the nearby keys in the animation. As with the methods that add animation keys, the time value for IDirect3DRMAnimation::SetTime is an arbitrary value, based on the positions of keys the application has already added.

A Direct3DRMAnimationSet object allows Direct3DRMAnimation objects to be grouped together. This allows all the animations in an animation set to share the same time parameter, simplifying the playback of complex articulated animation sequences. An application can add an animation to an animation set by using the IDirect3DRMAnimationSet::AddAnimation method, and it can remove one by using the IDirect3DRMAnimationSet::DeleteAnimation method. Animation sets are driven by calling the IDirect3DRMAnimationSet::SetTime method.

For related information, see the IDirect3DRMAnimation and IDirect3DRMAnimationSet interfaces.

IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces

All forms of rendered output must be associated with an output device. The device object represents the visual display destination for the renderer.

The renderer's behavior depends on the type of output device that is specified. You can define multiple viewports on a device, allowing different aspects of the scene to be viewed simultaneously. You can also specify any number of devices, allowing multiple destination devices for the same scene.

Retained Mode supports devices that render directly to the screen, to windows, or into application memory.

While an IDirect3DRMDevice interface, when created from the IDirect3DRM interface, works with an IDirect3DDevice Immediate Mode device, an IDirect3DRMDevice2 interface, when created from the IDirect3DRM2 interface or initialized by the IDirect3DRMDevice2::InitFromClipper, IDirect3DRMDevice2::InitFromD3D2, or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

The IDirect3DRMDevice2::InitFromClipper and IDirect3DRMDevice2::InitFromSurface methods use the IDirect3DRM2::CreateDevice method to create an IDirect3DRMDevice2 object. The IDirect3DRMDevice2::InitFromD3D2 method uses an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device to initialize an IDirect3DDevice2 Retained Mode device.

You can still query back and forth between the IDirect3DRMDevice and IDirect3DRMDevice2 interfaces. The main difference is in how the underlying Immediate Mode device is created.

The IDirect3DRMDevice2 interface contains all the methods found in the IDirect3DRMDevice interface, plus two additional ones that allow you to control transparency—IDirect3DRMDevice2::GetRenderMode and IDirect3DRMDevice2::SetRenderMode—and one additional initialization method: IDirect3DRMDevice2::InitFromSurface.

For related information, see IDirect3DRMDevice and IDirect3DRMDevice2.

This section describes the options available to display Direct3D images to output devices.

  • Quality
  • Color Models
  • Window Management

Quality

The device allows the scene and its component parts to be rendered with various degrees of realism. The device rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device. Mesh, progressive mesh, and mesh builder objects can also have a specified rendering quality.

A device's or object's quality has three components: shade mode (flat or Gouraud; Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wireframe or solid).

You can set the quality of a device with IDirect3DRMDevice::SetQuality and IDirect3DRMDevice2::SetQuality methods. By default, the device quality is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh, Direct3DRMMeshBuilder, or Direct3DRMMeshBuilder2 object with their respective SetQuality methods: IDirect3DRMProgressiveMesh::SetQuality, IDirect3DRMMeshBuilder::SetQuality, and IDirect3DRMMeshBuilder2::SetQuality. By default, the quality of these objects is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT then the object will be rendered with flat shading, solid fill, and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, then the object will be rendered with flat shading, lights off, and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

Color Models

Retained Mode supports two color models: an RGB model and a monochromatic (or ramp) model. To retrieve the color model, an application can use the IDirect3DRMDevice::GetColorModel method.

The RGB model treats color as a combination of red, green, and blue light, and it supports multiple light sources that can be colored. There is no limit to the number of colors in the scene. You can use this model with 8-, 16-, 24-, and 32-bit displays. If the display depth is less than 24 bits, the limited color resolution can produce banding artifacts. You can avoid these artifacts by using optional dithering.

The monochromatic model also supports multiple light sources, but their color content is ignored. Each source is set to a gray intensity. RGB colors at a vertex are interpreted as brightness levels, which (in Gouraud shading) are interpolated across a face between vertices with different brightnesses. The number of differently colored objects in the scene is limited; after all the system's free palette entries are used up, the system's internal palette manager finds colors that already exist in the palette and that most closely match the intended colors. Like the RGB model, you can use this model with 8-, 16-, 24-, and 32-bit displays. (The monochromatic model supports only 8-bit textures, however.) The advantage of the monochromatic model over the RGB model is simply performance.

It is not possible to change the color model of a Direct3D device. Your application should use the IDirect3D::EnumDevices or IDirect3D::FindDevice method to identify a driver that supports the required color model, then specify this driver in one of the device-creation methods.

Palettes are supported for textures, off-screen surfaces, and overlay surfaces, none of which is required to have the same palette as the primary surface. If a device supports a 4-bit indexed palette (16 colors) and you have 8-bit indexed art (256 colors), Retained Mode will render the art as 4-bit by taking the first 16 entries from your palette and remapping to those. Therefore, you should put your 16 preferred colors at the front of the palette if possible.

Window Management

For correct operation, applications must inform Direct3D when the WM_MOVE, WM_PAINT, and WM_ACTIVATE messages are received from the operating system by using the IDirect3DRMWinDevice::HandlePaint and IDirect3DRMWinDevice::HandleActivate methods.

For related information, see IDirect3DRMWinDevice.

IDirect3DRMFace and IDirect3DRMFaceArray Interfaces

A face represents a single polygon in a mesh. An application can set the color, texture, and material of the face by using the IDirect3DRMFace::SetColor, IDirect3DRMFace::SetColorRGB, IDirect3DRMFace::SetTexture, and IDirect3DRMFace::SetMaterial methods.

Faces are constructed from vertices by using the IDirect3DRMFace::AddVertex and IDirect3DRMFace::AddVertexAndNormalIndexed methods. An application can read the vertices of a face by using the IDirect3DRMFace::GetVertices and IDirect3DRMFace::GetVertex methods.

For related information, see IDirect3DRMFace.

IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces

The term frame is derived from an object's physical frame of reference. The frame's role in Retained Mode is similar to a window's role in a windowing system. Objects can be placed in a scene by stating their spatial relationship to a relevant reference frame; they are not simply placed in world space. A frame is used to position objects in a scene, and visuals take their positions and orientation from frames.

A scene in Retained Mode is defined by a frame that has no parent frame; that is, a frame at the top of the hierarchy of frames. This frame is also sometimes called a root frame or master frame. The scene defines the frame of reference for all of the other objects. You can create a scene by calling the IDirect3DRM::CreateFrame method and specifying NULL for the first parameter.

The IDirect3DRMFrame2 interface is an extension of the IDirect3DRMFrame interface. IDirect3DRMFrame2 has methods that enable using materials, bounding boxes, and axes with frames. IDirect3DRMFrame2 also supports ray picking.

By using the IDirect3DRMFrame2::SetAxes method and using the right-handed projection types in the D3DRMPROJECTIONTYPE structure with the IDirect3DRMViewport::SetProjection method, you can enable right-handed projection.

For related information, see IDirect3DRMFrame and IDirect3DRMFrame2.

This section describes frames and how your application can use them.

  • Hierarchies
  • Transformations
  • Motion
  • Callback Functions

Hierarchies

The frames in a scene are arranged in a tree structure. Frames can have a parent frame and child frames. Remember, a frame that has no parent frame defines a scene and is called a root frame.

Child frames have positions and orientations relative to their parent frames. If the parent frame moves, the child frames also move.

An application can set the position and orientation of a frame relative to any other frame in the scene, including the root frame if it needs to set an absolute position. You can also remove frames from one parent frame and add them to another at any time by using the IDirect3DRMFrame::AddChild method. To remove a child frame entirely, use the IDirect3DRMFrame::DeleteChild method. To retrieve a frame's child and parent frames, use the IDirect3DRMFrame::GetChildren and IDirect3DRMFrame::GetParent methods.

You can add frames as visuals to other frames, allowing you to use a given hierarchy many times throughout a scene. The new hierarchies are referred to as instances. Be careful to avoid instancing a parent frame into its children because that will degrade performance. Retained Mode does no run-time checking for cyclic hierarchies. You cannot create a cyclic hierarchy by using the methods of the IDirect3DRMFrame interface; instead, this is possible only when you add a frame as a visual.

Transformations

You can think of the position and orientation of a frame relative to its parent frame as a linear transformation. This transformation takes vectors defined relative to the child frame and changes them to equivalent vectors defined relative to the parent.

Transformations can be represented by 4×4 matrices, and coordinates can be represented by four-element row vectors, [x, y, z,1].

If vchild is a coordinate in the child frame, then vparent, the equivalent coordinate in the parent frame, is defined as:

Definition of the parent frame

Tchild is the child frame's transformation matrix.

The transformations of all the parent frames above a child frame up to the root frame are concatenated with the transformation of that child to produce a world transformation. This world transformation is then applied to the visuals on the child frame before rendering. Coordinates relative to the child frame are sometimes called model coordinates. After the world transformation is applied, coordinates are called world coordinates.

The transformation of a frame can be modified directly by using the IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::AddScale, IDirect3DRMFrame::AddRotation, and IDirect3DRMFrame::AddTranslation methods. Each of these methods specifies a member of the D3DRMCOMBINETYPE enumerated type, which specifies how the matrix supplied by the application should be combined with the current frame's matrix.

The IDirect3DRMFrame::GetRotation and IDirect3DRMFrame::GetTransform methods allow you to retrieve a frame's rotation axis and transformation matrix. To change the rotation of a frame, use the IDirect3DRMFrame::SetRotation method.

Use the IDirect3DRMFrame::Transform and IDirect3DRMFrame::InverseTransform methods to change between world coordinates and model coordinates.

You can find a more general discussion of transformations in the section devoted to viewports, Transformations. For an overview of the mathematics of transformations, see 3-D Transformations.

Motion

Every frame has an intrinsic rotation and velocity. Frames that are neither rotating nor translating simply have zero values for these attributes. These attributes are used before each scene is rendered to move objects in the scene, and they can also be used to create simple animations.

Callback Functions

Frames support a callback function that you can use to support more complex animations. The application registers a function that the frame calls before the motion attributes are applied. When there are multiple frames in a hierarchy, each with associated callback functions, the parent frames are called before the child frames. For a given hierarchy, rendering does not take place until all of the required callback functions have been invoked.

To add this callback function, use the IDirect3DRMFrame::AddMoveCallback method; to remove it, use the IDirect3DRMFrame::DeleteMoveCallback method.

You can use these callback functions to provide new positions and orientations from a preprogrammed animation sequence or to implement dynamic motion in which the activities of visuals depend upon the positions of other objects in the scene.

IDirect3DRMInterpolator Interface

Interpolators provide a way of storing actions and applying them to objects with automatic calculation of in-between values. For example, you can set a scene's background color to red at time zero and green at time ten, and the interpolator will automatically tint successive scenes to blend from red to green. With an interpolator, you can blend colors, move objects smoothly between positions, morph meshes, and perform many other transformations.

In the Direct3D Retained Mode implementation, interpolators are a generalization of the IDirect3DRMAnimation interface that increases the kinds of object parameters you can animate. While the IDirect3DRMAnimation interface allows animation of an object's position, size and orientation, the IDirect3DRMInterpolator interface further enables animation of colors, meshes, textures, and materials.

Interpolator Keys

The actions stored by the interpolator are called keys. A key is a stored procedure call and has an index associated with it. The interpolator automatically calculates between the key values.

Keys are stored in the interpolator by calling one of the supported interface methods that can be interpolated. The method and the parameter values passed to it make up the key. Methods Supported by the Interpolator supplies a list of supported methods.

Every key stored inside an interpolator has an index value. When the key is recorded, it is stamped with the current interpolator index value. The key's index value never changes once this value is set.

Interpolator Types

Objects can be attached to interpolators of an associated type; for example, a Mesh can be attached to a MeshInterpolator. The interpolator types are:

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

Other interpolators can also be attached to an interpolator. When you change the index of an interpolator, it sets the indices of any attached interpolators to the same value.

Note that for MeshInterpolators, you add a SetVertices key to a MeshInterpolator object by calling SetVertices on the MeshInterpolator object's IDirect3DRMMesh interface. The group index used with SetVertices must correspond to a valid group index in the Mesh object or objects that the interpolator is applied to.

Interpolator Example

As an example, if you want to interpolate a frame's position, you will need a FrameInterpolator object with two interfaces, IDirect3DRMInterpolator and IDirect3DRMFrame.

pd3drm->CreateObject(CLSID_CDirect3DRMFrameInterpolator, 0, IID_IDirect3DRMInterpolator, &pInterp);
pInterp->QueryInterface(IID_IDirect3DRMFrame, &pFrameInterp);

To add a position key to the interpolator, set the interpolator's internal index through the IDirect3DRMInterpolator interface, and record the position by calling the IDirect3DRMFrame::SetPosition method on the IDirect3DRMFrame interface. This method is applied to the interpolator rather than to a real frame. The function call and its parameters are stored in the interpolator as a new key with the current index.

pInterp->SetIndex(keytime);
pFrameInterp->SetPosition(NULL, keypos.x, keypos.y, keypos.z);

You can add more keys by repeating the sequence of setting the index with SetIndex followed by one or more object methods. To play actions back through a real frame, attach the frame to the interpolator.

pInterp->AttachObject(pRealFrame);

Now call Interpolate to set the position of the pRealFrame parameter using the interpolated position.

pInterp->Interpolate(time, NULL, D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

The interpolator will call the attached frame's SetPosition method, passing it a position it has calculated by interpolating (in this case, using a B-spline) between the nearest SetPosition keys.

Alternatively, you can use the immediate form of Interpolate and pass the object as the second parameter. This overrides any attached objects.

pInterp->Interpolate(time, pRealFrame, D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

You can use the same interpolator to store other keys such as orientation, scale, velocity, and color keys. Each property exists on a parallel timeline, and calling Interpolate assigns the interpolated value for each property to the attached frames.

It is possible to interpolate more than one method. For example, you can store SetGroupColor and SetVertices keys in the same interpolator. It is not possible to interpolate between keys of different methods, so they are stored in parallel execution threads called Key Chains. Also, if you specify two keys from different groups, such as SetGroupColor(0, black) and SetGroupColor(2, white), it does not make sense for the interpolator to generate an in-between action of SetGroupColor(1, gray) because the keys apply to different groups. In this case, the keys are also stored in separate chains.

Methods Supported by the Interpolator

Viewport

SetFront(value)
SetBack(value)
SetField(value)
SetPlane(left, right, bottom, top)

Frame and Frame2

SetPosition(reference*, x, y, z)
SetRotation(reference*, x, y, z, theta)
SetVelocity(reference*, x, y, z, withRotation*)
SetOrientation(reference*, dx, dy, dz, ux, uy, uz)
SetColor(color)
SetColorRGB(red, green, blue)
SetSceneBackground(color)
SetSceneBackgroundRGB(red, green, blue)
SetSceneFogColor(color)
SetSceneFogParams(start, end, density)
SetQuaternion(reference*, quat)

Mesh

Translate(x, y, z)
SetVertices(group*, index*, count*, vertices)
SetGroupColor(group*, color)
SetGroupColorRGB(group*, red, green, blue)

Light

SetColor(color)
SetColorRGB(red, green, blue)
SetRange(value)
SetUmbra(value)
SetPenumbra(value)
SetConstantAttenuation(value)
SetLinearAttenuation(value)
SetQuadraticAttenuation(value)

Texture and Texture2

SetDecalSize(width, height)
SetDecalOrigin(x, y)
SetDecalTransparentColor(color)

Material

SetPower(value)
SetSpecular(red, green, blue)
SetEmissive(red, green, blue)

*—Indicates keys with different values for this parameter are inserted in separate chains

An attempt to set a key of any unsupported method will result in a non-fatal D3DRMERR_BADOBJECT error.

Interpolator Index Span

The interpolator covers a span of index values. This index span is dictated by the following rules:

  • The start of the span is the minimum of all key index values and the current index.
  • The end of the span is the maximum of all key index values and the current index.

Interpolation Options

Interpolation can be performed with one or more of the following options:

  • D3DRMINTERPOLATION_CLOSED
  • D3DRMINTERPOLATION_LINEAR
  • D3DRMINTERPOLATION_NEAREST
  • D3DRMINTERPOLATION_OPEN
  • D3DRMINTERPOLATION_SLERPNORMALS
  • D3DRMINTERPOLATION_SPLINE
  • D3DRMINTERPOLATION_VERTEXCOLOR

If the interpolator is executed CLOSED, the interpolation is cyclic. The keys effectively repeat infinitely with a period equal to the index span. For compatibility with animations, any key with an index equal to the end of the span is ignored.

If the interpolation is OPEN, the first and last keys of each key chain fix the interpolated values outside of the index span.

The NEAREST, LINEAR, and SPLINE options specify how in-betweening is performed on each key chain. If NEAREST is specified the nearest key value is used. LINEAR performs linear interpolation between the 2 nearest keys. SPLINE uses a B-spline blending function on the 4 nearest keys.

The following two options affect only the interpolation of IDirect3DRMMesh::SetVertices:

  • VERTEXCOLOR specifies that vertex colors should be interpolated.
  • SLERPNORMALS specifies that vertex normals should be spherically interpolated (not currently implemented).

IDirect3DRMLight and IDirect3DRMLightArray Interfaces

Lighting effects are employed to increase the visual fidelity of a scene. The system colors each object based on the object's orientation to the light sources in the scene. The contribution of each light source is combined to determine the color of the object during rendering. All lights have color and intensity that can be varied independently.

An application can attach lights to a frame to represent a light source in a scene. When a light is attached to a frame, it illuminates visual objects in the scene. The frame provides both position and orientation for the light. In other words, the light originates from the origin of the frame it is attached to. An application can move and redirect a light source simply by moving and reorienting the frame the light source is attached to.

Each viewport owns one or more lights. No light can be owned by more than one viewport.

Retained Mode currently provides five types of light sources: ambient, directional, parallel point, point, and spotlight.

For a reference to the methods of the IDirect3DRMLight interface, see IDirect3DRMLight.

This section describes lighting effects available in Direct3D and how your application can use them.

  • Ambient
  • Directional
  • Parallel Point
  • Point
  • Spotlight

Ambient

An ambient light source illuminates everything in the scene, regardless of the orientation, position, and surface characteristics of the objects in the scene. Because ambient light illuminates a scene with equal strength everywhere, the position and orientation of the frame it is attached to are inconsequential. Multiple ambient light sources are combined within a scene.

Directional

A directional light source has orientation but no position. The light is attached to a frame but appears to illuminate all objects with equal intensity, as if it were at an infinite distance from the objects. The directional source is commonly used to simulate distant light sources, such as the sun. It is the best choice of light to use for maximum rendering speed.

Parallel Point

A parallel point light source illuminates objects with parallel light, but the orientation of the light is taken from the position of the parallel point light source. That is, like a directional light source, a parallel point light source has orientation, but it also has position. For example, two meshes on either side of a parallel point light source are lit on the side that faces the position of the source. The parallel point light source offers similar rendering-speed performance to the directional light source.

Point

A point light source radiates light equally in all directions from its origin. It requires the calculation of a new lighting vector for every facet or normal it illuminates, and for this reason it is computationally more expensive than a parallel point light source. It does, however, produce a more faithful lighting effect and should be chosen where visual fidelity is the deciding concern.

Spotlight

A spotlight emits a cone of light. Only objects within the cone are illuminated. The cone produces light of two degrees of intensity, with a central brightly lit section (the umbra) that acts as a point source, and a surrounding dimly lit section (the penumbra) that merges with the surrounding deep shadow. The angles of these two sections can be individually specified by using the IDirect3DRMLight::GetPenumbra, IDirect3DRMLight::GetUmbra, IDirect3DRMLight::SetPenumbra, and IDirect3DRMLight::SetUmbra methods.

Illustration of penumbra angle, umbra angle, and umbra cone

IDirect3DRMMaterial Interface

A material defines how a surface reflects light. A material has two components: an emissive property (whether it emits light) and a specular property, whose brightness is determined by a power setting. The value of the power determines the sharpness of the reflected highlights, with a value of 5 giving a metallic appearance and higher values giving a more plastic appearance.

An application can control the emission of a material by using the IDirect3DRMMaterial::GetEmissive and IDirect3DRMMaterial::SetEmissive methods, the specular component by using the IDirect3DRMMaterial::GetSpecular and IDirect3DRMMaterial::SetSpecular methods, and the power by using the IDirect3DRMMaterial::GetPower and IDirect3DRMMaterial::SetPower methods.

For a reference to the methods of the IDirect3DRMMaterial interface, see IDirect3DRMMaterial.

IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces

A mesh is a visual object that is made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces (the faces are defined in terms of the vertices and normals of the mesh). Changing a vertex or normal that is used by several faces changes the appearance of all faces sharing it.

The vertices of a mesh define the positions of faces in the mesh, and they can also be used to define 2-D coordinates within a texture map.

You can manipulate meshes in Retained Mode by using three COM interfaces: IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2. IDirect3DRMMesh is very fast, and you should use it when a mesh is subject to frequent changes, such as when morphing. IDirect3DRMMeshBuilder is built on top of the IDirect3DRMMesh interface. Although the IDirect3DRMMeshBuilder interface is a convenient way to perform operations on individual faces and vertices, the system must convert a Direct3DRMMeshBuilder object into a Direct3DRMMesh object before rendering it. For meshes that do not change or that change infrequently, this conversion has a negligible impact on performance.

IDirect3DRMMeshBuilder2 has all the functionality of IDirect3DRMMeshBuilder plus one enhanced and one added method. IDirect3DRMMeshBuilder2::GenerateNormals2 gives you more control over how normals are generated. IDirect3DRMMeshBuilder2::GetFace allows you to access a single face in a mesh.

If an application needs to assign the same characteristics (such as material or texture) to several vertices or faces, it can use the IDirect3DRMMesh interface to combine them in a group. If the application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups. The IDirect3DRMMesh::AddGroup method assigns a group identifier to a collection of faces. This identifier is used to refer to the group in subsequent calls.

The IDirect3DRMMeshBuilder, IDirect3DRMMeshBuilder2, and IDirect3DRMMesh interfaces allow an application to create faces with more than three sides. They also automatically split a mesh into multiple buffers if, for example, the hardware the application is rendering to has a limit of 64K and a mesh is larger than that size. These features set the Direct3DRMMesh and Direct3DRMMeshBuilder API apart from the Direct3D API.

You can add vertices and faces individually to a mesh by using the IDirect3DRMMeshBuilder::AddVertex, IDirect3DRMMeshBuilder::AddFace, and IDirect3DRMMeshBuilder::AddFaces methods or the equivalent IDirect3DRMMeshBuilder2 methods. You can retrieve an individual face with the IDirect3DRMMeshBuilder2::GetFace.

You can define individual color, texture, and material properties for each face in the mesh, or for all faces in the mesh at once, by using the IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB, IDirect3DRMMesh::SetGroupTexture, and IDirect3DRMMesh::SetGroupMaterial methods.

For a mesh to be rendered, you must first add it to a frame by using the IDirect3DRMFrame::AddVisual method. You can add a single mesh to multiple frames to create multiple instances of that mesh.

Your application can use flat, Gouraud, and Phong shade modes, as specified by a call to the IDirect3DRMMesh::SetGroupQuality method. (Phong shading is not yet available, however.) This method uses values from the D3DRMRENDERQUALITY enumerated type. For more information about shade modes, see Polygons.

You can set normals (which should be unit vectors), or normals can be calculated by averaging the face normals of the surrounding faces by using the IDirect3DRMMeshBuilder::GenerateNormals method.

Direct3DRMObject

Direct3DRMObject is the common superclass of all objects in the system. A Direct3DRMObject object has characteristics common to all objects.

Each Direct3DRMObject object is instantiated as a COM object. In addition to the methods of the IUnknown interface, each object has a standard set of methods that are generic to all.

To create an object, the application must first have instantiated a Direct3D Retained Mode object by calling the Direct3DRMCreate function. The application then calls the method of the object's interface that creates an object, and it specifies parameters specific to the object. For example, to create a Direct3DRMAnimation object, the application would call the IDirect3DRM::CreateAnimation method. The creation method then creates a new object, initializes some of the object's attributes from data passed in the parameters (leaving all others with their default values), and returns the object. Applications can then specify the interface for this object to modify and use the object.

Any object can store 32 bits of application-specific data. This data is not interpreted or altered by Retained Mode. The application can read this data by using the IDirect3DRMObject::GetAppData method, and it can write to it by using the IDirect3DRMObject::SetAppData method. Finding this data is simpler if the application keeps a structure for each Direct3DRMFrame object. For example, if calling the IDirect3DRMFrame::GetParent method retrieves a Direct3DRMFrame object, the application can easily retrieve the data by using a pointer to its private structure, possibly avoiding a time-consuming search.

You might also want to assign a name to an object to help you organize an application or as part of your application's user interface. You can use the IDirect3DRMObject::SetName and IDirect3DRMObject::GetName methods to set and retrieve object names.

Another example of possible uses for application-specific data is when an application needs to group the faces within a mesh into subsets (for example, for front and back faces). You could use the application data in the face to note in which of these groups a face should be included.

An application can specify a function to call when an object is destroyed, such as when the application needs to deallocate memory associated with the object. To do this, use the IDirect3DRMObject::AddDestroyCallback method. To remove a function previously registered with this method, use the IDirect3DRMObject::DeleteDestroyCallback method.

The callback function is called only when the object is destroyed—that is, when the object's reference count has reached 0 and the system is about to deallocate the memory for the object. If an application kept additional data about an object (so that its dynamics could be implemented, for example), the application could use this callback function as a way to notify itself that it can dispose of the data.

For related information, see IDirect3DRMObject and IDirect3DRMObjectArray.

IDirect3DRMPickedArray and IDirect3DRMPicked2Array Interfaces

Picking is the process of searching for visuals in a scene, given a 2-D coordinate in a viewport or a vector in a frame.

You can use the IDirect3DRMViewport::Pick method to retrieve an IDirect3DRMPickedArray interface, and then call the IDirect3DRMPickedArray::GetPick method to retrieve an IDirect3DRMFrameArray interface and a visual object. The array of frames is the path through the hierarchy leading to the visual object; that is, a hierarchical list of the visual object's parent frames, with the topmost parent in the hierarchy first in the array.

You can use the IDirect3DRMFrame2::RayPick method to retrieve an IDirect3DRMPicked2Array interface, and then call the IDirect3DRMPicked2Array::GetPick method to retrieve an IDirect3DRMFrameArray interface, a visual object, and information about the object intersected by the ray, including the face and group identifiers, pick position, and horizontal and vertical texture coordinates for the vertex, vertex normal, and color of the object. The array of frames is the path through the hierarchy leading to the visual object.

IDirect3DRMProgressiveMesh Interface

A mesh is a visual object that is made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces.

A progressive mesh is a mesh that is stored as a base mesh (a coarse version) and a set of records that are used to increasingly refine the mesh. This allows you to set the level of detail rendered for a mesh and also allows progressive download from remote sources.

Using the methods of the IDirect3DRMProgressiveMesh interface, you can set the number of vertices or faces to render and thereby control the render detail. You can also specify a minimum level of detail required for rendering. Normally, a progressive mesh is rendered once the base mesh is available, but with the IDirect3DRMProgressiveMesh::SetMinRenderDetail method you can specify that a greater level of detail is necessary before rendering. You can also build a Direct3DRMMesh object from a particular state of the progressive mesh using the IDirect3DRMProgressiveMesh::CreateMesh method.

You can load a progressive mesh from a file, resource, memory, or URL. Loading can be done synchronously or asynchronously. You can check the status of a download with the IDirect3DRMProgressiveMesh::GetLoadStatus method, and terminate a download with the IDirect3DRMProgressiveMesh::Abort method. If loading is asynchronous, it is up to the application to use events through the IDirect3DRMProgressiveMesh::RegisterEvents and IDirect3DRMProgressiveMesh::GetLoadStatus methods to find out how the load is progressing.

IDirect3DRMShadow Interface

Applications can produce an initialized and usable shadow simply by calling the IDirect3DRM::CreateShadow method. The IDirect3DRMShadow interface exists so that applications which create a shadow by using the IDirect3DRM::CreateObject method can initialize the shadow by calling the IDirect3DRMShadow::Init method.

IDirect3DRMTexture and IDirect3DRMTexture2 Interfaces

A texture is a rectangular array of colored pixels. (The rectangle does not necessarily have to be square, although the system deals most efficiently with square textures.) You can use textures for texture-mapping faces, in which case their dimensions must be powers of two.

Your application can use the IDirect3DRM::CreateTexture method to create a texture from a D3DRMIMAGE structure, or the IDirect3DRM::CreateTextureFromSurface method to create a texture from a DirectDraw surface. The IDirect3DRM::LoadTexture method allows your application to load a texture from a file; the texture should be in Microsoft® Windows® bitmap (.bmp) or Portable Pixmap (.ppm) format. To avoid unnecessary delays when creating textures, hold onto textures you want to use again, instead of creating them each time they're needed. For optimal performance, use a texture surface format that is supported by the device you are using. This will avoid a costly format conversion when the texture is created and any time it changes.

The texture coordinates of each face define the region in the texture that is mapped onto that particular face. Your application can use a wrap to calculate texture coordinates. For more information, see IDirect3DRMWrap Interface.

The IDirect3DRMTexture2 interface is an extension of the IDirect3DRMTexture interface. The IDirect3DRMTexture2::InitFromResource2 method allows resources to be loaded from DLLs and executables other than the currently executing file. In addition, IDirect3DRMTexture2 has two new methods. IDirect3DRMTexture2::InitFromImage creates a texture from an image in memory. This method is equivalent to IDirect3DRM::CreateTexture. IDirect3DRMTexture2::GenerateMIPMap generates a MIP map from a source image.

Textures are loaded from BMP and DIB (device-independent bitmap) files right-side up in IDirect3DRMTexture2::InitFromFile and IDirect3DRMTexture2::InitFromResource2, unlike IDirect3DRMTexture::InitFromFile and IDirect3DRMTexture::InitFromResource where they are loaded inverted.

For a reference to the methods of these interfaces, see IDirect3DRMTexture and IDirect3DRMTexture2.

This section describes the types of textures supported by Direct3D and how your application can use them.

  • Decals
  • Texture Colors
  • Mipmaps
  • Texture Filtering
  • Texture Transparency
  • Texture Format Selection Rules

Decals

Textures can also be rendered directly, as visuals. Textures used this way are sometimes known as decals, a term adopted by Retained Mode. A decal is rendered into a viewport-aligned rectangle. The rectangle can optionally be scaled by the depth component of the decal's position. The size of the decal is taken from a rectangle defined relative to the containing frame by using the IDirect3DRMTexture::SetDecalSize method. (An application can retrieve the size of the decal by using the IDirect3DRMTexture::GetDecalSize method.) The decal is then transformed and perspective projection is applied.

Decals have origins that your application can set and retrieve by using the IDirect3DRMTexture::SetDecalOrigin and IDirect3DRMTexture::GetDecalOrigin methods. The origin is an offset from the top-left corner of the decal. The default origin is [0, 0]. The decal's origin is aligned with its frame's position when rendering.

Texture Colors

You can set and retrieve the number of colors that are used to render a texture by using the IDirect3DRMTexture::SetColors and IDirect3DRMTexture::GetColors methods.

If your application uses the RGB color model, you can use 8-bit, 24-bit, and 32-bit textures. If you use the monochromatic (or ramp) color model, however, you can use only 8-bit textures.

Several shades of each color are used when lighting a scene. An application can set and retrieve the number of shades used for each color by calling the IDirect3DRMTexture::SetShades and IDirect3DRMTexture::GetShades methods.

A Direct3DRMTexture object uses a D3DRMIMAGE structure to define the bitmap that the texture will be rendered from. If the application provides the D3DRMIMAGE structure, the texture can easily be animated or altered during rendering.

Mipmaps

A mipmap is a sequence of textures, each of which is a progressively lower resolution, prefiltered representation of the same image. Mipmapping is a computationally low-cost way of improving the quality of rendered textures. Each prefiltered image, or level, in the mipmap is a power of two smaller than the previous level. You can specify mipmaps when filtering textures by calling the IDirect3DRMDevice::SetTextureQuality method.

For more information about mipmaps, see Mipmaps.

Texture Filtering

After a texture has been mapped to a surface, the texture elements (texels) of the texture rarely correspond to individual pixels in the final image. A pixel in the final image can correspond to a large collection of texels or to a small piece of a single texel. You can use texture filtering to specify how to interpolate texel values to pixels.

You can use the IDirect3DRMDevice::SetTextureQuality method and the D3DRMTEXTUREQUALITY enumerated type to specify the texture filtering mode for your application.

Texture Transparency

You can use the IDirect3DRMTexture::SetDecalTransparency method to produce transparent textures. Another method for achieving transparency is to use DirectDraw's support for color keys. Color keys are colors or ranges of colors that can be part of either the source or destination of a blit or overlay operation. You can specify that these colors should always be overwritten or never be overwritten.

For more information about DirectDraw's support for color keys, see Color Keying.

Texture Format Selection Rules

When you use a device-independent source image to create a device-dependent texture surface for rendering, the rules are (in order of precedence):

1. Preserve RGB/palettized nature

2. Preserve alpha channel

3. Preserve bit depth or palette size

4. Preserve RBGA masks

5. Prefer 8-bit palettized or 16-bit RGB

For more information about texture pixel formats, see Texture Map Formats.

For related information, see IDirect3DRMTexture and IDirect3DRMTexture2.

IDirect3DRMUserVisual Interface

User-visual objects are application-defined data that an application can add to a scene and then render, typically by using a customized rendering module. For example, an application could add sound as a user-visual object in a scene, and then render the sound during playback.

You can use the IDirect3DRM::CreateUserVisual method to create a user-visual object and the IDirect3DRMUserVisual::Init method to initialize the object.

IDirect3DRMViewport and IDirect3DRMViewportArray Interface

The viewport defines how the 3-D scene is rendered into a 2-D window. The viewport defines a rectangular area on a device that objects will be rendered into.

For a reference to the methods of this interface, see IDirect3DRMViewport.

This section describes the viewport, its components, and techniques for their use.

  • Camera
  • Viewing Frustum
  • Transformations
  • Picking

Camera

The viewport uses a Direct3DRMFrame object as a camera. The camera frame defines which scene is rendered and the viewing position and direction. The viewport renders only what is visible along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.

An application can call the IDirect3DRMViewport::SetCamera method to set a camera for a given viewport. This method sets a viewport's position, direction, and orientation to that of the given camera frame. To retrieve the current camera settings, call the IDirect3DRMViewport::GetCamera method.

Viewing Frustum

The viewing frustum is a 3-D volume in a scene positioned relative to the viewport's camera. For perspective viewing, the camera is positioned at the tip of an imaginary pyramid. This pyramid is intersected by two clipping planes, the front clipping plane and the back clipping plane. The volume in the pyramid between the front and back clipping planes is the viewing frustum. Only objects in the viewing frustum are visible.

Diagram showing the front and back clipping plane and the viewing frustum

The z-axis of the camera runs from the tip of the pyramid to the center of the back clipping plane. Your application can set and retrieve the positions of the front and back clipping planes by using the IDirect3DRMViewport::SetFront, IDirect3DRMViewport::SetBack, IDirect3DRMViewport::GetFront, and IDirect3DRMViewport::GetBack methods.

The dimensions of the viewport on the front clipping plane determine the apparent focal length of the camera's lens. (You can also think of this as a way to set the magnification of objects in the frustum.) To set and retrieve proportional dimensions for the viewport on the front clipping plane, use the IDirect3DRMViewport::SetField and IDirect3DRMViewport::GetField methods. To set and retrieve arbitrary dimensions for the viewport on the front clipping plane, use the IDirect3DRMViewport::SetPlane and IDirect3DRMViewport::GetPlane methods.

You can use the following equation to determine the relationship between the height (or width) of the front clipping plane and the viewing angle:

Equation showing relationship between the front clipping plane and the viewing angle

In this formula, the viewing angle is A, the front clipping plane is a distance D from the camera, and the height or width of the front clipping plane is 2h. If the device is not square, and thus the clipping planes are not square, the viewing angle is calculated using half the height or half the width of the front clipping plane, whichever is larger. The scale factors are set to the major axis of the device so you don't get distorted objects. If this is not what you want, you need to set uniform scaling.

Illustration of the dimensions used in the previous equation

The viewing frustum is a pyramid only for perspective viewing. For orthographic viewing, the viewing frustum is cuboid. These viewing types (or projection types) are defined by the D3DRMPROJECTIONTYPE enumerated type and used by the IDirect3DRMViewport::GetProjection and IDirect3DRMViewport::SetProjection methods.

Transformations

To render objects with 3-D coordinates in a 2-D window, the object must be transformed into the camera's frame. A projection matrix is then used to give a four-element homogeneous coordinate [x y z w], which is used to derive a three-element coordinate [x/w y/w z/w], where [x/w y/w] is the coordinate to be used in the window and z/w is the depth, ranging from 0 at the front clipping plane to 1 at the back clipping plane. The projection matrix is a combination of a perspective transformation followed by a scaling and translation to scale the objects into the window.

The following values are the elements of the projection matrix. In these formulas, h is the half-height of the viewing frustum, F is the distance from the camera, and D is the position in z-coordinates of the front clipping plane:

After projection, the next step is clipping and the conversion of x and y to screen-pixel coordinates within a viewport. Use the D3DVIEWPORT data members for this. The viewport is a rectangular window on the rendering surface.

typedef struct _D3DVIEWPORT {
    DWORD    dwSize;
    DWORD    dwX;
    DWORD    dwY;
    DWORD    dwWidth;
    DWORD    dwHeight;
    D3DVALUE dvScaleX;
    D3DVALUE dvScaleY;
    D3DVALUE dvMaxX;
    D3DVALUE dvMaxY;
    D3DVALUE dvMinZ;
    D3DVALUE dvMaxZ;
} D3DVIEWPORT, *LPD3DVIEWPORT;

The dwX and dwY fields specify the offset in screen pixels to the top left of the viewport on the surface.

The dwWidth and dwHeight fields are the width and height of the viewport in screen pixels.

The dvScaleX and dvScaleY fields are the scaling factors that are applied to the x and y values to yield screen coordinates. You would usually want to map the entire normalized perspective view volume onto the viewport using the following formulas:

  dvScaleX = dwWidth / 2
  dvScaleY = dwHeight / 2

X coordinates, for example, in the range of -1 to 1, will be scaled into the range of -dwWidth / 2 to dwWidth / 2. An offset of dwWidth / 2 is then added. This scaling occurs after clipping.

If the window is not square and you would like to preserve a correct aspect ratio, use the larger of the two window dimensions for both scaling values. You will also need to clip some of the view volume.

The dvMaxX, dvMaxY, dvinZ, and dvMaxZ fields specify the clipping planes: x = dvMaxX, x = —dvMaxX, y = dvMaxy, y = —dvMaxY, z = dvMinZ, z = dvMaxZ. To display all of the view volume, for example, you would set dvMaxX = dvMaxY = dvMaxZ = 1 and dvMinZ = 0. As noted above, if you want to preserve the correct aspect ratio on a nonsquare window, you will need to clip some of the view volume. To do so, use the following equations. These equations also work with square viewports, so use them all the time.

dvMaxX = dwWidth / (2 * dvScaleX)
dvMaxY = dwHeight / (2 * dvScaleY)

An application uses the viewport transformation to ensure that the distance by which the object is moved in world coordinates is scaled by the object's distance from the camera to account for perspective. Note that the result from IDirect3DRMViewport::Transform is a four-element homogeneous vector. This avoids the problems associated with coordinates being scaled by an infinite amount near the camera's position.

For information about transformations for frames, see Transformations. For an overview of the mathematics of transformations, see 3-D Transformations.

Picking

Picking is the process of searching for visuals in the scene given a 2-D coordinate in the viewport's window. An application can use the IDirect3DRMViewport::Pick method to retrieve either the closest object in the scene or a depth-sorted list of objects.

IDirect3DRMVisual and IDirect3DRMVisualArray Interfaces

Visuals are objects that can be rendered in a scene. Visuals are visible only when they are added to a frame in that scene. An application can add a visual to a frame by using the IDirect3DRMFrame::AddVisual method. The frame provides the visual with position and orientation for rendering.

You should use the IDirect3DRMVisualArray interface to work with groups of visual objects; although there is a IDirect3DRMVisual COM interface, it has no methods.

The most common visual types are Direct3DRMMeshBuilder and Direct3DRMTexture objects.

IDirect3DRMWrap Interface

You can use a wrap to calculate texture coordinates for a face or mesh. To create a wrap, the application must specify a type, a reference frame, an origin, a direction vector, and an up vector. The application must also specify a pair of scaling factors and an origin for the texture coordinates.

Your application calls the IDirect3DRM::CreateWrap function to create an IDirect3DRMWrap interface. This interface has two unique methods: IDirect3DRMWrap::Apply, which applies a wrap to the vertices of the object, and IDirect3DRMWrap::ApplyRelative, which transforms the vertices of a wrap as it is applied.

In the examples, the direction vector (the v vector) lies along the z-axis, and the up vector (the u vector) lies along the y-axis, with the origin at [0 0 0].

For a reference to the methods of the IDirect3DRMWrap interface, see IDirect3DRMWrap.

This section describes the wrapping flags and the four wrapping types:

  • Wrapping Flags
  • Flat
  • Cylindrical
  • Spherical
  • Chrome

Wrapping Flags

The D3DRMMAPPING type includes the D3DRMMAP_WRAPU and D3DRMMAP_WRAPV flags. These flags determine how the rasterizer interprets texture coordinates. The rasterizer always interpolates the shortest distance between texture coordinates—that is, a line. The path taken by this line, and the valid values for the u- and v-coordinates, varies with the use of the wrapping flags. If either or both flags is set, the line can wrap around the texture edge in the u or v direction, as if the texture had a cylindrical or toroidal topology.

  • In flat wrapping mode, in which neither of the wrapping flags is set, the plane specified by the u- and v-coordinates is an infinite tiling of the texture. In this case, values greater than 1.0 are valid for u and v. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0.5, 0.5).
  • If either D3DRMMAP_WRAPU or D3DRMMAP_WRAPV is set, the texture is a cylinder with an infinite length and a circumference of 1.0. Texture coordinates greater than 1.0 are valid only in the dimension that is not wrapped. The shortest distance between texture coordinates varies with the wrapping flag; if D3DRMMAP_WRAPU is set, the shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0.5).
  • If both D3DRMMAP_WRAPU and D3DRMMAP_WRAPV are set, the texture is a torus. Because the system is closed, texture coordinates greater that 1.0 are invalid. The shortest line between (0.1, 0.1) and (0.9, 0.9) passes through (0, 0).

Although texture coordinates that are outside the valid range may be truncated to valid values, this behavior is not defined.

Typically, applications set a wrap flag for cylindrical wraps when the intersection of the texture edges does not match the edges of the face; applications do not set a wrap flag when more than half of a texture is applied to a single face.

Flat

The flat wrap conforms to the faces of an object as if the texture were a piece of rubber that was stretched over the object.

The [u v] coordinates are derived from a vector [x y z] by using the following equations:

Equations for deriving u-v coordinates from a vector in a flat wrap

In these formulas, s is the window-scaling factor and o is the window origin. The application should choose a pair of scaling factors and offsets that map the ranges of x and y to the range from 0 to 1 for u and v.

Cylindrical

The cylindrical wrap treats the texture as if it were a piece of paper that is wrapped around a cylinder so that the left edge is joined to the right edge. The object is then placed in the middle of the cylinder and the texture is deformed inward onto the surface of the object.

For a cylindrical texture map, the effects of the various vectors are shown in the following illustration.

Diagram showing the effects of vectors on a cylindrical wrap

The direction vector specifies the axis of the cylinder, and the up vector specifies the point on the outside of the cylinder where u equals 0. To calculate the texture [u v] coordinates for a vector [x y z], the system uses the following equations:

Equations for deriving u-v coordinates from a vector in a cylindrical wrap

Typically, u would be left unscaled and v would be scaled and translated so that the range of z maps to the range from 0 to 1 for v.

Spherical

For a spherical wrap, the u-coordinate is derived from the angle that the vector [x y 0] makes with the x-axis (as in the cylindrical map) and the v-coordinate from the angle that the vector [x y z] makes with the z-axis. Note that this mapping causes distortion of the texture at the z-axis.

Diagram showing the effects of vectors on a spherical wrap

This translates to the following equations:

Equations for deriving u-v coordinates from a vector in a spherical wrap

The scaling factors and texture origin will often not be needed here as the unscaled range of u and v is already 0 through 1.

Chrome

A chrome wrap allocates texture coordinates so that the texture appears to be reflected onto the objects. The chrome wrap takes the reference frame position and uses the vertex normals in the mesh to calculate reflected vectors. The texture u- and v-coordinates are then calculated from the intersection of these reflected vectors with an imaginary sphere that surrounds the mesh. This gives the effect of the mesh reflecting whatever is wrapped on the sphere.


Direct3D Retained Mode Tutorial

To create a Microsoft® Windows®-based, Direct3D® Retained Mode application, you set up the features of two different environments: the devices, viewports, and color capabilities of the Windows environment, and the models, textures, lights, and positions of the virtual environment. This section is a tutorial that contains all the code for a simple Retained Mode application. The following illustration is a single frame from the running animation:

The tutorial is divided into the following sections:

  • Making the Helworld Sample
  • Definitions and Global Variables
  • Windows Setup and Initialization
  • Enumerating Device Drivers
  • Setting up the 3-D Environment
  • The Rendering Loop
  • Creating the Scene
  • Cleaning Up

Making the Helworld Sample

This tutorial includes all the code for a working Direct3D Retained Mode application. You can copy the code from this tutorial into a single .c file and then compile and run it if the following conditions are met:

  • You have the Direct3D header files (D3d.h, D3drm.h, and so on) in your include path.
  • You link with the Winmm.lib, D3drm.lib, and Ddraw.lib static libraries.
  • Your compiler can find the Sphere3.x file in the media directory of the Microsoft® DirectX® Software Development Kit.
  • You supply a bitmap called Tutor.bmp.

    Note that this bitmap must have pixel dimensions that are a power of 2; for example, a 16×16 pixel bitmap, a 128×1024 pixel bitmap, a 512×256 pixel bitmap, and so on.

Most of the code responsible for 3-D effects in this sample has been broken out into discrete functions so that you can modify parts of the system incrementally in your own experiments. You should look at the samples in the SDK for implementations of more complicated features of Direct3D.

The following topics describe some of the concerns that apply to the overall development of a simple Direct3D Retained Mode application.

  • Limitations of the Sample
  • DirectDraw Windowed Mode

Limitations of the Sample

This tutorial contains the Helworld.c example code, which creates a sphere, applies a texture to it, and rotates it in a window. This is the only C source file required to build this application. The only other files you need are Sphere3.x, a mesh file that ships in the Media directory of the DirectX SDK; and Tutor.bmp, a bitmap you supply. (Note that you must have the Direct3D header files in your include path and link to the Winmm.lib, D3drm.lib, and Ddraw.lib static libraries.)

This tutorial is a simplified version of the Globe sample that is part of the DirectX SDK. The Globe sample, like all the Direct3D Retained Mode samples in the SDK, requires the inclusion of a file named Rmmain.cpp and a number of header files. In Helworld.c, the relevant parts of Rmmain.cpp have been converted to C from C++ and integrated into the source code.

The code shown in this tutorial should not be mistaken for production code. The only possible user interactions with the program are starting it, stopping it, and minimizing the window while it is running. Most of the error checking has been removed for clarity. The purpose of this example is analogous to the purpose of the beginning program that prints "Hello, world!" on the screen: to produce output with as little confusion as possible.

DirectDraw Windowed Mode

Nearly all Direct3D applications will use DirectDraw® to display their graphics on the screen. These applications will either use DirectDraw full-screen (exclusive) mode or DirectDraw windowed mode. The code in this documentation uses windowed mode. Although the full-screen mode offers some benefits in performance and convenience, it is much easier to debug code written in windowed mode. Most developers will write their code in windowed mode and port it to full-screen mode late in the development cycle, when most of the bugs have been worked out.

Definitions and Global Variables

Below are the first lines of the Helworld.c example. Helworld.c is the only C source file required to build this application.

Notice that INITGUID must be defined prior to all other includes and defines. This is a crucial point that is sometimes missed by developers who are new to DirectX.

/////////////////////////////////////////////////////////////////////
//
//  Copyright (C) 1996 Microsoft Corporation. All Rights Reserved.
//
//  File: Helworld.c
//
//  Simplified Direct3D Retained Mode example, based on
//  the "Globe" SDK sample.
//
/////////////////////////////////////////////////////////////////////

#define INITGUID           // Must precede other defines and includes

#include <windows.h>
#include <malloc.h>        // Required by memset call
#include <d3drmwin.h>

#define MAX_DRIVERS 5           // Maximum D3D drivers expected

// Global variables

LPDIRECT3DRM lpD3DRM;           // Direct3DRM object
LPDIRECTDRAWCLIPPER lpDDClipper;// DirectDrawClipper object

struct _myglobs {
    LPDIRECT3DRMDEVICE dev;     // Direct3DRM device
    LPDIRECT3DRMVIEWPORT view;  // Direct3DRM viewport through which
                                // the scene is viewed
    LPDIRECT3DRMFRAME scene;    // Master frame in which others are
                                // placed
    LPDIRECT3DRMFRAME camera;   // Frame describing the user's POV

    GUID DriverGUID[MAX_DRIVERS];     // GUIDs of available D3D drivers
    char DriverName[MAX_DRIVERS][50]; // Names of available D3D drivers
    int  NumDrivers;                  // Number of available D3D drivers
    int  CurrDriver;                  // Number of D3D driver currently
                                      // being used

    BOOL bQuit;                 // Program is about to terminate
    BOOL bInitialized;          // All D3DRM objects are initialized
    BOOL bMinimized;            // Window is minimized

    int BPP;                    // Bit depth of the current display mode

} myglobs;

// Function prototypes.

static BOOL InitApp(HINSTANCE, int);
long FAR PASCAL WindowProc(HWND, UINT, WPARAM, LPARAM);
static BOOL EnumDrivers(HWND win);
static HRESULT WINAPI enumDeviceFunc(LPGUID lpGuid,
    LPSTR lpDeviceDescription, LPSTR lpDeviceName,
    LPD3DDEVICEDESC lpHWDesc, LPD3DDEVICEDESC lpHELDesc,
    LPVOID lpContext);
static DWORD BPPToDDBD(int bpp);
static BOOL CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper,
    int driver, int width, int height);
static BOOL SetRenderState(void);
static BOOL RenderLoop(void);
static BOOL MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,
    LPDIRECT3DRMFRAME scene, LPDIRECT3DRMFRAME camera);
void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME * lplpLightFrame1,
    LPDIRECT3DRMFRAME * lplpWorld_frame);
void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2);
void SetMyPositions(LPDIRECT3DRMFRAME lpScene,
    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMFRAME lpWorld_frame);
void MakeMyMesh(LPDIRECT3DRMMESHBUILDER * lplpSphere3_builder);
void MakeMyWrap(LPDIRECT3DRMMESHBUILDER sphere3_builder,
                LPDIRECT3DRMWRAP * lpWrap);
void AddMyTexture(LPDIRECT3DRMMESHBUILDER lpSphere3_builder,
                  LPDIRECT3DRMTEXTURE * lplpTex);
static void CleanUp(void);

Windows Setup and Initialization

This section describes the standard setup and initialization functions in a Windows program, as implemented in the Helworld.c sample code.

  • The WinMain Function
  • The InitApp Function
  • The Main Window Procedure

The WinMain Function

The WinMain function in Helworld.c has only a few lines of code that are unique to an application that uses DirectDraw and Direct3D Retained Mode. The InitApp and CleanUp functions are standard parts of a Windows program, although in the case of Helworld, they perform some unique tasks. The most important call in WinMain, from the perspective of Direct3D, is the call to the RenderLoop function. RenderLoop is responsible for drawing each new frame of the animation. For more information about the RenderLoop function, see The Rendering Loop.

/////////////////////////////////////////////////////////////////////
//
// WinMain
// Initializes the application and enters a message loop.
// The message loop renders the scene until a quit message is received.
//
/////////////////////////////////////////////////////////////////////

int PASCAL
WinMain (HINSTANCE this_inst, HINSTANCE prev_inst, LPSTR cmdline,
    int cmdshow)
{
    MSG     msg;
    HACCEL  accel = NULL;
    int     failcount = 0;  // Number of times RenderLoop has failed

    prev_inst;
    cmdline;

    // Create the window and initialize all objects needed to begin
    // rendering.

    if (!InitApp(this_inst, cmdshow))
        return 1;

    while (!myglobs.bQuit) {

        // Monitor the message queue until there are no pressing
        // messages.

        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {
            if (!TranslateAccelerator(msg.hwnd, accel, &msg)) {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }

        // If the app is not minimized, not about to quit, and D3DRM has
        // been initialized, begin rendering.

        if (!myglobs.bMinimized && !myglobs.bQuit &&
             myglobs.bInitialized) {

            // Attempt to render a frame. If rendering fails more than
            // twice, abort execution.

            if (!RenderLoop())
                ++failcount;
            if (failcount > 2) {
                CleanUp();
                break;
            }
        }
    }
    return msg.wParam;
}

The InitApp Function

The initialization function in Helworld.c creates the window class and main application window, just as in most Windows-based applications. After this, however, it does some work that is unique to applications using DirectDraw and Direct3D.

Next, InitApp retrieves the current display's bits per pixel. This information is used to help set the rendering quality for the application. For more information, see Setting the Render State.

InitApp then uses the locally defined EnumDrivers function to determine which Direct3D drivers are available and to choose one. For more information about enumerating drivers, see Enumerating Device Drivers.

Next, the code uses the Direct3DRMCreate function to create an IDirect3DRM interface. It uses this interface in the calls to IDirect3DRM::CreateFrame and IDirect3DRMFrame::SetPosition that create the scene and camera frames, and position the camera in the scene.

A DirectDrawClipper object makes it simple to manage the clipping planes that control which parts are visible of a 3-D scene. Helworld.c uses the DirectDrawCreateClipper function to create an IDirectDrawClipper interface, and then uses the IDirectDrawClipper::SetHWnd method to set the window handle that obtains the clipping information.

Now the InitApp function uses the locally defined CreateDevAndView function to create the Direct3D device and viewport. For more information about this function, see Creating the Device and Viewport.

When the entire supporting structure of a Direct3D application has been put into place, the details of the 3-D scene can be constructed. The MyScene function does this. For more information about MyScene, see Creating the Device and Viewport.

Finally, just as in a standard initialization function, InitApp shows and updates the window.

/////////////////////////////////////////////////////////////////////
//
// InitApp
// Creates window and initializes all objects necessary to begin
// rendering.
//
/////////////////////////////////////////////////////////////////////

static BOOL
InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;
    HDC hdc;
    WNDCLASS wc;
    RECT rc;

    // Set up and register the window class.

    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(this_inst, "AppIcon");
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (!RegisterClass(&wc))
        return FALSE;

    // Initialize the global variables.

    memset(&myglobs, 0, sizeof(myglobs));

    // Create the window.

    win =
        CreateWindow
        (   "D3DRM Example",            // Class
            "Hello World (Direct3DRM)", // Title bar
            WS_VISIBLE | WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU |
                 WS_MINIMIZEBOX | WS_MAXIMIZEBOX,
            CW_USEDEFAULT,              // Init. x pos
            CW_USEDEFAULT,              // Init. y pos
            300,                        // Init. x size
            300,                        // Init. y size
            NULL,                       // Parent window
            NULL,                       // Menu handle
            this_inst,                  // Program handle
            NULL                        // Create parms
        );
    if (!win)
        return FALSE;

    // Record the current display bits-per-pixel.

    hdc = GetDC(win);
    myglobs.BPP = GetDeviceCaps(hdc, BITSPIXEL);
    ReleaseDC(win, hdc);

    // Enumerate the D3D drivers and select one.

    if (!EnumDrivers(win))
        return FALSE;

    // Create the D3DRM object and the D3DRM window object.

    lpD3DRM = NULL;
    Direct3DRMCreate(&lpD3DRM);

    // Create the master scene frame and camera frame.

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, NULL, &myglobs.scene);
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, myglobs.scene,
        &myglobs.camera);
    myglobs.camera->lpVtbl->SetPosition(myglobs.camera, myglobs.scene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));

    // Create a DirectDrawClipper object and associate the
    // window with it.

    DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    lpDDClipper->lpVtbl->SetHWnd(lpDDClipper, 0, win);

    // Create the D3DRM device by using the selected D3D driver.

    GetClientRect(win, &rc);
    if (!CreateDevAndView(lpDDClipper, myglobs.CurrDriver, rc.right,
            rc.bottom)) {
        return FALSE;
    }

    // Create the scene to be rendered.

    if (!MyScene(myglobs.dev, myglobs.view, myglobs.scene,
            myglobs.camera))
        return FALSE;

    myglobs.bInitialized = TRUE;  // Initialization completed

    // Display the window.

    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return TRUE;
}

The Main Window Procedure

The Helworld.c sample has a very simple main window procedure—after all, the application allows practically no user interaction.

When the window procedure receives a WM_DESTROY message, it uses the CleanUp function, just as you would expect.

When it receives a WM_ACTIVATE message, it retrieves an IDirect3DRMWinDevice interface and uses the IDirect3DRMWinDevice::HandleActivate method to ensure that the colors are correct in the active rendering window. Similarly, the function reacts to a WM_PAINT message by using the IDirect3DRMWinDevice::HandlePaint method.

/////////////////////////////////////////////////////////////////////
//
// WindowProc
// Main window message handler.
//
/////////////////////////////////////////////////////////////////////

LONG FAR PASCAL WindowProc(HWND win, UINT msg,
    WPARAM wparam, LPARAM lparam)
{
    RECT r;
    PAINTSTRUCT ps;
    LPDIRECT3DRMWINDEVICE lpD3DRMWinDev;

    switch (msg)    {

    case WM_DESTROY:
        CleanUp();
        break;

    case WM_ACTIVATE:
        {

        // Create a Windows-specific Direct3D Retained Mode window device to handle this
        // message.

        LPDIRECT3DRMWINDEVICE lpD3DRMWinDev;
        if (!myglobs.dev)
            break;
        myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,
            &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);
        lpD3DRMWinDev->lpVtbl->HandleActivate(lpD3DRMWinDev,
            (WORD) wparam);
        lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);
        }
        break;

    case WM_PAINT:
        if (!myglobs.bInitialized || !myglobs.dev)
            return DefWindowProc(win, msg, wparam, lparam);

        // Create a Windows-specific Direct3D Retained Mode window device to handle this
        // message.

        if (GetUpdateRect(win, &r, FALSE)) {
            BeginPaint(win, &ps);
            myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,
                &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);
            lpD3DRMWinDev->lpVtbl->HandlePaint(lpD3DRMWinDev, ps.hdc);
            lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);
            EndPaint(win, &ps);
        }
        break;
    default:
        return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

Enumerating Device Drivers

Applications that use Direct3D always enumerate the available drivers and choose the one that best matches their needs. The following sections each describe one of the functions that perform this task:

  • The EnumDrivers Function
  • The enumDeviceFunc Callback Function
  • The BPPToDDBD Helper Function

The EnumDrivers Function

The EnumDrivers function is used by the InitApp function just before InitApp creates the application's scene and camera.

The IDirect3D Component Object Model (COM) interface is really an interface to a DirectDraw object, so the first thing this enumeration function does is use the DirectDrawCreate function to create a DirectDrawObject. Then EnumDrivers uses the QueryInterface method to create an IDirect3D interface. Notice that the C implementation of QueryInterface requires that you pass the address of the interface identifier as the second parameter, not simply the constant itself (like in the C++ implementation).

The enumeration is handled by the IDirect3D::EnumDevices method, which depends on the locally defined enumDeviceFunc callback function. For more information about this callback function, see The enumDeviceFunc Callback Function.

Notice that IDirect3D::EnumDevices is a Direct3D method, not a Direct3DRM method; there is no enumeration method in the Retained Mode API. This is a good example of the natural use of both Retained Mode and Immediate Mode methods in a single application.

/////////////////////////////////////////////////////////////////////
//
// EnumDrivers
// Enumerate the available D3D drivers and choose one.
//
/////////////////////////////////////////////////////////////////////

static BOOL
EnumDrivers(HWND win)
{
    LPDIRECTDRAW lpDD;
    LPDIRECT3D lpD3D;
    HRESULT rval;

    // Create a DirectDraw object and query for the Direct3D interface
    // to use to enumerate the drivers.

    DirectDrawCreate(NULL, &lpDD, NULL);
    rval = lpDD->lpVtbl->QueryInterface(lpDD, &IID_IDirect3D,
        (void**) &lpD3D);
    if (rval != DD_OK) {
        lpDD->lpVtbl->Release(lpDD);
        return FALSE;
    }

    // Enumerate the drivers, setting CurrDriver to -1 to initialize the
    // driver selection code in enumDeviceFunc.

    myglobs.CurrDriver = -1;
    lpD3D->lpVtbl->EnumDevices(lpD3D, enumDeviceFunc,
        &myglobs.CurrDriver);

    // Ensure at least one valid driver was found.

    if (myglobs.NumDrivers == 0) {
        return FALSE;
    }
    lpD3D->lpVtbl->Release(lpD3D);
    lpDD->lpVtbl->Release(lpDD);

    return TRUE;
}

The enumDeviceFunc Callback Function

The enumDeviceFunc callback function is of the D3DENUMDEVICESCALLBACK type, as defined in the D3dcaps.h header file. The system uses this function with identifiers and names for each Direct3D driver in the system, as well as the hardware and emulated capabilities of the driver.

The callback function uses the dcmColorModel member of the D3DDEVICEDESC structure to determine whether to examine the hardware or emulated driver description. If the member has been filled by the hardware description, the function consults the hardware description.

Next, the callback function determines whether the driver being enumerated can render in the current bit depth. If not, the function returns D3DENUMRET_OK to skip the rest of the process for this driver and continue the enumeration with the next driver. The callback function uses the locally defined BPPToDDBD function to compare the reported bit depth against the bits-per-pixel retrieved by the call to the GetDeviceCaps function in the InitApp function. (BPPToDDBD stands for bits-per-pixel to DirectDraw bit-depth.) For the code for this function, see The BPPToDDBD Helper Function.

If the driver being enumerated passes a few simple tests, other parts of D3DDEVICEDESC are examined. The callback function will choose hardware over software emulation, and RGB lighting capabilities over monochromatic lighting capabilities.

/////////////////////////////////////////////////////////////////////
//
// enumDeviceFunc
// Callback function that records each usable D3D driver's name
// and GUID. Chooses a driver and sets *lpContext to this driver.
//
/////////////////////////////////////////////////////////////////////

static HRESULT
WINAPI enumDeviceFunc(LPGUID lpGuid, LPSTR lpDeviceDescription,
    LPSTR lpDeviceName, LPD3DDEVICEDESC lpHWDesc,
    LPD3DDEVICEDESC lpHELDesc, LPVOID lpContext)
{
    static BOOL hardware = FALSE; // Current start driver is hardware
    static BOOL mono = FALSE;     // Current start driver is mono light
    LPD3DDEVICEDESC lpDesc;
    int *lpStartDriver = (int *)lpContext;

    // Decide which device description should be consulted.

    lpDesc = lpHWDesc->dcmColorModel ? lpHWDesc : lpHELDesc;

    // If this driver cannot render in the current display bit-depth,
    // skip it and continue with the enumeration.

    if (!(lpDesc->dwDeviceRenderBitDepth & BPPToDDBD(myglobs.BPP)))
        return D3DENUMRET_OK;

    // Record this driver's name and GUID.

    memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid,
        sizeof(GUID));
    lstrcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);

    // Choose hardware over software, RGB lights over mono lights.

    if (*lpStartDriver == -1) {

        // This is the first valid driver.

        *lpStartDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ? TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;
    } else if (lpDesc == lpHWDesc && !hardware) {

        // This driver is hardware and the start driver is not.

        *lpStartDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ? TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;
    } else if ((lpDesc == lpHWDesc && hardware ) ||
               (lpDesc == lpHELDesc && !hardware)) {
        if (lpDesc->dcmColorModel == D3DCOLOR_MONO && !mono) {

            // This driver and the start driver are the same type, and
            // this driver is mono whereas the start driver is not.

            *lpStartDriver = myglobs.NumDrivers;
            hardware = lpDesc == lpHWDesc ? TRUE : FALSE;
            mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ? TRUE : FALSE;
        }
    }
    myglobs.NumDrivers++;
    if (myglobs.NumDrivers == MAX_DRIVERS)
        return (D3DENUMRET_CANCEL);
    return (D3DENUMRET_OK);
}

The BPPToDDBD Helper Function

The enumDeviceFunc callback function uses the BPPToDDBD helper function to convert the stored bits-per-pixel the current device supports to a form that can be compared against the bit depth for the driver being enumerated. For more information about enumDeviceFunc, see The enumDeviceFunc Callback Function.

/////////////////////////////////////////////////////////////////////
//
// BPPToDDBD
// Converts bits-per-pixel to a DirectDraw bit-depth flag.
//
/////////////////////////////////////////////////////////////////////

static DWORD
BPPToDDBD(int bpp)
{
    switch(bpp) {
        case 1:
            return DDBD_1;
        case 2:
            return DDBD_2;
        case 4:
            return DDBD_4;
        case 8:
            return DDBD_8;
        case 16:
            return DDBD_16;
        case 24:
            return DDBD_24;
        case 32:
            return DDBD_32;
        default:
            return 0;
    }
}

Setting up the 3-D Environment

This section describes the code in Helworld.c that establishes the 3-D environment. The following sections describe the two functions that perform this task:

  • Creating the Device and Viewport
  • Setting the Render State

These functions do not populate the 3-D environment with objects, frames, and lights. That is done by the MyScene function and the functions it uses. For information about filling up the 3-D environment, see Creating the Scene.

Creating the Device and Viewport

The Direct3D device and viewport are created as part of the application's initialization. After creating a DirectDrawClipper object, the InitApp function uses CreateDevAndView, passing as parameters the DirectDrawClipper object, the driver that was chosen, and the dimensions of the client rectangle.

The CreateDevAndView function uses the IDirect3DRM::CreateDeviceFromClipper method to create a Direct3DRM device, using the driver that was selected by the enumeration process. It uses this IDirect3DRMDevice interface to retrieve the device's width and height, by using IDirect3DRMDevice::GetWidth and IDirect3DRMDevice::GetHeight methods. After it has retrieved this information, it uses the IDirect3DRM::CreateViewport method to retrieve the IDirect3DRMViewport interface.

When CreateDevAndView has used the IDirect3DRMViewport::SetBack method to set the back clipping plane of the viewport, it uses the locally defined SetRenderState function. SetRenderState is described in the next section, Setting the Render State.

/////////////////////////////////////////////////////////////////////
//
// CreateDevAndView
// Create the D3DRM device and viewport with the given D3D driver and
// with the specified size.
//
/////////////////////////////////////////////////////////////////////

static BOOL
CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper, int driver,
    int width, int height)
{
    HRESULT rval;

    // Create the D3DRM device from this window by using the specified
    // D3D driver.

    lpD3DRM->lpVtbl->CreateDeviceFromClipper(lpD3DRM, lpDDClipper,
        &myglobs.DriverGUID[driver], width, height, &myglobs.dev);

    // Create the D3DRM viewport by using the camera frame. Set the
    // background depth to a large number. The width and height
    // might have been slightly adjusted, so get them from the device.

    width = myglobs.dev->lpVtbl->GetWidth(myglobs.dev);
    height = myglobs.dev->lpVtbl->GetHeight(myglobs.dev);
    rval = lpD3DRM->lpVtbl->CreateViewport(lpD3DRM, myglobs.dev,
        myglobs.camera, 0, 0, width, height, &myglobs.view);
    if (rval != D3DRM_OK) {
        myglobs.dev->lpVtbl->Release(myglobs.dev);
        return FALSE;
    }
    rval = myglobs.view->lpVtbl->SetBack(myglobs.view, D3DVAL(5000.0));
    if (rval != D3DRM_OK) {
        myglobs.dev->lpVtbl->Release(myglobs.dev);
        myglobs.view->lpVtbl->Release(myglobs.view);
        return FALSE;
    }

    // Set the render quality, fill mode, lighting state,
    // and color shade info.

    if (!SetRenderState())
        return FALSE;
    return TRUE;
}

Setting the Render State

Direct3D is a state machine; applications set up the state of the lighting, rendering, and transformation modules and then pass data through them. This architecture is integral to Immediate Mode, but it is partially hidden by the Retained Mode API. The SetRenderState function is a simple way to set the rendering state for a Retained Mode application.

First, SetRenderState uses the IDirect3DRMDevice::SetQuality method, specifying that the lights are on, that the fill mode is solid, and that Gouraud shading should be used. At this point, applications that need to change the dithering mode or texture quality can use the IDirect3DRMDevice::SetDither or IDirect3DRMDevice::SetTextureQuality methods.

/////////////////////////////////////////////////////////////////////
//
// SetRenderState
// Set the render quality and shade information.
//
/////////////////////////////////////////////////////////////////////

BOOL
SetRenderState(void)
{
    HRESULT rval;

    // Set the render quality (light toggle, fill mode, shade mode).

    rval = myglobs.dev->lpVtbl->SetQuality(myglobs.dev,
        D3DRMLIGHT_ON | D3DRMFILL_SOLID | D3DRMSHADE_GOURAUD);
    if (rval != D3DRM_OK) {
        return FALSE;
    }

    // If you want to change the dithering mode, use SetDither here.

    // If you want a texture quality other than D3DRMTEXTURE_NEAREST
    // (the default value), use SetTextureQuality here.

   return TRUE;
}

The Rendering Loop

The WinMain function uses the RenderLoop function to draw each new frame of the animation. The RenderLoop function performs a few simple tasks:

  • Uses the IDirect3DRMFrame::Move method to apply the rotations and velocities for all frames in the hierarchy.
  • Uses the IDirect3DRMViewport::Clear method to clear the current viewport, setting it to the current background color.
  • Uses the IDirect3DRMViewport::Render method to render the current scene into the current viewport.
  • Uses the IDirect3DRMDevice::Update method to copy the rendered image to the display.
/////////////////////////////////////////////////////////////////////
//
// RenderLoop
// Clear the viewport, render the next frame, and update the window.
//
/////////////////////////////////////////////////////////////////////

static BOOL
RenderLoop()
{
    HRESULT rval;

    // Tick the scene.

    rval = myglobs.scene->lpVtbl->Move(myglobs.scene, D3DVAL(1.0));
    if (rval != D3DRM_OK) {
        return FALSE;
    }

    // Clear the viewport.

    rval = myglobs.view->lpVtbl->Clear(myglobs.view);
    if (rval != D3DRM_OK) {
        return FALSE;
    }

    // Render the scene to the viewport.

    rval = myglobs.view->lpVtbl->Render(myglobs.view, myglobs.scene);
    if (rval != D3DRM_OK) {
        return FALSE;
    }

    // Update the window.

    rval = myglobs.dev->lpVtbl->Update(myglobs.dev);
    if (rval != D3DRM_OK) {
        return FALSE;
    }
    return TRUE;
}

Creating the Scene

After setting up the 3-D environment—choosing a device driver, creating the 3-D device and viewport, setting the rendering state, and so on—Helworld.c uses a series of functions to populate this 3-D environment with objects, frames, and lights:

  • The MyScene Function
  • The MakeMyFrames Function
  • The MakeMyLights Function
  • The SetMyPositions Function
  • The MakeMyMesh Function
  • The MakeMyWrap Function
  • The AddMyTexture Function

The MyScene Function

The MyScene function in Helworld.c corresponds to the BuildScene function that is implemented in all the Direct3D samples in the DirectX SDK. This is where all the work occurs that displays unique objects with unique textures and lighting effects.

The MyScene function uses a series of locally defined functions that set up the separate features of the scene that is being created. These functions are:

  • MakeMyFrames
  • MakeMyLights
  • SetMyPositions
  • MakeMyMesh
  • MakeMyWrap
  • AddMyTexture

When these functions have set up the visual object, MyScene uses the IDirect3DRMFrame::AddVisual method to add the object to the environment's world frame. After adding the visual object, MyScene no longer needs the interfaces it has created, so it uses the Release method repeatedly to release them all.

/////////////////////////////////////////////////////////////////////
//
// MyScene
// Uses the functions that create the frames, lights, mesh, and
// texture. Releases all interfaces on completion.
//
/////////////////////////////////////////////////////////////////////

BOOL
MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,
    LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera)
{
    LPDIRECT3DRMFRAME lpLightframe1 = NULL;
    LPDIRECT3DRMFRAME lpWorld_frame = NULL;
    LPDIRECT3DRMLIGHT lpLight1      = NULL;
    LPDIRECT3DRMLIGHT lpLight2      = NULL;
    LPDIRECT3DRMTEXTURE lpTex       = NULL;
    LPDIRECT3DRMWRAP lpWrap         = NULL;
    LPDIRECT3DRMMESHBUILDER lpSphere3_builder = NULL;

    MakeMyFrames(lpScene, lpCamera, &lpLightframe1, &lpWorld_frame);
    MakeMyLights(lpScene, lpCamera, lpLightframe1, &lpLight1,
        &lpLight2);
    SetMyPositions(lpScene, lpCamera, lpLightframe1, lpWorld_frame);
    MakeMyMesh(&lpSphere3_builder);
    MakeMyWrap(lpSphere3_builder, &lpWrap);
    AddMyTexture(lpSphere3_builder, &lpTex);

    // If you need to create a material (for example, to create
    // a shiny surface), use CreateMaterial and SetMaterial here.

    // Now that the visual object has been created, add it
    // to the world frame.

    lpWorld_frame->lpVtbl->AddVisual(lpWorld_frame,
        (LPDIRECT3DRMVISUAL) lpSphere3_builder);

    lpLightframe1->lpVtbl->Release(lpLightframe1);
    lpWorld_frame->lpVtbl->Release(lpWorld_frame);
    lpSphere3_builder->lpVtbl->Release(lpSphere3_builder);
    lpLight1->lpVtbl->Release(lpLight1);
    lpLight2->lpVtbl->Release(lpLight2);
    lpTex->lpVtbl->Release(lpTex);
    lpWrap->lpVtbl->Release(lpWrap);

    return TRUE;
}

The MakeMyFrames Function

The MyScene function uses the MakeMyFrames function to create the frames for the directional light and the world frame used in Helworld.c. MakeMyFrames does this work by using the IDirect3DRM::CreateFrame method.

/////////////////////////////////////////////////////////////////////
//
// MakeMyFrames
// Create frames used in the scene.
//
/////////////////////////////////////////////////////////////////////

void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME * lplpLightFrame1,
    LPDIRECT3DRMFRAME * lplpWorld_frame)
{
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpLightFrame1);
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpWorld_frame);
}

The MakeMyLights Function

The MyScene function uses the MakeMyLights function to create the directional and ambient lights used in Helworld.c. MakeMyLights uses the IDirect3DRM::CreateLightRGB and IDirect3DRMFrame::AddLight methods to create a bright directional light and add it to a light frame, and to create a dim ambient light and add it to the entire scene. (Ambient lights are always associated with an entire scene.)

/////////////////////////////////////////////////////////////////////
//
// MakeMyLights
// Create lights used in the scene.
//
/////////////////////////////////////////////////////////////////////

void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2)
{
    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_DIRECTIONAL,
        D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9), lplpLight1);

    lpLightFrame1->lpVtbl->AddLight(lpLightFrame1, *lplpLight1);

    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_AMBIENT,
        D3DVAL(0.1), D3DVAL(0.1), D3DVAL(0.1), lplpLight2);

    lpScene->lpVtbl->AddLight(lpScene, *lplpLight2);
}

The SetMyPositions Function

The MyScene function uses the SetMyPositions function to set the positions and orientations of the frames used in Helworld.c. SetMyPositions does this work by using the IDirect3DRMFrame::SetPosition and IDirect3DRMFrame::SetOrientation methods. The IDirect3DRMFrame::SetRotation method imparts a spin to the frame to which the sphere will be added.

/////////////////////////////////////////////////////////////////////
//
// SetMyPositions
// Set the positions and orientations of the light, camera, and
// world frames. Establish a rotation for the globe.
//
/////////////////////////////////////////////////////////////////////

void SetMyPositions(LPDIRECT3DRMFRAME lpScene,
    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMFRAME lpWorld_frame)
{

    lpLightFrame1->lpVtbl->SetPosition(lpLightFrame1, lpScene,
        D3DVAL(2), D3DVAL(0.0), D3DVAL(22));

    lpCamera->lpVtbl->SetPosition(lpCamera, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));
    lpCamera->lpVtbl->SetOrientation(lpCamera, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),
        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetPosition(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(15));
    lpWorld_frame->lpVtbl->SetOrientation(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),
        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetRotation(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.1), D3DVAL(0.0), D3DVAL(0.05));
}

The MakeMyMesh Function

The MyScene function uses the MakeMyMesh function to load and set the spherical mesh used in Helworld.c. MakeMyMesh uses the IDirect3DRM::CreateMeshBuilder method to create an IDirect3DRMMeshBuilder interface. Then it uses the IDirect3DRMMeshBuilder::Load, IDirect3DRMMeshBuilder::Scale, and IDirect3DRMMeshBuilder::SetColorRGB methods to prepare the mesh represented by the Sphere3.x file. (The Sphere3.x file is included in the DirectX SDK, as part of the media provided for use with the sample code.)

/////////////////////////////////////////////////////////////////////
//
// MakeMyMesh
// Create MeshBuilder object, load, scale, and color the mesh.
//
/////////////////////////////////////////////////////////////////////

void MakeMyMesh(LPDIRECT3DRMMESHBUILDER * lplpSphere3_builder)
{
    lpD3DRM->lpVtbl->CreateMeshBuilder(lpD3DRM, lplpSphere3_builder);

    (*lplpSphere3_builder)->lpVtbl->Load(*lplpSphere3_builder,
        "sphere3.x", NULL, D3DRMLOAD_FROMFILE, NULL, NULL);

    (*lplpSphere3_builder)->lpVtbl->Scale(*lplpSphere3_builder,
        D3DVAL(2), D3DVAL(2), D3DVAL(2));

    // Set sphere to white to avoid unexpected texture-blending results.

    (*lplpSphere3_builder)->lpVtbl->SetColorRGB(*lplpSphere3_builder,
        D3DVAL(1), D3DVAL(1), D3DVAL(1));
}

The MakeMyWrap Function

The MyScene function uses the MakeMyWrap function to create and apply texture coordinates to the sphere loaded by the MakeMyMesh function. MakeMyWrap uses the IDirect3DRMMeshBuilder::GetBox method to retrieve the bounding box that contains the sphere and uses the dimensions of that bounding box in a call to the IDirect3DRM::CreateWrap method, which creates a cylindrical texture wrap and retrieves the IDirect3DRMWrap interface. A call to the IDirect3DRMWrap::Apply method applies the texture coordinates to the sphere.

/////////////////////////////////////////////////////////////////////
//
// MakeMyWrap
// Creates and applies wrap for texture.
//
/////////////////////////////////////////////////////////////////////

void MakeMyWrap(LPDIRECT3DRMMESHBUILDER sphere3_builder,
                LPDIRECT3DRMWRAP * lpWrap)
{
    D3DVALUE miny, maxy, height;
    D3DRMBOX box;

    sphere3_builder->lpVtbl->GetBox(sphere3_builder, &box);

    maxy = box.max.y;
    miny = box.min.y;
    height = maxy - miny;

    lpD3DRM->lpVtbl->CreateWrap
        (lpD3DRM, D3DRMWRAP_CYLINDER, NULL,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0),
        D3DVAL(0.0), D3DVAL(1.0), D3DVAL(0.0),
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1.0),
        D3DVAL(0.0), D3DDivide(miny, height),
        D3DVAL(1.0), D3DDivide(D3DVAL(1.0), height),
        lpWrap);

    (*lpWrap)->lpVtbl->Apply(*lpWrap, (LPDIRECT3DRMOBJECT)
        sphere3_builder);

}

The AddMyTexture Function

The MyScene function uses the AddMyTexture function to load a texture and associate it with the sphere. AddMyTexture uses the IDirect3DRM::LoadTexture method to load a bitmap called Tutor.bmp, and then it uses the IDirect3DRMMeshBuilder::SetTexture method to associate the bitmap with the sphere.

Bitmap used as a texture on the sphere

/////////////////////////////////////////////////////////////////////
//
// AddMyTexture
// Creates and applies wrap for texture.
//
/////////////////////////////////////////////////////////////////////

void AddMyTexture(LPDIRECT3DRMMESHBUILDER lpSphere3_builder,
    LPDIRECT3DRMTEXTURE * lplpTex)
{
    lpD3DRM->lpVtbl->LoadTexture(lpD3DRM, "tutor.bmp", lplpTex);

    // If you need a color depth other than the default (16),
    // use IDirect3DRMTexture::SetShades here.

    lpSphere3_builder->lpVtbl->SetTexture(lpSphere3_builder, *lplpTex);

}

Cleaning Up

Helworld.c uses the CleanUp function when it receives a WM_DESTROY message or after several consecutive unsuccessful attempts to use the RenderLoop function.

/////////////////////////////////////////////////////////////////////
//
// CleanUp
// Release all D3DRM objects and set the bQuit flag.
//
/////////////////////////////////////////////////////////////////////

void
CleanUp(void)
{
    myglobs.bInitialized = FALSE;
    myglobs.scene->lpVtbl->Release(myglobs.scene);
    myglobs.camera->lpVtbl->Release(myglobs.camera);
    myglobs.view->lpVtbl->Release(myglobs.view);
    myglobs.dev->lpVtbl->Release(myglobs.dev);
    lpD3DRM->lpVtbl->Release(lpD3DRM);
    lpDDClipper->lpVtbl->Release(lpDDClipper);

    myglobs.bQuit = TRUE;
}


Reference

The Microsoft® Direct3D® Retained Mode reference provides detailed information about the interface methods, functions, and callbacks with syntax, parameter descriptions, and flag descriptions. It also describes the members of Direct3D structures, enumerated types, other defined types, and the possible error values that can be returned.

This section contains the following topics:

Functions

Callback Functions

IDirect3DRM Array Interfaces

IDirect3DRM

IDirect3DRM2

IDirect3DRMAnimation

IDirect3DRMAnimationSet

IDirect3DRMDevice

IDirect3DRMDevice2

IDirect3DRMFace

IDirect3DRMFrame

IDirect3DRMFrame2

IDirect3DRMInterpolator

IDirect3DRMLight

IDirect3DRMMaterial

IDirect3DRMMesh

IDirect3DRMMeshBuilder

IDirect3DRMMeshBuilder2

IDirect3DRMObject

IDirect3DRMProgressiveMesh

IDirect3DRMShadow

IDirect3DRMTexture

IDirect3DRMTexture2

IDirect3DRMUserVisual

IDirect3DRMViewport

IDirect3DRMWinDevice

IDirect3DRMWrap

Structures

Enumerated Types

Other Types

Return Values

Further Reading


Functions

The Microsoft® Direct3D® Retained Mode functions are:

  • D3DRMColorGetAlpha
  • D3DRMColorGetBlue
  • D3DRMColorGetGreen
  • D3DRMColorGetRed
  • D3DRMCreateColorRGB
  • D3DRMCreateColorRGBA
  • D3DRMFREEFUNCTION
  • D3DRMMALLOCFUNCTION
  • D3DRMMatrixFromQuaternion
  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMREALLOCFUNCTION
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract
  • Direct3DRMCreate

D3DRMColorGetAlpha

Retrieves the alpha component of a color.

D3DVALUE D3DRMColorGetAlpha(
D3DCOLOR d3drmc
);

Parameters
d3drmc
Color from which the alpha component is retrieved. A value between 0 and 255.
Return Values

Returns the alpha value if successful, or zero otherwise.

See Also

D3DRMColorGetBlue, D3DRMColorGetGreen, D3DRMColorGetRed

D3DRMColorGetBlue

Retrieves the blue component of a color.

D3DVALUE D3DRMColorGetBlue(
D3DCOLOR d3drmc
);

Parameters
d3drmc
Color from which the blue component is retrieved. A value between 0 and 255.
Return Values

Returns the blue value if successful, or zero otherwise.

See Also

D3DRMColorGetAlpha, D3DRMColorGetGreen, D3DRMColorGetRed

D3DRMColorGetGreen

Retrieves the green component of a color.

D3DVALUE D3DRMColorGetGreen(
D3DCOLOR d3drmc
);

Parameters
d3drmc
Color from which the green component is retrieved. A value between 0 and 255.
Return Values

Returns the green value if successful, or zero otherwise.

See Also

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetRed

D3DRMColorGetRed

Retrieves the red component of a color.

D3DVALUE D3DRMColorGetRed(
D3DCOLOR d3drmc
);

Parameters
d3drmc
Color from which the red component is retrieved.
Return Values

Returns the red value if successful, or zero otherwise.

See Also

D3DRMColorGetAlpha, D3DRMColorGetBlue, D3DRMColorGetGreen

Direct3DRMCreate

Creates an instance of a Direct3DRM object.

HRESULT Direct3DRMCreate(
LPDIRECT3DRM FAR * lplpD3DRM
);

Parameters
lplpD3DRM
Address of a pointer that will be initialized with a valid Direct3DRM pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

Direct3DRMObject

D3DRMCreateColorRGB

Creates an RGB color from supplied red, green, and blue components.

D3DCOLOR D3DRMCreateColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
red, green, and blue
Components of the RGB color.
Return Values

Returns the new RGB value if successful, or zero otherwise.

See Also

D3DRMCreateColorRGBA

D3DRMCreateColorRGBA

Creates an RGBA color from supplied red, green, blue, and alpha components.

D3DCOLOR D3DRMCreateColorRGBA(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue,
D3DVALUE alpha
);

Parameters
red, green, blue, and alpha
Components of the RGBA color. Values between 0 and 1.

Return Values

Returns the new RGBA value if successful, or zero otherwise.

See Also

D3DRMCreateColorRGB

D3DRMFREEFUNCTION

Frees memory. This function is application-defined.

typedef VOID (*D3DRMFREEFUNCTION)(LPVOID lpArg);
typedef D3DRMFREEFUNCTION *LPD3DRMFREEFUNCTION;
Parameters
lpArg
Address of application-defined data.
Return Values

No return value.

Remarks

Applications might define their own memory-freeing function if the standard C run-time routines do not meet their requirements.

D3DRMMALLOCFUNCTION

Allocates memory. This function is application-defined.

typedef LPVOID (*D3DRMMALLOCFUNCTION)(DWORD dwSize);
typedef D3DRMMALLOCFUNCTION *LPD3DRMMALLOCFUNCTION;
Parameters
dwSize
Size, in bytes, of the memory that will be allocated.
Return Values

Returns the address of the allocated memory if successful, or zero otherwise.

Remarks

Applications might define their own memory-allocation function if the standard C run-time routines do not meet their requirements.

D3DRMMatrixFromQuaternion

Calculates the matrix for the rotation that a unit quaternion represents.

void D3DRMMatrixFromQuaternion (
D3DRMMATRIX4D mat,
LPD3DRMQUATERNION lpquat
);

Parameters
mat
Address that will contain the calculated matrix when the function returns. (The D3DRMMATRIX4D type is an array.)
lpquat
Address of the D3DRMQUATERNION structure.
Return Values

No return value.

D3DRMQuaternionFromRotation

Retrieves a unit quaternion that represents a rotation of a specified number of radians around the given axis.

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(
LPD3DRMQUATERNION lpquat,
LPD3DVECTOR lpv,
D3DVALUE theta
);

Parameters
lpquat
Address of a D3DRMQUATERNION structure that will contain the result of the operation.
lpv
Address of a D3DVECTOR structure specifying the axis of rotation.
theta
Number of radians to rotate around the axis specified by the lpv parameter.
Return Values

Returns the address of the unit quaternion that was passed as the first parameter if successful, or zero otherwise.

D3DRMQuaternionMultiply

Calculates the product of two quaternion structures.

LPD3DRMQUATERNION D3DRMQuaternionMultiply(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb
);

Parameters
lpq
Address of the D3DRMQUATERNION structure that will contain the product of the multiplication.
lpa and lpb
Addresses of the D3DRMQUATERNION structures that will be multiplied together.
Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.

D3DRMQuaternionSlerp

Interpolates between two quaternion structures, using spherical linear interpolation.

LPD3DRMQUATERNION D3DRMQuaternionSlerp(
LPD3DRMQUATERNION lpq,
LPD3DRMQUATERNION lpa,
LPD3DRMQUATERNION lpb,
D3DVALUE alpha
);

Parameters
lpq
Address of the D3DRMQUATERNION structure that will contain the interpolation.
lpa and lpb
Addresses of the D3DRMQUATERNION structures that are used as the starting and ending points for the interpolation, respectively.
alpha
Value between 0 and 1 that specifies how far to interpolate between lpa and lpb.
Return Values

Returns the address of the quaternion that was passed as the first parameter if successful, or zero otherwise.

D3DRMREALLOCFUNCTION

Reallocates memory. This function is application-defined.

typedef LPVOID (*D3DRMREALLOCFUNCTION)(LPVOID lpArg,
    DWORD dwSize);
typedef D3DRMREALLOCFUNCTION *LPD3DRMREALLOCFUNCTION;
Parameters
lpArg
Address of application-defined data.
dwSize
Size, in bytes, of the reallocated memory.
Return Values

Returns an address of the reallocated memory if successful, or zero otherwise.

Remarks

Applications may define their own memory-reallocation function if the standard C run-time routines do not meet their requirements.

D3DRMVectorAdd

Adds two vectors.

LPD3DVECTOR D3DRMVectorAdd(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain the result of the addition.
lps1 and lps2
Addresses of the D3DVECTOR structures that will be added together.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

D3DRMVectorCrossProduct

Calculates the cross product of the two vector arguments.

LPD3DVECTOR D3DRMVectorCrossProduct(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain the result of the cross product.
lps1 and lps2
Addresses of the D3DVECTOR structures from which the cross product is produced.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

D3DRMVectorDotProduct

Returns the vector dot product.

D3DVALUE D3DRMVectorDotProduct(
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters
lps1 and lps2
Addresses of the D3DVECTOR structures from which the dot product is produced.
Return Values

Returns the result of the dot product if successful, or zero otherwise.

D3DRMVectorModulus

Returns the length of a vector according to the following formula:

Square root of x squared plus y squared plus z squared

D3DVALUE D3DRMVectorModulus(
LPD3DVECTOR lpv
);

Parameters
lpv
Address of the D3DVECTOR structure whose length is returned.
Return Values

Returns the length of the D3DVECTOR structure if successful, or zero otherwise.

D3DRMVectorNormalize

Scales a vector so that its modulus is 1.

LPD3DVECTOR D3DRMVectorNormalize(
LPD3DVECTOR lpv
);

Parameters
lpv
Address of a D3DVECTOR structure that will contain the result of the scaling operation.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero if an error occurs. An example of an error is if a zero vector were passed.

D3DRMVectorRandom

Returns a random unit vector.

LPD3DVECTOR D3DRMVectorRandom(
LPD3DVECTOR lpd
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain a random unit vector.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

D3DRMVectorReflect

Reflects a ray about a given normal.

LPD3DVECTOR D3DRMVectorReflect(
LPD3DVECTOR lpd,
LPD3DVECTOR lpRay,
LPD3DVECTOR lpNorm
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain the result of the operation.
lpRay
Address of a D3DVECTOR structure that will be reflected about a normal.
lpNorm
Address of a D3DVECTOR structure specifying the normal about which the vector specified in lpRay is reflected.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

D3DRMVectorRotate

Rotates a vector around a given axis. Returns a normalized vector if successful.

LPD3DVECTOR D3DRMVectorRotate(
LPD3DVECTOR lpr,
LPD3DVECTOR lpv,
LPD3DVECTOR lpaxis,
D3DVALUE theta
);

Parameters
lpr
Address of a D3DVECTOR structure that will contain the normalized result of the operation.
lpv
Address of a D3DVECTOR structure that will be rotated around the given axis.
lpaxis
Address of a D3DVECTOR structure that is the axis of rotation.
theta
The amount of rotation in radians.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise. This vector is normalized.

D3DRMVectorScale

Scales a vector uniformly in all three axes.

LPD3DVECTOR D3DRMVectorScale(
LPD3DVECTOR lpd,
LPD3DVECTOR lps,
D3DVALUE factor
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain the result of the operation.
lps
Address of a D3DVECTOR structure that this function scales.
factor
Scaling factor. A value of 1 does not change the scaling; a value of 2 doubles it, and so on.

Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.

D3DRMVectorSubtract

Subtracts two vectors.

LPD3DVECTOR D3DRMVectorSubtract(
LPD3DVECTOR lpd,
LPD3DVECTOR lps1,
LPD3DVECTOR lps2
);

Parameters
lpd
Address of a D3DVECTOR structure that will contain the result of the operation.
lps1
Address of the D3DVECTOR structure from which lps2 is subtracted.
lps2
Address of the D3DVECTOR structure that is subtracted from lps1.
Return Values

Returns the address of the vector that was passed as the first parameter if successful, or zero otherwise.


Callback Functions

The Microsoft® Direct3D® Retained Mode callback functions are:

  • D3DRMDEVICEPALETTECALLBACK
  • D3DRMFRAMEMOVECALLBACK
  • D3DRMLOADCALLBACK
  • D3DRMLOADTEXTURECALLBACK
  • D3DRMOBJECTCALLBACK
  • D3DRMUPDATECALLBACK
  • D3DRMUSERVISUALCALLBACK
  • D3DRMWRAPCALLBACK

D3DRMDEVICEPALETTECALLBACK

Enumerates palette entries. This callback function is application-defined.

void (
*D3DRMDEVICEPALETTECALLBACK
)
(
LPDIRECT3DRMDEVICE lpDirect3DRMDev,
LPVOID lpArg,
DWORD dwIndex,
LONG red,
LONG green,
LONG blue
);

Parameters
lpDirect3DRMDev
Address of the IDirect3DRMDevice interface for this device.
lpArg
Address of application-defined data passed to this callback function.
dwIndex
Index of the palette entry being described.
red, green, and blue
Red, green, and blue components of the color at the given index in the palette.
Return Values

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

D3DRMFRAMEMOVECALLBACK

Enables an application to apply customized algorithms when a frame is moved or updated. You can use this callback function to compensate for changing frame rates. This callback function is application-defined.

void (
*D3DRMFRAMEMOVECALLBACK
)(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPVOID lpArg,
D3DVALUE delta
);

Parameters
lpD3DRMFrame
Address of the Direct3DRMFrame object that is being moved.
lpArg
Address of application-defined data passed to this callback function.
delta
Amount of change to apply to the movement. There are two components to the change in position of a frame: linear and rotational. The change in each component is equal to velocity_of_component×delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.
Return Values

No return value.

Remarks

Your application can synthesize the acceleration of a frame relative to its parent frame. To do so, on each tick your application should set the velocity of the child frame relative to itself to (a units per tick) × 1 tick, where a is the required acceleration. This is equal to a × delta units per tick. Internally, a × delta units per tick relative to the child frame is converted to (v + (a × delta)) units per tick relative to the parent frame, where v is the current velocity of the child relative to the parent.

You can add and remove this callback function from your application by using the IDirect3DRMFrame::AddMoveCallback and IDirect3DRMFrame::DeleteMoveCallback methods.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

D3DRMLOADCALLBACK

Loads objects named in a call to the IDirect3DRM::Load method. This callback function is application-defined.

void (
*D3DRMLOADCALLBACK
)(
LPDIRECT3DRMOBJECT lpObject,
REFIID ObjectGuid,
LPVOID lpArg
);

Parameters
lpObject
Address of the Direct3DRMObject being loaded.
ObjectGuid
Globally unique identifier (GUID) of the object being loaded.
lpArg
Address of application-defined data passed to this callback function.
Return Values

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM::Load

D3DRMLOADTEXTURECALLBACK

Loads texture maps from a file or resource named in a call to one of the Load methods. This callback function is application-defined.

HRESULT (
*D3DRMLOADTEXTURECALLBACK
)(
char *tex_name,
void *lpArg,
LPDIRECT3DRMTEXTURE *lpD3DRMTex
);

Parameters
tex_name
Address of a string containing the name of the texture.
lpArg
Address of application-specific data.
lpD3DRMTex
Address of the Direct3DRMTexture object.
Return Values

Should return D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Applications can use this callback function to implement support for textures that are not in the Microsoft® Windows® bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load

D3DRMOBJECTCALLBACK

Enumerates objects in response to a call to the IDirect3DRM::EnumerateObjects method. This callback function is application-defined.

void (
*D3DRMOBJECTCALLBACK
)(
LPDIRECT3DRMOBJECT lpD3DRMobj,
LPVOID lpArg
);

Parameters
lpD3DRMobj
Address of an IDirect3DRMObject interface for the object being enumerated. The application must use the Release method for each enumerated object.
lpArg
Address of application-defined data passed to this callback function.
Return Values

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRM::EnumerateObjects

D3DRMUPDATECALLBACK

Alerts the application when the device changes. This callback function is application-defined.

void (
*D3DRMUPDATECALLBACK
)(
LPDIRECT3DRMDEVICE lpobj,
LPVOID lpArg,
int iRectCount,
LPD3DRECT d3dRectUpdate
);

Parameters
lpobj
Address of the Direct3DRMDevice object to which this callback function applies.
lpArg
Address of application-defined data passed to this callback function.
iRectCount
Number of rectangles specified in the d3dRectUpdate parameter.
d3dRectUpdate
Array of one or more D3DRECT structures that describe the area to be updated. The coordinates are specified in device units.
Return Values

No return value.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update

D3DRMUSERVISUALCALLBACK

Alerts an application that supplies user-visual objects that it should execute the execute buffer. This function is application-defined.

int (
*D3DRMUSERVISUALCALLBACK
)(
LPDIRECT3DRMUSERVISUAL lpD3DRMUV,
LPVOID lpArg,
D3DRMUSERVISUALREASON lpD3DRMUVreason,
LPDIRECT3DRMDEVICE lpD3DRMDev,
LPDIRECT3DRMVIEWPORT lpD3DRMview
);

Parameters
lpD3DRMUV
Address of the Direct3DRMUserVisual object.
lpArg
Address of application-defined data passed to this callback function.
lpD3DRMUVreason
One of the members of the D3DRMUSERVISUALREASON enumerated type:
D3DRMUSERVISUAL_CANSEE
The application should return TRUE if the user-visual object is visible in the viewport. In this case, the application uses the device specified in the lpD3DRMview parameter.
D3DRMUSERVISUAL_RENDER
The application should render the user-visual element. In this case, the application uses the device specified in the lpD3DRMDev parameter.
lpD3DRMDev
Address of a Direct3DRMDevice object used to render the Direct3DRMUserVisual object.
lpD3DRMview
Address of a Direct3DRMViewport object used to determine whether the Direct3DRMUserVisual object is visible.
Return Values

Returns TRUE if the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_CANSEE and the user-visual object is visible in the viewport. Returns FALSE otherwise. If the lpD3DRMUVreason parameter is D3DRMUSERVISUAL_RENDER, the return value is application-defined. It is always safe to return TRUE.

Remarks

When determining the order in which to use callback functions, the system searches the objects highest in the hierarchy first, and then uses their callback functions in the order in which they were created.

See Also

IDirect3DRMUserVisual::Init

D3DRMWRAPCALLBACK

This callback function is not supported.

void (
*D3DRMWRAPCALLBACK
)(
LPD3DVECTOR lpD3DVector,
int* lpU,
int* lpV,
LPD3DVECTOR lpD3DRMVA,
LPD3DVECTOR lpD3DRMVB,
LPVOID lpArg
);


IDirect3DRM Array Interfaces

The array interfaces make it possible for your application to group objects into arrays, making it simpler to apply operations to the entire group. The following array interfaces are available:

  • IDirect3DRMArray
  • IDirect3DRMDeviceArray
  • IDirect3DRMFaceArray
  • IDirect3DRMFrameArray
  • IDirect3DRMLightArray
  • IDirect3DRMObjectArray
  • IDirect3DRMPickedArray
  • IDirect3DRMPicked2Array
  • IDirect3DRMViewportArray
  • IDirect3DRMVisualArray

IDirect3DRMArray

The IDirect3DRMArray interface organizes groups of objects. Applications typically use the particular array interface they need (for example, IDirect3DRMFaceArray), rather than using this interface directly.

The IDirect3DRMArray interface supports the GetSize method.

The IDirect3DRMArray interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. This interface supports the following three methods:
AddRef
QueryInterface
Release

IDirect3DRMArray::GetSize

IDirect3DRMArray

Retrieves the size, in number of objects, of the Direct3DRMArray object.

DWORD GetSize( );

Return Values

Returns the size.

IDirect3DRMDeviceArray

Applications use the methods of the IDirect3DRMDeviceArray interface to organize device objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces.

The IDirect3DRMDeviceArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMDeviceArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMDeviceArray object is obtained by calling the IDirect3DRM::GetDevices method.

IDirect3DRMDeviceArray::GetElement

IDirect3DRMDeviceArray

Retrieves a specified element in a Direct3DRMDeviceArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters
index
Element in the array.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMDeviceArray::GetSize

IDirect3DRMDeviceArray

Retrieves the number of elements contained in a Direct3DRMDeviceArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMFaceArray

Applications use the methods of the IDirect3DRMFaceArray interface to organize faces in a mesh. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMFace and IDirect3DRMFaceArray Interfaces.

The IDirect3DRMFaceArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMFaceArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMFaceArray object is obtained by calling the IDirect3DRMMeshBuilder::GetFaces method.

IDirect3DRMFaceArray::GetElement

IDirect3DRMFaceArray

Retrieves a specified element in a Direct3DRMFaceArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMFACE * lplpD3DRMFace
);

Parameters
index
Element in the array.
lplpD3DRMFace
Address that will be filled with a pointer to an IDirect3DRMFace interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFaceArray::GetSize

IDirect3DRMFaceArray

Retrieves the number of elements contained in a Direct3DRMFaceArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMFrameArray

Applications use the methods of the IDirect3DRMFrameArray interface to organize frame objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces.

The IDirect3DRMFrameArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMFrameArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMFrameArray object is obtained by calling the IDirect3DRMPickedArray::GetPick, IDirect3DRMPicked2Array::GetPick, or IDirect3DRMFrame::GetChildren method.

IDirect3DRMFrameArray::GetElement

IDirect3DRMFrameArray

Retrieves a specified element in a Direct3DRMFrameArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMFRAME * lplpD3DRMFrame
);

Parameters
index
Element in the array.
lplpD3DRMFrame
Address that will be filled with a pointer to an IDirect3DRMFrame interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrameArray::GetSize

IDirect3DRMFrameArray

Retrieves the number of elements contained in a Direct3DRMFrameArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMLightArray

Applications use the methods of the IDirect3DRMLightArray interface to organize light objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMLight and IDirect3DRMLightArray Interfaces.

The IDirect3DRMLightArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMLightArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMLightArray object is obtained by calling the IDirect3DRMFrame::GetLights method.

IDirect3DRMLightArray::GetElement

IDirect3DRMLightArray

Retrieves a specified element in a Direct3DRMLightArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMLIGHT * lplpD3DRMLight
);

Parameters
index
Element in the array.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMLightArray::GetSize

IDirect3DRMLightArray

Retrieves the number of elements contained in a Direct3DRMLightArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMObjectArray

Applications use the methods of the IDirect3DRMObjectArray interface to organize Direct3DRMObject objects. This section is a reference to the methods of this interface. For a conceptual overview, see Direct3DRMObject.

The IDirect3DRMObjectArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMObjectArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMObjectArray object is obtained by calling the IDirect3DRMInterpolator::GetAttachedObjects method.

IDirect3DRMObjectArray::GetElement

IDirect3DRMObjectArray

Retrieves a specified element in a Direct3DRMObjectArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMOBJECT * lplpD3DRMObject
);

Parameters
index
Element in the array.
lplpD3DRMObject
Address that will be filled with a pointer to an IDirect3DRMObject interface.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObjectArray::GetSize

IDirect3DRMObjectArray

Retrieves the number of elements contained in a Direct3DRMObjectArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMPickedArray

Applications use the methods of the IDirect3DRMPickedArray interface to organize pick objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMPickedArray and IDirect3DRMPicked2Array Interfaces.

The IDirect3DRMPickedArray interface supports the following methods:
GetPick
GetSize

The IDirect3DRMPickedArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMPickedArray object is obtained by calling the IDirect3DRMViewport::Pick method.

IDirect3DRMPickedArray::GetPick

IDirect3DRMPickedArray

Retrieves the Direct3DRMVisual and Direct3DRMFrame objects intersected by the specified pick.

HRESULT GetPick(
DWORD index,
LPDIRECT3DRMVISUAL * lplpVisual,
LPDIRECT3DRMFRAMEARRAY * lplpFrameArray,
LPD3DRMPICKDESC lpD3DRMPickDesc
);

Parameters
index
Index into the pick array identifying the pick for which information will be retrieved.
lplpVisual
Address that will contain a pointer to the Direct3DRMVisual object associated with the specified pick.
lplpFrameArray
Address that will contain a pointer to the Direct3DRMFrameArray object associated with the specified pick.
lpD3DRMPickDesc
Address of a D3DRMPICKDESC structure specifying the pick position and face and group identifiers of the objects being retrieved.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport::Pick

IDirect3DRMPickedArray::GetSize

IDirect3DRMPickedArray

Retrieves the number of elements contained in a Direct3DRMPickedArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMPicked2Array

Applications use the methods of the IDirect3DRMPicked2Array interface to organize pick objects and to return more information about the pick objects. The D3DRMPICKDESC2 structure returned by IDirect3DRMPicked2Array::GetPick contains the face and group identifiers, pick position, horizontal and vertical texture coordinates for the vertex, vertex normal, and color of the intersected objects. A pointer to this interface pointer is returned in the IDirect3DRMFrame2::RayPick method during ray picks.

This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMPickedArray and IDirect3DRMPicked2Array Interfaces.

The IDirect3DRMPicked2Array interface supports the following methods:
GetPick
GetSize

The IDirect3DRMPicked2Array interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMPicked2Array object is obtained by calling the IDirect3DRMFrame2::RayPick method.

IDirect3DRMPicked2Array::GetPick

IDirect3DRMPicked2Array

Retrieves the Direct3DRMVisual and Direct3DRMFrame objects intersected by the specified pick.

HRESULT GetPick(
DWORD index,
LPDIRECT3DRMVISUAL * lplpVisual,
LPDIRECT3DRMFRAMEARRAY * lplpFrameArray,
LPD3DRMPICKDESC2 lpD3DRMPickDesc2
);

Parameters
index
Index into the pick array identifying the pick for which information will be retrieved.
lplpVisual
Address that will contain a pointer to the Direct3DRMVisual object associated with the specified pick.
lplpFrameArray
Address that will contain a pointer to the Direct3DRMFrameArray object associated with the specified pick.
lpD3DRMPickDesc
Address of a D3DRMPICKDESC2 structure specifying the face and group identifiers, pick position, horizontal and vertical texture coordinates for the vertex, vertex normal, and color of the intersected objects.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Return Values.

See Also

IDirect3DRMFrame2::RayPick

IDirect3DRMPicked2Array::GetSize

IDirect3DRMPicked2Array

Retrieves the number of elements contained in a Direct3DRMPicked2Array object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMViewportArray

Applications use the methods of the IDirect3DRMViewportArray interface to organize viewport objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMViewport and IDirect3DRMViewportArray Interface.

The IDirect3DRMViewportArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMViewportArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMViewportArray object is obtained by calling the IDirect3DRM::CreateFrame method.

IDirect3DRMViewportArray::GetElement

IDirect3DRMViewportArray

Retrieves a specified element in a Direct3DRMViewportArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMVIEWPORT * lplpD3DRMViewport
);

Parameters
index
Element in the array.
lplpD3DRMViewport
Address that will be filled with a pointer to an IDirect3DRMViewport interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewportArray::GetSize

IDirect3DRMViewportArray

Retrieves the number of elements contained in a Direct3DRMViewportArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.

IDirect3DRMVisualArray

Applications use the methods of the IDirect3DRMVisualArray interface to organize groups of visual objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMVisual and IDirect3DRMVisualArray Interfaces.

The IDirect3DRMVisualArray interface supports the following methods:
GetElement
GetSize

The IDirect3DRMVisualArray interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMVisualArray object is obtained by calling the IDirect3DRMFrame::GetVisuals method.

IDirect3DRMVisualArray::GetElement

IDirect3DRMVisualArray

Retrieves a specified element in a Direct3DRMVisualArray object.

HRESULT GetElement(
DWORD index,
LPDIRECT3DRMVISUAL * lplpD3DRMVisual
);

Parameters
index
Element in the array.
lplpD3DRMVisual
Address that will be filled with a pointer to an IDirect3DRMVisual interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMVisualArray::GetSize

IDirect3DRMVisualArray

Retrieves the number of elements contained in a Direct3DRMVisualArray object.

DWORD GetSize( );

Return Values

Returns the number of elements.


IDirect3DRM

Applications use the methods of the IDirect3DRM interface to create Microsoft® Direct3D® Retained Mode objects and work with system-level variables. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRM and IDirect3DRM2 Interfaces.

The methods of the IDirect3DRM interface can be organized into the following groups:
Animation | CreateAnimation
CreateAnimationSet
Devices | CreateDevice
CreateDeviceFromClipper
CreateDeviceFromD3D
CreateDeviceFromSurface
GetDevices
Enumeration | EnumerateObjects
Faces | CreateFace
Frames | CreateFrame
Lights | CreateLight
CreateLightRGB
Materials | CreateMaterial
Meshes | CreateMesh
CreateMeshBuilder
Miscellaneous | CreateObject
CreateUserVisual
GetNamedObject
Load
Tick
Search paths | AddSearchPath
GetSearchPath
SetSearchPath
Shadows | CreateShadow
Textures | CreateTexture
CreateTextureFromSurface
LoadTexture
LoadTextureFromResource
SetDefaultTextureColors
SetDefaultTextureShades
Viewports | CreateViewport
Wraps | CreateWrap

The IDirect3DRM interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The IDirect3DRM COM interface is created by using the Direct3DRMCreate function.

IDirect3DRM::AddSearchPath

IDirect3DRM

Adds a list of directories to the end of the current file search path.

HRESULT AddSearchPath(
LPCSTR lpPath
);

Parameters
lpPath
Address of a null-terminated string, specifying the path to add to the current search path.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

For Microsoft® Windows®, the path should be a list of directories separated by semicolons (;).

See Also

IDirect3DRM::SetSearchPath

IDirect3DRM::CreateAnimation

IDirect3DRM

Creates an empty Direct3DRMAnimation object.

HRESULT CreateAnimation(
LPDIRECT3DRMANIMATION * lplpD3DRMAnimation
);

Parameters
lplpD3DRMAnimation
Address that will be filled with a pointer to an IDirect3DRMAnimation interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Immediate Mode Return Values.

IDirect3DRM::CreateAnimationSet

IDirect3DRM

Creates an empty Direct3DRMAnimationSet object.

HRESULT CreateAnimationSet (
LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet
);

Parameters
lplpD3DRMAnimationSet
Address that will be filled with a pointer to an IDirect3DRMAnimationSet interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateDevice

IDirect3DRM

Not implemented on the Windows platform.

HRESULT CreateDevice(
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMDEVICE* lplpD3DRMDevice
);

IDirect3DRM::CreateDeviceFromClipper

IDirect3DRM

Creates a Direct3D Retained Mode Windows device by using a specified DirectDrawClipper object.

HRESULT CreateDeviceFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters
lpDDClipper
Address of a DirectDrawClipper object.
lpGUID
Address of a globally unique identifier (GUID). This parameter can be NULL.
width and height
Width and height of the device to be created.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the lpGUID parameter is NULL, the system searches for a device with a default set of device capabilities. This is the recommended way to create a Retained Mode device because it always works, even if the user installs new hardware.

The system describes the default settings by using the following flags from the D3DPRIMCAPS structure in internal device-enumeration calls:
D3DPCMPCAPS_LESSEQUAL
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTADDRESSCAPS_WRAP
D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE
D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY
D3DPTFILTERCAPS_NEAREST

If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying NULL for lpGUID if it has special needs that are not met by this list of default settings.

IDirect3DRM::CreateDeviceFromD3D

IDirect3DRM

Creates a Direct3D Retained Mode Windows device by using specified Direct3D objects.

HRESULT CreateDeviceFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DDev,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters
lpD3D
Address of an instance of Direct3D.
lpD3DDev
Address of a Direct3D device object.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateDeviceFromSurface

IDirect3DRM

Creates a Windows device for rendering from the specified DirectDraw surfaces.

HRESULT CreateDeviceFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack,
LPDIRECT3DRMDEVICE * lplpD3DRMDevice
);

Parameters
lpGUID
Address of the globally unique identifier (GUID) used as the required device driver. If this parameter is NULL, the default device driver is used.
lpDD
Address of the DirectDraw object that is the source of the DirectDraw surface.
lpDDSBack
Address of the DirectDrawSurface object that represents the back buffer.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateFace

IDirect3DRM

Creates an instance of the IDirect3DRMFace interface.

HRESULT CreateFace(
LPDIRECT3DRMFACE * lplpd3drmFace
);

Parameters
lplpd3drmFace
Address that will be filled with a pointer to an IDirect3DRMFace interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateFrame

IDirect3DRM

Creates a new child frame of the given parent frame.

HRESULT CreateFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPDIRECT3DRMFRAME* lplpD3DRMFrame
);

Parameters
lpD3DRMFrame
Address of a frame that is to be the parent of the new frame.
lplpD3DRMFrame
Address that will be filled with a pointer to an IDirect3DRMFrame interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The child frame inherits the motion attributes of its parent. For example, if the parent is moving with a given velocity, the child frame will also move with that velocity. Furthermore, if the parent is set rotating, the child frame will rotate about the origin of the parent. Frames that have no parent are called "scenes". To create a scene, specify NULL as the parent. An application can create a frame with no parent and then associate it with a parent frame later by using the IDirect3DRMFrame::AddChild method.

See Also

IDirect3DRMFrame::AddChild

IDirect3DRM::CreateLight

IDirect3DRM

Creates a new light source with the given type and color.

HRESULT CreateLight(
D3DRMLIGHTTYPE d3drmltLightType,
D3DCOLOR cColor,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters
d3drmltLightType
One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.
cColor
Color of the light.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateLightRGB

IDirect3DRM

Creates a new light source with the given type and color.

HRESULT CreateLightRGB(
D3DRMLIGHTTYPE ltLightType,
D3DVALUE vRed,
D3DVALUE vGreen,
D3DVALUE vBlue,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters
ltLightType
One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.
vRed, vGreen, and vBlue
Color of the light.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateMaterial

IDirect3DRM

Creates a material with the given specular property.

HRESULT CreateMaterial(
D3DVALUE vPower,
LPDIRECT3DRMMATERIAL * lplpD3DRMMaterial
);

Parameters
vPower
Sharpness of the reflected highlights, with a value of 5 giving a metallic look, and higher values giving a more plastic look to the rendered surface.
lplpD3DRMMaterial
Address that will be filled with a pointer to an IDirect3DRMMaterial interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateMesh

IDirect3DRM

Creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters
lplpD3DRMMesh
Address that will be filled with a pointer to an IDirect3DRMMesh interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateMeshBuilder

IDirect3DRM

Creates a new mesh builder object.

HRESULT CreateMeshBuilder(
LPDIRECT3DRMMESHBUILDER* lplpD3DRMMeshBuilder
);

Parameters
lplpD3DRMMeshBuilder
Address that will be filled with a pointer to an IDirect3DRMMeshBuilder interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateObject

IDirect3DRM

Creates a new object without initializing the object.

HRESULT CreateObject(
REFCLSID rclsid,
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID FAR* ppv
);

Parameters
rclsid
Class identifier for the new object.
pUnkOuter
Pointer to the outer IUnknown that allows COM aggregation features.
riid
Interface identifier of the object to be created.
ppv
Address of a pointer to the object when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

An application that uses this method must initialize the object that has been created. (The other creation methods of the IDirect3DRM interface initialize the object automatically.) To initialize the new object, you should use the Init method for that object. An application should use the Init method only once to initialize any given object.

Applications can use this method to implement aggregation in Direct3DRM objects.

IDirect3DRM::CreateShadow

IDirect3DRM

Creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

HRESULT CreateShadow(
LPDIRECT3DRMVISUAL lpVisual,
LPDIRECT3DRMLIGHT lpLight,
D3DVALUE px,
D3DVALUE py,
D3DVALUE pz,
D3DVALUE nx,
D3DVALUE ny,
D3DVALUE nz,
LPDIRECT3DRMVISUAL * lplpShadow
);

Parameters
lpVisual
Address of the Direct3DRMVisual object that is casting the shadow.
lpLight
Address of the IDirect3DRMLight interface that is the light source.
px, py, and pz
Plane that the shadow is to be projected on.
nx, ny, and nz
Normal to the plane that the shadow is to be projected on.
lplpShadow
Address of a pointer to be initialized with a valid pointer to the shadow visual, if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateTexture

IDirect3DRM

Creates a texture from an image in memory.

HRESULT CreateTexture(
LPD3DRMIMAGE lpImage,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);

Parameters
lpImage
Address of a D3DRMIMAGE structure describing the source for the texture.
lplpD3DRMTexture
Address that will be filled with a pointer to an IDirect3DRMTexture interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The memory associated with the image is used each time the texture is rendered, rather than the memory being copied into the Direct3D Retained Mode buffers. This allows the image to be used both as a rendering target and as a texture.

IDirect3DRM::CreateTextureFromSurface

IDirect3DRM

Creates a texture from a specified DirectDraw surface.

HRESULT CreateTextureFromSurface(
LPDIRECTDRAWSURFACE lpDDS,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);

Parameters
lpDDS
Address of the DirectDrawSurface object containing the texture.
lplpD3DRMTexture
Address that will be filled with a pointer to an IDirect3DRMTexture interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateUserVisual

IDirect3DRM

Creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.

HRESULT CreateUserVisual(
D3DRMUSERVISUALCALLBACK fn,
LPVOID lpArg,
LPDIRECT3DRMUSERVISUAL * lplpD3DRMUV
);

Parameters
fn
Callback function that is D3DRMUSERVISUALCALLBACK application-defined.

lpArg
Address of application-defined data passed to the callback function.
lplpD3DRMUV
Address that will be filled with a pointer to an IDirect3DRMUserVisual interface if the call succeeds.
Return Values

Should return D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::CreateViewport

IDirect3DRM

Creates a viewport on a device with device coordinates (dwXPos, dwYPos) to (dwXPos + dwWidth, dwYPos + dwHeight).

HRESULT CreateViewport(
LPDIRECT3DRMDEVICE lpDev,
LPDIRECT3DRMFRAME lpCamera,
DWORD dwXPos,
DWORD dwYPos,
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport
);

Parameters
lpDev
Device on which the viewport is to be created.
lpCamera
Frame that describes the position and direction of the view.
dwXPos, dwYPos, dwWidth, and dwHeight
Position and size of the viewport, in device coordinates. The viewport size cannot be larger than the physical device or the method will fail.
lplpD3DRMViewport
Address that will be filled with a pointer to an IDirect3DRMViewport interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. If the viewport size is larger than the physical device, returns D3DRMERR_BADVALUE. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The viewport displays objects in the scene that contains the camera, with the view direction and up vector taken from the camera. The viewport size cannot be larger than the physical device.

IDirect3DRM::CreateWrap

IDirect3DRM

Creates a wrapping function that can be used to assign texture coordinates to faces and meshes. The vector [ox oy oz] gives the origin of the wrap, [dx dy dz] gives its z-axis, and [ux uy uz] gives its y-axis. The 2-D vectors [ou ov] and [su sv] give an origin and scale factor in the texture applied to the result of the wrapping function.

HRESULT CreateWrap(
D3DRMWRAPTYPE type,
LPDIRECT3DRMFRAME lpRef,
D3DVALUE ox,
D3DVALUE oy,
D3DVALUE oz,
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz,
D3DVALUE ou,
D3DVALUE ov,
D3DVALUE su,
D3DVALUE sv,
LPDIRECT3DRMWRAP* lplpD3DRMWrap
);

Parameters
type
One of the members of the D3DRMWRAPTYPE enumerated type.
lpRef
Reference frame for the wrap.
ox, oy, and oz
Origin of the wrap.
dx, dy, and dz
Z-axis of the wrap.
ux, uy, and uz
Y-axis of the wrap.
ou and ov
Origin in the texture.
su and sv
Scale factor in the texture.
lplpD3DRMWrap
Address that will be filled with a pointer to an IDirect3DRMWrap interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMWrap

IDirect3DRM::EnumerateObjects

IDirect3DRM

Uses the callback function specified by the func parameter on each of the active Direct3DRM objects.

HRESULT EnumerateObjects(
D3DRMOBJECTCALLBACK func,
LPVOID lpArg
);

Parameters
func
Application-defined D3DRMOBJECTCALLBACK callback function to be used with each Direct3DRMObject object and the application-defined argument.
lpArg
Address of application-defined data passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::GetDevices

IDirect3DRM

Returns all the Direct3DRM devices that have been created in the system.

HRESULT GetDevices(
LPDIRECT3DRMDEVICEARRAY* lplpDevArray
);

Parameters
lplpDevArray
Address of a pointer that will be filled with the resulting array of Direct3DRM devices. For information about the Direct3DRMDeviceArray object, see the IDirect3DRMDeviceArray interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::GetNamedObject

IDirect3DRM

Finds a Direct3DRMObject given the Direct3DRMObject name.

HRESULT GetNamedObject(
const char * lpName,
LPDIRECT3DRMOBJECT* lplpD3DRMObject
);

Parameters
lpName
Name of the object to be searched for.
lplpD3DRMObject
Address of a pointer to be initialized with a valid Direct3DRMObject pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the system does not find an object with the name specified in the lpName parameter, this method returns D3DRM_OK, but the lplpD3DRMObject parameter is NULL.

IDirect3DRM::GetSearchPath

IDirect3DRM

Returns the current search path. For Windows, the path is a list of directories separated by semicolons (;).

HRESULT GetSearchPath(
DWORD * lpdwSize,
LPSTR lpszPath
);

Parameters
lpdwSize
Pointer to a DWORD. Should contain the length of lpszPath when GetSearchPath is used. On return, contains the length of the string in lpszPath containing the current search path. This parameter cannot be NULL.
lpszPath
A pointer to a null-terminated string specifying the search path. If lpszPath equals NULL when GetSearchPath is used, the method returns the length of the current string in the location pointed to by the lpdwSize parameter.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRM::SetSearchPath

IDirect3DRM::Load

IDirect3DRM

Loads an object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
LPIID * lplpGUIDs,
DWORD dwcGUIDs,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADCALLBACK d3drmLoadProc,
LPVOID lpArgLP,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP,
LPDIRECT3DRMFRAME lpParentFrame
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
lplpGUIDs
Address of an array of interface identifiers to be loaded. For example, if this parameter is a two-element array containing IID_IDirect3DRMMeshBuilder and IID_IDirect3DRMAnimationSet, this method loads all the animation sets and mesh-builder objects. Possible GUIDs must be one or more of the following: IID_IDirect3DRMMeshBuilder, IID_IDirect3DRMAnimationSet, IID_IDirect3DRMAnimation, and IID_IDirect3DRMFrame.
dwcGUIDs
Number of elements specified in the lplpGUIDs parameter.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadProc
A D3DRMLOADCALLBACK callback function used when the system reads the specified object.
lpArgLP
Address of application-defined data passed to the D3DRMLOADCALLBACK callback function.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.
lpArgLTP
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
lpParentFrame
Address of a parent Direct3DRMFrame object. This argument only affects the loading of animation sets. When an animation that is loaded from an .x file references an unparented frame in the .x file, the unparented frame's parent is set to the parent frame at lpParentFrame. However, if you call Load to load any frames in the .x file, the parent frame at lpParentFrame will not be used as the parent frame for frames in the .x file with no parent. That is, lpParentFrame is used only when you load animation sets. This value of lpParentFrame can be NULL.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method allows great flexibility in loading objects from Microsoft® DirectX® files. Here is an example of how to use it:

#include <windows.h>
#include <stdio.h>
#include <initguid.h>
#include <d3drm.h>

LPDIRECT3DRM d3dApi;

int totalMesh = 0, totalAnim = 0, totalFrames = 0;

HRESULT loadTexture(LPSTR name, LPVOID lpArg, LPDIRECT3DRMTEXTURE *tex)
{
    return d3dApi->lpVtbl->LoadTexture(d3dApi, name, tex);
}

void loadCallback(LPDIRECT3DRMOBJECT lpObject, REFIID objGuid, LPVOID lpArg)
{
    if (IsEqualIID(objGuid, &IID_IDirect3DRMFrame)) {
        totalFrames ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMAnimationSet)) {
        totalAnim ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMMeshBuilder)) {
        totalMesh ++;
        return;
    }

    return;
}

BOOL loadObjects(LPSTR filename)
{
    LPGUID guids[] = { (LPGUID)&IID_IDirect3DRMMeshBuilder,
        (LPGUID)&IID_IDirect3DRMAnimationSet,
        (LPGUID)&IID_IDirect3DRMFrame };

    /* Tell the loader which objects you're interested in */

    if (FAILED(d3dApi->lpVtbl->Load(d3dApi, filename, NULL,
            guids, 3, D3DRMLOAD_FROMFILE,
            loadCallback, NULL, loadTexture, NULL, NULL)))
        return FALSE;

    printf("Total Frames loaded = %d\n", totalFrames);
    printf("Total Animation Sets loaded = %d\n", totalAnim);
    printf("Total Meshbuilders loaded = %d\n", totalMesh);

    return TRUE;
}

int main(int argc, char **argv)
{

    if (FAILED(Direct3DRMCreate(&d3dApi)))
        return FALSE;

    if (argc != 2) {
        fprintf(stderr, "usage: %s filename\n", argv[0]);
        return FALSE;
    }

    if (!loadObjects(argv[1])) return FALSE;

  return(0);
}

IDirect3DRM::LoadTexture

IDirect3DRM

Loads a texture from the specified file. This texture can have 8, 24, or 32 bits-per-pixel, and it should be in either the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

HRESULT LoadTexture(
const char * lpFileName,
LPDIRECT3DRMTEXTURE* lplpD3DRMTexture
);

Parameters
lpFileName
Name of the required .bmp or .ppm file.
lplpD3DRMTexture
Address of a pointer to be initialized with a valid Direct3DRMTexture pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

LoadTexture checks whether the texture is in .bmp or .ppm format, which are the formats it can load. If you want to load other formats, you can add code to the callback to load the image into a D3DRMIMAGE structure and then use IDirect3DRM::CreateTexture.

If you write your own texture callback, the LoadTexture call in the texture callback does not take a reference to the texture. For example:

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE *tex)
{
    return lpD3DRM->LoadTexture(name, tex);
}

In this sample, no reference is taken for tex. If you want to keep a reference to each texture loaded by your texture callback, you should AddRef the texture. For example:

LPDIRECT3DRMTEXTURE *texarray;

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE *tex)
{
    if (FAILED(lpD3DRM->LoadTexture(name, tex)) {
        return NULL;
    }

    texArray[current++] = tex;
    tex->AddRef();

    return tex;
}

IDirect3DRM::LoadTextureFromResource

IDirect3DRM

Loads a texture from a specified resource.

HRESULT LoadTextureFromResource(
HRSRC rs,
LPDIRECT3DRMTEXTURE * lplpD3DRMTexture
);

Parameters
rs
Handle of the resource.
lplpD3DRMTexture
Address of a pointer to be initialized with a valid Direct3DRMTexture object if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRM::SetDefaultTextureColors

IDirect3DRM

Sets the default colors to be used for a Direct3DRMTexture object.

HRESULT SetDefaultTextureColors(
DWORD dwColors
);

Parameters
dwColors
Number of colors.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method affects the texture colors only when it is used before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM::SetDefaultTextureShades

IDirect3DRM

Sets the default shades to be used for an Direct3DRMTexture object.

HRESULT SetDefaultTextureShades(
DWORD dwShades
);

Parameters
dwShades
Number of shades.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method affects the texture shades only when it is used before the IDirect3DRM::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM::SetSearchPath

IDirect3DRM

Sets the current file search path from a list of directories. For Windows, the path should be a list of directories separated by semicolons (;).

HRESULT SetSearchPath(
LPCSTR lpPath
);

Parameters
lpPath
Address of a null-terminated string specifying the path to set as the current search path.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The default search path is taken from the value of the D3DPATH environment variable. If this is not set, the search path will be empty. When opening a file, the system first looks for the file in the current working directory and then checks every directory in the search path.

See Also

IDirect3DRM::GetSearchPath

IDirect3DRM::Tick

IDirect3DRM

Performs the Direct3DRM system heartbeat. When this method is used, the positions of all moving frames are updated according to their current motion attributes, the scene is rendered to the current device, and relevant callback functions are used at their appropriate times. Control is returned when the rendering cycle is complete.

HRESULT Tick(
D3DVALUE d3dvalTick
);

Parameters
d3dvalTick
Velocity and rotation step for the IDirect3DRMFrame::SetRotation and IDirect3DRMFrame::SetVelocity methods.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

You can implement this method by using other Retained Mode methods to allow more flexibility in rendering a scene.


IDirect3DRM2

Applications use the methods of the IDirect3DRM2 interface to create Direct3DRM2 objects and work with system-level variables.

Applications use the methods of the IDirect3DRMDevice2 and IDirect3DRMDevice interfaces to interact with the output device. While the IDirect3DRMDevice interface, when created from the IDirect3DRM interface, works with an IDirect3DDevice Immediate Mode device, the IDirect3DRMDevice2 interface, when created from the IDirect3DRM2 interface or initialized by the IDirect3DRMDevice2::InitFromClipper, IDirect3DRMDevice2::InitFromD3D2, or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRM2 supports all the methods in IDirect3DRM. In addition, the IDirect3DRM2::CreateProgressiveMesh method had been added. The IDirect3DRM2::CreateDeviceFromSurface, IDirect3DRM2::CreateDeviceFromD3D, and IDirect3DRM2::CreateDeviceFromClipper methods all create a DIRECT3DRMDEVICE2 object. The IDirect3DRM2::CreateViewport method creates a viewport on a DirectDRMDevice2 object. The IDirect3DRM2::LoadTexture and IDirect3DRM2::LoadTextureFromResource methods load a Direct3DRMTexture2 object.

To access the IDirect3DRM2 Component Object Model (COM) interface, create an IDirect3DRM object with Direct3DRMCreate, then query for IDirect3DRM2 from IDirect3DRM.

For a conceptual overview, see IDirect3DRM and IDirect3DRM2 Interfaces.

The methods of the IDirect3DRM2 interface can be organized into the following groups:

Animation | CreateAnimation
CreateAnimationSet
Devices | CreateDevice
CreateDeviceFromClipper
CreateDeviceFromD3D
CreateDeviceFromSurface
GetDevices
Enumeration | EnumerateObjects
Faces | CreateFace
Frames | CreateFrame
Lights | CreateLight
CreateLightRGB
Materials | CreateMaterial
Meshes | CreateMesh
CreateMeshBuilder
Miscellaneous | CreateObject
CreateUserVisual
GetNamedObject
Load
Tick
Progressive Meshes | CreateProgressiveMesh
Search paths | AddSearchPath
GetSearchPath
SetSearchPath
Shadows | CreateShadow
Textures | CreateTexture
CreateTextureFromSurface
LoadTexture
LoadTextureFromResource
SetDefaultTextureColors
SetDefaultTextureShades
Viewports | CreateViewport
Wraps | CreateWrap

The IDirect3DRM2 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

IDirect3DRM2::AddSearchPath

IDirect3DRM2

Adds a list of directories to the end of the current file search path.

HRESULT AddSearchPath(
LPCSTR lpPath
);

Parameters
lpPath
Address of a null-terminated string specifying the path to add to the current search path.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

For Microsoft® Windows®, the path should be a list of directories separated by semicolons (;).

See Also

IDirect3DRM2::SetSearchPath

IDirect3DRM2::CreateAnimation

IDirect3DRM2

Creates an empty Direct3DRMAnimation object.

HRESULT CreateAnimation(
LPDIRECT3DRMANIMATION * lplpD3DRMAnimation
);

Parameters
lplpD3DRMAnimation
Address that will be filled with a pointer to an IDirect3DRMAnimation interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateAnimationSet

IDirect3DRM2

Creates an empty Direct3DRMAnimationSet object.

HRESULT CreateAnimationSet (
LPDIRECT3DRMANIMATIONSET * lplpD3DRMAnimationSet
);

Parameters
lplpD3DRMAnimationSet
Address that will be filled with a pointer to an IDirect3DRMAnimationSet interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateDevice

IDirect3DRM2

Not implemented on the Windows platform.

HRESULT CreateDevice(
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMDEVICE* lplpD3DRMDevice
);

IDirect3DRM2::CreateDeviceFromClipper

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device by using a specified DirectDrawClipper object. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

HRESULT CreateDeviceFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height,
LPDIRECT3DRMDEVICE2 * lplpD3DRMDevice
);

Parameters
lpDDClipper
Address of a DirectDrawClipper object.
lpGUID
Address of a globally unique identifier (GUID). This parameter can be NULL.
width and height
Width and height of the device to be created.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

If the lpGUID parameter is NULL, the system searches for a device with a default set of device capabilities. This is the recommended way to create a Retained Mode device because it always works, even if the user installs new hardware.

The system describes the default settings by using the following flags from the D3DPRIMCAPS structure in internal device-enumeration calls:
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPCMPCAPS_LESSEQUAL
D3DPTFILTERCAPS_NEAREST
D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY
D3DPTADDRESSCAPS_WRAP

If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying NULL in the lpGUID parameter if it has special needs that are not met by this list of default settings.

IDirect3DRM2::CreateDeviceFromD3D

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device by using specified Direct3D objects. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

HRESULT CreateDeviceFromD3D(
LPDIRECT3D2 lpD3D,
LPDIRECT3DDEVICE2 lpD3DDev,
LPDIRECT3DRMDEVICE2 * lplpD3DRMDevice
);

Parameters
lpD3D
Address of an instance of Direct3D2.
lpD3DDev
Address of a Direct3D2 device object.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateDeviceFromSurface

IDirect3DRM2

Creates a Direct3DRMDevice2 Windows device for rendering from the specified DirectDraw surfaces. An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

HRESULT CreateDeviceFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack,
LPDIRECT3DRMDEVICE2 * lplpD3DRMDevice
);

Parameters
lpGUID
Address of the globally unique identifier (GUID) used as the required device driver. If this parameter is NULL, the default device driver is used.
lpDD
Address of the DirectDraw object that is the source of the DirectDraw surface.
lpDDSBack
Address of the DirectDrawSurface object that represents the back buffer.
lplpD3DRMDevice
Address that will be filled with a pointer to an IDirect3DRMDevice2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateFace

IDirect3DRM2

Creates an instance of the IDirect3DRMFace interface.

HRESULT CreateFace(
LPDIRECT3DRMFACE * lplpd3drmFace
);

Parameters
lplpd3drmFace
Address that will be filled with a pointer to an IDirect3DRMFace interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateFrame

IDirect3DRM2

Creates a new child frame (a Direct3DRMFrame2 object) of the given parent frame.

HRESULT CreateFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame,
LPDIRECT3DRMFRAME2* lplpD3DRMFrame2
);

Parameters
lpD3DRMFrame
Address of a DIRECT3DRMFRAME object that is to be the parent of the new frame.
lplpD3DRMFrame
Address that will be filled with a pointer to an IDirect3DRMFrame2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The child frame inherits the motion attributes of its parent. For example, if the parent is moving with a given velocity, the child frame will also move with that velocity. Furthermore, if the parent is set rotating, the child frame will rotate about the origin of the parent. Frames that have no parent are called scenes. To create a scene, specify NULL as the parent. An application can create a frame with no parent and then associate it with a parent frame later by using the IDirect3DRMFrame2::AddChild method.

See Also

IDirect3DRMFrame2::AddChild

IDirect3DRM2::CreateLight

IDirect3DRM2

Creates a new light source with the given type and color.

HRESULT CreateLight(
D3DRMLIGHTTYPE d3drmltLightType,
D3DCOLOR cColor,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters
d3drmltLightType
One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.
cColor
Color of the light.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateLightRGB

IDirect3DRM2

Creates a new light source with the given type and color.

HRESULT CreateLightRGB(
D3DRMLIGHTTYPE ltLightType,
D3DVALUE vRed,
D3DVALUE vGreen,
D3DVALUE vBlue,
LPDIRECT3DRMLIGHT* lplpD3DRMLight
);

Parameters
ltLightType
One of the lighting types given in the D3DRMLIGHTTYPE enumerated type.
vRed, vGreen, and vBlue
Color of the light.
lplpD3DRMLight
Address that will be filled with a pointer to an IDirect3DRMLight interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateMaterial

IDirect3DRM2

Creates a material with the given specular property.

HRESULT CreateMaterial(
D3DVALUE vPower,
LPDIRECT3DRMMATERIAL * lplpD3DRMMaterial
);

Parameters
vPower
Sharpness of the reflected highlights, with a value of 5 giving a metallic look and higher values giving a more plastic look to the rendered surface.
lplpD3DRMMaterial
Address that will be filled with a pointer to an IDirect3DRMMaterial interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateMesh

IDirect3DRM2

Creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters
lplpD3DRMMesh
Address that will be filled with a pointer to an IDirect3DRMMesh interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateMeshBuilder

IDirect3DRM2

Creates a new mesh builder object.

HRESULT CreateMeshBuilder(
LPDIRECT3DRMMESHBUILDER2* lplpD3DRMMeshBuilder2
);

Parameters
lplpD3DRMMeshBuilder
Address that will be filled with a pointer to an IDirect3DRMMeshBuilder2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateObject

IDirect3DRM2

Creates a new object without initializing the object.

HRESULT CreateObject(
REFCLSID rclsid,
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID FAR* ppv
);

Parameters
rclsid
Class identifier for the new object.
pUnkOuter
Pointer to the outer IUnknown that allows COM aggregation features.
riid
Interface identifier of the object to be created.
ppv
Address of a pointer to the object when the method returns.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

An application that uses this method must initialize the object that has been created. (The other creation methods of the IDirect3DRM2 interface initialize the object automatically.) To initialize the new object, you should use the Init method for that object. An application should use the Init method only once to initialize any given object.

Applications can use this method to implement aggregation in Direct3DRM objects.

IDirect3DRM2::CreateProgressiveMesh

IDirect3DRM2

Creates a new progressive mesh object with no faces. The mesh is not visible until it is added to a frame.

HRESULT CreateProgressiveMesh(
LPDIRECT3DRMPROGRESSIVEMESH* lplpD3DRMProgressiveMesh
);

Parameters
lplpD3DRMProgressiveMesh
Address that will be filled with a pointer to an IDirect3DRMProgressiveMesh interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateShadow

IDirect3DRM2

Creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

HRESULT CreateShadow(
LPDIRECT3DRMVISUAL lpVisual,
LPDIRECT3DRMLIGHT lpLight,
D3DVALUE px,
D3DVALUE py,
D3DVALUE pz,
D3DVALUE nx,
D3DVALUE ny,
D3DVALUE nz,
LPDIRECT3DRMVISUAL * lplpShadow
);

Parameters
lpVisual
Address of the Direct3DRMVisual object that is casting the shadow.
lpLight
Address of the IDirect3DRMLight interface that is the light source.
px, py, and pz
Plane that the shadow is to be projected on.
nx, ny, and nz
Normal to the plane that the shadow is to be projected on.
lplpShadow
Address of a pointer to be initialized with a valid pointer to the shadow visual, if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateTexture

IDirect3DRM2

Creates a texture from an image in memory.

HRESULT CreateTexture(
LPD3DRMIMAGE lpImage,
LPDIRECT3DRMTEXTURE2* lplpD3DRMTexture2
);

Parameters
lpImage
Address of a D3DRMIMAGE structure describing the source for the texture.
lplpD3DRMTexture2
Address that will be filled with a pointer to an IDirect3DRMTexture2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The memory associated with the image is used each time the texture is rendered, rather than the memory being copied into Direct3D Retained Mode's buffers. This allows the image to be used both as a rendering target and as a texture.

IDirect3DRM2::CreateTextureFromSurface

IDirect3DRM2

Creates a texture from a specified DirectDraw surface.

HRESULT CreateTextureFromSurface(
LPDIRECTDRAWSURFACE lpDDS,
LPDIRECT3DRMTEXTURE2 * lplpD3DRMTexture2
);

Parameters
lpDDS
Address of the DirectDrawSurface object containing the texture.
lplpD3DRMTexture
Address that will be filled with a pointer to an IDirect3DRMTexture2 interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateUserVisual

IDirect3DRM2

Creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.

HRESULT CreateUserVisual(
D3DRMUSERVISUALCALLBACK fn,
LPVOID lpArg,
LPDIRECT3DRMUSERVISUAL * lplpD3DRMUV
);

Parameters
fn
Application-defined D3DRMUSERVISUALCALLBACK callback function.

lpArg
Address of application-defined data passed to the callback function.
lplpD3DRMUV
Address that will be filled with a pointer to an IDirect3DRMUserVisual interface if the call succeeds.
Return Values

Should return D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::CreateViewport

IDirect3DRM2

Creates a viewport on a Direct3DRMDevice2 device with device coordinates (dwXPos, dwYPos) to (dwXPos + dwWidth, dwYPos + dwHeight).

HRESULT CreateViewport(
LPDIRECT3DRMDEVICE2 lpDev,
LPDIRECT3DRMFRAME lpCamera,
DWORD dwXPos,
DWORD dwYPos,
DWORD dwWidth,
DWORD dwHeight,
LPDIRECT3DRMVIEWPORT* lplpD3DRMViewport
);

Parameters
lpDev
Address of a Direct3DRMDevice2 device on which the viewport is to be created.
lpCamera
Address of a frame that describes the position and direction of the view.
dwXPos, dwYPos, dwWidth, and dwHeight
Position and size of the viewport, in device coordinates. The viewport size cannot be larger than the physical device or the method will fail.
lplpD3DRMViewport
Address that will be filled with a pointer to an IDirect3DRMViewport interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. If the viewport size is larger than the physical device, returns D3DRMERR_BADVALUE. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The viewport displays objects in the scene that contains the camera, with the view direction and up vector taken from the camera. The viewport size cannot be larger than the physical device.

An IDirect3DRMDevice2 interface works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRM2::CreateWrap

IDirect3DRM2

Creates a wrapping function that can be used to assign texture coordinates to faces and meshes. The vector [ox oy oz] gives the origin of the wrap, [dx dy dz] gives its z-axis, and [ux uy uz] gives its y-axis. The 2-D vectors [ou ov] and [su sv] give an origin and scale factor in the texture applied to the result of the wrapping function.

HRESULT CreateWrap(
D3DRMWRAPTYPE type,
LPDIRECT3DRMFRAME lpRef,
D3DVALUE ox,
D3DVALUE oy,
D3DVALUE oz,
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz,
D3DVALUE ou,
D3DVALUE ov,
D3DVALUE su,
D3DVALUE sv,
LPDIRECT3DRMWRAP* lplpD3DRMWrap
);

Parameters
type
One of the members of the D3DRMWRAPTYPE enumerated type.
lpRef
Reference frame for the wrap.
ox, oy, and oz
Origin of the wrap.
dx, dy, and dz
The z-axis of the wrap.
ux, uy, and uz
The y-axis of the wrap.
ou and ov
Origin in the texture.
su and sv
Scale factor in the texture.
lplpD3DRMWrap
Address that will be filled with a pointer to an IDirect3DRMWrap interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMWrap

IDirect3DRM2::EnumerateObjects

IDirect3DRM2

Uses the callback function specified by the func parameter on each of the active Direct3DRM objects.

HRESULT EnumerateObjects(
D3DRMOBJECTCALLBACK func,
LPVOID lpArg
);

Parameters
func
Application-defined D3DRMOBJECTCALLBACK callback function to be used with each Direct3DRMObject object and the application-defined argument.
lpArg
Address of application-defined data passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::GetDevices

IDirect3DRM2

Returns all the Direct3DRM devices that have been created in the system.

HRESULT GetDevices(
LPDIRECT3DRMDEVICEARRAY* lplpDevArray
);

Parameters
lplpDevArray
Address of a pointer that will be filled with the resulting array of Direct3DRM devices. For information about the Direct3DRMDeviceArray object, see the IDirect3DRMDeviceArray interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::GetNamedObject

IDirect3DRM2

Finds a Direct3DRMObject given the Direct3DRMObject name.

HRESULT GetNamedObject(
const char * lpName,
LPDIRECT3DRMOBJECT* lplpD3DRMObject
);

Parameters
lpName
Name of the object to be searched for.
lplpD3DRMObject
Address of a pointer to be initialized with a valid Direct3DRMObject pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

If the system does not find an object with the name specified in the lpName parameter, this method returns D3DRM_OK but the lplpD3DRMObject parameter is NULL.

IDirect3DRM2::GetSearchPath

IDirect3DRM2

Returns the current search path. For Windows, the path is a list of directories separated by semicolons (;).

HRESULT GetSearchPath(
DWORD * lpdwSize,
LPSTR lpszPath
);

Parameters
lpdwSize
Pointer to a DWORD. Should contain the length of lpszPath when GetSearchPath is used. On return, contains the length of the string in lpszPath containing the current search path. This parameter cannot be NULL.
lpszPath
A pointer to a null-terminated string specifying the search path. If lpszPath equals NULL when GetSearchPath is used, the method returns the length of the current string in the location pointed to by the lpdwSize parameter.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRM2::SetSearchPath

IDirect3DRM2::Load

IDirect3DRM2

Loads an object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
LPIID * lplpGUIDs,
DWORD dwcGUIDs,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADCALLBACK d3drmLoadProc,
LPVOID lpArgLP,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP,
LPDIRECT3DRMFRAME lpParentFrame
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
lplpGUIDs
Address of an array of interface identifiers to be loaded. For example, if this parameter is a two-element array containing IID_IDirect3DRMMeshBuilder and IID_IDirect3DRMAnimationSet, this method loads all the animation sets and mesh-builder objects. Possible GUIDs must be one or more of the following: IID_IDirect3DRMMeshBuilder, IID_IDirect3DRMAnimationSet, IID_IDirect3DRMAnimation, and IID_IDirect3DRMFrame.
dwcGUIDs
Number of elements specified in the lplpGUIDs parameter.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadProc
A D3DRMLOADCALLBACK callback function used when the system reads the specified object.
lpArgLP
Address of application-defined data passed to the D3DRMLOADCALLBACK callback function.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.
lpArgLTP
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
lpParentFrame
Address of a parent Direct3DRMFrame object. This argument only affects the loading of animation sets. When an animation that is loaded from an .x file references an unparented frame in the .x file, the unparented frame's parent is set to the parent frame at lpParentFrame. However, if you use Load to load any frames in the .x file, the parent frame at lpParentFrame will not be used as the parent frame for frames in the .x file with no parent. That is, lpParentFrame is used only when you load animation sets. This value of lpParentFrame can be NULL.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method allows great flexibility in loading objects from DirectX files. See IDirect3DRM::Load for an example of how to use it.

IDirect3DRM2::LoadTexture

IDirect3DRM2

Loads a Direct3DRMTexture2 texture from the specified file. This texture can have 8, 24, or 32 bits-per-pixel, and it should be in either the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

HRESULT LoadTexture(
const char * lpFileName,
LPDIRECT3DRMTEXTURE2* lplpD3DRMTexture
);

Parameters
lpFileName
Address of the name of the required .bmp or .ppm file.
lplpD3DRMTexture
Address of a pointer to be initialized with a valid IDirect3DRMTexture2 pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

LoadTexture checks whether the texture is in BMP or PPM format, which are the formats it can load. If you want to load other formats, you can add code to the callback to load the image into a D3DRMIMAGE structure and then use IDirect3DRM2::CreateTexture.

If you write your own texture callback, the LoadTexture call in the texture callback does not take a reference to the texture. For example:

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    return lpD3DRM2->LoadTexture(name, tex);
}

In this sample, no reference is taken for tex. If you want to keep a reference to each texture loaded by your texture callback, you should AddRef the texture. For example:

LPDIRECT3DRMTEXTURE2 *texarray;

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    if (FAILED(lpD3DRM2->LoadTexture(name, tex)) {
        return NULL;
    }

    texArray[current++] = tex;
    tex->AddRef();

    return tex;
}

IDirect3DRM2::LoadTextureFromResource

IDirect3DRM2

Loads a Direct3DRMTexture2 texture from a specified resource.

HRESULT LoadTextureFromResource(
HMODULE hModule,
LPCTSTR strName,
LPCTSTR strType,
LPDIRECT3DRMTEXTURE2 * lplpD3DRMTexture
);

Parameters
hModule
Handle of the module whose executable file contains the resource.
strName
A null-terminated string specifying the name of the resource to be used as the texture.
strType
A null-terminated string specifying the type name of the resource. This parameter can be one of the following resource types or a user-defined type:
Value | Meaning
RT_BITMAP | Bitmap reource
RT_RCDATA | Application-defined resource (raw data)
lplpD3DRMTexture
Address of a pointer to be initialized with a valid IDirect3DRMTexture2 object if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRM2::SetDefaultTextureColors

IDirect3DRM2

Sets the default colors to be used for a Direct3DRMTexture2 object.

HRESULT SetDefaultTextureColors(
DWORD dwColors
);

Parameters
dwColors
Number of colors.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method affects the texture colors only when it is used before the IDirect3DRM2::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM2::SetDefaultTextureShades

IDirect3DRM2

Sets the default shades to be used for an Direct3DRMTexture2 object.

HRESULT SetDefaultTextureShades(
DWORD dwShades
);

Parameters
dwShades
Number of shades.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method affects the texture shades only when it is used before the IDirect3DRM2::CreateTexture method; it has no effect on textures that have already been created.

IDirect3DRM2::SetSearchPath

IDirect3DRM2

Sets the current file search path from a list of directories. For Windows, the path should be a list of directories separated by semicolons (;).

HRESULT SetSearchPath(
LPCSTR lpPath
);

Parameters
lpPath
Address of a null-terminated string specifying the path to set as the current search path.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The default search path is taken from the value of the D3DPATH environment variable. If this is not set, the search path will be empty. When opening a file, the system first looks for the file in the current working directory and then checks every directory in the search path.

D3DPATH is an environment variable that sets the default search path.

See Also

IDirect3DRM2::GetSearchPath

IDirect3DRM2::Tick

IDirect3DRM2

Performs the Direct3DRM system heartbeat. When this method is used, the positions of all moving frames are updated according to their current motion attributes, the scene is rendered to the current device, and relevant callback functions are used at their appropriate times. Control is returned when the rendering cycle is complete.

HRESULT Tick(
D3DVALUE d3dvalTick
);

Parameters
d3dvalTick
Velocity and rotation step for the IDirect3DRMFrame::SetRotation and IDirect3DRMFrame::SetVelocity methods.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

You can implement this method by using other Retained Mode methods to allow more flexibility in rendering a scene.


IDirect3DRMAnimation

Applications use the methods of the IDirect3DRMAnimation interface to animate the position, orientation, and scaling of visuals, lights, and viewports. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMAnimation and IDirect3DRMAnimationSet Interfaces.

The methods of the IDirect3DRMAnimation interface can be organized into the following groups:

Keys | AddPositionKey
AddRotateKey
AddScaleKey
DeleteKey
Miscellaneous | SetFrame
SetTime
Options | GetOptions
SetOptions

The IDirect3DRMAnimation interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMAnimation interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMAnimation object is obtained by calling the IDirect3DRM::CreateAnimation method.

IDirect3DRMAnimation::AddPositionKey

IDirect3DRMAnimation

Adds a position key to the animation.

HRESULT AddPositionKey(
D3DVALUE rvTime,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rvTime
Time in the animation to store the position key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rvX, rvY, and rvZ
Position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The transformation applied by this method is a translation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation::DeleteKey

IDirect3DRMAnimation::AddRotateKey

IDirect3DRMAnimation

Adds a rotate key to the animation.

HRESULT AddRotateKey(
D3DVALUE rvTime,
D3DRMQUATERNION *rqQuat
);

Parameters
rvTime
Time in the animation to store the rotate key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rqQuat
Quaternion representing the rotation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method applies a rotation transformation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation::DeleteKey

IDirect3DRMAnimation::AddScaleKey

IDirect3DRMAnimation

Adds a scale key to the animation.

HRESULT AddScaleKey(
D3DVALUE rvTime,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rvTime
Time in the animation to store the scale key. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
rvX, rvY, and rvZ
Scale factor.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method applies a scaling transformation. For information about the matrix mathematics involved in transformations, see 3-D Transformations.

See Also

IDirect3DRMAnimation::DeleteKey

IDirect3DRMAnimation::DeleteKey

IDirect3DRMAnimation

Removes a key from an animation.

HRESULT DeleteKey(
D3DVALUE rvTime
);

Parameters
rvTime
Time identifying the key that will be removed from the animation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimation::GetOptions

IDirect3DRMAnimation

Retrieves animation options.

D3DRMANIMATIONOPTIONS GetOptions( );

Return Values

Returns the value of the D3DRMANIMATIONOPTIONS type describing the animation options.

See Also

IDirect3DRMAnimation::SetOptions

IDirect3DRMAnimation::SetFrame

IDirect3DRMAnimation

Sets the frame for the animation.

HRESULT SetFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters
lpD3DRMFrame
Address of a variable representing the frame to set for the animation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimation::SetOptions

IDirect3DRMAnimation

Sets the animation options.

HRESULT SetOptions(
D3DRMANIMATIONOPTIONS d3drmanimFlags
);

Parameters
d3drmanimFlags
Value of the D3DRMANIMATIONOPTIONS type describing the animation options.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMAnimation::GetOptions

IDirect3DRMAnimation::SetTime

IDirect3DRMAnimation

Sets the current time for this animation.

HRESULT SetTime(
D3DVALUE rvTime
);

Parameters
rvTime
New current time for the animation. The time units are arbitrary and zero-based; a key whose rvTime value is 49 occurs exactly in the middle of an animation whose last key has an rvTime value of 99.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMAnimationSet

Applications use the methods of the IDirect3DRMAnimationSet interface to group Direct3DRMAnimation objects together, which can simplify the playback of complex animation sequences. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMAnimation and IDirect3DRMAnimationSet Interfaces.

The methods of the IDirect3DRMAnimationSet interface can be organized into the following groups:

Adding, loading, | AddAnimation
and removing | DeleteAnimation
Load
Time | SetTime

The IDirect3DRMAnimationSet interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMAnimationSet interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMAnimationSet object is obtained by calling the IDirect3DRM::CreateAnimationSet method.

IDirect3DRMAnimationSet::AddAnimation

IDirect3DRMAnimationSet

Adds an animation to the animation set.

HRESULT AddAnimation(
LPDIRECT3DRMANIMATION lpD3DRMAnimation
);

Parameters
lpD3DRMAnimation
Address of the Direct3DRMAnimation object to be added to the animation set.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimationSet::DeleteAnimation

IDirect3DRMAnimationSet

Removes a previously added animation from the animation set.

HRESULT DeleteAnimation(
LPDIRECT3DRMANIMATION lpD3DRMAnimation
);

Parameters
lpD3DRMAnimation
Address of the Direct3DRMAnimation object to be removed from the animation set.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMAnimationSet::Load

IDirect3DRMAnimationSet

Loads an animation set.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP,
LPDIRECT3DRMFRAME lpParentFrame
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by the object that require special formatting. This parameter can be NULL.
lpArgLTP
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
lpParentFrame
Address of a parent Direct3DRMFrame object. This argument only affects the loading of animation sets. When an animation that is loaded from an .x file references an unparented frame in the .x file, the frame's parent is set to this parent frame argument. However, if you call Load to load any frames in the .x file, the parent frame argument will not be used as the parent frame for frames in the .x file with no parent. That is, the parent frame argument is used only when you load animation sets. The value of this argument can be NULL.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first animation set in the file specified by the lpvObjSource parameter.

IDirect3DRMAnimationSet::SetTime

IDirect3DRMAnimationSet

Sets the time for this animation set.

HRESULT SetTime(
D3DVALUE rvTime
);

Parameters
rvTime
New time.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.


IDirect3DRMDevice

Applications use the methods of the IDirect3DRMDevice interface to interact with the output device. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces.

The methods of the IDirect3DRMDevice interface can be organized into the following groups:

Buffer counts | GetBufferCount
SetBufferCount
Color models | GetColorModel
Dithering | GetDither
SetDither
Initialization | Init
InitFromClipper
InitFromD3D
Miscellaneous | GetDirect3DDevice
GetHeight
GetTrianglesDrawn
GetViewports
GetWidth
GetWireframeOptions
Update
Notifications | AddUpdateCallback
DeleteUpdateCallback
Rendering quality | GetQuality
SetQuality
Shading | GetShades
SetShades
Texture quality | GetTextureQuality
SetTextureQuality

The IDirect3DRMDevice interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMDevice interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMDevice object is obtained by using the IDirect3DRM::CreateDevice method.

IDirect3DRMDevice::AddUpdateCallback

IDirect3DRMDevice

Adds a callback function that alerts the application when a change occurs to the device. The system uses this callback function whenever the application uses the IDirect3DRMDevice::Update method.

HRESULT AddUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters
d3drmUpdateProc
Address of an application-defined callback function, D3DRMUPDATECALLBACK.
arg
Private data to be passed to the update callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice::DeleteUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK

IDirect3DRMDevice::DeleteUpdateCallback

IDirect3DRMDevice

Removes an update callback function that was added by using the IDirect3DRMDevice::AddUpdateCallback method.

HRESULT DeleteUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters
d3drmUpdateProc
Address of an application-defined callback function, D3DRMUPDATECALLBACK.
arg
Private data that was passed to the update callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice::AddUpdateCallback, IDirect3DRMDevice::Update, D3DRMUPDATECALLBACK

IDirect3DRMDevice::GetBufferCount

IDirect3DRMDevice

Retrieves the value set in a call to the IDirect3DRMDevice::SetBufferCount method.

DWORD GetBufferCount( );

Return Values

Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.

IDirect3DRMDevice::GetColorModel

IDirect3DRMDevice

Retrieves the color model of a device.

D3DCOLORMODEL GetColorModel( );

Return Values

Returns a value from the D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome).

See Also

Color Models

IDirect3DRMDevice::GetDirect3DDevice

IDirect3DRMDevice

Retrieves a pointer to an Immediate Mode device.

HRESULT GetDirect3DDevice(
LPDIRECT3DDEVICE * lplpD3DDevice
);

Parameters
lplpD3DDevice
Address of a pointer that is initialized with a pointer to an Immediate Mode device object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice::GetDither

IDirect3DRMDevice

Retrieves the dither flag for the device.

BOOL GetDither( );

Return Values

Returns TRUE if the dither flag is set, or FALSE otherwise.

See Also

IDirect3DRMDevice::SetDither

IDirect3DRMDevice::GetHeight

IDirect3DRMDevice

Retrieves the height, in pixels, of a device. This method is a convenience function.

DWORD GetHeight( );

Return Values

Returns the height.

IDirect3DRMDevice::GetQuality

IDirect3DRMDevice

Retrieves the rendering quality for the device.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns one or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type.

See Also

IDirect3DRMDevice::SetQuality

IDirect3DRMDevice::GetShades

IDirect3DRMDevice

Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) color model.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMDevice::SetShades

IDirect3DRMDevice::GetTextureQuality

IDirect3DRMDevice

Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.

D3DRMTEXTUREQUALITY GetTextureQuality( );

Return Values

Returns one of the members of the D3DRMTEXTUREQUALITY enumerated type.

See Also

IDirect3DRMDevice::SetTextureQuality

IDirect3DRMDevice::GetTrianglesDrawn

IDirect3DRMDevice

Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.

DWORD GetTrianglesDrawn( );

Return Values

Returns the number of triangles.

Remarks

The number of triangles includes those that were passed to the renderer but were not drawn because they were backfacing. The number does not include triangles that were rejected for lying outside of the viewing frustum.

IDirect3DRMDevice::GetViewports

IDirect3DRMDevice

Constructs a Direct3DRMViewportArray object that represents the viewports currently constructed from the device.

HRESULT GetViewports(
LPDIRECT3DRMVIEWPORTARRAY* lplpViewports
);

Parameters
lplpViewports
Address of a pointer that is initialized with a valid Direct3DRMViewportArray object if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice::GetWidth

IDirect3DRMDevice

Retrieves the width, in pixels, of a device. This method is a convenience function.

DWORD GetWidth( );

Return Values

Returns the width.

IDirect3DRMDevice::GetWireframeOptions

IDirect3DRMDevice

Retrieves the wireframe options of a given device.

DWORD GetWireframeOptions( );

Return Values

Returns a bitwise OR of the following values:

D3DRMWIREFRAME_CULL
The backfacing faces are not drawn.
D3DRMWIREFRAME_HIDDENLINE
Wireframe-rendered lines are obscured by nearer objects.

IDirect3DRMDevice::Init

IDirect3DRMDevice

Not implemented on the Windows® platform.

HRESULT Init(
ULONG width,
ULONG height
);

IDirect3DRMDevice::InitFromClipper

IDirect3DRMDevice

Initializes a device from a specified DirectDrawClipper object.

HRESULT InitFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height
);

Parameters
lpDDClipper
Address of the DirectDrawClipper object to use as an initializer.
lpGUID
Address of the globally unique identifier (GUID) used as the interface identifier.
width and height
Width and height of the device in pixels.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice::InitFromD3D

IDirect3DRMDevice

Initializes a Retained Mode device from a specified Direct3D Immediate Mode object and Immediate Mode device.

HRESULT InitFromD3D(
LPDIRECT3D lpD3D,
LPDIRECT3DDEVICE lpD3DIMDev
);

Parameters
lpD3D
Address of the Direct3D Immediate Mode object to use to initialize the Retained Mode device.
lpD3DIMDev
Address of the Immediate Mode device to use to initialize the Retained Mode device.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice::SetBufferCount

IDirect3DRMDevice

Sets the number of buffers currently being used by the application.

HRESULT SetBufferCount(
DWORD dwCount
);

Parameters
dwCount
Specifies the number of buffers—one for single-buffering, two for double-buffering, and so on. The default value is 1, which is correct only for a single-buffered window operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

An application that employs double-buffering or triple-buffering must use this method to inform the system of how many buffers it is using so that the system can calculate how much of the window to clear and update on each frame.

See Also

IDirect3DRMDevice::GetBufferCount

IDirect3DRMDevice::SetDither

IDirect3DRMDevice

Sets the dither flag for the device.

HRESULT SetDither(
BOOL bDither
);

Parameters
bDither
New dithering mode for the device. The default is TRUE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice::GetDither

IDirect3DRMDevice::SetQuality

IDirect3DRMDevice

Sets the rendering quality of a device.

HRESULT SetQuality (
D3DRMRENDERQUALITY rqQuality
);

Parameters
rqQuality
One or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type. The default setting is D3DRMRENDER_FLAT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device.

An object's quality has three components: shade mode (flat or Gouraud, Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wireframe or solid).

You set the quality of a device with SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh, Direct3DRMMeshBuilder, or Direct3DRMMeshBuilder2 object with their respective SetQuality methods. By default, the quality of these objects is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT then the object will be rendered with flat shading, solid fill and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, then the object will be rendered with flat shading, lights off and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMDevice::GetQuality

IDirect3DRMDevice::SetShades

IDirect3DRMDevice

Sets the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.

HRESULT SetShades(
DWORD ulShades
);

Parameters
ulShades
New number of shades. This parameter must be a power of 2. The default is 32.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice::GetShades

IDirect3DRMDevice::SetTextureQuality

IDirect3DRMDevice

Sets the texture quality for the device.

HRESULT SetTextureQuality(
D3DRMTEXTUREQUALITY tqTextureQuality
);

Parameters
tqTextureQuality
One of the members of the D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice::GetTextureQuality

IDirect3DRMDevice::Update

IDirect3DRMDevice

Copies the image that has been rendered to the display. It also provides a heartbeat function to the device driver.

HRESULT Update( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Each call to this method causes the system to use an application-defined callback function, D3DRMUPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice::AddUpdateCallback method.

See Also

IDirect3DRMDevice::AddUpdateCallback, D3DRMUPDATECALLBACK


IDirect3DRMDevice2

Applications use the methods of the IDirect3DRMDevice2 and IDirect3DRMDevice interfaces to interact with the output device. While IDirect3DRMDevice, when created from the IDirect3DRM interface, works with an IDirect3DDevice Immediate Mode device, IDirect3DRMDevice2, when created from the IDirect3DRM2 interface, or initialized by the IDirect3DRMDevice2::InitFromD3D2 or IDirect3DRMDevice2::InitFromSurface method, works with an IDirect3DDevice2 Immediate Mode device. The IDirect3DDevice2 device supports the DrawPrimitive interface, as well as execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

The IDirect3DRMDevice2::InitFromSurface method uses the IDirect3DRM2::CreateDevice method to create an IDirect3DRMDevice2 interface. The IDirect3DRMDevice2::InitFromD3D2 method uses an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device to initialize an IDirect3DRMDevice2 Microsoft® Direct3D® Retained Mode device.

You can still query back and forth between IDirect3DRMDevice and IDirect3DRMDevice2. The main difference is in how the underlying Immediate Mode device is created.

IDirect3DRMDevice2 contains all the methods in IDirect3DRMDevice, plus two addition ones that allow you to control transparency: IDirect3DRMDevice2::GetRenderMode and IDirect3DRMDevice2::SetRenderMode; one additional initialization method: IDirect3DRMDevice2::InitFromSurface; and two changed methods IDirect3DRMDevice2::GetDirect3DDevice2 and IDirect3DRMDevice2::InitFromD3D2, which get and initialize an IDirect3DRMDevice2 object rather than an IDirect3DRMDevice object.

This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMDevice, IDirect3DRMDevice2, and IDirect3DRMDeviceArray Interfaces.

The methods of the IDirect3DRMDevice2 interface can be organized into the following groups:

Buffer counts | GetBufferCount
SetBufferCount
Color models | GetColorModel
Dithering | GetDither
SetDither
Initialization | Init
InitFromClipper
InitFromD3D2
InitFromSurface
Miscellaneous | GetDirect3DDevice2
GetHeight
GetTrianglesDrawn
GetViewports
GetWidth
GetWireframeOptions
Update
Notifications | AddUpdateCallback
DeleteUpdateCallback
Rendering quality | GetQuality
SetQuality
Shading | GetShades
SetShades
Texture quality | GetTextureQuality
SetTextureQuality
Transparency | GetRenderMode
SetRenderMode

The IDirect3DRMDevice2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMDevice2 interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMDevice2 object is obtained by calling the IDirect3DRM2::CreateDevice method.

IDirect3DRMDevice2::AddUpdateCallback

IDirect3DRMDevice2

Adds a callback function that alerts the application when a change occurs to the device. The system calls this callback function whenever the application calls the IDirect3DRMDevice2::Update method.

HRESULT AddUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters
d3drmUpdateProc
Address of an application-defined callback function, D3DRMUPDATECALLBACK.
arg
Private data to be passed to the update callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::DeleteUpdateCallback, IDirect3DRMDevice2::Update, D3DRMUPDATECALLBACK

IDirect3DRMDevice2::DeleteUpdateCallback

IDirect3DRMDevice2

Removes an update callback function that was added by calling the IDirect3DRMDevice2::AddUpdateCallback method.

HRESULT DeleteUpdateCallback(
D3DRMUPDATECALLBACK d3drmUpdateProc,
LPVOID arg
);

Parameters
d3drmUpdateProc
Address of an application-defined callback function, D3DRMUPDATECALLBACK.
arg
Private data that was passed to the update callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::AddUpdateCallback, IDirect3DRMDevice2::Update, D3DRMUPDATECALLBACK

IDirect3DRMDevice2::GetBufferCount

IDirect3DRMDevice2

Retrieves the value set in a call to the IDirect3DRMDevice2::SetBufferCount method.

DWORD GetBufferCount( );

Return Values

Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.

IDirect3DRMDevice2::GetColorModel

IDirect3DRMDevice2

Retrieves the color model of a device.

D3DCOLORMODEL GetColorModel( );

Return Values

Returns a value from the D3DCOLORMODEL enumerated type that describes the Direct3D color model (RGB or monochrome).

See Also

Color Models

IDirect3DRMDevice2::GetDirect3DDevice2

IDirect3DRMDevice2

Retrieves a pointer to an IDirect3DDevice2 Immediate Mode device.

HRESULT GetDirect3DDevice2(
LPDIRECT3DDEVICE2 * lplpD3DDevice
);

Parameters
lplpD3DDevice
Address of a pointer that is initialized with a pointer to an IDirect3DDevice2 Immediate Mode device object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DDevice2 device will support the DrawPrimitive interface and execute buffers and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRMDevice2::GetDither

IDirect3DRMDevice2

Retrieves the dither flag for the device.

BOOL GetDither( );

Return Values

Returns TRUE if the dither flag is set, or FALSE otherwise.

See Also

IDirect3DRMDevice2::SetDither

IDirect3DRMDevice2::GetHeight

IDirect3DRMDevice2

Retrieves the height, in pixels, of a device. This method is a convenience function.

DWORD GetHeight( );

Return Values

Returns the height.

IDirect3DRMDevice2::GetQuality

IDirect3DRMDevice2

Retrieves the rendering quality for the device.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns one or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type.

See Also

IDirect3DRMDevice2::SetQuality

IDirect3DRMDevice2::GetRenderMode

IDirect3DRMDevice2

Retrieves the current transparency flags.

DWORD GetRenderMode( );

Return Values

Returns the value of the current transparency flags.

Remarks

Transparency flags have the following values:

Flag | Value
No flag set (default) | 0
D3DRMRENDERMODE_BLENDEDTRANSPARENCY | 1
D3DRMRENDERMODE_SORTEDTRANSPARENCY | 2

See Also

IDirect3DRMDevice2::SetRenderMode

IDirect3DRMDevice2::GetShades

IDirect3DRMDevice2

Retrieves the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMDevice2::SetShades

IDirect3DRMDevice2::GetTextureQuality

IDirect3DRMDevice2

Retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.

D3DRMTEXTUREQUALITY GetTextureQuality( );

Return Values

Returns one of the members of the D3DRMTEXTUREQUALITY enumerated type.

See Also

IDirect3DRMDevice2::SetTextureQuality

IDirect3DRMDevice2::GetTrianglesDrawn

IDirect3DRMDevice2

Retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.

DWORD GetTrianglesDrawn( );

Return Values

Returns the number of triangles.

Remarks

The number of triangles includes those that were passed to the renderer but were not drawn because they were backfacing. The number does not include triangles that were rejected for lying outside of the viewing frustum.

IDirect3DRMDevice2::GetViewports

IDirect3DRMDevice2

Constructs a Direct3DRMViewportArray object that represents the viewports currently constructed from the device.

HRESULT GetViewports(
LPDIRECT3DRMVIEWPORTARRAY* lplpViewports
);

Parameters
lplpViewports
Address of a pointer that is initialized with a valid Direct3DRMViewportArray object if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice2::GetWidth

IDirect3DRMDevice2

Retrieves the width, in pixels, of a device. This method is a convenience function.

DWORD GetWidth( );

Return Values

Returns the width.

IDirect3DRMDevice2::GetWireframeOptions

IDirect3DRMDevice2

Retrieves the wireframe options of a given device.

DWORD GetWireframeOptions( );

Return Values

Returns a bitwise OR of the following values:

D3DRMWIREFRAME_CULL
The backfacing faces are not drawn.
D3DRMWIREFRAME_HIDDENLINE
Wireframe-rendered lines are obscured by nearer objects.

IDirect3DRMDevice2::Init

IDirect3DRMDevice2

Not implemented on the Microsoft® Windows® platform.

HRESULT Init(
ULONG width,
ULONG height
);

IDirect3DRMDevice2::InitFromClipper

IDirect3DRMDevice2

Initializes an IDirect3DDevice2 device from a specified DirectDrawClipper object using IDirect3DRM2::CreateDevice.

HRESULT InitFromClipper(
LPDIRECTDRAWCLIPPER lpDDClipper,
LPGUID lpGUID,
int width,
int height
);

Parameters
lpDDClipper
Address of the DirectDrawClipper object to use as an initializer.
lpGUID
Direct3D device driver to use.
width and height
Width and height of the device in pixels.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMDevice2::InitFromD3D2

IDirect3DRMDevice2

Initializes an IDirect3DRMDevice2 Retained Mode device from an IDirect3D2 Immediate Mode object and an IDirect3DDevice2 Immediate Mode device.

HRESULT InitFromD3D2(
LPDIRECT3D2 lpD3D,
LPDIRECT3DDEVICE2 lpD3DIMDev
);

Parameters
lpD3D
Address of the IDirect3D2 Immediate Mode object to use to initialize the Retained Mode device.
lpD3DIMDev
Address of the IDirect3DDevice2 Immediate Mode device to use to initialize the Retained Mode device.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DRMDevice2 device initialized from IDirect3DDevice2 will support the DrawPrimitive interface and execute buffers and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRMDevice2::InitFromSurface

IDirect3DRMDevice2

Initializes a IDirect3DDevice2 device from a specified DirectDraw surface, using the IDirect3DRM2::CreateDevice method.

HRESULT InitFromSurface(
LPGUID lpGUID,
LPDIRECTDRAW lpDD,
LPDIRECTDRAWSURFACE lpDDSBack
);

Parameters
lpGUID
Address of the globally unique identifier (GUID) that identifies the Direct3D device driver to use.
lpDD
Address of the interface of a DirectDraw object that created the DirectDrawSurface.
lpDDSBack
Address of the interface of a DirectDrawSurface back buffer onto which the device will render.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The IDirect3DRMDevice2 device initialized will support the DrawPrimitive interface and execute buffers, and is required for progressive meshes and for alpha blending and sorting of transparent objects.

IDirect3DRMDevice2::SetBufferCount

IDirect3DRMDevice2

Sets the number of buffers currently being used by the application.

HRESULT SetBufferCount(
DWORD dwCount
);

Parameters
dwCount
Number of buffers—one for single-buffering, two for double-buffering, and so on. The default value is 1, which is correct only for a single-buffered window operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

An application that employs double-buffering or triple-buffering must use this method to inform the system of how many buffers it is using so that the system can calculate how much of the window to clear and update on each frame.

See Also

IDirect3DRMDevice2::GetBufferCount

IDirect3DRMDevice2::SetDither

IDirect3DRMDevice2

Sets the dither flag for the device.

HRESULT SetDither(
BOOL bDither
);

Parameters
bDither
New dithering mode for the device. The default is TRUE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetDither

IDirect3DRMDevice2::SetQuality

IDirect3DRMDevice2

Sets the rendering quality of a device

HRESULT SetQuality (
D3DRMRENDERQUALITY rqQuality
);

Parameters
rqQuality
One or more of the members of the enumerated types represented by the D3DRMRENDERQUALITY type. The default setting is D3DRMRENDER_FLAT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device.

An object's quality has three components: shade mode (flat or Gouraud; Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wireframe or solid).

You set the quality of a device with SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh, Direct3DRMMeshBuilder, or Direct3DRMMeshBuilder2 object with their respective SetQuality methods. By default, the quality of these objects is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT, the object will be rendered with flat shading, solid fill, and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, the object will be rendered with flat shading, lights off, and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMDevice2::GetQuality

IDirect3DRMDevice2::SetRenderMode

IDirect3DRMDevice2

Sets the transparency mode. The mode type determines how transparent objects will be rendered. The default mode renders transparent objects with stippled transparency.

HRESULT SetRenderMode(
DWORD dwFlags
);

Parameters
dwFlags
One or more of the transparent mode flags. The default (dwFlags = 0) sets the transparency mode to stippled transparency. In addition, flags can have one or more of the following values:
D3DRMRENDERMODE_BLENDEDTRANSPARENCY (dwFlags = 1) sets the transparency mode to alpha blending.
D3DRMRENDERMODE_SORTEDTRANSPARENCY (dwFlags = 2) sets the transparency mode so that transparent polygons in the scene are buffered, sorted, and rendered in a second pass. This flag has no effect if the D3DRMRENDERMODE_BLENDEDTRANSPARENCY flag is not also set.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

If the D3DRMRENDERMODE_BLENDEDTRANSPARENCY and D3DRMRENDERMODE_SORTEDTRANSPARENCY flags are set together, it ensures that when two transparent objects are rendered one on top of the other, the image will blend in the correct order to ensure the right visual result.

See Also

IDirect3DRMDevice2::GetRenderMode

IDirect3DRMDevice2::SetShades

IDirect3DRMDevice2

Sets the number of shades in a ramp of colors used for shading in the monochromatic (or ramp) model.

HRESULT SetShades(
DWORD ulShades
);

Parameters
ulShades
New number of shades. This parameter must be a power of 2. The default is 32.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetShades

IDirect3DRMDevice2::SetTextureQuality

IDirect3DRMDevice2

Sets the texture quality for the device.

HRESULT SetTextureQuality(
D3DRMTEXTUREQUALITY tqTextureQuality
);

Parameters
tqTextureQuality
One of the members of the D3DRMTEXTUREQUALITY enumerated type. The default is D3DRMTEXTURE_NEAREST.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMDevice2::GetTextureQuality

IDirect3DRMDevice2::Update

IDirect3DRMDevice2

Copies the image that has been rendered to the display. It also provides a heartbeat function to the device driver.

HRESULT Update( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

Each call to this method causes the system to call an application-defined callback function, D3DRMUPDATECALLBACK. To add a callback function, use the IDirect3DRMDevice2::AddUpdateCallback method.

See Also

IDirect3DRMDevice2::AddUpdateCallback, D3DRMUPDATECALLBACK


IDirect3DRMFace

Applications use the methods of the IDirect3DRMFace interface to interact with a single polygon in a mesh. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMFace and IDirect3DRMFaceArray Interfaces.

The methods of the IDirect3DRMFace interface can be organized into the following groups:

Color | GetColor
SetColor
SetColorRGB
Materials | GetMaterial
SetMaterial
Textures | GetTexture
GetTextureCoordinateIndex
GetTextureCoordinates
GetTextureTopology
SetTexture
SetTextureCoordinates
SetTextureTopology
Vertices and normals | AddVertex
AddVertexAndNormalIndexed
GetNormal
GetVertex
GetVertexCount
GetVertexIndex
GetVertices

The IDirect3DRMFace interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMFace interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMFace object is obtained by using the IDirect3DRM::CreateFace method.

IDirect3DRMFace::AddVertex

IDirect3DRMFace

Adds a vertex to a Direct3DRMFace object.

HRESULT AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
x, y, and z
The x, y, and z components of the new vertex position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::AddVertexAndNormalIndexed

IDirect3DRMFace

Adds a vertex and a normal to a Direct3DRMFace object, using an index for the vertex and an index for the normal in the containing mesh builder. The face, vertex, and normal must already be part of a Direct3DRMMeshBuilder object.

HRESULT AddVertexAndNormalIndexed(
DWORD vertex,
DWORD normal
);

Parameters
vertex and normal
Indexes of the vertex and normal to add.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::GetColor

IDirect3DRMFace

Retrieves the color of a Direct3DRMFace object.

D3DCOLOR GetColor( );

Return Values

Returns the color.

See Also

IDirect3DRMFace::SetColor

IDirect3DRMFace::GetMaterial

IDirect3DRMFace

Retrieves the material of a Direct3DRMFace object.

HRESULT GetMaterial(
LPDIRECT3DRMMATERIAL* lplpMaterial
);

Parameters
lplpMaterial
Address of the pointer to the Direct3DRMMaterial object applied to the face.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::SetMaterial

IDirect3DRMFace::GetNormal

IDirect3DRMFace

Retrieves the normal vector of a Direct3DRMFace object.

HRESULT GetNormal(
D3DVECTOR *lpNormal
);

Parameters
lpNormal
Address of a D3DVECTOR structure that will be filled with the normal vector of the face.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::GetTexture

IDirect3DRMFace

Retrieves the Direct3DRMTexture object applied to a Direct3DRMFace object.

HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);

Parameters
lplpTexture
Address of a variable that will be filled with a pointer to the texture applied to the face.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::SetTexture

IDirect3DRMFace::GetTextureCoordinateIndex

IDirect3DRMFace

Retrieves the index of the vertex for texture coordinates in the face's mesh. You pass in the face-relative vertex index in the which parameter, and this method returns the corresponding mesh-relative vertex index.

int GetTextureCoordinateIndex(
DWORD which
);

Parameters
which
Index within the face of the vertex whose coorresponding mesh vertex index is being retrieved.
Return Values

Returns the face's mesh-relative vertex index.

IDirect3DRMFace::GetTextureCoordinates

IDirect3DRMFace

Retrieves the texture coordinates of a vertex in a Direct3DRMFace object.

HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);

Parameters
index
Index of the vertex.
lpU and lpV
Addresses of variables that are filled with the texture coordinates of the vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::GetTextureTopology

IDirect3DRMFace

Retrieves the texture topology of a Direct3DRMFace object.

HRESULT GetTextureTopology(
BOOL *lpU,
BOOL *lpV
);

Parameters
lpU and lpV
Addresses of variables that are set or cleared, depending on how the cylindrical wrapping flags are set for the face.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::SetTextureTopology

IDirect3DRMFace::GetVertex

IDirect3DRMFace

Retrieves the position and normal of a vertex in a Direct3DRMFace object.

HRESULT GetVertex(
DWORD index,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);

Parameters
index
Index of the vertex.
lpPosition and lpNormal
Addresses of D3DVECTOR structures that will be filled with the position and normal of the vertex, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::GetVertexCount

IDirect3DRMFace

Retrieves the number of vertices in a Direct3DRMFace object.

int GetVertexCount( );

Return Values

Returns the number of vertices.

IDirect3DRMFace::GetVertexIndex

IDirect3DRMFace

Retrieves the index of the vertex in the face's mesh. You pass in the face-relative vertex index in the which parameter, and this method returns the corresponding mesh-relative vertex index.

int GetVertexIndex (
DWORD which
);

Parameters
which
Index within the face of the vertex whose coorresponding mesh vertex index is being retrieved.
Return Values

Returns the mesh-relative vertex index.

IDirect3DRMFace::GetVertices

IDirect3DRMFace

Retrieves the position and normal vector of each vertex in a Direct3DRMFace object.

HRESULT GetVertices(
DWORD *lpdwVertexCount,
D3DVECTOR *lpPosition,
D3DVECTOR *lpNormal
);

Parameters
lpdwVertexCount
Address of a variable that is filled with the number of vertices. This parameter cannot be NULL.
lpPosition and lpNormal
Arrays of D3DVECTOR structures that will be filled with the positions and normal vectors of the vertices, respectively. If both of these parameters are NULL, the method will fill the lpdwVertexCount parameter with the number of vertices that will be retrieved.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::SetColor

IDirect3DRMFace

Sets a Direct3DRMFace object to a given color.

HRESULT SetColor(
D3DCOLOR color
);

Parameters
color
Color to set.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::GetColor

IDirect3DRMFace::SetColorRGB

IDirect3DRMFace

Sets a Direct3DRMFace object to a given color.

HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
red, green, and blue
The red, green, and blue components of the color.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::SetMaterial

IDirect3DRMFace

Sets the material of a Direct3DRMFace object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpD3DRMMaterial
);

Parameters
lpD3DRMMaterial
Address of the material.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::GetMaterial

IDirect3DRMFace::SetTexture

IDirect3DRMFace

Sets the texture of a Direct3DRMFace object.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters
lpD3DRMTexture
Address of the texture.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::GetTexture

IDirect3DRMFace::SetTextureCoordinates

IDirect3DRMFace

Sets the texture coordinates of a specified vertex in a Direct3DRMFace object.

HRESULT SetTextureCoordinates(
DWORD vertex,
D3DVALUE u,
D3DVALUE v
);

Parameters
vertex
Index of the vertex to be set. For example, if the face were a triangle, the possible vertex indices would be 0, 1, and 2.
u and v
Texture coordinates to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFace::SetTextureTopology

IDirect3DRMFace

Sets the texture topology of a Direct3DRMFace object.

HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);

Parameters
cylU and cylV
Specify whether the texture has a cylindrical topology in the u and v dimensions.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFace::GetTextureTopology

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMFrame

Applications use the methods of the IDirect3DRMFrame interface to interact with frames—an object's frame of reference. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces.

The methods of the IDirect3DRMFrame interface can be organized into the following groups:

Background | GetSceneBackground
GetSceneBackgroundDepth
SetSceneBackground
SetSceneBackgroundDepth
SetSceneBackgroundImage
SetSceneBackgroundRGB
Color | GetColor
SetColor
SetColorRGB
Fog | GetSceneFogColor
GetSceneFogEnable
GetSceneFogMode
GetSceneFogParams
SetSceneFogColor
SetSceneFogEnable
SetSceneFogMode
SetSceneFogParams
Hierarchies | AddChild
DeleteChild
GetChildren
GetParent
GetScene
Lighting | AddLight
DeleteLight
GetLights
Loading | Load
Material modes | GetMaterialMode
SetMaterialMode
Positioning and | AddMoveCallback
movement | AddRotation
AddScale
AddTranslation
DeleteMoveCallback
GetOrientation
GetPosition
GetRotation
GetVelocity
LookAt
Move
SetOrientation
SetPosition
SetRotation
SetVelocity
Sorting | GetSortMode
GetZbufferMode
SetSortMode
SetZbufferMode
Textures | GetTexture
GetTextureTopology
SetTexture
SetTextureTopology
Transformations | AddTransform
GetTransform
InverseTransform
Transform
Visual objects | AddVisual
DeleteVisual
GetVisuals

The IDirect3DRMFrame interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMFrame interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMFrame object is obtained by using the IDirect3DRM::CreateFrame method.

IDirect3DRMFrame::AddChild

IDirect3DRMFrame

Adds a child frame to a frame hierarchy.

HRESULT AddChild(
LPDIRECT3DRMFRAME lpD3DRMFrameChild
);

Parameters
lpD3DRMFrameChild
Address of the Direct3DRMFrame object that will be added as a child.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.

To preserve an object's transformation, use the IDirect3DRMFrame::GetTransform method to retrieve the object's transformation before using the AddChild method. Then reapply the transformation after the frame is added.

See Also

Hierarchies

IDirect3DRMFrame::AddLight

IDirect3DRMFrame

Adds a light to a frame.

HRESULT AddLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters
lpD3DRMLight
Address of a variable that represents the Direct3DRMLight object to be added to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::AddMoveCallback

IDirect3DRMFrame

Adds a callback function for special movement processing. The callback is called when the frame is moved or updated.

HRESULT AddMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);

Parameters
d3drmFMC
Application-defined D3DRMFRAMEMOVECALLBACK callback function.
lpArg
Application-defined data to be passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::Move, IDirect3DRMFrame::DeleteMoveCallback

IDirect3DRMFrame::AddRotation

IDirect3DRMFrame

Adds a rotation about (rvX, rvY, rvZ) by the number of radians specified in rvTheta.

HRESULT AddRotation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters
rctCombine
A member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new rotation with any current frame transformation.
rvX, rvY, and rvZ
Axis about which to rotate.
rvTheta
Angle of rotation, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified rotation changes the matrix only for the frame identified by this IDirect3DRMFrame interface. This method changes the objects in the frame only once, unlike IDirect3DRMFrame::SetRotation, which changes the matrix with every render tick.

See Also

3-D Transformations, IDirect3DRMFrame::SetRotation

IDirect3DRMFrame::AddScale

IDirect3DRMFrame

Scales a frame's local transformation by (rvX, rvY, rvZ).

HRESULT AddScale(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new scale with any current frame transformation.
rvX, rvY, and rvZ
Defines the scale factors in the x, y, and z directions.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

IDirect3DRMFrame::AddTransform

IDirect3DRMFrame

Transforms the local coordinates of the frame by the affine transformation specified by rctCombine and rmMatrix.

HRESULT AddTransform(
D3DRMCOMBINETYPE rctCombine,
D3DRMMATRIX4D rmMatrix
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new transformation with any current transformation.
rmMatrix
Member of the D3DRMMATRIX4D array that defines the transformation matrix to be combined.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Although a 4×4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.

The specified transformation only changes the matrix for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

IDirect3DRMFrame::AddTranslation

IDirect3DRMFrame

Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.

HRESULT AddTranslation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new translation with any current translation.
rvX, rvY, and rvZ
Defines the position changes in the x, y, and z directions.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame interface.

See Also

3-D Transformations

IDirect3DRMFrame::AddVisual

IDirect3DRMFrame

Adds a visual object to a frame.

HRESULT AddVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters
lpD3DRMVisual
Address of a variable that represents the Direct3DRMVisual object to be added to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The frame references the visual object.

IDirect3DRMFrame::DeleteChild

IDirect3DRMFrame

Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.

HRESULT DeleteChild(
LPDIRECT3DRMFRAME lpChild
);

Parameters
lpChild
Address of the Direct3DRMFrame object to be used as the child.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

Hierarchies

IDirect3DRMFrame::DeleteLight

IDirect3DRMFrame

Removes a light from a frame, destroying the light if it is no longer referenced. When a light is removed from a frame, it no longer affects meshes in the scene its frame was in.

HRESULT DeleteLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters
lpD3DRMLight
Address of a variable that represents the Direct3DRMLight object to be removed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::DeleteMoveCallback

IDirect3DRMFrame

Removes a frame-move callback function previously added with AddMoveCallback.

HRESULT DeleteMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);

Parameters
d3drmFMC
Application-defined D3DRMFRAMEMOVECALLBACK callback function.
lpArg
Application-defined data that was passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::AddMoveCallback, IDirect3DRMFrame::Move

IDirect3DRMFrame::DeleteVisual

IDirect3DRMFrame

Removes a visual object from a frame, destroying it if it is no longer referenced.

HRESULT DeleteVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters
lpD3DRMVisual
Address of a variable that represents the Direct3DRMVisual object to be removed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::GetChildren

IDirect3DRMFrame

Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.

HRESULT GetChildren(
LPDIRECT3DRMFRAMEARRAY* lplpChildren
);

Parameters
lplpChildren
Address of a pointer to be initialized with a valid Direct3DRMFrameArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

Direct3DRMFrameArray, Hierarchies

IDirect3DRMFrame::GetColor

IDirect3DRMFrame

Retrieves the color of the frame.

D3DCOLOR GetColor( );

Return Values

Returns the color of the Direct3DRMFrame object.

See Also

IDirect3DRMFrame::SetColor

IDirect3DRMFrame::GetLights

IDirect3DRMFrame

Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.

HRESULT GetLights(
LPDIRECT3DRMLIGHTARRAY* lplpLights
);

Parameters
lplpLights
Address of a pointer to be initialized with a valid Direct3DRMLightArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMLightArray

IDirect3DRMFrame::GetMaterialMode

IDirect3DRMFrame

Retrieves the material mode of the frame.

D3DRMMATERIALMODE GetMaterialMode( );

Return Values

Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode.

See Also

IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame::GetOrientation

IDirect3DRMFrame

Retrieves the orientation of a frame relative to the given reference frame.

HRESULT GetOrientation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvDir,
LPD3DVECTOR lprvUp
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvDir and lprvUp
Addresses of D3DVECTOR structures that will be filled with the directions of the frame's z-axis and y-axis, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetOrientation

IDirect3DRMFrame::GetParent

IDirect3DRMFrame

Retrieves the parent frame of the current frame.

HRESULT GetParent(
LPDIRECT3DRMFRAME* lplpParent
);

Parameters
lplpParent
Address of a pointer that will be filled with the pointer to the Direct3DRMFrame object representing the frame's parent. If the current frame is the root, this pointer will be NULL when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::GetPosition

IDirect3DRMFrame

Retrieves the position of a frame relative to the given reference frame, that is, it retrieves the distance of the frame from the reference. The distance is stored in the lprvPos parameter as a vector rather than as a linear measure.

HRESULT GetPosition(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvPos
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvPos
Address of a D3DVECTOR structure that will be filled with the frame's position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetPosition

IDirect3DRMFrame::GetRotation

IDirect3DRMFrame

Retrieves the rotation of the frame relative to the given reference frame.

HRESULT GetRotation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvAxis,
LPD3DVALUE lprvTheta
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvAxis
Address of a D3DVECTOR structure that will be filled with the frame's axis of rotation.
lprvTheta
Address of a variable that will be the frame's rotation, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetRotation, Transformations

IDirect3DRMFrame::GetScene

IDirect3DRMFrame

Retrieves the root frame of the hierarchy containing the given frame.

HRESULT GetScene(
LPDIRECT3DRMFRAME* lplpRoot
);

Parameters
lplpRoot
Address of the pointer that will be filled with the pointer to the Direct3DRMFrame object representing the scene's root frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::GetSceneBackground

IDirect3DRMFrame

Retrieves the background color of a scene.

D3DCOLOR GetSceneBackground( );

Return Values

Returns the color.

IDirect3DRMFrame::GetSceneBackgroundDepth

IDirect3DRMFrame

Retrieves the current background-depth buffer for the scene.

HRESULT GetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE * lplpDDSurface
);

Parameters
lplpDDSurface
Address of a pointer that will be initialized with the address of a DirectDraw surface representing the current background-depth buffer.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetSceneBackgroundDepth

IDirect3DRMFrame::GetSceneFogColor

IDirect3DRMFrame

Retrieves the fog color of a scene.

D3DCOLOR GetSceneFogColor( );

Return Values

Returns the fog color.

IDirect3DRMFrame::GetSceneFogEnable

IDirect3DRMFrame

Retrieves whether fog is currently enabled for this scene.

BOOL GetSceneFogEnable( );

Return Values

Returns TRUE if fog is enabled, or FALSE otherwise.

IDirect3DRMFrame::GetSceneFogMode

IDirect3DRMFrame

Retrieves the current fog mode for this scene.

D3DRMFOGMODE GetSceneFogMode( );

Return Values

Returns a member of the D3DRMFOGMODE enumerated type that specifies the current fog mode.

IDirect3DRMFrame::GetSceneFogParams

IDirect3DRMFrame

Retrieves the current fog parameters for this scene.

HRESULT GetSceneFogParams(
D3DVALUE * lprvStart,
D3DVALUE * lprvEnd,
D3DVALUE * lprvDensity
);

Parameters
lprvStart, lprvEnd, and lprvDensity
Addresses of variables that will be the fog start, end, and density values.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::GetSortMode

IDirect3DRMFrame

Retrieves the sorting mode used to process child frames.

D3DRMSORTMODE GetSortMode( );

Return Values

Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode.

See Also

IDirect3DRMFrame::SetSortMode

IDirect3DRMFrame::GetTexture

IDirect3DRMFrame

Retrieves the texture of the given frame.

HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);

Parameters
lplpTexture
Address of the pointer that will be filled with the address of the Direct3DRMTexture object representing the frame's texture.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetTexture

IDirect3DRMFrame::GetTextureTopology

IDirect3DRMFrame

Retrieves the topological properties of a texture when mapped onto objects in the given frame.

HRESULT GetTextureTopology(
BOOL * lpbWrap_u,
BOOL * lpbWrap_v
);

Parameters
lpbWrap_u and lpbWrap_v
Addresses of variables that are set to TRUE if the texture is mapped in the u and v directions, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetTextureTopology

IDirect3DRMFrame::GetTransform

IDirect3DRMFrame

Retrieves the local transformation of the frame as a 4×4 affine matrix.

HRESULT GetTransform(
D3DRMMATRIX4D rmMatrix
);

Parameters
rmMatrix
A D3DRMMATRIX4D array that will be filled with the frame's transformation. Because this is an array, this value is actually an address.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

3-D Transformations

IDirect3DRMFrame::GetVelocity

IDirect3DRMFrame

Retrieves the velocity of the frame relative to the given reference frame. Velocity is specified as units per tick. See IDirect3DRM::Tick for more information.

HRESULT GetVelocity(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvVel,
BOOL fRotVel
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvVel
Address of a D3DVECTOR structure that will be filled with the frame's velocity.
fRotVel
Flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is TRUE, the object's rotational velocity is included in the calculation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetVelocity

IDirect3DRMFrame::GetVisuals

IDirect3DRMFrame

Retrieves a list of visuals in the frame.

HRESULT GetVisuals(
LPDIRECT3DRMVISUALARRAY* lplpVisuals
);

Parameters
lplpVisuals
Address of a pointer to be initialized with a valid Direct3DRMVisualArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::GetZbufferMode

IDirect3DRMFrame

Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.

D3DRMZBUFFERMODE GetZbufferMode( );

Return Values

Returns one of the members of the D3DRMZBUFFERMODE enumerated type.

See Also

IDirect3DRMFrame::SetZbufferMode

IDirect3DRMFrame::InverseTransform

IDirect3DRMFrame

Transforms the vector in the lprvSrc parameter in world coordinates to model coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
D3DVECTOR *lprvDst,
D3DVECTOR *lprvSrc
);

Parameters
lprvDst
Address of a D3DVECTOR structure that will be filled with the result of the transformation.
lprvSrc
Address of a D3DVECTOR structure that is the source of the transformation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::Transform, 3-D Transformations

IDirect3DRMFrame::Load

IDirect3DRMFrame

Loads a Direct3DRMFrame object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by the object that require special formatting. This parameter can be NULL.
lpArgLTP
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first frame hierarchy in the file specified by the lpvObjSource parameter. The frame that uses this method is used as the parent of the new frame hierarchy.

IDirect3DRMFrame::LookAt

IDirect3DRMFrame

Faces the frame toward the target frame, relative to the given reference frame, locking the rotation by the given constraints.

HRESULT LookAt(
LPDIRECT3DRMFRAME lpTarget,
LPDIRECT3DRMFRAME lpRef,
D3DRMFRAMECONSTRAINT rfcConstraint
);

Parameters
lpTarget and lpRef
Addresses of variables that represent the Direct3DRMFrame objects to be used as the target and reference, respectively.
rfcConstraint
Member of the D3DRMFRAMECONSTRAINT enumerated type that specifies the axis of rotation to constrain.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::Move

IDirect3DRMFrame

Applies the linear and rotational velocities for all frames in the given hierarchy.

HRESULT Move(
D3DVALUE delta
);

Parameters
delta
Amount to change the linear and rotational velocity. The change in each component is equal to the velocity of that component multiplied by delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::SetColor

IDirect3DRMFrame

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColor(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a color key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::GetColor, IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame::SetColorRGB

IDirect3DRMFrame

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters
rvRed, rvGreen, and rvBlue
New color for the frame. Each component of the color should be in the range 0 to 1.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add an RGB color key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame

Sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.

HRESULT SetMaterialMode(
D3DRMMATERIALMODE rmmMode
);

Parameters
rmmMode
One of the members of the D3DRMMATERIALMODE enumerated type.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::GetMaterialMode

IDirect3DRMFrame::SetOrientation

IDirect3DRMFrame

Aligns a frame so that its z-direction points along the direction vector [rvDx, rvDy, rvDz] and its y-direction aligns with the vector [rvUx, rvUy, rvUz].

HRESULT SetOrientation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvDx,
D3DVALUE rvDy,
D3DVALUE rvDz,
D3DVALUE rvUx,
D3DVALUE rvUy,
D3DVALUE rvUz
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvDx, rvDy, and rvDz
New z-axis for the frame.
rvUx, rvUy, and rvUz
New y-axis for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

If [rvUx, rvUy, rvUz] is parallel to [rvDx, rvDy, rvDz], the D3DRMERR_BADVALUE error value is returned; otherwise, the [rvUx, rvUy, rvUz] vector passed is projected onto the plane that is perpendicular to [rvDx, rvDy, rvDz].

This method is also used to add an orientation key to a Direct3DRMRFrameInterpolator object.

See Also

IDirect3DRMFrame::GetOrientation

IDirect3DRMFrame::SetPosition

IDirect3DRMFrame

Sets the position of a frame relative to the frame of reference. It places the frame a distance of [rvX, rvY, rvZ] from the reference. When a child frame is created within a parent, it is placed at [0, 0, 0] in the parent frame.

HRESULT SetPosition(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
New position for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method also is used to add a position key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame::GetPosition

IDirect3DRMFrame::SetRotation

IDirect3DRMFrame

Sets a frame rotating by the given angle around the given vector at each call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method. The direction vector [rvX, rvY, rvZ] is defined in the reference frame.

HRESULT SetRotation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
Vector about which rotation occurs.
rvTheta
Rotation angle, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified rotation changes the matrix with every render tick, unlike the IDirect3DRMFrame::AddRotation method, which changes the objects in the frame only once.

See Also

IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::GetRotation

IDirect3DRMFrame::SetSceneBackground

IDirect3DRMFrame

Sets the background color of a scene.

HRESULT SetSceneBackground(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the background.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a background color key to a Direct3DRMFrameInterpolator object.

IDirect3DRMFrame::SetSceneBackgroundDepth

IDirect3DRMFrame

Specifies a background-depth buffer for a scene.

HRESULT SetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE lpImage
);

Parameters
lpImage
Address of a DirectDraw surface that will store the new background depth for the scene.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The image must have a depth of 16 bits per pixel. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.

See Also

IDirect3DRMFrame::GetSceneBackgroundDepth

IDirect3DRMFrame::SetSceneBackgroundImage

IDirect3DRMFrame

Specifies a background image for a scene.

HRESULT SetSceneBackgroundImage(
LPDIRECT3DRMTEXTURE lpTexture
);

Parameters
lpTexture
Address of a Direct3DRMTexture object that will contain the new background scene.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring extra overhead.

IDirect3DRMFrame::SetSceneBackgroundRGB

IDirect3DRMFrame

Sets the background color of a scene.

HRESULT SetSceneBackgroundRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters
rvRed, rvGreen, and rvBlue
New color for the background.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a background RGB color key to a Direct3DRMFrameInterpolator object.

IDirect3DRMFrame::SetSceneFogColor

IDirect3DRMFrame

Sets the fog color of a scene.

HRESULT SetSceneFogColor(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the fog.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a fog color key to a Direct3DRMRFrameInterpolator object.

IDirect3DRMFrame::SetSceneFogEnable

IDirect3DRMFrame

Sets the fog-enable state.

HRESULT SetSceneFogEnable(
BOOL bEnable
);

Parameters
bEnable
New fog-enable state.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame::SetSceneFogMode

IDirect3DRMFrame

Sets the fog mode.

HRESULT SetSceneFogMode(
D3DRMFOGMODE rfMode
);

Parameters
rfMode
One of the members of the D3DRMFOGMODE enumerated type, specifying the new fog mode.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::SetSceneFogParams

IDirect3DRMFrame::SetSceneFogParams

IDirect3DRMFrame

Sets the current fog parameters for this scene.

HRESULT SetSceneFogParams(
D3DVALUE rvStart,
D3DVALUE rvEnd,
D3DVALUE rvDensity
);

Parameters
rvStart and rvEnd
Fog start and end points for linear fog mode. These settings determine the distance from the camera at which fog effects first become visible and the distance at which fog reaches its maximum density.
rvDensity
Fog density for the exponential fog modes. This value should be in the range 0 through 1.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method also is used to add a fog parameters key to a Direct3DRMRFrameInterpolator object.

See Also

D3DRMFOGMODE, IDirect3DRMFrame::SetSceneFogMode

IDirect3DRMFrame::SetSortMode

IDirect3DRMFrame

Sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.

HRESULT SetSortMode(
D3DRMSORTMODE d3drmSM
);

Parameters
d3drmSM
One of the members of the D3DRMSORTMODE enumerated type, specifying the sorting mode. The default value is D3DRMSORT_FROMPARENT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::GetSortMode

IDirect3DRMFrame::SetTexture

IDirect3DRMFrame

Sets the texture of the frame.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters
lpD3DRMTexture
Address of a variable that represents the Direct3DRMTexture object to be used.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The texture is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a NULL texture.

See Also

IDirect3DRMFrame::GetTexture, IDirect3DRMFrame::SetMaterialMode

IDirect3DRMFrame::SetTextureTopology

IDirect3DRMFrame

Defines the topological properties of the texture coordinates across objects in the frame.

HRESULT SetTextureTopology(
BOOL bWrap_u,
BOOL bWrap_v
);

Parameters
bWrap_u and bWrap_v
Variables that are set to TRUE to map the texture in the u- and v-directions, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::GetTextureTopology

IDirect3DRMFrame::SetVelocity

IDirect3DRMFrame

Sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [rvX, rvY, rvZ] with respect to the reference frame at each successive call to the IDirect3DRM::Tick or IDirect3DRMFrame::Move method.

HRESULT SetVelocity(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
BOOL fRotVel
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
New velocity for the frame.
fRotVel
Flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If TRUE, the object's rotational velocity is included in the calculation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::GetVelocity

IDirect3DRMFrame::SetZbufferMode

IDirect3DRMFrame

Sets the z-buffer mode.

HRESULT SetZbufferMode(
D3DRMZBUFFERMODE d3drmZBM
);

Parameters
d3drmZBM
One of the members of the D3DRMZBUFFERMODE enumerated type, specifying the z-buffer mode. The default value is D3DRMZBUFFER_FROMPARENT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::GetZbufferMode

IDirect3DRMFrame::Transform

IDirect3DRMFrame

Transforms the vector in the lpd3dVSrc parameter in model coordinates to world coordinates, returning the result in the lpd3dVDst parameter.

HRESULT Transform(
D3DVECTOR *lpd3dVDst,
D3DVECTOR *lpd3dVSrc
);

Parameters
lpd3dVDst
Address of a D3DVECTOR structure that will be filled with the result of the transformation operation.
lpd3dVSrc
Address of a D3DVECTOR structure that is the source of the transformation operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame::InverseTransform, 3-D Transformations


IDirect3DRMFrame2

The IDirect3DRMFrame2 interface is an extension of the IDirect3DRMFrame interface. IDirect3DRMFrame2 has additional methods that enable using materials, bounding boxes, and axes with frames. IDirect3DRMFrame2 also has a IDirect3DRMFrame2::RayPick method to calculate the intersections of visuals in the frame with a ray of specified position and direction. In addition, IDirect3DRMFrame2 has one changed method IDirect3DRMFrame2::AddMoveCallback2.

For a conceptual overview, see IDirect3DRMFrame, IDirect3DRMFrame2, and IDirect3DRMFrameArray Interfaces.

The methods of the IDirect3DRMFrame2 interface can be organized into the following groups:

Axes | GetAxes
GetInheritAxes
SetAxes
SetInheritAxes
Background | GetSceneBackground
GetSceneBackgroundDepth
SetSceneBackground
SetSceneBackgroundDepth
SetSceneBackgroundImage
SetSceneBackgroundRGB
Bounding Box | GetBox
GetBoxEnable
GetHierarchyBox
SetBox
SetBoxEnable
Color | GetColor
SetColor
SetColorRGB
Fog | GetSceneFogColor
GetSceneFogEnable
GetSceneFogMode
GetSceneFogParams
SetSceneFogColor
SetSceneFogEnable
SetSceneFogMode
SetSceneFogParams
Hierarchies | AddChild
DeleteChild
GetChildren
GetParent
GetScene
Lighting | AddLight
DeleteLight
GetLights
Loading | Load
Material | GetMaterial
SetMaterial
Material modes | GetMaterialMode
SetMaterialMode
Positioning and movement | AddMoveCallback2
AddRotation
AddScale
AddTranslation
DeleteMoveCallback
GetOrientation
GetPosition
GetRotation
GetVelocity
LookAt
Move
SetOrientation
SetPosition
SetQuaternion
SetRotation
SetVelocity
Ray Picking | RayPick
Sorting | GetSortMode
GetZbufferMode
SetSortMode
SetZbufferMode
Textures | GetTexture
GetTextureTopology
SetTexture
SetTextureTopology
Transformations | AddTransform
GetTransform
InverseTransform
Transform
Visual objects | AddVisual
DeleteVisual
GetVisuals

The IDirect3DRMFrame2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMFrame2 interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMFrame2 object is obtained by using the IDirect3DRM2::CreateFrame method.

IDirect3DRMFrame2::AddChild

IDirect3DRMFrame2

Adds a child frame to a frame hierarchy.

HRESULT AddChild(
LPDIRECT3DRMFRAME lpD3DRMFrameChild
);

Parameters
lpD3DRMFrameChild
Address of the Direct3DRMFrame object that will be added as a child.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.

To preserve an object's transformation, use the IDirect3DRMFrame2::GetTransform method to retrieve the object's transformation before using the AddChild method. Then reapply the transformation after the frame is added.

See Also

Hierarchies

IDirect3DRMFrame2::AddLight

IDirect3DRMFrame2

Adds a light to a frame.

HRESULT AddLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters
lpD3DRMLight
Address of a variable that represents the Direct3DRMLight object to be added to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::AddMoveCallback2

IDirect3DRMFrame2

Adds a callback function for special movement processing. The callback is called when the frame is moved or updated.

HRESULT AddMoveCallback2(
D3DRMFRAME2MOVECALLBACK d3drmFMC,
VOID * lpArg,
DWORD dwFlags
);

Parameters
d3drmFMC
Application-defined D3DRMFRAME2MOVECALLBACK callback function.
lpArg
Application-defined data to be passed to the callback function.
dwFlags
One of the following values:
D3DRMCALLBACK_PREORDER — The default value. When IDirect3DRMFrame2::Move traverses the hierarchy, callbacks for a frame are used before any child frames are traversed.
D3DRMCALLBACK_POSTORDER — When IDirect3DRMFrame2::Move traverses the hierarchy, callbacks for a frame are used after the child frames are traversed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Multiple callbacks on an individual frame are used in the order that the callbacks were created.

See Also

IDirect3DRMFrame2::Move, IDirect3DRMFrame2::DeleteMoveCallback

IDirect3DRMFrame2::AddRotation

IDirect3DRMFrame2

Adds a rotation about (rvX, rvY, rvZ) by the number of radians specified in rvTheta.

HRESULT AddRotation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters
rctCombine
A member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new rotation with any current frame transformation.
rvX, rvY, and rvZ
Axis about which to rotate.
rvTheta
Angle of rotation, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified rotation changes the matrix only for the frame identified by this IDirect3DRMFrame2 interface. This method changes the objects in the frame only once, unlike IDirect3DRMFrame2::SetRotation, which changes the matrix with every render tick.

See Also

3-D Transformations, IDirect3DRMFrame2::SetRotation

IDirect3DRMFrame2::AddScale

IDirect3DRMFrame2

Scales a frame's local transformation by (rvX, rvY, rvZ).

HRESULT AddScale(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new scale with any current frame transformation.
rvX, rvY, and rvZ
Scale factors in the x-, y-, and z-directions.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified transformation only changes the matrix for the frame identified by the IDirect3DRMFrame2 interface.

See Also

3-D Transformations

IDirect3DRMFrame2::AddTransform

IDirect3DRMFrame2

Transforms the local coordinates of the frame by the affine transformation specified by rctCombine and rmMatrix.

HRESULT AddTransform(
D3DRMCOMBINETYPE rctCombine,
D3DRMMATRIX4D rmMatrix
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new transformation with any current transformation.
rmMatrix
Member of the D3DRMMATRIX4D array that defines the transformation matrix to be combined.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Although a 4×4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.

The specified transformation changes the matrix only for the frame identified by this IDirect3DRMFrame2 interface.

See Also

3-D Transformations

IDirect3DRMFrame2::AddTranslation

IDirect3DRMFrame2

Adds a translation by (rvX, rvY, rvZ) to a frame's local coordinate system.

HRESULT AddTranslation(
D3DRMCOMBINETYPE rctCombine,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
rctCombine
Member of the D3DRMCOMBINETYPE enumerated type that specifies how to combine the new translation with any current translation.
rvX, rvY, and rvZ
Definitions of the position changes in the x-, y-, and z-directions.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified translation changes the matrix only for the frame identified by this IDirect3DRMFrame2 interface.

See Also

3-D Transformations

IDirect3DRMFrame2::AddVisual

IDirect3DRMFrame2

Adds a visual object to a frame.

HRESULT AddVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters
lpD3DRMVisual
Address of a variable that represents the Direct3DRMVisual object to be added to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The frame references the visual object.

IDirect3DRMFrame2::DeleteChild

IDirect3DRMFrame2

Removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.

HRESULT DeleteChild(
LPDIRECT3DRMFRAME lpChild
);

Parameters
lpChild
Address of the Direct3DRMFrame object to be used as the child.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

Hierarchies

IDirect3DRMFrame2::DeleteLight

IDirect3DRMFrame2

Removes a light from a frame, destroying the light if it is no longer referenced. When a light is removed from a frame, the light no longer affects meshes in the scene its frame was in.

HRESULT DeleteLight(
LPDIRECT3DRMLIGHT lpD3DRMLight
);

Parameters
lpD3DRMLight
Address of a variable that represents the Direct3DRMLight object to be removed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::DeleteMoveCallback

IDirect3DRMFrame2

Removes a frame-move callback function previously added with AddMoveCallback.

HRESULT DeleteMoveCallback(
D3DRMFRAMEMOVECALLBACK d3drmFMC,
VOID * lpArg
);

Parameters
d3drmFMC
Application-defined D3DRMFRAMEMOVECALLBACK callback function.
lpArg
Application-defined data that was passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::AddMoveCallback2, IDirect3DRMFrame2::Move

IDirect3DRMFrame2::DeleteVisual

IDirect3DRMFrame2

Removes a visual object from a frame, destroying it if it is no longer referenced.

HRESULT DeleteVisual(
LPDIRECT3DRMVISUAL lpD3DRMVisual
);

Parameters
lpD3DRMVisual
Address of a variable that represents the Direct3DRMVisual object to be removed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::GetAxes

IDirect3DRMFrame2

Retrieves the vectors that are aligned with the direction (rvDx, rvDy, rvDz) and up (rvUx, rvUy, rvUz) vectors supplied to the IDirect3DRMFrame2::SetOrientation method.

HRESULT GetAxes(
LPD3DVECTOR dir,
LPD3DVECTOR up
);

Parameters
dir
The z-axis for the frame. Default is (0,0,1).
up
The y-axis for the frame. Default is (0,1,0).
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method along with IDirect3DRMFrame2::SetAxes helps support both left-handed and right-handed coordinate systems. SetAxes allows you to specify that the negative z-axis represents the front of the object.

See Also

IDirect3DRMFrame2::SetAxes, IDirect3DRMFrame2::GetInheritAxes, IDirect3DRMFrame2::SetInheritAxes

IDirect3DRMFrame2::GetBox

IDirect3DRMFrame2

Retrieves the bounding box containing a DIRECT3DRMFRAME2 object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX * lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. Returns D3DRMERR_BOXNOTSET unless a valid bounding box has already been set on the frame. For a list of other possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method supports a bounding box on a frame for hierarchical culling. A valid bounding box must be set on the frame with IDirect3DRMFrame2::SetBox. For a bounding box to be enabled, the IDirect3DRMFrame2::SetBoxEnable method must be used to set the enable flag to TRUE. By default, the box-enable flag is FALSE. There is no default bounding box.

See Also

IDirect3DRMFrame2::SetBox, IDirect3DRMFrame2::SetBoxEnable, IDirect3DRMFrame2::GetBoxEnable

IDirect3DRMFrame2::GetBoxEnable

IDirect3DRMFrame2

Retrieves the flag that determines whether a bounding box is enabled for this Direct3DRMFrame2 object.

BOOL GetBoxEnable( );

Return Values

Returns TRUE if a bounding box is enabled, or FALSE if it is not enabled.

Remarks

For a bounding box to be enabled, the IDirect3DRMFrame2::SetBoxEnable flag must be used to set the enable flag to TRUE. By default, the box enable flag is FALSE.

See Also

IDirect3DRMFrame2::SetBoxEnable IDirect3DRMFrame2::GetBox, IDirect3DRMFrame2::SetBox

IDirect3DRMFrame2::GetChildren

IDirect3DRMFrame2

Retrieves a list of child frames in the form of a Direct3DRMFrameArray object.

HRESULT GetChildren(
LPDIRECT3DRMFRAMEARRAY* lplpChildren
);

Parameters
lplpChildren
Address of a pointer to be initialized with a valid Direct3DRMFrameArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

DIRECT3DRMFRAMEARRAY, Hierarchies

IDirect3DRMFrame2::GetColor

IDirect3DRMFrame2

Retrieves the color of the frame.

D3DCOLOR GetColor( );

Return Values

Returns the color of the Direct3DRMFrame2 object.

See Also

IDirect3DRMFrame2::SetColor

IDirect3DRMFrame2::GetHierarchyBox

IDirect3DRMFrame2

Calculates a bounding box to contain all the geometry in the hierarchy rooted in this Direct3DRMFrame2 object.

HRESULT GetHierarchyBox(
D3DRMBOX * lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetBox, IDirect3DRMFrame2::SetBox, IDirect3DRMFrame2::SetBoxEnable, IDirect3DRMFrame2::GetBoxEnable

IDirect3DRMFrame2::GetInheritAxes

IDirect3DRMFrame2

Retrieves the flag that indicates whether the axes for the frame are inherited from the parent frame.

BOOL GetInheritAxes( );

Return Values

Returns TRUE if the frame inherits axes (the default) and FALSE if the frame does not inherit axes.

Remarks

By default, the axes are inherited from the parent. If a frame is set to inherit from a parent and there is no parent, the frame acts as if it inherits from a parent with the default axes (direction=(0,0,1) and up=(0,1,0)).

This method and the IDirect3DRMFrame2::SetInheritAxes method allow a single policy for axes to be set at the root of the hierarchy.

See Also

IDirect3DRMFrame2::SetInheritAxes, IDirect3DRMFrame2::GetAxes, IDirect3DRMFrame2::SetAxes

IDirect3DRMFrame2::GetLights

IDirect3DRMFrame2

Retrieves a list of lights in the frame in the form of a Direct3DRMLightArray object.

HRESULT GetLights(
LPDIRECT3DRMLIGHTARRAY* lplpLights
);

Parameters
lplpLights
Address of a pointer to be initialized with a valid Direct3DRMLightArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMLightArray

IDirect3DRMFrame2::GetMaterial

IDirect3DRMFrame2

Retrieves the material of the Direct3DRMFrame2 object.

HRESULT GetMaterial(
LPDIRECT3DRMMATERIAL *lplpMaterial
);

Parameters
lplpMaterial
Address of a variable that will be filled with a pointer to the Direct3DRMMaterial object that is applied to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetMaterial

IDirect3DRMFrame2::GetMaterialMode

IDirect3DRMFrame2

Retrieves the material mode of the frame.

D3DRMMATERIALMODE GetMaterialMode( );

Return Values

Returns a member of the D3DRMMATERIALMODE enumerated type that specifies the current material mode.

See Also

IDirect3DRMFrame2::SetMaterialMode

IDirect3DRMFrame2::GetOrientation

IDirect3DRMFrame2

Retrieves the orientation of a frame relative to the given reference frame.

HRESULT GetOrientation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvDir,
LPD3DVECTOR lprvUp
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvDir and lprvUp
Addresses of D3DVECTOR structures that will be filled with the normalized directions of the frame's z-axis and y-axis, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetOrientation

IDirect3DRMFrame2::GetParent

IDirect3DRMFrame2

Retrieves the parent frame of the current frame.

HRESULT GetParent(
LPDIRECT3DRMRAME * lplpParent
);

Parameters
lplpParent
Address of a pointer that will be filled with the pointer to the Direct3DRMFrame object representing the frame's parent. If the current frame is the root, this pointer will be NULL when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::GetPosition

IDirect3DRMFrame2

Retrieves the position of a frame relative to the given reference frame, that is, it retrieves the distance of the frame from the reference. The distance is stored in the lprvPos parameter as a vector rather than as a linear measure.

HRESULT GetPosition(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvPos
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvPos
Address of a D3DVECTOR structure that will be filled with the frame's position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetPosition

IDirect3DRMFrame2::GetRotation

IDirect3DRMFrame2

Retrieves the rotation of the frame relative to the given reference frame.

HRESULT GetRotation(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvAxis,
LPD3DVALUE lprvTheta
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvAxis
Address of a D3DVECTOR structure that will be filled with the frame's axis of rotation.
lprvTheta
Address of a variable that will be the frame's rotation, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetRotation, Transformations

IDirect3DRMFrame2::GetScene

IDirect3DRMFrame2

Retrieves the root frame of the hierarchy containing the given frame.

HRESULT GetScene(
LPDIRECT3DRMFRAME lplpRoot
);

Parameters
lplpRoot
Address of the pointer that will be filled with the pointer to the Direct3DRMFrame object representing the scene's root frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::GetSceneBackground

IDirect3DRMFrame2

Retrieves the background color of a scene.

D3DCOLOR GetSceneBackground( );

Return Values

Returns the color.

IDirect3DRMFrame2::GetSceneBackgroundDepth

IDirect3DRMFrame2

Retrieves the current background-depth buffer for the scene.

HRESULT GetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE * lplpDDSurface
);

Parameters
lplpDDSurface
Address of a pointer that will be initialized with the address of a DirectDraw surface representing the current background-depth buffer.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetSceneBackgroundDepth

IDirect3DRMFrame2::GetSceneFogColor

IDirect3DRMFrame2

Retrieves the fog color of a scene.

D3DCOLOR GetSceneFogColor( );

Return Values

Returns the fog color.

IDirect3DRMFrame2::GetSceneFogEnable

IDirect3DRMFrame2

Retrieves whether fog is currently enabled for this scene.

BOOL GetSceneFogEnable( );

Return Values

Returns TRUE if fog is enabled, and FALSE otherwise.

IDirect3DRMFrame2::GetSceneFogMode

IDirect3DRMFrame2

Retrieves the current fog mode for this scene.

D3DRMFOGMODE GetSceneFogMode( );

Return Values

Returns a member of the D3DRMFOGMODE enumerated type that specifies the current fog mode.

IDirect3DRMFrame2::GetSceneFogParams

IDirect3DRMFrame2

Retrieves the current fog parameters for this scene.

HRESULT GetSceneFogParams(
D3DVALUE * lprvStart,
D3DVALUE * lprvEnd,
D3DVALUE * lprvDensity
);

Parameters
lprvStart, lprvEnd, and lprvDensity
Addresses of variables that will be the fog start, end, and density values.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::GetSortMode

IDirect3DRMFrame2

Retrieves the sorting mode used to process child frames.

D3DRMSORTMODE GetSortMode( );

Return Values

Returns the member of the D3DRMSORTMODE enumerated type that specifies the sorting mode.

See Also

IDirect3DRMFrame2::SetSortMode

IDirect3DRMFrame2::GetTexture

IDirect3DRMFrame2

Retrieves the texture of the given frame.

HRESULT GetTexture(
LPDIRECT3DRMTEXTURE* lplpTexture
);

Parameters
lplpTexture
Address of the pointer that will be filled with the address of the Direct3DRMTexture object representing the frame's texture.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetTexture

IDirect3DRMFrame2::GetTextureTopology

IDirect3DRMFrame2

Retrieves the topological properties of a texture when mapped onto objects in the given frame.

HRESULT GetTextureTopology(
BOOL * lpbWrap_u,
BOOL * lpbWrap_v
);

Parameters
lpbWrap_u and lpbWrap_v
Addresses of variables that are set to TRUE if the texture is mapped in the u- and v-directions, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetTextureTopology

IDirect3DRMFrame2::GetTransform

IDirect3DRMFrame2

Retrieves the local transformation of the frame as a 4×4 affine matrix.

HRESULT GetTransform(
D3DRMMATRIX4D rmMatrix
);

Parameters
rmMatrix
A D3DRMMATRIX4D array that will be filled with the frame's transformation. Because this is an array, this value is actually an address.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

3-D Transformations

IDirect3DRMFrame2::GetVelocity

IDirect3DRMFrame2

Retrieves the velocity of the frame relative to the given reference frame. Velocity is specified as units per tick. See IDirect3DRM::Tick for more information.

HRESULT GetVelocity(
LPDIRECT3DRMFRAME lpRef,
LPD3DVECTOR lprvVel,
BOOL fRotVel
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
lprvVel
Address of a D3DVECTOR structure that will be filled with the frame's velocity.
fRotVel
Flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is TRUE, the object's rotational velocity is included in the calculation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetVelocity

IDirect3DRMFrame2::GetVisuals

IDirect3DRMFrame2

Retrieves a list of visuals in the frame.

HRESULT GetVisuals(
LPDIRECT3DRMVISUALARRAY* lplpVisuals
);

Parameters
lplpVisuals
Address of a pointer to be initialized with a valid Direct3DRMVisualArray pointer if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::GetZbufferMode

IDirect3DRMFrame2

Retrieves the z-buffer mode; that is, whether z-buffering is enabled or disabled.

D3DRMZBUFFERMODE GetZbufferMode( );

Return Values

Returns one of the members of the D3DRMZBUFFERMODE enumerated type.

See Also

IDirect3DRMFrame2::SetZbufferMode

IDirect3DRMFrame2::InverseTransform

IDirect3DRMFrame2

Transforms the vector in the lprvSrc parameter in world coordinates to model coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
D3DVECTOR *lprvDst,
D3DVECTOR *lprvSrc
);

Parameters
lprvDst
Address of a D3DVECTOR structure that will be filled with the result of the transformation.
lprvSrc
Address of a D3DVECTOR structure that is the source of the transformation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::Transform, 3-D Transformations

IDirect3DRMFrame2::Load

IDirect3DRMFrame2

Loads a Direct3DRMFrame2 object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpArgLTP
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by the object that require special formatting. This parameter can be NULL.
lpArgLTP
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first frame hierarchy in the file specified by the lpvObjSource parameter. The frame that uses this method is used as the parent of the new frame hierarchy.

IDirect3DRMFrame2::LookAt

IDirect3DRMFrame2

Faces the frame toward the target frame, relative to the given reference frame, locking the rotation by the given constraints.

HRESULT LookAt(
LPDIRECT3DRMFRAME lpTarget,
LPDIRECT3DRMFRAME lpRef,
D3DRMFRAMECONSTRAINT rfcConstraint
);

Parameters
lpTarget and lpRef
Addresses of variables that represent the Direct3DRMFrame objects to be used as the target and reference, respectively.
rfcConstraint
Member of the D3DRMFRAMECONSTRAINT enumerated type that specifies the axis of rotation to constrain.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::Move

IDirect3DRMFrame2

Applies the linear and rotational velocities for all frames in the given hierarchy.

HRESULT Move(
D3DVALUE delta
);

Parameters
delta
Amount to change the linear and rotational velocity. The change in each component is equal to the velocity of that component multiplied by delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::RayPick

IDirect3DRMFrame2

Searches the hierarchy starting at this Direct3DRMFrame2 object and calculates the intersections between any visuals and the ray specified by the dvPosition and dvDirection parameters in the coordinate space specified by the lpRefFrame parameter.

HRESULT RayPick(
LPDIRECT3DRMFRAME lpRefFrame,
LPD3DRMRAY ray,
DWORD dwFlags,
LPD3DRMPICKED2ARRAY* lplpPicked2Array
);

Parameters
lpRefFrame
Address of the Direct3DRMFrame object that contains the ray.
ray
Pointer to a D3DRMRAY structure that contains two D3DVECTOR structures. The first D3DVECTOR structure is the vector direction of the ray. The second D3DVECTOR structure is the position of the origin of the ray.
dwFlags
Can be one of the following values:
D3DRMRAYPICK_ONLYBOUNDINGBOXES – Only intersections with bounding boxes of the visuals in the hierarchy are returned. Does not check for exact face intersections.
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES – Only the closest visual that intersects the ray is returned. Ignores visuals farther away than the closest one found so far in a search.
D3DRMRAYPICK_INTERPOLATEUV – Interpolate texture coordinates.
D3DRMRAYPICK_INTERPOLATECOLOR – Interpolate color.
D3DRMRAYPICK_INTERPOLATENORMAL – Interpolate normal.
lplpPicked2Array
The address of a pointer to be initialized with a valid pointer to the IDirect3DRMPicked2Array interface. You then use the IDirect3DRMPicked2Array::GetPick method to retrieve a visual object, an IDirect3DRMFrameArray interface, and a D3DRMPICKDESC2 structure. The array of frames is the path through the hierarchy leading to the visual object that intersected the ray. The D3DRMPICKDESC2 structure contains the face and group identifiers, pick position, horizontal and vertical texture coordinates for the vertex, vertex normal, and color of the intersected objects.

If you specify D3DRMRAYPICK_ONLYBOUNDINGBOXES, the texture, normal, and color data in the D3DRMPICKDESC2 structure will be invalid.

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

There are two kinds of flags: optimization flags and interpolation flags. Optimization flags allow you to limit the search and therefore make it faster. Interpolation flags specify what to interpolate if a primitive is hit. The three interpolation choices are color, normal, and texture coordinates.

The ray is specified in the reference frame coordinate space (pointed to by lpRefFrame). If the reference frame is NULL, the ray is specified in world coordinates.

IDirect3DRMFrame2::Save

IDirect3DRMFrame2

Saves a Direct3DRMFrame2 object to the specified file.

HRESULT Save(
LPCSTR lpFilename,
D3DRMXOFFORMAT d3dFormat,
D3DRMSAVEOPTIONS d3dSaveFlags
);

Parameters
lpFilename
Address specifying the name of the created file. This file must have a .x file name extension.
d3dFormat
D3DRMXOF_TEXT value from the D3DRMXOFFORMAT enumerated type.
d3dSaveFlags
Value of the D3DRMSAVEOPTIONS type describing the save options.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::SetAxes

IDirect3DRMFrame2

Sets the vectors that define a coordinate space by which the IDirect3DRMFrame2::SetOrientation vectors are transformed.

HRESULT SetAxes(
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz
);

Parameters
dx, dy, dz
The z-axis for the frame. Default is (0,0,1).
ux, uy, uz
The y-axis for the frame. Default is (0,1,0).
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method helps support both left-handed and right-handed coordinate systems. This method also allows you to specify that the negative z-axis represents the front of the object.

The IDirect3DRMFrame2::SetOrientation direction (rvDx, rvDy, rvDz) and up (rvUx, rvUy, rvUz) vectors are transformed according to the value of the SetAxes vectors.

The axes are inherited by child frames as specified in IDirect3DRMFrame2::SetInheritAxes.

See Also

IDirect3DRMFrame2::GetAxes, IDirect3DRMFrame2::GetInheritAxes, IDirect3DRMFrame2::SetInheritAxes

IDirect3DRMFrame2::SetBox

IDirect3DRMFrame2

Sets the box to be used in bounding-box testing. In order for the bounding box to be valid, its minimum x must be less than or equal to its maximum x, minimum y must be less than or equal to its maximum y, and minimum z must be less than or equal to its maximum z.

HRESULT SetBox(
D3DRMBOX * lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that contains the bounding-box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method supports a bounding box on a frame for hierarchical culling. For a bounding box to be enabled, the IDirect3DRMFrame2::SetBoxEnable method must be used to set the enable flag to TRUE. By default, the box-enable flag is FALSE.

See Also

IDirect3DRMFrame2::GetBox, IDirect3DRMFrame2::SetBoxEnable, IDirect3DRMFrame2::GetBoxEnable

IDirect3DRMFrame2::SetBoxEnable

IDirect3DRMFrame2

Enables or disables bounding-box testing for this Direct3DRMFrame2 object. Bounding-box testing cannot be enabled unless a valid bounding box has already been set on the frame.

HRESULT SetBoxEnable(
BOOL bEnableFlag
);

Parameters
bEnableFlag
Flag specifying whether bounding boxes are enabled or not. TRUE to enable a bounding box. FALSE if a bounding box is not enabled. Default is FALSE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

For a bounding box to be enabled, this method must be used to set the enable flag to TRUE. By default, the box-enable flag is FALSE.

Bounding-box testing is performed as follows: At render time, the bounding box is transformed into model space and checked for intersection with the viewing frustum. If the entire box is outside of the viewing frustum, none of the visuals in the frame, or in any child frame, are rendered. Otherwise, rendering continues as normal.

Enabling bounding-box testing with a box of {0,0,0,0} completely prevents a frame from being rendered.

See Also

IDirect3DRMFrame2::GetBoxEnable, IDirect3DRMFrame2::GetBox, IDirect3DRMFrame2::SetBox

IDirect3DRMFrame2::SetColor

IDirect3DRMFrame2

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColor(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a color key to a DIRECT3DRMFRAMEINTERPOLATOR object.

See Also

IDirect3DRMFrame2::GetColor, IDirect3DRMFrame2::SetMaterialMode

IDirect3DRMFrame2::SetColorRGB

IDirect3DRMFrame2

Sets the color of the frame. This color is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters
rvRed, rvGreen, and rvBlue
New color for the frame. Each component of the color should be in the range 0 to 1.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add an RGB color key to a DIRECT3DRMFRAMEINTERPOLATOR object.

See Also

IDirect3DRMFrame2::SetMaterialMode

IDirect3DRMFrame2::SetInheritAxes

IDirect3DRMFrame2

Specifies whether the axes for the frame are inherited from the parent frame.

HRESULT SetInheritAxes(
BOOL inherit_from_parent
);

Parameters
inherit_from_parent
Flag indicating whether the frame should inherit axes from its parent. If TRUE, the frame inherits axes (the default). If FALSE, the frame does not inherit axes.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, the axes are inherited from the parent. If a frame is set to inherit from the parent, and there is no parent, the frame acts as if it inherits from a parent with the default axes (direction=(0,0,1) and up=(0,1,0)). This method allows a single policy for axes to be set at the root of the hierarchy.

See Also

IDirect3DRMFrame2::GetInheritAxes, IDirect3DRMFrame2::GetAxes, IDirect3DRMFrame2::SetAxes

IDirect3DRMFrame2::SetMaterial

IDirect3DRMFrame2

Sets the material of the Direct3DRMFrame2 object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL *lplpMaterial
);

Parameters
lplpMaterial
Address of the Direct3DRMMaterial object that will be applied to the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetMaterial

IDirect3DRMFrame2::SetMaterialMode

IDirect3DRMFrame2

Sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.

HRESULT SetMaterialMode(
D3DRMMATERIALMODE rmmMode
);

Parameters
rmmMode
One of the members of the D3DRMMATERIALMODE enumerated type.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetMaterialMode

IDirect3DRMFrame2::SetOrientation

IDirect3DRMFrame2

Aligns a frame so that its z-direction points along the direction vector [rvDx, rvDy, rvDz] and its y-direction aligns with the vector [rvUx, rvUy, rvUz].

HRESULT SetOrientation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvDx,
D3DVALUE rvDy,
D3DVALUE rvDz,
D3DVALUE rvUx,
D3DVALUE rvUy,
D3DVALUE rvUz
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvDx, rvDy, and rvDz
New z-axis for the frame.
rvUx, rvUy, and rvUz
New y-axis for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

If [rvUx, rvUy, rvUz] is parallel to [rvDx, rvDy, rvDz], the D3DRMERR_BADVALUE error value is returned; otherwise, the [rvUx, rvUy, rvUz] vector passed is projected onto the plane that is perpendicular to [rvDx, rvDy, rvDz].

This method is also used to add an orientation key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame2::GetOrientation

IDirect3DRMFrame2::SetPosition

IDirect3DRMFrame2

Sets the position of a frame relative to the frame of reference. It places the frame a distance of [rvX, rvY, rvZ] from the reference. When a child frame is created within a parent, it is placed at [0, 0, 0] in the parent frame.

HRESULT SetPosition(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
New position for the frame.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a position key to a Direct3DRMFrameInterpolator object.

See Also

IDirect3DRMFrame2::GetPosition

IDirect3DRMFrame2::SetQuaternion

IDirect3DRMFrame2

Sets a frame's orientation relative to a reference frame using a unit quaternion.

HRESULT SetQuaternion(
LPDIRECT3DRMFRAME2 lpRef,
D3DRMQUATERNION *quat
)

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame2 object to be used as the reference.
quat
A D3DRMQUATERNION structure that holds the unit quaternion.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

A quaternion is a four-valued vector that can be used to represent any rotation and that has properties that are useful when interpolating between orientations. A quaternion is a unit quaternion if s**2 + x**2 + y**2 + z**2 = 1.

The function D3DRMQuaternionFromRotation can be used to generate unit quaternions from arbitrary rotation values.

The SetQuaternion method is supported by FrameInterpolators. See IDirect3DRMInterpolator Interface for more information about interpolators.

IDirect3DRMFrame2::SetRotation

IDirect3DRMFrame2

Sets a frame rotating by the given angle around the given vector at each call to the IDirect3DRM::Tick or IDirect3DRMFrame2::Move method. The direction vector [rvX, rvY, rvZ] is defined in the reference frame.

HRESULT SetRotation(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
D3DVALUE rvTheta
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
Vector about which rotation occurs.
rvTheta
Rotation angle, in radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The specified rotation changes the matrix with every render tick, unlike the IDirect3DRMFrame2::AddRotation method, which changes the objects in the frame only once.

See Also

IDirect3DRMFrame2::AddRotation, IDirect3DRMFrame2::GetRotation

IDirect3DRMFrame2::SetSceneBackground

IDirect3DRMFrame2

Sets the background color of a scene.

HRESULT SetSceneBackground(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the background.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a background color key to a Direct3DRMFrameInterpolator object.

IDirect3DRMFrame2::SetSceneBackgroundDepth

IDirect3DRMFrame2

Specifies a background-depth buffer for a scene.

HRESULT SetSceneBackgroundDepth(
LPDIRECTDRAWSURFACE lpImage
);

Parameters
lpImage
Address of a DirectDraw surface that will store the new background depth for the scene.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The image must have a depth of 16 bits per pixel. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.

See Also

IDirect3DRMFrame2::GetSceneBackgroundDepth

IDirect3DRMFrame2::SetSceneBackgroundImage

IDirect3DRMFrame2

Specifies a background image for a scene.

HRESULT SetSceneBackgroundImage(
LPDIRECT3DRMTEXTURE lpTexture
);

Parameters
lpTexture
Address of a Direct3DRMTexture object that will contain the new background scene.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring any extra overhead.

IDirect3DRMFrame2::SetSceneBackgroundRGB

IDirect3DRMFrame2

Sets the background color of a scene.

HRESULT SetSceneBackgroundRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters
rvRed, rvGreen, and rvBlue
New color for the background.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a background RGB color key to a Direct3DRMFrameInterpolator object.

IDirect3DRMFrame2::SetSceneFogColor

IDirect3DRMFrame2

Sets the fog color of a scene.

HRESULT SetSceneFogColor(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the fog.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a fog color key to a Direct3DRMRFrameInterpolator object.

IDirect3DRMFrame2::SetSceneFogEnable

IDirect3DRMFrame2

Sets the fog-enable state.

HRESULT SetSceneFogEnable(
BOOL bEnable
);

Parameters
bEnable
New fog-enable state.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMFrame2::SetSceneFogMode

IDirect3DRMFrame2

Sets the fog mode.

HRESULT SetSceneFogMode(
D3DRMFOGMODE rfMode
);

Parameters
rfMode
One of the members of the D3DRMFOGMODE enumerated type, specifying the new fog mode.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::SetSceneFogParams

IDirect3DRMFrame2::SetSceneFogParams

IDirect3DRMFrame2

Sets the current fog parameters for this scene.

HRESULT SetSceneFogParams(
D3DVALUE rvStart,
D3DVALUE rvEnd,
D3DVALUE rvDensity
);

Parameters
rvStart and rvEnd
Fog start and end points for linear fog mode. These settings determine the distance from the camera at which fog effects first become visible, and the distance at which fog reaches its maximum density.
rvDensity
Fog density for the exponential fog modes. This value should be in the range 0 through 1.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a fog parameters key to a Direct3DRMRFrameInterpolator object.

See Also

D3DRMFOGMODE, IDirect3DRMFrame2::SetSceneFogMode

IDirect3DRMFrame2::SetSortMode

IDirect3DRMFrame2

Sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.

HRESULT SetSortMode(
D3DRMSORTMODE d3drmSM
);

Parameters
d3drmSM
One of the members of the D3DRMSORTMODE enumerated type, specifying the sorting mode. The default value is D3DRMSORT_FROMPARENT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetSortMode

IDirect3DRMFrame2::SetTexture

IDirect3DRMFrame2

Sets the texture of the frame.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters
lpD3DRMTexture
Address of a variable that represents the Direct3DRMTexture object to be used.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The texture is used for meshes in the frame when the D3DRMMATERIALMODE enumerated type is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a NULL texture.

See Also

IDirect3DRMFrame2::GetTexture, IDirect3DRMFrame2::SetMaterialMode

IDirect3DRMFrame2::SetTextureTopology

IDirect3DRMFrame2

Defines the topological properties of the texture coordinates across objects in the frame.

HRESULT SetTextureTopology(
BOOL bWrap_u,
BOOL bWrap_v
);

Parameters
bWrap_u and bWrap_v
Variables that are set to TRUE to map the texture in the u- and v-directions, respectively.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetTextureTopology

IDirect3DRMFrame2::SetVelocity

IDirect3DRMFrame2

Sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [rvX, rvY, rvZ] with respect to the reference frame at each successive call to the IDirect3DRM::Tick or IDirect3DRMFrame2::Move method.

HRESULT SetVelocity(
LPDIRECT3DRMFRAME lpRef,
D3DVALUE rvX,
D3DVALUE rvY,
D3DVALUE rvZ,
BOOL fRotVel
);

Parameters
lpRef
Address of a variable that represents the Direct3DRMFrame object to be used as the reference.
rvX, rvY, and rvZ
New velocity for the frame.
fRotVel
Flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If TRUE, the object's rotational velocity is included in the calculation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetVelocity

IDirect3DRMFrame2::SetZbufferMode

IDirect3DRMFrame2

Sets the z-buffer mode; that is, whether z-buffering is enabled or disabled.

HRESULT SetZbufferMode(
D3DRMZBUFFERMODE d3drmZBM
);

Parameters
d3drmZBM
One of the members of the D3DRMZBUFFERMODE enumerated type, specifying the z-buffer mode. The default value is D3DRMZBUFFER_FROMPARENT.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::GetZbufferMode

IDirect3DRMFrame2::Transform

IDirect3DRMFrame2

Transforms the vector in the lpd3dVSrc parameter in model coordinates to world coordinates, returning the result in the lpd3dVDst parameter.

HRESULT Transform(
D3DVECTOR *lpd3dVDst,
D3DVECTOR *lpd3dVSrc
);

Parameters
lpd3dVDst
Address of a D3DVECTOR structure that will be filled with the result of the transformation operation.
lpd3dVSrc
Address of a D3DVECTOR structure that is the source of the transformation operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMFrame2::InverseTransform, 3-D Transformations


IDirect3DRMInterpolator

Interpolators provide a way of storing actions and applying them to objects with automatic calculation of in-between values. With an interpolator you can blend colors, move objects smoothly between positions, morph meshes, and perform many other transformations.

The IDirect3DRMInterpolator interface is a superset of the IDirect3DRMAnimation interface that increases the kinds of object parameters you can animate. While IDirect3DRMAnimation allows animation of an object's position, size, and orientation, IDirect3DRMInterpolator further enables animation of color, meshes, texture, and material.

For a conceptual overview, see IDirect3DRMInterpolator Overview.

In addition to the standard IUnknown and IDirect3DRMObject methods, IDirect3DRMInterpolator contains the following methods:

Attaching Objects | AttachObject
DetachObject
GetAttachedObjects
Interpolating | GetIndex
Interpolate
SetIndex

The IDirect3DRMInterpolator interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, IDirect3DRMInterpolator interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMInterpolator::AttachObject

IDirect3DRMInterpolator

Connects an object to the interpolator.

HRESULT AttachObject(
LPDIRECT3DRMOBJECT lpD3DRMObject
)

Parameters
lpD3DRMObject
Address of the Direct3DRMObject object to be attached to the interpolator.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The attached object can be another interpolator or an object of type x where the interpolator is of type xInterpolator. For example, a Viewport can be attached to a ViewportInterpolator. The interpolator types are:

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

IDirect3DRMInterpolator::DetachObject

IDirect3DRMInterpolator

Detaches an object from the interpolator.

HRESULT DetachObject(
LPDIRECT3DRMOBJECT lpD3DRMObject
)

Parameters
lpD3DRMObject
Address of the Direct3DRMObject object to be detached from the interpolator.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMInterpolator::GetAttachedObjects

IDirect3DRMInterpolator

Retrieves an array of objects currently attached to the interpolator.

HRESULT GetAttachedObjects(
LPDIRECT3DRMOBJECTARRAY lpD3DRMObjectArray
)

Parameters
lpD3DRMObjectArray
Address of an IDirect3DRMObjectArray object containing the Direct3DRMObject objects currently attached to the interpolator.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMInterpolator::GetIndex

IDirect3DRMInterpolator

Retrieves the interpolator's current internal index (time).

D3DVALUE GetIndex( )

Return Values

Returns a D3DVALUE that contains the interpolator's current internal index.

Remarks

Every key stored in an interpolator has an index value. When a key is recorded (by using a method), the key is stamped with the current interpolator index value. The key's index value does not change after being stamped.

IDirect3DRMInterpolator::Interpolate

IDirect3DRMInterpolator

Generates a series of actions by interpolating between keys stored in the interpolator. The actions are then applied to the specified object. If no object is specified, the actions are applied to the currently attached objects.

HRESULT Interpolate(
D3DVALUE d3dVal,
LPDIRECT3DRMOBJECT lpD3DRMObject,
D3DRMINTERPOLATIONOPTIONS d3drmInterpFlags
)

Parameters
d3dVal
A D3DVALUE that contains the interpolator's current internal index.
lpD3DRMObject
Address of the Direct3DRMObject object which will be assigned interpolated values for all properties stored in the interpolator. Can be NULL, in which case the property values of all attached objects will be set to interpolated values.
d3drmInterpFlags
One of several flags that control the kind of interpolation done. Possible values are:
D3DRMINTERPOLATION_CLOSED
D3DRMINTERPOLATION_LINEAR
D3DRMINTERPOLATION_NEAREST
D3DRMINTERPOLATION_OPEN
D3DRMINTERPOLATION_SLERPNORMALS
D3DRMINTERPOLATION_SPLINE
D3DRMINTERPOLATION_VERTEXCOLOR
See Interpolation Options for a description of these options.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMInterpolator::SetIndex

IDirect3DRMInterpolator

Sets the interpolator's internal index (time) to the specified value. If other interpolators are attached to the interpolator, this method recursively synchronizes their indices to the same value.

HRESULT SetIndex(
D3DVALUE d3dVal
)

Parameters
d3dVal
The time to set for the interpolator's internal index.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Every key stored in an interpolator has an index value. When a key is recorded (by using a method), the key is stamped with the current interpolator index value. The key's index value does not change after being stamped.


IDirect3DRMLight

Applications use the methods of the IDirect3DRMLight interface to interact with light objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMLight and IDirect3DRMLightArray Interfaces.

The methods of the IDirect3DRMLight interface can be organized into the following groups:
Attenuation | GetConstantAttenuation
GetLinearAttenuation
GetQuadraticAttenuation
SetConstantAttenuation
SetLinearAttenuation
SetQuadraticAttenuation
Color | GetColor
SetColor
SetColorRGB
Enable frames | GetEnableFrame
SetEnableFrame
Light types | GetType
SetType
Range | GetRange
SetRange
Spotlight options | GetPenumbra
GetUmbra
SetPenumbra
SetUmbra

The IDirect3DRMLight interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMLight interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMLight object is obtained by using the IDirect3DRM::CreateLight or IDirect3DRM::CreateLightRGB method.

IDirect3DRMLight::GetColor

IDirect3DRMLight

Retrieves the color of the current Direct3DRMLight object.

D3DCOLOR GetColor( );

Return Values

Returns the color.

See Also

IDirect3DRMLight::SetColor

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight

Retrieves the constant attenuation factor for the Direct3DRMLight object.

D3DVALUE GetConstantAttenuation( );

Return Values

Returns the constant attenuation value.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on the distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

See Also

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight

Retrieves the enable frame for a light.

HRESULT GetEnableFrame(
LPDIRECT3DRMFRAME * lplpEnableFrame
);

Parameters
lplpEnableFrame
Address of a pointer that will contain the enable frame for the current Direct3DRMFrame object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight

Retrieves the linear attenuation factor for a light.

D3DVALUE GetLinearAttenuation( );

Return Values

Returns the linear attenuation value.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

See Also

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight

Retrieves the penumbra angle of a spotlight.

D3DVALUE GetPenumbra( );

Return Values

Returns the penumbra value.

See Also

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight

Retrieves the quadratic attenuation factor for a light.

D3DVALUE GetQuadraticAttenuation( );

Return Values

Returns the quadratic attenuation value.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

See Also

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight::GetRange

IDirect3DRMLight

Retrieves the range of the current Direct3DRMLight object.

D3DVALUE GetRange( );

Return Values

Returns a value describing the range.

See Also

IDirect3DRMLight::SetRange

IDirect3DRMLight::GetType

IDirect3DRMLight

Retrieves the type of a given light.

D3DRMLIGHTTYPE GetType( );

Return Values

Returns one of the members of the D3DRMLIGHTTYPE enumerated type.

See Also

IDirect3DRMLight::SetType

IDirect3DRMLight::GetUmbra

IDirect3DRMLight

Retrieves the umbra angle of the Direct3DRMLight object.

D3DVALUE GetUmbra( );

Return Values

Returns the umbra angle.

See Also

IDirect3DRMLight::SetUmbra

IDirect3DRMLight::SetColor

IDirect3DRMLight

Sets the color of the given light.

HRESULT SetColor(
D3DCOLOR rcColor
);

Parameters
rcColor
New color for the light.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a color key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetColor

IDirect3DRMLight::SetColorRGB

IDirect3DRMLight

Sets the color of the given light.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

Parameters
rvRed, rvGreen, and rvBlue
New color for the light.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add an RGB color key to a Direct3DRMLightInterpolator object.

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight

Sets the constant attenuation factor for a light.

HRESULT SetConstantAttenuation(
D3DVALUE rvAtt
);

Parameters
rvAtt
New constant attenuation factor.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on the distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a constant attenuation key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight

Sets the enable frame for a light.

HRESULT SetEnableFrame(
LPDIRECT3DRMFRAME lpEnableFrame
);

Parameters
lpEnableFrame
Address of the light's enable frame. Child frames of this frame are also enabled for this light source.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight

Sets the linear attenuation factor for a light.

HRESULT SetLinearAttenuation(
D3DVALUE rvAtt
);

Parameters
rvAtt
New linear attenuation factor.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a linear attenuation key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight

Sets the angle of the penumbra cone.

HRESULT SetPenumbra(
D3DVALUE rvAngle
);

Parameters
rvAngle
New penumbra angle. This angle must be greater than or equal to the angle of the umbra. If you set the penumbra angle to less than the umbra angle, the umbra angle will be set equal to the penumbra angle. The default value is 0.5 radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a penumbra angle key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight

Sets the quadratic attenuation factor for a light.

HRESULT SetQuadraticAttenuation(
D3DVALUE rvAtt
);

Parameters
rvAtt
New quadratic attenuation factor.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a quadratic attenuation key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight::SetRange

IDirect3DRMLight

Sets the range of a spotlight. The light affects objects that are within the range only.

HRESULT SetRange(
D3DVALUE rvRange
);

Parameters
rvRange
New range. The default value is 256 modeling-space units.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The range property is for spotlights only. This method is also used to add a range key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetRange

IDirect3DRMLight::SetType

IDirect3DRMLight

Changes the light's type.

HRESULT SetType(
D3DRMLIGHTTYPE d3drmtType
);

Parameters
d3drmtType
New light type specified by one of the members of the D3DRMLIGHTTYPE enumerated type.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMLight::GetType

IDirect3DRMLight::SetUmbra

IDirect3DRMLight

Sets the angle of the umbra cone.

HRESULT SetUmbra(
D3DVALUE rvAngle
);

Parameters
rvAngle
New umbra angle. This angle must be less than or equal to the angle of the penumbra. If you set the umbra angle to greater than the penumbra angle, the penumbra angle will be set equal to the umbra angle. The default value is 0.4 radians.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add an umbra angle key to a Direct3DRMLightInterpolator object.

See Also

IDirect3DRMLight::GetUmbra

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMMaterial

Applications use the methods of the IDirect3DRMMaterial interface to interact with material objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMMaterial Interface.

The methods of the IDirect3DRMMaterial interface can be organized into the following groups:
Emission | GetEmissive
SetEmissive
Power for | GetPower
specular exponent | SetPower
Specular | GetSpecular
SetSpecular

The IDirect3DRMMaterial interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMMaterial interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMMaterial object is obtained by using the IDirect3DRM::CreateMaterial method.

IDirect3DRMMaterial::GetEmissive

IDirect3DRMMaterial

Retrieves the setting for the emissive property of a material. The setting of this property is the color and intensity of the light the object emits.

HRESULT GetEmissive(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);

Parameters
lpr, lpg, and lpb
Addresses that will contain the red, green, and blue components of the emissive color when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMaterial::SetEmissive

IDirect3DRMMaterial::GetPower

IDirect3DRMMaterial

Retrieves the power used for the specular exponent in the given material.

D3DVALUE GetPower( );

Return Values

Returns the value specifying the power of the specular exponent.

See Also

IDirect3DRMMaterial::SetPower

IDirect3DRMMaterial::GetSpecular

IDirect3DRMMaterial

Retrieves the color of the specular highlights of a material.

HRESULT GetSpecular(
D3DVALUE *lpr,
D3DVALUE *lpg,
D3DVALUE *lpb
);

Parameters
lpr, lpg, and lpb
Addresses that will contain the red, green, and blue components of the color of the specular highlights when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMaterial::SetSpecular

IDirect3DRMMaterial::SetEmissive

IDirect3DRMMaterial

Sets the emissive property of a material.

HRESULT SetEmissive(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);

Parameters
r, g, and b
Red, green, and blue components of the emissive color.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add an emissive property key to a Direct3DRMMaterialInterpolator object.

See Also

IDirect3DRMMaterial::GetEmissive

IDirect3DRMMaterial::SetPower

IDirect3DRMMaterial

Sets the power used for the specular exponent in a material.

HRESULT SetPower(
D3DVALUE rvPower
);

Parameters
rvPower
New specular exponent.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a spectral power key to a Direct3DRMMaterialInterpolator object.

See Also

IDirect3DRMMaterial::GetPower

IDirect3DRMMaterial::SetSpecular

IDirect3DRMMaterial

Sets the color of the specular highlights for a material.

HRESULT SetSpecular(
D3DVALUE r,
D3DVALUE g,
D3DVALUE b
);

Parameters
r, g, and b
Red, green, and blue components of the color of the specular highlights.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a spectral color key to a Direct3DRMMaterialInterpolator object.

See Also

IDirect3DRMMaterial::GetSpecular

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMMesh

Applications use the methods of the IDirect3DRMMesh interface to interact with groups of meshes. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces.

The methods of the IDirect3DRMMesh interface can be organized into the following groups:

Color | GetGroupColor
SetGroupColor
SetGroupColorRGB
Creation and | AddGroup
information | GetBox
GetGroup
GetGroupCount
Materials | GetGroupMaterial
SetGroupMaterial
Miscellaneous | Scale
Translate
Rendering quality | GetGroupQuality
SetGroupQuality
Texture mapping | GetGroupMapping
SetGroupMapping
Textures | GetGroupTexture
SetGroupTexture
Vertex positions | GetVertices
SetVertices

The IDirect3DRMMesh interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMMesh interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMMesh object is obtained by using the IDirect3DRM::CreateMesh method.

IDirect3DRMMesh::AddGroup

IDirect3DRMMesh

Groups a collection of faces and retrieves an identifier for the group. The first group added to a mesh always has index 0. The index of each successive group increases by 1.

HRESULT AddGroup(
unsigned vCount,
unsigned fCount,
unsigned vPerFace,
unsigned *fData,
D3DRMGROUPINDEX *returnId
);

Parameters
vCount and fCount
Number of vertices and faces in the group.
vPerFace
Number of vertices per face in the group, if all faces have the same vertex count. If the group contains faces with varying vertex counts, this parameter should be zero.
fData
Address of face data. If the vPerFace parameter specifies a value, this data is simply a list of indices into the group's vertex array. If vPerFace is zero, the vertex indices should be preceded by an integer specifying the number of vertices in that face. For example, if vPerFace is zero and the group is made up of triangular and quadrilateral faces, the data might be in the following form: 3 index index index 4 index index index index 3 index index index ...
returnId
Address of the variable that identifies the group when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

A newly added group has the following default properties:

  • White
  • No texture
  • No specular reflection
  • Position, normal, and color of each vertex in the vertex array equal to zero

To set the positions of the vertices, use the IDirect3DRMMesh::SetVertices method.

IDirect3DRMMesh::GetBox

IDirect3DRMMesh

Retrieves the bounding box containing a Direct3DRMMesh object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX * lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMesh::GetGroup

IDirect3DRMMesh

Retrieves the data associated with a specified group.

HRESULT GetGroup(
D3DRMGROUPINDEX id,
unsigned *vCount,
unsigned *fCount,
unsigned *vPerFace,
DWORD *fDataSize,
unsigned *fData
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
vCount and fCount
Addresses of variables that will contain the number of vertices and the number of faces for the group when the method returns. These parameters can be NULL.
vPerFace
Address of a variable that will contain the number of vertices per face for the group when the method returns. This parameter can be NULL.
fDataSize
Address of a variable that specifies the number of unsigned elements in the buffer that the fData parameter points to. This parameter cannot be NULL.
fData
Address of a buffer that will contain the face data for the group when the method returns. The format of this data is the same as was specified in the call to the IDirect3DRMMesh::AddGroup method. If this parameter is NULL, the method returns the required size of the buffer in the fDataSize parameter.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMesh::GetGroupColor

IDirect3DRMMesh

Retrieves the color for a group.

D3DCOLOR GetGroupColor(
D3DRMGROUPINDEX id
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Values

Returns a D3DCOLOR variable specifying the color if successful, or zero otherwise.

See Also

IDirect3DRMMesh::SetGroupColor, IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::GetGroupCount

IDirect3DRMMesh

Retrieves the number of groups for a given Direct3DRMMesh object.

unsigned GetGroupCount( );

Return Values

Returns the number of groups if successful, or zero otherwise.

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh

Retrieves a description of how textures are mapped to a group in a Direct3DRMMesh object.

D3DRMMAPPING GetGroupMapping(
D3DRMGROUPINDEX id
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Values

Returns one of the D3DRMMAPPING values that describe how textures are mapped to a group, if successful. Returns zero otherwise.

See Also

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh

Retrieves a pointer to the material associated with a group in a Direct3DRMMesh object.

HRESULT GetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL *returnPtr
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
returnPtr
Address of a pointer to a variable that will contain the IDirect3DRMMaterial interface for the group when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh

Retrieves the rendering quality for a specified group in a Direct3DRMMesh object.

D3DRMRENDERQUALITY GetGroupQuality(
D3DRMGROUPINDEX id
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
Return Values

Returns values from the enumerated types represented by D3DRMRENDERQUALITY if successful, or zero otherwise. These values include the shading, lighting, and fill modes for the object.

See Also

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh

Retrieves an address of the texture associated with a group in a Direct3DRMMesh object.

HRESULT GetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE *returnPtr
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
returnPtr
Address of a pointer to a variable that will contain the IDirect3DRMTexture interface for the group when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh

Retrieves vertex information for a specified group in a Direct3DRMMesh object.

HRESULT GetVertices(
D3DRMGROUPINDEX id,
DWORD index,
DWORD count,
D3DRMVERTEX *returnPtr
);

Parameters
id
Identifier of the group. This identifier must have been produced by using the IDirect3DRMMesh::AddGroup method.
index
Index into the array of D3DRMVERTEX structures at which to begin returning vertex positions.
count
Number of D3DRMVERTEX structures (vertices) to retrieve following the index given in the index parameter. This parameter cannot be NULL. To retrieve the number of vertices in a group, use the IDirect3DRMMesh::GetGroup method.
returnPtr
Array of D3DRMVERTEX structures that will contain the vertex information (vertex positions, colors, texture coordinates, and so on) when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::GetGroup, IDirect3DRMMesh::SetVertices

IDirect3DRMMesh::Scale

IDirect3DRMMesh

Scales a Direct3DRMMesh object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);

Parameters
sx, sy, and sz
Scaling factors that are applied along the x-, y-, and z-axes.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh

Sets the color of a group in a Direct3DRMMesh object.

HRESULT SetGroupColor(
D3DRMGROUPINDEX id,
D3DCOLOR value
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
value
Color of the group.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a group color key to a Direct3DRMMeshInterpolator object.

See Also

IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh

Sets the color of a group in a Direct3DRMMesh object, using individual RGB values.

HRESULT SetGroupColorRGB(
D3DRMGROUPINDEX id,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
red, green, and blue
Red, green, and blue components of the group color.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a group RGB key to a Direct3DRMMeshInterpolator object.

See Also

IDirect3DRMMesh::GetGroupColor, IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh

Sets the mapping for a group in a Direct3DRMMesh object. The mapping controls how textures are mapped to a surface.

HRESULT SetGroupMapping(
D3DRMGROUPINDEX id,
D3DRMMAPPING value
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
value
Value of the D3DRMMAPPING type that describes the mapping for the group.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh

Sets the material associated with a group in a Direct3DRMMesh object.

HRESULT SetGroupMaterial(
D3DRMGROUPINDEX id,
LPDIRECT3DRMMATERIAL value
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
value
Address of the IDirect3DRMMaterial interface for the Direct3DRMMesh object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh

Sets the rendering quality for a specified group in a Direct3DRMMesh object.

HRESULT SetGroupQuality(
D3DRMGROUPINDEX id,
D3DRMRENDERQUALITY value
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
value
Values from the enumerated types represented by the D3DRMRENDERQUALITY type. These values include the shading, lighting, and fill modes for the object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh

Sets the texture associated with a group in a Direct3DRMMesh object.

HRESULT SetGroupTexture(
D3DRMGROUPINDEX id,
LPDIRECT3DRMTEXTURE value
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
value
Address of the IDirect3DRMTexture interface for the Direct3DRMMesh object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh::SetVertices

IDirect3DRMMesh

Sets the vertex positions for a specified group in a Direct3DRMMesh object.

HRESULT SetVertices(
D3DRMGROUPINDEX id,
unsigned index,
unsigned count,
D3DRMVERTEX *values
);

Parameters
id
Identifier of the group. This identifier must be produced by using the IDirect3DRMMesh::AddGroup method.
index
Index of the first vertex in the mesh group to be modified.
count
Number of consecutive vertices to set. The values array must contain at least the number of count elements.
values
Array of D3DRMVERTEX structures specifying the vertex positions to be set.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Vertices are local to the group. If an application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups.

This method is also used to add a vertex position key to a Direct3DRMMeshInterpolator object.

See Also

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh::Translate

IDirect3DRMMesh

Adds the specified offsets to the vertex positions of a Direct3DRMMesh object.

HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);

Parameters
tx, ty, and tz
Offsets that are added to the x-, y-, and z-coordinates, respectively, of each vertex position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMMeshBuilder

Applications use the methods of the IDirect3DRMMeshBuilder interface to interact with mesh objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces.

The methods of the IDirect3DRMMeshBuilder interface can be organized into the following groups:

Color | GetColorSource
SetColor
SetColorRGB
SetColorSource
Creation and | GetBox
information
Faces | AddFace
AddFaces
CreateFace
GetFaceCount
GetFaces
Loading | Load
Meshes | AddMesh
CreateMesh
Miscellaneous | AddFrame
AddMeshBuilder
ReserveSpace
Save
Scale
SetMaterial
Translate
Normals | AddNormal
GenerateNormals
SetNormal
Perspective | GetPerspective
SetPerspective
Rendering quality | GetQuality
SetQuality
Textures | GetTextureCoordinates
SetTexture
SetTextureCoordinates
SetTextureTopology
Vertices | AddVertex
GetVertexColor
GetVertexCount
GetVertices
SetVertex
SetVertexColor
SetVertexColorRGB

The IDirect3DRMMeshBuilder interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMMeshBuilder interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMMeshBuilder object is obtained by using the IDirect3DRM::CreateMeshBuilder method.

IDirect3DRMMeshBuilder::AddFace

IDirect3DRMMeshBuilder

Adds a face to a Direct3DRMMeshBuilder object.

HRESULT AddFace(
LPDIRECT3DRMFACE lpD3DRMFace
);

Parameters
lpD3DRMFace
Address of the face being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Any one face can exist in only one mesh at a time.

IDirect3DRMMeshBuilder::AddFaces

IDirect3DRMMeshBuilder

Adds faces to a Direct3DRMMeshBuilder object.

HRESULT AddFaces(
DWORD dwVertexCount,
D3DVECTOR * lpD3DVertices,
DWORD normalCount,
D3DVECTOR *lpNormals,
DWORD *lpFaceData,
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters
dwVertexCount
Number of vertices.
lpD3DVertices
Base address of an array of D3DVECTOR structures that stores the vertex positions.
normalCount
Number of normals.
lpNormals
Base address of an array of D3DVECTOR structures that stores the normal positions.
lpFaceData
For each face, this parameter should contain a vertex count followed by the indices into the vertices array. If normalCount is not zero, this parameter should contain a vertex count followed by pairs of indices, with the first index of each pair indexing into the array of vertices, and the second indexing into the array of normals. The list of indices must terminate with a zero.
lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that will be filled with a pointer to the newly created faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::AddFrame

IDirect3DRMMeshBuilder

Adds the contents of a frame to a Direct3DRMMeshBuilder object.

HRESULT AddFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters
lpD3DRMFrame
Address of the frame whose contents are being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The source frame is not modified or referenced by this operation.

IDirect3DRMMeshBuilder::AddMesh

IDirect3DRMMeshBuilder

Adds a mesh to a Direct3DRMMeshBuilder object.

HRESULT AddMesh(
LPDIRECT3DRMMESH lpD3DRMMesh
);

Parameters
lpD3DRMMesh
Address of the mesh being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::AddMeshBuilder

IDirect3DRMMeshBuilder

Adds the contents of a Direct3DRMMeshBuilder object to another Direct3DRMMeshBuilder object.

HRESULT AddMeshBuilder(
LPDIRECT3DRMMESHBUILDER lpD3DRMMeshBuild
);

Parameters
lpD3DRMMeshBuild
Address of the Direct3DRMMeshBuilder object whose contents are being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The source Direct3DRMMeshBuilder object is not modified or referenced by this operation.

IDirect3DRMMeshBuilder::AddNormal

IDirect3DRMMeshBuilder

Adds a normal to a Direct3DRMMeshBuilder object.

int AddNormal(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
x, y, and z
The x-, y-, and z-components of the direction of the new normal.
Return Values

Returns the index of the normal.

IDirect3DRMMeshBuilder::AddVertex

IDirect3DRMMeshBuilder

Adds a vertex to a Direct3DRMMeshBuilder object.

int AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
x, y, and z
The x-, y-, and z-components of the position of the new vertex.
Return Values

Returns the index of the vertex.

IDirect3DRMMeshBuilder::CreateFace

IDirect3DRMMeshBuilder

Creates a new face with no vertices and adds it to a Direct3DRMMeshBuilder object.

HRESULT CreateFace(
LPDIRECT3DRMFACE* lplpD3DRMFace
);

Parameters
lplpD3DRMFace
Address of a pointer to an IDirect3DRMFace interface that will be filled with a pointer to the face that was created.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::CreateMesh

IDirect3DRMMeshBuilder

Creates a new mesh from a Direct3DRMMeshBuilder object.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters
lplpD3DRMMesh
Address that will be filled with a pointer to an IDirect3DRMMesh interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::GenerateNormals

IDirect3DRMMeshBuilder

Processes the Direct3DRMMeshBuilder object and generates vertex normals that are the average of each vertex's adjoining face normals.

HRESULT GenerateNormals( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Averaging the normals of back-to-back faces produces a zero normal.

IDirect3DRMMeshBuilder::GetBox

IDirect3DRMMeshBuilder

Retrieves the bounding box containing a Direct3DRMMeshBuilder object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX *lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::GetColorSource

IDirect3DRMMeshBuilder

Retrieves the color source of a Direct3DRMMeshBuilder object. The color source can be either a face or a vertex.

D3DRMCOLORSOURCE GetColorSource( );

Return Values

Returns a member of the D3DRMCOLORSOURCE enumerated type.

See Also

IDirect3DRMMeshBuilder::SetColorSource

IDirect3DRMMeshBuilder::GetFaceCount

IDirect3DRMMeshBuilder

Retrieves the number of faces in a Direct3DRMMeshBuilder object.

int GetFaceCount( );

Return Values

Returns the number of faces.

IDirect3DRMMeshBuilder::GetFaces

IDirect3DRMMeshBuilder

Retrieves the faces of a Direct3DRMMeshBuilder object.

HRESULT GetFaces(
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters
lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that is filled with an address of the faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::GetPerspective

IDirect3DRMMeshBuilder

Determines whether perspective correction is on for a Direct3DRMMeshBuilder object.

BOOL GetPerspective( );

Return Values

Returns TRUE if perspective correction is on, or FALSE otherwise.

IDirect3DRMMeshBuilder::GetQuality

IDirect3DRMMeshBuilder

Retrieves the rendering quality of a Direct3DRMMeshBuilder object.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.

See Also

IDirect3DRMMeshBuilder::SetQuality

IDirect3DRMMeshBuilder::GetTextureCoordinates

IDirect3DRMMeshBuilder

Retrieves the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);

Parameters
index
Index of the vertex.
lpU and lpV
Addresses of variables that will be filled with the texture coordinates of the vertex when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder::SetTextureCoordinates

IDirect3DRMMeshBuilder::GetVertexColor

IDirect3DRMMeshBuilder

Retrieves the color of a specified vertex in a Direct3DRMMeshBuilder object.

D3DCOLOR GetVertexColor(
DWORD index
);

Parameters
index
Index of the vertex.
Return Values

Returns the color.

See Also

IDirect3DRMMeshBuilder::SetVertexColor

IDirect3DRMMeshBuilder::GetVertexCount

IDirect3DRMMeshBuilder

Retrieves the number of vertices in a Direct3DRMMeshBuilder object.

int GetVertexCount( );

Return Values

Returns the number of vertices.

IDirect3DRMMeshBuilder::GetVertices

IDirect3DRMMeshBuilder

Retrieves the vertices, normals, and face data for a Direct3DRMMeshBuilder object.

HRESULT GetVertices(
DWORD *vcount,
D3DVECTOR *vertices,
DWORD *ncount,
D3DVECTOR *normals,
DWORD *face_data_size,
DWORD *face_data
);

Parameters
vcount
Address of a variable that will contain the number of vertices.
vertices
Address of an array of D3DVECTOR structures that will contain the vertices for the Direct3DRMMeshBuilder object. If this parameter is NULL, the method returns the number of vertices in the vcount parameter.
ncount
Address of a variable that will contain the number of normals.
normals
Address of an array of D3DVECTOR structures that will contain the normals for the Direct3DRMMeshBuilder object. If this parameter is NULL, the method returns the number of normals in the ncount parameter.
face_data_size
Address of a variable that specifies the size of the buffer pointed to by the face_data parameter. The size is given in units of DWORD values. This parameter cannot be NULL.
face_data
Address of the face data for the Direct3DRMMeshBuilder object. This data is in the same format as specified in the IDirect3DRMMeshBuilder::AddFaces method except that it is null-terminated. If this parameter is NULL, the method returns the required size of the face-data buffer in the face_data_size parameter.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::Load

IDirect3DRMMeshBuilder

Loads a Direct3DRMMeshBuilder object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpvArg
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.
lpvArg
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first mesh from the source specified in the lpvObjSource parameter.

IDirect3DRMMeshBuilder::ReserveSpace

IDirect3DRMMeshBuilder

Reserves space within a Direct3DRMMeshBuilder object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.

HRESULT ReserveSpace(
DWORD vertexCount,
DWORD normalCount,
DWORD faceCount
);

Parameters
vertexCount, normalCount, and faceCount
Number of vertices, normals, and faces to allocate space for.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::Save

IDirect3DRMMeshBuilder

Saves a Direct3DRMMeshBuilder object.

HRESULT Save(
const char * lpFilename,
D3DRMXOFFORMAT d3drmXOFFormat,
D3DRMSAVEOPTIONS d3drmSOContents
);

Parameters
lpFilename
Address specifying the name of the created file. This file must have a .x file name extension.
d3drmXOFFormat
The D3DRMXOF_TEXT value from the D3DRMXOFFORMAT enumerated type.
d3drmSOContents
Value of the D3DRMSAVEOPTIONS type describing the save options.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::Scale

IDirect3DRMMeshBuilder

Scales a Direct3DRMMeshBuilder object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);

Parameters
sx sy, and sz
Scaling factors that are applied along the x-, y-, and z-axes.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetColor

IDirect3DRMMeshBuilder

Sets all the faces of a Direct3DRMMeshBuilder object to a given color.

HRESULT SetColor(
D3DCOLOR color
);

Parameters
color
Color of the faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetColorRGB

IDirect3DRMMeshBuilder

Sets all the faces of a Direct3DRMMeshBuilder object to a given color.

HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
red, green, and blue
Red, green, and blue components of the color.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetColorSource

IDirect3DRMMeshBuilder

Sets the color source of a Direct3DRMMeshBuilder object.

HRESULT SetColorSource(
D3DRMCOLORSOURCE source
);

Parameters
source
Member of the D3DRMCOLORSOURCE enumerated type that specifies the new color source to use.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder::GetColorSource

IDirect3DRMMeshBuilder::SetMaterial

IDirect3DRMMeshBuilder

Sets the material of all the faces of a Direct3DRMMeshBuilder object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpIDirect3DRMmaterial
);

Parameters
lpIDirect3DRMmaterial
Address of IDirect3DRMMaterial interface for the Direct3DRMMeshBuilder object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetNormal

IDirect3DRMMeshBuilder

Sets the normal vector of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetNormal(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
index
Index of the normal to be set.
x, y, and z
The x-, y-, and z-components of the vector to assign to the specified normal.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetPerspective

IDirect3DRMMeshBuilder

Enables or disables perspective-correct texture-mapping for a Direct3DRMMeshBuilder object.

HRESULT SetPerspective(
BOOL perspective
);

Parameters
perspective
Specify TRUE if the mesh should be texture-mapped with perspective correction, or FALSE otherwise.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetQuality

IDirect3DRMMeshBuilder

Sets the rendering quality of a Direct3DRMMeshBuilder object.

HRESULT SetQuality(
D3DRMRENDERQUALITY quality
);

Parameters
quality
Member of the D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

An object's quality has three components: shade mode (flat or Gouraud, Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wire-frame or solid).

You can set the quality of a device with IDirect3DRMDevice::SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMMeshBuilder object with the SetQuality method. By default, a Direct3DRMMeshBuilder object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT then the object will be rendered with flat shading, solid fill and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, then the object will be rendered with flat shading, lights off and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMMeshBuilder::GetQuality

IDirect3DRMMeshBuilder::SetTexture

IDirect3DRMMeshBuilder

Sets the texture of all the faces of a Direct3DRMMeshBuilder object.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters
lpD3DRMTexture
Address of the required Direct3DRMTexture object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetTextureCoordinates

IDirect3DRMMeshBuilder

Sets the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetTextureCoordinates(
DWORD index,
D3DVALUE u,
D3DVALUE v
);

Parameters
index
Index of the vertex to be set.
u and v
Texture coordinates to assign to the specified mesh vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder::GetTextureCoordinates

IDirect3DRMMeshBuilder::SetTextureTopology

IDirect3DRMMeshBuilder

Sets the texture topology of a Direct3DRMMeshBuilder object.

HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);

Parameters
cylU and cylV
Specify TRUE for either or both of these parameters if you want the texture to have a cylindrical topology in the u- and v-dimensions, respectively; otherwise, specify FALSE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetVertex

IDirect3DRMMeshBuilder

Sets the position of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertex(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
index
Index of the vertex to be set.
x, y, and z
The x-, y-, and z-components of the position to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::SetVertexColor

IDirect3DRMMeshBuilder

Sets the color of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertexColor(
DWORD index,
D3DCOLOR color
);

Parameters
index
Index of the vertex to be set.
color
Color to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder::GetVertexColor

IDirect3DRMMeshBuilder::SetVertexColorRGB

IDirect3DRMMeshBuilder

Sets the color of a specified vertex in a Direct3DRMMeshBuilder object.

HRESULT SetVertexColorRGB(
DWORD index,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
index
Index of the vertex to be set.
red, green, and blue
Red, green, and blue components of the color to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder::Translate

IDirect3DRMMeshBuilder

Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder object.

HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);

Parameters
tx, ty, and tz
Offsets that are added to the x-, y-, and z-coordinates respectively of each vertex position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMMeshBuilder2

Applications use the methods of the IDirect3DRMMeshBuilder2 interface to interact with mesh objects. IDirect3DRMMeshBuilder2 has the same functionality as IDirect3DRMMeshBuilder and in addition has extended the IDirect3DRMMeshBuilder2::GenerateNormals2 method to give greater control over the mesh normals generated. IDirect3DRMMeshBuilder2 also allows you to retrieve a single mesh face with IDirect3DRMMeshBuilder2::GetFace.

This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMMesh, IDirect3DRMMeshBuilder, and IDirect3DRMMeshBuilder2 Interfaces.

The methods of the IDirect3DRMMeshBuilder2 interface can be organized into the following groups:
Color | GetColorSource
SetColor
SetColorRGB
SetColorSource
Creation | GetBox
Faces | AddFace
AddFaces
CreateFace
GetFaceCount
GetFace
GetFaces
Loading | Load
Meshes | AddMesh
CreateMesh
Miscellaneous | AddFrame
AddMeshBuilder
ReserveSpace
Save
Scale
SetMaterial
Translate
Normals | AddNormal
GenerateNormals2
SetNormal
Perspective | GetPerspective
SetPerspective
Rendering quality | GetQuality
SetQuality
Textures | GetTextureCoordinates
SetTexture
SetTextureCoordinates
SetTextureTopology
Vertices | AddVertex
GetVertexColor
GetVertexCount
GetVertices
SetVertex
SetVertexColor
SetVertexColorRGB

The IDirect3DRMMeshBuilder2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMMeshBuilder2 interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMMeshBuilder2 object is obtained by using the IDirect3DRM::CreateMeshBuilder method.

IDirect3DRMMeshBuilder2::AddFace

IDirect3DRMMeshBuilder2

Adds a face to a Direct3DRMMeshBuilder2 object.

HRESULT AddFace(
LPDIRECT3DRMFACE lpD3DRMFace
);

Parameters
lpD3DRMFace
Address of the face being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Any one face can exist in only one mesh at a time.

IDirect3DRMMeshBuilder2::AddFaces

IDirect3DRMMeshBuilder2

Adds faces to a Direct3DRMMeshBuilder2 object.

HRESULT AddFaces(
DWORD dwVertexCount,
D3DVECTOR * lpD3DVertices,
DWORD normalCount,
D3DVECTOR *lpNormals,
DWORD *lpFaceData,
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters
dwVertexCount
Number of vertices.
lpD3DVertices
Base address of an array of D3DVECTOR structures that stores the vertex positions.
normalCount
Number of normals.
lpNormals
Base address of an array of D3DVECTOR structures that stores the normal positions.
lpFaceData
For each face, this parameter should contain a vertex count followed by the indices into the vertices array. If normalCount is not zero, this parameter should contain a vertex count followed by pairs of indices, with the first index of each pair indexing into the array of vertices, and the second indexing into the array of normals. The list of indices must terminate with a zero.
lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that will be filled with a pointer to the newly created faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::AddFrame

IDirect3DRMMeshBuilder2

Adds the contents of a frame to a Direct3DRMMeshBuilder2 object.

HRESULT AddFrame(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters
lpD3DRMFrame
Address of the frame whose contents are being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The source frame is not modified or referenced by this operation.

IDirect3DRMMeshBuilder2::AddMesh

IDirect3DRMMeshBuilder2

Adds a mesh to a Direct3DRMMeshBuilder2 object.

HRESULT AddMesh(
LPDIRECT3DRMMESH lpD3DRMMesh
);

Parameters
lpD3DRMMesh
Address of the mesh being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::AddMeshBuilder

IDirect3DRMMeshBuilder2

Adds the contents of a Direct3DRMMeshBuilder object to a Direct3DRMMeshBuilder2 object.

HRESULT AddMeshBuilder(
LPDIRECT3DRMMESHBUILDER lpD3DRMMeshBuild
);

Parameters
lpD3DRMMeshBuild
Address of the Direct3DRMMeshBuilder object whose contents are being added.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The source Direct3DRMMeshBuilder object is not modified or referenced by this operation.

IDirect3DRMMeshBuilder2::AddNormal

IDirect3DRMMeshBuilder2

Adds a normal to a Direct3DRMMeshBuilder2 object.

int AddNormal(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
x, y, and z
The x-, y-, and z-components of the direction of the new normal.
Return Values

Returns the index of the normal.

IDirect3DRMMeshBuilder2::AddVertex

IDirect3DRMMeshBuilder2

Adds a vertex to a Direct3DRMMeshBuilder2 object.

int AddVertex(
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
x, y, and z
The x-, y-, and z-components of the position of the new vertex.
Return Values

Returns the index of the vertex.

IDirect3DRMMeshBuilder2::CreateFace

IDirect3DRMMeshBuilder2

Creates a new face with no vertices and adds it to a Direct3DRMMeshBuilder2 object.

HRESULT CreateFace(
LPDIRECT3DRMFACE* lplpD3DRMFace
);

Parameters
lplpD3DRMFace
Address of a pointer to an IDirect3DRMFace interface that will be filled with a pointer to the face that was created.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::CreateMesh

IDirect3DRMMeshBuilder2

Creates a new mesh from a Direct3DRMMeshBuilder2 object.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
);

Parameters
lplpD3DRMMesh
Address that will be filled with a pointer to an IDirect3DRMMesh interface.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::GenerateNormals2

IDirect3DRMMeshBuilder2

Processes the Direct3DRMMeshBuilder2 object and generates normals for each vertex in a mesh by averaging the face normals for each face that shares the vertex. New normals are generated if the faces sharing a vertex have an angle between them greater than the crease angle.

HRESULT GenerateNormals2(
D3DVALUE dvCreaseAngle,
DWORD dwFlags
);

Parameters
dvCreaseAngle
The least angle in radians that faces can have between them and have a new normal generated.
dwFlags
One of the following values.
D3DRMGENERATENORMALS_PRECOMPACT (dwFlags = 1) — Specifies that the algorithm should attempt to compact mesh vertices before it generates normals. See comments below.
D3DRMGENERATENORMALS_USECREASEANGLE (dwFlags = 2) — Specifies that the dvCreaseAngle parameter should be used. Otherwise, the crease angle is ignored.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If you specify the D3DRMGENERATENORMALS_PRECOMPACT flag, the precompact pass searches all the vertices in the mesh and merges any that are the same. This is a good way of compacting a mesh that has been loaded. Some meshes have multiple vertices if they have multiple normals at that vertex. This is not necessary in Direct3D Retained Mode. Specifying this flag is the way to get rid of the multiple vertices.

After compacting, the normals are generated. The edges between faces are examined, and if the angle the faces make at the edge is less than the crease angle, the face normals are averaged to generate the vertex normal. If the angle is greater than the crease angle, a new normal is generated. Note that a new vertex is not generated.

IDirect3DRMMeshBuilder2::GetBox

IDirect3DRMMeshBuilder2

Retrieves the bounding box containing a Direct3DRMMeshBuilder2 object. The bounding box gives the minimum and maximum model coordinates in each dimension.

HRESULT GetBox(
D3DRMBOX *lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::GetColorSource

IDirect3DRMMeshBuilder2

Retrieves the color source of a Direct3DRMMeshBuilder2 object. The color source can be either a face or a vertex.

D3DRMCOLORSOURCE GetColorSource( );

Return Values

Returns a member of the D3DRMCOLORSOURCE enumerated type.

See Also

IDirect3DRMMeshBuilder2::SetColorSource

IDirect3DRMMeshBuilder2::GetFace

IDirect3DRMMeshBuilder2

Retrieves a single face of a Direct3DRMMeshBuilder2 object.

HRESULT GetFace(
DWORD dwIndex,
LPDIRECT3DRMFACE* lplpD3DRMFace
);

Parameters
dwIndex
The index of the mesh face to be retrieved. The face must already be part of a Direct3DRMMeshBuilder2 object.
lplpD3DRMFace
Address of a pointer to an IDirect3DRMFace interface that is filled with an address of the face.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::GetFaceCount

IDirect3DRMMeshBuilder2

Retrieves the number of faces in a Direct3DRMMeshBuilder2 object.

int GetFaceCount( );

Return Values

Returns the number of faces.

IDirect3DRMMeshBuilder2::GetFaces

IDirect3DRMMeshBuilder2

Retrieves the faces of a Direct3DRMMeshBuilder2 object.

HRESULT GetFaces(
LPDIRECT3DRMFACEARRAY* lplpD3DRMFaceArray
);

Parameters
lplpD3DRMFaceArray
Address of a pointer to an IDirect3DRMFaceArray interface that is filled with an address of the faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::GetPerspective

IDirect3DRMMeshBuilder2

Determines whether perspective correction is on for a Direct3DRMMeshBuilder2 object.

BOOL GetPerspective( );

Return Values

Returns TRUE if perspective correction is on, or FALSE otherwise.

IDirect3DRMMeshBuilder2::GetQuality

IDirect3DRMMeshBuilder2

Retrieves the rendering quality of a Direct3DRMMeshBuilder2 object.

D3DRMRENDERQUALITY GetQuality( );

Return Values

Returns a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the mesh.

See Also

IDirect3DRMMeshBuilder2::SetQuality

IDirect3DRMMeshBuilder2::GetTextureCoordinates

IDirect3DRMMeshBuilder2

Retrieves the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT GetTextureCoordinates(
DWORD index,
D3DVALUE *lpU,
D3DVALUE *lpV
);

Parameters
index
Index of the vertex.
lpU and lpV
Addresses of variables that will be filled with the texture coordinates of the vertex when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder2::SetTextureCoordinates

IDirect3DRMMeshBuilder2::GetVertexColor

IDirect3DRMMeshBuilder2

Retrieves the color of a specified vertex in a Direct3DRMMeshBuilder2 object.

D3DCOLOR GetVertexColor(
DWORD index
);

Parameters
index
Index of the vertex.
Return Values

Returns the color.

See Also

IDirect3DRMMeshBuilder2::SetVertexColor

IDirect3DRMMeshBuilder2::GetVertexCount

IDirect3DRMMeshBuilder2

Retrieves the number of vertices in a Direct3DRMMeshBuilder2 object.

int GetVertexCount( );

Return Values

Returns the number of vertices.

IDirect3DRMMeshBuilder2::GetVertices

IDirect3DRMMeshBuilder2

Retrieves the vertices, normals, and face data for a Direct3DRMMeshBuilder2 object.

HRESULT GetVertices(
DWORD *vcount,
D3DVECTOR *vertices,
DWORD *ncount,
D3DVECTOR *normals,
DWORD *face_data_size,
DWORD *face_data
);

Parameters
vcount
Address of a variable that will contain the number of vertices.
vertices
Address of an array of D3DVECTOR structures that will contain the vertices for the Direct3DRMMeshBuilder2 object. If this parameter is NULL, the method returns the number of vertices in the vcount parameter.
ncount
Address of a variable that will contain the number of normals.
normals
Address of an array of D3DVECTOR structures that will contain the normals for the Direct3DRMMeshBuilder2 object. If this parameter is NULL, the method returns the number of normals in the ncount parameter.
face_data_size
Address of a variable that specifies the size of the buffer pointed to by the face_data parameter. The size is given in units of DWORD values. This parameter cannot be NULL.
face_data
Address of the face data for the Direct3DRMMeshBuilder2 object. This data is in the same format as specified in the IDirect3DRMMeshBuilder2::AddFaces method except that it is null-terminated. If this parameter is NULL, the method returns the required size of the face-data buffer in the face_data_size parameter.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::Load

IDirect3DRMMeshBuilder2

Loads a Direct3DRMMeshBuilder2 object.

HRESULT Load(
LPVOID lpvObjSource,
LPVOID lpvObjID,
D3DRMLOADOPTIONS d3drmLOFlags,
D3DRMLOADTEXTURECALLBACK d3drmLoadTextureProc,
LPVOID lpvArg
);

Parameters
lpvObjSource
Source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the d3drmLOFlags parameter.
lpvObjID
Object name or position to be loaded. The use of this parameter depends on the identifier flags specified in the d3drmLOFlags parameter. If the D3DRMLOAD_BYPOSITION flag is specified, this parameter is a pointer to a DWORD value that gives the object's order in the file. This parameter can be NULL.
d3drmLOFlags
Value of the D3DRMLOADOPTIONS type describing the load options.
d3drmLoadTextureProc
A D3DRMLOADTEXTURECALLBACK callback function used to load any textures used by an object that require special formatting. This parameter can be NULL.
lpvArg
Address of application-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

By default, this method loads the first mesh from the source specified in the lpvObjSource parameter.

IDirect3DRMMeshBuilder2::ReserveSpace

IDirect3DRMMeshBuilder2

Reserves space within a Direct3DRMMeshBuilder2 object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.

HRESULT ReserveSpace(
DWORD vertexCount,
DWORD normalCount,
DWORD faceCount
);

Parameters
vertexCount, normalCount, and faceCount
Number of vertices, normals, and faces to allocate space for.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::Save

IDirect3DRMMeshBuilder2

Saves a Direct3DRMMeshBuilder2 object.

HRESULT Save(
const char * lpFilename,
D3DRMXOFFORMAT d3drmXOFFormat,
D3DRMSAVEOPTIONS d3drmSOContents
);

Parameters
lpFilename
Address specifying the name of the created file. This file must have a .x file name extension.
d3drmXOFFormat
The D3DRMXOF_TEXT value from the D3DRMXOFFORMAT enumerated type.
d3drmSOContents
Value of the D3DRMSAVEOPTIONS type describing the save options.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::Scale

IDirect3DRMMeshBuilder2

Scales a Direct3DRMMeshBuilder2 object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

HRESULT Scale(
D3DVALUE sx,
D3DVALUE sy,
D3DVALUE sz
);

Parameters
sx, sy, and sz
Scaling factors that are applied along the x-, y-, and z-axes.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetColor

IDirect3DRMMeshBuilder2

Sets all the faces of a Direct3DRMMeshBuilder2 object to a given color.

HRESULT SetColor(
D3DCOLOR color
);

Parameters
color
Color of the faces.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetColorRGB

IDirect3DRMMeshBuilder2

Sets all the faces of a Direct3DRMMeshBuilder2 object to a given color.

HRESULT SetColorRGB(
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
red, green, and blue
Red, green, and blue components of the color.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetColorSource

IDirect3DRMMeshBuilder2

Sets the color source of a Direct3DRMMeshBuilder2 object.

HRESULT SetColorSource(
D3DRMCOLORSOURCE source
);

Parameters
source
Member of the D3DRMCOLORSOURCE enumerated type that specifies the new color source to use.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder2::GetColorSource

IDirect3DRMMeshBuilder2::SetMaterial

IDirect3DRMMeshBuilder2

Sets the material of all the faces of a Direct3DRMMeshBuilder2 object.

HRESULT SetMaterial(
LPDIRECT3DRMMATERIAL lpIDirect3DRMmaterial
);

Parameters
lpIDirect3DRMmaterial
Address of IDirect3DRMMaterial interface for the Direct3DRMMeshBuilder2 object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetNormal

IDirect3DRMMeshBuilder2

Sets the normal vector of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT SetNormal(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
index
Index of the normal to be set.
x, y, and z
The x-, y-, and z-components of the vector to assign to the specified normal.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetPerspective

IDirect3DRMMeshBuilder2

Enables or disables perspective-correct texture-mapping for a Direct3DRMMeshBuilder2 object.

HRESULT SetPerspective(
BOOL perspective
);

Parameters
perspective
Specify TRUE if the mesh should be texture-mapped with perspective correction, or FALSE otherwise.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetQuality

IDirect3DRMMeshBuilder2

Sets the rendering quality of a Direct3DRMMeshBuilder2 object.

HRESULT SetQuality(
D3DRMRENDERQUALITY quality
);

Parameters
quality
Member of the D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

An object's quality has three components: shade mode (flat or Gouraud; Phong shading is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wireframe, or solid).

You can set the quality of a device with IDirect3DRMDevice::SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMMeshBuilder2 object with the SetQuality method. By default, a Direct3DRMMeshBuilder2 object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT then the object will be rendered with flat shading, solid fill and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, then the object will be rendered with flat shading, lights off, and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMMeshBuilder2::GetQuality

IDirect3DRMMeshBuilder2::SetTexture

IDirect3DRMMeshBuilder2

Sets the texture of all the faces of a Direct3DRMMeshBuilder2 object.

HRESULT SetTexture(
LPDIRECT3DRMTEXTURE lpD3DRMTexture
);

Parameters
lpD3DRMTexture
Address of the required Direct3DRMTexture object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetTextureCoordinates

IDirect3DRMMeshBuilder2

Sets the texture coordinates of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT SetTextureCoordinates(
DWORD index,
D3DVALUE u,
D3DVALUE v
);

Parameters
index
Index of the vertex to be set.
u and v
Texture coordinates to assign to the specified mesh vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder2::GetTextureCoordinates

IDirect3DRMMeshBuilder2::SetTextureTopology

IDirect3DRMMeshBuilder2

Sets the texture topology of a Direct3DRMMeshBuilder2 object.

HRESULT SetTextureTopology(
BOOL cylU,
BOOL cylV
);

Parameters
cylU and cylV
Specify TRUE for either or both of these parameters if you want the texture to have a cylindrical topology in the u- and v-dimensions, respectively; otherwise, specify FALSE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetVertex

IDirect3DRMMeshBuilder2

Sets the position of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT SetVertex(
DWORD index,
D3DVALUE x,
D3DVALUE y,
D3DVALUE z
);

Parameters
index
Index of the vertex to be set.
x, y, and z
The x-, y-, and z-components of the position to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::SetVertexColor

IDirect3DRMMeshBuilder2

Sets the color of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT SetVertexColor(
DWORD index,
D3DCOLOR color
);

Parameters
index
Index of the vertex to be set.
color
Color to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMMeshBuilder2::GetVertexColor

IDirect3DRMMeshBuilder2::SetVertexColorRGB

IDirect3DRMMeshBuilder2

Sets the color of a specified vertex in a Direct3DRMMeshBuilder2 object.

HRESULT SetVertexColorRGB(
DWORD index,
D3DVALUE red,
D3DVALUE green,
D3DVALUE blue
);

Parameters
index
Index of the vertex to be set.
red, green, and blue
Red, green, and blue components of the color to assign to the specified vertex.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMMeshBuilder2::Translate

IDirect3DRMMeshBuilder2

Adds the specified offsets to the vertex positions of a Direct3DRMMeshBuilder2 object.

HRESULT Translate(
D3DVALUE tx,
D3DVALUE ty,
D3DVALUE tz
);

Parameters
tx, ty, and tz
Offsets that are added to the x-, y-, and z-coordinates, respectively, of each vertex position.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMObject

Applications use the methods of the IDirect3DRMObject interface to work with the object superclass of Microsoft® Direct3D® Retained Mode objects. This section is a reference to the methods of this interface. For a conceptual overview, see Direct3DRMObject.

The methods of the IDirect3DRMObject interface can be organized into the following groups:
Application-specific | GetAppData
data | SetAppData
Cloning | Clone
Naming | GetClassName
GetName
SetName
Notifications | AddDestroyCallback
DeleteDestroyCallback

The IDirect3DRMObject interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMObject object is obtained through the appropriate call to the QueryInterface method from any Retained Mode object. All Retained Mode objects inherit the IDirect3DRMObject interface methods.

IDirect3DRMObject::AddDestroyCallback

IDirect3DRMObject

Registers a function that will be called when an object is destroyed.

HRESULT AddDestroyCallback(
D3DRMOBJECTCALLBACK lpCallback,
LPVOID lpArg
);

Parameters
lpCallback
User-defined callback function that will be used when the object is destroyed.
lpArg
Address of application-defined data passed to the callback function. Because this function is used after the object has been destroyed, you should not use this function with the object as an argument.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject::Clone

IDirect3DRMObject

Creates a copy of an object.

HRESULT Clone(
LPUNKNOWN pUnkOuter,
REFIID riid,
LPVOID *ppvObj
);

Parameters
pUnkOuter
Pointer to the outer IUnknown interface that allows COM aggregation features.
riid
Identifier of the object being copied.
ppvObj
Address that will contain the copy of the object when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject::DeleteDestroyCallback

IDirect3DRMObject

Removes a function previously registered with the IDirect3DRMObject::AddDestroyCallback method.

HRESULT DeleteDestroyCallback(
D3DRMOBJECTCALLBACK d3drmObjProc,
LPVOID lpArg
);

Parameters
d3drmObjProc
User-defined D3DRMOBJECTCALLBACK callback function that will be used when the object is destroyed.
lpArg
Address of application-defined data passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject::GetAppData

IDirect3DRMObject

Retrieves the 32 bits of application-specific data in the object. The default value of the data is 0.

DWORD GetAppData( );

Return Values

Returns the data value defined by the application.

See Also

IDirect3DRMObject::SetAppData

IDirect3DRMObject::GetClassName

IDirect3DRMObject

Retrieves the name of the object's class.

HRESULT GetClassName(
LPDWORD lpdwSize,
LPSTR lpName
);

Parameters
lpdwSize
Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.
lpName
Address of a variable that will contain a null-terminated string identifying the class name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMObject::GetName

IDirect3DRMObject

Retrieves the object's name.

HRESULT GetName(
LPDWORD lpdwSize,
LPSTR lpName
);

Parameters
lpdwSize
Address of a variable containing the size, in bytes, of the buffer pointed to by the lpName parameter.
lpName
Address of a variable that will contain a null-terminated string identifying the object's name when the method returns. If this parameter is NULL, the lpdwSize parameter will contain the required size for the string when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMObject::SetName

IDirect3DRMObject::SetAppData

IDirect3DRMObject

Sets the 32 bits of application-specific data in the object.

HRESULT SetAppData(
DWORD ulData
);

Parameters
ulData
User-defined data to be stored with the object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMObject::GetAppData

IDirect3DRMObject::SetName

IDirect3DRMObject

Sets the object's name.

HRESULT SetName(
const char * lpName
);

Parameters
lpName
User-defined data to name the object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMObject::GetName

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMProgressiveMesh

The progressive mesh is a form of mesh that allows for progressive refinement. Conceptually, it consists of a base mesh representation and a number of "vertex split" records. A mesh can be stored as a much coarser mesh together with records of how to incrementally refine the mesh. This allows for a generalized level of detail to be set on the mesh, as well as progressive download of the mesh from a remote source.

The progressive mesh is a visual in Microsoft® Direct3D® Retained Mode and may be used in the standard ways that visuals are used. That is, a progressive mesh can be added to frame hierarchies, multiply instanced and picked.

The Direct3DRMProgressiveMesh object is created by using the IDirect3DRM2::CreateProgressiveMesh method. After creation, the object can be added to a hierarchy, but will not render until at least the base mesh is available.

For a conceptual overview, see IDirect3DRMProgressiveMesh.

In addition to the standard IUnknown and IDirect3DRMObject methods, this API contains the following members:

Creating and Copying Meshes | Clone
CreateMesh
Duplicate
GetBox
Loading | Abort
GetLoadStatus
Load
Setting Quality | SetQuality
GetQuality
Managing Details | GetDetail
GetFaceDetail
GetFaceDetailRange
GetVertexDetail
GetVertexDetailRange
SetDetail
SetFaceDetail
SetMinRenderDetail
SetVertexDetail
Registering Events | RegisterEvents

The IDirect3DRMProgressiveMesh interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMProgressiveMesh interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMProgressiveMesh::Abort

IDirect3DRMProgressiveMesh

Terminates the currently active download.

HRESULT Abort(
DWORD dwFlags
)

Parameters
dwFlags
Must be set to zero.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

Remarks

If the base mesh has been downloaded before this method is used, the effect is as if the progressive mesh has loaded, the vertex splits are in a valid state, and the progressive mesh is renderable. The other progressive mesh methods will work. If the base mesh has not been downloaded before the IDirect3DRMProgressiveMesh::Abort call and you have added the progressive mesh to a scene, the Render will succeed but the progressive mesh will not be rendered. Also, if the base mesh has not been downloaded, when you try to use the progressive mesh (to create a mesh or clone, for example) the call will return D3DRMERR_NOTENOUGHDATA.

If there are any outstanding events, they are signaled.

IDirect3DRMProgressiveMesh::Clone

IDirect3DRMProgressiveMesh

Creates a copy of the currently loaded Direct3DRMProgressiveMesh object.

HRESULT Clone(
LPDIRECT3DRMPROGRESSIVEMESH* lplpD3DRMPMesh
)

Parameters
lplpD3DRMPMesh
Address of a Direct3DRMProgressiveMesh pointer that will be filled in with a pointer to the newly generated Direct3DRMProgressiveMesh object.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

Remarks

The progressive mesh being cloned must have at least its base mesh loaded. If you use this method on a progressive mesh that is currently being asynchronously loaded, the cloned mesh only has as much detail as the loading progressive mesh had at the time it was cloned. Any vertex splits loaded after the duplication are not available to the cloned mesh.

This method does not try to share any of the progressive mesh's internal data, whereas the IDirect3DRMProgressiveMesh::Duplicate does.

See Also

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh::CreateMesh

IDirect3DRMProgressiveMesh

Builds a mesh from the current level of detail.

HRESULT CreateMesh(
LPDIRECT3DRMMESH* lplpD3DRMMesh
)

Parameters
lplpD3DRMMesh
Address of a Direct3DRMMesh pointer that will be filled in with a pointer to the newly generated Direct3DRMMesh object.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

Remarks

If the application has requested a level of detail that is not yet available, or the base mesh is not yet available, this method returns the error D3DRMERR_NOTENOUGHDATA.

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh

Creates a copy of the Direct3DRMProgressiveMesh object. The copy shares all geometry and face data with the original, but has a detail level that can be set independently of the original. This enables the same mesh data to be used in different parts of the hierarchy but with different levels of detail. In essence, you almost have two instances of a progressive mesh within the frame hierarchy.

HRESULT Duplicate(
LPDIRECT3DRMPROGRESSIVEMESH* lplpD3DRMPMesh
)

Parameters
lplpD3DRMPMesh
Address of a Direct3DRMProgressiveMesh pointer that will be filled with a pointer to the newly generated Direct3DRMProgressiveMesh object.
Return Values

Returns DD_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

Remarks

The progressive mesh being duplicated must have at least its base mesh loaded. If you use this method on a progressive mesh that is currently being asynchronously loaded, the duplicated mesh only has as much detail as the loading progressive mesh had at the time it was duplicated. Any vertex splits loaded after the duplication are not available to the duplicated mesh.

A progressive mesh has a set of data representing the base mesh, and a set of data representing the vertex splits. The base mesh data and data describing the current state of the progressive mesh and the current level of detail isn't shared between meshes that are duplicated, but the vertex splits are. This method creates a new instance of the progressive mesh that shares all geometry and face data with the original, but has a detail level that can be set independently of the original.

IDirect3DRMProgressiveMesh::GetBox

IDirect3DRMProgressiveMesh

Retrieves the bounding box containing a Direct3DRMProgressiveMesh object. The bounding box gives the minimum and maximum coordinates relative to a child frame, in each dimension.

HRESULT GetBox(
D3DRMBOX * lpD3DRMBox
);

Parameters
lpD3DRMBox
Address of a D3DRMBOX structure that will be filled with the bounding box coordinates.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMProgressiveMesh::GetDetail

IDirect3DRMProgressiveMesh

Returns the current detail level of the progressive mesh normalized between 0.0 and 1.0.

HRESULT GetDetail(
LPD3DVALUE lpdvVal
)

Parameters
lpdvVal
Address of a D3DVALUE that will be filled with the current detail level of the progressive mesh.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

Remarks

If the base mesh has not yet downloaded then this method will return D3DRMERR_PENDING. If a requested level of detail has been set, the return value will increase on each subsequent call until the requested level has been met. If no level has been requested, the detail will increase until all vertex splits have been downloaded.

The normalized value 0.0 represents the minimum number of vertices (the number of vertices in the base mesh), and the normalized value 1.0 represents the maximum number of vertices.

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh

Retrieves the number of faces in the progressive mesh.

HRESULT GetFaceDetail(
LPDWORD lpdwCount
)

Parameters
lpdwCount
Address of a DWORD that will be filled in with the number of faces in the progressive mesh.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_PENDING
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

Remarks

If the number of faces is not available, this method returns D3DRMERR_PENDING.

IDirect3DRMProgressiveMesh::GetFaceDetailRange

IDirect3DRMProgressiveMesh

Retrieves the minimum and maximum face count available in the progressive mesh.

HRESULT GetFaceDetailRange(
LPDWORD lpdwMinFaces,
LPDWORD lpdwMaxFaces
)

Parameters
lpdwMinFaces
Address of a DWORD that will be filled in with the minimum number of faces.
lpdwMaxFaces
Address of a DWORD that will be filled in with the maximum number of faces.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

Remarks

If the face count is not available, this method returns D3DRMERR_PENDING.

IDirect3DRMProgressiveMesh::GetLoadStatus

IDirect3DRMProgressiveMesh

Allows the application to inquire about the current status of the load.

HRESULT GetLoadStatus(
LPD3DRMPMESHLOADSTATUS lpStatus
)

Parameters
lpStatus
Address of a D3DRMPMESHLOADSTATUS structure defined as follows:
typedef struct _D3DRMPMESHLOADSTATUS
{
    DWORD dwSize;			// Size of this structure
    DWORD dwPMeshSize;		// Total size (bytes)
    DWORD dwBaseMeshSize;		// Size of base mesh (bytes)
    DWORD dwBytesLoaded;		// Total number of bytes loaded
    DWORD dwVerticesLoaded;		// Number of vertices loaded
    DWORD dwFacesLoaded;		// Number of faces loaded
    DWORD dwFlags;
}
D3DRMPMESHLOADSTATUS;
typedef D3DRMPMESHLOADSTATUS *LPD3DRMPMESHLOADSTATUS;
The dwFlags member can take the following values:
D3DRMPMESHSTATUS_VALID — The progressive mesh object contains valid data.
D3DRMPMESHSTATUS_INTERRUPTED — The download was interrupted either because the application used Abort or because the connection was lost.
D3DRMPMESHSTATUS_BASEMESH — The base mesh has been downloaded.
D3DRMPMESHSTATUS_COMPLETE — All data has been downloaded.
D3DRMPMESHSTATUS_RENDERABLE — It is now possible to render the mesh.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

Remarks

If the mesh is renderable (the base mesh has been downloaded and the data is not corrupt) then the dwFlags member contains D3DRMPMESHSTATUS_RENDERABLE. If the download was interrupted, the dwFlags member will contain D3DRMPMESHSTATUS_INTERRUPTED.

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh

Retrieves a member of the D3DRMRENDERQUALITY enumerated type that specifies the rendering quality of the progressive mesh.

HRESULT GetQuality(
LPD3DRMRENDERQUALITY lpQuality
);

Parameters
lpQuality
Pointer to the D3DRMRENDERQUALITY member if successful that specifies rendering quality.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_BADOBJECT — The progressive mesh is invalid.
D3DRMERR_BADVALUE — The pointer to the D3DRMRENDERQUALITY member is invalid.

See Also

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh::GetVertexDetail

IDirect3DRMProgressiveMesh

Retrieves the number of vertices in the progressive mesh.

HRESULT GetVertexDetail(
LPDWORD lpdwCount
)

Parameters
lpdwCount
Address of a DWORD that will be filled in with the number of vertices in the progressive mesh.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

Remarks

If the number of vertices is not available, this method returns D3DRMERR_PENDING.

IDirect3DRMProgressiveMesh::GetVertexDetailRange

IDirect3DRMProgressiveMesh

Retrieves the minimum and maximum vertex count available in the progressive mesh.

HRESULT GetVertexDetailRange(
LPDWORD lpdwMinVertices,
LPDWORD lpdwMaxVertices
)

Parameters
lpdwMinVertices
Address of a DWORD that will be filled in with the minimum number of vertices.
lpdwMaxVertices
Address of a DWORD that will be filled in with the maximum number of vertices.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

Remarks

If the vertex count information is not available, this method returns D3DRMERR_PENDING.

IDirect3DRMProgressiveMesh::Load

IDirect3DRMProgressiveMesh

Loads the progressive mesh object from memory, a file, a resource, or an URL. Loading can be done synchronously or asynchronously.

HRESULT Load(
LPVOID lpSource,
LPVOID lpObjID,
D3DRMLOADOPTIONS dloLoadflags,
D3DRMLOADTEXTURECALLBACK lpCallback,
LPVOID lpArg
)

Parameters
lpSource
Address of the source for the object to be loaded. This source can be a file, resource, memory block, or stream, depending on the source flags specified in the dloLoadflags parameter.
lpObjID
Address of the ID of the DirectX file record that is a progressive mesh. This can either be a string or a UUID (determined by dloLoadflags). If lpObjID is NULL, dloLoadflags must be D3DRMLOAD_FIRST.
dloLoadflags
Value of the D3DRMLOADOPTIONS type describing how the load is to be performed. One flag from each of the following two groups must be included:

The following values determine which object in the DirectX file is loaded:

D3DRMLOAD_BYNAME | The lpObjID parameter is interpreted as a string.
D3DRMLOAD_BYGUID | The lpObjID parameter is interpreted as a UUID.
D3DRMLOAD_FIRST | The first progressive mesh found is loaded.

The following flags determine the source of the DirectX file:
D3DRMLOAD_FROMFILE | The lpSource parameter is interpreted as a string representing a local file name.
D3DRMLOAD_FROMRESOURCE | The lpSource parameter is interpreted as a pointer to a D3DRMLOADRESOURCE structure.
D3DRMLOAD_FROMMEMORY | The lpSource parameter is interpreted as a pointer to a D3DRMLOADMEMORY structure.
D3DRMLOAD_FROMURL | The lpSource parameter is interpreted as a URL.

In addition, you can specify whether the download is synchronous or asynchronous. By default, loading is synchronous and the Load call will not return until all data has been loaded or an error occurs. To specify asynchronous loading, include the following flag:

D3DRMLOAD_ASYNCHRONOUS — The Load call will return immediately. It is up to the application to use events with IDirect3DRMProgressiveMesh::RegisterEvents and IDirect3DRMProgressiveMesh::GetLoadStatus to find out how the load is progressing.

lpCallback
Address of a D3DRMLOADTEXTURECALLBACK callback function that will be used to load any texture encountered. The callback will be used with the texture name as encountered by the loader and the user-defined lpArg parameter. A new thread is not spawned for the callback. If you want the application to download a texture progressively, it must spawn a thread and return with a LPDIRECT3DRMTEXTURE as normal.
lpArg
Address of user-defined data passed to the D3DRMLOADTEXTURECALLBACK callback function.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_BADPMDATA
D3DRMERR_BADFILE
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

Remarks

The progressive mesh is not useful unless it has been initialized. If asynchronous download is specified, the API returns immediately, and a separate thread is spawned to perform the download.

This method, IDirect3DRMProgressiveMesh::Clone, and IDirect3DRMProgressiveMesh::Duplicate all initialize a progressive mesh. You can only initialize an object once. Therefore, you cannot clone or duplicate a progressive mesh and then try to load into the cloned or duplicated mesh, nor can you load into a previously loaded mesh.

IDirect3DRMProgressiveMesh::RegisterEvents

IDirect3DRMProgressiveMesh

Allows the application to register events with the progressive mesh object that will be signaled when the appropriate conditions are met.

HRESULT RegisterEvents(
HANDLE hEvent,
DWORD dwFlags,
DWORD dwReserved
)

Parameters
hEvent
Event to be signaled when the required condition is met.
dwFlags
Can be one of the following flags:

D3DRMPMESHEVENT_BASEMESH | The event is signaled when the base mesh has been downloaded.
D3DRMPMESHEVENT_COMPLETE | The event is signaled when all data has been downloaded.

dwReserved
Must be zero.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

Remarks

This method can be used to monitor the progress of loads. Events will also be signaled if an error occurs, so your application should always use the IDirect3DRMProgressiveMesh::GetLoadStatus method after being signaled.

IDirect3DRMProgressiveMesh::SetDetail

IDirect3DRMProgressiveMesh

Sets a requested level of detail normalized between 0.0 and 1.0.

HRESULT SetDetail(
D3DVALUE dvVal
)

Parameters
dvVal
The requested level of detail.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

Remarks

If not enough detail has been downloaded yet (but will be available), the request is acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available.

The normalized value 0.0 represents the minimum number of vertices (the number of vertices in the base mesh), and the normalized value 1.0 represents the maximum number of vertices.

IDirect3DRMProgressiveMesh::SetFaceDetail

IDirect3DRMProgressiveMesh

Sets the requested level of face detail.

HRESULT SetFaceDetail(
DWORD dwCount
)

Parameters
dwCount
The number of faces requested.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

Remarks

Sometimes it is not possible to set the progressive mesh to the number of faces requested, though it will always be within 1 of the requested value. This is because a vertex split can add 1 or 2 faces. For example, if you use SetFaceDetail(20), the progressive mesh may only be able to set the face detail to 19 or 21. You can always get the actual number of faces in the progressive mesh by using the IDirect3DRMProgressiveMesh::GetFaceDetail method.

If not enough detail has been downloaded yet (but will be available), the request is be acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available. If the detail requested is greater that the detail available in the progressive mesh, D3DRMERR_REQUESTTOOLARGE is returned.

See Also

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh::SetMinRenderDetail

IDirect3DRMProgressiveMesh

Sets the minimum level of detail that will be rendered during a load from 0.0 (minimum detail) to 1.0 (maximum detail). Normally, the progressive mesh will be rendered once the base mesh is available (and the mesh is in the scene graph).

HRESULT SetMinRenderDetail(
D3DVALUE dvCount
)

Parameters
dvCount
Requested minimum detail.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE
D3DRMERR_REQUESTTOOSMALL

Remarks

This API sets the minimum number of faces/vertices that will be rendered during the load (larger than the base mesh).

Any subsequent IDirect3DRMProgressiveMesh::SetDetail, IDirect3DRMProgressiveMesh::SetFaceDetail, or IDirect3DRMProgressiveMesh::SetVertexDetail calls will override this.

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh

Sets the rendering quality of a Direct3DRMProgressiveMesh object.

HRESULT SetQuality(
D3DRMRENDERQUALITY quality
);

Parameters
quality
Member of the D3DRMRENDERQUALITY enumerated type that specifies the new rendering quality to use.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

An object's quality has three components: shade mode (flat or Gouraud, Phong is not yet implemented and will default to Gouraud shading), lighting type (on or off), and fill mode (point, wire-frame or solid).

You can set the quality of a device with IDirect3DRMDevice::SetQuality. By default it is D3DRMRENDER_FLAT (flat shading, lights on, and solid fill).

You can set the quality of a Direct3DRMProgressiveMesh object with the SetQuality method. By default, a Direct3DRMProgressiveMesh object's quality is D3DRMRENDER_GOURAUD (Gouraud shading, lights on, and solid fill).

Direct3D Retained Mode renders an object at the lowest quality setting based on the device and object's current setting for each individual component. For example, if the object's current quality setting is D3DRMRENDER_GOURAUD, and the device is D3DRMRENDER_FLAT, the object will be rendered with flat shading, solid fill and lights on.

If the object's current quality setting is D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME and the device's quality setting is D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT, the object will be rendered with flat shading, lights off, and point fill mode.

These rules apply to Direct3DRMMeshBuilder objects, Direct3DRMMeshBuilder2 objects, and Direct3DRMProgressiveMesh objects. However, Direct3DRMMesh objects do not follow these rules. Mesh objects ignore the device's quality settings and use the group quality setting (which defaults to D3DRMRENDER_GOURAUD).

See Also

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh::SetVertexDetail

IDirect3DRMProgressiveMesh

Sets the requested level of vertex detail.

HRESULT SetVertexDetail(
DWORD dwCount
)

Parameters
dwCount
The number of vertices requested.
Return Values

Returns D3DRM_OK if successful, or one of the following errors:
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

Remarks

If not enough detail has been downloaded yet (but will be available), the request will be acknowledged and D3DRMERR_PENDING is returned. This error is informational and indicates that the requested level will be set as soon as enough detail is available. If the detail requested is greater than the detail available in the progressive mesh, D3DRMERR_REQUESTTOOLARGE is returned.

See Also

IDirect3DRMProgressiveMesh::GetVertexDetail

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMShadow

Applications use the IDirect3DRMShadow interface to initialize Direct3DRMShadow objects. Note that this initialization is not necessary if the application uses the IDirect3DRM::CreateShadow method; it is required only if the application uses the IDirect3DRM::CreateObject method to create the shadow.

This section is a reference to the methods of the IDirect3DRMShadow interface. For a conceptual overview, see IDirect3DRMShadow Interface.

The IDirect3DRMShadow interface supports the Init method.

The IDirect3DRMShadow interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMShadow interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMShadow object is obtained by using the IDirect3DRM::CreateShadow method.

IDirect3DRMShadow::Init

IDirect3DRMShadow

Initializes a Direct3DRMShadow object.

HRESULT Init(
LPDIRECT3DRMVISUAL lpD3DRMVisual,
LPDIRECT3DRMLIGHT lpD3DRMLight,
D3DVALUE px,
D3DVALUE py,
D3DVALUE pz,
D3DVALUE nx,
D3DVALUE ny,
D3DVALUE nz
);

Parameters
lpD3DRMVisual
Address of the Direct3DRMVisual object casting the shadow.
lpD3DRMLight
Address of the Direct3DRMLight object that provides the light that defines the shadow.
px, py, and pz
Coordinates of a point on the plane on which the shadow is cast.
nx, ny, and nz
Coordinates of the normal vector of the plane on which the shadow is cast.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMTexture

Applications use the methods of the IDirect3DRMTexture interface to work with textures, which are rectangular arrays of pixels. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMTexture and IDirect3DRMTexture2 Interfaces.

To avoid unnecessary delays when creating textures, hold onto textures you want to use again, instead of creating them each time they're needed. For optimal performance, use a texture surface format that is supported by the device you are using. This will avoid a costly format conversion when the texture is created and any time it changes.

See the remarks in IDirect3DRM::LoadTexture for an example showing how to keep a reference to textures loaded in a texture callback through IDirect3DRM::LoadTexture.

The methods of the IDirect3DRMTexture interface can be organized into the following groups:

Color | GetColors
SetColors
Decals | GetDecalOrigin
GetDecalScale
GetDecalSize
GetDecalTransparency
GetDecalTransparentColor
SetDecalOrigin
SetDecalScale
SetDecalSize
SetDecalTransparency
SetDecalTransparentColor
Images | GetImage
Initialization | InitFromFile
InitFromResource
InitFromSurface
Renderer notification | Changed
Shading | GetShades
SetShades

The IDirect3DRMTexture interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMTexture interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMTexture object is obtained by using the IDirect3DRM::CreateTexture method.

IDirect3DRMTexture::Changed

IDirect3DRMTexture

Informs the renderer that the application has changed the pixels or the palette of a texture.

HRESULT Changed(
BOOL bPixels,
BOOL bPalette
);

Parameters
bPixels
If this parameter is TRUE, the pixels have changed.
bPalette
If this parameter is TRUE, the palette has changed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMTexture::GetColors

IDirect3DRMTexture

Retrieves the maximum number of colors used for rendering a texture.

DWORD GetColors( );

Return Values

Returns the number of colors.

Remarks

This method returns the number of colors that the texture has been quantized to, not the number of colors in the image from which the texture was created. Consequently, the number of colors that are returned usually matches the colors that were set by using the IDirect3DRM::SetDefaultTextureColors method—unless you used the IDirect3DRMTexture::SetColors method explicitly to change the colors for the texture.

See Also

IDirect3DRMTexture::SetColors

IDirect3DRMTexture::GetDecalOrigin

IDirect3DRMTexture

Retrieves the current origin of the decal.

HRESULT GetDecalOrigin(
LONG * lplX,
LONG * lplY
);

Parameters
lplX and lplY
Addresses of variables that will be filled with the origin of the decal when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::SetDecalOrigin

IDirect3DRMTexture::GetDecalScale

IDirect3DRMTexture

Retrieves the scaling property of the given decal.

DWORD GetDecalScale( );

Return Values

Returns the scaling property if successful, or -1 otherwise.

See Also

IDirect3DRMTexture::SetDecalScale

IDirect3DRMTexture::GetDecalSize

IDirect3DRMTexture

Retrieves the size of the decal.

HRESULT GetDecalSize(
D3DVALUE *lprvWidth,
D3DVALUE *lprvHeight
);

Parameters
lprvWidth and lprvHeight
Addresses of variables that will be filled with the width and height of the decal when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::SetDecalSize

IDirect3DRMTexture::GetDecalTransparency

IDirect3DRMTexture

Retrieves the transparency property of the decal.

BOOL GetDecalTransparency( );

Return Values

Returns TRUE if the decal has a transparent color, FALSE otherwise.

See Also

IDirect3DRMTexture::SetDecalTransparency

IDirect3DRMTexture::GetDecalTransparentColor

IDirect3DRMTexture

Retrieves the transparent color of the decal.

D3DCOLOR GetDecalTransparentColor( );

Return Values

Returns the value of the transparent color.

See Also

IDirect3DRMTexture::SetDecalTransparentColor

IDirect3DRMTexture::GetImage

IDirect3DRMTexture

Retrieves an address of the image that the texture was created with. Returns a NULL pointer if the current texture was created with a DirectDraw surface.

D3DRMIMAGE * GetImage( );

Return Values

Returns the address of the D3DRMIMAGE structure that the current texture was created with.

IDirect3DRMTexture::GetShades

IDirect3DRMTexture

Retrieves the number of shades used for each color in the texture when rendering.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMTexture::SetShades

IDirect3DRMTexture::InitFromFile

IDirect3DRMTexture

Initializes a texture by using the information in a given file.

HRESULT InitFromFile(
const char *filename
);

Parameters
filename
Address of a string specifying the file from which initialization information is drawn.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

You must have created the texture to be initialized using the IDirect3DRM::CreateObject method.

See Also

IDirect3DRMTexture::InitFromResource, IDirect3DRMTexture::InitFromSurface

IDirect3DRMTexture::InitFromResource

IDirect3DRMTexture

Initializes a Direct3DRMTexture object from a specified resource.

HRESULT InitFromResource(
HRSRC rs
);

Parameters
rs
Handle of the specified resource.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromSurface

IDirect3DRMTexture::InitFromSurface

IDirect3DRMTexture

Initializes a texture by using the data from a given DirectDraw surface.

HRESULT InitFromSurface(
LPDIRECTDRAWSURFACE lpDDS
);

Parameters
lpDDS
Address of a DirectDraw surface from which initialization information is drawn.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::InitFromFile, IDirect3DRMTexture::InitFromResource

IDirect3DRMTexture::SetColors

IDirect3DRMTexture

Sets the maximum number of colors used for rendering a texture. This method is required only in the ramp color model.

HRESULT SetColors(
DWORD ulColors
);

Parameters
ulColors
Number of colors. The default value is 8.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::GetColors

IDirect3DRMTexture::SetDecalOrigin

IDirect3DRMTexture

Sets the origin of the decal as an offset from the top left of the decal.

HRESULT SetDecalOrigin(
LONG lX,
LONG lY
);

Parameters
lX and lY
New origin, in decal coordinates, for the decal. The default origin is [0, 0].
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The decal's origin is mapped to its frame's position when rendering. For example, the origin of a decal of a cross would be set to the middle of the decal, and the origin of an arrow pointing down would be set to midway along the bottom edge.

This method is also used to add a decal origin key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture::GetDecalOrigin

IDirect3DRMTexture::SetDecalScale

IDirect3DRMTexture

Sets the scaling property for a decal.

HRESULT SetDecalScale(
DWORD dwScale
);

Parameters
dwScale
If this parameter is TRUE, depth is taken into account when the decal is scaled. If it is FALSE, depth information is ignored. The default value is TRUE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::GetDecalScale

IDirect3DRMTexture::SetDecalSize

IDirect3DRMTexture

Sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.

HRESULT SetDecalSize(
D3DVALUE rvWidth,
D3DVALUE rvHeight
);

Parameters
rvWidth and rvHeight
New width and height, in model coordinates, of the decal. The default size is [1, 1].
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a decal size key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture::GetDecalSize

IDirect3DRMTexture::SetDecalTransparency

IDirect3DRMTexture

Sets the transparency property of the decal.

HRESULT SetDecalTransparency(
BOOL bTransp
);

Parameters
bTransp
If this parameter is TRUE, the decal has a transparent color. If it is FALSE, it has an opaque color. The default value is FALSE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::GetDecalTransparency

IDirect3DRMTexture::SetDecalTransparentColor

IDirect3DRMTexture

Sets the transparent color for a decal.

HRESULT SetDecalTransparentColor(
D3DCOLOR rcTransp
);

Parameters
rcTransp
New transparent color. The default transparent color is black.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a decal transparent color key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture::GetDecalTransparentColor

IDirect3DRMTexture::SetShades

IDirect3DRMTexture

Sets the maximum number of shades to use for each color of the texture when rendering. This method is required only in the ramp color model.

HRESULT SetShades(
DWORD ulShades
);

Parameters
ulShades
New number of shades. This value must be a power of 2. The default value is 16.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture::GetShades

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMTexture2

The IDirect3DRMTexture2 interface is an extension of the IDirect3DRMTexture interface. IDirect3DRMTexture2::InitFromResource2 allows resources to be loaded from DLLs and executables other than the currently executing file. In addition, IDirect3DRMTexture2 has two additional methods. The IDirect3DRMTexture2::InitFromImage method creates a texture from an image in memory. This method is equivalent to the IDirect3DRM::CreateTexture method. The IDirect3DRMTexture2::GenerateMIPMap method generates a mipmap from a source image.

To avoid unnecessary delays when creating textures, hold onto textures you want to use again, instead of creating them each time they're needed. For optimal performance, use a texture surface format that is supported by the device you are using. This will avoid a costly format conversion when the texture is created and any time it changes.

See the remarks in IDirect3DRM2::LoadTexture for an example showing how to keep a reference to textures loaded in a texture callback through IDirect3DRM2::LoadTexture.

For a conceptual overview, see IDirect3DRMTexture and IDirect3DRMTexture2.

The methods of the IDirect3DRMTexture2 interface can be organized into the following groups:
Color | GetColors
SetColors
Decals | GetDecalOrigin
GetDecalScale
GetDecalSize
GetDecalTransparency
GetDecalTransparentColor
SetDecalOrigin
SetDecalScale
SetDecalSize
SetDecalTransparency
SetDecalTransparentColor
Images | GetImage
Initialization | InitFromFile
InitFromImage
InitFromResource2
InitFromSurface
MIP map generation | GenerateMIPMap
Renderer notification | Changed
Shading | GetShades
SetShades

The IDirect3DRMTexture2 interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMTexture2 interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

You can create an IDirect3DRMTexture2 object by calling IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface.

IDirect3DRMTexture2::Changed

IDirect3DRMTexture2

Informs the renderer that the application has changed the pixels or the palette of a Direct3DRMTexture2 object.

HRESULT Changed(
BOOL bPixels,
BOOL bPalette
);

Parameters
bPixels
If this parameter is TRUE, the pixels have changed.
bPalette
If this parameter is TRUE, the palette has changed.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

IDirect3DRMTexture2::GenerateMIPMap

IDirect3DRMTexture2

Generates a mipmap from a single image source.

HRESULT GenerateMIPMap(
DWORD dwFlags
);

Parameters
dwFlags
Should be set to zero.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method can be called any time after a texture is created. It will generate a MIP map of the source image down to a resolution of 1×1 by using bilinear filtering between levels. Once a MIP map has been generated, it will always be available and will be updated whenever IDirect3DRMTexture::Changed is called. When using MIP mapping, remember to change the texture quality to D3DRMTEXTURE_MIPNEAREST, D3DRMTEXTURE_MIPLINEAR, D3DRMTEXTURE_LINEARMIPNEAREST, or D3DRMTEXTURE_LINEARMIPLINEAR using IDirect3DRMDevice::SetTextureQuality. Extra MIP map levels will not be put into video memory for hardware devices unless the texture quality includes a MIP mapping type and the hardware device supports MIP mapping.

See Also

Mipmaps

IDirect3DRMTexture2::GetColors

IDirect3DRMTexture2

Retrieves the maximum number of colors used for rendering a Direct3DRMTexture2 object.

DWORD GetColors( );

Return Values

Returns the number of colors.

Remarks

This method returns the number of colors that the Direct3DRMTexture2 object has been quantized to, not the number of colors in the image from which the Direct3DRMTexture2 object was created. Consequently, the number of colors that are returned usually matches the colors that were set by calling the IDirect3DRM::SetDefaultTextureColors method, unless you used the IDirect3DRMTexture2::SetColors method explicitly to change the colors for the Direct3DRMTexture2 object.

See Also

IDirect3DRMTexture2::SetColors

IDirect3DRMTexture2::GetDecalOrigin

IDirect3DRMTexture2

Retrieves the current origin of the decal.

HRESULT GetDecalOrigin(
LONG * lplX,
LONG * lplY
);

Parameters
lplX and lplY
Addresses of variables that will be filled with the origin of the decal when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::SetDecalOrigin

IDirect3DRMTexture2::GetDecalScale

IDirect3DRMTexture2

Retrieves the scaling property of the given decal.

DWORD GetDecalScale( );

Return Values

Returns the scaling property if successful, or -1 otherwise.

See Also

IDirect3DRMTexture2::SetDecalScale

IDirect3DRMTexture2::GetDecalSize

IDirect3DRMTexture2

Retrieves the size of the decal.

HRESULT GetDecalSize(
D3DVALUE *lprvWidth,
D3DVALUE *lprvHeight
);

Parameters
lprvWidth and lprvHeight
Addresses of variables that will be filled with the width and height of the decal when the method returns.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::SetDecalSize

IDirect3DRMTexture2::GetDecalTransparency

IDirect3DRMTexture2

Retrieves the transparency property of the decal.

BOOL GetDecalTransparency( );

Return Values

Returns TRUE if the decal has a transparent color, FALSE otherwise.

See Also

IDirect3DRMTexture2::SetDecalTransparency

IDirect3DRMTexture2::GetDecalTransparentColor

IDirect3DRMTexture2

Retrieves the transparent color of the decal.

D3DCOLOR GetDecalTransparentColor( );

Return Values

Returns the value of the transparent color.

See Also

IDirect3DRMTexture2::SetDecalTransparentColor

IDirect3DRMTexture2::GetImage

IDirect3DRMTexture2

Returns an address of the image that the texture was created with.

D3DRMIMAGE * GetImage( );

Return Values

Returns the address of the D3DRMIMAGE structure that the current Direct3DRMTexture2 object was created with.

IDirect3DRMTexture2::GetShades

IDirect3DRMTexture2

Retrieves the number of shades used for each color in the texture when rendering.

DWORD GetShades( );

Return Values

Returns the number of shades.

See Also

IDirect3DRMTexture2::SetShades

IDirect3DRMTexture2::InitFromFile

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object using the information in a given file.

HRESULT InitFromFile(
LPCSTR filename
);

Parameters
filename
A string that specifies the file from which the texture initialization information is drawn.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

You must have created the Direct3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromResource2, IDirect3DRMTexture2::InitFromSurface

IDirect3DRMTexture2::InitFromImage

IDirect3DRMTexture2

Initializes a texture from an image in memory.

HRESULT InitFromImage(
LPD3DRMIMAGE lpImage
);

Parameters
lpImage
Address of a D3DRMIMAGE structure describing the source of the texture.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

You must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromResource2, IDirect3DRMTexture2::InitFromSurface

IDirect3DRMTexture2::InitFromResource2

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object from a specified resource.

HRESULT InitFromResource2(
HModule hModule,
LPCTSTR strName,
LPCTSTR strType
);

Parameters
hModule
Handle of the specified resource.
strName
The name of the resource to be used to initialize the texture.
strType
The type name of the resource used to initialize the texture. Textures can be stored in RT_BITMAP and RT_RCDATA resource types, or user-defined types. If the resource type is user-defined, this method passes the resource module handle, the resource name, and the resource type to the FindResource Win32 API.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

You must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromSurface

IDirect3DRMTexture2::InitFromSurface

IDirect3DRMTexture2

Initializes a Direct3DRMTexture2 object by using the data from a given DirectDraw surface. This method performs the same as IDirect3DRMTexture::InitFromSurface.

HRESULT InitFromSurface(
LPDIRECTDRAWSURFACE lpDDS
);

Parameters
lpDDS
Address of a DirectDraw surface from which initialization information is drawn.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

You must have created the IDirect3DRMTexture2 object to be initialized using the IDirect3DRM2::CreateTexture or IDirect3DRM2::CreateTextureFromSurface methods.

See Also

IDirect3DRMTexture2::InitFromFile, IDirect3DRMTexture2::InitFromImage, IDirect3DRMTexture2::InitFromResource2

IDirect3DRMTexture2::SetColors

IDirect3DRMTexture2

Sets the maximum number of colors used for rendering a Direct3DRMTexture2 object. This method is required only in the ramp color model.

HRESULT SetColors(
DWORD ulColors
);

Parameters
ulColors
Number of colors. The default value is 8.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::GetColors

IDirect3DRMTexture2::SetDecalOrigin

IDirect3DRMTexture2

Sets the origin of the decal as an offset from the top left of the decal.

HRESULT SetDecalOrigin(
LONG lX,
LONG lY
);

Parameters
lX and lY
New origin, in decal coordinates, for the decal. The default origin is [0, 0].
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

The decal's origin is mapped to its frame's position when rendering. For example, the origin of a decal of a cross would be set to the middle of the decal, and the origin of an arrow pointing down would be set to midway along the bottom edge.

This method is also used to add a decal origin key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalOrigin

IDirect3DRMTexture2::SetDecalScale

IDirect3DRMTexture2

Sets the scaling property for a decal.

HRESULT SetDecalScale(
DWORD dwScale
);

Parameters
dwScale
If this parameter is TRUE, depth is taken into account when the decal is scaled. If it is FALSE, depth information is ignored. The default value is TRUE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::GetDecalScale

IDirect3DRMTexture2::SetDecalSize

IDirect3DRMTexture2

Sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.

HRESULT SetDecalSize(
D3DVALUE rvWidth,
D3DVALUE rvHeight
);

Parameters
rvWidth and rvHeight
New width and height, in model coordinates, of the decal. The default size is [1, 1].
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a decal size key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalSize

IDirect3DRMTexture2::SetDecalTransparency

IDirect3DRMTexture2

Sets the transparency property of the decal.

HRESULT SetDecalTransparency(
BOOL bTransp
);

Parameters
bTransp
If this parameter is TRUE, the decal has a transparent color. If it is FALSE, it has an opaque color. The default value is FALSE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::GetDecalTransparency

IDirect3DRMTexture2::SetDecalTransparentColor

IDirect3DRMTexture2

Sets the transparent color for a decal.

HRESULT SetDecalTransparentColor(
D3DCOLOR rcTransp
);

Parameters
rcTransp
New transparent color. The default transparent color is black.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a decal transparent color key to a Direct3DRMTextureInterpolator object.

See Also

IDirect3DRMTexture2::GetDecalTransparentColor

IDirect3DRMTexture2::SetShades

IDirect3DRMTexture2

Sets the maximum number of shades to use for each color for the Direct3DRMTexture2 object when rendering. This method is required only in the ramp color model.

HRESULT SetShades(
DWORD ulShades
);

Parameters
ulShades
New number of shades. This value must be a power of 2. The default value is 16.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible return codes, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMTexture2::GetShades

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

* Top of Page


IDirect3DRMUserVisual

Applications use the IDirect3DRMUserVisual interface to initialize Direct3DRMUserVisual objects. Note that this initialization is not necessary if the application uses the IDirect3DRM::CreateUserVisual method; it is required only if the application uses the IDirect3DRM::CreateObject method to create the user-visual object. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMUserVisual Interface.

The IDirect3DRMUserVisual interface supports the Init method.

The IDirect3DRMUserVisual interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMUserVisual interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMUserVisual object is obtained by using the IDirect3DRM::CreateUserVisual method.

IDirect3DRMUserVisual::Init

IDirect3DRMUserVisual

Initializes a Direct3DRMUserVisual object.

HRESULT Init(
D3DRMUSERVISUALCALLBACK d3drmUVProc,
void * lpArg
);

Parameters
d3drmUVProc
Application-defined D3DRMUSERVISUALCALLBACK callback function.
lpArg
Application-defined data to be passed to the callback function.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Applications can use the IDirect3DRM::CreateUserVisual method to create and initialize a user-visual object at the same time. It is necessary to use IDirect3DRMUserVisual::Init only when the application has created the user-visual object by using the IDirect3DRM::CreateObject method.


IDirect3DRMViewport

Applications use the methods of the IDirect3DRMViewport interface to work with viewport objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMViewport and IDirect3DRMViewportArray Interface.

The methods of the IDirect3DRMViewport interface can be organized into the following groups:

Camera | GetCamera
SetCamera
Clipping planes | GetBack
GetFront
GetPlane
SetBack
SetFront
SetPlane
Dimensions | GetHeight
GetWidth
Field of view | GetField
SetField
Initialization | Init
Miscellaneous | Clear
Configure
ForceUpdate
GetDevice
GetDirect3DViewport
Pick
Render
Offsets | GetX
GetY
Projection types | GetProjection
SetProjection
Scaling | GetUniformScaling
SetUniformScaling
Transformations | InverseTransform
Transform

The IDirect3DRMViewport interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMViewport interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMViewport object is obtained by using the IDirect3DRM::CreateViewport method.

IDirect3DRMViewport::Clear

IDirect3DRMViewport

Clears the given viewport to the current background color.

HRESULT Clear( );

Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::Configure

IDirect3DRMViewport

Reconfigures the origin and dimensions of a viewport.

HRESULT Configure(
LONG lX,
LONG lY,
DWORD dwWidth,
DWORD dwHeight
);

Parameters
lX and lY
New position of the viewport.
dwWidth and dwHeight
New width and height of the viewport.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method returns D3DRMERR_BADVALUE if lX + dwWidth or lY + dwHeight are greater than the width or height of the device, or if any value of lX, lY, dwWidth, or dwHeight is less than zero.

IDirect3DRMViewport::ForceUpdate

IDirect3DRMViewport

Forces an area of the viewport to be updated. The specified area will be copied to the screen at the next call to the IDirect3DRMDevice::Update method.

HRESULT ForceUpdate(
DWORD dwX1,
DWORD dwY1,
DWORD dwX2,
DWORD dwY2
);

Parameters
dwX1 and dwY1
Upper-left corner of area to be updated.
dwX2 and dwY2
Lower-right corner of area to be updated.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The system might update any region that is larger than the specified rectangle, possibly including the entire window.

IDirect3DRMViewport::GetBack

IDirect3DRMViewport

Retrieves the position of the back clipping plane for a viewport.

D3DVALUE GetBack( );

Return Values

Returns a value describing the distance between the back clipping plane and the camera.

See Also

IDirect3DRMViewport::SetBack, Viewing Frustum

IDirect3DRMViewport::GetCamera

IDirect3DRMViewport

Retrieves the camera for a viewport.

HRESULT GetCamera(
LPDIRECT3DRMFRAME *lpCamera
);

Parameters
lpCamera
Pointer to the Direct3DRMFrame object representing the camera.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport::SetCamera, Camera

IDirect3DRMViewport::GetDevice

IDirect3DRMViewport

Retrieves the device associated with a viewport.

HRESULT GetDevice(
LPDIRECT3DRMDEVICE *lpD3DRMDevice
);

Parameters
lpD3DRMDevice
Address of a variable that represents the Direct3DRMDevice object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::GetDirect3DViewport

IDirect3DRMViewport

Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport.

HRESULT GetDirect3DViewport(
LPDIRECT3DVIEWPORT * lplpD3DViewport
);

Parameters
lplpD3DViewport
Address of a pointer that is initialized with a pointer to the Direct3DViewport object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::GetField

IDirect3DRMViewport

Retrieves the field of view for a viewport.

D3DVALUE GetField( );

Return Values

Returns a value describing the field of view.

See Also

IDirect3DRMViewport::SetField, Viewing Frustum

IDirect3DRMViewport::GetFront

IDirect3DRMViewport

Retrieves the position of the front clipping plane for a viewport.

D3DVALUE GetFront( );

Return Values

Returns a value describing the distance from the camera to the front clipping plane.

See Also

IDirect3DRMViewport::SetFront, Viewing Frustum

IDirect3DRMViewport::GetHeight

IDirect3DRMViewport

Retrieves the height, in pixels, of the viewport.

DWORD GetHeight( );

Return Values

Returns the pixel height.

IDirect3DRMViewport::GetPlane

IDirect3DRMViewport

Retrieves the dimensions of the viewport on the front clipping plane.

HRESULT GetPlane(
D3DVALUE *lpd3dvLeft,
D3DVALUE *lpd3dvRight,
D3DVALUE *lpd3dvBottom,
D3DVALUE *lpd3dvTop
);

Parameters
lpd3dvLeft, lpd3dvRight, lpd3dvBottom, and lpd3dvTop
Addresses of variables that will be filled with the dimensions of the viewport on the front clipping plane.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport::SetPlane

IDirect3DRMViewport::GetProjection

IDirect3DRMViewport

Retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.

D3DRMPROJECTIONTYPE GetProjection( );

Return Values

Returns one of the members of the D3DRMPROJECTIONTYPE enumerated type.

See Also

IDirect3DRMViewport::SetProjection

IDirect3DRMViewport::GetUniformScaling

IDirect3DRMViewport

Retrieves the scaling property used to scale the viewing volume into the larger window dimension.

BOOL GetUniformScaling( );

Return Values

Returns TRUE if the viewport scales uniformly, or FALSE otherwise.

See Also

IDirect3DRMViewport::SetUniformScaling

IDirect3DRMViewport::GetWidth

IDirect3DRMViewport

Retrieves the width, in pixels, of the viewport.

DWORD GetWidth( );

Return Values

Returns the pixel width.

IDirect3DRMViewport::GetX

IDirect3DRMViewport

Retrieves the x-offset of the start of the viewport on a device.

LONG GetX( );

Return Values

Returns the x-offset.

IDirect3DRMViewport::GetY

IDirect3DRMViewport

Retrieves the y-offset of the start of the viewport on a device.

LONG GetY( );

Return Values

Returns the y-offset.

IDirect3DRMViewport::Init

IDirect3DRMViewport

Initializes a Direct3DRMViewport object.

HRESULT Init(
LPDIRECT3DRMDEVICE lpD3DRMDevice,
LPDIRECT3DRMFRAME lpD3DRMFrameCamera,
DWORD xpos,
DWORD ypos,
DWORD width,
DWORD height
);

Parameters
lpD3DRMDevice
Address of the DirectD3DRMDevice object associated with this viewport.
lpD3DRMFrameCamera
Address of the camera frame associated with this viewport.
xpos and ypos
The x- and y-coordinates of the upper-left corner of the viewport.
width and height
Width and height of the viewport.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::InverseTransform

IDirect3DRMViewport

Transforms the vector in the lprvSrc parameter in screen coordinates to world coordinates, and returns the result in the lprvDst parameter.

HRESULT InverseTransform(
D3DVECTOR * lprvDst,
D3DRMVECTOR4D * lprvSrc
);

Parameters
lprvDst
Address of a D3DVECTOR structure that will be filled with the result of the operation when the method returns.
lprvSrc
Address of a D3DRMVECTOR4D structure that represents the source of the operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::Pick

IDirect3DRMViewport

Finds a depth-sorted list of objects (and faces, if relevant) that includes the path taken in the hierarchy from the root down to the frame that contained the object.

HRESULT Pick(
LONG lX,
LONG lY,
LPDIRECT3DRMPICKEDARRAY* lplpVisuals
);

Parameters
lX and lY
Coordinates used for picking.
lplpVisuals
Address of a pointer that is initialized with a valid pointer to the IDirect3DRMPickedArray interface if the call succeeds.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::Render

IDirect3DRMViewport

Renders a frame hierarchy to the given viewport. Only those visuals on the given frame and any frames below it in the hierarchy are rendered.

HRESULT Render(
LPDIRECT3DRMFRAME lpD3DRMFrame
);

Parameters
lpD3DRMFrame
Address of a variable that represents the Direct3DRMFrame object that represents the frame hierarchy to be rendered.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport::SetBack

IDirect3DRMViewport

Sets the position of the back clipping plane for a viewport.

HRESULT SetBack(
D3DVALUE rvBack
);

Parameters
rvBack
Distance between the camera and the back clipping plane.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a back clipping plane position key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport::GetBack, IDirect3DRMViewport::SetFront, Viewing Frustum

IDirect3DRMViewport::SetCamera

IDirect3DRMViewport

Sets a camera for a viewport.

HRESULT SetCamera(
LPDIRECT3DRMFRAME lpCamera
);

Parameters
lpCamera
Address of a variable that represents the Direct3DRMFrame object that represents the camera.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method sets a viewport's position, direction, and orientation to that of the given camera frame. The view is oriented along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.

See Also

IDirect3DRMViewport::GetCamera, Camera

IDirect3DRMViewport::SetField

IDirect3DRMViewport

Sets the field of view for a viewport.

HRESULT SetField(
D3DVALUE rvField
);

Parameters
rvField
New field of view. This value is a fraction of the viewing angle. The default value is 0.5. If this value is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error. The viewing angle is defined as the 2 times the arctangent of the front clipping plane over the distance from the camera. See Viewing Frustum for more information on the viewing angle. An rvField value of 0.5 would be one-half the viewing angle A shown in the Viewing Frustum section.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a field of view key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport::GetField, Viewing Frustum

IDirect3DRMViewport::SetFront

IDirect3DRMViewport

Sets the position of the front clipping plane for a viewport.

HRESULT SetFront(
D3DVALUE rvFront
);

Parameters
rvFront
Distance from the camera to the front clipping plane.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The default position is 1.0. If the value passed is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error.

This method is also used to add a front clipping plane position key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport::GetFront, Viewing Frustum

IDirect3DRMViewport::SetPlane

IDirect3DRMViewport

Sets the dimensions of the viewport on the front clipping plane, relative to the camera's z-axis.

HRESULT SetPlane(
D3DVALUE rvLeft,
D3DVALUE rvRight,
D3DVALUE rvBottom,
D3DVALUE rvTop
);

Parameters
rvLeft, rvRight, rvBottom, and rvTop
Minimum x-, maximum x-, minimum y-, and maximum y-coordinates, respectively, of the four sides of the viewport.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Unlike the IDirect3DRMViewport::SetField method, which specifies a centered proportional viewport, this method allows you to specify a viewport of arbitrary proportion and position. For example, this method could be used to construct a sheared viewing frustum to implement a right- or left-eye stereo view.

This method is also used to add a plane key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport::GetPlane, IDirect3DRMViewport::SetField

IDirect3DRMViewport::SetProjection

IDirect3DRMViewport

Sets the projection type for a viewport.

HRESULT SetProjection(
D3DRMPROJECTIONTYPE rptType
);

Parameters
rptType
One of the members of the D3DRMPROJECTIONTYPE enumerated type.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport::GetProjection

IDirect3DRMViewport::SetUniformScaling

IDirect3DRMViewport

Sets the scaling property used to scale the viewing volume into the larger dimension of the window.

HRESULT SetUniformScaling(
BOOL bScale
);

Parameters
bScale
New scaling property. If this parameter is TRUE, the same horizontal and vertical scaling factor is used to scale the viewing volume. Otherwise, different scaling factors are used to scale the viewing volume exactly into the window. The default setting is TRUE.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is typically used with the IDirect3DRMViewport::SetPlane method to support banding.

See Also

IDirect3DRMViewport::GetUniformScaling

IDirect3DRMViewport::Transform

IDirect3DRMViewport

Transforms the vector in the lprvSrc parameter in world coordinates to screen coordinates, and returns the result in the lprvDst parameter.

HRESULT Transform(
D3DRMVECTOR4D * lprvDst,
D3DVECTOR * lprvSrc
);

Parameters
lprvDst
Address of a D3DRMVECTOR4D structure that acts as the destination for the transformation operation.
lprvSrc
Address of a D3DVECTOR structure that acts as the source for the transformation operation.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The result of the transformation is a four-element homogeneous vector. The point represented by the resulting vector is visible if the following equations are true:

Equations for testing whether the point is visible


IDirect3DRMWinDevice

Applications use the methods of the IDirect3DRMWinDevice interface to respond to window messages in a window procedure. This section is a reference to the methods of this interface. For a conceptual overview, see Window Management.

The IDirect3DRMWinDevice interface supports the following methods:
HandleActivate
HandlePaint

The IDirect3DRMWinDevice interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

The Direct3DRMWinDevice object is obtained by calling the IDirect3DRMObject::QueryInterface method and specifying IID_IDirect3DRMWinDevice, or by calling a method such as IDirect3DRM::CreateDeviceFromD3D. The IDirect3DRMWinDevice methods are inherited from the IDirect3DRMDevice interface.

IDirect3DRMWinDevice::HandleActivate

IDirect3DRMWinDevice

Responds to a Microsoft® Windows®w WM_ACTIVATE message. This ensures that the colors are correct in the active rendering window.

HRESULT HandleActivate(
WORD wParam
);

Parameters
wParam
WPARAM parameter passed to the message-processing procedure with the WM_ACTIVATE message.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMWinDevice::HandlePaint

IDirect3DRMWinDevice

Responds to a Windows WM_PAINT message. The hDC parameter should be taken from the PAINTSTRUCT structure given to the Windows BeginPaint function. This method should be called before repainting any application areas in the window because it may repaint areas outside the viewports that have been created on the device.

HRESULT HandlePaint(
HDC hDC
);

Parameters
hDC
Handle of the device context (DC).
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.


IDirect3DRMWrap

Applications use the methods of the IDirect3DRMWrap interface to work with wrap objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMWrap Interface.

The methods of the IDirect3DRMWrap interface can be organized into the following groups:
Initialization | Init
Wrap | Apply
ApplyRelative

The IDirect3DRMWrap interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMWrap interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMWrap object is obtained by using the IDirect3DRM::CreateWrap method.

IDirect3DRMWrap::Apply

IDirect3DRMWrap

Applies a Direct3DRMWrap object to its destination object. The destination object is typically a face or a mesh.

HRESULT Apply(
LPDIRECT3DRMOBJECT lpObject
);

Parameters
lpObject
Address of the destination object.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRM::CreateWrap

IDirect3DRMWrap::ApplyRelative

IDirect3DRMWrap

Applies the wrap to the vertices of the object, first transforming each vertex by the frame's world transformation and the inverse world transformation of the wrap's reference frame.

HRESULT ApplyRelative(
LPDIRECT3DRMFRAME frame,
LPDIRECT3DRMOBJECT mesh
);

Parameters
frame
Direct3DRMFrame object containing the object to wrap.
mesh
Direct3DRMWrap object to apply.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRM::CreateWrap

IDirect3DRMWrap::Init

IDirect3DRMWrap

Initializes a Direct3DRMWrap object.

HRESULT Init(
D3DRMWRAPTYPE d3drmwt,
LPDIRECT3DRMFRAME lpd3drmfRef,
D3DVALUE ox,
D3DVALUE oy,
D3DVALUE oz,
D3DVALUE dx,
D3DVALUE dy,
D3DVALUE dz,
D3DVALUE ux,
D3DVALUE uy,
D3DVALUE uz,
D3DVALUE ou,
D3DVALUE ov,
D3DVALUE su,
D3DVALUE sv
);

Parameters
d3drmwt
One of the members of the D3DRMWRAPTYPE enumerated type.
lpd3drmfRef
Address of a Direct3DRMFrame object representing the reference frame for this Direct3DRMWrap object.
ox, oy, and oz
Origin of the wrap.
dx, dy, and dz
The z-axis of the wrap.
ux, uy, and uz
The y-axis of the wrap.
ou and ov
Origin of the texture.
su and sv
Scale factor of the texture.
Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRM::CreateWrap


Structures

The Microsoft® Direct3D® Retained Mode structures are:

  • D3DRMBOX
  • D3DRMIMAGE
  • D3DRMLOADMEMORY
  • D3DRMLOADRESOURCE
  • D3DRMPALETTEENTRY
  • D3DRMPICKDESC
  • D3DRMPICKDESC2
  • D3DRMPMESHLOADSTATUS
  • D3DRMQUATERNION
  • D3DRMRAY
  • D3DRMVECTOR4D
  • D3DRMVERTEX

D3DRMBOX

Defines the bounding box retrieved by the IDirect3DRMMesh::GetBox and IDirect3DRMMeshBuilder::GetBox methods.

typedef struct _D3DRMBOX {
    D3DVECTOR min, max;
}D3DRMBOX;
typedef D3DRMBOX *LPD3DRMBOX;
Members
min and max
Values defining the bounds of the box. These values are D3DVECTOR structures.
See Also

D3DVECTOR, IDirect3DRMMesh::GetBox, IDirect3DRMMeshBuilder::GetBox

D3DRMIMAGE

Describes an image that is attached to a texture by the IDirect3DRM::CreateTexture method. IDirect3DRMTexture::GetImage returns the address of this image.

typedef struct _D3DRMIMAGE {
    int                width, height;
    int                aspectx, aspecty;
    int                depth;
    int                rgb;
    int                bytes_per_line;
    void*              buffer1;
    void*              buffer2;
    unsigned long      red_mask;
    unsigned long      green_mask;
    unsigned long      blue_mask;
    unsigned long      alpha_mask;
    int                palette_size;
    D3DRMPALETTEENTRY* palette;
}D3DRMIMAGE;
typedef D3DRMIMAGE, *LPD3DRMIMAGE;
Members
width and height
Width and height of the image, in pixels.
aspectx and aspecty
Aspect ratio for nonsquare pixels.
depth
Number of bits that specify each pixel.
rgb
A flag that indicates whether pixels are RGB values or palette indices. If this member is FALSE, pixels are indices into a palette. Otherwise, pixels encode RGB values.
bytes_per_line
Number of bytes of memory for a scan line. This value must be a multiple of four.
buffer1
Memory to render into (first buffer).
buffer2
Second rendering buffer for double buffering. Set this member to NULL for single buffering.
red_mask, green_mask, blue_mask, and alpha_mask
A mask for RGB pixels or pixel palette indices. If rgb is TRUE, these members are masks for the red, green, and blue parts of a pixel. Otherwise, they are masks for the significant bits of the red, green, and blue elements in the palette. For example, most Super VGA (SVGA) displays use 64 intensities of red, green, and blue, so the masks should all be set to 0xfc.
palette_size
Number of entries in the palette.
palette
A pointer to a D3DRMPALETTEENTRY structure describing the color palette to be used. This structure is only used if the D3DRMIMAGE rgb member is FALSE.

See Also

IDirect3DRM::CreateTexture, IDirect3DRMTexture::GetImage

D3DRMLOADMEMORY

Identifies a resource to be loaded when an application uses the IDirect3DRM::Load method (or one of the other Load methods) and specifies D3DRMLOAD_FROMMEMORY.

typedef struct _D3DRMLOADMEMORY {
    LPVOID lpMemory;
    DWORD  dSize;
} D3DRMLOADMEMORY, *LPD3DRMLOADMEMORY;
Members
lpMemory
Address of a block of memory to be loaded.
dSize
Size, in bytes, of the block of memory to be loaded.
See Also

IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADOPTIONS, D3DRMLOADRESOURCE

D3DRMLOADRESOURCE

Identifies a resource to be loaded when an application uses the IDirect3DRM::Load method (or one of the other Load methods) and specifies D3DRMLOAD_FROMRESOURCE.

typedef struct _D3DRMLOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
} D3DRMLOADRESOURCE, *LPD3DRMLOADRESOURCE;
Members
hModule
Handle of the module containing the resource to be loaded. If this member is NULL, the resource must be attached to the using executable file.

lpName
Name of the resource to be loaded. For example, if the resource is a mesh, this member should specify the name of the mesh file.
lpType
User-defined type identifying the resource.
Remarks

If the high-order word of the lpName or lpType member is zero, the low-order word specifies the integer identifier of the name or type of the given resource. Otherwise, those parameters are long pointers to null-terminated strings. If the first character of the string is a number sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource's name or type. For example, the string "#258" represents the integer identifier 258. An application should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

When an application uses a Load method and specifies D3DRMLOAD_FROMRESOURCE, it does not need to find or unlock any resources; the system handles this automatically.

See Also

IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, D3DRMLOADMEMORY, D3DRMLOADOPTIONS

D3DRMPALETTEENTRY

Describes the color palette used in a D3DRMIMAGE structure. This structure is used only if the rgb member of the D3DRMIMAGE structure is FALSE. (If it is TRUE, RGB values are used.)

typedef struct _D3DRMPALETTEENTRY {
    unsigned char red;
    unsigned char green;
    unsigned char blue;
    unsigned char flags;
}D3DRMPALETTEENTRY;
typedef D3DRMPALETTEENTRY, *LPD3DRMPALETTEENTRY;
Members
red, green, and blue
Values defining the primary color components that define the palette. These values can range from 0 through 255.
flags
Value defining how the palette is used by the renderer. This value is one of the members of the D3DRMPALETTEFLAGS enumerated type.
See Also

D3DRMIMAGE, D3DRMPALETTEFLAGS

D3DRMPICKDESC

Contains the pick position and face and group identifiers of the objects retrieved by the IDirect3DRMPickedArray::GetPick method.

typedef struct _D3DRMPICKDESC {
    ULONG       ulFaceIdx;
    LONG        lGroupIdx;
    D3DVECTOR   vPosition;
} D3DRMPICKDESC, *LPD3DRMPICKDESC;
Members
ulFaceIdx
Face index of the retrieved object.
lGroupIdx
Group index of the retrieved object.
vPosition
Value describing the position of the retrieved object. This value is a D3DVECTOR structure.
See Also

D3DVECTOR, IDirect3DRMPickedArray::GetPick

D3DRMPICKDESC2

Contains the face and group identifiers, pick position, horizontal and vertical texture coordinates for the vertex, vertex normal, and color of the objects retrieved by the IDirect3DRMPicked2Array::GetPick method.

typedef struct _D3DRMPICKDESC2
{
    ULONG	ulFaceIdx;
    LONG	lGroupIdx;
    D3DVECTOR	dvPosition;
    D3DVALUE	tu;
    D3DVALUE	tv;
    D3DVECTOR	dvNormal;
    D3DCOLOR	dcColor;

} D3DRMPICKDESC2, *LPD3DRMPICKDESC2;
Members
ulFaceIdx
Face index of the retrieved object.
lGroupIdx
Group index of the retrieved object.
vPosition
Value describing the position of the retrieved object. This value is a D3DVECTOR structure.
tu and tv
Horizontal and vertical texture coordinates, respectively, for the vertex.
dvNormal
Normal vector for the vertex.
dcColor
Vertex color.

D3DRMPMESHLOADSTATUS

Contains the loading status of a progressive mesh loaded with the IDirect3DRMProgressiveMesh::Load method. This structure can be retrieved with the IDirect3DRMProgressiveMesh::GetLoadStatus method.

typedef struct _D3DRMPMESHLOADSTATUS {
    DWORD dwSize;
    DWORD dwPMeshSize;
    DWORD dwBaseMeshSize;
    DWORD dwBytesLoaded;
    DWORD dwVerticesLoaded;
    DWORD dwFacesLoaded;
    DWORD dwFlags;
} D3DRMPMESHLOADSTATUS;
typedef D3DRMPMESHLOADSTATUS *LPD3DRMPMESHLOADSTATUS;
Members
dwSize
Size of the structure.
dwPMeshSize
Size of the total progressive mesh in bytes.
dwBaseMeshSize
Size of the base mesh in bytes.
dwBytesLoaded
Number of total bytes loaded.
dwVerticesLoaded
Number of vertices loaded.
dwFacesLoaded
Number of faces loaded.
dwFlags
Flags that indicate the status of the progressive mesh loading. Can be one of the following values:

D3DRMPMESHSTATUS_VALID — The progressive mesh object contains valid data.
D3DRMPMESHSTATUS_INTERRUPTED — The download was interrupted either because the application used IDirect3DRMProgressiveMesh::Abort or because the connection was lost.
D3DRMPMESHSTATUS_BASEMESHCOMPLETE — The base mesh has been downloaded.
D3DRMPMESHSTATUS_COMPLETE — All data has been downloaded.
D3DRMPMESHSTATUS_RENDERABLE — It is now possible to render the mesh.
See Also

IDirect3DRMProgressiveMesh::GetLoadStatus, IDirect3DRMProgressiveMesh::Load

D3DRMQUATERNION

Describes the rotation used by the IDirect3DRMAnimation::AddRotateKey method, and the quaternion used in IDirect3DRMFrame2::SetQuaternion. It is also used in several of the Direct3D mathematical functions.

typedef struct _D3DRMQUATERNION {
    D3DVALUE   s;
    D3DVECTOR  v;
}D3DRMQUATERNION;
typedef D3DRMQUATERNION, *LPD3DRMQUATERNION;
See Also

IDirect3DRMAnimation::AddRotateKey, IDirect3DRMFrame2::SetQuaternion, D3DRMQuaternionFromRotation, D3DRMQuaternionMultiply, D3DRMQuaternionSlerp, D3DRMMatrixFromQuaternion

D3DRMRAY

Defines the direction and starting position of the ray in IDirect3DRMFrame2::RayPick.

typedef struct _D3DRMRAY
{   D3DVECTOR dvDir;
    D3DVECTOR dvPos;
} D3DRMRAY, *LPD3DRMRAY;
Members
dvDir
Direction of the ray used in a ray pick.
dvPos
Starting position of the ray used in a ray pick.

D3DRMVECTOR4D

Describes the screen coordinates used as the destination of a transformation by the IDirect3DRMViewport::Transform method and as the source of a transformation by the IDirect3DRMViewport::InverseTransform method.

typedef struct _D3DRMVECTOR4D {
    D3DVALUE x;
    D3DVALUE y;
    D3DVALUE z;
    D3DVALUE w;
}D3DRMVECTOR4D;
typedef D3DRMVECTOR4D, *LPD3DRMVECTOR4D;
Members
x, y, z, and w
Values of the D3DVALUE type describing homogeneous values. These values define the result of the transformation.
See Also

IDirect3DRMViewport::Transform, IDirect3DRMViewport::InverseTransform

D3DRMVERTEX

Describes a vertex in a Direct3DRMMesh object.

typedef struct _D3DRMVERTEX{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DVALUE  tu, tv;
    D3DCOLOR  color;
} D3DRMVERTEX;
Members
position
Position of the vertex.
normal
Normal vector for the vertex.
tu and tv
Horizontal and vertical texture coordinates, respectively, for the vertex.
color
Vertex color.
See Also

IDirect3DRMMesh::GetVertices, IDirect3DRMMesh::SetVertices


Enumerated Types

The Microsoft® Direct3D® Retained Mode enumerated types are:

  • D3DRMCOLORSOURCE
  • D3DRMCOMBINETYPE
  • D3DRMFILLMODE
  • D3DRMFOGMODE
  • D3DRMFRAMECONSTRAINT
  • D3DRMLIGHTMODE
  • D3DRMLIGHTTYPE
  • D3DRMMATERIALMODE
  • D3DRMPALETTEFLAGS
  • D3DRMPROJECTIONTYPE
  • D3DRMRENDERQUALITY
  • D3DRMSHADEMODE
  • D3DRMSORTMODE
  • D3DRMTEXTUREQUALITY
  • D3DRMUSERVISUALREASON
  • D3DRMWRAPTYPE
  • D3DRMXOFFORMAT
  • D3DRMZBUFFERMODE

D3DRMCOLORSOURCE

Describes the color source of a Direct3DRMMeshBuilder object. You can set the color source by using the IDirect3DRMMeshBuilder::SetColorSource method. To retrieve it, use the IDirect3DRMMeshBuilder::GetColorSource method.

typedef enum _D3DRMCOLORSOURCE{
    D3DRMCOLOR_FROMFACE,
    D3DRMCOLOR_FROMVERTEX
} D3DRMCOLORSOURCE;
Values
D3DRMCOLOR_FROMFACE
Object's color source is a face.
D3DRMCOLOR_FROMVERTEX
Object's color source is a vertex.
See Also

IDirect3DRMMeshBuilder::SetColorSource, IDirect3DRMMeshBuilder::GetColorSource

D3DRMCOMBINETYPE

Specifies how to combine two matrices.

typedef enum _D3DRMCOMBINETYPE{
    D3DRMCOMBINE_REPLACE,
    D3DRMCOMBINE_BEFORE,
    D3DRMCOMBINE_AFTER
} D3DRMCOMBINETYPE;
Values
D3DRMCOMBINE_REPLACE
Supplied matrix replaces the frame's current matrix.
D3DRMCOMBINE_BEFORE
Supplied matrix is multiplied with the frame's current matrix and precedes the current matrix in the calculation.
D3DRMCOMBINE_AFTER
Supplied matrix is multiplied with the frame's current matrix and follows the current matrix in the calculation.
Remarks

The order of the supplied and current matrices when they are multiplied is important because matrix multiplication is not commutative.

See Also

IDirect3DRMFrame::AddRotation, IDirect3DRMFrame::AddScale, IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::AddTranslation

D3DRMFILLMODE

Used to define the D3DRMRENDERQUALITY type.

typedef enum _D3DRMFILLMODE {
    D3DRMFILL_POINTS    = 0 * D3DRMLIGHT_MAX,
    D3DRMFILL_WIREFRAME = 1 * D3DRMLIGHT_MAX,
    D3DRMFILL_SOLID     = 2 * D3DRMLIGHT_MAX,
    D3DRMFILL_MASK      = 7 * D3DRMLIGHT_MAX,
    D3DRMFILL_MAX       = 8 * D3DRMLIGHT_MAX
} D3DRMFILLMODE;
Values
D3DRMFILL_POINTS
Fills points only; minimum fill mode.
D3DRMFILL_WIREFRAME
Fill wire frames.
D3DRMFILL_SOLID
Fill solid objects.
D3DRMFILL_MASK
Fill using a mask.
D3DRMFILL_MAX
Maximum value for fill mode.
See Also

D3DRMLIGHTMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY

D3DRMFOGMODE

Contains values that specify how rapidly and in what ways the fog effect intensifies with increasing distance from the camera.

In monochromatic (ramp) lighting mode, fog works properly only when the fog color is black. (If there is no lighting, any fog color will work, since in this case any fog color is effectively black.)

typedef enum _D3DRMFOGMODE{
    D3DRMFOG_LINEAR,
    D3DRMFOG_EXPONENTIAL,
    D3DRMFOG_EXPONENTIALSQUARED
} D3DRMFOGMODE;
Values
D3DRMFOG_LINEAR
Fog effect intensifies linearly between the start and end points, according to the following formula:

Equation showing linear increase of fog effect with distance

This is the only fog mode currently supported.

D3DRMFOG_EXPONENTIAL
Fog effect intensifies exponentially, according to the following formula:

Equation showing exponential increase of fog effect with distance

D3DRMFOG_EXPONENTIALSQUARED
Fog effect intensifies exponentially with the square of the distance, according to the following formula:

Equation showing exponential increase of fog effect with distance squared

Remarks

Note that fog can be considered a measure of visibility—the lower the fog value produced by one of the fog equations, the less visible an object is.

You can specify the fog's density and start and end points by using the IDirect3DRMFrame::SetSceneFogParams method. In the formulas for the exponential fog modes, e is the base of the natural logarithms; its value is approximately 2.71828.

See Also

IDirect3DRMFrame::SetSceneFogMode, IDirect3DRMFrame::SetSceneFogParams

D3DRMFRAMECONSTRAINT

Describes the axes of rotation to constrain when viewing a Direct3DRMFrame object. The IDirect3DRMFrame::LookAt method uses this enumerated type.

typedef enum _D3DRMFRAMECONSTRAINT {
    D3DRMCONSTRAIN_Z,
    D3DRMCONSTRAIN_Y,
    D3DRMCONSTRAIN_X
} D3DRMFRAMECONSTRAINT;
Values
D3DRMCONSTRAIN_Z
Use only x- and y- rotations.
D3DRMCONSTRAIN_Y
Use only x- and z- rotations.
D3DRMCONSTRAIN_X
Use only y- and z- rotations.
See Also

IDirect3DRMFrame::LookAt

D3DRMLIGHTMODE

Used to define the D3DRMRENDERQUALITY type.

typedef enum _D3DRMLIGHTMODE {
    D3DRMLIGHT_OFF      = 0 * D3DRMSHADE_MAX,
    D3DRMLIGHT_ON       = 1 * D3DRMSHADE_MAX,
    D3DRMLIGHT_MASK     = 7 * D3DRMSHADE_MAX,
    D3DRMLIGHT_MAX      = 8 * D3DRMSHADE_MAX
} D3DRMLIGHTMODE;
Values
D3DRMLIGHT_OFF
Lighting is off.
D3DRMLIGHT_ON
Lighting is on.
D3DRMLIGHT_MASK
Lighting uses a mask.
D3DRMLIGHT_MAX
Maximum lighting mode.
See Also

D3DRMFILLMODE, D3DRMSHADEMODE, D3DRMRENDERQUALITY

D3DRMLIGHTTYPE

Defines the light type in uses to the IDirect3DRM::CreateLight method.

typedef enum _D3DRMLIGHTTYPE{
    D3DRMLIGHT_AMBIENT,
    D3DRMLIGHT_POINT,
    D3DRMLIGHT_SPOT,
    D3DRMLIGHT_DIRECTIONAL,
    D3DRMLIGHT_PARALLELPOINT
} D3DRMLIGHTTYPE;
Values
D3DRMLIGHT_AMBIENT
Light is an ambient source.
D3DRMLIGHT_POINT
Light is a point source.
D3DRMLIGHT_SPOT
Light is a spotlight source.
D3DRMLIGHT_DIRECTIONAL
Light is a directional source.
D3DRMLIGHT_PARALLELPOINT
Light is a parallel point source.

D3DRMMATERIALMODE

Describes the source of material information for visuals rendered with a frame.

typedef enum _D3DRMMATERIALMODE{
    D3DRMMATERIAL_FROMMESH,
    D3DRMMATERIAL_FROMPARENT,
    D3DRMMATERIAL_FROMFRAME
} D3DRMMATERIALMODE;
Values
D3DRMMATERIAL_FROMMESH
Material information is retrieved from the visual object (the mesh) itself. This is the default setting.
D3DRMMATERIAL_FROMPARENT
Material information, along with color or texture information, is inherited from the parent frame.
D3DRMMATERIAL_FROMFRAME
Material information is retrieved from the frame, overriding any previous material information that the visual object may have possessed.
See Also

IDirect3DRMFrame::GetMaterialMode, IDirect3DRMFrame::SetMaterialMode

D3DRMPALETTEFLAGS

Used to define how a color can be used in the D3DRMPALETTEENTRY structure.

typedef enum _D3DRMPALETTEFLAGS {
    D3DRMPALETTE_FREE,
    D3DRMPALETTE_READONLY,
    D3DRMPALETTE_RESERVED
} D3DRMPALETTEFLAGS;
Values
D3DRMPALETTE_FREE
Renderer can use this entry freely.
D3DRMPALETTE_READONLY
Fixed but can be used by renderer.
D3DRMPALETTE_RESERVED
Cannot be used by renderer.
See Also

D3DRMPALETTEENTRY

D3DRMPROJECTIONTYPE

Defines the type of projection used in a Direct3DRMViewport object. The IDirect3DRMViewport::GetProjection and IDirect3DRMViewport::SetProjection methods use this enumerated type. The right-hand types enable right-handed projection.

The axes of the camera (see IDirect3DRMFrame2::SetAxes) are used in both left-handed and right-handed projection to determine what direction the camera is facing.

typedef enum _D3DRMPROJECTIONTYPE{
    D3DRMPROJECT_PERSPECTIVE,
    D3DRMPROJECT_ORTHOGRAPHIC,
    D3DRMPROJECT_RIGHTHANDPERSPECTIVE,
    D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
} D3DRMPROJECTIONTYPE;
Values
D3DRMPROJECT_PERSPECTIVE
Projection is perspective and left-handed.
D3DRMPROJECT_ORTHOGRAPHIC
Projection is orthographic and left-handed.
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
Projection is perspective and right-handed.
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
Projection is orthographic and right-handed.
See Also

IDirect3DRMViewport::GetProjection, IDirect3DRMViewport::SetProjection

D3DRMRENDERQUALITY

Combines descriptions of the shading mode, lighting mode, and filling mode for a Direct3DRMMesh object.

typedef enum _D3DRMSHADEMODE {
    D3DRMSHADE_FLAT        = 0,
    D3DRMSHADE_GOURAUD     = 1,
    D3DRMSHADE_PHONG       = 2,
    D3DRMSHADE_MASK        = 7,
    D3DRMSHADE_MAX         = 8
} D3DRMSHADEMODE;
typedef enum _D3DRMLIGHTMODE {
    D3DRMLIGHT_OFF          = 0 * D3DRMSHADE_MAX,
    D3DRMLIGHT_ON           = 1 * D3DRMSHADE_MAX,
    D3DRMLIGHT_MASK         = 7 * D3DRMSHADE_MAX,
    D3DRMLIGHT_MAX          = 8 * D3DRMSHADE_MAX
} D3DRMLIGHTMODE;
typedef enum _D3DRMFILLMODE {
    D3DRMFILL_POINTS        = 0 * D3DRMLIGHT_MAX,
    D3DRMFILL_WIREFRAME     = 1 * D3DRMLIGHT_MAX,
    D3DRMFILL_SOLID         = 2 * D3DRMLIGHT_MAX,
    D3DRMFILL_MASK          = 7 * D3DRMLIGHT_MAX,
    D3DRMFILL_MAX           = 8 * D3DRMLIGHT_MAX
} D3DRMFILLMODE;

typedef DWORD D3DRMRENDERQUALITY;

#define D3DRMRENDER_WIREFRAME   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_WIREFRAME)
#define D3DRMRENDER_UNLITFLAT   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_SOLID)
#define D3DRMRENDER_FLAT        (D3DRMSHADE_FLAT+D3DRMLIGHT_ON+D3DRMFILL_SOLID)
#define D3DRMRENDER_GOURAUD     (D3DRMSHADE_GOURAUD+D3DRMLIGHT_ON+D3DRMFILL_SOLID)
#define D3DRMRENDER_PHONG       (D3DRMSHADE_PHONG+D3DRMLIGHT_ON+D3DRMFILL_SOLID)
Values
D3DRMSHADEMODE, D3DRMLIGHTMODE, and D3DRMFILLMODE
These enumerated types describe the shade, light, and fill modes for Direct3DRMMesh objects.

D3DRMRENDER_WIREFRAME
Display only the edges.
D3DRMRENDER_UNLITFLAT
Flat shaded without lighting.
D3DRMRENDER_FLAT
Flat shaded.
D3DRMRENDER_GOURAUD
Gouraud shaded.
D3DRMRENDER_PHONG
Phong shaded. Phong shading is not currently supported.
See Also

IDirect3DRMMesh::GetGroupQuality, IDirect3DRMMesh::SetGroupQuality,IDirect3DRMDevice2::SetRenderMode

D3DRMSHADEMODE

Used to define the D3DRMRENDERQUALITY type.

typedef enum _D3DRMSHADEMODE {
    D3DRMSHADE_FLAT     = 0,
    D3DRMSHADE_GOURAUD  = 1,
    D3DRMSHADE_PHONG    = 2,
    D3DRMSHADE_MASK     = 7,
    D3DRMSHADE_MAX      = 8
} D3DRMSHADEMODE;
See Also

D3DRMFILLMODE, D3DRMLIGHTMODE, D3DRMRENDERQUALITY

D3DRMSORTMODE

Describes how child frames are sorted in a scene.

typedef enum _D3DRMSORTMODE {
    D3DRMSORT_FROMPARENT,
    D3DRMSORT_NONE,
    D3DRMSORT_FRONTTOBACK,
    D3DRMSORT_BACKTOFRONT
} D3DRMSORTMODE;
Values
D3DRMSORT_FROMPARENT
Child frames inherit the sorting order of their parents. This is the default setting.
D3DRMSORT_NONE
Child frames are not sorted.
D3DRMSORT_FRONTTOBACK
Child frames are sorted front-to-back.
D3DRMSORT_BACKTOFRONT
Child frames are sorted back-to-front.
See Also

IDirect3DRMFrame::GetSortMode, IDirect3DRMFrame::SetSortMode

D3DRMTEXTUREQUALITY

Describes how a device interpolates between pixels in a texture and pixels in a viewport. This enumerated type is used by the IDirect3DRMDevice::SetTextureQuality and IDirect3DRMDevice::GetTextureQuality methods.

typedef enum _D3DRMTEXTUREQUALITY{
    D3DRMTEXTURE_NEAREST,
    D3DRMTEXTURE_LINEAR,
    D3DRMTEXTURE_MIPNEAREST,
    D3DRMTEXTURE_MIPLINEAR,
    D3DRMTEXTURE_LINEARMIPNEAREST,
    D3DRMTEXTURE_LINEARMIPLINEAR
} D3DRMTEXTUREQUALITY;
Values
D3DRMTEXTURE_NEAREST
Choose the nearest pixel in the texture. Does not support mipmapping.
D3DRMTEXTURE_LINEAR
Linearly interpolate the four nearest pixels. Does not support mipmapping.
D3DRMTEXTURE_MIPNEAREST
Similar to D3DRMTEXTURE_NEAREST, but uses the appropriate mipmap instead of the texture. Pixel sampling and mipmapping are both nearest.
D3DRMTEXTURE_MIPLINEAR
Similar to D3DRMTEXTURE_LINEAR, but uses the appropriate mipmap instead of the texture. Pixel sampling is linear; mipmapping is nearest.
D3DRMTEXTURE_LINEARMIPNEAREST
Similar to D3DRMTEXTURE_MIPNEAREST, but interpolates between the two nearest mipmaps. Pixel sampling is nearest; mipmapping is linear.
D3DRMTEXTURE_LINEARMIPLINEAR
Similar to D3DRMTEXTURE_MIPLINEAR, but interpolates between the two nearest mipmaps. Both pixel sampling and mipmapping are linear.

D3DRMUSERVISUALREASON

Defines the reason the system has used the D3DRMUSERVISUALCALLBACK callback function.

typedef enum _D3DRMUSERVISUALREASON {
    D3DRMUSERVISUAL_CANSEE,
    D3DRMUSERVISUAL_RENDER
} D3DRMUSERVISUALREASON;
Values
D3DRMUSERVISUAL_CANSEE
Callback function should return TRUE if the user-visual object is visible in the viewport.
D3DRMUSERVISUAL_RENDER
Callback function should render the user-visual object.
See Also

D3DRMUSERVISUALCALLBACK

D3DRMWRAPTYPE

Defines the type of Direct3DRMWrap object created by the IDirect3DRM::CreateWrap method. You can also use this enumerated type to initialize a Direct3DRMWrap object in a call to the IDirect3DRMWrap::Init method.

typedef enum _D3DRMWRAPTYPE{
    D3DRMWRAP_FLAT,
    D3DRMWRAP_CYLINDER,
    D3DRMWRAP_SPHERE,
    D3DRMWRAP_CHROME
} D3DRMWRAPTYPE;
Values
D3DRMWRAP_FLAT
Wrap is flat.
D3DRMWRAP_CYLINDER
Wrap is cylindrical.
D3DRMWRAP_SPHERE
Wrap is spherical.
D3DRMWRAP_CHROME
Wrap allocates texture coordinates so that the texture appears to be reflected onto the objects.
See Also

IDirect3DRM::CreateWrap, IDirect3DRMWrap::Init, IDirect3DRMWrap Interface

D3DRMXOFFORMAT

Defines the file type used by the IDirect3DRMMeshBuilder::Save method.

typedef enum _D3DRMXOFFORMAT{
    D3DRMXOF_BINARY,
    D3DRMXOF_COMPRESSED,
    D3DRMXOF_TEXT
} D3DRMXOFFORMAT;
Values
D3DRMXOF_BINARY
File is in binary format. This is the default setting.
D3DRMXOF_COMPRESSED
Not currently supported.
D3DRMXOF_TEXT
File is in text format.
Remarks

The D3DRMXOF_BINARY and D3DRMXOF_TEXT settings are mutually exclusive.

See Also

IDirect3DRMMeshBuilder::Save

D3DRMZBUFFERMODE

Describes whether z-buffering is enabled.

typedef enum _D3DRMZBUFFERMODE {
    D3DRMZBUFFER_FROMPARENT,
    D3DRMZBUFFER_ENABLE,
    D3DRMZBUFFER_DISABLE
} D3DRMZBUFFERMODE;
Values
D3DRMZBUFFER_FROMPARENT
The frame inherits the z-buffer setting from its parent frame. This is the default setting.
D3DRMZBUFFER_ENABLE
Z-buffering is enabled.
D3DRMZBUFFER_DISABLE
Z-buffering is disabled.
See Also

IDirect3DRMFrame::GetZbufferMode, IDirect3DRMFrame::SetZbufferMode


Other Types

Microsoft® Direct3D® Retained Mode includes other type definitions, not included in structures or enumerated types. These are:

  • D3DRMANIMATIONOPTIONS
  • D3DRMCOLORMODEL
  • D3DRMINTERPOLATIONOPTIONS
  • D3DRMLOADOPTIONS
  • D3DRMMAPPING
  • D3DRMMATRIX4D
  • D3DRMSAVEOPTIONS

D3DRMANIMATIONOPTIONS

Specifies values used by the IDirect3DRMAnimation::GetOptions and IDirect3DRMAnimation::SetOptions methods to define how animations are played.

typedef DWORD D3DRMANIMATIONOPTIONS;
#define D3DRMANIMATION_CLOSED             0x02L
#define D3DRMANIMATION_LINEARPOSITION     0x04L
#define D3DRMANIMATION_OPEN               0x01L
#define D3DRMANIMATION_POSITION           0x00000020L
#define D3DRMANIMATION_SCALEANDROTATION   0x00000010L
#define D3DRMANIMATION_SPLINEPOSITION     0x08L
Parameters
D3DRMANIMATION_CLOSED
Animation plays continually, looping back to the beginning when it reaches the end. In a closed animation, the last key in the animation should be a repeat of the first. This repeated key is used to indicate the time difference between the last and first keys in the looping animation.
D3DRMANIMATION_LINEARPOSITION
Animation's position is set linearly.
D3DRMANIMATION_OPEN
Animation plays once and stops.
D3DRMANIMATION_POSITION
Animation's position matrix should overwrite any transformation matrices that could be set by other methods.
D3DRMANIMATION_SCALEANDROTATION
Animation's scale and rotation matrix should overwrite any transformation matrices that could be set by other methods.
D3DRMANIMATION_SPLINEPOSITION
Animation's position is set using splines.

D3DRMCOLORMODEL

Describes the color model implemented by the device. For more information, see the D3DCOLORMODEL enumerated type.

typedef D3DCOLORMODEL D3DRMCOLORMODEL;
See Also

D3DCOLORMODEL

D3DRMINTERPOLATIONOPTIONS

Defines options for the IDirect3DRMInterpolator::Interpolate method. These options modify how the object is loaded.

typedef DWORD D3DRMINTERPOLATIONOPTIONS;
#define D3DRMINTERPOLATION_OPEN 0x01L
#define D3DRMINTERPOLATION_CLOSED 0x02L
#define D3DRMINTERPOLATION_NEAREST 0x0100L
#define D3DRMINTERPOLATION_LINEAR 0x04L
#define D3DRMINTERPOLATION_SPLINE 0x08L
#define D3DRMINTERPOLATION_VERTEXCOLOR 0x40L
#define D3DRMINTERPOLATION_SLERPNORMALS 0x80L
Parameters
D3DRMINTERPOLATION_OPEN
First and last keys of each key chain will fix the interpolated values outside of the index span.
D3DRMINTERPOLATION_CLOSED
The interpolation is cyclic. The keys effectively repeat infinitely with a period equal to the index span. For compatibility with animations, any key with an index equal to the end of the span is ignored.
D3DRMINTERPOLATION_NEAREST
Nearest key value is used for determining in-between values on each key chain (execution thread).
D3DRMINTERPOLATION_LINEAR
Linear interpolation between the two nearest keys is used for determining in-between values on each key chain.
D3DRMINTERPOLATION_SPLINE
B-spline blending function on the four nearest keys is used for determining in-between values on each key chain.
D3DRMINTERPOLATION_VERTEXCOLOR
Specifies that vertex colors should be interpolated. Only affects the interpolation of IDirect3DRMMesh::SetVertices.
D3DRMINTERPOLATION_SLERPNORMALS
Specifies that vertex normals should be spherically interpolated (not currently implemented). Only affects the interpolation of IDirect3DRMMesh::SetVertices.

D3DRMLOADOPTIONS

Defines options for the IDirect3DRM::Load, IDirect3DRMAnimationSet::Load, IDirect3DRMFrame::Load, IDirect3DRMMeshBuilder::Load, and IDirect3DRMProgressiveMesh::Load methods. These options modify how the object is loaded.

typedef DWORD D3DRMLOADOPTIONS;
#define D3DRMLOAD_FROMFILE             0x00L
#define D3DRMLOAD_FROMRESOURCE         0x01L
#define D3DRMLOAD_FROMMEMORY           0x02L
#define D3DRMLOAD_FROMURL              0x08L
#define D3DRMLOAD_BYNAME               0x10L
#define D3DRMLOAD_BYPOSITION           0x20L
#define D3DRMLOAD_BYGUID               0x30L
#define D3DRMLOAD_FIRST                0x40L
#define D3DRMLOAD_INSTANCEBYREFERENCE  0x100L
#define D3DRMLOAD_INSTANCEBYCOPYING    0x200L
#define D3DRMLOAD_ASYNCHRONOUS         0x400L
Parameters
Source flags
D3DRMLOAD_FROMFILE
Load from a file. This is the default setting.
D3DRMLOAD_FROMRESOURCE
Load from a resource. If this flag is specified, the lpvObjSource parameter of the calling Load method must point to a D3DRMLOADRESOURCE structure.
D3DRMLOAD_FROMMEMORY
Load from memory. If this flag is specified, the lpvObjSource parameter of the calling Load method must point to a D3DRMLOADMEMORY structure.
D3DRMLOAD_FROMURL
Load from an URL.
Identifier flags
D3DRMLOAD_BYNAME
Load any object by using a specified name.
D3DRMLOAD_BYPOSITION
Load a stand-alone object based on a given zero-based position (that is, the nth object in the file). Stand-alone objects can contain other objects, but are not contained by any other objects.
D3DRMLOAD_BYGUID
Load any object by using a specified globally unique identifier (GUID).
D3DRMLOAD_FIRST
The default setting. Load the first stand-alone object of the given type (for example, a mesh if the application uses IDirect3DRMMeshBuilder::Load). Stand-alone objects can contain other objects, but are not contained by any other objects.
Instance flags
D3DRMLOAD_INSTANCEBYREFERENCE
Check whether an object already exists with the same name as specified and, if so, use an instance of that object instead of creating a new one.
D3DRMLOAD_INSTANCEBYCOPYING
Check whether an object already exists with the same name as specified and, if so, copy that object.
Source flags
D3DRMLOAD_ASYNCHRONOUS
The Load call will return immediately. It is up to the application to use events to find out how the load is progressing. By default, loading is done synchronously, and the Load call will not return until all data has been loaded or an error occurs.
Remarks

Each of the Load methods uses an lpvObjSource parameter to specify the source of the object and an lpvObjID parameter to identify the object. The system interprets the contents of the lpvObjSource parameter based on the choice of source flags, and it interprets the contents of the lpvObjID parameter based on the choice of identifier flags.

The instance flags do not change the interpretation of any of the parameters. By using the D3DRMLOAD_INSTANCEBYREFERENCE flag, it is possible for an application to load the same file twice without creating any new objects. If an object does not have a name, setting the D3DRMLOAD_INSTANCEBYREFERENCE flag has the same effect as setting the D3DRMLOAD_INSTANCEBYCOPYING flag—the loader creates each unnamed object as a new one, even if some of the objects are identical.

D3DRMMAPPING

Specifies values used by the IDirect3DRMMesh::GetGroupMapping and IDirect3DRMMesh::SetGroupMapping methods to define how textures are mapped to a group.

typedef DWORD D3DRMMAPPING, D3DRMMAPPINGFLAG;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPU = 1;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPV = 2;
static const D3DRMMAPPINGFLAG D3DRMMAP_PERSPCORRECT = 4;
Parameters
D3DRMMAPPINGFLAG
Type equivalent to D3DRMMAPPING.
D3DRMMAP_WRAPU
Texture wraps in the u-direction.
D3DRMMAP_WRAPV
Texture wraps in the v-direction.
D3DRMMAP_PERSPCORRECT
Texture wrapping is perspective-corrected.

Remarks

The D3DRMMAP_WRAPU and D3DRMMAP_WRAPV flags determine how the rasterizer interprets texture coordinates. The rasterizer always interpolates the shortest distance between texture coordinates; that is, a line. The path taken by this line, and the valid values for the u- and v-coordinates, varies with the use of the wrapping flags. If either or both flags are set, the line can wrap around the texture edge in the u- or v- direction, as if the texture had a cylindrical or toroidal topology. For more information, see IDirect3DRMWrap Interface.

See Also

IDirect3DRMWrap Interface, IDirect3DRMMesh::GetGroupMapping, IDirect3DRMMesh::SetGroupMapping

D3DRMMATRIX4D

Expresses a transformation as an array. The organization of the matrix entries is D3DRMMATRIX4D[row][column].

typedef D3DVALUE D3DRMMATRIX4D[4][4];
See Also

IDirect3DRMFrame::AddTransform, IDirect3DRMFrame::GetTransform

D3DRMSAVEOPTIONS

Defines options for the IDirect3DRMMeshBuilder::Save method.

typedef DWORD D3DRMSAVEOPTIONS;
#define D3DRMXOFSAVE_NORMALS 1
#define D3DRMXOFSAVE_TEXTURECOORDINATES 2
#define D3DRMXOFSAVE_MATERIALS 4
#define D3DRMXOFSAVE_TEXTURENAMES 8
#define D3DRMXOFSAVE_ALL 15
#define D3DRMXOFSAVE_TEMPLATES 16
#define D3DRMSAVE_TEXTURETOPOLOGY 32
Parameters
D3DRMXOFSAVE_NORMALS
Save normal vectors in addition to the basic geometry.
D3DRMXOFSAVE_TEXTURECOORDINATES
Save texture coordinates in addition to the basic geometry.
D3DRMXOFSAVE_MATERIALS
Save materials in addition to the basic geometry.
D3DRMXOFSAVE_TEXTURENAMES
Save texture names in addition to the basic geometry.
D3DRMXOFSAVE_ALL
Save normal vectors, texture coordinates, materials, and texture names in addition to the basic geometry.
D3DRMXOFSAVE_TEMPLATES
Save templates with the file. By default, templates are not saved.
D3DRMSAVE_TEXTURETOPOLOGY
Save the mesh's face wrap values (set by IDirect3DRMMeshBuilder::SetTextureTopology or IDirect3DRMFace::SetTextureTopology). This flag is not included when you pass D3DRMXOFSAVE_ALL to the Save method. You should pass D3DRMSAVE_TEXTURETOPOLOGY|D3DRMXOFSAVE_ALL if you want to save everything. You only need to pass this flag when you have called IDirect3DRMMeshBuilder::SetTextureTopology or IDirect3DRMFace::SetTextureTopology and want to preserve the values you set.


Return Values

The methods of the Microsoft® Direct3D® Retained Model (COM) interfaces can return the following values.

D3DRM_OK
No error.
D3DRMERR_BADALLOC
Out of memory.
D3DRMERR_BADDEVICE
Device is not compatible with renderer.
D3DRMERR_BADFILE
Data file is corrupt.
D3DRMERR_BADMAJORVERSION
Bad DLL major version.
D3DRMERR_BADMINORVERSION
Bad DLL minor version.
D3DRMERR_BADOBJECT
Object expected in argument.
D3DRMERR_BADPMDATA
The data in the .x file is corrupted. The conversion to a progressive mesh succeeded but produced an invalid progressive mesh in the .x file.
D3DRMERR_BADTYPE
Bad argument type passed.
D3DRMERR_BADVALUE
Bad argument value passed.
D3DRMERR_BOXNOTSET
An attempt was made to access a bounding box (for example, with IDirect3DRMFrame2::GetBox) when no bounding box was set on the frame.
D3DRMERR_CONNECTIONLOST
Data connection was lost during a load, clone, or duplicate.
D3DRMERR_FACEUSED
Face already used in a mesh.
D3DRMERR_FILENOTFOUND
File cannot be opened.
D3DRMERR_INVALIDDATA
Method received or accessed data that is invalid.
D3DRMERR_INVALIDOBJECT
Method received a pointer to an object that is invalid.
D3DRMERR_INVALIDPARAMS
One of the parameters passed to the method is invalid.
D3DRMERR_NOTDONEYET
Unimplemented.
D3DRMERR_NOTENOUGHDATA
Not enough data has been loaded to perform the requested operation.
D3DRMERR_NOTFOUND
Object not found in specified place.
D3DRMERR_PENDING
Data required to supply the requested information has not finished loading.
D3DRMERR_REQUESTTOOLARGE
Attempt was made to set a level of detail in a progressive mesh greater than the maximum available.
D3DRMERR_REQUESTTOOSMALL
Attempt was made to set the minimum rendering detail of a progressive mesh smaller than the detail in the base mesh (the minimum for rendering).
D3DRMERR_UNABLETOEXECUTE
Unable to carry out procedure.


Further Reading

Color Keying
A color key is typically a single uncommon color that the artist does not use for anything but transparency, but it can also be a specified range of colors. Using the IDirectDrawSurface3::SetColorKey method, you can set the color key for a surface. After the color key is set, subsequent calls to IDirectDrawSurface3::BltFast take advantage of that color key, ignoring the pixels that match it. This type of color key is known as a source color key. Because the source color key prevents "transparent" pixels from being written to the destination, the original background pixels are preserved in these places, making it look like a sprite is a non-rectangular object passing over the background. You can also use a color key that effects the destination surface (a destination color key).

A destination color key is a color on a surface that is used for pixels that can be overwritten by a sprite. Again, the artist chooses an arbitrary color that is not used elsewhere in the image, reserving it as a portion of the image where you are allowed to blit. When you blit a sprite to the destination surface with a destination color key specified, the sprite's pixels will only be blitted to pixels on the destination that are using the destination color key. Because the normal destination pixels are preserved, it looks like the sprite passes behind the image on the destination surface. For more information, see "Transparent Blitting and Color Keys" in the "Sprite Concepts" topic of the "DirectDraw Getting Started: Basic Graphics Concepts" section of the DirectX Foundation SDK.

D3DCOLOR_MONO
A value of the D3DRMCOLORMODEL constant that tells the system to use a monochromatic model (or ramp model). In this model, the blue component of a vertex color is used to define the brightness of a lit vertex.
D3DCOLOR_RGB
A value of the D3DRMCOLORMODEL constant that tells the system to use a full RGB model.
D3DCOLORMODEL
A constant that defines the color model in which the system will run.

typedef enum _D3DCOLORMODEL {
    D3DCOLOR_MONO = 1,
    D3DCOLOR_RGB  = 2,
} D3DCOLORMODEL;
D3DDEVICEDESC
A structure that contains a description of the current device. For more information, see "Structures" in the DirectX Foundation Immediate Mode Reference.
D3DENUMDEVICESCALLBACK
The prototype definition for the callback function to enumerate installed Direct3D devices. For more information, see "Callback Functions" in the DirectX Foundation Immediate Mode Reference.

typedef HRESULT (FAR PASCAL * LPD3DENUMDEVICESCALLBACK)
  (LPGUID lpGuid,
  LPSTR lpDeviceDescription,
  LPSTR lpDeviceName,
  LPD3DDEVICEDESC lpD3DHWDeviceDesc,
  LPD3DDEVICEDESC lpD3DHELDeviceDesc,
  LPVOID lpUserArg
);
D3DMATRIX
A structure that describes a matrix.

typedef struct _D3DMATRIX {
    D3DVALUE _11, _12, _13, _14;
    D3DVALUE _21, _22, _23, _24;
    D3DVALUE _31, _32, _33, _34;
    D3DVALUE _41, _42, _43, _44;
} D3DMATRIX, *LPD3DMATRIX;
D3DPRIMCAPS
A structure that defines the capabilities for each primitive type. Used by IDirect3DRM::CreateDeviceFromClipper and IDirect3DRM2::CreateDeviceFromClipper to set these default capabilities:

D3DPCMPCAPS_LESSEQUAL — Pass the z-buffer comparison if the new z is less than or equal to the current z.

D3DPMISCCAPS_CULLCCW — The driver supports counterclockwise culling through the D3DRENDERSTATE_CULLMODE state. (This applies only to triangle primitives.)

D3DPRASTERCAPS_FOGVERTEX — The device calculates the fog value during the lighting operation, places the value into the alpha component of the D3DCOLOR value given for the specular member of the D3DTLVERTEX structure, and interpolates the fog value during rasterization.

D3DPSHADECAPS_ALPHAFLATSTIPPLED — The device can support an alpha component for flat blended and stippled transparency, respectively (the D3DSHADE_FLAT state for the D3DSHADEMODE enumerated type). In these modes, the alpha color component for a primitive is provided as part of the color for the first vertex of the primitive.

D3DPTADDRESSCAPS_WRAP — The device can wrap textures to addresses.

D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE — The copy texture-blending mode (D3DTBLEND_COPY from the D3DTEXTUREBLEND enumerated type) and the modulate texture-blending mode (D3DTBLEND_MODULATE from the D3DTEXTUREBLEND enumerated type) are supported.

D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY — Perspective correction and texture transparency are supported.

D3DPTFILTERCAPS_NEAREST — The texel (a single element of a texture) with coordinates nearest to the desired pixel value is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, then both must be supported.

D3DRECT
A structure that is a rectangle definition.

typedef struct _D3DRECT {
    union {
        LONG x1;
        LONG lX1;  //upper left x
    };
    union {
        LONG y1;
        LONG lY1;  //upper left y
    };
    union {
        LONG x2;
        LONG lX2; //lower right x
    };
    union {
        LONG y2;
        LONG lY2;  //lower right y
    };
} D3DRECT, *LPD3DRECT;
D3DTRIANGLE
The structure that describes the base type for all triangles. The triangle is the main rendering primitive.
D3DVALUE
The fundamental Direct3D fractional data type.

typedef float D3DVALUE, *LPD3DVALUE;
D3DVECTOR
The structure that defines a vector for many Direct3D and Direct3D Retained Mode methods and structures.

typedef struct _D3DVECTOR {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
} D3DVECTOR, *LPD3DVECTOR;
DirectDrawCreate
A function that creates an instance of a DirectDraw object. For more information, see "Functions" in the DirectX Foundation DirectDraw Reference.
DirectDrawCreateClipper
A function that creates an instance of a DirectDrawClipper object not associated with a DirectDraw object. For more information, see "Functions" in the DirectX Foundation DirectDraw Reference.
IDirect3D
Applications use the methods of the IDirect3D2 interface to create Direct3D objects and to set up the environment. For more information, see "IDirect3D2" in the "Interfaces" topic in DirectX Foundation Immediate Mode Reference.
IDirect3D::EnumDevices — This method enumerates all Direct3D device drivers installed on the system.
IDirect3D::FindDevice — This method finds a device with the specified characteristics and retrieves a description of it.
IDirectDrawClipper
Applications use the methods of the IDirectDrawClipper interface to manage clip lists. For more information, see the DirectX Foundation DirectDraw Reference.
IDirectDrawClipper::SetHWnd — This method sets the window handle that will obtain the clipping information.
IUnknown Interface
All Component Object Model (COM) interfaces are derived from the IUnknown interface. This interface provides control of the object's lifetime and the ability to navigate multiple interfaces. IUnknown has three methods: AddRef, which increments the object's reference count by 1 when an interface or another application binds itself to the object; QueryInterface, which queries the object about the features it supports by requesting pointers to a specific interface; Release, which decrements the object's reference count by 1. When the count reaches 0, the object is deallocated.

IUnknown::AddRef and IUnknown::Release — These IUnknown methods maintain an object's reference count. For example, if you create a DirectPlay object (with CoCreateInstance, for example), the object's reference count is set to 1. Every time a function returns a pointer to an interface for that object, the function must call AddRef through that pointer to increment the reference count. You must match each AddRef call with a call to Release. Before the pointer can be destroyed, you must call Release through that pointer. After an object's reference count reaches 0, the object is destroyed and all interfaces to it become invalid.
IUnknown::QueryInterface — This IUnknown method determines whether an object supports a specific interface. If an object supports the interface, QueryInterface returns a pointer to that interface. You then can use the methods contained in that interface to communicate with the object. If QueryInterface successfully returns a pointer to an interface, it implicitly calls AddRef to increment the reference count, so your application must call Release to decrement the reference count before destroying the pointer to the interface.
Mipmaps
A mipmap is a sequence of textures, each of which is a progressively lower resolution, prefiltered representation of the same image. Each prefiltered image, or level, in the mipmap is a power of two smaller than the previous level. A high-resolution level is used for objects that are close to the viewer. Lower-resolution levels are used as the object moves farther away. Mipmapping is a computationally low-cost way of improving the quality of rendered textures. For more information, see "Mipmaps" in the "Textures" topic in the "Direct3D Immediate-Mode Essentials" section of the DirectX Foundation SDK.
Texture Map Formats
A wide range of texture pixel formats are supported by the Microsoft® DirectX® hardware-emulation layer. The table in "Texture Map Formats" in the "Pixel Format Masks" topic in the DirectX Foundation DirectDraw Reference shows these formats.


DirectX File Format

This document specifies the file format introduced with Microsoft® DirectX® 2. A binary version of this format was subsequently released with DirectX 3, which is also detailed in this reference.

The DirectX file format provides a rich template-driven file format that enables the storage of meshes, textures, animations, and user-definable objects. Support for animation sets allows predefined paths to be stored for playback in real time. Instancing and hierarchies are also supported. Instancing allows multiple references to an object, such as a mesh, while storing its data only once per file. Hierarchies are used to express relationships between data records. The DirectX file format is used natively by the Microsoft® Direct3D® Retained Mode API, providing support for reading predefined objects into an application or writing mesh information constructed by the application in real time.

The DirectX file format provides low-level data primitives, upon which applications define higher-level primitives through templates. This is the method by which Direct3D defines higher-level primitives such as vectors, meshes, matrices and colors.

This document details the API-independent features of the file format and also the method by which Direct3D Retained Mode uses the file format. It includes the following topics:

  • DirectX File Format Architecture
  • Appendix A: Templates
  • Appendix B: Example
  • Appendix C: Binary Format
  • Appendix D: The Conv3ds.exe Utility


DirectX File Format Architecture

The Microsoft® DirectX® file format is an architecture- and context-free file format. It is template driven and is free of any usage knowledge. The file format may be used by any client application and currently is used by Microsoft® Direct3D® Retained Mode to describe geometry data, frame hierarchies and animations.

The rest of this section will deal with the content and syntax of the file format. The file format uses the extension .x when used with the DirectX Software Development Kit.

Reserved Words

The following words are reserved and must not be used:

  • ARRAY
  • BYTE
  • CHAR
  • CSTRING
  • DOUBLE
  • DWORD
  • FLOAT
  • STRING
  • TEMPLATE
  • UCHAR
  • UNICODE
  • WORD

Header

The variable length header is compulsory and must be at the beginning of the data stream. The header contains the following:

Type | Sub Type | Size | Contents | Content Meaning
Magic Number (required) | 4 bytes | "xof "
Version Number (required) | Major Number | 2 bytes | 03 | Major version 3
Minor Number | 2 bytes | 02 | Minor version 2
Format Type (required) | 4 bytes | "txt " | Text File
"bin " | Binary File
"com " | Compressed File
Compression Type (required | 4 bytes | "lzw "
if format type is compressed) | "zip "
etc...
Float size (required) | 4 bytes | 0064 | 64 bit floats
0032 | 32 bit floats

Example

xof 0302txt 0064

Comments

Comments are only applicable in text files. Comments can occur anywhere in the data stream. A comment begins with either C++ style double-slashes "//", or a number sign "#". The comment runs to the next new line.

# This is a comment.
// This is another comment.

Templates

Templates define how the data stream is interpreted—the data is modulated by the template definition. A template has the following form:

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

This section discusses the following parts of a template:

  • Template name
  • UUID
  • Members
  • Restrictions

Example templates are presented in Examples.

Template name

This is an alphanumeric name that may include the underscore character "_". It must not begin with a digit.

UUID

A universally unique identifier formatted to the Open Software Foundation's Distributed Distributed Computing Environment standard and surrounded by angle brackets "<" and ">". For example: <3D82AB43-62DA-11cf-AB39-0020AF71E433>

Members

Template members consist of a named data type followed by an optional name or an array of a named data type. Valid primitive data types are:

Type | Size
WORD | 16 bits
DWORD | 32 bits
FLOAT | IEEE float
DOUBLE | 64 bits
CHAR | 8 bits
UCHAR | 8 bits
BYTE | 8 bits
STRING | NULL terminated string
CSTRING | Formatted C-string (currently unsupported)
UNICODE | UNICODE string (currently unsupported)

Additional data types defined by templates encountered earlier in the data stream can also be referenced within a template definition. No forward references are allowed.

Any valid data type can be expressed as an array in the template definition. The basic syntax is as follows:

array <data-type> <name>[<dimension-size>];

Where <dimension-size> can either be an integer or a named reference to another template member whose value is then substituted.

Arrays may be n-dimensional, where n is determined by the number of paired square brackets trailing the statement. For example:

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];

Restrictions

Templates may be open, closed, or restricted. These restrictions determine which data types may appear in the immediate hierarchy of a data object defined by the template. An open template has no restrictions, a closed template rejects all data types, and a restricted template allows a named list of data types. The syntax is as follows:

Three periods enclosed by square brackets indicate an open template.

[ ((( ]

A comma-separated list of named data types followed optionally by their UUIDs enclosed by square brackets indicates a restricted template.

[ { data-type [ UUID ] , }... ]

The absence of either of the above indicates a closed template.

Examples

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // An open template
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // A closed template
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // A restricted template
}

There is one special template—the Header template. It is recommended that each application define such a template, and use it to define application-specific information, such as version information. If present, this header will be read by the DirectX file format API, and if a flags member is available, it will be used to determine how the following data is interpreted. The flags member, if defined, should be a DWORD. One bit is currently defined—bit 0. If this bit is clear, the following data in the file is binary. If set, the following data is text. Multiple header data objects can be used to switch between binary and text within the file.

Data

Data objects contain the actual data or a reference to that data. Each has a corresponding template that specifies the data type.

Data objects have the following form:

<Identifier> [name] {
<member 1>;
...
<member n>;
}

This section discusses the following parts of data objects:

  • Identifier
  • Name
  • Members

Example templates are presented in Examples.

Identifier

This part is compulsory and must match a previously defined data type or primitive.

Name

This part is optional. (See earlier for the syntax definition.)

Members

Data members can be one of the following: data object, data reference, integer list, float list, or string list.

Data object

A nested data object. This allows the hierarchical nature of the file format to be expressed. The types of nested data objects allowed in the hierarchy may be restricted. See Templates earlier.

Data reference

A reference to a previously encountered data object. The syntax is as follows:

{ name }

Integer list

A semicolon-separated list of integers. For example:

1; 2; 3;

Float list

A semicolon-separated list of floats. For example:

1.0; 2.0; 3.0;

String List

A semicolon-separated list of strings. For example:

"Moose"; "Goats"; "Sheep";

Use of Commas and Semicolons

This is perhaps the most complex syntax issue in the file format, and it is very strict: Commas are used to separate array members; semicolons terminate every data item.

For example, if we have a template defined as:

template mytemp {
DWORD myvar;
}

Then an instance of this would look like:

mytemp dataTemp {
1;
}

Next, we have a template containing another template:

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

Then an instance of this would look like:

container dataContainer {
1.1;
2; 3;;
}

Note that the second line that represents the mytemp inside container has two semicolons at the end of the line. The first indicates the end of the data item aTemp (inside container), and the second indicates the end of the container.

Next consider arrays.

Template mytemp {
array DWORD myvar[3];
}

Then an instance of this would look like:

mytemp aTemp {
1, 2, 3;
}

In the array case, there is no need for the data items to be separated by a semicolon because they are delineated by a comma. The semicolon at the end marks the end of the array.

Now consider a template that contains an array of data items defined by a template.

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

Then an instance of this would look like:

container aContainer {
3;
1;2;,3;4;,5;6;;
}


Appendix A: Templates

This appendix lists the templates used by Microsoft® Direct3D® Retained Mode. A familiarity with Direct3D Retained Mode data types is assumed.

  • Template Name: Header
  • Template Name: Vector
  • Template Name: Coords2d
  • Template Name: Quaternion
  • Template Name: Matrix4x4
  • Template Name: ColorRGBA
  • Template Name: ColorRGB
  • Template Name: Indexed Color
  • Template Name: Boolean
  • Template Name: Boolean2d
  • Template Name: Material
  • Template Name: TextureFilename
  • Template Name: MeshFace
  • Template Name: MeshFaceWraps
  • Template Name: MeshTextureCoords
  • Template Name: MeshNormals
  • Template Name: MeshVertexColors
  • Template Name: MeshMaterialList
  • Template Name: Mesh
  • Template Name: FrameTransformMatrix
  • Template Name: Frame
  • Template Name: FloatKeys
  • Template Name: TimedFloatKeys
  • Template Name: AnimationKey
  • Template Name: AnimationOptions
  • Template Name: Animation
  • Template Name: AnimationSet

Template Name: Header

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
major | WORD | None
minor | WORD
flags | DWORD

Description

This template defines the application-specific header for the Direct3D Retained Mode usage of the DirectX file format. The Retained Mode uses the major and minor flags to specify the current major and minor versions for the Retained Mode file format.

Template Name: Vector

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
x | FLOAT | None
y | FLOAT
z | FLOAT

Description

This template defines a vector.

Template Name: Coords2d

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
u | FLOAT | None
v | FLOAT

Description

A two dimensional vector used to define a mesh's texture coordinates.

Template Name: Quaternion

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
s | FLOAT | None
v | Vector

Description

Currently unused.

Template Name: Matrix4x4

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
matrix | array FLOAT | 16 | None

Description

This template defines a 4×4 matrix. This is used as a frame transformation matrix.

Template Name: ColorRGBA

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
red | FLOAT | None
green | FLOAT
blue | FLOAT
alpha | FLOAT

Description

This template defines a color object with an alpha component. This is used for the face color in the material template definition.

Template Name: ColorRGB

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
red | FLOAT | None
green | FLOAT
blue | FLOAT

Description

This template defines the basic RGB color object.

Template Name: Indexed Color

UUID

<1630B820-7842-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size
index | DWORD
ColorRGBA | indexColor

Description

This template consists of an index parameter and an RGBA color and is used for defining mesh vertex colors. The index defines the vertex to which the color is applied.

Template Name: Boolean

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
WORD | truefalse | None

Description

Defines a simple Boolean type. This template should be set to 0 or 1.

Template Name: Boolean2d

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
u | Boolean | None
v | Boolean

Description

This template defines a set of two Boolean values used in the MeshFaceWraps template to define the texture topology of an individual face.

Template Name: Material

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
faceColor | ColorRGBA | Any
power | FLOAT
specularColor | ColorRGB
emissiveColor | ColorRGB

Description

This template defines a basic material color that can be applied to either a complete mesh or a mesh's individual faces. The power is the specular exponent of the material. Note that the ambient color requires an alpha component.

TextureFilename is an optional data object used by Direct3D Retained Mode. If this is not present, the face is untextured.

Template Name: TextureFilename

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
filename | STRING | None

Description

This template allows you to specify the file name of a texture to apply to a mesh or a face. This should appear within a material object.

Template Name: MeshFace

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
nFaceVertexIndices | DWORD | None
faceVertexIndices | array DWORD | nFaceVertexIndicies

Description

This template is used by the Mesh template to define a mesh's faces. Each element of the nFaceVertexIndices array references a mesh vertex used to build the face.

Template Name: MeshFaceWraps

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nFaceWrapValues | DWORD | None
faceWrapValues | Boolean2d

Description

This template is used to define the texture topology of each face in a wrap. The value of the nFaceWrapValues member should be equal to the number of faces in a mesh.

Template Name: MeshTextureCoords

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nTextureCoords | DWORD | None
textureCoords | array Coords2d | nTextureCoords

Description

This template defines a mesh's texture coordinates.

Template Name: MeshNormals

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nNormals | DWORD | None
normals | array Vector | nNormals
nFaceNormals | DWORD
faceNormals | array MeshFace | nFaceNormals

Description

This template defines normals for a mesh. The first array of vectors is the normal vectors themselves, and the second array is an array of indexes specifying which normals should be applied to a given face. The value of the nFaceNormals member should be equal to the number of faces in a mesh.

Template Name: MeshVertexColors

UUID

<1630B821-7842-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nVertexColors | DWORD | None
vertexColors | array IndexedColor | nVertexColors

Description

This template specifies vertex colors for a mesh, instead of applying a material per face or per mesh.

Template Name: MeshMaterialList

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nMaterials | DWORD | Material
nFaceIndexes | DWORD
FaceIndexes | array DWORD | nFaceIndexes

Description

This template is used in a mesh object to specify which material applies to which faces. The nMaterials member specifies how many materials are present, and materials specify which material to apply.

Template Name: Mesh

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
nVertices | DWORD | Any
vertices | array Vector | nVertices
nFaces | DWORD
faces | array MeshFace | nFaces

Description

This template defines a simple mesh. The first array is a list of vertices, and the second array defines the faces of the mesh by indexing into the vertex array.

Optional Data Elements

The following optional data elements are used by Direct3D Retained Mode.

MeshFaceWraps | If this is not present, wrapping for both u and v defaults to false.
MeshTextureCoords | If this is not present, there are no texture coordinates.
MeshNormals | If this is not present, normals are generated using the GenerateNormals method of the API.
MeshVertexColors | If this is not present, the colors default to white.
MeshMaterialList | If this is not present, the material defaults to white.

Template Name: FrameTransformMatrix

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
frameMatrix | Matrix4x4 | None

Description

This template defines a local transform for a frame (and all its child objects).

Template Name: Frame

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
None | Any

Description

This template defines a frame. Currently, the frame can contain objects of the type Mesh and a FrameTransformMatrix.

Optional Data Elements

The following optional data elements are used by Direct3D Retained Mode.

FrameTransformMatrix | If this is not present, no local transform is applied to the frame.
Mesh | Any number of mesh objects that become children of the frame. These objects can be specified inline or by reference.

Template Name: FloatKeys

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
nValues | DWORD | None
values | array FLOAT | nValues

Description

This template defines an array of floats and the number of floats in that array. This is used for defining sets of animation keys.

Template Name: TimedFloatKeys

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
time | DWORD | None
tfkeys | FloatKeys

Description

This template defines a set of floats and a positive time used in animations.

Template Name: AnimationKey

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
keyType | DWORD | None
nKeys | DWORD
keys | array TimedFloatKeys | nKeys

Description

This template defines a set of animation keys. The keyType member specifies whether the keys are rotation, scale or position keys (using the integers 0, 1, or 2 respectively).

Template Name: AnimationOptions

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>
Member Name | Type | Optional Array Size | Optional Data Objects
openclosed | DWORD | None
positionquality | DWORD

Description

This template allows you to set the Direct3D Retained Mode Animation options. The openclosed parameter can be either 0 for a closed or 1 for an open animation. The positionquality parameter is used to set the position quality for any position keys specified and can either be 0 for spline positions or 1 for linear positions. By default, an animation is open and uses linear position keys.

Template Name: Animation

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
None | Any

Description

This template contains animations referencing a previous frame. It should contain one reference to a frame and at least one set of AnimationKeys. It also can contain an AnimationOptions data object.

Optional Data Elements

The following optional data elements are used by Direct3D Retained Mode.
AnimationKey | An animation is meaningless without AnimationKeys.
AnimationOptions | If this element is not present, an animation is closed.

Template Name: AnimationSet

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>
Member Name | Type | Optional Array Size | Optional Data Objects
none | Animation

Description

An AnimationSet contains one or more Animation objects and is the equivalent to the Direct3D Retained Mode concept of animation sets. This means each animation within an animation set has the same time at any given point. Increasing the animation set's time will increase the time for all the animations it contains.


Appendix B: Example

This appendix describes a simple cube and then shows how to add textures, frames, and animations to it.

  • A Simple Cube
  • Adding Textures
  • Frames and Animations

A Simple Cube

This file defines a simple cube that has four red sides and two green sides. Notice in this file that optional information is being used to add information to the data object defined by the Mesh template.

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 1.0, G = 0.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
// Define a mesh with 8 vertices and 12 faces (triangles). Use
// optional data objects in the mesh to specify materials, normals,
// and texture coordinates.
Mesh CubeMesh {
8;                                // 8 vertices
1.000000;1.000000;-1.000000;,     // vertex 0
-1.000000;1.000000;-1.000000;,    // vertex 1
-1.000000;1.000000;1.000000;,     // etc...
1.000000;1.000000;1.000000;,
1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;1.000000;,
1.000000;-1.000000;1.000000;;

12;                      // 12 faces
3;0,1,2;,                // face 0 has 3 vertices
3;0,2,3;,                // etc...
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;

// All required data has been defined. Now define optional data
// using the hierarchical nature of the file format.
MeshMaterialList {
2;                    // Number of materials used
12;                   // A material for each face
0,                    // face 0 uses the first
0,                    // material
0,
0,
0,
0,
0,
0,
1,                    // face 8 uses the second
1,                    // material
1,
1;;
{RedMaterial}         // References to the definitions
{GreenMaterial}       // of material 0 and 1
}
MeshNormals {
8;                    // define 8 normals
0.333333;0.666667;-0.666667;,
-0.816497;0.408248;-0.408248;,
-0.333333;0.666667;0.666667;,
0.816497;0.408248;0.408248;,
0.666667;-0.666667;-0.333333;,
-0.408248;-0.408248;-0.816497;,
-0.666667;-0.666667;0.333333;,
0.408248;-0.408248;0.816497;;
12;                   // For the 12 faces,
3;0,1,2;,             // define the normals
3;0,2,3;,
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;
}
MeshTextureCoords {
8;                        // Define texture coords
0.000000;1.000000;        // for each of the vertices
1.000000;1.000000;
0.000000;1.000000;
1.000000;1.000000;
0.000000;0.000000;
1.000000;0.000000;
0.000000;0.000000;
1.000000;0.000000;;
}
}

Adding Textures

To add textures, use the hierarchical nature of the file format and add an optional TextureFilename data object to the Material data objects. So, the Material objects now read as follows:

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 1.0, G = 0.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"tex1.ppm";
}
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"win95.ppm";
}
}

Frames and Animations

This section shows how to add frames and animations to a simple cube.

  • Frames
  • AnimationSets and Animations

Frames

A frame is expected to take the following structure:

Frame Aframe {        // The frame name is chosen for convenience.
FrameTransformMatrix {
...transform data...
}
[ Meshes ] and/or [ More frames]
}

Place the previously defined cube mesh inside a frame with an identity transform. Then apply an animation to this frame.

Frame CubeFrame {
FrameTransformMatrix {
1.000000, 0.000000, 0.000000, 0.000000,
0.000000, 1.000000, 0.000000, 0.000000,
0.000000, 0.000000, 1.000000, 0.000000,
0.000000, 0.000000, 0.000000, 1.000000;;
}
{CubeMesh}        // You could have the mesh inline, but this                  // uses an object reference instead.
}

AnimationSets and Animations

Animations and AnimationSets in the DirectX file format map directly to the Direct3D Retained Mode animation concepts.

Animation Animation0 {        // The name is chosen for convenience.
{ Frame that it applies to&em;normally a reference }
AnimationKey {
...animation key data...
}
{ ...more animation keys... }
}

Animations are then grouped into AnimationSets:
AnimationSet AnimationSet0 { // The name is chosen for convenience.
{ an animation—could be inline or a reference }
{ ... more animations ... }
}

Now take the cube through an animation.

AnimationSet AnimationSet0 {
Animation Animation0 {
{CubeFrame}    // Use the frame containing the cube
AnimationKey {
2;             // Position keys
9;             // 9 keys
10; 3; -100.000000, 0.000000, 0.000000;;,
20; 3; -75.000000, 0.000000, 0.000000;;,
30; 3; -50.000000, 0.000000, 0.000000;;,
40; 3; -25.500000, 0.000000, 0.000000;;,
50; 3; 0.000000, 0.000000, 0.000000;;,
60; 3; 25.500000, 0.000000, 0.000000;;,
70; 3; 50.000000, 0.000000, 0.000000;;,
80; 3; 75.500000, 0.000000, 0.000000;;,
90; 3; 100.000000, 0.000000, 0.000000;;;
}
}
}


Appendix C: Binary Format

This section details the binary version of the Microsoft® DirectX® file format as introduced with the release of DirectX 3. This appendix should be read in conjunction with the DirectX File Format Architecture section.

The binary format is a tokenized representation of the text format. Tokens may be stand-alone or accompanied by primitive data records. Stand-alone tokens give grammatical structure and record-bearing tokens supply the necessary data.

Note that all data is stored in little endian format.

A valid binary data stream consists of a header followed by templates and/or data objects.

This section discusses the following components of the binary file format:

  • Header
  • Templates
  • Data
  • Tokens
  • Token Records

In addition, example templates are provided, in Example Templates. A binary data object is shown in Example Data.

Header

The following definitions should be used when directly reading and writing the binary header. Note that compressed data streams are not currently supported and are therefore not detailed here.

#define XOFFILE_FORMAT_MAGIC \
  ((long)'x' + ((long)'o' << 8) + ((long)'f' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_VERSION \
  ((long)'0' + ((long)'3' << 8) + ((long)'0' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_BINARY \
  ((long)'b' + ((long)'i' << 8) + ((long)'n' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_TEXT   \
  ((long)'t' + ((long)'x' << 8) + ((long)'t' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_COMPRESSED \
  ((long)'c' + ((long)'m' << 8) + ((long)'p' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_32 \
  ((long)'0' + ((long)'0' << 8) + ((long)'3' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_64 \
  ((long)'0' + ((long)'0' << 8) + ((long)'6' << 16) + ((long)'4' << 24))

Templates

A template has the following syntax definition:

template              : TOKEN_TEMPLATE name TOKEN_OBRACE
                            class_id
                            template_parts
                            TOKEN_CBRACE

template_parts        : template_members_part TOKEN_OBRACKET
                        template_option_info
                        TOKEN_CBRACKET
                      | template_members_list

template_members_part : /* Empty */
                      | template_members_list

template_option_info  : ellipsis
                      | template_option_list

template_members_list :    template_members
                      | template_members_list template_members

template_members      : primitive
                      | array
                      | template_reference

primitive             : primitive_type optional_name TOKEN_SEMICOLON

array                 : TOKEN_ARRAY array_data_type name dimension_list
                        TOKEN_SEMICOLON

template_reference    : name optional_name YT_SEMICOLON

primitive_type        : TOKEN_WORD
                      | TOKEN_DWORD
                      | TOKEN_FLOAT
                      | TOKEN_DOUBLE
                      | TOKEN_CHAR
                      | TOKEN_UCHAR
                      | TOKEN_SWORD
                      | TOKEN_SDWORD
                      | TOKEN_LPSTR
                      | TOKEN_UNICODE
                      | TOKEN_CSTRING

array_data_type       : primitive_type
                      | name

dimension_list        : dimension
                      | dimension_list dimension

dimension             : TOKEN_OBRACKET dimension_size TOKEN_CBRACKET

dimension_size        : TOKEN_INTEGER
                      | name

template_option_list  : template_option_part
                      | template_option_list template_option_part

template_option_part  : name optional_class_id

name                  : TOKEN_NAME

optional_name         : /* Empty */
                      | name

class_id              : TOKEN_GUID

optional_class_id     : /* Empty */
                      | class_id

ellipsis              : TOKEN_DOT TOKEN_DOT TOKEN_DOT

Data

A data object has the following syntax definition:

object                : identifier optional_name TOKEN_OBRACE
                            optional_class_id
                            data_parts_list
                            TOKEN_CBRACE
data_parts_list       : data_part
                      | data_parts_list data_part

data_part             : data_reference
                      | object
                      | number_list
                      | float_list
                      | string_list

number_list           : TOKEN_INTEGER_LIST

float_list            : TOKEN_FLOAT_LIST

string_list           : string_list_1 list_separator

string_list_1         : string
                      | string_list_1 list_separator string

list_separator        : comma
                      | semicolon

string                : TOKEN_STRING

identifier            : name
                      | primitive_type

data_reference        : TOKEN_OBRACE name optional_class_id TOKEN_CBRACE

Tokens

Tokens are written as little endian DWORDs. A list of token values follows. The list is divided into record-bearing and stand-alone tokens.

Record-bearing

#define TOKEN_NAME 1
#define TOKEN_STRING 2
#define TOKEN_INTEGER 3
#define TOKEN_GUID 5
#define TOKEN_INTEGER_LIST 6
#define TOKEN_REALNUM_LIST 7

Stand-alone

#define TOKEN_OBRACE 10
#define TOKEN_CBRACE 11
#define TOKEN_OPAREN 12
#define TOKEN_CPAREN 13
#define TOKEN_OBRACKET 14
#define TOKEN_CBRACKET 15
#define TOKEN_OANGLE 16
#define TOKEN_CANGLE 17
#define TOKEN_DOT 18
#define TOKEN_COMMA 19
#define TOKEN_SEMICOLON 20
#define TOKEN_TEMPLATE 31
#define TOKEN_WORD 40
#define TOKEN_DWORD 41
#define TOKEN_FLOAT 42
#define TOKEN_DOUBLE 43
#define TOKEN_CHAR 44
#define TOKEN_UCHAR 45
#define TOKEN_SWORD 46
#define TOKEN_SDWORD 47
#define TOKEN_VOID 48
#define TOKEN_LPSTR 49
#define TOKEN_UNICODE 50
#define TOKEN_CSTRING 51
#define TOKEN_ARRAY 52

Token Records

This section describes the format of the records for each of the record-bearing tokens.
TOKEN_NAME
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_NAME
count | DWORD | 4 | Length of name field, in bytes
name | BYTE array | Count | ASCII name

TOKEN_NAME is a variable length record. The token is followed by a count value that specifies the number of bytes that follow in the name field. An ASCII name of length count completes the record.
TOKEN_STRING
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_STRING
count | DWORD | 4 | Length of string field in bytes
string | BYTE array | Count | ASCII string
terminator | DWORD | 4 | TOKEN_SEMICOLON or TOKEN_COMMA

TOKEN_STRING is a variable length record. The token is followed by a count value that specifies the number of bytes that follow in the string field. An ASCII string of length count continues the record, which is completed by a terminating token. The choice of terminator is determined by syntax issues discussed elsewhere.
TOKEN_INTEGER
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_INTEGER
value | DWORD | 4 | Single integer

TOKEN_INTEGER is a fixed length record. The token is followed by the integer value required.
TOKEN_GUID
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_GUID
data1 | DWORD | 4 | UUID data field 1
data2 | WORD | 2 | UUID data field 2
data3 | WORD | 2 | UUID data field 3
data4 | BYTE array | 8 | UUID data field 4

TOKEN_GUID is a fixed-length record. The token is followed by the four data fields as defined by the OSF DCE standard.
TOKEN_INTEGER_LIST
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_INTEGER_LIST
count | DWORD | 4 | Number of integers in list field
list | DWORD array | 4 x count | Integer list

TOKEN_INTEGER_LIST is a variable length record. The token is followed by a count value that specifies the number of integers that follow in the list field. For efficiency, consecutive integer lists should be compounded into a single list.
TOKEN_REALNUM_LIST
Field | Type | Size (bytes) | Contents
token | DWORD | 4 | TOKEN_REALNUM_LIST
count | DWORD | 4 | Number of floats or doubles in list field
list | float/double array | 4 or 8 x count | Float or double list

TOKEN_REALNUM_LIST is a variable-length record. The token is followed by a count value that specifies the number of floats or doubles that follow in the list field. The size of the floating point value (float or double) is determined by the value of float size specified in the file header. For efficiency, consecutive realnum lists should be compounded into a single list.

Example Templates

Two example binary template definitions follow. Note that data is stored in little endian format, which is not shown in these examples.

The closed template RGB is identified by the UUID {55b6d780-37ec-11d0-ab39-0020af71e433} and has three members r, g, and b each of type float.

TOKEN_TEMPLATE, TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_OBRACE,
TOKEN_GUID, 55b6d780, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_FLOAT, TOKEN_NAME, 1, 'r', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'g', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'b', TOKEN_SEMICOLON,
TOKEN_CBRACE

The closed template Matrix4x4 is identified by the UUID {55b6d781-37ec-11d0-ab39-0020af71e433} and has one member—a two-dimensional array named matrix of type float.

TOKEN_TEMPLATE, TOKEN_NAME, 9, 'M', 'a', 't', 'r', 'i', 'x', '4', 'x', '4', TOKEN_OBRACE,
TOKEN_GUID, 55b6d781, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_ARRAY, TOKEN_FLOAT, TOKEN_NAME, 6, 'm', 'a', 't', 'r', 'i', 'x',
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_CBRACE

Example Data

The binary data object that follows shows an instance of the RGB template defined earlier. The example object is named blue, and its three members r, g, and b have the values 0.0, 0.0 and 1.0, respectively. Note that data is stored in little endian format, which is not shown in this example.

TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_NAME, 4, 'b', 'l', 'u', 'e', TOKEN_OBRACE,
TOKEN_FLOAT_LIST, 3, 0.0, 0.0, 1.0, TOKEN_CBRACE


Appendix D: The Conv3ds.exe Utility

The Conv3ds.exe utility converts 3-D models produced by Autodesk 3-D Studio and other modeling packages into the Microsoft® DirectX® file format. By default, the utility produces binary .x files with no templates.

Using Conv3ds.exe

You can run Conv3ds.exe with no options, and it will produce an .x file containing a hierarchy of frames. For example, consider the command:

conv3ds File.3ds

This command will produce an .x file called File.x from the .3ds file. You can use IDirect3DRMFrame::Load to load the frame.

Conv3ds.exe Optional Arguments

Conv3ds.exe -A

If the .3ds file contains key frame data, you can use the -A option to produce an .x file that contains an animation set. The command for doing this would be:

conv3ds -A File.3ds

The File.3ds parameter is the name of the file to be converted. You can use IDirect3DRMAnimationSet::Load to load the animation.

Conv3ds.exe -m

Use the -m option to make an .x file that contains a single mesh made from all the objects in the .3ds file.

conv3ds -m File.3ds

Use IDirect3DRMMeshBuilder::Load to load the mesh.

Conv3ds.exe -T

Use the-T option to wrap all the objects and frame hierarchies in a single top-level frame. Using this option, all the frames and objects in the .3ds file can be loaded with a single call to IDirect3DRMFrame::Load. The first top-level frame hierarchy in the .x file will be loaded. The frame containing all the other frames and meshes is called "x3ds_filename" (without the .3ds extension). The -T option will have no effect if it is used with the -m option.

Conv3ds.exe -s

The -s option allows you to specify a scale factor for all the objects converted in the .3ds file. For example, the following command makes all objects 10 times bigger:

conv3ds -s10 File.3ds

The following command makes all objects 10 times smaller:

conv3ds -s0.1 File.3ds

Conv3ds.exe -r

The -r option reverses the winding order of the faces when the .3ds file is converted. If, after converting the .3ds file and viewing it in Direct3D, the object appears inside-out, try converting it with the -r option. All Lightwave models exported as .3ds files need this option. See 3DS Files Produced from Lightwave Objects for details.

Conv3ds.exe -v

The -v option turns on verbose output mode. Specify an integer with it. The following table shows the currently supported integers.
Option | Meaning
-v0 | Default. Verbose mode off.
-v1 | Prints warnings about bad objects, and prints general information about what the converter is doing.
-v2 | Prints basic key frame information, the objects being included in the conversion process, and information about the objects being saved.
-v3 | Very verbose. Mostly useful for the debugging information it provides.

Conv3ds.exe -e

The -e option allows you to change the extension for texture map files. For example, consider the command:

conv3ds -e"ppm" File.3ds

If File.3ds contains objects that reference the texture map file Brick.gif, the .x file will reference the texture map file Brick.ppm. The converter does not convert the texture map file. The texture map files must be in the D3DPATH when the resulting .x file is loaded. The D3DPath is an environment variable that sets the default search path.

Conv3ds.exe -x

The -x option forces the Conv3ds.exe utility to produce a text .x file, instead of a binary .x file. Text files are larger but can be hand-edited easily.

Conv3ds.exe -X

The -X option forces the Conv3ds.exe utility to include the Direct3D Retained Mode .x file templates in the file. By default, the templates are not included.

Conv3ds.exe -t

The -t option specifies that the .x file produced will not contain texture information.

Conv3ds.exe -N

The -N option specifies that the .x file produced will not contain normal vector information. All the Direct3D Retained Mode load calls will generate normal vectors for objects with no normal vectors in the .x file.

Conv3ds.exe -c

The -c option specifies that the .x file produced should not contain texture coordinates. By default, if you use the -m option, the mesh that is output will contain (0,0) uv texture coordinates if the .3ds object had no texture coordinates.

Conv3ds.exe -f

The -f option specifies that the .x file produced should not contain a frame transformation matrix.

Conv3ds.exe - z and Conv3ds.exe -Z

The -z and -Z options allow you to adjust the alpha face color value of all the materials referenced by objects in the .x file. For example, the following command causes Conv3ds.exe to add 0.1 to all alpha values under 0.2:

conv3ds -z0.1 -Z0.2 File.3ds

The following command causes Conv3ds.exe to subtract 0.2 from the alpha values for all alphas:

conv3ds-z"-0.2" -z1 File.3ds

Conv3ds.exe -o

The -o option allows you to specify the file name for the .x file produced.

Conv3ds.exe -h

The -h option tells the converter not to try to resolve any hierarchy information in the .3ds file (usually produced by the key framer). Instead, all the objects are output in top-level frames if the -m option is not used.

3DS Files Produced from Lightwave Objects

There are several issues with .3ds files exported by the Trans3d plug-in for Lightwave. These are best handled using the following Conv3ds.exe command:

conv3ds -r -N -f -h -T|m trans3dfile.3ds

All the .3ds objects produced by Trans3d and the Lightwave object editor need their winding order reversed. Otherwise, they appear inside-out when displayed. They contain no surface normal vector information.

Hints and Tips

If you cannot see objects produced by Conv3ds.exe after loading them into the Direct3D Retained Mode viewer, use the scale option -s with a scale factor of approximately 100. This will increase the scale of the objects in the .x file.

If, after loading the object into the viewer and switching from flat shading into Gouraud shading, the object turns dark gray, try converting with the -N option.

If the textures are not loaded after the object is converted, check whether the object is referencing either .ppm or .bmp files by using the -e option. Also check whether the textures' widths and heights are a power of 2. Make sure the textures are stored in one of the directories in your D3DPATH.

Currently, Conv3ds.exe cannot handle dummy frames used in .3ds animations. It ignores them. However, it will convert any child objects.


Direct3D Retained Mode Glossary

This glossary primarily defines terms related to Microsoft® Direct3D® Retained Mode. Entries are grouped by letter in alphabetical order. See the Microsoft Windows® NT® or Microsoft Windows® 95 online Help for additional information.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

ambient
A light source that illuminates everything in a scene, regardless of the orientation, position, and surface characteristics of the objects in the scene. Because this illuminates a scene with equal strength everywhere, the position and orientation of the frame it is attached to are inconsequential. Multiple ambient light sources are combined within a scene.
array object
A group of objects organized into an array. Array objects make it simpler to apply operations to the entire group. The Component Object Model (COM) interfaces that enable you to work with array objects contain the GetElement and GetSize methods. These methods retrieve a pointer to an element in the array and the size of the array, respectively.


B

back buffer
A nonvisible surface that bitmaps and other images can be drawn to while the primary surface displays the currently visible image.
back clipping plane
The far boundary of a viewing frustum beyond which objects are not rendered. See also front clipping plane.


C

camera
A Direct3DRMFrame object used by the viewport to define the viewing position and direction. The viewport renders only what is visible along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.


D

decal
A texture that is rendered directly as a visual. Decals are rendered into a viewport-aligned rectangle.
directional
A light source that is attached to a frame but appears to illuminate all objects with equal intensity, as if it were at an infinite distance from the objects. Directional light has orientation but no position, and it is commonly used to simulate distant light sources, such as the sun.


E

emissive property
The material property that determines whether a material emits light. The emissive property of a material is one of two properties that determines how the material reflects light. See also specular property.
enable frame
The frame to which a light applies.


F

front clipping plane
The near boundary of a viewing frustum. Any object closer to the camera than the front clipping plane is not rendered. The height of the front clipping plane defines the field of view. See also back clipping plane.


M

mipmap
A sequence of textures, each of which is a progressively lower-resolution, prefiltered representation of the same image. A higher-resolution image is used when a visible object is close to the viewer. As the object moves farther away (and gets smaller), lower-resolution images are used.
model coordinates
Coordinates that are relative to a child frame. See also world coordinates.


N

normal vector
An imaginary ray extending perpendicularly from a surface that defines the face's orientation.


P

parallel point
A light source that illuminates objects with parallel light, but the orientation of the light is taken from the position of the parallel point light source. For example, two meshes on either side of a parallel point light source are lit on the side that faces the position of the source.
penumbra
The outer, dimly lit section of a spotlight's cone of light. The penumbra surrounds the umbra and merges with the surrounding deep shadow. See also umbra, and spotlight.
point
A light source that radiates equally in all directions from its origin.
power
In the specular property of a material, the value that determines the sharpness of specular highlights. A value of 5 gives a metallic appearance, and higher values give a more plastic appearance.


R

reference count
A control for a Component Object Model (COM) object. When an object is created, its reference count is set to 1. Every time an interface is bound to the object, its reference count is incremented. When the interface connection is destroyed, the reference count is decremented. The object is destroyed when the reference count reaches 0. All interfaces to that object are then invalid.
root frame
A frame in Direct3D that has no parent frame. A frame at the top of a hierarchy of frames. The root frame contains the entire set of objects that make up a scene.


S

specular property
The material property that determines how a point of light on a shiny object corresponds to the reflected light source. The specular property of a material is one of two properties that determines how a material reflects light. See also emissive property.
spotlight
A light source that emits a cone of light. Only objects within the cone are illuminated. The cone produces light of two degrees of intensity with a central brightly lit section (the umbra) that acts as a point source, and a surrounding dimly lit section (the penumbra) that merges with the surrounding deep shadow.


T

texture blending
The technique of combining the colors of a texture with the colors of the surface to which the texture is applied.


U

umbra
The central brightly lit section of a spotlight's cone of light. The umbra can act as a point source. See also penumbra and spotlight.


V

viewing frustum
A 3-D volume in a scene positioned relative to the viewport's camera. Objects within the frustum are visible. For perspective viewing, the viewing frustum is the volume of an imaginary pyramid that is between the front clipping plane and the back clipping plane. For orthographic viewing, the viewing frustum is cuboid.


W

world coordinates
Coordinates that are relative to the root frame. See also model coordinates.


CopyRight

NOTICE SPECIFIC TO SOFTWARE AVAILABLE ON THIS WEBSITE

Any software that is made available to download from this server ("Software") is the copyrighted work of Microsoft Corporation and/or its suppliers. Use of the Software is governed by the terms of the end user license agreement, if any, which accompanies or is included with the Software ("License Agreement") . An end user will be unable to install any Software that is accompanied by or includes a License Agreement, unless he or she first agrees to the License Agreement terms.

The Software is made available for downloading solely for use by end users according to the License Agreement. Any reproduction or redistribution of the Software not in accordance with the License Agreement is expressly prohibited by law, and may result in severe civil and criminal penalties. Violators will be prosecuted to the maximum extent possible.

WITHOUT LIMITING THE FOREGOING, COPYING OR REPRODUCTION OF THE SOFTWARE TO ANY OTHER SERVER OR LOCATION FOR FURTHER REPRODUCTION OR REDISTRIBUTION IS EXPRESSLY PROHIBITED.

THE SOFTWARE IS WARRANTED, IF AT ALL, ONLY ACCORDING TO THE TERMS OF THE LICENSE AGREEMENT. EXCEPT AS WARRANTED IN THE LICENSE AGREEMENT, MICROSOFT CORPORATION HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT.

RESTRICTED RIGHTS LEGEND. Any Software which is downloaded from this Server for or on behalf of the United States of America, its agencies and/or instrumentalities ("U.S. Government"), is provided with Restricted Rights. Use , duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Microsoft Corporation, One Microsoft Way, Redmond, WA 98052-6399.

NOTICE SPECIFIC TO DOCUMENTS AVAILABLE ON THIS WEBSITE

Permission to use Documents (such as white papers, press releases, datasheets and FAQs) from this server ("Server") is granted, provided that (1) the below copyright notice appears in all copies and that both the copyright notice and this permission notice appear, (2) use of such Documents from this Server is for informational and non-commercial or personal use only and will not be copied or posted on any network computer or broadcast in any media, and (3) no modifications of any Documents are made. Use for any other purpose is expressly prohibited by law, and may result in severe civil and criminal penalties. Violators will be prosecuted to the maximum extent possible.

Documents specified above do not include the design or layout of the Microsoft .com website or any other Microsoft owned, operated, licensed or controlled site. Elements of Microsoft websites are protected by trade dress and other laws and may not be copied or imitated in whole or in part. No logo, graphic , sound or image from any Microsoft website may be copied or retransmitted unless expressly permitted by Microsoft.

MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION CONTAINED IN THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THIS SERVER FOR ANY PURPOSE. ALL SUCH DOCUMENTS AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THIS SERVER.

THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THIS SERVER COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN. MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME.

NOTICES REGARDING SOFTWARE, DOCUMENTS AND SERVICES AVAILABLE ON THIS WEBSITE.

IN NO EVENT SHALL MICROSOFT AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT , NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF SOFTWARE, DOCUMENTS, PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR INFORMATION AVAILABLE FROM THIS SERVER.

LINKS TO THIRD PARTY SITES

THE LINKS IN THIS AREA WILL LET YOU LEAVE MICROSOFT'S SITE. THE LINKED SITES ARE NOT UNDER THE CONTROL OF MICROSOFT AND MICROSOFT IS NOT RESPONSIBLE FOR THE CONTENTS OF ANY LINKED SITE OR ANY LINK CONTAINED IN A LINKED SITE. MICROSOFT IS PROVIDING THESE LINKS TO YOU ONLY AS A CONVENIENCE, AND THE INCLUSION OF ANY LINK DOES NOT IMPLY ENDORSEMENT BY MICROSOFT OF THE SITE.

COPYRIGHT NOTICE. Copyright © 1998 Microsoft and/or its suppliers, One Microsoft Way, Redmond, Washington 98052-6399 U.S.A. All rights reserved.

TRADEMARKS. Microsoft, Windows, Windows NT, MSN, The Microsoft Network and/or other Microsoft products referenced herein are either trademarks or registered trademarks of Microsoft. Other product and company names mentioned herein may be the trademarks of their respective owners.

The names of companies, products, people, characters and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product or event, unless otherwise noted.

Any rights not expressly granted herein are reserved.

Contact Microsoft with questions or problems with this service.
**

** ** © 1998 Microsoft Corporation. All rights reserved. Terms of Use.


DirectAnimation Readme

© 1998 Microsoft Corporation. All rights reserved. Terms of use.

This document provides late-breaking or other information that supplements the Microsoft DirectAnimation documentation.

Overview

Requirements, Dependencies, and Installation

Additional Information

Known Bugs

Contact Information

Overview

DirectAnimation was released as an integrated component of Internet Explorer 4.0 minimal install. This provides unprecedented animation and multimedia capabilities built into a major Internet browser (no special download is needed). Furthermore, DirectAnimation allows for integration with DHTML, and hence is especially suitable for adding compact and lightweight animation effects to web pages.

DirectAnimation is the component of the DirectX family of APIs that provides rich animation and integrated media support for Web pages, CD-ROM titles, and multimedia applications. DirectAnimation provides unified and comprehensive support for the different media types, including: 2-D vector graphics, 3-D graphics, sprites, audio, video, and a rich time and event model that applies uniformly across the different media types. DirectAnimation is a COM API and an underlying engine/run time whose functionally can be accessed in different ways by different user groups:

  • HTML authors can integrate animation using the DirectAnimation controls.
  • Visual Basic® Scripting Edition (VBScript), JScript™ users, and Java applet writers can program animation for web pages with integration with DHTML.
  • Finally, Java, Visual Basic, and C++ programmers can develop ActiveX Controls or full applications with rich media and interactivity.

The supported media types are as follows:

  • 2-D images (.bmp, .gif, .png, and .jpeg files)
  • 3-D models (.x and VRML files)
  • Sounds (.wav and .midi files)
  • Movies (.avi, .mpeg, and .mov files)
  • Text
  • Vector graphics

In the case of movies and sounds, additional media formats can be supported by supplying DirectShow CODECs for those formats.

One of the key DirectAnimation classes is the Behavior class. Different types of media are incorporated into the animation by encapsulating them as DirectAnimation Behavior objects. Behavior objects can be used interchangeably, and have a number of methods applied to them, independent of the media type they are encapsulating. Of course, you can still access methods that are specific to the different types of behaviors, based on the type of media.

Back to the top

Requirements, Dependencies, and Installation

The minimum requirements in order to run DirectAnimation applications and content are as follows:

  • Pentium-based computer with 16 Megabytes of memory
  • Windows 95 or NT 4.0
  • DirectX, including Direct3D (for NT users, we recommend SP3)

The DirectAnimation run time comes as part of IE4 minimal install . DirectAnimation will also be part of Windows 98 and future releases of Windows NT.

Back to the top

Additional Information

DirectAnimation supports several scripting languages (JScript and VBScript), as well as the integration of the multimedia controls (in Internet Explorer 4.x) with the DirectAnimation run time. In addition to the multimedia controls, a windowed control is provided which can be used, not only with IE 4.0, but also with IE 3.02 and with Visual Basic 5.0. With the addition of the multimedia controls, content developers can now access DirectAnimation functionality through different levels, from PARAM tags at the control level, to scripting, to raw COM.

The DirectAnimation Java classes are dependent on the version of the Java VM that ships with the Microsoft SDK for Java 2.0 and Internet Explorer 4.x. We used Microsoft Visual J++ 1.1 to author the Java samples.

In order to use DirectAnimation Java-based content within Netscape's Navigator, follow these instructions:

Microsoft has made a plug-in available to users of Netscape Navigator 2.02 and 3.0 which allows them to make use of the Microsoft Java VM. Netscape Communicator is not yet supported because of changes made to the plug-in interface. Note that this plug-in does not replace the Netscape Java VM, but it does provide access to the MS VM through the use of the <embed> tag. To get an applet up and running under Netscape, follow these simple steps:

  1. Get the plug-in from the Java SDK 2.0 and place it in your Navigator\Program\Plugins directory.
  2. Install the required MS Java VM, if you haven't already.
  3. Change the applet tag in your source html from this:

<applet code="myjava.class" width=100 height=100></applet>

To this:

<embed src="myjava.class" width=100 height=100></embed>

In general, we recommend that you upgrade to the DirectX 5 set of video drivers. Several visual artifacts that appear under older versions of video drivers disappear with the newer set.

We have added some C++ based samples to the SDK. Some samples rely on the DA control, while others composite directly to a DirectDraw surface.

When possible, we suggest that you take advantage of the asynchronous import methods. This leads to more responsive content, since the end user does not have to wait for all the content to load, before experiencing the animation.

Back to the top

Known Bugs

The following is a list of current known problems. We strongly encourage you to send us mail if you find a problem ( dxmbug@microsoft.com ). There are newsgroups set up to allow DirectAnimation content developers to discuss issues and ideas; however, mailing a bug description is the only sure way to get a fix for a bug.

The release of DirectAnimation in this SDK and accompanying redist package is newer than that distributed with IE 4.0. There were many bug fixes related to memory leaks, as well as the following functional changes:

  • In the size parameter for text, a negative quantity can be specified. The negative quantity allows you to indicate to DirectAnimation that the text behavior's size/orientation is not going to be animated (although animating the position is fine), allowing us to produce a higher quality text. We will carry support for this parameter forward, but eventually you will get the same high quality text regardless of transforms applied to the text behavior.
  • The timer source for the DirectAnimation control can be selected using the IDAViewerControl::TimerSource property. This is useful for Web scripting. By default, DirectAnimation uses WM_TIMER messages
    You can use the IE 4.0 DHTML timers by specifying values of DA_TIMER_SOURCE type, which allows your DirectAnimation content to be in sync with other controls or DHTML elements. Note that, if you use this property, you should check for the version number which is accessible through the VersionString method on DAStatics. Failure to do so will cause an error when the page is viewed with the previous version of DirectAnimation.
  • If you find a problem with your scripting-based content that seems to make your Web page appear unresponsive to events and timers outside of your DirectAnimation content, you should set the UpdateInterval property of the control to 0.15 (this causes a new frame to be drawn every 0.15 seconds, meaning that the content gets 6.66 frames per second).
  • The DirectAnimation Java classes fully enforce the Java security model, only allowing media located in directories below the location of the Web page to be opened by the applet.

General

  • For Java content, all initialization of DirectAnimation behaviors and events needs to happen in methods (cannot happen in classes outside of methods); however, you can have declarations of behaviors outside methods to make them accessible from other classes and throughout the methods of a class.
  • There are some small memory leaks, most notably when using 3-D, sounds, or notifiers. To fix this in Java, implement public void cleanup() to the class that extends Model. In this method, call super.cleanup() and set all behaviors that are suspected of leaking memory to NULL. If you have other classes which contain DA behaviors, implement public void cleanup() and only set suspect behaviors to NULL. Also, add the public void destroy() to the class that extends DXMApplet. In this method, call super.destroy() and set the model to NULL.
  • For Java content, sometimes the LeftButtonPress events miss.
  • The cursor is considered to be in the middle of the window when DirectAnimation first comes up.
  • TextPath and TextImage are now obsolete. Please use StringPath and StringImage instead.
  • Notifiers can only be implemented in Java.
  • AnimateControlPosition takes parameters in meters, even if you are using the pixel library.
  • Only DirectDraw surfaces created through DirectDrawEx can be imported.
  • bvrhook does not get called at snapshot time.

Graphics

  • Shearing movies and lines does not work properly.
  • Color palette is not correct for 256 colors displays under NT.
  • SubstituteTime does not work right when applied to splines.
  • FollowPathAngleUpright isn't doing the uprightness.
  • Although class browsers or Visual Basic show the parameters to arc and roundedrect as radius, they are really the diameter.
  • Using Java, time-varying opacity may cause the whole object to become solid after some time.
  • TextMatte isn't allowing enough of the image to be drawn through.
  • Knot duplicity for splines is not handled.
  • Bounding box of a sheared behavior is incorrect.
  • Overlaying an image on a solidColorImage, cropping it, and then adding a rotation transform, results in the solidColorImage disappearing. The workaround is to crop the solidColorImage into a matte.
  • Underline and strikethrough don't work on NT.
  • When loading a large number of JPEG images, there is a significant delay. A workaround is to make use of the asynchronous import method.

Audio

  • Sound does not turn off all the time.
  • SinSynth plays at 440Hz no matter what rate is specified.
  • Dynamic phasing isn't enabled.
  • Loop causes the leaf sounds to loop, not the combined sound behavior (this is the intended behavior).
  • SinSynth mixed with static sound gives a choppy sinusoidal sound.
  • Audio time substitutions not accumulating

3-D

  • Textures are not propagating down the leaf geometries for .X-files-based 3-D objects.

Movies

  • To use a movie as a texture, you have to use the following workaround (code snippet in JScript):

movieImport
        = m.ImportMovie("http://movie.avi");
movieImg = movieImport .Image;

// This is the workaround
movieBBox = movieImg.BoundingBox;
solidImg = m.SolidColorImage(m.White);
solidImg = solidImg.Crop(movieBBox.Min,movieBBox.Max);

movieImg = m.Overlay(movieImg,solidImg);

Controls

  • When using the Sprite multimedia control, source .bmp images over 2048 pixels long have to be broken into arrays of images (rows and columns of images, instead of just one long row or column).
  • Under some video drivers, filtered transparent pixels render as black.
  • For the Path control, TimeMarker persistence parameter "-1" works like FALSE in JScript.

Using Visual Basic

  • Use the DirectAnimation Windowed Control when creating Visual Basic samples. There is a buffering problem in Visual Basic 5.0 that causes flashing if the DirectAnimation Windowless Control is used instead. This will be fixed in a future version of Visual Basic.
  • Button events do not work.
  • If the animation runs too slowly, increase the value of the UpdateInterval property.

Back to the top

Contact Information

We've set public news groups on the Microsoft Public News Server , as a forum for the DirectAnimation user community. We encourage you to post all questions related to the use of DirectAnimation on the appropriate news group:

  • microsoft.public.multimedia.directx.danimation.controls is for users of the DirectAnimation controls.
  • microsoft.public.multimedia.directx.danimation.programming is for programmers of the DirectAnimation API.

For reporting bugs against the preview version, send mail to dxmbug@microsoft.com . When you do so, make sure to be specific about the OS, PC/graphics card, version of IE4, and specific host language/control that you're using to access DirectAnimation.

Back to the top


DirectShow Readme

Welcome to the DirectShow SDK

© 1998 Microsoft Corporation. All rights reserved. Terms of use.

This document provides late-breaking or other information that supplements the Microsoft DirectShow documentation.

Overview

New Since DirectShow 5.1

New Since ActiveMovie 1.0

Building the Samples

Known Issues and Troubleshooting

Contact Information

Capture Hardware Tested with this Release

Overview

To get started with the DirectShow SDK, please do the following:

Read Getting Started section of the Microsoft DirectShow SDK documentation.

Read the NEW SINCE DirectShow 5.1 section of this Readme.

Read the license information.

Licensing information is located in the license.doc in the root of the CD, and eula.doc in the x86\redist and alpha\redist directories.

DirectShow will fully replace MCI functionality over time, but that functionality is not completely implemented yet. In addition, Visual Basic support for some properties of the ActiveMovie control is not yet complete, which might result in some restricted functionality. A detailed list of the known limitations can be found in Microsoft's on-line Knowledge Base (http://www.microsoft.com/kb), searching the Win32 SDK database for article number Q157060.

The DirectShow team welcomes any feedback regarding bugs or restrictions so that problems can be rectified as soon as possible. Please direct your feedback via e-mail to dxmbeta@microsoft.com.

For the latest on DirectShow, check out Microsoft's on-line Knowledge Base (http://www.microsoft.com/kb). Search the Win32 SDK product for keywords such as ActiveMovie, DirectShow and kbmm.

Back to the top

New Since DirectShow 5.1

The DirectX Media 5.2b run time has improvements in two specific areas - DVD Playback and WDM Capture support.

For DVD playback, the run time provides support for PAL DVD discs as well as improved interactive responsiveness. The run time has also been tested with many new DVD titles that were released in the last two months.

The Overlay Mixer, which is a key rendering component for DVD playback, has been improved in the following areas.

  • New interfaces added on each pin of Overlay Mixer.
    • IOverlay enables upstream filters to do the rendering themselves, leaving only the window management to the Overlay Mixer.
    • IMixerPinConfig2 has methods to set and get brightness, contrast, and other color control features, as if setting the color controls on the overlay surface.
    • IVPNotify2 has methods to make the video port the sync master of the VGA, and to determine if the video port is the sync master.
  • The IMixerPinConfig methods SetZOrder, GetZOrder, SetBlendingParameter, and GetBlendingParameter, which previously returned E_NOTIMPL, have been enabled now.
  • Overlay Mixer now tries to create the overlay surface in AGP memory if allocation in video memory fails.
  • Some important scaling bugs, including one that did not allow shrinking of overlay surfaces on certain video cards (like ATI rage pro), have now been fixed.
  • Previously, using IBasicVideo to zoom or stretch video did not do the correct thing. That has now been fixed.

The video and audio capture infrastructure has been enhanced to add support for more types of WDM streaming class capture hardware running under Microsoft® Windows® 98 or Windows NT® 5.0. If your application is going to work with this new hardware, you should re-read the capture interface descriptions and re-read the code for our sample capture application, Amcap.exe found in the Capture sample directory.

In addition, a new video control interface has been added, IAMVideoControl, that enables you to flip a picture horizontally and/or vertically, to set up a stream so that it can capture from an external trigger, to simulate an external trigger in software, and to list the current frame rate, maximum frame rate, and available frame rates.

A new filter, Smart Tee, has been added to aid preview on capture filters that only have a capture pin and not a preview pin.

Back to the top

New Since ActiveMovie 1.0

  • MIDI file playback support.
  • Multimedia stream interfaces. See About the Multimedia Streaming Architecture in the documentation.
  • Improved Filter Graph Editor (GraphEdt.exe) SDK tool.
  • Integration with the DirectAnimation run time.
  • New samples, headers, and libraries for developers to use and modify, including the "AMCap" audio/video capture application (see samples\dshow\capture).
  • VFW Capture filter. Wraps Video for Windows capture drivers
  • Audio Capture filter. Wraps waveIn sound drivers
  • AVI Compressor filter. Uses ICM compressors to compress video.
  • AVI Draw filter. Allows access to hardware based ICM video decompressors.
  • AVI Mux filter. Multiplexes streams into an AVI stream suitable for a file writer.
  • File Writer filter.
  • Capture graph building interface (ICaptureGraphBuilder). See AMCap sample (see samples\dshow\capture) and documentation for usage.
  • All capture related interfaces are defined in axextend.idl and also documented in the documentation.
  • DirectSound audio renderer. Includes 3-D and arbitrary DirectSound processing support.
  • Improved ActiveX playback control. Improved scripting and Visual Basic support. ActiveMovie ActiveX playback control now by default supports: MID, RMI and WAV formats. Dynamically maintains the aspect ratio of the video when resizing through the control. To turn off the aspect ratio during a resize, hold down the CTRL key.

Back to the top

Building the Samples

To build the DirectShow SDK samples, you must install Microsoft Visual C++ version 5.0. The header files and libraries from the DirectShow SDK are also required.

To build all the samples, run nmake in the \samples\dshow directory. Debug versions will be built by default. To produce non-debug versions set the 'nodebug' environment variable (that is, set nodebug=1), or type nmake NODEBUG=1.

Back to the top

Known Issues and Troubleshooting

The following is a list of current problems. Some of them have already been fixed; those fixes will appear in upcoming releases.

General

    Trouble Shooting
    • Installation Problems
      • Problem: I am receiving an error copying files when installing the SDK or run time on NT.
      • Solution: DirectX Media requires that the user be an administrator for installing. Please modify your installation program to require administrative privileges before installing.
      • Problem: I am receiving an error using DirectShow property pages on NT ALPHA.
      • Solution: Make sure you have NT ALPHA SP3 installed with the DirectX Media run time.
    • Capture
      • Problem: I would like to improve my capture performance using DirectShow.
      • Solution: Please read the Improving Capture Performance section of your DirectShow documentation.
      • Problem: My capture card does not work correctly with the new DirectShow.
      • Solution: Please contact your capture card manufacturer for the latest drivers. Many problems you encounter with capture can be solved by simply obtaining the latest drivers.
    • DVD
      • Problem: I am encountering problems playing DVD on a 640x480 or a very high resolution and/or color depth.
      • Solution: Change your screen resolution to 800x600, and/or lower the color depth.
    • DV
      • Problem: The DV Muxer won't accept an audio stream unless a video stream is already connected.
      • Solution: If you just want to write audio data, send black video frames to the Mux as well.
    Known Issues
    • Capture
      • The Broadway card does not capture with the AMCap application.
    • Setup
      • DirectShow requires SP3 on NT ALPHA only.
      • Setup requires the user be logged on as an administrator.
      • The DirectX Media run time installation installs a minimum version of DirectX. If your application is going to install DirectX 5.0, make sure that it installs DirectX 5.0 after the DirectX Media run time.
    • DVD
      • ChapterPlayAutoStop and ChapterPlay calls are only allowed in VTSM, VMGM, or TT Domains.

Back to the top

Contact Information

Development questions, feature requests, and business opportunities for those developing tools or content based on DirectShow should be addressed to: dxmbeta@microsoft.com.

Bugs should be reported to dxmbug@microsoft.com

DirectShow has created public news groups on the Microsoft Public News Server, as a forum for the DirectX media user community. You are encouraged to post questions on the appropriate news group:

  • microsoft.public.multimedia.directx.dshow.activemovie — a newsgroup for users of the DirectShow control.
  • microsoft.public.multimedia.directx.dshow.programming — a newsgroup for programmers of the DirectShow API.

Back to the top

Capture Hardware Tested with this Release

The following capture hardware has been successfully tested in this release using the DirectShow audio and video capture filters (as appropriate):

  • Truevision TARGA 2000 Pro, DTX, and RTX
  • miro Computer Products miroVIDEO DC30
  • miro Computer Products miroVIDEO DC20 (Win95)
  • Creative Labs Sound Blaster AWE32 PnP
  • FAST Electronic AV Master
  • Winnov Videum AV
  • Connectix Color QuickCam
  • Broadway
  • ATI All in Wonder
  • Intel Smart Video Recorder III

Back to the top


DirectX Media Shell Page

DirectX Media SDK DirectAnimation SDK
DirectX Media SDK
DirectShow SDK
DirectPlay SDK
Direct3D Retained Mode SDK


Index

A B C D E F G H I L M N P R S T U V W X Y Z

GenerateMIPMap
GenerateMIPMap (IDirect3DRMTexture2)
GenerateNormals
GenerateNormals (IDirect3DRMMeshBuilder)
GenerateNormals2
GenerateNormals2 (IDirect3DRMMeshBuilder2)
GetAppData
GetAppData (IDirect3DRMObject)
GetAttachedObjects
GetAttachedObjects (IDirect3DRMInterpolator)
GetAxes
GetAxes (IDirect3DRMFrame2)
GetBack
GetBack (IDirect3DRMViewport)
GetBox (IDirect3DRMFrame2)
GetBox (IDirect3DRMMesh)
GetBox (IDirect3DRMMeshBuilder)
GetBox (IDirect3DRMMeshBuilder2)
GetBox (IDirect3DRMProgressiveMesh)
GetBox (IDirect3DRMFrame2)
GetBox (IDirect3DRMMesh)
GetBox (IDirect3DRMMeshBuilder)
GetBox (IDirect3DRMMeshBuilder2)
GetBox (IDirect3DRMProgressiveMesh)
GetBoxEnable
GetBoxEnable (IDirect3DRMFrame2)
GetBufferCount (IDirect3DRMDevice)
GetBufferCount (IDirect3DRMDevice2)
GetBufferCount (IDirect3DRMDevice)
GetBufferCount (IDirect3DRMDevice2)
GetCamera
GetCamera (IDirect3DRMViewport)
GetChildren (IDirect3DRMFrame)
GetChildren (IDirect3DRMFrame2)
GetChildren (IDirect3DRMFrame)
GetChildren (IDirect3DRMFrame2)
GetClassName
GetClassName (IDirect3DRMObject)
GetColor (IDirect3DRMFace)
GetColor (IDirect3DRMFrame)
GetColor (IDirect3DRMFrame2)
GetColor (IDirect3DRMLight)
GetColor (IDirect3DRMFace)
GetColor (IDirect3DRMFrame)
GetColor (IDirect3DRMFrame2)
GetColor (IDirect3DRMLight)
GetColorModel (IDirect3DRMDevice)
GetColorModel (IDirect3DRMDevice2)
GetColorModel (IDirect3DRMDevice)
GetColorModel (IDirect3DRMDevice2)
GetColors (IDirect3DRMTexture)
GetColors (IDirect3DRMTexture2)
GetColors (IDirect3DRMTexture)
GetColors (IDirect3DRMTexture2)
GetColorSource (IDirect3DRMMeshBuilder)
GetColorSource (IDirect3DRMMeshBuilder2)
GetColorSource (IDirect3DRMMeshBuilder)
GetColorSource (IDirect3DRMMeshBuilder2)
GetConstantAttenuation
GetConstantAttenuation (IDirect3DRMLight)
GetDecalOrigin (IDirect3DRMTexture)
GetDecalOrigin (IDirect3DRMTexture2)
GetDecalOrigin (IDirect3DRMTexture)
GetDecalOrigin (IDirect3DRMTexture2)
GetDecalScale (IDirect3DRMTexture)
GetDecalScale (IDirect3DRMTexture2)
GetDecalScale (IDirect3DRMTexture)
GetDecalScale (IDirect3DRMTexture2)
GetDecalSize (IDirect3DRMTexture)
GetDecalSize (IDirect3DRMTexture2)
GetDecalSize (IDirect3DRMTexture)
GetDecalSize (IDirect3DRMTexture2)
GetDecalTransparency (IDirect3DRMTexture)
GetDecalTransparency (IDirect3DRMTexture2)
GetDecalTransparency (IDirect3DRMTexture)
GetDecalTransparency (IDirect3DRMTexture2)
GetDecalTransparentColor (IDirect3DRMTexture)
GetDecalTransparentColor (IDirect3DRMTexture2)
GetDecalTransparentColor (IDirect3DRMTexture)
GetDecalTransparentColor (IDirect3DRMTexture2)
GetDetail
GetDetail (IDirect3DRMProgressiveMesh)
GetDevice
GetDevice (IDirect3DRMViewport)
GetDevices (IDirect3DRM)
GetDevices (IDirect3DRM2)
GetDevices (IDirect3DRM)
GetDevices (IDirect3DRM2)
GetDirect3DDevice
GetDirect3DDevice (IDirect3DRMDevice)
GetDirect3DDevice2
GetDirect3DDevice2 (IDirect3DRMDevice2)
GetDirect3DViewport
GetDirect3DViewport (IDirect3DRMViewport)
GetDither (IDirect3DRMDevice)
GetDither (IDirect3DRMDevice2)
GetDither (IDirect3DRMDevice)
GetDither (IDirect3DRMDevice2)
GetElement (IDirect3DRMDeviceArray)
GetElement (IDirect3DRMFaceArray)
GetElement (IDirect3DRMFrameArray)
GetElement (IDirect3DRMLightArray)
GetElement (IDirect3DRMObjectArray)
GetElement (IDirect3DRMViewportArray)
GetElement (IDirect3DRMVisualArray)
GetElement (IDirect3DRMDeviceArray)
GetElement (IDirect3DRMFaceArray)
GetElement (IDirect3DRMFrameArray)
GetElement (IDirect3DRMLightArray)
GetElement (IDirect3DRMObjectArray)
GetElement (IDirect3DRMViewportArray)
GetElement (IDirect3DRMVisualArray)
GetEmissive
GetEmissive (IDirect3DRMMaterial)
GetEnableFrame
GetEnableFrame (IDirect3DRMLight)
GetFace
GetFace (IDirect3DRMMeshBuilder2)
GetFaceCount (IDirect3DRMMeshBuilder)
GetFaceCount (IDirect3DRMMeshBuilder2)
GetFaceCount (IDirect3DRMMeshBuilder)
GetFaceCount (IDirect3DRMMeshBuilder2)
GetFaceDetail
GetFaceDetail (IDirect3DRMProgressiveMesh)
GetFaceDetailRange
GetFaceDetailRange (IDirect3DRMProgressiveMesh)
GetFaces (IDirect3DRMMeshBuilder)
GetFaces (IDirect3DRMMeshBuilder2)
GetFaces (IDirect3DRMMeshBuilder)
GetFaces (IDirect3DRMMeshBuilder2)
GetField
GetField (IDirect3DRMViewport)
GetFront
GetFront (IDirect3DRMViewport)
GetGroup
GetGroup (IDirect3DRMMesh)
GetGroupColor
GetGroupColor (IDirect3DRMMesh)
GetGroupCount
GetGroupCount (IDirect3DRMMesh)
GetGroupMapping
GetGroupMapping (IDirect3DRMMesh)
GetGroupMaterial
GetGroupMaterial (IDirect3DRMMesh)
GetGroupQuality
GetGroupQuality (IDirect3DRMMesh)
GetGroupTexture
GetGroupTexture (IDirect3DRMMesh)
GetHeight (IDirect3DRMDevice)
GetHeight (IDirect3DRMDevice2)
GetHeight (IDirect3DRMViewport)
GetHeight (IDirect3DRMDevice)
GetHeight (IDirect3DRMDevice2)
GetHeight (IDirect3DRMViewport)
GetHierarchyBox
GetHierarchyBox (IDirect3DRMFrame2)
GetImage (IDirect3DRMTexture)
GetImage (IDirect3DRMTexture2)
GetImage (IDirect3DRMTexture)
GetImage (IDirect3DRMTexture2)
GetIndex
GetIndex (IDirect3DRMInterpolator)
GetInheritAxes
GetInheritAxes (IDirect3DRMFrame2)
GetLights (IDirect3DRMFrame)
GetLights (IDirect3DRMFrame2)
GetLights (IDirect3DRMFrame)
GetLights (IDirect3DRMFrame2)
GetLinearAttenuation
GetLinearAttenuation (IDirect3DRMLight)
GetLoadStatus
GetLoadStatus (IDirect3DRMProgressiveMesh)
GetMaterial (IDirect3DRMFace)
GetMaterial (IDirect3DRMFrame2)
GetMaterial (IDirect3DRMFace)
GetMaterial (IDirect3DRMFrame2)
GetMaterialMode (IDirect3DRMFrame)
GetMaterialMode (IDirect3DRMFrame2)
GetMaterialMode (IDirect3DRMFrame)
GetMaterialMode (IDirect3DRMFrame2)
GetName
GetName (IDirect3DRMObject)
GetNamedObject (IDirect3DRM)
GetNamedObject (IDirect3DRM2)
GetNamedObject (IDirect3DRM)
GetNamedObject (IDirect3DRM2)
GetNormal
GetNormal (IDirect3DRMFace)
GetOptions
GetOptions (IDirect3DRMAnimation)
GetOrientation (IDirect3DRMFrame)
GetOrientation (IDirect3DRMFrame2)
GetOrientation (IDirect3DRMFrame)
GetOrientation (IDirect3DRMFrame2)
GetParent (IDirect3DRMFrame)
GetParent (IDirect3DRMFrame2)
GetParent (IDirect3DRMFrame)
GetParent (IDirect3DRMFrame2)
GetPenumbra
GetPenumbra (IDirect3DRMLight)
GetPerspective (IDirect3DRMMeshBuilder)
GetPerspective (IDirect3DRMMeshBuilder2)
GetPerspective (IDirect3DRMMeshBuilder)
GetPerspective (IDirect3DRMMeshBuilder2)
GetPick (IDirect3DRMPicked2Array)
GetPick (IDirect3DRMPickedArray)
GetPick (IDirect3DRMPicked2Array)
GetPick (IDirect3DRMPickedArray)
GetPlane
GetPlane (IDirect3DRMViewport)
GetPosition (IDirect3DRMFrame)
GetPosition (IDirect3DRMFrame2)
GetPosition (IDirect3DRMFrame)
GetPosition (IDirect3DRMFrame2)
GetPower
GetPower (IDirect3DRMMaterial)
GetProjection
GetProjection (IDirect3DRMViewport)
GetQuadraticAttenuation
GetQuadraticAttenuation (IDirect3DRMLight)
GetQuality (IDirect3DRMDevice)
GetQuality (IDirect3DRMDevice2)
GetQuality (IDirect3DRMMeshBuilder)
GetQuality (IDirect3DRMMeshBuilder2)
GetQuality (IDirect3DRMProgressiveMesh)
GetQuality (IDirect3DRMDevice)
GetQuality (IDirect3DRMDevice2)
GetQuality (IDirect3DRMMeshBuilder)
GetQuality (IDirect3DRMMeshBuilder2)
GetQuality (IDirect3DRMProgressiveMesh)
GetRange
GetRange (IDirect3DRMLight)
GetRenderMode
GetRenderMode (IDirect3DRMDevice2)
GetRotation (IDirect3DRMFrame)
GetRotation (IDirect3DRMFrame2)
GetRotation (IDirect3DRMFrame)
GetRotation (IDirect3DRMFrame2)
GetScene (IDirect3DRMFrame)
GetScene (IDirect3DRMFrame2)
GetScene (IDirect3DRMFrame)
GetScene (IDirect3DRMFrame2)
GetSceneBackground (IDirect3DRMFrame)
GetSceneBackground (IDirect3DRMFrame2)
GetSceneBackground (IDirect3DRMFrame)
GetSceneBackground (IDirect3DRMFrame2)
GetSceneBackgroundDepth (IDirect3DRMFrame)
GetSceneBackgroundDepth (IDirect3DRMFrame2)
GetSceneBackgroundDepth (IDirect3DRMFrame)
GetSceneBackgroundDepth (IDirect3DRMFrame2)
GetSceneFogColor (IDirect3DRMFrame)
GetSceneFogColor (IDirect3DRMFrame2)
GetSceneFogColor (IDirect3DRMFrame)
GetSceneFogColor (IDirect3DRMFrame2)
GetSceneFogEnable (IDirect3DRMFrame)
GetSceneFogEnable (IDirect3DRMFrame2)
GetSceneFogEnable (IDirect3DRMFrame)
GetSceneFogEnable (IDirect3DRMFrame2)
GetSceneFogMode (IDirect3DRMFrame)
GetSceneFogMode (IDirect3DRMFrame2)
GetSceneFogMode (IDirect3DRMFrame)
GetSceneFogMode (IDirect3DRMFrame2)
GetSceneFogParams (IDirect3DRMFrame)
GetSceneFogParams (IDirect3DRMFrame2)
GetSceneFogParams (IDirect3DRMFrame)
GetSceneFogParams (IDirect3DRMFrame2)
GetSearchPath (IDirect3DRM)
GetSearchPath (IDirect3DRM2)
GetSearchPath (IDirect3DRM)
GetSearchPath (IDirect3DRM2)
GetShades (IDirect3DRMDevice)
GetShades (IDirect3DRMDevice2)
GetShades (IDirect3DRMTexture)
GetShades (IDirect3DRMTexture2)
GetShades (IDirect3DRMDevice)
GetShades (IDirect3DRMDevice2)
GetShades (IDirect3DRMTexture)
GetShades (IDirect3DRMTexture2)
GetSize (IDirect3DRMArray)
GetSize (IDirect3DRMDeviceArray)
GetSize (IDirect3DRMFaceArray)
GetSize (IDirect3DRMFrameArray)
GetSize (IDirect3DRMLightArray)
GetSize (IDirect3DRMObjectArray)
GetSize (IDirect3DRMPicked2Array)
GetSize (IDirect3DRMPickedArray)
GetSize (IDirect3DRMViewportArray)
GetSize (IDirect3DRMVisualArray)
GetSize (IDirect3DRMArray)
GetSize (IDirect3DRMDeviceArray)
GetSize (IDirect3DRMFaceArray)
GetSize (IDirect3DRMFrameArray)
GetSize (IDirect3DRMLightArray)
GetSize (IDirect3DRMObjectArray)
GetSize (IDirect3DRMPicked2Array)
GetSize (IDirect3DRMPickedArray)
GetSize (IDirect3DRMViewportArray)
GetSize (IDirect3DRMVisualArray)
GetSortMode (IDirect3DRMFrame)
GetSortMode (IDirect3DRMFrame2)
GetSortMode (IDirect3DRMFrame)
GetSortMode (IDirect3DRMFrame2)
GetSpecular
GetSpecular (IDirect3DRMMaterial)
GetTexture (IDirect3DRMFace)
GetTexture (IDirect3DRMFrame)
GetTexture (IDirect3DRMFrame2)
GetTexture (IDirect3DRMFace)
GetTexture (IDirect3DRMFrame)
GetTexture (IDirect3DRMFrame2)
GetTextureCoordinateIndex
GetTextureCoordinateIndex (IDirect3DRMFace)
GetTextureCoordinates (IDirect3DRMFace)
GetTextureCoordinates (IDirect3DRMMeshBuilder)
GetTextureCoordinates (IDirect3DRMMeshBuilder2)
GetTextureCoordinates (IDirect3DRMFace)
GetTextureCoordinates (IDirect3DRMMeshBuilder)
GetTextureCoordinates (IDirect3DRMMeshBuilder2)
GetTextureQuality (IDirect3DRMDevice)
GetTextureQuality (IDirect3DRMDevice2)
GetTextureQuality (IDirect3DRMDevice)
GetTextureQuality (IDirect3DRMDevice2)
GetTextureTopology (IDirect3DRMFace)
GetTextureTopology (IDirect3DRMFrame)
GetTextureTopology (IDirect3DRMFrame2)
GetTextureTopology (IDirect3DRMFace)
GetTextureTopology (IDirect3DRMFrame)
GetTextureTopology (IDirect3DRMFrame2)
GetTransform (IDirect3DRMFrame)
GetTransform (IDirect3DRMFrame2)
GetTransform (IDirect3DRMFrame)
GetTransform (IDirect3DRMFrame2)
GetTrianglesDrawn (IDirect3DRMDevice)
GetTrianglesDrawn (IDirect3DRMDevice2)

More entries...


Index

A B C D E F G H I L M N P R S T U V W X Y Z

IDirect3D
IDirect3D::EnumDevices
IDirect3D::FindDevice
IDirect3DRM::AddSearchPath
IDirect3DRM::CreateAnimation
IDirect3DRM::CreateAnimationSet
IDirect3DRM::CreateDevice
IDirect3DRM::CreateDeviceFromClipper
IDirect3DRM::CreateDeviceFromD3D
IDirect3DRM::CreateDeviceFromSurface
IDirect3DRM::CreateFace
IDirect3DRM::CreateFrame
IDirect3DRM::CreateLight
IDirect3DRM::CreateLightRGB
IDirect3DRM::CreateMaterial
IDirect3DRM::CreateMesh
IDirect3DRM::CreateMeshBuilder
IDirect3DRM::CreateObject
IDirect3DRM::CreateShadow
IDirect3DRM::CreateTexture
IDirect3DRM::CreateTextureFromSurface
IDirect3DRM::CreateUserVisual
IDirect3DRM::CreateViewport
IDirect3DRM::CreateWrap
IDirect3DRM::EnumerateObjects
IDirect3DRM::GetDevices
IDirect3DRM::GetNamedObject
IDirect3DRM::GetSearchPath
IDirect3DRM::Load
IDirect3DRM::LoadTexture
IDirect3DRM::LoadTextureFromResource
IDirect3DRM::SetDefaultTextureColors
IDirect3DRM::SetDefaultTextureShades
IDirect3DRM::SetSearchPath
IDirect3DRM::Tick
IDirect3DRM2::AddSearchPath
IDirect3DRM2::CreateAnimation
IDirect3DRM2::CreateAnimationSet
IDirect3DRM2::CreateDevice
IDirect3DRM2::CreateDeviceFromClipper
IDirect3DRM2::CreateDeviceFromD3D
IDirect3DRM2::CreateDeviceFromSurface
IDirect3DRM2::CreateFace
IDirect3DRM2::CreateFrame
IDirect3DRM2::CreateLight
IDirect3DRM2::CreateLightRGB
IDirect3DRM2::CreateMaterial
IDirect3DRM2::CreateMesh
IDirect3DRM2::CreateMeshBuilder
IDirect3DRM2::CreateObject
IDirect3DRM2::CreateProgressiveMesh
IDirect3DRM2::CreateShadow
IDirect3DRM2::CreateTexture
IDirect3DRM2::CreateTextureFromSurface
IDirect3DRM2::CreateUserVisual
IDirect3DRM2::CreateViewport
IDirect3DRM2::CreateWrap
IDirect3DRM2::EnumerateObjects
IDirect3DRM2::GetDevices
IDirect3DRM2::GetNamedObject
IDirect3DRM2::GetSearchPath
IDirect3DRM2::Load
IDirect3DRM2::LoadTexture
IDirect3DRM2::LoadTextureFromResource
IDirect3DRM2::SetDefaultTextureColors
IDirect3DRM2::SetDefaultTextureShades
IDirect3DRM2::SetSearchPath
IDirect3DRM2::Tick
IDirect3DRMAnimation::AddPositionKey
IDirect3DRMAnimation::AddRotateKey
IDirect3DRMAnimation::AddScaleKey
IDirect3DRMAnimation::DeleteKey
IDirect3DRMAnimation::GetOptions
IDirect3DRMAnimation::SetFrame
IDirect3DRMAnimation::SetOptions
IDirect3DRMAnimation::SetTime
IDirect3DRMAnimationSet::AddAnimation
IDirect3DRMAnimationSet::DeleteAnimation
IDirect3DRMAnimationSet::Load
IDirect3DRMAnimationSet::SetTime
IDirect3DRMArray::GetSize
IDirect3DRMDevice::AddUpdateCallback
IDirect3DRMDevice::DeleteUpdateCallback
IDirect3DRMDevice::GetBufferCount
IDirect3DRMDevice::GetColorModel
IDirect3DRMDevice::GetDirect3DDevice
IDirect3DRMDevice::GetDither
IDirect3DRMDevice::GetHeight
IDirect3DRMDevice::GetQuality
IDirect3DRMDevice::GetShades
IDirect3DRMDevice::GetTextureQuality
IDirect3DRMDevice::GetTrianglesDrawn
IDirect3DRMDevice::GetViewports
IDirect3DRMDevice::GetWidth
IDirect3DRMDevice::GetWireframeOptions
IDirect3DRMDevice::Init
IDirect3DRMDevice::InitFromClipper
IDirect3DRMDevice::InitFromD3D
IDirect3DRMDevice::SetBufferCount
IDirect3DRMDevice::SetDither
IDirect3DRMDevice::SetQuality
IDirect3DRMDevice::SetShades
IDirect3DRMDevice::SetTextureQuality
IDirect3DRMDevice::Update
IDirect3DRMDevice2::AddUpdateCallback
IDirect3DRMDevice2::DeleteUpdateCallback
IDirect3DRMDevice2::GetBufferCount
IDirect3DRMDevice2::GetColorModel
IDirect3DRMDevice2::GetDirect3DDevice2
IDirect3DRMDevice2::GetDither
IDirect3DRMDevice2::GetHeight
IDirect3DRMDevice2::GetQuality
IDirect3DRMDevice2::GetRenderMode
IDirect3DRMDevice2::GetShades
IDirect3DRMDevice2::GetTextureQuality
IDirect3DRMDevice2::GetTrianglesDrawn
IDirect3DRMDevice2::GetViewports
IDirect3DRMDevice2::GetWidth
IDirect3DRMDevice2::GetWireframeOptions
IDirect3DRMDevice2::Init
IDirect3DRMDevice2::InitFromClipper
IDirect3DRMDevice2::InitFromD3D2
IDirect3DRMDevice2::InitFromSurface
IDirect3DRMDevice2::SetBufferCount
IDirect3DRMDevice2::SetDither
IDirect3DRMDevice2::SetQuality
IDirect3DRMDevice2::SetRenderMode
IDirect3DRMDevice2::SetShades
IDirect3DRMDevice2::SetTextureQuality
IDirect3DRMDevice2::Update
IDirect3DRMDeviceArray::GetElement
IDirect3DRMDeviceArray::GetSize
IDirect3DRMFace::AddVertex
IDirect3DRMFace::AddVertexAndNormalIndexed
IDirect3DRMFace::GetColor
IDirect3DRMFace::GetMaterial
IDirect3DRMFace::GetNormal
IDirect3DRMFace::GetTexture
IDirect3DRMFace::GetTextureCoordinateIndex
IDirect3DRMFace::GetTextureCoordinates
IDirect3DRMFace::GetTextureTopology
IDirect3DRMFace::GetVertex
IDirect3DRMFace::GetVertexCount
IDirect3DRMFace::GetVertexIndex
IDirect3DRMFace::GetVertices
IDirect3DRMFace::SetColor
IDirect3DRMFace::SetColorRGB
IDirect3DRMFace::SetMaterial
IDirect3DRMFace::SetTexture
IDirect3DRMFace::SetTextureCoordinates
IDirect3DRMFace::SetTextureTopology
IDirect3DRMFaceArray::GetElement
IDirect3DRMFaceArray::GetSize
IDirect3DRMFrame::AddChild
IDirect3DRMFrame::AddLight
IDirect3DRMFrame::AddMoveCallback
IDirect3DRMFrame::AddRotation
IDirect3DRMFrame::AddScale
IDirect3DRMFrame::AddTransform
IDirect3DRMFrame::AddTranslation
IDirect3DRMFrame::AddVisual
IDirect3DRMFrame::DeleteChild
IDirect3DRMFrame::DeleteLight
IDirect3DRMFrame::DeleteMoveCallback
IDirect3DRMFrame::DeleteVisual
IDirect3DRMFrame::GetChildren
IDirect3DRMFrame::GetColor
IDirect3DRMFrame::GetLights
IDirect3DRMFrame::GetMaterialMode
IDirect3DRMFrame::GetOrientation
IDirect3DRMFrame::GetParent
IDirect3DRMFrame::GetPosition
IDirect3DRMFrame::GetRotation
IDirect3DRMFrame::GetScene
IDirect3DRMFrame::GetSceneBackground
IDirect3DRMFrame::GetSceneBackgroundDepth
IDirect3DRMFrame::GetSceneFogColor
IDirect3DRMFrame::GetSceneFogEnable
IDirect3DRMFrame::GetSceneFogMode
IDirect3DRMFrame::GetSceneFogParams
IDirect3DRMFrame::GetSortMode
IDirect3DRMFrame::GetTexture
IDirect3DRMFrame::GetTextureTopology
IDirect3DRMFrame::GetTransform
IDirect3DRMFrame::GetVelocity
IDirect3DRMFrame::GetVisuals
IDirect3DRMFrame::GetZbufferMode
IDirect3DRMFrame::InverseTransform
IDirect3DRMFrame::Load
IDirect3DRMFrame::LookAt
IDirect3DRMFrame::Move
IDirect3DRMFrame::SetColor
IDirect3DRMFrame::SetColorRGB
IDirect3DRMFrame::SetMaterialMode
IDirect3DRMFrame::SetOrientation
IDirect3DRMFrame::SetPosition
IDirect3DRMFrame::SetRotation
IDirect3DRMFrame::SetSceneBackground
IDirect3DRMFrame::SetSceneBackgroundDepth
IDirect3DRMFrame::SetSceneBackgroundImage
IDirect3DRMFrame::SetSceneBackgroundRGB
IDirect3DRMFrame::SetSceneFogColor
IDirect3DRMFrame::SetSceneFogEnable
IDirect3DRMFrame::SetSceneFogMode
IDirect3DRMFrame::SetSceneFogParams
IDirect3DRMFrame::SetSortMode
IDirect3DRMFrame::SetTexture
IDirect3DRMFrame::SetTextureTopology
IDirect3DRMFrame::SetVelocity
IDirect3DRMFrame::SetZbufferMode
IDirect3DRMFrame::Transform
IDirect3DRMFrame2::AddChild
IDirect3DRMFrame2::AddLight
IDirect3DRMFrame2::AddMoveCallback2
IDirect3DRMFrame2::AddRotation
IDirect3DRMFrame2::AddScale
IDirect3DRMFrame2::AddTransform
IDirect3DRMFrame2::AddTranslation
IDirect3DRMFrame2::AddVisual
IDirect3DRMFrame2::DeleteChild
IDirect3DRMFrame2::DeleteLight
IDirect3DRMFrame2::DeleteMoveCallback
IDirect3DRMFrame2::DeleteVisual
IDirect3DRMFrame2::GetAxes
IDirect3DRMFrame2::GetBox
IDirect3DRMFrame2::GetBoxEnable
IDirect3DRMFrame2::GetChildren
IDirect3DRMFrame2::GetColor
IDirect3DRMFrame2::GetHierarchyBox
IDirect3DRMFrame2::GetInheritAxes
IDirect3DRMFrame2::GetLights
IDirect3DRMFrame2::GetMaterial
IDirect3DRMFrame2::GetMaterialMode
IDirect3DRMFrame2::GetOrientation
IDirect3DRMFrame2::GetParent
IDirect3DRMFrame2::GetPosition
IDirect3DRMFrame2::GetRotation
IDirect3DRMFrame2::GetScene
IDirect3DRMFrame2::GetSceneBackground
IDirect3DRMFrame2::GetSceneBackgroundDepth
IDirect3DRMFrame2::GetSceneFogColor
IDirect3DRMFrame2::GetSceneFogEnable
IDirect3DRMFrame2::GetSceneFogMode
IDirect3DRMFrame2::GetSceneFogParams
IDirect3DRMFrame2::GetSortMode
IDirect3DRMFrame2::GetTexture
IDirect3DRMFrame2::GetTextureTopology
IDirect3DRMFrame2::GetTransform
IDirect3DRMFrame2::GetVelocity
IDirect3DRMFrame2::GetVisuals
IDirect3DRMFrame2::GetZbufferMode
IDirect3DRMFrame2::InverseTransform
IDirect3DRMFrame2::Load
IDirect3DRMFrame2::LookAt
IDirect3DRMFrame2::Move
IDirect3DRMFrame2::RayPick
IDirect3DRMFrame2::Save
IDirect3DRMFrame2::SetAxes
IDirect3DRMFrame2::SetBox
IDirect3DRMFrame2::SetBoxEnable
IDirect3DRMFrame2::SetColor
IDirect3DRMFrame2::SetColorRGB
IDirect3DRMFrame2::SetInheritAxes
IDirect3DRMFrame2::SetMaterial
IDirect3DRMFrame2::SetMaterialMode
IDirect3DRMFrame2::SetOrientation
IDirect3DRMFrame2::SetPosition
IDirect3DRMFrame2::SetQuaternion
IDirect3DRMFrame2::SetRotation
IDirect3DRMFrame2::SetSceneBackground
IDirect3DRMFrame2::SetSceneBackgroundDepth
IDirect3DRMFrame2::SetSceneBackgroundImage
IDirect3DRMFrame2::SetSceneBackgroundRGB
IDirect3DRMFrame2::SetSceneFogColor
IDirect3DRMFrame2::SetSceneFogEnable
IDirect3DRMFrame2::SetSceneFogMode
IDirect3DRMFrame2::SetSceneFogParams
IDirect3DRMFrame2::SetSortMode
IDirect3DRMFrame2::SetTexture
IDirect3DRMFrame2::SetTextureTopology
IDirect3DRMFrame2::SetVelocity
IDirect3DRMFrame2::SetZbufferMode
IDirect3DRMFrame2::Transform
IDirect3DRMFrameArray::GetElement
IDirect3DRMFrameArray::GetSize
IDirect3DRMInterpolator::AttachObject
IDirect3DRMInterpolator::DetachObject
IDirect3DRMInterpolator::GetAttachedObjects
IDirect3DRMInterpolator::GetIndex
IDirect3DRMInterpolator::Interpolate
IDirect3DRMInterpolator::SetIndex
IDirect3DRMLight::GetColor
IDirect3DRMLight::GetConstantAttenuation
IDirect3DRMLight::GetEnableFrame
IDirect3DRMLight::GetLinearAttenuation
IDirect3DRMLight::GetPenumbra
IDirect3DRMLight::GetQuadraticAttenuation
IDirect3DRMLight::GetRange
IDirect3DRMLight::GetType
IDirect3DRMLight::GetUmbra
IDirect3DRMLight::SetColor
IDirect3DRMLight::SetColorRGB
IDirect3DRMLight::SetConstantAttenuation
IDirect3DRMLight::SetEnableFrame
IDirect3DRMLight::SetLinearAttenuation
IDirect3DRMLight::SetPenumbra
IDirect3DRMLight::SetQuadraticAttenuation
IDirect3DRMLight::SetRange
IDirect3DRMLight::SetType
IDirect3DRMLight::SetUmbra
IDirect3DRMLightArray::GetElement
IDirect3DRMLightArray::GetSize
IDirect3DRMMaterial::GetEmissive
IDirect3DRMMaterial::GetPower
IDirect3DRMMaterial::GetSpecular
IDirect3DRMMaterial::SetEmissive
IDirect3DRMMaterial::SetPower
IDirect3DRMMaterial::SetSpecular
IDirect3DRMMesh::AddGroup
IDirect3DRMMesh::GetBox
IDirect3DRMMesh::GetGroup
IDirect3DRMMesh::GetGroupColor
IDirect3DRMMesh::GetGroupCount
IDirect3DRMMesh::GetGroupMapping
IDirect3DRMMesh::GetGroupMaterial
IDirect3DRMMesh::GetGroupQuality
IDirect3DRMMesh::GetGroupTexture
IDirect3DRMMesh::GetVertices
IDirect3DRMMesh::Scale
IDirect3DRMMesh::SetGroupColor

More entries...


Index

A B C D E F G H I L M N P R S T U V W X Y Z

GetTrianglesDrawn (IDirect3DRMDevice)
GetTrianglesDrawn (IDirect3DRMDevice2)
GetType
GetType (IDirect3DRMLight)
GetUmbra
GetUmbra (IDirect3DRMLight)
GetUniformScaling
GetUniformScaling (IDirect3DRMViewport)
GetVelocity (IDirect3DRMFrame)
GetVelocity (IDirect3DRMFrame2)
GetVelocity (IDirect3DRMFrame)
GetVelocity (IDirect3DRMFrame2)
GetVertex
GetVertex (IDirect3DRMFace)
GetVertexColor (IDirect3DRMMeshBuilder)
GetVertexColor (IDirect3DRMMeshBuilder2)
GetVertexColor (IDirect3DRMMeshBuilder)
GetVertexColor (IDirect3DRMMeshBuilder2)
GetVertexCount (IDirect3DRMFace)
GetVertexCount (IDirect3DRMMeshBuilder)
GetVertexCount (IDirect3DRMMeshBuilder2)
GetVertexCount (IDirect3DRMFace)
GetVertexCount (IDirect3DRMMeshBuilder)
GetVertexCount (IDirect3DRMMeshBuilder2)
GetVertexDetail
GetVertexDetail (IDirect3DRMProgressiveMesh)
GetVertexDetailRange
GetVertexDetailRange (IDirect3DRMProgressiveMesh)
GetVertexIndex
GetVertexIndex (IDirect3DRMFace)
GetVertices (IDirect3DRMFace)
GetVertices (IDirect3DRMMesh)
GetVertices (IDirect3DRMMeshBuilder)
GetVertices (IDirect3DRMMeshBuilder2)
GetVertices (IDirect3DRMFace)
GetVertices (IDirect3DRMMesh)
GetVertices (IDirect3DRMMeshBuilder)
GetVertices (IDirect3DRMMeshBuilder2)
GetViewports (IDirect3DRMDevice)
GetViewports (IDirect3DRMDevice2)
GetViewports (IDirect3DRMDevice)
GetViewports (IDirect3DRMDevice2)
GetVisuals (IDirect3DRMFrame)
GetVisuals (IDirect3DRMFrame2)
GetVisuals (IDirect3DRMFrame)
GetVisuals (IDirect3DRMFrame2)
GetWidth (IDirect3DRMDevice)
GetWidth (IDirect3DRMDevice2)
GetWidth (IDirect3DRMViewport)
GetWidth (IDirect3DRMDevice)
GetWidth (IDirect3DRMDevice2)
GetWidth (IDirect3DRMViewport)
GetWireframeOptions (IDirect3DRMDevice)
GetWireframeOptions (IDirect3DRMDevice2)
GetWireframeOptions (IDirect3DRMDevice)
GetWireframeOptions (IDirect3DRMDevice2)
GetX
GetX (IDirect3DRMViewport)
GetY
GetY (IDirect3DRMViewport)
GetZbufferMode (IDirect3DRMFrame)
GetZbufferMode (IDirect3DRMFrame2)
GetZbufferMode (IDirect3DRMFrame)
GetZbufferMode (IDirect3DRMFrame2)
green
green_mask


Index

A B C D E F G H I L M N P R S T U V W X Y Z

IDirect3DRMMesh::SetGroupColorRGB
IDirect3DRMMesh::SetGroupMapping
IDirect3DRMMesh::SetGroupMaterial
IDirect3DRMMesh::SetGroupQuality
IDirect3DRMMesh::SetGroupTexture
IDirect3DRMMesh::SetVertices
IDirect3DRMMesh::Translate
IDirect3DRMMeshBuilder::AddFace
IDirect3DRMMeshBuilder::AddFaces
IDirect3DRMMeshBuilder::AddFrame
IDirect3DRMMeshBuilder::AddMesh
IDirect3DRMMeshBuilder::AddMeshBuilder
IDirect3DRMMeshBuilder::AddNormal
IDirect3DRMMeshBuilder::AddVertex
IDirect3DRMMeshBuilder::CreateFace
IDirect3DRMMeshBuilder::CreateMesh
IDirect3DRMMeshBuilder::GenerateNormals
IDirect3DRMMeshBuilder::GetBox
IDirect3DRMMeshBuilder::GetColorSource
IDirect3DRMMeshBuilder::GetFaceCount
IDirect3DRMMeshBuilder::GetFaces
IDirect3DRMMeshBuilder::GetPerspective
IDirect3DRMMeshBuilder::GetQuality
IDirect3DRMMeshBuilder::GetTextureCoordinates
IDirect3DRMMeshBuilder::GetVertexColor
IDirect3DRMMeshBuilder::GetVertexCount
IDirect3DRMMeshBuilder::GetVertices
IDirect3DRMMeshBuilder::Load
IDirect3DRMMeshBuilder::ReserveSpace
IDirect3DRMMeshBuilder::Save
IDirect3DRMMeshBuilder::Scale
IDirect3DRMMeshBuilder::SetColor
IDirect3DRMMeshBuilder::SetColorRGB
IDirect3DRMMeshBuilder::SetColorSource
IDirect3DRMMeshBuilder::SetMaterial
IDirect3DRMMeshBuilder::SetNormal
IDirect3DRMMeshBuilder::SetPerspective
IDirect3DRMMeshBuilder::SetQuality
IDirect3DRMMeshBuilder::SetTexture
IDirect3DRMMeshBuilder::SetTextureCoordinates
IDirect3DRMMeshBuilder::SetTextureTopology
IDirect3DRMMeshBuilder::SetVertex
IDirect3DRMMeshBuilder::SetVertexColor
IDirect3DRMMeshBuilder::SetVertexColorRGB
IDirect3DRMMeshBuilder::Translate
IDirect3DRMMeshBuilder2::AddFace
IDirect3DRMMeshBuilder2::AddFaces
IDirect3DRMMeshBuilder2::AddFrame
IDirect3DRMMeshBuilder2::AddMesh
IDirect3DRMMeshBuilder2::AddMeshBuilder
IDirect3DRMMeshBuilder2::AddNormal
IDirect3DRMMeshBuilder2::AddVertex
IDirect3DRMMeshBuilder2::CreateFace
IDirect3DRMMeshBuilder2::CreateMesh
IDirect3DRMMeshBuilder2::GenerateNormals2
IDirect3DRMMeshBuilder2::GetBox
IDirect3DRMMeshBuilder2::GetColorSource
IDirect3DRMMeshBuilder2::GetFace
IDirect3DRMMeshBuilder2::GetFaceCount
IDirect3DRMMeshBuilder2::GetFaces
IDirect3DRMMeshBuilder2::GetPerspective
IDirect3DRMMeshBuilder2::GetQuality
IDirect3DRMMeshBuilder2::GetTextureCoordinates
IDirect3DRMMeshBuilder2::GetVertexColor
IDirect3DRMMeshBuilder2::GetVertexCount
IDirect3DRMMeshBuilder2::GetVertices
IDirect3DRMMeshBuilder2::Load
IDirect3DRMMeshBuilder2::ReserveSpace
IDirect3DRMMeshBuilder2::Save
IDirect3DRMMeshBuilder2::Scale
IDirect3DRMMeshBuilder2::SetColor
IDirect3DRMMeshBuilder2::SetColorRGB
IDirect3DRMMeshBuilder2::SetColorSource
IDirect3DRMMeshBuilder2::SetMaterial
IDirect3DRMMeshBuilder2::SetNormal
IDirect3DRMMeshBuilder2::SetPerspective
IDirect3DRMMeshBuilder2::SetQuality
IDirect3DRMMeshBuilder2::SetTexture
IDirect3DRMMeshBuilder2::SetTextureCoordinates
IDirect3DRMMeshBuilder2::SetTextureTopology
IDirect3DRMMeshBuilder2::SetVertex
IDirect3DRMMeshBuilder2::SetVertexColor
IDirect3DRMMeshBuilder2::SetVertexColorRGB
IDirect3DRMMeshBuilder2::Translate
IDirect3DRMObject::AddDestroyCallback
IDirect3DRMObject::Clone
IDirect3DRMObject::DeleteDestroyCallback
IDirect3DRMObject::GetAppData
IDirect3DRMObject::GetClassName
IDirect3DRMObject::GetName
IDirect3DRMObject::SetAppData
IDirect3DRMObject::SetName
IDirect3DRMObjectArray::GetElement
IDirect3DRMObjectArray::GetSize
IDirect3DRMPicked2Array::GetPick
IDirect3DRMPicked2Array::GetSize
IDirect3DRMPickedArray::GetPick
IDirect3DRMPickedArray::GetSize
IDirect3DRMProgressiveMesh::Abort
IDirect3DRMProgressiveMesh::Clone
IDirect3DRMProgressiveMesh::CreateMesh
IDirect3DRMProgressiveMesh::Duplicate
IDirect3DRMProgressiveMesh::GetBox
IDirect3DRMProgressiveMesh::GetDetail
IDirect3DRMProgressiveMesh::GetFaceDetail
IDirect3DRMProgressiveMesh::GetFaceDetailRange
IDirect3DRMProgressiveMesh::GetLoadStatus
IDirect3DRMProgressiveMesh::GetQuality
IDirect3DRMProgressiveMesh::GetVertexDetail
IDirect3DRMProgressiveMesh::GetVertexDetailRange
IDirect3DRMProgressiveMesh::Load
IDirect3DRMProgressiveMesh::RegisterEvents
IDirect3DRMProgressiveMesh::SetDetail
IDirect3DRMProgressiveMesh::SetFaceDetail
IDirect3DRMProgressiveMesh::SetMinRenderDetail
IDirect3DRMProgressiveMesh::SetQuality
IDirect3DRMProgressiveMesh::SetVertexDetail
IDirect3DRMShadow::Init
IDirect3DRMTexture::Changed
IDirect3DRMTexture::GetColors
IDirect3DRMTexture::GetDecalOrigin
IDirect3DRMTexture::GetDecalScale
IDirect3DRMTexture::GetDecalSize
IDirect3DRMTexture::GetDecalTransparency
IDirect3DRMTexture::GetDecalTransparentColor
IDirect3DRMTexture::GetImage
IDirect3DRMTexture::GetShades
IDirect3DRMTexture::InitFromFile
IDirect3DRMTexture::InitFromResource
IDirect3DRMTexture::InitFromSurface
IDirect3DRMTexture::SetColors
IDirect3DRMTexture::SetDecalOrigin
IDirect3DRMTexture::SetDecalScale
IDirect3DRMTexture::SetDecalSize
IDirect3DRMTexture::SetDecalTransparency
IDirect3DRMTexture::SetDecalTransparentColor
IDirect3DRMTexture::SetShades
IDirect3DRMTexture2::Changed
IDirect3DRMTexture2::GenerateMIPMap
IDirect3DRMTexture2::GetColors
IDirect3DRMTexture2::GetDecalOrigin
IDirect3DRMTexture2::GetDecalScale
IDirect3DRMTexture2::GetDecalSize
IDirect3DRMTexture2::GetDecalTransparency
IDirect3DRMTexture2::GetDecalTransparentColor
IDirect3DRMTexture2::GetImage
IDirect3DRMTexture2::GetShades
IDirect3DRMTexture2::InitFromFile
IDirect3DRMTexture2::InitFromImage
IDirect3DRMTexture2::InitFromResource2
IDirect3DRMTexture2::InitFromSurface
IDirect3DRMTexture2::SetColors
IDirect3DRMTexture2::SetDecalOrigin
IDirect3DRMTexture2::SetDecalScale
IDirect3DRMTexture2::SetDecalSize
IDirect3DRMTexture2::SetDecalTransparency
IDirect3DRMTexture2::SetDecalTransparentColor
IDirect3DRMTexture2::SetShades
IDirect3DRMUserVisual::Init
IDirect3DRMViewport::Clear
IDirect3DRMViewport::Configure
IDirect3DRMViewport::ForceUpdate
IDirect3DRMViewport::GetBack
IDirect3DRMViewport::GetCamera
IDirect3DRMViewport::GetDevice
IDirect3DRMViewport::GetDirect3DViewport
IDirect3DRMViewport::GetField
IDirect3DRMViewport::GetFront
IDirect3DRMViewport::GetHeight
IDirect3DRMViewport::GetPlane
IDirect3DRMViewport::GetProjection
IDirect3DRMViewport::GetUniformScaling
IDirect3DRMViewport::GetWidth
IDirect3DRMViewport::GetX
IDirect3DRMViewport::GetY
IDirect3DRMViewport::Init
IDirect3DRMViewport::InverseTransform
IDirect3DRMViewport::Pick
IDirect3DRMViewport::Render
IDirect3DRMViewport::SetBack
IDirect3DRMViewport::SetCamera
IDirect3DRMViewport::SetField
IDirect3DRMViewport::SetFront
IDirect3DRMViewport::SetPlane
IDirect3DRMViewport::SetProjection
IDirect3DRMViewport::SetUniformScaling
IDirect3DRMViewport::Transform
IDirect3DRMViewportArray::GetElement
IDirect3DRMViewportArray::GetSize
IDirect3DRMVisualArray::GetElement
IDirect3DRMVisualArray::GetSize
IDirect3DRMWinDevice::HandleActivate
IDirect3DRMWinDevice::HandlePaint
IDirect3DRMWrap::Apply
IDirect3DRMWrap::ApplyRelative
IDirect3DRMWrap::Init
IDirectDrawClipper
IDirectDrawClipper::SetHWnd
Init (IDirect3DRMDevice)
Init (IDirect3DRMDevice2)
Init (IDirect3DRMShadow)
Init (IDirect3DRMUserVisual)
Init (IDirect3DRMViewport)
Init (IDirect3DRMWrap)
Init (IDirect3DRMDevice)
Init (IDirect3DRMDevice2)
Init (IDirect3DRMShadow)
Init (IDirect3DRMUserVisual)
Init (IDirect3DRMViewport)
Init (IDirect3DRMWrap)
InitFromClipper (IDirect3DRMDevice)
InitFromClipper (IDirect3DRMDevice2)
InitFromClipper (IDirect3DRMDevice)
InitFromClipper (IDirect3DRMDevice2)
InitFromD3D
InitFromD3D (IDirect3DRMDevice)
InitFromD3D2
InitFromD3D2 (IDirect3DRMDevice2)
InitFromFile (IDirect3DRMTexture)
InitFromFile (IDirect3DRMTexture2)
InitFromFile (IDirect3DRMTexture)
InitFromFile (IDirect3DRMTexture2)
InitFromImage
InitFromImage (IDirect3DRMTexture2)
InitFromResource
InitFromResource (IDirect3DRMTexture)
InitFromResource2
InitFromResource2 (IDirect3DRMTexture2)
InitFromSurface (IDirect3DRMDevice2)
InitFromSurface (IDirect3DRMTexture)
InitFromSurface (IDirect3DRMTexture2)
InitFromSurface (IDirect3DRMDevice2)
InitFromSurface (IDirect3DRMTexture)
InitFromSurface (IDirect3DRMTexture2)
Interpolate
Interpolate (IDirect3DRMInterpolator)
InverseTransform (IDirect3DRMFrame)
InverseTransform (IDirect3DRMFrame2)
InverseTransform (IDirect3DRMViewport)
InverseTransform (IDirect3DRMFrame)
InverseTransform (IDirect3DRMFrame2)
InverseTransform (IDirect3DRMViewport)
IUnknown Interface
IUnknown::AddRef
IUnknown::QueryInterface
IUnknown::Release


Index

A B C D E F G H I L M N P R S T U V W X Y Z

A

Abort
Abort (IDirect3DRMProgressiveMesh)
AddAnimation
AddAnimation (IDirect3DRMAnimationSet)
AddChild (IDirect3DRMFrame)
AddChild (IDirect3DRMFrame2)
AddChild (IDirect3DRMFrame)
AddChild (IDirect3DRMFrame2)
AddDestroyCallback
AddDestroyCallback (IDirect3DRMObject)
AddFace (IDirect3DRMMeshBuilder)
AddFace (IDirect3DRMMeshBuilder2)
AddFace (IDirect3DRMMeshBuilder)
AddFace (IDirect3DRMMeshBuilder2)
AddFaces (IDirect3DRMMeshBuilder)
AddFaces (IDirect3DRMMeshBuilder2)
AddFaces (IDirect3DRMMeshBuilder)
AddFaces (IDirect3DRMMeshBuilder2)
AddFrame (IDirect3DRMMeshBuilder)
AddFrame (IDirect3DRMMeshBuilder2)
AddFrame (IDirect3DRMMeshBuilder)
AddFrame (IDirect3DRMMeshBuilder2)
AddGroup
AddGroup (IDirect3DRMMesh)
AddLight (IDirect3DRMFrame)
AddLight (IDirect3DRMFrame2)
AddLight (IDirect3DRMFrame)
AddLight (IDirect3DRMFrame2)
AddMesh (IDirect3DRMMeshBuilder)
AddMesh (IDirect3DRMMeshBuilder2)
AddMesh (IDirect3DRMMeshBuilder)
AddMesh (IDirect3DRMMeshBuilder2)
AddMeshBuilder (IDirect3DRMMeshBuilder)
AddMeshBuilder (IDirect3DRMMeshBuilder2)
AddMeshBuilder (IDirect3DRMMeshBuilder)
AddMeshBuilder (IDirect3DRMMeshBuilder2)
AddMoveCallback
AddMoveCallback (IDirect3DRMFrame)
AddMoveCallback2
AddMoveCallback2 (IDirect3DRMFrame2)
AddNormal (IDirect3DRMMeshBuilder)
AddNormal (IDirect3DRMMeshBuilder2)
AddNormal (IDirect3DRMMeshBuilder)
AddNormal (IDirect3DRMMeshBuilder2)
AddPositionKey
AddPositionKey (IDirect3DRMAnimation)
AddRotateKey
AddRotateKey (IDirect3DRMAnimation)
AddRotation (IDirect3DRMFrame)
AddRotation (IDirect3DRMFrame2)
AddRotation (IDirect3DRMFrame)
AddRotation (IDirect3DRMFrame2)
AddScale (IDirect3DRMFrame)
AddScale (IDirect3DRMFrame2)
AddScale (IDirect3DRMFrame)
AddScale (IDirect3DRMFrame2)
AddScaleKey
AddScaleKey (IDirect3DRMAnimation)
AddSearchPath (IDirect3DRM)
AddSearchPath (IDirect3DRM2)
AddSearchPath (IDirect3DRM)
AddSearchPath (IDirect3DRM2)
AddTransform (IDirect3DRMFrame)
AddTransform (IDirect3DRMFrame2)
AddTransform (IDirect3DRMFrame)
AddTransform (IDirect3DRMFrame2)
AddTranslation (IDirect3DRMFrame)
AddTranslation (IDirect3DRMFrame2)
AddTranslation (IDirect3DRMFrame)
AddTranslation (IDirect3DRMFrame2)
AddUpdateCallback (IDirect3DRMDevice)
AddUpdateCallback (IDirect3DRMDevice2)
AddUpdateCallback (IDirect3DRMDevice)
AddUpdateCallback (IDirect3DRMDevice2)
AddVertex (IDirect3DRMFace)
AddVertex (IDirect3DRMMeshBuilder)
AddVertex (IDirect3DRMMeshBuilder2)
AddVertex (IDirect3DRMFace)
AddVertex (IDirect3DRMMeshBuilder)
AddVertex (IDirect3DRMMeshBuilder2)
AddVertexAndNormalIndexed
AddVertexAndNormalIndexed (IDirect3DRMFace)
AddVisual (IDirect3DRMFrame)
AddVisual (IDirect3DRMFrame2)
AddVisual (IDirect3DRMFrame)
AddVisual (IDirect3DRMFrame2)
alpha_mask
ambient
Apply
Apply (IDirect3DRMWrap)
ApplyRelative
ApplyRelative (IDirect3DRMWrap)
array object
aspectx
aspecty
AttachObject
AttachObject (IDirect3DRMInterpolator)

B

back buffer
back clipping plane
blue
blue_mask
buffer1
buffer2
bytes_per_line

C

camera
Changed (IDirect3DRMTexture)
Changed (IDirect3DRMTexture2)
Changed (IDirect3DRMTexture)
Changed (IDirect3DRMTexture2)
Clear
Clear (IDirect3DRMViewport)
Clone (IDirect3DRMObject)
Clone (IDirect3DRMProgressiveMesh)
Clone (IDirect3DRMObject)
Clone (IDirect3DRMProgressiveMesh)
color
Color Keying
Configure
Configure (IDirect3DRMViewport)
CreateAnimation (IDirect3DRM)
CreateAnimation (IDirect3DRM2)
CreateAnimation (IDirect3DRM)
CreateAnimation (IDirect3DRM2)
CreateAnimationSet (IDirect3DRM)
CreateAnimationSet (IDirect3DRM2)
CreateAnimationSet (IDirect3DRM)
CreateAnimationSet (IDirect3DRM2)
CreateDevice (IDirect3DRM)
CreateDevice (IDirect3DRM2)
CreateDevice (IDirect3DRM)
CreateDevice (IDirect3DRM2)
CreateDeviceFromClipper (IDirect3DRM)
CreateDeviceFromClipper (IDirect3DRM2)
CreateDeviceFromClipper (IDirect3DRM)
CreateDeviceFromClipper (IDirect3DRM2)
CreateDeviceFromD3D (IDirect3DRM)
CreateDeviceFromD3D (IDirect3DRM2)
CreateDeviceFromD3D (IDirect3DRM)
CreateDeviceFromD3D (IDirect3DRM2)
CreateDeviceFromSurface (IDirect3DRM)
CreateDeviceFromSurface (IDirect3DRM2)
CreateDeviceFromSurface (IDirect3DRM)
CreateDeviceFromSurface (IDirect3DRM2)
CreateFace (IDirect3DRM)
CreateFace (IDirect3DRM2)
CreateFace (IDirect3DRMMeshBuilder)
CreateFace (IDirect3DRMMeshBuilder2)
CreateFace (IDirect3DRM)
CreateFace (IDirect3DRM2)
CreateFace (IDirect3DRMMeshBuilder)
CreateFace (IDirect3DRMMeshBuilder2)
CreateFrame (IDirect3DRM)
CreateFrame (IDirect3DRM2)
CreateFrame (IDirect3DRM)
CreateFrame (IDirect3DRM2)
CreateLight (IDirect3DRM)
CreateLight (IDirect3DRM2)
CreateLight (IDirect3DRM)
CreateLight (IDirect3DRM2)
CreateLightRGB (IDirect3DRM)
CreateLightRGB (IDirect3DRM2)
CreateLightRGB (IDirect3DRM)
CreateLightRGB (IDirect3DRM2)
CreateMaterial (IDirect3DRM)
CreateMaterial (IDirect3DRM2)
CreateMaterial (IDirect3DRM)
CreateMaterial (IDirect3DRM2)
CreateMesh (IDirect3DRM)
CreateMesh (IDirect3DRM2)
CreateMesh (IDirect3DRMMeshBuilder)
CreateMesh (IDirect3DRMMeshBuilder2)
CreateMesh (IDirect3DRMProgressiveMesh)
CreateMesh (IDirect3DRM)
CreateMesh (IDirect3DRM2)
CreateMesh (IDirect3DRMMeshBuilder)
CreateMesh (IDirect3DRMMeshBuilder2)
CreateMesh (IDirect3DRMProgressiveMesh)
CreateMeshBuilder (IDirect3DRM)
CreateMeshBuilder (IDirect3DRM2)
CreateMeshBuilder (IDirect3DRM)
CreateMeshBuilder (IDirect3DRM2)
CreateObject (IDirect3DRM)
CreateObject (IDirect3DRM2)
CreateObject (IDirect3DRM)
CreateObject (IDirect3DRM2)
CreateProgressiveMesh
CreateProgressiveMesh (IDirect3DRM2)
CreateShadow (IDirect3DRM)
CreateShadow (IDirect3DRM2)
CreateShadow (IDirect3DRM)
CreateShadow (IDirect3DRM2)
CreateTexture (IDirect3DRM)
CreateTexture (IDirect3DRM2)
CreateTexture (IDirect3DRM)
CreateTexture (IDirect3DRM2)
CreateTextureFromSurface (IDirect3DRM)
CreateTextureFromSurface (IDirect3DRM2)
CreateTextureFromSurface (IDirect3DRM)
CreateTextureFromSurface (IDirect3DRM2)
CreateUserVisual (IDirect3DRM)
CreateUserVisual (IDirect3DRM2)
CreateUserVisual (IDirect3DRM)
CreateUserVisual (IDirect3DRM2)
CreateViewport (IDirect3DRM)
CreateViewport (IDirect3DRM2)
CreateViewport (IDirect3DRM)
CreateViewport (IDirect3DRM2)
CreateWrap (IDirect3DRM)
CreateWrap (IDirect3DRM2)
CreateWrap (IDirect3DRM)
CreateWrap (IDirect3DRM2)

More entries...


Index

A B C D E F G H I L M N P R S T U V W X Y Z

D

D3DCOLOR_MONO
D3DCOLOR_RGB
D3DCOLORMODEL
D3DDEVICEDESC
D3DENUMDEVICESCALLBACK
D3DMATRIX
D3DPATH
D3DPCMPCAPS_LESSEQUAL
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPRIMCAPS
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTADDRESSCAPS_WRAP
D3DPTBLENDCAPS_COPY
D3DPTBLENDCAPS_MODULATE
D3DPTEXTURECAPS_PERSPECTIVE
D3DPTEXTURECAPS_TRANSPARENCY
D3DPTFILTERCAPS_NEAREST
D3DRECT
D3DRM_OK
D3DRMANIMATION_CLOSED
D3DRMANIMATION_LINEARPOSITION
D3DRMANIMATION_OPEN
D3DRMANIMATION_POSITION
D3DRMANIMATION_SCALEANDROTATION
D3DRMANIMATION_SPLINEPOSITION
D3DRMANIMATIONOPTIONS
D3DRMBOX
D3DRMCOLOR_FROMFACE
D3DRMCOLOR_FROMVERTEX
D3DRMColorGetAlpha
D3DRMColorGetBlue
D3DRMColorGetGreen
D3DRMColorGetRed
D3DRMCOLORMODEL
D3DRMCOLORSOURCE
D3DRMCOMBINE_AFTER
D3DRMCOMBINE_BEFORE
D3DRMCOMBINE_REPLACE
D3DRMCOMBINETYPE
D3DRMCONSTRAIN_X
D3DRMCONSTRAIN_Y
D3DRMCONSTRAIN_Z
D3DRMCreateColorRGB
D3DRMCreateColorRGBA
D3DRMDEVICEPALETTECALLBACK
D3DRMERR_BADALLOC
D3DRMERR_BADDEVICE
D3DRMERR_BADFILE
D3DRMERR_BADMAJORVERSION
D3DRMERR_BADMINORVERSION
D3DRMERR_BADOBJECT
D3DRMERR_BADPMDATA
D3DRMERR_BADTYPE
D3DRMERR_BADVALUE
D3DRMERR_BOXNOTSET
D3DRMERR_CONNECTIONLOST
D3DRMERR_FACEUSED
D3DRMERR_FILENOTFOUND
D3DRMERR_INVALIDDATA
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTDONEYET
D3DRMERR_NOTENOUGHDATA
D3DRMERR_NOTFOUND
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE
D3DRMERR_REQUESTTOOSMALL
D3DRMERR_UNABLETOEXECUTE
D3DRMFILL_MASK
D3DRMFILL_MAX
D3DRMFILL_POINTS
D3DRMFILL_SOLID
D3DRMFILL_WIREFRAME
D3DRMFILLMODE
D3DRMFOG_EXPONENTIAL
D3DRMFOG_EXPONENTIALSQUARED
D3DRMFOG_LINEAR
D3DRMFOGMODE
D3DRMFRAMECONSTRAINT
D3DRMFRAMEMOVECALLBACK
D3DRMFREEFUNCTION
D3DRMIMAGE
D3DRMINTERPOLATION_CLOSED
D3DRMINTERPOLATION_LINEAR
D3DRMINTERPOLATION_NEAREST
D3DRMINTERPOLATION_OPEN
D3DRMINTERPOLATION_SLERPNORMALS
D3DRMINTERPOLATION_SPLINE
D3DRMINTERPOLATION_VERTEXCOLOR
D3DRMINTERPOLATIONOPTIONS
D3DRMLIGHT_AMBIENT
D3DRMLIGHT_DIRECTIONAL
D3DRMLIGHT_MASK
D3DRMLIGHT_MAX
D3DRMLIGHT_OFF
D3DRMLIGHT_ON
D3DRMLIGHT_PARALLELPOINT
D3DRMLIGHT_POINT
D3DRMLIGHT_SPOT
D3DRMLIGHTMODE
D3DRMLIGHTTYPE
D3DRMLOAD_ASYNCHRONOUS
D3DRMLOAD_BYGUID
D3DRMLOAD_BYNAME
D3DRMLOAD_BYPOSITION
D3DRMLOAD_FIRST
D3DRMLOAD_FROMFILE
D3DRMLOAD_FROMMEMORY
D3DRMLOAD_FROMRESOURCE
D3DRMLOAD_FROMURL
D3DRMLOAD_INSTANCEBYCOPYING
D3DRMLOAD_INSTANCEBYREFERENCE
D3DRMLOADCALLBACK
D3DRMLOADMEMORY
D3DRMLOADOPTIONS
D3DRMLOADRESOURCE
D3DRMLOADTEXTURECALLBACK
D3DRMMALLOCFUNCTION
D3DRMMAP_PERSPCORRECT
D3DRMMAP_WRAPU
D3DRMMAP_WRAPV
D3DRMMAPPING
D3DRMMAPPINGFLAG
D3DRMMATERIAL_FROMFRAME
D3DRMMATERIAL_FROMMESH
D3DRMMATERIAL_FROMPARENT
D3DRMMATERIALMODE
D3DRMMATRIX4D
D3DRMMatrixFromQuaternion
D3DRMOBJECTCALLBACK
D3DRMPALETTE_FREE
D3DRMPALETTE_READONLY
D3DRMPALETTE_RESERVED
D3DRMPALETTEENTRY
D3DRMPALETTEFLAGS
D3DRMPICKDESC
D3DRMPICKDESC2
D3DRMPMESHLOADSTATUS
D3DRMPROJECT_ORTHOGRAPHIC
D3DRMPROJECT_PERSPECTIVE
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
D3DRMPROJECTIONTYPE
D3DRMQUATERNION
D3DRMQuaternionFromRotation
D3DRMQuaternionMultiply
D3DRMQuaternionSlerp
D3DRMRAY
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES
D3DRMRAYPICK_INTERPOLATECOLOR
D3DRMRAYPICK_INTERPOLATENORMAL
D3DRMRAYPICK_INTERPOLATEUV
D3DRMRAYPICK_ONLYBOUNDINGBOXES
D3DRMREALLOCFUNCTION
D3DRMRENDER_FLAT
D3DRMRENDER_GOURAUD
D3DRMRENDER_PHONG
D3DRMRENDER_UNLITFLAT
D3DRMRENDER_WIREFRAME
D3DRMRENDERMODE_BLENDEDTRANSPARENCY
D3DRMRENDERMODE_SORTEDTRANSPARENCY
D3DRMRENDERQUALITY
D3DRMSAVE_TEXTURETOPOLOGY
D3DRMSAVEOPTIONS
D3DRMSHADEMODE
D3DRMSORT_BACKTOFRONT
D3DRMSORT_FROMPARENT
D3DRMSORT_FRONTTOBACK
D3DRMSORT_NONE
D3DRMSORTMODE
D3DRMTEXTURE_LINEAR
D3DRMTEXTURE_LINEARMIPLINEAR
D3DRMTEXTURE_LINEARMIPNEAREST
D3DRMTEXTURE_MIPLINEAR
D3DRMTEXTURE_MIPNEAREST
D3DRMTEXTURE_NEAREST
D3DRMTEXTUREQUALITY
D3DRMUPDATECALLBACK
D3DRMUSERVISUAL_CANSEE
D3DRMUSERVISUAL_RENDER
D3DRMUSERVISUALCALLBACK
D3DRMUSERVISUALREASON
D3DRMVECTOR4D
D3DRMVectorAdd
D3DRMVectorCrossProduct
D3DRMVectorDotProduct
D3DRMVectorModulus
D3DRMVectorNormalize
D3DRMVectorRandom
D3DRMVectorReflect
D3DRMVectorRotate
D3DRMVectorScale
D3DRMVectorSubtract
D3DRMVERTEX
D3DRMWIREFRAME_CULL (IDirect3DRMDevice::GetWireframeOptions)
D3DRMWIREFRAME_CULL (IDirect3DRMDevice2::GetWireframeOptions)
D3DRMWIREFRAME_HIDDENLINE (IDirect3DRMDevice::GetWireframeOptions)
D3DRMWIREFRAME_HIDDENLINE (IDirect3DRMDevice2::GetWireframeOptions)
D3DRMWRAP_CHROME
D3DRMWRAP_CYLINDER
D3DRMWRAP_FLAT
D3DRMWRAP_SPHERE
D3DRMWRAPCALLBACK
D3DRMWRAPTYPE
D3DRMXOF_BINARY
D3DRMXOF_COMPRESSED
D3DRMXOF_TEXT
D3DRMXOFFORMAT
D3DRMXOFSAVE_ALL
D3DRMXOFSAVE_MATERIALS
D3DRMXOFSAVE_NORMALS
D3DRMXOFSAVE_TEMPLATES
D3DRMXOFSAVE_TEXTURECOORDINATES
D3DRMXOFSAVE_TEXTURENAMES
D3DRMZBUFFER_DISABLE
D3DRMZBUFFER_ENABLE
D3DRMZBUFFER_FROMPARENT
D3DRMZBUFFERMODE
D3DTRIANGLE
D3DVALUE
D3DVECTOR
dcColor
decal
DeleteAnimation
DeleteAnimation (IDirect3DRMAnimationSet)
DeleteChild (IDirect3DRMFrame)
DeleteChild (IDirect3DRMFrame2)
DeleteChild (IDirect3DRMFrame)
DeleteChild (IDirect3DRMFrame2)
DeleteDestroyCallback
DeleteDestroyCallback (IDirect3DRMObject)
DeleteKey
DeleteKey (IDirect3DRMAnimation)
DeleteLight (IDirect3DRMFrame)
DeleteLight (IDirect3DRMFrame2)
DeleteLight (IDirect3DRMFrame)
DeleteLight (IDirect3DRMFrame2)
DeleteMoveCallback (IDirect3DRMFrame)
DeleteMoveCallback (IDirect3DRMFrame2)
DeleteMoveCallback (IDirect3DRMFrame)
DeleteMoveCallback (IDirect3DRMFrame2)
DeleteUpdateCallback (IDirect3DRMDevice)
DeleteUpdateCallback (IDirect3DRMDevice2)
DeleteUpdateCallback (IDirect3DRMDevice)
DeleteUpdateCallback (IDirect3DRMDevice2)
DeleteVisual (IDirect3DRMFrame)
DeleteVisual (IDirect3DRMFrame2)
DeleteVisual (IDirect3DRMFrame)
DeleteVisual (IDirect3DRMFrame2)
depth
DetachObject
DetachObject (IDirect3DRMInterpolator)
Direct3DRMCreate
DirectDrawCreate
DirectDrawCreateClipper
directional
DirectX File Format
dSize
Duplicate
Duplicate (IDirect3DRMProgressiveMesh)
dvDir
dvNormal
dvPos
dwBaseMeshSize
dwBytesLoaded
dwFacesLoaded
dwFlags
dwPMeshSize
dwSize
dwVerticesLoaded

E

emissive property
enable frame
EnumerateObjects (IDirect3DRM)
EnumerateObjects (IDirect3DRM2)
EnumerateObjects (IDirect3DRM)
EnumerateObjects (IDirect3DRM2)

F

flags
ForceUpdate
ForceUpdate (IDirect3DRMViewport)
front clipping plane

G

GenerateMIPMap to GetTrianglesDrawn
GetTrianglesDrawn (IDirect3DRMDevice) to green_mask

H

HandleActivate
HandleActivate (IDirect3DRMWinDevice)
HandlePaint
HandlePaint (IDirect3DRMWinDevice)
height
hModule

I

IDirect3D to IDirect3DRMMesh::SetGroupColor
IDirect3DRMMesh::SetGroupColorRGB to IUnknown::Release

L

lGroupIdx (D3DRMPICKDESC)
lGroupIdx (D3DRMPICKDESC2)
Load (IDirect3DRM)
Load (IDirect3DRM2)
Load (IDirect3DRMAnimationSet)
Load (IDirect3DRMFrame)
Load (IDirect3DRMFrame2)
Load (IDirect3DRMMeshBuilder)
Load (IDirect3DRMMeshBuilder2)
Load (IDirect3DRMProgressiveMesh)
Load (IDirect3DRM)
Load (IDirect3DRM2)
Load (IDirect3DRMAnimationSet)
Load (IDirect3DRMFrame)
Load (IDirect3DRMFrame2)
Load (IDirect3DRMMeshBuilder)
Load (IDirect3DRMMeshBuilder2)
Load (IDirect3DRMProgressiveMesh)
LoadTexture (IDirect3DRM)
LoadTexture (IDirect3DRM2)
LoadTexture (IDirect3DRM)
LoadTexture (IDirect3DRM2)
LoadTextureFromResource (IDirect3DRM)
LoadTextureFromResource (IDirect3DRM2)
LoadTextureFromResource (IDirect3DRM)
LoadTextureFromResource (IDirect3DRM2)
LookAt (IDirect3DRMFrame)
LookAt (IDirect3DRMFrame2)
LookAt (IDirect3DRMFrame)
LookAt (IDirect3DRMFrame2)
lpMemory
lpName
lpType

M

max
min
mipmap
Mipmaps
model coordinates
Move (IDirect3DRMFrame)
Move (IDirect3DRMFrame2)
Move (IDirect3DRMFrame)
Move (IDirect3DRMFrame2)

N

normal
normal vector

P

palette
palette_size
parallel point
penumbra
Pick
Pick (IDirect3DRMViewport)
point
position
power

More entries...


Index

A B C D E F G H I L M N P R S T U V W X Y Z

R

RayPick
RayPick (IDirect3DRMFrame2)
red
red_mask
reference count
RegisterEvents
RegisterEvents (IDirect3DRMProgressiveMesh)
Render
Render (IDirect3DRMViewport)
ReserveSpace (IDirect3DRMMeshBuilder)
ReserveSpace (IDirect3DRMMeshBuilder2)
ReserveSpace (IDirect3DRMMeshBuilder)
ReserveSpace (IDirect3DRMMeshBuilder2)
rgb
root frame

S

Save (IDirect3DRMMeshBuilder)
Save (IDirect3DRMMeshBuilder2)
Save (IDirect3DRMFrame2)
Save (IDirect3DRMMeshBuilder)
Save (IDirect3DRMMeshBuilder2)
Saves
Scale (IDirect3DRMMesh)
Scale (IDirect3DRMMeshBuilder)
Scale (IDirect3DRMMeshBuilder2)
Scale (IDirect3DRMMesh)
Scale (IDirect3DRMMeshBuilder)
Scale (IDirect3DRMMeshBuilder2)
SetAppData
SetAppData (IDirect3DRMObject)
SetAxes
SetAxes (IDirect3DRMFrame2)
SetBack
SetBack (IDirect3DRMViewport)
SetBox
SetBox (IDirect3DRMFrame2)
SetBoxEnable
SetBoxEnable (IDirect3DRMFrame2)
SetBufferCount (IDirect3DRMDevice)
SetBufferCount (IDirect3DRMDevice2)
SetBufferCount (IDirect3DRMDevice)
SetBufferCount (IDirect3DRMDevice2)
SetCamera
SetCamera (IDirect3DRMViewport)
SetColor (IDirect3DRMFace)
SetColor (IDirect3DRMFrame)
SetColor (IDirect3DRMFrame2)
SetColor (IDirect3DRMLight)
SetColor (IDirect3DRMMeshBuilder)
SetColor (IDirect3DRMMeshBuilder2)
SetColor (IDirect3DRMFace)
SetColor (IDirect3DRMFrame)
SetColor (IDirect3DRMFrame2)
SetColor (IDirect3DRMLight)
SetColor (IDirect3DRMMeshBuilder)
SetColor (IDirect3DRMMeshBuilder2)
SetColorRGB (IDirect3DRMFace)
SetColorRGB (IDirect3DRMFrame)
SetColorRGB (IDirect3DRMFrame2)
SetColorRGB (IDirect3DRMLight)
SetColorRGB (IDirect3DRMMeshBuilder)
SetColorRGB (IDirect3DRMMeshBuilder2)
SetColorRGB (IDirect3DRMFace)
SetColorRGB (IDirect3DRMFrame)
SetColorRGB (IDirect3DRMFrame2)
SetColorRGB (IDirect3DRMLight)
SetColorRGB (IDirect3DRMMeshBuilder)
SetColorRGB (IDirect3DRMMeshBuilder2)
SetColors (IDirect3DRMTexture)
SetColors (IDirect3DRMTexture2)
SetColors (IDirect3DRMTexture)
SetColors (IDirect3DRMTexture2)
SetColorSource (IDirect3DRMMeshBuilder)
SetColorSource (IDirect3DRMMeshBuilder2)
SetColorSource (IDirect3DRMMeshBuilder)
SetColorSource (IDirect3DRMMeshBuilder2)
SetConstantAttenuation
SetConstantAttenuation (IDirect3DRMLight)
SetDecalOrigin (IDirect3DRMTexture)
SetDecalOrigin (IDirect3DRMTexture2)
SetDecalOrigin (IDirect3DRMTexture)
SetDecalOrigin (IDirect3DRMTexture2)
SetDecalScale (IDirect3DRMTexture)
SetDecalScale (IDirect3DRMTexture2)
SetDecalScale (IDirect3DRMTexture)
SetDecalScale (IDirect3DRMTexture2)
SetDecalSize (IDirect3DRMTexture)
SetDecalSize (IDirect3DRMTexture2)
SetDecalSize (IDirect3DRMTexture)
SetDecalSize (IDirect3DRMTexture2)
SetDecalTransparency (IDirect3DRMTexture)
SetDecalTransparency (IDirect3DRMTexture2)
SetDecalTransparency (IDirect3DRMTexture)
SetDecalTransparency (IDirect3DRMTexture2)
SetDecalTransparentColor (IDirect3DRMTexture)
SetDecalTransparentColor (IDirect3DRMTexture2)
SetDecalTransparentColor (IDirect3DRMTexture)
SetDecalTransparentColor (IDirect3DRMTexture2)
SetDefaultTextureColors (IDirect3DRM)
SetDefaultTextureColors (IDirect3DRM2)
SetDefaultTextureColors (IDirect3DRM)
SetDefaultTextureColors (IDirect3DRM2)
SetDefaultTextureShades (IDirect3DRM)
SetDefaultTextureShades (IDirect3DRM2)
SetDefaultTextureShades (IDirect3DRM)
SetDefaultTextureShades (IDirect3DRM2)
SetDetail
SetDetail (IDirect3DRMProgressiveMesh)
SetDither (IDirect3DRMDevice)
SetDither (IDirect3DRMDevice2)
SetDither (IDirect3DRMDevice)
SetDither (IDirect3DRMDevice2)
SetEmissive
SetEmissive (IDirect3DRMMaterial)
SetEnableFrame
SetEnableFrame (IDirect3DRMLight)
SetFaceDetail
SetFaceDetail (IDirect3DRMProgressiveMesh)
SetField
SetField (IDirect3DRMViewport)
SetFrame
SetFrame (IDirect3DRMAnimation)
SetFront
SetFront (IDirect3DRMViewport)
SetGroupColor
SetGroupColor (IDirect3DRMMesh)
SetGroupColorRGB
SetGroupColorRGB (IDirect3DRMMesh)
SetGroupMapping
SetGroupMapping (IDirect3DRMMesh)
SetGroupMaterial
SetGroupMaterial (IDirect3DRMMesh)
SetGroupQuality
SetGroupQuality (IDirect3DRMMesh)
SetGroupTexture
SetGroupTexture (IDirect3DRMMesh)
SetIndex
SetIndex (IDirect3DRMInterpolator)
SetInheritAxes
SetInheritAxes (IDirect3DRMFrame2)
SetLinearAttenuation
SetLinearAttenuation (IDirect3DRMLight)
SetMaterial (IDirect3DRMFace)
SetMaterial (IDirect3DRMFrame2)
SetMaterial (IDirect3DRMMeshBuilder)
SetMaterial (IDirect3DRMMeshBuilder2)
SetMaterial (IDirect3DRMFace)
SetMaterial (IDirect3DRMFrame2)
SetMaterial (IDirect3DRMMeshBuilder)
SetMaterial (IDirect3DRMMeshBuilder2)
SetMaterialMode (IDirect3DRMFrame)
SetMaterialMode (IDirect3DRMFrame2)
SetMaterialMode (IDirect3DRMFrame)
SetMaterialMode (IDirect3DRMFrame2)
SetMinRenderDetail
SetMinRenderDetail (IDirect3DRMProgressiveMesh)
SetName
SetName (IDirect3DRMObject)
SetNormal (IDirect3DRMMeshBuilder)
SetNormal (IDirect3DRMMeshBuilder2)
SetNormal (IDirect3DRMMeshBuilder)
SetNormal (IDirect3DRMMeshBuilder2)
SetOptions
SetOptions (IDirect3DRMAnimation)
SetOrientation (IDirect3DRMFrame)
SetOrientation (IDirect3DRMFrame2)
SetOrientation (IDirect3DRMFrame)
SetOrientation (IDirect3DRMFrame2)
SetPenumbra
SetPenumbra (IDirect3DRMLight)
SetPerspective (IDirect3DRMMeshBuilder)
SetPerspective (IDirect3DRMMeshBuilder2)
SetPerspective (IDirect3DRMMeshBuilder)
SetPerspective (IDirect3DRMMeshBuilder2)
SetPlane
SetPlane (IDirect3DRMViewport)
SetPosition (IDirect3DRMFrame)
SetPosition (IDirect3DRMFrame2)
SetPosition (IDirect3DRMFrame)
SetPosition (IDirect3DRMFrame2)
SetPower
SetPower (IDirect3DRMMaterial)
SetProjection
SetProjection (IDirect3DRMViewport)
SetQuadraticAttenuation
SetQuadraticAttenuation (IDirect3DRMLight)
SetQuality (IDirect3DRMDevice)
SetQuality (IDirect3DRMDevice2)
SetQuality (IDirect3DRMMeshBuilder)
SetQuality (IDirect3DRMMeshBuilder2)
SetQuality (IDirect3DRMProgressiveMesh)
SetQuality (IDirect3DRMDevice)
SetQuality (IDirect3DRMDevice2)
SetQuality (IDirect3DRMMeshBuilder)
SetQuality (IDirect3DRMMeshBuilder2)
SetQuality (IDirect3DRMProgressiveMesh)
SetQuarternion
SetQuaternion (IDirect3DRMFrame2)
SetRange
SetRange (IDirect3DRMLight)
SetRenderMode
SetRenderMode (IDirect3DRMDevice2)
SetRotation (IDirect3DRMFrame)
SetRotation (IDirect3DRMFrame2)
SetRotation (IDirect3DRMFrame)
SetRotation (IDirect3DRMFrame2)
SetSceneBackground (IDirect3DRMFrame)
SetSceneBackground (IDirect3DRMFrame2)
SetSceneBackground (IDirect3DRMFrame)
SetSceneBackground (IDirect3DRMFrame2)
SetSceneBackgroundDepth (IDirect3DRMFrame)
SetSceneBackgroundDepth (IDirect3DRMFrame2)
SetSceneBackgroundDepth (IDirect3DRMFrame)
SetSceneBackgroundDepth (IDirect3DRMFrame2)
SetSceneBackgroundImage (IDirect3DRMFrame)
SetSceneBackgroundImage (IDirect3DRMFrame2)
SetSceneBackgroundImage (IDirect3DRMFrame)
SetSceneBackgroundImage (IDirect3DRMFrame2)
SetSceneBackgroundRGB (IDirect3DRMFrame)
SetSceneBackgroundRGB (IDirect3DRMFrame2)
SetSceneBackgroundRGB (IDirect3DRMFrame)
SetSceneBackgroundRGB (IDirect3DRMFrame2)
SetSceneFogColor (IDirect3DRMFrame)
SetSceneFogColor (IDirect3DRMFrame2)
SetSceneFogColor (IDirect3DRMFrame)
SetSceneFogColor (IDirect3DRMFrame2)
SetSceneFogEnable (IDirect3DRMFrame)
SetSceneFogEnable (IDirect3DRMFrame2)
SetSceneFogEnable (IDirect3DRMFrame)
SetSceneFogEnable (IDirect3DRMFrame2)
SetSceneFogMode (IDirect3DRMFrame)
SetSceneFogMode (IDirect3DRMFrame2)
SetSceneFogMode (IDirect3DRMFrame)
SetSceneFogMode (IDirect3DRMFrame2)
SetSceneFogParams (IDirect3DRMFrame)
SetSceneFogParams (IDirect3DRMFrame2)
SetSceneFogParams (IDirect3DRMFrame)
SetSceneFogParams (IDirect3DRMFrame2)
SetSearchPath (IDirect3DRM)
SetSearchPath (IDirect3DRM2)
SetSearchPath (IDirect3DRM)
SetSearchPath (IDirect3DRM2)
SetShades (IDirect3DRMDevice)
SetShades (IDirect3DRMDevice2)
SetShades (IDirect3DRMTexture)
SetShades (IDirect3DRMTexture2)
SetShades (IDirect3DRMDevice)
SetShades (IDirect3DRMDevice2)
SetShades (IDirect3DRMTexture)
SetShades (IDirect3DRMTexture2)
SetSortMode (IDirect3DRMFrame)
SetSortMode (IDirect3DRMFrame2)
SetSortMode (IDirect3DRMFrame)
SetSortMode (IDirect3DRMFrame2)
SetSpecular
SetSpecular (IDirect3DRMMaterial)
SetTexture (IDirect3DRMFace)
SetTexture (IDirect3DRMFrame)
SetTexture (IDirect3DRMFrame2)
SetTexture (IDirect3DRMMeshBuilder)
SetTexture (IDirect3DRMMeshBuilder2)
SetTexture (IDirect3DRMFace)
SetTexture (IDirect3DRMFrame)
SetTexture (IDirect3DRMFrame2)
SetTexture (IDirect3DRMMeshBuilder)
SetTexture (IDirect3DRMMeshBuilder2)
SetTextureCoordinates (IDirect3DRMFace)
SetTextureCoordinates (IDirect3DRMMeshBuilder)
SetTextureCoordinates (IDirect3DRMMeshBuilder2)
SetTextureCoordinates (IDirect3DRMFace)
SetTextureCoordinates (IDirect3DRMMeshBuilder)
SetTextureCoordinates (IDirect3DRMMeshBuilder2)
SetTextureQuality (IDirect3DRMDevice)
SetTextureQuality (IDirect3DRMDevice2)
SetTextureQuality (IDirect3DRMDevice)
SetTextureQuality (IDirect3DRMDevice2)
SetTextureTopology (IDirect3DRMFace)
SetTextureTopology (IDirect3DRMFrame)
SetTextureTopology (IDirect3DRMFrame2)
SetTextureTopology (IDirect3DRMMeshBuilder)
SetTextureTopology (IDirect3DRMMeshBuilder2)
SetTextureTopology (IDirect3DRMFace)
SetTextureTopology (IDirect3DRMFrame)
SetTextureTopology (IDirect3DRMFrame2)
SetTextureTopology (IDirect3DRMMeshBuilder)
SetTextureTopology (IDirect3DRMMeshBuilder2)
SetTime (IDirect3DRMAnimation)
SetTime (IDirect3DRMAnimationSet)
SetTime (IDirect3DRMAnimation)
SetTime (IDirect3DRMAnimationSet)
SetType
SetType (IDirect3DRMLight)
SetUmbra
SetUmbra (IDirect3DRMLight)
SetUniformScaling
SetUniformScaling (IDirect3DRMViewport)
SetVelocity (IDirect3DRMFrame)
SetVelocity (IDirect3DRMFrame2)
SetVelocity (IDirect3DRMFrame)
SetVelocity (IDirect3DRMFrame2)
SetVertex (IDirect3DRMMeshBuilder)
SetVertex (IDirect3DRMMeshBuilder2)
SetVertex (IDirect3DRMMeshBuilder)
SetVertex (IDirect3DRMMeshBuilder2)
SetVertexColor (IDirect3DRMMeshBuilder)
SetVertexColor (IDirect3DRMMeshBuilder2)
SetVertexColor (IDirect3DRMMeshBuilder)
SetVertexColor (IDirect3DRMMeshBuilder2)
SetVertexColorRGB (IDirect3DRMMeshBuilder)
SetVertexColorRGB (IDirect3DRMMeshBuilder2)
SetVertexColorRGB (IDirect3DRMMeshBuilder)
SetVertexColorRGB (IDirect3DRMMeshBuilder2)
SetVertexDetail
SetVertexDetail (IDirect3DRMProgressiveMesh)
SetVertices
SetVertices (IDirect3DRMMesh)
SetZbufferMode (IDirect3DRMFrame)
SetZbufferMode (IDirect3DRMFrame2)
SetZbufferMode (IDirect3DRMFrame)
SetZbufferMode (IDirect3DRMFrame2)
specular property
spotlight

More entries...


Index

A B C D E F G H I L M N P R S T U V W X Y Z

T

texture blending
Texture Map Formats
Tick (IDirect3DRM)
Tick (IDirect3DRM2)
Tick (IDirect3DRM)
Tick (IDirect3DRM2)
Transform (IDirect3DRMFrame)
Transform (IDirect3DRMFrame2)
Transform (IDirect3DRMViewport)
Transform (IDirect3DRMFrame)
Transform (IDirect3DRMFrame2)
Transform (IDirect3DRMViewport)
Translate (IDirect3DRMMesh)
Translate (IDirect3DRMMeshBuilder)
Translate (IDirect3DRMMeshBuilder2)
Translate (IDirect3DRMMesh)
Translate (IDirect3DRMMeshBuilder)
Translate (IDirect3DRMMeshBuilder2)
tu (D3DRMPICKDESC2)
tu (D3DRMVERTEX)
tv (D3DRMPICKDESC2)
tv (D3DRMVERTEX)

U

ulFaceIdx (D3DRMPICKDESC)
ulFaceIdx (D3DRMPICKDESC2)
umbra
Update (IDirect3DRMDevice)
Update (IDirect3DRMDevice2)
Update (IDirect3DRMDevice)
Update (IDirect3DRMDevice2)

V

viewing frustum
vPosition (D3DRMPICKDESC)
vPosition (D3DRMPICKDESC2)

W

w
width
world coordinates

X

x

Y

y

Z

z


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

A

Abs (DAStatic Functions Relevant to DANumber Objects)
abs (Static Methods Relevant to NumberBvr Objects)
Acos (DAStatic Functions Relevant to DANumber Objects)
acos (Static Methods Relevant to NumberBvr Objects)
action set (A)
Action Set (Sequencer Control)
add (BvrsToRun Methods)
Add (DAStatic Functions Relevant to DANumber Objects)
add (Static Methods Relevant to NumberBvr Objects)
add (Static Methods Relevant to Point2Bvr Objects)
add (Static Methods Relevant to Point3Bvr Objects)
add (Static Methods Relevant to Vector2Bvr Objects)
add (Static Methods Relevant to Vector3Bvr Objects)
AddBehaviorToRun
AddFrameMarker Method
addModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 1)
addModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 2)
addNotify
AddPoint2Vector
AddPoint3Vector
AddTimeMarker Method (Path Control Events)
AddTimeMarker Method (Sprite Control Events)
AddVector2
AddVector3
Album3D Java sample
Always (DAStatic Properties Relevant to DAEvent Objects)
always (Static Fields Relevant to DXMEvent Objects)
ambient light
AmbientLight (DAStatic Properties Relevant to DAGeometry Objects)
ambientLight (Static Fields Relevant to GeometryBvr Objects)
Americana Java sample
And (DAStatic Functions Relevant to DABoolean Objects)
and (Static Methods Relevant to BooleanBvr Objects)
AndEvent (DAStatic Functions Relevant to DAEvent Objects)
andEvent (Static Methods Relevant to DXMEvent Objects)
AniFilt DirectAnimation control sample
AnimateControlPositionPixel
AnimatedGlow JScript sample
AnimatedProperties JScript sample
AnimatedProperties VBScript sample
AnimateProperty (DANumber Functions)
AnimateProperty (DAString Functions)
AnnotatedLogo JScript sample
AntiAliasing (DAFontStyle Functions)
AntiAliasing (DALineStyle Functions)
Apple Java sample
AppTriggeredEvent Class
AppTriggeredEvent()
Aqua (DAStatic Properties Relevant to DAColor Objects)
aqua (Static Fields Relevant to ColorBvr Objects)
arc
Arc Method
ArcDegrees (DADrawingSurface Subroutines)
ArcDegrees (DAStatic Functions Relevant to DAPath2 Objects)
arcDegrees (Static Methods Relevant to Path2Bvr Objects)
ArcRadians
ArcRadians (DADrawingSurface Subroutines)
ArcRadiansAnim
AreBlockingImportsComplete
ArrayBvr Class
Asin (DAStatic Functions Relevant to DANumber Objects)
asin (Static Methods Relevant to NumberBvr Objects)
Async_Load Java sample
Async_Load JScript sample
At Method
Atan (DAStatic Functions Relevant to DANumber Objects)
atan (Static Methods Relevant to NumberBvr Objects)
Atan2 (DAStatic Functions Relevant to DANumber Objects)
atan2 (Static Methods Relevant to NumberBvr Objects)
AttachData (DAEvent Functions)
attachData (DXMEvent Methods)
AudioMixing VBScript sample
AutoSizeFillScale
AutoStart Property (Path Control Events)
AutoStart Property (Sprite Control Events)

B

BackgroundImage
Basic JScript sample
Basic VBScript sample
BasicApplet Java sample
BasicDS JScript sample
BasicDS VBScript sample
Bbox2Bvr Class
Bbox3Bvr Class
Behavior Class
Behavior.debug
Black (DAStatic Properties Relevant to DAColor Objects)
black (Static Fields Relevant to ColorBvr Objects)
Blue (DAColor Properties)
Blue (DAStatic Properties Relevant to DAColor Objects)
blue (Static Fields Relevant to ColorBvr Objects)
Bold (DAFontStyle Functions)
bold (FontStyleBvr Methods)
BooleanBvr Class
BorderColor
BorderDashStyle
BorderJoinStyle
BorderStyle
BorderWidth
Bounce JScript sample
Bounce Property
bounding box
BoundingBox (DAGeometry Properties)
BoundingBox (DAImage Functions)
BoundingBox (DAPath2 Functions)
boundingBox (GeometryBvr Methods)
boundingBox (ImageBvr Methods)
boundingBox (Path2Bvr Methods)
BrowserDetect JScript sample
bSpline (Static Methods Relevant to NumberBvr Objects)
bSpline (Static Methods Relevant to Point2Bvr Objects)
bSpline (Static Methods Relevant to Point3Bvr Objects)
bSpline (Static Methods Relevant to Vector2Bvr Objects)
bSpline (Static Methods Relevant to Vector3Bvr Objects)
buildURL
ButtonPick Java sample
Buttons DirectAnimation control sample
ButtonSwitch VBScript sample
BvrCallback Interface
bvrHook
BvrsToRun Class

C

Callback VBScript sample
camera
CameraBvr Class
Ceiling (DAStatic Functions Relevant to DANumber Objects)
ceiling (Static Methods Relevant to NumberBvr Objects)
Center-Based Positioning
Chess Application
CityScape Java sample
Clear
Clear Method
ClearMatte (DAStatic Properties Relevant to DAMatte Objects)
clearMatte (Static Fields Relevant to MatteBvr Objects)
ClientSite
clip
Clip (DAImage Functions)
clip (ImageBvr Methods)
ClipMatte
clipPolygon
ClipPolygonImage
Clock DirectAnimation control sample
Clock VBScript sample
Close (DAPath2 Functions)
close (Path2Bvr Methods)
Cm (Miscellaneous DAStatic Properties)
cm (Static Fields (Miscellaneous))
Coffee Java sample
Coffee VBScript sample
Collage3D JScript sample
color
Color (DAFontStyle Functions)
Color (DALineStyle Functions)
color (FontStyleBvr Methods)
color (LineStyleBvr Methods)
ColorArray JScript sample
ColorBvr Class
ColorHsl (DAStatic Functions Relevant to DAColor Objects)
colorHsl (Static Methods Relevant to ColorBvr Objects)
ColorHslAnim
ColorKey Property
ColorRgb (DAStatic Functions Relevant to DAColor Objects)
colorRgb (Static Methods Relevant to ColorBvr Objects)
ColorRgb255 (DAStatic Functions Relevant to DAColor Objects)
colorRgb255 (Static Methods Relevant to ColorBvr Objects)
ColorRgbAnim
ColorSwitch JScript sample
CompletionEvent
Complex DirectAnimation control sample
compose (Static Methods Relevant to Transform2Bvr Objects)
compose (Static Methods Relevant to Transform3Bvr Objects)
Compose2
Compose2Array (DAStatic Functions Relevant to DATransform2 Objects)
compose2Array (Static Methods Relevant to Transform2Bvr Objects)
Compose3
Compose3Array (DAStatic Functions Relevant to DATransform3 Objects)
compose3Array (Static Methods Relevant to Transform3Bvr Objects)
Concat (DAStatic Functions Relevant to DAPath2 Objects)
concat (Static Methods Relevant to Path2Bvr Objects)
concat (Static Methods Relevant to StringBvr Objects)
ConcatArray (DAStatic Functions Relevant to DAPath2 Objects)
concatArray (Static Methods Relevant to Path2Bvr Objects)
ConcatString
Cond (DAStatic Functions Relevant to DABehavior Objects)
cond (Static Methods Relevant to Behavior Objects)
Constructing Geometries
Container
CoordinateSystem Property
CoordsAndPaths JScript sample
Cos (DAStatic Functions Relevant to DANumber Objects)
cos (Static Methods Relevant to NumberBvr Objects)
Count DirectAnimation control sample
createBackgroundImage
createModel
crop
Crop (DADrawingSurface Subroutines)
Crop (DAImage Functions)
crop (ImageBvr Methods)
Cropping JScript sample
CropPoints
cross
CrossVector3
CubicBSplinePath (DAStatic Functions Relevant to DAPath2 Objects)
cubicBSplinePath (Static Methods Relevant to Path2Bvr Objects)
Curves VBScript sample
Cyan (DAStatic Properties Relevant to DAColor Objects)
cyan (Static Fields Relevant to ColorBvr Objects)
Cycler Class
Cycler Constructor

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

D

DAArray
DAArray Class
DABbox2 Class
DABbox3 Class
DABehavior Class
DABoolean
DABoolean Class
DACamera Class
DAColor Class
DADashStyle Class
DADrawingSurface Class
DAEndStyle Class
DAEvent Class
DAFalse
DAFontStyle Class
DAGeometry Class
DAImage Class
DAImportationResult Class
DAJoinStyle Class
DALineStyle Class
DAMatte Class
DAMicrophone Class
DAMontage Class
DancingTrapzoids VBScript sample
DANumber
DANumber Class
DAPair Class
DAPath2 Class
DAPickableResult Class
DAPoint2 Class
DAPoint3 Class
Dash (DALineStyle Functions)
dash (LineStyleBvr Methods)
DashStyleBvr Class
DashStyleDashed (DAStatic Properties Relevant to DADashStyle Objects)
dashStyleDashed (Static Fields Relevant to DashStyleBvr Objects)
DashStyleSolid (DAStatic Properties Relevant to DADashStyle Objects)
dashStyleSolid (Static Fields Relevant to DashStyleBvr Objects)
DASound Class
DAStatic Functions Relevant to DAArray Objects
DAStatic Functions Relevant to DABehavior Objects
DAStatic Functions Relevant to DABoolean Objects
DAStatic Functions Relevant to DACamera Objects
DAStatic Functions Relevant to DAColor Objects
DAStatic Functions Relevant to DAEvent Objects
DAStatic Functions Relevant to DAFontStyle Objects
DAStatic Functions Relevant to DAGeometry Objects
DAStatic Functions Relevant to DAImage Objects
DAStatic Functions Relevant to DAMatte Objects
DAStatic Functions Relevant to DAMontage Objects
DAStatic Functions Relevant to DANumber Objects
DAStatic Functions Relevant to DAPath2 Objects
DAStatic Functions Relevant to DAPoint2 Objects
DAStatic Functions Relevant to DAPoint3 Objects
DAStatic Functions Relevant to DASound Objects
DAStatic Functions Relevant to DAString Objects
DAStatic Functions Relevant to DATransform2 Objects
DAStatic Functions Relevant to DATransform3 Objects
DAStatic Functions Relevant to DATuple Objects
DAStatic Functions Relevant to DAVector2 Objects
DAStatic Functions Relevant to DAVector3 Objects
DAStatic Functions Relevent to DADrawingSurface Objects
DAStatic Properties Relevant to DABoolean Objects
DAStatic Properties Relevant to DAColor Objects
DAStatic Properties Relevant to DADashStyle Objects
DAStatic Properties Relevant to DAEndStyle Objects
DAStatic Properties Relevant to DAEvent Objects
DAStatic Properties Relevant to DAFontStyle Objects
DAStatic Properties Relevant to DAGeometry Objects
DAStatic Properties Relevant to DAImage Objects
DAStatic Properties Relevant to DAJoinStyle Objects
DAStatic Properties Relevant to DALineStyle Objects
DAStatic Properties Relevant to DAMatte Objects
DAStatic Properties Relevant to DAMicrophone Objects
DAStatic Properties Relevant to DAMontage Objects
DAStatic Properties Relevant to DANumber Objects
DAStatic Properties Relevant to DAPoint2 Objects
DAStatic Properties Relevant to DAPoint3 Objects
DAStatic Properties Relevant to DASound Objects
DAStatic Properties Relevant to DATransform2 Objects
DAStatic Properties Relevant to DATransform3 Objects
DAStatic Properties Relevant to DAVector2 Objects
DAStatic Properties Relevant to DAVector3 Objects
DAStatics Class
DAString
DAString Class
Data
DATransform2 Class
DATransform3 Class
DATrue
DATuple
DATuple Class
DAUserData Class
DAVector2 Class
DAVector3 Class
DAViewerControl Class
debug (Java Reference: Behavior Class: Behavior Methods: 1)
debug (Java Reference: Behavior Class: Behavior Methods: 2)
debug (Java Reference: Behavior Class: Behavior Methods: 3)
debug (Java Reference: Behavior Class: Behavior Methods: 4)
DefaultFont (DAStatic Properties Relevant to DAFontStyle Objects)
defaultFont (Static Fields Relevant to FontStyleBvr Objects)
DefaultLineStyle (DAStatic Properties Relevant to DALineStyle Objects)
defaultLineStyle (Static Fields Relevant to LineStyleBvr Objects)
DefaultMicrophone (DAStatic Properties Relevant to DAMicrophone Objects)
defaultMicrophone (Static Fields Relevant to MicrophoneBvr Objects)
degreesToRadians
depth (CameraBvr Methods)
Depth (DACamera Functions)
DepthAnim
depthResolution (CameraBvr Methods)
DepthResolution (DACamera Functions)
DepthResolutionAnim
Derivative (DAStatic Functions Relevant to DANumber Objects)
derivative (Static Methods Relevant to NumberBvr Objects)
derivative (Static Methods Relevant to Point2Bvr Objects)
derivative (Static Methods Relevant to Point3Bvr Objects)
derivative (Static Methods Relevant to Vector2Bvr Objects)
derivative (Static Methods Relevant to Vector3Bvr Objects)
DerivativePoint2
DerivativePoint3
DerivativeVector2
DerivativeVector3
detach
Detail (DALineStyle Functions)
detail (LineStyleBvr Methods)
detectability
DetectableEmptyImage (DAStatic Properties Relevant to DAImage Objects)
detectableEmptyImage (Static Fields Relevant to ImageBvr Objects)
difference
DifferenceMatte
DiffuseColor (DAGeometry Functions)
diffuseColor (GeometryBvr Methods)
Direction Property
directional light
DirectionalLight (DAStatic Properties Relevant to DAGeometry Objects)
directionalLight (Static Fields Relevant to GeometryBvr Objects)
distance (Static Methods Relevant to Point2Bvr Objects)
distance (Static Methods Relevant to Point3Bvr Objects)
DistancePoint2
DistancePoint3
distanceSquared (Static Methods Relevant to Point2Bvr Objects)
distanceSquared (Static Methods Relevant to Point3Bvr Objects)
DistanceSquaredPoint2
DistanceSquaredPoint3
Div (DAStatic Functions Relevant to DANumber Objects)
Div (DAVector2 Functions)
Div (DAVector3 Functions)
div (Static Methods Relevant to NumberBvr Objects)
div (Vector2Bvr Class: Vector2Bvr Methods)
div (Vector3Bvr Class: Vector3Bvr Methods)
DivAnim (DAVector2 Functions)
DivAnim (DAVector3 Functions)
dot (Static Methods Relevant to Vector2Bvr Objects)
dot (Static Methods Relevant to Vector3Bvr Objects)
DotVector2
DotVector3
Drag
DragDrop
DragIcon
DragMode
DragOver
Draw (DAPath2 Functions)
draw (Path2Bvr Methods)
Drawing Surface
DrawingSurface Property
DrawPath
duration (Behavior Methods)
Duration (DABehavior Functions)
Duration (DAImportationResult Properties)
Duration Property
DurationAnim
DXMApplet Class
DXMApplet Constructor
DXMCanvas Class
DXMCanvas Constructor
DXMEvent Class
DXMEvent Constructor
DXMException Class
DXMException Constructor
DxMLogoDots JScript sample
DxMLogoGeo JScript sample

E

Empty Images
EmptyGeometry (DAStatic Properties Relevant to DAGeometry Objects)
emptyGeometry (Static Fields Relevant to GeometryBvr Objects)
EmptyImage (DAStatic Properties Relevant to DAImage Objects)
emptyImage (Static Fields Relevant to ImageBvr Objects)
EmptyLineStyle
EmptyMontage (DAStatic Properties Relevant to DAMontage Objects)
emptyMontage (Static Fields Relevant to MontageBvr Objects)
Encarta Java sample
End (DALineStyle Functions)
end (LineStyleBvr Methods)
EndStyleBvr Class
EndStyleFlat (DAStatic Properties Relevant to DAEndStyle Objects)
endStyleFlat (Static Fields Relevant to EndStyleBvr Objects)
EndStyleRound (DAStatic Properties Relevant to DAEndStyle Objects)
endStyleRound (Static Fields Relevant to EndStyleBvr Objects)
EndStyleSquare (DAStatic Properties Relevant to DAEndStyle Objects)
endStyleSquare (Static Fields Relevant to EndStyleBvr Objects)
EQ (DAStatic Functions Relevant to DANumber Objects)
eq (Static Methods Relevant to NumberBvr Objects)
ErrorAndWarningReceiver Interface
EventCallbackObject Interface
Exp (DAStatic Functions Relevant to DANumber Objects)
exp (Static Methods Relevant to NumberBvr Objects)
ExtendedApplet Java sample
ExtentHeight, ExtentWidth, ExtentLeft, ExtentTop Properties
extract (Behavior Methods)
extract (BooleanBvr Methods)
Extract (DABoolean Functions)
Extract (DANumber Functions)
Extract (DAString Functions)
extract (NumberBvr Methods)
extract (StringBvr Methods)
Eyes JScript sample

F

falseBvr
Family (DAFontStyle Functions)
family (FontStyleBvr Methods)
FamilyAnim
FifteenPuzzle Java sample
Fill (DAPath2 Functions)
fill (Path2Bvr Methods)
FillColor
FillImage
FillMatte (DAStatic Functions Relevant to DAMatte Objects)
fillMatte (Static Methods Relevant to MatteBvr Objects)
FillPath
FillSpline Method
FillStyle
FillTexture
Filter DirectAnimation control sample
FinalFrame Property
First
FixedFillScale
Floor (DAStatic Functions Relevant to DANumber Objects)
floor (Static Methods Relevant to NumberBvr Objects)
FollowPath (DAStatic Functions Relevant to DATransform2 Objects)
followPath (Static Methods Relevant to Transform2Bvr Objects)
FollowPathAngle (DAStatic Functions Relevant to DATransform2 Objects)
followPathAngle (Static Methods Relevant to Transform2Bvr Objects)
FollowPathAngleEval
FollowPathAngleUpright (DAStatic Functions Relevant to DATransform2 Objects)
followPathAngleUpright (Static Methods Relevant to Transform2Bvr Objects)
FollowPathAngleUprightEval
FollowPathEval
Font (DADrawingSurface Subroutines)
Font (DAStatic Functions Relevant to DAFontStyle Objects)
font (Static Methods Relevant to FontStyleBvr Objects)
FontAnim
FontStyle
FontStyleBvr Class
Foot (Miscellaneous DAStatic Properties)
foot (Static Fields (Miscellaneous))
Frame Property
FrameMap Property
FrameSeek Method
Fuchsia (DAStatic Properties Relevant to DAColor Objects)
fuchsia (Static Fields Relevant to ColorBvr Objects)

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

G

Gain (DASound Functions)
gain (SoundBvr Methods)
Gain (Using Sound)
GainAnim
GeoApplet1 Java sample
GeoApplet2 Java sample
GeoImage Java sample
geometry
Geometry (DAImportationResult Properties)
Geometry (DAPickableResult Properties)
Geometry Coordinate System
Geometry Java sample
Geometry JScript sample
GeometryBvr Class
GeometryBvr.diffuseColor(ColorBvr col)
GeometryBvr.lightAttenuation(NumberBvr const, NumberBvr linear, NumberBvr quadratic)
GeometryBvr.lightColor(ColorBvr col)
GeometryBvr.opacity((NumberBvr opac)
GeometryBvr.texture(ImageBvr image)
GeometryDrag Java sample
getBlue
getBoolean
getBvr (Cycler Methods)
getBvr (ModifiableBehavior Methods)
getBvr (PropertyDispatcher Methods)
getCanvas
GetClassName
getCurrentTickTime (DXMCanvas Methods from Viewer Interface)
getCurrentTickTime (Viewer Methods)
getCurrentTime (DXMCanvas Methods from Viewer Interface)
getCurrentTime (Viewer Methods)
getDouble
getErrorCode
getErrorString
getFirst
getGeometryBvr
getGreen
getHue
getImage
getImageBvr
getImportBase
getInt
getLightness
getMax (Bbox2Bvr Methods)
getMax (Bbox3Bvr Methods)
getMin (Bbox2Bvr Methods)
getMin (Bbox3Bvr Methods)
getModel (DXMApplet Methods)
getModel (DXMCanvas Methods)
getPickEvent (PickableGeometry Methods)
getPickEvent (PickableImage Methods)
getPolarCoordAngle (Point2Bvr Methods)
getPolarCoordAngle (Vector2Bvr Methods)
getPolarCoordLength
getPolarCoordLength()
getPreferences (DXMCanvas Methods from Viewer Interface)
getPreferences (Viewer Methods)
getRed
getSaturation
getSecond
getSound
getSphericalCoordLength (Point3Bvr Methods)
getSphericalCoordLength (Vector3Bvr Methods)
getSphericalCoordXYAngle (Point3Bvr Methods)
getSphericalCoordXYAngle (Vector3Bvr Methods)
getSphericalCoordYZAngle (Point3Bvr Methods)
getSphericalCoordYZAngle (Vector3Bvr Methods)
getString
getVersionString
getX (Point2Bvr Methods)
getX (Point3Bvr Methods)
getX (Vector2Bvr Methods)
getX (Vector3Bvr Methods)
getY (Point2Bvr Methods)
getY (Point3Bvr Methods)
getY (Vector2Bvr Methods)
getY (Vector3Bvr Methods)
getZ (Point3Bvr Methods)
getZ (Vector3Bvr Methods)
GlobalTime (DAStatic Properties Relevant to DANumber Objects)
globalTime (Static Fields Relevant to NumberBvr Objects)
Globe DirectAnimation control sample
GotFocus
grabBackgroundImageComPtr
grabImageComPtr
grabSoundComPtr
grabViewComPtr
Gradient Fill Images
GradientExtent
GradientExtentPoints
GradientHorizontal (DAStatic Functions Relevant to DAImage Objects)
gradientHorizontal (Static Methods Relevant to ImageBvr Objects)
GradientHorizontalAnim
GradientPolygon (DAStatic Functions Relevant to DAImage Objects)
gradientPolygon (Static Methods Relevant to ImageBvr Objects)
GradientRolloffPower
GradientRolloffPowerAnim
GradientShape
GradientSquare (DAStatic Functions Relevant to DAImage Objects)
gradientSquare (Static Methods Relevant to ImageBvr Objects)
Gray (DAStatic Properties Relevant to DAColor Objects)
gray (Static Fields Relevant to ColorBvr Objects)
Green (DAColor Properties)
Green (DAStatic Properties Relevant to DAColor Objects)
green (Static Fields Relevant to ColorBvr Objects)
GT (DAStatic Functions Relevant to DANumber Objects)
gt (Static Methods Relevant to NumberBvr Objects)
GTE (DAStatic Functions Relevant to DANumber Objects)
gte (Static Methods Relevant to NumberBvr Objects)

H

handleError
handleEvent
handleTickError
handleTickWarning
handleWarning
HatchBackwardDiagonal (DAStatic Functions Relevant to DAImage Objects)
hatchBackwardDiagonal (Static Methods Relevant to ImageBvr Objects)
HatchBackwardDiagonalAnim
HatchCross (DAStatic Functions Relevant to DAImage Objects)
hatchCross (Static Methods Relevant to ImageBvr Objects)
HatchCrossAnim
HatchDiagonalCross (DAStatic Functions Relevant to DAImage Objects)
hatchDiagonalCross (Static Methods Relevant to ImageBvr Objects)
HatchDiagonalCrossAnim
HatchFillTransparent
HatchForwardDiagonal (DAStatic Functions Relevant to DAImage Objects)
hatchForwardDiagonal (Static Methods Relevant to ImageBvr Objects)
HatchForwardDiagonalAnim
HatchHorizontal (DAStatic Functions Relevant to DAImage Objects)
hatchHorizontal (Static Methods Relevant to ImageBvr Objects)
HatchHorizontalAnim
HatchVertical (DAStatic Functions Relevant to DAImage Objects)
hatchVertical (Static Methods Relevant to ImageBvr Objects)
HatchVerticalAnim
Height
Hello Java sample
HelloBvr Java sample
HelloCycle Java sample
HelloRBvr Java sample
HelloWorld JScript sample
HelloWorld VBScript sample
HelloWorldJS JScript sample
HelpContextID
hide
hideModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 1)
hideModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 2)
HighQuality Property
Hook
HorizontalFillScale
Hue

I

IDABvrHook Class
IDASite Class
IdentityTransform2 (DAStatic Properties Relevant to DATransform2 Objects)
identityTransform2 (Static Fields Relevant to Transform2Bvr Objects)
IdentityTransform3 (DAStatic Properties Relevant to DATransform3 Objects)
identityTransform3 (Static Fields Relevant to Transform3Bvr Objects)
IE4_Windowless Java sample
image
Image (DADrawingSurface Properties)
Image (DAImportationResult Properties)
Image (DAPickableResult Properties)
Image (DAViewerControl Properties)
Image Coordinate System
Image Java sample
Image JScript sample
Image Property
Image Property (Sprite Control Events)
ImageBvr Class
ImageBvr.opacity(NumberBvr opac)
ImageDrag Java sample
ImageMontage (DAStatic Functions Relevant to DAMontage Objects)
imageMontage (Static Methods Relevant to MontageBvr Objects)
ImageMontageAnim
ImageOsc sample
Import Java sample
ImportDirectDrawSurface
ImportGeometry (DAStatic Functions Relevant to DAGeometry Objects)
importGeometry (Java Reference: Static Methods Relevant to GeometryBvr Objects: 1)
importGeometry (Java Reference: Static Methods Relevant to GeometryBvr Objects: 2)
ImportGeometryAsync
ImportImage (DAStatic Functions Relevant to DAImage Objects)
importImage (Java Reference: Static Methods Relevant to ImageBvr Objects: 1)
importImage (Java Reference: Static Methods Relevant to ImageBvr Objects: 2)
ImportImageAsync
ImportImageAsyncColorKey
ImportImageColorKey (DAStatic Functions Relevant to DAImage Objects)
importImageColorKey (Java Reference: Static Methods Relevant to ImageBvr Objects: 1)
importImageColorKey (Java Reference: Static Methods Relevant to ImageBvr Objects: 2)
ImportMovie (DAStatic Functions Relevant to DAImage Objects)
importMovie (Java Reference: Static Methods Relevant to ImageBvr Objects: 1)
importMovie (Java Reference: Static Methods Relevant to ImageBvr Objects: 2)
ImportMovieAsync
ImportSound (DAStatic Functions Relevant to DASound Objects)
importSound (Java Reference: Static Methods Relevant to SoundBvr Objects: 1)
importSound (Java Reference: Static Methods Relevant to SoundBvr Objects: 2)
ImportSoundAsync
Inch (Miscellaneous DAStatic Properties)
inch (Static Fields (Miscellaneous))
Index
init (Behavior Methods)
Init (DABehavior Functions)
InitialFrame Property
Integral (DAStatic Functions Relevant to DANumber Objects)
integral (Static Methods Relevant to NumberBvr Objects)
integral (Static Methods Relevant to Vector2Bvr Objects)
integral (Static Methods Relevant to Vector3Bvr Objects)
IntegralVector2
IntegralVector3
Interpolate (DAStatic Functions Relevant to DANumber Objects)
interpolate (Static Methods Relevant to NumberBvr Objects)
InterpolateAnim
intersect
IntersectMatte
Inverse (DATransform2 Functions)
Inverse (DATransform3 Functions)
inverse (Transform2Bvr Methods)
inverse (Transform3Bvr Methods)
invoke
IsReady
IsSingular (DATransform2 Properties)
IsSingular (DATransform3 Properties)
isSingular (Transform2Bvr Methods)
isSingular (Transform3Bvr Methods)
Italic (DAFontStyle Functions)
italic (FontStyleBvr Methods)

J

Java Class/Methods Summary
Java Defaults
Java Event Data
Java Hierarchy Chart
Java Reference Introduction
Join (DALineStyle Functions)
join (LineStyleBvr Methods)
JoinStyleBevel (DAStatic Properties Relevant to DAJoinStyle Objects)
joinStyleBevel (Static Fields Relevant to JoinStyleBvr Objects)
JoinStyleBvr Class
JoinStyleMiter (DAStatic Properties Relevant to DAJoinStyle Objects)
joinStyleMiter (Static Fields Relevant to JoinStyleBvr Objects)
JoinStyleRound (DAStatic Properties Relevant to DAJoinStyle Objects)
joinStyleRound (Static Fields Relevant to JoinStyleBvr Objects)
JumpURL Java sample
JumpURL JScript sample

K

KeyDown (DAStatic Functions Relevant to DAEvent Objects)
keyDown (Static Methods Relevant to DXMEvent Objects)
KeyFrame Method
KeyState (DAStatic Functions Relevant to DABoolean Objects)
keyState (Static Methods Relevant to BooleanBvr Objects)
KeyUp (DAStatic Functions Relevant to DAEvent Objects)
keyUp (Static Methods Relevant to DXMEvent Objects)

L

Left
LeftButtonDown (DAStatic Properties Relevant to DAEvent Objects)
leftButtonDown (Static Fields Relevant to DXMEvent Objects)
LeftButtonState (DAStatic Properties Relevant to DABoolean Objects)
leftButtonState (Static Fields Relevant to BooleanBvr Objects)
LeftButtonUp (DAStatic Properties Relevant to DAEvent Objects)
leftButtonUp (Static Fields Relevant to DXMEvent Objects)
length (ArrayBvr Methods)
Length (DAArray Functions)
Length (DATuple Functions)
Length (DAVector2 Properties)
Length (DAVector3 Properties)
length (TupleBvr Methods)
length (Vector2Bvr Methods)
length (Vector3Bvr Methods)
LengthSquared (DAVector2 Properties)
LengthSquared (DAVector3 Properties)
lengthSquared (Vector2Bvr Methods)
lengthSquared (Vector3Bvr Methods)
Library Property
Library Property (Path Control Events)
Library Property (Sprite Control Events)
light
LightAttenuation (DAGeometry Functions)
lightAttenuation (GeometryBvr Methods)
LightAttenuationAnim
LightBox JScript sample
LightBoxBG JScript sample
LightColor (DAGeometry Functions)
lightColor (GeometryBvr Methods)
Lighthouse Java sample
Lightness
Lime (DAStatic Properties Relevant to DAColor Objects)
lime (Static Fields Relevant to ColorBvr Objects)
Line (DADrawingSurface Subroutines)
Line (DAStatic Functions Relevant to DAPath2 Objects)
line (Static Methods Relevant to Path2Bvr Objects)
lineAntialiasing
LineColor
LineDashStyle
LineEndStyle
LineJoinStyle
LinePoints
LineStyle
LineStyleBvr Class
LineStyleBvr.color(ColorBvr color)
LineStyleBvr.dash(DashStyleBvr ds)
LineStyleBvr.detail()
LineStyleBvr.end(EndStyleBvr es)
LineStyleBvr.join(JoinStyleBvr js)
LineWidth
Ln (DAStatic Functions Relevant to DANumber Objects)
ln (Static Methods Relevant to NumberBvr Objects)
LocalContextImage
LocalTime (DAStatic Properties Relevant to DANumber Objects)
localTime (Static Fields Relevant to NumberBvr Objects)
Log10 (DAStatic Functions Relevant to DANumber Objects)
log10 (Static Methods Relevant to NumberBvr Objects)
LookAtFrom (DAStatic Functions Relevant to DATransform3 Objects)
lookAtFrom (Static Methods Relevant to Transform3Bvr Objects)
Loop (DASound Functions)
loop (SoundBvr Methods)
LostFocus
LT (DAStatic Functions Relevant to DANumber Objects)
lt (Static Methods Relevant to NumberBvr Objects)
LTE (DAStatic Functions Relevant to DANumber Objects)
lte (Static Methods Relevant to NumberBvr Objects)

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

M

Magenta (DAStatic Properties Relevant to DAColor Objects)
magenta (Static Fields Relevant to ColorBvr Objects)
Magnify Java sample
MapToUnitSquare (DAImage Functions)
mapToUnitSquare (ImageBvr Methods)
Maroon (DAStatic Properties Relevant to DAColor Objects)
maroon (Static Fields Relevant to ColorBvr Objects)
MatteBvr Class
Max (DABbox2 Properties)
Max (DABbox3 Properties)
MaximumRate Property
Mega DirectAnimation control sample
Meter (Miscellaneous DAStatic Properties)
meter (Static Fields (Miscellaneous))
Meter-Based Space
MeterCoords JScript sample
MeterLibrary
MicrophoneBvr
MicrophoneBvr Class
Min (DABbox2 Properties)
Min (DABbox3 Properties)
Miscellaneous DAStatic Functions
Miscellaneous DAStatic Properties
Mix (DAStatic Functions Relevant to DASound Objects)
mix (Static Methods Relevant to SoundBvr Objects)
MixArray (DAStatic Functions Relevant to DASound Objects)
mixArray (Static Methods Relevant to SoundBvr Objects)
Mm (Miscellaneous DAStatic Properties)
mm (Static Fields (Miscellaneous))
Mod (DAStatic Functions Relevant to DANumber Objects)
mod (Static Methods Relevant to NumberBvr Objects)
Model Class
Model Constructor
ModelMakerApplet Class
ModelMakerApplet Constructor
ModifiableBehavior
ModifiableBehavior Class
ModifiableBehavior Constructor
MontageBvr Class
Montages
MouseEventsEnabled
MouseEventsEnabled Property
MouseEventsEnabled Property and Mouse Events
MousePosition (DAStatic Properties Relevant to DAPoint2 Objects)
mouseposition (Static Fields Relevant to Point2Bvr Objects)
Move
Movie Java sample
Movie JScript sample
Movie VBScript sample
MsCubes Java sample
MsCubes VBScript sample
MSWorldLogo JScript sample
Mul (DAStatic Functions Relevant to DANumber Objects)
Mul (DAVector2 Functions)
Mul (DAVector3 Functions)
mul (Static Methods Relevant to NumberBvr Objects)
mul (Vector2Bvr Class: Vector2Bvr Methods)
mul (Vector3Bvr Class: Vector3Bvr Methods)
MulAnim (DAVector2 Functions)
MulAnim (DAVector3 Functions)

N

Name
Navy (DAStatic Properties Relevant to DAColor Objects)
navy (Static Fields Relevant to ColorBvr Objects)
NE (DAStatic Functions Relevant to DANumber Objects)
ne (Static Methods Relevant to NumberBvr Objects)
Neg (DAStatic Functions Relevant to DANumber Objects)
neg (Static Methods Relevant to NumberBvr Objects)
neg (Static Methods Relevant to Vector2Bvr Objects)
neg (Static Methods Relevant to Vector3Bvr Objects)
NegVector2
NegVector3
Never (DAStatic Properties Relevant to DAEvent Objects)
never (Static Fields Relevant to DXMEvent Objects)
NewDrawingSurface
newUninit
newUninitBvr (ArrayBvr Methods)
newUninitBvr (Bbox2Bvr Methods)
newUninitBvr (CameraBvr Methods)
newUninitBvr (ColorBvr Methods)
newUninitBvr (DXMEvent Methods)
newUninitBvr (EndStyleBvr Methods)
newUninitBvr (FontStyleBvr Methods)
newUninitBvr (GeometryBvr Methods)
newUninitBvr (ImageBvr Methods)
newUninitBvr (JoinStyleBvr Methods)
newUninitBvr (LineStyleBvr Methods)
newUninitBvr (MatteBvr Methods)
newUninitBvr (MicrophoneBvr Methods)
newUninitBvr (MontageBvr Methods)
newUninitBvr (NumberBvr Methods)
newUninitBvr (Path2Bvr Methods)
newUninitBvr (Point2Bvr Methods)
newUninitBvr (Point3Bvr Methods)
newUninitBvr (SoundBvr Methods)
newUninitBvr (StringBvr Methods)
newUninitBvr (Transform2Bvr Methods)
newUninitBvr (Transform3Bvr Methods)
newUninitBvr (Vector2Bvr Methods)
newUninitBvr (Vector3Bvr Methods)
newUninitBvr(); (Bbox3Bvr Methods)
newUninitBvr(); (BooleanBvr Methods)
newUninitBvr(); (DashStyleBvr Methods)
Normalize (DAVector2 Functions)
Normalize (DAVector3 Functions)
normalize (Vector2Bvr Methods)
normalize (Vector3Bvr Methods)
Not (DAStatic Functions Relevant to DABoolean Objects)
not (Static Methods Relevant to BooleanBvr Objects)
NotEvent (DAStatic Functions Relevant to DAEvent Objects)
notEvent (Static Methods Relevant to DXMEvent Objects)
notify (BvrCallback Methods)
Notify (DAEvent Functions)
Notify (IDABvrHook Functions)
notify (UntilNotifier Methods)
notifyEvent
nth (ArrayBvr Methods)
Nth (DATuple Functions)
nth (TupleBvr Methods)
NthAnim
NumberBSpline
NumberBvr Class
NumFrames Property
NumFramesAcross Property
NumFramesDown Property

O

Object
Olive (DAStatic Properties Relevant to DAColor Objects)
olive (Static Fields Relevant to ColorBvr Objects)
onclick Event
ondblclick Event
onframeseek Event
oninit Event
onmarker Event (Path Control Events)
onmarker Event (Sprite Control Events)
onmedialoaded Event
onmousedown Event
onmousemove Event
onmouseout Event
onmouseover Event
onmouseup Event
onpause Event (Action Set)
onpause Event (Path Control Events)
onpause Event (Sprite Control Events)
onplay Event (Action Set)
onplay Event (Path Control Events)
onplay Event (Sprite Control Events)
onplaymarker Event (Path Control Events)
onplaymarker Event (Sprite Control Events)
onseek Event (Action Set)
onseek Event (Path Control Events)
onseek Event (Sprite Control Events)
onstop Event (Action Set)
onstop Event (Path Control Events)
onstop Event (Sprite Control Events)
opacity
Opacity (DADrawingSurface Subroutines)
Opacity (DAGeometry Functions)
Opacity (DAImage Functions)
opacity (GeometryBvr Methods)
opacity (ImageBvr Methods)
OpacityAnim (DADrawingSurface Subroutines)
OpacityAnim (DAGeometry Functions)
OpacityAnim (DAImage Functions)
OpaqueMatte (DAStatic Properties Relevant to DAMatte Objects)
opaqueMatte (Static Fields Relevant to MatteBvr Objects)
Operations on Geometries
Or (DAStatic Functions Relevant to DABoolean Objects)
or (Static Methods Relevant to BooleanBvr Objects)
OrEvent (DAStatic Functions Relevant to DAEvent Objects)
orEvent (Static Methods Relevant to DXMEvent Objects)
Origin2 (DAStatic Properties Relevant to DAPoint2 Objects)
origin2 (Static Fields Relevant to Point2Bvr Objects)
Origin3 (DAStatic Properties Relevant to DAPoint3 Objects)
origin3 (Static Fields Relevant to Point3Bvr Objects)
Oval (DADrawingSurface Subroutines)
Oval (DAStatic Functions Relevant to DAPath2 Objects)
oval (Static Methods Relevant to Path2Bvr Objects)
Oval Method
Oval Method (Path Control Events)
OvalAnim
Overlay (DAStatic Functions Relevant to DAImage Objects)
overlay (O)
overlay (Static Methods Relevant to ImageBvr Objects)
OverlayArray (DAStatic Functions Relevant to DAImage Objects)
overlayArray (Static Methods Relevant to ImageBvr Objects)
OverlayImage

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

P

paint
pairBvr
PairObject Class
PairObject Constructor
Pan (DASound Functions)
pan (SoundBvr Methods)
Pan (Using Sound)
PanAnim
ParallelCamera (DAStatic Functions Relevant to DACamera Objects)
parallelCamera (Static Methods Relevant to CameraBvr Objects)
ParallelCameraAnim
ParallelTransform2 (DATransform3 Functions)
parallelTransform2 (Transform3Bvr Methods)
Parent
path
Path Control
Path Control Events
Path Control Methods
Path Control Properties
Path DirectAnimation control sample
Path2Bvr Class
Path2Bvr fill(ImageBvr im, LineStyleBvr ls)
Path2Bvr.draw(LineStyleBvr ls)
Pause Method (Action Set)
Pause Method (Path Control Events)
Pause Method (Sprite Control Events)
PerspectiveCamera (DAStatic Functions Relevant to DACamera Objects)
perspectiveCamera (Static Methods Relevant to CameraBvr Objects)
PerspectiveCameraAnim
PerspectiveImg JScript sample
Phase (DASound Functions)
phase (SoundBvr Methods)
PhaseAnim
Pick3 Java sample
Pick3 VBScript sample
Pickable (DAGeometry Functions)
Pickable (DAImage Functions)
PickableGeometry Class
PickableGeometry Constructor
PickableImage Class
PickableImage Constructor
PickableOccluded
PickEvent
pie
Pie Method
PieDegrees (DADrawingSurface Subroutines)
PieDegrees (DAStatic Functions Relevant to DAPath2 Objects)
pieDegrees (Static Methods Relevant to Path2Bvr Objects)
PieRadians
PieRadians (DADrawingSurface Subroutines)
PieRadiansAnim
Pixel
Pixel-Based Space
pixelBvr
PixelConstructionMode
PixelCoords JScript sample
PixelLibrary
Plane3D JScript sample
Play Method (Action Set)
Play Method (Path Control Events)
Play Method (Sprite Control Events)
PlayRate Property
PlayState Property (Action Set)
Playstate Property (Path Control Events)
PlayState Property (Sprite Control Events)
point (2-D)
point (3-D)
point light
Point2 (DAStatic Functions Relevant to DAPoint2 Objects)
point2 (Static Methods Relevant to Point2Bvr Objects)
Point2Anim
Point2BSpline
Point2Bvr Class
Point2Polar (DAStatic Functions Relevant to DAPoint2 Objects)
point2Polar (Static Methods Relevant to Point2Bvr Objects)
Point2PolarAnim
Point3 (DAStatic Functions Relevant to DAPoint3 Objects)
point3 (Static Methods Relevant to Point3Bvr Objects)
Point3Anim
Point3BSpline
Point3Bvr Class
Point3Spherical (DAStatic Functions Relevant to DAPoint3 Objects)
point3Spherical (Static Methods Relevant to Point3Bvr Objects)
Point3SphericalAnim
PointLight (DAStatic Properties Relevant to DAGeometry Objects)
pointLight (Static Fields Relevant to GeometryBvr Objects)
PolarCoordAngle (DAPoint2 Properties)
PolarCoordAngle (DAVector2 Properties)
PolarCoordLength (DAPoint2 Properties)
PolarCoordLength (DAVector2 Properties)
PolyDrawPath (DAStatic Functions Relevant to DAPath2 Objects)
polydrawPath (Static Methods Relevant to Path2Bvr Objects)
Polygon
Polygon Method
Polygon Method (Path Control Events)
Polyline (DADrawingSurface Subroutines)
Polyline (DAStatic Functions Relevant to DAPath2 Objects)
polyline (Static Methods Relevant to Path2Bvr Objects)
PolyLine Method
PolyLine Method (Path Control Events)
PolySpline Method
Pow (DAStatic Functions Relevant to DANumber Objects)
pow (Static Methods Relevant to NumberBvr Objects)
Predicate (DAStatic Functions Relevant to DAEvent Objects)
predicate (Static Methods Relevant to DXMEvent Objects)
Preferences Class
Preferences Constructor
Preferences.COLOR_KEY_BLUE
Preferences.COLOR_KEY_GREEN
Preferences.COLOR_KEY_RED
Preferences.DITHERING
Preferences.ENGINE_OPTIMIZATIONS
Preferences.FILL_MODE
Preferences.MAX_FRAMES_PER_SEC
Preferences.OVERRIDE_APPLICATION_PREFERENCES
Preferences.PERSPECTIVE_CORRECT
Preferences.RGB_LIGHTING_MODE
Preferences.SHADE_MODE
Preferences.TEXTURE_QUALITY
Preferences.USE_3-D_HW
Preferences.USE_VIDEOMEM
PreserveAspectRatio Property
Progress
Project (DAPoint3 Functions)
project (Point3Bvr Methods)
propagate
PropertyDispatcher Class
PropertyDispatcher Constructor
public final static int FILL_MODE_POINT
public final static int FILL_MODE_SOLID
public final static int FILL_MODE_WIREFRAME
public final static int SHADE_MODE_GOURAUD
public final static int SHADE_MODE_PHONG
public final static int TEXTURE_QUALITY_LINEAR
public final static int TEXTURE_QUALITY_NEAREST
public final static MAX_FRAMES_PER_SEC
public final static SHADE_MODE_FLAT
public final static String COLOR_KEY_BLUE
public final static String COLOR_KEY_GREEN
public final static String COLOR_KEY_RED
public final static String DITHERING
public final static String ENGINE_OPTIMIZATIONS
public final static String FILL_MODE
public final static String OVERRIDE_APPLICATION_PREFERENCES
public final static String PERSPECTIVE_CORRECT
public final static String RGB_LIGHTING_MODE
public final static String SHADE_MODE
public final static String TEXTURE_QUALITY
public final static String USE_3-D_HW
public final static USE_VIDEOMEM
Purple (DAStatic Properties Relevant to DAColor Objects)
purple (Static Fields Relevant to ColorBvr Objects)

R

RadialGradientPolygon (DAStatic Functions Relevant to DAImage Objects)
radialGradientPolygon (Static Methods Relevant to ImageBvr Objects)
RadialGradientPolygonAnim
RadialGradientRegularPoly (DAStatic Functions Relevant to DAImage Objects)
radialGradientRegularPoly (Static Methods Relevant to ImageBvr Objects)
RadialGradientRegularPolyAnim
RadialGradientSquare (DAStatic Functions Relevant to DAImage Objects)
radialGradientSquare (Static Methods Relevant to ImageBvr Objects)
RadialGradientSquareAnim
radiansToDegrees
Random JScript sample
Rate (DASound Functions)
rate (SoundBvr Methods)
RateAnim
Ray (DAStatic Functions Relevant to DAPath2 Objects)
ray (Static Methods Relevant to Path2Bvr Objects)
Rect (DADrawingSurface Subroutines)
Rect (DAStatic Functions Relevant to DAPath2 Objects)
rect (Static Methods Relevant to Path2Bvr Objects)
Rect Method
Rect Method (Path Control Events)
RectAnim
Red (DAColor Properties)
Red (DAStatic Properties Relevant to DAColor Objects)
red (Static Fields Relevant to ColorBvr Objects)
registerCallback
registerErrorAndWarningReceiver
registerErrorAndWarningReceiver (DXMCanvas Methods from Viewer Interface)
registerErrorAndWarningReceiver (ModelMakerApplet Methods)
registerErrorAndWarningReceiver (Viewer Methods)
Relative Property
remove
removeModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 1)
removeModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 2)
removeNotify
Render (DAGeometry Functions)
Render (DAMontage Functions)
render (Java Reference: GeometryBvr Class: GeometryBvr Methods: 1)
render (Java Reference: GeometryBvr Class: GeometryBvr Methods: 2)
render (Java Reference: MontageBvr Class: MontageBvr Methods: 3)
RenderSound
repeat (Behavior Methods)
Repeat (DABehavior Functions)
Repeat Property (Path Control Events)
Repeat Property (Sprite Control Events)
repeatForever (Behavior Methods)
RepeatForever (DABehavior Functions)
ReportGC
Reset
reshape
Resize JScript sample
RestoreGraphicsState
RightButtonDown (DAStatic Properties Relevant to DAEvent Objects)
rightButtonDown (Static Fields Relevant to DXMEvent Objects)
RightButtonState (DAStatic Properties Relevant to DABoolean Objects)
rightButtonState (Static Fields Relevant to BooleanBvr Objects)
RightButtonUp (DAStatic Properties Relevant to DAEvent Objects)
rightButtonUp (Static Fields Relevant to DXMEvent Objects)
rotate (Static Methods Relevant to Transform2Bvr Objects)
rotate (Static Methods Relevant to Transform3Bvr Objects)
Rotate Method
Rotate2
Rotate2Anim
Rotate2-Degrees
Rotate2Rate
Rotate2RateDegrees
Rotate3
Rotate3Anim
Rotate3-Degrees
Rotate3Rate
Rotate3RateDegrees
rotateDegrees (Static Methods Relevant to Transform2Bvr Objects)
rotateDegrees (Static Methods Relevant to Transform3Bvr Objects)
rotateRate (Static Methods Relevant to Transform2Bvr Objects)
rotateRate (Static Methods Relevant to Transform3Bvr Objects)
rotateRateDegrees (Static Methods Relevant to Transform2Bvr Objects)
rotateRateDegrees (Static Methods Relevant to Transform3Bvr Objects)
Rotational JScript sample
Round (DAStatic Functions Relevant to DANumber Objects)
round (Static Methods Relevant to NumberBvr Objects)
RoundRect (DADrawingSurface Subroutines)
RoundRect (DAStatic Functions Relevant to DAPath2 Objects)
roundRect (Static Methods Relevant to Path2Bvr Objects)
RoundRect Method
RoundRectAnim
run
Runners VBScript sample
runOnce (Behavior Methods)
RunOnce (DABehavior Functions)

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

S

Saturation
SaveGraphicsState
scale (Java Reference: Static Methods Relevant to Transform2Bvr Objects: 1)
scale (Java Reference: Static Methods Relevant to Transform2Bvr Objects: 2)
scale (Java Reference: Static Methods Relevant to Transform3Bvr Objects: 3)
scale (Java Reference: Static Methods Relevant to Transform3Bvr Objects: 4)
Scale Method
Scale2 (DAStatic Functions Relevant to DATransform2 Objects)
scale2 (Static Methods Relevant to Transform2Bvr Objects)
Scale2Anim
Scale2Rate (DAStatic Functions Relevant to DATransform2 Objects)
scale2Rate (Static Methods Relevant to Transform2Bvr Objects)
Scale2Uniform
Scale2UniformAnim
Scale2UniformRate
Scale2Vector
Scale3 (DAStatic Functions Relevant to DATransform3 Objects)
scale3 (Static Methods Relevant to Transform3Bvr Objects)
Scale3Anim
Scale3Rate (DAStatic Functions Relevant to DATransform3 Objects)
scale3Rate (Static Methods Relevant to Transform3Bvr Objects)
Scale3Uniform
Scale3UniformAnim
Scale3UniformRate
Scale3Vector
scaleRate (Static Methods Relevant to Transform2Bvr Objects)
scaleRate (Static Methods Relevant to Transform3Bvr Objects)
ScriptCallback
Scripting Reference Introduction
ScrollSwitch VBScript sample
Second
SecondaryFillColor
SeededRandom (DAStatic Functions Relevant to DANumber Objects)
seededRandom (Static Methods Relevant to NumberBvr Objects)
Seek Method (Action Set)
Seek Method (Path Control Events)
Seek Method (Sprite Control Events)
Sequence (DAStatic Functions Relevant to DABehavior Objects)
sequence (Static Methods Relevant to Behavior Objects)
Sequencer Control
Sequencer Control Events
Sequencer Control Methods
Sequencing JScript sample
set (Java Reference: Preferences Class: Preferences Methods: 1)
set (Java Reference: Preferences Class: Preferences Methods: 2)
set (Java Reference: Preferences Class: Preferences Methods: 3)
set (Java Reference: Preferences Class: Preferences Methods: 4)
setControl
SetFillColor Method
SetFillStyle Method
SetFocus
SetFont Method
SetGradientFill Method
SetGradientShape Method
SetHatchFill Method
SetIdentity Method
setImage
setImportBase
SetLineColor Method
SetLineStyle Method
setModel (DXMApplet Methods)
setModel (DXMCanvas Methods)
setModel (ModelMakerApplet Methods)
setPropertyName
setSound
SetStatusString
SetTextureFill Method
SG-DrawingSurface DirectAnimation control sample
SG-Preserve DirectAnimation control sample
Shapes JScript sample
show
showModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 1)
showModel (Java Reference: DXMCanvas Class: DXMCanvas Methods: 2)
ShowWhatsThis
Silence (DAStatic Properties Relevant to DASound Objects)
silence (Static Fields Relevant to SoundBvr Objects)
Silver (DAStatic Properties Relevant to DAColor Objects)
silver (Static Fields Relevant to ColorBvr Objects)
Sin (DAStatic Functions Relevant to DANumber Objects)
sin (Static Methods Relevant to NumberBvr Objects)
SinSynth (DAStatic Properties Relevant to DASound Objects)
sinSynth (Static Fields Relevant to SoundBvr Objects)
Site
Size (DAFontStyle Functions)
Size (DAImportationResult Properties)
size (FontStyleBvr Methods)
SizeAnim
SlowInSlowOut (DAStatic Functions Relevant to DANumber Objects)
slowInSlowOut (Static Methods Relevant to NumberBvr Objects)
SlowInSlowOutAnim
Snapshot
snapshotEvent
Solar Java sample
SolidColorImage (DAStatic Functions Relevant to DAImage Objects)
solidColorImage (Static Methods Relevant to ImageBvr Objects)
sound
Sound (DAImportationResult Properties)
Sound (DAViewerControl Properties)
Sound Java sample
SoundBvr Class
SoundSource (DAStatic Functions Relevant to DAGeometry Objects)
soundSource (Static Methods Relevant to GeometryBvr Objects)
source light
SourceURL Property
SourceURL Property (Sprite Control Events)
SphericalCoordLength (DAPoint3 Properties)
SphericalCoordLength (DAVector3 Properties)
SphericalCoordXYAngle
SphericalCoordYZAngle (DAPoint3 Properties)
SphericalCoordYZAngle (DAVector3 Properties)
SpinIE DirectAnimation control sample
spline
Spline Method
SplineLogo VBScript sample
Splines Java sample
SpotLight (DAStatic Functions Relevant to DAGeometry Objects)
spotLight (Static Methods Relevant to GeometryBvr Objects)
SpotLightAnim
sprite
Sprite Control
Sprite Control Events
Sprite Control Methods
Sprite Control Properties
Sqrt (DAStatic Functions Relevant to DANumber Objects)
sqrt (Static Methods Relevant to NumberBvr Objects)
Start (DAViewerControl Subroutines)
start (DXMApplet Methods)
startModel (DXMCanvas Methods from Viewer Interface)
startModel (Viewer Methods)
StartTime JScript sample
Static Fields (Miscellaneous)
Static Fields Relevant to BooleanBvr Objects
Static Fields Relevant to ColorBvr Objects
Static Fields Relevant to DashStyleBvr Objects
Static Fields Relevant to DXMEvent Objects
Static Fields Relevant to EndStyleBvr Objects
Static Fields Relevant to FontStyleBvr Objects
Static Fields Relevant to GeometryBvr Objects
Static Fields Relevant to ImageBvr Objects
Static Fields Relevant to JoinStyleBvr Objects
Static Fields Relevant to LineStyleBvr Objects
Static Fields Relevant to MatteBvr Objects
Static Fields Relevant to MicrophoneBvr Objects
Static Fields Relevant to MontageBvr Objects
Static Fields Relevant to NumberBvr Objects
Static Fields Relevant to Point2Bvr Objects
Static Fields Relevant to Point3Bvr Objects
Static Fields Relevant to SoundBvr Objects
Static Fields Relevant to Transform2Bvr Objects
Static Fields Relevant to Transform3Bvr Objects
Static Fields Relevant to Vector2Bvr Objects
Static Fields Relevant to Vector3Bvr Objects
Static Methods (Miscellaneous)
Static Methods Relevant to Behavior Objects
Static Methods Relevant to BooleanBvr Objects
Static Methods Relevant to CameraBvr Objects
Static Methods Relevant to ColorBvr Objects
Static Methods Relevant to DXMApplet Objects
Static Methods Relevant to DXMEvent Objects
Static Methods Relevant to FontStyleBvr Objects
Static Methods Relevant to GeometryBvr Objects
Static Methods Relevant to ImageBvr Objects
Static Methods Relevant to MatteBvr Objects
Static Methods Relevant to MontageBvr Objects
Static Methods Relevant to NumberBvr Objects
Static Methods Relevant to Path2Bvr Objects
Static Methods Relevant to Point2Bvr Objects
Static Methods Relevant to Point3Bvr Objects
Static Methods Relevant to SoundBvr Objects
Static Methods Relevant to StringBvr Objects
Static Methods Relevant to Transform2Bvr Objects
Static Methods Relevant to Transform3Bvr Objects
Static Methods Relevant to TupleBvr Objects
Static Methods Relevant to Vector2Bvr Objects
Static Methods Relevant to Vector3Bvr Objects
Statics Class
Statics.defaultFont
Statics.defaultLineStyle
Statics.public static Path2Bvr polyline(Point2Bvr[] points)
stop
Stop Method (Action Set)
Stop Method (Path Control Events)
Stop Method (Sprite Control Events)
stopModel (DXMCanvas Methods from Viewer Interface)
stopModel (Viewer Methods)
Strikethrough (DAFontStyle Functions)
strikethrough (FontStyleBvr Methods)
StringBvr Class
StringImage (DAStatic Functions Relevant to DAImage Objects)
stringImage (Static Methods Relevant to ImageBvr Objects)
StringImageAnim
StringPath (DAStatic Functions Relevant to DAPath2 Objects)
stringPath (Static Methods Relevant to Path2Bvr Objects)
StringPathAnim
Structured Graphics Control
Sub (DAStatic Functions Relevant to DANumber Objects)
sub (Java Reference: Static Methods Relevant to Point2Bvr Objects: 1)
sub (Java Reference: Static Methods Relevant to Point2Bvr Objects: 2)
sub (Java Reference: Static Methods Relevant to Point3Bvr Objects: 3)
sub (Java Reference: Static Methods Relevant to Point3Bvr Objects: 4)
sub (Java Reference: Static Methods Relevant to Vector2Bvr Objects: 5)
sub (Java Reference: Static Methods Relevant to Vector3Bvr Objects: 6)
sub (Static Methods Relevant to NumberBvr Objects)
SubPoint2
SubPoint2Vector
SubPoint3
SubPoint3Vector
substituteTime (Behavior Methods)
SubstituteTime (DABehavior Functions)
SubVector2
SubVector3
Switch Java sample
SwitchTo (DABehavior Subroutines)
switchTo (ModifiableBehavior Methods)

T

TabStop
Tag
Tan (DAStatic Functions Relevant to DANumber Objects)
tan (Static Methods Relevant to NumberBvr Objects)
Target Property
Teal (DAStatic Properties Relevant to DAColor Objects)
teal (Static Fields Relevant to ColorBvr Objects)
Text
Text Method
textAntialiasing
TextMask DirectAnimation control sample
TextMatte (DAStatic Functions Relevant to DAMatte Objects)
textMatte (Static Methods Relevant to MatteBvr Objects)
TextPoint
texture
Texture (DAGeometry Functions)
texture (GeometryBvr Methods)
ThenEvent (DAStatic Functions Relevant to DAEvent Objects)
thenEvent (Static Methods Relevant to DXMEvent Objects)
tick (Java Reference: DXMCanvas Class: DXMCanvas Methods from Viewer Interface: 1)
tick (Java Reference: DXMCanvas Class: DXMCanvas Methods from Viewer Interface: 2)
tick (Java Reference: Viewer Interface: Viewer Methods: 3)
tick (Java Reference: Viewer Interface: Viewer Methods: 4)
tile
Tile (DAImage Functions)
tile (ImageBvr Methods)
Tile Java sample
Tile JScript sample
Time Property (Action Set)
Time Property (Path Control Events)
Time Property (Sprite Control Events)
Timer (DAStatic Functions Relevant to DAEvent Objects)
timer (Static Methods Relevant to DXMEvent Objects)
TimerAnim
TimerInterval Property (Path Control Events)
TimerInterval Property (Sprite Control Events)
toBvr (Static Methods Relevant to BooleanBvr Objects)
toBvr (Static Methods Relevant to NumberBvr Objects)
toBvr (Static Methods Relevant to StringBvr Objects)
ToDegrees
ToolTipText
Top
ToRadians
ToString (DANumber Functions)
toString (Java Reference: NumberBvr Class: NumberBvr Methods: 1)
toString (Java Reference: NumberBvr Class: NumberBvr Methods: 2)
ToStringAnim
transform (CameraBvr Methods)
Transform (DACamera Functions)
Transform (DADrawingSurface Subroutines)
Transform (DAGeometry Functions)
Transform (DAImage Functions)
Transform (DAMatte Functions)
Transform (DAMicrophone Functions)
Transform (DAPath2 Functions)
Transform (DAPoint2 Functions)
Transform (DAPoint3 Functions)
Transform (DAVector2 Functions)
Transform (DAVector3 Functions)
transform (GeometryBvr Methods)
transform (ImageBvr Methods)
transform (MatteBvr Methods)
transform (MicrophoneBvr Methods)
transform (Path2Bvr Methods)
transform (Point2Bvr Methods)
transform (Point3Bvr Methods)
transform (Vector2Bvr Methods)
transform (Vector3Bvr Methods)
Transform Property
Transform2Bvr Class
Transform3Bvr Class
transform3x2
Transform3x2Anim
transform4x4
Transform4x4 Method
Transform4x4Anim
Transformations
translate (Java Reference: Static Methods Relevant to Transform2Bvr Objects: 1)
translate (Java Reference: Static Methods Relevant to Transform2Bvr Objects: 2)
translate (Java Reference: Static Methods Relevant to Transform2Bvr Objects: 3)
translate (Java Reference: Static Methods Relevant to Transform3Bvr Objects: 4)
translate (Java Reference: Static Methods Relevant to Transform3Bvr Objects: 5)
translate (Java Reference: Static Methods Relevant to Transform3Bvr Objects: 6)
Translate Method
Translate2
Translate2Anim
Translate2Point
Translate2Rate
Translate2Vector
Translate3
Translate3Anim
Translate3Point
Translate3Rate
Translate3Vector
translateRate (Static Methods Relevant to Transform2Bvr Objects)
translateRate (Static Methods Relevant to Transform3Bvr Objects)
trigger (Java Reference: AppTriggeredEvent Class: AppTriggeredEvent Methods: 1)
trigger (Java Reference: AppTriggeredEvent Class: AppTriggeredEvent Methods: 2)
TriggerEvent
tripleBvr
trueBvr
TupleBvr Class
TupleBvr Constructor

More entries...


Index

A B C D E F G H I J K L M N O P R S T U V W X Y Z

U

Underline (DAFontStyle Functions)
underline (FontStyleBvr Methods)
Undetectable (DAGeometry Functions)
Undetectable (DAImage Functions)
undetectable (GeometryBvr Methods)
undetectable (ImageBvr Methods)
UninitializedArray
UninitializedTuple
union (Static Methods Relevant to GeometryBvr Objects)
union (Static Methods Relevant to MatteBvr Objects)
union (Static Methods Relevant to MontageBvr Objects)
Union Java sample
unionArray
UnionGeometry
UnionGeometryArray
UnionMatte
UnionMontage
Units
unregisterCallback
Until (DAStatic Functions Relevant to DABehavior Objects)
until (Static Methods Relevant to Behavior Objects)
UntilEx (DAStatic Functions Relevant to DABehavior Objects)
untilEx (Static Methods Relevant to Behavior Objects)
UntilNotifier Interface
untilNotify
update
UpdateInterval
UseColorKey Property
Using_AFCMenus Java sample
Using_AFCScrollBar Java sample
Using_VBScript Java sample

V

VCR Java sample
vector
Vector2 (DAStatic Functions Relevant to DAVector2 Objects)
vector2 (Static Methods Relevant to Vector2Bvr Objects)
Vector2Anim
Vector2BSpline
Vector2Bvr Class
Vector2Polar (DAStatic Functions Relevant to DAVector2 Objects)
vector2Polar (Static Methods Relevant to Vector2Bvr Objects)
Vector2PolarAnim
Vector2PolarDegrees (DAStatic Functions Relevant to DAVector2 Objects)
vector2PolarDegrees (Static Methods Relevant to Vector2Bvr Objects)
Vector3 (DAStatic Functions Relevant to DAVector3 Objects)
vector3 (Static Methods Relevant to Vector3Bvr Objects)
Vector3Anim
Vector3BSpline
Vector3Bvr Class
vector3Obj.SphericalCoordXYAngle
Vector3Spherical (DAStatic Functions Relevant to DAVector3 Objects)
vector3Spherical (Static Methods Relevant to Vector3Bvr Objects)
Vector3SphericalAnim
VersionString
VerticalFillScale
Viewer Interface
Visible

W

WebVCR JScript sample
Weight (DAFontStyle Functions)
weight (FontStyleBvr Methods)
WeightAnim
WhatsThisHelpID
White (DAStatic Properties Relevant to DAColor Objects)
white (Static Fields Relevant to ColorBvr Objects)
Width (DALineStyle Functions)
Width (DAViewerControl Properties)
width (LineStyleBvr Methods)
WidthAnim
Windows Metafile to Structured Graphics Converter

X

X (DAPoint2 Properties)
X (DAPoint3 Properties)
X (DAVector2 Properties)
X (DAVector3 Properties)
xShear (Static Methods Relevant to Transform2Bvr Objects)
xShear (Static Methods Relevant to Transform3Bvr Objects)
XShear2
XShear2Anim
XShear2Rate
XShear3
XShear3Anim
XShear3Rate
xShearRate (Static Methods Relevant to Transform2Bvr Objects)
xShearRate (Static Methods Relevant to Transform3Bvr Objects)
XVector2 (DAStatic Properties Relevant to DAVector2 Objects)
xVector2 (Static Fields Relevant to Vector2Bvr Objects)
XVector3 (DAStatic Properties Relevant to DAVector3 Objects)
xVector3 (Static Fields Relevant to Vector3Bvr Objects)

Y

Y (DAPoint2 Properties)
Y (DAPoint3 Properties)
Y (DAVector2 Properties)
Y (DAVector3 Properties)
Yellow (DAStatic Properties Relevant to DAColor Objects)
yellow (Static Fields Relevant to ColorBvr Objects)
Yoyo DirectAnimation control sample
yShear (Static Methods Relevant to Transform2Bvr Objects)
yShear (Static Methods Relevant to Transform3Bvr Objects)
YShear2
YShear2Anim
YShear2Rate
YShear3
YShear3Anim
YShear3Rate
yShearRate (Static Methods Relevant to Transform2Bvr Objects)
yShearRate (Static Methods Relevant to Transform3Bvr Objects)
YVector2 (DAStatic Properties Relevant to DAVector2 Objects)
yVector2 (Static Fields Relevant to Vector2Bvr Objects)
YVector3 (DAStatic Properties Relevant to DAVector3 Objects)
yVector3 (Static Fields Relevant to Vector3Bvr Objects)

Z

Z (DAPoint3 Properties)
Z (DAVector3 Properties)
ZeroVector2 (DAStatic Properties Relevant to DAVector2 Objects)
zeroVector2 (Static Fields Relevant to Vector2Bvr Objects)
ZeroVector3 (DAStatic Properties Relevant to DAVector3 Objects)
zeroVector3 (Static Fields Relevant to Vector3Bvr Objects)
ZOrder
zShear
ZShear3
ZShear3Anim
ZShear3Rate
zShearRate
ZVector3 (DAStatic Properties Relevant to DAVector3 Objects)
zVector3 (Static Fields Relevant to Vector3Bvr Objects)


DirectAnimation SDK, JScript sample

3-D Cube


 Code Frame


DirectAnimation SDK, JScript sample

Arcs


Array Sample


DirectAnimation SDK, JScript sample

Button


 Display Frame


DrawingSurface Drawing Methods (Text)

Drawing Surface Sample


DirectAnimation SDK, JScript sample

Matte


DirectAnimation SDK, JScript sample

Sequencing


DirectAnimation SDK, JScript sample

Opacity


DirectAnimation SDK, JScript sample

Panning


Microsoft DirectAnimation Multimedia Controls Sample

Path Sample


DirectAnimation Controls Path Wizard

This page helps you to build a path

Shape to be used:

Shape parameters:
X position Y position Width Height

Path motion:

Repeat:

Playback Duration - seconds.milliseconds

You can copy the code from the first frame and paste it into a new file to use the path you've created, as displayed in the second frame.


Simple Pick Example

Simple Picking Example


DirectAnimation SDK, JScript sample

Pies


Polygon Path Wizard

This page generates a polygon shaped path.

X 1: Y 1: Shape to be used:
X 2: Y 2: Path motion:
X 3: Y 3:
Repeat:
X 4: Y 4:
X 5: Y 5: 		Playback Duration - seconds.milliseconds:

You can copy the code from the first frame and paste it into a new file to use the path you've created, as displayed in the second frame.


Microsoft DirectAnimation Controls - Path KeyFrame and OnMarker sample

This example uses a Keyframe-based path to define its shape,
and utilizes the onmarker event to change the text on the page.
Current position of the path:


Microsoft DirectAnimation Controls - Path Target sample

 This example assigns the path target depending upon the button clicked and plays relative to the target's current position.


DirectAnimation SDK, JScript sample

Rectangles


DirectAnimation SDK, JScript sample

Rotations


Microsoft DirectAnimation Multimedia Controls Samples - Sequencer

DirectAnimation Controls - Sequencer Sample


Microsoft DirectAnimation Multimedia Controls Sample

Arc


Microsoft DirectAnimation Multimedia Controls Sample

Oval


Microsoft DirectAnimation Multimedia Controls Sample

Pie


Microsoft DirectAnimation Multimedia Controls Sample

Polygon


Microsoft DirectAnimation Multimedia Controls Sample

PolyLine


Microsoft DirectAnimation Multimedia Controls Sample

Rectangle


Microsoft DirectAnimation Multimedia Controls Sample

Round Rectangle


Microsoft DirectAnimation Multimedia Controls Sample

SetFillColor / SetFillStyle / SetGradientFill


Texture fill

Tile Fill
Scale to Fit


Microsoft DirectAnimation Multimedia Controls Sample

Move the mouse pointer over the rectangle
and it will change into a star shape.


Microsoft DirectAnimation Multimedia Controls Sample - Structured Graphics utilizing DrawingSurface

Structured Graphics Sample utilizing DrawingSurface


DirectAnimation Controls - Structured Graphics and Sequencer Wizard

This page helps you to build your own rotating text logo

Logo Text
Font to be used:

Logo Text Color - must be integer value between 0 and 255 for each color.
Red Value Green Value Blue Value

Distance from center point:
X axis distance Y axis distance Initial text rotation

Rotation angles:
X axis Y axis Z axis

Rotation Speed - seconds.milliseconds

You can copy the code from the first frame and paste it into a new file to get the logo you've created, as displayed in the second frame.


Simple Sample


MIcrosoft DirectAnimation Controls sample - Sprite MouseMove Event

Feedback is displayed here...


Microsoft DirectAnimation Controls - Sprite OnMarker and Frame Property sample

This example shows conditional execution, based on the Sprite's FrameMarkers.
Mouse over the globe to start playback. Click on the globe to find out what part of the globe you selected.


Multi State Buttons

 Roll over Button to activate
Roll off Button to deactivate
Click Button to change state


Microsoft DirectAnimation Multimedia Controls Sample - Structured Graphics

Structured Graphics Sample


DirectAnimation SDK, JScript sample

Text


DirectAnimation SDK, JScript sample

Vectors


Index

A C D E G H I L O P R S T U

A

Accessing COM
AddGroupToGroup
AddGroupToGroup (IDirectPlay3)
AddPlayerToGroup
AddPlayerToGroup (IDirectPlay3)

C

CLASS_E_NOAGGREGATION
client/server session
Close
Close (IDirectPlay3)
CoCreateInstance
Connect
Connect (IDirectPlayLobby2)
CreateAddress
CreateAddress (IDirectPlayLobby2)
CreateCompoundAddress
CreateCompoundAddress (IDirectPlayLobby2)
CreateGroup
CreateGroup (IDirectPlay3)
CreateGroupInGroup
CreateGroupInGroup (IDirectPlay3)
CreatePlayer
CreatePlayer (IDirectPlay3)

D

DeleteGroupFromGroup
DeleteGroupFromGroup (IDirectPlay3)
DeletePlayerFromGroup
DeletePlayerFromGroup (IDirectPlay3)
DestroyGroup
DestroyGroup (IDirectPlay3)
DestroyPlayer
DestroyPlayer (IDirectPlay3)
DirectPlay address
DirectPlay defined property
DirectPlayCreate
DirectPlayEnumerate
DirectPlayLobbyCreate
DP_OK
DPACCOUNTDESC
DPCAPS
DPCAPS_ENCRYPTIONSUPPORTED
DPCAPS_GROUPOPTIMIZED
DPCAPS_GUARANTEEDOPTIMIZED
DPCAPS_GUARANTEEDSUPPORTED
DPCAPS_ISHOST
DPCAPS_KEEPALIVEOPTIMIZED
DPCAPS_SIGNINGSUPPORTED
DPCHAT
DPCOMPORTADDRESS
DPCOMPOUNDADDRESSELEMENT
DPCONNECTION_DIRECTPLAY
DPCONNECTION_DIRECTPLAYLOBBY
DPCPA_DTRFLOW
DPCPA_NOFLOW
DPCPA_RTSDTRFLOW
DPCPA_RTSFLOW
DPCPA_XONXOFFFLOW
DPCREDENTIALS
dpDesc
DPENUMGROUPS_ALL (IDirectPlay3::EnumGroups)
DPENUMGROUPS_ALL (IDirectPlay3::EnumGroupsInGroup)
DPENUMGROUPS_LOCAL (IDirectPlay3::EnumGroups)
DPENUMGROUPS_LOCAL (IDirectPlay3::EnumGroupsInGroup)
DPENUMGROUPS_REMOTE (IDirectPlay3::EnumGroups)
DPENUMGROUPS_REMOTE (IDirectPlay3::EnumGroupsInGroup)
DPENUMGROUPS_SESSION (IDirectPlay3::EnumGroups)
DPENUMGROUPS_SESSION (IDirectPlay3::EnumGroupsInGroup)
DPENUMGROUPS_SHORTCUT
DPENUMGROUPS_STAGINGAREA (IDirectPlay3::EnumGroups)
DPENUMGROUPS_STAGINGAREA (IDirectPlay3::EnumGroupsInGroup)
DPENUMPLAYERS_ALL
DPENUMPLAYERS_GROUP
DPENUMPLAYERS_LOCAL (IDirectPlay3::EnumGroupPlayers)
DPENUMPLAYERS_LOCAL (IDirectPlay3::EnumPlayers)
DPENUMPLAYERS_REMOTE (IDirectPlay3::EnumGroupPlayers)
DPENUMPLAYERS_REMOTE (IDirectPlay3::EnumPlayers)
DPENUMPLAYERS_SERVERPLAYER (IDirectPlay3::EnumGroupPlayers)
DPENUMPLAYERS_SERVERPLAYER (IDirectPlay3::EnumPlayers)
DPENUMPLAYERS_SESSION
DPENUMPLAYERS_SPECTATOR (IDirectPlay3::EnumGroupPlayers)
DPENUMPLAYERS_SPECTATOR (IDirectPlay3::EnumPlayers)
DPENUMSESSIONS_ALL
DPENUMSESSIONS_ASYNC
DPENUMSESSIONS_AVAILABLE
DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_RETURNSTATUS
DPENUMSESSIONS_STOPASYNC
DPERR_ACCESSDENIED
DPERR_ACTIVEPLAYERS
DPERR_ALREADYINITIALIZED
DPERR_APPNOTSTARTED
DPERR_AUTHENTICATIONFAILED
DPERR_BUFFERTOOLARGE
DPERR_BUFFERTOOSMALL
DPERR_BUSY
DPERR_CANTADDPLAYER
DPERR_CANTCREATEGROUP
DPERR_CANTCREATEPLAYER
DPERR_CANTCREATEPROCESS
DPERR_CANTCREATESESSION
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CAPSNOTAVAILABLEYET
DPERR_CONNECTING
DPERR_ENCRYPTIONFAILED
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDCREDENTIALS
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_INVALIDPLAYER
DPERR_LOGONDENIED
DPERR_NOCAPS
DPERR_NOCONNECTION
DPERR_NOINTERFACE
DPERR_NOMESSAGES
DPERR_NONAMESERVERFOUND
DPERR_NONEWPLAYERS
DPERR_NOPLAYERS
DPERR_NOSESSIONS
DPERR_NOTLOBBIED
DPERR_NOTLOGGEDIN
DPERR_OUTOFMEMORY
DPERR_PLAYERLOST
DPERR_SENDTOOBIG
DPERR_SESSIONLOST
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNAVAILABLE
DPERR_UNINITIALIZED
DPERR_UNKNOWNAPPLICATION
DPERR_UNSUPPORTED
DPERR_USERCANCEL
DPESC_TIMEDOUT
DPGET_LOCAL (IDirectPlay3::GetGroupData)
DPGET_LOCAL (IDirectPlay3::GetPlayerData)
DPGET_REMOTE (IDirectPlay3::GetGroupData)
DPGET_REMOTE (IDirectPlay3::GetPlayerData)
DPGETCAPS_GUARANTEED (IDirectPlay3::GetCaps)
DPGETCAPS_GUARANTEED (IDirectPlay3::GetPlayerCaps)
DPGROUP_STAGINGAREA
dpId (DPMSG_CREATEPLAYERORGROUP)
dpId (DPMSG_DESTROYPLAYERORGROUP)
dpId (DPMSG_SETPLAYERORGROUPDATA)
dpId (DPMSG_SETPLAYERORGROUPNAME)
dpIdFrom
dpIdGroup (DPMSG_ADDGROUPTOGROUP)
dpIdGroup (DPMSG_ADDPLAYERTOGROUP)
dpIdGroup (DPMSG_DELETEGROUPFROMGROUP)
dpIdGroup (DPMSG_DELETEPLAYERFROMGROUP)
dpIdParent (DPMSG_CREATEPLAYERORGROUP)
dpIdParent (DPMSG_DESTROYPLAYERORGROUP)
dpIdParentGroup (DPMSG_ADDGROUPTOGROUP)
dpIdParentGroup (DPMSG_DELETEGROUPFROMGROUP)
dpIdPlayer (DPMSG_ADDPLAYERTOGROUP)
dpIdPlayer (DPMSG_DELETEPLAYERFROMGROUP)
DPLAPPINFO
DPLCONNECTION
DPLCONNECTION_CREATESESSION
DPLCONNECTION_JOINSESSION
DPLMSG_GENERIC
DPLMSG_GETPROPERTY
DPLMSG_GETPROPERTYRESPONSE
DPLMSG_SETPROPERTY
DPLMSG_SETPROPERTYRESPONSE
DPLMSG_STANDARD
DPLMSG_SYSTEM
DPLSYS_APPTERMINATED
DPLSYS_CONNECTIONSETTINGSREAD
DPLSYS_DPLAYCONNECTFAILED
DPLSYS_DPLAYCONNECTSUCCEEDED
DPMSG_ADDGROUPTOGROUP
DPMSG_ADDPLAYERTOGROUP
DPMSG_CHAT
DPMSG_CREATEPLAYERORGROUP
DPMSG_DELETEGROUPFROMGROUP
DPMSG_DELETEPLAYERFROMGROUP
DPMSG_DESTROYPLAYERORGROUP
DPMSG_GENERIC
DPMSG_HOST
DPMSG_SECUREMESSAGE
DPMSG_SESSIONLOST
DPMSG_SETPLAYERORGROUPDATA
DPMSG_SETPLAYERORGROUPNAME
DPMSG_SETSESSIONDESC
DPMSG_STARTSESSION
DPNAME
dpnName (DPMSG_CREATEPLAYERORGROUP)
dpnName (DPMSG_DESTROYPLAYERORGROUP)
dpnName (DPMSG_SETPLAYERORGROUPNAME)
DPOPEN_CREATE
DPOPEN_JOIN
DPOPEN_RETURNSTATUS
DPPLAYER_SERVERPLAYER
DPPLAYER_SPECTATOR
DPRECEIVE_ALL
DPRECEIVE_FROMPLAYER
DPRECEIVE_PEEK
DPRECEIVE_TOPLAYER
DPSECURITYDESC
DPSEND_ENCRYPTED
DPSEND_GUARANTEED
DPSEND_SIGNED
DPSESSION_CLIENTSERVER
DPSESSION_JOINDISABLED
DPSESSION_KEEPALIVE
DPSESSION_MIGRATEHOST
DPSESSION_MULTICASTSERVER
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_NOMESSAGEID
DPSESSION_PASSWORDREQUIRED
DPSESSION_PRIVATE
DPSESSION_SECURESERVER
DPSESSIONDESC2
DPSET_GUARANTEED (IDirectPlay3::SetGroupData)
DPSET_GUARANTEED (IDirectPlay3::SetGroupName)
DPSET_GUARANTEED (IDirectPlay3::SetPlayerData)
DPSET_GUARANTEED (IDirectPlay3::SetPlayerName)
DPSET_LOCAL (IDirectPlay3::SetGroupData)
DPSET_LOCAL (IDirectPlay3::SetGroupName)
DPSET_LOCAL (IDirectPlay3::SetPlayerData)
DPSET_LOCAL (IDirectPlay3::SetPlayerName)
DPSET_REMOTE (IDirectPlay3::SetGroupData)
DPSET_REMOTE (IDirectPlay3::SetGroupName)
DPSET_REMOTE (IDirectPlay3::SetPlayerData)
DPSET_REMOTE (IDirectPlay3::SetPlayerName)
dwAddressSize
dwBaudRate
dwCAPIProviderType
dwComPort
dwCurrentPlayers (DPMSG_CREATEPLAYERORGROUP)
dwCurrentPlayers (DPSESSIONDESC2)
dwDataSize (DPCOMPOUNDADDRESSELEMENT)
dwDataSize (DPLMSG_GETPROPERTYRESPONSE)
dwDataSize (DPLMSG_SETPROPERTY)
dwDataSize (DPMSG_CREATEPLAYERORGROUP)
dwDataSize (DPMSG_SECUREMESSAGE)
dwDataSize (DPMSG_SETPLAYERORGROUPDATA)
dwEncryptionAlgorithm
dwFlags (DPACCOUNTDESC)
dwFlags (DPCAPS)
dwFlags (DPCHAT)
dwFlags (DPCREDENTIALS)
dwFlags (DPLCONNECTION)
dwFlags (DPMSG_CHAT)
dwFlags (DPMSG_CREATEPLAYERORGROUP)
dwFlags (DPMSG_DESTROYPLAYERORGROUP)
dwFlags (DPMSG_SECUREMESSAGE)
dwFlags (DPNAME)
dwFlags (DPSECURITYDESC)
dwFlags (DPSESSIONDESC2)
dwFlowControl
dwHeaderLength
dwHundredBaud
dwLatency
dwLocalDataSize
dwMaxBufferSize
dwMaxLocalPlayers
dwMaxPlayers (DPCAPS)
dwMaxPlayers (DPSESSIONDESC2)
dwMaxQueueSize
dwParity
dwPlayerType (DPMSG_CREATEPLAYERORGROUP)
dwPlayerType (DPMSG_DESTROYPLAYERORGROUP)
dwPlayerType (DPMSG_SETPLAYERORGROUPDATA)
dwPlayerType (DPMSG_SETPLAYERORGROUPNAME)
dwPropertyData (DPLMSG_GETPROPERTYRESPONSE)
dwPropertyData (DPLMSG_SETPROPERTY)
dwRemoteDataSize
dwRequestID (DPLMSG_GETPROPERTY)
dwRequestID (DPLMSG_GETPROPERTYRESPONSE)
dwRequestID (DPLMSG_SETPROPERTY)
dwRequestID (DPLMSG_SETPROPERTYRESPONSE)
dwReserved1
dwReserved2
dwSize (DPACCOUNTDESC)
dwSize (DPCAPS)
dwSize (DPCHAT)
dwSize (DPCREDENTIALS)
dwSize (DPLAPPINFO)
dwSize (DPLCONNECTION)
dwSize (DPNAME)
dwSize (DPSECURITYDESC)
dwSize (DPSESSIONDESC2)
dwStopBits
dwTimeout
dwType (DPLMSG_GENERIC)
dwType (DPLMSG_GETPROPERTY)
dwType (DPLMSG_GETPROPERTYRESPONSE)
dwType (DPLMSG_SETPROPERTY)
dwType (DPLMSG_SETPROPERTYRESPONSE)
dwType (DPMSG_ADDGROUPTOGROUP)
dwType (DPMSG_ADDPLAYERTOGROUP)
dwType (DPMSG_CHAT)
dwType (DPMSG_CREATEPLAYERORGROUP)
dwType (DPMSG_DELETEGROUPFROMGROUP)
dwType (DPMSG_DELETEPLAYERFROMGROUP)
dwType (DPMSG_DESTROYPLAYERORGROUP)
dwType (DPMSG_GENERIC)
dwType (DPMSG_SECUREMESSAGE)
dwType (DPMSG_SETPLAYERORGROUPDATA)
dwType (DPMSG_SETPLAYERORGROUPNAME)
dwType (DPMSG_SETSESSIONDESC)
dwType (DPMSG_STARTSESSION)
dwUser1
dwUser2
dwUser3
dwUser4

E

EnumAddress
EnumAddress (IDirectPlayLobby2)
EnumAddressCallback
EnumAddressTypeCallback
EnumAddressTypes
EnumAddressTypes (IDirectPlayLobby2)
EnumConnections
EnumConnections (IDirectPlay3)
EnumConnectionsCallback
EnumDPCallback
EnumGroupPlayers
EnumGroupPlayers (IDirectPlay3)
EnumGroups
EnumGroups (IDirectPlay3)
EnumGroupsInGroup
EnumGroupsInGroup (IDirectPlay3)
EnumLocalApplications
EnumLocalApplications (IDirectPlayLobby2)
EnumLocalApplicationsCallback
EnumPlayers
EnumPlayers (IDirectPlay3)
EnumPlayersCallback2
EnumSessions
EnumSessions (IDirectPlay3)
EnumSessionsCallback2

More entries...


Index

A C D E G H I L O P R S T U

G

GetCaps
GetCaps (IDirectPlay3)
GetConnectionSettings
GetConnectionSettings (IDirectPlayLobby2)
GetGroupConnectionSettings
GetGroupConnectionSettings (IDirectPlay3)
GetGroupData
GetGroupData (IDirectPlay3)
GetGroupFlags
GetGroupFlags (IDirectPlay3)
GetGroupName
GetGroupName (IDirectPlay3)
GetGroupParent
GetGroupParent (IDirectPlay3)
GetMessageCount
GetMessageCount (IDirectPlay3)
GetPlayerAccount
GetPlayerAccount (IDirectPlay3)
GetPlayerAddress
GetPlayerAddress (IDirectPlay3)
GetPlayerCaps
GetPlayerCaps (IDirectPlay3)
GetPlayerData
GetPlayerData (IDirectPlay3)
GetPlayerFlags
GetPlayerFlags (IDirectPlay3)
GetPlayerName
GetPlayerName (IDirectPlay3)
GetSessionDesc
GetSessionDesc (IDirectPlay3)
group
guidApplication (DPLAPPINFO)
guidApplication (DPSESSIONDESC2)
guidDataType
guidInstance
guidPlayer (DPLMSG_GETPROPERTY)
guidPlayer (DPLMSG_GETPROPERTYRESPONSE)
guidPlayer (DPLMSG_SETPROPERTY)
guidPlayer (DPLMSG_SETPROPERTYRESPONSE)
guidPropertyTag (DPLMSG_GETPROPERTY)
guidPropertyTag (DPLMSG_GETPROPERTYRESPONSE)
guidPropertyTag (DPLMSG_SETPROPERTY)
guidPropertyTag (DPLMSG_SETPROPERTYRESPONSE)
guidSP

H

host
hr (DPLMSG_GETPROPERTYRESPONSE)
hr (DPLMSG_SETPROPERTYRESPONSE)

I

idFromPlayer
IDirectPlay3::AddGroupToGroup
IDirectPlay3::AddPlayerToGroup
IDirectPlay3::Close
IDirectPlay3::CreateGroup
IDirectPlay3::CreateGroupInGroup
IDirectPlay3::CreatePlayer
IDirectPlay3::DeleteGroupFromGroup
IDirectPlay3::DeletePlayerFromGroup
IDirectPlay3::DestroyGroup
IDirectPlay3::DestroyPlayer
IDirectPlay3::EnumConnections
IDirectPlay3::EnumGroupPlayers
IDirectPlay3::EnumGroups
IDirectPlay3::EnumGroupsInGroup
IDirectPlay3::EnumPlayers
IDirectPlay3::EnumSessions
IDirectPlay3::GetCaps
IDirectPlay3::GetGroupConnectionSettings
IDirectPlay3::GetGroupData
IDirectPlay3::GetGroupFlags
IDirectPlay3::GetGroupName
IDirectPlay3::GetGroupParent
IDirectPlay3::GetMessageCount
IDirectPlay3::GetPlayerAccount
IDirectPlay3::GetPlayerAddress
IDirectPlay3::GetPlayerCaps
IDirectPlay3::GetPlayerData
IDirectPlay3::GetPlayerFlags
IDirectPlay3::GetPlayerName
IDirectPlay3::GetSessionDesc
IDirectPlay3::Initialize
IDirectPlay3::InitializeConnection
IDirectPlay3::Open
IDirectPlay3::Receive
IDirectPlay3::SecureOpen
IDirectPlay3::Send
IDirectPlay3::SendChatMessage
IDirectPlay3::SetGroupConnectionSettings
IDirectPlay3::SetGroupData
IDirectPlay3::SetGroupName
IDirectPlay3::SetPlayerData
IDirectPlay3::SetPlayerName
IDirectPlay3::SetSessionDesc
IDirectPlay3::StartSession
IDirectPlayLobby2::Connect
IDirectPlayLobby2::CreateAddress
IDirectPlayLobby2::CreateCompoundAddress
IDirectPlayLobby2::EnumAddress
IDirectPlayLobby2::EnumAddressTypes
IDirectPlayLobby2::EnumLocalApplications
IDirectPlayLobby2::GetConnectionSettings
IDirectPlayLobby2::ReceiveLobbyMessage
IDirectPlayLobby2::RunApplication
IDirectPlayLobby2::SendLobbyMessage
IDirectPlayLobby2::SetConnectionSettings
IDirectPlayLobby2::SetLobbyMessageEvent
idToGroup
idToPlayer
Initialize
Initialize (IDirectPlay3)
InitializeConnection
InitializeConnection (IDirectPlay3)
IPX service provider
IUnknown Interface
IUnknown::AddRef
IUnknown::QueryInterface
IUnknown::Release

L

latency
lobby client
lobby provider
lobby server
lobby session
lobby-aware application
lpAddress
lpChat
lpConn
lpData (DPCOMPOUNDADDRESSELEMENT)
lpData (DPMSG_CREATEPLAYERORGROUP)
lpData (DPMSG_SECUREMESSAGE)
lpData (DPMSG_SETPLAYERORGROUPDATA)
lpLocalData
lpPlayerName
lpRemoteData
lpSessionDesc
lpszAccountID
lpszAccountIDA
lpszAppName
lpszAppNameA
lpszCAPIProvider
lpszCAPIProviderA
lpszDomain
lpszDomainA
lpszLongName
lpszLongNameA
lpszMessage
lpszMessageA
lpszPassword (DPCREDENTIALS)
lpszPassword (DPSESSIONDESC2)
lpszPasswordA (DPCREDENTIALS)
lpszPasswordA (DPSESSIONDESC2)
lpszSessionName
lpszSessionNameA
lpszShortName
lpszShortNameA
lpszSSPIProvider
lpszSSPIProviderA
lpszUsername
lpszUsernameA

O

Open
Open (IDirectPlay3)

P

peer-to-peer session

R

Receive
Receive (IDirectPlay3)
ReceiveLobbyMessage
ReceiveLobbyMessage (IDirectPlayLobby2)
RunApplication
RunApplication (IDirectPlayLobby2)

S

secure session
SecureOpen
SecureOpen (IDirectPlay3)
Send
Send (IDirectPlay3)
SendChatMessage
SendChatMessage (IDirectPlay3)
SendLobbyMessage
SendLobbyMessage (IDirectPlayLobby2)
service provider
session
SetConnectionSettings
SetConnectionSettings (IDirectPlayLobby2)
SetGroupConnectionSettings
SetGroupConnectionSettings (IDirectPlay3)
SetGroupData
SetGroupData (IDirectPlay3)
SetGroupName
SetGroupName (IDirectPlay3)
SetLobbyMessageEvent
SetLobbyMessageEvent (IDirectPlayLobby2)
SetPlayerData
SetPlayerData (IDirectPlay3)
SetPlayerName
SetPlayerName (IDirectPlay3)
SetSessionDesc
SetSessionDesc (IDirectPlay3)
staging area
StartSession
StartSession (IDirectPlay3)
system message

T

TCP/IP service provider

U

user authentication


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

C/C++-based Sample Applications
CAggDirectDraw (CAggDirectDraw)
CAggDirectDraw Class
CAggDirectDraw::CAggDirectDraw
CAggDirectDraw::NonDelegatingQueryInterface
CAggDirectDraw::SetDirectDraw
CAggDirectDraw::SetDisplayMode
CAggDrawSurface (CAggDrawSurface)
CAggDrawSurface Class
CAggDrawSurface::Blt
CAggDrawSurface::CAggDrawSurface
CAggDrawSurface::GetDC
CAggDrawSurface::NonDelegatingQueryInterface
CAggDrawSurface::SetDirectDrawSurface
Calibrate
Calibrate (IAMExtDevice)
CallWorker
CallWorker (CAMThread)
CameraControl_Exposure
CameraControl_Focus
CameraControl_Iris
CameraControl_Pan
CameraControl_Roll
CameraControl_Tilt
CameraControl_Zoom
CameraControlProperty
CAMEvent (CAMEvent)
CAMEvent Class
CAMEvent::CAMEvent
CAMEvent::Check
CAMEvent::operator HANDLE
CAMEvent::Reset
CAMEvent::Set
CAMEvent::Wait
CAMMsgEvent Class
CAMMsgEvent::WaitMsg
CAMSchedule (CAMSchedule)
CAMSchedule Class
CAMSchedule::AddAdvisePacket
CAMSchedule::Advise
CAMSchedule::CAMSchedule
CAMSchedule::GetAdviseCount
CAMSchedule::GetEvent
CAMSchedule::GetNextAdviseTime
CAMSchedule::Unadvise
CAMThread (CAMThread)
CAMThread Class
CAMThread::CallWorker
CAMThread::CAMThread
CAMThread::CheckRequest
CAMThread::Close
CAMThread::Create
CAMThread::GetRequest
CAMThread::GetRequestHandle
CAMThread::GetRequestParam
CAMThread::InitialThreadProc
CAMThread::Reply
CAMThread::ThreadExists
CAMThread::ThreadProc
Cancel (Implemented INonDelegatingUnknown Methods)
Cancel (Methods in Vtable Order)
Cancel (CDeferredCommand)
Cancel (IDeferredCommand)
CancelDefaultHandling (IAMovie Interface: Methods in Vtable Order)
CancelDefaultHandling (IMediaEvent Interface: Methods in Vtable Order)
CancelDefaultHandling (IAMovie)
CancelDefaultHandling (IMediaEvent)
CancelDefaultHandling Method (IMediaEvent Object)
CancelNotification
CancelNotification (CBaseRenderer)
CancelRequest
CancelRequest (IResourceManager)
CanRoute
CanRoute (IAMCrossbar)
CanSeekBackward (Implemented INonDelegatingUnknown Methods)
CanSeekBackward (Methods in Vtable Order)
CanSeekBackward (CPosPassThru)
CanSeekBackward (IMediaPosition)
CanSeekBackward Method (IMediaPosition Object)
CanSeekForward (Implemented INonDelegatingUnknown Methods)
CanSeekForward (Methods in Vtable Order)
CanSeekForward (CPosPassThru)
CanSeekForward (IMediaPosition)
CanSeekForward Method (IMediaPosition Object)
CanUseOverlayStretch
CanUseOverlayStretch (IDirectDrawVideo)
CanUseScanLine
CanUseScanLine (IDirectDrawVideo)
Caption Property (IVideoWindow Object)
Capture and Preview Pin Requirements
Capture filter graphs
Capture filter graphs (Adding Audio Capture)
Capture filter graphs (Capture Filter Input Pins)
Capture filter graphs (Capture Introduction)
Capture filter graphs (Filter Graph Configuration)
Capture filter graphs (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs (Video Capture Filter Graphs)
Capture filter graphs (Video Preview Filter Graphs)
Capture filter graphs (WDM Overview)
Capture filter graphs (WDM Video Capture Architecture)
Capture filter graphs:adding audio capture
Capture filter graphs:adding audio capture (Adding Audio Capture)
Capture filter graphs:adding audio capture (Capture Filter Input Pins)
Capture filter graphs:adding audio capture (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs:adding audio capture (Video Capture Filter Graphs)
Capture filter graphs:adding audio capture (Video Preview Filter Graphs)
Capture filter graphs:building capture and preview
Capture filter graphs:capture statistics
Capture filter graphs:controlling
Capture filter graphs:input pins
Capture filter graphs:input pins (Adding Audio Capture)
Capture filter graphs:input pins (Capture Filter Input Pins)
Capture filter graphs:input pins (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs:input pins (Video Capture Filter Graphs)
Capture filter graphs:input pins (Video Preview Filter Graphs)
Capture filter graphs:saving the capture file
Capture filter graphs:video capture
Capture filter graphs:video capture (Adding Audio Capture)
Capture filter graphs:video capture (Capture Filter Input Pins)
Capture filter graphs:video capture (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs:video capture (Video Capture Filter Graphs)
Capture filter graphs:video capture (Video Preview Filter Graphs)
Capture filter graphs:video capture and preview combined
Capture filter graphs:video capture and preview combined (Adding Audio Capture)
Capture filter graphs:video capture and preview combined (Capture Filter Input Pins)
Capture filter graphs:video capture and preview combined (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs:video capture and preview combined (Video Capture Filter Graphs)
Capture filter graphs:video capture and preview combined (Video Preview Filter Graphs)
Capture filter graphs:video preview
Capture filter graphs:video preview (Adding Audio Capture)
Capture filter graphs:video preview (Capture Filter Input Pins)
Capture filter graphs:video preview (Video Capture and Preview Filter Graphs Combined)
Capture filter graphs:video preview (Video Capture Filter Graphs)
Capture filter graphs:video preview (Video Preview Filter Graphs)
Capture Filter Input Pins
Capture Introduction
Capture performance improvements
Capture performance improvements (Disk Settings in Window 95 and Later)
Capture performance improvements (Optimizing the Hard Disk for Capture)
Capture performance:hard disk
Capture performance:hard disk (Disk Settings in Window 95 and Later)
Capture performance:hard disk (Optimizing the Hard Disk for Capture)
Capture performance:Windows 95 settings
Capture performance:Windows 95 settings (Disk Settings in Window 95 and Later)
Capture performance:Windows 95 settings (Optimizing the Hard Disk for Capture)
capture topics
Capture, VFW
Capture:suggested reading
Capturing:suggested reading
categories, filter
CAutoLock (CAutoLock)
CAutoLock Class
CAutoLock::CAutoLock
cbAlign
CBaseAllocator (CBaseAllocator)
CBaseAllocator Class
CBaseAllocator::Alloc
CBaseAllocator::CBaseAllocator
CBaseAllocator::Commit
CBaseAllocator::Decommit
CBaseAllocator::Free
CBaseAllocator::GetBuffer
CBaseAllocator::GetProperties
CBaseAllocator::NonDelegatingQueryInterface
CBaseAllocator::NotifySample
CBaseAllocator::ReleaseBuffer
CBaseAllocator::SetProperties
CBaseAllocator::SetWaiting
CBaseBasicVideo (CBaseBasicVideo)
CBaseBasicVideo Class
CBaseBasicVideo::CBaseBasicVideo
CBaseBasicVideo::GetIDsOfNames
CBaseBasicVideo::GetTypeInfo
CBaseBasicVideo::GetTypeInfoCount
CBaseBasicVideo::Invoke
CBaseBasicVideo::NonDelegatingQueryInterface
CBaseControlVideo (CBaseControlVideo)
CBaseControlVideo Class
CBaseControlVideo::CBaseControlVideo
CBaseControlVideo::CheckSourceRect
CBaseControlVideo::CheckTargetRect
CBaseControlVideo::CopyImage
CBaseControlVideo::get_AvgTimePerFrame
CBaseControlVideo::get_BitErrorRate
CBaseControlVideo::get_BitRate
CBaseControlVideo::get_DestinationHeight
CBaseControlVideo::get_DestinationLeft
CBaseControlVideo::get_DestinationTop
CBaseControlVideo::get_DestinationWidth
CBaseControlVideo::get_SourceHeight
CBaseControlVideo::get_SourceLeft
CBaseControlVideo::get_SourceTop
CBaseControlVideo::get_SourceWidth
CBaseControlVideo::get_VideoHeight
CBaseControlVideo::get_VideoWidth
CBaseControlVideo::GetCurrentImage
CBaseControlVideo::GetDestinationPosition
CBaseControlVideo::GetImageSize
CBaseControlVideo::GetSourcePosition
CBaseControlVideo::GetSourceRect
CBaseControlVideo::GetStaticImage
CBaseControlVideo::GetTargetRect
CBaseControlVideo::GetVideoFormat
CBaseControlVideo::GetVideoPaletteEntries
CBaseControlVideo::GetVideoSize
CBaseControlVideo::IsDefaultSourceRect
CBaseControlVideo::IsDefaultTargetRect
CBaseControlVideo::IsUsingDefaultDestination
CBaseControlVideo::IsUsingDefaultSource
CBaseControlVideo::OnUpdateRectangles
CBaseControlVideo::OnVideoSizeChange
CBaseControlVideo::put_DestinationHeight
CBaseControlVideo::put_DestinationLeft
CBaseControlVideo::put_DestinationTop
CBaseControlVideo::put_DestinationWidth
CBaseControlVideo::put_SourceHeight
CBaseControlVideo::put_SourceLeft
CBaseControlVideo::put_SourceTop
CBaseControlVideo::put_SourceWidth
CBaseControlVideo::SetControlVideoPin
CBaseControlVideo::SetDefaultDestinationPosition
CBaseControlVideo::SetDefaultSourcePosition
CBaseControlVideo::SetDefaultSourceRect
CBaseControlVideo::SetDefaultTargetRect
CBaseControlVideo::SetDestinationPosition
CBaseControlVideo::SetSourcePosition
CBaseControlVideo::SetSourceRect
CBaseControlVideo::SetTargetRect
CBaseControlWindow (CBaseControlWindow)
CBaseControlWindow Class
CBaseControlWindow::CBaseControlWindow
CBaseControlWindow::DoGetWindowStyle
CBaseControlWindow::DoSetWindowStyle
CBaseControlWindow::get_AutoShow
CBaseControlWindow::get_BackgroundPalette
CBaseControlWindow::get_BorderColor
CBaseControlWindow::get_Caption
CBaseControlWindow::get_FullScreenMode
CBaseControlWindow::get_Height
CBaseControlWindow::get_Left
CBaseControlWindow::get_MessageDrain
CBaseControlWindow::get_Owner
CBaseControlWindow::get_Top
CBaseControlWindow::get_Visible
CBaseControlWindow::get_Width
CBaseControlWindow::get_WindowState
CBaseControlWindow::get_WindowStyle
CBaseControlWindow::get_WindowStyleEx
CBaseControlWindow::GetBorderColour
CBaseControlWindow::GetMaxIdealImageSize
CBaseControlWindow::GetMinIdealImageSize
CBaseControlWindow::GetOwnerWindow
CBaseControlWindow::GetRestorePosition
CBaseControlWindow::GetWindowPosition
CBaseControlWindow::HideCursor
CBaseControlWindow::IsAutoShowEnabled
CBaseControlWindow::IsCursorHidden
CBaseControlWindow::NotifyOwnerMessage
CBaseControlWindow::PossiblyEatMessage
CBaseControlWindow::put_AutoShow
CBaseControlWindow::put_BackgroundPalette
CBaseControlWindow::put_BorderColor
CBaseControlWindow::put_Caption
CBaseControlWindow::put_FullScreenMode
CBaseControlWindow::put_Height
CBaseControlWindow::put_Left
CBaseControlWindow::put_MessageDrain
CBaseControlWindow::put_Owner
CBaseControlWindow::put_Top
CBaseControlWindow::put_Visible
CBaseControlWindow::put_Width
CBaseControlWindow::put_WindowState
CBaseControlWindow::put_WindowStyle
CBaseControlWindow::put_WindowStyleEx
CBaseControlWindow::SetControlWindowPin
CBaseControlWindow::SetWindowForeground
CBaseControlWindow::SetWindowPosition
CBaseDispatch (CBaseDispatch)
CBaseDispatch Class
CBaseDispatch::CBaseDispatch
CBaseDispatch::GetIDsOfNames
CBaseDispatch::GetTypeInfo
CBaseDispatch::GetTypeInfoCount
CBaseFilter (CBaseFilter)
CBaseFilter Class
CBaseFilter::CBaseFilter
CBaseFilter::EnumPins
CBaseFilter::FindPin
CBaseFilter::GetClassID
CBaseFilter::GetFilterGraph
CBaseFilter::GetPin
CBaseFilter::GetPinCount
CBaseFilter::GetPinVersion
CBaseFilter::GetSetupData
CBaseFilter::GetState
CBaseFilter::GetSyncSource
CBaseFilter::IncrementPinVersion
CBaseFilter::IsActive
CBaseFilter::JoinFilterGraph
CBaseFilter::NonDelegatingQueryInterface
CBaseFilter::NotifyEvent
CBaseFilter::Pause
CBaseFilter::QueryFilterInfo
CBaseFilter::QueryVendorInfo
CBaseFilter::ReconnectPin
CBaseFilter::Register
CBaseFilter::Run
CBaseFilter::SetSyncSource
CBaseFilter::Stop
CBaseFilter::StreamTime
CBaseFilter::Unregister
CBaseInputPin (CBaseInputPin)
CBaseInputPin Class
CBaseInputPin::BeginFlush
CBaseInputPin::CBaseInputPin
CBaseInputPin::CheckStreaming
CBaseInputPin::Disconnect
CBaseInputPin::EndFlush

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

Gargle filter
Gargle Sample (Gargle Filter)
GdiFlush
General Questions
Generating the Complete Filter Graph
Get (Member Functions)
Get (Methods in Vtable Order)
Get (CGenericList)
Get (IAMVideoProcAmp)
Get (IKsPropertySet)
get_AntiClogControl
get_AntiClogControl (IAMExtTransport)
get_AudioFrequency
get_AudioFrequency (IAMTVTuner)
get_AutoShow (Implemented IVideoWindow Methods)
get_AutoShow (Methods in Vtable Order)
get_AutoShow (CBaseControlWindow)
get_AutoShow (IVideoWindow)
get_AvailableTVFormats
get_AvailableTVFormats (IAMTVTuner)
get_AvgFrameRate (Implemented IQualityControl Methods)
get_AvgFrameRate (Methods in Vtable Order)
get_AvgFrameRate (CBaseVideoRenderer)
get_AvgFrameRate (IQualProp)
get_AvgSyncOffset (Implemented IQualityControl Methods)
get_AvgSyncOffset (Methods in Vtable Order)
get_AvgSyncOffset (CBaseVideoRenderer)
get_AvgSyncOffset (IQualProp)
get_AvgTimePerFrame (Implemented IBasicVideo Methods)
get_AvgTimePerFrame (Methods in Vtable Order)
get_AvgTimePerFrame (CBaseControlVideo)
get_AvgTimePerFrame (IBasicVideo)
get_BackgroundPalette (Implemented IVideoWindow Methods)
get_BackgroundPalette (Methods in Vtable Order)
get_BackgroundPalette (CBaseControlWindow)
get_BackgroundPalette (IVideoWindow)
get_Balance
get_Balance (IBasicAudio)
get_Bass
get_Bass (IAMAudioInputMixer)
get_BassRange
get_BassRange (IAMAudioInputMixer)
get_BitErrorRate (Implemented IBasicVideo Methods)
get_BitErrorRate (Methods in Vtable Order)
get_BitErrorRate (CBaseControlVideo)
get_BitErrorRate (IBasicVideo)
get_BitRate (Implemented IBasicVideo Methods)
get_BitRate (Methods in Vtable Order)
get_BitRate (CBaseControlVideo)
get_BitRate (IBasicVideo)
get_BorderColor (Implemented IVideoWindow Methods)
get_BorderColor (Methods in Vtable Order)
get_BorderColor (CBaseControlWindow)
get_BorderColor (IVideoWindow)
get_Caption (Implemented IVideoWindow Methods)
get_Caption (Methods in Vtable Order)
get_Caption (CBaseControlWindow)
get_Caption (IVideoWindow)
get_Channel
get_Channel (IAMTVTuner)
get_ConnectedTo
get_ConnectedTo (IPinInfo)
get_ConnectInput
get_ConnectInput (IAMTVTuner)
get_ConnectionMediaType
get_ConnectionMediaType (IPinInfo)
get_Count
get_Count (IAMCollection)
get_CountryCode
get_CountryCode (IAMTVTuner)
get_CrossbarPinInfo
get_CrossbarPinInfo (IAMCrossbar)
get_CurrentPosition (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
get_CurrentPosition (CSourcePosition Class: Implemented IMediaPosition Methods)
get_CurrentPosition (IAMovie Interface: Methods in Vtable Order)
get_CurrentPosition (IMediaPosition Interface: Methods in Vtable Order)
get_CurrentPosition (CPosPassThru)
get_CurrentPosition (CSourcePosition)
get_CurrentPosition (IAMovie)
get_CurrentPosition (IMediaPosition)
get_DestinationHeight (Implemented IBasicVideo Methods)
get_DestinationHeight (Methods in Vtable Order)
get_DestinationHeight (CBaseControlVideo)
get_DestinationHeight (IBasicVideo)
get_DestinationLeft (Implemented IBasicVideo Methods)
get_DestinationLeft (Methods in Vtable Order)
get_DestinationLeft (CBaseControlVideo)
get_DestinationLeft (IBasicVideo)
get_DestinationTop (Implemented IBasicVideo Methods)
get_DestinationTop (Methods in Vtable Order)
get_DestinationTop (CBaseControlVideo)
get_DestinationTop (IBasicVideo)
get_DestinationWidth (Implemented IBasicVideo Methods)
get_DestinationWidth (Methods in Vtable Order)
get_DestinationWidth (CBaseControlVideo)
get_DestinationWidth (IBasicVideo)
get_DevicePort
get_DevicePort (IAMExtDevice)
get_DevicePower
get_DevicePower (IAMExtDevice)
get_DevSyncOffset (Implemented IQualityControl Methods)
get_DevSyncOffset (Methods in Vtable Order)
get_DevSyncOffset (CBaseVideoRenderer)
get_DevSyncOffset (IQualProp)
get_Direction
get_Direction (IPinInfo)
get_Duration (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
get_Duration (CSourcePosition Class: Implemented IMediaPosition Methods)
get_Duration (IAMovie Interface: Methods in Vtable Order)
get_Duration (IMediaPosition Interface: Methods in Vtable Order)
get_Duration (CPosPassThru)
get_Duration (CSourcePosition)
get_Duration (IAMovie)
get_Duration (IMediaPosition)
get_EditStart
get_EditStart (IAMExtTransport)
get_Enable
get_Enable (IAMAudioInputMixer)
get_ExternalDeviceID
get_ExternalDeviceID (IAMExtDevice)
get_ExternalDeviceVersion
get_ExternalDeviceVersion (IAMExtDevice)
get_Filename
get_Filename (IFilterInfo)
get_Filter
get_Filter (IFilterInfo)
get_FilterCollection
get_FilterCollection (IMediaControl)
get_FilterInfo
get_FilterInfo (IPinInfo)
get_FramesDrawn (Implemented IQualityControl Methods)
get_FramesDrawn (Methods in Vtable Order)
get_FramesDrawn (CBaseVideoRenderer)
get_FramesDrawn (IQualProp)
get_FramesDroppedInRenderer (Implemented IQualityControl Methods)
get_FramesDroppedInRenderer (Methods in Vtable Order)
get_FramesDroppedInRenderer (CBaseVideoRenderer)
get_FramesDroppedInRenderer (IQualProp)
get_FullScreenMode (Implemented IVideoWindow Methods)
get_FullScreenMode (Methods in Vtable Order)
get_FullScreenMode (CBaseControlWindow)
get_FullScreenMode (IVideoWindow)
get_Height (Implemented IVideoWindow Methods)
get_Height (Methods in Vtable Order)
get_Height (CBaseControlWindow)
get_Height (IVideoWindow)
get_InputType
get_InputType (IAMTVTuner)
get_Interleaving
get_Interleaving (IConfigInterleaving)
get_IsFileSource
get_IsFileSource (IFilterInfo)
get_IsRoutedTo
get_IsRoutedTo (IAMCrossbar)
get_Jitter (Implemented IQualityControl Methods)
get_Jitter (Methods in Vtable Order)
get_Jitter (CBaseVideoRenderer)
get_Jitter (IQualProp)
get_KeyFrameRate
get_KeyFrameRate (IAMVideoCompression)
get_Left (Implemented IVideoWindow Methods)
get_Left (Methods in Vtable Order)
get_Left (CBaseControlWindow)
get_Left (IVideoWindow)
get_LocalControl
get_LocalControl (IAMExtTransport)
get_Loudness
get_Loudness (IAMAudioInputMixer)
get_MediaState
get_MediaState (IAMExtTransport)
get_MediaTypes
get_MediaTypes (IPinInfo)
get_MessageDrain (Implemented IVideoWindow Methods)
get_MessageDrain (Methods in Vtable Order)
get_MessageDrain (CBaseControlWindow)
get_MessageDrain (IVideoWindow)
get_MixLevel
get_MixLevel (IAMAudioInputMixer)
get_Mode (IAMExtTransport Interface: Methods in Vtable Order)
get_Mode (IConfigInterleaving Interface: Methods in Vtable Order)
get_Mode (IAMExtTransport)
get_Mode (IConfigInterleaving)
get_Mono
get_Mono (IAMAudioInputMixer)
get_Name (IFilterInfo Interface: Methods in Vtable Order)
get_Name (IPinInfo Interface: Methods in Vtable Order)
get_Name (IRegFilterInfo Interface: Methods in Vtable Order)
get_Name (IFilterInfo)
get_Name (IPinInfo)
get_Name (IRegFilterInfo)
get_NewEnum
get_NewEnum (IAMCollection)
get_NumInputConnections
get_NumInputConnections (IAMTVTuner)
get_Owner (Implemented IVideoWindow Methods)
get_Owner (Methods in Vtable Order)
get_Owner (CBaseControlWindow)
get_Owner (IVideoWindow)
get_Pan
get_Pan (IAMAudioInputMixer)
get_PFramesPerKeyFrame
get_PFramesPerKeyFrame (IAMVideoCompression)
get_Pin
get_Pin (IPinInfo)
get_PinCounts
get_PinCounts (IAMCrossbar)
get_PinID
get_PinID (IPinInfo)
get_Pins
get_Pins (IFilterInfo)
get_PrerollTime (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
get_PrerollTime (CSourcePosition Class: Implemented IMediaPosition Methods)
get_PrerollTime (IAMovie Interface: Methods in Vtable Order)
get_PrerollTime (IMediaPosition Interface: Methods in Vtable Order)
get_PrerollTime (CPosPassThru)
get_PrerollTime (CSourcePosition)
get_PrerollTime (IAMovie)
get_PrerollTime (IMediaPosition)
get_Quality
get_Quality (IAMVideoCompression)
get_Rate (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
get_Rate (CSourcePosition Class: Implemented IMediaPosition Methods)
get_Rate (IAMExtTransport Interface: Methods in Vtable Order)
get_Rate (IAMovie Interface: Methods in Vtable Order)
get_Rate (IMediaPosition Interface: Methods in Vtable Order)
get_Rate (CPosPassThru)
get_Rate (CSourcePosition)
get_Rate (IAMExtTransport)
get_Rate (IAMovie)
get_Rate (IMediaPosition)
get_RegFilterCollection
get_RegFilterCollection (IMediaControl)
get_SourceHeight (Implemented IBasicVideo Methods)
get_SourceHeight (Methods in Vtable Order)
get_SourceHeight (CBaseControlVideo)
get_SourceHeight (IBasicVideo)
get_SourceLeft (Implemented IBasicVideo Methods)
get_SourceLeft (Methods in Vtable Order)
get_SourceLeft (CBaseControlVideo)
get_SourceLeft (IBasicVideo)
get_SourceTop (Implemented IBasicVideo Methods)
get_SourceTop (Methods in Vtable Order)
get_SourceTop (CBaseControlVideo)
get_SourceTop (IBasicVideo)
get_SourceWidth (Implemented IBasicVideo Methods)
get_SourceWidth (Methods in Vtable Order)
get_SourceWidth (CBaseControlVideo)
get_SourceWidth (IBasicVideo)
get_StopTime (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
get_StopTime (CSourcePosition Class: Implemented IMediaPosition Methods)
get_StopTime (IAMovie Interface: Methods in Vtable Order)
get_StopTime (IMediaPosition Interface: Methods in Vtable Order)
get_StopTime (CPosPassThru)
get_StopTime (CSourcePosition)
get_StopTime (IAMovie)
get_StopTime (IMediaPosition)
get_Subtype
get_Subtype (IMediaTypeInfo)
get_Top (Implemented IVideoWindow Methods)
get_Top (Methods in Vtable Order)
get_Top (CBaseControlWindow)
get_Top (IVideoWindow)
get_Treble
get_Treble (IAMAudioInputMixer)
get_TrebleRange
get_TrebleRange (IAMAudioInputMixer)
get_TuningSpace
get_TuningSpace (IAMTVTuner)
get_TVFormat
get_TVFormat (IAMTVTuner)
get_Type
get_Type (IMediaTypeInfo)
get_VendorInfo
get_VendorInfo (IFilterInfo)
get_VideoFrequency
get_VideoFrequency (IAMTVTuner)
get_VideoHeight (Implemented IBasicVideo Methods)
get_VideoHeight (Methods in Vtable Order)
get_VideoHeight (CBaseControlVideo)
get_VideoHeight (IBasicVideo)
get_VideoWidth (Implemented IBasicVideo Methods)
get_VideoWidth (Methods in Vtable Order)
get_VideoWidth (CBaseControlVideo)
get_VideoWidth (IBasicVideo)
get_Visible (Implemented IVideoWindow Methods)
get_Visible (Methods in Vtable Order)
get_Visible (CBaseControlWindow)
get_Visible (IVideoWindow)
get_VITCLine
get_VITCLine (IAMTimecodeGenerator)
get_VITCLine (IAMTimecodeReader)
get_Volume
get_Volume (IBasicAudio)
get_Width (Implemented IVideoWindow Methods)
get_Width (Methods in Vtable Order)
get_Width (CBaseControlWindow)
get_Width (IVideoWindow)
get_WindowSize
get_WindowSize (IAMVideoCompression)
get_WindowState (Implemented IVideoWindow Methods)
get_WindowState (Methods in Vtable Order)
get_WindowState (CBaseControlWindow)
get_WindowState (IVideoWindow)
get_WindowStyle (Implemented IVideoWindow Methods)
get_WindowStyle (Methods in Vtable Order)
get_WindowStyle (CBaseControlWindow)
get_WindowStyle (IVideoWindow)
get_WindowStyleEx (Implemented IVideoWindow Methods)
get_WindowStyleEx (Methods in Vtable Order)
get_WindowStyleEx (CBaseControlWindow)
get_WindowStyleEx (IVideoWindow)
GetActualDataLength (Implemented INonDelegatingUnknown Methods)
GetActualDataLength (Methods in Vtable Order)
GetActualDataLength (CMediaSample)
GetActualDataLength (IMediaSample)
GetAdviseCount
GetAdviseCount (CAMSchedule)
GetAllGPRMs
GetAllGPRMs (IDvdInfo)
GetAllocator (Implemented IMemInputPin Methods)
GetAllocator (Implemented IQualityControl Methods)
GetAllocator (Methods in Vtable Order)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

IAMAudioCutListElement Interface
IAMAudioCutListElement::GetStreamIndex
IAMAudioCutListElement::HasFadeIn
IAMAudioCutListElement::HasFadeOut
IAMAudioInputMixer Interface
IAMAudioInputMixer::get_Bass
IAMAudioInputMixer::get_BassRange
IAMAudioInputMixer::get_Enable
IAMAudioInputMixer::get_Loudness
IAMAudioInputMixer::get_MixLevel
IAMAudioInputMixer::get_Mono
IAMAudioInputMixer::get_Pan
IAMAudioInputMixer::get_Treble
IAMAudioInputMixer::get_TrebleRange
IAMAudioInputMixer::put_Bass
IAMAudioInputMixer::put_Enable
IAMAudioInputMixer::put_Loudness
IAMAudioInputMixer::put_MixLevel
IAMAudioInputMixer::put_Mono
IAMAudioInputMixer::put_Pan
IAMAudioInputMixer::put_Treble
IAMBufferNegotiation Interface
IAMBufferNegotiation::GetAllocatorProperties
IAMBufferNegotiation::SuggestAllocatorProperties
IAMCollection Interface
IAMCollection Object
IAMCollection::get_Count
IAMCollection::get_NewEnum
IAMCollection::Item
IAMCopyCaptureFileProgress Interface
IAMCopyCaptureFileProgress::Progress
IAMCrossbar Interface
IAMCrossbar::CanRoute
IAMCrossbar::get_CrossbarPinInfo
IAMCrossbar::get_IsRoutedTo
IAMCrossbar::get_PinCounts
IAMCrossbar::Route
IAMCutListElement Interface
IAMCutListElement::ElementStatus
IAMCutListElement::GetElementDuration
IAMCutListElement::GetElementStartPosition
IAMCutListElement::IsFirstElement
IAMCutListElement::IsLastElement
IAMCutListElement::IsNull
IAMDevMemoryAllocator Interface
IAMDevMemoryAllocator::Alloc
IAMDevMemoryAllocator::CheckMemory
IAMDevMemoryAllocator::Free
IAMDevMemoryAllocator::GetDevMemoryObject
IAMDevMemoryAllocator::GetInfo
IAMDevMemoryControl Interface
IAMDevMemoryControl::GetDevId
IAMDevMemoryControl::QueryWriteSync
IAMDevMemoryControl::WriteSync
IAMDirectSound Interface
IAMDirectSound::GetDirectSoundInterface
IAMDirectSound::GetPrimaryBufferInterface
IAMDirectSound::GetSecondaryBufferInterface
IAMDirectSound::GetWindowFocus
IAMDirectSound::ReleaseDirectSoundInterface
IAMDirectSound::ReleasePrimaryBufferInterface
IAMDirectSound::ReleaseSecondaryBufferInterface
IAMDirectSound::SetWindowFocus
IAMDroppedFrames Interface
IAMDroppedFrames::GetAverageFrameSize
IAMDroppedFrames::GetDroppedInfo
IAMDroppedFrames::GetNumDropped
IAMDroppedFrames::GetNumNotDropped
IAMExtDevice Interface
IAMExtDevice::Calibrate
IAMExtDevice::get_DevicePort
IAMExtDevice::get_DevicePower
IAMExtDevice::get_ExternalDeviceID
IAMExtDevice::get_ExternalDeviceVersion
IAMExtDevice::GetCapability
IAMExtDevice::put_DevicePort
IAMExtDevice::put_DevicePower
IAMExtTransport Interface
IAMExtTransport::get_AntiClogControl
IAMExtTransport::get_EditStart
IAMExtTransport::get_LocalControl
IAMExtTransport::get_MediaState
IAMExtTransport::get_Mode
IAMExtTransport::get_Rate
IAMExtTransport::GetBump
IAMExtTransport::GetCapability
IAMExtTransport::GetChase
IAMExtTransport::GetEditProperty
IAMExtTransport::GetEditPropertySet
IAMExtTransport::GetStatus
IAMExtTransport::GetTransportAudioParameters
IAMExtTransport::GetTransportBasicParameters
IAMExtTransport::GetTransportVideoParameters
IAMExtTransport::put_AntiClogControl
IAMExtTransport::put_EditStart
IAMExtTransport::put_LocalControl
IAMExtTransport::put_MediaState
IAMExtTransport::put_Mode
IAMExtTransport::put_Rate
IAMExtTransport::SetBump
IAMExtTransport::SetChase
IAMExtTransport::SetEditProperty
IAMExtTransport::SetEditPropertySet
IAMExtTransport::SetTransportAudioParameters
IAMExtTransport::SetTransportBasicParameters
IAMExtTransport::SetTransportVideoParameters
IAMFileCutListElement Interface
IAMFileCutListElement::GetElementSplitOffset
IAMFileCutListElement::GetFileName
IAMFileCutListElement::GetOriginPosition
IAMFileCutListElement::GetTrimInPosition
IAMFileCutListElement::GetTrimLength
IAMFileCutListElement::GetTrimOutPosition
IAMLine21Decoder Interface
IAMLine21Decoder::GetBackgroundColor
IAMLine21Decoder::GetCurrentService
IAMLine21Decoder::GetDecoderLevel
IAMLine21Decoder::GetDrawBackgroundMode
IAMLine21Decoder::GetOutputFormat
IAMLine21Decoder::GetRedrawAlways
IAMLine21Decoder::GetServiceState
IAMLine21Decoder::SetBackgroundColor
IAMLine21Decoder::SetCurrentService
IAMLine21Decoder::SetDrawBackgroundMode
IAMLine21Decoder::SetOutputFormat
IAMLine21Decoder::SetRedrawAlways
IAMLine21Decoder::SetServiceState
IAMMediaStream Interface
IAMMediaStream::Initialize
IAMMediaStream::JoinAMMultiMediaStream
IAMMediaStream::JoinFilter
IAMMediaStream::JoinFilterGraph
IAMMediaStream::SetState
IAMMultiMediaStream Interface
IAMMultiMediaStream::AddMediaStream
IAMMultiMediaStream::GetFilter
IAMMultiMediaStream::GetFilterGraph
IAMMultiMediaStream::Initialize
IAMMultiMediaStream::OpenFile
IAMMultiMediaStream::OpenMoniker
IAMMultiMediaStream::Render
IAMovie Interface
IAMovie::AddSourceFilter
IAMovie::CancelDefaultHandling
IAMovie::Connect
IAMovie::EnumFiltersByInterface
IAMovie::EnumPins
IAMovie::EnumPinsIn
IAMovie::EnumPinsOut
IAMovie::FreeEventParams
IAMovie::get_CurrentPosition
IAMovie::get_Duration
IAMovie::get_PrerollTime
IAMovie::get_Rate
IAMovie::get_StopTime
IAMovie::GetEvent
IAMovie::GetEventHandle
IAMovie::GetState
IAMovie::Pause
IAMovie::Play
IAMovie::PlayFile
IAMovie::put_CurrentPosition
IAMovie::put_PrerollTime
IAMovie::put_Rate
IAMovie::put_StopTime
IAMovie::RemoveAllFilters
IAMovie::Render
IAMovie::RenderAll
IAMovie::RenderFile
IAMovie::RenderNewFile
IAMovie::RestoreDefaultHandling
IAMovie::Run
IAMovie::Stop
IAMovie::WaitForCompletion
IAMovieSetup Interface
IAMovieSetup::Register
IAMovieSetup::Unregister
IAMStreamConfig Interface
IAMStreamConfig::GetFormat
IAMStreamConfig::GetNumberOfCapabilities
IAMStreamConfig::GetStreamCaps
IAMStreamConfig::SetFormat
IAMStreamControl Interface
IAMStreamControl::GetInfo
IAMStreamControl::StartAt
IAMStreamControl::StopAt
IAMStreamSelect Interface
IAMStreamSelect::Count
IAMStreamSelect::Enable
IAMStreamSelect::Info
IAMTimecodeDisplay Interface
IAMTimecodeDisplay::GetTCDisplay
IAMTimecodeDisplay::GetTCDisplayEnable
IAMTimecodeDisplay::SetTCDisplay
IAMTimecodeDisplay::SetTCDisplayEnable
IAMTimecodeGenerator Interface
IAMTimecodeGenerator::get_VITCLine
IAMTimecodeGenerator::GetTCGMode
IAMTimecodeGenerator::GetTimecode
IAMTimecodeGenerator::put_VITCLine
IAMTimecodeGenerator::SetTCGMode
IAMTimecodeGenerator::SetTimecode
IAMTimecodeReader Interface
IAMTimecodeReader::get_VITCLine
IAMTimecodeReader::GetTCRMode
IAMTimecodeReader::GetTimecode
IAMTimecodeReader::put_VITCLine
IAMTimecodeReader::SetTCRMode
IAMTVTuner Interface
IAMTVTuner::AutoTune
IAMTVTuner::ChannelMinMax
IAMTVTuner::get_AudioFrequency
IAMTVTuner::get_AvailableTVFormats
IAMTVTuner::get_Channel
IAMTVTuner::get_ConnectInput
IAMTVTuner::get_CountryCode
IAMTVTuner::get_InputType
IAMTVTuner::get_NumInputConnections
IAMTVTuner::get_TuningSpace
IAMTVTuner::get_TVFormat
IAMTVTuner::get_VideoFrequency
IAMTVTuner::put_Channel
IAMTVTuner::put_ConnectInput
IAMTVTuner::put_CountryCode
IAMTVTuner::put_InputType
IAMTVTuner::put_TuningSpace
IAMTVTuner::StoreAutoTune
IAMVfwCaptureDialogs Interface
IAMVfwCaptureDialogs::HasDialog
IAMVfwCaptureDialogs::SendDriverMessage
IAMVfwCaptureDialogs::ShowDialog
IAMVfwCompressDialogs Interface
IAMVfwCompressDialogs::GetState
IAMVfwCompressDialogs::SendDriverMessage
IAMVfwCompressDialogs::SetState
IAMVfwCompressDialogs::ShowDialog
IAMVideoCompression Interface
IAMVideoCompression::get_KeyFrameRate
IAMVideoCompression::get_PFramesPerKeyFrame
IAMVideoCompression::get_Quality
IAMVideoCompression::get_WindowSize
IAMVideoCompression::GetInfo
IAMVideoCompression::OverrideFrameSize
IAMVideoCompression::OverrideKeyFrame
IAMVideoCompression::put_KeyFrameRate
IAMVideoCompression::put_PFramesPerKeyFrame
IAMVideoCompression::put_Quality
IAMVideoCompression::put_WindowSize
IAMVideoControl Interface
IAMVideoControl::GetCaps
IAMVideoControl::GetCurrentActualFrameRate
IAMVideoControl::GetFrameRateList
IAMVideoControl::GetMaxAvailableFrameRate
IAMVideoControl::GetMode
IAMVideoControl::SetMode
IAMVideoCutListElement Interface
IAMVideoCutListElement::GetStreamIndex
IAMVideoCutListElement::IsSingleFrame
IAMVideoProcAmp Interface
IAMVideoProcAmp::Get
IAMVideoProcAmp::GetRange
IAMVideoProcAmp::Set
IAsyncReader Interface
IAsyncReader Transport
IAsyncReader::BeginFlush
IAsyncReader::EndFlush
IAsyncReader::Length
IAsyncReader::Request
IAsyncReader::RequestAllocator
IAsyncReader::SyncRead
IAsyncReader::SyncReadAligned
IAsyncReader::WaitForNext
IAudioData Interface
IAudioData::GetFormat
IAudioData::SetFormat
IAudioMediaStream Interface
IAudioMediaStream::CreateSample
IAudioMediaStream::GetFormat
IAudioMediaStream::SetFormat
IAudioStreamSample Interface
IAudioStreamSample::GetAudioData
IBaseFilter Interface
IBaseFilter::EnumPins
IBaseFilter::FindPin
IBaseFilter::JoinFilterGraph
IBaseFilter::QueryFilterInfo
IBaseFilter::QueryVendorInfo
IBasicAudio Interface
IBasicAudio Object
IBasicAudio::get_Balance
IBasicAudio::get_Volume
IBasicAudio::put_Balance
IBasicAudio::put_Volume
IBasicVideo Interface
IBasicVideo Object
IBasicVideo::get_AvgTimePerFrame
IBasicVideo::get_BitErrorRate
IBasicVideo::get_BitRate
IBasicVideo::get_DestinationHeight
IBasicVideo::get_DestinationLeft
IBasicVideo::get_DestinationTop
IBasicVideo::get_DestinationWidth
IBasicVideo::get_SourceHeight
IBasicVideo::get_SourceLeft
IBasicVideo::get_SourceTop
IBasicVideo::get_SourceWidth
IBasicVideo::get_VideoHeight
IBasicVideo::get_VideoWidth
IBasicVideo::GetCurrentImage
IBasicVideo::GetDestinationPosition
IBasicVideo::GetSourcePosition
IBasicVideo::GetVideoPaletteEntries
IBasicVideo::GetVideoSize
IBasicVideo::IsUsingDefaultDestination
IBasicVideo::IsUsingDefaultSource
IBasicVideo::put_DestinationHeight
IBasicVideo::put_DestinationLeft
IBasicVideo::put_DestinationTop
IBasicVideo::put_DestinationWidth
IBasicVideo::put_SourceHeight
IBasicVideo::put_SourceLeft
IBasicVideo::put_SourceTop
IBasicVideo::put_SourceWidth
IBasicVideo::SetDefaultDestinationPosition
IBasicVideo::SetDefaultSourcePosition
IBasicVideo::SetDestinationPosition
IBasicVideo::SetSourcePosition
IBindCtx
ICAbout
ICaptureGraphBuilder Interface
ICaptureGraphBuilder::AllocCapFile
ICaptureGraphBuilder::ControlStream
ICaptureGraphBuilder::CopyCaptureFile
ICaptureGraphBuilder::FindInterface
ICaptureGraphBuilder::GetFiltergraph
ICaptureGraphBuilder::RenderStream
ICaptureGraphBuilder::SetFiltergraph
ICaptureGraphBuilder::SetOutputFileName
ICConfigure
ICGetState
IClassFactory
IClassFactory::CreateInstance
IConfigAviMux Interface
IConfigAviMux::GetMasterStream
IConfigAviMux::GetOutputCompatibilityIndex
IConfigAviMux::SetMasterStream
IConfigAviMux::SetOutputCompatibilityIndex
IConfigInterleaving Interface
IConfigInterleaving::get_Interleaving
IConfigInterleaving::get_Mode
IConfigInterleaving::put_Interleaving
IConfigInterleaving::put_Mode
ICreateDevEnum Interface
ICreateDevEnum::CreateClassEnumerator
ICSendMessage
ICutListGraphBuilder Interface
ICutListGraphBuilder::AddCutList
ICutListGraphBuilder::GetElementFlags
ICutListGraphBuilder::GetFilterGraph
ICutListGraphBuilder::RemoveCutList

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

m_AccessLock
m_bAbort
m_bActivated
m_bAtEndOfStream
m_bAutoShow
m_bBackground
m_bBatchExact
m_bChanged
m_bCommitted
m_bCompleteNotified
m_bCursorHidden
m_bDecommitInProgress
m_bDirty
m_bDoGetDC
m_bDrawLateFrames
m_bEOS
m_bEOSDelivered (CBaseRenderer Class: Protected Data Members)
m_bEOSDelivered (CTransformFilter Class: Protected Data Members)
m_bFlushed
m_bFlushing (CBaseInputPin Class: Protected Data Members)
m_bFlushing (COutputQueue Class: Protected Data Members)
m_bInit
m_bNoSkip
m_BorderColour
m_bQualityChanged (CTransformFilter Class: Protected Data Members)
m_bQualityChanged (CVideoTransformFilter Class: Protected Data Members)
m_bReadOnly (CBaseInputPin Class: Protected Data Members)
m_bReadOnly (CTransInPlaceInputPin Class: Protected Data Members)
m_bRepaintStatus
m_bRunning
m_bRunTimeError
m_bSampleSkipped
m_bSendAnyway
m_bSkipping
m_bStream
m_bStreaming
m_bStretch
m_bSupplierHandlingQuality
m_bTerminate
m_bUsingImageAllocator
m_cbBuffer
m_cFramesDrawn
m_cFramesDropped
m_ClassStyles
m_clsid (CBaseFilter Class: Protected Data Members)
m_clsid (CBaseMediaFilter Class: Protected Data Members)
m_ClsID (CFactoryTemplate Class: Protected Data Members)
m_Connected
m_Count
m_cRef
m_csFilter
m_csReceive
m_cStateLock
m_DialogId
m_DibData
m_dir
m_Dispatch
m_dispidMethod
m_Display
m_DispParams
m_Dlg
m_dRate
m_dRateSeeking
m_Duration
m_dwAdvise (CBaseRenderer Class: Protected Data Members)
m_dwAdvise (CCmdQueue Class: Protected Data Members)
m_dwFlags
m_dwSeekingCaps
m_End
m_EndOfStreamTimer
m_EndSample
m_evComplete
m_evDue
m_evFlushComplete
m_hdc (CBaseWindow Class: Protected Data Members)
m_hdc (CDrawImage Class: Protected Data Members)
m_Height
m_hEvent
m_hInstance
m_hPalette (CBaseWindow Class: Protected Data Members)
m_hPalette (CImagePalette Class: Protected Data Members)
m_hr
m_hrResult
m_hSem (CBaseAllocator Class: Protected Data Members)
m_hSem (CMsgThread Class: Protected Data Members)
m_hSem (COutputQueue Class: Protected Data Members)
m_hThread (CBaseWindow Class: Protected Data Members)
m_hThread (COutputQueue Class: Protected Data Members)
m_hwnd (CBasePropertyPage Class: Protected Data Members)
m_hwnd (CBaseWindow Class: Protected Data Members)
m_hwndDrain
m_hwndOwner
m_idDecision
m_idDuration
m_idFrameAccuracy
m_idFrameAvg
m_idFrameType
m_idLate
m_idQualityRate
m_idQualityTime
m_idRenderAvg
m_idSchLateTime
m_idSendQuality
m_idSkip
m_idTimeStamp
m_idTimeTillKey
m_idTransform
m_idTransInPlace
m_idWait
m_idWaitReal
m_iid
m_InterfaceLock
m_iPins
m_iSumFrameTime
m_iSumSqAcc
m_iSumSqFrameTime
m_iTotAcc
m_itrAvgDecode
m_itrLate
m_lActual
m_lAlignment
m_lAllocated
m_lBatchSize
m_lCount
m_lFree
m_List
m_listPresentation
m_listStream
m_Lock (CCmdQueue Class: Protected Data Members)
m_Lock (CMsgThread Class: Protected Data Members)
m_lpfnInit
m_lpfnNew
m_lPrefix
m_lSize
m_lWaiting (CBaseAllocator Class: Protected Data Members)
m_lWaiting (CMsgThread Class: Protected Data Members)
m_lWaiting (COutputQueue Class: Protected Data Members)
m_MediaEnd
m_MediaStart
m_MemoryDC (CBaseWindow Class: Protected Data Members)
m_MemoryDC (CDrawImage Class: Protected Data Members)
m_mt
m_Name
m_nBatched
m_nFramesSinceKeyFrame
m_nKeyFramePeriod
m_nNormal
m_nWaitForKey
m_PaletteVersion
m_pAlloc
m_pAllocator (CBaseInputPin Class: Protected Data Members)
m_pAllocator (CBaseOutputPin Class: Protected Data Members)
m_pAllocator (CMediaSample Class: Protected Data Members)
m_pAMovieSetup_Filter
m_paStreams
m_pBaseWindow (CDrawImage Class: Protected Data Members)
m_pBaseWindow (CImagePalette Class: Protected Data Members)
m_pBuffer
m_pClassName
m_pClock (CBaseFilter Class: Protected Data Members)
m_pClock (CBaseMediaFilter Class: Protected Data Members)
m_pClock (CCmdQueue Class: Protected Data Members)
m_pDirectDraw
m_pDirectDrawSurface
m_pDrawImage
m_perfidRenderNow
m_perfidRenderTime
m_pFilter (CBaseControlVideo Class: Protected Data Members)
m_pFilter (CBaseControlWindow Class: Protected Data Members)
m_pFilter (CBasePin Class: Protected Data Members)
m_pFilter (CImageAllocator Class: Protected Data Members)
m_pFirst
m_pGraph
m_Pin
m_pInput
m_pInputPin (CBaseOutputPin Class: Protected Data Members)
m_pInputPin (CBaseRenderer Class: Protected Data Members)
m_pInputPin (COutputQueue Class: Protected Data Members)
m_pInterfaceLock (CBaseControlVideo Class: Protected Data Members)
m_pInterfaceLock (CBaseControlWindow Class: Protected Data Members)
m_PinVersion
m_pLast
m_pLock (CAutoLock Class: Protected Data Members)
m_pLock (CBaseFilter Class: Protected Data Members)
m_pLock (CBasePin Class: Protected Data Members)
m_pLock (CSourcePosition Class: Protected Data Members)
m_pLock (CSourceSeeking Class: Protected Data Members)
m_pMediaFilter
m_pMediaSample
m_pMediaType (CDrawImage Class: Protected Data Members)
m_pMediaType (CImageAllocator Class: Protected Data Members)
m_pMediaType (CMediaSample Class: Protected Data Members)
m_pName (CBaseFilter Class: Protected Data Members)
m_pName (CBasePin Class: Protected Data Members)
m_pNext
m_pOutput
m_pPageSite
m_pPin (CBaseControlVideo Class: Protected Data Members)
m_pPin (CBaseControlWindow Class: Protected Data Members)
m_pPin (COutputQueue Class: Protected Data Members)
m_pPosition (Protected Data Members)
m_pPosition (Public Data Members)
m_ppSamples
m_pQSink (CBasePin Class: Protected Data Members)
m_pQSink (CBaseRenderer Class: Protected Data Members)
m_pQueue
m_pRenderer
m_pSchedule
m_pSink
m_PString
m_pTIPFilter (CTransInPlaceInputPin Class: Protected Data Members)
m_pTIPFilter (CTransInPlaceOutputPin Class: Protected Data Members)
m_pTransformFilter (CTransformInputPin Class: Protected Data Members)
m_pTransformFilter (CTransformOutputPin Class: Protected Data Members)
m_pUnk
m_pvarResult
m_Rate
m_RealizePalette
m_RendererLock
m_RenderEvent
m_rtDuration
m_rtStart
m_rtStop
m_ShowStageMessage
m_ShowStageTop
m_SignalTime
m_SourceRect
m_Start (CMediaSample Class: Protected Data Members)
m_Start (CSourcePosition Class: Protected Data Members)
m_StartSample
m_State (CBaseFilter Class: Protected Data Members)
m_State (CBaseMediaFilter Class: Protected Data Members)
m_Stop
m_StreamTimeOffset
m_String
m_SyncWorker
m_SyncWorkerCreate
m_TargetRect
m_tCurrentAdvise
m_tDecodeStart
m_ThreadQueue
m_ThreadSignal (CBaseRenderer Class: Protected Data Members)
m_ThreadSignal (CBaseWindow Class: Protected Data Members)
m_time (Data Members)
m_time (Protected Data Members)
m_TitleId
m_trDuration
m_trEarliness
m_trFrame
m_trFrameAvg
m_trLastDraw
m_trLate
m_trRenderAvg
m_trRenderLast
m_trRenderStart
m_trThrottle
m_trWaitAvg
m_tStart (CBaseFilter Class: Protected Data Members)
m_tStart (CBaseMediaFilter Class: Protected Data Members)
m_tStart (CBasePin Class: Protected Data Members)
m_tStop
m_tStreamingStart
m_TypeVersion
m_wFlags
m_Width
m_WindowLock
m_WindowStyles
m_WindowStylesEx
m_WorkerLock
MACROVISIONLevel
MainAVIHeader
major type
majortype
Make Added Interfaces Available Through NonDelegatingQueryInterface
MakeIdentityPalette
MakeIdentityPalette (CImagePalette)
MakePalette
MakePalette (CImagePalette)
Managing the User Interface of the ActiveMovie Control
MatchesPartial
MatchesPartial (CMediaType)
Math Helper Functions
MAX_TIME
MaxBitsPerSecond
MaxCroppingSize
MaxFrameInterval
MaximumBitsPerSample
MaximumChannels
MaximumSampleFrequency
MaxOutputSize
Media Control and Positioning Classes
Media Sample and Enumerator Interfaces
Media Sample Data Flow
Media Sample Interfaces
media sample protocol
Media seeking from C++
media time
Media Type Functions
MediaTypes Property (IPinInfo Object)
memcmp
MenuCall
MenuCall (IDvdControl)
MenuLanguageSelect
MenuLanguageSelect (IDvdControl)
merit
Message Function
MessageDrain Property (IVideoWindow Object)
method
MFCPlay Sample (C++/COM-based Media Player Application)
MIDI Parser
MIDI Renderer
Millisecs
Millisecs (CRefTime)
MinBitsPerSecond
MinCroppingSize
MinFrameInterval
minidriver
Minimal Null filter
MinimumBitsPerSample
MinimumChannels
MinimumSampleFrequency
minor type
MinOutputSize
Minutes1
Minutes10
Miscellaneous Macros
MODE_BOBNONINTERLEAVED
moniker
Monitoring ActiveMovie Control Events
MouseActivate
MouseActivate (IDvdControl)
MouseSelect
MouseSelect (IDvdControl)
Move
Move (CBasePropertyPage)
MoveToHead
MoveToHead (CBaseList)
MoveToTail
MoveToTail (CBaseList)
MoveWindow
Movies, play from C++
MovieWindowSize Property
MPEG Audio Decoder
MPEG Audio Decoder filter
MPEG Video Decoder
MPEG Video Decoder filter
MPEG-1 Stream Splitter
MPEG1_SEQUENCE_INFO
MPEG1VIDEOINFO

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

SAMI (CC) Parser
SampIOS Sample (IOStream Helper Library)
Sample Applications
Sample Filters
Sample Locations
SampleFrequencyGranularity
Samples, DirectShow
Samples, DirectShow (Ball Sample (Bouncing Ball Filter))
SampVid Sample (Video Renderer Filter)
saturation
Save
Save (CPersistStream)
Saving the Captured File
ScaleHeight
ScaleSourceRect
ScaleSourceRect (CDrawImage)
ScaleWidth
Scaling and Translating the Video Output
ScheduleSample (Helper Function)
ScheduleSample (Implemented IQualityControl Methods)
ScheduleSample (CBaseRenderer)
ScheduleSample (CBaseVideoRenderer)
Scope Sample (Oscilloscope Filter)
SECAM
Seconds1
Seconds10
Seek (Methods in Vtable Order)
Seek (Overridable Member Functions)
Seek (CPullPin)
Seek (IMultiMediaStream)
seekable renderer
SelectionEnd Property
SelectionStart Property
SendAnyway
SendAnyway (COutputQueue)
SendDriverMessage (IAMVfwCaptureDialogs Interface: Methods in Vtable Order)
SendDriverMessage (IAMVfwCompressDialogs Interface: Methods in Vtable Order)
SendDriverMessage (IAMVfwCaptureDialogs)
SendDriverMessage (IAMVfwCompressDialogs)
SendEndOfStream (Helper Function)
SendEndOfStream (Methods in Vtable Order)
SendEndOfStream (CBaseRenderer)
SendEndOfStream (IMediaStream)
SendMessage
SendNotifyWindow (CBaseRenderer)
SendQuality
SendQuality (CBaseVideoRenderer)
SendRepaint
SendRepaint (CBaseRenderer)
Serializing Data
servo
Set (CAMEvent Class: Member Functions)
Set (IAMVideoProcAmp Interface: Methods in Vtable Order)
Set (IKsPropertySet Interface: Methods in Vtable Order)
Set (CAMEvent)
Set (IAMVideoProcAmp)
Set (IKsPropertySet)
SetAbortSignal
SetAbortSignal (CBaseRenderer)
SetActual
SetActual (IMemoryData)
SetActualDataLength (Implemented INonDelegatingUnknown Methods)
SetActualDataLength (Methods in Vtable Order)
SetActualDataLength (CMediaSample)
SetActualDataLength (IMediaSample)
SetAspectRatioMode
SetAspectRatioMode (IMixerPinConfig)
SetBackgroundColor
SetBackgroundColor (IAMLine21Decoder)
SetBlendingParameter
SetBlendingParameter (IMixerPinConfig)
SetBuffer
SetBuffer (IMemoryData)
SetBump
SetBump (IAMExtTransport)
SetCaption
SetCaption (IFullScreenVideo)
SetChase
SetChase (IAMExtTransport)
SetClipFactor
SetClipFactor (IFullScreenVideo)
SetColorKey (IMixerPinConfig)
SetColorKey (IOverlay)
SetConnectInfo
SetConnectInfo (IVPBaseConfig)
SetControlVideoPin
SetControlVideoPin (CBaseControlVideo)
SetControlWindowPin
SetControlWindowPin (CBaseControlWindow)
SetCurrentService
SetCurrentService (IAMLine21Decoder)
SetDDSurfaceKernelHandle
SetDDSurfaceKernelHandle (IVPBaseConfig)
SetDefault (IDirectDrawVideo Interface: Methods in Vtable Order)
SetDefault (IFullScreenVideo Interface: Methods in Vtable Order)
SetDefault (IDirectDrawVideo)
SetDefault (IFullScreenVideo)
SetDefaultDestinationPosition (Implemented IBasicVideo Methods)
SetDefaultDestinationPosition (Methods in Vtable Order)
SetDefaultDestinationPosition (CBaseControlVideo)
SetDefaultDestinationPosition (IBasicVideo)
SetDefaultDestinationPosition Method (IBasicVideo Object)
SetDefaultSourcePosition (Implemented IBasicVideo Methods)
SetDefaultSourcePosition (Methods in Vtable Order)
SetDefaultSourcePosition (CBaseControlVideo)
SetDefaultSourcePosition (IBasicVideo)
SetDefaultSourcePosition Method (IBasicVideo Object)
SetDefaultSourceRect
SetDefaultSourceRect (CBaseControlVideo)
SetDefaultSyncSource
SetDefaultSyncSource (IFilterGraph)
SetDefaultTargetRect
SetDefaultTargetRect (CBaseControlVideo)
SetDeinterlaceMode
SetDeinterlaceMode (IVPNotify)
SetDestinationPosition (Implemented IBasicVideo Methods)
SetDestinationPosition (Methods in Vtable Order)
SetDestinationPosition (CBaseControlVideo)
SetDestinationPosition (IBasicVideo)
SetDestinationPosition Method (IBasicVideo Object)
SetDIBColorTable
SetDIBData
SetDIBData (CImageSample)
SetDIBitsToDevice
SetDirectDraw (IDirectDrawMediaStream Interface: Methods in Vtable Order)
SetDirectDraw (IDirectDrawVideo Interface: Methods in Vtable Order)
SetDirectDraw (Implemented IDirectDraw Methods)
SetDirectDraw (CAggDirectDraw)
SetDirectDraw (IDirectDrawMediaStream)
SetDirectDraw (IDirectDrawVideo)
SetDirectDrawKernelHandle
SetDirectDrawKernelHandle (IVPBaseConfig)
SetDirectDrawSurface
SetDirectDrawSurface (CAggDrawSurface)
SetDirty
SetDirty (CPersistStream)
SetDiscontinuity (Implemented INonDelegatingUnknown Methods)
SetDiscontinuity (Methods in Vtable Order)
SetDiscontinuity (CMediaSample)
SetDiscontinuity (IMediaSample)
SetDlgItemText
SetDrawBackgroundMode
SetDrawBackgroundMode (IAMLine21Decoder)
SetDrawContext
SetDrawContext (CDrawImage)
SetEditProperty
SetEditProperty (IAMExtTransport)
SetEditPropertySet
SetEditPropertySet (IAMExtTransport)
SetEnabled
SetEnabled (IFullScreenVideo)
SetFileAndStream
SetFileAndStream (IFileClip)
SetFileName
SetFileName (IFileSinkFilter)
SetFilterGraph (CBaseStreamControl Class: Member Functions)
SetFiltergraph (ICaptureGraphBuilder Interface: Methods in Vtable Order)
SetFilterGraph (ICutListGraphBuilder Interface: Methods in Vtable Order)
SetFilterGraph (CBaseStreamControl)
SetFiltergraph (ICaptureGraphBuilder)
SetFilterGraph (ICutListGraphBuilder)
SetFocus
SetFocus (IResourceManager)
SetFormat (IAMStreamConfig Interface: Methods in Vtable Order)
SetFormat (IAudioData Interface: Methods in Vtable Order)
SetFormat (IAudioMediaStream Interface: Methods in Vtable Order)
SetFormat (IDirectDrawMediaStream Interface: Methods in Vtable Order)
SetFormat (Operators)
SetFormat (CMediaType)
SetFormat (IAMStreamConfig)
SetFormat (IAudioData)
SetFormat (IAudioMediaStream)
SetFormat (IDirectDrawMediaStream)
SetFormatType
SetFormatType (CMediaType)
SetFOURCC
SetFOURCC (FOURCCMap)
SetInvertPolarity
SetInvertPolarity (IVPBaseConfig)
SetLogFile (IGraphBuilder)
SetMasterStream (IConfigAviMux)
SetMediaTime (CMediaSample)
SetMediaTime (IMediaSample)
SetMediaType (CBasePin)
SetMediaType (CBaseRenderer)
SetMediaType (CMediaSample)
SetMediaType (CRendererInputPin)
SetMediaType (CTransformFilter)
SetMediaType (CTransformInputPin)
SetMediaType (CTransformOutputPin)
SetMediaType (IMediaSample)
SetMediaType (IStandardCutList)
SetMessageDrain
SetMessageDrain (IFullScreenVideo)
SetMode (IAMVideoControl)
SetMode (IFileSinkFilter2)
SetMonitor
SetMonitor (IFullScreenVideo)
SetNotifyFlags
SetNotifyFlags (IMediaEventEx)
SetNotifyWindow
SetNotifyWindow (IMediaEventEx)
SetObjects
SetObjects (CBasePropertyPage)
SetOutputCompatibilityIndex
SetOutputCompatibilityIndex (IConfigAviMux)
SetOutputFileName (ICaptureGraphBuilder Interface: Methods in Vtable Order)
SetOutputFileName (ICutListGraphBuilder Interface: Methods in Vtable Order)
SetOutputFileName (ICaptureGraphBuilder)
SetOutputFileName (ICutListGraphBuilder)
SetOutputFormat
SetOutputFormat (IAMLine21Decoder)
SetOverlaySurfaceColorControls (IMixerPinConfig2)
SetPageSite (CBasePropertyPage)
SetPalette (Methods in Vtable Order)
SetPalette (Overridable Member Functions)
SetPalette (CBaseWindow)
SetPalette (IOverlay)
SetParent
SetPointer
SetPointer (CMediaSample)
SetPositions (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
SetPositions (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
SetPositions (Methods in Vtable Order)
SetPositions (CPosPassThru)
SetPositions (CSourceSeeking)
SetPositions (IMediaSeeking)
SetPreroll (Implemented INonDelegatingUnknown Methods)
SetPreroll (Methods in Vtable Order)
SetPreroll (CMediaSample)
SetPreroll (IMediaSample)
SetProperties (CBaseAllocator)
SetProperties (CImageAllocator)
SetProperties (CMemAllocator)
SetProperties (IMediaSample2)
SetProperties (IMemAllocator)
SetRate (CPosPassThru)
SetRate (CSourceSeeking)
SetRate (IMediaSeeking)
SetRect
SetRect (IDirectDrawStreamSample)
SetRedrawAlways
SetRedrawAlways (IAMLine21Decoder)
SetRelativePosition
SetRelativePosition (IMixerPinConfig)
SetRepaintStatus
SetRepaintStatus (CBaseRenderer)
SetRoot
SetRoot (IDvdControl)
SetSameFormat
SetSameFormat (IMediaStream)
SetSampleSize
SetSampleSize (CMediaType)
SetSampleTimes
SetSampleTimes (IStreamSample)
SetScalingFactors
SetScalingFactors (IVPConfig)
SetServiceState
SetServiceState (IAMLine21Decoder)
SetSink (Implemented INonDelegatingUnknown Methods)
SetSink (Implemented IQualityControl Methods)
SetSink (Methods in Vtable Order)
SetSink (CBasePin)
SetSink (CBaseVideoRenderer)
SetSink (IQualityControl)
SetSourcePosition (Implemented IBasicVideo Methods)
SetSourcePosition (Methods in Vtable Order)
SetSourcePosition (CBaseControlVideo)
SetSourcePosition (IBasicVideo)
SetSourcePosition Method (IBasicVideo Object)
SetSourceRect (Implemented IBasicVideo Methods)
SetSourceRect (Member Functions)
SetSourceRect (CBaseControlVideo)
SetSourceRect (CDrawImage)
SetState (IAMMediaStream Interface: Methods in Vtable Order)
SetState (IAMVfwCompressDialogs Interface: Methods in Vtable Order)
SetState (IMultiMediaStream Interface: Methods in Vtable Order)
SetState (IAMMediaStream)
SetState (IAMVfwCompressDialogs)
SetState (IMultiMediaStream)
SetStreamTransparent
SetStreamTransparent (IMixerPinConfig)
SetStretchMode
SetStretchMode (CDrawImage)
SetSubtype
SetSubtype (CMediaType)
SetSurfaceParameters
SetSurfaceParameters (IVPBaseConfig)
SetSwitches
SetSwitches (IDirectDrawVideo)
SetSyncPoint (Implemented INonDelegatingUnknown Methods)
SetSyncPoint (Methods in Vtable Order)
SetSyncPoint (CMediaSample)
SetSyncPoint (IMediaSample)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

CBaseInputPin::GetAllocator
CBaseInputPin::GetAllocatorRequirements
CBaseInputPin::Inactive
CBaseInputPin::IsFlushing
CBaseInputPin::IsReadOnly
CBaseInputPin::NonDelegatingQueryInterface
CBaseInputPin::Notify
CBaseInputPin::NotifyAllocator
CBaseInputPin::PassNotify
CBaseInputPin::Receive
CBaseInputPin::ReceiveCanBlock
CBaseInputPin::ReceiveMultiple
CBaseList (CBaseList)
CBaseList Class
CBaseList::AddAfter
CBaseList::AddAfterI
CBaseList::AddBefore
CBaseList::AddBeforeI
CBaseList::AddHead
CBaseList::AddHeadI
CBaseList::AddTail
CBaseList::AddTailI
CBaseList::CBaseList
CBaseList::FindI
CBaseList::GetCountI
CBaseList::GetHeadPositionI
CBaseList::GetI
CBaseList::GetNextI
CBaseList::GetTailPositionI
CBaseList::MoveToHead
CBaseList::MoveToTail
CBaseList::Next
CBaseList::Prev
CBaseList::RemoveAll
CBaseList::RemoveHeadI
CBaseList::RemoveI
CBaseList::RemoveTailI
CBaseList::Reverse
CBaseMediaFilter (CBaseMediaFilter)
CBaseMediaFilter Class
CBaseMediaFilter::CBaseMediaFilter
CBaseMediaFilter::GetClassID
CBaseMediaFilter::GetState
CBaseMediaFilter::GetSyncSource
CBaseMediaFilter::IsActive
CBaseMediaFilter::NonDelegatingQueryInterface
CBaseMediaFilter::Pause
CBaseMediaFilter::Run
CBaseMediaFilter::SetSyncSource
CBaseMediaFilter::Stop
CBaseMediaFilter::StreamTime
CBaseObject (CBaseObject)
CBaseObject and CUnknown Classes
CBaseObject Class
CBaseObject::CBaseObject
CBaseObject::ObjectsActive
CBaseOutputPin (CBaseOutputPin)
CBaseOutputPin Class
CBaseOutputPin::Active
CBaseOutputPin::BeginFlush
CBaseOutputPin::BreakConnect
CBaseOutputPin::CBaseOutputPin
CBaseOutputPin::CheckConnect
CBaseOutputPin::CompleteConnect
CBaseOutputPin::DecideAllocator
CBaseOutputPin::DecideBufferSize
CBaseOutputPin::Deliver
CBaseOutputPin::DeliverBeginFlush
CBaseOutputPin::DeliverEndFlush
CBaseOutputPin::DeliverEndOfStream
CBaseOutputPin::DeliverNewSegment
CBaseOutputPin::EndFlush
CBaseOutputPin::EndOfStream
CBaseOutputPin::GetDeliveryBuffer
CBaseOutputPin::Inactive
CBaseOutputPin::InitAllocator
CBasePin (CBasePin)
CBasePin Class
CBasePin::Active
CBasePin::AgreeMediaType
CBasePin::AttemptConnection
CBasePin::BreakConnect
CBasePin::CBasePin
CBasePin::CheckConnect
CBasePin::CheckMediaType
CBasePin::CompleteConnect
CBasePin::Connect
CBasePin::ConnectedTo
CBasePin::ConnectionMediaType
CBasePin::CurrentRate
CBasePin::CurrentStartTime
CBasePin::CurrentStopTime
CBasePin::Disconnect
CBasePin::DisplayPinInfo
CBasePin::DisplayTypeInfo
CBasePin::EndOfStream
CBasePin::EnumMediaTypes
CBasePin::GetConnected
CBasePin::GetMediaType
CBasePin::GetMediaTypeVersion
CBasePin::Inactive
CBasePin::IncrementTypeVersion
CBasePin::IsConnected
CBasePin::IsStopped
CBasePin::Name
CBasePin::NewSegment
CBasePin::NonDelegatingAddRef
CBasePin::NonDelegatingQueryInterface
CBasePin::NonDelegatingRelease
CBasePin::Notify
CBasePin::QueryAccept
CBasePin::QueryDirection
CBasePin::QueryId
CBasePin::QueryInternalConnections
CBasePin::QueryPinInfo
CBasePin::ReceiveConnection
CBasePin::Run
CBasePin::SetMediaType
CBasePin::SetSink
CBasePin::TryMediaTypes
CBasePropertyPage (CBasePropertyPage)
CBasePropertyPage Class
CBasePropertyPage::Activate
CBasePropertyPage::Apply
CBasePropertyPage::CBasePropertyPage
CBasePropertyPage::Deactivate
CBasePropertyPage::GetPageInfo
CBasePropertyPage::Help
CBasePropertyPage::IsPageDirty
CBasePropertyPage::Move
CBasePropertyPage::NonDelegatingAddRef
CBasePropertyPage::NonDelegatingQueryInterface
CBasePropertyPage::NonDelegatingRelease
CBasePropertyPage::OnActivate
CBasePropertyPage::OnApplyChanges
CBasePropertyPage::OnConnect
CBasePropertyPage::OnDeactivate
CBasePropertyPage::OnDisconnect
CBasePropertyPage::OnReceiveMessage
CBasePropertyPage::SetObjects
CBasePropertyPage::SetPageSite
CBasePropertyPage::Show
CBasePropertyPage::TranslateAccelerator
CBaseReferenceClock (CBaseReferenceClock)
CBaseReferenceClock Class
CBaseReferenceClock::AdvisePeriodic
CBaseReferenceClock::AdviseTime
CBaseReferenceClock::CBaseReferenceClock
CBaseReferenceClock::GetPrivateTime
CBaseReferenceClock::GetSchedule
CBaseReferenceClock::GetTime
CBaseReferenceClock::NonDelegatingQueryInterface
CBaseReferenceClock::SetTimeDelta
CBaseReferenceClock::TriggerThread
CBaseReferenceClock::Unadvise
CBaseRenderer (CBaseRenderer)
CBaseRenderer Callback Function
CBaseRenderer Class
CBaseRenderer::Active
CBaseRenderer::BeginFlush
CBaseRenderer::BreakConnect
CBaseRenderer::CancelNotification
CBaseRenderer::CBaseRenderer
CBaseRenderer::CheckMediaType
CBaseRenderer::CheckReady
CBaseRenderer::ClearPendingSample
CBaseRenderer::CompleteConnect
CBaseRenderer::CompleteStateChange
CBaseRenderer::DisplayRendererState
CBaseRenderer::DoRenderSample
CBaseRenderer::EndFlush
CBaseRenderer::EndOfStream
CBaseRenderer::FindPin
CBaseRenderer::GetCurrentSample
CBaseRenderer::GetMediaPositionInterface
CBaseRenderer::GetPin
CBaseRenderer::GetPinCount
CBaseRenderer::GetRealState
CBaseRenderer::GetRenderEvent
CBaseRenderer::GetSampleTimes
CBaseRenderer::GetState
CBaseRenderer::HaveCurrentSample
CBaseRenderer::Inactive
CBaseRenderer::IsEndOfStream
CBaseRenderer::IsEndOfStreamDelivered
CBaseRenderer::IsStreaming
CBaseRenderer::NonDelegatingQueryInterface
CBaseRenderer::NotifyEndOfStream
CBaseRenderer::NotReady
CBaseRenderer::OnReceiveFirstSample
CBaseRenderer::OnRenderEnd
CBaseRenderer::OnRenderStart
CBaseRenderer::OnStartStreaming
CBaseRenderer::OnStopStreaming
CBaseRenderer::OnWaitEnd
CBaseRenderer::OnWaitStart
CBaseRenderer::Pause
CBaseRenderer::PrepareReceive
CBaseRenderer::PrepareRender
CBaseRenderer::Ready
CBaseRenderer::Receive
CBaseRenderer::Render
CBaseRenderer::ResetEndOfStream
CBaseRenderer::ResetEndOfStreamTimer
CBaseRenderer::Run
CBaseRenderer::ScheduleSample
CBaseRenderer::SendEndOfStream
CBaseRenderer::SendNotifyWindow
CBaseRenderer::SendRepaint
CBaseRenderer::SetAbortSignal
CBaseRenderer::SetMediaType
CBaseRenderer::SetRepaintStatus
CBaseRenderer::ShouldDrawSampleNow
CBaseRenderer::SignalTimerFired
CBaseRenderer::SourceThreadCanWait
CBaseRenderer::StartStreaming
CBaseRenderer::Stop
CBaseRenderer::StopStreaming
CBaseRenderer::TimerCallback
CBaseRenderer::WaitForReceiveToComplete
CBaseRenderer::WaitForRenderTime
CBaseStreamControl (CBaseStreamControl)
CBaseStreamControl Class
CBaseStreamControl::CBaseStreamControl
CBaseStreamControl::CheckStreamState
CBaseStreamControl::Flushing
CBaseStreamControl::GetInfo
CBaseStreamControl::NotifyFilterState
CBaseStreamControl::SetFilterGraph
CBaseStreamControl::SetSyncSource
CBaseStreamControl::StartAt
CBaseStreamControl::StopAt
CBaseVideoRenderer (CBaseVideoRenderer)
CBaseVideoRenderer Class
CBaseVideoRenderer::CBaseVideoRenderer
CBaseVideoRenderer::get_AvgFrameRate
CBaseVideoRenderer::get_AvgSyncOffset
CBaseVideoRenderer::get_DevSyncOffset
CBaseVideoRenderer::get_FramesDrawn
CBaseVideoRenderer::get_FramesDroppedInRenderer
CBaseVideoRenderer::get_Jitter
CBaseVideoRenderer::GetStdDev
CBaseVideoRenderer::JoinFilterGraph
CBaseVideoRenderer::NonDelegatingQueryInterface
CBaseVideoRenderer::Notify
CBaseVideoRenderer::OnDirectRender
CBaseVideoRenderer::OnRenderEnd
CBaseVideoRenderer::OnRenderStart
CBaseVideoRenderer::OnStartStreaming
CBaseVideoRenderer::OnStopStreaming
CBaseVideoRenderer::OnWaitEnd
CBaseVideoRenderer::OnWaitStart
CBaseVideoRenderer::PreparePerformanceData
CBaseVideoRenderer::RecordFrameLateness
CBaseVideoRenderer::ResetStreamingTimes
CBaseVideoRenderer::ScheduleSample
CBaseVideoRenderer::SendQuality
CBaseVideoRenderer::SetSink
CBaseVideoRenderer::ShouldDrawSampleNow
CBaseVideoRenderer::ThrottleWait
CBaseVideoWindow (CBaseVideoWindow)
CBaseVideoWindow Class
CBaseVideoWindow::CBaseVideoWindow
CBaseVideoWindow::GetIDsOfNames
CBaseVideoWindow::GetTypeInfo
CBaseVideoWindow::GetTypeInfoCount
CBaseVideoWindow::Invoke
CBaseVideoWindow::NonDelegatingQueryInterface
CBaseWindow (CBaseWindow)
CBaseWindow Class
CBaseWindow::ActivateWindow
CBaseWindow::CBaseWindow
CBaseWindow::DoneWithWindow
CBaseWindow::DoRealisePalette
CBaseWindow::DoSetWindowForeground
CBaseWindow::DoShowWindow
CBaseWindow::GetClassWindowStyles
CBaseWindow::GetDefaultRect
CBaseWindow::GetMemoryHDC
CBaseWindow::GetWindowHDC
CBaseWindow::GetWindowHeight
CBaseWindow::GetWindowHWND
CBaseWindow::GetWindowWidth
CBaseWindow::InactivateWindow
CBaseWindow::InitialiseWindow
CBaseWindow::OnClose
CBaseWindow::OnPaletteChange
CBaseWindow::OnReceiveMessage
CBaseWindow::OnSize
CBaseWindow::PaintWindow
CBaseWindow::PerformanceAlignWindow
CBaseWindow::PossiblyEatMessage
CBaseWindow::PrepareWindow
CBaseWindow::SetPalette
CBaseWindow::UninitialiseWindow
CBasicAudio (CBasicAudio)
CBasicAudio Class
CBasicAudio::CBasicAudio
CBasicAudio::GetIDsOfNames
CBasicAudio::GetTypeInfo
CBasicAudio::GetTypeInfoCount
CBasicAudio::Invoke
CBasicAudio::NonDelegatingQueryInterface
cbBuffer (ALLOCATOR_PROPERTIES)
cbBuffer (AM_SAMPLE2_PROPERTIES)
cbData
cbFormat
cbPrefix
cbSequenceHeader (MPEG1VIDEOINFO)
cbSequenceHeader (MPEG2VIDEOINFO)
cBuffers
CClassFactory
CCmdQueue (CCmdQueue)
CCmdQueue Class
CCmdQueue::CCmdQueue
CCmdQueue::CheckTime
CCmdQueue::EndRun
CCmdQueue::GetCommandDueFor
CCmdQueue::GetDueCommand
CCmdQueue::GetDueHandle
CCmdQueue::Insert
CCmdQueue::New
CCmdQueue::Remove
CCmdQueue::Run
CCmdQueue::SetSyncSource
CCmdQueue::SetTimeAdvise
CCritSec (CCritSec)
CCritSec Class
CCritSec Debug Functions
CCritSec::CCritSec
CCritSec::Lock
CCritSec::Unlock
CDeferredCommand (CDeferredCommand)
CDeferredCommand Class
CDeferredCommand::Cancel
CDeferredCommand::CDeferredCommand
CDeferredCommand::Confidence
CDeferredCommand::GetFlags
CDeferredCommand::GetHResult
CDeferredCommand::GetIID
CDeferredCommand::GetMethod
CDeferredCommand::GetParams
CDeferredCommand::GetResult
CDeferredCommand::GetTime
CDeferredCommand::Invoke
CDeferredCommand::IsStreamTime
CDeferredCommand::NonDelegatingQueryInterface
CDeferredCommand::Postpone
CDisp (CDisp)
CDisp Class
CDisp::CDisp
CDisp::LPCTSTR
CDispBasic
CDispBasic (CDispBasic)
CDispBasic::CDispBasic
CDispParams (CDispParams)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

GetAllocator (CBaseInputPin)
GetAllocator (CTransInPlaceInputPin)
GetAllocator (IMemInputPin)
GetAllocatorProperties (IAMBufferNegotiation)
GetAllocatorRequirements (CBaseInputPin)
GetAllocatorRequirements (CTransInPlaceInputPin)
GetAllocatorRequirements (IMemInputPin)
GetAllSPRMs (IDvdInfo)
GetAspectRatioMode (IMixerPinConfig)
GetAudioData (IAudioStreamSample)
GetAudioLanguage (IDvdInfo)
GetAvailable (CPosPassThru)
GetAvailable (CSourceSeeking)
GetAvailable (IMediaSeeking)
GetAverageFrameSize (IAMDroppedFrames)
GetBackgroundColor (IAMLine21Decoder)
GetBitCount
GetBitmapFormatSize
GetBitmapPalette
GetBitmapSize
GetBitmapSubtype
GetBitMasks (CImageDisplay)
GetBlendingParameter (IMixerPinConfig)
GetBorderColour (CBaseControlWindow)
GetBuffer (CBaseAllocator)
GetBuffer (IMemAllocator)
GetBump (IAMExtTransport)
GetCapabilities (CPosPassThru)
GetCapabilities (CSourceSeeking)
GetCapabilities (IMediaSeeking)
GetCapability (IAMExtDevice)
GetCapability (IAMExtTransport)
GetCaps (IAMVideoControl)
GetCaps (IDirectDrawVideo)
GetCaption (IFullScreenVideo)
GetChase (IAMExtTransport)
GetClassFile
GetClassID (CBaseFilter)
GetClassID (CBaseMediaFilter)
GetClassID (CPersistStream)
GetClassID (CSystemClock)
GetClassWindowStyles (CBaseWindow)
GetClientRect
GetClipFactor (IFullScreenVideo)
GetClipList (IOverlay)
GetColorKey (IMixerPinConfig)
GetColorKey (IOverlay)
GetColourMask
GetColourMask (CImageDisplay)
GetCommandDueFor (CCmdQueue)
GetConnected
GetConnected (CBasePin)
GetConnectInfo
GetConnectInfo (IVPBaseConfig)
GetCount
GetCount (CGenericList)
GetCountI
GetCountI (CBaseList)
GetCurFile (IFileSinkFilter)
GetCurfile (IFileSourceFilter)
GetCurrentActualFrameRate (IAMVideoControl)
GetCurrentAngle (IDvdInfo)
GetCurrentAudio (IDvdInfo)
GetCurrentAudioAttributes
GetCurrentAudioAttributes (IDvdInfo)
GetCurrentButton
GetCurrentButton (IDvdInfo)
GetCurrentDomain
GetCurrentDomain (IDvdInfo)
GetCurrentImage (CBaseControlVideo)
GetCurrentImage (IBasicVideo)
GetCurrentImage Method (IBasicVideo Object)
GetCurrentLocation
GetCurrentLocation (IDvdInfo)
GetCurrentMode
GetCurrentMode (IFullScreenVideo)
GetCurrentPosition (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetCurrentPosition (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetCurrentPosition (Methods in Vtable Order)
GetCurrentPosition (CPosPassThru)
GetCurrentPosition (CSourceSeeking)
GetCurrentPosition (IMediaSeeking)
GetCurrentSample
GetCurrentSample (CBaseRenderer)
GetCurrentService
GetCurrentService (IAMLine21Decoder)
GetCurrentSubpicture
GetCurrentSubpicture (IDvdInfo)
GetCurrentSubpictureAttributes
GetCurrentSubpictureAttributes (IDvdInfo)
GetCurrentUOPS
GetCurrentUOPS (IDvdInfo)
GetCurrentVideoAttributes
GetCurrentVideoAttributes (IDvdInfo)
GetCurrentVolumeInfo
GetCurrentVolumeInfo (IDvdInfo)
GetDDInterface
GetDecoderLevel
GetDecoderLevel (IAMLine21Decoder)
GetDefaultColorKey
GetDefaultColorKey (IOverlay)
GetDefaultRect
GetDefaultRect (CBaseWindow)
GetDeinterlaceMode
GetDeinterlaceMode (IVPNotify)
GetDeliveryBuffer
GetDeliveryBuffer (CBaseOutputPin)
GetDestinationPosition (Implemented IBasicVideo Methods)
GetDestinationPosition (Methods in Vtable Order)
GetDestinationPosition (CBaseControlVideo)
GetDestinationPosition (IBasicVideo)
GetDestinationPosition Method (IBasicVideo Object)
GetDevId
GetDevId (IAMDevMemoryControl)
GetDevMemoryObject
GetDevMemoryObject (IAMDevMemoryAllocator)
GetDialogSize
GetDIBData
GetDIBData (CImageSample)
GetDirectDraw (IDirectDrawMediaStream Interface: Methods in Vtable Order)
GetDirectDraw (IDirectDrawVideo Interface: Methods in Vtable Order)
GetDirectDraw (Member Functions)
GetDirectDraw (CLoadDirectDraw)
GetDirectDraw (IDirectDrawMediaStream)
GetDirectDraw (IDirectDrawVideo)
GetDirectSoundInterface
GetDirectSoundInterface (IAMDirectSound)
GetDisplayDepth
GetDisplayDepth (CImageDisplay)
GetDisplayFormat
GetDisplayFormat (CImageDisplay)
GetDrawBackgroundMode
GetDrawBackgroundMode (IAMLine21Decoder)
GetDroppedInfo
GetDroppedInfo (IAMDroppedFrames)
GetDueCommand
GetDueCommand (CCmdQueue)
GetDueHandle
GetDueHandle (CCmdQueue)
GetDuration (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetDuration (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetDuration (IMediaSeeking Interface: Methods in Vtable Order)
GetDuration (IMultiMediaStream Interface: Methods in Vtable Order)
GetDuration (CPosPassThru)
GetDuration (CSourceSeeking)
GetDuration (IMediaSeeking)
GetDuration (IMultiMediaStream)
GetDvdInterface
GetDvdInterface (IDvdGraphBuilder)
GetDVDTextInfo
GetDVDTextInfo (IDvdInfo)
GetEditProperty
GetEditProperty (IAMExtTransport)
GetEditPropertySet
GetEditPropertySet (IAMExtTransport)
GetElementDuration
GetElementDuration (IAMCutListElement)
GetElementFlags
GetElementFlags (ICutListGraphBuilder)
GetElementSplitOffset
GetElementSplitOffset (IAMFileCutListElement)
GetElementStartPosition
GetElementStartPosition (IAMCutListElement)
GetEmulatedCaps
GetEmulatedCaps (IDirectDrawVideo)
GetEndOfStreamEventHandle
GetEndOfStreamEventHandle (IMultiMediaStream)
GetEvent (CAMSchedule Class: Member Functions)
GetEvent (IAMovie Interface: Methods in Vtable Order)
GetEvent (IMediaEvent Interface: Methods in Vtable Order)
GetEvent (CAMSchedule)
GetEvent (IAMovie)
GetEvent (IMediaEvent)
GetEvent Method (IMediaEvent Object)
GetEventHandle (IAMovie Interface: Methods in Vtable Order)
GetEventHandle (IMediaEvent Interface: Methods in Vtable Order)
GetEventHandle (IAMovie)
GetEventHandle (IMediaEvent)
GetEventHandle Method (IMediaEvent Object)
GetFileName
GetFileName (IAMFileCutListElement)
GetFilter
GetFilter (IAMMultiMediaStream)
GetFilterGraph (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
GetFilterGraph (IAMMultiMediaStream Interface: Methods in Vtable Order)
GetFiltergraph (ICaptureGraphBuilder Interface: Methods in Vtable Order)
GetFilterGraph (ICutListGraphBuilder Interface: Methods in Vtable Order)
GetFiltergraph (IDvdGraphBuilder Interface: Methods in Vtable Order)
GetFilterGraph (CBaseFilter)
GetFilterGraph (IAMMultiMediaStream)
GetFiltergraph (ICaptureGraphBuilder)
GetFilterGraph (ICutListGraphBuilder)
GetFiltergraph (IDvdGraphBuilder)
GetFirstElement
GetFirstElement (IStandardCutList)
GetFlags
GetFlags (CDeferredCommand)
GetFormat (IAMStreamConfig Interface: Methods in Vtable Order)
GetFormat (IAudioData Interface: Methods in Vtable Order)
GetFormat (IAudioMediaStream Interface: Methods in Vtable Order)
GetFormat (IDirectDrawMediaStream Interface: Methods in Vtable Order)
GetFormat (IAMStreamConfig)
GetFormat (IAudioData)
GetFormat (IAudioMediaStream)
GetFormat (IDirectDrawMediaStream)
GetFOURCC (FOURCCMap)
GetFourCCCodes (IDirectDrawVideo)
GetFrameRateList (IAMVideoControl)
GetHead (CGenericList)
GetHeadPosition (CGenericList)
GetHeadPositionI
GetHeadPositionI (CBaseList)
GetHResult (Implemented INonDelegatingUnknown Methods)
GetHResult (Methods in Vtable Order)
GetHResult (CDeferredCommand)
GetHResult (IDeferredCommand)
GetI
GetI (CBaseList)
GetIDsOfNames (CBaseBasicVideo Class: Implemented IDispatch Methods)
GetIDsOfNames (CBaseDispatch Class: Implemented IDispatch Methods)
GetIDsOfNames (CBaseVideoWindow Class: Implemented IDispatch Methods)
GetIDsOfNames (CBasicAudio Class: Implemented IDispatch Methods)
GetIDsOfNames (CMediaControl Class: Implemented IDispatch Methods)
GetIDsOfNames (CMediaEvent Class: Implemented IDispatch Methods)
GetIDsOfNames (CMediaPosition Class: Implemented IDispatch Methods)
GetIDsOfNames (CBaseBasicVideo)
GetIDsOfNames (CBaseDispatch)
GetIDsOfNames (CBaseVideoWindow)
GetIDsOfNames (CBasicAudio)
GetIDsOfNames (CMediaControl)
GetIDsOfNames (CMediaEvent)
GetIDsOfNames (CMediaPosition)
GetIID
GetIID (CDeferredCommand)
GetImageSize
GetImageSize (CBaseControlVideo)
GetInfo (CBaseStreamControl Class: Member Functions)
GetInfo (IAMDevMemoryAllocator Interface: Methods in Vtable Order)
GetInfo (IAMStreamControl Interface: Methods in Vtable Order)
GetInfo (IAMVideoCompression Interface: Methods in Vtable Order)
GetInfo (IMemoryData Interface: Methods in Vtable Order)
GetInfo (CBaseStreamControl)
GetInfo (IAMDevMemoryAllocator)
GetInfo (IAMStreamControl)
GetInfo (IAMVideoCompression)
GetInfo (IMemoryData)
GetInformation (IMediaStream Interface: Methods in Vtable Order)
GetInformation (IMultiMediaStream Interface: Methods in Vtable Order)
GetInformation (IMediaStream)
GetInformation (IMultiMediaStream)
GetInterface
GetLastElement (IStandardCutList)
GetLastError
GetMasterStream (IConfigAviMux)
GetMaxAvailableFrameRate (IAMVideoControl)
GetMaxIdealImageSize (CBaseControlWindow)
GetMaxIdealImageSize (IVideoWindow)
GetMaxIdealImageSize Method (IVideoWindow Object)
GetMaxPixelRate (IVPBaseConfig)
GetMediaPositionInterface
GetMediaPositionInterface (CBaseRenderer)
GetMediaStream (IMultiMediaStream Interface: Methods in Vtable Order)
GetMediaStream (IStreamSample Interface: Methods in Vtable Order)
GetMediaStream (IMultiMediaStream)
GetMediaStream (IStreamSample)
GetMediaTime (CMediaSample Class: Implemented INonDelegatingUnknown Methods)
GetMediaTime (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetMediaTime (CRendererPosPassThru Class: Member Functions)
GetMediaTime (Methods in Vtable Order)
GetMediaTime (CMediaSample)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

ICutListGraphBuilder::Render
ICutListGraphBuilder::SetFilterGraph
ICutListGraphBuilder::SetOutputFileName
IDataObject
IDeferredCommand Interface
IDeferredCommand::Cancel
IDeferredCommand::Confidence
IDeferredCommand::GetHResult
IDeferredCommand::Postpone
IDirectDraw
IDirectDraw::Compact
IDirectDraw::CreateClipper
IDirectDraw::CreatePalette
IDirectDraw::CreateSurface
IDirectDraw::DuplicateSurface
IDirectDraw::EnumDisplayModes
IDirectDraw::EnumSurfaces
IDirectDraw::FlipToGDISurface
IDirectDraw::GetCaps
IDirectDraw::GetDisplayMode
IDirectDraw::GetFourCCCodes
IDirectDraw::GetGDISurface
IDirectDraw::GetMonitorFrequency
IDirectDraw::GetScanLine
IDirectDraw::GetVerticalBlankStatus
IDirectDraw::Initialize
IDirectDraw::RestoreDisplayMode
IDirectDraw::SetCooperativeLevel
IDirectDraw::SetDisplayMode
IDirectDraw::WaitForVerticalBlank
IDirectDraw2
IDirectDraw2::CreateSurface
IDirectDraw2::SetCooperativeLevel
IDirectDraw3 Interface
IDirectDraw3::CreateClipper
IDirectDraw3::CreateSurface
IDirectDraw3::GetSurfaceFromDC
IDirectDrawClipper
IDirectDrawClipper::SetHWnd
IDirectDrawFactory Interface
IDirectDrawFactory::CreateDirectDraw
IDirectDrawFactory::DirectDrawEnumerate
IDirectDrawMediaStream Interface
IDirectDrawMediaStream::CreateSample
IDirectDrawMediaStream::GetDirectDraw
IDirectDrawMediaStream::GetFormat
IDirectDrawMediaStream::GetTimePerFrame
IDirectDrawMediaStream::SetDirectDraw
IDirectDrawMediaStream::SetFormat
IDirectDrawStreamSample Interface
IDirectDrawStreamSample::GetSurface
IDirectDrawStreamSample::SetRect
IDirectDrawSurface
IDirectDrawSurface::AddAttachedSurface
IDirectDrawSurface::Blt
IDirectDrawSurface::BltBatch
IDirectDrawSurface::BltFast
IDirectDrawSurface::DeleteAttachedSurface
IDirectDrawSurface::EnumAttachedSurfaces
IDirectDrawSurface::EnumOverlayZOrders
IDirectDrawSurface::Flip
IDirectDrawSurface::GetAttachedSurface
IDirectDrawSurface::GetBltStatus
IDirectDrawSurface::GetCaps
IDirectDrawSurface::GetClipper
IDirectDrawSurface::GetColorKey
IDirectDrawSurface::GetDC
IDirectDrawSurface::GetFlipStatus
IDirectDrawSurface::GetOverlayPosition
IDirectDrawSurface::GetPalette
IDirectDrawSurface::GetPixelFormat
IDirectDrawSurface::GetSurfaceDesc
IDirectDrawSurface::Initialize
IDirectDrawSurface::IsLost
IDirectDrawSurface::Lock
IDirectDrawSurface::ReleaseDC
IDirectDrawSurface::Restore
IDirectDrawSurface::SetClipper
IDirectDrawSurface::SetColorKey
IDirectDrawSurface::SetOverlayPosition
IDirectDrawSurface::SetPalette
IDirectDrawSurface::Unlock
IDirectDrawSurface::UpdateOverlay
IDirectDrawSurface::UpdateOverlayDisplay
IDirectDrawSurface::UpdateOverlayZOrder
IDirectDrawSurface3::Blt
IDirectDrawVideo Interface
IDirectDrawVideo::CanUseOverlayStretch
IDirectDrawVideo::CanUseScanLine
IDirectDrawVideo::GetCaps
IDirectDrawVideo::GetDirectDraw
IDirectDrawVideo::GetEmulatedCaps
IDirectDrawVideo::GetFourCCCodes
IDirectDrawVideo::GetSurfaceDesc
IDirectDrawVideo::GetSurfaceType
IDirectDrawVideo::GetSwitches
IDirectDrawVideo::SetDefault
IDirectDrawVideo::SetDirectDraw
IDirectDrawVideo::SetSwitches
IDirectDrawVideo::UseOverlayStretch
IDirectDrawVideo::UseScanLine
IDirectDrawVideo::UseWhenFullScreen
IDirectDrawVideo::WillUseFullScreen
IDirectSound
IDirectSoundBuffer
IDispatch
IDispatch::GetIDsOfNames
IDispatch::GetTypeInfo
IDispatch::GetTypeInfoCount
IDispatch::Invoke
IDistributorNotify Interface
IDistributorNotify::NotifyGraphChange
IDistributorNotify::Pause
IDistributorNotify::Run
IDistributorNotify::SetSyncSource
IDistributorNotify::Stop
IDvdControl Interface
IDvdControl::AngleChange
IDvdControl::AudioStreamChange
IDvdControl::BackwardScan
IDvdControl::ButtonActivate
IDvdControl::ButtonSelectAndActivate
IDvdControl::ChapterPlay
IDvdControl::ChapterPlayAutoStop
IDvdControl::ChapterSearch
IDvdControl::ForwardScan
IDvdControl::GoUp
IDvdControl::KaraokeAudioPresentationModeChange
IDvdControl::LeftButtonSelect
IDvdControl::LowerButtonSelect
IDvdControl::MenuCall
IDvdControl::MenuLanguageSelect
IDvdControl::MouseActivate
IDvdControl::MouseSelect
IDvdControl::NextPGSearch
IDvdControl::ParentalCountrySelect
IDvdControl::ParentalLevelSelect
IDvdControl::PauseOff
IDvdControl::PauseOn
IDvdControl::PrevPGSearch
IDvdControl::Resume
IDvdControl::RightButtonSelect
IDvdControl::SetRoot
IDvdControl::StillOff
IDvdControl::StopForResume
IDvdControl::SubpictureStreamChange
IDvdControl::TimePlay
IDvdControl::TimeSearch
IDvdControl::TitlePlay
IDvdControl::TopPGSearch
IDvdControl::UpperButtonSelect
IDvdControl::VideoModePreferrence
IDvdGraphBuilder Interface
IDvdGraphBuilder::GetDvdInterface
IDvdGraphBuilder::GetFiltergraph
IDvdGraphBuilder::RenderDvdVideoVolume
IDvdInfo Interface
IDvdInfo::GetAllGPRMs
IDvdInfo::GetAllSPRMs
IDvdInfo::GetAudioLanguage
IDvdInfo::GetCurrentAngle
IDvdInfo::GetCurrentAudio
IDvdInfo::GetCurrentAudioAttributes
IDvdInfo::GetCurrentButton
IDvdInfo::GetCurrentDomain
IDvdInfo::GetCurrentLocation
IDvdInfo::GetCurrentSubpicture
IDvdInfo::GetCurrentSubpictureAttributes
IDvdInfo::GetCurrentUOPS
IDvdInfo::GetCurrentVideoAttributes
IDvdInfo::GetCurrentVolumeInfo
IDvdInfo::GetDVDTextInfo
IDvdInfo::GetNumberOfChapters
IDvdInfo::GetPlayerParentalLevel
IDvdInfo::GetRoot
IDvdInfo::GetSubpictureLanguage
IDvdInfo::GetTitleAttributes
IDvdInfo::GetTitleParentalLevels
IDvdInfo::GetTotalTitleTime
IDvdInfo::GetVMGAttributes
IEnumFilters Interface
IEnumFilters::Clone
IEnumFilters::Next
IEnumFilters::Reset
IEnumFilters::Skip
IEnumMediaTypes Interface
IEnumMediaTypes::Clone
IEnumMediaTypes::Next
IEnumMediaTypes::Reset
IEnumMediaTypes::Skip
IEnumMoniker
IEnumPins Interface
IEnumPins::Clone
IEnumPins::Next
IEnumPins::Reset
IEnumPins::Skip
IEnumRegFilters Interface
IEnumRegFilters::Clone
IEnumRegFilters::Next
IEnumRegFilters::Reset
IEnumRegFilters::Skip
IEnumVARIANT
IEnumXXXX
IFileClip Interface
IFileClip::CreateCut
IFileClip::GetMediaType
IFileClip::SetFileAndStream
IFileSinkFilter Interface
IFileSinkFilter::GetCurFile
IFileSinkFilter::SetFileName
IFileSinkFilter2 Interface
IFileSinkFilter2::GetMode
IFileSinkFilter2::SetMode
IFileSourceFilter Interface
IFileSourceFilter::GetCurfile
IFileSourceFilter::Load
IFilterGraph Interface
IFilterGraph::AddFilter
IFilterGraph::ConnectDirect
IFilterGraph::Disconnect
IFilterGraph::EnumFilters
IFilterGraph::FindFilterByName
IFilterGraph::Reconnect
IFilterGraph::RemoveFilter
IFilterGraph::SetDefaultSyncSource
IFilterGraph2 Interface
IFilterGraph2::AddSourceFilterForMoniker
IFilterGraph2::ReconnectEx
IFilterInfo Interface
IFilterInfo Object
IFilterInfo::FindPin
IFilterInfo::get_Filename
IFilterInfo::get_Filter
IFilterInfo::get_IsFileSource
IFilterInfo::get_Name
IFilterInfo::get_Pins
IFilterInfo::get_VendorInfo
IFilterInfo::put_Filename
IFilterMapper Interface
IFilterMapper::EnumMatchingFilters
IFilterMapper::RegisterFilter
IFilterMapper::RegisterFilterInstance
IFilterMapper::RegisterPin
IFilterMapper::RegisterPinType
IFilterMapper::UnregisterFilter
IFilterMapper::UnregisterFilterInstance
IFilterMapper::UnregisterPin
IFilterMapper2 Interface
IFilterMapper2::CreateCategory
IFilterMapper2::EnumMatchingFilters
IFilterMapper2::RegisterFilter
IFilterMapper2::UnregisterFilter
IFullScreenVideo Interface
IFullScreenVideo::CountModes
IFullScreenVideo::GetCaption
IFullScreenVideo::GetClipFactor
IFullScreenVideo::GetCurrentMode
IFullScreenVideo::GetMessageDrain
IFullScreenVideo::GetModeInfo
IFullScreenVideo::GetMonitor
IFullScreenVideo::HideOnDeactivate
IFullScreenVideo::IsHideOnDeactivate
IFullScreenVideo::IsModeAvailable
IFullScreenVideo::IsModeEnabled
IFullScreenVideo::SetCaption
IFullScreenVideo::SetClipFactor
IFullScreenVideo::SetDefault
IFullScreenVideo::SetEnabled
IFullScreenVideo::SetMessageDrain
IFullScreenVideo::SetMonitor
IGraphBuilder Interface
IGraphBuilder::AddSourceFilter
IGraphBuilder::Connect
IGraphBuilder::Render
IGraphBuilder::RenderFile
IGraphBuilder::SetLogFile
IGraphVersion Interface
IGraphVersion::QueryVersion
IKsPropertySet Interface
IKsPropertySet::Get
IKsPropertySet::QuerySupported
IKsPropertySet::Set
Image Effects filter
IMediaControl Interface
IMediaControl Object
IMediaControl::AddSourceFilter
IMediaControl::get_FilterCollection
IMediaControl::get_RegFilterCollection
IMediaControl::GetState
IMediaControl::Pause
IMediaControl::RenderFile
IMediaControl::Run
IMediaControl::Stop
IMediaControl::StopWhenReady
IMediaEvent Interface
IMediaEvent Object
IMediaEvent::CancelDefaultHandling
IMediaEvent::FreeEventParams
IMediaEvent::GetEvent
IMediaEvent::GetEventHandle
IMediaEvent::RestoreDefaultHandling
IMediaEvent::WaitForCompletion
IMediaEventEx Interface
IMediaEventEx::GetNotifyFlags
IMediaEventEx::SetNotifyFlags
IMediaEventEx::SetNotifyWindow
IMediaEventSink Interface
IMediaEventSink::Notify
IMediaFilter Interface
IMediaFilter::GetState
IMediaFilter::GetSyncSource
IMediaFilter::Pause
IMediaFilter::Run
IMediaFilter::SetSyncSource
IMediaFilter::Stop
IMediaPosition Interface
IMediaPosition Object
IMediaPosition::CanSeekBackward
IMediaPosition::CanSeekForward
IMediaPosition::get_CurrentPosition
IMediaPosition::get_Duration
IMediaPosition::get_PrerollTime
IMediaPosition::get_Rate
IMediaPosition::get_StopTime
IMediaPosition::put_CurrentPosition
IMediaPosition::put_PrerollTime
IMediaPosition::put_Rate
IMediaPosition::put_StopTime
IMediaPropertyBag Interface
IMediaPropertyBag::EnumProperty
IMediaSample Interface
IMediaSample::GetActualDataLength
IMediaSample::GetMediaTime
IMediaSample::GetMediaType
IMediaSample::GetPointer
IMediaSample::GetSize
IMediaSample::GetTime
IMediaSample::IsDiscontinuity
IMediaSample::IsPreroll
IMediaSample::IsSyncPoint

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

MPEG2Level
MPEG2Level_High
MPEG2Level_High1440
MPEG2Level_Low
MPEG2Level_Main
MPEG2Profile
MPEG2Profile_High
MPEG2Profile_Main
MPEG2Profile_Simple
MPEG2Profile_SNRScalable
MPEG2Profile_SpatiallyScalable
MPEG2VIDEOINFO
MPEGProp Sample (MPEG Property Page Display Application)
MPGAudio Sample (MPEG Audio Decoder Filter)
MPGVideo Sample (MPEG Video Decoder Filter)
mPS_dwFileVersion
mPS_fDirty
MS_E_BUSY
MS_E_INCOMPATIBLE
MS_E_INVALIDSTREAMTYPE
MS_E_NOSEEKING
MS_E_NOSTREAM
MS_E_NOTINIT
MS_E_NOTRUNNING
MS_E_PURPOSEID
MS_E_SAMPLEALLOC
MS_E_SOURCEALREADYDEFINED
MS_S_ENDOFSTREAM
MS_S_NOUPDATE
MS_S_PENDING
MSG
MsgWaitForMultipleObjects
MSPID
MSR_START
MSR_STOP
MultiByteToWideChar
Multi-File Parser
Multimedia Data Type Classes
Multimedia Streaming Data Types
Multiple Clocks in a Filter Graph


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

SetSyncSource (CBaseFilter)
SetSyncSource (CBaseMediaFilter)
SetSyncSource (CBaseStreamControl)
SetSyncSource (CCmdQueue)
SetSyncSource (IDistributorNotify)
SetSyncSource (IMediaFilter)
SetTargetRect (Implemented IBasicVideo Methods)
SetTargetRect (Member Functions)
SetTargetRect (CBaseControlVideo)
SetTargetRect (CDrawImage)
SetTCDisplay
SetTCDisplay (IAMTimecodeDisplay)
SetTCDisplayEnable
SetTCDisplayEnable (IAMTimecodeDisplay)
SetTCGMode
SetTCGMode (IAMTimecodeGenerator)
SetTCRMode
SetTCRMode (IAMTimecodeReader)
SetTemporalCompression
SetTemporalCompression (CMediaType)
SetThreadPriority
SetThreadPriority (CMsgThread)
SetTime (Implemented INonDelegatingUnknown Methods)
SetTime (Methods in Vtable Order)
SetTime (CMediaSample)
SetTime (IMediaSample)
SetTimeAdvise
SetTimeAdvise (CCmdQueue)
SetTimecode
SetTimecode (IAMTimecodeGenerator)
SetTimeDelta
SetTimeDelta (CBaseReferenceClock)
SetTimeFormat (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
SetTimeFormat (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
SetTimeFormat (Methods in Vtable Order)
SetTimeFormat (CPosPassThru)
SetTimeFormat (CSourceSeeking)
SetTimeFormat (IMediaSeeking)
Setting Up the Registry
SetTransportAudioParameters
SetTransportAudioParameters (IAMExtTransport)
SetTransportBasicParameters
SetTransportBasicParameters (IAMExtTransport)
SetTransportVideoParameters
SetTransportVideoParameters (IAMExtTransport)
SetType (CMediaType)
SetVariableSize (CMediaType)
SetVideoFormat (IVPBaseConfig)
SetVideoPortID (IVPBaseConfig)
SetVPSyncMaster (IVPNotify2)
SetWaiting (CBaseAllocator)
SetWindowFocus
SetWindowFocus (IAMDirectSound)
SetWindowForeground (Implemented IVideoWindow Methods)
SetWindowForeground (Methods in Vtable Order)
SetWindowForeground (CBaseControlWindow)
SetWindowForeground (IVideoWindow)
SetWindowForeground Method (IVideoWindow Object)
SetWindowLong
SetWindowPosition (Implemented IVideoWindow Methods)
SetWindowPosition (Methods in Vtable Order)
SetWindowPosition (CBaseControlWindow)
SetWindowPosition (IVideoWindow)
SetWindowPosition Method (IVideoWindow Object)
SetZOrder
SetZOrder (IMixerPinConfig)
ShouldDrawSampleNow (Helper Function)
ShouldDrawSampleNow (Implemented IQualityControl Methods)
ShouldDrawSampleNow (CBaseRenderer)
ShouldDrawSampleNow (CBaseVideoRenderer)
ShouldSkipFrame
ShouldSkipFrame (CVideoTransformFilter)
ShouldUpdate
ShouldUpdate (CImagePalette)
Show
Show (CBasePropertyPage)
ShowControls Property
ShowDialog (IAMVfwCaptureDialogs Interface: Methods in Vtable Order)
ShowDialog (IAMVfwCompressDialogs Interface: Methods in Vtable Order)
ShowDialog (IAMVfwCaptureDialogs)
ShowDialog (IAMVfwCompressDialogs)
ShowDisplay Property
ShowPositionControls Property
ShowSelectionControls Property
ShowStrm Sample (Multimedia Streaming Application)
ShowTracker Property
ShowWindow
ShrinkTapsX
ShrinkTapsY
SignalTimerFired
SignalTimerFired (CBaseRenderer)
Simplecl Sample (Cutlist Application)
sink file
SIZE
SIZE_EGA_PALETTE
SIZE_MASKS
SIZE_MPEG1VIDEOINFO
SIZE_PALETTE
SIZE_PREHEADER
SIZE_VIDEOHEADER
SizeMax
SizeMax (CPersistStream)
Skip (CEnumMediaTypes Class: Implemented IEnumMediaTypes Methods)
Skip (CEnumPins Class: Implemented IEnumPins Methods)
Skip (IEnumFilters Interface: Methods in Vtable Order)
Skip (IEnumMediaTypes Interface: Methods in Vtable Order)
Skip (IEnumPins Interface: Methods in Vtable Order)
Skip (IEnumRegFilters Interface: Methods in Vtable Order)
Skip (CEnumMediaTypes)
Skip (CEnumPins)
Skip (IEnumFilters)
Skip (IEnumMediaTypes)
Skip (IEnumPins)
Skip (IEnumRegFilters)
SlowRender
SlowRender (CDrawImage)
Smart Tee filter
SMPTE timecode (Capturing Timecode)
SMPTE timecode (Typical Uses of Timecode)
SMPTE timecode (Understanding SMPTE Timecode)
source filter
Source Filters
SourceHeight Property (IBasicVideo Object)
SourceLeft Property (IBasicVideo Object)
SourceThreadCanWait
SourceThreadCanWait (CBaseRenderer)
SourceTop Property (IBasicVideo Object)
SourceWidth Property (IBasicVideo Object)
sppal
sscanf
StartAt (Member Functions)
StartAt (Methods in Vtable Order)
StartAt (CBaseStreamControl)
StartAt (IAMStreamControl)
StartPTM
StartStreaming (Helper Function)
StartStreaming (Implemented IBaseFilter Methods)
StartStreaming (Overridable Member Functions)
StartStreaming (CBaseRenderer)
StartStreaming (CTransformFilter)
StartStreaming (CVideoTransformFilter)
StartTime
StartX
StartY
State_Paused
State_Running
State_Stopped
StateChange Event
StgOpenStorage
StillOff
StillOff (IDvdControl)
Stop (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
Stop (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
Stop (CBaseRenderer Class: Helper Function)
Stop (CSourceStream Class: Implemented IPin Methods)
Stop (CTransformFilter Class: Implemented IBaseFilter Methods)
Stop (IAMovie Interface: Methods in Vtable Order)
Stop (IDistributorNotify Interface: Methods in Vtable Order)
Stop (IMediaControl Interface: Methods in Vtable Order)
Stop (IMediaFilter Interface: Methods in Vtable Order)
Stop (CBaseFilter)
Stop (CBaseMediaFilter)
Stop (CBaseRenderer)
Stop (CSourceStream)
Stop (CTransformFilter)
Stop (IAMovie)
Stop (IDistributorNotify)
Stop (IMediaControl)
Stop (IMediaFilter)
Stop Method
Stop Method (IMediaControl Object)
StopAt (Member Functions)
StopAt (Methods in Vtable Order)
StopAt (CBaseStreamControl)
StopAt (IAMStreamControl)
StopForResume
StopForResume (IDvdControl)
StopStreaming (Helper Function)
StopStreaming (Implemented IBaseFilter Methods)
StopStreaming (CBaseRenderer)
StopStreaming (CTransformFilter)
StopTime Property (IMediaPosition Object)
StopWhenReady
StopWhenReady (IMediaControl)
StopX
StopY
StoreAutoTune
StoreAutoTune (IAMTVTuner)
strConnectsToPin (AMOVIESETUP_PIN)
strConnectsToPin (REGFILTERPINS)
Stream Control Architecture
Stream Integer Functions
stream notification
stream time
STREAM_DISCARDING
STREAM_FLOWING
STREAM_STATE
STREAM_TIME
STREAM_TYPE
StreamControlState
STREAMSTATE_RUN
STREAMSTATE_STOP
StreamTime (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
StreamTime (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
StreamTime (CBaseFilter)
StreamTime (CBaseMediaFilter)
STREAMTYPE_READ
STREAMTYPE_TRANSFORM
STREAMTYPE_WRITE
StretchBlt
StretchDIBits
Stretching the Output of a Renderer Full-Screen
StretchTapsX
StretchTapsY
String Functions
StringFromResource
strName (AMOVIESETUP_FILTER)
strName (AMOVIESETUP_PIN)
strName (REGFILTERPINS)
Structures
SubpictureStreamChange
SubpictureStreamChange (IDvdControl)
subtype
Subtype (CMediaType)
subtype (media type)
Subtype Property (IMediaTypeInfo Object)
SUCCEEDED
SuggestAllocatorProperties
SuggestAllocatorProperties (IAMBufferNegotiation)
Summary
Summary of DirectShow COM Interfaces
Summary of Notifications
Supplying a Full-Screen Renderer Filter
SuspendThread
SuspendThread (CMsgThread)
sync source
Synchronization
SyncRead
SyncRead (IAsyncReader)
SyncReadAligned
SyncReadAligned (IAsyncReader)
Synth Sample (Audio Synthesizer Filter)
SysAllocString
SysFreeString


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

CDispParams Class
CDispParams::CDispParams
CDrawImage (CDrawImage)
CDrawImage Class
CDrawImage::CDrawImage
CDrawImage::DisplaySampleTimes
CDrawImage::DrawImage
CDrawImage::FastRender
CDrawImage::GetPaletteVersion
CDrawImage::GetSourceRect
CDrawImage::GetTargetRect
CDrawImage::IncrementPaletteVersion
CDrawImage::NotifyAllocator
CDrawImage::NotifyEndDraw
CDrawImage::NotifyMediaType
CDrawImage::NotifyStartDraw
CDrawImage::ResetPaletteVersion
CDrawImage::ScaleSourceRect
CDrawImage::SetDrawContext
CDrawImage::SetSourceRect
CDrawImage::SetStretchMode
CDrawImage::SetTargetRect
CDrawImage::SlowRender
CDrawImage::UpdateColourTable
CDrawImage::UsingImageAllocator
CEnumMediaTypes (CEnumMediaTypes)
CEnumMediaTypes Class
CEnumMediaTypes::AddRef
CEnumMediaTypes::CEnumMediaTypes
CEnumMediaTypes::Clone
CEnumMediaTypes::Next
CEnumMediaTypes::QueryInterface
CEnumMediaTypes::Release
CEnumMediaTypes::Reset
CEnumMediaTypes::Skip
CEnumPins (CEnumPins)
CEnumPins Class
CEnumPins::AddRef
CEnumPins::CEnumPins
CEnumPins::Clone
CEnumPins::Next
CEnumPins::QueryInterface
CEnumPins::Release
CEnumPins::Reset
CEnumPins::Skip
CFactoryTemplate Class
CFactoryTemplate::CreateInstance
CFactoryTemplate::IsClassID
CGenericList (CGenericList)
CGenericList Class
CGenericList::AddAfter
CGenericList::AddBefore
CGenericList::AddHead
CGenericList::AddTail
CGenericList::CGenericList
CGenericList::Find
CGenericList::Get
CGenericList::GetCount
CGenericList::GetHead
CGenericList::GetHeadPosition
CGenericList::GetNext
CGenericList::GetTailPosition
CGenericList::Remove
CGenericList::RemoveHead
CGenericList::RemoveTail
CGuidNameList Class
CGuidNameList::operator[ ]
ChangeRate (Implemented IMediaPosition Methods)
ChangeRate (Implemented INonDelegatingUnknown Methods)
ChangeRate (CSourcePosition)
ChangeRate (CSourceSeeking)
ChangeStart (Implemented IMediaPosition Methods)
ChangeStart (Implemented INonDelegatingUnknown Methods)
ChangeStart (CSourcePosition)
ChangeStart (CSourceSeeking)
ChangeStop (Implemented IMediaPosition Methods)
ChangeStop (Implemented INonDelegatingUnknown Methods)
ChangeStop (CSourcePosition)
ChangeStop (CSourceSeeking)
ChannelMinMax
ChannelMinMax (IAMTVTuner)
ChannelsGranularity
ChapterNum
ChapterPlay
ChapterPlay (IDvdControl)
ChapterPlayAutoStop
ChapterPlayAutoStop (IDvdControl)
ChapterSearch
ChapterSearch (IDvdControl)
Characteristics of a Reference Clock
Check
Check (CAMEvent)
CheckBitFields
CheckBitFields (CImageDisplay)
CheckCapabilities (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
CheckCapabilities (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
CheckCapabilities (Methods in Vtable Order)
CheckCapabilities (CPosPassThru)
CheckCapabilities (CSourceSeeking)
CheckCapabilities (IMediaSeeking)
CheckConnect (CBasePin Class: Implemented INonDelegatingUnknown Methods)
CheckConnect (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
CheckConnect (Implemented IBaseFilter Methods)
CheckConnect (Implemented IMemInputPin Methods)
CheckConnect (Implemented IPin Methods)
CheckConnect (CBaseOutputPin)
CheckConnect (CBasePin)
CheckConnect (CTransformFilter)
CheckConnect (CTransformInputPin)
CheckConnect (CTransformOutputPin)
CheckHeaderValidity
CheckHeaderValidity (CImageDisplay)
CheckInputType
CheckInputType (CTransformFilter)
CheckMediaType (CBasePin Class: Implemented INonDelegatingUnknown Methods)
CheckMediaType (CRendererInputPin Class: Implemented IPin Methods)
CheckMediaType (CSourceStream Class: Implemented IPin Methods)
CheckMediaType (CTransformInputPin Class: Implemented IMemInputPin Methods)
CheckMediaType (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
CheckMediaType (CTransInPlaceInputPin Class: Implemented IMemInputPin Methods)
CheckMediaType (CTransInPlaceOutputPin Class: Implemented IPin Methods)
CheckMediaType (Helper Function)
CheckMediaType (Member Functions)
CheckMediaType (CBasePin)
CheckMediaType (CBaseRenderer)
CheckMediaType (CImageDisplay)
CheckMediaType (CRendererInputPin)
CheckMediaType (CSourceStream)
CheckMediaType (CTransformInputPin)
CheckMediaType (CTransformOutputPin)
CheckMediaType (CTransInPlaceInputPin)
CheckMediaType (CTransInPlaceOutputPin)
CheckMemory
CheckMemory (IAMDevMemoryAllocator)
CheckPaletteHeader
CheckPaletteHeader (CImageDisplay)
CheckPointer
CheckReady
CheckReady (CBaseRenderer)
CheckRequest (Implemented IPin Methods)
CheckRequest (Member Functions)
CheckRequest (CAMThread)
CheckRequest (CSourceStream)
CheckSizes
CheckSizes (CImageAllocator)
CheckSourceRect
CheckSourceRect (CBaseControlVideo)
CheckStreaming (Implemented IMemInputPin Methods)
CheckStreaming (Implemented IQualityControl Methods)
CheckStreaming (CBaseInputPin)
CheckStreaming (CTransformInputPin)
CheckStreamState
CheckStreamState (CBaseStreamControl)
CheckTargetRect
CheckTargetRect (CBaseControlVideo)
CheckTime
CheckTime (CCmdQueue)
CheckTransform (Implemented IBaseFilter Methods)
CheckTransform (Overridable Member Functions)
CheckTransform (CTransformFilter)
CheckTransform (CTransInPlaceFilter)
CheckVideoType
CheckVideoType (CImageDisplay)
ChlgKey
chroma burst
CImageAllocator (CImageAllocator)
CImageAllocator Class
CImageAllocator::Alloc
CImageAllocator::CheckSizes
CImageAllocator::CImageAllocator
CImageAllocator::CreateDIB
CImageAllocator::CreateImageSample
CImageAllocator::Free
CImageAllocator::NonDelegatingAddRef
CImageAllocator::NonDelegatingRelease
CImageAllocator::NotifyMediaType
CImageAllocator::SetProperties
CImageDisplay (CImageDisplay)
CImageDisplay Class
CImageDisplay::CheckBitFields
CImageDisplay::CheckHeaderValidity
CImageDisplay::CheckMediaType
CImageDisplay::CheckPaletteHeader
CImageDisplay::CheckVideoType
CImageDisplay::CImageDisplay
CImageDisplay::CountPrefixBits
CImageDisplay::CountSetBits
CImageDisplay::GetBitMasks
CImageDisplay::GetColourMask
CImageDisplay::GetDisplayDepth
CImageDisplay::GetDisplayFormat
CImageDisplay::IsPalettized
CImageDisplay::RefreshDisplayType
CImageDisplay::UpdateFormat
CImagePalette (CImagePalette)
CImagePalette Class
CImagePalette::CImagePalette
CImagePalette::CopyPalette
CImagePalette::MakeIdentityPalette
CImagePalette::MakePalette
CImagePalette::PreparePalette
CImagePalette::RemovePalette
CImagePalette::ShouldUpdate
CImageSample (CImageSample)
CImageSample Class
CImageSample::CImageSample
CImageSample::GetDIBData
CImageSample::SetDIBData
cInstances
CK_INDEX
CK_NOCOLORKEY
CK_RGB
CL_ELEM_ALL
CL_ELEM_FIRST
CL_ELEM_FLAGS
CL_ELEM_LAST
CL_ELEM_NONE
CL_ELEM_NULL
CL_ELEM_STATUS
CL_FINISHED
CL_NOT_PLAYED
CL_PLAYING
CL_STATE_INVALID
CL_STATE_MASK
CL_WAIT_FOR_STATE
class factory
class factory template
Cleaning Up
ClearPendingSample
ClearPendingSample (CBaseRenderer)
ClientToScreen
clipper
CLoadDirectDraw (CLoadDirectDraw)
CLoadDirectDraw Class
CLoadDirectDraw::CLoadDirectDraw
CLoadDirectDraw::GetDirectDraw
CLoadDirectDraw::IsDirectDrawLoaded
CLoadDirectDraw::IsDirectDrawVersion1
CLoadDirectDraw::LoadDirectDraw
CLoadDirectDraw::ReleaseDirectDraw
Clock Base Classes
Clocks, DirectShow
Clone (CEnumMediaTypes Class: Implemented IEnumMediaTypes Methods)
Clone (CEnumPins Class: Implemented IEnumPins Methods)
Clone (IEnumFilters Interface: Methods in Vtable Order)
Clone (IEnumMediaTypes Interface: Methods in Vtable Order)
Clone (IEnumPins Interface: Methods in Vtable Order)
Clone (IEnumRegFilters Interface: Methods in Vtable Order)
Clone (CEnumMediaTypes)
Clone (CEnumPins)
Clone (IEnumFilters)
Clone (IEnumMediaTypes)
Clone (IEnumPins)
Clone (IEnumRegFilters)
Close
Close (CAMThread)
clsConnectsToFilter (AMOVIESETUP_PIN)
clsConnectsToFilter (REGFILTERPINS)
clsID (AMOVIESETUP_FILTER)
Clsid (REGFILTER)
CLSID_ACMWrapper
CLSID_ActiveMovieCategories
CLSID_AMovie
CLSID_AsyncReader
CLSID_AudioCompressorCategory
CLSID_AudioFileClip
CLSID_AudioInputDeviceCategory
CLSID_AudioProperties
CLSID_AudioRecord
CLSID_AudioRender
CLSID_AudioRendererCategory
CLSID_AVIDec
CLSID_AviDest
CLSID_AviDoc
CLSID_AVIMIDIRender
CLSID_AviMuxProptyPage
CLSID_AviMUXProptyPage1
CLSID_AviSplitter
CLSID_CAcmCoClassManager
CLSID_CaptureGraphBuilder
CLSID_CaptureProperties
CLSID_CIcmCoClassManager
CLSID_CMidiOutClassManager
CLSID_CMpegAudioCodec
CLSID_CMpegVideoCodec
CLSID_Colour
CLSID_CQzFilterClassManager
CLSID_CutListGraphBuilder
CLSID_CVidCapClassManager
CLSID_CWaveinClassManager
CLSID_CWaveOutClassManager
CLSID_Dither
CLSID_DSoundRender
CLSID_DVDecPropertiesPage
CLSID_DVDNavigator
CLSID_DVEncPropertiesPage
CLSID_DVMUX
CLSID_DVMuxPropertyPage
CLSID_DVSplitter
CLSID_DVVideoCodec
CLSID_DVVideoEnc
CLSID_FileWriter
CLSID_FilterGraph
CLSID_FilterMapper
CLSID_InfTee
CLSID_LegacyAmFilterCategory
CLSID_Line21Decoder
CLSID_MidiRendererCategory
CLSID_ModexProperties
CLSID_ModexRenderer
CLSID_MPEG1Splitter
CLSID_MTXRiffs (Cutlist CLSIDs)
CLSID_MTXRiffs (Filter and Filter Property Page CLSIDs)
CLSID_OverlayMixer
CLSID_PersistMonikerPID
CLSID_SeekingPassThru
CLSID_SimpleCutList
CLSID_SystemClock
CLSID_TextRender
CLSID_URLReader
CLSID_VfwCapture
CLSID_VideoCompressorCategory
CLSID_VideoFileClip
CLSID_VideoInputDeviceCategory
CLSID_VideoRenderer
clsMajorType (AMOVIESETUP_MEDIATYPE)
clsMajorType (REGPINTYPES)
clsMedium
clsMinorType (AMOVIESETUP_MEDIATYPE)
clsMinorType (REGPINTYPES)
clsPinCategory
CLText Sample (Text Cutlist Application)
CMediaControl (CMediaControl)
CMediaControl Class
CMediaControl::CMediaControl
CMediaControl::GetIDsOfNames
CMediaControl::GetTypeInfo
CMediaControl::GetTypeInfoCount
CMediaControl::Invoke
CMediaControl::NonDelegatingQueryInterface
CMediaEvent (CMediaEvent)
CMediaEvent Class
CMediaEvent::CMediaEvent
CMediaEvent::GetIDsOfNames
CMediaEvent::GetTypeInfo
CMediaEvent::GetTypeInfoCount
CMediaEvent::Invoke
CMediaEvent::NonDelegatingQueryInterface
CMediaPosition (CMediaPosition)
CMediaPosition Class

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

GetMediaTime (CPosPassThru)
GetMediaTime (CRendererPosPassThru)
GetMediaTime (IMediaSample)
GetMediaType (CBasePin Class: Implemented INonDelegatingUnknown Methods)
GetMediaType (CMediaSample Class: Implemented INonDelegatingUnknown Methods)
GetMediaType (CSourceStream Class: Implemented IPin Methods)
GetMediaType (CTransformFilter Class: Implemented IBaseFilter Methods)
GetMediaType (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
GetMediaType (CTransInPlaceFilter Class: Overridable Member Functions)
GetMediaType (IFileClip Interface: Methods in Vtable Order)
GetMediaType (IMediaSample Interface: Methods in Vtable Order)
GetMediaType (IStandardCutList Interface: Methods in Vtable Order)
GetMediaType (CBasePin)
GetMediaType (CMediaSample)
GetMediaType (CSourceStream)
GetMediaType (CTransformFilter)
GetMediaType (CTransformOutputPin)
GetMediaType (CTransInPlaceFilter)
GetMediaType (IFileClip)
GetMediaType (IMediaSample)
GetMediaType (IStandardCutList)
GetMediaTypeVersion
GetMediaTypeVersion (CBasePin)
GetMemoryHDC
GetMemoryHDC (CBaseWindow)
GetMessage
GetMessageDrain
GetMessageDrain (IFullScreenVideo)
GetMethod
GetMethod (CDeferredCommand)
GetMinIdealImageSize (CBaseControlWindow)
GetMinIdealImageSize (IVideoWindow)
GetMinIdealImageSize Method (IVideoWindow Object)
GetMode (IAMVideoControl)
GetMode (IFileSinkFilter2)
GetModeInfo (IFullScreenVideo)
GetMonitor (IFullScreenVideo)
GetMultiMediaStream
GetMultiMediaStream (IMediaStream)
GetNext (CGenericList)
GetNextAdviseTime
GetNextAdviseTime (CAMSchedule)
GetNextElement
GetNextElement (IStandardCutList)
GetNextI
GetNextI (CBaseList)
GetNotifyFlags
GetNotifyFlags (IMediaEventEx)
GetNumberOfCapabilities
GetNumberOfCapabilities (IAMStreamConfig)
GetNumberOfChapters
GetNumberOfChapters (IDvdInfo)
GetNumDropped
GetNumDropped (IAMDroppedFrames)
GetNumNotDropped
GetNumNotDropped (IAMDroppedFrames)
GetOpenFileName
GetOriginPosition
GetOriginPosition (IAMFileCutListElement)
GetOutputCompatibilityIndex
GetOutputCompatibilityIndex (IConfigAviMux)
GetOutputFormat (IAMLine21Decoder)
GetOverlaySurface (IVPBaseConfig)
GetOverlaySurfaceColorControls (IMixerPinConfig2)
GetOwner (CUnknown)
GetOwnerWindow
GetOwnerWindow (CBaseControlWindow)
GetPageInfo
GetPageInfo (CBasePropertyPage)
GetPalette
GetPalette (IOverlay)
GetPaletteVersion
GetPaletteVersion (CDrawImage)
GetParams
GetParams (CDeferredCommand)
GetPin (CSource Class: Implemented IBaseFilter Methods)
GetPin (CTransformFilter Class: Implemented IBaseFilter Methods)
GetPin (CTransInPlaceFilter Class: Overridable Member Functions)
GetPin (Helper Function)
GetPin (Implemented INonDelegatingUnknown Methods)
GetPin (CBaseFilter)
GetPin (CBaseRenderer)
GetPin (CSource)
GetPin (CTransformFilter)
GetPin (CTransInPlaceFilter)
GetPinCount (Helper Function)
GetPinCount (Implemented IBaseFilter Methods)
GetPinCount (Implemented INonDelegatingUnknown Methods)
GetPinCount (CBaseFilter)
GetPinCount (CBaseRenderer)
GetPinCount (CSource)
GetPinCount (CTransformFilter)
GetPinVersion
GetPinVersion (CBaseFilter)
GetPlayerParentalLevel
GetPlayerParentalLevel (IDvdInfo)
GetPointer (Implemented INonDelegatingUnknown Methods)
GetPointer (Methods in Vtable Order)
GetPointer (CMediaSample)
GetPointer (IMediaSample)
GetPositions (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetPositions (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetPositions (Methods in Vtable Order)
GetPositions (CPosPassThru)
GetPositions (CSourceSeeking)
GetPositions (IMediaSeeking)
GetPreroll (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetPreroll (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetPreroll (Methods in Vtable Order)
GetPreroll (CPosPassThru)
GetPreroll (CSourceSeeking)
GetPreroll (IMediaSeeking)
GetPreviousElement
GetPreviousElement (IStandardCutList)
GetPrimaryBufferInterface
GetPrimaryBufferInterface (IAMDirectSound)
GetPrivateTime
GetPrivateTime (CBaseReferenceClock)
GetProperties (CBaseAllocator Class: Implemented INonDelegatingUnknown Methods)
GetProperties (IMediaSample2 Interface: Methods in Vtable Order)
GetProperties (IMemAllocator Interface: Methods in Vtable Order)
GetProperties (CBaseAllocator)
GetProperties (IMediaSample2)
GetProperties (IMemAllocator)
GetQueueObject
GetQueueObject (CQueue)
GetRange
GetRange (IAMVideoProcAmp)
GetRate (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetRate (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetRate (Methods in Vtable Order)
GetRate (CPosPassThru)
GetRate (CSourceSeeking)
GetRate (IMediaSeeking)
GetReader
GetReader (CPullPin)
GetRealState
GetRealState (CBaseRenderer)
GetRedrawAlways
GetRedrawAlways (IAMLine21Decoder)
GetRelativePosition
GetRelativePosition (IMixerPinConfig)
GetRenderEvent
GetRenderEvent (CBaseRenderer)
GetRequest (Implemented IPin Methods)
GetRequest (Member Functions)
GetRequest (CAMThread)
GetRequest (CSourceStream)
GetRequestHandle
GetRequestHandle (CAMThread)
GetRequestParam
GetRequestParam (CAMThread)
GetRestorePosition (Implemented IVideoWindow Methods)
GetRestorePosition (Methods in Vtable Order)
GetRestorePosition (CBaseControlWindow)
GetRestorePosition (IVideoWindow)
GetRestorePosition Method (IVideoWindow Object)
GetResult
GetResult (CDeferredCommand)
GetRoot
GetRoot (IDvdInfo)
GetSampleSize
GetSampleSize (CMediaType)
GetSampleTimes (Helper Function)
GetSampleTimes (Methods in Vtable Order)
GetSampleTimes (CBaseRenderer)
GetSampleTimes (IStreamSample)
GetSchedule
GetSchedule (CBaseReferenceClock)
GetSecondaryBufferInterface
GetSecondaryBufferInterface (IAMDirectSound)
GetServiceState
GetServiceState (IAMLine21Decoder)
GetSetupData
GetSetupData (CBaseFilter)
GetSize (Implemented INonDelegatingUnknown Methods)
GetSize (Methods in Vtable Order)
GetSize (CMediaSample)
GetSize (IMediaSample)
GetSizeMax
GetSizeMax (CPersistStream)
GetSoftwareVersion
GetSoftwareVersion (CPersistStream)
GetSourcePosition (Implemented IBasicVideo Methods)
GetSourcePosition (Methods in Vtable Order)
GetSourcePosition (CBaseControlVideo)
GetSourcePosition (IBasicVideo)
GetSourcePosition Method (IBasicVideo Object)
GetSourceRect (Implemented IBasicVideo Methods)
GetSourceRect (Member Functions)
GetSourceRect (CBaseControlVideo)
GetSourceRect (CDrawImage)
GetState (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
GetState (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
GetState (CBaseRenderer Class: Helper Function)
GetState (IAMovie Interface: Methods in Vtable Order)
GetState (IAMVfwCompressDialogs Interface: Methods in Vtable Order)
GetState (IMediaControl Interface: Methods in Vtable Order)
GetState (IMediaFilter Interface: Methods in Vtable Order)
GetState (IMultiMediaStream Interface: Methods in Vtable Order)
GetState (CBaseFilter)
GetState (CBaseMediaFilter)
GetState (CBaseRenderer)
GetState (IAMovie)
GetState (IAMVfwCompressDialogs)
GetState (IMediaControl)
GetState (IMediaFilter)
GetState (IMultiMediaStream)
GetState Method (IMediaControl Object)
GetStaticImage
GetStaticImage (CBaseControlVideo)
GetStatus
GetStatus (IAMExtTransport)
GetStdDev
GetStdDev (CBaseVideoRenderer)
GetStopPosition (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetStopPosition (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetStopPosition (Methods in Vtable Order)
GetStopPosition (CPosPassThru)
GetStopPosition (CSourceSeeking)
GetStopPosition (IMediaSeeking)
GetStreamCaps
GetStreamCaps (IAMStreamConfig)
GetStreamIndex (IAMAudioCutListElement Interface: Methods in Vtable Order)
GetStreamIndex (IAMVideoCutListElement Interface: Methods in Vtable Order)
GetStreamIndex (IAMAudioCutListElement)
GetStreamIndex (IAMVideoCutListElement)
GetStreamTransparent
GetStreamTransparent (IMixerPinConfig)
GetSubpictureLanguage
GetSubpictureLanguage (IDvdInfo)
GetSubtypeName
GetSurface
GetSurface (IDirectDrawStreamSample)
GetSurfaceDesc
GetSurfaceDesc (IDirectDrawVideo)
GetSurfaceFromDC
GetSurfaceFromDC (IDirectDraw3)
GetSurfaceType
GetSurfaceType (IDirectDrawVideo)
GetSwitches
GetSwitches (IDirectDrawVideo)
GetSyncSource (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
GetSyncSource (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
GetSyncSource (Methods in Vtable Order)
GetSyncSource (CBaseFilter)
GetSyncSource (CBaseMediaFilter)
GetSyncSource (IMediaFilter)
GetSystemPaletteEntries
GetTailPosition
GetTailPosition (CGenericList)
GetTailPositionI
GetTailPositionI (CBaseList)
GetTargetRect (Implemented IBasicVideo Methods)
GetTargetRect (Member Functions)
GetTargetRect (CBaseControlVideo)
GetTargetRect (CDrawImage)
GetTCDisplay
GetTCDisplay (IAMTimecodeDisplay)
GetTCDisplayEnable
GetTCDisplayEnable (IAMTimecodeDisplay)
GetTCGMode
GetTCGMode (IAMTimecodeGenerator)
GetTCRMode
GetTCRMode (IAMTimecodeReader)
GetThreadHandle
GetThreadHandle (CMsgThread)
GetThreadID
GetThreadID (CMsgThread)
GetThreadMsg
GetThreadMsg (CMsgThread)
GetThreadPriority
GetThreadPriority (CMsgThread)
GetTime (CBaseReferenceClock Class: Implemented INonDelegatingUnknown Methods)
GetTime (CDeferredCommand Class: Implemented INonDelegatingUnknown Methods)
GetTime (CMediaSample Class: Implemented INonDelegatingUnknown Methods)
GetTime (IMediaSample Interface: Methods in Vtable Order)
GetTime (IMultiMediaStream Interface: Methods in Vtable Order)
GetTime (IReferenceClock Interface: Methods in Vtable Order)
GetTime (CBaseReferenceClock)
GetTime (CDeferredCommand)
GetTime (CMediaSample)
GetTime (IMediaSample)
GetTime (IMultiMediaStream)
GetTime (IReferenceClock)
GetTimecode (IAMTimecodeGenerator Interface: Methods in Vtable Order)
GetTimecode (IAMTimecodeReader Interface: Methods in Vtable Order)
GetTimecode (IAMTimecodeGenerator)
GetTimecode (IAMTimecodeReader)
GetTimeFormat (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
GetTimeFormat (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
GetTimeFormat (Methods in Vtable Order)
GetTimeFormat (CPosPassThru)
GetTimeFormat (CSourceSeeking)
GetTimeFormat (IMediaSeeking)
GetTimePerFrame
GetTimePerFrame (IDirectDrawMediaStream)
Getting and Setting the Rate
Getting and Setting the Start Position
GetTitleAttributes
GetTitleAttributes (IDvdInfo)
GetTitleParentalLevels
GetTitleParentalLevels (IDvdInfo)
GetTotalTitleTime
GetTotalTitleTime (IDvdInfo)
GetTransportAudioParameters
GetTransportAudioParameters (IAMExtTransport)
GetTransportBasicParameters
GetTransportBasicParameters (IAMExtTransport)
GetTransportVideoParameters
GetTransportVideoParameters (IAMExtTransport)
GetTrimInPosition
GetTrimInPosition (IAMFileCutListElement)
GetTrimLength
GetTrimLength (IAMFileCutListElement)
GetTrimOutPosition
GetTrimOutPosition (IAMFileCutListElement)
GetTrueColorType

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

IMediaSample::SetActualDataLength
IMediaSample::SetDiscontinuity
IMediaSample::SetMediaTime
IMediaSample::SetMediaType
IMediaSample::SetPreroll
IMediaSample::SetSyncPoint
IMediaSample::SetTime
IMediaSample2 Interface
IMediaSample2::GetProperties
IMediaSample2::SetProperties
IMediaSeeking Interface
IMediaSeeking::CheckCapabilities
IMediaSeeking::ConvertTimeFormat
IMediaSeeking::GetAvailable
IMediaSeeking::GetCapabilities
IMediaSeeking::GetCurrentPosition
IMediaSeeking::GetDuration
IMediaSeeking::GetPositions
IMediaSeeking::GetPreroll
IMediaSeeking::GetRate
IMediaSeeking::GetStopPosition
IMediaSeeking::GetTimeFormat
IMediaSeeking::IsFormatSupported
IMediaSeeking::IsUsingTimeFormat
IMediaSeeking::QueryPreferredFormat
IMediaSeeking::SetPositions
IMediaSeeking::SetRate
IMediaSeeking::SetTimeFormat
IMediaStream Interface
IMediaStream::AllocateSample
IMediaStream::CreateSharedSample
IMediaStream::GetInformation
IMediaStream::GetMultiMediaStream
IMediaStream::SendEndOfStream
IMediaStream::SetSameFormat
IMediaTypeInfo Interface
IMediaTypeInfo Object
IMediaTypeInfo::get_Subtype
IMediaTypeInfo::get_Type
IMemAllocator Interface
IMemAllocator::Commit
IMemAllocator::Decommit
IMemAllocator::GetBuffer
IMemAllocator::GetProperties
IMemAllocator::ReleaseBuffer
IMemAllocator::SetProperties
IMemInputPin Interface
IMemInputPin::GetAllocator
IMemInputPin::GetAllocatorRequirements
IMemInputPin::NotifyAllocator
IMemInputPin::Receive
IMemInputPin::ReceiveCanBlock
IMemInputPin::ReceiveMultiple
IMemoryData Interface
IMemoryData::GetInfo
IMemoryData::SetActual
IMemoryData::SetBuffer
IMixerPinConfig Interface
IMixerPinConfig::GetAspectRatioMode
IMixerPinConfig::GetBlendingParameter
IMixerPinConfig::GetColorKey
IMixerPinConfig::GetRelativePosition
IMixerPinConfig::GetStreamTransparent
IMixerPinConfig::GetZOrder
IMixerPinConfig::SetAspectRatioMode
IMixerPinConfig::SetBlendingParameter
IMixerPinConfig::SetColorKey
IMixerPinConfig::SetRelativePosition
IMixerPinConfig::SetStreamTransparent
IMixerPinConfig::SetZOrder
IMixerPinConfig2 Interface
IMixerPinConfig2::GetOverlaySurfaceColorControls
IMixerPinConfig2::SetOverlaySurfaceColorControls
IMoniker
IMoniker::BindToObject
IMoniker::BindToStorage
Implementing Dual Interfaces
Implementing Self-Registration
Implementing the Class Factory
Implications of Full-Screen Support for the Application
Improving Capture Performance
IMultiMediaStream Interface
IMultiMediaStream::EnumMediaStreams
IMultiMediaStream::GetDuration
IMultiMediaStream::GetEndOfStreamEventHandle
IMultiMediaStream::GetInformation
IMultiMediaStream::GetMediaStream
IMultiMediaStream::GetState
IMultiMediaStream::GetTime
IMultiMediaStream::Seek
IMultiMediaStream::SetState
InactivateWindow
InactivateWindow (CBaseWindow)
Inactive (CBaseOutputPin Class: Implemented IPin Methods)
Inactive (CRendererInputPin Class: Implemented IPin Methods)
Inactive (Helper Function)
Inactive (Implemented INonDelegatingUnknown Methods)
Inactive (Implemented IQualityControl Methods)
Inactive (Overridable Member Functions)
Inactive (CBaseInputPin)
Inactive (CBaseOutputPin)
Inactive (CBasePin)
Inactive (CBaseRenderer)
Inactive (CPullPin)
Inactive (CRendererInputPin)
Inactive (CSourceStream)
IncrementPaletteVersion
IncrementPaletteVersion (CDrawImage)
IncrementPinVersion
IncrementPinVersion (CBaseFilter)
IncrementTypeVersion
IncrementTypeVersion (CBasePin)
Indeo 4.3 Video Compression
Indeo 4.3 Video Decompression
Indeo 5.0 Audio Decompression
Indeo 5.0 Video Compression
Indeo 5.0 Video Decompression
Indeo 5.0 Video Progressive Download Sources
Infinite Pin Tee filter
Info
Info (IAMStreamSelect)
InformVPInputFormats
InformVPInputFormats (IVPBaseConfig)
Inftee Sample (Infinite-Pin Tee Filter)
Init
Init (CSourceStream)
Init (ISeekingPassThru)
InitAllocator
InitAllocator (CBaseOutputPin)
InitialiseWindow
InitialiseWindow (CBaseWindow)
Initialize (IAMMediaStream Interface: Methods in Vtable Order)
Initialize (IAMMultiMediaStream Interface: Methods in Vtable Order)
Initialize (IAMMediaStream)
Initialize (IAMMultiMediaStream)
InitializeCriticalSection
Initializing the Filter Graph Manager and the Filter Graph
InitialThreadProc (CAMThread Class: Member Functions)
InitialThreadProc (COutputQueue Class: Member Functions)
InitialThreadProc (CAMThread)
InitialThreadProc (COutputQueue)
InitMediaType
InitMediaType (CMediaType)
INonDelegatingUnknown
INonDelegatingUnknown Interface
INonDelegatingUnknown::NonDelegatingAddRef
INonDelegatingUnknown::NonDelegatingQueryInterface
INonDelegatingUnknown::NonDelegatingRelease
input pin
InputPin
InputPin (CTransInPlaceFilter)
InputSize
Insert
Insert (CCmdQueue)
Installing and Registering Quartz.dll
Installing the Files
Instantiate the Filter
Instantiating the Filter Graph
Instantiating the Filter Graph Manager
Int64x32Div32
Interfaces on a Typical Filter Graph
Interfaces that Access the Filter Graph Manager
interlace
INTERLEAVE_CAPTURE
INTERLEAVE_FULL
INTERLEAVE_NONE
interleaving
InterleavingMode
Internal Script Command Renderer
Introducing the CTransformFilter and CTransInPlaceFilter Classes
Introducing the DirectShow COM Interfaces
Introduction to ICaptureGraphBuilder
Introduction to the DirectShow C++ Class Library
IntToWstr
iNumStreams
iNumStreamsFailed
Invoke (CBaseBasicVideo Class: Implemented IDispatch Methods)
Invoke (CBaseVideoWindow Class: Implemented IDispatch Methods)
Invoke (CBasicAudio Class: Implemented IDispatch Methods)
Invoke (CDeferredCommand Class: Implemented INonDelegatingUnknown Methods)
Invoke (CMediaControl Class: Implemented IDispatch Methods)
Invoke (CMediaEvent Class: Implemented IDispatch Methods)
Invoke (CMediaPosition Class: Implemented IDispatch Methods)
Invoke (CBaseBasicVideo)
Invoke (CBaseVideoWindow)
Invoke (CBasicAudio)
Invoke (CDeferredCommand)
Invoke (CMediaControl)
Invoke (CMediaEvent)
Invoke (CMediaPosition)
InvokeAtPresentationTime
InvokeAtPresentationTime (IQueueCommand)
InvokeAtStreamTime
InvokeAtStreamTime (IQueueCommand)
Invoking Methods on the Interfaces
InWindow Sample (Window Playback Application)
IOStream Sample Code
IOverlay Interface
IOverlay::Advise
IOverlay::GetClipList
IOverlay::GetColorKey
IOverlay::GetDefaultColorKey
IOverlay::GetPalette
IOverlay::GetVideoPosition
IOverlay::GetWindowHandle
IOverlay::SetColorKey
IOverlay::SetPalette
IOverlay::Unadvise
IOverlayNotify Interface
IOverlayNotify::OnClipChange
IOverlayNotify::OnColorKeyChange
IOverlayNotify::OnPaletteChange
IOverlayNotify::OnPositionChange
IPersist
IPersistFile
IPersistMediaPropertyBag
IPersistPropertyBag
IPersistPropertyBag::Load
IPersistStream
IPersistStream::GetSizeMax
IPersistStream::IsDirty
IPersistStream::Load
IPersistStream::Save
IPin Interface
IPin::BeginFlush
IPin::Connect
IPin::ConnectedTo
IPin::ConnectionMediaType
IPin::Disconnect
IPin::EndFlush
IPin::EndOfStream
IPin::EnumMediaTypes
IPin::NewSegment
IPin::QueryAccept
IPin::QueryDirection
IPin::QueryId
IPin::QueryInternalConnections
IPin::QueryPinInfo
IPin::ReceiveConnection
IPinInfo Interface
IPinInfo Object
IPinInfo::Connect
IPinInfo::ConnectDirect
IPinInfo::ConnectWithType
IPinInfo::Disconnect
IPinInfo::get_ConnectedTo
IPinInfo::get_ConnectionMediaType
IPinInfo::get_Direction
IPinInfo::get_FilterInfo
IPinInfo::get_MediaTypes
IPinInfo::get_Name
IPinInfo::get_Pin
IPinInfo::get_PinID
IPinInfo::Render
IPlay Sample (Indeo Player Application)
IPropertyBag
IPropertyPage
IPropertyPage::Active
IPropertyPage::Apply
IPropertyPage::Deactivate
IPropertyPage::GetPageInfo
IPropertyPage::Help
IPropertyPage::IsPageDirty
IPropertyPage::Move
IPropertyPage::SetObjects
IPropertyPage::SetPageSite
IPropertyPage::Show
IPropertyPage::TranslateAccelerator
IPropertyPageSite
IQualityControl Interface
IQualityControl::Notify
IQualityControl::SetSink
IQualProp Interface
IQualProp::get_AvgFrameRate
IQualProp::get_AvgSyncOffset
IQualProp::get_DevSyncOffset
IQualProp::get_FramesDrawn
IQualProp::get_FramesDroppedInRenderer
IQualProp::get_Jitter
IQueueCommand Interface
IQueueCommand::InvokeAtPresentationTime
IQueueCommand::InvokeAtStreamTime
IReferenceClock Interface
IReferenceClock::AdvisePeriodic
IReferenceClock::AdviseTime
IReferenceClock::GetTime
IReferenceClock::Unadvise
IRegFilterInfo Interface
IRegFilterInfo Object
IRegFilterInfo::Filter
IRegFilterInfo::get_Name
IResourceConsumer Interface
IResourceConsumer::AcquireResource
IResourceConsumer::ReleaseResource
IResourceManager Interface
IResourceManager::CancelRequest
IResourceManager::NotifyAcquire
IResourceManager::NotifyRelease
IResourceManager::Register
IResourceManager::RegisterGroup
IResourceManager::ReleaseFocus
IResourceManager::RequestResource
IResourceManager::SetFocus
IsActive (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
IsActive (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
IsActive (CBaseFilter)
IsActive (CBaseMediaFilter)
IsAutoShowEnabled
IsAutoShowEnabled (CBaseControlWindow)
IsBadReadPtr
IsClassID
IsClassID (CFactoryTemplate)
IsConnected
IsConnected (CBasePin)
IsCursorHidden (Implemented IVideoWindow Methods)
IsCursorHidden (Methods in Vtable Order)
IsCursorHidden (CBaseControlWindow)
IsCursorHidden (IVideoWindow)
IsCursorHidden Method (IVideoWindow Object)
IsDefaultSourceRect
IsDefaultSourceRect (CBaseControlVideo)
IsDefaultTargetRect
IsDefaultTargetRect (CBaseControlVideo)
IsDirectDrawLoaded
IsDirectDrawLoaded (CLoadDirectDraw)
IsDirectDrawVersion1
IsDirectDrawVersion1 (CLoadDirectDraw)
IsDirty
IsDirty (CPersistStream)
IsDiscontinuity (Implemented INonDelegatingUnknown Methods)
IsDiscontinuity (Methods in Vtable Order)
IsDiscontinuity (CMediaSample)
IsDiscontinuity (IMediaSample)
ISeekingPassThru Interface
ISeekingPassThru::Init
IsEndOfStream
IsEndOfStream (CBaseRenderer)
IsEndOfStreamDelivered
IsEndOfStreamDelivered (CBaseRenderer)
IsEqualObject
IsFileSource Property (IFilterInfo Object)
IsFirstElement
IsFirstElement (IAMCutListElement)
IsFixedSize
IsFixedSize (CMediaType)
IsFlushing
IsFlushing (CBaseInputPin)
IsFormatSupported (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
IsFormatSupported (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
IsFormatSupported (Methods in Vtable Order)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

CMediaPosition::CMediaPosition
CMediaPosition::GetIDsOfNames
CMediaPosition::GetTypeInfo
CMediaPosition::GetTypeInfoCount
CMediaPosition::Invoke
CMediaPosition::NonDelegatingQueryInterface
CMediaSample (CMediaSample)
CMediaSample Class
CMediaSample::AddRef
CMediaSample::CMediaSample
CMediaSample::GetActualDataLength
CMediaSample::GetMediaTime
CMediaSample::GetMediaType
CMediaSample::GetPointer
CMediaSample::GetSize
CMediaSample::GetTime
CMediaSample::IsDiscontinuity
CMediaSample::IsPreroll
CMediaSample::IsSyncPoint
CMediaSample::NonDelegatingQueryInterface
CMediaSample::QueryInterface
CMediaSample::Release
CMediaSample::SetActualDataLength
CMediaSample::SetDiscontinuity
CMediaSample::SetMediaTime
CMediaSample::SetMediaType
CMediaSample::SetPointer
CMediaSample::SetPreroll
CMediaSample::SetSyncPoint
CMediaSample::SetTime
CMediaType (CMediaType)
CMediaType Class
CMediaType::AllocFormatBuffer
CMediaType::CMediaType
CMediaType::Format
CMediaType::FormatLength
CMediaType::FormatType
CMediaType::GetSampleSize
CMediaType::InitMediaType
CMediaType::IsFixedSize
CMediaType::IsPartiallySpecified
CMediaType::IsTemporalCompressed
CMediaType::IsValid
CMediaType::MatchesPartial
CMediaType::operator !=
CMediaType::operator =
CMediaType::operator ==
CMediaType::ReallocFormatBuffer
CMediaType::ResetFormatBuffer
CMediaType::SetFormat
CMediaType::SetFormatType
CMediaType::SetSampleSize
CMediaType::SetSubtype
CMediaType::SetTemporalCompression
CMediaType::SetType
CMediaType::SetVariableSize
CMediaType::Subtype
CMediaType::Type
CMemAllocator (CMemAllocator)
CMemAllocator Class
CMemAllocator::Alloc
CMemAllocator::CMemAllocator
CMemAllocator::CreateInstance
CMemAllocator::Free
CMemAllocator::ReallyFree
CMemAllocator::SetProperties
CMsg (CMsg)
CMsg Class
CMsg::CMsg
CMsgThread (CMsgThread)
CMsgThread Class
CMsgThread::CMsgThread
CMsgThread::CreateThread
CMsgThread::GetThreadHandle
CMsgThread::GetThreadID
CMsgThread::GetThreadMsg
CMsgThread::GetThreadPriority
CMsgThread::OnThreadInit
CMsgThread::PutThreadMsg
CMsgThread::ResumeThread
CMsgThread::SetThreadPriority
CMsgThread::SuspendThread
CMsgThread::ThreadMessageProc
CMsgThread::WaitForThreadExit
COARefTime (COARefTime)
COARefTime Class
COARefTime::COARefTime
COARefTime::double
COARefTime::Operator !=
COARefTime::Operator –
COARefTime::Operator –=
COARefTime::Operator >
COARefTime::Operator >=
COARefTime::Operator <
COARefTime::Operator <=
COARefTime::Operator *
COARefTime::Operator /
COARefTime::Operator +
COARefTime::Operator +=
COARefTime::Operator =
COARefTime::Operator ==
CoCreateInstance
codec
CoGetClassObject
CoInitialize
ColCon
Color Space Converter
COLORKEY
COLORREF
COLORS
COM Classes
COM Objects in DirectShow
COM Overview
Commit (Implemented INonDelegatingUnknown Methods)
Commit (Methods in Vtable Order)
Commit (CBaseAllocator)
Commit (IMemAllocator)
CompleteConnect (CBaseOutputPin Class: Implemented IPin Methods)
CompleteConnect (CBasePin Class: Implemented INonDelegatingUnknown Methods)
CompleteConnect (CRendererInputPin Class: Implemented IPin Methods)
CompleteConnect (CTransformFilter Class: Implemented IBaseFilter Methods)
CompleteConnect (CTransformInputPin Class: Implemented IMemInputPin Methods)
CompleteConnect (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
CompleteConnect (CTransInPlaceFilter Class: Overridable Member Functions)
CompleteConnect (Helper Function)
CompleteConnect (CBaseOutputPin)
CompleteConnect (CBasePin)
CompleteConnect (CBaseRenderer)
CompleteConnect (CRendererInputPin)
CompleteConnect (CTransformFilter)
CompleteConnect (CTransformInputPin)
CompleteConnect (CTransformOutputPin)
CompleteConnect (CTransInPlaceFilter)
CompleteStateChange
CompleteStateChange (CBaseRenderer)
CompletionStatus
CompletionStatus (IStreamSample)
compression filter
Compression Filters:About
Compression Filters:How to Write
CompressionCaps
CompressionCaps_CanBFrame
CompressionCaps_CanCrunch
CompressionCaps_CanKeyFrame
CompressionCaps_CanQuality
CompressionCaps_CanWindow
Confidence (Implemented INonDelegatingUnknown Methods)
Confidence (Methods in Vtable Order)
Confidence (CDeferredCommand)
Confidence (IDeferredCommand)
Connect (CBasePin Class: Implemented INonDelegatingUnknown Methods)
Connect (CPullPin Class: Overridable Member Functions)
Connect (IAMovie Interface: Methods in Vtable Order)
Connect (IGraphBuilder Interface: Methods in Vtable Order)
Connect (IPin Interface: Methods in Vtable Order)
Connect (IPinInfo Interface: Methods in Vtable Order)
Connect (CBasePin)
Connect (CPullPin)
Connect (IAMovie)
Connect (IGraphBuilder)
Connect (IPin)
Connect (IPinInfo)
Connect Method (IPinInfo Object)
ConnectDirect (IFilterGraph Interface: Methods in Vtable Order)
ConnectDirect (IPinInfo Interface: Methods in Vtable Order)
ConnectDirect (IFilterGraph)
ConnectDirect (IPinInfo)
ConnectDirect Method (IPinInfo Object)
ConnectedIMemInputPin
ConnectedIMemInputPin (CTransInPlaceOutputPin)
ConnectedTo (Implemented INonDelegatingUnknown Methods)
ConnectedTo (Methods in Vtable Order)
ConnectedTo (CBasePin)
ConnectedTo (IPin)
ConnectedTo Property (IPinInfo Object)
Connecting Filter Graphs: An Example
Connecting Filter Pins
Connecting Transform Filters
Connection Model
Connection Process
ConnectionMediaType (Implemented INonDelegatingUnknown Methods)
ConnectionMediaType (Methods in Vtable Order)
ConnectionMediaType (CBasePin)
ConnectionMediaType (IPin)
ConnectionMediaType Property (IPinInfo Object)
ConnectWithType
ConnectWithType (IPinInfo)
ConnectWithType Method (IPinInfo Object)
Constructing Filter Graphs Using Visual Basic
ContainsPalette
Contrast Sample (Video Contrast Filter)
Control Distributors
Control Information Data
Control Interfaces
Control the Video Playback Window from C++
Controlling Audio
Controlling Filter Graphs Using C
Controlling Filter Graphs Using Visual Basic
Controlling the Capture Filter Graph
Controlling VCRs (External Device Control)
Controlling VCRs (Introduction)
ControlStream
ControlStream (ICaptureGraphBuilder)
Conversion Functions
ConvertTimeFormat (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
ConvertTimeFormat (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
ConvertTimeFormat (Methods in Vtable Order)
ConvertTimeFormat (CPosPassThru)
ConvertTimeFormat (CSourceSeeking)
ConvertTimeFormat (IMediaSeeking)
ConvertToMilliseconds
cooperative level
Copy
Copy (CTransInPlaceFilter)
CopyCaptureFile
CopyCaptureFile (ICaptureGraphBuilder)
CopyImage
CopyImage (CBaseControlVideo)
CopyMediaType
CopyPalette
CopyPalette (CImagePalette)
CoTaskMemAlloc
CoTaskMemFree
Count
Count (IAMStreamSelect)
Count Property (IAMCollection Object)
CountModes
CountModes (IFullScreenVideo)
CountPrefixBits
CountPrefixBits (CImageDisplay)
CountSetBits
CountSetBits (CImageDisplay)
cout
COutputQueue (COutputQueue)
COutputQueue Class
COutputQueue::BeginFlush
COutputQueue::COutputQueue
COutputQueue::EndFlush
COutputQueue::EOS
COutputQueue::FreeSamples
COutputQueue::InitialThreadProc
COutputQueue::IsIdle
COutputQueue::IsQueued
COutputQueue::IsSpecialSample
COutputQueue::NewSegment
COutputQueue::NotifyThread
COutputQueue::QueueSample
COutputQueue::Receive
COutputQueue::ReceiveMultiple
COutputQueue::Reset
COutputQueue::SendAnyway
COutputQueue::ThreadProc
CPersistStream (CPersistStream)
CPersistStream Class
CPersistStream::CPersistStream
CPersistStream::GetClassID
CPersistStream::GetSizeMax
CPersistStream::GetSoftwareVersion
CPersistStream::IsDirty
CPersistStream::Load
CPersistStream::ReadFromStream
CPersistStream::Save
CPersistStream::SetDirty
CPersistStream::SizeMax
CPersistStream::WriteToStream
cPins
cPins2
CPlay Sample (C/COM-based Media Player Application)
CPlay Sample Application
CPlay Tutorial
CPosPassThru (CPosPassThru)
CPosPassThru Class
CPosPassThru Helper Function
CPosPassThru::CanSeekBackward
CPosPassThru::CanSeekForward
CPosPassThru::CheckCapabilities
CPosPassThru::ConvertTimeFormat
CPosPassThru::CPosPassThru
CPosPassThru::ForceRefresh
CPosPassThru::get_CurrentPosition
CPosPassThru::get_Duration
CPosPassThru::get_PrerollTime
CPosPassThru::get_Rate
CPosPassThru::get_StopTime
CPosPassThru::GetAvailable
CPosPassThru::GetCapabilities
CPosPassThru::GetCurrentPosition
CPosPassThru::GetDuration
CPosPassThru::GetMediaTime
CPosPassThru::GetPositions
CPosPassThru::GetPreroll
CPosPassThru::GetRate
CPosPassThru::GetStopPosition
CPosPassThru::GetTimeFormat
CPosPassThru::IsFormatSupported
CPosPassThru::IsUsingTimeFormat
CPosPassThru::NonDelegatingQueryInterface
CPosPassThru::put_CurrentPosition
CPosPassThru::put_PrerollTime
CPosPassThru::put_Rate
CPosPassThru::put_StopTime
CPosPassThru::QueryPreferredFormat
CPosPassThru::SetPositions
CPosPassThru::SetRate
CPosPassThru::SetTimeFormat
CPullPin (CPullPin)
CPullPin Class
CPullPin::Active
CPullPin::AlignDown
CPullPin::AlignUp
CPullPin::BeginFlush
CPullPin::Connect
CPullPin::CPullPin
CPullPin::DecideAllocator
CPullPin::Disconnect
CPullPin::Duration
CPullPin::EndFlush
CPullPin::EndOfStream
CPullPin::GetReader
CPullPin::Inactive
CPullPin::OnError
CPullPin::Receive
CPullPin::Seek
CQueue (CQueue)
CQueue Class
CQueue::CQueue
CQueue::GetQueueObject
CQueue::PutQueueObject
Create
Create (CAMThread)
CreateAudioMediaType
CreateCategory
CreateCategory (IFilterMapper2)
CreateClassEnumerator
CreateClassEnumerator (ICreateDevEnum)
CreateCut
CreateCut (IFileClip)
CreateDIB
CreateDIB (CImageAllocator)
CreateDIBSection
CreateDirectDraw
CreateDirectDraw (IDirectDrawFactory)
CreateEvent
CreateFile
CreateImageSample
CreateImageSample (CImageAllocator)
CreateInstance (Implemented IMemAllocator Methods)
CreateInstance (Implemented INonDelegatingUnknown Methods)
CreateInstance (Member Functions)
CreateInstance (CFactoryTemplate)
CreateInstance (CMemAllocator)
CreateInstance (CSystemClock)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

GetTypeInfo (CBaseBasicVideo)
GetTypeInfo (CBaseDispatch)
GetTypeInfo (CBaseVideoWindow)
GetTypeInfo (CBasicAudio)
GetTypeInfo (CMediaControl)
GetTypeInfo (CMediaEvent)
GetTypeInfo (CMediaPosition)
GetTypeInfoCount (CBaseBasicVideo Class: Implemented IDispatch Methods)
GetTypeInfoCount (CBaseDispatch Class: Implemented IDispatch Methods)
GetTypeInfoCount (CBaseVideoWindow Class: Implemented IDispatch Methods)
GetTypeInfoCount (CBasicAudio Class: Implemented IDispatch Methods)
GetTypeInfoCount (CMediaControl Class: Implemented IDispatch Methods)
GetTypeInfoCount (CMediaEvent Class: Implemented IDispatch Methods)
GetTypeInfoCount (CMediaPosition Class: Implemented IDispatch Methods)
GetTypeInfoCount (CBaseBasicVideo)
GetTypeInfoCount (CBaseDispatch)
GetTypeInfoCount (CBaseVideoWindow)
GetTypeInfoCount (CBasicAudio)
GetTypeInfoCount (CMediaControl)
GetTypeInfoCount (CMediaEvent)
GetTypeInfoCount (CMediaPosition)
GetUnits (CRefTime)
GetVideoFormat (CBaseControlVideo)
GetVideoFormats (IVPBaseConfig)
GetVideoPaletteEntries (CBaseControlVideo)
GetVideoPaletteEntries (IBasicVideo)
GetVideoPaletteEntries Method (IBasicVideo Object)
GetVideoPosition (IOverlay)
GetVideoSize (CBaseControlVideo)
GetVideoSize (IBasicVideo)
GetVideoSize Method (IBasicVideo Object)
GetVMGAttributes (IDvdInfo)
GetVPDataInfo (IVPBaseConfig)
GetVPSyncMaster (IVPNotify2)
GetWindowFocus (IAMDirectSound)
GetWindowHandle (IOverlay)
GetWindowHDC (CBaseWindow)
GetWindowHeight (CBaseWindow)
GetWindowHWND (CBaseWindow)
GetWindowLong
GetWindowPosition (CBaseControlWindow)
GetWindowPosition (IVideoWindow)
GetWindowPosition Method (IVideoWindow Object)
GetWindowWidth
GetWindowWidth (CBaseWindow)
GetZOrder
GetZOrder (IMixerPinConfig)
GoUp
GoUp (IDvdControl)
Graph-Level Interfaces
GUID
guid (AUDIO_STREAM_CONFIG_CAPS)
guid (VIDEO_STREAM_CONFIG_CAPS)
GuidNames


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

IsFormatSupported (CPosPassThru)
IsFormatSupported (CSourceSeeking)
IsFormatSupported (IMediaSeeking)
IsHideOnDeactivate
IsHideOnDeactivate (IFullScreenVideo)
IsIdle
IsIdle (COutputQueue)
IsLastElement
IsLastElement (IAMCutListElement)
IsModeAvailable
IsModeAvailable (IFullScreenVideo)
IsModeEnabled
IsModeEnabled (IFullScreenVideo)
IsNull
IsNull (IAMCutListElement)
IsPageDirty
IsPageDirty (CBasePropertyPage)
IsPalettized
IsPalettized (CImageDisplay)
IsPartiallySpecified
IsPartiallySpecified (CMediaType)
ISpecifyPropertyPages
ISpecifyPropertyPages::GetPages
IsPreroll (Implemented INonDelegatingUnknown Methods)
IsPreroll (Methods in Vtable Order)
IsPreroll (CMediaSample)
IsPreroll (IMediaSample)
IsQueued
IsQueued (COutputQueue)
IsReadOnly
IsReadOnly (CBaseInputPin)
IsSingleFrame
IsSingleFrame (IAMVideoCutListElement)
IsSoundCardEnabled Method
IsSpecialSample
IsSpecialSample (COutputQueue)
IsStopped
IsStopped (CBasePin)
IsStreaming
IsStreaming (CBaseRenderer)
IsStreamTime
IsStreamTime (CDeferredCommand)
IsSyncPoint (Implemented INonDelegatingUnknown Methods)
IsSyncPoint (Methods in Vtable Order)
IsSyncPoint (CMediaSample)
IsSyncPoint (IMediaSample)
IStandardCutList Interface
IStandardCutList::AddElement
IStandardCutList::GetFirstElement
IStandardCutList::GetLastElement
IStandardCutList::GetMediaType
IStandardCutList::GetNextElement
IStandardCutList::GetPreviousElement
IStandardCutList::RemoveElement
IStandardCutList::SetMediaType
IsTemporalCompressed
IsTemporalCompressed (CMediaType)
IStorage::OpenStream
IStream
IStreamSample Interface
IStreamSample::CompletionStatus
IStreamSample::GetMediaStream
IStreamSample::GetSampleTimes
IStreamSample::SetSampleTimes
IStreamSample::Update
IsUsingDefaultDestination (Implemented IBasicVideo Methods)
IsUsingDefaultDestination (Methods in Vtable Order)
IsUsingDefaultDestination (CBaseControlVideo)
IsUsingDefaultDestination (IBasicVideo)
IsUsingDefaultSource (Implemented IBasicVideo Methods)
IsUsingDefaultSource (Methods in Vtable Order)
IsUsingDefaultSource (CBaseControlVideo)
IsUsingDefaultSource (IBasicVideo)
IsUsingDefaultSource Method (IBasicVideo Object)
IsUsingTimeFormat (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
IsUsingTimeFormat (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
IsUsingTimeFormat (Methods in Vtable Order)
IsUsingTimeFormat (CPosPassThru)
IsUsingTimeFormat (CSourceSeeking)
IsUsingTimeFormat (IMediaSeeking)
IsValid
IsValid (CMediaType)
IsVPDecimationAllowed
IsVPDecimationAllowed (IVPConfig)
Item
Item (IAMCollection)
Item Method (IAMCollection Object)
ITypeInfo
IUnknown Interface
IUnknown Macro
IUnknown::AddRef
IUnknown::QueryInterface
IUnknown::Release
IVideoWindow Interface
IVideoWindow Object
IVideoWindow::get_AutoShow
IVideoWindow::get_BackgroundPalette
IVideoWindow::get_BorderColor
IVideoWindow::get_Caption
IVideoWindow::get_FullScreenMode
IVideoWindow::get_Height
IVideoWindow::get_Left
IVideoWindow::get_MessageDrain
IVideoWindow::get_Owner
IVideoWindow::get_Top
IVideoWindow::get_Visible
IVideoWindow::get_Width
IVideoWindow::get_WindowState
IVideoWindow::get_WindowStyle
IVideoWindow::get_WindowStyleEx
IVideoWindow::GetMaxIdealImageSize
IVideoWindow::GetMinIdealImageSize
IVideoWindow::GetRestorePosition
IVideoWindow::GetWindowPosition
IVideoWindow::HideCursor
IVideoWindow::IsCursorHidden
IVideoWindow::NotifyOwnerMessage
IVideoWindow::put_AutoShow
IVideoWindow::put_BackgroundPalette
IVideoWindow::put_BorderColor
IVideoWindow::put_Caption
IVideoWindow::put_FullScreenMode
IVideoWindow::put_Height
IVideoWindow::put_Left
IVideoWindow::put_MessageDrain
IVideoWindow::put_Owner
IVideoWindow::put_Top
IVideoWindow::put_Visible
IVideoWindow::put_Width
IVideoWindow::put_WindowState
IVideoWindow::put_WindowStyle
IVideoWindow::put_WindowStyleEx
IVideoWindow::SetWindowForeground
IVideoWindow::SetWindowPosition
IVPBaseConfig Interface
IVPBaseConfig::GetConnectInfo
IVPBaseConfig::GetMaxPixelRate
IVPBaseConfig::GetOverlaySurface
IVPBaseConfig::GetVideoFormats
IVPBaseConfig::GetVPDataInfo
IVPBaseConfig::InformVPInputFormats
IVPBaseConfig::SetConnectInfo
IVPBaseConfig::SetDDSurfaceKernelHandle
IVPBaseConfig::SetDirectDrawKernelHandle
IVPBaseConfig::SetInvertPolarity
IVPBaseConfig::SetSurfaceParameters
IVPBaseConfig::SetVideoFormat
IVPBaseConfig::SetVideoPortID
IVPBaseNotify Interface
IVPBaseNotify::RenegotiateVPParameters
IVPConfig Interface
IVPConfig::IsVPDecimationAllowed
IVPConfig::SetScalingFactors
IVPNotify Interface
IVPNotify::GetDeinterlaceMode
IVPNotify::SetDeinterlaceMode
IVPNotify2 Interface
IVPNotify2::GetVPSyncMaster
IVPNotify2::SetVPSyncMaster


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

CreateMediaType
CreatePosPassThru
CreateSample (IAudioMediaStream Interface: Methods in Vtable Order)
CreateSample (IDirectDrawMediaStream Interface: Methods in Vtable Order)
CreateSample (IAudioMediaStream)
CreateSample (IDirectDrawMediaStream)
CreateSharedSample
CreateSharedSample (IMediaStream)
CreateSurface
CreateSurface (IDirectDraw3)
CreateThread
CreateThread (CMsgThread)
CreateWindow
CreateWindowEx
Creating a Capture Application
Creating a Custom Graph
Creating a Filter Graph
Creating a New Filter Graph and Adding Filters
Creating a Transform Filter
Creating a Video Cutlist
Creating Both Video and Audio Cutlists
Creating Filters
Creating Plug-in Distributors
CRefTime (CRefTime)
CRefTime Class
CRefTime::CRefTime
CRefTime::GetUnits
CRefTime::Millisecs
CRefTime::operator –=
CRefTime::operator (REFERENCE_TIME)
CRefTime::operator +=
CRefTime::operator =
CRenderedInputPin (CRenderedInputPin)
CRenderedInputPin Class
CRenderedInputPin::Active
CRenderedInputPin::CRenderedInputPin
CRenderedInputPin::EndFlush
CRenderedInputPin::EndOfStream
CRenderedInputPin::Run
CRendererInputPin (CRendererInputPin)
CRendererInputPin Class
CRendererInputPin::Active
CRendererInputPin::Allocator
CRendererInputPin::BeginFlush
CRendererInputPin::BreakConnect
CRendererInputPin::CheckMediaType
CRendererInputPin::CompleteConnect
CRendererInputPin::CRendererInputPin
CRendererInputPin::EndFlush
CRendererInputPin::EndOfStream
CRendererInputPin::Inactive
CRendererInputPin::QueryId
CRendererInputPin::Receive
CRendererInputPin::SetMediaType
CRendererPosPassThru (CRendererPosPassThru)
CRendererPosPassThru Class
CRendererPosPassThru::CRendererPosPassThru
CRendererPosPassThru::GetMediaTime
CRendererPosPassThru::RegisterMediaTime
CRendererPosPassThru::ResetMediaTime
CritCheckIn
CritCheckOut
Critical Section Usage
CRITICAL_SECTION
CropAlignX
CropAlignY
CropGranularityX
CropGranularityY
CSource (CSource)
CSource Class
CSource::AddPin
CSource::CSource
CSource::FindPinNumber
CSource::GetPin
CSource::GetPinCount
CSource::pStateLock
CSource::RemovePin
CSourcePosition (CSourcePosition)
CSourcePosition Class
CSourcePosition::ChangeRate
CSourcePosition::ChangeStart
CSourcePosition::ChangeStop
CSourcePosition::CSourcePosition
CSourcePosition::get_CurrentPosition
CSourcePosition::get_Duration
CSourcePosition::get_PrerollTime
CSourcePosition::get_Rate
CSourcePosition::get_StopTime
CSourcePosition::put_CurrentPosition
CSourcePosition::put_PrerollTime
CSourcePosition::put_Rate
CSourcePosition::put_StopTime
CSourceSeeking (CSourceSeeking)
CSourceSeeking Class
CSourceSeeking::ChangeRate
CSourceSeeking::ChangeStart
CSourceSeeking::ChangeStop
CSourceSeeking::CheckCapabilities
CSourceSeeking::ConvertTimeFormat
CSourceSeeking::CSourceSeeking
CSourceSeeking::GetAvailable
CSourceSeeking::GetCapabilities
CSourceSeeking::GetCurrentPosition
CSourceSeeking::GetDuration
CSourceSeeking::GetPositions
CSourceSeeking::GetPreroll
CSourceSeeking::GetRate
CSourceSeeking::GetStopPosition
CSourceSeeking::GetTimeFormat
CSourceSeeking::IsFormatSupported
CSourceSeeking::IsUsingTimeFormat
CSourceSeeking::NonDelegatingQueryInterface
CSourceSeeking::QueryPreferredFormat
CSourceSeeking::SetPositions
CSourceSeeking::SetRate
CSourceSeeking::SetTimeFormat
CSourceStream (CSourceStream)
CSourceStream Class
CSourceStream::Active
CSourceStream::CheckMediaType
CSourceStream::CheckRequest
CSourceStream::CSourceStream
CSourceStream::DoBufferProcessingLoop
CSourceStream::Exit
CSourceStream::FillBuffer
CSourceStream::GetMediaType
CSourceStream::GetRequest
CSourceStream::Inactive
CSourceStream::Init
CSourceStream::OnThreadCreate
CSourceStream::OnThreadDestroy
CSourceStream::OnThreadStartPlay
CSourceStream::Pause
CSourceStream::Run
CSourceStream::Stop
CSourceStream::ThreadProc
CSystemClock (CSystemClock)
CSystemClock Class
CSystemClock::CreateInstance
CSystemClock::CSystemClock
CSystemClock::GetClassID
CSystemClock::NonDelegatingQueryInterface
CTL_E_BADFILEMODE
CTL_E_BADFILENAME
CTL_E_BADFILENAMEORNUMBER
CTL_E_BADRECORDLENGTH
CTL_E_BADRECORDNUMBER
CTL_E_CANTSAVEFILETOTEMP
CTL_E_DEVICEIOERROR
CTL_E_DEVICEUNAVAILABLE
CTL_E_DISKFULL
CTL_E_DISKNOTREADY
CTL_E_DIVISIONBYZERO
CTL_E_FILEALREADYEXISTS
CTL_E_FILEALREADYOPEN
CTL_E_FILENOTFOUND
CTL_E_GETNOTSUPPORTED
CTL_E_GETNOTSUPPORTEDATRUNTIME
CTL_E_ILLEGALFUNCTIONCALL
CTL_E_INVALIDCLIPBOARDFORMAT
CTL_E_INVALIDFILEFORMAT
CTL_E_INVALIDPATTERNSTRING
CTL_E_INVALIDPICTURE
CTL_E_INVALIDPROPERTYARRAYINDEX
CTL_E_INVALIDPROPERTYVALUE
CTL_E_INVALIDUSEOFNULL
CTL_E_NEEDPROPERTYARRAYINDEX
CTL_E_OUTOFMEMORY
CTL_E_OUTOFSTACKSPACE
CTL_E_OUTOFSTRINGSPACE
CTL_E_OVERFLOW
CTL_E_PATHFILEACCESSERROR
CTL_E_PATHNOTFOUND
CTL_E_PERMISSIONDENIED
CTL_E_PRINTERERROR
CTL_E_PROPERTYNOTFOUND
CTL_E_REPLACEMENTSTOOLONG
CTL_E_SEARCHTEXTNOTFOUND
CTL_E_SETNOTPERMITTED
CTL_E_SETNOTSUPPORTED
CTL_E_SETNOTSUPPORTEDATRUNTIME
CTL_E_TOOMANYFILES
CTransformFilter (CTransformFilter)
CTransformFilter Class
CTransformFilter::AlterQuality
CTransformFilter::BeginFlush
CTransformFilter::BreakConnect
CTransformFilter::CheckConnect
CTransformFilter::CheckInputType
CTransformFilter::CheckTransform
CTransformFilter::CompleteConnect
CTransformFilter::CTransformFilter
CTransformFilter::DecideBufferSize
CTransformFilter::EndFlush
CTransformFilter::EndOfStream
CTransformFilter::FindPin
CTransformFilter::GetMediaType
CTransformFilter::GetPin
CTransformFilter::GetPinCount
CTransformFilter::NewSegment
CTransformFilter::Pause
CTransformFilter::Receive
CTransformFilter::RegisterPerfId
CTransformFilter::SetMediaType
CTransformFilter::StartStreaming
CTransformFilter::Stop
CTransformFilter::StopStreaming
CTransformFilter::Transform
CTransformInputPin (CTransformInputPin)
CTransformInputPin Class
CTransformInputPin::BeginFlush
CTransformInputPin::BreakConnect
CTransformInputPin::CheckConnect
CTransformInputPin::CheckMediaType
CTransformInputPin::CheckStreaming
CTransformInputPin::CompleteConnect
CTransformInputPin::CTransformInputPin
CTransformInputPin::CurrentMediaType
CTransformInputPin::EndFlush
CTransformInputPin::EndOfStream
CTransformInputPin::NewSegment
CTransformInputPin::QueryId
CTransformInputPin::Receive
CTransformInputPin::SetMediaType
CTransformOutputPin (CTransformOutputPin)
CTransformOutputPin Class
CTransformOutputPin::BreakConnect
CTransformOutputPin::CheckConnect
CTransformOutputPin::CheckMediaType
CTransformOutputPin::CompleteConnect
CTransformOutputPin::CTransformOutputPin
CTransformOutputPin::CurrentMediaType
CTransformOutputPin::DecideBufferSize
CTransformOutputPin::GetMediaType
CTransformOutputPin::NonDelegatingQueryInterface
CTransformOutputPin::Notify
CTransformOutputPin::QueryId
CTransformOutputPin::SetMediaType
CTransInPlaceFilter (CTransInPlaceFilter)
CTransInPlaceFilter Class
CTransInPlaceFilter::CheckTransform
CTransInPlaceFilter::CompleteConnect
CTransInPlaceFilter::Copy
CTransInPlaceFilter::CTransInPlaceFilter
CTransInPlaceFilter::DecideBufferSize
CTransInPlaceFilter::GetMediaType
CTransInPlaceFilter::GetPin
CTransInPlaceFilter::InputPin
CTransInPlaceFilter::OutputPin
CTransInPlaceFilter::Receive
CTransInPlaceFilter::RegisterPerfId
CTransInPlaceFilter::Transform
CTransInPlaceInputPin (CTransInPlaceInputPin)
CTransInPlaceInputPin Class
CTransInPlaceInputPin::CheckMediaType
CTransInPlaceInputPin::CTransInPlaceInputPin
CTransInPlaceInputPin::EnumMediaTypes
CTransInPlaceInputPin::GetAllocator
CTransInPlaceInputPin::GetAllocatorRequirements
CTransInPlaceInputPin::NotifyAllocator
CTransInPlaceInputPin::PeekAllocator
CTransInPlaceInputPin::ReadOnly
CTransInPlaceOutputPin (CTransInPlaceOutputPin)
CTransInPlaceOutputPin Class
CTransInPlaceOutputPin::CheckMediaType
CTransInPlaceOutputPin::ConnectedIMemInputPin
CTransInPlaceOutputPin::CTransInPlaceOutputPin
CTransInPlaceOutputPin::DecideAllocator
CTransInPlaceOutputPin::EnumMediaTypes
CTransInPlaceOutputPin::PeekAllocator
CTransInPlaceOutputPin::ReceiveAllocator
CUnknown (CUnknown)
CUnknown Class
CUnknown::CUnknown
CUnknown::GetOwner
CUnknown::NonDelegatingAddRef
CUnknown::NonDelegatingQueryInterface
CUnknown::NonDelegatingRelease
CurrentMediaType (Implemented IMemInputPin Methods)
CurrentMediaType (Implemented INonDelegatingUnknown Methods)
CurrentMediaType (CTransformInputPin)
CurrentMediaType (CTransformOutputPin)
CurrentPosition Property
CurrentPosition Property (IMediaPosition Object)
CurrentRate
CurrentRate (CBasePin)
CurrentStartTime
CurrentStartTime (CBasePin)
CurrentState Property
CurrentStopTime
CurrentStopTime (CBasePin)
cutlist
cutlist element
Cutlist File Source
Cutlist Limitations
Cutlist Objects and Interfaces
Cutlist Sample Applications
Cutlist Sample Code (Simplecl)
CVideoTransformFilter (CVideoTransformFilter)
CVideoTransformFilter Class
CVideoTransformFilter::AlterQuality
CVideoTransformFilter::CVideoTransformFilter
CVideoTransformFilter::EndFlush
CVideoTransformFilter::Receive
CVideoTransformFilter::RegisterPerfId
CVideoTransformFilter::ShouldSkipFrame
CVideoTransformFilter::StartStreaming


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

_CrtSetDbgFlag
~ Prefix for Pin Names
~ Prefix for Pin Names (Capture and Preview Pin Requirements)

A

A Sample Transform Filter Declaration
About Capture Filter Graphs
About Compression Filters
About Cutlists
About DVD-Video
About Filter Graphs
About Reference Clocks
About Stream Architecture
About the DirectShow Filter Graph Editor
About the DirectShow Quartz.dll Objects
About Time
AboutBox Method
achName (FILTER_INFO)
achName (PIN_INFO)
ACM Audio Compressor
AcquireResource
AcquireResource (IResourceConsumer)
Activate
Activate (CBasePropertyPage)
ActivateWindow
ActivateWindow (CBaseWindow)
Active (CBaseOutputPin Class: Implemented IPin Methods)
Active (CPullPin Class: Overridable Member Functions)
Active (CRenderedInputPin Class: Overridable Member Functions)
Active (CRendererInputPin Class: Implemented IPin Methods)
Active (CSourceStream Class: Implemented IPin Methods)
Active (Helper Function)
Active (Implemented INonDelegatingUnknown Methods)
Active (CBaseOutputPin)
Active (CBasePin)
Active (CBaseRenderer)
Active (CPullPin)
Active (CRenderedInputPin)
Active (CRendererInputPin)
Active (CSourceStream)
Add the Filter as an Additional DLL in Developer Studio
AddAdvisePacket
AddAdvisePacket (CAMSchedule)
AddAfter (CBaseList Class: Member Functions)
AddAfter (CGenericList Class: Member Functions)
AddAfter (CBaseList)
AddAfter (CGenericList)
AddAfterI
AddAfterI (CBaseList)
AddBefore (CBaseList Class: Member Functions)
AddBefore (CGenericList Class: Member Functions)
AddBefore (CBaseList)
AddBefore (CGenericList)
AddBeforeI
AddBeforeI (CBaseList)
AddCutList
AddCutList (ICutListGraphBuilder)
AddElement
AddElement (IStandardCutList)
AddFilter
AddFilter (IFilterGraph)
AddHead (CBaseList Class: Member Functions)
AddHead (CGenericList Class: Member Functions)
AddHead (CBaseList)
AddHead (CGenericList)
AddHeadI
AddHeadI (CBaseList)
AddMediaStream
AddMediaStream (IAMMultiMediaStream)
AddPin
AddPin (CSource)
AddRef
AddRef (CEnumMediaTypes)
AddRef (CEnumPins)
AddRef (CMediaSample)
AddRef (IUnknown)
AddSourceFilter (IAMovie Interface: Methods in Vtable Order)
AddSourceFilter (IGraphBuilder Interface: Methods in Vtable Order)
AddSourceFilter (IMediaControl Interface: Methods in Vtable Order)
AddSourceFilter (IAMovie)
AddSourceFilter (IGraphBuilder)
AddSourceFilter (IMediaControl)
AddSourceFilter Method (IMediaControl Object)
AddSourceFilterForMoniker
AddSourceFilterForMoniker (IFilterGraph2)
AddTail (CBaseList Class: Member Functions)
AddTail (CGenericList Class: Member Functions)
AddTail (CBaseList)
AddTail (CGenericList)
AddTailI
AddTailI (CBaseList)
advise
Advise (Member Functions)
Advise (Methods in Vtable Order)
Advise (CAMSchedule)
Advise (IOverlay)
AdvisePeriodic (Implemented INonDelegatingUnknown Methods)
AdvisePeriodic (Methods in Vtable Order)
AdvisePeriodic (CBaseReferenceClock)
AdvisePeriodic (IReferenceClock)
AdviseTime (Implemented INonDelegatingUnknown Methods)
AdviseTime (Methods in Vtable Order)
AdviseTime (CBaseReferenceClock)
AdviseTime (IReferenceClock)
AgreeMediaType
AgreeMediaType (CBasePin)
AlignDown
AlignDown (CPullPin)
AlignUp
AlignUp (CPullPin)
Alloc (CImageAllocator Class: Implemented IMemAllocator Methods)
Alloc (CMemAllocator Class: Implemented IMemAllocator Methods)
Alloc (Implemented INonDelegatingUnknown Methods)
Alloc (Methods in Vtable Order)
Alloc (CBaseAllocator)
Alloc (CImageAllocator)
Alloc (CMemAllocator)
Alloc (IAMDevMemoryAllocator)
AllocateSample
AllocateSample (IMediaStream)
Allocator
Allocator (CRendererInputPin)
ALLOCATOR_PROPERTIES
AllocCapFile
AllocCapFile (ICaptureGraphBuilder)
AllocFormatBuffer
AllocFormatBuffer (CMediaType)
AllowChangeDisplayMode Property
AllowHideControls Property
AllowHideDisplay Property
Alternative Video Renderers
AlterQuality (Implemented IBaseFilter Methods)
AlterQuality (Overridable Member Functions)
AlterQuality (CTransformFilter)
AlterQuality (CVideoTransformFilter)
AM_ARMODE_CROP
AM_ARMODE_LETTER_BOX
AM_ARMODE_NONE
AM_ASPECT_RATIO_MODE
AM_COLCON
AM_COPY_MACROVISION
AM_COPY_MACROVISION_LEVEL
AM_DVD_GRAPH_FLAGS
AM_DVD_HWDEC_ONLY
AM_DVD_HWDEC_PREFER
AM_DVD_NOVPE
AM_DVD_RENDERSTATUS
AM_DVD_STREAM_AUDIO
AM_DVD_STREAM_FLAGS
AM_DVD_STREAM_SUBPIC
AM_DVD_STREAM_VIDEO
AM_DVD_SWDEC_ONLY
AM_DVD_SWDEC_PREFER
AM_DVD_YUV
AM_DVDCOPY_BUSKEY
AM_DVDCOPY_CHLGKEY
AM_DVDCOPY_DISCKEY
AM_DVDCOPY_SET_COPY_STATE
AM_DVDCOPY_TITLEKEY
AM_DVDCOPYSTATE
AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED
AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED
AM_DVDCOPYSTATE_DONE
AM_DVDCOPYSTATE_INITIALIZE
AM_DVDCOPYSTATE_INITIALIZE_TITLE
AM_ExactRateChange
AM_KSPROPSETID_CopyProt
AM_KSPROPSETID_DvdSubPic
AM_L21_CCLEVEL_TC2
AM_L21_CCSERVICE_Caption1
AM_L21_CCSERVICE_Caption2
AM_L21_CCSERVICE_None
AM_L21_CCSERVICE_Text1
AM_L21_CCSERVICE_Text2
AM_L21_CCSERVICE_XDS
AM_L21_CCSTATE_Off
AM_L21_CCSTATE_On
AM_L21_DRAWBGMODE_Opaque
AM_L21_DRAWBGMODE_Transparent
AM_LINE21_CCLEVEL
AM_LINE21_CCSERVICE
AM_LINE21_CCSTATE
AM_LINE21_DRAWBGMODE
AM_MACROVISION_DISABLED
AM_MACROVISION_LEVEL1
AM_MACROVISION_LEVEL2
AM_MACROVISION_LEVEL3
AM_MaxFullDataRate
AM_MEDIA_TYPE
AM_PROPERTY_COMPOSIT_ON
AM_PROPERTY_COPY_MACROVISION
AM_PROPERTY_DVDCOPY_CHLG_KEY
AM_PROPERTY_DVDCOPY_DEC_KEY2
AM_PROPERTY_DVDCOPY_DISC_KEY
AM_PROPERTY_DVDCOPY_DVD_KEY1
AM_PROPERTY_DVDCOPY_REGION
AM_PROPERTY_DVDCOPY_SET_COPY_STATE
AM_PROPERTY_DVDCOPY_TITLE_KEY
AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON
AM_PROPERTY_DVDSUBPIC_HLI
AM_PROPERTY_DVDSUBPIC_PALETTE
AM_PROPERTY_SPHLI
AM_PROPERTY_SPPAL
AM_RATE_ExactRateChange
AM_RATE_MaxFullDataRate
AM_RATE_SimpleRateChange
AM_RATE_Step
AM_SAMPLE_DATADISCONTINUITY
AM_SAMPLE_ENDOFSTREAM
AM_SAMPLE_FLUSH_ON_PAUSE
AM_SAMPLE_PREROLL
AM_SAMPLE_PROPERTY_FLAGS
AM_SAMPLE_SPLICEPOINT
AM_SAMPLE_STOPVALID
AM_SAMPLE_TIMEDISCONTINUITY
AM_SAMPLE_TIMEVALID
AM_SAMPLE_TYPECHANGED
AM_SAMPLE2_PROPERTIES
AM_SEEKING_AbsolutePositioning
AM_SEEKING_IncrementalPositioning
AM_SEEKING_NoFlush
AM_SEEKING_NoPositioning
AM_SEEKING_PositioningBitsMask
AM_SEEKING_RelativePositioning
AM_SEEKING_ReturnTime
AM_SEEKING_SEEKING_CAPABILITIES
AM_SEEKING_SeekToKeyFrame
AM_SEEKING_Segment
AM_SimpleRateChange
AM_Step
AM_STREAM_CONTROL
AM_STREAM_INFO
AM_STREAM_INFO_DISCARDING
AM_STREAM_INFO_FLAGS
AM_STREAM_INFO_START_DEFINED
AM_STREAM_INFO_STOP_DEFINED
AM_STREAM_INFO_STOP_SEND_EXTRA
AM_STREAM_MEDIA
AM_TS_RATE_CHANGE
AMCap Sample (DirectShow Capture Application)
AMGetErrorText
AMGetWideString
AMovieDllRegisterServer
AMovieDllRegisterServer2
AMovieDllUnregisterServer
AMOVIESETUP_FILTER
AMOVIESETUP_MEDIATYPE
AMOVIESETUP_PIN
AMovieSetupRegisterFilter
AMovieSetupRegisterFilter2
AMPROPERTY_PIN_CATEGORY
AMPROPSETID_Pin
AMSTREAMSELECTENABLE_ENABLE
AMSTREAMSELECTENABLE_ENABLEALL
AMSTREAMSELECTINFO_ENABLED
AMSTREAMSELECTINFO_EXCLUSIVE
AMTUNER_MODE_AM_RADIO
AMTUNER_MODE_DEFAULT
AMTUNER_MODE_DSS
AMTUNER_MODE_FM_RADIO
AMTUNER_MODE_TV
AMTunerModeType
AMVP_BEST_BANDWIDTH
AMVP_DO_NOT_CARE
AMVP_INPUT_SAME_AS_OUTPUT
AMVP_MODE
AMVP_MODE_BOBINTERLEAVED
AMVP_MODE_SKIPEVEN
AMVP_MODE_SKIPODD
AMVP_MODE_WEAVE
AMVP_SELECT_FORMAT_BY
AMVPDATAINFO
AMVPDIMINFO
amvpDimInfo (AMVPDATAINFO)
AMVPSIZE
Analog Video Crossbar
AnalogVideo_None
AnalogVideo_NTSC_M
AnalogVideo_NTSC_M_J
AnalogVideo_PAL_B
AnalogVideo_PAL_D
AnalogVideo_PAL_H
AnalogVideo_PAL_I
AnalogVideo_PAL_M
AnalogVideo_PAL_N
AnalogVideo_SECAM_B
AnalogVideo_SECAM_D
AnalogVideo_SECAM_G
AnalogVideo_SECAM_H
AnalogVideo_SECAM_K
AnalogVideo_SECAM_K1
AnalogVideo_SECAM_L
ANALOGVIDEOINFO
AnalogVideoStandard
AngleChange
AngleChange (IDvdControl)
Appearance Property
Application Development Questions
application notification
Application-Level Interfaces
Apply
Apply (CBasePropertyPage)
AreEqualVideoTypes
ASSERT
Assert Macros and Functions
Assertion Checking
asychronous reader filter
Async Sample (Asynchronous Reader Filter)
atoi
ATR
AttemptConnection
AttemptConnection (CBasePin)
Audio Capture
Audio Capture Filter:How to Write an Audio Capture Filter
Audio Capture Filter:Necessary Interfaces
Audio Capture Pin Requirements
Audio Renderer
Audio Synthesizer filter
AUDIO_STREAM_CONFIG_CAPS
AudioStreamChange
AudioStreamChange (IDvdControl)
Automatically Connecting Pins
AutoRewind Property
AutoShow Property (IVideoWindow Object)
AutoStart Property
AutoTune
AutoTune (IAMTVTuner)
Auxillary device control (External Device Control)
Auxillary device control (Introduction)
AvgTimePerFrame (ANALOGVIDEOINFO)
AvgTimePerFrame (VIDEOINFO)
AvgTimePerFrame (VIDEOINFOHEADER)
AvgTimePerFrame (VIDEOINFOHEADER2)
AvgTimePerFrame Property (IBasicVideo Object)
AVI 2.0 File Format Extensions
AVI Compressor
AVI Decompressor
AVI Draw
AVI MUX
AVI Splitter
AVI/WAV File Source
Avoid GUID Conflicts

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

B

backcol
backcon
BackgroundPalette Property (IVideoWindow Object)
backing object
BackwardScan
BackwardScan (IDvdControl)
Balance Property
Balance Property (IBasicAudio Object)
Ball Sample (Bouncing Ball Filter)
Base Classes
Base Classes that Implement Interfaces
bDataIsInterlaced
bDVDVolInvalid
bDVDVolUnknown
BeginFlush (CBaseInputPin Class: Implemented IQualityControl Methods)
BeginFlush (CBaseOutputPin Class: Implemented IPin Methods)
BeginFlush (CBaseRenderer Class: Helper Function)
BeginFlush (COutputQueue Class: Member Functions)
BeginFlush (CPullPin Class: Overridable Member Functions)
BeginFlush (CRendererInputPin Class: Implemented IPin Methods)
BeginFlush (CTransformFilter Class: Implemented IBaseFilter Methods)
BeginFlush (CTransformInputPin Class: Implemented IMemInputPin Methods)
BeginFlush (IAsyncReader Interface: Methods in Vtable Order)
BeginFlush (IPin Interface: Methods in Vtable Order)
BeginFlush (CBaseInputPin)
BeginFlush (CBaseOutputPin)
BeginFlush (CBaseRenderer)
BeginFlush (COutputQueue)
BeginFlush (CPullPin)
BeginFlush (CRendererInputPin)
BeginFlush (CTransformFilter)
BeginFlush (CTransformInputPin)
BeginFlush (IAsyncReader)
BeginFlush (IPin)
bEnableDoubleClock
bEnableVACT
bFieldPolarityInverted
bFixedSizeSamples
biHeight
bi-phase mark
BIT_MASKS_MATCH
BitBlt
BitErrorRate Property (IBasicVideo Object)
Bitmap Functions, Macros, and Data
BITMAPINFO
BITMAPINFOHEADER Structure
BITMASKS
BitRate Property (IBasicVideo Object)
bits555
bits565
bits888
BitsPerSampleGranularity
biWidth
blackburst
blit
bMany (AMOVIESETUP_PIN)
bMany (REGFILTERPINS)
bmiColors
bmiColors[iPALETTE_COLORS]
bmiHeader (VIDEOINFO)
bmiHeader (VIDEOINFOHEADER)
bmiHeader (VIDEOINFOHEADER2)
bNoLine21In
bNoLine21Out
bob
BorderColor Property (IVideoWindow Object)
BorderStyle Property
Bouncing Ball filter
Bouncing Ball filter (Ball Sample (Bouncing Ball Filter))
bOutput (AMOVIESETUP_PIN)
bOutput (REGFILTERPINS)
BreakConnect (CBaseOutputPin Class: Implemented IPin Methods)
BreakConnect (CBasePin Class: Implemented INonDelegatingUnknown Methods)
BreakConnect (CRendererInputPin Class: Implemented IPin Methods)
BreakConnect (CTransformFilter Class: Implemented IBaseFilter Methods)
BreakConnect (CTransformInputPin Class: Implemented IMemInputPin Methods)
BreakConnect (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
BreakConnect (Helper Function)
BreakConnect (CBaseOutputPin)
BreakConnect (CBasePin)
BreakConnect (CBaseRenderer)
BreakConnect (CRendererInputPin)
BreakConnect (CTransformFilter)
BreakConnect (CTransformInputPin)
BreakConnect (CTransformOutputPin)
Breakpoint Macros and Function
bRendered (AMOVIESETUP_PIN)
bRendered (REGFILTERPINS)
bSequenceHeader
BSTR
BSTR Functions
bTemporalCompression
Build a Filter or Application with Visual C++ 5.x
Build Information
Building the Capture and Preview Filter Graph
Building the Samples
BusKey
ButtonActivate
ButtonActivate (IDvdControl)
ButtonSelectAndActivate
ButtonSelectAndActivate (IDvdControl)
bVPEFailed
bZero (AMOVIESETUP_PIN)
bZero (REGFILTERPINS)

C

C/C++-based Sample Applications to CBaseInputPin::EndFlush
CBaseInputPin::GetAllocator to CDispParams (CDispParams)
CDispParams Class to CMediaPosition Class
CMediaPosition::CMediaPosition to CreateInstance (CSystemClock)
CreateMediaType to CVideoTransformFilter::StartStreaming

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

D

Data Flow in the Filter Graph
Data Types
DbgAssert
DbgBreak
DbgBreakPoint
DbgCheckModuleLevel
DbgDumpObjectRegister
DbgInitialise
DbgKernelAssert
DbgLockTrace
DbgLog
DbgLogInfo
DbgOutString
DbgSetModuleLevel
DbgSetWaitTimeout
DbgTerminate
DbgWaitForMultipleObjects
DbgWaitForSingleObject
DDCAPS
DDCOLORCONTROL
DDEnumCallback
DDPIXELFORMAT
DDSCAPS
DDSURFACEDESC
DDVIDEOPORTCONNECT
Deactivate
Deactivate (CBasePropertyPage)
DEBUG
debug build
debug level
Debug Logging
Debug Logging by Module Level
Debug NOTE (Message) Macros
Debug Output
Debug Output Location
Debugging Classes
Debugging New Filters
Debugging with DirectShow
DecideAllocator (CBaseOutputPin Class: Implemented IPin Methods)
DecideAllocator (CTransInPlaceOutputPin Class: Implemented IPin Methods)
DecideAllocator (Overridable Member Functions)
DecideAllocator (CBaseOutputPin)
DecideAllocator (CPullPin)
DecideAllocator (CTransInPlaceOutputPin)
DecideBufferSize (Implemented IBaseFilter Methods)
DecideBufferSize (Implemented INonDelegatingUnknown Methods)
DecideBufferSize (Implemented IPin Methods)
DecideBufferSize (Overridable Member Functions)
DecideBufferSize (CBaseOutputPin)
DecideBufferSize (CTransformFilter)
DecideBufferSize (CTransformOutputPin)
DecideBufferSize (CTransInPlaceFilter)
DECLARE_IUNKNOWN
Decommit (Implemented INonDelegatingUnknown Methods)
Decommit (Methods in Vtable Order)
Decommit (CBaseAllocator)
Decommit (IMemAllocator)
DefWindowProc
DeleteCriticalSection
DeleteMediaType
Deliver
Deliver (CBaseOutputPin)
DeliverBeginFlush
DeliverBeginFlush (CBaseOutputPin)
DeliverEndFlush
DeliverEndFlush (CBaseOutputPin)
DeliverEndOfStream
DeliverEndOfStream (CBaseOutputPin)
DeliverNewSegment
DeliverNewSegment (CBaseOutputPin)
DestinationHeight Property (IBasicVideo Object)
DestinationLeft Property (IBasicVideo Object)
DestinationTop Property (IBasicVideo Object)
DestinationWidth Property (IBasicVideo Object)
Detecting Leaks
Determine if the Filter Must Copy Media Samples
Determine Which Base Classes to Use
Determining a Media Type with CBasePin::TryMediaTypes
Device Enumeration and Capture Interfaces
DIBDATA
DIBSECTION
DibSection (DIBDATA)
DIBSIZE
dir
DirectDraw
DirectDrawClipper
DirectDrawCreate
DirectDrawEnumerate
DirectDrawEnumerate (Methods in Vtable Order)
DirectDrawEnumerate (IDirectDrawFactory)
DirectDrawSurface
Direction Property (IPinInfo Object)
DirectShow and COM
DirectShow applications, build in Visual C++
DirectShow Clock Classes
DirectShow Filters
DirectShow Filters and Filter Graphs
DirectShow Graph File Format
DirectShow Interfaces, Visual Basic Objects, and Registering Quartz.dll
DirectShow objects, register
DirectShow Samples
DiscKey
Disconnect (CBaseInputPin Class: Implemented IQualityControl Methods)
Disconnect (CBasePin Class: Implemented INonDelegatingUnknown Methods)
Disconnect (CPullPin Class: Overridable Member Functions)
Disconnect (IFilterGraph Interface: Methods in Vtable Order)
Disconnect (IPin Interface: Methods in Vtable Order)
Disconnect (IPinInfo Interface: Methods in Vtable Order)
Disconnect (CBaseInputPin)
Disconnect (CBasePin)
Disconnect (CPullPin)
Disconnect (IFilterGraph)
Disconnect (IPin)
Disconnect (IPinInfo)
Disconnect Method (IPinInfo Object)
DispatchMessage
Display a Filter's Property Page from C++
DISPLAY_16x9
DISPLAY_4x3_LETTERBOX_PREFERRED
DISPLAY_4x3_PANSCAN_PREFERRED
DISPLAY_CONTENT_DEFAULT
DisplayBackColor Property
DisplayForeColor Property
DisplayMode Property
DisplayModeChange Event
DisplayPinInfo
DisplayPinInfo (CBasePin)
DisplayRendererState
DisplayRendererState (CBaseRenderer)
DisplaySampleTimes
DisplaySampleTimes (CDrawImage)
DisplayType
DisplayTypeInfo
DisplayTypeInfo (CBasePin)
DISPPARAMS
DLL and Setup Functions
DLL Base Address Conflicts
DllCanUnloadNow
DllGetClassObject
DllRegisterServer
DllUnregisterServer
DoBufferProcessingLoop
DoBufferProcessingLoop (CSourceStream)
DoGetWindowStyle
DoGetWindowStyle (CBaseControlWindow)
DoneWithWindow
DoneWithWindow (CBaseWindow)
DoRealisePalette
DoRealisePalette (CBaseWindow)
DoRenderSample
DoRenderSample (CBaseRenderer)
DoSetWindowForeground
DoSetWindowForeground (CBaseWindow)
DoSetWindowStyle
DoSetWindowStyle (CBaseControlWindow)
DoShowWindow
DoShowWindow (CBaseWindow)
double
double (COARefTime)
downstream filter
DrawImage
DrawImage (CDrawImage)
DSound Audio Renderer
Dump filter
Dump Sample (Dump Filter)
DumpGraph
Duration
Duration (CPullPin)
Duration Property (IMediaPosition Object)
DV Data in the AVI File Format
DV media types table
DV Muxer
DV Splitter
DV Video Decoder
DV Video Encoder
DVD Control Data Structure
DVD Copy Protection Property Set
DVD Event Notification Codes
DVD Features
DVD for Application Developers
DVD for Title Vendors
DVD Interfaces
DVD Navigator
DVD Resources on the Web
DVD Subpicture Property Set
DVD Time Stamp Rate Change Property Set
DVD_ATR
DVD_DISC_SIDE
DVD_DOMAIN
DVD_DOMAIN_FirstPlay
DVD_DOMAIN_Stop
DVD_DOMAIN_Title
DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_ERROR
DVD_ERROR_CopyProtectFail
DVD_ERROR_InvalidDiscRegion
DVD_ERROR_InvalidDVD1_0Disc
DVD_ERROR_LowParentalLevel
DVD_ERROR_Unexpected
DVD_FPS_25
DVD_FPS_30NonDrop
DVD_FRAMERATE
DVD_MENU_Angle
DVD_MENU_Audio
DVD_MENU_Chapter
DVD_MENU_ID
DVD_MENU_Root
DVD_MENU_Subpicture
DVD_MENU_Title
DVD_PARENTAL_LEVEL_1
DVD_PARENTAL_LEVEL_6
DVD_PARENTAL_LEVEL_8
DVD_PLAYBACK_LOCATION
DVD_PREFERRED_DISPLAY_MODE
DVD_SIDE_A
DVD_SIDE_B
DVD_TIMECODE
DVD_WARNING
DVD_WARNING_FormatNotSupported
DVD_WARNING_InvalidDVD1_0Disc
DVDCopyState
Dvdsampl Sample (DVD Player Application)
DVD-Video specification
DVINFO
dw1
dw2
dwActiveHeight
dwActiveWidth
dwBitErrorRate (VIDEOINFO)
dwBitErrorRate (VIDEOINFOHEADER)
dwBitErrorRate (VIDEOINFOHEADER2)
dwBitMasks
dwBitMasks[iMASK_COLORS]
dwBitRate (VIDEOINFO)
dwBitRate (VIDEOINFOHEADER)
dwBitRate (VIDEOINFOHEADER2)
dwCopyProtectFlags
dwFailedStreamsFlag
dwFieldHeight
dwFieldWidth
dwFlags
dwFlags (AM_STREAM_INFO)
dwFlags (MPEG2VIDEOINFO)
dwFlags (REGFILTERPINS2)
dwFlags (TIMECODE_SAMPLE)
dwFrames
dwHeight
dwInterlaceFlags
dwLevel
dwMerit (AMOVIESETUP_FILTER)
dwMerit (REGFILTER2)
dwMicrosecondsPerField
dwNumLinesInVREF
DWORD
dwPictAspectRatioX (AMVPDATAINFO)
dwPictAspectRatioX (VIDEOINFOHEADER2)
dwPictAspectRatioY (AMVPDATAINFO)
dwPictAspectRatioY (VIDEOINFOHEADER2)
dwProfile
dwReserved1 (AMVPDATAINFO)
dwReserved1 (VIDEOINFOHEADER2)
dwReserved2
dwSampleFlags
dwSequenceHeader
dwSize
dwStartCookie
dwStartTimeCode (MPEG1VIDEOINFO)
dwStartTimeCode (MPEG2VIDEOINFO)
dwStopCookie
dwStreamId
dwTypeSpecificFlags
dwUser
dwVBIHeight
dwVBIWidth
dwVersion
dwWidth

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

E

EC_ACTIVATE
EC_BUFFERING_DATA
EC_CLOCK_CHANGED
EC_COMPLETE
EC_DISPLAY_CHANGED
EC_DVD_ANGLE_CHANGE
EC_DVD_AUDIO_STREAM_CHANGE
EC_DVD_BUTTON_CHANGE
EC_DVD_CHAPTER_AUTOSTOP
EC_DVD_CHAPTER_START
EC_DVD_CURRENT_TIME
EC_DVD_DOMAIN_CHANGE
EC_DVD_ERROR
EC_DVD_STILL_OFF
EC_DVD_STILL_ON
EC_DVD_SUBPICTURE_STREAM_CHANGE
EC_DVD_TITLE_CHANGE
EC_DVD_VALID_UOPS_CHANGE
EC_DVD_WARNING
EC_END_OF_SEGMENT
EC_ERROR_STILLPLAYING
EC_ERRORABORT
EC_FULLSCREEN_LOST
EC_NEED_RESTART
EC_NOTIFY_WINDOW
EC_OLE_EVENT
EC_OPENING_FILE
EC_PALETTE_CHANGED
EC_QUALITY_CHANGE
EC_REPAINT
EC_SEGMENT_STARTED
EC_SHUTTING_DOWN
EC_STARVATION
EC_STREAM_CONTROL_STARTED
EC_STREAM_CONTROL_STOPPED
EC_STREAM_ERROR_STILLPLAYING
EC_STREAM_ERROR_STOPPED
EC_TIME
EC_USERABORT
EC_VIDEO_SIZE_CHANGED
EC_WINDOW_DESTROYED
edit decision list
Editing (External Device Control)
Editing (Introduction)
effect filter
ElementStatus
ElementStatus (IAMCutListElement)
emph1col
emph1con
emph2col
emph2con
Enable
Enable (IAMStreamSelect)
EnableContextMenu Property
Enabled Property
EnablePositionControls Property
EnableSelectionControls Property
EnableTracker Property
EndFlush (CBaseInputPin Class: Implemented IQualityControl Methods)
EndFlush (CBaseOutputPin Class: Implemented IPin Methods)
EndFlush (CBaseRenderer Class: Helper Function)
EndFlush (COutputQueue Class: Member Functions)
EndFlush (CPullPin Class: Overridable Member Functions)
EndFlush (CRenderedInputPin Class: Overridable Member Functions)
EndFlush (CRendererInputPin Class: Implemented IPin Methods)
EndFlush (CTransformFilter Class: Implemented IBaseFilter Methods)
EndFlush (CTransformInputPin Class: Implemented IMemInputPin Methods)
EndFlush (CVideoTransformFilter Class: Overridable Member Functions)
EndFlush (IAsyncReader Interface: Methods in Vtable Order)
EndFlush (IPin Interface: Methods in Vtable Order)
EndFlush (CBaseInputPin)
EndFlush (CBaseOutputPin)
EndFlush (CBaseRenderer)
EndFlush (COutputQueue)
EndFlush (CPullPin)
EndFlush (CRenderedInputPin)
EndFlush (CRendererInputPin)
EndFlush (CTransformFilter)
EndFlush (CTransformInputPin)
EndFlush (CVideoTransformFilter)
EndFlush (IAsyncReader)
EndFlush (IPin)
EndOfStream (CBaseOutputPin Class: Implemented IPin Methods)
EndOfStream (CPullPin Class: Overridable Member Functions)
EndOfStream (CRenderedInputPin Class: Overridable Member Functions)
EndOfStream (CRendererInputPin Class: Implemented IPin Methods)
EndOfStream (CTransformFilter Class: Implemented IBaseFilter Methods)
EndOfStream (CTransformInputPin Class: Implemented IMemInputPin Methods)
EndOfStream (Helper Function)
EndOfStream (Implemented INonDelegatingUnknown Methods)
EndOfStream (Methods in Vtable Order)
EndOfStream (CBaseOutputPin)
EndOfStream (CBasePin)
EndOfStream (CBaseRenderer)
EndOfStream (CPullPin)
EndOfStream (CRenderedInputPin)
EndOfStream (CRendererInputPin)
EndOfStream (CTransformFilter)
EndOfStream (CTransformInputPin)
EndOfStream (IPin)
End-Of-Stream Notifications
end-of-stream protocol
EndOfStreamTimer
EndPTM
EndRun
EndRun (CCmdQueue)
enum
Enumerator Base Classes
Enumerator Interfaces
EnumFilters
EnumFilters (IFilterGraph)
EnumFiltersByInterface
EnumFiltersByInterface (IAMovie)
EnumMatchingFilters (IFilterMapper Interface: Methods in Vtable Order)
EnumMatchingFilters (IFilterMapper2 Interface: Methods in Vtable Order)
EnumMatchingFilters (IFilterMapper)
EnumMatchingFilters (IFilterMapper2)
EnumMediaStreams
EnumMediaStreams (IMultiMediaStream)
EnumMediaTypes (Implemented IMemInputPin Methods)
EnumMediaTypes (Implemented INonDelegatingUnknown Methods)
EnumMediaTypes (Implemented IPin Methods)
EnumMediaTypes (Methods in Vtable Order)
EnumMediaTypes (CBasePin)
EnumMediaTypes (CTransInPlaceInputPin)
EnumMediaTypes (CTransInPlaceOutputPin)
EnumMediaTypes (IPin)
EnumPins (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
EnumPins (IAMovie Interface: Methods in Vtable Order)
EnumPins (IBaseFilter Interface: Methods in Vtable Order)
EnumPins (CBaseFilter)
EnumPins (IAMovie)
EnumPins (IBaseFilter)
EnumPinsIn
EnumPinsIn (IAMovie)
EnumPinsOut
EnumPinsOut (IAMovie)
EnumProperty
EnumProperty (IMediaPropertyBag)
EOS
EOS (COutputQueue)
EqualPins
Err
Error and Success Codes
Error and Success Codes for Multimedia Streaming
error detection and reporting protocol
Error Event
Error Message Function
Establishing Media Type Connections
event notification
Event Notification Codes
Event Notifications
EXECUTE_ASSERT
Exit
Exit (CSourceStream)
Explicitly Connecting Two Pins
Exposing Capture and Compression Formats
EzRGB24 Sample (Image Effect Filter)

F

FAILED
Famine
FAQ, DirectShow
FastRender
FastRender (CDrawImage)
field
File Source (Async)
File Source (URL)
File Stream Renderer
File Writer
file writer (F)
FileName Property
Filename Property (IFilterInfo Object)
Files in CPlay
FILETIME
FillBuffer
FillBuffer (CSourceStream)
filter
Filter (Methods in Vtable Order)
Filter (IRegFilterInfo)
Filter and Pin Interfaces
Filter Base Classes
filter categories
Filter Development Questions
filter graph
Filter Graph Control Data
Filter Graph Editor
filter graph manager
Filter Graph Manager and Filter Graphs
Filter Graph Manager Interfaces
Filter graphs, control from C++
Filter Interfaces
Filter Method (IRegFilterInfo Object)
Filter Property (IFilterInfo Object)
Filter property pages, display from C++
FILTER_INFO
FILTER_STATE
FilterCollection Property (IMediaControl Object)
FilterGraph Property
FilterGraphDispatch Property
FilterInfo Property (IPinInfo Object)
Filter-Level Interfaces
Filters
Filters and Pins
Filters, build in Visual C++
Filters, DirectShow
Find
Find (CGenericList)
FindFilterByName
FindFilterByName (IFilterGraph)
FindI
FindI (CBaseList)
Finding a Filter That Can Be Stretched Full-Screen at No Cost
Finding a Filter That Supports Full-Screen Mode
FindInterface
FindInterface (ICaptureGraphBuilder)
FindPin (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
FindPin (CBaseRenderer Class: Helper Function)
FindPin (CTransformFilter Class: Implemented IBaseFilter Methods)
FindPin (IBaseFilter Interface: Methods in Vtable Order)
FindPin (IFilterInfo Interface: Methods in Vtable Order)
FindPin (CBaseFilter)
FindPin (CBaseRenderer)
FindPin (CTransformFilter)
FindPin (IBaseFilter)
FindPin (IFilterInfo)
FindPin Method (IFilterInfo Object)
FindPinNumber
FindPinNumber (CSource)
Flood
Flushing (Control Information Data)
Flushing (Member Functions)
Flushing (CBaseStreamControl)
flushing protocol
ForceRefresh
ForceRefresh (CPosPassThru)
Format
Format (CMediaType)
format type
Format types
FormatLength
FormatLength (CMediaType)
FormatType
formattype (AM_MEDIA_TYPE)
FormatType (CMediaType)
ForwardScan
ForwardScan (IDvdControl)
FOURCC
FOURCC codes in DirectShow
FOURCCMap (FOURCCMap)
FOURCCMap Class
FOURCCMap::FOURCCMap
FOURCCMap::GetFOURCC
FOURCCMap::SetFOURCC
frame blitting
FrameRateCode
Frames1
Frames10
Free (CImageAllocator Class: Implemented IMemAllocator Methods)
Free (CMemAllocator Class: Implemented IMemAllocator Methods)
Free (Implemented INonDelegatingUnknown Methods)
Free (Methods in Vtable Order)
Free (CBaseAllocator)
Free (CImageAllocator)
Free (CMemAllocator)
Free (IAMDevMemoryAllocator)
FreeBSTR
FreeEventParams (IAMovie Interface: Methods in Vtable Order)
FreeEventParams (IMediaEvent Interface: Methods in Vtable Order)
FreeEventParams (IAMovie)
FreeEventParams (IMediaEvent)
FreeMediaType
FreeSamples
FreeSamples (COutputQueue)
Frequently Asked Questions
Full Screen Renderer
Full-Screen Video Renderer
FullScreenMode Property
FullScreenMode Property (IVideoWindow Object)

G

Gargle filter to GetAllocator
GetAllocator (CBaseInputPin) to GetMediaTime (CMediaSample)
GetMediaTime (CPosPassThru) to GetTrueColorType
GetTypeInfo (CBaseBasicVideo) to GuidNames

H

HANDLE
Handling Dynamic Format Changes
Handling EC_REPAINT Notifications
Handling End-of-stream and Flushing Notifications
Handling Events
Handling Notifications in Full-Screen Mode
Handling Persistent Properties
Handling State Changes and Pause Completion
Handling Termination
HasDialog
HasDialog (IAMVfwCaptureDialogs)
HasFadeIn
HasFadeIn (IAMAudioCutListElement)
HasFadeOut
HasFadeOut (IAMAudioCutListElement)
HaveCurrentSample
HaveCurrentSample (CBaseRenderer)
HBITMAP
hBitmap (DIBDATA)
hdr (MPEG1VIDEOINFO)
hdr (MPEG2VIDEOINFO)
HEADER
Height Property (IVideoWindow Object)
Help
Help (CBasePropertyPage)
HideCursor (Implemented IVideoWindow Methods)
HideCursor (Methods in Vtable Order)
HideCursor (CBaseControlWindow)
HideCursor (IVideoWindow)
HideCursor Method (IVideoWindow Object)
HideOnDeactivate
HideOnDeactivate (IFullScreenVideo)
HighColorValue
HLISS
hMapping
Hours1
Hours10
How Allocator Negotiation Works
How Data Moves in a Filter Graph
How the Base Classes Implement Connection
How to Write a Compression Filter
How to Write a Video Capture Filter
How to Write an Audio Capture Filter
HRESULT
hrVPEStatus
hue

I

IAMAudioCutListElement Interface to ICutListGraphBuilder::RemoveCutList
ICutListGraphBuilder::Render to IMediaSample::IsSyncPoint
IMediaSample::SetActualDataLength to IsFormatSupported
IsFormatSupported (CPosPassThru) to IVPNotify2::SetVPSyncMaster

J

JoinAMMultiMediaStream
JoinAMMultiMediaStream (IAMMediaStream)
JoinFilter
JoinFilter (IAMMediaStream)
JoinFilterGraph (IAMMediaStream Interface: Methods in Vtable Order)
JoinFilterGraph (IBaseFilter Interface: Methods in Vtable Order)
JoinFilterGraph (Implemented INonDelegatingUnknown Methods)
JoinFilterGraph (Implemented IQualityControl Methods)
JoinFilterGraph (CBaseFilter)
JoinFilterGraph (CBaseVideoRenderer)
JoinFilterGraph (IAMMediaStream)
JoinFilterGraph (IBaseFilter)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

K

KaraokeAudioPresentationModeChange
KaraokeAudioPresentationModeChange (IDvdControl)
KASSERT
KDbgBreak
kernel mode
Kernel streaming
Kernel streaming (Filter Graph Configuration)
Kernel streaming (WDM Overview)
Kernel streaming (WDM Video Capture Architecture)
KeyFlags
keyframe
KeyType

L

lActual
Late
Left Property (IVideoWindow Object)
LeftButtonSelect
LeftButtonSelect (IDvdControl)
Length
Length (IAsyncReader)
letterbox
lHalfLinesEven
lHalfLinesOdd
Line 21 Decoder
Linear editing
List and Queue Classes
List of Filters and Samples
Listing Filters in the Filter Graph
Listing Pins Defined for a Filter
llMulDiv
Load (Implemented IPersistStream Methods)
Load (Methods in Vtable Order)
Load (CPersistStream)
Load (IFileSourceFilter)
LoadDirectDraw
LoadDirectDraw (CLoadDirectDraw)
LoadLibrary
LoadOLEAut32
Lock
Lock (CCritSec)
LOG_ERROR
LOG_LOCKING
LOG_MEMORY
LOG_TIMING
LOG_TRACE
long (Appendixes: Further Reading: 1)
Long (Appendixes: Further Reading: 2)
LONG (Appendixes: Further Reading: 3)
LONGLONG
LowColorValue
LowerButtonSelect
LowerButtonSelect (IDvdControl)
LPCTSTR
LPCTSTR (Operators)
LPCTSTR (CDisp)
LPDDSURFACEDESC
lpMediaType (AMOVIESETUP_PIN)
lpMediaType (REGFILTERPINS)
lpMediaType (REGFILTERPINS2)
lpMedium
lpParam
lpPin
LPSTR
LPWSTR
LRESULT
lSampleSize
lstrcmpiW
lstrcmpW
lstrcpynW
lstrcpyW
lstrlenW
LTC
Lyric Parser

M

m_AccessLock to MPEG1VIDEOINFO
MPEG2Level to Multiple Clocks in a Filter Graph

N

NAME
Name (Implemented INonDelegatingUnknown Methods)
Name (REGFILTER)
Name (CBasePin)
Name Property (IFilterInfo Object)
Name Property (IPinInfo Object)
Name Property (IRegFilterInfo Object)
Naming Conventions:Pins
Negotiating Media Types with CBasePin::AgreeMediaType
New
New (CCmdQueue)
new segment protocol
NewSegment (Implemented IBaseFilter Methods)
NewSegment (Implemented IMemInputPin Methods)
NewSegment (Implemented INonDelegatingUnknown Methods)
NewSegment (Member Functions)
NewSegment (Methods in Vtable Order)
NewSegment (CBasePin)
NewSegment (COutputQueue)
NewSegment (CTransformFilter)
NewSegment (CTransformInputPin)
NewSegment (IPin)
Next (CBaseList Class: Member Functions)
Next (CEnumMediaTypes Class: Implemented IEnumMediaTypes Methods)
Next (CEnumPins Class: Implemented IEnumPins Methods)
Next (IEnumFilters Interface: Methods in Vtable Order)
Next (IEnumMediaTypes Interface: Methods in Vtable Order)
Next (IEnumPins Interface: Methods in Vtable Order)
Next (IEnumRegFilters Interface: Methods in Vtable Order)
Next (CBaseList)
Next (CEnumMediaTypes)
Next (CEnumPins)
Next (IEnumFilters)
Next (IEnumMediaTypes)
Next (IEnumPins)
Next (IEnumRegFilters)
NextPGSearch
NextPGSearch (IDvdControl)
nMediaTypes (AMOVIESETUP_PIN)
nMediaTypes (REGFILTERPINS)
nMediaTypes (REGFILTERPINS2)
nMediums
NonDelegatingAddRef (CBasePin Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingAddRef (CUnknown Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingAddRef (Implemented IMemAllocator Methods)
NonDelegatingAddRef (Implemented IPropertyPage Methods)
NonDelegatingAddRef (CBasePin)
NonDelegatingAddRef (CBasePropertyPage)
NonDelegatingAddRef (CImageAllocator)
NonDelegatingAddRef (CUnknown)
NonDelegatingQueryInterface (CBaseAllocator Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CBaseBasicVideo Class: Implemented IDispatch Methods)
NonDelegatingQueryInterface (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CBaseInputPin Class: Implemented IQualityControl Methods)
NonDelegatingQueryInterface (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CBasePin Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CBasePropertyPage Class: Implemented IPropertyPage Methods)
NonDelegatingQueryInterface (CBaseRenderer Class: Helper Function)
NonDelegatingQueryInterface (CBaseVideoRenderer Class: Implemented IQualityControl Methods)
NonDelegatingQueryInterface (CBaseVideoWindow Class: Implemented IDispatch Methods)
NonDelegatingQueryInterface (CBasicAudio Class: Implemented IDispatch Methods)
NonDelegatingQueryInterface (CDeferredCommand Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CMediaEvent Class: Implemented IDispatch Methods)
NonDelegatingQueryInterface (CMediaPosition Class: Implemented IDispatch Methods)
NonDelegatingQueryInterface (CMediaSample Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CSystemClock Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (CUnknown Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingQueryInterface (Implemented IDirectDraw Methods)
NonDelegatingQueryInterface (Implemented IDirectDrawSurface Methods)
NonDelegatingQueryInterface (CAggDirectDraw)
NonDelegatingQueryInterface (CAggDrawSurface)
NonDelegatingQueryInterface (CBaseAllocator)
NonDelegatingQueryInterface (CBaseBasicVideo)
NonDelegatingQueryInterface (CBaseFilter)
NonDelegatingQueryInterface (CBaseInputPin)
NonDelegatingQueryInterface (CBaseMediaFilter)
NonDelegatingQueryInterface (CBasePin)
NonDelegatingQueryInterface (CBasePropertyPage)
NonDelegatingQueryInterface (CBaseReferenceClock)
NonDelegatingQueryInterface (CBaseRenderer)
NonDelegatingQueryInterface (CBaseVideoRenderer)
NonDelegatingQueryInterface (CBaseVideoWindow)
NonDelegatingQueryInterface (CBasicAudio)
NonDelegatingQueryInterface (CDeferredCommand)
NonDelegatingQueryInterface (CMediaControl)
NonDelegatingQueryInterface (CMediaEvent)
NonDelegatingQueryInterface (CMediaPosition)
NonDelegatingQueryInterface (CMediaSample)
NonDelegatingQueryInterface (CPosPassThru)
NonDelegatingQueryInterface (CSourceSeeking)
NonDelegatingQueryInterface (CSystemClock)
NonDelegatingQueryInterface (CTransformOutputPin)
NonDelegatingQueryInterface (CUnknown)
NonDelegatingRelease (CBasePin Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingRelease (CUnknown Class: Implemented INonDelegatingUnknown Methods)
NonDelegatingRelease (Implemented IMemAllocator Methods)
NonDelegatingRelease (Implemented IPropertyPage Methods)
NonDelegatingRelease (CBasePin)
NonDelegatingRelease (CBasePropertyPage)
NonDelegatingRelease (CImageAllocator)
NonDelegatingRelease (CUnknown)
nonlinear editing
NOTE through NOTE5 Macros
Notify (CBaseInputPin Class: Implemented IQualityControl Methods)
Notify (CBasePin Class: Implemented INonDelegatingUnknown Methods)
Notify (CBaseVideoRenderer Class: Implemented IQualityControl Methods)
Notify (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
Notify (IMediaEventSink Interface: Methods in Vtable Order)
Notify (IQualityControl Interface: Methods in Vtable Order)
Notify (CBaseInputPin)
Notify (CBasePin)
Notify (CBaseVideoRenderer)
Notify (CTransformOutputPin)
Notify (IMediaEventSink)
Notify (IQualityControl)
NotifyAcquire
NotifyAcquire (IResourceManager)
NotifyAllocator (Implemented IMemInputPin Methods)
NotifyAllocator (Implemented IQualityControl Methods)
NotifyAllocator (Member Functions)
NotifyAllocator (Methods in Vtable Order)
NotifyAllocator (CBaseInputPin)
NotifyAllocator (CDrawImage)
NotifyAllocator (CTransInPlaceInputPin)
NotifyAllocator (IMemInputPin)
NotifyEndDraw
NotifyEndDraw (CDrawImage)
NotifyEndOfStream
NotifyEndOfStream (CBaseRenderer)
NotifyEvent
NotifyEvent (CBaseFilter)
NotifyFilterState
NotifyFilterState (CBaseStreamControl)
NotifyGraphChange
NotifyGraphChange (IDistributorNotify)
NotifyMediaType (Implemented IMemAllocator Methods)
NotifyMediaType (Member Functions)
NotifyMediaType (CDrawImage)
NotifyMediaType (CImageAllocator)
NotifyOwnerMessage (Implemented IVideoWindow Methods)
NotifyOwnerMessage (Methods in Vtable Order)
NotifyOwnerMessage (CBaseControlWindow)
NotifyOwnerMessage (IVideoWindow)
NotifyOwnerMessage Method (IVideoWindow Object)
NotifyRelease
NotifyRelease (IResourceManager)
NotifySample
NotifySample (CBaseAllocator)
NotifyStartDraw
NotifyStartDraw (CDrawImage)
NotifyThread
NotifyThread (COutputQueue)
NotReady
NotReady (CBaseRenderer)
nPins
NTSC
Null In Place filter
Nullip Sample (Null In Place Filter)
Nullnull Sample (Minimal Null Filter)
Number

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

O

Object and Pin Functions
object register
Object Register Debugging
ObjectsActive
ObjectsActive (CBaseObject)
Obtaining Capture Statistics
offline editing
OleCreatePropertyFrame
OnActivate
OnActivate (CBasePropertyPage)
OnApplyChanges
OnApplyChanges (CBasePropertyPage)
OnClipChange
OnClipChange (IOverlayNotify)
OnClose
OnClose (CBaseWindow)
OnColorKeyChange
OnColorKeyChange (IOverlayNotify)
OnConnect
OnConnect (CBasePropertyPage)
OnDeactivate
OnDeactivate (CBasePropertyPage)
OnDirectRender
OnDirectRender (CBaseVideoRenderer)
OnDisconnect
OnDisconnect (CBasePropertyPage)
OnError
OnError (CPullPin)
online editing
OnPaletteChange (Methods in Vtable Order)
OnPaletteChange (Overridable Member Functions)
OnPaletteChange (CBaseWindow)
OnPaletteChange (IOverlayNotify)
OnPositionChange
OnPositionChange (IOverlayNotify)
OnReceiveFirstSample
OnReceiveFirstSample (CBaseRenderer)
OnReceiveMessage (Implemented IPropertyPage Methods)
OnReceiveMessage (Overridable Member Functions)
OnReceiveMessage (CBasePropertyPage)
OnReceiveMessage (CBaseWindow)
OnRenderEnd (Helper Function)
OnRenderEnd (Implemented IQualityControl Methods)
OnRenderEnd (CBaseRenderer)
OnRenderEnd (CBaseVideoRenderer)
OnRenderStart (Helper Function)
OnRenderStart (Implemented IQualityControl Methods)
OnRenderStart (CBaseRenderer)
OnRenderStart (CBaseVideoRenderer)
OnSize
OnSize (CBaseWindow)
OnStartStreaming (Helper Function)
OnStartStreaming (Implemented IQualityControl Methods)
OnStartStreaming (CBaseRenderer)
OnStartStreaming (CBaseVideoRenderer)
OnStopStreaming (Helper Function)
OnStopStreaming (Implemented IQualityControl Methods)
OnStopStreaming (CBaseRenderer)
OnStopStreaming (CBaseVideoRenderer)
OnThreadCreate
OnThreadCreate (CSourceStream)
OnThreadDestroy
OnThreadDestroy (CSourceStream)
OnThreadInit
OnThreadInit (CMsgThread)
OnThreadStartPlay
OnThreadStartPlay (CSourceStream)
OnUpdateRectangles
OnUpdateRectangles (CBaseControlVideo)
OnVideoSizeChange
OnVideoSizeChange (CBaseControlVideo)
OnWaitEnd (Helper Function)
OnWaitEnd (Implemented IQualityControl Methods)
OnWaitEnd (CBaseRenderer)
OnWaitEnd (CBaseVideoRenderer)
OnWaitStart (Helper Function)
OnWaitStart (Implemented IQualityControl Methods)
OnWaitStart (CBaseRenderer)
OnWaitStart (CBaseVideoRenderer)
OpenComplete Event
OpenFile
OpenFile (IAMMultiMediaStream)
OPENFILENAME
Opening and Running DirectShow Source Files
OpenMoniker
OpenMoniker (IAMMultiMediaStream)
operator != (CMediaType)
Operator != (COARefTime)
Operator – (COARefTime)
Operator –= (COARefTime)
operator –= (CRefTime)
Operator > (COARefTime)
Operator >= (COARefTime)
Operator < (COARefTime)
Operator <= (COARefTime)
operator (REFERENCE_TIME) (CRefTime)
Operator * (COARefTime)
Operator / (COARefTime)
Operator + (COARefTime)
Operator += (COARefTime)
operator += (CRefTime)
operator = (CMediaType)
Operator = (COARefTime)
operator = (CRefTime)
operator == (CMediaType)
Operator == (COARefTime)
operator HANDLE (CAMEvent)
operator[ ] (CGuidNameList)
Oscilloscope filter
output pin
OutputDebugString
OutputGranularityX
OutputGranularityY
OutputPin
OutputPin (CTransInPlaceFilter)
OutputZeroTime
Overlay Mixer
Override the Base Class Member Functions
OverrideFrameSize
OverrideFrameSize (IAMVideoCompression)
OverrideKeyFrame
OverrideKeyFrame (IAMVideoCompression)
Overriding the CheckInputType Member Function
Overriding the CheckTransform Member Function
Overriding the DecideBufferSize Member Function
Overriding the GetMediaType Member Function
Overriding the Transform Member Function
Owner Property (IVideoWindow Object)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

P

PaintWindow
PaintWindow (CBaseWindow)
PAL
PALETTE_ENTRIES
PALETTEENTRY
PaletteIndex
PaletteVersion
PALETTISED
pan-scan
ParentalCountrySelect
ParentalCountrySelect (IDvdControl)
ParentalLevelSelect
ParentalLevelSelect (IDvdControl)
parser filter
Pass Debugging Names
PassNotify
PassNotify (CBaseInputPin)
patcol
patcon
Pause (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
Pause (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
Pause (CBaseRenderer Class: Helper Function)
Pause (CSourceStream Class: Implemented IPin Methods)
Pause (CTransformFilter Class: Implemented IBaseFilter Methods)
Pause (IAMovie Interface: Methods in Vtable Order)
Pause (IDistributorNotify Interface: Methods in Vtable Order)
Pause (IMediaControl Interface: Methods in Vtable Order)
Pause (IMediaFilter Interface: Methods in Vtable Order)
Pause (CBaseFilter)
Pause (CBaseMediaFilter)
Pause (CBaseRenderer)
Pause (CSourceStream)
Pause (CTransformFilter)
Pause (IAMovie)
Pause (IDistributorNotify)
Pause (IMediaControl)
Pause (IMediaFilter)
Pause Method
Pause Method (IMediaControl Object)
PauseOff
PauseOff (IDvdControl)
PauseOn
PauseOn (IDvdControl)
pBase
pbATRI
pbBuffer
pbFormat
PCMWAVEFORMAT
PeekAllocator (Implemented IMemInputPin Methods)
PeekAllocator (Implemented IPin Methods)
PeekAllocator (CTransInPlaceInputPin)
PeekAllocator (CTransInPlaceOutputPin)
PeekMessage
PERF
performance build
Performance Macros
PerformanceAlignWindow
PerformanceAlignWindow (CBaseWindow)
periodic advise
pEvent
pFilter
pGraph
PID Sample (Plug-In Distributor Application)
pin
Pin Base Classes
Pin Interfaces
Pin Names
Pin Property (IPinInfo Object)
Pin Property Set
PIN_CATEGORY_ANALOGVIDEOIN
PIN_CATEGORY_CAPTURE
PIN_CATEGORY_CC
PIN_CATEGORY_EDS
PIN_CATEGORY_NABTS
PIN_CATEGORY_PREVIEW
PIN_CATEGORY_STILL
PIN_CATEGORY_TELETEXT
PIN_CATEGORY_TIMECODE
PIN_CATEGORY_VBI
PIN_CATEGORY_VIDEOPORT
PIN_DIRECTION
PIN_INFO
PINDIR_INPUT
PINDIR_OUTPUT
PinID Property (IPinInfo Object)
Pins Property (IFilterInfo Object)
Play
Play (IAMovie)
Play a Movie from C++
Play a Movie in a Window Using DirectDrawEx and Multimedia Streaming
Playback windows, control from C++
PlayCount Property
PlayFile
PlayFile (IAMovie)
PlayFile Sample (Simple Playback Application)
Playing Back Files Over the Internet
Playing, Pausing, and Stopping the Video Stream
plug-in distributor
Plug-in Distributors
Plug-in Distributors and Extensibility
pMediaType
Pointer Validation
Pointer Validation Macros
Porting Code from ActiveMovie
POSITION
PositionChange Event
PossiblyEatMessage (Implemented IVideoWindow Methods)
PossiblyEatMessage (Overridable Member Functions)
PossiblyEatMessage (CBaseControlWindow)
PossiblyEatMessage (CBaseWindow)
Post production editing (External Device Control)
Post production editing (Introduction)
PostMessage
Postpone (Implemented INonDelegatingUnknown Methods)
Postpone (Methods in Vtable Order)
Postpone (CDeferredCommand)
Postpone (IDeferredCommand)
PreparePalette
PreparePalette (CImagePalette)
PreparePerformanceData
PreparePerformanceData (CBaseVideoRenderer)
PrepareReceive
PrepareReceive (CBaseRenderer)
PrepareRender
PrepareRender (CBaseRenderer)
PrepareWindow
PrepareWindow (CBaseWindow)
Preparing to Use the DirectShow Objects
preroll
preroll time
PrerollTime Property (IMediaPosition Object)
presentation time
Prev
Prev (CBaseList)
preview section
PrevPGSearch
PrevPGSearch (IDvdControl)
primary surface
printf
Progress
Progress (IAMCopyCaptureFileProgress)
Property Page Helper Functions
Property pages for filters, display from C++
Property Sets
Proportion
PROPPAGEINFO
pStateLock
pStateLock (CSource)
pUnk
put_AntiClogControl
put_AntiClogControl (IAMExtTransport)
put_AutoShow (Implemented IVideoWindow Methods)
put_AutoShow (Methods in Vtable Order)
put_AutoShow (CBaseControlWindow)
put_AutoShow (IVideoWindow)
put_BackgroundPalette (Implemented IVideoWindow Methods)
put_BackgroundPalette (Methods in Vtable Order)
put_BackgroundPalette (CBaseControlWindow)
put_BackgroundPalette (IVideoWindow)
put_Balance
put_Balance (IBasicAudio)
put_Bass
put_Bass (IAMAudioInputMixer)
put_BorderColor (Implemented IVideoWindow Methods)
put_BorderColor (Methods in Vtable Order)
put_BorderColor (CBaseControlWindow)
put_BorderColor (IVideoWindow)
put_Caption (Implemented IVideoWindow Methods)
put_Caption (Methods in Vtable Order)
put_Caption (CBaseControlWindow)
put_Caption (IVideoWindow)
put_Channel
put_Channel (IAMTVTuner)
put_ConnectInput
put_ConnectInput (IAMTVTuner)
put_CountryCode
put_CountryCode (IAMTVTuner)
put_CurrentPosition (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
put_CurrentPosition (CSourcePosition Class: Implemented IMediaPosition Methods)
put_CurrentPosition (IAMovie Interface: Methods in Vtable Order)
put_CurrentPosition (IMediaPosition Interface: Methods in Vtable Order)
put_CurrentPosition (CPosPassThru)
put_CurrentPosition (CSourcePosition)
put_CurrentPosition (IAMovie)
put_CurrentPosition (IMediaPosition)
put_DestinationHeight (Implemented IBasicVideo Methods)
put_DestinationHeight (Methods in Vtable Order)
put_DestinationHeight (CBaseControlVideo)
put_DestinationHeight (IBasicVideo)
put_DestinationLeft (Implemented IBasicVideo Methods)
put_DestinationLeft (Methods in Vtable Order)
put_DestinationLeft (CBaseControlVideo)
put_DestinationLeft (IBasicVideo)
put_DestinationTop (Implemented IBasicVideo Methods)
put_DestinationTop (Methods in Vtable Order)
put_DestinationTop (CBaseControlVideo)
put_DestinationTop (IBasicVideo)
put_DestinationWidth (Implemented IBasicVideo Methods)
put_DestinationWidth (Methods in Vtable Order)
put_DestinationWidth (CBaseControlVideo)
put_DestinationWidth (IBasicVideo)
put_DevicePort
put_DevicePort (IAMExtDevice)
put_DevicePower
put_DevicePower (IAMExtDevice)
put_EditStart
put_EditStart (IAMExtTransport)
put_Enable
put_Enable (IAMAudioInputMixer)
put_Filename
put_Filename (IFilterInfo)
put_FullScreenMode (Implemented IVideoWindow Methods)
put_FullScreenMode (Methods in Vtable Order)
put_FullScreenMode (CBaseControlWindow)
put_FullScreenMode (IVideoWindow)
put_Height (Implemented IVideoWindow Methods)
put_Height (Methods in Vtable Order)
put_Height (CBaseControlWindow)
put_Height (IVideoWindow)
put_InputType
put_InputType (IAMTVTuner)
put_Interleaving
put_Interleaving (IConfigInterleaving)
put_KeyFrameRate
put_KeyFrameRate (IAMVideoCompression)
put_Left (Implemented IVideoWindow Methods)
put_Left (Methods in Vtable Order)
put_Left (CBaseControlWindow)
put_Left (IVideoWindow)
put_LocalControl
put_LocalControl (IAMExtTransport)
put_Loudness
put_Loudness (IAMAudioInputMixer)
put_MediaState
put_MediaState (IAMExtTransport)
put_MessageDrain (Implemented IVideoWindow Methods)
put_MessageDrain (Methods in Vtable Order)
put_MessageDrain (CBaseControlWindow)
put_MessageDrain (IVideoWindow)
put_MixLevel
put_MixLevel (IAMAudioInputMixer)
put_Mode (IAMExtTransport Interface: Methods in Vtable Order)
put_Mode (IConfigInterleaving Interface: Methods in Vtable Order)
put_Mode (IAMExtTransport)
put_Mode (IConfigInterleaving)
put_Mono
put_Mono (IAMAudioInputMixer)
put_Owner (Implemented IVideoWindow Methods)
put_Owner (Methods in Vtable Order)
put_Owner (CBaseControlWindow)
put_Owner (IVideoWindow)
put_Pan
put_Pan (IAMAudioInputMixer)
put_PFramesPerKeyFrame
put_PFramesPerKeyFrame (IAMVideoCompression)
put_PrerollTime (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
put_PrerollTime (CSourcePosition Class: Implemented IMediaPosition Methods)
put_PrerollTime (IAMovie Interface: Methods in Vtable Order)
put_PrerollTime (IMediaPosition Interface: Methods in Vtable Order)
put_PrerollTime (CPosPassThru)
put_PrerollTime (CSourcePosition)
put_PrerollTime (IAMovie)
put_PrerollTime (IMediaPosition)
put_Quality
put_Quality (IAMVideoCompression)
put_Rate (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
put_Rate (CSourcePosition Class: Implemented IMediaPosition Methods)
put_Rate (IAMExtTransport Interface: Methods in Vtable Order)
put_Rate (IAMovie Interface: Methods in Vtable Order)
put_Rate (IMediaPosition Interface: Methods in Vtable Order)
put_Rate (CPosPassThru)
put_Rate (CSourcePosition)
put_Rate (IAMExtTransport)
put_Rate (IAMovie)
put_Rate (IMediaPosition)
put_SourceHeight (Implemented IBasicVideo Methods)
put_SourceHeight (Methods in Vtable Order)
put_SourceHeight (CBaseControlVideo)
put_SourceHeight (IBasicVideo)
put_SourceLeft (Implemented IBasicVideo Methods)
put_SourceLeft (Methods in Vtable Order)
put_SourceLeft (CBaseControlVideo)
put_SourceLeft (IBasicVideo)
put_SourceTop (Implemented IBasicVideo Methods)
put_SourceTop (Methods in Vtable Order)
put_SourceTop (CBaseControlVideo)
put_SourceTop (IBasicVideo)
put_SourceWidth (Implemented IBasicVideo Methods)
put_SourceWidth (Methods in Vtable Order)
put_SourceWidth (CBaseControlVideo)
put_SourceWidth (IBasicVideo)
put_StopTime (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
put_StopTime (CSourcePosition Class: Implemented IMediaPosition Methods)
put_StopTime (IAMovie Interface: Methods in Vtable Order)
put_StopTime (IMediaPosition Interface: Methods in Vtable Order)
put_StopTime (CPosPassThru)
put_StopTime (CSourcePosition)
put_StopTime (IAMovie)
put_StopTime (IMediaPosition)
put_Top (Implemented IVideoWindow Methods)
put_Top (Methods in Vtable Order)
put_Top (CBaseControlWindow)
put_Top (IVideoWindow)
put_Treble
put_Treble (IAMAudioInputMixer)
put_TuningSpace
put_TuningSpace (IAMTVTuner)
put_Visible (Implemented IVideoWindow Methods)
put_Visible (Methods in Vtable Order)
put_Visible (CBaseControlWindow)
put_Visible (IVideoWindow)
put_VITCLine
put_VITCLine (IAMTimecodeGenerator)
put_VITCLine (IAMTimecodeReader)
put_Volume
put_Volume (IBasicAudio)
put_Width (Implemented IVideoWindow Methods)
put_Width (Methods in Vtable Order)
put_Width (CBaseControlWindow)
put_Width (IVideoWindow)
put_WindowSize
put_WindowSize (IAMVideoCompression)
put_WindowState (Implemented IVideoWindow Methods)
put_WindowState (Methods in Vtable Order)
put_WindowState (CBaseControlWindow)
put_WindowState (IVideoWindow)
put_WindowStyle (Implemented IVideoWindow Methods)
put_WindowStyle (Methods in Vtable Order)
put_WindowStyle (CBaseControlWindow)
put_WindowStyle (IVideoWindow)
put_WindowStyleEx (Implemented IVideoWindow Methods)
put_WindowStyleEx (Methods in Vtable Order)
put_WindowStyleEx (CBaseControlWindow)
put_WindowStyleEx (IVideoWindow)
PutQueueObject
PutQueueObject (CQueue)
PutThreadMsg
PutThreadMsg (CMsgThread)

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

Q

Quality
Quality Control Data
quality management protocol
quality sink
Quality-Control Management
QualityMessageType
QueryAccept (Implemented INonDelegatingUnknown Methods)
QueryAccept (Methods in Vtable Order)
QueryAccept (CBasePin)
QueryAccept (IPin)
QueryDirection (Implemented INonDelegatingUnknown Methods)
QueryDirection (Methods in Vtable Order)
QueryDirection (CBasePin)
QueryDirection (IPin)
QueryFilterInfo (Implemented INonDelegatingUnknown Methods)
QueryFilterInfo (Methods in Vtable Order)
QueryFilterInfo (CBaseFilter)
QueryFilterInfo (IBaseFilter)
QueryId (CBasePin Class: Implemented INonDelegatingUnknown Methods)
QueryId (CTransformOutputPin Class: Implemented INonDelegatingUnknown Methods)
QueryId (Implemented IMemInputPin Methods)
QueryId (Implemented IPin Methods)
QueryId (Methods in Vtable Order)
QueryId (CBasePin)
QueryId (CRendererInputPin)
QueryId (CTransformInputPin)
QueryId (CTransformOutputPin)
QueryId (IPin)
QueryInterface
QueryInterface (CEnumMediaTypes)
QueryInterface (CEnumPins)
QueryInterface (CMediaSample)
QueryInterface (IUnknown)
QueryInternalConnections (Implemented INonDelegatingUnknown Methods)
QueryInternalConnections (Methods in Vtable Order)
QueryInternalConnections (CBasePin)
QueryInternalConnections (IPin)
QueryPinInfo (Implemented INonDelegatingUnknown Methods)
QueryPinInfo (Methods in Vtable Order)
QueryPinInfo (CBasePin)
QueryPinInfo (IPin)
QueryPreferredFormat (CPosPassThru Class: Implemented INonDelegatingUnknown Methods)
QueryPreferredFormat (CSourceSeeking Class: Implemented INonDelegatingUnknown Methods)
QueryPreferredFormat (Methods in Vtable Order)
QueryPreferredFormat (CPosPassThru)
QueryPreferredFormat (CSourceSeeking)
QueryPreferredFormat (IMediaSeeking)
QuerySupported
QuerySupported (IKsPropertySet)
QueryVendorInfo (Implemented INonDelegatingUnknown Methods)
QueryVendorInfo (Methods in Vtable Order)
QueryVendorInfo (CBaseFilter)
QueryVendorInfo (IBaseFilter)
QueryVersion
QueryVersion (IGraphVersion)
QueryWriteSync
QueryWriteSync (IAMDevMemoryControl)
QueueSample
QueueSample (COutputQueue)
Quick Start: Insert and Use the ActiveMovie Control
QuickTime Decompressor
QuickTime Movie Parser
qwTick

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

R

Rate Property
Rate Property (IMediaPosition Object)
rcSource (ANALOGVIDEOINFO)
rcSource (VIDEOINFO)
rcSource (VIDEOINFOHEADER)
rcSource (VIDEOINFOHEADER2)
rcTarget (ANALOGVIDEOINFO)
rcTarget (VIDEOINFO)
rcTarget (VIDEOINFOHEADER)
rcTarget (VIDEOINFOHEADER2)
rcValidRegion
ReadFromStream
ReadFromStream (CPersistStream)
ReadInt
ReadOnly
ReadOnly (CTransInPlaceInputPin)
Ready
Ready (CBaseRenderer)
ReadyState Property
ReadyStateChange Event
ReallocFormatBuffer
ReallocFormatBuffer (CMediaType)
ReallyFree
ReallyFree (CMemAllocator)
Receive (CPullPin Class: Overridable Member Functions)
Receive (CTransInPlaceFilter Class: Overridable Member Functions)
Receive (CVideoTransformFilter Class: Overridable Member Functions)
Receive (Helper Function)
Receive (Implemented IBaseFilter Methods)
Receive (Implemented IMemInputPin Methods)
Receive (Implemented IPin Methods)
Receive (Implemented IQualityControl Methods)
Receive (Member Functions)
Receive (Methods in Vtable Order)
Receive (CBaseInputPin)
Receive (CBaseRenderer)
Receive (COutputQueue)
Receive (CPullPin)
Receive (CRendererInputPin)
Receive (CTransformFilter)
Receive (CTransformInputPin)
Receive (CTransInPlaceFilter)
Receive (CVideoTransformFilter)
Receive (IMemInputPin)
ReceiveAllocator
ReceiveAllocator (CTransInPlaceOutputPin)
ReceiveCanBlock (Implemented IQualityControl Methods)
ReceiveCanBlock (Methods in Vtable Order)
ReceiveCanBlock (CBaseInputPin)
ReceiveCanBlock (IMemInputPin)
ReceiveConnection (Implemented INonDelegatingUnknown Methods)
ReceiveConnection (Methods in Vtable Order)
ReceiveConnection (CBasePin)
ReceiveConnection (IPin)
ReceiveMultiple (Implemented IQualityControl Methods)
ReceiveMultiple (Member Functions)
ReceiveMultiple (Methods in Vtable Order)
ReceiveMultiple (CBaseInputPin)
ReceiveMultiple (COutputQueue)
ReceiveMultiple (IMemInputPin)
Recommended Compressor Interfaces
Reconnect
Reconnect (IFilterGraph)
ReconnectEx
ReconnectEx (IFilterGraph2)
ReconnectPin
ReconnectPin (CBaseFilter)
RecordFrameLateness
RecordFrameLateness (CBaseVideoRenderer)
RECT
Redistribution
Redistribution (Frequently Asked Questions)
reference clock
reference time
Reference Time Function
REFERENCE_TIME
RefreshDisplayType
RefreshDisplayType (CImageDisplay)
REG_PINFLAG
REG_PINFLAG_B_MANY
REG_PINFLAG_B_OUTPUT
REG_PINFLAG_B_RENDERER
REG_PINFLAG_B_ZERO
REGFILTER
REGFILTER2
RegFilterCollection Property (IMediaControl Object)
REGFILTERPINS
REGFILTERPINS2
Register (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
Register (IAMovieSetup Interface: Methods in Vtable Order)
Register (IResourceManager Interface: Methods in Vtable Order)
Register (CBaseFilter)
Register (IAMovieSetup)
Register (IResourceManager)
Register DirectShow Objects
RegisterFilter (IFilterMapper Interface: Methods in Vtable Order)
RegisterFilter (IFilterMapper2 Interface: Methods in Vtable Order)
RegisterFilter (IFilterMapper)
RegisterFilter (IFilterMapper2)
RegisterFilterInstance
RegisterFilterInstance (IFilterMapper)
RegisterGroup
RegisterGroup (IResourceManager)
Registering a Custom File Type
Registering a Video Capture Filter
Registering an Audio Capture Filter
Registering Quartz.dll with Visual Basic
RegisterMediaTime
RegisterMediaTime (CRendererPosPassThru)
RegisterPerfId (Implemented IBaseFilter Methods)
RegisterPerfId (Overridable Member Functions)
RegisterPerfId (CTransformFilter)
RegisterPerfId (CTransInPlaceFilter)
RegisterPerfId (CVideoTransformFilter)
RegisterPin
RegisterPin (IFilterMapper)
RegisterPinType (IFilterMapper)
REGPINMEDIUM
REGPINTYPES
Release
Release (CEnumMediaTypes)
Release (CEnumPins)
Release (CMediaSample)
Release (IUnknown)
ReleaseBuffer (Implemented INonDelegatingUnknown Methods)
ReleaseBuffer (Methods in Vtable Order)
ReleaseBuffer (CBaseAllocator)
ReleaseBuffer (IMemAllocator)
ReleaseDirectDraw
ReleaseDirectDraw (CLoadDirectDraw)
ReleaseDirectSoundInterface
ReleaseDirectSoundInterface (IAMDirectSound)
ReleaseFocus
ReleaseFocus (IResourceManager)
ReleasePrimaryBufferInterface
ReleasePrimaryBufferInterface (IAMDirectSound)
ReleaseResource
ReleaseResource (IResourceConsumer)
ReleaseSecondaryBufferInterface
ReleaseSecondaryBufferInterface (IAMDirectSound)
ReleaseSemaphore
REMIND
Remove (Member Functions)
Remove (Overridable Member Functions)
Remove (CCmdQueue)
Remove (CGenericList)
RemoveAll
RemoveAll (CBaseList)
RemoveAllFilters
RemoveAllFilters (IAMovie)
RemoveCutList
RemoveCutList (ICutListGraphBuilder)
RemoveElement
RemoveElement (IStandardCutList)
RemoveFilter
RemoveFilter (IFilterGraph)
RemoveHead
RemoveHead (CGenericList)
RemoveHeadI
RemoveHeadI (CBaseList)
RemoveI
RemoveI (CBaseList)
RemovePalette
RemovePalette (CImagePalette)
RemovePin
RemovePin (CSource)
RemoveTail
RemoveTail (CGenericList)
RemoveTailI
RemoveTailI (CBaseList)
Render (CBaseRenderer Class: Helper Function)
Render (IAMMultiMediaStream Interface: Methods in Vtable Order)
Render (IAMovie Interface: Methods in Vtable Order)
Render (ICutListGraphBuilder Interface: Methods in Vtable Order)
Render (IGraphBuilder Interface: Methods in Vtable Order)
Render (IPinInfo Interface: Methods in Vtable Order)
Render (CBaseRenderer)
Render (IAMMultiMediaStream)
Render (IAMovie)
Render (ICutListGraphBuilder)
Render (IGraphBuilder)
Render (IPinInfo)
Render Method (IPinInfo Object)
RenderAll
RenderAll (IAMovie)
RenderDvdVideoVolume
RenderDvdVideoVolume (IDvdGraphBuilder)
renderer
Renderer Filters
RenderFile (IAMovie Interface: Methods in Vtable Order)
RenderFile (IGraphBuilder Interface: Methods in Vtable Order)
RenderFile (IMediaControl Interface: Methods in Vtable Order)
RenderFile (IAMovie)
RenderFile (IGraphBuilder)
RenderFile (IMediaControl)
RenderFile Method (IMediaControl Object)
rendering filter
Rendering Video
RenderNewFile
RenderNewFile (IAMovie)
RenderStream
RenderStream (ICaptureGraphBuilder)
RenegotiateVPParameters
RenegotiateVPParameters (IVPBaseNotify)
Reply
Reply (CAMThread)
Request
Request (IAsyncReader)
RequestAllocator
RequestAllocator (IAsyncReader)
RequestResource
RequestResource (IResourceManager)
Reserved Identifiers
Reset (CAMEvent Class: Member Functions)
Reset (CEnumMediaTypes Class: Implemented IEnumMediaTypes Methods)
Reset (CEnumPins Class: Implemented IEnumPins Methods)
Reset (COutputQueue Class: Member Functions)
Reset (IEnumFilters Interface: Methods in Vtable Order)
Reset (IEnumMediaTypes Interface: Methods in Vtable Order)
Reset (IEnumPins Interface: Methods in Vtable Order)
Reset (IEnumRegFilters Interface: Methods in Vtable Order)
Reset (CAMEvent)
Reset (CEnumMediaTypes)
Reset (CEnumPins)
Reset (COutputQueue)
Reset (IEnumFilters)
Reset (IEnumMediaTypes)
Reset (IEnumPins)
Reset (IEnumRegFilters)
RESET_HEADER
RESET_MASKS
RESET_PALETTE
ResetEndOfStream
ResetEndOfStream (CBaseRenderer)
ResetEndOfStreamTimer (CBaseRenderer)
ResetFormatBuffer
ResetFormatBuffer (CMediaType)
ResetMediaTime
ResetMediaTime (CRendererPosPassThru)
ResetPaletteVersion
ResetPaletteVersion (CDrawImage)
ResetStreamingTimes
ResetStreamingTimes (CBaseVideoRenderer)
RestoreDefaultHandling (IAMovie Interface: Methods in Vtable Order)
RestoreDefaultHandling (IMediaEvent Interface: Methods in Vtable Order)
RestoreDefaultHandling (IAMovie)
RestoreDefaultHandling (IMediaEvent)
RestoreDefaultHandling Method (IMediaEvent Object)
Resume
Resume (IDvdControl)
ResumeThread
ResumeThread (CMsgThread)
retail build
Reverse
Reverse (CBaseList)
Reviewing the Instantiation Process
RGBQUAD
rgPins
rgPins2
RightButtonSelect
RightButtonSelect (IDvdControl)
Route
Route (IAMCrossbar)
Run (CBaseFilter Class: Implemented INonDelegatingUnknown Methods)
Run (CBaseMediaFilter Class: Implemented INonDelegatingUnknown Methods)
Run (CBasePin Class: Implemented INonDelegatingUnknown Methods)
Run (CBaseRenderer Class: Helper Function)
Run (CCmdQueue Class: Overridable Member Functions)
Run (CRenderedInputPin Class: Overridable Member Functions)
Run (CSourceStream Class: Implemented IPin Methods)
Run (IAMovie Interface: Methods in Vtable Order)
Run (IDistributorNotify Interface: Methods in Vtable Order)
Run (IMediaControl Interface: Methods in Vtable Order)
Run (IMediaFilter Interface: Methods in Vtable Order)
Run (CBaseFilter)
Run (CBaseMediaFilter)
Run (CBasePin)
Run (CBaseRenderer)
Run (CCmdQueue)
Run (CRenderedInputPin)
Run (CSourceStream)
Run (IAMovie)
Run (IDistributorNotify)
Run (IMediaControl)
Run (IMediaFilter)
Run Method
Run Method (IMediaControl Object)
run time

S

SAMI (CC) Parser to SetSyncPoint
SetSyncSource (CBaseFilter) to SysFreeString

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

T

tearing
Test With the Filter Graph Editor and Other Sample Filters
Text Display filter
TextOut Sample (Text Display Filter)
The Connection Process: A Summary
The Filter Graph Manager Starts the Connection
The VBDemo Sample Application
The Visual Basic Ocxvb01 Sample
ThreadExists
ThreadExists (CAMThread)
ThreadMessageProc
ThreadMessageProc (CMsgThread)
ThreadProc (Implemented IPin Methods)
ThreadProc (Member Functions)
ThreadProc (CAMThread)
ThreadProc (COutputQueue)
ThreadProc (CSourceStream)
ThrottleWait
ThrottleWait (CBaseVideoRenderer)
Tilde (~) Prefix for Pin Names
Tilde (~) Prefix for Pin Names (Capture and Preview Pin Requirements)
time stamp
Time, DirectShow
timeBeginPeriod
TIMECODE (Structures)
timecode (T)
timecode (TIMECODE_SAMPLE)
TIMECODE_SAMPLE
timeGetTime
TimePlay
TimePlay (IDvdControl)
Timer Event
TimerCallback
TimerCallback (CBaseRenderer)
TimeSearch
TimeSearch (IDvdControl)
timeSetEvent
TimeStamp
TitleKey
TitleNum
TitlePlay
TitlePlay (IDvdControl)
Tools for Building the Samples
Top Property (IVideoWindow Object)
TopPGSearch
TopPGSearch (IDvdControl)
Tracking Status
Transform (Implemented IBaseFilter Methods)
Transform (Overridable Member Functions)
Transform (CTransformFilter)
Transform (CTransInPlaceFilter)
transform filter
Transform Filters
transform-inplace filter
TranslateAccelerator
TranslateAccelerator (CBasePropertyPage)
TranslateMessage
transport
Transport Base Classes
TriggerThread
TriggerThread (CBaseReferenceClock)
trimin
trimout
TRUECOLORINFO (Bitmap Functions, Macros, and Data)
TRUECOLORINFO (Structures: Structures: 1)
TrueColorInfo (Structures: Structures: VIDEOINFO: 2)
TrueMotion 2.0 Decompressor
TryMediaTypes
TryMediaTypes (CBasePin)
tStart (AM_SAMPLE2_PROPERTIES)
tStart (AM_STREAM_INFO)
tStop (AM_SAMPLE2_PROPERTIES)
tStop (AM_STREAM_INFO)
TunerInputAntenna
TunerInputCable
TunerInputType
TV Audio
TV Tuner
TXTDT_MG
Type
Type (Quality)
Type (CMediaType)
Type Property (IMediaTypeInfo Object)

U

U
ulCAT
uMsg
Unadvise (CAMSchedule Class: Member Functions)
Unadvise (CBaseReferenceClock Class: Implemented INonDelegatingUnknown Methods)
Unadvise (IOverlay Interface: Methods in Vtable Order)
Unadvise (IReferenceClock Interface: Methods in Vtable Order)
Unadvise (CAMSchedule)
Unadvise (CBaseReferenceClock)
Unadvise (IOverlay)
Unadvise (IReferenceClock)
Understanding Time and Clocks in DirectShow
UninitialiseWindow
UninitialiseWindow (CBaseWindow)
Unlock
Unlock (CCritSec)
Unregister (Implemented INonDelegatingUnknown Methods)
Unregister (Methods in Vtable Order)
Unregister (CBaseFilter)
Unregister (IAMovieSetup)
UnregisterFilter (IFilterMapper Interface: Methods in Vtable Order)
UnregisterFilter (IFilterMapper2 Interface: Methods in Vtable Order)
UnregisterFilter (IFilterMapper)
UnregisterFilter (IFilterMapper2)
UnregisterFilterInstance
UnregisterFilterInstance (IFilterMapper)
UnregisterPin
UnregisterPin (IFilterMapper)
unused
Update
Update (IStreamSample)
UpdateColourTable
UpdateColourTable (CDrawImage)
UpdateFormat
UpdateFormat (CImageDisplay)
UpperButtonSelect
UpperButtonSelect (IDvdControl)
upstream filter
URL moniker filter
UseOverlayStretch
UseOverlayStretch (IDirectDrawVideo)
userbits
UseScanLine
UseScanLine (IDirectDrawVideo)
UseWhenFullScreen
UseWhenFullScreen (IDirectDrawVideo)
Using a Reference Clock
Using an Object-Oriented Model
Using Cutlists
Using Different Kinds of Builds
Using the ActiveMovie Control in Visual Basic
Using the CTransformFilter and CTransInPlaceFilter Transform Base Classes
Using the Filter Graph Editor
Using the Filter Graph Manager
Using the IVideoWindow PID to Implement Full-Screen Support
Using timecode to control external devices (Capturing Timecode)
Using timecode to control external devices (Typical Uses of Timecode)
Using timecode to control external devices (Understanding SMPTE Timecode)
UsingImageAllocator
UsingImageAllocator (CDrawImage)
Utility Classes

V

V
ValidateReadPtr
ValidateReadWritePtr
ValidateStringPtr
ValidateStringPtrA
ValidateStringPtrW
ValidateWritePtr
VCR Control filter
Vcrctrl Sample (VCR Control Filter)
VendorInfo Property (IFilterInfo Object)
vertical blanking interval
VFW
VFW Video Capture
VFW_E_ADVISE_ALREADY_SET
VFW_E_ALREADY_CANCELLED
VFW_E_ALREADY_COMMITTED
VFW_E_ALREADY_CONNECTED
VFW_E_BAD_KEY
VFW_E_BAD_VIDEOCD
VFW_E_BADALIGN
VFW_E_BUFFER_NOTSET
VFW_E_BUFFER_OVERFLOW
VFW_E_BUFFER_UNDERFLOW
VFW_E_BUFFERS_OUTSTANDING
VFW_E_CANNOT_CONNECT
VFW_E_CANNOT_LOAD_SOURCE_FILTER
VFW_E_CANNOT_RENDER
VFW_E_CHANGING_FORMAT
VFW_E_CIRCULAR_GRAPH
VFW_E_COLOR_KEY_SET
VFW_E_CORRUPT_GRAPH_FILE
VFW_E_DDRAW_CAPS_NOT_SUITABLE
VFW_E_DUPLICATE_NAME
VFW_E_DVD_DECNOTENOUGH
VFW_E_DVD_GRAPHNOTREADY
VFW_E_DVD_INVALIDDOMAIN
VFW_E_DVD_NO_BUTTON
VFW_E_DVD_OPERATION_INHIBITED
VFW_E_DVD_RENDERFAIL
VFW_E_ENUM_OUT_OF_RANGE
VFW_E_ENUM_OUT_OF_SYNC
VFW_E_FILE_TOO_SHORT
VFW_E_FILTER_ACTIVE
VFW_E_IN_FULLSCREEN_MODE
VFW_E_INVALID_CLSID
VFW_E_INVALID_DIRECTION
VFW_E_INVALID_FILE_FORMAT
VFW_E_INVALID_FILE_VERSION
VFW_E_INVALID_MEDIA_TYPE
VFW_E_INVALID_RECT
VFW_E_INVALIDMEDIATYPE
VFW_E_INVALIDSUBTYPE
VFW_E_MEDIA_TIME_NOT_SET
VFW_E_MONO_AUDIO_HW
VFW_E_MPEG_NOT_CONSTRAINED
VFW_E_NEED_OWNER
VFW_E_NO_ACCEPTABLE_TYPES
VFW_E_NO_ADVISE_SET
VFW_E_NO_ALLOCATOR
VFW_E_NO_AUDIO_HARDWARE
VFW_E_NO_CAPTURE_HARDWARE
VFW_E_NO_CLOCK
VFW_E_NO_COLOR_KEY_FOUND
VFW_E_NO_COLOR_KEY_SET
VFW_E_NO_DECOMPRESSOR
VFW_E_NO_DISPLAY_PALETTE
VFW_E_NO_FULLSCREEN
VFW_E_NO_INTERFACE
VFW_E_NO_MODEX_AVAILABLE
VFW_E_NO_PALETTE_AVAILABLE
VFW_E_NO_SINK
VFW_E_NO_TIME_FORMAT
VFW_E_NO_TIME_FORMAT_SET
VFW_E_NO_TRANSPORT
VFW_E_NO_TYPES
VFW_E_NO_VP_HARDWARE
VFW_E_NOT_ALLOWED_TO_SAVE
VFW_E_NOT_COMMITTED
VFW_E_NOT_CONNECTED
VFW_E_NOT_FOUND
VFW_E_NOT_IN_GRAPH
VFW_E_NOT_OVERLAY_CONNECTION
VFW_E_NOT_PAUSED
VFW_E_NOT_RUNNING
VFW_E_NOT_SAMPLE_CONNECTION
VFW_E_NOT_STOPPED
VFW_E_OUT_OF_VIDEO_MEMORY
VFW_E_PALETTE_SET
VFW_E_PROCESSOR_NOT_SUITABLE
VFW_E_READ_ONLY
VFW_E_RPZA
VFW_E_RUNTIME_ERROR
VFW_E_SAMPLE_REJECTED
VFW_E_SAMPLE_REJECTED_EOS
VFW_E_SAMPLE_TIME_NOT_SET
VFW_E_SIZENOTSET
VFW_E_START_TIME_AFTER_END
VFW_E_STATE_CHANGED
VFW_E_TIME_ALREADY_PASSED
VFW_E_TIMEOUT
VFW_E_TOO_MANY_COLORS
VFW_E_TYPE_NOT_ACCEPTED
VFW_E_UNKNOWN_FILE_TYPE
VFW_E_UNSUPPORTED_AUDIO
VFW_E_UNSUPPORTED_STREAM
VFW_E_UNSUPPORTED_VIDEO
VFW_E_VP_NEGOTIATION_FAILED
VFW_E_WRONG_STATE
VFW_S_AUDIO_NOT_RENDERED
VFW_S_CANT_CUE
VFW_S_CONNECTIONS_DEFERRED
VFW_S_DUPLICATE_NAME
VFW_S_ESTIMATED
VFW_S_MEDIA_TYPE_IGNORED
VFW_S_NO_MORE_ITEMS
VFW_S_NO_STOP_TIME
VFW_S_PARTIAL_RENDER
VFW_S_RESERVED
VFW_S_RESOURCE_NOT_NEEDED
VFW_S_RPZA
VFW_S_SOME_DATA_IGNORED
VFW_S_STATE_INTERMEDIATE
VFW_S_STREAM_OFF
VFW_S_VIDEO_NOT_RENDERED
VfwCaptureDialog_Display
VfwCaptureDialog_Format
VfwCaptureDialog_Source
VfwCaptureDialogs
VfwCompressDialog_About
VfwCompressDialog_Config
VfwCompressDialogs
VFWROBUST
VGA 16 Color Ditherer
VidCap Sample (Video Capture Filter)
VidClip Sample (Video Editing Application)
Video and Audio Capture Filter Graphs
Video capture
Video capture (Filter Graph Configuration)
Video capture (WDM Overview)
Video capture (WDM Video Capture Architecture)
Video capture filter graphs:provided with DirectShow
Video Capture Filter:How to Write a Video Capture Filter
Video Capture Filter:Necessary Interfaces
Video Capture Filter:Pin Names
Video Contrast filter
Video Renderer
Video Renderer filter
VIDEO_STREAM_CONFIG_CAPS
VideoControlFlags
videoDialog
VideoHeight Property (IBasicVideo Object)
VIDEOINFO
VIDEOINFOHEADER
VIDEOINFOHEADER2
videoMessage
VideoModePreferrence
VideoModePreferrence (IDvdControl)
VideoProcAmpFlags
VideoProcAmp_BacklightCompensation
VideoProcAmp_Brightness
VideoProcAmp_ColorEnable
VideoProcAmp_Contrast
VideoProcAmp_Flags_Auto
VideoProcAmp_Flags_Manual
VideoProcAmp_Gamma
VideoProcAmp_Hue
VideoProcAmp_Saturation
VideoProcAmp_Sharpness
VideoProcAmp_WhiteBalance
VideoProcAmpFlags
VideoProcAmpProperty
VideoStandard
VideoWidth Property (IBasicVideo Object)
Viewing Pin Connection Information
Visible Property (IVideoWindow Object)
Visual Basic-Based ActiveX Player
Visual Basic-Based Filter Graph Builder
Visual Basic-Based Filter Graph Player
Visual Basic-Based Player
Visual Basic-based Sample Applications
VITC
Volume Property
Volume Property (IBasicAudio Object)
VPE
VTR

More entries...


Index

A B C D E F G H I J K L M N O P Q R S T U V W Y Z

W

Wait
Wait (CAMEvent)
Wait Debugging
WaitDispatchingMessages
WaitForCompletion (IAMovie Interface: Methods in Vtable Order)
WaitForCompletion (IMediaEvent Interface: Methods in Vtable Order)
WaitForCompletion (IAMovie)
WaitForCompletion (IMediaEvent)
WaitForCompletion Method (IMediaEvent Object)
WaitForMultipleObjects
WaitForNext
WaitForNext (IAsyncReader)
WaitForReceiveToComplete
WaitForReceiveToComplete (CBaseRenderer)
WaitForRenderTime
WaitForRenderTime (CBaseRenderer)
WaitForSingleObject
WaitForThreadExit
WaitForThreadExit (CMsgThread)
WaitMsg
WaitMsg (CAMMsgEvent)
WAVE Parser
WAVEFORMAT
WAVEFORMATEX Structure
WDM
WDM (Filter Graph Configuration)
WDM (WDM Overview)
WDM (WDM Video Capture Architecture)
WDM Video Capture
weave
wFrameFract
wFrameRate
What Are Cutlists?
What the Derived Class Must Provide
When a Reconnection Should Occur
When Reconnections Occur
WideStringFromResource
Width Property (IVideoWindow Object)
wildcards
WillUseFullScreen
WillUseFullScreen (IDirectDrawVideo)
Win32 Classes
Win32 HRESULT
WindowState Property (IVideoWindow Object)
WindowStyle Property (IVideoWindow Object)
WindowStyleEx Property (IVideoWindow Object)
WinMain
Write a Video Capture Filter
Write an Audio Capture Filter
WriteBSTR
WriteInt
WriteSync
WriteSync (IAMDevMemoryControl)
WriteToStream
WriteToStream (CPersistStream)
Writing a Compression Filter
Writing a Transform Filter
Writing an Alternative Renderer
Writing Code You Can Test and Debug
WstrToInt

Y

Y

Z

ZeroMemory


DirectAnimation SDK, Control sample

HTML text
STYLE="WIDTH:0;HEIGHT:0"


DirectAnimation SDK, Control sample

 Roll over Buttons to activate
Roll off Buttons to unactivate
Click Buttons to depress or to change state


DirectAnimation SDK, Control sample

NOW
IS THE
TIME


DirectAnimation SDK, Control sample

Filters can affect any HTML element; including text, windowless controls, intrinsic controls, and images.

Click one of the filter buttons to apply a filter to the objects.


DirectAnimation SDK, Control sample

This is an example of a sprite control. Mouse over the image to play, slowly mouse off to pause


DirectAnimation SDK, Control sample

Example of using a path to animate HTML elements

Paths can animate most visual objects - images, structured graphics, buttons. Here we have a standard input button, two images, and a structured graphic being animated by 4 seperate path objects.


DirectAnimation SDK, Control sample

Preserve Aspect Ratio Method


DirectAnimation SDK, Control sample

Welcome to
the Future of
Multimedia


DirectAnimation SDK, Control sample

Click the mouse button to activate the sprite.


DirectAnimation SDK, Java sample

Album3D

This is a cut&paste sample for a 3D photo album, which is easy to adapt to your favorite set of pictures and corresponding titles. The pictures are imported in JPEG or GIF formats and then normalized and textured on pages of a photo album in 3D.

You can flip the pages by using the right and left arrow keys to flip in the corresponding direction. (Don't forget to obtain input focus by clicking the left mouse button in the applet window). The flipping pages induce stereo sound effects that correspond to the position and orientation of the animation of the pages.

The key to this sample is a state machine with five states that control four reactive behaviors that represent the visual and audible state of the album. The state machine is implemented using the until construct and notification methods. It controls and coordinates two NumberBvrs, one GeometryBvr, and one SoundBvr.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

FifteenPuzzle

The classic fifteen-block puzzle executed in DirectAnimation. Note that the underlying image can be any image (time-varying, interactive, video-based, from a geometry, etc.), and also that the puzzle supports a mode where it is textured on an animate 3-D object while it preserves its interactivity.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

GeoImage

This sample textures a picture on both sides of a rectangle into what is called the geoImage. The geoImage preserves the original aspect ratio of the picture. The sample then animates the geoImage in 3-D space, including a page open/close simulation. The sample renders the geoImage on top of the original picture, which is displayed as a bitmap in the image plane.

2-D/3-D coordination is illustrated by flagging, with an audible click, the instance when geoImage lies on the image plane, in which case the textured rectangle and the original image overlap precisely. Furthermore, the projection of geoImage into the image plane is larger than the bitmap when it is closer than the image plane (positive Z) and smaller when further away (negative Z).

The right and left arrow keys advance pages forward and backward, respectively. (Don't forget to obtain focus by clicking the left mouse button on the applet). There is also a timeout event that automatically advances through the sequence of pictures.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Light House Demo

Wind Conditions:

LightHouse is a good example of 2D/3D/sound integration. The boat, bird, and anemometer are 3D objects rendered and coordinated with the 2D elements of the scene. You may click on the bird and drag it around. Three small seed sound files are attributed and mixed for the background ambient sound. A VB slider influences all aspects of the animation by representing the wind intensity.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Album3D Tutorial Introduction

Album3D imports images with corresponding labels and presents the images as a photo album in 3-D. It also allows the interactive flipping of pages and rotation of the view point, the former by using the left and right arrows, and the latter by using the up and down arrows. The flipping pages have corresponding stereo sound effects.

The key feature of this sample is a state machine used to control and coordinate the animation of the album and the corresponding sound effects. The state machine has five states and is used to control and coordinate four behaviors, including: indexes to the left and right pages of the album (NumberBvrs), the actual center page (GeometryBvr), and the sound effect (SoundBvr). The state machine flows between the different states when specific events occur, and it switches the above four behaviors into new behaviors, accordingly. This is done through the two forms of the "until" method.

The example suggests a systematic way to implement state machines in DirectAnmiation, based on mixed media behaviors. In addition, the approach lends itself to automatic generation of behavior-controlling state machines through visual authoring tools.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
The State and Structure of the Album

Kick-off the state machine. The "state" is a tuple with two number behaviors, one each for the left and right page indexes, a geometry behavior for the center page, and a sound behavior for the audio effects.
TupleBvr state = frontState();
extract the individual behaviors from the tuple
leftInd = (NumberBvr) state.nth(0);
rightInd = (NumberBvr) state.nth(1);
centerPage = (GeometryBvr) state.nth(2);
snd = (SoundBvr) state.nth(3);
extract the left and right pages and labels from their indices
GeometryBvr leftPage = ((GeometryBvr)picFrames.nth(leftInd)).transform(leftTrans);
GeometryBvr rightPage = ((GeometryBvr)picFrames.nth(rightInd)).transform(rightTrans);
StringBvr lPageLabel = (StringBvr)labels.nth(leftInd);
StringBvr rPageLabel = (StringBvr)labels.nth(rightInd);
now construct the album from the pages and the pivot line
ImageBvr album = overlay(renderPage(pivotLine),
overlay(renderPage(centerPage),
overlay(renderPage(rightPage),
renderPage(leftPage))));
Here, construct the two lables and position them under the album. Position them relative to the viewport to be at 12.5% from the bottom.
ImageBvr lLabel = renderStr(lPageLabel, labelColor,
neg(div(_halfWidth,toBvr(2))),
mul(toBvr(-0.75),_halfHeight));
ImageBvr rLabel = renderStr(rPageLabel, labelColor,
div(_halfWidth,toBvr(2)),
mul(toBvr(-0.75),_halfHeight));
The model is the album with the lables and a blue background.
ImageBvr model = overlay(album,
overlay(lLabel,
overlay(rLabel, solidColorImage(blue))));
setSound(snd);
setImage(model);

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
The State Machine

The state machine has five states controlled by two events, one for left page flips and one for right flips. The machine controls and coordinates the pages of the album and the sound effects of the album. The sample uses notification objects because of the cyclic dependency in the finite state machine (not because of event data, which is the second purpose for using notification objects). Notification objects, by providing a delayed execution construct, make it possible to construct cyclic calling dependencies without infinite looping. The sample also uses the until2 method instead of untilNotify since it allows the aggregatation of two notification events each with a different notification method; see the opened state below.

Note that both cyclic dependency and branching from one state into two or more states upon different events are commonly occuring patterns in general state machines. Hence the example below has the building blocks that are needed for typical state machines.

This state is the entry point into the state machine and is also returned to upon flipping the front page back (effectively going back to the start state). It sets the left page to blank, the right page to the front page of the album, and it emits the page-flip completion sound through the right speaker. The state waits on the leftEventNotify event upon which it invokes the transLeft notification object which implements the "transition left" state.
public static TupleBvr frontState () {
NumberBvr leftInd = toBvr(0);
Behavior newBvrs[] = { leftInd, add(leftInd, toBvr(1)),
emptyGeometry, endSnd.pan(+1)};
TupleBvr tuple = new TupleBvr(newBvrs);
return (TupleBvr)untilEx(tuple, leftEventNotify);
}
This state is entered upon the end of a page flip that causes the album to be properly opened (i.e., not in a boundary condition). It waits on either a left or a right event, at which point it invokes the transLeft or transRight notification objects, respectively, which carry it through either the left transition or to right transition state. It accepts an index to the left page plus the side to which the previous page was flipped to, in order to emit the page flip termination sound.
public static TupleBvr opened (NumberBvr leftInd, int side) {
Behavior newBvrs[] = {leftInd , add(leftInd, toBvr(1)),
emptyGeometry, endSnd.pan(toBvr(side))};
TupleBvr tuple = new TupleBvr(newBvrs);
return (TupleBvr)untilEx(tuple, orEvent(rightEventNotify,
leftEventNotify));
}
symmetric to frontState
public static TupleBvr backState () {
NumberBvr leftInd = toBvr(A3DM.numPics);
Behavior newBvrs[] = {leftInd, add(leftInd, toBvr(1)),
emptyGeometry, endSnd.pan(-1)};
TupleBvr tuple = new TupleBvr(newBvrs);
return (TupleBvr)untilEx(tuple, rightEventNotify);
}
This notifier object flips the center page to the left side until the completion of the page flip. At that point if we've flipped the last page then we go to the back state, else we go to the opened state, which is the nominal one. Notice how we extract the present left page index from the "previous" parameter of the "notify" method.
class TransLeft extends Statics implements UntilNotifier {
public Behavior notify(Object eventData, Behavior previous, BvrsToRun blst) {
NumberBvr leftInd = (NumberBvr)((TupleBvr)previous).nth(0);
Behavior newBvrs[] = {leftInd, add(leftInd, toBvr(2)),
A3DM.flip(add(leftInd, toBvr(1)), -1), A3DM.flippingSnd(-1)};
return (TupleBvr) until(new TupleBvr(newBvrs), A3DM.endFlip,
cond(eq(leftInd, toBvr(A3DM.numPics - 1)),
A3DM.backState(),
A3DM.opened(add(leftInd, toBvr(1)), -1)));
}
}
symmetric to TransLeft
class TransRight extends Statics implements UntilNotifier {
public Behavior notify(Object eventData, Behavior previous, BvrsToRun blst) {
NumberBvr leftInd = sub((NumberBvr)((TupleBvr)previous).nth(0), toBvr(1));
Behavior newBvrs[] = {leftInd, add(leftInd, toBvr(2)),
A3DM.flip(add(leftInd, toBvr(1)), +1), A3DM.flippingSnd(+1)};
return (TupleBvr) until(new TupleBvr(newBvrs), A3DM.endFlip,
cond(eq(leftInd, toBvr(0)),
A3DM.frontState(),
A3DM.opened(leftInd, +1)));
}
}
interaction events Right and left arrows to flip pages.
static final DXMEvent rightEvent = keyDown(Event.RIGHT);
static final DXMEvent leftEvent = keyDown(Event.LEFT);
signals the conclusion of a page flip animation
static final DXMEvent endFlip = timer(toBvr(period));
instantiate the notifier objects
static final TransRight transRight = new TransRight();
static final TransLeft transLeft = new TransLeft();
Define notify events based on the previous objects, these events get used in the state machine.
static final DXMEvent rightEventNotify = rightEvent.notifyEvent(transRight);
static final DXMEvent leftEventNotify = leftEvent.notifyEvent(transLeft);

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Importing and Defining the Media Parts

Build URL bases for importing images, geometries, and sounds.
URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase,"image/");
URL geoBase = buildURL(mediaBase,"geometry/");
URL sndBase = buildURL(mediaBase,"sound/");
Load the sound files that will be used for sound effects
startSnd = importSound(buildURL(sndBase,"inflate.mp2"), startLen);
flipSnd = importSound(buildURL(sndBase,"clock1.mp2"), null);
endSnd = importSound(buildURL(sndBase,"deflate.mp2"), null);
This image will be tiled into the paper texture.
paperTex = importImage(buildURL(imgBase,"sandbg1.jpg"));
Synthetically construct the front and back cover pages of the Album.
ColorBvr labelColor = red;
ImageBvr front1 = renderStr(toBvr("Outdoors"), labelColor, toBvr(0), toBvr(0.003));
ImageBvr front2 = renderStr(toBvr("Album"), labelColor, toBvr(0), toBvr(-0.003));
ImageBvr front = overlay(front1, front2);
ImageBvr back = renderStr(toBvr("The End"), labelColor, toBvr(0), toBvr(0));
Import a list of images, some of these could have been .gif images. We add the front and back covers appropriately, and we add empty images to pair with them.
ImageBvr pics[] = {emptyImage, front,
importImage(buildURL(imgBase,"phantom.jpg")),
importImage(buildURL(imgBase,"hiddenBeachSS.jpg")),
importImage(buildURL(imgBase,"hiddenBeachSG.jpg")),
importImage(buildURL(imgBase,"jotunheimen1.jpg")),
importImage(buildURL(imgBase,"redWoodCar.jpg")),
importImage(buildURL(imgBase,"wenatcheeCascades.jpg")),
importImage(buildURL(imgBase,"tulipsHol1.jpg")),
importImage(buildURL(imgBase,"tulipsHol2.jpg")),
importImage(buildURL(imgBase,"yosemiteCreek.jpg")),
importImage(buildURL(imgBase,"kidsUtah.jpg")),
importImage(buildURL(imgBase,"foliageUtah.jpg")),
back, emptyImage};
Ditto for corresponding labels. No labels for cover pages nor for empty ones.
StringBvr lbls[] = {toBvr(""), toBvr(""),
toBvr("Crater Lk., Oregon"),
toBvr("Klamath, California"),
toBvr("Klamath, California"),
toBvr("Jotenheimen, Norway"),
toBvr("Redwoods N.P., California"),
toBvr("Cascades, Washington"),
toBvr("Tulip Garden, Holland"),
toBvr("Tulip Garden, Holland"),
toBvr("Yosemite, California"),
toBvr("Centerville, Utah"),
toBvr("Bountiful, Utah"),
toBvr(""), toBvr("")};
ArrayBvr labels = new ArrayBvr(lbls);

numPics = lbls.length - 2;
don't count the emptyImages
a [-1, 1] square in X and Y with [0, 1] texture coordinates for both faces.
GeometryBvr square = importGeometry(buildURL(geoBase,"square.x"));
frame is a [0, 2]x[-1, 1] square, on right hand side of Y axis
GeometryBvr frame = square.transform(translate(1,0,0));
creates an array for the pages that are counter part to the pictures.
GeometryBvr frames[] = new GeometryBvr[numPics + 2];
first and last correspond to the empty pictures
frames[0] = emptyGeometry;
frames[numPics + 1] = emptyGeometry;
the rest correspond to the pictures
for (int i=1; i<=numPics; i++)
frames[i] = frame.texture(normalPic(pics[i]));
Construct a Behavior Array of the pages, so we can use NumberBvr indices
picFrames = new ArrayBvr(frames);
demarcates the line around which pages pivot
NumberBvr lineThickness = toBvr(6 * mm);
3% of page size
Make the square very thin in the X direction. We use a square to represent the line in 3D space.
GeometryBvr pivotLine = square.diffuseColor(red).
transform(scale(lineThickness, toBvr(1), toBvr(1)));

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Utility Functions

Takes an index to a page and a direction of motion. Returns the given page animated in the proper direction, both left and right page flips are supported.
public static GeometryBvr flip(NumberBvr ind, int dir) {
orientation of page flip depends on dir
Transform3Bvr flipTrans = rotate(yVector3, mul(toBvr(dir),
mul(toBvr(flipRate), localTime)));
starting angle of page depends on dir
GeometryBvr page = ((GeometryBvr)picFrames.nth(ind)).transform(
(Transform3Bvr)cond(toBvr(dir == +1), leftTrans, rightTrans));
return page.transform(flipTrans);
}
Flipping a page commences with startSnd and transitions to flipSound, stereo sound is used to reflect the direction of the page flip.
public static SoundBvr flippingSnd(int dir) {
double panRate = 2/period;
in period time it goes from 0 to 2
return (SoundBvr)until(startSnd.pan(-1 * dir), in -dir speaker
timer(startLen[0]),
timer(toBvr(1.0)),
substitute for startLen
flipSnd.loop().pan(mul(toBvr(dir),
varries from -dir to +dir.
sub(mul(toBvr(panRate), localTime), toBvr(1)))));
}
Pastes a picture on a unit-sized page while preserving its aspect ratio. The picture is left-centered. The extra space is filled with paper texture.
public static ImageBvr normalPic(ImageBvr pic) {
Bbox2Bvr picBbox = pic.boundingBox();
Point2Bvr ur = picBbox.getMax();
NumberBvr dim = maxNumBvr(ur.getX(), ur.getY());
ImageBvr croppedTex = paperTex.tile().crop(point2(neg(dim), neg(dim)),
point2(dim, dim));
return overlay(pic, croppedTex).mapToUnitSquare();
}
Constructs a number behavior which is a certain number or 0 depending on if the given key is pressed or not.
static NumberBvr keyIntegral(int key) {
NumberBvr cAngleRate = toBvr(Math.PI/8);
rate of motion of camera angle
NumberBvr factor = (NumberBvr)cond(keyState(key), cAngleRate, toBvr(0));
return integral(factor);
}
Takes a page of the album and renders it into an image based on consistent camera and lights. Animates the camera based on the up and down arrow keys.
static ImageBvr renderPage(GeometryBvr page) {
create an interactive angle to animate the camera
NumberBvr initialAngle = toBvr(Math.PI/20);
NumberBvr cameraAngle = add(initialAngle,
sub(keyIntegral(Event.UP),
keyIntegral(Event.DOWN)));
use the angle to rotate the camera
Transform3Bvr cameraTrans = rotate(xVector3, cameraAngle);
CameraBvr camera = perspectiveCamera(toBvr(5),
toBvr(4)).transform(cameraTrans);
scale the resulting image, map 1 unit to 50 pixels
Transform2Bvr scaleTrans = scale2(mul(toBvr(PAGESIZE),pixelBvr));
GeometryBvr scene = union(ambientLight, page);
return scene.render(camera).transform(scaleTrans);
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
General Declarations

static final int PAGESIZE = 60;
Album page size in pixels

static final double period = 3;
duration of a page flip in seconds
static final double tiltAngle = Math.PI / 4; angle at which resting pages sit
static final double flipRate = (Math.PI - 2*tiltAngle)/period; the rate of a page flip
album pages are slightly off horizontal resting position of left page
static final Transform3Bvr leftTrans = rotate(yVector3, toBvr(-Math.PI + tiltAngle));
resting position of right page
static final Transform3Bvr rightTrans = rotate(yVector3, toBvr(-tiltAngle));

static int numPics;
the number of pages in the album
the three sound files that will be imported the length of the start sound
static NumberBvr startLen[] = new NumberBvr[1];
at the begining of a page flip
static SoundBvr startSnd;
during a page flip
static SoundBvr flipSnd;
at the end of a page flip
static SoundBvr endSnd;
the texture used for the album paper
static ImageBvr paperTex;
static ArrayBvr picFrames;
the pages of the album
The state of the album consists of four behaviors
static NumberBvr leftInd;
index to left page
static NumberBvr rightInd; index to right page
static GeometryBvr centerPage; the actual center page
static SoundBvr snd; sound associated with page flipping

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Boiler Plates

imports
import com.ms.dxmedia.*; all DirectAnimation classes
import java.awt.*; Dimension class
import java.net.*; URL class
An applet that instantiates the Album3D model
public class Album3D extends DXMApplet {
public void init() {
super.init() ;
setModel (new A3DM(this)) ;
}
}

class A3DM extends Model {

A3DM(DXMApplet dxma) {
Dimension dim = dxma.getSize();
The base unit of measure in DirectAnimation is the meter. Convert the size into meters by multiplying it with the pixelBvr.
_halfHeight = mul(toBvr(dim.height*0.5),pixelBvr);
_halfWidth = mul(toBvr(dim.width*0.5),pixelBvr);
}
Here we create the Album3D model.
public void createModel(BvrsToRun blst) {

}
stores the height of the applet viewport in the member variable.
private NumberBvr _halfHeight;
private NumberBvr _halfWidth;

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
FifteenPuzzle Tutorial Introduction
The classic fifteen-puzzle in DirectAnimation. Note that the
underlying image can be *any* image (time-varying, interactive, video-
based, from a geometry, etc), also the puzzle supports a mode where
it is textured on an animate 3D object while it preserves its interactivity.

The main features highlighted in this sample include:
- using a time-varying, interactive image as a texture
- getting events to DirectAnimation from VBScript
- rendering geometry into an image
- overlaying text on video
- using reactive sound as feedback to user input

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section2: DA Events via VBScript Buttons
We start with the applet tag which centers the puzzle at the begining of the html page. Notice the use of the ID parameter to give the applet a label that gets used in VBScript. All public methods in the applet are visible to VBS (or JScript) scripting.
<CENTER>
<APPLET
CODE="FifteenPuzzle.class"
CODEBASE="../../../../../media/"
ID=fifteenPuzzleApplet
WIDTH=300
HEIGHT=300
ALIGN=CENTER
VSPACE=20>
</APPLET>
</CENTER>
We use three VBScript buttons:
1) for switching the mode of the puzzle from 2D to 3D and back,
2) for cycling through different images for the puzzle,
3) for reseting the puzzle to it's original image and state.
We first declare the buttons.
<CENTER>
<input type=button value="3D Puzzle" name="toggleProjectionButton">
<input type=button value="Donuts" name="toggleImageButton">
<input type=button value="Reset Puzzle" name="resetPuzzle">
</CENTER>
 We then use VBS as the glue between the buttons and the applet. Essentially each button invokes a corresponding subroutine below where the subroutine calls a corresponding public method in the applet and modifies the labels on the buttons as appropriate.
<script language="VBScript">
<!--
sub toggleProjectionButton_OnClick
document.fifteenPuzzleApplet.toggleGeomProjection
if toggleProjectionButton.value = "3D Puzzle" then
toggleProjectionButton.value = "2D Puzzle"
else
toggleProjectionButton.value = "3D Puzzle"
end if
end sub

sub toggleImageButton_OnClick
if toggleImageButton.value = "Donuts" then
toggleImageButton.value = "Movie"
elseif toggleImageButton.value = "Movie" then
toggleImageButton.value = "Movie with Counter"
elseif toggleImageButton.value = "Movie with Counter" then
toggleImageButton.value = "Counter"
else
toggleImageButton.value = "Donuts"
end if
document.fifteenPuzzleApplet.toggleImageUsed

end sub

sub resetPuzzle_OnClick
document.fifteenPuzzleApplet.resetPuzzle
toggleImageButton.value = "Donuts"
end sub

-->
</script>
These are DXMApplet public methods that are visible to VBScript and are used as conduits for VBScript button events to triggering AppTriggerEvents in DirectAnimation.
public void toggleGeomProjection() { _model.toggleGeomProjection(); }
public void toggleImageUsed() { _model.toggleImageUsed(); }
public void resetPuzzle() { _model.resetPuzzle(); }

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Construct the Cycling Image for the Puzzle

Create a unit-sized image to divide up into the puzzle. The image cycles through four images upon toggleImage events.
ImageBvr createUnitImageForPuzzle() {
Create the different images that will be used in the puzzle:

time-varying solid-colored image for background
ImageBvr bkgnd = createBackgroundColorCycler();
image of time-varying elapsed time in seconds
ImageBvr counterImg = createCounterImage();
first possible image for puzzle, time over colored background
ImageBvr unitIm1 = overlay(counterImg, bkgnd);
second possibility, based on rendered geometry
ImageBvr unitIm2 = createGeoImage();
third possibility, based in imported video
ImageBvr unitIm3 = createMovieImage();
forth possibility, time in second over the video
ImageBvr unitIm4 = overlay(counterImg, unitIm3);
Have these image behaviors run just once, so that they don't get restarted when events happen.
unitIm1 = (ImageBvr)unitIm1.runOnce();
unitIm2 = (ImageBvr)unitIm2.runOnce();
unitIm3 = (ImageBvr)unitIm3.runOnce();
unitIm4 = (ImageBvr)unitIm4.runOnce();
Cycle between the four images on occurence of this app event.
ImageBvr imageToShow = ImageBvr.newUninitBvr();
_toggleImageUsed = new AppTriggeredEvent();
imageToShow.init( until(unitIm1,
_toggleImageUsed, until(unitIm2,
_toggleImageUsed, until(unitIm3,
_toggleImageUsed, until(unitIm4,
_toggleImageUsed, imageToShow)))));
return imageToShow;
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Construct a 3-D rendered Image

Constructs one of the puzzle images by rendering three intertwined and animate instances of a doughnut.
public ImageBvr createGeoImage() {
construct a color with a time- varying hue
NumberBvr hue1 = mul(localTime, toBvr(0.2));
ColorBvr col = colorHsl(hue1, toBvr(0.5), toBvr(0.5));
import a half doughnut in the positive Y half space
GeometryBvr halfDonut =
importGeometry(buildURL(_geoBase,"hlfdonut.x"));
Construct a complete doughnut by combining with the second half. The resulting doughnut is centered around the origin and is of [-1,1] extent in X and Y.
GeometryBvr donut = union(halfDonut,
halfDonut.transform(rotate(xVector3, toBvr(Math.PI))));
The first doughnut rotates around the Y axis and has the time-varying color.
GeometryBvr donut0 =
donut.transform(compose(rotate(yVector3, localTime),
scale3(toBvr(0.3)))).diffuseColor(col);
The second doughnut is based on the first one scaled down by 25%, shifted by 0.2 in positive Z, and animated at a 30% faster rate than the first one.
GeometryBvr donut1 = (GeometryBvr)
donut0.transform(compose(translate(0,0,0.2),
scale3(0.75)))
when the first doughnut progresses by one unit, this second doughnut progresses by 1.3 units.
.substituteTime(mul(localTime, toBvr(1.3)));
The third doughnut is based on the first one scaled down by 25%, shifted by 0.2 in negative Z, and animated at a 40% slower rate than the first one.
GeometryBvr donut2 = (GeometryBvr)
donut0.transform(compose(translate(0,0,-0.2),
scale3(0.75))).substituteTime(mul(localTime, toBvr(0.6)));
Construct a 3-D rotational transform with a time-varying axis of rotation and a time-varying angle of rotation.
Transform3Bvr xf = rotate(vector3(sin(localTime),
cos(localTime), sin(mul(toBvr(1.34), localTime))),
mul(localTime, toBvr(0.62)));
The geometry for the image is the aggregation of the three doughnuts from above with the animate rotational transform applied.
GeometryBvr donuts = union(donut0, union(donut1, donut2)).transform(xf);
a camera with projection point at 3 and near plane at 2
CameraBvr cam = perspectiveCamera(toBvr(3),toBvr(2));

GeometryBvr geoWithLight = union(donuts, directionalLight);

ImageBvr im = geoWithLight.render(cam);
This translates the image so that its lower left corner is approximately at the origin. This approximation allows the image (doughnuts really) to get clipped slightly.
im = im.transform(translate(0.5,0.5));

return overlay(im, solidColorImage(white));
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Construct an Image of an Elapsed Time Counter

Returns an elapsed-seconds counter as an image.
ImageBvr createCounterImage() {
Convert localTime to a string and ignore fractional part.
FontStyleBvr fs = defaultFont.color(white).bold();
render into an image
ImageBvr underlyingImage = stringImage(localTime.toString(toBvr(0)),fs);
Scale into a unit square [0,1]. Note that as the size of the the string grows, for example going from 1 digit to 2, the scale adapts to fit the resulting image in the unit square.
return underlyingImage.mapToUnitSquare();
}
This is a time-varying solid-colored image, infinite in extent.
ImageBvr createBackgroundColorCycler() {
NumberBvr hue1 = mul(localTime, toBvr(0.2));
ColorBvr col1 = colorHsl(hue1, toBvr(0.5), toBvr(0.5));
return solidColorImage(col1);
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Construct an Image based on an Imported Video

This returns an imported video as a continually looped image behavior.
ImageBvr createMovieImage() {

SoundBvr [] snd = { null } ;
ImageBvr [] unitIm = { null } ;
NumberBvr len = importMovie(buildURL(_movieBase,"movie.avi"),
unitIm, snd);
loop it, by using the mod function
unitIm[0] = (ImageBvr)unitIm[0].substituteTime(mod(localTime, len ));
scale into unit square
return unitIm[0].mapToUnitSquare();
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Construct an Image of a Textured Rotating Fan

Constructs the image of a rotating two-bladed fan, and textures the given image on all of its four faces.
public ImageBvr textureOnFan(ImageBvr unitImForTexture) {
quad is [-1,+1]x[-1,+1] with texture coordinates [0,1]x[0,1]
GeometryBvr faceObj = importGeometry(buildURL(_geoBase,"quad.x"));
Replicate to give a textured backside as well.
faceObj = union(faceObj,
faceObj.transform(rotate(yVector3, toBvr(Math.PI))));
Replicate both sides with a 90 degree rotation to make a fan.
faceObj = union(faceObj,
faceObj.transform(rotate(yVector3, toBvr(Math.PI/2))));
construct a rotation around the Y axis
Transform3Bvr xf = rotate(yVector3, mul(localTime, toBvr(0.4)));
construct a rotating fan with the texture
faceObj = faceObj.texture(unitImForTexture).transform(xf);
construct a camera with projection point at 3 and near plane at 2
CameraBvr cam = perspectiveCamera(toBvr(3),toBvr(2));
use a light and obtain an image
GeometryBvr geoWithLight = union(faceObj, directionalLight);
ImageBvr im = geoWithLight.render(cam);

return im.transform(compose(translate(0.5, 0.5),
scale2(0.4)));
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Tie it together and Construct the Model

public void createModel(BvrsToRun blst) {
set the URL bases for the media imports
_mediaBase = getImportBase();
_sndBase = buildURL(_mediaBase,"sound/");
_movieBase = buildURL(_mediaBase,"movie/");
_geoBase = buildURL(_mediaBase,"geometry/");
create the reactive cycling image for the puzzle
ImageBvr unitIm = createUnitImageForPuzzle();
tile the image of the puzzle for playability
_puzz = new PuzzleLogic(unitIm, _viewedOn, _mediaBase);
ImageBvr puzzleIm = _puzz.getImage();
Give the puzzle a black background, so the empty square will be black.
puzzleIm = overlay(puzzleIm, solidColorImage(black));
Establish this as a runOnce bvr, so that when the code switches modes, the puzzle doesn't restart.
puzzleIm = (ImageBvr)puzzleIm.runOnce();
Now, create two images, one based on direct display and one based on texturing on the fan:

Translate the image down to center, and scale it down to 6 cms.
ImageBvr directDisplayIm =
puzzleIm.transform(compose(scale2(0.06),
translate(-0.5,-0.5)));
Texture the image on a 3-D rotating fan
ImageBvr projectedGeo = textureOnFan(puzzleIm);
projectedGeo =
projectedGeo.transform(compose(scale2(0.07),
translate(-0.5,-0.5)));
projectedGeo = overlay(projectedGeo, solidColorImage(black));
Cycle through 3-D and 2-D versions upon the toggle geometry event.
ImageBvr imageToShow = ImageBvr.newUninitBvr();
_toggleGeomProjection = new AppTriggeredEvent();
imageToShow.init( until(directDisplayIm,
_toggleGeomProjection, until(projectedGeo,
_toggleGeomProjection, imageToShow)));
These are the resultant image and sound that constitute the model.
setImage(imageToShow);
setSound(_puzz.getSound());
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Constructing the Interactive Image of the Puzzle

Construct the puzzle image as a composition of its distinct parts.
ImageBvr createImage() {

int i;
int j;
double x = 0;
double y = 0;
ImageBvr totalIm = emptyImage;
build up the cells
for (i = 0; i < _squares; i++, y += _inc) {
x = 0;
for (j = 0; j < _squares; j++, x += _inc) {
Skip the last one, to leave empty space.
if (i == _squares - 1 && j == _squares - 1) continue;
Crop to get next cell and move lower left corner to the origin.
ImageBvr croppedIm = _unitSourceIm.
crop(point2(toBvr(x), toBvr(y)),
point2(toBvr(x + _inc), toBvr(y + _inc)));
croppedIm = croppedIm.transform(translate(toBvr(-x), toBvr(-y)));
make pickable
PickableImage pick = new PickableImage(croppedIm);
ImageBvr pickableCroppedIm = pick.getImageBvr();
extract probe event and create pick event
DXMEvent probedEvent = pick.getPickEvent();
DXMEvent pickedEvent = andEvent(leftButtonDown, probedEvent);
Initially translate back to original space.
Transform2Bvr initXf = translate(toBvr(x), toBvr(y));
Allow transform to change as it's picked.
Transform2Bvr xf = (Transform2Bvr)
untilNotify(initXf, pickedEvent,
new ImagePicker(i, j, pickedEvent, this));
The entire cell is the transform applied to the cell at the origin.
ImageBvr movingIm = pickableCroppedIm.transform(xf);
accumulate the cells of the puzzle
totalIm = overlay(movingIm, totalIm);
}
first for
}
second for
Establish initial empty cell.
_emptyRow = _squares - 1;
_emptyCol = _squares - 1;

return totalIm;

}
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
The Notification Object upon Puzzle Events

This object accepts a user event, and if it's a legal move (cell that is adjacent to the empty location), then the cell is transitioned and success sound is emitted, else illegal move sound is emitted.
class ImagePicker extends Statics implements UntilNotifier {
public ImagePicker(int row,
int col,
DXMEvent ev,
PuzzleLogic puzz) {
_row = row;
_col = col;
_ev = ev;
_puzz = puzz;
}
invoked through the untilNotify construct
public Behavior notify(Object eventData,
Behavior currentRunningBvr,
BvrsToRun lst) {

Behavior xf = currentRunningBvr;
int r = _puzz._emptyRow;
int c = _puzz._emptyCol;
check to see if this is a legal move
if (((Math.abs(_row - r) == 1) && _col == c) ||
((Math.abs(_col - c) == 1) && _row == r)) {
find cell positions before and after the move
Point2Bvr start = point2(toBvr(_col * _puzz._inc),
toBvr(_row * _puzz._inc));
Point2Bvr finish = point2(toBvr(c * _puzz._inc),
toBvr(r * _puzz._inc));
Build up a transform to move from orig to final in 0.5 second
double transitionTime = 0.5;
the vector from start to finish
Vector2Bvr delta = sub(finish, start);
pos begins at start and transitions to finish in transitionTime seconds
Point2Bvr pos = add(start, delta.mul(div(localTime, toBvr(transitionTime))));
extract a translation from moving position
Transform2Bvr movingXf = translate(sub(pos, origin2));
Use this transform, and after the elapsed time freeze in place using a snapshot event.
xf = untilEx(movingXf,
timer(toBvr(transitionTime)).snapshotEvent(movingXf));
an alternative is: ,translate(finish.getX(), finish.getY()));

Set the new location of the empty cell
_puzz._emptyCol = _col;
_puzz._emptyRow = _row;
Set what position this cell is at now
_col = c;
_row = r;
emit success sound
_puzz.setHitSound(true);

} else {
emit illegal move sound
_puzz.setHitSound(false);
}
Return this new transform, waiting again for the pick event.
return untilNotify(xf, _ev, this);
}

int _row;
int _col;
DXMEvent _ev;
PuzzleLogic _puzz;
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
High Level Structure for Interactivity and Logic

Contains the logic for doing the puzzle.
class PuzzleLogic extends Statics {
Take a unit image and chop it up into the pieces of the puzzle.
public PuzzleLogic(ImageBvr unitSourceIm,
Viewer viewedOn,
URL importBase) {

_viewedOn = viewedOn;
for synchronization
_squares = 3;
_inc = 1.0 / _squares;

_unitSourceIm = unitSourceIm;
The image is a switcher to facilitate the resetting of the image; see the resetImage method below.
ImageBvr initialImage = createImage();
_imageSwitcher = new ModifiableBehavior(initialImage);
_image = (ImageBvr)_imageSwitcher.getBvr();
will switch to these sounds as appropriate.
_successSound = importSound(buildURL(importBase,
"sound/butin.wav"), null);
_failureSound = importSound(buildURL(importBase,
"sound/deflate.mp2"), null);
the puzzle sound is a switcher used in setHitSound below.
_soundSwitcher = new ModifiableBehavior(silence);
_sound = (SoundBvr)_soundSwitcher.getBvr();
}
Just recreate the image and switch to it. Synchronize with the viewer so the code doesn't vie for the processor with it.
public void resetImage() {
synchronized (_viewedOn) {
_imageSwitcher.switchTo( createImage() );
}
}
straightforward hit or fail sounds are generated.
public void setHitSound(boolean success) {
_soundSwitcher.switchTo(success ? _successSound : _failureSound);
}

public ImageBvr getImage() { return _image; }
public SoundBvr getSound() { return _sound; }

int _squares;
int _emptyRow;
int _emptyCol;
double _inc;
SoundBvr _successSound;
SoundBvr _failureSound;
ModifiableBehavior _soundSwitcher;

ImageBvr _unitSourceIm;
ImageBvr _image;
ModifiableBehavior _imageSwitcher;
SoundBvr _sound;
Viewer _viewedOn;
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Boiler Plates
imports
import java.applet.*;
import java.awt.*;
import java.net.*;
import com.ms.dxmedia.*;

public class FifteenPuzzle extends DXMApplet {
public void init() {
super.init() ;
_model = new FifteenPuzzleModel(getCanvas());
setModel(_model);
}

private FifteenPuzzleModel _model;
}

class FifteenPuzzleModel extends Model {

FifteenPuzzleModel(Viewer viewedOn) {
Hang onto this for synchronization.
_viewedOn = viewedOn;
}
Methods to trigger the AppTriggeredEvents, are called from DXMApplet.
public void toggleGeomProjection() { _toggleGeomProjection.trigger(); }
public void toggleImageUsed() { _toggleImageUsed.trigger(); }
public void resetPuzzle() { _puzz.resetImage(); }
Use this event which originates from VBScript to toggle between direct image and fan.
AppTriggeredEvent _toggleGeomProjection;
Use this event which originates from VBScript to toggle between the different images for the puzzle.
AppTriggeredEvent _toggleImageUsed;
PuzzleLogic _puzz;
Viewer _viewedOn;
URL _mediaBase;
URL _sndBase;
URL _movieBase;
URL _geoBase;
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
GeoImage Tutorial Introduction

GeoImage imports a list of pictures and corresponding labels. It textures a picture on a rectangle while preserving aspect ratio (the picture is called the GeoImage). The texturing takes place on both sides of the rectangle so that the picture is seen from either side. The sample animates the geoimage in 3-D, punctuates when the geoimage is in the image plane with an audible tick, uses arrow keys and the space bar to cycle through the pictures and corresponding labels, and renders the original picture as a bitmap, the animate geoimage, and the label.

The key DirectAnimation points that are demonstrated include:
- aggregate events using orEvent
- creating a counter with application event data and the untilNotify method
- using number behaviors as indexes to arrays of behaviors
- newUninitbvr and init for looping transform and sound
- texturing images on rectangles while preserving aspect ratio
- 2-D/3-D interplay, via the relation of geoimage with picture
- using sound to punctuate instances in the animation
- rendering text into images

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Interacting with geoImage

This class produces a bidirectional counter that cycles in a given range upon button presses.
class Counter extends Statics implements UntilNotifier {
constructor for a counter object
public Counter(NumberBvr limit) {
_counterLimit = limit;
upon a skip event invoke the notifier
_value = (NumberBvr)untilNotify(_initValue, skip, this);
}

public Behavior notify(Object eventData, Behavior previous, BvrsToRun lst) {
extract the application data (an integer), into a number behavior
NumberBvr adjustment = toBvr(((Integer)eventData).intValue());
use it as an inc/decrement
NumberBvr value = add((NumberBvr)previous, adjustment);
cycle between 0 and (limit - 1)
value = (NumberBvr)cond(eq(value, toBvr(-1)),
sub(_counterLimit, toBvr(1)),
if -1, wrap around
cond(eq(value, _counterLimit), toBvr(0), value));
if limit, wrap around
repeat with the new value
return untilNotify(value, skip, this);
}

public NumberBvr getBvr () {
return _value;
}
Key events with corresponding event data. For non-ASCII keys use the Java designation for the key.
private static final DXMEvent skipForward1 = keyDown(Event.RIGHT).attachData(new Integer(1));
private static final DXMEvent skipBack1 = keyDown(Event.LEFT).attachData(new Integer(-1));
For ASCII keys use the ASCII letter between single quotes.
private static final DXMEvent skipForward2 = keyDown(' ').attachData(new Integer(1));
There is also a timeout event for automatically switching between pictures if no manual key presses are issued.
private static final DXMEvent auto = timer(toBvr(8)).attachData(new Integer(1));
Aggregate the four events above into a single event.
private static final DXMEvent skip = orEvent(skipForward1,
orEvent(skipBack1,
orEvent(skipForward2, auto)));
These are aspects of the counter.
private NumberBvr _counterLimit;
private NumberBvr _initValue = toBvr(0);
start counting at 0
private NumberBvr _value; current value of counter

}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
The 3-D animation

the length of the first segment of the animation in seconds
NumberBvr period = toBvr(6);
time-varying angle, does a complete cycle per period
NumberBvr aniAngle = mul(localTime, mul(toBvr(2),
div(toBvr(Math.PI), period)));
A translation between front and back Z limits used for travel of the center of the geometric image. The limits are related to the extent of the picture.
NumberBvr distOfTravel = mul(toBvr(20), maxHalfExtent);
Transform3Bvr trans = translate(toBvr(0), toBvr(0),
mul(neg(distOfTravel), sin(aniAngle)));
a rotation with rate "aniAngle" around a time varying axis
Transform3Bvr rot = rotate(vector3(sin(aniAngle), cos(aniAngle),
div(sin(aniAngle), toBvr(2))), aniAngle);
tumbling in 3-D animation, performs a complete cycle in one "period":
Transform3Bvr rot1 = compose(trans, rot);
open page animation, opens in one quarter of "period":
Transform3Bvr rot2 =
compose(translate(neg(xUpperRight), toBvr(0), toBvr(0)),
compose(rotate(yVector3, neg(aniAngle)),
translate(xUpperRight, toBvr(0), toBvr(0))));
close page animation, closes in one quarter of "period":
Transform3Bvr rot3 =
compose(translate(neg(xUpperRight), toBvr(0), toBvr(0)),
the -PI/2 is to pick up from where the page open animation left of
compose(rotate(yVector3, add(div(neg(toBvr(Math.PI)), toBvr(2)), aniAngle)),
translate(xUpperRight, toBvr(0), toBvr(0))));
the cyclic animation of the geoimage: - tumbling in 3-D in one "period" - open page in quarter of "period" - close page in quarter of "period"
NumberBvr quarterPeriod = div(period, toBvr(4));
Transform3Bvr loopingTrans = Transform3Bvr.newUninitBvr();
loopingTrans.init(until(rot1, timer(period),
until(rot2, timer(quarterPeriod),
until(rot3, timer(quarterPeriod), loopingTrans))));

GeometryBvr loopingGeoImage = geoImage.transform(loopingTrans);

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Sound Punctuation & Rendering the Label

Generate a tick everytime the geoimage lies in the image plane. At that point the original picture (bitmap in image plane) coincides with geoimage (a 3-D rendering of a textured rectangle). GeoImage's projection is larger than the picture when closer than the image plane and its projection is smaller when it's further away.

import the ping sound.
SoundBvr ping = importSound(buildURL(sndBase, "butin.wav"), null);
Could have set the looping sound like the transform above; Instead, demonstrate the cycler. alternative: NumberBvr halfPeriod = div(period, toBvr(2)); SoundBvr loopingSound = SoundBvr.newUninitBvr(); loopingSound.init(until(ping, timer(halfPeriod), loopingSound));
NumberBvr halfPeriod = div(period, toBvr(2));
Behavior sounds[] = { ping };
Cycler cyl = new Cycler(sounds, timer(halfPeriod));
SoundBvr loopingSound = (SoundBvr)(cyl.getBvr());
label is yellow, bold, centered horizontally, and 15% above bottom
Transform2Bvr lablePos = translate(toBvr(0), mul(toBvr(-0.85), _halfHeightNum));

FontStyleBvr fs = defaultFont.color(yellow).bold();

ImageBvr lableImage = stringImage(lable, fs).transform(lablePos);

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Texture the Picture while Preserving Aspect Ratio

Extract the extent of the picture and scale the square into a rectangle with the same extent, to preserve the picture's aspect ratios upon texturing
Bbox2Bvr pictureBbox = picture.boundingBox();
Point2Bvr ll = pictureBbox.getMin();
Point2Bvr ur = pictureBbox.getMax();
NumberBvr xUpperRight = ur.getX();
NumberBvr yUpperRight = ur.getY();
Transform3Bvr scaleSquare = scale(xUpperRight, yUpperRight, toBvr(1));
NumberBvr maxHalfExtent = maxNumBvr(xUpperRight, yUpperRight);
GeoImage has the property that when it lies in the image plane it will have dimensions equal to its bitmap counterpart.
GeometryBvr geoImage = square.transform(scaleSquare).
The picture is normalized before texturing since the square's texture coordinates assume a unit square texture.
texture(picture.mapToUnitSquare());

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Load the Images and Specify the Labels

set the URL bases for importing the media
URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase,"image/");
URL sndBase = buildURL(mediaBase,"sound/");
URL geoBase = buildURL(mediaBase,"geometry/");
a [-1, 1] square in X and Y with [0, 1] texture coordinates for both of its faces.
GeometryBvr square =
importGeometry(buildURL(geoBase, "square.x"));
import a list of images, some of these images could have been .gif images
ImageBvr pics[] = {
importImage(buildURL(imgBase, "phantom.jpg")),
importImage(buildURL(imgBase, "hiddenBeachSS.jpg")),
importImage(buildURL(imgBase, "hiddenBeachSG.jpg")),
importImage(buildURL(imgBase, "jotunheimen1.jpg")),
importImage(buildURL(imgBase, "redWoodCar.jpg")),
importImage(buildURL(imgBase, "wenatcheeCascades.jpg")),
importImage(buildURL(imgBase, "tulipsHol1.jpg")),
importImage(buildURL(imgBase, "tulipsHol2.jpg")),
importImage(buildURL(imgBase, "yosemiteCreek.jpg")),
importImage(buildURL(imgBase, "kidsUtah.jpg")),
importImage(buildURL(imgBase, "foliageUtah.jpg"))};
construct a corresponding array of behaviors
ArrayBvr pictures = new ArrayBvr(pics);
ditto for corresponding labels
StringBvr lbls[] = {
toBvr("Phantom Is., Crater Lk., Oregon"),
toBvr("Hidden Beach, Klamath, California"),
toBvr("Hidden Beach, Klamath, California"),
toBvr("Jotenheimen, Norway"),
toBvr("Redwoods N.P., California"),
toBvr("Wenatchee, Cascades, Washington"),
toBvr("Tulip Garden, Holland"),
toBvr("Tulip Garden, Holland"),
toBvr("Yosemite, California"),
toBvr("Centerville, Utah"),
toBvr("Bountiful, Utah")};
ArrayBvr lables = new ArrayBvr(lbls);
Construct a NumberBvr counter object, and use it as an interactive index to select a picture and a corresponding lable.
NumberBvr numPics = lables.length();
NumberBvr index = (NumberBvr) (new Counter(numPics)).getBvr().runOnce();
ImageBvr picture = (ImageBvr) pictures.nth(index);
StringBvr lable = (StringBvr) lables.nth(index);

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Boiler Plates
imports
import java.awt.*; use Event and Dimension
import com.ms.dxmedia.*; DirectAnimation classes
import java.net.*; building URLs

public class GeoImage extends DXMApplet {
public void init() {
super.init() ;
setModel(new GeoImageModel(this));
}
}

class GeoImageModel extends Model {
stores the height of the applet viewport in the member variable.
private NumberBvr _halfHeightNum;

GeoImageModel(DXMApplet dxma) {
Dimension dim = dxma.getSize();
The base unit of measure for DirectAnimation is the meter. Convert the size into meters by multiplying it with the pixelBvr.
_halfHeightNum = mul(toBvr(dim.height*0.5),pixelBvr);
}

public void createModel(BvrsToRun blst) {
Don't want part of geoimage to be clipped when its center is at distOfTravel, so set the near plane slightly further than that and set the projection point a bit further than the near plane.
NumberBvr nearDist = add(distOfTravel, mul(toBvr(2.5), maxHalfExtent));
CameraBvr camera = perspectiveCamera(add(nearDist,
mul(maxHalfExtent, toBvr(10))), nearDist);
turn on the lights and render geoimage into an image
GeometryBvr lights = ambientLight;
GeometryBvr scene = union(lights, loopingGeoImage);
ImageBvr renderedGeo = scene.render(camera);
finally set what's to be displayed on a blue background
ImageBvr model = overlay(renderedGeo,
overlay(lableImage,
overlay(picture, solidColorImage(blue))));
the sound behavior to be presented
setSound(loopingSound);
the image behavior to be rendered
setImage(model);

}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section1: Club Microsoft Lighthouse Tutorial Introduction
This is one of the premier demonstrations of the kinds of integration and the possibilities available when using the DirectAnimation libraries. The main feature of this sample is the use of audio and graphics that are both controlled by a common animation description (the wind speed). It integrates 3-D models (the bird, the boat, and the weather vane). It also has more traditional sprite animation (the surf, the trees, the sky, and the boy with the kite). In addition, the sample makes use of synthetic audio, where sound seeds are dynamically manipulated and mixed together randomly for the both the ocean and seagull ambient sounds. This gives a rich audio environment which can respond to the user-controlled wind speed without having to download a long audio track. Events are used to synchronize the surf animation with the ocean surf sound. In addition, the seagull's sound is spatialized based on its 3-D location, and it has a flying behavior which is both autonomous and interactive (when dragging the bird). All three forms of media are coordinated and influenced by weather intensity, which is driven from VBScript by a slider.

The tutorial leads you through the process of creating this complex animation, step-by-step. Section 2 illustrates how to use VBScript to make the scrollbar control the wind speed. Section 3 describes how animated cell images are constructed using a helper class. Section 4 describes the process of integrating 3-D geometries into the sample. Section 5 illustrates the synthetic audio helper class and how it has been used to create some handy synthetic modules. Finally, Section 6 shows how to make the seagull interact with the mouse.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section2: Using scripting to change wind speed
We begin by adding a scroll bar and some simple VBScript to our HTML. The script will call the applet setWindSpeed and pass the value.
<OBJECT ID="ScrollBar1" WIDTH=203 HEIGHT=16
CLASSID="CLSID:DFD181E0-5E2F-11CE-A449-00AA004A803D">;
<PARAM NAME="Size" VALUE="5362;423">
<PARAM NAME="Max" VALUE="10">
<PARAM NAME="LargeChange" VALUE="2">
<PARAM NAME="Orientation" VALUE="1">
</OBJECT>
<script language="VBScript">
<!--
sub ScrollBar1_change()
document.lhouse.setWindSpeed scrollbar1.value
end sub
-->
</script>
Here, back in the lhouseModel class, declare a number of variables that will be used throughout the sample. These variables are declared as switchers so that the behavior (Bvr) they contain (a number) can be updated from an external method or a notifier.
public ModifiableBehavior _windSpeed;
Normalized value between 0 and 1
public ModifiableBehavior _windMode;
public ModifiableBehavior _breezeInterval;
public DXMEvent _grabEvent;
public Vector3Bvr _originalPath;
public Vector3Bvr _actualPath;
This is the method that the applet will call to update the wind speed. Notice the switchTo call that swaps the current Bvr for a new one. Note: to convert a primitive Java data types (such as integers) to behaviors use the toBvr() helper method.
public void setWindSpeed(int val) {
_windSpeed.switchTo( div(toBvr(val),toBvr(10)) );
_windMode.switchTo(mul(add(toBvr(val),toBvr(1)),toBvr(0.9)));
}
The createModel method, tells DirectAnimation how to construct a run time model for the animation.
public void createModel(BvrsToRun blist) {
Begin the demo code by initializing switchers and giving them their default number behaviors. For convenience get the actual Bvr out of the switcher and store it as the variable windSpeed. Also, create a windDistance value based on the windSpeed (this will be used to move the clouds later on). The most interesting variable here is the WindAngle which is a value that changes randomly over time. The example on this page allows you to see the changing values of these numbers as you move the slider.
_windSpeed = new ModifiableBehavior(toBvr(0));
_windMode = new ModifiableBehavior(toBvr(0));
_breezeInterval = new ModifiableBehavior(toBvr(2));

NumberBvr windSpeed = (NumberBvr)_windSpeed.getBvr();
NumberBvr windMode = (NumberBvr)_windMode.getBvr();
NumberBvr windDistance = integral(windSpeed);
NumberBvr windAngle = generateWindAngle(blist);
NumberBvr random = seededRandom(.11);
blist.add(random);
Above, you saw the use of the generateWindAngle to actually get the random value, here is what the method does:
private NumberBvr generateWindAngle(BvrsToRun blist) {
ModifiableBehavior breezeAngle = new ModifiableBehavior(toBvr(0));
Explicitly start a seededRandom behavior.
NumberBvr random = seededRandom(.27);
blist.add(random);
Create an event which triggers after each breeze interval passes.
DXMEvent timerEv = timer((NumberBvr)_breezeInterval.getBvr());
Attach the random value as eventData.
timerEv = timerEv.snapshotEvent(random);
You want a number behavior that refers to itself, so use newUninitBvr().
NumberBvr loop = NumberBvr.newUninitBvr();
To get a randomly changing breeze, create a method that will get called every time the timerEv event occurs, then smoothly transitions our current breezeAngle to a new random breezeAngle. This is the purpose of the newBreeze class, which extends UntilNotifier. Pass it the values it will need to construct and return a new behavior.
UntilNotifier newBreeze = new Breeze((NumberBvr)_windSpeed.getBvr(),
_breezeInterval, breezeAngle, loop);

NumberBvr angle = (NumberBvr)breezeAngle.getBvr();

timerEv = andEvent(timerEv, timerEv.snapshotEvent(angle));
Now, initialize the loop to the value that is the current breezeAngle, until timerEv, when the newBreeze notify method is called.
loop.init((NumberBvr)untilNotify(angle, timerEv, newBreeze));
return this value as the actual breeze angle.
return loop;
}
The callback serves an important function in DirectAnimation. It allows the reconstruction of a running behavior based on its current value and the time that it was triggered. In the breeze class, the sample uses the constructor to pass it all the values it needs to update the current behavior.
class Breeze extends Statics implements UntilNotifier {
private ModifiableBehavior _breezeInterval;
private ModifiableBehavior _breezeAngle;
private NumberBvr _windSpeed;
private NumberBvr _loop;

public Breeze(NumberBvr windSpeed, ModifiableBehavior breezeInterval,
ModifiableBehavior breezeAngle, NumberBvr loop) {
_windSpeed = windSpeed;
_breezeInterval = breezeInterval;
_breezeAngle = breezeAngle;
_loop = loop;
}
Now in the notify method, you can do some actual work.
public Behavior notify(Object eventData, Behavior curBvr, BvrsToRun lst) {
First snapshot (freeze) the random value attached as eventData.
NumberBvr random = (NumberBvr)((PairObject)eventData).getFirst();
Also snapshot the current breezeAngle based on the event time.
NumberBvr oldAngle = (NumberBvr)((PairObject)eventData).getSecond();
Calculate the difference delta between the two and transition the breezeAngle from one to the other over a period of two seconds.
NumberBvr deltaAngle = mul(toBvr(2), sub(random,toBvr(.5)));

_breezeInterval.switchTo(mul(toBvr(5), random));
_breezeAngle.switchTo(add(oldAngle,deltaAngle));

NumberBvr changingAngle =
add(oldAngle, mul(deltaAngle, DxmNumber.smooth0to1(toBvr(2))));

return (NumberBvr)until(changingAngle, timer(toBvr(2)), _loop);
}
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section3: Including Cell Based Images
Here, begin importing the raw images. If the image has multiple cells make use of the cellImage1 utility.
ImageBvr clouds,scene;
cellImage1 kite,ocean1,ocean2,palm1,palm2,palm3,beachboy;

URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase, "image/");
URL geoBase = buildURL(mediaBase, "geometry/");
URL sndBase = buildURL(mediaBase, "sound/");

kite = new cellImage1(buildURL(imgBase, "kite.gif"),4);
scene = importImage(buildURL(imgBase, "scene.jpg"));
ocean1 = new cellImage1(buildURL(imgBase, "ocean.gif"),4);
ocean2 = new cellImage1(buildURL(imgBase, "ocean2.gif"),4);
palm1 = new cellImage1(buildURL(imgBase, "palm1.gif"),5);
palm2 = new cellImage1(buildURL(imgBase, "palm2.gif"),5);
palm3 = new cellImage1(buildURL(imgBase, "palm3.gif"),5);
clouds = importImage(buildURL(imgBase, "clouds.gif"));
beachboy = new cellImage1(buildURL(imgBase, "beachboy.gif"),2);
Here, use the synthetic ocean sounds that are explained in Section 5. The event caused by a crashing wave is used to create an ocean index. An animateTrees method is called to generate psuedo-random tree indexes. These indexes will be used with the showIndex method to determine which tree cell to display.
oceanSynth ocean = new oceanSynth(add(toBvr(.2),windSpeed));
NumberBvr oceanIndex = animateOcean(ocean.soundEvent());
NumberBvr treeIndex1 = animateTrees(windSpeed, 1);
NumberBvr treeIndex2 = animateTrees(windSpeed, .88);
NumberBvr treeIndex3 = animateTrees(windSpeed, .71);
So how does cellImage1 work? The contructor takes an image and frame count and imports that image.
public class cellImage1 extends Statics {
public cellImage1(java.net.URL url, int frameCount) {
super();
_BaseImg = importImage(url);
_FrameCount = toBvr(frameCount);
}
To get a particular frame of the cellImage, the author can make a call to the showIndex method. This will return a properly cropped image. The following code calculates the minimum and maximum points of the indexed image, crops the entire image, then centers the new image.
public ImageBvr showIndex(NumberBvr index) {
NumberBvr actualIndex = sub(sub(_FrameCount, toBvr(1)), index);

Bbox2Bvr frame = _BaseImg.boundingBox();

NumberBvr cellHeight =
div(sub(frame.getMax().getY(),frame.getMin().getY()),
_FrameCount);

NumberBvr cellMin = add(frame.getMin().getY(), mul(cellHeight, actualIndex));
NumberBvr cellMax = add(cellMin, cellHeight);
ImageBvr cellImg =
_BaseImg.crop(
point2(frame.getMin().getX(), cellMin),
point2(frame.getMax().getX(), cellMax));

ImageBvr cntrImg =
cellImg.transform(
translate(toBvr(0), sub(neg(cellMin),div(cellHeight,toBvr(2)))));

return cntrImg;
}
The loopStrip is a handy method that cycles through all the cells at the indicated speed (in frames per second).
public ImageBvr loopStrip(NumberBvr speed) {
return showIndex(
mod(floor(mul(localTime,speed)),_FrameCount));
}

public ImageBvr _BaseImg;
public NumberBvr _FrameCount;
}
Here is how these two methods operate.
private NumberBvr animateOcean(DXMEvent ev) {
Sequence for clam ocean.
Behavior[] calm = { toBvr(0), toBvr(1) };
Sequence for crashing wave.
Behavior[] wave = { toBvr(2), toBvr(3), toBvr(2) };
Cycles through the calm values every 0.5 seconds.
Cycler calmCycle = new Cycler(calm, timer(toBvr(.5)));
Cycles through the calm values every 0.25 seconds.
Cycler crashCycle = new Cycler(wave, timer(toBvr(.25)));
Use an uninitialized behavior so it can refer to itself.
NumberBvr animateOcean = NumberBvr.newUninitBvr();
The behavior is calmCycle until ev, then crashCycle for 0.75 seconds, and then back to the initial state.
animateOcean.init((NumberBvr)
until(calmCycle.getBvr(), ev,
until(crashCycle.getBvr(), timer(toBvr(.75)), animateOcean)));

return animateOcean;
}

private NumberBvr animateTrees(NumberBvr windSpeed, double seed) {
A jitter method gives a semi-random value that oscillates between zero and one.
NumberBvr jitter =
floor(mod(
add(DxmNumber.smooth0to1(mul(sub(toBvr(1.2),windSpeed), toBvr(10*seed))),
(NumberBvr)_breezeInterval.getBvr()),
toBvr(2)));
As the wind speed increases, the trees tend to bend back. To get this effect increase the cell image used.
NumberBvr normalIndex = floor(mul(toBvr(3), windSpeed));
The final index jiggles the bent tree.
return add(normalIndex, jitter);
}
Here, construct moving clouds by translating an infinitely tiled image of clouds by the windDistance.
Bbox2Bvr BB = clouds.boundingBox();

Vector2Bvr cloudPos =
vector2(neg(mod(div(windDistance, toBvr(200)),
sub(BB.getMax().getX(), BB.getMin().getX()) )), toBvr(0));

ImageBvr xfClouds = clouds.transform(translate(cloudPos));

ImageBvr movingClouds = xfClouds.tile().crop(BB.getMin(), BB.getMax());
Here, create an array of all the time-varying sprite images, using loopStrip and showIndex where appropiate.
ImageBvr[] sprites = {
kite.loopStrip(add(windSpeed,toBvr(.2))),
scene,
ocean1.showIndex(oceanIndex),
ocean2.showIndex(oceanIndex),
palm1.showIndex(treeIndex1),
palm2.showIndex(treeIndex2),
palm3.showIndex(treeIndex3),
movingClouds,
beachboy.loopStrip(toBvr(1))
};
Also create an array of points which will be used as the initial positions of the above mentioned time-varying sprites.
Point2Bvr[] spritePos = {
kitePos,
point2(toBvr( 0),toBvr( 0)),
point2(mul(toBvr( 78),pixelBvr),mul(toBvr(-100),pixelBvr)),
point2(mul(toBvr(-252),pixelBvr),mul(toBvr( -21),pixelBvr)),
point2(mul(toBvr(-250),pixelBvr),mul(toBvr( 20),pixelBvr)),
point2(mul(toBvr(-158),pixelBvr),mul(toBvr( 2),pixelBvr)),
point2(mul(toBvr( -98),pixelBvr),mul(toBvr( -1),pixelBvr)),
point2(toBvr( 0),mul(toBvr( 106),pixelBvr)),
bboyPos
};
Then apply the sprite translation to all the sprites, to move them to their initial location.
ImageBvr[] iSprites = new ImageBvr[9];
for(int i=0; i< i++)
iSprites[i] = sprites[i]
.transform(translate(sub(spritePos[i],origin2)));
Overlay all the 2-D sprites (the first overlay is at the top and the last will be at the bottom). This new composite is made pickable for later use.
PickableImage allSprites = new PickableImage(
overlay(iSprites[0], overlay(iSprites[8], overlay(kiteString,
overlay(iSprites[4], overlay(iSprites[5], overlay(iSprites[6],
overlay(iSprites[7], overlay(iSprites[2],
overlay(iSprites[3], iSprites[1] ))))))))));
Finally, obtain the upper right corner of the composite, which will be used to scale the geometries.
Point2Bvr imageUR = allSprites.getImageBvr().boundingBox().getMax();

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section4: Including 3D Geometries
Now we want to create a weather vane, sailboat, and seagull which will look like they are part of the 2D scene we created with our cellImages. In this part of the tutorial, the process of creating the weather vane will be explained. The sailboat and seagull, although more complex, are created in similar fashion.
Here we have a class called weatherVane with a static method called getGeo, which returns a GeometryBvr. This kind of class can be refered to as a DirectAnimation module because it describes a set of media, in this case geometries, and behaviors built around that media, that form a more complex DirectAnimation behavior, in this case a GeometryBvr.
public class weatherVane extends Statics {
public static GeometryBvr getGeo(NumberBvr windAngle,
NumberBvr windDistance, URL importBase) {
Here we import pieces of geometry such as scoops and arrows, which will be used to construct the weather vane.
GeometryBvr nsewGeo = importGeometry(buildURL(importBase, "nsew.x"));
GeometryBvr arrowGeo = importGeometry(buildURL(importBase, "arrow.x"));
GeometryBvr scoopGeo = importGeometry(buildURL(importBase, "scoops.x"));
The arrows are going to rotate based on the wind angle.
GeometryBvr arrow = arrowGeo.transform(rotate(yVector3, windAngle));
The scoops will spin based on the wind speed.
GeometryBvr scoops =
scoopGeo.transform(
compose(rotate(yVector3, mul(toBvr(8),windDistance)),
scale3(toBvr(1.25))));
Combine these to form the complete weather vane (our first DirectAnimation module).
return union(arrow, union(scoops, union(nsewGeo, directionalLight)));
}
}
Back in the lhouseModel class, use the getGeo() model to construct the vane, and transform it to match the perspective of the scene.
GeometryBvr vane =
weatherVane.getGeo(windAngle,windDistance, geoBase).transform(
compose(translate(toBvr(-1.1),toBvr(-0.5),toBvr(0)),
compose(rotate(xVector3, toBvr(Math.PI/12)),
compose(rotate(yVector3, toBvr(Math.PI/4)),
scale3(toBvr(0.6))))));
In order to use the geometry in the scene, convert the geometry to an image. Here, define a helper method that takes any geometry, and the upper right corner of the scene. It then return a rendered and scaled image.
private ImageBvr geometryImage(GeometryBvr geo, Point2Bvr UR) {
CameraBvr camera =
perspectiveCamera(toBvr(1),toBvr(0))
.transform(translate(toBvr(0), toBvr(0), toBvr(2)));

NumberBvr scaleFactor = (NumberBvr)
cond(lte(UR.getX(), UR.getY()), UR.getX(), UR.getY());

return geo.render(camera).transform(scale2(mul(toBvr(2.8), scaleFactor)));
}
Overlay all of the rendered geometry images over the image composed of all the sprites.
ImageBvr composite =
overlay(geometryImage(gull, imageUR),
overlay(geometryImage(sailBoat.getGeo(windSpeed, geoBase), imageUR),
overlay(geometryImage(vane, imageUR), allSprites.getImageBvr())));

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section5: Using Synthetic Audio
Here, compose the audio for this demo. Both the ocean and seagull classes have static methods for defining the sound. This tutorial discusses how the sound is generated for the ocean module.
setSound(mix(ocean.getSound(sndBase), seagull.getSound(sndBase)));
The ocean module makes use of periodic and cycling sounds played by parametrically controlling the rate, gain, and periodicity. By describing how these parameters vary in time with methods, relatively small sound bites can form the basis for rich dynamic sounds. The first implementation of the algorithmic interface defines the characteristics of the pounding surf. Define the roughness (based on the wind speed), gain and rate.
class surf1 extends Statics implements algoFunc {
private NumberBvr _roughness;
public surf1(NumberBvr roughness) {
_roughness = roughness;
}
public Behavior periodFunc() {
return toBvr(0);
}
public Behavior gainFunc() {
return add(toBvr(0.45),mul(toBvr(.4),_roughness));
}
public Behavior rateFunc() {
return add(toBvr(1), sub(toBvr(.5),_roughness));
}
}
After implementing all the algorithmic descriptions for the sounds, define the oceanSynth class. The constructor for this class creates periodicSounds and cyclingSounds based on those descriptors. For more info on periodSound and cyclingSound examine their Java source code in the Lighthouse/utility directory.
public class oceanSynth extends Statics {

public oceanSynth(NumberBvr roughness) {
_wave1 = new periodicSound(new wave1(roughness));
_wave2 = new periodicSound(new wave2(roughness));
_surf1 = new cyclingSound(new surf1(roughness));
_surf2 = new cyclingSound(new surf2(roughness));
}
Now put the sound together. First import the surf and wave components (30K and 60K) each. Then query the sound method for each algoSound, passing it the actual wav files to use. This will return sound behaviors that can be mixed together to give the final sounds.
public SoundBvr getSound(URL importBase) {
SoundBvr wave = importSound(buildURL(importBase, "wave.mp2"),null);

SoundBvr surf = importSound(buildURL(importBase, "surf.mp2"),null);

return mix(_wave1.Sound(wave), mix(_wave2.Sound(wave),
mix(_surf1.Sound(surf), _surf2.Sound(surf))));
}

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section6: Making the seagull react to the mouse
This section describes how to make the seagull react to the user's mouse. When the user clicks and holds down the left mouse button, the seagull can be dragged across the screen. When the mouse button is released, the seagull returns to its original path. First construct the seagull in the same manner as the weather vane in Section 4, and apply its flight path to it.
seagullSynth seagull = new seagullSynth(_actualPath);
GeometryBvr gull = seagull.getGeo(true, geoBase)
.transform(translate(toBvr(0), toBvr(.5), toBvr(0)));
The original path is then constructed with the help of the figure8 utility method. This method uses the spline method to return a path in the form of a figure8.
Vector3Bvr subPath =
(Vector3Bvr)(add( DxmVector3.figure8(),
vector3(sin(localTime),
sin(mul(localTime, toBvr(.25))),
sin(mul(localTime, toBvr(.33))))
.mul(toBvr(.25)) )).runOnce();

_originalPath = (Vector3Bvr)
subPath.transform(
compose( rotate(xVector3, toBvr(Math.PI/8)),
rotate(yVector3, toBvr(Math.PI/2)) ))
.substituteTime(div(localTime, toBvr(2)));
Next an event is created that triggers when the left mouse button is pressed on the pickable image that was created in section 3.
_grabEvent = andEvent(leftButtonDown, allSprites.getPickEvent());
Construct two class objects. Their classes handle the behavior of the bird when it is grabbed, and when it is released.
_grabbedNotify = new grabbedBird(this);
_thrownNotify = new thrownBird(this);
The grabbedBird is a callback just like the Breeze class in Section 2. It links the movement of the bird to the position of the mouse pointer.
class grabbedBird extends Statics implements UntilNotifier {
private lhouseModel _model;

public grabbedBird(lhouseModel model) {
_model = model;
}
Now in the notify method you can do some actual work.
public Behavior notify(Object eventData, Behavior curBvr, BvrsToRun lst) {
Grab the position of the mouse pointer from the eventData tree.
Vector2Bvr offset =
(Vector2Bvr)((PairObject)((PairObject)eventData)
.getSecond()).getSecond();

Vector3Bvr offset3d =
vector3( offset.getX(), mul(toBvr(.75), offset.getY()),
mul(toBvr(-.25),offset.getY()) ).mul(toBvr(30));

Vector3Bvr newPath = add((Vector3Bvr)curBvr, offset3d);

return newPath;
}
}
The thrownBird is a callback just like the Breeze class in Section 2. It returns the seagull to its original path when it's released by the user.
class thrownBird extends Statics implements UntilNotifier {
private lhouseModel _model;

public thrownBird(lhouseModel model) {
_model = model;
}
Now in the notify method you can do some actual work.
public Behavior notify(Object eventData, Behavior curBvr, BvrsToRun lst) {
Obtain actualPath from the lhouseModel class.
Vector3Bvr originalPath = _model._actualPath;
Obtain the initial position of the seagull.
Vector3Bvr pathVector = (Vector3Bvr)originalPath
.substituteTime(toBvr(0));
Create a 3-D vector that contains the postion of the finalPath vector (in class lhouseModel) when throwEvent is triggered.
Vector3Bvr throwVector = (Vector3Bvr)eventData;

Vector3Bvr throwDirection = derivative((Vector3Bvr)curBvr);
Vector3Bvr pathDirection = vector3(toBvr(-1), toBvr(0), toBvr(0));

Vector3Bvr[] points = {
throwVector,
add(throwVector, throwDirection),
add(add(throwVector, pathVector).div(toBvr(2)),
sub(throwDirection, pathDirection)),
sub(pathVector, pathDirection.div(toBvr(3))),
pathVector
};

NumberBvr[] knots = { toBvr(0), toBvr(0), toBvr(0),
toBvr(1), toBvr(2), toBvr(2), toBvr(2) };
NumberBvr[] weights = { toBvr(1), toBvr(1),
toBvr(1), toBvr(1), toBvr(1) };
Create a path from the point of where the seagull was released, to its original starting point.
Vector3Bvr spline = bSpline(3, knots, points, weights,localTime);
Let the seagull fly the path in two seconds, and then return to its original path.
Vector3Bvr throwPath = (Vector3Bvr)
until( spline, timer(toBvr(2)),originalPath);

return throwPath;
}
}
Create a behavior that starts out as _original path, and then changes to the behavior constructed in the grabbedBird class when _grabEvent is triggered.
Vector3Bvr finalPath = (Vector3Bvr)untilNotify(
_originalPath, _grabEvent, _grabbedNotify);
Create an event that gets triggered when the left mouse button is released. Also create an event that snapshots the value of finalPath when throwEvent is triggered.
DXMEvent throwEvent = leftButtonUp;
DXMEvent throwSnapEvent = throwEvent.snapshotEvent(finalPath);
Create a behavior that starts out as finalPath, and then changes to the behavior constructed in the thrownBird class when throwSnapEvent is triggered. This is the composite seagull path that allows the user to grab it, drag it, and release it.
_actualPath = (Vector3Bvr)untilNotify(
finalPath, throwSnapEvent, _thrownNotify);

 © 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectAnimation SDK, Java sample

Asynchronous Loading

This demo makes use of Asynchronous importation APIs to mask load time. Here, the sample plays an opening animation until the media is loaded.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Basic Applet

This simple applet draws a blue solid color image. It shows the proper way to write a DirectAnimation applet.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Button Pick

This applet shows a black button that starts to change colors with time when the users mouse moves over it. When the user clicks on the button with the left mouse button, the applet takes a snapshot of the time-varying color. When the user moves the mouse away from the button, its color returns to black.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Extended Applet

This applet illustrates the construction of a Java DxM model including:

  • importing an image and a sound
  • using the height and width of the applet for scaling the image to fit properly
  • animating the image and looping the sound
  • setting the resulting image and sound to be presented
  • constructing a DxM applet, including the proper steps for initialization

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

GeoApplet1

This applet constructs a spinning cube to fit in the view window.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

GeoApplet2

This applet constructs a spinning cube to fit in the view window. Unlike GeoApplet1, which uses time-varying behaviors for the rotation angles of the spinning cube, this applet uses switchers to control these parameters. It also explicitly controls the sampling and rendering of the model by overriding the tick() method. The applet sets the frame rate to 5 frames per second.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Draggable Geometry Template

The red cube is an example of a draggable geometry. It can be clicked and dragged around and then dropped. It makes use of the DraggableGeometry and ReleaseHandlerGeo utility classes.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Windowless Control Template

The following example shows how DirectAnimation can be used to create a windowless control. The template shows a reactive animation that is seamlessly overlaid with regular HTML elements such as this text. Using dynamic HTML, you can switch the Z ordering of the animation in relation to other elements, such as the text. If the Z value is less than zero, the animation will be below the text and if greater than zero it will be above the text.
Right click to make the cube shrink so the you can read the text.
Left click to interact with the cube.
Click on the button to dynamically switch the Z ordering of the Text and Animation.

For a short tutorial on this sample click this button: TUTORIAL
View Java Source Code


DirectAnimation SDK, Java sample

Draggable Image Template

The red square is an example of a draggable image. It can be clicked and dragged around and then dropped. It makes use of the DraggableImage and ReleaseHandlerImg utility classes.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Jump URL Template

This template shows how DirectAnimation can be used along with Java. When you move the mouse over the picture of Seattle, a sound will start playing and a tip box will appear with instructions. The pickable image and sound are imported by using DirectAnimation. Linking to another webpage is done by using the Java's showDocument and getAppletContext methods.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Using AFC Menus

This sample shows how to use DirectAnimation with the Applet Foundation Classes (AFC). The menu is created by using AFC methods. The animation of the image (scaling, translating, rotating) is done in DirectAnimation.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

Using AFC Scrollbars

This sample shows how to use DirectAnimation with the Applet Foundation Classes (AFC). The scrollbar is created by using AFC classes and methods. The speed of the rotation of the geometry is mapped to the position of the scrollbar in DirectAnimation.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectAnimation SDK, Java sample

DirectAnimation and VBScripting

This example uses Forms 2.0 Controls and VBScript to send events
to the DirectAnimation applet and change the material color.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code

Dec Hex
Red
Green
Blue


DirectAnimation SDK, Java sample

Video Playback

This applet uses AWT UI controls to control the rate of a video playback. Click on the various AWT buttons to pause, restart, fast forward, or fast reverse. Click on the pause button a second time to un-pause the playback. You can also use the scrollbar to control the rate at a finer level.

For a short tutorial on this sample click this button: TUTORIAL

View Java Source Code


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section 1: Latency Mask with Asynchronous Download
This demo makes use of Asynchronous importation APIs to mask load time. Here, an opening animation plays until the media is loaded.

This class constructs the image and sound behaviors for the model.
class AsyncModel extends Model {

public void createModel(BvrsToRun blist) {
try {
Prepare the out parameters for importMovie.
ImageBvr[] movieImg = {null};
SoundBvr[] movieSnd = {null};
NumberBvr[] progress = {null};
ModifiableBehavior progressSw = new ModifiableBehavior(toBvr(0));
URL movieURL;
The location of the movie.
movieURL = buildURL(getImportBase(),"movie/movie.avi");
Create a stand-in image.
loadAnimation waitLogo = new loadAnimation();
ImageBvr standinImg = waitLogo.getImage((NumberBvr)progressSw.getBvr());
Create a movie image behavior and a movie sound behavior by importing an avi file.
importMovie(movieURL, movieImg, movieSnd,
standinImg, silence,
null, progress, null);

progressSw.switchTo(progress[0]);
Set the image and sound behaviors for this model. The stand-in image will be displayed while the movie is being downloaded. In this example, the stand-in sound is silence.
setImage(overlay(movieImg[0], solidColorImage(black)));
setSound(movieSnd[0]);
} catch(MalformedURLException ex) {}
}
}
Set the model in our applet class.
public class AsyncApplet extends DXMApplet {
public void init() {
super.init();
setModel(new AsyncModel());
}
}
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section 2: Stand-In Image

Define an opening animation used for latency masking during media files download.
class loadAnimation extends Statics {
public ImageBvr getImage(NumberBvr progress) {
There are two primary images, introImg and radarImg, in this animation. The introImg composes of a few text images and a progress indicator.
String[] intro = {"Direct", "X", "Media", "for Animation", "loading...please wait"},
info = {"Integrated", "2D", "3D", "and", "Audio", "for", "Java"};
double[] size = {3, 7, 3, 2, 1},
startPos = {-500,50, 0,500, 500,50, 6,-10, 0,-50},
endPos = {-98,50, 0,50, 100,50, 6,-10, 0,-50},
trigger = {.5, 1.5, 2.5, 4, 5};
ImageBvr[] introImgs = new ImageBvr[intro.length];
Create an array of text images for the introImg.
for(int i=0; i<intro.length; i++) {
Point2Bvr startPt = point2(mul(toBvr(startPos[2*i]),pixelBvr), mul(toBvr(startPos[2*i+1]),pixelBvr)),
endPt = point2(mul(toBvr(endPos[2*i]),pixelBvr), mul(toBvr(endPos[2*i+1]),pixelBvr));

FontStyleBvr fs = defaultFont.family(toBvr("Arial")).color(blue).bold();

ImageBvr textIm = textImage(toBvr(intro[i]), fs)
.transform(scale2(size[i]));

introImgs[i] = move(textIm, startPt, endPt, 1, trigger[i]);
}

introImgs[3] = introImgs[3].opacity(ramp(trigger[3],.3));
introImgs[4] = introImgs[4].opacity(mul(ramp(trigger[4],1), sin(mul(toBvr(4),localTime))));
Compose the text images together and overlay them on a black background.
ImageBvr introImg = solidColorImage(black);
for(int i=0; i<intro.length; i++)
introImg = overlay(introImgs[i],introImg);
Add a progress status indicator to the introImg.
Vector2Bvr statPos = vector2(toBvr(0),mul(toBvr(-80),pixelBvr));

FontStyleBvr fs = defaultFont.family(toBvr("Arial")).color(green);
ImageBvr statusImg = textImage(concat(mul(progress,toBvr(100))
.toString(toBvr(2)), toBvr("% complete") ), fs)
.opacity(ramp(trigger[4],1));

statusImg = statusImg.transform(compose(translate(statPos),scale2(.8)));
introImg = overlay(statusImg, introImg);
The radarImg has two parts. The infoImg is composed of a few text images clipped to a path of a rotating pie. The lineImg draws the the rotating edge of the pie.
ImageBvr infoImg = emptyImage;
for(int i=0; i<info.length; i++) {
infoImg = overlay(radiate(info[i], (2*Math.PI*i/info.length)+.3), infoImg);
}
infoImg = overlay(infoImg, solidColorImage(black));
Path2Bvr origin = ray(point2(1,0));
Path2Bvr pie = concat(origin,
arc(toBvr(0), mod(localTime, toBvr(2*Math.PI)),
toBvr(1), toBvr(1)));
infoImg = infoImg.clip(fillMatte(pie));
Create a line of length 0.05 meter then rotate it at the same rate the pie is rotating.
Path2Bvr ln = ray(point2(.05,0));
ImageBvr lineImg = ln.draw(defaultLineStyle.width(toBvr(.08*cm)).color(white)),
radarImg = overlay(lineImg.transform(rotate(localTime)), infoImg);
Delay the animation to create a more interesting effect.
radarImg = (ImageBvr)until(emptyImage, timer(toBvr(6)), radarImg);
introImg = overlay(radarImg, introImg);
return (ImageBvr)until(solidColorImage(black), timer(toBvr(1)), introImg);
}
This function creates an image from the given text string. It then moves the image to the position defined by the given radians.
ImageBvr radiate(String text, double radians) {
Rotate the vector (0.04, 0) by the given radians, that's where we'll translate the image to.
Vector2Bvr vec = vector2(.04,0).transform(rotate(toBvr(radians)));
FontStyleBvr fs = defaultFont.family(toBvr("Arial")).color(red).bold();
ImageBvr img = textImage(toBvr(text), fs)
.transform(scale2(1.3));

return img.transform(translate(vec));
}
Move the given image from the start position to the end position after second at the given rate.
ImageBvr move(ImageBvr img, Point2Bvr start, Point2Bvr end, double rate, double trigger) {
Vector2Bvr startPos = sub(start, origin2),
path = add(startPos, sub(end,start).mul(ramp(0,rate)) );
path = (Vector2Bvr) until(startPos, timer(toBvr(trigger)), path);
return img.transform(translate(path));
}
Before trigger seconds, return 0. After trigger seconds, return localTime*rate. When localTime*rate > 1, return 1.
NumberBvr ramp(double trigger, double rate) {
NumberBvr rampVal = mul(localTime,toBvr(rate));
return (NumberBvr) cond(lte(localTime,toBvr(trigger)), toBvr(0),
cond(lt(rampVal,toBvr(1)), rampVal, toBvr(1)));
}
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Basic Applet
This applet illustrates the proper steps to construct and initialize a simple DirectAnimation applet.

import com.ms.dxmedia.*; direct animation libraries.
This class extends the DXMApplet class. The model you set in this class, by calling the setModel() method, is the model that will be displayed.
public class BasicApplet extends DXMApplet {
The start() and stop() methods of DXMApplet restart and stop the DirectX Media animation loop already, so you don't need to implement these methods if you don't have other activities you need to stop and restart.

Set the model in the init() method.
public void init() {
Always call the super classes init first to ensure codeBase is set.
super.init() ;
Now set the model.
setModel(new BasicModel());
}
}
This class extends the Model class. The createModel method in this class is where you construct your animation.
class BasicModel extends Model {
Create the animation in the createModel method. In this example, we'll just display a solid blue image.
public void createModel(BvrsToRun blist)
{
Set the image that actually gets displayed using setImage()
setImage(solidColorImage(blue));
}
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Button that Reacts to a Mouse

This applet shows a black button that starts to change colors with time
when the user's mouse moves over it. When the user clicks on the button with
the left mouse button, the applet takes a snapshot of the time-varying color.
When the user moves the mouse away from the button, its color returns to black.

This applet illustrates the following:

- creating a solid-colored square.
- making that square react to mouse over and left mouse button clicks.

import com.ms.dxmedia.*; All DirectAnimation classes
ButtonPick is an applet that invokes ButtonPickModel which constructs a solid-colored square.
public class ButtonPick extends DXMApplet {
public void init() {
super.init() ;
setModel (new ButtonPickModel());
}
}
In the ButtonPickModel class the createModel method is where you construct your animation.
class ButtonPickModel extends Model {

public void createModel(BvrsToRun blist)
{
Create a detectable image and crop it to 100 by 100 pixels.
ImageBvr detectImg = detectableEmptyImage.
crop(point2(mul(toBvr(-50),pixelBvr), mul(toBvr(-50),pixelBvr)),
point2(mul(toBvr(50),pixelBvr), mul(toBvr(50),pixelBvr)));
Make the above created image pickable.
PickableImage pickPImg = new PickableImage(detectImg);
Create an event that will trigger when the mouse moves over detectImg.
DXMEvent pickEv = pickPImg.getPickEvent();
Create an event that will trigger when both the mouse moves over detectImg, and the left mouse button is clicked.
DXMEvent clickEv = andEvent(leftButtonDown, pickEv);
Create a color behavior that changes its hue with time.
ColorBvr changeClr = colorHsl(add(mul(sin(
localTime),toBvr(0.5)),toBvr(0.5)),
toBvr(0.5),toBvr(0.5));
Create a color behavior that starts out as black, changes to changeClr when the mouse moves over detectImg (pickEv), and returns to black after the mouse is no longer over detectImg (notEvent(pickEv)).
ColorBvr overClr = ColorBvr.newUninitBvr();
overClr.init(until(
black,pickEv,until(changeClr,notEvent(pickEv),overClr)));
Create an event that takes a snapshot of overClr when detectImg is clicked with the left mouse button.
DXMEvent snapEv = clickEv.snapshotEvent(overClr);
Create two color behaviors. One (snapClr) that starts out as overClr, and changes to whatever color overClr is when detectImg is clicked with the left mouse button. The second (totalClr) starts out as snapClr, and changes to black when the mouse is no longer over detectImg.
ColorBvr snapClr = (ColorBvr)untilNotify(overClr,snapEv,
new ButtonPickSnapshot());

ColorBvr totalClr = ColorBvr.newUninitBvr();
totalClr.init(until(
snapClr,notEvent(pickEv),totalClr));
Create a solid color image, crop it to 100 by 100 pixels, and apply the color behavior of totalClr to it.
ImageBvr initImg = solidColorImage(totalClr).
crop(point2(mul(toBvr(-50),pixelBvr), mul(toBvr(-50),pixelBvr)),
point2(mul(toBvr(50),pixelBvr), mul(toBvr(50),pixelBvr)));
Put the pickable Image on top of initImg.
ImageBvr finalImg = overlay(pickPImg.getImageBvr(),initImg);
Display the image on a blue background.
setImage(overlay(finalImg, solidColorImage(blue)));
}
}

class ButtonPickSnapshot extends Statics implements UntilNotifier {

public Behavior notify(Object eventData,
Behavior currentRunningBvr, BvrsToRun btr) {
Returns the color of overClr when the left mouse button is clicked on detectImg.
return (ColorBvr)eventData;
}
}
Thats all there is to it. Happy animating...

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Extended Applet
This applet illustrates the construction of a DxM model including:
1) importing an image and a sound
2) using the height and width of the applet for scaling the image to fit properly
3) animating the image and looping the sound
4) setting the resulting image and sound to be presented
5) constructing a DxM applet including the proper steps for initialization

import com.ms.dxmedia.*; direct animation libraries
import java.awt.*; for getting the applet dimension
import java.net.*; for URLs
This class extends the DXMApplet class. The model you set in this class, by calling the setModel() method, is the model that will be displayed.
public class ExtendedApplet extends DXMApplet {
The start() and stop() methods of DXMApplet restart and stop the DirectX Media animation loop already, so you don't need to implement these methods if you don't have other activities you need to stop and restart.

Set the model in the init() method.
public void init() {
Always call the super classes init first to ensure codeBase is set.
super.init() ;
Now set the model.
setModel(new ExtendedModel(this));
}
}
This class extends the Model class. The createModel method in this class is where you construct your animation. This example will make use of two of the primary media types supported by DirectAnimation: image and sound.
class ExtendedModel extends Model {
Get the size of the applet in the constructor, and store it in the member variables.
ExtendedModel(DXMApplet dxma) {
Get the size of the applet.
Dimension dim = dxma.getSize();
The base unit of measure for DirectAnimation is the meter. Convert the size into meters by multiplying it with the pixelBvr.
_halfWidthNum = mul(toBvr(dim.width*0.5),pixelBvr);
_halfHeightNum = mul(toBvr(dim.height*0.5),pixelBvr);
Notice the use of the toBvr() call. This helper function is used extensively in DirectAnimation to convert Java primitive data types to DxM behaviors. As you learn more about the system you will begin to appreciate the appreciate the power of behaviors, which can be time-varying values.
}
Create the animation in the createModel method.
public void createModel(BvrsToRun blist)
{
Build up a URL to import relative to.
URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase, "image/");
URL sndBase = buildURL(mediaBase, "sound/");
Create an image behavior by importing a bitmap.
ImageBvr img = importImage(buildURL(imgBase, "phantom.jpg"));
Create a sound behavior by importing a wave file.
SoundBvr snd = importSound(buildURL(sndBase, "earth.mp2"), null);
Find the length of the diagonal of the imported image, we'll use it later to scale the image to fit in the viewport. halfDiagonalNum = sqrt(xNum * xNum + yNum * yNum);
Point2Bvr maxPt2 = img.boundingBox().getMax();
NumberBvr xNum = maxPt2.getX();
NumberBvr yNum = maxPt2.getY();
NumberBvr halfDiagonalNum = sqrt(add(mul(xNum, xNum), mul(yNum, yNum)));
Find the smaller of the width and height.
NumberBvr minHalfExtNum = (NumberBvr)cond(lt(_halfWidthNum, _halfHeightNum),
_halfWidthNum, _halfHeightNum);
Create an image that fits in the viewport.
ImageBvr scaledImg = img.transform(scale2(div(minHalfExtNum,
halfDiagonalNum)));
Create a rotating image
ImageBvr rotatingImg = scaledImg.transform(rotate(localTime));
Set the image that actually gets displayed using setImage()
setImage(overlay(rotatingImg, solidColorImage(black)));
Create a sound that loops continuously.
SoundBvr loopingSnd = snd.loop();
And set the sound that gets played using setSound()
setSound(loopingSnd);
}

private NumberBvr _halfWidthNum, _halfHeightNum;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
GeoApplet1: A Spinning Cube
This applet constructs a spinning cube to fit in the view window. It illustrates how to import a geometry, manipulate it, and view it with a camera.

import com.ms.dxmedia.*; direct animation libraries
import java.awt.*; for getting the applet dimension
import java.net.*; for URLs
This class extends the DXMApplet class. The model you set in this class, by calling the setModel() method, is the model that will be displayed.
public class GeoApplet1 extends DXMApplet {
Set the model in the init() method.
public void init() {
Always call the super classes init first to ensure codeBase is set.
super.init() ;
Now set the model.
setModel (new GeoModel(this));
}
}
This class extends the Model class. The createModel method in this class is where you construct your animation.
class GeoModel extends Model {
Get the size of the applet in the constructor, and stores it in the member variables.
GeoModel(DXMApplet dxma) {
Get the size of the applet.
Dimension dim = dxma.getSize();
The base unit of measure for DirectAnimation is the meter. Convert the size into meters by multiplying it with the pixelBvr.
_halfWidthNum = mul(toBvr(dim.width*0.5),pixelBvr);
_halfHeightNum = mul(toBvr(dim.height*0.5),pixelBvr);
}
This function scales the geometry uniformly to fit in the unit box and centers it at the origin. The bounding box of the resulting geometry will be -0.5 to 0.5 in its largest dimension.
GeometryBvr mapToCenteredUnitBox(GeometryBvr geo) {
Find the extent and the center of the geometry.
Bbox3Bvr bbx3 = geo.boundingBox();
Point3Bvr minPt3 = bbx3.getMin();
Point3Bvr maxPt3 = bbx3.getMax();

Vector3Bvr extVec3 = sub(maxPt3, minPt3);
Point3Bvr centerPt3 = add(minPt3, extVec3.div(toBvr(2)));

NumberBvr maxExtNum = max(extVec3.getX(),
max(extVec3.getY(),
extVec3.getZ()));
Move the object to the origin, and resize it. Translate takes effect before scale is how compose works.
Transform3Bvr normalizingXf3 =
compose(scale3(div(toBvr(1), maxExtNum)),
translate(sub(origin3, centerPt3)));

return geo.transform(normalizingXf3);
}
Create the animation in the createModel method.
public void createModel(BvrsToRun blist) {
Build up a URL to import relative to.
URL mediaBase = getImportBase();
URL geoBase = buildURL(mediaBase, "geometry/");
Import a cube, scale it to the unit cube and center it at the origin. The resulting cube has a bounding box of -0.5 to 0.5 in all 3 dimensions.
GeometryBvr geo = importGeometry(buildURL(geoBase, "cube.x"));
geo = mapToCenteredUnitBox(geo);
Spin the cube around the origin. Find the smaller of the halfWidth and halfHeight of the view window, and use it to scale the cube so that the rendered image for the cube will be about half the size of the viewport. The part of the cube that's exactly on the viewing plane (Z = 0) will be exactly half the size of the viewport, the part that's behind the plane will be smaller, and the part that's in front will be bigger.
NumberBvr minHalfExtNum = min(_halfWidthNum, _halfHeightNum);
geo = geo.transform(compose(scale3(minHalfExtNum),
compose(rotate(yVector3, localTime),
rotate(zVector3, mul(localTime, toBvr(1.3))))));
Make the color time-varying.
geo = geo.diffuseColor(colorHsl(mul(localTime, toBvr(0.3)),
toBvr(0.8), toBvr(0.6)));
The near plane should be bigger than the max Z (in this case, sqrt(2)*minHalfExtNum after the cube is scaled to fit half viewport) of the bounding box of the spinning cube, so the cube doesn't get clipped out. The projection point determines the amount of perspective you'll see. The farther away it is from the viewing plane, the less perspective will result. Here, it's set to 5 times the near plane.
NumberBvr maxZNum = mul(sqrt(toBvr(2)), minHalfExtNum);
NumberBvr projPointNum = mul(toBvr(5), maxZNum);
CameraBvr cam = perspectiveCamera(projPointNum, maxZNum);
Overlay the cube on top of the color image background, and get the image displayed.
setImage(overlay(union(geo, directionalLight).render(cam),
solidColorImage(blue)));
}
max: returns max(x, y)
public static NumberBvr max(NumberBvr x, NumberBvr y) {
return (NumberBvr) cond(gt(y, x), y, x);
}
min: returns min(x, y)
public static NumberBvr min(NumberBvr x, NumberBvr y) {
return (NumberBvr) cond(lt(y, x), y, x);
}

private NumberBvr _halfWidthNum, _halfHeightNum;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
GeoApplet2: A Cube Spinning at 5 Frames Per Second
This applet constructs a spinning cube to fit in the view window. It illustrates how to import a geometry, manipulate it, and view it with a camera. Unlike GeoApplet1, which uses time-varying behaviors for the rotation angle of the spinning cube, this applet uses switchers to control these same parameters. It also explicitly controls the sampling and rendering of the model by overriding the tick() method.

import com.ms.dxmedia.*; direct animation libraries
import java.awt.*; for getting the applet dimension
import java.net.*; for URLs
import java.applet.Applet;
Create a DXMCanvas object and add it to the applet.
public class GeoApplet2 extends Applet {
public void init() {
setLayout(new BorderLayout());
GeoCanvas cv = new GeoCanvas(this);
add("Center", cv);
}
}
Override the tick method in DXMCanvas class to control the frame rate. Also create a switcher for each animating angle of the cube.
class GeoCanvas extends DXMCanvas {

public GeoCanvas(GeoApplet2 geoa) {
The rotation angles of the cube are switchers. Initialize each of them to a zero number behavior.
NumberBvr zeroNum = Statics.toBvr(0);
_yAngleSw = new ModifiableBehavior(zeroNum);
_zAngleSw = new ModifiableBehavior(zeroNum);
Now set the model.
setModel(new GeoModel(geoa, this));
}
Override the tick() to control the frame generation explicitly. Before calling super.tick(), update the values of the switchers for the next frame. This is called automatically by the system.
public void tick() {
Calculate the next tick time.
nextTickTime += 1/DESIREDFRAMERATE;
getCurrentTime returns the DirectAnimation global time. It starts at zero when the model is started. Switch the rotating angle of the cube based on the current time here.
double currTime = getCurrentTime();
_yAngleSw.switchTo(Statics.toBvr(currTime));
_zAngleSw.switchTo(Statics.toBvr(currTime*1.3));
Explicitly sample and display the model. Without this, you'd see a blank window.
super.tick();
Calculate how long the applet needs to sleep to achieve the desired frame rate. sleep() takes milliseconds so multiply by 1000.
long remainingTime = Math.round(1000*(nextTickTime - getCurrentTime()));
If you're running behind, sleep(0).
if (remainingTime < 0) remainingTime = 0;

try { Thread.sleep(remainingTime); } catch(InterruptedException e) {}
}
This is an approximate frame rate.
static final double DESIREDFRAMERATE = 5;
double nextTickTime = 0;
ModifiableBehavior _yAngleSw, _zAngleSw;
}
This class extends the Model class. The createModel method in this class is where you construct your animation.
class GeoModel extends Model {
Get the size of the applet in the constructor, and stores it in the member variables.
GeoModel(GeoApplet2 geoa, GeoCanvas cv) {
Get the size of the applet.
Dimension dim = geoa.getSize();
The base unit of measure for DirectAnimation is the meter. Convert the size into meters by multiplying it with the pixelBvr.
_halfWidthNum = mul(toBvr(dim.width*0.5),pixelBvr);
_halfHeightNum = mul(toBvr(dim.height*0.5),pixelBvr);
The spinning angles of the cube are switchers defined in the GeoApplet2 class. Save the references away so you can use them in the createModel() method.
_yAngleNum = (NumberBvr)cv._yAngleSw.getBvr();
_zAngleNum = (NumberBvr)cv._yAngleSw.getBvr();
}
This function scales the geometry uniformly to fit in the unit box and centers it at the origin.
GeometryBvr mapToCenteredUnitBox(GeometryBvr geo) {
Find the extent and the center of the geometry.
Bbox3Bvr bbx3 = geo.boundingBox();
Point3Bvr minPt3 = bbx3.getMin();
Point3Bvr maxPt3 = bbx3.getMax();

Vector3Bvr extVec3 = sub(maxPt3, minPt3);
Point3Bvr centerPt3 = add(minPt3, extVec3.div(toBvr(2)));

NumberBvr maxExtNum = max(extVec3.getX(),
max(extVec3.getY(),
extVec3.getZ()));
Move the object to the origin, and resize it.
Transform3Bvr normalizingXf3 =
compose(scale3(div(toBvr(1), maxExtNum)),
translate(sub(origin3, centerPt3)));

return geo.transform(normalizingXf3);
}
Create the animation in the createModel method.
public void createModel(BvrsToRun blist) {
Build up a URL to import relative to.
URL mediaBase = getImportBase();
URL geoBase = buildURL(mediaBase, "geometry/");
Import a cube, scale it to the unit cube and center it at the origin. The resulting cube has a bounding box of -0.5 to 0.5 in all 3 dimensions.

GeometryBvr geo = importGeometry(buildURL(geoBase, "cube.x"));
geo = mapToCenteredUnitBox(geo);
Spin the cube around the origin. Find the smaller of the halfWidth and halfHeight of the view window, and use it to resize the cube. The rendered image for the cube will be about half the size of the viewport. The part of the cube that's exactly on the viewing plane (Z = 0) will be exactly half the size of the viewport, the part that's behind the plane will be smaller, and the part that's in front will be bigger. The rotation angles around the yVector and zVector are switchers. The applet that displays the model updates their values frequently to create a spinning cube.
NumberBvr minHalfExtNum = min(_halfWidthNum, _halfHeightNum);
geo = geo.transform(
compose(scale3(minHalfExtNum),
sacle to fit half viewport
compose(rotate(yVector3, _yAngleNum),
rotate(zVector3, _zAngleNum))));
The hue of the color is a time-varying behavior. You can mix imperative (modifying the switchers and controlling the frame loop explicitly) and declarative (define the behaviors at a higher level) programming in DirectAnimation, and they'll work just fine.
geo = geo.diffuseColor(colorHsl(mul(localTime, toBvr(0.3)),
toBvr(0.8), toBvr(0.6)));
The near plane should be bigger than the max Z (in this case, sqrt(2)*minHalfExtNum after the cube is scaled to fit half viewport) of the bounding box of the spinning cube, so the cube doesn't get clipped out The projection point determines the amount of perspective you'll see. The farther away it is from the viewing plane, the less perspective will result. Set it to 5 times the near plane here.
NumberBvr maxZNum = mul(sqrt(toBvr(2)), minHalfExtNum);
NumberBvr projPointNum = mul(toBvr(5), maxZNum);
CameraBvr cam = perspectiveCamera(projPointNum, maxZNum);
Overlay the cube on top of the color image background, and get the image displayed.
setImage(overlay(union(geo, directionalLight).render(cam),
solidColorImage(red)));
}
max: returns max(x, y)
public static NumberBvr max(NumberBvr x, NumberBvr y) {
return (NumberBvr) cond(gt(y, x), y, x);
}
public static NumberBvr min(NumberBvr x, NumberBvr y) {
return (NumberBvr) cond(lt(y, x), y, x);
}

private NumberBvr _yAngleNum, _zAngleNum;
private NumberBvr _halfWidthNum, _halfHeightNum;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
min: returns min(x, y)

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

s DirectX Media SDK DirectAnimation Tutorial
Tutorial Home Page
Draggable Geometry

This applet shows a red cube that can be dragged around the applet.
Dragging actually consists of three parts: grabbing, dragging and releasing.
Grabbing occurs when the left mouse button is pressed and held down over the
red cube. Dragging happens when the mouse moves within the applet. During
this process, the color of the cube changes to blue. Releasing happens when
the left mouse button is released, and the cube is dropped in that position,
with its color returning to red.

It illustrates the following:

- making a imported cube draggable.
- getting events that trigger when the cube is grabbed and released.
- changing the color of the cube when it is being dragged.
- returning the cube to its original color when it is released.

import com.ms.dxmedia.*; All DirectAnimation classes
import utility.*; the DraggableImage class
import java.net.*; the Java URL classes

public class GeometryDrag extends DXMApplet {
public void init() {
super.init() ;
setModel (new GeometryPickTestModel());
}
}
In the GeometryPickTestModel class the createModel method is where you construct your animation.
class GeometryPickTestModel extends Model {
public void createModel(BvrsToRun listBvrs) {
Import the cube rotate it and scale it down.
URL mediaBase = getImportBase();
URL geoBase = buildURL(mediaBase,"geometry/");
GeometryBvr geo = importGeometry(buildURL(geoBase,"cube.x"));
geo = geo.transform(compose(
rotate(vector3(1,1,1), localTime),
scale3(1*cm) ));
Make geo draggable by creating a DraggableGeometry class object (grabGeo).
DraggableGeometry grabGeo = new DraggableGeometry(geo, origin3);
Initialize clr. Let it start out as red, change it to blue, when the cube is grabbed, and return to red when the cube is released. The grab and release events are obtained from the getGrabEvent() and getReleaseEvent() methods of the DraggableGeometry class respectively.
ColorBvr clr = ColorBvr.newUninitBvr();
clr.init(until(red, grabGeo.getGrabEvent(),
until(blue, grabGeo.getReleaseEvent(), clr)));
Get the GeometryBvr part of grabGeo, by calling the getGeometryBvr() method of DraggableGeometry.
GeometryBvr pickableGeo = grabGeo.getGeometryBvr();
Apply clr to pickableGeo.
pickableGeo = pickableGeo.diffuseColor(clr);

pickableGeo = union(pickableGeo, directionalLight);

CameraBvr cam = perspectiveCamera(toBvr(10*cm),toBvr(5*cm));
overlay the rendered on a black background.
setImage(overlay(pickableGeo.render(cam), solidColorImage(black)));
}
}
That's all there is to it. Happy animating...

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Constructing a Windowless Control

This template demonstrates how to construct an animation that makes use of IE4 windowless controls. It illustrates the following: - Using the modelmaker applet - Using the dxactrl (DirectAnimation windowless control) - Constructing the model and passing it to the control
import com.ms.dxmedia.*;
import module.*; This gets ReactiveCube
import java.net.*;
When designing windowless controls, the Java applet is used purely to construct the model. At runtime, hand the finished model over to the windowless control to be displayed.
class WindowlessModel extends Model {
public void createModel(BvrsToRun blist) {
Create any type of animation you like here... it is completely up to you what goes into the model.

The image is simply the rendered cube without any background. Since you want to overlay the windowless control with other HTML elements, specifically avoid a solidColor background.
setImage(cubeGeo.render(Cam));
setSound(cube.getSoundBvr());
}
}
Here is the important part, rather than extending DXMApplet as usual, extend ModelMakerApplet. Aside from the name, the construction is exactly the same as if you were doing a normal applet.
public class WindowlessApplet extends ModelMakerApplet {

public void init() {
Always call the super classes init first to ensure codeBase is set.
super.init() ;
Now set the model.
setModel (new WindowlessModel());
}
}

<!--
In the HTML file we place the DirectAnimation windowless control. This is what will actually display our model. Notice you can set it's style properties to get the proper layout and sizing. See IE4 documentation on style sheets for more information about using them.
-->
<OBJECT STYLE="POSITION:ABSOLUTE; TOP:45; LEFT:35%; WIDTH:375; HEIGHT:375; Z-INDEX:1"
ID="dxactrl" CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D"></OBJECT>

<!--
Also insert the applet which constructs your model. Notice that it's width and height are zero since it is only used to construct the animation
-->
<APPLET CODEBASE="IE4_Windowless" CODE=WindowlessApplet.class WIDTH=0 HEIGHT=0 ID=javaApp></APPLET>

<!--
A script is used to bridge the gap and pass the needed view, image and sound to the dxactrl for display.
-->
<SCRIPT LANGUAGE="VBScript">
<!--
AnimationOnTop = false

sub window_onLoad
dxactrl.View = javaApp.grabViewComPtr
dxactrl.Image = javaApp.grabImageComPtr
dxactrl.Sound = javaApp.grabSoundComPtr

' Start the control viewing
dxactrl.Start
end sub

Sub ChangeZ_OnClick
If AnimationOnTop Then
AnimationOnTop = false
dxactrl.style.zindex = 1
Else
AnimationOnTop = true
dxactrl.style.zindex = -1
End If
End Sub
-->
</SCRIPT>

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Draggable Image
This applet shows a red square that can be dragged around the applet.
Dragging actually consists of three parts: grabbing, dragging and releasing
Grabbing occurs when the left mouse button is pressed and held down over the
red square. Dragging happens when the mouse moves within the applet. During
this process, the color of the square changes to blue. Releasing happens when
the left mouse button is released, and the square is dropped in that position,
with its color returning to red.

It illustrates the following:

- making a square image draggable.
- getting events that trigger when the image is grabbed and released.
- changing the color of the square when it is being dragged.
- returning the square to its original color when it is released.

import com.ms.dxmedia.*; All DirectAnimation classes
import utility.*; the DraggableImage class

public class ImageDrag extends DXMApplet {
public void init() {
super.init() ;
setModel (new ImagePickTestModel());
}
}
class ImagePickTestModel extends Model {
public void createModel(BvrsToRun listBvrs) {

In the ImagePickTestModel class the createModel method is where you construct your animation.
ColorBvr clr = ColorBvr.newUninitBvr();

Create an uninitialized ColorBvr (clr).
ImageBvr blockImg = solidColorImage(clr).
crop(point2(toBvr(0), toBvr(0)),
point2(toBvr(0.005), toBvr(0.005)));

Create cropped square, and apply clr's color behavior to it.
DraggableImage grabImg = new DraggableImage(blockImg, origin2);
Make blockImg draggable by creating a DraggableImage class object (grabImg).

clr.init(until(red, grabImg.getGrabEvent(),
until(blue, grabImg.getReleaseEvent(), clr)));

Initialize clr. Let it start out as red, change it to blue, when the square is grabbed, and return to red when the square is released. The grab and release events are obtained from the getGrabEvent() and getReleaseEvent() methods of the DraggableImage class respectively.
ImageBvr pickableBlockImg = grabImg.getImageBvr();

Get the ImageBvr part of grabImg, by calling the getImageBvr() method of DraggableImage.
setImage(overlay(pickableBlockImg, solidColorImage(black)));
}
}

overlay pickableBlockImg on a black background.

That's all there is to it. Happy animating...
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Using DirectAnimation to Jump to another Website
 import com.ms.dxmedia.*;
import java.awt.*;
import java.net.*; gets URL.
import java.applet.*; gets getAppletContext.

public class JumpURL extends DXMApplet {

public void init() {
super.init() ;
JumpURLModel newJump = new JumpURLModel();
setModel(newJump);

There are two main pieces to any DirectAnimation applet, the DXMApplet class and the Model class. To use the DirectAnimation classes, import the media libraries like this:
newJump.appLink(getAppletContext());
}
}

Call AppletContext() and set _getAppContext to its return. _getAppContext will be used to call showDocument().
class JumpURLModel extends Model {

public void createModel(BvrsToRun blist) {

Then create a class that extends the Model class. In this class the createModel method is where you construct your animation. This example will make use of two of the primary media types supported by DirectAnimation: images and sound.
URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase,"image/");
URL sndBase = buildURL(mediaBase,"sound/");

Create bases for importing images and sounds.
ImageBvr seattleImg = importImage(buildURL(imgBase,"seattle.jpg"));

Import seattle.jpg.
SoundBvr pickSnd = importSound(buildURL(sndBase,
"etherial.mp2"),null).loop();

Import the sound that will be played when the mouse moves over seattleImg.
PickableImage pickPImg = new PickableImage(seattleImg,true);

Make seattleImg pickable.
DXMEvent pickEv = pickPImg.getPickEvent();

Create an event that will trigger when the mouse moves over detectImg.
ImageBvr pickImg = pickPImg.getImageBvr();

Get the image part of pickPImg.
StringBvr urlStr = toBvr("http:
seattle.sidewalk.com");

Create a string that contains the URL to Seattle Sidewalk.
FontStyleBvr font = font("Arial",12,white).bold();
ImageBvr tipTxtImg = stringImage(
"Click the red dot to go to Seattle Sidewalk", font);

Bbox2Bvr txtBB = tipTxtImg.boundingBox();

ImageBvr tipBackImg = solidColorImage(black)
.crop(txtBB.getMin(),txtBB.getMax());

ImageBvr tipImg = overlay(tipTxtImg,tipBackImg);

Create the tip box (tipImg), which consists of a black backgroud (tipBackIm), and white text (tipTxtIm).
ImageBvr jumpImg = solidColorImage(red).crop(point2(-0.003,-0.003),
point2(0.003,0.003));

jumpImg = jumpImg.transform(translate(toBvr(0),
mul(toBvr(-50),pixelBvr)));

Create a detectable image (jumpImg)and crop it to 6 by 6 mm. This image will be made pickable and used to jump to Seattle Sidewalk.
PickableImage jumpPImg = new PickableImage(jumpImg,true);

Make detectImg pickable.
DXMEvent jumpEv = jumpPImg.getPickEvent();

Create an event that will trigger when the mouse moves over jumpImg.
DXMEvent jumpClickEv = andEvent(leftButtonDown, jumpEv);

Create an event that will trigger when both the mouse moves over jumpImg, and the left mouse button is clicked.
ImageBvr jumpPointImg = jumpPImg.getImageBvr();

Get the image part of jumpPImg.
TupleBvr compTup1 = pairBvr(pickPImg.getImageBvr(),silence);
ImageBvr finalImg = overlay(jumpPointImg,overlay(tipImg,pickImg));
TupleBvr compTup2 = pairBvr(finalImg,pickSnd);

Combine the pickable images with the tip box and pair them with sound.
TupleBvr pickedTup = TupleBvr.newUninitBvr(pairBvr(emptyImage,silence));
pickedTup.init(until(compTup1,pickEv,until(compTup2,
notEvent(pickEv),pickedTup)));

Create a behavior (pickTup) that start out as a detectable empty image with no sound. When the mouse moves over it, the sound changes to pickSnd, and the tip box is displayed. When the mouse is no longer over it, it returns to the original behavior.
TupleBvr finalTup = (TupleBvr)untilNotify(pickedTup,
jumpClickEv,new JumpURLLink(urlStr));

Create a behavior that starts out as pickedTup, and that jumps to the Seattle Sidewalk site when the user clicks on pickPImg using the left mouse button.
setImage(overlay((ImageBvr)finalTup.nth(0),
overlay(seattleImg,solidColorImage(black))));

Display the final image.
setSound(mix((SoundBvr)finalTup.nth(1),silence));
}

public void appLink(AppletContext appGet) {
_getAppContext = appGet;
}
public static AppletContext _getAppContext;
}

class JumpURLLink extends Statics implements UntilNotifier {

public JumpURLLink(StringBvr url) {

Start the sound.
try {
_clickDest = new URL((String) url.extract());
}
catch(MalformedURLException mal) {
System.out.println("Malformed URL: Check Applet Tag.");
}
}

public Behavior notify(Object eventData,
Behavior currentRunningBvr, BvrsToRun btr) {

Convert urlStr into an URL.
JumpURLModel._getAppContext.showDocument(_clickDest,"_parent");

Use the Java showDocument method to load the Seattle Sidewalk page in the parent frame.
return currentRunningBvr;
}
URL _clickDest;
}
Return currentRunningBvr to keep the UntilNotify happy.

Thats all there is to it. Happy animating...

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Using AFC Menus
This sample shows how to use DirectAnimation with the Applet Foundation Classes (AFC). The menu is created by using AFC methods. The animation of the image (scaling, translating, rotating) is done in DirectAnimation.

It illustrates the following:
- using DirectAnimation along with AFC.
- creating menus and buttons in AFC.
- The use of ModifiableBehaviors.

import com.ms.dxmedia.*; All DirectAnimation classes
import com.ms.ui.*; The AFC classes
import java.awt.*; The event handle classes
import java.net.URL; The Java URL classes
public class AFCMenus extends AwtUIApplet {
public void init() {
setLayout(new FlowLayout(FlowLayout.LEFT,5,5));

Use AFC's AwtUIApplet to construct the applet.
UIPanel ctrls = new AFCControls();

Get the AFC (menu and button) part of the Applet.
Canvas cv = new DXMImage();

Get the DirectAnimation part of the Applet.
add("North",ctrls);
add("South",cv);

Position both parts.
cv.setSize(getSize().width - 25,
getSize().height - 25);
setBackground(Color.white);
}
}

The resize the DirectAnimation part, otherwise it will take over the entire viewport.
class AFCControls extends UIPanel {

The menu gets created in the AFCControls Class.
AFCControls() {

setLayout(new UIGridLayout(1, 1));
UIMenuList xformMenu = new UIMenuList();
UIMenuButton xformButton = new UIMenuButton("Apply Transform",
UIPushButton.RAISED, xformMenu);
add(xformButton);

Create the menu by using AFC's UIMenuList and UIMenuButton classes.
_scale = new UIMenuItem("Scale");
_translate = new UIMenuItem("Translate");
_rotate = new UIMenuItem("Rotate");

Create the "Scale", "Translate", and "Rotate" menu items.
xformMenu.add(_scale);
xformMenu.add(_translate);
xformMenu.add(_rotate);
}

Place the above mentioned items on the menu.
public boolean action(Event e, Object arg) {
if (arg == _scale) {
ImageModel.setXform(ImageModel.SCALE);
return true;
} else if (arg == _translate) {
ImageModel.setXform(ImageModel.TRANSLATE);
return true;
} else if (arg == _rotate) {
ImageModel.setXform(ImageModel.ROTATE);
return true;
}
return false;
}
UIMenuItem _scale, _translate, _rotate;
}

class DXMImage extends DXMCanvas {
DXMImage() {
setModel(new ImageModel());
}
}

Handle relevant events when the user interacts with the menu.
class ImageModel extends Model {
public void createModel(BvrsToRun bvrs) {

In the ImageModel class the createModel method is where you construct your animation.
URL mediaBase = getImportBase();
URL imgBase = buildURL(mediaBase, "image/");
ImageBvr img = importImage(buildURL(imgBase, "pretzel.gif"));

Import the image.
_xf = new ModifiableBehavior(identityTransform2);

Create a ModifiableBehavior (_xf) which will be linked to the menu item the user selects. This behavior will then be used to transform the image (img).
img = img.transform((Transform2Bvr)_xf.getBvr());

Apply _xf to img.
_scaleXf = scale2(add(toBvr(1), mul(sin(localTime), toBvr(0.5))));

_translateXf = translate(mul(sin(localTime),
mul(toBvr(100),pixelBvr)), toBvr(0));

_rotateXf = rotate(localTime);

Define the three transformations, that will be mapped to the respective menu items.
setImage(overlay(img, solidColorImage(white)));
}

Display the image on a white background.
static void setXform(int xformType) {
switch (xformType) {
case SCALE:
_xf.switchTo(_scaleXf);
break;
case TRANSLATE:
_xf.switchTo(_translateXf);
break;
case ROTATE:
default:
_xf.switchTo(_rotateXf);
break;
}
}

static Transform2Bvr _scaleXf, _translateXf, _rotateXf;
static ModifiableBehavior _xf;
final static int SCALE = 1;
final static int TRANSLATE = 2;
final static int ROTATE = 3;
}

This method is used in the AFCControls class to change _xf.
That's all there is to it. Happy animating...

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Using AFC Scrollbars
This sample shows how to use DirectAnimation with the Applet Foundation
Classes (AFC). The scrollbar is created by using AFC's UIScrollBar class.
The speed of the rotation of the geometry is mapped to the position of the
scrollbar in DirectAnimation.

It illustrates the following:
- using DirectAnimation along with AFC.
- creating a scrollbar in AFC.
- The use of ModifiableBehaviors.
import com.ms.dxmedia.*; All DirectAnimation classes
import com.ms.ui.*; The AFC classes
import java.awt.*; The event handle classes
import java.net.URL; The Java URL classes
public class AFCScroll extends AwtUIApplet {
public void init() {
setLayout(new UIBorderLayout());

Use AFC's AwtUIApplet to construct the applet.
UIPanel ctrls = new AFCControls();

Get the AFC (scrollbar) part of the Applet.
Canvas cv = new DXMImage();

Get the DirectAnimation part of the Applet.
add("North",cv);
add("South",ctrls);

Position both parts.
cv.setSize(getSize().width - 15,getSize().height - 15);

setBackground(Color.orange);
}
}

The resize the DirectAnimation part, otherwise it will take over the entire viewport.
class AFCControls extends UIPanel {

The scrollbar gets created in the AFCControls Class.
AFCControls() {
setLayout(new UIGridLayout(1, 1));
_speedBar = new UIScrollBar(0, 0, 30, 3, 1, 15);
_speedBar.setBackground(Color.orange);
add(_speedBar);
}

Create the scrollbar using AFC's UIScrollBar class.
public boolean handleEvent(Event e) {
switch (e.id) {
case Event.SCROLL_LINE_UP:
case Event.SCROLL_LINE_DOWN:
case Event.SCROLL_PAGE_UP:
case Event.SCROLL_PAGE_DOWN:
case Event.SCROLL_ABSOLUTE:

Handle relevant events when the user interacts with the scrollbar.
ImageModel.setSpeed(_speedBar.getScrollPos());
return true;
}
return false;
}
UIScrollBar _speedBar;
}

class DXMImage extends DXMCanvas {
DXMImage() {
setModel(new ImageModel());
}
}

The position of the scrollbar sent to the setSpeed() of the ImageModel class.
class ImageModel extends Model {
public void createModel(BvrsToRun bvrs) {

In the ImageModel class the createModel method is where you construct your animation.
URL mediaBase = getImportBase();
URL geoBase = buildURL(mediaBase, "geometry/");
GeometryBvr geo = importGeometry(buildURL(geoBase, "cube.x"));

Import the cube.
_speed = new ModifiableBehavior(toBvr(4));

NumberBvr spinYRate = (NumberBvr)_speed.getBvr();
NumberBvr spinZRate = mul(spinYRate, toBvr(1.3));
geo = geo.transform(compose(rotate(yVector3, integral(spinYRate)),
rotate(zVector3, integral(spinZRate))));

Create a ModifiableBehavior (_speed) which will be linked to the position of the scrollbar. This behavior will then be used to set the speed of rotation for the cube.
CameraBvr cam = perspectiveCamera(toBvr(5), toBvr(2));

Create a camera to view the cube.
setImage(overlay(union(geo, directionalLight).render(cam)
.transform(scale2(mul(toBvr(20),pixelBvr))),solidColorImage(blue)));
}

Display the cube on a blue background.
static void setSpeed(int speed) {
_speed.switchTo(toBvr(speed/3.0));
}

static ModifiableBehavior _speed;
}

This method is used in the AFCControls class to change _speed.
That's all there is to it. Happy animating...

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Using VBScript with DirectAnimation

Java applets can be driven just like ActiveX controls. The script can
read and write the public variables of the applet, as well as call its
public methods (including passing parameters and reading return values).

Note that only the Applet-derived class is directly accessible from
the scripting language. If your Java applet includes other classes that
you want to be available to the scripting language, you must define
public methods in your Applet-derived class that delegate to those
classes. Note, in order to communicate from the applet back to the script,
you will need to make use of the Dispatch methods in the Java SDK.
Please refer to the java SDK com.ms.com.Dispatch documentation.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Obtaining the Color from the Scrollbars
Here, in the Using_VBScript.html file, three subroutines are created which
retrieve the scrollbar values and set the VBScript class R,G,B data members.
They then call updateColor in the VBScriptModel class, which then updates
the color of the sphere applet of a change in color.
<SCRIPT LANGUAGE="VBScript">
<!--
Sub RedScroll_Change()
RedDec.Text=RedScroll.Value
RedHex.Text=Hex(RedScroll.Value)
document.DxmControl.R=RedScroll.Value/256
UpdateVals
End Sub

Sub GreenScroll_Change()
GreenDec.Text=GreenScroll.Value
GreenHex.Text=Hex(GreenScroll.Value)
document.DxmControl.G=GreenScroll.Value/256
UpdateVals
End Sub

Sub BlueScroll_Change()
BlueDec.Text=BlueScroll.Value
BlueHex.Text=Hex(BlueScroll.Value)
document.DxmControl.B=BlueScroll.Value/256
UpdateVals
End Sub

Sub UpdateVals
ColorTextBox.Backcolor = RGB(RedScroll.Value, GreenScroll.Value, BlueScroll.Value)
document.DxmControl.updateColor()
End Sub
-->
</SCRIPT>

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Changing the Color of the Sphere
Here in the VBScript class, you see the R,G, and B data members. The updateColor method just passes the data along to the VBScriptModel model class, where it will be used to change the color of the sphere.
public class VBScript extends DXMApplet {
private VBScriptModel _Model;
VBScript() {
_Model = new VBScriptModel();
setModel(_Model);
}
Public method accessable to VBScript subroutines in Using_VBScript.html
public void updateColor() {
_Model.updateColor(R,G,B);
}
Public method accessable to VBScript subroutines in Using_VBScript.html
public double R,G,B;
}
The VBScript class accesses this method to update the color of the sphere. This is done by switching sphereClrSw to a color based on the R,G, and B values obtained from the scrollbars.
public void updateColor(double R, double G, double B) {
ColorBvr newClr = colorRgb(toBvr(R),toBvr(G),toBvr(B));
sphereClrSw.switchTo(newClr);
}
Set up a simple model consisting of a sphere whose color can be switched upon notification.
class VBScriptModel extends Model {

public void createModel(BvrsToRun blist)
{
URL geoBase = buildURL(getImportBase(), "../../../../../Media/geometry/");
Create the sphere's initial color.
ColorBvr initClr = colorRgb(1,1,1);
Create a switcher behavior that will change whenever the scrollbars update the color.
sphereClrSw = new ModifiableBehavior(initClr);
Create a sphere and apply sphereClrSw's behavior to it
GeometryBvr sphereGeo =
importGeometry(buildURL(geoBase,"sphere.x"));
GeometryBvr coloredSphereGeo =
sphereGeo.diffuseColor((ColorBvr)sphereClrSw.getBvr());
Create a camera and light to render sphere.
CameraBvr Cam =
perspectiveCamera(toBvr(1),toBvr(0)).transform(
translate(0,0,50) );
GeometryBvr lightGeo =
directionalLight.transform(
translate(0,0,4));
Display the color changing sphere.
setImage(overlay(
union(coloredSphereGeo, lightGeo).render(Cam),
solidColorImage(white)));
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section 1: Video Playback
This applet uses AWT UI controls to control the rate of a video playback.

There are two components in this applet. One is a DXMCanvas used to display the movie image, the other is a panel of AWT controls used to control the playback.
public class VCR extends Applet {
public void init() {
setLayout(new BorderLayout());
DxmMovie cv = new DxmMovie();
Panel ctrls = new Controls(cv._model);
add("Center", cv);
add("South", ctrls);
}
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section 2: Display the Movie Model in DXMCanvas
This class extends the DXMCanvas class. The model you set in this class, by calling the setModel() method, is the model that will be displayed.
class DxmMovie extends DXMCanvas {
DxmMovie() {
_model = new VCRModel();
setModel(_model);
}

VCRModel _model;
}
This class extends the Model class. The createModel method in this class is where you construct your model.
class VCRModel extends Model {
Import a movie in the model and have a switcher behavior to control the playback rate.
public void createModel(BvrsToRun bvrs) {
Create a movie behavior by importing an avi file.
URL movieBase = buildURL(getImportBase(), "Movie/");
ImageBvr[] imgArr = {null};
SoundBvr[] sndArr = {null};
NumberBvr lenNum = importMovie(buildURL(movieBase, "movie.avi"),
imgArr, sndArr);
The playback rate switcher starts with 1, the normal rate.
_rateSw = new ModifiableBehavior(toBvr(1));
The playback position of the movie is the sum of the rate. Use modulus to loop the movie since positions less than 0 or greater than the length of the movie yields emptyImage. The specialMod is a private function that always returns a positive number less than lenNum.
NumberBvr posNum = specialMod(integral((NumberBvr)_rateSw.getBvr()), lenNum);
Use AppTriggeredEvent for the restart event. When the restart button is pressed, the event will be triggered. Construct a recursive position behavior - the resetablePosNum - that resets to itself when the event occurs. Note that integral has implicit time. When a restart posNum at the time _resetEv occurs, integration starts from 0.
_resetEv = new AppTriggeredEvent();
NumberBvr resetablePosNum = NumberBvr.newUninitBvr();
resetablePosNum.init(until(posNum, _resetEv, resetablePosNum));
Play the movie on top of a black background. Use substituteTime to control the position of a movie. The localTime for movies is implicit.
setImage(overlay((ImageBvr)imgArr[0].substituteTime(resetablePosNum),
solidColorImage(black)));
Loop the sound here.
setSound((SoundBvr)sndArr[0].loop().substituteTime(resetablePosNum));
}
This function does a "special" mod for negative numbers. It returns the linear distance between the passed-in numerator and the biggest multiple of the denominator smaller than the numerator. For example, specialMode(-1, 5) = 4, specialMod(-4, 5) = 1. This is defined so that a decreasing number behavior passed in as the numerator yields a consistent result whether its value is positive or negative.
NumberBvr specialMod(NumberBvr numNum, NumberBvr denomNum) {
return (NumberBvr)cond(gt(numNum, toBvr(0)),
mod(numNum, denomNum),
sub(denomNum, mod(abs(numNum), denomNum)));
}
This method changes the value of the rate switcher to the given rate. This is called by the event handlers of the playback controls.
void setRate(int rate) {
_rateSw.switchTo(toBvr(rate*0.1));
}
This method is called when the restart button is pressed. It resets the rate to the normal playback rate, and triggers the event to restart the movie.
void restart() {
setRate(10);
_resetEv.trigger();
}

AppTriggeredEvent _resetEv;
ModifiableBehavior _rateSw;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectX Media SDK DirectAnimation Tutorial

Tutorial Home Page
Section 3: Use AWT Controls

This class extends Panel. It has four buttons - pause, restart, fast forward, rewind - and a scrollbar. The scrollbar is used to control the playback rate at a finer level.
class Controls extends Panel {
Place the scrollbar at the center, then two buttons on either side.
Controls(VCRModel movie) {
_movie = movie;
setLayout(new BorderLayout());

_rateBar = new Scrollbar(Scrollbar.HORIZONTAL, 10, 1, -40, 40);
add("Center", _rateBar);
Pause and restart buttons on the west side.
Panel pWest = new Panel();
pWest.setLayout(new GridLayout(1, 2));
pWest.add(new Button("| |"));
pWest.add(new Button(">"));
add("West", pWest);
Fast forward and rewind buttons on the east side.
Panel pEast = new Panel();
pEast.setLayout(new GridLayout(1, 2));
pEast.add(new Button(">>"));
pEast.add(new Button("<<"));
add("East", pEast);
}
The event handler when any buttons are pressed.
public boolean handleEvent(Event ev) {
switch (ev.id) {
case Event.SCROLL_LINE_UP:
case Event.SCROLL_LINE_DOWN:
case Event.SCROLL_PAGE_UP:
case Event.SCROLL_PAGE_DOWN:
case Event.SCROLL_ABSOLUTE:
Scroll position changed: Clear the pause state, set the rate to the current scroll position.
_bPaused = false;
_movie.setRate(_rateBar.getValue());
return true;

case Event.ACTION_EVENT:
if (ev.arg == "| |") {
Pause: Toggle the pause state. This means that pressing the pause button the second time resumes the normal playback rate. The normal playback rate is 10, the pause rate is 0. Need to reflect the current rate in the scrollbar.
int rate;
if (_bPaused) {
_bPaused = false;
rate = 10;
} else {
_bPaused = true;
rate = 0;
}
_movie.setRate(rate);
_rateBar.setValue(rate);
return true;
} else if (ev.arg == ">") {
Restart: Clear the pause state, restart the movie at normal rate.
_bPaused = false;
_movie.restart();
_rateBar.setValue(10);
return true;
} else if (ev.arg == ">> {// Fast forward

FastForward: Clear the pause state, set rate to 30 and update the scrollbar position.
_bPaused = false;
_movie.setRate(30);
_rateBar.setValue(30);
return true;
} else if (ev.arg == "<<") {

Rewind: Clear the pause state, set rate to -30 and update the scrollbar position.
_bPaused = false;
_movie.setRate(-30);
_rateBar.setValue(-30);
return true;
}
}
return false;
}

boolean _bPaused = false;
Scrollbar _rateBar;
VCRModel _movie;
}

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Tutorial Home Page


DirectAnimation SDK, JScript sample

This vector graphics example shows a time varying glow being applied to the control elements. The control makes use of a montage (animated layering similar to z-Depth on style sheets) to allow the oval to pass over and under the text.


DirectAnimation SDK, JScript sample

Transforms on 2D Vector Primitives

Parades four animate structured graphics primitives. Pressing the Left Button applies an aditional 3D rotational transform. This shows a simple form of hierarchical articulation.


DirectAnimation SDK, JScript sample

A DAArray of Colors

A time varying index based on the "Floor" function is used to select a color.


DirectAnimation SDK, JScript sample

External events modifying a DA animation

Buttons set the color of a DirectAnimation object by using the modifiable behavior.


DirectAnimation SDK, JScript sample

Spinning Cube

The simplest geometry animation in under a dozen lines of code.


DirectAnimation SDK, JScript sample

Hello World in DirectAnimation


DirectAnimation SDK, JScript sample

Rotating Sprite


DirectAnimation SDK, JScript sample

Oscillating House

With coordinated pan on midi sound.


DirectAnimation SDK, JScript sample

Meter Coordinate System


DirectAnimation SDK, JScript sample

Scaling Movie

Sound volume varies with the scale of the movie.


DirectAnimation SDK, JScript sample

Pixel Coordinate System


DirectAnimation SDK, JScript sample

Number, Color, & String Behaviors

Text size, color and string are time varying. Pressing the left button sets the color to red. Pressing it again sets it to a time varying color. This shows how to set a cyclic behavior.


DirectAnimation SDK, JScript sample

Asynchronous Loading

This sample demonstrates how an asynchronous importation API uses an animation to mask load time. In this example, it is masking the time needed for importing a movie. If you are running the demo locally or with a fast network connection, there could be very little latency for the media load, which means the latency masking animation might not be displayed. To see the animation change the source url (movieURL) to your favorite movie on the web.


DirectAnimation SDK, JScript sample

This is a simple DirectAnimation windowless animation coordinated with an HTML image that is specified with an IMG tag.


DirectAnimation SDK, JScript sample

EYES

This example draws a face with eyeballs that track the mouse so long as it is within the boundaries of the control. The tracking is accomplished with 2D vectors.


DirectAnimation SDK, JScript sample

Light Box

This animation consists of both 2D and 3D graphical elements as well as a coordinated sound effect. Given the effects that it produces, this sample is quite compact. The media elements are only 15KB and the HTML file is 10KB. The animation is approximately 150 lines long in JScript, half of which are general and reusable utility functions.

The animation uses four motion paths that include two axes, an arc, and a spline. (press the left mouse button to see the annotations). Various images, with attached spotlights, travel back and forth, in a given duration, along these paths. The animated images include two green ovals, a sprite of a travelling car, and a rendered rotating 3D cube. The spot lights tilt gently towards the walls as they approach them.

A 3D room model with 5 walls underlies the 2D animation and is lit with the travelling spot lights as well as a stationary point light source. This is a good example of the 2D/3D interplay that is afforded by DirectAnimation's integrated media support; the motion paths and images are 2D elements while the spot lights and the cube are 3D elements.

An imported, looping audio clip is presented with dynamic gain and pan parameters. The travelling position along the Y axis is used to construct a gain between 1/2 and 1, while the point along the X axis is used to construct a pan between -1 and 1.


DirectAnimation SDK, JScript sample

Dancing Lights

This animated background is synthetically generated and rendered under HTML text as a windowless control. The media used is 6.3KBs in size. The JScript is under 100 lines long.

Four spot lights are animated using 2D paths and are pointed at an open room that is viewed with a perspective camera and a static, purple, pointlight source. The spot lights tilt gently towards the wall as they approach them. Lastly, the result of the 3D rendering is tiled to produce the final background.

Pressing the left mouse button first halts and then restarts the animation.


DirectAnimation SDK, JScript sample

North America
United States
Canada
Mexico
South America
Argentina
Brazil
Caribbean
Chile
Columbia
Venezuela
Europe
England
Ireland
Germany
Sweden
Poland
Venezuela
Africa
South Africa
North Africa
Asia
Japan
China
Thailand
Taiwan
India
Middle East
Australia
New Zealand
Australia
Antarctica
Microsoft Antarctica coming soon


DirectAnimation SDK, JScript sample

Plane travelling in 3D

An image of a airplane is textured onto both sides of a squared geometry. The Point3SphericalAnim() is then used to construct a path along which the geometry is moved. The z-index of the DAControl object is being updated dynamically with the z-coordinate of the path the geometry is on. This makes the geometry move in front of and behind the text. The panning of the sound you hear varies with the x-coordinate of the path the geometry is on. To give the plane the correct orientation, the Normalize(), CrossVector3(), DotVector3() are use to calculate the correct angle of rotation.


DirectAnimation SDK, JScript sample

Cropping and Tiling

This sample shows a gradient-filled, animated background rectangle with colors that vary over time. An imported JPEG image that is cropped and tiled overlays the rectangle. The cropping also varies with time.


DirectAnimation SDK, JScript sample

WebVCR: Controlling sound and movie playback through Microsoft's DirectAnimation scripting and Dynamic HTML

X
Rate: 1
Volume: 10
Status: Playing

Now everyone can design custom multimedia playback interfaces for their web pages. In this script, the majority of the logic is for controlling the buttons and status feedback. DirectAnimation is used to import a piece of media and control the rate of playback.


DirectAnimation JScript SDK Sample

Animated properties in JScript
This is a div using an animated string
This is a div using an animated number
This is a div using function callbacks
Behaviors don't just have to be used for multimedia elements, they can also be used to create a value which constantly updates a dynamic HTML property. Time varying strings, numbers, and function callbacks are demonstrated here.


DirectAnimation SDK, JScript sample

A Logo with a Spline shape

HTML Red
HTML Blue

This is a DirectAnimation that animates two HTML DIV tags.


DirectAnimation SDK, JScript sample

Oval using the Core Interface


DirectAnimation SDK, JScript sample

Oval Using the Drawing Surface Interface


DirectAnimation SDK, JScript sample

I bounce in the browser window even if you resize it!

I bounce in the browser window even if you resize it!

I bounce in the browser window even if you resize it!

I bounce in the browser window even if you resize it!

Hi


DirectAnimation SDK, JScript sample

Running Animations in different browser types and versions

The following animation will use DirectAnimation to create a spinning eightball in IE4, and IE3. For all other browser types it will default to a static eightball image.


DirectAnimation SDK, JScript sample

Coordinates and Motion Paths

Instantiates four paths including two axes, a circular arc, and a cubic spline. Constructs a rendering of each path along with a colored dot color that travels back and forth along the path in a given duration each way. SlowInSlowOut and FastInFastOut interpolation methods are used for going forward and backward, respectively.

This sample also demonstrates the pixel coordinate system by displaying the X and Y coordinates in terms of pixels. Also, the parameters for all paths are specified in terms of pixel coordinates. Notice that in Pixel Construction mode the positive Y-axis goes downwards, which is consistent with the HTML coordinate system.

The sample also demonstrates the construction of a freeform smooth path as a cubic spline. The sample uses a generally useful utility function, SimpleSpline, which takes a list of control points, automatically constructs a suitable knot vector, and returns the spline path.

The moving points are first class values in DirectAnimation, and can, therefore, be returned as parameters from functions. Here they are used to construct time-varying triangles. These triangles are partially opaque, as can be seen where they overlap. Also, the animation overlays the HTML text, which means the transparent triangles are composed with the underlying HTML. Set "z-index:-1" for the DA control, whereby the animation is rendered behind the text, and notice the subtle difference in the way the triangles and text interact.


DirectAnimation SDK, JScript sample

Image Cropping

This is an example of overlaying two images where one is cropped. Here the same image is constructed twice using two different colors. The second image is cropped by two points moving along a path. The rectangle also moves along the path and provides a border for the cropped image. The two images are overlayed together to give this nice effect.


DirectAnimation SDK, JScript sample

DirectAnimation Hello World

To use the DirectAnimation windowless control, simply place the control in the page and then, with scripting, build any animation and assign it to the control. In this example, the words "Hello JScript" are constructed using an animated color for the text.


DirectAnimation SDK, JScript sample

Jump URL in Scripting

This template shows how DirectAnimation can be used along with native JScript. When you move the mouse over the picture of Seattle, a sound will start playing and a tip box will appear with instructions. The pickable image and sound are imported by using DirectAnimation. Linking to another webpage is done by using DirectAnimation's Callback function and the href property of the Location object.


DirectAnimation SDK, JScript Sample

Perspective Images


DirectAnimation SDK, JScript sample

Periodic Randomness using the core scripting interface


DirectAnimation SDK, JScript sample

Dynamic resize of the control using DHTML

This example shows how the control's sizing can be tied to the current size of the browser window.


DirectAnimation SDK, JScript sample

Rotational Objects

Uses the Drawing Surface API to construct a 2D vector graphics-based image. This image is then animated with a 3D rotational transform and combined with other text-based images. Pressing the left mouse button makes the image rotate and stop.


DirectAnimation SDK, JScript sample

Sequencing

This sample demonstrates the time line and sequencing capabilities in DirectAnimation. It includes:

  • Giving behaviors a finite duration.
  • Repeating behaviors.
  • Sequencing behaviors.
  • Sequential and parallel composition of transform behaviors.
  • Specifying animation parameters to facilitate modifiability.

View source for further details.


DirectAnimation SDK, JScript sample

Graphics Primitives


DirectAnimation SDK, VBScript sample

CLOCK SAMPLE

This sample displays a clock and demonstrates the integration between VBScript and DirectAnimation. The time (hours, minutes, and seconds) for the clock is obtained using VBScript functions. These values are then used to construct the corresponding clock-hands using the DirectAnimation control.


DirectAnimation SDK, VBScript sample

Coffee Sprite Animation

This sample demonstrates the use of sprites, montages, and reactivity in DirectAnimation. Click on the image to activate the espresso machine.


DirectAnimation SDK, VBScript sample

Spline Matte

This is standard HTML and on top of it we have placed a DirectAnimation windowless control.

The animation you see is the clipping of an image with a time-varying closed cubic spline path.

The rate of the sound you hear also varies with time.


DirectAnimation SDK, VBScript sample

Dancing Trapezoids

DirectAnimation has a powerful, high-level interface for sequencing any behavior. DirectAnimation behaviors support methods for specifying their duration, number of repetitions, and for sequencing two behaviors together so that one will begin when the other ends. This example shows how this can be used to create very complex transformations with a minimum amount of scripting.


DirectAnimation SDK, VBScript sample

FLYING CUBES SAMPLE

Click on the DirectAnimation control to stop the horizontal movement of the animation. Click again to resume.


DirectAnimation SDK, VBScript sample

Animate 3D objects in a Windowless Controls

This animation is made up of 3D objects imported from .X files and animated in 3D using DirectAnimation. The objects are rendered as a windowless control on top of HTML text. You can still select text below the animate objects. Left-click on an object to change its color and start it spinning. Click again to stop it. One of the cubes assumes a time-varying color. Right-click to switch between a perspective and a parallel view.


DirectAnimation SDK, VBScript sample

Complex, animated graphics that use very little bandwidth.


DirectAnimation VBScript SDK Sample

Animated properties in VBScript
This is a div using an animated string
This is a div using an animated number
This is a div using function callbacks
Behaviors don't just have to be used for multimedia elements, they can also be used to create a value which constantly updates a dynamic HTML property. Time varying strings, numbers, and function callbacks are demonstrated here.


DirectAnimation SDK, VBScript sample

Audio Mixing

This template shows how DirectAnimation can be used to mix audio. The volume and panning of three sounds are controled by the positions of scrollbars.
VOLUME 1
PAN 1
VOLUME 2
PAN 2
VOLUME 3
PAN 3


DirectAnimation SDK, VBScript sample

Drawing a Rotating Oval


DirectAnimation SDK, VBScript sample

Drawing a Rotating Oval With the Drawing Surface


DirectAnimation SDK, VBScript sample

Using Modifiable Behaviors and Buttons

This sample demonstrates the switcher/switching functionality, in this case image and sound behaviors are switched to new values in reaction to button clicks.


DirectAnimation SDK, VBScript sample

Issuing Scripting callbacks

DirectAnimation scripting callbacks are used to move an HTML DIV tag. The buttons, when clicked, exhibit a simple animation and sound effect, and also call a function that moves the HTML.
Click on the buttons to move this text


DirectAnimation SDK, VBScript sample

DirectAnimation Hello World

To use the DirectAnimation windowless control, simply place it in the page and then, from scripting, build an animation and assign it to the control. In this example, the words "Hello VBScript" are constructed using an animated color for the text.


DirectAnimation SDK, Filter Download sample

Filter download

This sample demonstrates how a video codec can be downloaded automatically with the CODEBASE attribute of the OBJECT tag.


DirectAnimation SDK, VBScript sample

Using Modifiable Behaviors and Scrollbars

This sample demonstrates the use of a stream of events from a VB slider to repeatedly modify a behavior. In this case the position of the scrollbar is mapped to the X position of the oval.


DirectAnimation SDK, VBScript sample

A Spline Shape and Path


DirectX Media SDK Control Samples

Microsoft DirectX Media SDK Control Samples Last updated: November 15, 1998

Your browser does not support frames. For the latest release of Internet Explorer
CLICK HERE.


 Microsoft DirectAnimation SDK


DirectX Media SDK JScript Samples

Microsoft DirectX Media SDK JScript Samples Last updated: November 15, 1998

Your browser does not support frames. For the latest release of Internet Explorer
CLICK HERE.


DirectX Media SDK JScript Samples

Welcome to the DirectAnimation JScript Samples

Our JScript samples are divided into three categories:

  • Showcase
  • Templates
  • Exercises
We hope you enjoy viewing these samples.
© 1998 Microsoft Corporation. All rights reserved. Terms of use.
Best viewed in 16-bit color with Internet Explorer 4.0.
Email contact for this page is dxmbeta@microsoft.com.


DirectPlay

Microsoft Home


DirectX Media SDK Control Samples

 Control Samples

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK JScript Samples

 JScript Exercises

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK JScript Samples

 JScript Showcase

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK JScript Samples

 JScript Templates

* Basic
* Basic DS
* Hello JScript
* Resize
* Cropping
* Shapes
* Annotated Logo
* Rotational
* Sequencing
* Bounce
* CoordsAndPaths
* Animated Properties
* Perspective Images
* Random
* Jump URL
* Detect Browser

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK Java Tutorials

 Java Showcase Tutorials

To interact with the animation, left-click on it.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK Java Tutorials

 Java Template Tutorials

* Async Load
* Using VBScript
* Using AFC Menus
* Using AFC Scrollbars
* Basic Applet
* Extended Applet
* GeoApplet1
* GeoApplet2
* IE4 Windowless
* Draggable Image
* Draggable Geometry
* Pickable Button
* Jump URL
* VCR

To interact with the animation, left-click on it.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK VBScript Samples

 VBScript Showcase

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectAnimation SDK VBScript Samples

 VBScript Templates

To interact with the animation, left-click on it. To view the source code, right-click to the right of the animation.

Returnto DirectAnimation SDK Documentation Returnto DirectAnimation SDK Guide to Samples Page

Best experienced with
 Microsoft Internet Explorer
Click here to start.


DirectX Media SDK Java Tutorials

Microsoft DirectX Media SDK Java Tutorials Last updated: November 15, 1998

Your browser does not support frames. For the latest release of Internet Explorer
CLICK HERE.


DirectX Media SDK Java Tutorials

Welcome to the DirectAnimation Java Tutorials

Our Java tutorials are divided into two categories:
  • Showcase Tutorials
  • Template Tutorials
We hope you find these tutorials helpful.
© 1998 Microsoft Corporation. All rights reserved. Terms of use.
Best viewed in 16-bit color with Internet Explorer 4.0.
Email contact for this page is dxmbeta@microsoft.com.


DirectX Media SDK VBScript Samples

Microsoft DirectX Media SDK VBScript Samples Last updated: November 15, 1998

Your browser does not support frames. For the latest release of Internet Explorer
CLICK HERE.


DirectX Media SDK VBScript Samples

Welcome to the DirectAnimation VBScript Samples

Our VBScript samples are divided into two categories:

  • Showcase
  • Templates
We hope you enjoy viewing these samples.
© 1998 Microsoft Corporation. All rights reserved. Terms of use.
Best viewed in 16-bit color with Internet Explorer 4.0.
Email contact for this page is dxmbeta@microsoft.com.