patch [#28355] Better Environment Map scripting

from Tom Edwards (artfunkel), with minor edits.

This patch makes the following improvements to environment map scripting:

* Adds a "is_valid" RNA property to envmaps. True if the map is ready for use, False if it needs rendering.
* Adds a "clear" RNA function to envmaps. Deletes any envmap image data.
* Adds a "save" RNA function to envmaps. Writes the envmap to disc with a configurable layout. (Defaults to the current hard-coded layout.)
* Updates bpy.ops.texture.envmap_save with configurable layout support as above.

These changes, particularly configurable layouts, make exporting envmaps to other software much easier.

source/blender/editors/render/render_shading.c

@@ -85,6 +85,8 @@
 
 #include "UI_interface.h"
 
+#include "RE_pipeline.h"
+
 #include "render_intern.h"	// own include
 
 /********************** material slot operators *********************/
@@ -661,60 +663,21 @@ void TEXTURE_OT_slot_move(wmOperatorType *ot)
 
 /********************** environment map operators *********************/
 
-static int save_envmap(wmOperator *op, Scene *scene, EnvMap *env, char *str, int imtype)
+static int save_envmap(wmOperator *op, Scene *scene, EnvMap *env, char *path, int imtype)
 {
-	ImBuf *ibuf=NULL;
-	int dx;
-	int retval;
-	int relative= (RNA_struct_find_property(op->ptr, "relative_path") && RNA_boolean_get(op->ptr, "relative_path"));
+	float layout[12];
+	if ( RNA_struct_find_property(op->ptr, "layout") )
+		RNA_float_get_array(op->ptr, "layout",layout);
+	else
+		memcpy(layout, default_envmap_layout, sizeof(layout));
 
-	if(env->cube[1]==NULL) {
-		BKE_report(op->reports, RPT_ERROR, "There is no generated environment map available to save");
+	if (RE_WriteEnvmapResult(op->reports, scene, env, path, imtype, layout)) {
+		return OPERATOR_FINISHED;
+	}
+	else {
 		return OPERATOR_CANCELLED;
 	}
 
-	dx= env->cube[1]->x;
-	
-	if (env->type == ENV_CUBE) {
-		ibuf = IMB_allocImBuf(3*dx, 2*dx, 24, IB_rectfloat);
-
-		IMB_rectcpy(ibuf, env->cube[0], 0, 0, 0, 0, dx, dx);
-		IMB_rectcpy(ibuf, env->cube[1], dx, 0, 0, 0, dx, dx);
-		IMB_rectcpy(ibuf, env->cube[2], 2*dx, 0, 0, 0, dx, dx);
-		IMB_rectcpy(ibuf, env->cube[3], 0, dx, 0, 0, dx, dx);
-		IMB_rectcpy(ibuf, env->cube[4], dx, dx, 0, 0, dx, dx);
-		IMB_rectcpy(ibuf, env->cube[5], 2*dx, dx, 0, 0, dx, dx);
-	}
-	else if (env->type == ENV_PLANE) {
-		ibuf = IMB_allocImBuf(dx, dx, 24, IB_rectfloat);
-		IMB_rectcpy(ibuf, env->cube[1], 0, 0, 0, 0, dx, dx);		
-	}
-	else {
-		BKE_report(op->reports, RPT_ERROR, "Invalid environment map type");
-		return OPERATOR_CANCELLED;
-	}
-	
-	if (scene->r.color_mgt_flag & R_COLOR_MANAGEMENT)
-		ibuf->profile = IB_PROFILE_LINEAR_RGB;
-	
-	/* to save, we first get absolute path */
-	BLI_path_abs(str, G.main->name);
-	
-	if (BKE_write_ibuf(ibuf, str, imtype, scene->r.subimtype, scene->r.quality)) {
-		retval = OPERATOR_FINISHED;
-	}
-	else {
-		BKE_reportf(op->reports, RPT_ERROR, "Error saving environment map to %s.", str);
-		retval = OPERATOR_CANCELLED;
-	}
-	/* in case we were saving with relative paths, change back again */
-	if(relative)
-		BLI_path_rel(str, G.main->name);
-	
-	IMB_freeImBuf(ibuf);
-	ibuf = NULL;
-	
-	return retval;
 }
 
 static int envmap_save_exec(bContext *C, wmOperator *op)
@@ -753,7 +716,6 @@ static int envmap_save_invoke(bContext *C, wmOperator *op, wmEvent *UNUSED(event
 		return envmap_save_exec(C, op);
 
 	//RNA_enum_set(op->ptr, "file_type", scene->r.imtype);
-	
 	RNA_string_set(op->ptr, "filepath", G.main->name);
 	WM_event_add_fileselect(C, op);
 	
@@ -776,6 +738,7 @@ static int envmap_save_poll(bContext *C)
 
 void TEXTURE_OT_envmap_save(wmOperatorType *ot)
 {
+	PropertyRNA *prop;
 	/* identifiers */
 	ot->name= "Save Environment Map";
 	ot->idname= "TEXTURE_OT_envmap_save";
@@ -790,8 +753,10 @@ void TEXTURE_OT_envmap_save(wmOperatorType *ot)
 	ot->flag= OPTYPE_REGISTER; /* no undo since this doesnt modify the env-map */
 	
 	/* properties */
-	//RNA_def_enum(ot->srna, "file_type", image_file_type_items, R_PNG, "File Type", "File type to save image as.");
-	WM_operator_properties_filesel(ot, FOLDERFILE|IMAGEFILE|MOVIEFILE, FILE_SPECIAL, FILE_SAVE, WM_FILESEL_FILEPATH|WM_FILESEL_RELPATH);
+	prop= RNA_def_float_array(ot->srna, "layout", 12, default_envmap_layout, 0.0f, 0.0f, "File layout", "Flat array describing the X,Y position of each cube face in the output image, where 1 is the size of a face. Order is [+Z -Z +Y -X -Y +X]. Use -1 to skip a face.", 0.0f, 0.0f);
+	RNA_def_property_flag(prop, PROP_HIDDEN);
+
+	WM_operator_properties_filesel(ot, FOLDERFILE|IMAGEFILE|MOVIEFILE, FILE_SPECIAL, FILE_SAVE, WM_FILESEL_FILEPATH);
 }
 
 static int envmap_clear_exec(bContext *C, wmOperator *UNUSED(op))

source/blender/makesrna/intern/CMakeLists.txt

@@ -100,6 +100,7 @@ set(APISRC
 	rna_main_api.c
 	rna_material_api.c
 	rna_mesh_api.c
+	rna_texture_api.c
 	rna_object_api.c
 	rna_pose_api.c
 	rna_scene_api.c

source/blender/makesrna/intern/makesrna.c

@@ -2417,7 +2417,7 @@ typedef struct RNAProcessItem {
 static RNAProcessItem PROCESS_ITEMS[]= {
 	{"rna_rna.c", NULL, RNA_def_rna},
 	{"rna_ID.c", NULL, RNA_def_ID},
-	{"rna_texture.c", NULL, RNA_def_texture},
+	{"rna_texture.c", "rna_texture_api.c", RNA_def_texture},
 	{"rna_action.c", "rna_action_api.c", RNA_def_action},
 	{"rna_animation.c", "rna_animation_api.c", RNA_def_animation},
 	{"rna_animviz.c", NULL, RNA_def_animviz},

source/blender/makesrna/intern/rna_internal.h

@@ -260,6 +260,7 @@ void RNA_api_wm(struct StructRNA *srna);
 void RNA_api_sensor(struct StructRNA *srna);
 void RNA_api_controller(struct StructRNA *srna);
 void RNA_api_actuator(struct StructRNA *srna);
+void RNA_api_environment_map(struct StructRNA *srna);
 
 /* main collection functions */
 void RNA_def_main_cameras(BlenderRNA *brna, PropertyRNA *cprop);

source/blender/makesrna/intern/rna_texture.c

@@ -664,6 +664,13 @@ static void rna_def_environment_map(BlenderRNA *brna)
 	RNA_def_property_range(prop, 0, 5);
 	RNA_def_property_ui_text(prop, "Depth", "Number of times a map will be rendered recursively (mirror effects.)");
 	RNA_def_property_update(prop, 0, "rna_Texture_update");
+
+	prop= RNA_def_property(srna, "is_valid", PROP_BOOLEAN, 0);
+	RNA_def_property_boolean_sdna(prop, NULL, "ok", 2);
+	RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+	RNA_def_property_ui_text(prop, "Validity", "True if this map is ready for use, False if it needs rendering.");
+
+	RNA_api_environment_map(srna);
 }
 
 static EnumPropertyItem prop_noise_basis_items[] = {

source/blender/makesrna/intern/rna_texture_api.c

@@ -0,0 +1,95 @@
+/*
+ *
+ * ***** BEGIN GPL LICENSE BLOCK *****
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version. 
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * Contributor(s): Tom Edwards
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/makesrna/intern/rna_texture_api.c
+ *  \ingroup RNA
+ */
+
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+
+#include "RNA_define.h"
+#include "BKE_utildefines.h"
+
+#ifdef RNA_RUNTIME
+
+#include "IMB_imbuf.h"
+#include "IMB_imbuf_types.h"
+#include "DNA_scene_types.h"
+#include "BKE_context.h"
+#include "BKE_global.h"
+#include "RE_pipeline.h"
+
+void save_envmap(struct EnvMap *env, bContext *C, ReportList *reports, const char* filepath, struct Scene *scene, float layout[12])
+{
+	if (scene == NULL) {
+		scene = CTX_data_scene(C);
+	}
+
+	RE_WriteEnvmapResult(reports, scene, env, filepath, scene->r.imtype, layout);
+}
+
+void clear_envmap(struct EnvMap *env, bContext *C)
+{
+	Main *bmain = CTX_data_main(C);
+	Tex *tex;
+
+	BKE_free_envmapdata(env);
+	
+	for (tex=bmain->tex.first; tex; tex=tex->id.next)
+		if (tex->env == env) {
+			WM_event_add_notifier(C, NC_TEXTURE|NA_EDITED, tex);
+			break;
+		}
+}
+
+#else
+
+void RNA_api_environment_map(StructRNA *srna)
+{
+	FunctionRNA *func;
+	PropertyRNA *parm;
+	
+	static const float default_layout[] = { 0,0, 1,0, 2,0, 0,1, 1,1, 2,1 };
+	
+	func= RNA_def_function(srna, "clear", "clear_envmap");
+		RNA_def_function_ui_description(func, "Discard the environment map and free it from memory.");
+		RNA_def_function_flag(func, FUNC_USE_CONTEXT);
+
+
+	func= RNA_def_function(srna,"save", "save_envmap");
+		RNA_def_function_ui_description(func, "Save the environment map to disc using the scene render settings.");
+		RNA_def_function_flag(func, FUNC_USE_CONTEXT|FUNC_USE_REPORTS);
+	
+		parm= RNA_def_string_file_name(func,"filepath","",FILE_MAX,"File path","Location of the output file");
+			RNA_def_property_flag(parm, PROP_REQUIRED);
+	
+		RNA_def_pointer(func, "scene", "Scene", "", "Overrides the scene from which image parameters are taken.");
+
+		parm = RNA_def_float_array(func, "layout", 12, default_layout, 0.0f, 0.0f, "File layout", "Flat array describing the X,Y position of each cube face in the output image, where 1 is the size of a face. Order is [+Z -Z +Y -X -Y +X]. Use -1 to skip a face.", 0.0f, 0.0f);
+}
+
+#endif

source/blender/render/extern/include/RE_pipeline.h

@@ -51,6 +51,7 @@ struct ReportList;
 struct ReportList;
 struct Scene;
 struct SceneRenderLayer;
+struct EnvMap;
 
 /* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
 /* this include is what is exposed of render to outside world */
@@ -230,6 +231,9 @@ void RE_ReadRenderResult(struct Scene *scene, struct Scene *scenode);
 void RE_WriteRenderResult(RenderResult *rr, const char *filename, int compress);
 struct RenderResult *RE_MultilayerConvert(void *exrhandle, int rectx, int recty);
 
+extern const float default_envmap_layout[];
+int RE_WriteEnvmapResult(struct ReportList *reports, struct Scene *scene, struct EnvMap *env, const char *relpath, int imtype, float layout[12]);
+
 /* do a full sample buffer compo */
 void RE_MergeFullSample(struct Render *re, struct Main *bmain, struct Scene *sce, struct bNodeTree *ntree);
 

source/blender/render/intern/source/pipeline.c

@@ -3463,3 +3463,60 @@ static int external_render_3d(Render *re, int do_all)
 	return 1;
 }
 
+const float default_envmap_layout[] = { 0,0, 1,0, 2,0, 0,1, 1,1, 2,1 };
+
+int RE_WriteEnvmapResult(struct ReportList *reports, Scene *scene, EnvMap *env, const char *relpath, int imtype, float layout[12])
+{
+	ImBuf *ibuf=NULL;
+	int ok;
+	int dx;
+	int maxX=0,maxY=0,i=0;
+	char filepath[FILE_MAX];
+
+	if(env->cube[1]==NULL) {
+		BKE_report(reports, RPT_ERROR, "There is no generated environment map available to save");
+		return 0;
+	}
+
+	dx= env->cube[1]->x;
+
+	if (env->type == ENV_CUBE) {
+		for (i=0; i < 12; i+=2) {
+			maxX = MAX2(maxX,layout[i] + 1);
+			maxY = MAX2(maxY,layout[i+1] + 1);
+		}
+
+		ibuf = IMB_allocImBuf(maxX*dx, maxY*dx, 24, IB_rectfloat);
+
+		for (i=0; i < 12; i+=2)
+			if (layout[i] > -1 && layout[i+1] > -1)
+				IMB_rectcpy(ibuf, env->cube[i/2], layout[i]*dx, layout[i+1]*dx, 0, 0, dx, dx);
+	}
+	else if (env->type == ENV_PLANE) {
+		ibuf = IMB_allocImBuf(dx, dx, 24, IB_rectfloat);
+		IMB_rectcpy(ibuf, env->cube[1], 0, 0, 0, 0, dx, dx);
+	}
+	else {
+		BKE_report(reports, RPT_ERROR, "Invalid environment map type");
+		return 0;
+	}
+
+	if (scene->r.color_mgt_flag & R_COLOR_MANAGEMENT)
+		ibuf->profile = IB_PROFILE_LINEAR_RGB;
+
+	/* to save, we first get absolute path */
+	BLI_strncpy(filepath, relpath, sizeof(filepath));
+	BLI_path_abs(filepath, G.main->name);
+
+	ok= BKE_write_ibuf(ibuf, filepath, imtype, scene->r.subimtype, scene->r.quality);
+
+	IMB_freeImBuf(ibuf);
+
+	if(ok) {
+		return TRUE;
+	}
+	else {
+		BKE_report(reports, RPT_ERROR, "Error writing environment map.");
+		return FALSE;
+	}
+}