Part 2 - The MOSAIC Actions tab and export process:
The "MOSAIC Actions" tab is the first tab in the interface (expanded by default) and is designed for quick access to the most common export related actions. It consists of several action buttons as well as a series of toggles for quick control of the export process. These toggles are meant to speed up exporting by controlling what gets exported as well as aid in building RIB packages for external use. As such the toggle states are only temporary and are not saved in registry nor do they control internal exporter states (those can be controlled in the MOSAIC Settings tab).
Now that I've defined what this tab is for let's talk a little about how MOSAIC exports. RenderMan compliant renderers read text files that use the .rib extension that contain RiSpec descriptions of the scene, objects, lights, meshes, materials, etc. The exporter creates these RIB files by cycling through everything in the project (datablocks) and translating them into text according to their MOSAIC settings (datablock properties), using defaults if there are no settings. This works very well in that the exporter doesn't need to maintain the entire scene in memory separately but instead just reads it from Blender.
These text files are exported in the folder specified by the export directory button in the MOSAIC Settings tab and the project folder specified in the Project Setup tab. The default export directory is "/tmp/" (like Blender) and the default project folder is "Mosaic", so the files will be exported to "/tmp/Mosaic". If the folder does not exist it will be created, also note that all projects will export to the export directory but each project can have a different project folder so its possible to export and render multiple projects at the same time (if you give them different project folders). The exporter will then create several folders in the project folder:
- Project Folder - contains main RIBs, renders and batch/shell scripts
- Archives - contains all RIB archives
- Cache - contains temporary export data such as depth files and shader info
- Maps - contains textures, optimized maps, and generated maps
- Shaders - contains shader source and compiled shaders
The Archives folder also contains the following folders which are self explanatory:
RIB files have a feature called read archive that allows one RIB to call another RIB, by default the project is setup to use read archive (which is why the project is broken down into several folders). The basic RIB flow is: the project starts as a main RIB in the project folder which calls a scene RIB in the Archives/Scenes folder which in turn calls RIBs from the other folders as needed. MOSAIC attempts to use instancing through this mechanism to minimize the number of necessary RIBs as much as possible. It's possible to use other archiving methods by selecting "Read Archive", "Delayed Archive", "Instance Object" and "Inline Code" where available (see the RiSpec for differences between these). The "Inline Code" selection is used to tell MOSAIC to "inline" the code in the next connecting RIB in the chain, for instance if the entire project is set to "inline" then everything will be exported into the main RIB. These archiving methods can be mixed however you like :)
Now that we know the basics of where and how the project is exported to RIB let's outline how the action controls effect the export process.
(R)ender Current Frame/Passes:
This will render the current frame as well as any render passes using the current frame.
This will render an animation using all frame ranges to all passes or Blender's Sta to End if no passes exist.
(P)review Selected Object/s:
This handy feature will only render the current selections from the same perspective as your last used Blender 3D view window using all scenes, lights and any data already created for scene (such as shadow maps, occlusion maps, photon maps, brick maps, etc). This is great for zooming in or looking behind an object for tweaking independently.
Purge Export Project Folder:
This will completely remove the project folder and everything in it effectively "cleaning" it. This is handy for preparing a RIB package (where you don't want anything unnecessary in it), or purging any potentially unused RIB files (from changing object names etc). This is also helpful because sometimes the exporter will get confused when old unused RIB files begin to clutter the project folder.
Note : MS Windows likes to lock folders for no apparent reason, so if you get an error it usually means that everything in the project folder is removed but the project folder itself wasn't (which is fine).
Render RIB Files:
Call the renderer to render the RIB files after export.
Generate RIB Files:
Generate the RIB files to render, this is handy if you already have the RIB files or you're tweaking them by hand and just want to render them.
Export Render Passes:
Whether or not to include the render passes during export. This is handy if you've already exported the passes in an animation but only want to export the current scene.
Update Auto Passes:
If on, MOSAIC will automatically rebuild auto pass scenes using their filters before exporting, this insures that changes to the beauty scene will be updated in auto map scenes. It's sometimes handy to turn this off if you don't want the content of an auto map to update.
Lets you controls whether .sl and .h shader files in Blender's text editor are exported.
Do you want to compile any shader sources exported ? This is handy when you just want the sources for a clean RIB package or have already compiled the shader and don't want to do it every time.
Do you want to export any images in Blender's image editor ? Which images are exported and how they are optimized can be controlled form the Project Setup tab.
Do you want to optimize the exported images ? This is handy when you just want the sources for a clean RIB package or have already optimized the images and don't want to do it every time.
This feature tells the exporter to only generate RIB for the selected objects. This is primarily meant to exclude complex objects that have already been exported that may be very slow to export. No matter what's selected the underlying scene RIBs as well as lights and material RIBs are always exported.
This simply compresses the text RIB files with GZip. Many RenderMan renderers automatically support GZip compressed file input, this can greatly reduce project file size which is very important for large projects rendered over a farm.
This will generate stdout and stderr output logs called OUTPUTLOG.TXT and ERRORLOG.TXT for the renderer, shader compiler and texture optimizer. These logs will be placed in the project folder for the renderer, Shaders folder for compiler, and Maps folder for the optimizer. This is of course handy for debugging problems from the command line or sending error logs to developers.
This is mainly intended to aid in distributing RIB packages. Depending on which kind of scene you're exporting you can end up with a lot of main RIBs and it becomes impossible to know which ones to render in what order for the passes. This generates a Windows .bat batch script and a Unix .sh shell script that can automatically render the RIBs in the right order.
Starts Blender's script help browser (just has a few MOSAIC web sites for online references).
I think you can guess this one ;)
One last note, a very handy benefit of using RenderMan for your projects is RIB's universality and the availability of tools and information. This allows you to package your scenes for distribution for many purposes, such as sending a test project for a bug report or analysis, or packaging a scene to be sent to a render farm, or testing a scene under a wide variety of renderers and features, or even sending a project for help on what you're doing wrong. If you send the blend file only then only a Blender user can communicate with you, but if you send RIB packages then many people can communicate with you (including Blender users). To create a fresh RIB package for universal distribution the process would be:
- Be sure that any shaders the project needs are either available to where you're sending the RIB package or include their sources in Blender so they'll be exported.
- Click "Purge Export Project Folder" to completely clear any existing data
- Make sure to ENable "Generate RIB Files", "Export Render Passes", "Update Auto Passes", "Export SL", "Export Maps", "Generate Log" and "Batch Scripts".
- Make sure to DISable "Render RIB Files", "Compile SL", "Optimize Map".
Once exported compress the project folder and distribute the archive anywhere you need.
Phew, this was a long one... next post will be about the settings tab and how MOSAIC deals with render presets, export toggles and shader libraries.
Thanks for reading,