The Active Network

ActiveWin: DirectX Active Network | Articles | Editorials | Interviews | FAQ's | Forums 
 

Amazon.com

  *  

 DirectX 9 Release Notes


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

Contents:
Installation
What’s New

RELEASE NOTES
SDK
Documentation
Managed DirectX
DirectX Audio (DirectSound® & DirectMusic®
Direct3D®
D3DX
DirectInput®
DirectPlay®
Broadcast Driver Architecture
DirectShow®

Compiler Support
Special Thanks
Roland SoundCanvans Sound Set for General MIDI and GS

CD Layout




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

Installation
ALWAYS UNINSTALL PREVIOUS RELEASES of the DirectX SDK prior to installing DirectX 9.0 SDK Release (see UNINSTALL). Installing on top of a previous installation will cause you problems.
In addition, you should uninstall any DirectX SDK installations that may be part of a Microsoft Platform SDK installation prior to installing the DirectX 9.0 SDK.
DirectX 9.0 SDK does not support Windows 95, Windows NT, or NEC PC98 systems. Installations on these systems have been blocked.
On Windows 2000 or Windows XP, You must be logged on as an administrator before installing the DirectX 9.0 SDK, installing the runtime, using any of SDK tools, or running any of the SDK samples.
DirectX 9.0 SDK RC incorporates all Media Center Edition updates to DirectX files shipped in Windows XP Service Pack 1. However, extensive compatibility testing has not yet been performed on this configuration, so it is highly recommended to wait for the final release before installing on these systems.
Running the DirectX 9.0 SDK install on Windows XP and later checked builds may result in assertions from inside the install package. We have found no cases where continuing on past the assert dialog boxes results in improper installation of the DirectX 9.0 SDK, so it is safe to continue past these asserts.
An Internal error can occur after the NTFS permissions for the Administrators group or the System account have been removed from the %SystemRoot%\Installer folder. To resolve this issue, reset the NTFS permissions for the %SystemRoot%\Installer folder so that it includes both the Administrators group and the System account. Search the Microsoft knowledge base article for more information.
Please be alerted to the fact that using the "subst" command can result in path names that are too long for the installer to operate correctly. Please do not use this command for determining target drives of the DirectX SDK installer prior to invoking the installer. This is also liable to cause the SDK uninstaller to fail.
The DirectX 9.0 runtime installer should not be run in Compatibility Mode.
Direct Animation is not registered properly on SDKDev debug runtime install.
The DirectX 9.0 runtime requires a Pentium compatible CPU for operation. Setup will not install on processors that do not report Pentium compatibility. Some older Cyrix processors, while compatible with the Pentium instruction set, report as x486 processors, and thus do not support installation of the DirectX 9.0 runtime.
On pre-patched Win98SE machine DirectX SDK setup fails with the following error: Error number 0x80070725 Incompatible version of RPC stud
Info: http://support.installshield.com/kb/view.asp?pcode=ALL&articleid=Q105810
FIX : http://download.microsoft.com/download/msninvestor/Patch/1.0/WIN98/EN-US/mcrepair.EXE
The Reference Rasterize is not installed on any versions of .NET Server 2003 product family.
Several Virus Protection software applications interferes with SDK installation and may require you to temporarily disable the Virus Protection software until SDK installation is completed.
Managed DirectX ( MDX ) requires both Visual Studio .NET and the .NET framework for development. The runtime installs MDX, so MDX .NET applications will run as long as the .NET framework is installed. The .NET framework is available for download at: http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/829/msdncompositedoc.xml. This includes the .NET framework redistributable required to enable .NET applications, including MDX .NET applications, to execute on machines without the development tools installed. For more information, see the .NET framework FAQs: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndotnet/html/faq111700.asp . The .NET framework SP2 is a recommended update, available at http://msdn.microsoft.com/netframework/downloads/updates/sp/default.asp
Uninstall:
To uninstall, use "Add/Remove Programs" from the Control Panel to uninstall the InstallShield installations.


back to top




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

What's New
There are many new and exciting features in all of the DirectX components.
The SDK has added a new member to its core technology called Managed DirectX, a DirectPlay port for the PocketPC, a High Level Shader Language for D3DX, and Windows XP parity on downlevel operating systems for DirectShow and the DirectX audio APIs.
DirectShow also has a new Video Mixing Renderer (VMR9) which uses D3D9 surfaces and always renders video through the 3D pipeline, along with new and exciting samples.
The generic Windows Media Format SDK stub library (wmstub.lib) available in previous beta releases has been removed. DirectShow samples using this stub library have been reverted to the DirectX 8.1 behavior of displaying a warning to obtain the stub separately, and the readme.txt files have also been reverted with information on the process to obtain the stub.

DirectX 9.0 Sample Browser: This is a new method of access samples, documentation and projects with DirectX 9.0. With the Sample Browser, we’ve removed the lengthy Start Menu hierarchy to execute samples and replaced it with the Sample Browser. From the browser you can execute samples, view documentation, load a sample project in Visual Studio (version 6 or .NET) & access DirectX utilities.
See the "New Features:" section for each of the component for additional information.


back to top



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

DirectX 9.0 SDK Notes
New features:
DXDiag automation, to enable MSInfo32 and other clients to get at its info.
DirectPlay hot-switchable between retail and debug using SDK control panel.
VS.NET compatibility (projects, solutions, etc. )
New AppWizards for DMOs (DirectSound/DirectShow) and DMTool (DirectMusic)
New Samples - vastly improved DirectShow/Direct3D integration is a note worthy change over DirectX 8.x.
Updated AppWizard for VS 7.0
Direct3D Shader debugger, integrates with the VS IDE.
D3DSpy is a new addition to the DirectX 9.0 SDK and can be used to analyze Direct3D programs. D3DSpy provides a simple user interface that lets programmers monitor the internal state of the Direct3D runtime, track and step through every call a program makes into Direct3D, examine the contents of textures/models/etc., and see statistical information about how efficiently a program uses the Direct3D API. You’ll find D3DSpy in the bin\DXUtils folder. We need your feedback.
New SAMPLES: Shader Workshop interactive shader test environment
New to DirectX 9.0 is Managed DirectX. We have enabled access to the DirectX APIs though managed code. Visual Studio .NET developers can now take advantage of the multimedia functionality and hardware acceleration of DirectX. Exposed API include: Direct3D, DirectPlay, DirectInput, DirectSound and support for Audio/Video Playback. By eliminating the COM interop layer we are able to enhance performance over previous typelibs. For example, the performance goal for Managed Direct3D is 98% of core C++ performance. By using managed code we’ve also seen a minimum reduction in code of 10% and upwards of 40% in some cases. Managed code is a great productivity improvement and frees developers from having to deal with memory management tasks. Through the DirectX9 beta cycle you will find a growing set of C# samples and tutorials using the DirectX managed layer and increasingly detailed documentation. As always we are anxiously awaiting your feedback to make this feature work best for you. Have some fun and let us know what you think.
Issues:
Be sure to set the paths to the DirectX 9.0 lib and headers within Visual Studio. They must be listed first. Otherwise you may experience compiler errors.
DirectDraw labels its debug spew as coming from "Direct3D8".
NetMeeting and Windows XP Remote Desktop disable graphics hardware acceleration.
Not all the debug files are provided for .NET Server. They will be made available once .NET Server Releases.
Sample Browser (SDK Sample Browser)

Microsoft Internet Explorer v5.01 or higher is required to run the Sample Browser.
back to top




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

Documentation
New Features:


Issues:
The links to the DirectX 9.0 documentation files from the start menu do not work on Windows 98 SE. On all supported versions of Windows proper icons are not displayed for the start mention documentation links.

For proper viewing of the DirectX Documentation, install the docs from the DirectX 9.0 SDK CD. Specify a full installation, or if you chose a Custom install, ensure that you've selected Documentation.

The known issues with the DirectX 9.0 Documentation are described in a separate file. You will find these issues listed in the DirectX9_Doc_Readme.txt file found in the <DXSDK Installed Folder>\doc\DirectX9 folder. This file is also installed into the <DXSDK InstallFolder>\doc\DirectX9when Documentation is installed.

See DirectX 9.0 SDK CD extras\documentation directory for other related documentation from previous versions of DirectX. This content is also available as a download on http://www.betaplace.com/ for pre-releases, and http://www.msdn.microsoft.com/downloads/default.asp for final.

Requirements:
The Managed DirectX documentation can be viewed only in Visual Studio .NET. Open Visual Studio .NET, and then, from the Help menu at the top, choose Contents. The documentation node in the Table of Contents is called "DirectX 9.0 (Managed)."



back to top




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

DirectX for Managed DirectX Samples:
New features:
Full support for all features in Direct3D, D3DX, DirectDraw, DirectPlay, DirectInput, and DirectSound.

Support for simple playback of many common audio and video formats.

A near 1 for 1 complement of samples when compared with C++.

Code reduction: Most common tasks done in DirectX are done with fewer lines of code via Managed Code.

Tight integration with .NET - Managed DirectX fully utilizes .NET and it's common types anywhere it can. For example, you can create a Managed Direct3D texture from a .NET Bitmap object via the 'FromBitmap' method.

Issues:
Managed DirectX documentation is only available through the Visual Studio .NET IDE help system.

The Beta and Release Candidate development runtimes of Managed DirectX (%WINDIR%\Microsoft.Net\Managed Directx) will not removed during Uninstall. You may safely remove the old versions located in this folder. Note that if you have used the 'Browse' functionality on the Add References dialog, or have changed the 'Copy Local' property to your references to True, you may need to remove and re-add your references to ensure you have the latest assemblies. If your projects still reference the older 'short' names (ie, md3d), you will need to update your references as well.

Some Direct3D samples fail if compiled in 'Release' mode in VB.NET: This is a known issue, that is caused by the integer overflow checks in VB.NET, which are turned off for Debug mode. This will be addressed in our next release. To remove these errors, go to project properties, click on the 'Configuration Properties' tab, and select 'Optimizations'. From there, enable the 'Remove integer overflow checks' to get the samples working again.

The following samples were shipped with missing resx files, which are neccessary in order for the forms designer to work:

DirectInput Drumpad (C# & VB.Net )

DirectPlay ChatRelay (C# )

DirectPlay DataRelay (C#)



To enable the forms designer with these samples:

-Open the code view of the form that's missing a resx file, and select all the code.

-Make a note of the forms name, delete the form and add a new form, renaming it with the deleted forms name.

-Select all the code in the newly added form, and paste the code from the deleted form into the newly created form.

-The forms designer will now allow you to open the form for editing.





Requirements:
Managed DirectX ( MDX ) requires both Visual Studio .NET and the .NET framework for development. The runtime installs MDX, so MDX .NET applications will run as long as the .NET framework is installed. The .NET framework is available for download at: http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/027/001/829/msdncompositedoc.xml. This includes the .NET framework redistributable required to enable .NET applications, including MDX .NET applications, to execute on machines without the development tools installed. For more information, see the .NET framework FAQs: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndotnet/html/faq111700.asp . The .NET framework SP2 is a recommended update, available at http://msdn.microsoft.com/netframework/downloads/updates/sp/default.asp



back to top




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

DirectX Audio (DirectSound® & DirectMusic®)
New features:
DirectSound low-latency sink: enables DirectMusic to attain significantly lower latency when using audiopaths that play through the software synthesizer and DirectSound. This is of particular interest to sound designers and composers who wish to take advantage of DirectMusic's features but require low latency for quick interactive response. For this release the default latency for DirectMusic is 55 ms; however, on higher-end machines the latency can be set much lower.

DirectSound support of 192+ kHz: The maximum frequency of sound buffers has been increased from 100 kHz to 200 kHz, where supported by the operating system (i.e., starting with Windows XP SP1). Note that this new frequency limit is not currently supported by DirectShow.

Frequency and effects (DSBCAPS_CTRLFREQUENCY and DSBCAPS_CRTLFX flags) can now be combined on DirectSound buffers.

The effects in dsdmo.dll support parameter curves (when hosted outside of DirectSound) without having to call Process() on them repeatedly in very small increments. The effects in dsdmo.dll can also process audio data in
IEEE_FLOAT format.

WAVEFORMATEXTENSIBLE audio formats are fully supported throughout DirectSound. However, they cannot be used in conjunction with DMO effects.

DirectMusic waves in wave tracks have variable range values for attenuation and fine tuning, enabling another degree of randomness in playback.

DirectMusic streamed waves now have looping enabled. This is effective for the use of larger streamed waves for looped environments and ambiences.

DirectMusic clocktime looping is enabled, allowing loops that will not change when the musical tempo is altered. In order to function as expected, segment length should be set in clocktime; every segment track should also be specified to use clocktime in its property page.

DirectMusic compression improvement: a function to eliminate the empty space at the start of MP3 compressed wave files in DLS.

DirectSound and DirectMusic include all Windows XP and Windows XP SP1 bug fixes.

New Audio Effect DMO and DirectMusic Tool wizards. See CD Layout above for more detailed information.

DirectMusic Style Library in the Essentials directory. See CD Layout above for more detailed information.

DirectMusic Producer: see Dmusprod.txt after installing Producer for new feature information.

Issues:
Wave track volume is not reset after a transition if a band has altered that PChannel's volume. Workaround: add a band to the segment with the wave track

DirectSound notifications can be triggered by other DirectSound processes or other DirectSound buffers within the same process (rare but something to be aware of)

back to top




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

Direct3D®
New features:
Many new interesting data formats, including:

Floating point z buffer formats

16-bit floating point vertex and texture formats

64-bit integer and 32-bit floating point texture formats

10:10:10:2 pixel formats

Discardable depth and stencil buffers

Light-weight mipmap

two-sided stencils

Support for 2D/video/GDI features, including:

Support for video hardware acceleration

2D operations, e.g., stretch, BLT, scissoring

GDI interoperability with GetDC method

New 3D rendering features, including

Displacement maps

Depth biasing

Antialiased lines

Constant blend factor

Separate alpha channel blending

Multisampling quality control parameter

Tesselation

Multi-Element Texture support

Multiple render targets

Autogenerated mipmaps

Spherical TexGen mode

Miscelanous:

Asynchronous notification

New vertex stream declarations

Multi-head support

Cleaned up interfaces to Swap Effects and Presentation Rates

Improved monitor refresh rate heuristics

Gamma correction

Color-converting windowed presentation

New vertex and pixel shader models for current and future hardware

Pixel shader models 2.0 and 3.0

Vertex shader models 2.0 and 3.0

Issues:
D3D9 interfaces are restricted to DirectX 7 level and above DDI drivers.

A limitation of the Windows2000 Kernel can result in some resources being freed while the resource is locked and being accessed by the application.

This results in the app writing to freed memory, causing an exception.

The problem only occurs with D3DPOOL_DEFAULT resources that the display driver chooses to place in system memory. When the device is put into a lost state (due to a mode change or ALT+TAB), all D3DPOOL_DEFAULT resources are freed. Direct3D has code to alias video memory resource pointers and redirect them to a dummy page, but D3DPOOL_DEFAULT system memory resources are not protected. The most common D3DPOOL_DEFAULT resources that get placed in system memory are Index Buffers, but some drivers may choose to place other resources in system memory as well. Apps can protect themselves by wrapping all resource accesses inside try…catch blocks.

When using the Direct3D software T&L pipeline (device created with D3DCREATE_SOFTWARE_VERTEXPROCESSING flag set or with D3DCREATE_MIXED_VERTEXPROCESSING flag and software vertex processing toggled on), then point sprite support is guaranteed. When using hardware vertex processing, some drivers may not support point sprites, but they must indicated this by setting d3dcaps->MaxPointSize to 1.0f.

Issues (Vertex/Pixel Shader):
For additional information about DirectX 9.0 shaders please refer to "DirectX 9.0 Shader Model Specification" download located on www.BetaPlace.com.

Two vertex shader instructions may produce implementation-specific results for out-of-range inputs, such as the log of a negative number. The log, logp and y- component of the lit instruction macro should not be passed negative values for this reason.

The D3DMISCCAPS_CLIPPLANESCALEDPOINTS caps bit is improperly set in the DirectX 8 software vertex processing pipeline device. The bit is cleared in the corresponding DirectX 9 device; however, we have decided not to change the legacy behavior for the DirectX 8 device since this change would introduce inconsistent behavior between DirectX 8.0, 8.1 and DirectX 9.0 versions of the DirectX 8 device.

Intel PSGP does not process several declaration data types correctly:

- PIII: SHORT2N, USHORT2N, SHORT4N, USHORT4N, DEC3N, FLOAT16_4

- P4: SHORT2N, USHORT2N, DEC3N, FLOAT16_4

This will be fixed for Final







back to top




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

D3DX
New features:
DirectX 9 introduces a new high level shading language for shader programming. This language provides the ability to more easily write shaders with functions, arbitrary variable names, conditionals, and loops.
The shader compiler now supports the following profiles: vs_1_1, vs_2_0, ps_1_1, ps_1_2, ps_1_3, ps_1_4, ps_2_0, ps_2_sw.
A shader fragment linker has been added to facilitate the management and generation of shaders, The fragment linker links assembly or high level shading language shader fragments together. i.e. to allow mixing and matching of lighting types, skinning types, etc.
The Effect framework has undergone some exciting changes for DirectX9, specifically the addition of the ID3DXEffectCompiler interface. The Effect compiler interface can be used for shader specialization. i.e. marking a global variable as literal for a specific compile of the shader.
Added variable sharing between effects. Variables in effects files declared with the keyword "share" will be shared across all effects created with a given effect pool.
Patch support is included in the mesh library, including Adaptive tessellation.
A new animation subsystem and mesh hierarchy loader are now included.
The mesh library now supports arbitrary vertex declarations (single stream only). CloneMesh handles all data type conversions. i.e. FLOAT2 to FLOAT16_2, D3DDECLTYPE_DEC3N...
Language Limitations:
Profile ps_1_4 does not yet support more than two phases for dependent lookups
In ps_1_1, ps_1_2, ps_1_3, the texdp3tex and tex3xm* instructions may emit incorrect sampler information in the constant table. To correct this problem, the user should manually bind the samplers to the appropriate texture stage.
Issues:
This product includes software developed by the University of California, Berkeley.”
It is recommended that you recompile the 3dsmax exporter prior to using it.
The binaries for the Max X file exporter are no longer included in the distribution. In order to use it, compile the plugin with your version of Max. This should ensure proper functionality of the exporter.
back to top




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

DirectInput
New features:
This release of DirectInput has identical features to that of DirectX 8.1. At this time there is no plan to add additional features to DirectInput in DirectX 9.0



back to top




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

DirectPlay
New features:
The DirectPlay application programming interfaces (APIs) are available for the Microsoft Windows® Powered Pocket PC 2002. See DirectPlay for Pocket PC 2002 in the help file for more information.

DirectPlay8 Bluetooth Service Provider for Pocket PC 2002 is available for devices using the Microsoft Windows CE Bluetooth stack.

The DPN_MSGID_SEND_COMPLETE message structure has new members that allow you to accurately determine the round-trip travel time of individual messages.

DirectPlay has a new service provider for network simulation. You can continue to use the dp8simui.exe interface tool or try the new IDP8SimControl methods to test applications under a variety of network conditions.

Applications can cancel all messages sent by a particular player using the DPNCANCEL_PLAYER_SENDS flag when calling IDirectPlay8Peer::CancelAsyncOperation(),IDirectPlay8Server::CancelAsyncOperation(), or IDirectPlay8Client::CancelAsyncOperation().

Players receive their local player identifier (ID) in the DPN_MSGID_CONNECT_COMPLETE message.

Hosts can prevent DirectPlay from servicing enumeration queries by setting the DPNSESSION_NOENUMS flag in the DPN_APPLICATION_DESC structure when calling IDirectPlay8Peer::Host() or IDirectPlay8Server::Host(). Additionally, servicing enumeration queries may be turned off and on with this flag by calling IDirectPlay8Peer::SetApplicationDesc() or IDirectPlay8Server::SetApplicationDesc().

Messages sent to a group with no players in it will now return DPNSUCCESS_NOPLAYERSINGROUP instead of DPNERR_GENERIC.

Optional packet signing for all DirectPlay8 traffic

Improved defense against connection spoofing

Added DPNCLOSE_IMMEDIATE flag to Close() for ungraceful immediate shut down

Added DPNINITIALIZE_HINT_LANSESSION to Initialize() to provide DirectPlay8 a hint about the underlying session infrastructure

Added packet coalescence via DPNSEND_COALESCE flag for Send()/SendTo()

Allow application tuning of the DirectPlay8 protocol via DPN_CAPS_EX structure provided to SetCaps() and retrieved from GetCaps()

Added the group owner’s context value to the DPNMSG_CREATE_GROUP structure

Calls to Host() without the DPNSESSION_NODPNSVR flag set in the DPN_APPLICATION_DESC structure will fail if dpnsvr.exe fails to start and will return DPNERR_DPNSVRNOTAVAILABLE

Improved DirectPlay8 protocol behavior for slightly “lossy” links

Added new IDirectPlay8NATResolver interface and client side device address components DPNA_KEY_NAT_RESOLVER & DPNA_KEY_NAT_RESOLVER_USER_STRING to further improve NAT support.

Added new DPNA_KEY_TRAVERSALMODE device address component to control automated NAT and firewall traversal settings.

Added new IDirectPlay8ThreadPool interface for finer control over DirectPlay's threading, include a new DoWork threadless mode.

Added DPNGETLOCALHOSTADDRESSES_COMBINED flag for GetLocalHostAddresses() to combine all of the hosts addresses into a single address object. This can be passed to EnumHosts or Connect so that all addresses will be tried simultaneously.

Added transparent IPv6 support to the TCP/IP service provider. Applications should require no changes to support either IPv4 or IPv6 as long as they do not assume that the DPNA_KEY_HOSTNAME component is in IPv4 decimal dotted notation (nnn.nnn.nnn.nnn).

Issues:
To use DirectPlay Voice in full duplex mode, we recommend that you updateto the latest drivers for your audio device. Some older drivers do notprovide reliable full duplex performance.

If you successfully connect to a location with any asynchronous enumerations still active, the enumerations will be canceled automatically for you. The DPN_MSGID_ASYNC_OP_COMPLETE messages for the enumerations will list DPNERR_CONNECTING as the result code. As with all asynchronous operations, if you attempt to call CancelAsyncOperation() on the handle after you have received its DPN_MSGID_ASYNC_OP_COMPLETE message, you will get back the DPNERR_INVALIDHANDLE error code. Be aware that this is the expected behavior and that you should not exit with an error condition.

In DirectX 9.0 RC0, DirectPlay defaults to using "131.107.139.133:2323" for a NAT resolver. Every Host(), Connect(), or EnumHosts() operation with the TCP/IP service provider will therefore attempt to query this address before completing. No private information is contained in the queries. This is a temporary Microsoft server that implements an IDirectPlay8NATResolver interface, and replies to all queries regardless of the DPNA_KEY_NAT_RESOLVER_USER_STRING data. If you are on a private network and unable to contact this server, you may notice Host(), Connect(), or EnumHosts() operations taking longer than usual. If you wish to disable this default NAT resolver, create an empty string value called "DefaultNATResolver" under HKEY_LOCAL_MACHINE\Software\Microsoft\DirectPlay8. This default NAT Resolver string will be turned off in the next release. Additionally, the server at that address will no longer be available.

Notes on DirectPlay for Pocket PC:
In order to conserve memory usage, the retail binaries for the PocketPC version of DirectPlay do not contain parameter validation. During development, your application should make use of the debug binaries in order to check for parameter usage errors.

Notes on NATs (Network Address Translators):
When performing the first operation over the TCP/IP service provider, DirectPlay attempts to detect a Network Address Translator (NAT) or firewall. This increases the time that the Connect(), Host(), or EnumHosts()|calls take. If you are sure that your machine is not behind a NAT or|firewall, you can set the new DPNA_KEY_TRAVERSALMODE device address component to DPNA_TRAVERSALMODE_NONE to avoid this detection process.

When you specify a port in your device address, the default DirectPlay traversal mode DPNA_TRAVERSALMODE_PORTREQUIRED maps the same port number externally on the Universal Plug and Play (UPnP) compatible NAT. If this port is already in use, then the Connect(), Host(), or EnumHosts() could fail with DPNERR_INVALIDDEVICEADDRESS. In some cases, your application may not require that the public port be the same as the local port, or mapped at all. You can use DPNA_TRAVERSALMODE_NONE or DPNA_TRAVERSALMODE_PORTRECOMMENDED to alter this behavior.

Notes DirectPlay Voice codecs via Windows ACM (Audio Compression Manager):
DirectPlay Voice uses the following codecs via the Windows ACM: - Microsoft ADPCM - Microsoft GSM - DSP Group Truespeech

Installation of these codecs with Windows is optional. If they are not installed, then one or more of the compression types in DirectPlay Voice will not function. If the application attempts to use a compression type that is not functional due to a missing ACM codec, it will receive the DVERR_COMPRESSIONNOTSUPPORTED return code.

On Windows 2000, the user can install these codecs through the Add/Remove Hardware wizard. The user should select "Add/Troubleshoot a device". When a list of hardware is presented, the user should select "Add a new device", then on the next page select "No, I want to select the hardware from a list". This will bring up a list of hardware. Select "Sound, video, and game controllers". The "Audio Codecs" item is listed under "(Standard system devices)".

On Windows 9x, the user can install these codecs through the Add New Hardware wizard. When prompted, the user should select "No, I want to select the hardware from a list". In the list of device types, codecs are listed under "Sound video and game controllers". The codecs are listed under two manufacturers. The ADPCM and GSM codecs are listed under "Microsoft Audio Codecs" and the Truespeech codec is listed under "DSP Group".

back to top





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

Broadcast Driver Architecture
New Features:
Functional parity for down level systems (pre-Windows XP)

Addition of support for DVB-T and DVB-C broadcast standards

Issues:
Broadcast IP Data Reception under Windows 2000:
After rebooting a Windows 2000 system with a BDA receiver card installed, the BDA NDIS IP NIC is not immediately active. It becomes active only when an application inserts the BDA IPSink filter into a graph and connectsits input pin. Once activated by connecting the IPSink filter's input pin, it takes 20 to 30 seconds for the BDA NDIS IP NIC to be assigned an IP address. The address assigned will be a Net 10 address. Once activated, the BDA NDIS IP NIC will remain active until the system is rebooted.

There may be some applications that use the BDA NDIS IP NIC as the default LAN adapter. These apps will fail if the BDA NDIS IP NIC is active. To de-activate the BDA NDIS IP NIC, reboot the system and do not run a TV graph or application.

When viewing a BDA Network provider property page with GraphEdit, you cannot enter a -1 value. As a workaround, enter 0 and click the down arrow to set the value to -1.

Pin connections with mpe/slip with ipsink may fail if NO tuner is installed post-DX8.1 installation. This behavior is exactly as seen in Windows XP. This may be due to the TV tuner driver not being properly installed. Automatic loading of BDA NDIS miniport is restricted by design. The solution is to right click and install the bda.inf, followed by a machine reboot.



back to top




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

DirectShow
New features:
Video Mixing Renderer Filter 9 (VMR-9). - This new, redistributable rendering filter is similar in concept and design to the VMR that is available for Microsoft Windows XP Home Edition and Windows XP Professional. The VMR-9 is more powerful than the original VMR (now called "VMR-7") because it is fully compatible with the DirectX 9.0 graphics capabilities and it offers improved support for deinterlacing and ProcAmp control (brightness, contrast, hue, and saturation).

New deinterlacing support in the DV Video Decoder filter. The DV Decoder filter now supports interlaced output, as well as deinterlaced output. Earlier versions of the decoder always deinterlace the video. With the new version, the interlaced video can be preserved and saved to file, or the video can be deinterlaced by the VMR, for improved rendering quality.

New deinterlacing support in DirectX Video Acceleration.

AVStream driver development and runtime support on all platforms prior to Windows XP has been improved for close functional parity with Windows XP. A few AVStream and core Kernel Streaming behavioral differences still exist that are documented in the SDK.

New encoder application programming interface (API) specification. The Encoder API defines a standard, format-neutral way in which software or hardware encoders can communicate with applications and device drivers. IGetCapabilitiesKey is a new interface that filters can implement in order to enable applications to query for the filter's capabilities.

MPEG-2 Sections and Tables Filter. This new filter enables an application to get PSI tables from an MPEG-2 transport stream.

Microsoft TV Technologies now supports DVB-T (terrestrial) and DVB-C (cable), in addition to DVB-S (satellite). For more information, see the SDK documentation.

The Analog TV Tuner filter now supports adding new channel frequencies via the registry. This feature extends the existing mechanism for adding channel frequency overrides. For more information, see International Analog TV Tuning in the SDK.

DirectShow Editing Services (DES) now supports plug-in video resizing filters. For more information, see Providing a Custom Video Resizer in the SDK.

The DVD Graph Builder enables applications to use the VMR-9 through the IDvdGraphBuilder::RenderDvdVideoVolume method. The DVD Navigator now supports playback of audio during fast forward; users can now watch a movie at speeds higher than 1x without raising the pitch of the audio track, if the decoder supports this feature. The DVD navigator now provides faster DVD menu navigation.

Video renderer no longer displays frame counters on debug builds.

SDK Updates

Significant enhancements to the GraphEdit utility, including Windows Media Certification (dekeying of non-DRM WM graphs), Filter Favorites menu, improved connect/disconnect from remote graphs, save/restore options, frame stepping, and color coding of connected filters. XGR files are no longer supported by GraphEdit.

Sample source code has been improved to enhance security, reliability, and readability. Support for Visual Studio.NET has also been added (VC.NET projects, solutions, etc.)

Managed code for audio and video file playback. The Microsoft.DirectX.AudioVideoPlayback managed code namespace provides playback and simple control of audio and video media. For more information, refer to the DirectX documentation for the managed DirectX components.

Numerous bug fixes and refinements for SDK samples and tools

New Unicode Debug/Release build targets for Visual C++ 6.0 and Visual Studio.NET projects

New and revised content in the SDK documentation

New ProfileEnum tool (in Bin\DXUtils) lists the Windows Media system profiles that are available for use on your system. This tool is helpful if you are creating Windows Media files (ASF,WMA,WMV) through DirectShow interfaces.

The AMCap sample application now supports MPEG-2 program stream input, for example from analog TV Tuners that stream MPEG-2 content. A third-party DirectShow-compatible MPEG-2 decoder is still required to decode the streams.

The PlayCapMoniker sample demonstrates an alternate method (AddSourceFilter())because using RenderFile() with monikers is no longer supported.



New DirectShow samples:
Audiobox: Audio-only media player, similar to the Jukebox sample. It supports Favorites and playback of Windows Media Audio and MP3 files.

CaptureTex: Blends Texture3D and PlayCap to display incoming live video on a rotating Direct3D surface

CaptureTex9: Extends the CaptureTex sample to render live incoming video onto a Direct3D9 surface (a waving flag).

CompressView: Demonstrates how to recompress an audio or video file using a different compression type.

DSNetwork Filters: Implements an IP source filter and an IP rendering filter. This filter set allows you to transmit/receive MPEG-2 data on a network.

GrabBitmaps: Shows how to grab bitmaps from a video stream.

Metronome Filter: Sample filter that shows how to implement a reference clock.

PlayDVD: A simple windowed DVD player based on the PlayWnd sample.

PlayWndASF: Added limited DRM support to the previous PlayWndASF sample.

PSIParser Filter: Shows how to retrieve program information from an MPEG-2 transport stream.

PushSource Filters: Set of three source filters that output a single bitmap, a series of bitmaps, or a live desktop capture video stream.

RenderLog: Creates a text log of DirectShow's progress while rendering a media file. If you receive an error when you call IGraphBuilder::RenderFile, you can use this tool to create and view the log.

RGBFilters: Set of several sample source and transform filters useful for testing.

Texture3D9: Extends the Texture3D sample to play video on a DirectX 9 texture surface, utilizing Direct3D9 features for more efficient rendering.

TransViewer: Enables you to preview all of the DirectShow Editing Services transitions installed on your system.


New VMR samples that demonstrate various features of the VMR-7:
Blender: Demonstrates how to mix, blend, and manipulate two video streams.

MonitorInfo: Displays simple information about the available monitors (using a VMR interface).

Pip: Demonstrates how to create picture-in-picture effects using the VMR.

Text: Displays alpha-blended text over running video.

Ticker: Extends the Text sample to draw horizontally scrolling text across the bottom of the video. You can scroll text as a static bitmap or as a dynamically generated bitmap created from user input.

VMRMulti: Plays multiple video files over an animated Direct3D background. Each video stream is individually seekable.

VMRXclBasic: Shows how to play video in full-screen exclusive mode.

Watermark: Places an alpha-blended bitmap over the video and adds effects (alpha strobe, scrolling, bitmap animation).

Windowless: Demonstrates basic playback using the VMR's Windowless mode.

New VMR9 samples to demonstrate use of VMR9 on all DirectX9 systems:
VMR-9 versions of eight VMR-7 samples: Blender9, MonitorInfo9, Pip9, Text9, Ticker9, VMRPlayer9, Watermark9, and Windowless9

VMR9Allocator: Renders video onto a rotating Direct3D surface

BitmapMix: Uses the VMR9 to render video onto a Direct3D9 surface while blending a bitmap that can be moved via mouse input

MultiVMR9: Demonstrates using a custom VMR9 Allocator-Presenter in a multi-graph environment. There are three folders in this project, including a support DLL, a MultiPlayer sample, and a 3D GamePlayer sample that integrates video playback into a Direct3D game environment.

Removed Samples:
JukeboxASF has been removed. Its Windows Media support has been merged into the Jukebox sample.

Sample media files:
The video codec used in highway.avi and ruby.avi has been changed to Cinepak. This was done to enable playback on clean installations of Windows XP SP1, which no longer ships the Indeo codecs.

Issues:
A modification was made in the MPEG-1 audio decoder that no longer allows a dynamic change in the MPEG audio layer.

The beta 2 raw AV/C command issue has been resolved.

The beta 2 proppage.dll dependence on msvcp60.dll has been resolved.

The Windows Media Format SDK de-keying stub library (wmstub.lib) provided in previous beta releases has been removed. The affected samples have been reverted to the DirectX 8.1 behavior of displaying a warning to obtain the stub, and the sample readme files have the directions on obtaining the stub restored.

Note that wmstub.lib is not part of the redistributable file set, and may not legally be distributed

Some video card drivers incorrectly advertise the D3DPTEXTURECAPS_NONPOW2CONDITIONALflag, which indicates that the driver supports non-power-of-2 textures. Because of this driver bug, you may see garbled video data in the place of an alpha-blended bitmap. This will be noticeable when running the Text or TickerVMR samples in the Samples\DirectShow\bin folder. We hope that this vendor driver issue will be resolved soon.

The DirectShow Visual Basic 6.0 samples are installed in the Extras folder.There are no new VB or VB.NET samples available for DirectX 9.0.

There is a known problem with the MP3 decoder filter when used with Audio Effects DMOs. If you add an audio effect DMO (like WavesReverb, Echo,or Flange) to an existing MP3 filter graph, the audio could be played backat double speed. The problem would occur whenever the MP3 decoder is connected to a downstream audio effect dmo (via the dmo filter wrapper) that offers a default audio input type which doesn't match the native format of the uncompressed MP3 stream. For example, if you render a 22kHz MP3 file and add a DMO Audio effect, the MP3 filter could misinterpret the input type as being 44kHz when it is actually 22kHz. This would not be a problem for 44kHz MP3 files.

The WavesReverb DMO will only accept 16-bit audio input. If you attempt to connect the WavesReverb DMO to an 8-bit audio source, the connection will fail.

The sample XTL files were updated in DirectX 8.1 to reflect a change in the DES XML parser on Windows XP. XML attributes must now be specified in *lowercase*. Mixed-case attributes will fail on Windows XP.

The latest WM ASF Reader and WM ASF Writer filters, and the DMO Wrapper filter, are shipped in the Windows Media Format 9 Series SDK. The DirectShow SDK ships versions of these filters locked at the DirectX 8.1 level of functionality.

Both VMRXcl and VMRXclBasic samples requires a video adapter than can be set to 640x480 resolution at 32-bit display depth. Some older video cards support only 16-bit and 24-bit resolutions, which would prevent this sample from running properly.

The way that DirectShow Editing Services (DES) parses numbers in XTL files is not entirely consistent.

The following attributes must be integers that do not contain a period or comma:

- bitdepth

- buffering

- height

- samplingrate

- stream

- userid

- width

Correct:

<group type="video" width="1024" height="1024">



Incorrect:

<group type="video" width="1,024" height="1,024">



The following time-based attributes must use a period between the seconds and the frame number, regardless of user locale:

- cutpoint

- framerate

- mlength

- mstart

- mstop

- start

- stop

- time

- tlstart

- tlstop



Correct:

<clip src="sample.avi" start="1:00.30">



Incorrect:

<clip src="sample.avi" start="1:00,30">

All parameter values within a <param> element must use periods or commas depending on the user's locale.

Examples:

English: <param name="Vol" value="0.050000">

German: <param name="Vol" value="0,050000">



DirectShow Samples Build Notes:
To enable Windows XP VMR features, set the Windows version to 0x501 (the Windows XP version) in your Visual C++ project files.

Application development using the DirectShow base classes libraries requires installation of the DirectShow samples. The source code for the base classes is included as a sample project in the Samples\C++\DirectShow\BaseClassesdirectory. You must compile these base classes to generate strmbase.lib and strmbasd.lib, which are no longer installed as library files. If you are linking with strmbase.lib or strmbasd.lib with your own application, be sure to build and link with the updated DirectX 9 libraries (instead of the older libraries that may be installed with Visual Studio or the Microsoft Platform SDK).

You will be required to build the BaseClasses libraries before any sample that depends on them can be built. Please review the Readme.Txt file in the DirectShow samples root directory for more information on building the samples.

The samples included with the SDK are configured to compile and link with the sample BaseClasses libraries, which are generated by building the BaseClasses sample project. Further build instructions are provided in: <DXSDK Install Folder>\Samples\C++\DirectShow\readme.txt.

The DirectShow IDL files are installed in the SDK \include\DShowIDL directory.

The <streams.h> header file, along with many other DirectShow-specific header files, is located in the DirectShow samples BaseClasses directory, which includes the BaseClasses source code and header files. You must add the BaseClasses directory to the beginning of your project's include path settings in order for Visual C++ to find all of the updated header files.

If you have the SDK on CD-ROM, the Extras\DirectShow\Media directory contains additional media that can be used with DirectShow and the DirectShowEditing Services (DES) interfaces. We have included DV-encoded AVI videos, larger MPEG videos, and higher-quality JPEG images. Since the DV files are very large, you should copy them to your hard disk before playing them to ensure the best performance.

DirectShow MFC samples won’t build with the Unicode settings under Visual Studio 6 unless the MFC Unicode libraries (MFC42U.LIB and MFC42UD.LIB) are installed on the system. These libraries are not installed by default with Visual Studio 6.

To add them:

1) Select Add/Remove Programs from the control panel.

2) Highlight Visual Studio 6.

3) Push the “Change/Remove” button. This will start the setup application for Visual Studio 6.

4) Push the “Add/Remove” button.

5) Highlight Visual Studio C++ 6. Push the “Change Option…” button.

6) Highlight “VC++ MFC Libraries and Templates”. Push the “Change Option…” button.

7) Highlight “MS Foundation Class Libraries”. Push the “Change Option…” button.

8) Check “Shared Libraries for Unicode”. Push the “OK” button.



back to top




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

Compiler Support
All DirectX 9.0 SDK samples are developed and compiled with Visual Studio 7.0. The DirectX 9.0 SDK samples are optimized to compile with Visual Studio 7.0, and we have provided Visual Studio 6.0 DSP files for your convenience.

The DirectX SDK no longer supports using Visual Studio 5.0. While this may work, any issues with using Visual Studio 5.0 and the DirectX 9.0 SDK will not be addressed in this release or future releases. The DirectX 8.0a SDK supports VC 5.0 ( with the SP3 linker fix ) and Windows 95, so this may be an option for some developers.



back to top




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

Special Thanks


Marlin Studios



Textures used in the Billboard sample, tree02S.tga, tree01S.tga & tree35S.tga, are provided courtesy of Marlin Studios ( http://www.marlinstudios.com/).

They are provided for use with this sample only and cannot be distributed with any application without prior written consent.



Viewpoint Digital, Inc.



The model used by the Visual Basic AutoParts sample, engine1.x, is provided courtesy of Viewpoint Digital, Inc. ( http://www.viewpoint.com/). It is provided

for use with this sample only and cannot be distributed with any application without prior written consent. V6 Engine Model copyright 1999 Viewpoint

Digital, Inc..



3DCAFE and Platinum Pictures



The model in the Dolphin samples, Dolphin.x, is derived from the model files (dolphins.zip) provided courtesy of 3DCAFE and Platinum Pictures

(http://www.3dcafe.com/). It is provided for use with this sample only. For further terms of use please visit the 3DCAFE site or contact 3DCAFE.



back to top




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

ROLAND SoundCanvas Sound Set For General MIDI And GS Format


The Roland SoundCanvas Sound Set includes the necessary sounds to make a complete General MIDI compatible sound set. It also includes additional

sounds necessary to make a complete GS Format compatible sound set.



WHAT IS THE GS FORMAT?



The GS Format is a standardized set of specifications for sound sources that defines the manner in which multitimbral sound generating devices

will respond to MIDI messages. The GS Format also complies with General MIDI System Level 1.



The GS Format also defines a number of other details over and above the features of General MIDI. These include unique specifications for sound

and functions available for tone editing, effects, and other specifications concerning the manner in which sound sources will respond to MIDI messages.

Any device that is equipped with GS Format sound sources can faithfully reproduce both General MIDI sound recordings and GS Format MIDI sound

recordings.



HOW TO CONTACT ROLAND:



For more information, please contact:

Roland Corporation U.S.

7200 Dominion Circle

Los Angeles, CA 90040-3696

Phone: (323) 890-3700

Fax: (323) 890-3701



COPYRIGHT NOTICE AND LICENSE LIMITATIONS



Roland GS Sound Set/Microsoft (P) 1996 Roland Corporation U.S.



The Roland GS Sound Set/Microsoft, the "Sample Set", incorporates the Roland SoundCanvas Sound Set. Roland Corporation U.S. owns the Sample Set

and all copyrights pertaining thereto and has licensed the Sample Set for use solely on Microsoft operating system products and Microsoft Application

Products.



Roland reserves all rights to the Sample Set not expressly granted by Roland Corporation U.S. or by Microsoft under the terms of Microsoft's End User

License Agreement.



The Sample Set may only be redistributed with your software application as a part of a Microsoft operating system product installation and under the terms

of Microsoft's End User License Agreement. The Sample Set may not be separated from the Microsoft operating system product; the Sample Set may

only be installed by the Microsoft installation procedure for the associated Microsoft operating system product or for an associated software development

kit. All other uses of the Sample Set require a separate written license from Roland Corporation U.S.



The Sample Set may not be used, copied or redistributed in hardware ROM or similar technology of any device without prior express written permission

from an authorized representative of Roland Corporation U.S. The Sample Set may not be redistributed with any Musical Instrument . A "Musical

Instrument" is any device that is capable of generating musical sounds without being directly connected to a computer with a licensed Microsoft

operating system product. You may not modify the Sample Set under any circumstances.



back to top



CD Layout:

The following is a brief description of the directories found with a complete DirectX 9.0 SDK download. Depending on options specified during installation, some of these directories can be installed on your hard drive.

\Bin
\DXUtils
High level DirectX applications & tools. All can be accessed from the SDK sample browser.
\DirectX extensions for Visual Studio
Microsoft® Visual Studio® supports debugging assembly level and high-level language vertex and pixel shaders.

\Visual Studio 6.0 Wizards
This directory contains the application wizards that can be plugged into Microsoft Visual C++ 6.0. This wizards are installed by the SDK.
Audio Effects DMO Wizard (AEDMOWiz.awx, AEDMOWiz.hlp, and AEDMOWiz.cnt): simplifies the process of creating a custom Audio Effects DMO. It will create a ready-to-compile Visual Studio 6.0 project containing C++ code that handles the basic COM support and DLL entry points. In addition, the wizard will generate the DMO's interface and implementation class with basic services already implemented for you. Since the project is ready to be compiled into a DLL, all you have to do is complete the function that actually processes the audio samples.
DirectMusicTool Wizard (DMToolWizard.awx, DMToolWizard.hlp, DMToolWizard.cnt): simplifies the process of creating a custom DirectMusic tool. It will create a ready-to-compile project containing C++ code that handles the basic COM support and DLL entry points. In addition, the wizard will generate the tool's interface and implementation class with basic services already implemented for you. Since the project is ready to be compiled into a DLL, all you have to do is complete the function that actually processes the DirectMusic messages (DMUS_PMSG).
AppWizard (AppWiz9.awx): creates a minimal C++ template application that optionally includes integrated Direct3D, DirectInput, DirectMusic, DirectSound, and DirectPlay support.
To make the wizard available manually, copy it to the \Common\MSDev98\Template folder of your Visual Studio installation.
To use AppWizard:
1. Run VC6 or VS7
2. Click "New". Under the "New Projects" tab, select the
"DirectX AppWizard" wizard.
3. Type a project name and click OK.
4. Choose wizard options, and click finish when done.
5. Build and run the new project.
\Visual Studio 7.0 Wizards
This directory contains the application wizards that can be plugged into Microsoft Visual Studio 7.0. They are all installed by the DirectX 9.0 SDK
\Doc
Contains reference documentation for the DirectX 9.0 APIs. This Documentation must be viewed with Windows HTMLHelp. Note: The HTMLHelp viewer requires a minimum installation of Internet Explorer 5.0 (IE5). IE5 can be found at http://www.microsoft.com/windows/ie/default.htm.
\Essentials
\DirectMusic Producer
DirectMusic Producer is the authoring tool for DirectMusic. It allows composers and sound designers to use the interactive and variable resources of DirectMusic along with the consistent sound performance of DLS. DirectX Audio Scripting can also be authored and tested within Producer. The DirectMusic Producer setup program and all files are located here.
\DirectMusic Style Library
The Style Library contains 187 styles representing varying genres, 27 chordmaps, and a basic styleplayer to audition them. IMPORTANT: the StylePlayer.exe as well as all the styles (.sty) and chordmaps (.cdm) should be copied to a local machine and placed in the same directory (otherwise the app will not find the content files). See StylePlayer.txt for more detailed information.

\Extras (Available on CD or as separate download
\Direct3D
Skinning exporter tools
\DirectShow
Contains the DVDBoilerplate. See readme.txt within the directory for more information.
Contains additional media that can be used with DirectShow and the DirectShow Editing Services (DES) interfaces
\Documentation
Contains DirectX 7 HTMLHelp Documentation for English and Japanese. Also contains DirectX 7 Documentation in Microsoft Word format (English only). Contains DirectX 8 HTMLHelp Documentation for Japanese.
\Symbols
Contains directories of DirectX 9.0 symbol files for Windows 9x, Windows 2000 and Windows XP (retail and debug for each).

\POCKETPC
Contains the DirectPlay binaries, samples, and symbols (retail/debug) for the Pocket PC

\Include
Contains DirectX 9.0 include files for DirectX core components.

\Lib
Contains DirectX 9.0 library files for DirectX core components.

\License
Text versions of the DirectX SDK and End User License Agreements and the Redistributable License Agreement.

\Redist
Redistributable versions of the DirectX 9.0 Runtime.

\Samples
Contains all sample code and sample binaries. Most samples can be accessed from the Start menu when installed via the downloaded InstallShield setup.

\SDKDev
This directory contains the runtime installs that are installed with the SDK. They are English only and contain both debug and retail DirectX 9.0 system components that can be "switched" between retail and debug without re-installing. For the DirectX 9.0 components, retail or debug can be switched via the DirectX Control Panel. The \retail folder contains the setup that will install non-DirectX 9.0 retail components while the \debug folder will install all debug components. Both install DX9.0 retail and debug components; These are the only components that can be "switched".

ActiveWin.com Featured Partners:

1z0-042 exams enable the IT specialists in installing and configuring the oracle database 10g with the creation and administration of user accounts in the oracle database and backup and recuperation of the oracle database 10g. 70-301 exams are very good representation of management, organization and delivery of IT projects by highlighting the Microsoft solutions framework. 640-811 exams stand for interconnecting Cisco network devices course, enabling the IT applicants to choose, connect, troubleshoot and configure the management IP traffic with the entire accessibility of point to point connections , determination IP routers and extension of switched networking systems. 156-215 exams cover all areas of IT expertise to promote the proficiency and Excellency of IT industry. MB7-221 exams’ plausibility and feasibility is demonstrated by IT projects with the latest technology to ensure the thriving career of IT specialists.


Index

 

  *  
  *   *