What’s New in the July 2014 Xbox One XDK

The July 2014 release of the Xbox One XDK from Microsoft contains the following new features, tools, and documentation. For features that shipped in a previous release of the Xbox One XDK, see the What’s New document for that release, available from Features Introduced in Previous Releases.

Sections:

• Release Notes and Xbox One XDK Updates
• Xbox One XDK Version Info
• What’s new in the July 2014 XDK

Release Notes and Xbox One XDK Updates

The most recent release notes for and updates to the Xbox One XDK can always be found on Xbox One XDK Software Downloads on the Xbox Game Developer site. For access, log in with your ID and password on https://developer.microsoft.com/en-us/games/xbox/partner/index; at the top of the page, point to Development and click Downloads.

You can check with your account manager for the latest information about upcoming Xbox One XDK releases.

Xbox One XDK Version Info

The July 2014 Xbox One XDK contains the latest tools and libraries for Xbox One.

What’s new in the July 2014 XDK

Roadmap

The Xbox One Developer Roadmap on the XGD site has been updated with projections of developer-facing feature work from the July XDK through Q4 of this year. The roadmap is intended to help developers plan their implementation schedules around upcoming feature and tooling efforts for the Xbox One console and related services.

Table of Contents

Audio

Content Update and Storage

Developer Tools

Graphics

Multiplayer

NUI

PIX

System

Samples

Audio

Audio Hardware/CPU interaction performance optimizations
Context memory used by the Audio Control Processor (ACP) has transitioned from cached to uncached memory. Title CPU costs for managing and updating the ACP are significantly reduced (tests have measured >50% improvements), which will benefit nearly all titles that use SHAPE flowgraphs (e.g. audio middleware).

Title Notification
Titles are now notified when background music is played.

USB Audio Microphone Support
The July release adds support for stand-alone Xbox 360 USB microphones that comply with the USB audio v1.0 specifications and meet the following requirements:

• Mono-stream
• 16-bit depth
• USB Audio Format Type I

The USB microphone devices will default to the 48kHz sample rate, or to the max sample rate supported by the device if the default sample rate is not supported. This type of device is exposed by the audio infrastructure as another capture device, which means that applications can use the existing APIs to enumerate them (IMMDevice Interface) and to read the capture data (WASAPI).

Content Update and Storage

Tooling for File Based Content Updates
We are introducing the ability to create Content Updates with file-based granularity instead of chunk-based granularity. This functionality won’t be turned on in the Recovery until September but the July XDK tooling supports creating file-based Content Updates. This is not a required change – developers can continue to use the existing chunk-based content update method for future titles. Packages enabled for file-based content updates are fully compatible with the currently released recoveries and will update using the existing chunk-based content update method until the recovery support is released.

WARNING: Developers should not change the content update format for an already shipped package, as it will force a full re-download of the entire package.

For more information, see Make Package (makepkg.exe).

Persistent local storage (PLS)
In the July XDK we are introducing the ability to allow games to have a maximum of 4GB of local storage dedicated to their ERA title. To access this feature, the PLS Storage must be specified as part of the application manifest. This will cause the local storage to be created when the ERA title is installed. While this PLS is persistent, it can be removed by the user as part of HDD/Titles management so that they can free up space or clear up possible corruption of the local storage volume. PLS is also locked to the internal hard drive of the console on which it is created and so it does not roam with the user’s external storage. Due to these restrictions, titles must be resilient to PLS not retaining prior state and must be able to launch without it. If we unable to locate the PLS on Title launch, we will create a new instance of PLS for the title and allow the title to start. PLS is being provided to allow games to store extra data needed for the operation of their title but is not meant for Content Update, due to the fact that PLS is only accessible while the title is running and therefore cannot be updated in the background in the same way the title is through Content Update.

Note PLS should never be used to store saved games for the end-user.

For more information, see Local Storage.

Development Tools

Xbox One Manager
We’ve added the following functionality to Xbox One Manager for July:

1. Enabled pull deployment inside of the Xbox One Manager UI (Run app from PC)
2. Attach a debug monitor to a running app
3. Pass launch parameters to applications when launching them

We would like to get your feedback. If you have feedback or feature requests for the Xbox One Manager you can now send us your feedback directly from inside Xbox One Manager. Go to File->About and click on the Send feedback link.

For more information about Xbox One Manager, see Xbox One Manager.

Xbox One Neighborhood
Xbox One Neighborhood now has added support for package apps. You can now see packaged apps installed using “xbapp install” or Xbox One Manager as network shares on your console. The network shares for packaged apps are read-only. For more information, see Xbox One Neighborhood: Accessing the Console File System from Your PC.

Push Deployment Performance improved by over 50% for April, May, June, and July XDKs
We have made additional improvements to file I/O performance. This means that file copy operations and push deployment are now much faster. For push deployment, we have reduced the time to deploy a large title by 30%-60% depending on the layout of the game – we have seen the best improvements for titles with a small number of large files but even titles with a large number of small files should see dramatic improvements. For a typical 60GB+ game we have seen around a 20 minute reduction in deployment time. This table, based on our test results, gives an idea of the gains that you can expect to see for push deployment and file copy operations.

Note

  This improvement is in the Recovery not in the XDK, and so you should see improvements when you move to the July Recovery, even if you do not move to the July XDK. You will see the best results if you are using the June or July XDKs but you should still see significant improvements if you are using the April or May XDKs.

Push Deployment Restart Performance improved
When restarting a failed deployment, deployment will now restart at the point of failure rather than restarting from the beginning.

Stress can now be controlled directly from a console
The disk and memory stress available through the xbStress PC command line tool can now also be controlled from a snapped SRA application. This allows you to run stress without having a PC attached to your console.

XboxConsole available on CodePlex
XboxConsole is a managed code library for the XDK that allow you to control and automate your Xbox One development and test consoles. It provides a managed programming model on top of the XTF API that ships in the XDK. It is used extensively by Microsoft Studios as part of their test infrastructure.

XboxConsole is released as source code so that you can extend and customize its behavior. You can find it on CodePlex at https://xboxconsole.codeplex.com/.

Deployment Validate Manifest option
xbapp deploy, xbdeploy push, and xbdeploy pull now have a /VM option that does detailed manifest validation before attempting to deploy an application. This will help you understand and fix problems in your manifest that result in the “Failed (0x80073CF6) to register remote app.” error.

New XTF APIs
This release includes the following new XTF APIs:

• XtfGetAvailableSpaceForAppInstallation allows you to query the amount of free space on the console before deploying an app.
• XtfGetErrorText allows you to get the standard XTF error message for a particular HRESULT returned by one of the XTF APIs. This release covers HRESULTs for XTF transport failures. Future releases will add support for additional XTF HRESULTs.

Improved visualization of WinRT types in the Visual Studio debugger
More symbolic information is included in the XDK which allows you to see more of the fields of the WinRT types in Microsoft.Xbox.Services when using the debugger.

Graphics

GPU Performance in general is improved by 3.5%
Overall GPU performance for typical game workloads has improved from June to July by an average of 3.5% across titles. The amount of performance improvement depends on the game workload, so your measured performance may be more or less. This improvement was made through the following:

• An additional GPU hardware context has been made available to title rendering, bringing the available number of contexts up from 6 to 7. Doing so helps performance in portions of scenes where the GPU is context-roll bound.
• Shaders are now automatically prefetched by the GPU. Whenever a shader is set into the pipeline, as with PSSetShader, the GPU’s Command Processor block is instructed to automatically prefetch the shader instructions into the GPU L2 before the next Draw is executed. This helps with draw performance by eliminating shader stalls due to instruction fetches.
• Various internal GPU configuration parameters were tuned to optimize game workloads.

Typical DrawIndexed Calls Are 68% Faster on the CPU
DrawIndexed calls that go through the D3D fast-path are now 68% faster on the CPU than the previous XDK. In June, a DrawIndexed call that uses the Constant Engine block to gather and prefetch 24 descriptors for the draw’s shaders took 38.6 ns on the CPU. With the July XDK, it now takes 23.0 ns (good for 40 million draws per second from a single thread). In our profiling of shipping titles, 90.4% of all Draw calls go through the D3D fast-path. The fast-path handles only vertex shader and pixel shader combinations; draws using tessellation or geometry shaders go through the complex path. The GetDriverStatistics API may be used on Instrumented or Debug versions of D3D to determine when the complex-path is used by the driver, and why.

Performance with Fast Semantics is Improved
We recommend that all titles adopt fast semantics through the D3D11_CREATE_DEVICE_IMMEDIATE_CONTEXT_FAST_SEMANTICS and D3D11_CREATE_DEFERRED_CONTEXT_FAST_SEMANTICS flags. Doing so significantly improves CPU performance. It also improves GPU performance by virtue of explicit control over GPU synchronization and by allowing command buffers to be read through Garlic bus instead of Onion bus. Consider the following sequence:

PSSetShader();
VSSetShader();
DrawIndexed();  

This takes 51.2 ns on a deferred context when using fast semantics (good for just under 20 million iterations per second from a single thread). In contrast, with default legacy semantics this takes 214.5 ns (i.e., legacy semantics are 4x slower than fast semantics). Included in the cost for both is the overhead of instructing the Constant Engine to gather and prefetch 24 descriptors, and to prefetch the new shaders. Legacy semantics will be deprecated in favor of fast semantics in a future XDK for 2015 titles.

Better Instrumented D3D Performance
A performance bug was fixed that results in 10x better D3D CPU performance when using Instrumented versions of D3D with fast semantics. (Retail version performance of D3D with fast semantics was never affected by this bug, nor was any use of legacy semantics.) Additionally, Instrumented D3D performance overall has been much improved for fast and legacy semantics, bringing it much closer to Retail D3D performance when not actively invoking a PIX Timing or GPU capture. However, we still recommend that titles do regular profiling and benchmarking with Retail versions of D3D in addition to using Instrumented (For titles using the June XDK or older, it’s pretty much a necessity to never benchmark on Instrumented versions of D3D).

New FXC compiler define to reduce runtime memory usage (__XBOX_FULL_PRECOMPILE_PROMISE)
The __XBOX_FULL_PRECOMPILE_PROMISE define is a compile-time guarantee to the graphics driver that shader bytecode will not be needed after the initial call to CreateShader. With this guarantee the graphics driver avoids holding copies of shader bytecode which can provide a significant reduction in driver heap use. For more information, see Shaders and the FXC Shader Compiler.

Additionally, the d3dcompiler now supports a complete set of defines to disable precompilation of specific shader objects. These defines should be used when a default shader object is known to not be needed.

DXGIXSetVLineNotification and DXGI_PRESENT_DO_NOT_WAIT
DXGIXSetVLineNotification is a new API that allows a title to block a thread on an event that is triggered either at Vertical Blank or when scan-out reaches a specifiable horizontal scan line. When used in conjunction with the new DXGI_PRESENT_DO_NOT_WAIT option for IDXGISwapChain::Present Method or DXGIXPresentArray, the combination allows a title to reclaim CPU time when running far enough ahead that all of the back-buffers in the Swap Chain are complete and queued for display. Normally D3D does a spin-loop on the CPU in such a situation, but with this mechanism that can be turned into a triggered OS event and a different thread scheduled in the interim. The DXGIXSetVLineNotification event has an average latency of 50us (micro-seconds) under load with potential spikes up to 500us.

Reduce register usage and increase occupancy
__XBOX_WAVESIM_ITERATION_N and __XBOX_WAVESIM_ITERATION defines are more successful at driving down register usage and increasing occupancy. These flags can significantly improve shader performance but are not enabled by default because they add to compile time and can make shader performance worse in some cases.

Shader User Data Support
This release adds a new set of APIs and associated HLSL intrinsic to allow developers direct access to shader user data input registers. This allows you to directly pass 15 DWORDs worth of data directly into sregs upon shader execution without having to read it from memory. To populate the shader user data registers, use the ID3D11DeviceContextX::*SetShaderUserData family of APIs. To read the values in HLSL, use the intrinsic __XB_GetShaderUserData().

Draw ID for MultiDraw
The Multi Draw family of APIs has been extended to allow a unique identifier per draw within the multi-draw. This ID can be used in HLSL to calculate different values or perform different action depending on which draw is being rendered. The draw id can either be an automatically generated unique identifier (0,1,2…) or a completely custom value specified as part of the arguments buffer. To enable the draw id when using the multi-draw family of APIs, use the new flags D3D11X_MULTI_DRAW_DRAWID_AUTO_GENERATE or D3D11X_MULTI_DRAW_DRAWID_FROM_BUFFER_FOR_ARGS along with D3D11X_MULTI_DRAW_DRAWID_VERTEX_SHADER_USER_DATA_REG_n. To read the value in HLSL, use the shader use data HLSL intrinsic __XB_GetShaderUserData(). For more information about the enumeration values, see D3D11X_MULTI_DRAW_FLAG Enumeration.

Xbox Hang Investigation Tool (XHIT) Improvements
Starting with the July 2014 XDK, shader names are now present in graphics memory alongside the shader binary, and XHIT can use these names to correlate some GPU hangs with the specific HLSL shader that is hung.

New D3DCompiler Intrinsics
The following new D3DCompiler Intrinsics are available:

C++

__XB_MemTime()
__XB_GetShaderUserData()
float<> __XB_UnpackByte0 (in uint<> x);
float<> __XB_UnpackByte1 (in uint<> x);
float<> __XB_UnpackByte2 (in uint<> x);
float<> __XB_UnpackByte3 (in uint<> x);
uint __XB_PackF32ToU8(float insertvalue, uint idx, uint uSrc);
uint<> f32tof16nearest(in float_like<> x);
$type1 __XB_ReadLane (in any<> value, in int lane);
int __XB_IBFE (in uint width, in uint offset, in uint val);
uint __XB_UBFE (in uint width, in uint offset, in uint val);
uint<> __XB_BFM(in uint<> maskwidth, in uint<> maskloc);
uint<> __XB_BFI(in uint<> val, in uint<> preserve, in uint<> enable);
int<> __XB_F32ToI32RPI (in float<> val);
int<> __XB_F32ToI32FLR (in float<> val);
float<> __XB_I4ToF32 (in int<> x);  

See Shaders and the FXC Shader Compiler for more details.

HLSL Tools Disassembly
HLSL tools disassembly now lists potential performance problems found during compilation. For example integer division or if shader makes use of thread scratch memory.

New SetGDSRange APIs
On Xbox One GPU, the UAV append counters are stored in GDS. Performing atomic operations is slightly faster in GDS than in main memory, so AppendBuffers and ConsumeBuffers use GDS for the counters by default, to reduce contention on the main memory. This set APIs allows you to map areas of GDS to different contexts, which enables use of UAVs with counters on Async Compute contexts. For more information, see ID3D11ComputeContextX.SetGDSRange and ID3D11DeviceContextX.SetGDSRange.

New InsertWaitOnMemory API
This new API inserts a GPU command buffer packet that instructs the GPU command processor to spin-wait on a memory location, using a configurable comparison function, reference value, and mask. This API is now present on graphics, compute, and DMA engine contexts. Warning: The spin-waits do not have a timeout, so incorrect usage of this API can easily lead to GPU hangs. For more information, see ID3D11ComputeContextX.InsertWaitOnMemory, ID3D11DeviceContextX.InsertWaitOnMemory, and ID3D11DmaEngineContextX.InsertWaitOnMemory.

Multiplayer

Multiplayer Protocol Activation improvements
  Multiplayer protocol activation arguments have been updated in the July flash. The partyInviteAccept event arguments now have an “accepterXuid” reference in the URI.

NUI

Increased depth sensing range
The depth sensing range has been increased from 4.5 meters to 8 meters. The additional range can help titles better understand the environment. Built-in tracking features such as skeletal tracking, hand state, and identity will continue to function up to 4.5 meters as before. This change is available starting with the July version of the vision pipeline. Titles that lock to an older version will need to move to July in order to see this change.

Normalized Infrared
The IR streams are now being corrected for radial brightness falloff. The result is a more evenly-lit image, which can improve the consistency of IR-based algorithms as users move away from the center. To maximize dynamic range, the image is also about 50% dimmer in the center. This change is available starting with the July version of the vision pipeline. Titles that lock to an older version will need to move to July in order to see this change.

Japanese acoustic models (beta)
Initial acoustic models for Japanese which can be used for prototyping Japanese voice integration for apps and games.

PIX

Shader Profiling (Preview)
This release includes a preview of the new Shader Profiling feature in PIX. For this release, the Timeline view in GPU captures has been significantly extended to include a great deal of visualized data obtained from shader profiling runs during analysis. Of primary interest is a representation of GPU occupancy, and how it is affected throughout the scene by context availability, surface syncs, partial and cache flushes, and segment kicks. In addition, a number of streaming counters that represent hardware waits are graphed concurrently. Altogether, this new feature will give you far deeper insight into the performance of the GPU and the bottlenecks across your scene.

Timing data for command lists
PIX timing captures now include timing data for individual Draw events included within a command list. This enables you to see finer grained granularity of the performance of deferred context rendering.

Improved UPDB handling
PIX has improved handling for shader debug information stored in PDB files. PIX now:

• Respects the symbol path in the Settings pane of PIX. This is the common directory used for CPU and GPU shader symbol information.
• Properly handles relative paths embedded in the shader blob through the __XBOX_PDBFILENAME option.
• Allows the user to manually load shader PDB files from within the Settings pane when these PDB files cannot be found.

Pixel Cost Visualization
This release of PIX adds another new render target visualization in the Resources view for Pixel Cost. This visualization provides a representation of execution time spent on a per-pixel basis across the entire scene.

Enhanced ESRAM residency information now shows percentage of resource in ESRAM.
The ESRAM residency information in the Resources view of PIX has been enhanced for partially resident resources in this release to show the percentage of the resource that is located in ESRAM.

Updated Dr. PIX Experiment for Context Rolls
Context rolls can be one of the chief performance bottlenecks on Xbox One. In this release, Dr. PIX has an updated experiment for context roll reduction that now correctly measures the impact to performance over the entire frame or over a series of draw calls, using multi-select in the Events view, with varying numbers of GPU contexts. You can use this experiment to gauge the relative cost of context rolls in sections of your rendering code.

Function Butterfly View Enhancements
The function butterfly view is now available in function summary captures. The view itself now supports the ability to navigate to specific callers and callees by double clicking on a function name.

Visual Studio can be opened from CPU profiling captures
The context menu in function summary and callgraph captures now includes an Open in Visual Studio option. Choosing this option opens the source file that includes the selected function and navigates to the beginning of the function’s implementation.

Debug memory can now be directly mapped into title memory
Debug memory (previously only available through a call to DebugMemGetRegion) can now be accessed directly as part of your title’s memory. To enable this access mode, make sure ProfilingMode has been set to On and set xbConfig’s DebugMemoryMode setting to “Pix_Title”.

HLSL and GPU instruction correspondence
PIX in this release now shows correspondence between GPU instructions and HLSL in the Shaders view. As you walk through the list of generated GPU instructions, PIX will highlight the appropriate code within the HLSL Source and DXBC panes that led to the generation of that code. This feature will help you gain a better understanding of how the Xbox One shader compiler generates code and in conjunction with Edit and Continue for Shaders, help you further optimize your generated shader code.

PIX determinism test to aid in detection of synchronization issues
When starting analysis on a capture, PIX will now perform a test for determinism of displayed results. The test will play the capture back twice: once unmodified and a second time with the insertion of all D3D11X_GPU_PIPELINED_EVENT flush events, an idle of the GPU, and full cache invalidation after every draw. The contents of the buffers submitted to Swap on the two passes are then compared for equivalence. If the buffer has changed between runs (either from the addition of the synchronization logic or due to non-determinism inherent in the capture itself), PIX will display a warning message.

System

GetLaunchActivationArgs
Developers can use the new GetLaunchActivationArgs function to get the protocol activation arguments for use in static initialization. This function can be called prior to the application’s activation event. It will return the activation arguments specified in Visual Studio or from the command-line. This function is available for retail scenarios, however it returns an empty string.

To reference this API, right click on the visual studio project, select References, click Add New Reference and check the box next to Xbox DevKit Extensions.

More System components are now using XMemAlloc
We have migrated more System components to use XMemAlloc, making it easier for titles to track memory usage and reducing use of the legacy memory pool. There are still system components that do not use XMemAlloc and so you should still expect to see legacy memory allocations. There will be additional improvements in future XDKs.

Samples

Game Trials
A sample application that demonstrates how to implement game trials with Xbox One.

SmartGlass Poker
This sample demonstrates how to manage connections from multiple SmartGlass devices. It additionally shows how private screens sallow players to make decisions that are hidden from other players in the same room.