Merge branch 'master' into draw-viewport-data

# Conflicts:
#	source/blender/draw/DRW_engine_types.h
#	source/blender/draw/intern/draw_manager.c
#	source/blender/draw/intern/draw_manager.h
#	source/blender/draw/intern/draw_manager_profiling.c
#	source/blender/draw/intern/draw_manager_text.h
#	source/blender/draw/intern/draw_texture_pool.cc
#	source/blender/draw/intern/draw_texture_pool.h
#	source/blender/draw/intern/draw_view_data.cc
#	source/blender/draw/intern/draw_view_data.h
#	source/blender/editors/space_view3d/view3d_draw.c
#	source/blender/gpu/GPU_texture.h
#	source/blender/gpu/GPU_viewport.h
#	source/blender/gpu/intern/gpu_shader_create_info_private.hh
#	source/blender/gpu/intern/gpu_viewport.c

1 files changed, 27 insertions, 8 deletions

diff --git a/source/blender/blenkernel/BKE_camera.h b/source/blender/blenkernel/BKE_camera.h
index b42fcbe7808..ee78621c11f 100644
--- a/source/blender/blenkernel/BKE_camera.h
+++ b/source/blender/blenkernel/BKE_camera.h
@@ -37,22 +37,26 @@ struct Scene;
 struct View3D;
 struct rctf;
 
-/* Camera Datablock */
+/* Camera Data-block */
 
 void *BKE_camera_add(struct Main *bmain, const char *name);
 
 /* Camera Usage */
 
+/**
+ * Get the camera's DOF value, takes the DOF object into account.
+ */
 float BKE_camera_object_dof_distance(struct Object *ob);
 
 int BKE_camera_sensor_fit(int sensor_fit, float sizex, float sizey);
 float BKE_camera_sensor_size(int sensor_fit, float sensor_x, float sensor_y);
 
-/* Camera Parameters:
+/**
+ * Camera Parameters:
  *
  * Intermediate struct for storing camera parameters from various sources,
- * to unify computation of viewplane, window matrix, ... */
-
+ * to unify computation of view-plane, window matrix, ... etc.
+ */
 typedef struct CameraParams {
   /* lens */
   bool is_ortho;
@@ -84,7 +88,7 @@ typedef struct CameraParams {
   float winmat[4][4];
 } CameraParams;
 
-/* values for CameraParams.zoom, need to be taken into account for some operations */
+/* Values for CameraParams.zoom, need to be taken into account for some operations. */
 #define CAMERA_PARAM_ZOOM_INIT_CAMOB 1.0f
 #define CAMERA_PARAM_ZOOM_INIT_PERSP 2.0f
 
@@ -97,14 +101,17 @@ void BKE_camera_params_from_view3d(CameraParams *params,
 
 void BKE_camera_params_compute_viewplane(
     CameraParams *params, int winx, int winy, float aspx, float aspy);
+/**
+ * View-plane is assumed to be already computed.
+ */
 void BKE_camera_params_compute_matrix(CameraParams *params);
 
 /* Camera View Frame */
 
 void BKE_camera_view_frame_ex(const struct Scene *scene,
                               const struct Camera *camera,
-                              const float drawsize,
-                              const bool do_clip,
+                              float drawsize,
+                              bool do_clip,
                               const float scale[3],
                               float r_asp[2],
                               float r_shift[2],
@@ -114,6 +121,11 @@ void BKE_camera_view_frame(const struct Scene *scene,
                            const struct Camera *camera,
                            float r_vec[4][3]);
 
+/**
+ * \param r_scale: only valid/useful for orthographic cameras.
+ *
+ * \note Don't move the camera, just yield the fit location.
+ */
 bool BKE_camera_view_frame_fit_to_scene(struct Depsgraph *depsgraph,
                                         const struct Scene *scene,
                                         struct Object *camera_ob,
@@ -128,12 +140,18 @@ bool BKE_camera_view_frame_fit_to_coords(const struct Depsgraph *depsgraph,
 
 /* Camera multi-view API */
 
+/**
+ * Returns the camera to be used for render.
+ */
 struct Object *BKE_camera_multiview_render(const struct Scene *scene,
                                            struct Object *camera,
                                            const char *viewname);
+/**
+ * The view matrix is used by the viewport drawing, it is basically the inverted model matrix.
+ */
 void BKE_camera_multiview_view_matrix(const struct RenderData *rd,
                                       const struct Object *camera,
-                                      const bool is_left,
+                                      bool is_left,
                                       float r_viewmat[4][4]);
 void BKE_camera_multiview_model_matrix(const struct RenderData *rd,
                                        const struct Object *camera,
@@ -158,6 +176,7 @@ bool BKE_camera_multiview_spherical_stereo(const struct RenderData *rd,
                                            const struct Object *camera);
 
 /* Camera background image API */
+
 struct CameraBGImage *BKE_camera_background_image_new(struct Camera *cam);
 void BKE_camera_background_image_remove(struct Camera *cam, struct CameraBGImage *bgpic);
 void BKE_camera_background_image_clear(struct Camera *cam);