Also, in an effort to try and get a better sense of our users and community, we’ve put together this quick SlimDX developer survey and would appreciate your time in filling it out if you use, have used, or are considering using SlimDX for anything.

Finally, we’ve received several queries through various channels about contributing to SlimDX, especially the upcoming version 2.0 redesign. If you are at all interested in participating in or simply observing the discussions about the redesign, you should join the slimdx-devel mailing list.

That topic is how we’re not going to use IDisposable any longer.

More specifically, we’re not going to use it as much. Almost every SlimDX 1 object implements IDisposable, because IDisposable is all about cleaning up unmanaged resources and SlimDX objects are, for the most part, exactly that. But the sort of resources IDisposable is geared towards are those with very explicit lifetimes: you create it, do your thing, and then Dispose() of it. C# using-blocks allow you to implement this exact pattern for locally-held objects quite efficiently.

Long-time readers will recall that our IDisposable wrappers around COM objects have caused us a lot of trouble in the past, largely because the interface’s contract does not really jive with COM’s reference counting. To account for this, we implemented an object table based loosely on the same principles that the .NET RCW uses — specifically, we tried to maintain exactly one COM reference to any object known to SlimDX so that we could do the correct thing when Dispose() was called. This eventually led us to an overly-complicated system burdened with multiple creation code paths and inconsistent ownership semantics.

Our solution is to, essentially, side-step the issue entirely and just expose the reference counting directly. All SlimDX 2 objects that are backed by actual COM interfaces implement IComObject, which provides the familiar-looking methods AddReference() and Release(). For the trivial scenarios where you just want quick, scoped access to a COM object, we’ll be providing a simple IDisposable utility wrapper you can use in conjunction with a using-block to automatically drop the reference count when appropriate.

While it first might seem like this change is a step backwards, we think that it’s an improvement in the long run: it obviates the need for the exceedingly complex object ownership rules that existed with SlimDX 1 (which, we suspect, most of our users were getting wrong). Plus, it makes the SlimDX ownership semantics match those of the already-familiar native API.

I particularly enjoyed this post. Back in 2007, when SlimDX was a young API, we had the luxury of having very few serious users. When we realized we’d screwed something up, we just changed it, and it didn’t matter how much that change would impact a client code. There were no clients.

But now, three years later, that’s no longer the case. We have quite a few users; SlimDX has been used in commercially released games and applications, and helps power internal content production tools used by professional studios like Zipper Interactive. We no longer have the luxury of implementing sweeping changes on a whim, no matter how correct they may be. We have practical realities to consider: providing sufficient advance warning and documentation. Developing upgrade paths. Transitioning deprecated versions of the API to “support mode” for an appropriate period of time.

I believe that breaking changes are for the best when they actually improve the overall health of the API. But they’re also pretty scary.

The primary motivation for organizing the library in this fashion was to eliminate the problems with building “Any CPU” applications using SlimDX.

Managed applications built in “Any CPU” mode are essentially asking the CLR to load them as processes most-appropriate to the host machine: if you’re running on the x64 architecture, you get a 64-bit process. On x86, you’d get a 32-bit process.

For native code, however, the target architecture needs to be decided at compile-time, which is why there are distinct 32-bit and 64-bit versions of the SlimDX assembly. Unfortunately, you cannot load a 32-bit DLL into a 64-bit process.

If you’re using the copies of SlimDX that our installer places in the GAC, you can avoid running afoul of this problem by editing your .csproj. If you’re a user who prefers to reference the SlimDX DLLs themselves, you are out of luck. You have to pick a specific version to reference, and you have to set the machine type of your project to match.

By using a two-part distribution, we can ship a public assembly configured for “Any CPU” use. This assembly can detect whether 32- or 64-bit code would be more appropriate and load the correct private implementation DLL into your process.

This approach also allows us to write more of SlimDX in C#, which is far more pleasant language to work with than C++/CLI, and has a much better toolchain.

It also lets us improve the health of the code we do need to write in C++/CLI. Because of a peculiarity in how templates (not generics) interact with managed types, the presence of a template type anywhere in a class hierarchy results in a complete lack of IntelliSense support for that class hierarchy… but there’s a lot of redundant boilerplate code in SlimDX, exactly the kind of code one would like to use templates to write just once. We had to compromise and use macros to provide that code for SlimDX 1.

However, with the split-assembly approach — along with with our adoption of interfaces — the classes “polluted” by templates exist entirely in the private assembly and are never exposed by their concrete types; the lack of IntelliSense becomes a non-issue.

There is one small downside, unfortunately. Since the implementation DLL is loaded manually, clients who reference and ship private copies of SlimDX (that is, anyone not using the GAC version) will need to add or link the SlimDX implementation DLLs (and PDBs) in their .csproj files in order to allow the build system to copy those files into the directory of the built application.

The first is the question of how one initially obtains an interface. SlimDX 1 uses the constructors of its concrete objects to enable users to obtain new instances. Thus, in SlimDX 1 you would obtain a texture instance by doing new Texture2D( device, … ). This constructor will invoke the native ID3D10Device::CreateTexture(). In SlimDX 2, we’ll present a model that mirrors the native interface more closely, with an IDevice interface that demands a CreateTexture method.

To handle bootstrapping — obtaining that first interface — we’ll expose so-called “API objects” that will represent each of the primary subsystems SlimDX exposes to native code (for example, there will be a Direct3D10Api object that will let you obtain the initial D3D10 device interface. These API objects will also be a convenient location to present many of the native free functions. SlimDX doesn’t expose all of these now, and the ones it does provide are often tucked away, seldom-seen static members of one class or another.

The other half of the problem is translating those interfaces back into concrete, usable objects when they are passed back to SlimDX for one reason or another.

We could simply downcast the interface to the concrete type, but that relies on the assumption that such a cast would always succeed — and that isn’t true in general. SlimDX has always supported interoperation with other DirectX-wrapping managed libraries, and to make the assumption that our interfaces were only ever implemented by our own library would work against that.

Fortunately, as a result of that interoperability feature, we’ve had to have all of our objects expose their IUnknown or similar native pointer (wrapped up in a System.IntPtr). Thus, we can rely on an accessor for that pointer being available from the interfaces, and we can use that to obtain the actual interface we’re interested in working with in the SlimDX code.

There aren’t many major changes in the DirectX SDK this time around– PIX has gained some improvements, including better support for dealing with D3D11, and XNAMath got a few bug fixes, but most other changes are relatively minor. However, the SlimDX SDK includes some interesting changes (a full summary can be found in our release notes).

Ownership and Disposal

We made some modifications to certain interfaces to help clarify the ownership/disposal semantics of those interfaces under typical usage scenarios. In particular, we changed the ownership rules for GetBackBuffer so that users must call Dispose on the returned object themselves, and we changed how surfaces are constructed from swap chains (using the static FromSwapChain method on the Surface interface). These changes were made to alleviate some issues caused by unclear ownership semantics, leading users to not know when it was appropriate to Dispose of an interface, and in some cases making it impossible to correctly clean up a resource.

New Subsystems

August’s SDK release included DirectWrite wrappers, but they were severely lacking. We’ve implemented significantly more of the DirectWrite interface for this month’s release, although by our estimate we’re still missing about half of the subsystem.

We’ve also added wrappers for the XAPO API.

Decreased Subsystem Interdependence

D3D11 shares a few interfaces (and constants) with D3D10, so in the previous SlimDX release one would need to reference both namespaces to effectively utilize D3D11 functionality in some cases (involving, for example, the ShaderBytecode class). For February, we’ve split those shared interfaces into 10 and 11 versions, so this should no longer be necessary.

Revamped Sample Framework

Finally, as I have discussed previously, we had plans to rewrite the sample framework and the associated sample set. There were many problems with the previous sample framework, mostly centering on its similarity to XNA (which caused many users to interpret it as a reusable “game” framework and try to use it for real applications). It isn’t our intention to be providing that kind of a framework in SlimDX, so the new sample framework is significantly more bare-bones. We have removed most of the old samples from the distribution, replacing them with more narrowly-focused samples illustrating some specific basic concepts that we receive a lot of questions about — specifically, dealing with losing the device and resizing the window in D3D9 (illustrated by the framework itself) and in setting up depth and alpha blend states in D3D10 (illustrated by the SimpleMesh10 sample).

Unfortunately we didn’t have the time to complete everything we would have liked to have done with the new sample framework for this release, but we’ll be continuing to add samples of increased complexity in future releases.

SlimBuffer is a very straightforward API for creating and manipulating native-memory buffers from managed code. While there exist ways to do this directly — via unsafe blocks (in some languages) or various methods of the System.Marshal class — those methods are usually inelegant, inefficient, or both. SlimBuffer is written in C++/CLI for maximum efficiency and does what it does in a very clean, expressive manner.

If you’ve used SlimDX‘s DataStream class, you already have a basic idea of what SlimBuffer’s MemoryBuffer class is like. Indeed, DataStream is the conceptual basis for much of MemoryBuffer, and the problems with DataStream provided the impetus to spin off the SlimBuffer project.

The big difference is that MemoryBuffer is not a subclass of System.IO.Stream. Our original decision to make DataStream a stream was a poor one. It forced certain conventions on us that, as development and usage of our API progressed, became restrictive. For example, the lack of distinct read and write positions causes users to have to remember to “rewind” many streams before handing them back to SlimDX. MemoryBuffer is beholden to no such interface restrictions — save for those of IDisposable, but that’s a given since unmanaged resources are involved.

MemoryBuffer also allows for allocator customization, similar to that offered by the standard C++ containers. As of now, there is a default allocator that uses new and delete, as well as a simple delegating allocator.

SlimDX 2.0 will be replacing DataStream with MemoryBuffer, but the class (and some of the interesting tidbits I have planned for it) can be extremely useful on its own, so we’ve created a dedicated project for it. This way users who aren’t using other aspects of SlimDX can still take advantage of what SlimBuffer provides.

In the future, our intention is to create a firm split between official and community samples. Only the former will be checked into source control. The community samples will be hosted on our website somewhere, and when warranted we will fold appropriate community samples into the official distribution, after appropriate modification. One of the things we want to ensure is that the official samples have a uniform style (to make them easy to follow and compare) and that they meet certain quality criteria.

The other thing we’re going to do is refactor the sample framework itself. The current framework feels like a “mini-XNA,” which has caused some users to adopt it as a more generalized “game” framework, which is problematic for us. We do not want to be in the business of writing — more importantly, of maintaining — anything resembling an engine. There are other projects out there that fit that bill; SlimDX is a lightweight wrapper, and we want to preserve its minimalist ideals even across aspects of the project that are not the core library itself.

The sample framework should be about making it easy for us to build samples. The native SDK uses a pretty robust sample framework, and we’ve seen that hamper it as an educational tool. When the sample is trying to demonstrate some concept or technique, it should demonstrate that in the language of the API itself. API calls should be used as often as is reasonable in order to demonstrate ‘the simplest thing that could work,’ which is usually what a user is looking at the sample code for.

Basically, we want a relative lack of abstraction. Users are just going to peel away the abstraction layers anyway, so we’d just be creating more work for them.

It’s still going to be a framework, though! We’re still going to wrap the creation of the primary window and the ‘game loop,’ and we’ll provide extensibility points allowing a sample to customize the main phases of application execution: pre-initialization configuration, initialization and resource load, logic update, render update, and shutdown/cleanup. Simplifying such boilerplate code, code that is not directly related to the primary tasks one would use SlimDX for, is perfectly acceptable.

Similarly, we’ll probably wrap mesh loading (especially since there is no built-in method for creating ID3DX10Mesh objects from a file, and we’d like to use the same source assets when possible for homogeneity) and similar ancillary operations.

UI is another interesting issue. The native sample framework supports a simple collection of UI controls for tweaking parameters for a sample. I’d rather not implement (and thus maintain) a similar system in SlimDX, but the alternative of using Windows Forms controls means that tweaking won’t be available in samples running in fullscreen mode, which is a deal-breaker. So we’ll support a small set of basic controls useful for tweaking parameter values in the new framework as well.

These framework changes probably won’t make it into the next release (if indeed the next release is this month, as we suspect), but you should see them in the release immediately following that at the latest… as well as some other interesting changes. And of course, you can always live on the bleeding edge and work from the head of our repository.

In other SlimDX news, Arcen Games, LLC recently released AI War: Fleet Command. I’ve posted about this on Twitter already, and SlimDX lead Promit Roy has beaten me to the punch on a blog post, but I’ll repeat it here for the benefit of other readers: AI War is the first game available for purchase that was built using SlimDX! This is very cool. Developer Chris Park has written about his experience evaluating rendering solutions for C# projects, explaining how he ultimately chose SlimDX… head over and give his blog a read, and when you’re done, be sure to check out the game itself!

Today we’ll discuss them.

SlimDX supports the ability to share — in a sense — the native objects of other APIs using System.IntPtr, an opaque managed representation of a pointer or handle. All SlimDX COM objects expose their native pointer as an IntPtr. They can also be constructed from IntPtrs.

With the old SlimDX design, we only ran into two serious issues with this process. The first was that since IntPtrs are entirely opaque, we’d more-or-less trust the user to construct the correct type and pass the correct pointer. Sure, we performed a QueryInterface(), but that may not have been the best idea in retrospect — there are known scenarios (for example, see here and here) where DirectX objects don’t behave the way you might expect a COM interface to behave — and so our code might have occasionally failed in situations it should not have.

The second issue was that we used these IntPtr constructors internally, occasionally in scenarios where it was impractical to know the proper type to construct. Remember the GetDevice example from last time? In Direct3D10, there’s a similar method for resource views (GetResource()) that is used to get a pointer to the resource that the view object is looking at. The method is a member of the ID3D10View base class, so naturally we placed it in the analagous SlimDX.Direct3D10.ResourceView class. The implementation would have looked something like:

Resource^ ResourceView::GetResource()
{
  ID3D10Resource* resource = 0;
  NativeComInterface->GetResource( &resource );
  return gcnew Resource( IntPtr( resource ) ); 
}

The problem with this approach is that it logically “slices” the object. This is similar to slicing in, say, C++ except that the underlying object is not physical destroyed, only the way you can interact with that object reference. In other words, even if the ID3D10Resource* returned from the native call pointed to a derived ID3D10Texture2D, it would be an error to downcast the managed Resource reference to a managed Texture2D reference, because we statically constructed a Resource, not a Texture2D.

A solution to this is a factory-type construction process — fortunately for us, most of the types involved here had base class methods that would indicate the actual runtime type of the object somehow — even though that would mean we’d have to push most implementation of the method lower in the class hierarchy. That was the solution we were considering, until the object table was brought up, which neatly solved the whole issue for us.

Almost.

You see, there’s one final caveat. The reason the object table eliminates the need for a factory is that it stores the native pointer as the key, and the actual runtime managed instance as the value. Thus, the aforementioned code snippet becomes a table lookup instead of a gcnew statement. The problem rears its ugly little head when you consider the possibility that the table lookup can fail to find the key. At first that might seem impossible (and thus not worth handling) because the view can’t be created with a resource, and given the existence of the object table, the only way the resource can cease to exist before the view is if the programmer intentionally disposed of it. This would be a programmer error, which is generally something we do not concern ourselves with handling gracefully (that is, we’d throw an exception indicating the programmer is a dim bulb, rather than try to bravely soldier on).

Unfortunately, since SlimDX can exchange native resources with other APIs via IntPtr, it’s possible to get into this sticky situation rather easily — simply construct a new ResourceView using an exposed IntPtr. SlimDX will correctly handle the ResourceView, incrementing the native reference count and placing an entry in the object table. But SlimDX won’t know about the original resource, so if you call GetResource() on the view, SlimDX will not find the Resource’s key in the table. What will happen, in that case, is that SlimDX will treat the object as a new one, increment the native reference count, and add an object table entry. This is unfortunate because the user now has to Dispose() of that resource, even though they didn’t explictly allocate it with new.

We’re currently considering this a pathological use case, and aren’t addressing the issue. Users doing that kind of advanced interop with SlimDX will simply need to be aware of the problem and the non-standard call to Dispose() they’ll need to make. I do believe it is a fixable issue, but the fix isn’t in the March release since it will not adversely affect the majority of our user base — you’ll have to wait for June, if we’re even able to remedy it all. In the interim, however, it’s important to be aware of the dangers that lurk in the shady corners of the API.