attasi.com tom giannattasio @attasi

Introduction

Photon is a JavaScript library that adds simple lighting effects to DOM elements in 3D space. It's rather processor-intensive, so please use responsibly.

Contribute

If you'd like to help, please do so on GitHub or chat me up on twitter.

Quick Start

Create a Light

The Light object represents a point in 3D space from which faces are lit.

// creates a light at x: 0, y: 0, z: 100
var light = new Photon.Light();

Define Faces

Face objects specify which DOM elements should be shaded or tinted by the light.

// create a face with a max shade of .5
var face = new Photon.Face( $('.face-1')[0] );

Render

Call the render method on your faces to shade or tint them based on their angle from the specified light.

// shade face by its relation to light
face.render(light, true);

Library Reference

Light

Photon.Light( x = 0, y = 0, z = 100 )
constructor

Creates a new Light object. The default coordinates position the light straight towards the viewport.

moveTo( x, y, z )
method

Moves the light to a new set of coordinates.

Face

Photon.Face( element, maxShade = .5, maxTint = 0, isBackfaced = false )
constructor

Creates a new Face object. By default, the light will subtly shade each element.

element:object

The DOM object to which shading should be applied.

maxShade:float

The maximum amount of black that can be added to an element: 0–1.

maxTint:float

The maximum amount of white that can be added to an element: 0–1.

isBackfaced:boolean

Determines if the backface of the element should be shaded as if it were its own face. Rule of thumb: If the opposite side the element is visible, you probably want to set this to true.

render( light, getNewRotations, parentRotations )
method

Shades or tints the element based on its angle relative to the Light object. Shades and tints are applied to an empty div within the element with a class of photon-shader.

light :Light
The Light object to use to calculate shading or tinting.
getNewRotations :boolean
If true, a new rotation vector is calculated before shading is applied. Use this when the element's transform property has changed.
parentRotations :object
The parent object's rotations (x, y and z in radians). These are used primarily for FaceGroup objects.
setMaxShade( value )
method

Sets the maximum shade value: 0–1.

value :float
setMaxTint( value )
method

Sets the maximum tint value: 0–1.

value :float

FaceGroup

Photon.FaceGroup( parent, faces, maxShade = .5, maxTint = 0, isBackfaced = false )
constructor

Creates a new FaceGroup object, which allows one call of render to shade multiple faces. It also calculates the rotations of nested elements (i.e., if the parent element is rotated, the calculated rotations of the elements within it will be adjusted accordingly).

parent:object

The DOM object containing the faces to be shaded. Note: this element, itself, will not be shaded.

faces:array

An array of DOM elements within the parent object, which should be shaded.

maxShade:float

The maximum amount of black that can be added to the faces: 0–1.

maxTint:float

The maximum amount of white that can be added to the faces: 0–1.

isBackfaced:boolean

Determines if the backface of the faces should be shaded as if it were its own face. Rule of thumb: If the opposite side the element is visible, you probably want to set this to true.

render( light, getNewGroupRotations, getNewFaceRotations )
method

Shades or tints the element based on its angle relative to the Light object. Shades and tints are applied to an empty div within the element with a class of photon-shader.

light :Light
The Light object to use to calculate shading or tinting.
getNewGroupRotations :boolean
If true, a new rotation vector is calculated for the parent element before shading is applied. The new vector will affect the rotations of all faces. Use this when the parent's transform property has changed.
getNewFaceRotations :boolean
If true, new rotation vectors are calculated for all of the faces. Use this when the transform properties of thefaces have changed.
setMaxShade( value )
method

Sets the maximum shade value: 0–1.

value :float
setMaxTint( value )
method

Sets the maximum tint value: 0–1.

value :float