Graphics DebuggingOverviewGet to know the DirectX graphics debugging tools in Visual Studio. Learn how to capture a frame from a game, and then step through the individual graphics events to see how that frame was rendered. Explore the shader, and edit the C++ code to make changes to the game.

PrerequisitesFollow these steps to prepare the challenge.

Download the DirectX marble maze game sample by selecting to Help – Samples from the main menu in Visual Studio and searching for Marble Maze. Change the name to MarbleMaze, then click OK to download the sample project and open it in Visual Studio.

Right-click BasicPixelShader.hlsl in Solution Explorer and select Properties to open the properties window for that file.

Set Enable Debugging Information to Yes and click OK. This will allow us to debug the pixel shader later on.

We’ll also make one change to the Graphics Diagnostics options. Open the Options dialog by selecting Tools – Options from the main menu.

...

Navigate to the Graphics Diagnostics options, and select ‘for everything’ under ‘Collect call stacks during capture.’ This will make capture slower, but allows us to capture call stacks for all graphics events. Click OK to save your changes.

Build and run the project by selecting Debug – Start Debugging from the main menu (or press F5).

Return to Visual Studio and stop debugging.

The ChallengePart 1 – Adding Marble TrailThe first change we’ll make to the game is to add a trail to the marble, using small yellow dots to show the path that the marble followed. The goal is something like this:

But first let’s find out a little more about how the scene is rendered.Start the game again from Visual Studio, but this time using the Debug – Graphics – Start Diagnostics menu item (or just press Alt+F5). This will start the game under Graphics Diagnostics and allows us to capture graphics frames.

With the game in focus, press the Print Screen key in order to capture a frame, or click the Capture Frame button in Visual Studio. Then return to Visual Studio and stop debugging. You now have a diagsession file open in Visual Studio, which contains some frame timing graphs and your captured frame.

Either double-click on the image of the captured frame, or click on the frame number link to open the frame in the Visual Studio Graphics Analyzer.

In the Graphics Event List window, you can see all of the draw calls that were made in order to render this scene. Step through each of the draw calls to see how the scene was created. Expand the Render Maze section and find the DrawIndexed call that draws both the maze base as well as the ball’s shadow. Note: Your sequence of draw calls may differ slightly from the image below, depending on which part of the maze you were in when you captured the frame.

Right-click the DrawIndexed call and select Pipeline Stages.

This opens the Graphics Pipeline Stages window where you can see the graphics pipeline stages for the selected draw call.

Click on the PixelShader B(2) link to open the pixel shader code in the shader editor. Here we can experiment with changes to the shader by editing the hlsl code in the left half of the window. The modified code is automatically compiled in the background, and the compiler output is displayed in the right half of the window. This is also where you will find error messages if there is an error in your code.

Let’s experiment by changing the ambient light color. Change line 33 of BasicPixelShader.hlsl to: float3 ambientColor = float3(0.8, 0.0, 0.0);

Clicking the Apply button at the top left of the shader editor will apply the changes you made in your shader code to the current log file, and you’ll be able to view how the changes have impacted the scene immediately. Feel free to experiment with different color values.

Click Reset at the top left of the shader editor to undo the change (or leave it, if you prefer the new color).We’ll use code similar to the shadow code in order to draw the marble trail. Find the section in the pixel shader with the comment ‘Shadowing from ball.’ It calculates the amount of shadowing from the ball at the current pixel. This value is then used

when calculating the final pixel color. We’ll add similar code to the pixel shader to draw the marble trail.

Make the following highlighted changes to BasicPixelShader.hlsl:...

cbuffer ConstantBuffer : register(b0){ matrix model; matrix view; matrix projection; float4 marbleTrail[5]; float3 marblePosition; float marbleRadius; float lightStrength;};... // Shadowing from ball. if (input.worldPos.z > marblePosition.z) Kd = Kd * saturate(dist2D / (marbleRadius * 1.5));

// Trail from the ball float4 trail = float4(0.0f, 0.0f, 0.0f, 0.0f); if (input.worldPos.z > marblePosition.z && dist2D > marbleRadius) { for (int index = 0; index < 5; index++) { float2 vec2 = input.worldPos.xy - marbleTrail[index].xy; float distsqr2D = dot(vec2, vec2); if (distsqr2D < 3.0f) trail.xy = 0.5f / (6 - index); } }

// Diffuse reflection of light off ball....

// Final composite.float4 diffuseTexture = Texture.Sample(Sampler, input.tex);float3 color = diffuseTexture.rgb * ((ambientColor * Ka) + (lightColor * Kd));

return float4(color * lightStrength, diffuseTexture.a) + trail;...

Since we’ve made changes to the constant buffer format, we’ll first need to update some CPU code for our changes to work correctly. (Clicking Apply at this point will just render a completely black frame.)Changes made in the shader editor are only applied to the current capture log. Click Copy to… in order to save the changes back to the shader file in your project. In the Copy to… dialog, the default path has already been populated with the location of the shader file in the project, so just click Save to copy the change.

Now we’ll make the changes to the CPU code.In the Graphics Event List, expand the draw call that draws the maze floor and expand it until you see the PSSetConstantBuffers event. Right-click on the PSSetConstantBuffers event and select Event Call Stack.

This opens the Graphics Event Call Stack. Double-click on the Render call to navigate to the location in the code where the pixel shader constant buffer is set.

This is the code (line 464 in MarbleMazeMain.cpp).m_deviceResources->GetD3DDeviceContext()->PSSetConstantBuffers( 0, // starting at the first constant buffer slot 1, // set one constant buffer binding m_constantBuffer.GetAddressOf() // to use this buffer );Just above this section of code, you will find where the constant buffer is updated with data from m_mazeConstantBufferData. We will need to change the contents of m_mazeConstantBufferData to include the marble trail data.// Update the constant buffer with the new data.m_deviceResources->GetD3DDeviceContext()->UpdateSubresource( m_constantBuffer.Get(), 0, nullptr, &m_mazeConstantBufferData, 0, 0 );

Right click in the MarbleMazeMain.cpp file and select ‘Toggle Header/Code file’. This will open the MarbleMazeMain.h header file. Add marbleTrail to the ConstantBuffer structure.// Describes the constant buffer that draws the meshes.struct ConstantBuffer{ XMFLOAT4X4 model; XMFLOAT4X4 view; XMFLOAT4X4 projection;

XMFLOAT4 marbleTrail[5]; XMFLOAT3 marblePosition; float marbleRadius; float lightStrength;};

Go back to MarbleMazeMain.cpp, and add the following highlighted code at the end of the Update Constant Buffers region (line 1053).#pragma region Update Constant Buffers...m_marbleConstantBufferData.marbleRadius = m_physics.GetRadius();m_marbleConstantBufferData.lightStrength = m_lightStrength;

// Update the marble trail data in the constant bufferstatic UINT frameCounter = 0;UINT trailLength = ARRAYSIZE(m_mazeConstantBufferData.marbleTrail);frameCounter++;if (frameCounter % 15 == 0){

for (UINT index = 0; index < trailLength - 1; index++){

m_mazeConstantBufferData.marbleTrail[index] = m_mazeConstantBufferData.marbleTrail[index + 1];

}m_mazeConstantBufferData.marbleTrail[trailLength - 1].x = marblePosition.x;m_mazeConstantBufferData.marbleTrail[trailLength - 1].y = marblePosition.y;

}#pragma endregion

Build and run the game. Congratulations! You have now completed the first part of this walkthrough.

Feel free to play around and modify the marble trail. In order to add more complex code to the pixel shader, you may need to switch to a shader model that allows more shader instructions. You can do this by opening the Options dialog for the shader file and selecting a higher shader model. Keep in mind, switching to a higher shader model may limit the number of devices that your game will run on.Part 2 – Making the Marble TransparentBy now, you’ve probably gotten pretty good at playing Marble Maze. Let’s add a new challenge. We’ll make the ball transparent. Start by capturing a new frame (Alt+F5 to start Graphics Diagnostics, then Print Screen to capture a frame). This time we’ll use Pixel History to find the draw call that draws the marble. Click on the marble in the captured frame in the Render Target window. This opens the Graphics Pixel History window which lists all of the draw calls that

(potentially) contributed to the selected pixel. The one with the white square next to it is the one that drew the marble.

We’ll change the transparency of the marble by updating the blend factor and the blend state. You should still have the Graphics Event Call Stack window open from the previous section. If not, you can open it again using the toolbar button.

Make sure that the draw call that draws the marble is selected. You can do this by clicking on it in the Pixel History window. From the Graphics Event Call Stack, navigate to the code that draws the marble by double-clicking the MarbleMazeMain::Render call.

This takes you to the code that draws the marble (line 501 of MarbleMazeMain.cpp). Add the highlighted code just before this Render call.m_deviceResources->GetD3DDeviceContext()->PSSetConstantBuffers(

0, // starting at the first constant buffer slot1, // set one constant buffer bindingm_constantBuffer.GetAddressOf() // to use this buffer);

blendFactors[0] = blendFactors[1] = blendFactors[2] = 0.8f;m_deviceResources->GetD3DDeviceContext()->OMSetBlendState(m_blendState.Get(), blendFactors, 0xffffffff);

m_marbleMesh.Render(m_deviceResources->GetD3DDeviceContext(), 0, INVALID_SAMPLER_SLOT, INVALID_SAMPLER_SLOT);m_deviceResources->GetD3DDeviceContext()->EndEvent();

The last change we need to make is to modify the blend state to use the blend factor. In MarbleMazeMain.cpp, change the values of SrcBlend and DestBlend (line 271).// create the blend state.D3D11_BLEND_DESC blendDesc = { 0 };blendDesc.RenderTarget[0].BlendEnable = TRUE;blendDesc.RenderTarget[0].SrcBlend = D3D11_BLEND_INV_BLEND_FACTOR;blendDesc.RenderTarget[0].DestBlend = D3D11_BLEND_BLEND_FACTOR;blendDesc.RenderTarget[0].BlendOp = D3D11_BLEND_OP_ADD;blendDesc.RenderTarget[0].SrcBlendAlpha = D3D11_BLEND_ONE;blendDesc.RenderTarget[0].DestBlendAlpha = D3D11_BLEND_ZERO;blendDesc.RenderTarget[0].BlendOpAlpha = D3D11_BLEND_OP_ADD;blendDesc.RenderTarget[0].RenderTargetWriteMask = D3D11_COLOR_WRITE_ENABLE_ALL;

Build and run the modified game. The marble should now be transparent. You can make it completely invisible by setting the blend factors to 1.0f instead of 0.8f. Part 3 – Remove the Shadow (optional)In case the game is still too easy for you, let’s remove the shadow. At this point you should know how to do that, so this is left as an optional exercise (hint: remove some code from the pixel shader). Congratulations! You have now completed the walkthrough.Wrap UpCongratulations you have completed this challenge.

Want more? Visit www.microsoftvirtualacademy.com and check out our full collection of Quick Start Challenges.