The GPU Usage tool puts a lot of data out there, so I wanted to make a bit of a guide for how to diagnose and investigate some common performance issues with DirectX applications.

Running Well

Before we get into looking at performance problems we need to know what our baseline would be for an application that is running well. For my sample program I’m using the MiniEngine provided by a team down the hall here at Microsoft. The cool thing about MiniEngine is that while it’s basically a full blown game engine it’s also small enough to have a pretty full grasp of and it’s easier to make interesting tweaks and experiment on the code.

After starting up the ModelViewer project that is included with MiniEngine I’ve used Alt-F2 to start up a diagnostic tools session on my project. Turning on GPU Usage and running for ten seconds or so collected a log like the below.

From this overview it’s pretty easy to see that this application is running just fine on my system. Frame rate is steady at 60 FPS and utilization of the GPU is hovering at about 50% or so. If we select a chunk of time from this log we can dig in closer about what good performance looks like.

Note that in Update 1 we changed GPU usage to show a view that breaks down the profiling information by process and thread as opposed to the less useful core view that we used at Visual Studio 2015 RTM. If you ever need to see all the processes on a system, just select “All” from the Process dropdown and it will show you all the processes on all the different cores.

One of the first things to look at in the picture above is the thin grey lines coming down across the various timeline lanes. Those are the V-sync events from your monitor. To check out your frame rate you can just look to see if you are getting a present event into each frame that is being displayed to the user. The presents are represented by a “P” marker in each lane (which you might not see unless you zoom in closer). You can also just type “Present” into the Filter box at the top of the timeline control. Doing that will filter the list to just Present events and you can just arrow down through the events list to see where all the Presents fall.

In our example above we are fitting in all of our CPU processing and all of our GPU processing into the 16.6 or so milliseconds that we have to create each frame. As such, each frame comes out in time for the v-sync and we get that buttery smooth 60fps that gamers are looking for.

CPU Bound

So what does this look like when things are not running well? After some code tweaks a new log has been collected where the overview looks like this.

Our frametime is now off the chart, our FPS is wiggling around under 30 or so, and our GPU utilization has actually dropped. What we have here are the classic symptoms of CPU bound issues. Here our CPU has so much work scheduled on it that it can’t send commands to the GPU in a timely fashion. The GPU is stuck waiting around for work while the CPU spins madly. This  imbalance is even more obvious if we zoom into the detail page.

In the GPU lane chunks of work are about the same size as in the running well scenario. But in the CPU lanes we now have one thread (which is issuing our render commands) that is totally booked on the CPU. The Present calls are getting spaced out of the v-syncs so we are dropping frames and our game is starting to look pretty choppy for players. Note that the couple of small blue ticks on the GPU 3D line are actually devenv.exe, the Visual Studio process, doing a bit of work on the GPU.

When we know that we are dealing with a CPU bound issue we need to look at how we are spending our time on the CPU.  Part of this could be profiling non-graphics related CPU work that the application is doing to reduce the time spent there. Or if using something like DirectX 12 there is a much better ability to break up rendering code across multiple threads with command lists to keep the CPU busy submitting work to the GPU.

One of the nice things about the integration of GPU usage with the other Visual Studio diagnostic tools is that you can run the different tools in concert with each other. Our GPU usage tool simply shows what threads and processes are active on the CPU, but nothing about what was actually going on in those sections of time. Going back to the diagnostics tools page (Alt-F2) I can select both GPU and CPU usage and run them both at the same time.

Now over the same period of time that I’m looking at GPU Usage details for I can also look at what was happening on the CPU. Looks like a massive amount of time was being spent in AI processing for one specific enemy type during my per-frame update stage.

GPU Bound

Pictured below is another run of MiniEngine where midway through the run I kicked up some of the settings. From the overview it’s clear to see where our performance dropped from 60 fps down into the 30 fps range and with this run we see a corresponding uptick in GPU utilization.

The performance hit can be seen easily in the overview, but what is actually causing this performance change? In a situation like the above it can be nice to open two different details sections, one from when the application was performing correctly and another from when it was not.

On the left we can see the chunks of GPU work fitting into each v-sync. Meanwhile on the right the GPU lane is totally full and the Present events are not hitting each v-sync interval. Helpful, but at this point we could get much of the same information from a simple FPS counter. To make this comparison more useful we can dig into the blocks of GPU Usage in the timeline or into the Events list to figure out where are time is being spent on the GPU more specifically. The DirectX events in the events list initially will only show up in a big flat list, or grouped by CommandList in DirectX12. It can be very tricky to navigate to what each call is doing in a big list like this, so to get the most out of GPU Usage it’s best to add some well-placed marker events into your code. When these events are hit on the GPU, GPU Usage will group them hierarchically in the UI and roll up the durations for the DirectX events that they contain as in the examples below. For DirectX11 look at the BeginEvent API and for DirectX12 look at the PIXSetMarker API. With the hierarchy you can drill down into the time spent in different areas of rendering code.

In the example above we are showing the amount of time spent in the Main Render section of MiniEngine rendering code. As we select events or groupings in the event list the timelines at the top will update to show the amount of time for that event, we can also see in the CPU lane when that event was called from the CPU, so you can see delays that happen from when the API is called on the CPU to when the GPU queue actually gets around to executing that code.

 By looking at the good and bad sections with annotated code can make it trivial to pick out performance issues caused by changes in code or assets.

If navigating the event list gets hard using the filter options and column sorting can help to tweak what you are seeing. Pictured below is all the instances of the “Decompress and downsample” event grouping sorted by GPU Duration as opposed to when they were executed.

 In further entries I'll be looking into a few other new features added in Updates 1 and 2 for the GPU Usage tool.

Launching

When the GPU usage tool is started up the initial launching is handled by the Visual Studio Diagnostics Hub framework. This allows us to share launching behavior with other Visual Studio tools like the CPU usage or Memory usage tools. In addition, many of these tools can be combined into one single performance run, so you can do a single run to collect data for both GPU usage and CPU usage of your application. This hub can be opened with the Alt-F2 key combination or via Analyze->Start Diagnostics Tools Without Debugging option.

The diagnostic hub supports a number of diagnostic tools and allows for a variety of different project types to be targeted. Each tool can control what projects it is viable for, and will only allow for it to be enabled for those projects. The GPU usage tool is actually language agnostic in function. DirectX information is captured only at the GPU level and could be triggered by any type of project at the top level. For example, while DirectX is a C++ thing it could also be accessed through a C# project via SharpDX or a Python project via DirectPython11. As such, GPU usage is available to any basic project type targeting Windows Store or Windows Desktop. As there do not currently exist any phones that support both DirectX and the advanced driver data that we need for the GPU usage the feature is disabled for phone targeting projects.

In addition to Visual Studio projects you can also collect GPU usage data on any loose .exe applications that you have sitting around. Just open the executable as a solution in Visual Studio and then start up a diagnostics session and you can target it with GPU usage. This way if you are using some type of engine or alternative development environment you can still collect data on it as long as you end up with an executable.

Next to the GPU usage checkbox you’ll also have a small options page that you can bring up. The only option currently in here is the option to either start collection up right as you launch the application or to start up collection manually at a later point. The issue here is that when collecting data you’ll be logging events for everything that’s happening on your GPU as well as a fair amount of CPU data, which adds up relatively quickly. In our testing we can easily handle minutes of collection on AAA games so there is some leeway here. But it’s not something that you can just leave on and running all the time. So if you have isolated your performance issue to just a specific part of your game or app, it’s best to set GPU usage to start manually, navigate close to where you want to collect performance data, and then start collection then. Smaller file size also helps with keeping analysis time faster when collection finishes up.

Collection

Like most of the diagnostic hub tools GPU usage collects and then analyses Windows ETW events to provide its data. Collecting the correct set of events can actually be a bit of an arcane process when trying to manually collect ETW data, so it’s nice that VS handles all of the collection and deployment steps here for you. If you are using a VS project that is deploying to a remote machine then the hub will automatically collect on that remote machine and then bring that file back to the visual studio box for analysis.

When collection start up you’ll see a screen like the following running in VS.

At this point all of the ETW events that are getting collected are getting placed into a .diagsession file for storage. We don’t do any analysis at this point, as that is too expensive and long of a process so it would interfere with both the collection of the events and with the performance of the running application. However we do look at a small set of ETW events as they pass through into the log to show the information in the charts that VS displays while collecting. The top two charts that we show look at Present commands from the targeted application and check the time between them to tell both FPS and FrameTime values for this application. On the charts we’ve added a combo box to select a guideline targeting either 60fps or 30fps to help tell when your application performance is not up to snuff. If you selected to start full profiling manually you will still see these charts while running, but underneath the covers the events will not be saved into the logs aside from the events needed to generate these charts. We did this so users would still have the charts available to help figure out when to turn on full profiling during their repros. For manual starts, when you click the link to start full profiling we’ll place a small mark into the timeline at the top of the charts, this gives you the indication of where in the log you started collecting full data at. Later on during analysis you can use this mark to know after what point you can start selecting chunks of data for deeper analysis.

Collection can be terminated via either the stop button above the charts or via the stop link on the page.

Analysis

When collection is stopped a few things will happen to get this log opened up in Visual Studio for analysis. First off you’ll have a stage where the diagnostics hub brings the log back to the Visual Studio machine (if you were collecting remotely), and where the file is prepped for analysis. Of note here, while this stage should usually be relatively quick, it can be much longer if you are in a remote collection scenario and have collected a large file, or if you are running multiple diagnostic tools at the same time. When running multiple tools at the same time the ETW log files are merged before analysis, and this can be a bit of a time hog.

After that first analysis stage finishes you’ll then see a set of progress bars that look like this. If you selected multiple diagnostic tools you’ll also see entries for them here as well.

At this stage the diagnostics hub is utilizing a series of infosource DLLs to process all of the event data that was collected. It’s not something that you’ll have to worry about, but infosource DLLs essentially just compartmentalize processing of ETW data. For all the different tools available they can each examine the stream of ETW events to create some type of data model that we’ll later use for analysis. In the GPU usage case, we’re examining both thread and process context switches as well as GPU events to create a full picture of basic CPU utilization along with a detailed picture of what the GPU is doing at any point. These can be some very complex calculations involved here, in particular with figuring out how to correctly match up timings between when a DirectX event was triggered on the CPU side and when it was actually run on the GPU. Luckily for you, we take care of all this here at this stage for you.

User Interface

At this point all the work of collection and analysis is done and the job now is to expose all this information in the easiest to understand and navigate way as possible. As this part is the bulk of actually using our tool, I’ll just be covering it at a quick overview level now, and then diving in deeper in later blog entries.

Above is the screen that you will see when analysis is first finished. It’s basically the same as information that you see when you were collecting on your running application. Consider this screen the index page in a book, it probably doesn’t have the information to solve your issue here, but it allows you to jump around in the data to find the section that does have that info. Also of note here is that if you selected multiple diagnostic tools to run with you will see other tabs at the bottom of the section here. Moving over to those tabs and you can see the information that was captured in them. For games that are suffering from slow CPU perf, turning on the CPU usage tool along with the GPU usage tool can be a powerful combination for getting both the CPU and the GPU better optimized.

From this main screen you can highlight a section of time by dragging to select it, then clicking the link on the lower part of the page will open up a details view of just that specific time slice. There will be a bit of a delay (based on file ETW density and amount of time selected) here as data is transferred to the new details page and the page is populated. One of the key limitations to understand here is that only three seconds or less can be selected in this view. This limitation is due to the GPU usage UI being designed around examining a detailed set of issues and not needing to scale out to look at multi second segments of time. However if you do want to make some comparisons between frames that are far apart in the log you can always open up as many instances of these details pages as you want at this point, so just open up a second details section the same way as the first and compare between the two.

The details page can be broken up into two main sections. On the top of the page is the timeline view. In this view, you will see a series of horizontal timelines with various blocks of color in them. Each timeline represents a single atomic resource that is could be consumed by a 3D game or application. For the CPU we show a lane for each CPU core, and for the GPU we show a lane for each engine. For those not familiar with the concept, GPUs can have multiple engines internally. While a game is running the 3D engine could be performing a DrawIndexed call overlapping the same time that the Copy engine is moving around some data with an UpdateSubResource call. However each CPU core or GPU engine can only be performing one task at one time, which is why they each get a unique lane entry in the timeline.

Regarding the colors, each process which has submitted any GPU work in the details time period selected gets its own unique color. Processes that just used CPU time are represented in the CPU Core lanes by a half-size black and white section. Up on the top of the timeline we have a filter box to select just one process at a time to focus on and which lists out all the various process / color combinations that can be seen in the chart. This per process information can be very important as the GPU resources can be in use by multiple processes at any one time, and it’s entirely possible that performance hitches in the game could actually be traced down to something like DWM.exe (the windows display process which uses DirectX) using some of the GPU resources that you hoped to have available.

At a basic level two of the most important things that this timeline can tell you are how your CPU and GPU resources are being utilized as well as how close / far you are from hitting your VSync performance goals. With regards to utilization, by looking at the CPU and GPU lanes you can get a quick idea as to if your game’s performance is CPU bound or GPU bound. If the GPU lane is relatively empty, with lots of spaces in it then your GPU is not being fully utilized and it is spending time waiting around for instructions to come from the CPU. If your GPU lane is packed full, and the CPU lanes are sparse, then the GPU is bogged down while the CPU sits and waits. Also on this chart you can see blue vertical lines that slice across all of the lanes. These lines represent the VSyncs of the monitor on your system. Also in the GPU line you can see some small text “P” icons, which indicate when a Present was triggered. Assuming a 60 FPS target and a 60Hz monitor you should see one “P” event in the GPU lane between each set of VSync lines. If a “P” comes after the lines, that means your rendering code missed its timing for that frame and your display is starting to lag.

Below the timeline is an event list. This list provides a text accompaniment to the visual timeline above. When you change selection in the event list the selection in the timeline will change, and visa-versa. The combobox and search filters at the top of the timeline control help to control the events that you’ll see in this list. So by combining those filters with the column sorting on the events list and you can answer some interesting questions. Like you could filter by “Draw” and sort by GPU Duration column in descending order to figure out the most expensive draw calls for a process in a time period.

A second feature of the event list is that in the default sorting mode it will place events into a hierarchy according to any DirectX event pairs detected in code. Having at least a small set of these markers in place is super important for getting the most out of the GPU usage tool. The issue here is that the data that we currently have does not allow for us to match up GPU events with a CPU callstack. As such when you see an expensive Draw call in a GPU lane you can’t directly tell which Draw call in your source code triggered it. Having your rendering code broken down by section allows you to attribute each DirectX call to a more specific section and to roll up performance data to a higher level, which is needed for anything but the most basic of applications.

That’s the basics of how the tool works. I’ll be digging in more with future blog posts, specifically around how to pick out common performance issues in the UI.

To get to know these new templates better I’m going to take a post to tour around the new templates to introduce the overall architecture, point out a few interesting areas, and note the points where we expect users to replace or expand on the existing template code.

Getting Started

These new DirectX templates are included with the Professional, Premium and Ultimate editions of Visual Studio 2013 as well as the Visual Studio Express for Windows edition. If you want to start for free the Express Edition for Windows on Windows 8.1 is the place to start.

The new templates can be found after selecting New Project in the menus under the Visual C++ node in the Windows Store section. In that section there are two DirectX templates, one labeled “DirectX App” and one label “DirectX App (XAML).” The DirectX App template interfaces directly with CoreWindow and is the best place to start if your application is expected to have DirectX content always be full screen and not use things like the Windows Store app bar or show any other controls aside from the DirectX content. The DirectX App (XAML) template is a bit more complex, it hosts the DirectX content in a SwapChainPanel which allows the DirectX content to be placed into XAML controls as part of a bigger UI. Even if you intend on having your DirectX content always be fullscreen the XAML template allows you to use stuff like the AppBar for applications settings. In general, the XAML template is similar to the basic CoreWindow template with some interesting added complexity, so I’ll be using it as the base for this blog post.

Before looking at the code it’s best to just go ahead and compile and run the application so that you can see what the resulting output is going to be. What you should get is a 3D rotating cube with a framerate counter in the lower right and a small “hello” message in the upper right. If you use your mouse you can click and drag back and forth over the cube to rotate it around.

As a side note, the counters in the upper left with the white text are XAML specific framerate counters that help to show the current speed that your XAML content is rendering at. They are not specifically related to this template and you can turn them off by looking for the line “DebugSettings->EnableFrameRateCounter = true” and setting it to false. Just make sure that you don’t get them confused with the framerate counter in the lower right, which is a part of the code of this template and is showing you the current rendering speed of your DirectX content.

Template Tour

Before digging in too deep into any one specific area it’s best to take a quick high level look at the architecture of a freshly created DirectX (XAML) project, named MyApp for this example. Please forgive the informality of the diagram below, as it’s intended as just a quick overview and not any type of rigorous UML diagram.

Fig 1 – Architecture Overview

There are a few more small parts of this template, but the picture above captures the six main pieces of concern. Part of the design of the templates is to help make the correct break points to create separation between the various application components. In particular, care has been taken to break the update and render application engine in MyAppMain from the Window Store specific input / output code in the DirectXPage. Also, the renderers are created to be both independent of each other as well as keeping low level rendering code out of the MyAppMain engine so that they can easily be replaced or upgraded without messing with the main engine code.

Part by Part

Keeping the above graph in mind the template parts can be dug into with some more detail, both in what they provide as well as how they relate to each other.

App (XAML)

The App class does little but provide an entry point for application launching as well as handling events for when Windows suspends or resumes the application. When the application is launched, the App class creates an instance of DirectXPage and assigns it to the content of the current window. From then on DirectXPage handles most of the interactions (aside from the aforementioned suspend and resume events) with the user and with Windows.

DirectXPage (XAML)

Before getting into the DirectXPage code, it’s best to first familiarize yourself with the concepts of swap chains if you have not already. There is an excellent intro to them here, of which the basic summary is that swap chains represent both the front buffer of pixels current being displayed to the user as well as one (or more) back buffers. To keep up a smooth appearance to the user DirectX draws to the back buffers and then is able to instantly swap them with the front buffers when they are done drawing.

The two main controls of interest in the XAML file for the DirectXPage class are the SwapChainPanel and the AppBar class. If you have programmed for the Windows Store before the AppBar will be familiar, it’s a quick and easy place to place extra control and configuration buttons that you want to be hidden out of the way most of the time. The SwapChainPanel is a new control for Windows 8.1. Previously in Windows 8 the control to use for DirectX / XAML interop was the SwapChainBackgroundPanel. This control allowed for interop, but had a multitude of restrictions on how you could use it with XAML. For some examples of these limitations: you had to place it as the root XAML element, there could only be one SwapChain per window, and projection and transformation APIs would have no effect on its rendering. While SwapChainBackgroundPanel is still available to use it’s basically a Windows 8 legacy control at this point, the SwapChainPanel is far more flexible with its ability to be composed anywhere in to XAML layout, be resized and transformed, and to have multiple SwapChainPanels on the same page.

The SwapChainPanel provides an XAML target for DirectX swap chains so we need to tie that control together with the DirectX device that will actually draw our 3D content into that SwapChainPanel. The DeviceResources class, which I’ll detail later, is the class that sets up and manages the DirectX device, so in the constructor of the DirectXPage the DeviceResources class is created and the SwapChainPanel is set as its output target. As the final step of construction DirectXPage creates our MyAppMain (consider this our XAML independent game / app engine class) and passes in the DeviceResources class that we created.

// At this point we have access to the device. 
// We can create the device-dependent resources.
m_deviceResources = std::make_shared<DX::DeviceResources>();
m_deviceResources->SetSwapChainPanel(swapChainPanel);
…
m_main = std::unique_ptr<MyAppMain>(new MyAppMain(m_deviceResources));
m_main->StartRenderLoop();

After initialization the DirectXPage stays around looking for two main things: XAML composition changes and independent input. XAML composition changes are things like DPI changing, SwapChainPanel size changing, and orientation changes. When these events come in the DirectXPage updates the DeviceResources so that the DirectX device and device context can change for the new output parameters and also notifies the MyAppMain class so that the engine and any associated renders can also update or load new size dependent resources.

Independent input is a new concept that goes along with the SwapChainPanel and SwapChainBackgroundPanel controls. When you use independent input events come in and are processed on a background thread, this allows the engine to decouple from having input come in at the framerate that the XAML controls are running at. This rate can be different from your DX content in the SwapChainPanel, so your game is going to feel slow and laggy if your input is updating at 15fps along with XAML and your game is actually running at 60fps. In the code section below you can see the independent input source getting set up to run in a background thread and hooking up to a few pointer events which allow you to drag and rotate the cube back and forth. For another solid sample that uses independent input the Windows SDK provides an inking sample that uses independent input to maintain smooth performance while capturing ink stroke gestures on the screen.

// Register our SwapChainPanel to get independent input pointer events
auto workItemHandler = ref new WorkItemHandler([this] (IAsyncAction ^)
{
	// The CoreIndependentInputSource will raise pointer events for the specified device types on whichever thread it's created on.
	m_coreInput = swapChainPanel->CreateCoreIndependentInputSource(
		Windows::UI::Core::CoreInputDeviceTypes::Mouse |
		Windows::UI::Core::CoreInputDeviceTypes::Touch |
		Windows::UI::Core::CoreInputDeviceTypes::Pen
		);

	// Register for pointer events, which will be raised on the background thread.
	m_coreInput->PointerPressed += ref new TypedEventHandler<Object^, PointerEventArgs^>(this, &DirectXPage::OnPointerPressed);
	m_coreInput->PointerMoved += ref new TypedEventHandler<Object^, PointerEventArgs^>(this, &DirectXPage::OnPointerMoved);
	m_coreInput->PointerReleased += ref new TypedEventHandler<Object^, PointerEventArgs^>(this, &DirectXPage::OnPointerReleased);

	// Begin processing input messages as they're delivered.
	m_coreInput->Dispatcher->ProcessEvents(CoreProcessEventsOption::ProcessUntilQuit);
});

// Run task on a dedicated high priority background thread.
m_inputLoopWorker = ThreadPool::RunAsync(workItemHandler, WorkItemPriority::High, WorkItemOptions::TimeSliced);

MyAppMain

MyAppMain is where we encounter the standard game development update render loop that is the heart of most games. As timing is of the upmost importance in real time graphics applications our DirectX templates contain a StepTimer class (covered in the next section) which is used to control rendering loop timing. Like with our independent input events the rendering loop will be run on a background thread. Keeping it on a background thread prevents the possibly expensive update and rendering functions from dragging down our UI responsiveness if they start to fall behind.

// Create a task that will be run on a background thread.
auto workItemHandler = ref new WorkItemHandler([this](IAsyncAction ^ action)
{
	// Calculate the updated frame and render once per vertical blanking interval.
	while (action->Status == AsyncStatus::Started)
	{
		critical_section::scoped_lock lock(m_criticalSection);
		Update();
		if (Render())
		{
			m_deviceResources->Present();
		}
	}
});

// Run task on a dedicated high priority background thread.
m_renderLoopWorker = ThreadPool::RunAsync(workItemHandler, WorkItemPriority::High, WorkItemOptions::TimeSliced);

The work of the update function is quite simple. It first processes any per-frame input data that needs to be processed and then allows each renderer to perform their per-frame updates. The processing input step here is due to the independent input events coming in untethered from the visual framerate from the DirectX page. These event could be coming in much faster than the framerate, so instead of directly passing them to the renderers and forcing them to update much faster than we need to we store the state results of the input events in the engine, then we pass in that current engine state to the renderers to perform their per-frame updates.

// Updates the application state once per frame.
void MyAppMain::Update() 
{
	ProcessInput();

	// Update scene objects.
	m_timer.Tick([&]()
	{
		// TODO: Replace this with your app's content update functions.
		m_sceneRenderer->Update(m_timer);
		m_fpsTextRenderer->Update(m_timer);
	});
}

The Render function act similarly, only in this case it first gets the device context from the DeviceResources class, clears and sets the viewport, and then asks the renderers to perform their render functions.

// Renders the current frame according to the current application state.
// Returns true if the frame was rendered and is ready to be displayed.
bool MyAppMain::Render() 
{
	// Don't try to render anything before the first Update.
	if (m_timer.GetFrameCount() == 0)
	{
		return false;
	}

	auto context = m_deviceResources->GetD3DDeviceContext();

	// Reset the viewport to target the whole screen.
	auto viewport = m_deviceResources->GetScreenViewport();
	context->RSSetViewports(1, &viewport);

	// Reset render targets to the screen.
	ID3D11RenderTargetView *const targets[1] = { m_deviceResources->GetBackBufferRenderTargetView() };
	context->OMSetRenderTargets(1, targets, m_deviceResources->GetDepthStencilView());

	// Clear the back buffer and depth stencil view.
	context->ClearRenderTargetView(m_deviceResources->GetBackBufferRenderTargetView(), DirectX::Colors::CornflowerBlue);
	context->ClearDepthStencilView(m_deviceResources->GetDepthStencilView(), D3D11_CLEAR_DEPTH | D3D11_CLEAR_STENCIL, 1.0f, 0);

	// Render the scene objects.
	// TODO: Replace this with your app's content rendering functions.
	m_sceneRenderer->Render();
	m_fpsTextRenderer->Render();

	return true;
}

StepTimer

The StepTimer was not explicitly called out in the architecture diagram as it’s a smaller helper class, but as timing is the heart of any game loop it’s a very important component to understand. The timer provided with the templates was designed to cover a broad set of common features that are desired in a timer while still being concise and easy to understand. Before covering more of the StepTimer class it’s best to look back up the page just a little bit to the MyAppMain::Update function, where you can see the m_Timer.Tick function being called (this is the main point of usage of the StepTimer class).

The StepTimer is created during initialization of the MyAppMain class. By default it is created with a variable timestep mode. In this mode in the Tick function the StepTimer class will calculate the new amount of ticks elapsed since the last call to Tick and then without any checks directly call into the update function and then exit back out of Tick. Give the usage of the Tick function in MyAppMain::Update we can see that in this mode the logic updating of the Tick function is tied one to one with the Render() function of MyAppMain which is called after it. So in variable timestep mode the update and render functions will always be called as fast as possible and will always be called one after the other, with one update function called each time before each render function. Both of these will be called as fast as possible, with the framerate limited only by speed of update logic and speed of rendering.

At the initializing point of the StepTimer there is a bit of commented out code that illustrates the use of the fixed step mode of the timer.

// TODO: Change the timer settings if you want something other than the default variable timestep mode.
// e.g. for 60 FPS fixed timestep update logic, call:
/*
m_timer.SetFixedTimeStep(true);
m_timer.SetTargetElapsedSeconds(1.0 / 60);
*/

 This fixed step mode of the timer changes how the Tick function handles updates. If the above code is uncommented the calling of the update action from the Tick function is guaranteed a specific amount of times (and only that amount) per time period.

if (m_isFixedTimeStep)
{
	<extra code snipped>
m_leftOverTicks += timeDelta;

while (m_leftOverTicks >= m_targetElapsedTicks)
{
m_elapsedTicks = m_targetElapsedTicks;
m_totalTicks += m_targetElapsedTicks;
m_leftOverTicks -= m_targetElapsedTicks;
m_frameCount++;

update();
}
}

 In the above code if our time elapsed since the last call to update is not yet past our target amount we’ll add in the delta amount and exit out of the function without calling the update function. And if the amount of time is past the target amount we’ll call the update function as many times as needed based on the amount of time we are over the target interval. As such, with fixed time step we may call Render before running the update function or we might call the update function several times consecutively to catch up (if we are running slower than the target framerate) before calling the Render function once. It’s common for games to use either fixed or variable time step bases on other considerations on the engine such as how animations are handled or if the game is highly timing sensitive so both modes have been provided with the StepTimer.

DeviceResources

Before examining the DeviceResources class it’s best to be familiar with the DirectX 11 concepts of both devices and device contexts (more on creation of both here). The short answer if you don’t want to read up on those links is that a DirectX device represents the resources and capabilities tied to a display adapter while the device context controls the pipeline of how that device is used including stuff like setting data into buffers and loading shaders. Having at least a basic understanding of this is important as the DeviceResources class does much of the work for the template in managing and altering the device and device context.

As seen by the initial diagram, the DeviceResources class is used pervasively throughout the template. The DirectXPage, MyAppMain, and individual renderers all keep references to this class. What it contains is much of the heavy lifting required to create DirectX content to correctly output into the SwapChainPanel as well as providing all the DirectX setup needed for the renderers to do their work. Our hope with this class is that it will provide template users with a very good starting place for most types of games and applications and that by default they won’t have to edit it much for their specific applications. Still it’s always best to have a solid idea of what is going on under the covers in this class.

When created by the DirectXPage the DeviceResources class creates all the device independent resources as well as creating the initial device resources. The device independent resources are resources that will be held by DeviceResources for the life of the program and will not need to be recreated. On the other hand, device resource are resources that are tied to the DirectX device, so if the device is lost or needs to be recreated we have to recreate these resources. And finally, after construction of the DeviceResources class the DirectXPage passes in the target SwapChainPanel. At this point DeviceResources grabs window specific properties (orientation, dpi, logicalsize) and creates window size dependent resources. To keep these three classes of resources separate here is a table showing some examples of each type.

While all of the various resources are all worth knowing more about the important part here is there are the three categories of device independent, device, and window size dependent resources. The main function of the device resources class is to keep track of all these resources and to re-create them when needed. For an example, when the orientation of your device is changed the DirectXPage class gets an orientation changed event and passes it to the following function in DeviceResources.

// This method is called in the event handler for the OrientationChanged event.
void DX::DeviceResources::SetCurrentOrientation(DisplayOrientations currentOrientation)
{
	if (m_currentOrientation != currentOrientation)
	{
		m_currentOrientation = currentOrientation;
		CreateWindowSizeDependentResources();
	}
}

 The orientation state is updated and the window size dependent resources are recreated.

Renderers

The key point of the DirectX template renderers is their independence from each other and from the high level XAML and app code. The renderers main interactions are with the Update and Render functions called from the MyAppMain class. On update the renderers need to change any state for the current frame step. And on render they grab the D3DDeviceContext from the DeviceResources and draw all the text or primitives that they are responsible for. Because the DeviceResources class has taken care of all the swap chain sizing, orientation, dpi settings and such the renderers are free to be much smaller and cleaner and focused just on drawing their specific scene.

Just like DeviceResources, renderers can have device and window size dependent resources contained in them. In the Sample3DSceneRenderer::CreateDeviceDependentResources function the pixel and vertex shaders are loaded in and the mesh of the cube that we are going to draw is created. This function also provides a nice example of C++ Windows Store task continuation if you are interested in that.

void Sample3DSceneRenderer::CreateDeviceDependentResources()
{
	// Load shaders asynchronously.
	auto loadVSTask = DX::ReadDataAsync(L"SampleVertexShader.cso");
	auto loadPSTask = DX::ReadDataAsync(L"SamplePixelShader.cso");

	// After the vertex shader file is loaded, create the shader and input layout.
	auto createVSTask = loadVSTask.then([this](const std::vector<byte>& fileData) {
		DX::ThrowIfFailed(
			m_deviceResources->GetD3DDevice()->CreateVertexShader(
				&fileData[0],
				fileData.size(),
				nullptr,
				&m_vertexShader
				)
			);

		static const D3D11_INPUT_ELEMENT_DESC vertexDesc [] =
		{
			{ "POSITION", 0, DXGI_FORMAT_R32G32B32_FLOAT, 0, 0, D3D11_INPUT_PER_VERTEX_DATA, 0 },
			{ "COLOR", 0, DXGI_FORMAT_R32G32B32_FLOAT, 0, 12, D3D11_INPUT_PER_VERTEX_DATA, 0 },
		};

		DX::ThrowIfFailed(
			m_deviceResources->GetD3DDevice()->CreateInputLayout(
				vertexDesc,
				ARRAYSIZE(vertexDesc),
				&fileData[0],
				fileData.size(),
				&m_inputLayout
				)
			);
	});
…<more loading code snipped here>
}

 As this post is mainly concerned with the structure and use of the templates I’m not going to cover all of the drawing code included in these template files, as that topic is more of a general DirectX programming topic. But if you want to poke around in in the Sample3DSceneRenderer you can see the data being loaded in CreateDeviceDependentResources, the projection and view matrices being set up in CreateWindowSizeDependentResources, the model matrix being set via the Update function, and finally the vertex and index buffers being set and the primatives being drawn in the Render function. All of which makes perfect sense in the way that we’ve constructed these templates as the shader files and mesh data never needs to be updated, the view perspective needs to be updated when the window size or orientation changes, model matrix rotates the cube and thus is needed in when the engine updates, and the Render data needs to update once per frame drawn.

Where to modify these templates?

After getting a grip on the overall layout of the templates and the important classes within the next step is to start to expand them out for your particular game or application. If you search the solution for “todo:” you’ll get seven results in the MyAppMain class where template consumers are expected to start plugging in their initialization, state, input handling, and connections to custom renderers. Then by replacing out the template renderers with your own custom renders you can start to expand out on your own application with a very solid base already provided by the template update / render loop and the DeviceResources class’s handling of the XAML / DirectX interop connection. 

IntelliTrace Web Requests

Moving forward the Visual Studio team is committed to bringing new updates to Visual Studio on a much faster cadence than the usual release and service pack cycle. As part of our run up to this commitment we’ve used the Visual Studio 11 Beta period to add some new features to IntelliTrace that were not ready for the Beta release date. By downloading an update to Visual Studio 11 Beta, which should be available via an update from the VS UI this week, some powerful new IntelliTrace functionality will be added for helping to diagnose issues in production IIS web applications. This new functionality helps to capture the start and end of each web request hitting the server, collects and records information from each request, and shows which IntelliTrace events are correlated with the execution of each web request.

Collecting web request information on a server

Visual Studio 11 Beta already includes the means by which you can collect IntelliTrace web request information on a production server. However, there is no way to actually view the collected web request information with a non-updated VS11 Beta, the collected files can be opened, but no web request UI controls will be available to the user. The Beta update adds the new web requests UI and opens up the full potential of these IIS server collected IntelliTrace files.

This article is focused on how to use the new web request UI to analyze data, so the details of collecting the IntelliTrace logs are best left to our in-depth MSDN article on the topic. Note that this collection work makes use of our new standalone collection bits and PowerShell scripts, so that files can be quickly and easily collected through PowerShell while just having to copy over a few files to the server (no installation required).

Analyzing web request information

Opening an IntelliTrace file collected with web request information in Visual Studio 11 Ultimate after installing the Beta update will add a new web requests section to the IntelliTrace summary page. Expanding this web requests section will show a table like the one below. The example file below was collected on a Team Foundation Server instance that we use locally for source control.

This table is a listing of all the web requests that IntelliTrace recorded while collecting data on the server. For each request to the server we capture some basic information on the request: Method, Target URL, Time Taken, Status, Session Id, Client IP, User Agent, Start Time and End Time. Most of these categories are self-explanatory with the exception of Session Id. This value for Session Id is not related to ASP.net’s concepts of SessionID but is simply an increasing integer that IntelliTrace keeps internally and increments whenever a new session is started. So by looking at just web requests that have the same Session Id value in this view you will be seeing all web request for a specific user session, but you cannot match this value against the SessionID value from ASP.net Session State. By default the web request are sorted in the order in which they hit the server.

The search grid at the top of this control provides both plain text search, which searches all but the time columns, and some basic column filtering syntax. This column filtering is done by specifying the column name with no spaces, a colon, and then a filter value. You can do one of these filters per filterable column; the columns which are filterable are listed in the tooltip of the searchbox.

As an example, the following query will pull all of the web requests that returned a 304 and that contain the text “App_Themes.”

Status:304 App_Themes

Or here are all of the web requests that hit the server for the second recorded user session:

Closer analysis on a web request

From the summary page listing you can dig deeper into a web request by double clicking it in the list or selecting it and clicking the “Request Details” button at the bottom of the list. A new window will be opened as a preview tab, if you are not familiar with them yet (as they are new in VS11) preview tabs will continue to open in the same document tab unless you promote them to the main document well. As you open details on more web requests they will close the previously opened details page unless it was promoted from out of the preview tab. Currently if you have a very large file full of web requests opening this details page can take a little bit of time, this performance is being worked on, but expect a bit of a wait for now.

The top of the request details page has the same basic request information that were surfaced on the main summary page. Below that listing is list of IntelliTrace events that looks similar to the list that you would see while live debugging with IntelliTrace or actively debugging a recorded IntelliTrace log. This list shows all of the IntelliTrace events that were recorded while executing this specific web request on the server. They are listed in the order that they occurred with the first event starting at the top of the list.

In the example events list above you can see a bunch of ADO.net events pulling data from a database as well as a couple of possibly problematic exceptions being thrown (see below).

By double clicking on any of these events the debugger will start and begin debugging the IntelliTrace log at that specific event. If you have collected your log with method calls information, using the collection_plan.ASP.NET.trace.xml or by customizing your collection plan, you can then step around in code from that location and examine method parameters and return values. One important caveat to note here is that being able to view source when debugging a recorded log requires that the symbol (PDB) files for the version of your application that was running on the IIS server need to be available in the Visual Studio symbol path. Without these symbols, resolving to source locations is impossible and only the “symbols not found” window will be shown when debugging.

How it all works

After this quick little introduction to this new feature I’m next going to be digging in a bit more into how the internals of this web request feature works from the IntelliTrace side, so keep an eye out here for another blog entry soon on that topic.

Ian Huff

http://blogs.msdn.com/b/jasonz/archive/2010/12/07/announcing-visual-studio-2010-service-pack-1-beta.aspx

Overall the article writing process was fun, but not something that I’d want to do too often. All the editing and whatnot was just a little too time consuming for my tastes. I like just getting stuff done and getting it out there.

[ian]

For this blog I plan on keeping the focus on IntelliTrace (and that is what I mainly expect to be working on) but expect to see more info on the Profiler, Debugger, Static Analysis and Architecture tools scattered in here as well.

Currently I’m just finishing up on a project to improve our internal regression prevention system. Getting some experience with a Silverlight + RIA Services multitier app was fun, but the confusion that comes with trying to bring together a disparate team to accomplish a task and then disband was a little crazy at times. With that project wrapping up I’ll be back on the main product line and able to add some more IntelliTrace blog entries coming up soon.

[ian]

Currently our team is deep in the throes of MQ (Milestone Quality, essentially a chance to catch up on improving our own tooling, automation and build scenarios after a big release) so I’ve been a little short on time to post new blog articles. However I did have a few quick links to share out. First up is Chris Koenig’s how-to video for using IntelliTrace in Visual Studio 2010. This video provides a solid introduction to the basics of IntelliTrace debugging.

http://chriskoenig.net/index.php/2010/05/10/how-do-i-using-intellitrace-in-visual-studio-2010/

I also wanted to link in some of the excellent walkthroughs created by our MSDN team.

Debugging a card game in IntelliTrace Part 1

Debugging a card game in IntelliTrace Part 2

Debugging a Web Site with IntelliTrace Part 1

Debugging a Web Site with IntelliTrace Part 2

~Ian Huff

In Visual Studio 2010 we’ve done some major updating to the user interface, bringing most parts of the shell over into the WPF world from earlier technologies. This update was pretty painful for us internal teams that integrate heavily with the shell, but the end result was worth it as we’re able to do some really cool little UI things much easier than it would have been trying to do them with the old shell. Pinnable datatips are one of those nice little new additions that the shiny new shell affords us.

To check out pinnable datatips all you have to do is debug into a project, stop at a break point and mouse over a variable to bring up the datatip. When the datatip pops up you’ll notice a new little pin icon that appears at the end of each item’s row.

In the example above I want to examine the AvgValue property on each result as I move though the iteration loop. So after clicking the pin button next to the AvgValue property I’ll be left with a little control showing just that properly as shown below.

Note that the three little controls to the right of the pinnable datatip will only appear when I mouse over the data tip. If I’m not over it I’ll just see the tip and the value. This tip is now pinned into place over that specific line of source code and will stay over that line so you’ll only see it if that specific line is on screen. If I run to the next iteration of the loop and the value changes the text will be in red to draw my attention to the change (just like in the watch window).

The top button of the right side hover buttons will delete the pinnable datatip, just as one would hopefully expect from an icon with a big X on it. The second button will unpin that datatip from the specific source line and allow you to drag it around to where ever you want on the screen. When the tip is unpinned it will then stay in that location on screen as opposed to scrolling off with the source line (see pictures below). This mode can be seen more as a post it note stuck to a screen (hence the yellowish background color in this mode), as opposed to the pinned version, which is more of an annotation on a specific source line. If you want to repin the datatip just click the pin button again and the datatip will latch on to the closest source line (note, not the original source line that it was pinned to). This lets you group and position all your pinnable datatips either relative to the screen or relative to any handy source line. Note that in the picture below you can see the outline box of where I'm dragging the tip to, with the mouse cursor hidden by PrintScreen it's a little hard to tell that I'm dragging the tip to a new location.

The final button expands the post-it note concept further by allowing you to type in a little comment to associate with that specific pinned data tip. This note can be anything that you want to help with debugging. I know that in particularly hairy debugging sessions in previous releases this feature would have saved me lots of time just by helping to organize exactly why I was watching a specific variable at some point. In general I would take debugging notes like that on a sheet of paper, but now that I have the functionality to keep them in the debugger right where I’m working I find that I’m increasingly using notes on pinnable datatips as opposed to pencil and paper.

It’s very much one of my favorite new debugger features in VS 2010 and something that I think all VS developers could get a lot of use out of.

As a final note I realized that I was mostly working with properties above. Pinnable datatips can also pin types. These pinned types can be expanded in the same way that you would expand and examine a normal datatip. In the example below I’m watching a few properties and I’ve got the result object pinned to examine some properties off of.

~Ian Huff

While we are working on getting this scenario fixed for a future date I would like to mention that there is actually is a way to collect IntelliTrace data on 64-bit applications with just what ships with VS 2010 Ultimate. Some time ago I posted a blog article in which I talked about how to collect IntelliTrace data with Microsoft Test Manager, the new standalone test data collection application that ships with VS 2010 Ultimate. Because the launch patterns for our MTM IntelliTrace data collector and for F5 launch from Visual Studio are different we were actually able to get 64-bit working in the MTM scenario. Just follow the steps in my listed blog article and you will be able to capture IntelliTrace data for 64-bit applications, no special tweaks or changes to the workflow are needed from 32-bit applications in MTM.

It’s not the best workaround, especially if you don’t regularly use MTM already, but if you want to capture IntelliTrace data on 64-bit applications it’s currently the only option available.