Downloading OSL shaders from GitHub and using in 3ds Max 2019

Downloading Stuff Correctly 

I've gotten a few error reports from people saying "I've downloaded this OSL shader from GitHub and it doesn't work, I get a syntax error" ...

Invariably, what has happened is that the user has gone to GitHub page, seen a listing like this and just right-clicked on a file and selected "Save As...."

The problem is, that link actually leads to an HTML page that is displaying the file with a lot of other info. Saving from this position will actually save the HTML file, not the OSL file displayed in it. No, 3ds Max doesn't parse the HTML for you, it wants just the OSL code.

What you need to do is to click on the file name so you see the page displayed:

Then, find the button marked "Raw". The "Raw" button is what actually links to the files contents. This is the place where you right-click and to "Save As..."

However, there is another way. On the 1st page, you noticed this button depicted on the right. It's a button that downloads the entire repository as a .ZIP file, that you can then drop on your computer, anywhere.

To use them, you can just load an "OSL Map" into your scene, click the button with ". . . . ." on it, and load any file from any of the directories you just downloaded.

But they don't work....?

Not all OSL shaders found online work in 3ds Max, because the 3ds Max implementation of OSL has some built in limitations. Most notably, the following things will not work:

• Any shader returning a closure. A closure in OSL is a construct that can be thought of as a material (or a BRDF). For various reasons, we do not support this in 3ds Max - only texturing shaders are supported - so these shaders won't do anything. Often, the do-it-yourself guy can often edited the shader to extract the useful bits and turn them into texture shaders that can be used.
• The shader uses an #include statement. If it's for the standard stdosl.h file, it can just be deleted (3ds Max includes that implicitly), and if it is for any other file, the contents of that file can just be pasted in in place of the #include statement.
• Any shaders using structs or arrays as inputs or outputs are not supported. In practice very few (if any) such shaders actually exist.

So in principle, any other well formed OSL shader, that has one or more outputs of the basic types of int, float, string, color, vector, point or normal should work correctly in 3ds Max.

Making OSL-shaders Auto-Load

Clicking ". . . ." buttons and loading shaders manually is all well and good, but what if we want to our OSL shaders to automatically show up in the material browsers, just like anything else in the OSL category?

This is easy. On startup, 3ds Max looks in a certain set of folders for files of the type *.OSL and loads them in. First, it loads in all OSL shaders found in the main OSL folder under the 3ds Max install directory.

Then, it walks through each folder listed in the Customize -> System Paths dialog on the 3rd Party Plug-Ins tab:

It looks for an OSL subfolder under each of the above folders, and loads any *.OSL files found in those. Any subfolders under that folder becomes subcategories in the OSL category in the material browser.

Auto-loading the entire 3ds Max OSL Github

You can either download the entire repository using the "Download" button as mentioned above, or you can actually install a GIT client on your computer and in a CMD window navigate to some suitable folder, and type

    git clone https://github.com/ADN-DevTech/3dsMax-OSL-Shaders

This will pull down the entire repository to that folder.

After you have the entire repository downloaded, you will find that it is intentionally structured such that there is a main folder called 3dsmax-OSL-Shaders and all the interesting stuff is in an OSL subfolder to that folder.

Sounds familiar, right?

Simply go to your Customize -> System Paths and the 3rd Party Plug-Ins tab, and hit the "Add..." button and add the location of your 3dsmax-OSL-Shaders folder there.

Any and all shaders from the OSL Github will from now on automatically be loaded into your material browser.

If you used the GIT command method to download the files, then to update that folder to the latest and greatest, you only have to navigate to that folder in a CMD window and type

    git pull

And BAM - Bob's your Uncle.

/Z