GPU_framebuffer.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2005 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */

 
#pragma once
 
#include "GPU_common_types.hh"
#include "GPU_texture.hh"
 
struct GPUTexture;
 
enum eGPUFrameBufferBits {
  GPU_COLOR_BIT = (1 << 0),
  GPU_DEPTH_BIT = (1 << 1),
  GPU_STENCIL_BIT = (1 << 2),
};
 
ENUM_OPERATORS(eGPUFrameBufferBits, GPU_STENCIL_BIT)
 
/* Guaranteed by the spec and is never greater than 16 on any hardware or implementation. */
constexpr static int GPU_MAX_VIEWPORTS = 16;
 
struct GPUAttachment {
  GPUTexture *tex;
  int layer, mip;
};

struct GPUFrameBuffer;
 
/* -------------------------------------------------------------------- */

GPUFrameBuffer *GPU_framebuffer_create(const char *name);

GPUFrameBuffer *GPU_framebuffer_active_get();

GPUFrameBuffer *GPU_framebuffer_back_get();

 
/* -------------------------------------------------------------------- */

void GPU_framebuffer_free(GPUFrameBuffer *fb);
 
#define GPU_FRAMEBUFFER_FREE_SAFE(fb) \
  do { \
    if (fb != nullptr) { \
      GPU_framebuffer_free(fb); \
      fb = nullptr; \
    } \
  } while (0)

 
/* -------------------------------------------------------------------- */
 
enum eGPUBackBuffer {
  GPU_BACKBUFFER_LEFT = 0,
  GPU_BACKBUFFER_RIGHT,
};

void GPU_backbuffer_bind(eGPUBackBuffer back_buffer_type);

void GPU_framebuffer_bind(GPUFrameBuffer *fb);

void GPU_framebuffer_bind_no_srgb(GPUFrameBuffer *fb);

void GPU_framebuffer_restore();

 
/* -------------------------------------------------------------------- */
 
struct GPULoadStore {
  eGPULoadOp load_action;
  eGPUStoreOp store_action;
  float clear_value[4];
};
 
/* Empty bind point. */
#define NULL_ATTACHMENT_COLOR \
  { \
    0.0, 0.0, 0.0, 0.0 \
  }
#define NULL_LOAD_STORE \
  { \
    GPU_LOADACTION_DONT_CARE, GPU_STOREACTION_DONT_CARE, NULL_ATTACHMENT_COLOR \
  }

void GPU_framebuffer_bind_loadstore(GPUFrameBuffer *fb,
                                    const GPULoadStore *load_store_actions,
                                    uint load_store_actions_len);
#define GPU_framebuffer_bind_ex(_fb, ...) \
  { \
    GPULoadStore actions[] = __VA_ARGS__; \
    GPU_framebuffer_bind_loadstore(_fb, actions, (sizeof(actions) / sizeof(GPULoadStore))); \
  }

void GPU_framebuffer_subpass_transition_array(GPUFrameBuffer *fb,
                                              const GPUAttachmentState *attachment_states,
                                              uint attachment_len);
 
#define GPU_framebuffer_subpass_transition(_fb, ...) \
  { \
    GPUAttachmentState actions[] = __VA_ARGS__; \
    GPU_framebuffer_subpass_transition_array( \
        _fb, actions, (sizeof(actions) / sizeof(GPUAttachmentState))); \
  }

 
/* -------------------------------------------------------------------- */

#define GPU_framebuffer_ensure_config(_fb, ...) \
  do { \
    if (*(_fb) == nullptr) { \
      *(_fb) = GPU_framebuffer_create(#_fb); \
    } \
    GPUAttachment config[] = __VA_ARGS__; \
    GPU_framebuffer_config_array(*(_fb), config, (sizeof(config) / sizeof(GPUAttachment))); \
  } while (0)

void GPU_framebuffer_config_array(GPUFrameBuffer *fb, const GPUAttachment *config, int config_len);

#define GPU_ATTACHMENT_NONE \
  { \
    nullptr, -1, 0, \
  }

#define GPU_ATTACHMENT_LEAVE \
  { \
    nullptr, -1, -1, \
  }

#define GPU_ATTACHMENT_TEXTURE(_texture) \
  { \
    _texture, -1, 0, \
  }

#define GPU_ATTACHMENT_TEXTURE_MIP(_texture, _mip) \
  { \
    _texture, -1, _mip, \
  }

#define GPU_ATTACHMENT_TEXTURE_LAYER(_texture, _layer) \
  { \
    _texture, _layer, 0, \
  }

#define GPU_ATTACHMENT_TEXTURE_LAYER_MIP(_texture, _layer, _mip) \
  { \
    _texture, _layer, _mip, \
  }


#define GPU_ATTACHMENT_TEXTURE_CUBEFACE(_texture, _face) \
  { \
    _texture, _face, 0, \
  }

#define GPU_ATTACHMENT_TEXTURE_CUBEFACE_MIP(_texture, _face, _mip) \
  { \
    _texture, _face, _mip, \
  }

void GPU_framebuffer_texture_attach(GPUFrameBuffer *fb, GPUTexture *texture, int slot, int mip);

void GPU_framebuffer_texture_layer_attach(
    GPUFrameBuffer *fb, GPUTexture *texture, int slot, int layer, int mip);

void GPU_framebuffer_texture_cubeface_attach(
    GPUFrameBuffer *fb, GPUTexture *texture, int slot, int face, int mip);

void GPU_framebuffer_texture_detach(GPUFrameBuffer *fb, GPUTexture *texture);

bool GPU_framebuffer_check_valid(GPUFrameBuffer *fb, char err_out[256]);

 
/* -------------------------------------------------------------------- */

void GPU_framebuffer_default_size(GPUFrameBuffer *fb, int width, int height);

 
/* -------------------------------------------------------------------- */

void GPU_framebuffer_viewport_set(GPUFrameBuffer *fb, int x, int y, int width, int height);

void GPU_framebuffer_multi_viewports_set(GPUFrameBuffer *gpu_fb,
                                         const int viewport_rects[GPU_MAX_VIEWPORTS][4]);

void GPU_framebuffer_viewport_get(GPUFrameBuffer *fb, int r_viewport[4]);

void GPU_framebuffer_viewport_reset(GPUFrameBuffer *fb);

 
/* -------------------------------------------------------------------- */

void GPU_framebuffer_clear(GPUFrameBuffer *fb,
                           eGPUFrameBufferBits buffers,
                           const float clear_col[4],
                           float clear_depth,
                           unsigned int clear_stencil);

void GPU_framebuffer_clear_color(GPUFrameBuffer *fb, const float clear_col[4]);

void GPU_framebuffer_clear_depth(GPUFrameBuffer *fb, float clear_depth);

void GPU_framebuffer_clear_stencil(GPUFrameBuffer *fb, uint clear_stencil);

void GPU_framebuffer_clear_color_depth(GPUFrameBuffer *fb,
                                       const float clear_col[4],
                                       float clear_depth);

void GPU_framebuffer_clear_depth_stencil(GPUFrameBuffer *fb,
                                         float clear_depth,
                                         uint clear_stencil);
void GPU_framebuffer_clear_color_depth_stencil(GPUFrameBuffer *fb,
                                               const float clear_col[4],
                                               float clear_depth,
                                               uint clear_stencil);

void GPU_framebuffer_multi_clear(GPUFrameBuffer *fb, const float (*clear_colors)[4]);

void GPU_clear_color(float red, float green, float blue, float alpha);

void GPU_clear_depth(float depth);

 
/* -------------------------------------------------------------------- */
 
const char *GPU_framebuffer_get_name(GPUFrameBuffer *fb);

 
/* -------------------------------------------------------------------- */

#ifndef GPU_NO_USE_PY_REFERENCES
void **GPU_framebuffer_py_reference_get(GPUFrameBuffer *fb);
void GPU_framebuffer_py_reference_set(GPUFrameBuffer *fb, void **py_ref);
#endif

/* TODO(fclem): This has nothing to do with the GPU module and should be move to the pyGPU module.
 */
void GPU_framebuffer_push(GPUFrameBuffer *fb);
GPUFrameBuffer *GPU_framebuffer_pop();
uint GPU_framebuffer_stack_level_get();

 
/* -------------------------------------------------------------------- */

bool GPU_framebuffer_bound(GPUFrameBuffer *fb);

void GPU_framebuffer_read_depth(GPUFrameBuffer *fb,
                                int x,
                                int y,
                                int width,
                                int height,
                                eGPUDataFormat data_format,
                                void *r_data);

void GPU_framebuffer_read_color(GPUFrameBuffer *fb,
                                int x,
                                int y,
                                int width,
                                int height,
                                int channels,
                                int slot,
                                eGPUDataFormat data_format,
                                void *r_data);

void GPU_frontbuffer_read_color(
    int x, int y, int width, int height, int channels, eGPUDataFormat data_format, void *r_data);

void GPU_framebuffer_blit(GPUFrameBuffer *fb_read,
                          int read_slot,
                          GPUFrameBuffer *fb_write,
                          int write_slot,
                          eGPUFrameBufferBits blit_buffers);

void GPU_framebuffer_recursive_downsample(GPUFrameBuffer *fb,
                                          int max_level,
                                          void (*per_level_callback)(void *user_data, int level),
                                          void *user_data);

 
/* -------------------------------------------------------------------- */
 
struct GPUOffScreen;

GPUOffScreen *GPU_offscreen_create(int width,
                                   int height,
                                   bool with_depth_buffer,
                                   eGPUTextureFormat format,
                                   eGPUTextureUsage usage,
                                   bool clear,
                                   char err_out[256]);

void GPU_offscreen_free(GPUOffScreen *offscreen);

/* TODO(fclem): Remove the `save` parameter and always save/restore. */
void GPU_offscreen_bind(GPUOffScreen *offscreen, bool save);

/* TODO(fclem): Remove the `save` parameter and always save/restore. */
void GPU_offscreen_unbind(GPUOffScreen *offscreen, bool restore);

void GPU_offscreen_read_color(GPUOffScreen *offscreen, eGPUDataFormat data_format, void *r_data);
void GPU_offscreen_read_color_region(
    GPUOffScreen *offscreen, eGPUDataFormat data_format, int x, int y, int w, int h, void *r_data);

void GPU_offscreen_draw_to_screen(GPUOffScreen *offscreen, int x, int y);

int GPU_offscreen_width(const GPUOffScreen *offscreen);

int GPU_offscreen_height(const GPUOffScreen *offscreen);

GPUTexture *GPU_offscreen_color_texture(const GPUOffScreen *offscreen);

eGPUTextureFormat GPU_offscreen_format(const GPUOffScreen *offscreen);

void GPU_offscreen_viewport_data_get(GPUOffScreen *offscreen,
                                     GPUFrameBuffer **r_fb,
                                     GPUTexture **r_color,
                                     GPUTexture **r_depth);