利用者:Sionix/SummerOfCode2006/Sky

Sky

[ Back to the project ] [ http://sionix.pbwiki.com/SummerOfCode2006_Screenshots ]

How it works and User interface

New mode 'Sky' is introduced into World buttons. And new floating window for setting Sky engine parameters:

Lamp buttons are extended with 'Sun' window. It has controls to set lamp position via time and date properties:

Lamp also can be manually placed at any point of the scene, taking into account following rules:

• Zenith, East and South are respectively +Z, +X, -Y
• Although sun lamp object has a position, Sky engine uses only spherical coordinates of it. Zero point is scene's (0, 0, 0).

Usage examples

1. Activate World 'Sky' mode;

2. Set position, time, date params. Air turbidity;

3. Render scene - sky will be displayed.

Programming interface

There are two main interface instructions: SetupParams and GetRayColor. The first one is used for tuning Sky engine parameters and will be called from UI. The second is intended to be included into Render pipeline and returns the result of Sky engine's processing in given direction.

Integration into pipeline

GetRayColor instruction will be placed into source/blender/render/intern/source/rendercode.c module, shadepixel_sky() function. This place is used now for applying current World blend functionality into render results. And is the most convenient for GetRayColor call. (open issue: cooperation with current sky model - possibly some switch in World structure)

SetupParams will be placed into blender's UI module - source/blender/src/buttons_shading.c. And will be called each time when Sky UI updates World states.

Objects and relations

Interface functions

Library C interface functions for using in other Blender modules.

void BSG_getRayColor(float *color, float *view_vec, Object *camera);
void BSG_setTurbidity(float turbidity);
void BSG_setDateTime(short month, short day, float hour);
void BSG_updateSceneObjects(struct Scene *scene);

BSG_getRayColor:

@param[out] color Float buffer capable for holding 4 floats - RGBA values 
   of Sky engine's result.
@param[in] view_vec 3D vector pointing rendering pixel in Camera space.
@param[in] camera Current camera object.

BSG_setTurbidity:

@param[in] turbidity Turbidity value (air pollution coefficient) [0; 64].

BSG_setDateTime:

@param[in] month Date - month [0; 11].
@param[in] day Date - day [0; 31].
@param[in] hour Current time [0; 24].

BSG_updateSceneObjects:

@param[in] scene Pointer to scene.

Auxiliary mathematics

Classes for calculation optics equations, some auxiliary geometry functionality.

Vector class, some extra functionality over vectors. Will be extended.

class Vect3f
{
public:
	Vect3f();
	Vect3f(float x, float y, float z);
	Vect3f(const Vect3f &v);

	// General vector operators
	...

	const Vect3f &Transform(float mat[][3]);
	float Normalize();
	inline float Length();
	inline float SqrLength();

	inline operator float *();

protected:
	float data[3];
};

Optics color and conversion. Sky modelling uses CIE 1931 color space (http://www.easyrgb.com/math.php?MATH=M15#text15) so it needs special conversion functionality to get RGB value.

class OptColor : public Vect3f
{
public:
	const OptColor &ConvertYxyToRGB();
};

Converting local time into sun position over horizon.

class SunTime
{
public:
	SunTime();
	SunTime(int day, float hour);

	inline int Day();
	inline float Hour();
	inline void SetDay(int day);
	inline void SetHour(float hour);

	void SetDate(int month, int month_day);

public:
	struct PositionProperties
	{
		float latitude;
		float longitude;
		float standart_meridian;
	};

public:
	void SetPositionProperties(const PositionProperties &prop);
	void SetDefaultProperties();

	Vect3f GetSolarPosition();

private:
	PositionProperties m_properties;
	int m_day;
	float m_hour;
};

Detailed functions' description:

/// Default constructor.
SunTime::SunTime()

/// Constructor.
/// @param[in] day Day of the year in range [0; 365].
/// @param[in] hour Current local time [0; 24).
SunTime::SunTime(int day, float hour)

/// Getters and setters for time and date.
int SunTime::Day()
float SunTime::Hour()
void SunTime::SetDay(int day)
void SunTime::SetHour(float hour)

/// Calculate and set day using date info.
/// @param[in] month Month [0; 11].
/// @param[in] month_day Day of the month [0; 31].
void SunTime::SetDate(int month, int month_day)

/// Setup observer's position.
/// @param[in] prop Position properties data.
void SunTime::SetPositionProperties(const PositionProperties &prop)

/// Set default properties (coordinates of Minsk).
void SunTime::SetDefaultProperties()

/// Calculate solar position.
/// @return Direction vector.
Vect3f SunTime::GetSolarPosition()

Sky engine

Main class of the library. Incapsulates lib functionality.

class SkyEngine 
{
public:
	SkyEngine();

	// World params
	inline Vect3f &Zenith();
	inline Vect3f &South();
	inline SunTime &GetSunTime();
	inline float &Turbidity();

	// Output value
	void GetRayColor(Vect3f &res, const Vect3f &ray);

protected:
	// Structure used in computation model
	struct PerezCoeffs
	{
		float A, B, C, D, E;
	};

protected:
	// Get value of Perez functional
	float PerezFunc(const PerezCoeffs &pc, float cos_theta, float gamma);
	// Calculate Perez coefficients using current turbidity
	void CalcCoeffs(PerezCoeffs &pcY, PerezCoeffs &pcx, PerezCoeffs &pcy);

private:
	// Direction vectors
	Vect3f m_zenith;
	Vect3f m_south;

	// Sun location
	SunTime m_suntime;
	// Air pollution
	float m_turbidity;
};

Detailed functions' description:

/// Default constructor.
SkyEngine::SkyEngine()

/// Provide access to params.
Vect3f &SkyEngine::Zenith();
Vect3f &SkyEngine::South();
SunTime &SkyEngine::GetSunTime();
float &SkyEngine::Turbidity();

/// Get sky color in given direction.
/// @param[out] res RGB color result.
/// @param[in] ray Ray vector from observer.
void SkyEngine::GetRayColor(Vect3f &res, const Vect3f &ray)

// protected:

/// Get value of Perez functional
/// @param[in] pc Input perez coefficients.
/// @param[in] cos_theta Cos of theta angle of sun position.
/// @param[in] gamma Gamma angle in radians of sun position.
/// @return Value of Perez functional.
float SkyEngine::PerezFunc(const PerezCoeffs &pc, float cos_theta, float gamma)

/// Calculate Perez coefficients using current turbidity
/// @param[out] pcY Resulting coeffs for Y channel.
/// @param[out] pcx Resulting coeffs for x channel.
/// @param[out] pcy Resulting coeffs for y channel.
void SkyEngine::CalcCoeffs(PerezCoeffs &pcY, PerezCoeffs &pcx, PerezCoeffs &pcy)

World changes

Extension of World structure:

	/* sky engine */
	float turbidity;
	short sky_mode, add_angle;
	char sun_lamp_name[24];

turbidity - physical air pollution value

sky_mode - switch for Natural/User color and OneSun

add_angle - angle value in radians of horizon curvature

sun_lamp_name - lamp object name while in OneSun mode

New World sky type flags

#define WO_SKYSKY	32

/* sky mode */
#define WO_SKY_NATURAL	1
#define WO_SKY_ONESUN	2

Lamp changes

Sun location is calculated by SkyEngine using local time and position.

#define LA_USEDATE	32768

Extension of Lamp structure:

	/* sky engine */
	short date_month, date_day;  
	float date_hour;

Folders structure

Folders structure is common for whole SkyGen project.

soc-blender/
   projectfiles_vc7/
      blender/
         BSG_SkyGen/
            BSG_SkyGen.vcproj
   source/
      blender/
         BSG_SkyGen/
            BSG_SkyGen.h       // Interface header
            intern/
               BSG_SkyGen.cpp  // Interface functions implementation

               // Common modules
               sky_math.h          // Auxiliary math
               sky_math.cpp 

               // Sky module
               SkyEngine.h     // Sky engine
               SkyEngine.cpp   // Sky engine

               ...