Filters and Transitions

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 Microsoft 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
Sets or retrieves the filter or collection of filters 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 currently 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 currently 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 currently 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 currently 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
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 currently 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.