Current Concerns

Animated Scenes
Current design works well with static scenes with dynamic lighting, but it works poorly with dynamics scenes. The per vertex coordinates that are used for interactive display need to be updated every time the vertex normal changes. This could be quite an overhead.
Surface types other than diffuse

I think many methods combine SH lighting with regular lighting, processing the scene in multiple passes and combine them together in the end (e.g. specular). I'm currently a bit stuck on this, but hopefully I can figure something out soon.

Introduction

This document describes the current design of Blender light paint.

The system is designed to contain three main components:

SH math: provides computation routines, including SH coefficients calculation and constrained quadratic least square solver.
Light Environment (Node): provides capability to mix and compose light probe images
UI controls and display: provides means to modify and display lighting environment

Data Diagram

LightEnv

Questions:

In DNA_lightenv_types.h, probe_image is a pointer to an image in the list of available images. Do I need to store its data again? (scriptlink and preview data are stored with writedata)
Currently each scene has a pointer to lightenv. Is it better to let World point to LightEnv?
Scene's pointers are restored in lib_link_scene. How about pointers in LightEnv?

Scene SH Coefficients

SH coefficients for the vertices are stored as vdata for each mesh object.

Interfaces

Interface Overview

Light Paint UI

void PAINT_OT_light_paint_toggle(wmOperatorType *ot);
void PAINT_OT_light_paint(wmOperatorType *ot);
void PAINT_OT_light_paint_radial_control(w(wmOperatorType *ot);
void PAINT_OT_light_paint_rotate(struct wmOperatorType *ot);
void PAINT_OT_light_paint_recompute(struct wmOperatorType *ot);
void PAINT_OT_light_paint_save(struct wmOperatorType *ot);
void undo_lightpaint_step(bContext *C, int step); // undo&redo. used in editors/util/undo.c

SH Math

void SH_init(); // called on startup in WM_init();
void SH_exit(); // called on exit in WM_exit();

void SH_computeSceneCoefficients(struct Scene *scene, unsigned int customdata_mask, 
                                 short compute_shadow, short recompute);
void SH_computeMeshCoefficients(struct Object *ob, int compute_shadow);
void SH_computeLightCoefficients(struct LightEnv *env);

void SH_rotateLightEnv(struct LightEnv *env, float quat[4]);
void SH_reconstructLightProbe(struct LightEnv *env, struct ImBuf *ibuf);
void SH_lightProbePreview(struct LightEnv *env, int width, int height,
                          int xmin, int ymin, int xmax, int ymax, float *col);

void SH_from_disc(int L, float *n, float area, float *shresult);
float SH_eval(float *sh, float *v);
void SH_eval_color(float *col, struct LightEnv *env, float *n);

void SH_solve(float *P, float *I[3], int totvert, int num_sh, float *C[3]);

Light Environment

void init_def_lightenv(void); // called in SH_init()
void free_lightenv(struct LightEnv *env);
LightEnv* add_lightenv(char *name);

Component Details

SH math

SH Coefficients

Initialize SH coefficients when switching to light paint mode for the first time. Files that need to be modified or added:

 sh/SH_api.h
 sh/intern/compute.c
 editor/sculpt_paint/paint_light.c
 makesdna/DNA_meshdata_types.h
 editors/mesh/editmesh.c

A threaded job would be created to compute the coefficients for all mesh objects in the scene (one thread per mesh, or schedule threads in a way similar to rendering).

Update SH diffuse coefficients when vertices are changed in edit mode. Files to be modified:

 sh/SH_api.h
 sh/intern/compute.c
 editors/mesh/editmesh.c

Manually triggering a re-computation of SH coefficients reuses the routines for initialization with slight changes.

Constrained Quadratic Solver

sh/SH_api.h
sh/intern/solve.c

Light Environment (Node)

files to be changed:

+nodes/intern/TEX_nodes/TEX_lightenv.c
editors/space_node/drawnode.c
editors/space_node/node_edit.c
editors/space_node/node_header.c
editors/space_node/node_draw.c

UI controls and display

Light Paint Mode (UI)

Files that need to be modified or added:

 editors/space_view3d/view3d_header.c
 editors/sculpt_paint/paint_intern.h
 editors/sculpt_paint/paint_ops.c
+editors/sculpt_paint/paint_light.c

and related header files that define constants.

Light Node Space (UI)

Necessary UI change to display the initial light node when "Use Nodes" is switched on. Files to be changed:

 release/datafiles/blenderbuttons
 makesdna/DNA_node_types.h
 editors/include/UI_resources.h
 editors/datafiles/blenderbuttons.c
 editors/space_node/node_intern.h
 editors/space_node/node_header.c
 editors/space_node/node_edit.c

Interactive Rendering (view3d space)