NVASM - Vertex and Pixel Shader Macro Assembler

 

Overview

 

NVASM was developed for a variety of reasons. Allowing developers to assemble their Vertex and Pixel Shader source code into object code that can be loaded directly into DX8.  Better error reporting functionality was included so that you can double click on the error and be taken directly to the line of the error, inside of Microsoftâ Visual Studioâ.  Listing file support is included so that you can look at the output generated by the assembler.  Finally it was written so that it is easily extensible, so that when new assembly opcodes are defined, they can be integrated.

 

Features

 

 

How to use NVASM

 

NVASM can either be used from the command line or integrated inside of Microsoftâ Visual Studioâ.  Integration inside Visual Studioâ will be explained later in this document.  You can invoke NVASM from the command line.  Here is an example of how to do that.

 

      nvasm -lxh test.psa testpsa.h testpsa.lst

 

NVASM takes options first followed by the source file, then the output file and finally followed by the listing filename.  The output and listing filenames are optional and will be auto generated from the source file name if they are not specified.  Output take the base filename of the source file and append either .vso , .pso or .h for a vertex shader object file, pixel shader object file or output of a .h file, respectively.  The listing file is auto generated from the base filename of the source file with .lst appended.  This only is done if the -l option is specified.

 

NVASM Options

 

 

NVASM Error Reporting

 

NVASM has robust error reporting built in to it.  It will not only tell you what line the error was on, so that Visual Studioâ can understand it, it will tell you where the source line is even back tracking though macros.  This is a very powerful feature, because now you can just double click on the error and be taken directly to the macro that generated it and you still know the line where the macro was invoked.  Here is an example of the error output from NVASM:

 

.\test.vsa(41) : error Can't use vertex register as destination argument.

.\test.vsa(44) : References ->

constants.h(6) : error Can't use swizzle modifier on the address register.

----- Assembly unsuccessful, 68 line assembled, 10 errors, 3 warnings -----

 

As you can see from the above example, Line 44 in test.vsa has an error.  Sine Line 44 was a macro, the next line tells you that it came from constants.h at line(6).  If you double click on this line, you will taken directly to the macro line that generated the error.

 

Macros

 

NVASM has several ways to use macros.  You can use the #define type of macros that are used in C/C++ or you can use the "macro/endm" keywords.  #define macros do not have all the capabilities of the "macro/endm" type of macros.

 

Here is an example of how to use the "macro/endm" keywords:

 

macro Test  x,y

 

      dp3   r0, %x.x, %y

      dp3   r0, %x.y, %inc(%y)

endm

 

The "macro" line has the word "Test" on it and this is the name of the macro.  The next two items on the line are the parameters for the macro, if there are any.  The macro body is defined until the assembler reaches the "endm" keyword.  When the macro is invoked the assembler looks for the % sign to replace the parameters you specified inside of the macro body.  There are four special % macro functions that are available, the %inc(), %dec(), %add() and %sub() macro functions.  These take the string between the parentheses and do one of two things.  If the text between the parentheses has an explicit number in it, it will replace that number with another number that is either +1 or -1 for %inc and %dec, respectively. If there isn't an explicit number in the text between the parenthesis, then the functions look for the inner most brackets/ parenthesis or scans to the end of the line and inserts the text "+1" or"-1" for %inc and %dec, respectively.  The macros %add and %sub take one other argument that is the amount to offset the text.  So for example %add(%y, 5) would add 5 to the text.  The %add and %sub work in the exact same way as the %inc, %dec macros in terms of text replacement.

 

Now to invoke the macro in the source you would do the following

 

      Text  r1, c[EYE_NORMAL]

 

This would expand to the following inside the macro:

 

      dp3   r0, r1.x, c[EYE_NORMAL]

      dp3   r0, r1.y, c[EYE_NORMAL+1]

 

If you invoked the macro with the following parameters:

 

      Text  r1, r5

 

This would expand to the following inside the macro

 

      dp3   r0, r1.x, r5

      dp3   r0, r1.y, r6

 

Integration into Microsoftâ Visual Studioâ

 

The assembler can be integrated into your existing Visual Studioâ Project.  To include Vertex Assembly or Pixel Shader Assembly files into your project, follow these steps:

 

1.       Add files to the project with the Project->Add To Project->Files… menu options

2.       Setup the Custom Build settings by selecting Project->Settings… menu options and then selecting the assembly files.

3.       Click on the Custom Build tab

 

 

4.       Set the Description box to anything you like

5.       Put the NVASM command line in the Commands box.  You should specify any options you would like on this line also.  The above example uses the listing, expand macros and generate .h file options that will be explained later

6.       Set the Outputs box to be the name of the output file you would like generated.  The above example says the output file will be named testvsa.h.  The $(TargetPath) in the Command box will use this name when calling the NVASM program.

7.       Set any Dependencies by clicking on the Dependencies… button.  You should put any .h files that are included in the assembly language file in this dialog box. This will ensure that if you update the .h file, Visual Studioâ will re-assemble the assembler file.

8.       Click OK.

 

Contact

 

If you have any questions or comments regarding NVASM, contact:

 

Kenneth Hurley

NVIDIA Corporation

2701 San Thomas Expressway

Santa Clara, CA. 95050

khurley@nvidia.com