Multi-View: Cycles - Spherical Stereo support (VR Panoramas)

This is a new option for panorama cameras to render
stereo that can be used in virtual reality devices

The option is available under the camera panel when Multi-View is enabled (Views option in the Render Layers panel)

Known limitations:
------------------
* Parallel convergence is not supported (you need to set a convergence distance really high to simulate this effect).

* Pivot was not supposed to affect the render but it does, this has to be looked at, but for now set it to CENTER

* Derivatives in perspective camera need to be pre-computed or we shuld get rid of kcam->dx/dy (Sergey words, I don't fully grasp the implication shere)

* This works in perspective mode and in panorama mode. However, for fully benefit from this effect in perspective mode you need to render a cube map. (there is an addon for this, developed separately, perhaps we could include it in master).

* We have no support for "neck distance" at the moment. This is supposed to help with objects at short distances.

* We have no support to rotate the "Up Axis" of the stereo plane. Meaning, we hardcode 0,0,1 as UP, and create the stereo pair related to that. (although we could take the camera local UP when rendering panoramas, this wouldn't work for perspective cameras.

* We have no support for interocular distance attenuation based on the proximity of the poles  (which helps to reduce the pole rotation effect/artifact).

THIS NEEDS DOCS - both in 2.78 release log and the Blender manual.
Meanwhile you can read about it here: http://code.blender.org/2015/03/1451

This patch specifically dates from March 2015, as you can see in the code.blender.org post. Many thanks to all the reviewers, testers and minor sponsors who helped me maintain spherical-stereo for 1 year.

All that said, have fun with this. This feature was what got me started with Multi-View development (at the time what I was looking for was Fulldome stereo support, but the implementation is the same). In order to make this into Blender I had to make it aiming at a less-specic user-case	 Thus Multi-View started. (this was December 2012, during Siggraph Asia and a chat I had with Paul Bourke during the conference). I don't have the original patch anymore, but you can find a re-based version of it from March 2013, right before I start with the Multi-View project https://developer.blender.org/P332

Reviewers: sergey, dingto

Subscribers: #cycles

Differential Revision: https://developer.blender.org/D1223

11 files changed, 105 insertions, 7 deletions

diff --git a/source/blender/blenkernel/BKE_camera.h b/source/blender/blenkernel/BKE_camera.h
index 118153a9163..d13a711c589 100644
--- a/source/blender/blenkernel/BKE_camera.h
+++ b/source/blender/blenkernel/BKE_camera.h
@@ -144,6 +144,7 @@ void           BKE_camera_multiview_view_matrix(struct RenderData *rd, struct Ob
 void           BKE_camera_multiview_model_matrix(struct RenderData *rd, struct Object *camera, const char *viewname, float r_modelmat[4][4]);
 float          BKE_camera_multiview_shift_x(struct RenderData *rd, struct Object *camera, const char *viewname);
 void           BKE_camera_multiview_params(struct RenderData *rd, struct CameraParams *params, struct Object *camera, const char *viewname);
+bool           BKE_camera_multiview_spherical_stereo(struct RenderData *rd, struct Object *camera);
 
 #ifdef __cplusplus
 }
diff --git a/source/blender/blenkernel/BKE_scene.h b/source/blender/blenkernel/BKE_scene.h
index 2eac5b6ce5e..a4c44b9934e 100644
--- a/source/blender/blenkernel/BKE_scene.h
+++ b/source/blender/blenkernel/BKE_scene.h
@@ -135,6 +135,7 @@ float get_render_aosss_error(const struct RenderData *r, float error);
 
 bool BKE_scene_use_new_shading_nodes(const struct Scene *scene);
 bool BKE_scene_use_shading_nodes_custom(struct Scene *scene);
+bool BKE_scene_use_spherical_stereo(struct Scene *scene);
 
 bool BKE_scene_uses_blender_internal(const struct Scene *scene);
 bool BKE_scene_uses_blender_game(const struct Scene *scene);
diff --git a/source/blender/blenkernel/intern/camera.c b/source/blender/blenkernel/intern/camera.c
index 73b1f0e53f6..6fd756e2788 100644
--- a/source/blender/blenkernel/intern/camera.c
+++ b/source/blender/blenkernel/intern/camera.c
@@ -845,6 +845,29 @@ void BKE_camera_multiview_model_matrix(RenderData *rd, Object *camera, const cha
 	normalize_m4(r_modelmat);
 }
 
+bool BKE_camera_multiview_spherical_stereo(RenderData *rd, Object *camera)
+{
+	Camera *cam;
+	const bool is_multiview = (rd && rd->scemode & R_MULTIVIEW) != 0;
+
+	if (!is_multiview)
+		return false;
+
+	if (camera->type != OB_CAMERA)
+		return false;
+	else
+		cam = camera->data;
+
+	if ((rd->views_format == SCE_VIEWS_FORMAT_STEREO_3D) &&
+	    ELEM(cam->type, CAM_PANO, CAM_PERSP) &&
+	    ((cam->stereo.flag & CAM_S3D_SPHERICAL) != 0))
+	{
+		return true;
+	}
+
+	return false;
+}
+
 static Object *camera_multiview_advanced(Scene *scene, Object *camera, const char *suffix)
 {
 	SceneRenderView *srv;
diff --git a/source/blender/blenkernel/intern/scene.c b/source/blender/blenkernel/intern/scene.c
index 3ce000abcfb..6b297a143d6 100644
--- a/source/blender/blenkernel/intern/scene.c
+++ b/source/blender/blenkernel/intern/scene.c
@@ -2192,6 +2192,12 @@ bool BKE_scene_use_shading_nodes_custom(Scene *scene)
 	return (type && type->flag & RE_USE_SHADING_NODES_CUSTOM);
 }
 
+bool BKE_scene_use_spherical_stereo(Scene *scene)
+{
+	RenderEngineType *type = RE_engines_find(scene->r.engine);
+	return (type && type->flag & RE_USE_SPHERICAL_STEREO);
+}
+
 bool BKE_scene_uses_blender_internal(const  Scene *scene)
 {
 	return STREQ(scene->r.engine, RE_engine_id_BLENDER_RENDER);
diff --git a/source/blender/makesdna/DNA_camera_types.h b/source/blender/makesdna/DNA_camera_types.h
index c45322b818f..7f2e1aaadf9 100644
--- a/source/blender/makesdna/DNA_camera_types.h
+++ b/source/blender/makesdna/DNA_camera_types.h
@@ -51,7 +51,8 @@ typedef struct CameraStereoSettings {
 	float convergence_distance;
 	short convergence_mode;
 	short pivot;
-	short pad, pad2;
+	short flag;
+	short pad;
 } CameraStereoSettings;
 
 typedef struct Camera {
@@ -148,6 +149,11 @@ enum {
 	CAM_S3D_PIVOT_CENTER    = 2,
 };
 
+/* stereo->flag */
+enum {
+	CAM_S3D_SPHERICAL       = (1 << 0),
+};
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/makesrna/intern/rna_camera.c b/source/blender/makesrna/intern/rna_camera.c
index 341cbb70d64..e3f27625356 100644
--- a/source/blender/makesrna/intern/rna_camera.c
+++ b/source/blender/makesrna/intern/rna_camera.c
@@ -144,6 +144,13 @@ static void rna_def_camera_stereo_data(BlenderRNA *brna)
 	                         "The converge point for the stereo cameras "
 	                         "(often the distance between a projector and the projection screen)");
 	RNA_def_property_update(prop, NC_OBJECT | ND_DRAW, NULL);
+
+	prop = RNA_def_property(srna, "use_spherical_stereo", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_sdna(prop, NULL, "flag", CAM_S3D_SPHERICAL);
+	RNA_def_property_ui_text(prop, "Spherical Stereo",
+	                         "Render every pixel rotating the camera around the "
+	                         "middle of the interocular distance");
+	RNA_def_property_update(prop, NC_OBJECT | ND_DRAW, NULL);
 }
 
 void RNA_def_camera(BlenderRNA *brna)
diff --git a/source/blender/makesrna/intern/rna_render.c b/source/blender/makesrna/intern/rna_render.c
index 6fce93dd9f6..84382704b2b 100644
--- a/source/blender/makesrna/intern/rna_render.c
+++ b/source/blender/makesrna/intern/rna_render.c
@@ -522,6 +522,10 @@ static void rna_def_render_engine(BlenderRNA *brna)
 	prop = RNA_def_boolean(func, "do_break", 0, "Break", "");
 	RNA_def_function_return(func, prop);
 
+	func = RNA_def_function(srna, "active_view_get", "RE_engine_active_view_get");
+	prop = RNA_def_string(func, "view", NULL, 0, "View", "Single view active");
+	RNA_def_function_return(func, prop);
+
 	func = RNA_def_function(srna, "active_view_set", "RE_engine_active_view_set");
 	RNA_def_string(func, "view", NULL, 0, "View", "Single view to set as active");  /* NULL ok here */
 	RNA_def_property_flag(prop, PROP_REQUIRED);
@@ -529,15 +533,23 @@ static void rna_def_render_engine(BlenderRNA *brna)
 	func = RNA_def_function(srna, "camera_shift_x", "RE_engine_get_camera_shift_x");
 	prop = RNA_def_pointer(func, "camera", "Object", "", "");
 	RNA_def_property_flag(prop, PROP_REQUIRED);
+	prop = RNA_def_boolean(func, "use_spherical_stereo", 0, "Spherical Stereo", "");
 	prop = RNA_def_float(func, "shift_x", 0.0f, 0.0f, FLT_MAX, "Shift X", "", 0.0f, FLT_MAX);
 	RNA_def_function_return(func, prop);
 
 	func = RNA_def_function(srna, "camera_model_matrix", "RE_engine_get_camera_model_matrix");
 	prop = RNA_def_pointer(func, "camera", "Object", "", "");
 	RNA_def_property_flag(prop, PROP_REQUIRED);
+	prop = RNA_def_boolean(func, "use_spherical_stereo", 0, "Spherical Stereo", "");
 	prop = RNA_def_float_matrix(func, "r_model_matrix", 4, 4, NULL, 0.0f, 0.0f, "Model Matrix", "Normalized camera model matrix", 0.0f, 0.0f);
 	RNA_def_property_flag(prop, PROP_REQUIRED);
 
+	func = RNA_def_function(srna, "use_spherical_stereo", "RE_engine_get_spherical_stereo");
+	prop = RNA_def_pointer(func, "camera", "Object", "", "");
+	RNA_def_property_flag(prop, PROP_REQUIRED);
+	prop = RNA_def_boolean(func, "use_spherical_stereo", 0, "Spherical Stereo", "");
+	RNA_def_function_return(func, prop);
+
 	func = RNA_def_function(srna, "update_stats", "RE_engine_update_stats");
 	RNA_def_function_ui_description(func, "Update and signal to redraw render status text");
 	prop = RNA_def_string(func, "stats", NULL, 0, "Stats", "");
@@ -667,6 +679,10 @@ static void rna_def_render_engine(BlenderRNA *brna)
 	RNA_def_property_boolean_sdna(prop, NULL, "type->flag", RE_USE_SAVE_BUFFERS);
 	RNA_def_property_flag(prop, PROP_REGISTER_OPTIONAL);
 
+	prop = RNA_def_property(srna, "bl_use_spherical_stereo", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_sdna(prop, NULL, "type->flag", RE_USE_SPHERICAL_STEREO);
+	RNA_def_property_flag(prop, PROP_REGISTER_OPTIONAL);
+
 	RNA_define_verify_sdna(1);
 }
 
diff --git a/source/blender/makesrna/intern/rna_scene.c b/source/blender/makesrna/intern/rna_scene.c
index 7505dc28210..412c0bc0f96 100644
--- a/source/blender/makesrna/intern/rna_scene.c
+++ b/source/blender/makesrna/intern/rna_scene.c
@@ -1470,6 +1470,12 @@ static int rna_RenderSettings_use_shading_nodes_get(PointerRNA *ptr)
 	return BKE_scene_use_new_shading_nodes(scene);
 }
 
+static int rna_RenderSettings_use_spherical_stereo_get(PointerRNA *ptr)
+{
+	Scene *scene = (Scene *)ptr->id.data;
+	return BKE_scene_use_spherical_stereo(scene);
+}
+
 static int rna_RenderSettings_use_game_engine_get(PointerRNA *ptr)
 {
 	RenderData *rd = (RenderData *)ptr->data;
@@ -5945,6 +5951,11 @@ static void rna_def_scene_render_data(BlenderRNA *brna)
 	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
 	RNA_def_property_ui_text(prop, "Use Shading Nodes", "Active render engine uses new shading nodes system");
 
+	prop = RNA_def_property(srna, "use_spherical_stereo", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_funcs(prop, "rna_RenderSettings_use_spherical_stereo_get", NULL);
+	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+	RNA_def_property_ui_text(prop, "Use Spherical Stereo", "Active render engine supports spherical stereo rendering");
+
 	prop = RNA_def_property(srna, "use_game_engine", PROP_BOOLEAN, PROP_NONE);
 	RNA_def_property_boolean_funcs(prop, "rna_RenderSettings_use_game_engine_get", NULL);
 	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
diff --git a/source/blender/render/extern/include/RE_engine.h b/source/blender/render/extern/include/RE_engine.h
index d08b637454b..f83a210275f 100644
--- a/source/blender/render/extern/include/RE_engine.h
+++ b/source/blender/render/extern/include/RE_engine.h
@@ -62,6 +62,7 @@ struct BakePixel;
 #define RE_USE_SAVE_BUFFERS		64
 #define RE_USE_TEXTURE_PREVIEW		128
 #define RE_USE_SHADING_NODES_CUSTOM 	256
+#define RE_USE_SPHERICAL_STEREO 512
 
 /* RenderEngine.flag */
 #define RE_ENGINE_ANIMATION		1
@@ -140,9 +141,11 @@ struct RenderResult *RE_engine_begin_result(RenderEngine *engine, int x, int y,
 void RE_engine_update_result(RenderEngine *engine, struct RenderResult *result);
 void RE_engine_end_result(RenderEngine *engine, struct RenderResult *result, int cancel, int merge_results);
 
+const char *RE_engine_active_view_get(RenderEngine *engine);
 void RE_engine_active_view_set(RenderEngine *engine, const char *viewname);
-float RE_engine_get_camera_shift_x(RenderEngine *engine, struct Object *camera);
-void RE_engine_get_camera_model_matrix(RenderEngine *engine, struct Object *camera, float *r_modelmat);
+float RE_engine_get_camera_shift_x(RenderEngine *engine, struct Object *camera, int use_spherical_stereo);
+void RE_engine_get_camera_model_matrix(RenderEngine *engine, struct Object *camera, int use_spherical_stereo, float *r_modelmat);
+int RE_engine_get_spherical_stereo(RenderEngine *engine, struct Object *camera);
 
 int RE_engine_test_break(RenderEngine *engine);
 void RE_engine_update_stats(RenderEngine *engine, const char *stats, const char *info);
diff --git a/source/blender/render/intern/source/external_engine.c b/source/blender/render/intern/source/external_engine.c
index b31760c34dd..fd9d95c63b6 100644
--- a/source/blender/render/intern/source/external_engine.c
+++ b/source/blender/render/intern/source/external_engine.c
@@ -372,24 +372,46 @@ void RE_engine_set_error_message(RenderEngine *engine, const char *msg)
 	}
 }
 
+const char *RE_engine_active_view_get(RenderEngine *engine)
+{
+	Render *re = engine->re;
+	return RE_GetActiveRenderView(re);
+}
+
 void RE_engine_active_view_set(RenderEngine *engine, const char *viewname)
 {
 	Render *re = engine->re;
 	RE_SetActiveRenderView(re, viewname);
 }
 
-float RE_engine_get_camera_shift_x(RenderEngine *engine, Object *camera)
+float RE_engine_get_camera_shift_x(RenderEngine *engine, Object *camera, int use_spherical_stereo)
 {
 	Render *re = engine->re;
+
+	/* when using spherical stereo, get camera shift without multiview, leaving stereo to be handled by the engine */
+	if (use_spherical_stereo)
+		re = NULL;
+
 	return BKE_camera_multiview_shift_x(re ? &re->r : NULL, camera, re->viewname);
 }
 
-void RE_engine_get_camera_model_matrix(RenderEngine *engine, Object *camera, float *r_modelmat)
+void RE_engine_get_camera_model_matrix(RenderEngine *engine, Object *camera, int use_spherical_stereo, float *r_modelmat)
 {
 	Render *re = engine->re;
+
+	/* when using spherical stereo, get model matrix without multiview, leaving stereo to be handled by the engine */
+	if (use_spherical_stereo)
+		re = NULL;
+
 	BKE_camera_multiview_model_matrix(re ? &re->r : NULL, camera, re->viewname, (float (*)[4])r_modelmat);
 }
 
+int RE_engine_get_spherical_stereo(RenderEngine *engine, Object *camera)
+{
+	Render *re = engine->re;
+	return BKE_camera_multiview_spherical_stereo(re ? &re->r : NULL, camera) ? 1 : 0;
+}
+
 rcti* RE_engine_get_current_tiles(Render *re, int *r_total_tiles, bool *r_needs_free)
 {
 	static rcti tiles_static[BLENDER_MAX_THREADS];
diff --git a/source/blenderplayer/bad_level_call_stubs/stubs.c b/source/blenderplayer/bad_level_call_stubs/stubs.c
index e96e866245a..bbf0ffa4cd4 100644
--- a/source/blenderplayer/bad_level_call_stubs/stubs.c
+++ b/source/blenderplayer/bad_level_call_stubs/stubs.c
@@ -230,9 +230,11 @@ void RE_texture_rng_init() RET_NONE
 void RE_texture_rng_exit() RET_NONE
 
 bool RE_layers_have_name(struct RenderResult *result) {STUB_ASSERT(0); return 0;}
+const char *RE_engine_active_view_get(struct RenderEngine *engine) RET_NULL
 void RE_engine_active_view_set(struct RenderEngine *engine, const char *viewname) {STUB_ASSERT(0);}
-void RE_engine_get_camera_model_matrix(struct RenderEngine *engine, struct Object *camera, float *r_modelmat) {STUB_ASSERT(0);}
-float RE_engine_get_camera_shift_x(struct RenderEngine *engine, struct Object *camera) RET_ZERO
+void RE_engine_get_camera_model_matrix(struct RenderEngine *engine, struct Object *camera, int use_spherical_stereo, float *r_modelmat) {STUB_ASSERT(0);}
+float RE_engine_get_camera_shift_x(struct RenderEngine *engine, struct Object *camera, int use_spherical_stereo) RET_ZERO
+int RE_engine_get_spherical_stereo(struct RenderEngine *engine, struct Object *camera) RET_ZERO
 void RE_SetActiveRenderView(struct Render *re, const char *viewname) {STUB_ASSERT(0);}
 
 struct RenderPass *RE_pass_find_by_type(volatile struct RenderLayer *rl, int passtype, const char *viewname) RET_NULL