src/client/render/pipeline.h

   1 /*
   2 Minetest
   3 Copyright (C) 2022 x2048, Dmitry Kostenko <codeforsmile@gmail.com>
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation; either version 2.1 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License along
  16 with this program; if not, write to the Free Software Foundation, Inc.,
  17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19 #pragma once
  20
  21 #include "irrlichttypes_extrabloated.h"
  22
  23 #include <vector>
  24 #include <memory>
  25 #include <string>
  26
  27 class RenderSource;
  28 class RenderTarget;
  29 class RenderStep;
  30 class Client;
  31 class Hud;
  32 class ShadowRenderer;
  33
  34 struct PipelineContext
  35 {
  36         PipelineContext(IrrlichtDevice *_device, Client *_client, Hud *_hud, ShadowRenderer *_shadow_renderer, video::SColor _color, v2u32 _target_size)
  37                 : device(_device), client(_client), hud(_hud), shadow_renderer(_shadow_renderer), clear_color(_color), target_size(_target_size)
  38         {
  39         }
  40
  41         IrrlichtDevice *device;
  42         Client *client;
  43         Hud *hud;
  44         ShadowRenderer *shadow_renderer;
  45         video::SColor clear_color;
  46         v2u32 target_size;
  47
  48         bool show_hud {true};
  49         bool show_minimap {true};
  50         bool draw_wield_tool {true};
  51         bool draw_crosshair {true};
  52 };
  53
  54 /**
  55  * Base object that can be owned by RenderPipeline
  56  *
  57  */
  58 class RenderPipelineObject
  59 {
  60 public:
  61         virtual ~RenderPipelineObject() = default;
  62         virtual void reset(PipelineContext &context) {}
  63 };
  64
  65 /**
  66  * Represents a source of rendering information such as textures
  67  */
  68 class RenderSource : virtual public RenderPipelineObject
  69 {
  70 public:
  71         /**
  72          * Return the number of textures in the source.
  73          */
  74         virtual u8 getTextureCount() = 0;
  75
  76         /**
  77          * Get a texture by index.
  78          * Returns nullptr is the texture does not exist.
  79          */
  80         virtual video::ITexture *getTexture(u8 index) = 0;
  81 };
  82
  83 /**
  84  *      Represents a render target (screen or framebuffer)
  85  */
  86 class RenderTarget : virtual public RenderPipelineObject
  87 {
  88 public:
  89         /**
  90          * Activate the render target and configure OpenGL state for the output.
  91          * This is usually done by @see RenderStep implementations.
  92          */
  93         virtual void activate(PipelineContext &context)
  94         {
  95                 m_clear = false;
  96         }
  97
  98         /**
  99          * Resets the state of the object for the next pipeline iteration
 100          */
 101         virtual void reset(PipelineContext &context) override
 102         {
 103                 m_clear = true;
 104         }
 105
 106 protected:
 107         bool m_clear {true};
 108 };
 109
 110 /**
 111  * Texture buffer represents a framebuffer with a multiple attached textures.
 112  *
 113  * @note Use of TextureBuffer requires use of gl_FragData[] in the shader
 114  */
 115 class TextureBuffer : public RenderSource
 116 {
 117 public:
 118         virtual ~TextureBuffer() override;
 119
 120         /**
 121          * Configure fixed-size texture for the specific index
 122          *
 123          * @param index index of the texture
 124          * @param size width and height of the texture in pixels
 125          * @param height height of the texture in pixels
 126          * @param name unique name of the texture
 127          * @param format color format
 128          */
 129         void setTexture(u8 index, core::dimension2du size, const std::string& name, video::ECOLOR_FORMAT format);
 130
 131         /**
 132          * Configure relative-size texture for the specific index
 133          *
 134          * @param index index of the texture
 135          * @param scale_factor relation of the texture dimensions to the screen dimensions
 136          * @param name unique name of the texture
 137          * @param format color format
 138          */
 139         void setTexture(u8 index, v2f scale_factor, const std::string& name, video::ECOLOR_FORMAT format);
 140
 141         virtual u8 getTextureCount() override { return m_textures.size(); }
 142         virtual video::ITexture *getTexture(u8 index) override;
 143         virtual void reset(PipelineContext &context) override;
 144 private:
 145         static const u8 NO_DEPTH_TEXTURE = 255;
 146
 147         struct TextureDefinition
 148         {
 149                 bool valid { false };
 150                 bool fixed_size { false };
 151                 bool dirty { false };
 152                 v2f scale_factor;
 153                 core::dimension2du size;
 154                 std::string name;
 155                 video::ECOLOR_FORMAT format;
 156         };
 157
 158         /**
 159          * Make sure the texture in the given slot matches the texture definition given the current context.
 160          * @param textureSlot address of the texture pointer to verify and populate.
 161          * @param definition logical definition of the texture
 162          * @param context current context of the rendering pipeline
 163          * @return true if a new texture was created and put into the slot
 164          * @return false if the slot was not modified
 165          */
 166         bool ensureTexture(video::ITexture **textureSlot, const TextureDefinition& definition, PipelineContext &context);
 167
 168         video::IVideoDriver *m_driver { nullptr };
 169         std::vector<TextureDefinition> m_definitions;
 170         core::array<video::ITexture *> m_textures;
 171 };
 172
 173 /**
 174  * Targets output to designated texture in texture buffer
 175  */
 176 class TextureBufferOutput : public RenderTarget
 177 {
 178 public:
 179         TextureBufferOutput(TextureBuffer *buffer, u8 texture_index);
 180         TextureBufferOutput(TextureBuffer *buffer, const std::vector<u8> &texture_map);
 181         TextureBufferOutput(TextureBuffer *buffer, const std::vector<u8> &texture_map, u8 depth_stencil);
 182         virtual ~TextureBufferOutput() override;
 183         void activate(PipelineContext &context) override;
 184 private:
 185         static const u8 NO_DEPTH_TEXTURE = 255;
 186
 187         TextureBuffer *buffer;
 188         std::vector<u8> texture_map;
 189         u8 depth_stencil { NO_DEPTH_TEXTURE };
 190         video::IRenderTarget* render_target { nullptr };
 191         video::IVideoDriver* driver { nullptr };
 192 };
 193
 194 /**
 195  * Allows remapping texture indicies in another RenderSource.
 196  *
 197  * @note all unmapped indexes are passed through to the underlying render source.
 198  */
 199 class RemappingSource : RenderSource
 200 {
 201 public:
 202         RemappingSource(RenderSource *source)
 203                         : m_source(source)
 204         {}
 205
 206         /**
 207          * Maps texture index to a different index in the dependent source.
 208          *
 209          * @param index texture index as requested by the @see RenderStep.
 210          * @param target_index matching texture index in the underlying @see RenderSource.
 211          */
 212         void setMapping(u8 index, u8 target_index)
 213         {
 214                 if (index >= m_mappings.size()) {
 215                         u8 start = m_mappings.size();
 216                         m_mappings.resize(index);
 217                         for (u8 i = start; i < m_mappings.size(); ++i)
 218                                 m_mappings[i] = i;
 219                 }
 220
 221                 m_mappings[index] = target_index;
 222         }
 223
 224         virtual u8 getTextureCount() override
 225         {
 226                 return m_mappings.size();
 227         }
 228
 229         virtual video::ITexture *getTexture(u8 index) override
 230         {
 231                 if (index < m_mappings.size())
 232                         index = m_mappings[index];
 233
 234                 return m_source->getTexture(index);
 235         }
 236 public:
 237         RenderSource *m_source;
 238         std::vector<u8> m_mappings;
 239 };
 240
 241 class DynamicSource : public RenderSource
 242 {
 243 public:
 244         bool isConfigured() { return upstream != nullptr; }
 245         void setRenderSource(RenderSource *value) { upstream = value; }
 246
 247         /**
 248          * Return the number of textures in the source.
 249          */
 250         virtual u8 getTextureCount() override;
 251
 252         /**
 253          * Get a texture by index.
 254          * Returns nullptr is the texture does not exist.
 255          */
 256         virtual video::ITexture *getTexture(u8 index) override;
 257 private:
 258         RenderSource *upstream { nullptr };
 259 };
 260
 261 /**
 262  * Implements direct output to screen framebuffer.
 263  */
 264 class ScreenTarget : public RenderTarget
 265 {
 266 public:
 267         virtual void activate(PipelineContext &context) override;
 268         virtual void reset(PipelineContext &context) override;
 269 private:
 270         core::dimension2du size;
 271 };
 272
 273 class DynamicTarget : public RenderTarget
 274 {
 275 public:
 276         bool isConfigured() { return upstream != nullptr; }
 277         void setRenderTarget(RenderTarget *value) { upstream = value; }
 278         virtual void activate(PipelineContext &context) override;
 279 private:
 280         RenderTarget *upstream { nullptr };
 281 };
 282
 283 /**
 284  * Base class for rendering steps in the pipeline
 285  */
 286 class RenderStep : virtual public RenderPipelineObject
 287 {
 288 public:
 289         /**
 290          * Assigns render source to this step.
 291          *
 292          * @param source source of rendering information
 293          */
 294         virtual void setRenderSource(RenderSource *source) = 0;
 295
 296         /**
 297          * Assigned render target to this step.
 298          *
 299          * @param target render target to send output to.
 300          */
 301         virtual void setRenderTarget(RenderTarget *target) = 0;
 302
 303         /**
 304          * Runs the step. This method is invoked by the pipeline.
 305          */
 306         virtual void run(PipelineContext &context) = 0;
 307 };
 308
 309 /**
 310  * Provides default empty implementation of supporting methods in a rendering step.
 311  */
 312 class TrivialRenderStep : public RenderStep
 313 {
 314 public:
 315         virtual void setRenderSource(RenderSource *source) override {}
 316         virtual void setRenderTarget(RenderTarget *target) override {}
 317         virtual void reset(PipelineContext &) override {}
 318 };
 319
 320 /**
 321  * Dynamically changes render target of another step.
 322  *
 323  * This allows re-running parts of the pipeline with different outputs
 324  */
 325 class SetRenderTargetStep : public TrivialRenderStep
 326 {
 327 public:
 328         SetRenderTargetStep(RenderStep *step, RenderTarget *target);
 329         virtual void run(PipelineContext &context) override;
 330 private:
 331         RenderStep *step;
 332         RenderTarget *target;
 333 };
 334
 335 /**
 336  * Render Pipeline provides a flexible way to execute rendering steps in the engine.
 337  *
 338  * RenderPipeline also implements @see RenderStep, allowing for nesting of the pipelines.
 339  */
 340 class RenderPipeline : public RenderStep
 341 {
 342 public:
 343         /**
 344          * Add a step to the end of the pipeline
 345          *
 346          * @param step reference to a @see RenderStep implementation.
 347          */
 348         RenderStep *addStep(RenderStep *step)
 349         {
 350                 m_pipeline.push_back(step);
 351                 return step;
 352         }
 353
 354         /**
 355          * Capture ownership of a dynamically created @see RenderStep instance.
 356          *
 357          * RenderPipeline will delete the instance when the pipeline is destroyed.
 358          *
 359          * @param step reference to the instance.
 360          * @return RenderStep* value of the 'step' parameter.
 361          */
 362         template<typename T>
 363         T *own(std::unique_ptr<T> &&object)
 364         {
 365                 T* result = object.release();
 366                 m_objects.push_back(std::unique_ptr<RenderPipelineObject>(result));
 367                 return result;
 368         }
 369
 370         /**
 371          * Create a new object that will be managed by the pipeline
 372          *
 373          * @tparam T type of the object to be created
 374          * @tparam Args types of constructor arguments
 375          * @param args constructor arguments
 376          * @return T* pointer to the newly created object
 377          */
 378         template<typename T, typename... Args>
 379         T *createOwned(Args&&... args) {
 380                 return own(std::make_unique<T>(std::forward<Args>(args)...));
 381         }
 382
 383         /**
 384          * Create and add a step managed by the pipeline and return a pointer
 385          * to the step for further configuration.
 386          *
 387          * @tparam T Type of the step to be added.
 388          * @tparam Args Types of the constructor parameters
 389          * @param args Constructor parameters
 390          * @return RenderStep* Pointer to the created step for further configuration.
 391          */
 392         template<typename T, typename... Args>
 393         T *addStep(Args&&... args) {
 394                 T* result = own(std::make_unique<T>(std::forward<Args>(args)...));
 395                 addStep(result);
 396                 return result;
 397         }
 398
 399         RenderSource *getInput();
 400         RenderTarget *getOutput();
 401
 402         v2f getScale() { return scale; }
 403         void setScale(v2f value) { scale = value; }
 404
 405         virtual void reset(PipelineContext &context) override {}
 406         virtual void run(PipelineContext &context) override;
 407
 408         virtual void setRenderSource(RenderSource *source) override;
 409         virtual void setRenderTarget(RenderTarget *target) override;
 410 private:
 411         std::vector<RenderStep *> m_pipeline;
 412         std::vector< std::unique_ptr<RenderPipelineObject> > m_objects;
 413         DynamicSource m_input;
 414         DynamicTarget m_output;
 415         v2f scale { 1.0f, 1.0f };
 416 };