Metadata-Version: 2.4
Name: nv2a-debug
Version: 0.1.6
Summary: Simulator/debugger for the Xbox nv2a vertex shader
Project-URL: Documentation, https://github.com/abaire/nv2a_vsh_debug#readme
Project-URL: Issues, https://github.com/abaire/nv2a_vsh_debug/issues
Project-URL: Source, https://github.com/abaire/nv2a_vsh_debug
Author-email: Erik Abair <erik.abair@bearbrains.work>
License: This is free and unencumbered software released into the public domain.
        
        Anyone is free to copy, modify, publish, use, compile, sell, or
        distribute this software, either in source code form or as a compiled
        binary, for any purpose, commercial or non-commercial, and by any
        means.
        
        In jurisdictions that recognize copyright laws, the author or authors
        of this software dedicate any and all copyright interest in the
        software to the public domain. We make this dedication for the benefit
        of the public at large and to the detriment of our heirs and
        successors. We intend this dedication to be an overt act of
        relinquishment in perpetuity of all present and future rights to this
        software under copyright law.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
        
        For more information, please refer to <https://unlicense.org>
License-File: LICENSE
Keywords: assembler,nv2a,nvidia,vertex shader,xbox
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Requires-Dist: cffi~=1.17.1
Requires-Dist: nv2a-vsh~=0.1.2
Requires-Dist: textual~=1.0.0
Description-Content-Type: text/markdown

Simulator/debugger for the original Xbox nv2a vertex shader.

# Use

Run `nv2adbg` with `--help` to see command line options.

## Menus

### File menu

Allows inputs to be configured.

## Source window

The source window is split into three areas:

1. The program view on the left shows the shader instructions
1. The inputs panel on the right shows the value of register inputs for the
   currently selected line. Components of the register that are used will be
   highlighted.
1. The outputs panel at the bottom shows the computed values of the outputs.
   Components that are written to will be highlighted.

* Cursor up/down, page-up/down, and home/end in the source window navigate
  source lines.
* "a" will toggle ancestry tracing for the currently selected line, marking
  every line that contributes to the line's outputs.
    * In tracing mode
        * "space" will allow the current line to be locked so
          moving the cursor will not change the root of the ancestor trace.
        * "f" will filter out any lines that do not contribute to the
          instruction being traced. Press "f" again to return to full source
          view.
    * _NOTE_: At the time of this writing there is no way to choose between the
      MAC and ILU component of a paired command, both will be traced. If you
      only care about one or the other, the best option is to go to the first
      ancestor that contributes solely to the one you care about and do the
      trace from there.

# Helpful hints

* You can convert the contents of a [xemu](https://github.com/mborgerson/xemu)
  vertex shader using [RenderDoc](https://renderdoc.org/) to examine the draw
  and running it
  through https://github.com/abaire/renderdoc_util/blob/main/util/xemu_shader_to_nv2a.py
  to sanitize it.
* You can set initial values with csv dumps from RenderDoc (use `-h` to see the
  appropriate commands, the mesh view will have the input register values and
  you can expand the uniforms in the pipeline view to get the constant
  registers)
