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, 58 insertions, 7 deletions

diff --git a/source/blender/render/extern/include/RE_pipeline.h b/source/blender/render/extern/include/RE_pipeline.h
index d1b6673c792..2a07246eaba 100644
--- a/source/blender/render/extern/include/RE_pipeline.h
+++ b/source/blender/render/extern/include/RE_pipeline.h
@@ -35,8 +35,10 @@
 #include "DNA_listBase.h"
 #include "DNA_vec_types.h"
 
+struct bMovieHandle;
 struct bNodeTree;
 struct Image;
+struct ImageFormatData;
 struct Main;
 struct NodeBlurData;
 struct Object;
@@ -46,6 +48,7 @@ struct ReportList;
 struct Scene;
 struct SceneRenderLayer;
 struct EnvMap;
+struct RenderResult;
 
 /* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
 /* this include is what is exposed of render to outside world */
@@ -65,6 +68,19 @@ typedef struct Render Render;
  *   and how it's converted
  */
 
+typedef struct RenderView {
+	struct RenderView *next, *prev;
+	char name[64];		/* EXR_VIEW_MAXNAME */
+
+	/* if this exists, result of composited layers */
+	float *rectf;
+	/* if this exists, result of composited layers */
+	float *rectz;
+	/* optional, 32 bits version of picture, used for sequencer, ogl render and image curves */
+	int *rect32;
+
+} RenderView;
+
 typedef struct RenderPass {
 	struct RenderPass *next, *prev;
 	int passtype, channels;
@@ -72,6 +88,11 @@ typedef struct RenderPass {
 	char chan_id[8];	/* amount defined in openexr_multi.h */
 	float *rect;
 	int rectx, recty;
+
+	char internal_name[64]; /* EXR_PASS_MAXNAME */
+	char view[64];		/* EXR_VIEW_MAXNAME */
+	int view_id;	/* quick lookup */
+
 	int debug_type;
 } RenderPass;
 
@@ -81,7 +102,7 @@ enum {
 
 /* a renderlayer is a full image, but with all passes and samples */
 /* size of the rects is defined in RenderResult */
-/* after render, the Combined pass is in rectf, for renderlayers read from files it is a real pass */
+/* after render, the Combined pass is in combined, for renderlayers read from files it is a real pass */
 typedef struct RenderLayer {
 	struct RenderLayer *next, *prev;
 	
@@ -92,8 +113,10 @@ typedef struct RenderLayer {
 	
 	struct Material *mat_override;
 	struct Group *light_override;
-	
-	float *rectf;		/* 4 float, standard rgba buffer (read not above!) */
+
+	/* MULTIVIEW_TODO: acolrect and scolrect are not supported by multiview at the moment.
+	 * If they are really required they should be in RenderView instead */
+
 	float *acolrect;	/* 4 float, optional transparent buffer, needs storage for display updates */
 	float *scolrect;	/* 4 float, optional strand buffer, needs storage for display updates */
 	int *display_buffer;	/* 4 char, optional color managed display buffer which is used when
@@ -129,6 +152,9 @@ typedef struct RenderResult {
 	/* the main buffers */
 	ListBase layers;
 	
+	/* multiView maps to a StringVector in OpenEXR */
+	ListBase views;
+
 	/* allowing live updates: */
 	volatile rcti renrect;
 	volatile RenderLayer *renlay;
@@ -183,16 +209,18 @@ void RE_FreeRenderResult(struct RenderResult *rr);
 struct RenderResult *RE_AcquireResultRead(struct Render *re);
 struct RenderResult *RE_AcquireResultWrite(struct Render *re);
 void RE_ReleaseResult(struct Render *re);
-void RE_AcquireResultImage(struct Render *re, struct RenderResult *rr);
+void RE_AcquireResultImageViews(struct Render *re, struct RenderResult *rr);
+void RE_ReleaseResultImageViews(struct Render *re, struct RenderResult *rr);
+void RE_AcquireResultImage(struct Render *re, struct RenderResult *rr, const int view_id);
 void RE_ReleaseResultImage(struct Render *re);
 void RE_SwapResult(struct Render *re, struct RenderResult **rr);
 struct RenderStats *RE_GetStats(struct Render *re);
 
 void RE_ResultGet32(struct Render *re, unsigned int *rect);
-void RE_AcquiredResultGet32(struct Render *re, struct RenderResult *result, unsigned int *rect);
+void RE_AcquiredResultGet32(struct Render *re, struct RenderResult *result, unsigned int *rect, const int view_id);
 
 struct RenderLayer *RE_GetRenderLayer(struct RenderResult *rr, const char *name);
-float *RE_RenderLayerGetPass(struct RenderLayer *rl, int passtype);
+float *RE_RenderLayerGetPass(volatile struct RenderLayer *rl, int passtype, const char *viewname);
 
 /* obligatory initialize call, disprect is optional */
 void RE_InitState(struct Render *re, struct Render *source, struct RenderData *rd,
@@ -203,6 +231,7 @@ void RE_ChangeModeFlag(struct Render *re, int flag, bool clear);
 
 /* set up the viewplane/perspective matrix, three choices */
 struct Object *RE_GetCamera(struct Render *re); /* return camera override if set */
+void RE_SetOverrideCamera(struct Render *re, struct Object *camera);
 void RE_SetCamera(struct Render *re, struct Object *camera);
 void RE_SetEnvmapCamera(struct Render *re, struct Object *cam_ob, float viewscale, float clipsta, float clipend);
 void RE_SetWindow(struct Render *re, rctf *viewplane, float clipsta, float clipend);
@@ -232,6 +261,11 @@ void RE_init_threadcount(Render *re);
 /* the main processor, assumes all was set OK! */
 void RE_TileProcessor(struct Render *re);
 
+bool RE_WriteRenderViewsImage(struct ReportList *reports, struct RenderResult *rr, struct Scene *scene, struct Object *camera, const bool stamp, char *name);
+bool RE_WriteRenderViewsMovie(struct ReportList *reports, struct RenderResult *rr, struct Scene *scene, struct RenderData *rd,
+                              struct bMovieHandle *mh, const size_t width, const size_t height, void **movie_ctx_arr,
+                              const size_t totvideos);
+
 /* only RE_NewRender() needed, main Blender render calls */
 void RE_BlenderFrame(struct Render *re, struct Main *bmain, struct Scene *scene,
                      struct SceneRenderLayer *srl, struct Object *camera_override,
@@ -243,6 +277,9 @@ void RE_RenderFreestyleStrokes(struct Render *re, struct Main *bmain, struct Sce
 void RE_RenderFreestyleExternal(struct Render *re);
 #endif
 
+void RE_SetActiveRenderView(struct Render *re, const char *viewname);
+const char *RE_GetActiveRenderView(struct Render *re);
+
 /* error reporting */
 void RE_SetReports(struct Render *re, struct ReportList *reports);
 
@@ -250,7 +287,7 @@ void RE_SetReports(struct Render *re, struct ReportList *reports);
 void RE_PreviewRender(struct Render *re, struct Main *bmain, struct Scene *scene);
 
 bool RE_ReadRenderResult(struct Scene *scene, struct Scene *scenode);
-bool RE_WriteRenderResult(struct ReportList *reports, RenderResult *rr, const char *filename, int compress);
+bool RE_WriteRenderResult(struct ReportList *reports, RenderResult *rr, const char *filename, struct ImageFormatData *imf, const bool multiview, const char *view);
 struct RenderResult *RE_MultilayerConvert(void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty);
 
 extern const float default_envmap_layout[];
@@ -276,6 +313,8 @@ void RE_zbuf_accumulate_vecblur(struct NodeBlurData *nbd, int xsize, int ysize,
 
 int RE_seq_render_active(struct Scene *scene, struct RenderData *rd);
 
+bool RE_layers_have_name(struct RenderResult *result);
+
 /* shaded view or baking options */
 #define RE_BAKE_LIGHT				0	/* not listed in rna_scene.c -> can't be enabled! */
 #define RE_BAKE_ALL					1
@@ -297,6 +336,7 @@ void RE_Database_Baking(struct Render *re, struct Main *bmain, struct Scene *sce
 
 void RE_DataBase_GetView(struct Render *re, float mat[4][4]);
 void RE_GetCameraWindow(struct Render *re, struct Object *camera, int frame, float mat[4][4]);
+void RE_GetCameraModelMatrix(struct Render *re, struct Object *camera, float r_mat[4][4]);
 struct Scene *RE_GetScene(struct Render *re);
 
 bool RE_force_single_renderlayer(struct Scene *scene);
@@ -304,5 +344,16 @@ bool RE_is_rendering_allowed(struct Scene *scene, struct Object *camera_override
 
 bool RE_allow_render_generic_object(struct Object *ob);
 
+/******* defined in render_result.c *********/
+
+bool RE_HasFakeLayer(RenderResult *res);
+bool RE_RenderResult_is_stereo(RenderResult *res);
+
+float *RE_RenderViewGetRectf(struct RenderResult *rr, const int view_id);
+float *RE_RenderViewGetRectz(struct RenderResult *rr, const int view_id);
+int   *RE_RenderViewGetRect32(struct RenderResult *rr, const int view_id);
+void   RE_RenderViewSetRectf(struct RenderResult *res, const int view_id, float *rect);
+void   RE_RenderViewSetRectz(struct RenderResult *res, const int view_id, float *rect);
+
 #endif /* __RE_PIPELINE_H__ */