PDF Archive

Easily share your PDF documents with your contacts, on the Web and Social Networks.

Share a file Manage my documents Convert Recover PDF Search Help Contact



Spark Documentation .pdf


Original filename: Spark-Documentation.pdf
Title: Spark Documentation
Author: Nintendo

This PDF 1.3 document has been generated by Microsoft® Word 2013 / Mac OS X 10.10.5 Quartz PDFContext, and has been sent on pdf-archive.com on 26/12/2015 at 23:25, from IP address 104.33.x.x. The current document download page has been viewed 882 times.
File size: 1.9 MB (40 pages).
Privacy: public file




Download original PDF file









Document preview


Spark Documentation

The content of this document is highly confidential
and should be handled accordingly.

2012 Nintendo
CONFIDENTIAL

WUP-06-0124-001-A
Released: Review

Spark Documentation

Confidential
These coded instructions, statements, and computer programs contain proprietary information of Nintendo
and/or its licensed developers and are protected by national and international copyright laws. They may not
be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written
consent of Nintendo.

WUP-06-0124-001-A
Released: Review

2

2012 Nintendo
CONFIDENTIAL

Spark Documentation

Table of Contents
1

Introduction ...................................................................................................................................................5
1.1

2

1.1.1

Approximated Times .......................................................................................................................5

1.1.2

Accurate Times ...............................................................................................................................5

Getting Started ..............................................................................................................................................6
2.1

3

4

Regarding Timing Values from Spark ....................................................................................................5

Capture Options ....................................................................................................................................6

2.1.1

Capture via Spark ...........................................................................................................................6

2.1.2

Programmatically Triggered Captures ............................................................................................6

Spark Features .............................................................................................................................................7
3.1

Enhanced Shader Support ....................................................................................................................7

3.2

Menu Bar ...............................................................................................................................................7

3.3

Tool Bar .................................................................................................................................................9

3.3.1

Capture Button ...............................................................................................................................9

3.3.2

Analyze Button ...............................................................................................................................9

Data Views .................................................................................................................................................. 11
4.1

Common Data View Features ............................................................................................................. 11

4.2

Events View ........................................................................................................................................ 12

4.2.1
4.3

Timeline View ..................................................................................................................................... 13

4.4

GX2 State View .................................................................................................................................. 14

4.4.1

5

6

Sorting Data in the Events View .................................................................................................. 12

Filtering the GX2 State View ....................................................................................................... 15

4.5

Surfaces View ..................................................................................................................................... 16

4.6

Pixel History View ............................................................................................................................... 19

4.7

Uniform Data View .............................................................................................................................. 20

4.8

Uniform Watch View ........................................................................................................................... 21

4.9

Vertex Buffer View .............................................................................................................................. 22

4.10

Vertex 3D View ................................................................................................................................... 24

4.11

Pixel Shader and Vertex Shader Views .............................................................................................. 28

4.12

Log View ............................................................................................................................................. 29

Metrics ....................................................................................................................................................... 30
5.1

Introduction ......................................................................................................................................... 30

5.2

GPU Timing ........................................................................................................................................ 31

Experiments ............................................................................................................................................... 32
6.1

Shader Experiments ........................................................................................................................... 32

6.1.1

Shader Compilation Options ....................................................................................................... 32

2012 Nintendo
CONFIDENTIAL

3

WUP-06-0124-001-A
Released: Review

Spark Documentation

7

Application Side Spark Directives via Code ............................................................................................... 34

8

Technical Details......................................................................................................................................... 35

9

8.1

Spark and Shaders ............................................................................................................................. 35

8.2

Spark Related Data Flows .................................................................................................................. 36

8.3

File Formats ........................................................................................................................................ 38

Troubleshooting .......................................................................................................................................... 39
9.1

Problems During Capture ................................................................................................................... 39

9.2

Problems During Analyze .................................................................................................................... 39

9.3

General Application Crash .................................................................................................................. 39

WUP-06-0124-001-A
Released: Review

4

2012 Nintendo
CONFIDENTIAL

Spark Documentation

1 Introduction
Spark is a perpetual work in progress. We welcome your input on future feature prioritization. As
always, please let us know if you observe any problems.

1.1

Regarding Timing Values from Spark

1.1.1

Approximated Times
Due to the unavoidably disruptive nature of the capture process, timing values acquired during a
capture are not accurate.
While the resulting time values are not representative of the actual performance within a normal game
context, they are generally proportional. Despite the inaccuracy, we find the timing information to be
useful to show relative performance throughout a frame.
Previous versions of Spark presented these timing values, but noted that they were approximations.
None-the-less, the values proved to be misleading and generated confusion. Thus, going forward,
timing values derived during the capture process will be presented only as percentages of the overall
frame.

1.1.2

Accurate Times
To generate accurate timing values, click on the Analyze button (
Section 3.3.2 – Analyze Button for more details.

) on the toolbar. See

Following a successful analyze sequence, the timing values will be shown as milliseconds.

2012 Nintendo
CONFIDENTIAL

5

WUP-06-0124-001-A
Released: Review

Spark Documentation

2 Getting Started
Consult the separate “Getting Started” document as needed. This document assumes you can enable
GPU data capture.

Capture Options

2.1

There are two ways to capture GPU data: manually via Spark and programmatically via your code.

Capture via Spark

2.1.1

Capturing GPU data manually via Spark is quite straight forward. Simply click on the Capture button
(

) on the tool bar and wait for the capture to complete. The captured data is loaded

directly into Spark.
Note that the capture data exists in a file within the temporary directory. This file will not be retained
indefinitely. If you wish to preserve a given capture, simply use Save Capture As… from the File
menu. The last 20 capture files are kept in the temporary file directory. Older files are automatically
deleted.

2.1.2

Programmatically Triggered Captures
If you wish, you can also trigger GPU captures programmatically by calling function
GX2DebugCaptureFrame() from within your code. You must provide a filename to this function.
If the specified filename does not include a path (such as “MyFile.4mp”), then the resulting file will be
placed in directory $(CAFE_ROOT)\data\save\common\pm4capture on the host PC. The
directories “common” and “pm4capture” will be created if they do not already exist.
If the filename includes a partial or relative path (such as “MyDirectory/MyFile.4mp”), then that
path will be appended to $(CAFE_ROOT)\data\save\common\pm4capture. If any directory within
the relative path does not exist, such directories will not be created and the capture will be aborted.
If the specified filename includes a fully qualified path (such as “C:/MyDirectory/MyFile.4mp”)
then the output file will be created using the name and location provided. If any directory within the full
path does not exist, such directories will not be created and the capture will be aborted.
(Note: The underlying protocol used to communicate with the GPU is called PM4. After an Endian
byte reversal, the resulting 4MP signature is used as the capture file extension.)

WUP-06-0124-001-A
Released: Review

6

2012 Nintendo
CONFIDENTIAL

Spark Documentation

3 Spark Features
3.1

Enhanced Shader Support
Updated “Spark aware” versions of both the stand-alone shader compiler (gshCompile) and the shader
compiler dynamic link library (shaderUtils) are available. These updated versions generate auxiliary
shader symbol files. Such files are used by Spark to provide Enhanced Shader Support features
which include:
Shader source code display.
Shader disassembly which incorporates symbolic information.
Shader symbols in Uniform Data view.
Uniform Watch view is populated with symbols and properly typed values.
And more in future Spark releases…
When the Enhanced Shader Support features are not enabled, Spark can only provide the following:
Shader disassembly with no symbolic information.
When a new capture is loaded, Spark will inspect all shaders within the capture data and attempt to
load the corresponding auxiliary shader symbol files. By default, Spark and the shader compiler will
use same directory.
See Section 8.1 – Spark and Shaders for more information.
Note that GX2 is introducing support for “compute shaders”. This version of Spark does not support
compute shaders.

3.2

Menu Bar
Use the File menu to open an existing capture file. You will also be able to reopen recently viewed
capture files as long as the file is still present in the location previously used. You can load either
“capture” files (*.4mp) or Spark files (*.spark). Spark files have the advantage of integrating all
information regarding a given frame within a single file. The “capture” files, which are generated during
the capture process, do not include shader symbol information (generated by the shader compilation
tools) nor accurate timing values (generated by SparkPlay) if available.
This menu also provides a Save Capture As… option to allow you to save a capture to a file of your
choice. You can only save in the Spark (*.spark) file format.
After successfully running the Analyze feature (see Section 3.3.2 – Analyze Button), the Export
Metrics… option will be available. This will save all metrics to a CSV file which can be subsequently
loaded into Excel for further processing and analysis. See Section 5 – Metrics for more information.

2012 Nintendo
CONFIDENTIAL

7

WUP-06-0124-001-A
Released: Review

Spark Documentation

The Views menu allows you to create new views of the various types available. Furthermore, you can
save and load the layout of your Spark session. Available view types are described in Section 4 –
Data Views below.
The Tools menu gives you access to the Options dialog box.
The Capture Options panel provide various options which can be used to speed up captures by
restricting the data which is collected. They include:
Capture Render Products – When checked, the capture system will acquire all active render
targets per draw event in the frame. When not checked, you will not see the state of your
frame buffer (or other render targets) as it is created over the course of the frame.
Capture Textures – When checked, the capture system will acquire all textures used in the
course of the frame. When not checked, you will not see the pixels of the textures.
Capture Attribute Buffers – When checked, attribute buffer data is collected. When not
checked, you will not see vertex information or 3D representations thereof.
Capture Uniform Buffers – When checked, uniform buffer (or uniform block) data is collected.
Fast Capture – When this option is checked, the capture system will assume that the CPU
never modifies GPU buffers during the frame. If the CPU does alter a GPU buffer, then the
capture may appear incorrect in Spark.
The Coordinates panel allows you to select the coordinate space which is native to your game. The
default is “Right Handed, Y Axis Up”. If you have a visible Vertex 3D view with 3D data displayed, it will
automatically preview your selection.

The Shader Symbols panel allows you to specify directories in which Spark should for shader symbol
files generated by a Spark enabled shader compiler. Multiple directories can be specified. Spark will
search for desired shader symbol files in the order in which the directories are listed. The first match
WUP-06-0124-001-A
Released: Review

8

2012 Nintendo
CONFIDENTIAL

Spark Documentation

found will be used. This allows you, for example, to keep shader symbol files corresponding to local
edits while shared symbol files are stored in a location accessible by multiple members of a team.
Thus, Spark can use symbol files from a shared data depot while preferring local shader edits.
The Layout Hot Keys panel allows you to assign previously saved layouts to ten available hot keys.
Finally, the External Tools panel allows you to configure an external “diff” application which can be
used to compare revised shader source against the originally captured shader source.

3.3

Tool Bar

3.3.1

Capture Button
The Capture button (

) remains disabled until Spark detects an application running on the

Wii U development hardware which was linked against the gx2spark.a library.
Simply click the Capture button to trigger a GPU data capture. This process will take several seconds
(possibly multiple minutes in the current version). When complete, the resulting frame capture is
automatically loaded into Spark.
Note that captures acquired via the Capture button reside in temporary files. If you wish to preserve
the file, use Save Capture As… on the File menu.

3.3.2

Analyze Button
The Analyze button (

) allows you to investigate a capture in more detail. The analysis

features are currently limited. But, as usual, we are working on it!
Clicking on the Analyze button will have the following effects:
If SparkPlay is not already running, Spark will generate a SparkPlay.rpx file in the
$(LOCALAPPDATA)\Temp\Nintendo\Cafe\Spark directory. The SparkPlay executable image is
embedded within Spark itself.
Again, if SparkPlay is not already running, Spark will launch the SparkPlay utility program on
your Wii U devkit. Note that this will terminate any game running on the hardware.
SparkPlay will generate accurate timing values which will be automatically loaded into Spark.
Metrics for all render operations will be collected and loaded into Spark.
BETA FEATURE – SparkPlay will remain running and will display on the television screen the
revised frame capture following any shader edits.
SparkPlay initially displays a slowly cycling color field to indicate that it is active.
In order for SparkPlay to be launched, the following environment variables must be properly defined:
CAFE_ROOT and MION_BRIDGE_TOOLS. These must be set before Spark is launched.
BETA FEATURE – This version of Spark introduces basic shader experimentation. If edits are made
to existing shader source code, Spark will attempt to compile the revised shaders. If there are no
errors, Spark will send the updated shader binary code down to SparkPlay. If there are no problems,
2012 Nintendo
CONFIDENTIAL

9

WUP-06-0124-001-A
Released: Review


Related documents


spark documentation
nintendo is in crisis the wii u and the 2ds
zeus crimeware toolkit
v4 software overview
crash invades nintendo rules guidelines
digital slr photography guide


Related keywords