Command-Line Options¶

The NVIDIA CloudXR SDK sample applications and the CloudXR Server can use command-line options (also called launch options) to control certain runtime features. The available options are different for client and server, and in some cases there are client-specific options as well.

The methods available for providing launch options to clients and servers is OS-dependent. The overall methods include using a text file to store the options, running from a command prompt with the options appended, and OS-specific or debugger-specific parameter passing.

Setting launch options via text file is just like launching from a command-line, you just put them into a file. The options can be on one line like a console command, or you can break the options into individual lines for legibility. Each option needs to still be prefixed with a dash in either case. For servers, you will name the file CloudXRServerOptions.txt, and for clients use the name CloudXRLaunchOptions.txt.

Note

Should you want to quickly disable or comment out some commands in any of the above approaches, but not remove them completely, you can prefix or append something like “ZZZ” to the option name – so “ipZZZ” for example. That makes it so the option name doesn’t match anything and is skipped over. That allows you to leave an handful of extra options ‘available’.

For inline comments, there is no custom character at this time – if your text editor recognizes something as a comment (‘//’ or ‘#’), feel free to use that. Just don’t put any actual dashes in those comment lines, as the parser is very basic and will see the dash and look for a command name. We may add an explicit comment character in the future – or you can add it yourself if needed since the parsing code is all provided in the /shared code path.

The launch options all clearly funnel into settings in each of the samples. So you can also choose to create a ClientOptions object, manually set certain fields, and then have it pass through into various structures mirroring what the sample clients already do.

Note

There have been changes in 4.0 with respect to input and output paths, please read these sections for more detail on where the launch options file needs to be located. And further information on what your application needs to do to expose its data directory so CloudXR knows where it is can be found in CloudXR File Storage.

Platform-Specific Methods¶

Windows Options¶

For the SteamVR CloudXR Server driver, the only way to pass launch options is to create CloudXRServerOptions.txt in the C:\Users\*user-name*\AppData\Local\NVIDIA\CloudXR\SteamVR\ folder, with the desired options, prior to starting SteamVR.
For the new Server Sample application, there are a few methods available: #) You can create CloudXRServerOptions.txt in the C:\Users\*user-name*\AppData\Local\NVIDIA\CloudXR\ServerSample\ folder with launch options, prior to starting the executable. #) You can launch the executable from a command prompt, and append the dashed options as desired. #) You can make a shortcut to the executable, and modify the Target line to have the options appended as if a command prompt.
For the Client Sample application, there are a number of methods: #) You can create CloudXRLaunchOptions.txt in the C:\Users\*user-name*\AppData\Local\NVIDIA\CloudXR\SampleClient\ folder with desired launch options, prior to starting the client. #) You can launch the executable from a command prompt, and append the dashed options as desired. #) You can make a shortcut to the executable, and modify the Target line to have the options appended as if a command prompt. #) If you are building and launching from Visual Studio, you can set launch options in the Command Arguments box in the debugging configuration.

Android Options¶

For Android clients, you can launch in a few different ways: #) To run direct from Android Studio, click Run > Edit Configurations for the active configuration, and set the Launch Flags field to something like the following:
--es args "-s 192.168.1.1 -f 50"
The first part of that, the –es args piece, tells Android we want to launch with an extra string intent named ‘args’. Then, inside the double quotes you can list launch options you want as if it was a command-line. When a client is launched, in Java it can check for an extra string intent named ‘args’, and pass that content of that string (without the double quotes) into the sample’s native code for handling.
1. To start a client directly on the device (from a launch icon or app list), you first need to create a file called CloudXRLaunchOptions.txt, and add launch options as desired.
  
  Next you must run the client app once (and exit if it doesn’t on its own), as the first run of an installed application is when Android creates application-specific data directories. This is part of Android security that a newly installed app can’t do much of anything until the user has manually interacted with it (to prevent malware, etc.).
  
  Finally you need to copy the options file to the device, into the newly-created app data directory. The application data path will be something like /sdcard/Android/data/[com.app.name]/files/, but of course with a client-specific package name. For example the Oculus/Meta sample is com.nvidia.cloudxr.ovr and the ARCore sample is com.nvidia.ar.hellocloudxr.
  
  To get the file on your device, if it shows up as a USB drive on your desktop, you can simply drill down to the files subdirectory, and drag and drop the text file over. Alternatively, you can use an ADB command to push it to the right place, like:
```
adb.exe push CloudXRLaunchOptions.txt /sdcard/Android/data/[com.app.name]/files/
```

iOS Options¶

For an iOS client, there is currently no built-in support in the sample app to pass launch options via a file or by reading from command-line. You can review how the other clients load and parse the options, and add code to try to open that file from the app data path (which is where we write log files). We plan to add that in a future release.

The following tables provide a list of all command-line options that are available for the client and server, and extra options that were added for the Android ARCore sample (which is a great example of extending off the base set of options). The options include both an abbreviated command strings (1-3 chars) and a long format string (human-readable descriptor) for each option, prefixed with a dash (-) for command clarity (as the dash is always required), and notations when there is an argument needed for a given options, such as N when there’s a numeric value to specify, or S when there is some form of alphanumeric/string argument required, then a brief description of each option and range or list of argument values.

Server Command-Line Options¶

Long Format Name	Abbreviation	Description
-log-verbose	-v	Enable more verbose logging.
-log-quiet	-q	Disable logging to file, use only debug output.
-trace-stream-events	-t	Enable tracing of streaming events as ‘ETL’ log. May have high runtime impact. You might need to run the SteamVR process in admin mode so that certain traces can be captured.
-dump-images	-d	Dump streamed images to log folder periodically (currently every 300 frames).
-dump-audio	-da	Dump sent/received audio streams to CloudXR log folder.
-log-privacy-disable	-p	Disable privacy filtering in logging (allows full IP visibility).
-trace-local-events	-tle	Enable tracing of local events to xml file in log folder (see Local Event Traces (CloudXR Visual Profiler).
-embed-server-info	-esi	Embed server info in frames during streaming.
Value range is from -1 to 365	where 1+ specifies the number of days age to prune (so the max age is one year)	-1 resets to the system default (5d)	and 0 sets to never prune log files.”
-log-max-kb N	-lmk N	Maximum log size in kilobytes. Value range is from -1 to 1024, where values 1+ specifies the KB size to cap (so the max file size is 1GB), -1 resets to system default (5MB), and 0 sets to uncapped.
-fast-scale	-fs	Use simple, lower-quality downscale filtering when client request frame foveation
-disable-send-audio	-dsa	Disable sending server audio to the client. This is Enabled by default.
-enable-receive-audio	-ra	Enable receiving audio from client (i.e., microphone capture). This is Disabled by default.

Client Command-Line Options¶

Long Format Name	Abbreviation	Description
-server IP	-s IP	IP address of the server to which the client will connect.
-log-verbose	-v	Enable more verbose logging.
-log-quiet	-q	Disable logging.
-trace-stream-events	-t	Enable tracing of streaming events as ‘ETL’ log. May have high runtime impact. Note that you may need to run the SteamVR process in admin mode in order for certain traces to be captured.
-trace-local-events	-tle	Enable tracing of local events to xml file in log folder (see Local Event Traces (CloudXR Visual Profiler).
-trace-qos-stats	-tqs	Enable tracing of QoS statistics to a csv file. May have high runtime impact.
-dump-images	-d	Dump streamed images to log folder periodically (currently every 300 frames).
-capture-client-bitstream	-ccb	Capture the client-received video bitstream to CloudXR log folder on client.
-capture-server-bitstream	-csb	Capture the server-sent video bitstream to CloudXR log folder on server.
-dump-audio	-da	Dump sent/received audio streams to CloudXR log folder.
-embed-server-info	-esi	Embed server information in frames during streaming.
-embed-client-info	-eci	`Windows-only` Embed client information in framebuffers.
-log-privacy-disable	-p	Disable privacy filtering in logging.
-disable-ir-decoder	-ird	`Android-only` Disable AImageReader decoder on Android devices
-fallback-decoder	-fbd	If available, try to use a fallback video decoder for the platform.
-windowed	-w	`Windows/Linux-only` For desktop OSes, render to a standard window rather than to a connected HMD.
-no-button-remap	-b	Do not remap various controller buttons to SteamVR system menu and other functions.
-max-res-factor N	-m N	Maximum stream resolution as factor of given device res (oversampling). Value range is 0.5-2.0, default is 1.2 if not otherwise specified in client application code (which might want to explicitly set `maxResFactor` to 1.0 for no oversampling). If value is set to zero for any reason, internally the factor is set as 1.0.
-latency-test	-l	Runs local latency testing, where screen is black when no input, changes to white with input. Helps to determine local presentation cost.
-enable-alpha	-a	`Windows/Linux-only` Enable alpha streaming and display (sets client `deliveryType`)
-enable-send-audio	-sa	Enable sending audio to the server (i.e., microphone capture). Disabled by default.
-disable-receive-audio	-dra	Disable receiving audio from the server (i.e., play server audio on client). Enabled by default.
-log-max-kb N	-lmk N	Maximum log size in kilobytes. Value range is -1 to 1024², where values 1+ specify KB size to cap (so max is 1GB file), -1 resets to system default (5MB), and 0 sets to uncapped.
-num-video-streams N	-ns N	In Generic streaming mode, this option specifies number of video streams opened from server to client and will depend upon a custom server application that sets up custom streams. Value range is 1-6.
-graphics-type S	-g S	Choose graphics context type if need to override for some reason. Options are `gles`, `cuda`, or `d3d11`.
-user-data S	-u S	Send a user string to the server to exercise user data support.
-foveation N	-f N	Enable foveated scaling at given percentage scale. Values from 25-100 as a percentage scale factor on original frame to destination post-foveated frame size. 0 to disable (or to override an options text file value from the command-line). Defaults to 0. We strongly recommend that you always enable for VR use. Suggested value is 50 percent, using `-f 50` or explicitly preset in client code in `foveatedScaleFactor`)
-network-interface-client	-nic S	Choose the client network interface used to connect to the server. Options are `ethernet`, `wifi5ghz`, `wifi24ghz`, `mobilelte`, or `mobile5g`.
-network-topology	-nt S	Choose the network topology between the client and server. Options are `lan` or `wan`.
-enable-l4s	-l4s	Enable L4S congestion handling.
-requested-refresh-rate	-rrr N	Run the CloudXR Oculus Quest 2 client at the requested refresh rate. For example to run at 90Hz use `-rrr 90`. Running CloudXR at values greater than 90Hz are untested and not guaranteed to work.

ARCore Client Command-Line Options¶

Long Format Name	Abbreviation	Description
-env-lighting N	-el N	Send client environment lighting data to server. Values are 0 or 1, 0 disables, 1 enables. Default is 1/enabled.
-res-factor N	-rf N	Scales down the client resolution sent to server to help manage encode/decode and bandwidth costs for high-res devices. Value range is 0.5-1.0, with a default of 0.75.