Tuesday, July 08, 2008

MOSAIC feature ramblings - part 1

Greetings RenderMan enthusiasts,

After a great deal of work I've decided it's time to start documenting some of the features that have been added to MOSAIC since the first download package was released 9 months ago. At this point there's a bunch of new features that aren't mentioned in the Wiki and I still have a way to go before I can update it... so in the mean time I thought it would be good to write a series of blogs that are loosely structured explanations instead.

These will just be ramblings of anything I feel is helpful or I'm concerned will be forgotten, which will hopefully help me document and structure my thoughts for re-writing the Wiki later on. I'm not sure how many posts I will do but I plan on beginning with not so obvious features in Blender then covering MOSAIC tab by tab, and finally pulling it together to show some basic techniques.

Let me also say that some of the things I will mention involving direct integration in Blender are likely to change as I'm currently rewriting the built-in shaders to directly access most of Blender's important settings "out-of-the-box"... so let's get started :)

Part 1 - Overview of MOSAIC and obscure features:

I want to start off talking about several features that MOSAIC uses in Blender that some of you may or may not know are there! First let's cover some boring ground now to make it clearer later on, Datablocks. Blender stores the elements of a project internally into what are called datablocks. These datablocks are organized in a hierarchy according to the structure within the project itself:

  • Scenes

  • Objects

  • Meshes

  • Materials

  • Textures

  • Images

One very simple way to see this structure is to browse a project with Blender's outliner. This is important because all settings in MOSAIC's GUI are stored in them, this is key because the structure of MOSAIC's data is aligned to the datablocks in Blender which loosely represents the RIB scene's structure.

OK, enough tech rambling, if I didn't confuse you too much let's talk about what all this means to you.

Blender has a very interesting feature in the "file" menu called "append or link".

This allows you to either append (insert into your project) or link (constantly use from another project) datablocks from other blend files. This is of key importance because it allows building large libraries of content separately and then pull them together later.

One good example of using this is building a model that uses displacement baking.

To do this you would need a high res sculpted model and a low res SDS model that the high res is baked to at world origin. You couldn't rig and use the object without destroying the setup necessary to remake it (which means you wouldn't be able to tweak it later).

Instead you could setup a blend file for the baking and then link in the finished model, materials and textures to another project for rigging and animating, any changes you made to the baking project would automatically show up in other linked projects.

This will also work cleanly in MOSAIC because all properties related to RenderMan and MOSAIC are linked to the datablocks directly, so for instance all MOSAIC material tab settings would link with materials from other projects, etc.

Note : If you're techy and curious you can run a script in Blender's help menu called "ID Property Browser" that will let you browse MOSAIC settings on the datablocks directly.

This has been handy when trying to migrate old projects to a new version of MOSAIC with different property keys ;)

Another handy feature is MOSAIC's translation of border rendering.

This is the equivalent of RenderMan's RiCropping and allows rendering just a select region of the full render.

This is accessed in Blender by going to the "Render" menu, selecting "Set Render Border" and then clicking and dragging the region on the active 3D camera view window you want to crop.

MOSAIC automatically uses the cropping region for the current active camera per scene per pass as used.

To disable cropping in Blender goto the "Buttons" window and disable the "Border" toggle in the scene's "Render" tab.

One very hidden feature in MOSAIC is bounds visualization rendering. This is a scene debugging tool I've added to help visualize bound boxes during render. RenderMan renderers can be very picky about object bound boxes (especially when multiple objects bounds cross).

If you select an object in 3D view and go to the "Buttons" window and select the "Object" and "Object Buttons" panel you can change the objects draw type to "Bounds". Blender will show the object as just a bounds box, but if you render in MOSAIC you'll get the object surrounded in a blue transparent bounds box. This can also be handy for getting an idea of how much DisplacementBound to add.

A very important tool to MOSAIC (if you're doing custom code fragment work) is Blender's text editor. This can be accessed in Blender by just changing one of your windows to the text editor. This is just a normal text editor inside Blender with a few important exceptions, first, any texts created in the Blender project are automatically saved in the blend file regardless of whether they are saved to the file system (this includes texts loaded from the file system), and second, Python scripts have full access to these text files.

MOSAIC looks at the name of the text files to see if any are intended for use in MOSAIC, if a text name begins with "cf_", "ss_", "ds_", "ls_", "vs_", "is_" or ends with ".sl" or ".h" then MOSAIC will show it in the corresponding fragment menus or will compile it as a shader according to the extension (these can be changed to anything you want in the setup tab but not recommended).

Most of the code shader fragments can be automatically created and maintained in MOSAIC's utilities tab but can be edited by hand if you wish, "cf_" code fragments can contain any code you wish including MOSAIC tokens and can be inserted at the beginning or end of a RIB sections according to the menus in MOSAIC's interface. The code you write will be inserted in the RIB stream "as-is" with no rules or restrictions. MOSAIC tokens are primarily intended to be used in shader fragments and can be easily used in shader parameters in MOSAIC's utilities tab but they can also be typed by hand in any code fragment.

I also wanted to mention a few notes on MOSAIC's GUI.

Almost every control in the interface has a tooltip, if you're not sure what something does just look for a tooltip.

The GUI is intended to be used vertically but can semi-successfully be used horizontally.

The entire interface is broken down into color coded horizontal tabs prioritized from top to bottom.

Each tab can be expanded and collapsed by clicking it with the mouse.

When tabs pass beyond the current window the mouse wheel and up/down arrow keys can be used to scroll the entire GUI.

The "r", "a", and "p" keys are hot keys to call render, animate and preview.

Also you can right click and call the preview as well as collapse and expand all windows.

Something else to mention is if you have a Scene, Camera, Geometry, Lights or Material tab open and you change your selection in Blender the contents of those tabs will update the moment your mouse crosses back over MOSAIC ;)

When exporting the progress bar will scroll and report its progress, you can also get more detailed info during export by watching the console (as well as error reports and warnings).

Well that's it for now, next post I'll begin discussing some of the new and old features of MOSAIC's render tab :)

Thanks for reading,


  1. This is a very good and informative background. Especially using similarities between Blender's and RenderMan's scene file structures.

    In over 8 years of discussion and effort in Blender to RenderMan, I don't think I've seen any mention of this.

  2. When I began initially laying out the data structure and interface for MOSAIC I was surprised how well they meshed. Something I didn't mention is the export RIB file structure is also inline with the datablocks. Not very exiting stuff (unless your into that sort of thing) but potentially informative, especially when dealing with appending and linking projects together. I've also found the render cropping very helpful for previewing and testing.

    The next post will hopefully be a little more interesting to RenderMan users since it will deal with the exporting process and packaging RIB projects (still fairly techy thou). I think these posts wont start getting interesting to Blender users until I get to the utilities tab and start dealing with playing with shaders :)