source/renderer/ModelVertexRenderer.h

   1 /* Copyright (C) 2012 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Definition of ModelVertexRenderer, the abstract base class for model
  20  * vertex transformation implementations.
  21  */
  22
  23 #ifndef INCLUDED_MODELVERTEXRENDERER
  24 #define INCLUDED_MODELVERTEXRENDERER
  25
  26 #include "graphics/MeshManager.h"
  27 #include "graphics/ShaderProgramPtr.h"
  28
  29 class CModel;
  30 class CModelRData;
  31
  32 /**
  33  * Class ModelVertexRenderer: Normal ModelRenderer implementations delegate
  34  * vertex array management and vertex transformation to an implementation of
  35  * ModelVertexRenderer.
  36  *
  37  * ModelVertexRenderer implementations should be designed so that one
  38  * instance of the implementation can be used with more than one ModelRenderer
  39  * simultaneously.
  40  */
  41 class ModelVertexRenderer
  42 {
  43 public:
  44         virtual ~ModelVertexRenderer() { }
  45
  46
  47         /**
  48          * CreateModelData: Create internal data for one model.
  49          *
  50          * ModelRenderer implementations must call this once for every
  51          * model that will later be rendered, with @p key set to a value
  52          * that's unique to that ModelRenderer.
  53          *
  54          * ModelVertexRenderer implementations should use this function to
  55          * create per-CModel and per-CModelDef data like vertex arrays.
  56          *
  57          * @param key An opaque pointer to pass to the CModelRData constructor
  58          * @param model The model.
  59          *
  60          * @return A new CModelRData that will be passed into other
  61          * ModelVertexRenderer functions whenever the same CModel is used again.
  62          */
  63         virtual CModelRData* CreateModelData(const void* key, CModel* model) = 0;
  64
  65
  66         /**
  67          * UpdateModelData: Calculate per-model data for each frame.
  68          *
  69          * ModelRenderer implementations must call this once per frame for
  70          * every model that is to be rendered in this frame, even if the
  71          * value of updateflags will be zero.
  72          * This implies that this function will also be called at least once
  73          * between a call to CreateModelData and a call to RenderModel.
  74          *
  75          * ModelVertexRenderer implementations should use this function to
  76          * perform software vertex transforms and potentially other per-frame
  77          * calculations.
  78          *
  79          * @param model The model.
  80          * @param data Private data as returned by CreateModelData.
  81          * @param updateflags Flags indicating which data has changed during
  82          * the frame. The value is the same as the value of the model's
  83          * CRenderData::m_UpdateFlags.
  84          */
  85         virtual void UpdateModelData(CModel* model, CModelRData* data, int updateflags) = 0;
  86
  87
  88         /**
  89          * BeginPass: Setup global OpenGL state for this ModelVertexRenderer.
  90          *
  91          * ModelVertexRenderer implementations should prepare "heavy" OpenGL
  92          * state such as vertex shader state to prepare for rendering models
  93          * and delivering vertex data to the fragment stage as described by
  94          * streamflags.
  95          *
  96          * ModelRenderer implementations must call this function before any
  97          * calls to other rendering related functions.
  98          *
  99          * Recursive calls to BeginPass are not allowed, and every BeginPass
 100          * is matched by a corresponding call to EndPass.
 101          *
 102          * @param streamflags Vertex streams required by the fragment stage.
 103          */
 104         virtual void BeginPass(int streamflags) = 0;
 105
 106
 107         /**
 108          * EndPass: Cleanup OpenGL state set up by BeginPass.
 109          *
 110          * ModelRenderer implementations must call this function after
 111          * rendering related functions for one pass have been called.
 112          *
 113          * @param streamflags Vertex streams required by the fragment stage.
 114          * This equals the streamflags parameter passed on the last call to
 115          * BeginPass.
 116          */
 117         virtual void EndPass(int streamflags) = 0;
 118
 119
 120         /**
 121          * PrepareModelDef: Setup OpenGL state for rendering of models that
 122          * use the given CModelDef object as base.
 123          *
 124          * ModelRenderer implementations must call this function before
 125          * rendering a sequence of models based on the given CModelDef.
 126          * When a ModelRenderer switches back and forth between CModelDefs,
 127          * it must call PrepareModelDef for every switch.
 128          *
 129          * @param streamflags Vertex streams required by the fragment stage.
 130          * This equals the streamflags parameter passed on the last call to
 131          * BeginPass.
 132          * @param def The model definition.
 133          */
 134         virtual void PrepareModelDef(const CShaderProgramPtr& shader, int streamflags, const CModelDef& def) = 0;
 135
 136
 137         /**
 138          * RenderModel: Invoke the rendering commands for the given model.
 139          *
 140          * ModelRenderer implementations must call this function to perform
 141          * the actual rendering.
 142          *
 143          * preconditions  : The most recent call to PrepareModelDef since
 144          * BeginPass has been for model->GetModelDef().
 145          *
 146          * @param streamflags Vertex streams required by the fragment stage.
 147          * This equals the streamflags parameter passed on the last call to
 148          * BeginPass.
 149          * @param model The model that should be rendered.
 150          * @param data Private data for the model as returned by CreateModelData.
 151          *
 152          * postconditions : Subsequent calls to RenderModel for models
 153          * that use the same CModelDef object and the same texture must
 154          * succeed.
 155          */
 156         virtual void RenderModel(const CShaderProgramPtr& shader, int streamflags, CModel* model, CModelRData* data) = 0;
 157 };
 158
 159
 160 #endif // INCLUDED_MODELVERTEXRENDERER