Home | History | Annotate | Download | only in glsl
      1 /* -*- c++ -*- */
      2 /*
      3  * Copyright  2010 Intel Corporation
      4  *
      5  * Permission is hereby granted, free of charge, to any person obtaining a
      6  * copy of this software and associated documentation files (the "Software"),
      7  * to deal in the Software without restriction, including without limitation
      8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
      9  * and/or sell copies of the Software, and to permit persons to whom the
     10  * Software is furnished to do so, subject to the following conditions:
     11  *
     12  * The above copyright notice and this permission notice (including the next
     13  * paragraph) shall be included in all copies or substantial portions of the
     14  * Software.
     15  *
     16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
     19  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
     22  * DEALINGS IN THE SOFTWARE.
     23  */
     24 
     25 #pragma once
     26 #ifndef IR_HIERARCHICAL_VISITOR_H
     27 #define IR_HIERARCHICAL_VISITOR_H
     28 
     29 /**
     30  * Enumeration values returned by visit methods to guide processing
     31  */
     32 enum ir_visitor_status {
     33    visit_continue,		/**< Continue visiting as normal. */
     34    visit_continue_with_parent,	/**< Don't visit siblings, continue w/parent. */
     35    visit_stop			/**< Stop visiting immediately. */
     36 };
     37 
     38 
     39 /**
     40  * Base class of hierarchical visitors of IR instruction trees
     41  *
     42  * Hierarchical visitors differ from traditional visitors in a couple of
     43  * important ways.  Rather than having a single \c visit method for each
     44  * subclass in the composite, there are three kinds of visit methods.
     45  * Leaf-node classes have a traditional \c visit method.  Internal-node
     46  * classes have a \c visit_enter method, which is invoked just before
     47  * processing child nodes, and a \c visit_leave method which is invoked just
     48  * after processing child nodes.
     49  *
     50  * In addition, each visit method and the \c accept methods in the composite
     51  * have a return value which guides the navigation.  Any of the visit methods
     52  * can choose to continue visiting the tree as normal (by returning \c
     53  * visit_continue), terminate visiting any further nodes immediately (by
     54  * returning \c visit_stop), or stop visiting sibling nodes (by returning \c
     55  * visit_continue_with_parent).
     56  *
     57  * These two changes combine to allow nagivation of children to be implemented
     58  * in the composite's \c accept method.  The \c accept method for a leaf-node
     59  * class will simply call the \c visit method, as usual, and pass its return
     60  * value on.  The \c accept method for internal-node classes will call the \c
     61  * visit_enter method, call the \c accpet method of each child node, and,
     62  * finally, call the \c visit_leave method.  If any of these return a value
     63  * other that \c visit_continue, the correct action must be taken.
     64  *
     65  * The final benefit is that the hierarchical visitor base class need not be
     66  * abstract.  Default implementations of every \c visit, \c visit_enter, and
     67  * \c visit_leave method can be provided.  By default each of these methods
     68  * simply returns \c visit_continue.  This allows a significant reduction in
     69  * derived class code.
     70  *
     71  * For more information about hierarchical visitors, see:
     72  *
     73  *    http://c2.com/cgi/wiki?HierarchicalVisitorPattern
     74  *    http://c2.com/cgi/wiki?HierarchicalVisitorDiscussion
     75  */
     76 
     77 class ir_hierarchical_visitor {
     78 public:
     79    ir_hierarchical_visitor();
     80 
     81    /**
     82     * \name Visit methods for leaf-node classes
     83     */
     84    /*@{*/
     85    virtual ir_visitor_status visit(class ir_rvalue *);
     86    virtual ir_visitor_status visit(class ir_variable *);
     87    virtual ir_visitor_status visit(class ir_constant *);
     88    virtual ir_visitor_status visit(class ir_loop_jump *);
     89 
     90    /**
     91     * ir_dereference_variable isn't technically a leaf, but it is treated as a
     92     * leaf here for a couple reasons.  By not automatically visiting the one
     93     * child ir_variable node from the ir_dereference_variable, ir_variable
     94     * nodes can always be handled as variable declarations.  Code that used
     95     * non-hierarchical visitors had to set an "in a dereference" flag to
     96     * determine how to handle an ir_variable.  By forcing the visitor to
     97     * handle the ir_variable within the ir_dereference_variable visitor, this
     98     * kludge can be avoided.
     99     *
    100     * In addition, I can envision no use for having separate enter and leave
    101     * methods.  Anything that could be done in the enter and leave methods
    102     * that couldn't just be done in the visit method.
    103     */
    104    virtual ir_visitor_status visit(class ir_dereference_variable *);
    105    /*@}*/
    106 
    107    /**
    108     * \name Visit methods for internal-node classes
    109     */
    110    /*@{*/
    111    virtual ir_visitor_status visit_enter(class ir_loop *);
    112    virtual ir_visitor_status visit_leave(class ir_loop *);
    113    virtual ir_visitor_status visit_enter(class ir_function_signature *);
    114    virtual ir_visitor_status visit_leave(class ir_function_signature *);
    115    virtual ir_visitor_status visit_enter(class ir_function *);
    116    virtual ir_visitor_status visit_leave(class ir_function *);
    117    virtual ir_visitor_status visit_enter(class ir_expression *);
    118    virtual ir_visitor_status visit_leave(class ir_expression *);
    119    virtual ir_visitor_status visit_enter(class ir_texture *);
    120    virtual ir_visitor_status visit_leave(class ir_texture *);
    121    virtual ir_visitor_status visit_enter(class ir_swizzle *);
    122    virtual ir_visitor_status visit_leave(class ir_swizzle *);
    123    virtual ir_visitor_status visit_enter(class ir_dereference_array *);
    124    virtual ir_visitor_status visit_leave(class ir_dereference_array *);
    125    virtual ir_visitor_status visit_enter(class ir_dereference_record *);
    126    virtual ir_visitor_status visit_leave(class ir_dereference_record *);
    127    virtual ir_visitor_status visit_enter(class ir_assignment *);
    128    virtual ir_visitor_status visit_leave(class ir_assignment *);
    129    virtual ir_visitor_status visit_enter(class ir_call *);
    130    virtual ir_visitor_status visit_leave(class ir_call *);
    131    virtual ir_visitor_status visit_enter(class ir_return *);
    132    virtual ir_visitor_status visit_leave(class ir_return *);
    133    virtual ir_visitor_status visit_enter(class ir_discard *);
    134    virtual ir_visitor_status visit_leave(class ir_discard *);
    135    virtual ir_visitor_status visit_enter(class ir_if *);
    136    virtual ir_visitor_status visit_leave(class ir_if *);
    137    /*@}*/
    138 
    139 
    140    /**
    141     * Utility function to process a linked list of instructions with a visitor
    142     */
    143    void run(struct exec_list *instructions);
    144 
    145    /* Some visitors may need to insert new variable declarations and
    146     * assignments for portions of a subtree, which means they need a
    147     * pointer to the current instruction in the stream, not just their
    148     * node in the tree rooted at that instruction.
    149     *
    150     * This is implemented by visit_list_elements -- if the visitor is
    151     * not called by it, nothing good will happen.
    152     */
    153    class ir_instruction *base_ir;
    154 
    155    /**
    156     * Callback function that is invoked on entry to each node visited.
    157     *
    158     * \warning
    159     * Visitor classes derived from \c ir_hierarchical_visitor \b may \b not
    160     * invoke this function.  This can be used, for example, to cause the
    161     * callback to be invoked on every node type execpt one.
    162     */
    163    void (*callback)(class ir_instruction *ir, void *data);
    164 
    165    /**
    166     * Extra data parameter passed to the per-node callback function
    167     */
    168    void *data;
    169 
    170    /**
    171     * Currently in the LHS of an assignment?
    172     *
    173     * This is set and cleared by the \c ir_assignment::accept method.
    174     */
    175    bool in_assignee;
    176 };
    177 
    178 void visit_tree(ir_instruction *ir,
    179 		void (*callback)(class ir_instruction *ir, void *data),
    180 		void *data);
    181 
    182 ir_visitor_status visit_list_elements(ir_hierarchical_visitor *v, exec_list *l,
    183                                       bool statement_list = true);
    184 
    185 #endif /* IR_HIERARCHICAL_VISITOR_H */
    186