Read and Write Mental Ray User Data

Submitted by nicolas.chaverou on Tue, 02/14/2012 - 00:22

During the time I worked on the integration of Golaem Crowd with Mental Ray as a shader plugin, I had two recurrent thoughts :

  • When I was on the geometry shader, it was something like : “damn this Developper Manual rocks: all is well documented, there are some inspiring samples, some tips… This is a real pleasure to develop stuff for this rendering engine…”
  • Then, I had to work on the material shader and it was more something like : “#@%! how the hell am I suppose to do that !!? This is a real nightmare to developp stuff for this rendering engine...”

How to write/read userdata? How to dynamically create a material and call it (if like me, you would expect that mi_call_material would do that, do not even think about it)? Add some silent crashing function calls and weird behaviors to the whole and you almost got it. Now, I better understand why Shader Writer is a real job: it requires a lot of patience, tenacity, courage and puzzle solving skills. Those guys are heroes…

What about internet and forums? Well, too many often for my poor nerves, I felt in this classic situation:
 

Wisdom of the ancients

Wisdom Of The Ancients
Source: http://xkcd.com/979/

Thus, as I now consider myself as an ancient, I feel this need to share my knowledge with the next generations of Mental Ray sorcerer apprentices. Please sons, spead the good word around you and never let another soul wander in the darkness again…
 

MRay Implementation

In this post, I’ll answer my first question : How to store user data in an object and read/write it in a shader ? In mental ray, arbitrary user data can be attached to any element in the scene, or stand by itself, for usage by a shader. User data can be attached to instances, objects, lights, instance groups… to extend the scene entity with extra data or attributes.

Why would you use them? Well, it could be efficient for varying the look of large numbers of object instances, adding simulation data usable by parallel jobs running in mental ray or sharing huge data between several shaders (e.g. data which could not get through the shading network)…

In my example, I considered two plugins :

  • myPluginOne writes data of type myStructData in the hit object (miObject);
  •  myPluginTwo reads this data and displays it.

//-------------------------------------------------------------------------
// myStructData – data struct to share
//-------------------------------------------------------------------------
struct myStructData
{
  int importantData;
};
    
//-------------------------------------------------------------------------
// myPluginOne – writes user data of type myStructData in the hit object
//-------------------------------------------------------------------------
miBoolean
myPluginOne(miColor* result, miState* state, void* paras)
{
  // get the hit object (which stores the userdata)
  miTag objectTag;
  if(mi_query(miQ_INST_ITEM, state, state->instance, &objectTag))
  {
    miObject* object((miObject*)mi_db_access(objectTag));

    // allocate your data struct
    // NOTE: it is important to dynamically allocate your struct data, else
    // mi_api_data_byte_copy will crash. As far as I can understand without
    // seeing the actual code, it is because it is deallocating the pointer
    // it receives upon exit.
    int data_size (sizeof(struct myStructData));
    struct myStructData* myData (((myStructData*)mi_mem_allocate(data_size)));

    // fill it
    myData->importantData = 42;
            
    // build a MRay data block
    // the first param of mi_api_data_begin corresponds to the name of the
    // block. If an already existing name is used, mi_api_data_byte_copy will
    // override its content
    mi_api_data_begin(mi_mem_strdup("myDataBlockName"), 0, (void*)data_size);
    mi_api_data_byte_copy(data_size, (miUchar*)myData);
    miTag userdataTag(mi_api_data_end());
    // append with the existing data (just in case)
    miTag appendUserdataTag(mi_api_data_append(userdataTag, object->userdata));

    // add it to the shader userdata block
    object->userdata = appendUserdataTag;

    return miTRUE;
  }

  return miFALSE;
}

//-------------------------------------------------------------------------
// myPluginTwo – reads user data of type myStructData in the hit object
//-------------------------------------------------------------------------
miBoolean
myPluginTwo(miColor* result, miState* state, void* paras)
{
  // get the hit object (which stores the userdata)
  miTag objectTag, userdataTag;
  if(mi_query(miQ_INST_ITEM, state, state->instance, &objectTag) &&
     mi_query(miQ_OBJ_DATA, NULL, objectTag, &userdataTag))
  {
    // get & check userdata
    int userdataSize(0);
    struct myStructData* myData(NULL);
    if(mi_query(miQ_DATA_PARAM_SIZE, state, userdataTag, &userdataSize) &&
       mi_query(miQ_DATA_PARAM, state, userdataTag, &myData) &&
       (userdataSize == sizeof(struct myStructData)))
    {
      // here you go
      std::cout << "What's the answer ? " << myData->importantData;

      return miTRUE;
    }
  }

  return miFALSE;
}

As always, any question, improvement suggestion, bug report is welcome and will help me to access perfection and all-wisdom. Finally I’d like to thank the LAMRUG (Los Angeles Mental Ray User Group) which website is a bible and whose owners are prophets!