Multi-View and Stereo 3D

Official Documentation:
http://www.blender.org/manual/render/workflows/multiview.html

Implemented Features
====================
Builtin Stereo Camera
* Convergence Mode
* Interocular Distance
* Convergence Distance
* Pivot Mode

Viewport
* Cameras
* Plane
* Volume

Compositor
* View Switch Node
* Image Node Multi-View OpenEXR support

Sequencer
* Image/Movie Strips 'Use Multiview'

UV/Image Editor
* Option to see Multi-View images in Stereo-3D or its individual images
* Save/Open Multi-View (OpenEXR, Stereo3D, individual views) images

I/O
* Save/Open Multi-View (OpenEXR, Stereo3D, individual views) images

Scene Render Views
* Ability to have an arbitrary number of views in the scene

Missing Bits
============
First rule of Multi-View bug report: If something is not working as it should *when Views is off* this is a severe bug, do mention this in the report.

Second rule is, if something works *when Views is off* but doesn't (or crashes) when *Views is on*, this is a important bug. Do mention this in the report.

Everything else is likely small todos, and may wait until we are sure none of the above is happening.

Apart from that there are those known issues:
* Compositor Image Node poorly working for Multi-View OpenEXR
(this was working prefectly before the 'Use Multi-View' functionality)
* Selecting camera from Multi-View when looking from camera is problematic
* Animation Playback (ctrl+F11) doesn't support stereo formats
* Wrong filepath when trying to play back animated scene
* Viewport Rendering doesn't support Multi-View
* Overscan Rendering
* Fullscreen display modes need to warn the user
* Object copy should be aware of views suffix

Acknowledgments
===============
* Francesco Siddi for the help with the original feature specs and design
* Brecht Van Lommel for the original review of the code and design early on
* Blender Foundation for the Development Fund to support the project wrap up

Final patch reviewers:
* Antony Riakiotakis (psy-fi)
* Campbell Barton (ideasman42)
* Julian Eisel (Severin)
* Sergey Sharybin (nazgul)
* Thomas Dinged (dingto)

Code contributors of the original branch in github:
* Alexey Akishin
* Gabriel Caraballo

1 files changed, 101 insertions, 27 deletions

diff --git a/source/blender/makesrna/intern/rna_render.c b/source/blender/makesrna/intern/rna_render.c
index 124a83a5f30..94fabb857e3 100644
--- a/source/blender/makesrna/intern/rna_render.c
+++ b/source/blender/makesrna/intern/rna_render.c
@@ -27,6 +27,7 @@
 #include <stdlib.h>
 
 #include "DNA_scene_types.h"
+#include "DNA_object_types.h"
 
 #include "BLI_utildefines.h"
 #include "BLI_path_util.h"
@@ -322,38 +323,35 @@ static PointerRNA rna_RenderEngine_render_get(PointerRNA *ptr)
 	}
 }
 
-static void rna_RenderResult_layers_begin(CollectionPropertyIterator *iter, PointerRNA *ptr)
+static PointerRNA rna_RenderEngine_camera_override_get(PointerRNA *ptr)
 {
-	RenderResult *rr = (RenderResult *)ptr->data;
-	rna_iterator_listbase_begin(iter, &rr->layers, NULL);
-}
+	RenderEngine *engine = (RenderEngine *)ptr->data;
 
-static void rna_RenderLayer_passes_begin(CollectionPropertyIterator *iter, PointerRNA *ptr)
-{
-	RenderLayer *rl = (RenderLayer *)ptr->data;
-	rna_iterator_listbase_begin(iter, &rl->passes, NULL);
+	if (engine->re) {
+		Object *cam = RE_GetCamera(engine->re);
+		return rna_pointer_inherit_refine(ptr, &RNA_Object, cam);
+	}
+	else {
+		return rna_pointer_inherit_refine(ptr, &RNA_Object, engine->camera_override);
+	}
 }
 
-static int rna_RenderLayer_rect_get_length(PointerRNA *ptr, int length[RNA_MAX_ARRAY_DIMENSION])
+static void rna_RenderResult_views_begin(CollectionPropertyIterator *iter, PointerRNA *ptr)
 {
-	RenderLayer *rl = (RenderLayer *)ptr->data;
-
-	length[0] = rl->rectx * rl->recty;
-	length[1] = 4;
-
-	return length[0] * length[1];
+	RenderResult *rr = (RenderResult *)ptr->data;
+	rna_iterator_listbase_begin(iter, &rr->views, NULL);
 }
 
-static void rna_RenderLayer_rect_get(PointerRNA *ptr, float *values)
+static void rna_RenderResult_layers_begin(CollectionPropertyIterator *iter, PointerRNA *ptr)
 {
-	RenderLayer *rl = (RenderLayer *)ptr->data;
-	memcpy(values, rl->rectf, sizeof(float) * rl->rectx * rl->recty * 4);
+	RenderResult *rr = (RenderResult *)ptr->data;
+	rna_iterator_listbase_begin(iter, &rr->layers, NULL);
 }
 
-void rna_RenderLayer_rect_set(PointerRNA *ptr, const float *values)
+static void rna_RenderLayer_passes_begin(CollectionPropertyIterator *iter, PointerRNA *ptr)
 {
 	RenderLayer *rl = (RenderLayer *)ptr->data;
-	memcpy(rl->rectf, values, sizeof(float) * rl->rectx * rl->recty * 4);
+	rna_iterator_listbase_begin(iter, &rl->passes, NULL);
 }
 
 static int rna_RenderPass_rect_get_length(PointerRNA *ptr, int length[RNA_MAX_ARRAY_DIMENSION])
@@ -384,6 +382,18 @@ static PointerRNA rna_BakePixel_next_get(PointerRNA *ptr)
 	return rna_pointer_inherit_refine(ptr, &RNA_BakePixel, bp + 1);
 }
 
+static RenderPass *rna_RenderPass_find_by_type(RenderLayer *rl, int passtype, const char *view)
+{
+	RenderPass *rp;
+	for (rp = rl->passes.first; rp; rp = rp->next) {
+		if (rp->passtype == passtype) {
+			if (STREQ(rp->view, view))
+				return rp;
+		}
+	}
+	return NULL;
+}
+
 #else /* RNA_RUNTIME */
 
 static void rna_def_render_engine(BlenderRNA *brna)
@@ -467,6 +477,7 @@ static void rna_def_render_engine(BlenderRNA *brna)
 	prop = RNA_def_int(func, "h", 0, 0, INT_MAX, "Height", "", 0, INT_MAX);
 	RNA_def_property_flag(prop, PROP_REQUIRED);
 	RNA_def_string(func, "layer", NULL, 0, "Layer", "Single layer to get render result for");  /* NULL ok here */
+	RNA_def_string(func, "view", NULL, 0, "View", "Single view to get render result for");  /* NULL ok here */
 	prop = RNA_def_pointer(func, "result", "RenderResult", "Result", "");
 	RNA_def_function_return(func, prop);
 
@@ -487,6 +498,22 @@ 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_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);
+
+	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_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_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, "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", "");
@@ -548,7 +575,7 @@ static void rna_def_render_engine(BlenderRNA *brna)
 	RNA_def_property_boolean_sdna(prop, NULL, "flag", RE_ENGINE_PREVIEW);
 
 	prop = RNA_def_property(srna, "camera_override", PROP_POINTER, PROP_NONE);
-	RNA_def_property_pointer_sdna(prop, NULL, "camera_override");
+	RNA_def_property_pointer_funcs(prop, "rna_RenderEngine_camera_override_get", NULL, NULL, NULL);
 	RNA_def_property_struct_type(prop, "Object");
 
 	prop = RNA_def_property(srna, "layer_override", PROP_BOOLEAN, PROP_LAYER_MEMBER);
@@ -647,9 +674,56 @@ static void rna_def_render_result(BlenderRNA *brna)
 	                                  "rna_iterator_listbase_end", "rna_iterator_listbase_get",
 	                                  NULL, NULL, NULL, NULL);
 
+	parm = RNA_def_property(srna, "views", PROP_COLLECTION, PROP_NONE);
+	RNA_def_property_struct_type(parm, "RenderView");
+	RNA_def_property_collection_funcs(parm, "rna_RenderResult_views_begin", "rna_iterator_listbase_next",
+	                                  "rna_iterator_listbase_end", "rna_iterator_listbase_get",
+	                                  NULL, NULL, NULL, NULL);
+
+	RNA_define_verify_sdna(1);
+}
+
+static void rna_def_render_view(BlenderRNA *brna)
+{
+	StructRNA *srna;
+	PropertyRNA *prop;
+
+	srna = RNA_def_struct(brna, "RenderView", NULL);
+	RNA_def_struct_ui_text(srna, "Render View", "");
+
+	RNA_define_verify_sdna(0);
+
+	prop = RNA_def_property(srna, "name", PROP_STRING, PROP_NONE);
+	RNA_def_property_string_sdna(prop, NULL, "name");
+	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+	RNA_def_struct_name_property(srna, prop);
+
 	RNA_define_verify_sdna(1);
 }
 
+static void rna_def_render_passes(BlenderRNA *brna, PropertyRNA *cprop)
+{
+	StructRNA *srna;
+
+	FunctionRNA *func;
+	PropertyRNA *parm;
+
+	RNA_def_property_srna(cprop, "RenderPasses");
+	srna = RNA_def_struct(brna, "RenderPasses", NULL);
+	RNA_def_struct_sdna(srna, "RenderLayer");
+	RNA_def_struct_ui_text(srna, "Render Passes", "Collection of render passes");
+
+	func = RNA_def_function(srna, "find_by_type", "rna_RenderPass_find_by_type");
+	RNA_def_function_ui_description(func, "Get the render pass for a given type and view");
+	parm = RNA_def_enum(func, "pass_type", render_pass_type_items, SCE_PASS_COMBINED, "Pass", "");
+	RNA_def_property_flag(parm, PROP_REQUIRED);
+	parm = RNA_def_string(func, "view", NULL, 0, "View", "Render view to get pass from");  /* NULL ok here */
+	RNA_def_property_flag(parm, PROP_REQUIRED);
+	parm = RNA_def_pointer(func, "render_pass", "RenderPass", "", "The matching render pass");
+	RNA_def_function_return(func, parm);
+
+}
+
 static void rna_def_render_layer(BlenderRNA *brna)
 {
 	StructRNA *srna;
@@ -679,12 +753,7 @@ static void rna_def_render_layer(BlenderRNA *brna)
 	RNA_def_property_collection_funcs(prop, "rna_RenderLayer_passes_begin", "rna_iterator_listbase_next",
 	                                  "rna_iterator_listbase_end", "rna_iterator_listbase_get",
 	                                  NULL, NULL, NULL, NULL);
-
-	prop = RNA_def_property(srna, "rect", PROP_FLOAT, PROP_NONE);
-	RNA_def_property_flag(prop, PROP_DYNAMIC);
-	RNA_def_property_multi_array(prop, 2, NULL);
-	RNA_def_property_dynamic_array_funcs(prop, "rna_RenderLayer_rect_get_length");
-	RNA_def_property_float_funcs(prop, "rna_RenderLayer_rect_get", "rna_RenderLayer_rect_set", NULL);
+	rna_def_render_passes(brna, prop);
 
 	RNA_define_verify_sdna(1);
 }
@@ -728,6 +797,10 @@ static void rna_def_render_pass(BlenderRNA *brna)
 	RNA_def_property_dynamic_array_funcs(prop, "rna_RenderPass_rect_get_length");
 	RNA_def_property_float_funcs(prop, "rna_RenderPass_rect_get", "rna_RenderPass_rect_set", NULL);
 
+	prop = RNA_def_property(srna, "view_id", PROP_INT, PROP_NONE);
+	RNA_def_property_int_sdna(prop, NULL, "view_id");
+	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+
 	prop = RNA_def_property(srna, "debug_type", PROP_ENUM, PROP_NONE);
 	RNA_def_property_enum_sdna(prop, NULL, "debug_type");
 	RNA_def_property_enum_items(prop, render_pass_debug_type_items);
@@ -783,6 +856,7 @@ void RNA_def_render(BlenderRNA *brna)
 {
 	rna_def_render_engine(brna);
 	rna_def_render_result(brna);
+	rna_def_render_view(brna);
 	rna_def_render_layer(brna);
 	rna_def_render_pass(brna);
 	rna_def_render_bake_pixel(brna);