Yaf(a)Ray

Introduction

So what is Yaf(a)Ray?
It is my try (me == Mathias) to completely renew the YafRay core, because the old structure just reached its limit after years of evolutional changes. We reached a point where the integration of many new techniques require substantial changes throughout the whole core to be fully functional. I came to the conclusion that this would actually be more work than shattering the current code into pieces, design a new concept and glue them together with new code (although, currently there's more glue than shattered pieces to stay with the metaphore...)

Of course i do know that Alejandro has started a re-design codenamed "fry", however he had to stop at a point where the really important decisions (interfaces of classes etc.) were yet to be made, so instead of guessing what the inventor of YafRay would have done next, i again started from scratch. The whole thing mainly began in order to find out if i really could create a working renderer. I think the concept now is stable enough for more isolated code changes, that means other people can contribute more easily now, i only have that feeling that it will not happen nevertheless...
Documentation is perhaps the most critical part to prevent a fade into obscurity, i hope i find the time and motivation to document the design ideas more indepth, but you can already extract quite a few class an class member description via doxygen.
Speaking of obscurity, if you asked what the additional "a" in Yaf(a)Ray means, i don't want to speak it out too loud, let's just hope it does not become reality, okay?

Current Features

These are the current features
Note: Not all features are accessible from blender (yet)

• plugin based (as before), with following classes:
  • lights
  • materials (new, partially replaces shaders)
  • shaders
  • textures
  • backgrounds
  • cameras (new)
  • integrators (new)
• lights:
  • point
  • spot light
  • area light (rectangular, or parallelogramm actually)
  • mesh light (uses a triangle mesh as light source)
  • sphere light
  • directional (with optinal radius)
  • sunlight (basically a directional with incoming direction sampled from a cone)
  • environment light, with importance sampling for efficient image based lighting (even without GI)
• materials:
  • basic diffuse w. specular reflection, transparency and translucency, support for shader nodes on various properties
  • diffuse+glossy material (Ashikhmin&Shirley), Blinn or anisotropic microfacet distribution w. fresnel effect,
    shader nodes support on diffuse+glossy color, glossiness and bump
  • coated version of the above mentioned, adding specular reflection with fresnel effect (dielectric)
  • basic glass (dielectric) material, with fresnel, filter, absorption and dispersion
  • export of blender's texture layers as shader nodes
• textures:basic image textures (tga, jpeg, png, exr, hdr), cloud, marble, wood, voronoi, musgrave, distorted noise and "RGB-cube"
• backgrounds: constant, sunsky, texture, simple gradient
• cameras: perspective camera with DoF, orthographic camera, angular camera
• surface integrators (all still under construction!):
  • direct lighting with support for ambient occlusion and caustic photon maps
  • path tracing
  • photon mapping with final gather
• antialiasing
  • adaptive (simple color threshold based)
  • variable size reconstruction filters (box, gauss and mitchell-netravali currently)
• transparent shadows
• multithreaded rendering passes and radiance map creation
• basic XML writing and reading (using libXML) for scenes (see YafaRayXML for specifications)

Missing Features:

Yaf(a)Ray

• irradiance cache (at some point it will be back i hope)
• more complete texture mapping
• better bump mapping (provisional code currently...), normal mapping
• geometry instancing
• tone mapping of output (though better left to a post-processing tool IMHO, check out qtpfsgui for example...)
• and more...

Building

The code is still in the subversion repository where i started it all:
ssl.little-isp.de/svn/lynx/yafaray
To checkout, you will obviously need subversion ("svn"). The actual render core is in the mainline tree, and the blender export in the blender tree.
Note: The code is mainly tested on Linux (32 and 64bit) and Windows (32bit) and OS X (intel). Other platforms may require some work on configurations
Note: For additional information about customization etc. please read the "INSTALL" in the source tree.

Get Yaf(a)Ray, the render code:
svn co https://ssl.little-isp.de/svn/lynx/yafaray/mainline/ yafaray
The last argument is the name of your local directory that should be created. If you omit it, it becomes the last subdir of the path (i.e. "mainline" here)

Compiling Yaf(a)Ray goes pretty much the same way as YafRay, via scons. Note that you need at least scons 0.97 now, version 1.0 recommended!
For building the Python bindings (to use Yaf(a)Ray from blender without source code manipulations) you will also need SWIG

The list of libraries you need for a build with all features enabled became a bit longer though. Currently these are:
pthread (wrapper library for Windows)
libxml (for xml loader)
libjpeg
libpng
OpenEXR
freetype 2
zlib
Qt

If you want to build the Qt GUI, you need to enable Qt by adding WITH_YF_QT='true' in your user-config.py

The basic commands to scons are:
scons or scons build : builds the binaries
scons swig : build the Python bindings, found in bindings/python afterwards
scons install : install the binaries to your file system (*nix) or copy to win32pak for building an installer (windows)

If you are using the Visual Studio 8 Compiler, you can now get all libraries except Qt precompiled in SVN too:
svn co https://ssl.little-isp.de/svn/lynx/yafaray/libs
They were all (except libjpeg, which is from the old yafray repository) compiled with MSVC8 using dynamic runtime.
On Windows, the libs directory is assumed to be on the same level as the directory containing the sources. To achieve this, do the checkout commands in the same directory, for example if you do it in "C:\SomeDir" it should look something like:
C:\SomeDir\yafaray
C:\SomeDir\libs

On Linux, you should have no problem getting all the libraries via your package manager, as they are all used in well established linux applications. Just don't forget to install the developer versions (for headers and libraries) too.

Python based Blender export

The Python export scripts for blender can be checked out with: svn co https://ssl.little-isp.de/svn/lynx/yafaray/blender/python

These scripts obviously need to go into blender's scripts directory. For the scripts to work you also need to copy the python bindings to blender's scripts directory (see above for creating SWIG bindings with scons)

Building blender with Yaf(a)Ray export:

Get the export code for blender:
svn co https://ssl.little-isp.de/svn/lynx/yafaray/blender/

Note: This export code was only a temporary solution! Most people should be fine with Python bindings!
Note: Currently only SCons can be used to compile the modified blender!
We have to wait for the upcoming blender render API (still not ready to use despite a dedicated GSoC project...) for a less invasive and more seamless integration. Modifying and compiling blender to export to the new render engine needs a few more steps:
the files you checked out from .../yafaray/blender (as explained above) need to be copied (overwriting existing files) to where the old export code is located in the blender source tree. I.e. the checked out blender/yafray directory corresponds to my_blender_sources/source/blender/yafray.
The export code gets updated to work with current blender SVN trunk regularly, so there is no guarantee it still works with the last official release, but usually it does too.
Currently, there also is an absolute path in source/blender/yafray/SConscript. So open this file with a text editor of your choice and change the path assigned to YF_SOURCE to the path of your local yafaray source tree.

Usage

Note: There are several conceptual differences to YafRay, DO NOT EXPECT OLD SCENES TO LOOK SIMILAR OR EVEN THE SAME!
Currently rendering only works via the plugin, no matter if XML is used or not! This is because the XML file is not written by blender but by the yaf(a)ray core itself now, via the same interface used for direct rendering with render progress display. This was done to remove the duplication of major amounts of the export code.
Note: Because of this and the fact that the interface is still C++ you must use ABI-compatible compilers for blender and Yaf(a)Ray, even if you export to XML!
When "rendering" with XML enabled, only the XML file is written, the rendering does not occur automatically anymore. This is because the whole purpose of XML now is reduced to manual editing the scene before rendering from command line, there simply is no other benefit from XML. The XML loader is still very basic, the binary is called "testloader" and can be found in the build/testsuite directory after compilation.

Custom Properties

The exporter now uses the new ID Property mechanism of blender to store most of the yafray specific settings, which greatly helps to add custom properties to objects, materials etc. without adding any custom code to other blender parts. This is probably a big step forward for the integration of many external renderers.
Bert Buchholz started a script to edit all those settings. The script is now in SVN with the exporter code (see above on how to checkout) and called yafaray_ui.py. Installed to blender's script directory ( ~/.blender/scripts on Linux for example), it is directly accessible in the Render menu!

For specific cases not yet in the export script, or if you're just curious, you can also use the Python browser included in the scources to manually edit parameters.
When the scripts are copied to your scripts folder you can access the generic "ID Property Browser" via the Help menu.

List of abused blender settings

Since I wanted to keep the changes of blender sources as small as possible, and the future of connecting external renderers was (and still is) unclear, I initially re-used whatever there was, including some not-so-obvious abuses:

Others

Naming a material y_null creates a dummy-material (does nothing, it's just pitch black), useful for example to "swallow" photons you don't need, like the outside of a building when doing interior views etc. which saves time on creating the radiance map for example.

More Documentation

A (still incomplete) list of parameters the various scene elements take can be found here: YafaRayParameters
More technical details about the blender export can be found here: YafaRayBlender
Informations on the new XML format: YafaRayXML

to top