Managed DirectX - Introduction to .NET and Multimedia
1. .NET and Multimedia - Introduction of managed DirectX
Andreas Lennartz
University of Applied Sciences, Fulda
alenn@gmx.net
Abstract any CLR compliant language can optionally
be used) (?).
DirectX is a multimedia API that DirectX allow it to make non-hardware-
provides a standard interface to specific function calls. For this purpose,
interact with graphics and sound DirectX is accountible for the execution on
cards, input devices and more. Di- the hardware. If the function is supported
rectX abstracts code from the spe- from the hardware, the hardware acceleration
cific hardware and translates it to makes the API functions work fast. If not, Di-
a common set of instructions into rectX has software emulation that takes over.
hardware specific commands. The It will be slower, but in spite of that the
actual implementation of DirectX same low-level API can be used. Developer
contains an integration in managed can focus on the application development it-
Code, which combines the advan- self. The layer of DirectX that takes care
tages of both world, and is called of hardware-supported features is called the
managed DirectX. hardware acceleration layer (HAL), and the
software emulation layer that kicks in if the
1 Introduction hardware doesn’t support a feature is called
the hardware emulation layer (HEL).
Currently there are two vendors offering APIs When writing applications with managed
for developing 3D-Applications available. On DirectX or unmanaged DirectX, managed Di-
one hand Microsoft provides its DirectX-API rectX has the prejudice that it is slower than
and on the other hand there is the open source unmanaged. But this is only true in certain
alternative OpenGL. circumstances. So far a lot of games were
OpenGL is an environment for developing created with managed code or using a mix
portable, interactive 2D and 3D graphics ap- of managed and unmanaged code. Writing
plications. Introduced in 1992, OpenGL is in managed code makes the developers more
one of the industry’s first choice for 2D and productive and thus write more code in less
3D graphics APIs (?). Because of its stan- time and produces safer code.
darisation it is platform independent. With
OpenGL, rapid application development with 2 Managed Code
a broad set of rendering, texture mapping,
special effects and other powerful visualiza- Managed code is code that has its execution
tion functions can be archieved. managed by the .NET Framework Common
DirectX first appeared in 1995 and was then Language Runtime (CLR). It refers to a con-
called the ”GameSDK”. Originally it was tar- tract of cooperation between natively execut-
geted at developers using C and C++. With ing code and the runtime. In this contract it
the release of the first managed version (9.0) is specified that at any point of execution, the
of the API in December 2002 it is possible to runtime may stop an executing CPU. Then it
use C# or VB.NET with DirectX (Actually may retrieve information specific to the cur-
2. rent CPU instruction address. Information tections in place around memory management
that must be queryable generally belongs to and port I/O and so forth, but the system
runtime state, such as register or stack mem- doesn’t actually know what the application is
ory contents. doing. Therefore, it can’t make any guaran-
The necessary information is encoded in an tees about what happens when the applica-
Intermediate Language (IL) and associated tion runs.”’ see (?)
metadata. The symbolic information that de-
scribes all of the entry points and the con-
3 DirectX components
structs is exposed in the IL (e.g., methods, DirectX 9.0 for Managed Code is made up of
properties) and their characteristics. With the following major components (The depre-
the Common Language Infrastructure (CLI) cated parts of DirectX will not be included in
Standard, a description is given how the in- the further discussion):
formation has to be encoded. Programming
languages that target the runtime will build • Direct3D Graphics provides a single API
the correct encoding. Therefore, the devel- that can be used for 3D graphics pro-
oper only has to know that any of the lan- gramming.
guages that target the runtime produce man- • DirectInput provides support for a vari-
aged code. This code contains encoded files ety of input devices, including full sup-
that contain IL and metadata. There are a lot port for force-feedback technology.
of languages to choose from, because there are
over 20 different languages provided by third • DirectSound provides support for playing
parties in addition to the standard languages and capturing prerecorded digital sam-
from Microsoft. (C#, J#, VB .Net, Jscript ples.
.Net, and C++).
• AudioVideoPlayback allows for playback
Before execution of the code, the Virtual and simple control of audio and video
machine compiles the IL into native exe- media.
cutable code. While the compilation happens
by the managed execution environment, the 3.1 Direct 3D Graphics
managed execution environment can make Direct3D Graphics is for device independent
guarantees about what the code is going to access to the 3D-graphic hardware and accel-
do. The enviroment can insert traps and ap- eration. If no hardware acceleration is sup-
propriate garbage collection hooks, exception ported, the software renderer will emulate the
handling, type safety, array bounds and index hardware. (?)
checking, etc. E.g, such a compiler makes sure Complicated 3D-figures and objects are
to lay out stack frames and everything just usually modeled with a 3D-software and then
right so that the garbage collector can run saved to file. The .x file format is an ex-
in the background on a separate thread, con- ample for such a file. (?),(?) Microsoft Di-
stantly walking the active call stack, finding rect3D can create objects from these files us-
all the roots, chasing down all the live ob- ing meshes. A mesh is an abstract data con-
jects. In addition because the IL has a notion tainer with the data for a complex model. It
of type safety the execution engine will main- contains resources such as textures and mate-
tain the guarantee of type safety eliminating rials, and attributes such as position data and
a whole class of programming mistakes that adjacency data. Meshes itselves are some-
often lead to security holes. what complicated, but accessing and using
”‘Contrast this to the unmanaged world: them with Direct3D makes it easier. In the
Unmanaged executable files are basically a following an example is shown how to load,
binary image, x86 code, loaded into mem- render, and unload a mesh. With this exam-
ory. The program counter gets put there and ple an overview will be given over the func-
that’s the last the OS knows. There are pro- tionality of Direct3D.
3. First of all, the mesh object has to be ini- Furthermore in the application defined On-
tialized. Also we need a device for the out- ResetDevice method it is possible to initialize
put. There are two device types in DirectX: an ExtendedMaterial object as an array that
a hardware device and a reference device. is used to capture the mesh file data to a Ma-
The hardware device is the primary device terial structure. In the method the device can
which supports hardware-accelerated raster- be adjusted, for e.g. turning on the z-buffer
ization as well as hardware vertex processing. and white ambient lighting. This function is
For this purpose the display adapter of the called when the device is initialized and in
computer has to support Direct3D. The hard- some different cases reseted.
ware device then implements all or part of the Now the mesh object has to be loaded.
transformations, lighting, and rasterization in As shown in the following code fragment
hardware. The application itself does not ac- as a part of the OnResetDevice method a
cess the hardware device directly - it calls Di- mesh is loaded that represents a texture-
rect3D functions and methods which access mapped 3D tiger from a tiger.x file. In this
the hardware through a hardware abstraction Mesh.FromFile method call, the SystemMem-
layer (HAL). If the hardware supports Di- ory constant of the MeshFlags enumeration
rect3D, these functions and methods are exe- indicates that the mesh is to be loaded into
cuted with best performance of the hardware. system RAM not typically accessible by the
Direct3D supports additional a device called device.
reference device. This reference device emu- mesh = Mesh.FromFile("tiger.x", MeshFlags.
lates all Direct3D functions and methods via SystemMemory, device, out extendedMaterials);
software without any hardware acceleration. After the mesh is loaded, a meshMateri-
Furthermore, if Direct3D functionalities are als Material object extendedMaterials has its
used which are not implemented in the hard- members filled with the Material structures
ware, the reference device will then emulate of the materials object that came from the
the corresponding part of the hardware de- mesh file. These materials could now be set
vice. inside the OnResetDevice method to a specific
To create a new Direct3D device, the fol- ambient color or could be set to a MeshTex-
lowing command has to be executed, e.g. in ture object loaded from a texture of a file. A
a Windows Form Class: texture object file could be loaded with the
device = new Device(Manager.Adapters.Default TextureLoader.FromFile method. For exam-
.Adapter, DeviceType.Hardware,this,CreateFlags. ple, it is possible to set for all extendedMa-
SoftwareVertexProcessing,new
PresentParameters()) terials of a mesh the ambient material color.
This could take place by an iteration over the
For creating a new device these parameters
length of the materials from the mesh. Af-
are needed:
terwards the texture had to be loaded. The
1. A graphics adapter to connect to the out- following code fragment (with i as the itera-
put device, e.g. to connect one monitor tion counter) shows this:
to the graphics card. meshMaterials[i].Ambient = meshMaterials[i].
Diffuse;
2. A parameter which decides whether a meshTextures[i] = TextureLoader.FromFile
hardware of software rendering is done. (device, extendedMaterials[i].
TextureFilename)
3. The class (e.g. the windows form) which Finally, after the mesh has been loaded and
connects Direct3D with the application. initialized, the next step is to render it. For
this purpose we have to call the private Ren-
4. Some flags for setting the behavior of the
der method. This method is called every time
rendering pipeline.
an object needs to be rendered. The function
5. Parameters for the presentation behav- is accountable for making the Mesh object
ior. looking as desired. Inside the render method,
4. the rendering pipeline can be adjusted. To does not depend on the existence of particu-
render the mesh itself, it is divided into sub- lar device objects (e.g. specific buttons). Ac-
sets, one for each material that was loaded. A tion mapping simplifies the input loop and
loop needs to be run for rendering each ma- therefore reduces the need for custom game
terial subset. This loop can for example be drivers and custom configuration user inter-
used to make the following operations on the faces in games. (?)
object: To capture the device input using Microsoft
DirectInput, it is necessary to know from
• Setting the material property which device the input has to be captured.
(And, of course, if it is currently attached to
• Draw the material subset with the the user’s computer). To do this, there is a
mesh.DrawSubset() method enumeration of DeviceInstance objects which
can be looped. This Enumeration serves the
With the commands device.EndScene() following purposes:
and device.Present() the end of the render-
ing pipeline is indicated and the object will • Reports what DirectInput devices are
get visible. available.
Now, it is realized to load, render and
• Supplies a globally unique identifier
present a mesh with a Direct3D device. If the
(GUID) for each DirectInput device.
graphic device supports Direct3D, the ben-
efits of hardware acceleration would be used. • Possibility to create a DeviceInstance ob-
For a deeper look at this example and its code ject for each DirectInput device as it is
there are more information in (?) enumerated. With this the type of de-
vice and its capabilities can be checked.
3.2 Direct Input
An example code fragment for this loop
With Microsoft DirectInput it is possible to would be
establish a direct communication between the foreach(DeviceInstance di in Manager.Devices)
hardware drivers of an input device. Nor- string name = di.InstanceName;
mally the communication would be provided
Capturing the device input itself with Di-
over a Windows message relay supported by
rectInput can be done in three parts. First
the Microsoft Win32 API. With DirectIn-
a device object that represents the input de-
put the application retrieves the data directly
vice needs to be created. After the creation of
from the device, even when the application is
the device object the configuration has to be
inactive. Furthermore, with DirectInput all
done. After the configuration the device state
kind of input devices with DirectInput drivers
can be checked within the application. There
are supported, as well as functionalities for
will be callback functions registered which are
Force Feedback. With Force Feedback it is
called after the corresponding action from the
allowed to send messages and properties to a
user (e.g. pressing a button.)
user’s DirectInput device to relay feedback in
An example for the configuration of a joy-
the form of physical force.
stick device could be:
DirectInput implements the technology of
foreach(DeviceObjectInstance doi in
action mapping. Action mapping applica- joystick.Objects)
tions can retrieve input data without knowing joystick.Properties.SetRange(
what kind of device is being used to generate ParameterHow.ById, doi.ObjectId,
new InputRange(-5000,5000));
it. DirectInput does not provide any special
support for keyboard devices or mouse navi- Furthermore, in the callback function Up-
gation. Action mapping provides a possibil- dateJoystick() which is registered for joystick
ity to establish a connection between input events, the state of the buttons could be re-
actions and input devices. This connection quested with this command:
5. byte[] buttons = joystick.CurrentJoystickState. by a dot and the operation name. For exam-
GetButtons; ple sound.Play() starts playing the sound or
As seen in the examples, DirectInput pro- sound.Format.* gives back additional sound
vides an easy way to access an input device. information like the number of channels or
The benefit of DirectInput devices is the di- samples per second.
rect communication between hardware and When a secondary buffer is created with
application, as long as the devices have corre- enabled flag for the control3D property, Di-
sponding hardware drivers. rectSound offers the possibility to set an al-
gorithm to simulate 3D spatial location of
3.3 Direct Sound a sound. By default, no head-related trans-
Microsoft DirectSound provides a system to fer function (HRTF) processing is performed,
capture sounds from input devices and play and the location of the sound relative to the
sounds through various playback devices. listener is indicated by panning and volume
The input devices are realized in several sec- only. To optimize the 3D effects for the user’s
ondary software or hardware sound buffers. system DirectSound also uses the speaker con-
Software buffers keep their data always in figuration. The SpeakerConfig property from
system memory and are mixed by the CPU. the sound device allows users to set up the
Hardware buffers can keep their data either sound system to the given speaker system by
in system memory or, if the application re- switching the flag to true, for example mono,
quests it and resources are available, in on- stereo, 5.1 or 7.1 surround sound.
board memory and are mixed by the sound One of the most important features of Di-
card processor. Each of them contains a static rectSound is the possibility to apply real-time
single sound or a dynamic stream of audio. audio effects to the sounds in playback. All
When sounds in secondary buffers are played, the effects are applied in hardware (that is,
DirectSound mixes them in the so called pri- implemented by the sound card driver) when-
mary buffer and sends them to the output ever possible, otherwise emulated via soft-
device. Only the available processing time ware. The latter causes an important drop
limits the number of secondary buffers that in the performance. There are 9 effects exist-
DirectSound can mix. The primary buffer is ing: Chorus, Compressor, Distortion, Echo,
always a hardware buffer on the soundcard, Flangler, Gargle, Interactive3DLevelReverb,
which means there is only one available and ParamEqualizer and WavesReverb. Each of
its memory size is limited. So the primary them has its own different settings ((?)). To
buffer holds the audio that the listener will implement an effect on a buffer first the effect
hear. Unlike the primary buffer there ex- flag in the buffer description has to be set to
ists several settings for the secondary sound true and then the SecondaryBuffer.SetEffects
buffer that can be changed. When creating method has to be used. This method takes
a new secondary buffer the most important an array of EffectDescription structures that
command line is: describe the effects. An effect can only be
sound = new SecondaryBuffer (filePath, applied if the sound is not played. An exam-
bufferDescription, SoundDevice) ple and a great summary of the Direct Sound
As shown each secondary buffer has a buffer functionalities gives The Ultimate Managed
description which contains one or more con- DirectSound 9 Tutorial 1 . It creates a small
trol properties (like pan, volume, frequency, application which demonstrates all Direct-
effects, 3D) from the BufferCaps structure Sound elements that have been described be-
(?). To allow the control of these properties fore. A big disadvantage of Microsoft Direct-
the corresponding flags just have to be en- Sound is that it plays only wave and Pulse
abled. According to those settings different Code Modulation (PCM) files. Waveform au-
operations can be executed by simply typing 1
http://www.codeproject.com/cs/media/Direct
in the name of the secondary buffer followed Sound9p1.asp
6. dio data consists of digital samples of the graphs have to be combined. For further in-
sound at a fixed sampling rate, whereas PCM formation on that topic see (?).
the representation of an analog signal by a se-
quence of numbers means. Managed Direct- 4 DirectX versus OpenGL
Sound does neither support compressed WAV OpenGL is an open standard, so everyone can
formats nor audio formats with more than two use it for free. The fact that it is a standard
channels. Therefore AudioVideoPlayback is for graphics cards makes it running on every
the better choice for playback other formats operating system (as long as the OS consid-
like mp3 for example. ers a graphic user interface). Compared to
that, DirectX is an API developed by Mi-
3.4 Audio Video Playback
crosoft and consists of several subsystems like
The AudioVideoPlayback application pro- shown in the previous chapters. So only the
gramming interface (API) provides like the DirectX graphic component can be compared
older DirectX version the playback and simple with OpenGL. Considering the DirectX sound
control of audio and video files. But Microsoft part, the analogue would be OpenAL, which
has highly simplified the usage. All function- is an open audio standard. As already men-
alities for the playback are packed into a sin- tioned, DirectX is a Microsoft product, so it
gle dll-file. Thus the integration of a video can only be found on Microsoft operating sys-
into an application became much easier, be- tems where it is preferred to OpenGL. Never-
cause the user only needs to refer to the Mi- theless Microsoft cannot ignore OpenGL, be-
crosoft.DirectX.AudioVideoPlayback names- cause it is an industrial standard. So the
pace. The command: graphics card manufaturers support their cus-
Video ourVideo = new Video("C:Example.avi") tomers with the latest OpenGL driver ver-
sions and makes OpenGL usable under Win-
creates an instance of the video class
dows.
and provides the possibility to control
Considering OpenGL and DirectX both
the playback. For instance the method
are quite similar and offer equal functionali-
ourVideo.Stop() stops the playback and
ties. Anyway there still exist some differences
ourVideo.Play() plays it. The size of the play-
which are illustrated in table 1 on the follow-
back window can be set by ourVideo.Size =
ing page.
new Size(480, 320). If the video file contains
audio, the Video.Audio property returns an 5 Conclusion
Audio object that can be used to change the
volume or the stereo balance for the audio, for With Managed DirectX there exists a struc-
example Video.Audio.Volume = 100. tured and easy to use low-level API. While
in C++ the developer took great pain to sim-
Audio ourAudio = new Audio("C:AudioFile.mp3")
plify and integrate unmangaged C++ classes,
The Audio object is similar to the Video with the .NET style and the design of names-
object, but it supports only properties that paces, classes and properties, programming
relate to audio, such as Volume and Balance. Managed DirectX is very comfortable for
That means the Audio class is primarily de- the developer. Compared to OpenGL, Di-
signed for very simple playback scenarios, or rectX has some very important advantages
for use with the Video class. Whenever a for game developers. With Managed DirectX,
greater control over the audio playback is the developers also write more productive and
needed, it is better to use Microsoft Direct- therefore more code in less time and produce
Sound to play audio files. safer code.
The managed DirectX AudioVideoPlay- After a short introduction in Managed Di-
back API doesn’t support video converting. rectSound, DirectInput, Direct3D and Au-
The only way to do this is using the old dioVideoPlayback APIs the reader should for
unmanaged C++ code, where several filter- himself recognize the obviously advantages of
7. Features OpenGL DirectX
object oriented no yes
operating system many only all Windows versions
useable drivers available for high end graphics cards nearly all graphics cards
driver quality mostly bad often better than OpenGL driver
usage university, research and development, CAD game industry
documentations, tutorials, samples many less than for OpenGL
version release every 5 years every 15 months
trademark of Silicon Graphics Inc. Microsoft
Table 1: The list compares the key features between OpenGL and DirectX
managed DirectX. With regard to the coming
Windows Vista where DirectX is an elemen-
tal component, DirectX will play a more im-
portant role even for application designers in
every part of future application development.