Blender  V3.3
session/display_driver.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: Apache-2.0
2  * Copyright 2021-2022 Blender Foundation */
3 
4 #pragma once
5 
6 #include "util/half.h"
7 #include "util/types.h"
8 
10 
11 /* Display driver for efficient interactive display of renders.
12  *
13  * Host applications implement this interface for viewport rendering. For best performance, we
14  * recommend:
15  * - Allocating a texture on the GPU to be interactively updated
16  * - Using the graphics interop mechanism to avoid CPU-GPU copying overhead
17  * - Using a dedicated or thread-safe graphics API context for updates, to avoid
18  * blocking the host application.
19  */
21  public:
22  DisplayDriver() = default;
23  virtual ~DisplayDriver() = default;
24 
25  /* Render buffer parameters. */
26  struct Params {
27  public:
28  /* Render resolution, ignoring progressive resolution changes.
29  * The texture buffer should be allocated with this size. */
30  int2 size = make_int2(0, 0);
31 
32  /* For border rendering, the full resolution of the render, and the offset within that larger
33  * render. */
36 
37  bool modified(const Params &other) const
38  {
39  return !(full_offset == other.full_offset && full_size == other.full_size &&
40  size == other.size);
41  }
42  };
43 
44  virtual void next_tile_begin() = 0;
45 
46  /* Update the render from the rendering thread.
47  *
48  * Cycles periodically updates the render to be displayed. For multithreaded updates with
49  * potentially multiple rendering devices, it will call these methods as follows.
50  *
51  * if (driver.update_begin(params, width, height)) {
52  * parallel_for_each(rendering_device) {
53  * buffer = driver.map_texture_buffer();
54  * if (buffer) {
55  * fill(buffer);
56  * driver.unmap_texture_buffer();
57  * }
58  * }
59  * driver.update_end();
60  * }
61  *
62  * The parameters may dynamically change due to camera changes in the scene, and resources should
63  * be re-allocated accordingly.
64  *
65  * The width and height passed to update_begin() are the effective render resolution taking into
66  * account progressive resolution changes, which may be equal to or smaller than the params.size.
67  * For efficiency, changes in this resolution should be handled without re-allocating resources,
68  * but rather by using a subset of the full resolution buffer. */
69  virtual bool update_begin(const Params &params, int width, int height) = 0;
70  virtual void update_end() = 0;
71 
72  /* Optionally flush outstanding display commands before ending the render loop. */
73  virtual void flush(){};
74 
75  virtual half4 *map_texture_buffer() = 0;
76  virtual void unmap_texture_buffer() = 0;
77 
78  /* Optionally return a handle to a native graphics API texture buffer. If supported,
79  * the rendering device may write directly to this buffer instead of calling
80  * map_texture_buffer() and unmap_texture_buffer(). */
82  public:
83  /* Dimensions of the buffer, in pixels. */
84  int buffer_width = 0;
85  int buffer_height = 0;
86 
87  /* OpenGL pixel buffer object. */
88  int opengl_pbo_id = 0;
89 
90  /* Clear the entire buffer before doing partial write to it. */
91  bool need_clear = false;
92 
93  /* Enforce re-creation of the graphics interop object.
94  *
95  * When this field is true then the graphics interop will be re-created no matter what the
96  * rest of the configuration is.
97  * When this field is false the graphics interop will be re-created if the PBO or buffer size
98  * did change.
99  *
100  * This allows to ensure graphics interop is re-created when there is a possibility that an
101  * underlying PBO was re-allocated but did not change its ID. */
102  bool need_recreate = false;
103  };
104 
106  {
107  return GraphicsInterop();
108  }
109 
110  /* (De)activate graphics context required for editing or deleting the graphics interop
111  * object.
112  *
113  * For example, destruction of the CUDA object associated with an OpenGL requires the
114  * OpenGL context to be active. */
115  virtual void graphics_interop_activate(){};
116  virtual void graphics_interop_deactivate(){};
117 
118  /* Clear the display buffer by filling it with zeros. */
119  virtual void clear() = 0;
120 
121  /* Draw the render using the native graphics API.
122  *
123  * Note that this may be called in parallel to updates. The implementation is responsible for
124  * mutex locking or other mechanisms to avoid conflicts.
125  *
126  * The parameters may have changed since the last update. The implementation is responsible for
127  * deciding to skip or adjust render display for such changes.
128  *
129  * Host application drawing the render buffer should use Session.draw(), which will
130  * call this method. */
131  virtual void draw(const Params &params) = 0;
132 };
133 
_GL_VOID GLfloat value _GL_VOID_RET _GL_VOID const GLuint GLboolean *residences _GL_BOOL_RET _GL_VOID GLsizei height
_GL_VOID GLfloat value _GL_VOID_RET _GL_VOID const GLuint GLboolean *residences _GL_BOOL_RET _GL_VOID GLsizei GLfloat GLfloat GLfloat GLfloat const GLubyte *bitmap _GL_VOID_RET _GL_VOID GLenum const void *lists _GL_VOID_RET _GL_VOID const GLdouble *equation _GL_VOID_RET _GL_VOID GLdouble GLdouble blue _GL_VOID_RET _GL_VOID GLfloat GLfloat blue _GL_VOID_RET _GL_VOID GLint GLint blue _GL_VOID_RET _GL_VOID GLshort GLshort blue _GL_VOID_RET _GL_VOID GLubyte GLubyte blue _GL_VOID_RET _GL_VOID GLuint GLuint blue _GL_VOID_RET _GL_VOID GLushort GLushort blue _GL_VOID_RET _GL_VOID GLbyte GLbyte GLbyte alpha _GL_VOID_RET _GL_VOID GLdouble GLdouble GLdouble alpha _GL_VOID_RET _GL_VOID GLfloat GLfloat GLfloat alpha _GL_VOID_RET _GL_VOID GLint GLint GLint alpha _GL_VOID_RET _GL_VOID GLshort GLshort GLshort alpha _GL_VOID_RET _GL_VOID GLubyte GLubyte GLubyte alpha _GL_VOID_RET _GL_VOID GLuint GLuint GLuint alpha _GL_VOID_RET _GL_VOID GLushort GLushort GLushort alpha _GL_VOID_RET _GL_VOID GLenum mode _GL_VOID_RET _GL_VOID GLint GLsizei width
virtual void flush()
virtual half4 * map_texture_buffer()=0
virtual void update_end()=0
virtual void next_tile_begin()=0
virtual bool update_begin(const Params &params, int width, int height)=0
virtual GraphicsInterop graphics_interop_get()
virtual void draw(const Params &params)=0
DisplayDriver()=default
virtual ~DisplayDriver()=default
virtual void clear()=0
virtual void unmap_texture_buffer()=0
virtual void graphics_interop_activate()
virtual void graphics_interop_deactivate()
#define CCL_NAMESPACE_END
Definition: cuda/compat.h:9
uiWidgetBaseParameters params[MAX_WIDGET_BASE_BATCH]
#define make_int2(x, y)
Definition: metal/compat.h:206
bool modified(const Params &other) const
Definition: half.h:64