Filters and Transitions

This topic documents a feature of Visual Filters and Transitions, which is deprecated as of Windows Internet Explorer 9.

With Microsoft Internet Explorer 4.0 and later, you can apply various multimedia-style visual effects to your Web page. You can implement these effects in Web pages using Cascading Style Sheets (CSS) properties. By combining filters and transitions with basic scripting, you have a powerful tool for creating visually engaging and interactive documents. Internet Explorer 5.5 and later supports the richest variety of optimized filters. This documentation covers the basics of filters and transitions as well as all of the reference components.

Overviews/Tutorials

About Procedural Surfaces

The Microsoft DirectX Transform architecture enables you to write procedural surfaces. These DXSurfaces are not stored as an array of samples, but instead as a set of instructions that specify how to render a surface of arbitrary size and resolution. Procedural surfaces take up a fraction of the memory used to store bitmap images, and they can produce realistic marble and wood textures. The resulting surfaces can be used as background images.

About Transforms and DXSurfaces

DirectX Transform objects apply space and time effects to Microsoft DirectDraw objects. DirectX Transform objects read data from a source, modify it, and write it to a destination object. In certain cases the source and destination data objects can be the same if the transform is capable of executing in place. DirectX Transform exposes a number of Component Object Model (COM) interfaces and data types that enable you to create your own unique effects and plug them into the existing architecture.

Architecture

In order to properly use DirectX Transform objects and interfaces, it is important to know what they are and how they all relate to one another.

Author's Guide to Transforms

This article should be considered required reading for transform authors. It contains important information that you need in order for your transform to function correctly under DirectX Transform containers. It also includes conventions and tips that are useful for writing transforms.

Building DirectX Transform Samples and Applications

This overview explains the download and installation procedures necessary to prepare your build environment to build the samples and applications described in the DirectX Transform documentation.

CDXMMXInfo Constructor

This constructor is used to to determine whether MMX instructions are present.

Copyright Information

DirectX Transform provides a way for you to secure the transforms you write so that only registered users can legally use your copyrighted transforms with their content. You can easily implement this, and it provides you with legal recourse for copyright violations.

DirectX Transform C++ Samples

Several sample applications are provided to demonstrate the various features of transforms.

DXETool for Transform Users

The DirectX Transform documentation includes an application called DXETool.exe, which helps you verify that your transforms work properly within the DirectX Transform architecture. You can also use this application to view transform output and determine settings for the custom properties.

DXETool for Transform Writers

The DXETool application is a useful tool in the transform writing process. This overview provides instructions for setting-up and using DXETool.

Example: The Wipe Transform

This topic walks you through the Wipe transform sample code. This transform uses custom helper functions and elements common to all DLL files that use DirectX Transform routines.

Example: The WipeDlg Application

DirectX Transform provides you with powerful tools for manipulating 2-D image data. With DirectX Transform, you can perform operations on a single image—for example, the MotionBlur or BasicImage transform—or combine two images to form a single output image—for example, the Iris or Wheel transform.

Getting Started

This overview provides a starting point for readers new to DirectX Transform.

How to Apply a Transition on an Image

This article demonstrates how to implement a simple transition on an image.

How to Implement Procedural Surfaces

This tutorial describes the process of implementing procedural surfaces with Microsoft Visual Studio.

How Transforms Work

In a general sense, each transform is a set of rules for how to produce one graphic output.

Implementation Guide

This overview provides a procedure for building an image transform DLL using Microsoft Visual C++ and the DirectX Transform interfaces.

Introduction to Filters and Transitions

With Internet Explorer 4.0 and above, you can apply various multimedia-style visual effects to your Web page. You can implement these effects in Web pages using CSS properties. By combining filters and transitions with basic scripting, you have a powerful tool for creating visually engaging and interactive documents. Internet Explorer 5.5 and above supports the richest variety of optimized filters. Most examples in this article require that you have Internet Explorer 5.5 installed.

Security Considerations: Filters and Transitions

This topic provides a list of topics that contain security information. These topics do not provide all you need to know about security issues—instead, use them as a starting point and reference for this technology area.

Supported Pixel Formats

One of the most useful capabilities of DirectX Transform is that it enables you to import and export graphics data in a number of standard pixel formats.

Understanding DXSurfaces

A DirectX surface object, DXSurface, is an abstract image whose pixel data is obtainable in 32-bit ARGB color format, regardless of the underlying pixel representation. DirectX Transform uses this data object for both input and output images. The DXSurface enables you to concentrate on the logical aspects of designing the transform, while letting the supporting software take care of numerous details, such as alpha blending, dithering, and converting among different pixel formats.

Using the CDXBaseNTo1 Base Class

CDXBaseNTo1 is a base class that you can use to implement transforms that take multiple images as inputs and produce a single image. If you choose not to use this base class, you can create a transform by directly implementing the IDXTransform interface, the IObjectWithSite COM interface, and, if you are using an image transform, the IDXSurfacePick interface. However, you will find it easier to use this base class because it performs parameter validation, preprocesses data, and implements the full IDXTransform interface. This simplifies development by only requiring implementation of the code specific to the transform.

Using Transforms

This overview suggests further reading regarding how to use a DirectX Transform in a Windows application.

Using Transforms in C++

To use a transform in a C++ application, you must be familiar with a few key interfaces, methods, and objects. This section describes how to use an existing transform in a C++ application.

What is DirectX Transform?

DirectX Transform is a DirectX media API you can use to create, animate, and edit digital images. DirectX Transform works with 2-D images, which can be used to create stand-alone Windows applications or dynamic plug-ins for Web graphics.

Writing Transforms

DirectX Transform enables you to produce effects on images. The API provides sophisticated graphics tools for modifying and combining images. These tools include scaling, dithering, compositing, alpha blending, image filtering, and many others. You can use transforms in your own image-based applications.

Attributes/Properties

Brightness

Sets and retrieves the settings for the lookup table brightness curve.

BuildOrder

Sets and retrieves the order of operations used to build the lookup table.

Capabilities

Retrieves a value that indicates specific capabilities of a transition.

ColorBalance

Sets and retrieves the tint curves for color balance operations on the selected color.

Contrast

Sets and retrieves the settings for the lookup table contrast curve.

Duration

Sets or retrieves the length of time the transition takes to complete.

Duration

Retrieves the recommended length of time for performing a transition. Sets the suggested duration for the transition.

Enabled

Sets or retrieves a value that indicates whether the filter is enabled.

filter

Gets or sets the filter or collection of filters that are applied to the object.

Gamma

Sets and retrieves the value used for gamma correction.

Invert

Sets and retrieves the threshold value for color inversion, which represents a fraction of a one-byte color channel.

LevelsPerChannel

Sets and retrieves the number of color levels to use for the posterizing operation.

NumBuildSteps

Retrieves the number of lookup table operations to perform.

Opacity

Sets and retrieves the opacity adjustment for the lookup table.

Percent

Sets or retrieves the point in a transition at which to capture the display for a static filter output.

Progress

Retrieves the setting of the transform's Progress property. Sets the requested progress made on the transform.

StepResolution

Retrieves the step size that corresponds to the smallest meaningful change for the Progress property.

Threshold

Sets and retrieves the value for threshold filtering operations.

Methods

Apply

Captures the initial display of an object's content for a transition.

ApplyTables

Translates a set of samples in place.

BitBlt

Copies samples from one DXSurface to another.

Bottom

Retrieves the minimum y-axis value.

BoundsAreEmpty

Tests whether the bounds are empty.

BoundsAreNull

Tests whether the bounds are null.

CDXTWorkInfoNTo1

Constructs a CDXTWorkInfoNTo1 and initializes the data members.

ClearDirty

Indicates to the transform that it is properly set up and ready to produce output.

CopyAndMoveBoth

Copies the specified number of samples from the current position of the source surface to the current position of the output surface.

CopyRect

Copies the specified number of samples from the specified rectangle in the source surface to the current position on the output surface.

CopySurfaceToNewFormat

Copies one surface to another and changes its pixel format.

CreateARGBPointer

Allocates an ARGB read pointer object.

CreateD3DRMTexture

Not supported.

CreateFromDDSurface

Creates a DXSurface that contains a specified DirectDrawSurface object.

CreateSurface

Creates a DXSurface object of the specified size and format.

CreateTransform

Creates and initializes a transform.

DeleteARGBPointer

Frees an ARGB read pointer object.

Depth

Retrieves the depth of the z-axis dimension.

DetermineBnds

Called by the base class to determine the output bounds of 2-D transforms.

DetermineBnds

Not supported.

DoDither

Determines whether the transform output should be dithered.

DoOver

Determines whether the transform output should be alpha blended over the output surface.

Duration

Retrieves the size of the t-axis dimension.

DXBASESAMPLE

Constructs an uninitialized DXBASESAMPLE object.

DXBASESAMPLE

Constructs a DXBASESAMPLE object with members initialized to the specified values.

DXBASESAMPLE

Constructs a DXBASESAMPLE object with members initialized to the values specified in a Integer.

DXPMSAMPLE

Constructs an uninitialized DXPMSAMPLE object.

DXPMSAMPLE

Constructs a DXPMSAMPLE object with members initialized to the specified values.

DXPMSAMPLE

Constructs a DXPMSAMPLE object with members initialized to the values specified in a Integer.

DXSAMPLE

Constructs an uninitialized DXSAMPLE object.

DXSAMPLE

Constructs a DXSAMPLE object with members initialized to the specified values.

DXSAMPLE

Constructs a DXSAMPLE object with members initialized to the values specified in a Integer.

Execute

Executes the transform operation given the specified portion bounds and places the result in the destination data object.

Expand

Adds to the object's dimensions about its center by the specified amount.

Expand

Adds to the object's dimensions about its center by the specified amount.

FillAndMove

Fills the output surface with the specified sample value, starting at the current position and advancing the current position.

FillRect

Fills a rectangle with the sample value, optionally doing an alpha-blend with the destination.

FillSamples

A method called by the base class to generate a row of output samples.

GetAppData

Retrieves an application-specific Integer of data.

GetBackground

Retrieves a pointer to the DXSurface used as a background.

GetBehaviorSite

Not implemented.

GetBias

Retrieves the bias value used for the convolution.

GetBounds

Retrieves a structure that contains the surface's boundary region.

GetBrightness

Retrieves the settings for the lookup table brightness curve.

GetBuildOrder

Retrieves the order of operations used to build the lookup table.

GetColorBalance

Retrieves the tint curves used for color balance operations on the selected color.

GetColorKey

Retrieves the surface's color key value.

GetCompositeOperation

Retrieves the method used for image compositing.

GetConcurrencyLimit

Retrieves the number of threads allowed to execute on a single processor at a given time.

GetContrast

Retrieves the settings for the lookup table contrast curve.

GetConvertToGray

Retrieves a value that indicates whether the filter output color is converted to grayscale.

GetDC

Retrieves the current device context (DC).

GetDirectDrawSurface

Retrieves an interface on the underlying GetDirectDrawSurface object if the DXSurface object is aggregated onto a GetDirectDrawSurface.

GetEffectProgress

Retrieves a value indicating the current progress of the transform effect.

GetExcludeAlpha

Retrieves a value that indicates whether the alpha channel should be filtered along with the color data.

GetFillColor

Retrieves the surface fill color.

GetFilterType

Retrieves the selected filter type for the convolution.

GetForeground

Retrieves a pointer to the DXSurface used as a foreground.

GetGamma

Retrieves the value used for gamma correction.

GetGenerationId

Retrieves the current generation ID for the object.

GetIndexValues

Retrieves the component values for a specific index in the table.

GetInOutInfo

Retrieves input or output information about the specified data object, and an optional pointer to it.

GetInvert

Retrieves the threshold value used for color inversion.

GetLevelsPerChannel

Retrieves the number of color levels to use for the posterizing operation.

GetLookup

Retrieves the interface to the selected color lookup table.

GetMaxVector

Stores the maximum values for each dimension into the specified vector.

GetMinVector

Stores the minimum values for each dimension into the specified vector.

GetMiscFlags

Retrieves flags that describe the behavior of the transform.

GetNativeType

Retrieves the native underlying pixel format of a DXSurface.

GetNumBuildSteps

Retrieves the number of lookup table operations to perform.

GetNumInputs

Retrieves the number of inputs used during the transform setup.

GetObjectSize

Retrieves the size, in bytes, of the data object (for example, a surface or buffer).

GetOpacity

Retrieves the opacity adjustment for the lookup table.

GetOpacity

Retrieves the opacity of the foreground surface.

GetOutputSize

Retrieves the size of the output surface.

GetPixelFormat

Retrieves the pixel format of the surface.

GetQuality

Retrieves the quality level used to render the transform result.

GetSafeArray

Gets the value of the data object to the bounds in the specified array data type.

GetScale

Gets the scale for an alpha sample as a floating point value.

GetScaleAlphaValue

Gets the scale for an alpha sample as a byte integer value.

GetScales

Retrieves the x-axis and y-axis scale factors.

GetSize

Retrieves the bounds translated so that the minimum values are positioned at zero.

GetStatusFlags

Retrieves the status flags of the DXSurface object.

GetSurface

Retrieves a pointer to the parent DXSurface.

GetSurfaceInfo

Retrieves information about the attributes and structure of the raw surface object's pixel data.

GetTables

Retrieves a copy of the lookup tables.

GetThreadPoolSize

Retrieves the number of threads in the thread pool.

GetThreshold

Retrieves the value used for threshold filtering operations.

GetXYRect

Stores the x-axis and y-axis bounds into the specified rectangle.

GetXYSize

Stores the x and y size of the bounds into the specified SIZE structure.

HaveInput

Tests whether an input data object is associated with the specified input index.

HaveOutput

Tests whether an output data object is associated with the transform.

Height

Retrieves the height of the y-axis dimension.

IncrementGenerationId

Manually increments the object generation ID.

InitFromDDSurface

Initializes a DXSurface from an existing DirectDrawSurface.

InitFromRawSurface

Initializes a DXSurface object from a client-created object that supports the IDXRawSurface interface.

InitFromSafeArray

Sets the value of the data object to the bounds in the specified array.

InitializeTransform

Initializes a transform that has been created by the caller.

InitSurface

Initializes a DXSurface object with the specified volume boundary and format from a DirectDraw object.

InputMeshBuilder

Not supported.

InputSampleFormat

Retrieves the pixel format type for the selected input surface.

InputSurface

Retrieves a pointer to the selected input surface.

IntersectBounds

Determines whether the two specified bounds intersect.

IntersectBounds

Determines whether the two specified bounds intersect.

IsChannelIdentity

Determines whether the application of a channel's table will have any effect.

IsInputDirty

Determines whether a transform input has changed since the last time this method was called.

IsOutputDirty

Determines whether an output has changed since the last time this method was called.

IsTransformDirty

Determines whether the transform parameters or inputs have changed since the last time this method was called.

Left

Retrieves the minimum x-axis value.

LoadImage

Binds the specified file name or URL and returns a DXSurface containing the image data.

LoadImageFromStream

Loads an image from a stream and returns a DXSurface.

LockSurface

Locks a region of the surface and returns a pointer through which you can access samples on DXSurfaces.

LockSurfaceDC

Locks a region of the surface and returns an IDXDCLock interface.

MapBoundsIn2Out

Maps the input coordinate space to the output coordinate space.

MapBoundsOut2In

Maps the output coordinate space to the input coordinate space.

MinMMXOverCount

Returns a value that indicates whether MMX instructions are present.

Move

Moves the sample pointer along the x-axis relative to its current position.

MoveAndGetRunInfo

Moves the sample pointer to a specified row and retrieves a pointer to the run information associated with that row.

MoveToRow

Moves the sample pointer to an absolute row along the y-axis and resets the x-axis position to zero.

MoveToXY

Moves the sample pointer to an absolute position.

NeedDestPMBuff

Determines whether a temporary buffer is needed when calling a sample for surface read/write methods.

NeedSrcPMBuff

Determines whether a temporary buffer is needed when calling sample input methods on the IDXARGBReadPtr interface.

NormalizeBounds

Makes all of the minimum bounds less than or equal to the maximum bounds.

Offset

Adds the specified vector to the minimum and maximum for each dimension.

Offset

Adds the specified values to the minimum and maximum for each dimension.

OnExecute

Called by the base class to cause a transform to produce its output.

OnFreeInstData

Frees resources allocated by the OnInitInstData method.

OnGetObjectSize

Called by the base class to determine the amount of data space currently occupied by the transform.

OnGetObjectSize

Called by the base class to determine the object's size, in bytes.

OnGetSurfacePickOrder

Provides the base class with the necessary information to perform surface picking for the transform.

OnInitInstData

Enables the transform to allocate resources or compute any data that is to be shared across threads.

OnReleaseObjects

Called to release resources when the transform is being set up with null inputs or outputs.

OnSetSize

Sets the width and height of the surface.

OnSetup

Called after the base class has completed its setup.

OnSurfacePick

Called by the base class to enable the derived transform to fully implement surface picking.

OnSurfacePick

Determines whether any part of the surface is located at the specified point.

OnUpdateGenerationId

Called by the base class to check the input and output data object generation IDs and increment the transform generation ID.

operator DWORD

Casts the sample as a Integer.

operator DWORD

Casts the sample as a Integer.

operator DWORD

Casts the sample as a Integer.

operator DXPMSAMPLE

Casts the sample as a DXPMSAMPLE.

operator DXSAMPLE

Casts the sample as a DXSAMPLE.

operator=

Assigns the color values of the sample.

operator=

Assigns the color values of the sample.

operator=

Assigns the color values of the sample.

OutputMeshBuilder

Not supported.

OutputSampleFormat

Retrieves the pixel format type of the output surface.

OutputSurface

Retrieves a pointer to the output surface.

OverArrayAndMove

Alpha-blends an array of samples over the output surface and moves the pointer a specified number of samples.

OverSample

Alpha-blends the sample value over the sample at the specified position.

PackAndMove

Places a buffer of ARGB32 samples into the output surface and moves the sample pointer.

PackPremultAndMove

Places a buffer of ARGB32 samples into the output surfaces and moves the sample pointer.

PackRect

Accepts a buffer of either PMARGB32 or ARGB32 samples and writes them to a subsection of the output surface defined by a DXPACKEDRECTDESC structure.

Play

Plays the transition.

PointPick

Performs a surface pick at the specified output point.

QueryNumProcessors

Retrieves the number of processors installed in the system.

Right

Retrieves the maximum x-axis value.

SampleFormatEnum

Retrieves the native pixel format of the surface.

Scale

Scales the object about its center by the specified scaling factors.

Scale

Scales the object about its center by the specified scaling factors.

ScaleArray

Applies a lookup table to an array of DXSAMPLE structures.

ScaleArrayAlphaOnly

Applies alpha portion of a lookup table to an array of DXSAMPLE structures.

ScaleBaseArray

Applies a lookup table to an array of DXBASESAMPLE structures.

ScaleFitToSize

Sets the scale factors used to fit a portion of the input to match a specified size.

ScalePremultArray

Applies a lookup table to an array of DXPMSAMPLE structures.

ScaleSample

Applies a lookup table to a single DXBASESAMPLE structure.

ScaleType

Returns a value that indicates the scale type.

ScaleType (const)

Returns a value that indicates the scale type.

ScheduleTasks

Defines a set of tasks to execute.

SetAppData

Sets the surface's application-specified Integer of data.

SetBackground

Sets the surface modifier background surface.

SetBehaviorSite

Sets the behavior site.

SetBias

Sets the bias value used for the convolution.

SetBindHost

Specifies the bind host that the transform should use.

SetBounds

Sets all the values of the data object with the specified bounds.

SetBounds

Sets the surface's volume boundary structure.

SetBrightness

Sets the values for the lookup table brightness curve.

SetBuildOrder

Sets the order of operations used to build the lookup table.

SetColorBalance

Sets the tint curves for color balance operations on the selected color.

SetColorKey

Sets the surface's color_key value.

SetCompositeOperation

Selects the method used for image compositing.

SetConcurrencyLimit

Defines the number of threads that can execute from a thread pool at a given time.

SetContrast

Sets the values for the lookup table contrast curve.

SetConvertToGray

Sets a value that indicates whether the filter output color is converted to grayscale.

SetCustomFilter

Sets the convolution to use a custom filter.

SetDirty

Increments the transform generation ID.

SetEmpty

Sets all minimum and maximum bound values to zero.

SetExcludeAlpha

Sets a value that indicates whether the alpha channel should be filtered with the color data.

SetFillColor

Sets the surface fill color.

SetFilterType

Sets the selected filter type for the convolution.

SetForeground

Selects the DXSurface to use as a foreground.

SetGamma

Sets the value used for gamma correction.

SetGradient

Sets the parameters used to produce the gradient surface.

SetHostUrl

Sets the host URL.

SetInvert

Sets the threshold value for color inversion.

SetLevelsPerChannel

Sets the number of color levels to use for the posterizing operation.

SetLookup

Sets the interface to use for color lookup table operations on the foreground surface.

SetMiscFlags

Sets transform flags that specify how to generate the output.

SetOpacity

Sets the opacity adjustment for the lookup table.

SetOpacity

Sets the opacity of the foreground surface.

SetOutputSize

Sets the size of the scaled transform output.

SetPlacement

Translates the bounds to the absolute position specified by the vector.

SetQuality

Sets the quality level used to render the transform result.

SetScale

Sets the scale using a float value.

SetScaleAlphaValue

Sets the scale for an alpha sample using a byte integer value.

SetScales

Sets the x-axis and y-axis scale factors.

SetService

Adds a service provider to the Transform Factory.

SetStatusFlags

Sets the status flags of the DXSurface object.

SetThreadPoolSize

Specifies the number of threads to create and make available to execute tasks.

SetThreshold

Sets the value for threshold filtering operations.

SetToMeshBounds

Not supported.

SetToSize

Translates the bounds to the absolute position specified by the vector.

SetToSurfaceBounds

Sets the value of the data object to the bounds of the specified surface.

Setup

Defines the input and output data objects used in the transform.

SetXYPoint

Sets the x-axis and y-axis bounds of the object to one pixel width at the specified point.

SetXYRect

Sets the x-axis and y-axis bounds of the object to the specified rectangle.

SetXYSize

Sets the x-axis and y-axis bounds of the object to the specified size.

SetXYSize

Sets the x-axis and y-axis bounds of the object to the specified size.

Size

Retrieves the bounds translated so that the minimum values are positioned at zero.

Stop

Stops the transition playback.

SurfaceCLSID

Retrieves the class identifier (CLSID) of the surface.

TerminateRequest

Terminates a task based on its request ID value that was used when the task was scheduled.

TerminateTasks

Terminates a set of tasks previously scheduled by the task manager.

TestIntersect

Tests whether the specified bounds intersect the data object.

Top

Retrieves the maximum y-axis value.

UnionBounds

Creates a union of the two specified bounds and assigns the result to the data object.

Unpack

Unpacks the specified number of samples into the supplied buffer in ARGB32 pixel format. This method can only unpack a single row. Use UnpackRect to unpack multiple rows.

UnpackPremult

Unpacks the specified number of samples into the supplied buffer in alpha-premultiplied PMARGB32 pixel format. This method only unpacks a single row. Use UnpackRect to unpack multiple rows.

UnpackRect

Unpacks a subsection of source samples defined by a rectangle structure and advances the horizontal position of the read pointer. Use to unpack multiple rows.

Width

Retrieves the width of the x-axis dimension.

Width

Retrieves the width of the specified dimension.

WorkProc

Called in a response to the Execute method to render a portion of the output space to the current output surface.

WorkProc

Called by the transform base class to enable the surface to function as a transform.

Events

onfilterchange

Fires when a visual filter changes state or completes a transition.

Collections

filters

Retrieves the collection of filters that have been applied to the object.