Sample Code IV- Examing ISF files: ISFDoc

Making and working with ISFDoc
VVISF::ISFDoc is how you interface with ISF files- you can create a VVISF::ISFDoc from a path to a file on disk, or from the frag/vertex shader strings. When the doc is created, the JSON blob in the frag shader string is prased, and the VVISF::ISFDoc instance is populated with a variety of ISFAttrRef and ISFPassTargetRef instances that describe the contents and value of the ISF file. This allows the properties of the ISF document to be examined programmatically.

As with other classes in these libs, ISFDocRef is the preferred means of interacting with ISFDoc. Because it contains attributes and passes and lots of things that have value, performing a deep copy isn't something you want to do unnecesarily. ISFDocRef allows an instance of ISFDoc to be accessed simultaneously from number of different places (ISFDoc is threadsafe).

VVISF::ISFDoc performs a variety of important functions beyond introspection: it generates source code for GL shaders with all the appropriate variable declarations for the ISF variables, and it maintains the state of the inputs and render passes and is used by ISFScene when doing rendering, etc. Much of VVISF::ISFScene's logic revolves around getting values from and sending values to the VVISF::ISFDoc it's using to store and track the state/value of all the shader inputs used to render frames.

//  ISFDoc can throw a variety of exceptions, so we'll define it in a try block...
ISFDocRef       myDoc = nullptr;
try {
    //  You can create an ISFRef from a given file on disk...
    myDoc = CreateISFDocRef(string("/some/path/some_ISF.fs"));
    
    //  ...or you can create an ISFRef from frag/vert shader strings...
    myDoc = CreateISFDocRef(someFragStringVar, someVertStringVar);

}
catch (ISFErr & exc)    {
    cout << "ERR: caught exception: " << exc.genTypeString() << ": " << exc.general << "- " << exc.specific << endl;
}

//  print some basic information about the doc
if (myDoc != nullptr)   {
    cout << "successfully loaded ISF doc!\n";
    cout << "description: " << myDoc->description() << endl;
    cout << "file type: " << ISFFileTypeString(myDoc->type()) << endl;
    
    auto            attrs = myDoc->inputs();
    cout << "file\'s doc has " << attrs.size() << " attributes\n";
    ISFAttrRef      firstAttr = (attrs.size()<1) ? nullptr : attrs.front();
    if (firstAttr == nullptr)
        cout << "first attr is null\n";
    else
        cout << "first attr is " << firstAttr->getAttrDescription() << endl;
    
    auto            passes = myDoc->renderPasses();
    cout << "the ISF doc has " << passes.size() << " render passes\n";
}
else
    cout << "err: problem loading the ISFDoc!\n";