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         void swapTextures(u8 texture_a, u8 texture_b);
 145 private:
 146         static const u8 NO_DEPTH_TEXTURE = 255;
 147
 148         struct TextureDefinition
 149         {
 150                 bool valid { false };
 151                 bool fixed_size { false };
 152                 bool dirty { false };
 153                 v2f scale_factor;
 154                 core::dimension2du size;
 155                 std::string name;
 156                 video::ECOLOR_FORMAT format;
 157         };
 158
 159         /**
 160          * Make sure the texture in the given slot matches the texture definition given the current context.
 161          * @param textureSlot address of the texture pointer to verify and populate.
 162          * @param definition logical definition of the texture
 163          * @param context current context of the rendering pipeline
 164          * @return true if a new texture was created and put into the slot
 165          * @return false if the slot was not modified
 166          */
 167         bool ensureTexture(video::ITexture **textureSlot, const TextureDefinition& definition, PipelineContext &context);
 168
 169         video::IVideoDriver *m_driver { nullptr };
 170         std::vector<TextureDefinition> m_definitions;
 171         core::array<video::ITexture *> m_textures;
 172 };
 173
 174 /**
 175  * Targets output to designated texture in texture buffer
 176  */
 177 class TextureBufferOutput : public RenderTarget
 178 {
 179 public:
 180         TextureBufferOutput(TextureBuffer *buffer, u8 texture_index);
 181         TextureBufferOutput(TextureBuffer *buffer, const std::vector<u8> &texture_map);
 182         TextureBufferOutput(TextureBuffer *buffer, const std::vector<u8> &texture_map, u8 depth_stencil);
 183         virtual ~TextureBufferOutput() override;
 184         void activate(PipelineContext &context) override;
 185 private:
 186         static const u8 NO_DEPTH_TEXTURE = 255;
 187
 188         TextureBuffer *buffer;
 189         std::vector<u8> texture_map;
 190         u8 depth_stencil { NO_DEPTH_TEXTURE };
 191         video::IRenderTarget* render_target { nullptr };
 192         video::IVideoDriver* driver { nullptr };
 193 };
 194
 195 /**
 196  * Allows remapping texture indicies in another RenderSource.
 197  *
 198  * @note all unmapped indexes are passed through to the underlying render source.
 199  */
 200 class RemappingSource : RenderSource
 201 {
 202 public:
 203         RemappingSource(RenderSource *source)
 204                         : m_source(source)
 205         {}
 206
 207         /**
 208          * Maps texture index to a different index in the dependent source.
 209          *
 210          * @param index texture index as requested by the @see RenderStep.
 211          * @param target_index matching texture index in the underlying @see RenderSource.
 212          */
 213         void setMapping(u8 index, u8 target_index)
 214         {
 215                 if (index >= m_mappings.size()) {
 216                         u8 start = m_mappings.size();
 217                         m_mappings.resize(index);
 218                         for (u8 i = start; i < m_mappings.size(); ++i)
 219                                 m_mappings[i] = i;
 220                 }
 221
 222                 m_mappings[index] = target_index;
 223         }
 224
 225         virtual u8 getTextureCount() override
 226         {
 227                 return m_mappings.size();
 228         }
 229
 230         virtual video::ITexture *getTexture(u8 index) override
 231         {
 232                 if (index < m_mappings.size())
 233                         index = m_mappings[index];
 234
 235                 return m_source->getTexture(index);
 236         }
 237 public:
 238         RenderSource *m_source;
 239         std::vector<u8> m_mappings;
 240 };
 241
 242 class DynamicSource : public RenderSource
 243 {
 244 public:
 245         bool isConfigured() { return upstream != nullptr; }
 246         void setRenderSource(RenderSource *value) { upstream = value; }
 247
 248         /**
 249          * Return the number of textures in the source.
 250          */
 251         virtual u8 getTextureCount() override;
 252
 253         /**
 254          * Get a texture by index.
 255          * Returns nullptr is the texture does not exist.
 256          */
 257         virtual video::ITexture *getTexture(u8 index) override;
 258 private:
 259         RenderSource *upstream { nullptr };
 260 };
 261
 262 /**
 263  * Implements direct output to screen framebuffer.
 264  */
 265 class ScreenTarget : public RenderTarget
 266 {
 267 public:
 268         virtual void activate(PipelineContext &context) override;
 269         virtual void reset(PipelineContext &context) override;
 270 private:
 271         core::dimension2du size;
 272 };
 273
 274 class DynamicTarget : public RenderTarget
 275 {
 276 public:
 277         bool isConfigured() { return upstream != nullptr; }
 278         void setRenderTarget(RenderTarget *value) { upstream = value; }
 279         virtual void activate(PipelineContext &context) override;
 280 private:
 281         RenderTarget *upstream { nullptr };
 282 };
 283
 284 /**
 285  * Base class for rendering steps in the pipeline
 286  */
 287 class RenderStep : virtual public RenderPipelineObject
 288 {
 289 public:
 290         /**
 291          * Assigns render source to this step.
 292          *
 293          * @param source source of rendering information
 294          */
 295         virtual void setRenderSource(RenderSource *source) = 0;
 296
 297         /**
 298          * Assigned render target to this step.
 299          *
 300          * @param target render target to send output to.
 301          */
 302         virtual void setRenderTarget(RenderTarget *target) = 0;
 303
 304         /**
 305          * Runs the step. This method is invoked by the pipeline.
 306          */
 307         virtual void run(PipelineContext &context) = 0;
 308 };
 309
 310 /**
 311  * Provides default empty implementation of supporting methods in a rendering step.
 312  */
 313 class TrivialRenderStep : public RenderStep
 314 {
 315 public:
 316         virtual void setRenderSource(RenderSource *source) override {}
 317         virtual void setRenderTarget(RenderTarget *target) override {}
 318         virtual void reset(PipelineContext &) override {}
 319 };
 320
 321 /**
 322  * Dynamically changes render target of another step.
 323  *
 324  * This allows re-running parts of the pipeline with different outputs
 325  */
 326 class SetRenderTargetStep : public TrivialRenderStep
 327 {
 328 public:
 329         SetRenderTargetStep(RenderStep *step, RenderTarget *target);
 330         virtual void run(PipelineContext &context) override;
 331 private:
 332         RenderStep *step;
 333         RenderTarget *target;
 334 };
 335
 336 /**
 337  * Swaps two textures in the texture buffer.
 338  *
 339  */
 340 class SwapTexturesStep : public TrivialRenderStep
 341 {
 342 public:
 343         SwapTexturesStep(TextureBuffer *buffer, u8 texture_a, u8 texture_b);
 344         virtual void run(PipelineContext &context) override;
 345 private:
 346         TextureBuffer *buffer;
 347         u8 texture_a;
 348         u8 texture_b;
 349 };
 350
 351 /**
 352  * Render Pipeline provides a flexible way to execute rendering steps in the engine.
 353  *
 354  * RenderPipeline also implements @see RenderStep, allowing for nesting of the pipelines.
 355  */
 356 class RenderPipeline : public RenderStep
 357 {
 358 public:
 359         /**
 360          * Add a step to the end of the pipeline
 361          *
 362          * @param step reference to a @see RenderStep implementation.
 363          */
 364         RenderStep *addStep(RenderStep *step)
 365         {
 366                 m_pipeline.push_back(step);
 367                 return step;
 368         }
 369
 370         /**
 371          * Capture ownership of a dynamically created @see RenderStep instance.
 372          *
 373          * RenderPipeline will delete the instance when the pipeline is destroyed.
 374          *
 375          * @param step reference to the instance.
 376          * @return RenderStep* value of the 'step' parameter.
 377          */
 378         template<typename T>
 379         T *own(std::unique_ptr<T> &&object)
 380         {
 381                 T* result = object.release();
 382                 m_objects.push_back(std::unique_ptr<RenderPipelineObject>(result));
 383                 return result;
 384         }
 385
 386         /**
 387          * Create a new object that will be managed by the pipeline
 388          *
 389          * @tparam T type of the object to be created
 390          * @tparam Args types of constructor arguments
 391          * @param args constructor arguments
 392          * @return T* pointer to the newly created object
 393          */
 394         template<typename T, typename... Args>
 395         T *createOwned(Args&&... args) {
 396                 return own(std::make_unique<T>(std::forward<Args>(args)...));
 397         }
 398
 399         /**
 400          * Create and add a step managed by the pipeline and return a pointer
 401          * to the step for further configuration.
 402          *
 403          * @tparam T Type of the step to be added.
 404          * @tparam Args Types of the constructor parameters
 405          * @param args Constructor parameters
 406          * @return RenderStep* Pointer to the created step for further configuration.
 407          */
 408         template<typename T, typename... Args>
 409         T *addStep(Args&&... args) {
 410                 T* result = own(std::make_unique<T>(std::forward<Args>(args)...));
 411                 addStep(result);
 412                 return result;
 413         }
 414
 415         RenderSource *getInput();
 416         RenderTarget *getOutput();
 417
 418         v2f getScale() { return scale; }
 419         void setScale(v2f value) { scale = value; }
 420
 421         virtual void reset(PipelineContext &context) override {}
 422         virtual void run(PipelineContext &context) override;
 423
 424         virtual void setRenderSource(RenderSource *source) override;
 425         virtual void setRenderTarget(RenderTarget *target) override;
 426 private:
 427         std::vector<RenderStep *> m_pipeline;
 428         std::vector< std::unique_ptr<RenderPipelineObject> > m_objects;
 429         DynamicSource m_input;
 430         DynamicTarget m_output;
 431         v2f scale { 1.0f, 1.0f };
 432 };