Managing LightWave 3D ScreamerNet LWSN Config Files

Managing LightWave 3D ScreamerNet LWSN Config Files introduces you to LightWave’s config files and the settings used by ScreamerNet LWSN. LightWave’s Config Files are plain text files that store basic configuration information for LightWave and ScreamerNet. It’s very important that you know where these config files are located so that both LightWave and ScreamerNet can access them. It’s also important to understand which ScreamerNet relevant settings are stored in the config file, and how to use them.

Managing LightWave 3D ScreamerNet LWSN Config Files
Online Documentation Contents

Creating and Updating LightWave 3D ScreamerNet LWSN Config Files
LightWave 3D Config Folder Path, Defaults and Locations
- Default LightWave 3D Config Folder Path on Mac OS X
- Default LightWave 3D Config Folder Path on Windows
Custom LightWave 3D Config Folder
Config Settings for LightWave 3D ScreamerNet LWSN

Creating and Updating LightWave 3D ScreamerNet LWSN Config Files

LightWave only updates the config file when you quit the program. Therefore anytime you make changes to any of the config settings (other than menu or shortcut changes which are saved when you close the respective editor) you must be sure to quit LightWave to ensure that the changes are written to the config file itself. ScreamerNet only reads the config file when first launched. Therefore, if you wish to make changes to the config file for ScreamerNet and you are using a single config file for both Lightwave and ScreamerNet, you should perform the following steps:

Quit ScreamerNet LWSN if running.
Launch LightWave Layout.
Make changes to the desired config settings in LightWave Layout, as discussed later.
Quit LightWave Layout to write the changes out to the config file.
Re-launch ScreamerNet LWSN so that it reads the updated config file.
Re-launch LightWave Layout if you’re using the built-in network controller to manage ScreamerNet.

LightWave 3D Config Folder Path, Defaults and Locations

LightWave 3D Layout, Modeler, Hub and ScreamerNet LWSN use a few configuration files, or config files to store various information between launches.

When writing out such paths (such as for LWSN command lines) on Mac OS X always make sure to use the Unix separator “/” (forward slash). On windows use the DOS separator “\” (back slash). Enclose the path in quotes if the path includes spaces, or even if it doesn’t just to be safe.

LightWave automatically scans plugins when launched. If you wish to add custom third-party plugins then an easy way is to create a 3rdParty folder inside the support/plugins/ folder inside the LightWave 3D folder and put any new 3rd party plugins into that folder so that they will automatically load.

If you run into problems with LightWave 3D ScreamerNet and suspect a corrupted config file, you can simply delete the config file. Then launch and quit LightWave Layout and it will create a new default config file.

Default LightWave 3D Config Folder Path on Mac OS X

On Mac OS X the full default path for the config folder is:
"/Users/userx/Library/Application Support/NewTek/LightWave/2015.2/"

Replace userx with your actual user name, and 2015.2 with your version of LightWave. The default Config File folder is in the Application Support folder in the Library folder of the current user’s home folder. This would mean that any config files kept in this default location would only apply to this user as each user would have their own set of config files on this Mac in each of their own home folders.

The config files are named as follows:

Layout 2015.2 : Basic Layout Settings
Modeler 2015.2 : Basic Modeler Settings
Extensions 2015.2 : User plugin paths
Extension Cache: Scanned plugin paths
Hub 2015.2 : Basic Hub Settings

Up to Mac OS X 10.6 Snow Leopard the user’s Library folder is visible in their home folder. In Mac OS X Lion (10.7) or later the user’s Library folder is hidden but you can still access it by using the Go->Go to Folder… menu item in the Finder and typing ~/Library into the text field, which tells it to open the current user’s Library folder.

Alternatively on Mac OS X you may create a custom folder named Preferences within the LightWave3D application folder and LightWave Layout, Modeler and ScreamerNet LWSN will use that folder as the default to create a new set of config files. This alternate default path would be:

"/Applications/NewTek/LightWave3D_2015.2/Preferences/"

Where 2015.2 is replaced with the version of your LightWave 3D.

This can be useful if you have multiple builds of LightWave on the same Mac. It’s also useful if you want multiple users on the same Mac to all use a single set of config files because they’d be stored in the common Applications folder rather than in the user’s Library folder or to copy the configs to other computers along with copying the LightWave 3D folder for other network render nodes.

Default LightWave 3D Config Folder Path on Windows

On Windows the full default path for the config folder is: "C:\Users\userx\.NewTek\LightWave\2015.2"

The Windows config files names are:

LW2015.2-64 : Basic Layout Settings
LWM2015.2-64 : Basic Modeler Settings
LWEXT2015.2-64 : User plugin paths
Extension Cache-64: Scanned plugin paths
LWHUB2015.2-64 : Basic Hub Settings

Because these are running on a 64 bit version of Windows the file names end in “-64”.

Custom LightWave 3D Config Folder

You don’t need to specify any of these default config files by name, only the path to the folder where they are stored, and that’s only if you decide to keep your config files in a custom location other than one of these default locations. If you leave the config files in one of these default locations, you do not need to specify their path for LightWave, Modeler, the Hub, or for ScreamerNet (lwsn). DLI_SNUB-Launcher and DreamLight Constellation will also automatically locate the same default config folders that LightWave does.

You may wish to use a different custom config folder for ScreamerNet in some situations, such as:

When running ScreamerNet over a network with a common set of configs for all nodes.
When running ScreamerNet for multiple users with a common set of configs for all users.
When running ScreamerNet over a network and using separate configs for machines with varying resources, such as available RAM or number of processors/cores.

If using a custom config folder location for ScreamerNet then you would need to supply the config folder path to LWSN, DLI_SNUB-Launcher and DreamLight Constellation.

Config Settings for LightWave 3D ScreamerNet LWSN

The following settings are stored in the LightWave Layout config file and are used by LightWave 3D ScreamerNet LWSN Config Files: Content Directory, Command Directory, Default Segment Memory, and Multithreading.

Content Directory

Sample Content Directory entry from the config file on Mac OS X:
ContentDirectory /Users/userx/Documents/DLI_SuperBalls/

Sample Content Directory entry from the config file on Mac Windows:
ContentDirectory C:\Users\userx\Documents\DLI_SuperBalls

The content directory or Content Folder is a folder that contains all the asset files needed for a project in a specific organization for LightWave 3D ScreamerNet. It usually contains a full compliment of special sub folders for the various types of files contained in the project, such as Images, Objects, Scenes, etc. If you wish to use ScreamerNet (lwsn) successfully you must learn to properly use LightWave’s Content Folder structure to package your projects correctly or you will run into problems attempting to render them in ScreamerNet.

A Content Folder in LightWave 3D is very similar to a Web site’s root folder. When used properly, all necessary file paths are specified relative to that root folder, and all files are located in sub folders of this root folder. This means the project’s root folder is a self contained unit that may be moved as desired, including to other machines, without breaking all the dependent file/folder links.

In LightWave, the Content Folder itself may be named whatever you like, but there are some specific sub folders that LightWave expects to find inside the Content Folder that you should not rename or move. The most common of these special sub folders are named Images, Scenes & Objects. For a list of other possible sub folders look at LightWave Layout’s Paths tab on the Preferences panel. These sub folders are where you should store all your image, scene and object files respectively, for a project. You may name your files anything you wish (being sure to use proper file extensions), as long as you place them inside the proper sub folders.

In addition to ScreamerNet‘s normal uses of the Content Folder, DreamLight Constellation also uses the Content Folder for local/remote and cross-platform path remapping, features that the stock built-in ScreamerNet LWSN lacks. So for best results you should also put the Command Folder (Commands), RGB Output Folder (Renders) and Log Folder (Logs) inside the Content Folder so that all render nodes can locate all the necessary folders.

There are two approaches to effectively organize the Content Folder. Using a separate Content Folder for each project, or using a single master Content Folder for all your projects.

DLI_SuperBalls prebuilt sample Content Folder

Using a Separate Content Folder for Each Project

If you generally only need to render one project at a time, your projects don’t typically share assets and you don’t mind resetting the Content Folder in DreamLight Constellation and DLI_SNUB-Launcher for each project you render, then you can keep each project in its own self-contained Content Folder. In this case simply put all of the project’s objects in an Objects folder, all the project’s images in an Images folder and all the project’s scenes in a Scenes folder within the project’s Content Folder. The included DLI_SuperBalls sample content is structured as such a prebuilt Content Folder ready for use in the following tutorials.

NOTE: You can easily create such a self-contained Content Folder from any LightWave scene in Layout, even if it is not already properly structured and it accesses objects and images from far-flung folders. Simply open the scene in LightWave Layout, select File->Package Scene, select a destination folder and click the OK button. This will copy the scene and all associated asset files into a new properly structured Content Folder that may then be successfully rendered with ScreamerNet lwsn.

How to Structure a Multi-project Content Folder

Using a Single Common Content Folder for Multiple Projects

If you often need to render multiple projects at the same time, your projects typically share assets or resetting the Content Folder often would be inconvenient, then you can organize a single common Content Folder for all your projects to share. If all projects use the same common Content Folder then you may leave ScreamerNet running and rendering while adding new scenes to DreamLight Constellation‘s Scene Queue to render as needed, without having to keep changing the Content Folder for each project.

The trick to organizing a common Content Folder is to make separate folders for each project inside each of the Images, Objects and Scenes folders. Those project specific sub folders may be named anything you like, but the enclosing folders at the top level of the Content Folder must be named Images, Objects and Scenes, unless you explicitly changed those names in LightWave’s path preferences panel.

Setting the Content Directory in the Config File

The ContentDirectory entry is not actually written to the config file until you Quit LightWave after specifically setting a Content Directory or by allowing LightWave to automatically change the Content Directory when loading a scene file. You may explicitly set a Content Directory as follows.

Launch LightWave Layout
Select: Edit->Set Content Directory… & Choose your desired Content Directory folder,
or open a scene file and click Yes when asked if you’d like to change the Content Directory.
Quit LightWave Layout, to actually save the changes to the config file.

Command Directory

Sample Command Directory entry from the config file on Mac OS X:
CommandDirectory /Users/userx/Documents/DLI_SuperBalls/Commands/

Sample Command Directory entry from the config file on Windows
CommandDirectory c:\Users\userx\Documents\DLI_Superball\Commands

Believe it or not, LightWave really doesn’t do any “network” rendering. Neither LightWave nor ScreamerNet LWSN really has any idea that it may be communicating over a network or even that any network even exists. All LightWave does is write simple text commands into a job command text file in a common Command Directory. Then each ScreamerNet LWSN render node simply reads those text commands from the job text files, executes the commands and writes a text reply into an ack (acknowledgment) text file in the same Command Directory. What makes this work over a network is setting it all up so that each machine has read/write access to the same Command Directory folder.

The Command Directory is the folder that contains the job command file and the acknowledgement ack file. These are two plain text files that the ScreamerNet controller uses to communicate with each ScreamerNet LWSN node during batch or network rendering.

The communication goes like this:

The ScreamerNet controller creates a job file.
The ScreamerNet controller writes a command into the job file.
The ScreamerNet lwsn node reads the command from the job file.
The ScreamerNet lwsn node performs the command.
The ScreamerNet lwsn node creates an ack (acknowledgment) file.
The ScreamerNet lwsn node writes a reply to the ack file.
The ScreamerNet controller reads the reply from the ack file to decide what’s next.

These files are named: job# and ack# where # is replaced with the number of the ScreamerNet lwsn node to control. If only one instance of ScreamerNet lwsn is being used these files would be named job1 and ack1. For a second instance of ScreamerNet lwsn, they would be named job2 and ack2, etc. No ".txt" extension is used on the filenames. Also note that there is no leading zero, space or anything else between the number and the words job or ack.

Both the user running the ScreamerNet controller (LightWave’s Network Render panel, DreamLight Constellation or another third party controller) and the user running ScreamerNet LWSN (if different) must have read/write access to the same Command Directory. Non-administrator users don’t typically have write access to the Applications directories on Mac OS X. Therefore, rather than using a Command Directory in the LightWave 3D folder, I prefer to use a shared Content Directory, with read/write access for all network users, and keep everything inside this shared Content Directory, including my ScreamerNet Command Directory folder folder that I name Commands (DreamLight Constellation will default the Command Folder to a Commands folder inside the default Content Folder).

Setting the Command Directory in the Config File

Here’s a step-by-step example of how to configure such a simple self contained Content Directory with its own Command Directory folder.

Launch LightWave Layout.
Set LightWave’s Content Directory with: Edit->Set Content Directory…
to your desired Content Directory folder.
Select: Render->Network Render
Click the Command Directory button.

Navigate to the same Content Directory you set in step 2.
Create a New Folder named Commands inside the Content Directory.
Click the Choose button to close the dialog and accept the changes.
If asked to initialize the ScreamerNet, click No (we’re not ready to render yet).
Quit LightWave Layout to save your changes to the config file.

Default Segment Memory

Here is a sample Default Segment Memory entry from the config file:

DefaultSegmentMemory 32000000

This is the maximum number of bytes to use for the rendered image segment memory. It defaults to 32 million bytes which is just under 32 Megabytes. This only affects the memory allocated for image buffers used in rendering the image itself, it doesn’t affect the amount of RAM used to load objects, textures etc. The number you set is the maximum upper limit. LightWave will only use as much RAM as it needs for the actual render buffers, up to this limit. If more memory is needed, LightWave will break the image up into as many segments as necessary so that each fits within the segment memory limit. In general you want this number set high enough for an entire frame to be rendered within one segment, as long as it fits comfortably within your machine’s physical RAM capacity, while still leaving enough physical RAM free for objects, textures etc.

This value is set in the Render Globals panel (typically while a scene is open) but is stored in the Config file, only if you say yes when asked to use the changed value as a new default. It is never stored in the scene file, and is not stored anywhere if you click no when asked to use the changed value as a new default. In that case it will only affect a render in the current session of LightWave itself until you quit LightWave. The next time you launch LightWave the old value in the config file will be reinstated.

Setting the Default Segment Memory in the Config File

Here’s a simple step-by-step example of how to set the Default Segment Memory

Launch LightWave Layout.
Open the Render->Options->Render Globals panel.
Set the resolution to whatever you wish on the Camera tab.
Notice the readout directly under the Segment Memory Limit button on the General tab.
If it lists more than one Segment then you may want to increase the Segment Memory Limit.
Click the Segment Memory Limit button.
The Segment Memory Limit dialog opens, with the current DefaultSegmentMemory config value.

(NOTE: This number is in millions of bytes, not megabytes. The rounded integer shown is simply multiplied by 1,000,000 when stored in the config file. A true Megabyte of RAM is actually 1024*1024 = 1,048,576 bytes. )

Enter an integer that is equal to the old number multiplied by the number X that was displayed in the readout Segments:X from step 5. For instance, if the old value was 32, and the readout said: Segments:2, you could enter 64 into the field, to be sure to be able to render the entire frame in one segment.
Click the OK button.
You will now see a dialog that asks: “Should this value become the new default?” Yes/No. You must click the Yes button, or the new value will not be stored anywhere and will only persist during this session of LightWave until you quit LightWave Layout.
The readout below the Segment Memory Limit button should now read: Segments:1
Quit LightWave to actually save the change to the config file.

You may also simply locate and edit the line DefaultSegmentMemory 32000000 in your config file directly in a text editor. Simply change the leading integer from 32 to whatever you desire (followed by six zeros) and save the config file. Make sure your text editor keeps the file as a plain text file and doesn’t add any file extension to the config’s filename.

Multithreading / RenderThreads

Here is a sample Render Threads entry from the config file:

RenderThreads 0

This is the number of concurrent threads (strings of commands) to execute during rendering. A setting of 0 in the config file corresponds to a setting of Automatic in the Render Globals panel and allows Layout/ScreamerNet lwsn to use as many threads as the computer supports, so a 12-Core/24-Thread Mac Pro would use 24 render threads. In the Activity Monitor it will show more threads than that since additional threads are used for support functions, but the heavy rendering will be limited to 24 threads.

In general you’ll get the best results by using the automatic setting and running one ScreamerNet lwsn node on each computer. This way you can run the minimum number of nodes using the maximum number of threads on each computer. In some cases though, if your particular scene primarily uses single-threaded processes or plugins then you may get better results running multiple nodes per computer set to use fewer than the full number of threads, such as 2 ScreamerNet lwsn nodes, each set to 12 threads or 4 nodes each set to 6 threads. One thing to keep in mind though is that running multiple instances of lwsn means you’ll be using multiple times as much memory as a single instance. So if memory is an issue you may still want to run single instances per computer. Another reason you may want to set it to use less than the maximum number of threads on your computer is if you want to render in the background while still using the same computer to do other work. In that case you may want to limit the render threads so that your computer still has plenty of horsepower available for your other work.

Since the Multithreading setting is stored in the config file (as RenderThreads), if you wish to change it, be sure to check/set the Multithreading setting in LightWave (or directly check RenderThreads in the config file with a text editor) and quit LightWave Layout to be sure the config is written to disk, prior to launching ScreamerNet LWSN.

Setting the Multithreading / RenderThreads in the Config File

Here’s a step-by-step example of how to set the Multithreading/RenderThreads setting with LightWave Layout:

Launch LightWave Layout.
Open Render->Options->Render Globals
Click on the Render tab.
Set the Multithreading pop-up menu to Automatic or a specific number of threads, as desired.
Quit LightWave Layout, to write the change to the config file.

You may also locate and edit the RenderThreads line in your config file directly in a text editor. Simply change the number to 0 for automatic or 1, 2, 3, 4, 8, 12, 16, 24, 32 or 64 as desired and save the config file. Make sure your text editor keeps the file as a plain text file and doesn’t add any file extension to the config’s filename, or it will not load properly.

Managing LightWave 3D ScreamerNet LWSN Config Files
Online Documentation Contents

Creating and Updating LightWave 3D ScreamerNet LWSN Config Files