RE_ShaderAtlas.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        Render Library (C++)
 *
 * COMMENTS:
 *      A collection of shader programs which can be retrieved with string tags.
 */

#ifndef RE_ShaderAtlas_h
#define RE_ShaderAtlas_h

#include "RE_API.h"
#include "RE_ShaderHandle.h"
#include <UT/UT_StringMap.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_SharedPtr.h>

class RE_Render;
class RE_Shader;

typedef UT_SharedPtr<RE_ShaderHandle> RE_ShaderHandlePtr;

/// A Shader Atlas is a collection of related shaders identified by tags.
/// It has its own simple file format which associates .prog shader files with
/// a set of tags. To retrieve that shader, supply the list of tags.
class RE_API RE_ShaderAtlas
{
public:
     RE_ShaderAtlas(const UT_StringRef &shader_atlas_file);
    virtual ~RE_ShaderAtlas();

    // Load an atlas file. Does not load all the shaders,
    // just their definitions.
    bool        loadAtlas();
    
    // Return the bit corresponding to a string tag, needed for getShader().
    // These should be cached to avoid string ops, often right after loadAtlas.
    exint       getBit(const UT_StringRef &tag) const;

    // Return the shader matching the tags (exact matches only)
    RE_Shader *getShader(RE_Render *r, exint shbits) const;

    const UT_StringHolder& getFilePath() const { return myAtlasFile; }

    // This is mostly for debug (glslcompile)
    const UT_Map<exint, RE_ShaderHandlePtr> &shaders() const { return myMap; }
    const UT_StringMap<exint>               &bits() const { return myBits; }

    void                 printTags(exint tags);
protected:
    void        applyDefsToMatchingShaders(const UT_StringArray &tag_stack,
                                           UT_WorkBuffer &defines);
    void        addShader(const UT_StringArray  &tag_stack,
                          const UT_StringArray  &tokens,
                          const UT_StringHolder &program,
                          UT_WorkBuffer         &defines);
    bool        addShader(exint key,
                          const UT_StringHolder &program,
                          const UT_StringHolder &defines,
                          bool check_for_abs_path);
    virtual 
    RE_ShaderHandlePtr createShaderImpl(const char *program,
                                        const char *defines);
    exint       registerTokens(const UT_StringArray &tokens);

    UT_Map<exint, RE_ShaderHandlePtr> myMap;
    UT_StringMap<exint>           myBits;
    int                           myMaxBit;
    
    UT_StringHolder               myAtlasFile;
    UT_StringHolder               myAtlasDir;
    bool                          myAtlasLoaded;
    bool                          myAtlasValid;
};

// sample.patl:

// // This is a sample program atlas file.
// shaded
// {
//    . shaded_geo.prog
//    wire shaded_wire.prog
//    flat
//    {
//      . flat_shaded_geo.prog
//      wire flat_shaded_wire.prog
//    }
//    vertnorm shaded_geo.prog : "#define VERTEX_NORMALS"
// }
// wire wireframe.prog
// wire hidden hidden_line_wire.prog
// tangent APPLYTO vertnorm : "#define USE_TANGENTS"

// atlas->getShader(ren, atlas->getBit("shaded") | atlas->getBit("wire"));
//    returns the shader program shaded_wire.prog.
// atlas->getShader(ren, atlas->getBit("flat") | atlas->getBit("wire"));
//    returns null, no such shader

// NOTES:
// - putting a tag before {} adds it to all programs in that group.
// - multiple tags can be applied on the line the program is specified on.
// - '.' acts as an empty tag (no tag specified)
// - '@' in place of a shader filename will use the last entry's filename
// - It is an error to have 2 or more shaders with the exact same set of tags.
// - A shader can be referenced by more than one set of tags, a unique instance
//   will be returned for each set.
// - : "" can be specified after a program file to inject the text within ""
//   to the top of all shader files' text. This can be used to further vary
//   the shader code by use of #ifdef's in the shader text.
// - DUPLICATE will apply the preceding tag(s) and define to all existing
//   shaders that are tagged with the following matching tag(s). The matching
//   tags may be zero, in which case all existing shaders are affected.
//   "Existing shaders" means every shader previously created at that point
//   in the file. In the example above, all shaders with the 'vertnorm' tag
//   are duplicated and the 'tangent' and "#define USE_TANGENTS" tag added to
//   the new copies.
// - if the DUPLICATE matching tag list includes '^' then tags after the '^'
//   will be treated as an exclude list. The DUPLICATE will only apply to 
//   shaders that do not have any tags from the exclude list

#endif