 |
|
Dec 5th,2008 |
| Brief
Explanation of how Mental ray shaders work in general. |
What is
Mental ray Shader? A Shader is a plug-in module written
in C or C++ that is loaded by mental ray at runtime. In
general mental ray shaders are divided into types with
different purposes. Followings are a brife list of these
shaders:
Material Shader,Texture Shader,Shadow
Shader,Photon Shader,Volume Shader,Geometry Shader,etc.....
In this tutorial we will be focused on Color shader
since it is the simplest shader that can specify a
single color for an object.You may want to ask how
mental ray calculate these shaders?, The simple answer
would be that Mental ray works by shooting rays from
camera into the scene to test and see if objects in the
scene are hit by these rays. In case they are hit by
rays, mental ray has to figure out where they hit the
object, what material shader they have, and then pass
all these information back to mental ray. In this
tutorial the shader only return the same color no matter
where the ray hits the object surface. This cause the
same effect as a simple constant shader. |
|
| What Tools you
need to start? |
To write all
your shaders you need to have Microsft Visual Studio
2008 or in case you don’t have one you can download a
free version of MS VC Express 2008. Also you need to have all the headers and libraries
for mental ray 3.6+ to write and compile your shaders.
|
|
|
How to setup
Visual Studio C++? |
The first step is to open up Visual Studio and make sure
that you have setup all the path to Mental ray headers
and libraries.
To do that go to
Tools-->
Options --> under Project and Solutions
click on VC++ directories.
Next define the path for both "include" and "Library"
under "show directories for".
In Lib folder you should have:
Shader.lib
In
Include folder you should have following header files:
Shader.h, mrpoly.h, mirelay.h, miaux.h,
mia_material_api.h, mi_version.h,
mi_shader_if.h,matrix.h, geoshader.h, Contour_structs.h,
Contour_info.h
 |
|
 |
Next Step is to make a new project. Under project type
select win32 and then "Win32
Console Application".
Then select a name for your project for instance
HS_SimpleColor and hit Ok.
Once you hit Ok , "Win32
Console Application Wizard"
pops out. Select Application Settings and under
"Application type" make sure "DLL"
option is checked. Also, since we are writing everything
from scratch make sure "Empty
Project"
is checked as well. (Shaders can be provided as source
code or object modules, but are most commonly collected
into shared libraries (
Dynamic
Shared Object (DSO) on Unix,
or Dynamic Link Library (DLL)
on Windows NT).
Next "Right Click" on "Source files" and then select C++
file(.cpp). Here you call your shader name "
HS_SimpleColor".
Now you are ready to start coding but before that you
need to do one more thing. Go to project properties
"Alt+F7" and add
Shader.lib
to "Additional
Dependencies"
and hit Ok.
|
|
|
Source Code Explanation |
Before starting to code you need to know about typical
structures of a shader.
1-
Library Function Declarations:
#include "shader.h"
2- Version Function:
int HS_SimpleColor_version(void) {return 1;}
This
Line of code allows mental ray to guarantee that the
scene file declaration and the argument of the C++ file
are the same.
3-
Parameter Structure:
struct HS_SimpleColor {
miColor Color;
};
The
parameter structure is typically defined in the same
source file as the shader function which uses it as a
data type for its parameter arguments.
4-
Shader Function:
miBoolean HS_SimpleColor(miColor *result, miState *state,
struct HS_SimpleColor *param)
{
miColor *Color = mi_eval_color(¶m->Color);
result->r = Color->r;
result->g = Color->g;
result->b = Color->b;
return miTRUE;
}
The function
that includes all the element in previous structure that
can be compiled and loaded at render time by mental ray.
Extern
"C" linkage declaration
extern "C" is meant to be recognized by a C++ compiler
and to notify the compiler that the noted function is
(or to be) compiled in C style.
It is not uncommon for C++ code fragments to be called
by non-C++ programs such as a C-based communication
software, COBOL based TP monitors and the likes.
However, global functions in C++ cannot be called by
non-C++ programs since the function name is very
different from the one supplied by the programmer. Why
is this? By default, the C++ compiler uses a technique
termed name mangling which incorporates the
function name with its signature (list of arguments) in
order to create a unique name for it, even in case of
overloading (this technique is used both for external
function and class member functions). (Danny Kalev)
Also note that that a function declared as extern "C"
cannot be overloaded, and that extern "C" declaration
can only be applied to global.
"DLLEXPORT"
linkage declaration
The dllexport is Microsoft-specific extensions to
the C and C++ languages. It enables you to export
functions, data, and objects to a DLL. functions.
Here is a
complete version of the code: |
|
|
|
#include "shader.h"
extern "C" {
DLLEXPORT int
HS_SimpleColor_version() {return 1;}
DLLEXPORT
miBoolean HS_SimpleColor(miColor *, miState *, struct
HS_SimpleColor *);
}
struct
HS_SimpleColor {
miColor Color;
};
DLLEXPORT
miBoolean HS_SimpleColor( miColor *result, miState
*state, struct HS_SimpleColor *param)
{
miColor *Color =
mi_eval_color(¶m->Color);
result->r =
Color->r;
result->g = Color->g;
result->b = Color->b;
return miTRUE;
} |
|
|
|
| Compiling The
Shader |
At this stage you are ready to compile your shader. By
default your shader is compiled in "Debug" mode change
this to "Release" mode since debug mode is used for
debugging your code and is not recommended for final
output. Press "F7"
to build your solution.
Now in your project folder you should have a folder
called " Release". You should have a file called "HS_SimpleColor.DLL".
Congrats, you are almost done!
|
|
| Scene
Construction |
A scene
description is a high-level "blueprint" of elements like
Geometric object, lights, camera, material, etc .....
The file format for our scene file is a simple text file
with extension "mi" (HS_SimpleColor.mi).
For our shader to be used to a scene, we need to specify
the names of the shader's parameters and their data
types in the scence file.
Let's take a look at our "mi" file (Notice # is used for
commenting)
|
#
*******************Maya User
Interface*********************
declare shader
color "HS_SimpleColor"
# Our Shader Name
(
color "Color", default 0.0 0.0 1.0
# Parameter Name, see Parameter Structure
)
version 1
# Optional but it is good to determine inconsistencies
between the declaration and the
C or C++ function during rendering.
apply material
# It is not used by mental ray, but can be referenced by
applications such as maya
to organize shader by result type in their menu
interface.
# *******************3dsmax User
Interface*********************
gui "HS_SimpleColor" {
control "Global" "Global" ("uiName" "HS_SimpleColor","category"
"Material")
control "Color" "color" ("value" 0.0 0.0 1.0, "range"
0.0 1.0)
}
end declare |
|
|
|
HOW TO MAKE AN ICON FOR YOUR SHADER |
This
section is optional, until now you can plug everything
we learned into Maya or 3dsmax and it should work fine.
Final touch is to have Icons to represent your shader
based on their functionality. In Maya you basically need
two Icon Formats (XPM (Maya
shader Icon)
and FTI (Hypershade
node icon
)). To
Convert your image files to XPM Icon you need to download
"makexpm-v1.0" from www.Highend3d.com.This tool will
convert XPM to BMP or BMP to XPM. Works on windows. Also
Make Sure your XPM Icon resolution is set to be (32*32).
To make your fti files you can use fti_exporter that
comes with Bonus tools.
|
|
HOW TO INSTALL
YOUR SHADER IN MAYA OR 3DSMAX |
|
For
Maya:
Copy the .mi in your maya/mentalray/include folder
Copy the .dll in your maya/mentalray/lib folder
Copy the .xpm in your My documents\maya\6.0\prefs/icons
folder
Add following lines of code to your
maya.rayrc
file:
link
"{MAYABASE}/lib/HS_SimpleColor.{DSO}"
mi "{MAYABASE}/include/HS_SimpleColor.mi"
For
Max:
Put the mi file into 3dsmax9\mentalray\shaders_standard\include.
Put DLL file into 3dsmax9\mentalray\shaders_standard\shaders
Add following lines of code to your
standard.mi
file:
link "HS_SimpleColor.dll"
mi "HS_SimpleColor.mi"
Here you can
download
all the files you need for this shader.
|
|
|
CONCLUSION |
|
|
|
In this
tutorial you learned how to make a simple constant color shader to be used in Maya or 3dsmax.Although the first
shader is simple but the same concepts can be applied to
more advanced topics in future. I hope this tutorial was
helpful for you as I enjoyed writing it. In case you
have any concerns or comments leave me a message at
hamed.sabri@gmail.com |
|
|
|
