API Docs for: 1.0.0

PhongMaterial

Extends Material
Module: materials
Parent Module: xeogl

A PhongMaterial is a Material that defines the surface appearance of attached Entities using the classic Blinn-Phong lighting model.

Examples

Phong textures Video texture Fresnels

Overview

  • Used for rendering non-realistic objects such as "helpers", wireframe objects, labels etc.
  • Use the physically-based MetallicMaterial or SpecularMaterial realism is required.

The following table summarizes PhongMaterial properties:

Property Type Range Default Value Space Description
ambient Array [0, 1] for all components [1,1,1,1] linear The RGB components of the ambient light reflected by the material.
diffuse Array [0, 1] for all components [1,1,1,1] linear The RGB components of the diffuse light reflected by the material.
specular Array [0, 1] for all components [1,1,1,1] linear The RGB components of the specular light reflected by the material.
emissive Array [0, 1] for all components [0,0,0] linear The RGB components of the light emitted by the material.
opacity Number [0, 1] 1 linear The transparency of the material surface (0 fully transparent, 1 fully opaque).
shininess Number [0, 128] 80 linear Determines the size and sharpness of specular highlights.
reflectivity Number [0, 1] 1 linear Determines the amount of reflectivity.
diffuseMap Texture null sRGB Texture RGB components multiplying by diffuse. If the fourth component (A) is present, it multiplies by opacity.
specularMap Texture null sRGB Texture RGB components multiplying by specular. If the fourth component (A) is present, it multiplies by opacity.
emissiveMap Texture null linear Texture with RGB components multiplying by emissive.
opacityMap Texture null linear Texture with first component multiplying by opacity.
occlusionMap Texture null linear Ambient occlusion texture multiplying by ambient, diffuse and specular.
normalMap Texture null linear Tangent-space normal map.
diffuseFresnel Fresnel null Fresnel term applied to diffuse.
specularFresnel Fresnel null Fresnel term applied to specular.
emissiveFresnel Fresnel null Fresnel term applied to emissive.
reflectivityFresnel Fresnel null Fresnel term applied to reflectivity.
opacityFresnel Fresnel null Fresnel term applied to opacity.
lineWidth Number [0..100] 1 Line width in pixels.
pointSize Number [0..100] 1 Point size in pixels.

Usage

In this example we have an Entity with

var entity = new xeogl.Entity({

   lights: new xeogl.Lights({
       lights: [
           new xeogl.AmbientLight({
               color: [0.7, 0.7, 0.7]
           }),
           new xeogl.DirLight({
               dir: [-1, -1, -1],
               color: [0.5, 0.7, 0.5],
               intensity: [1.0, 1.0, 1.0],
               space: "view"
           })
       ]
   }),

   material: new xeogl.PhongMaterial({
       ambient: [0.3, 0.3, 0.3],
       diffuse: [0.5, 0.5, 0.0],   // Ignored, since we have assigned a Texture to diffuseMap, below
       diffuseMap: new xeogl.Texture({
           src: "diffuseMap.jpg"
       }),
       specular: [1, 1, 1],
       specularFresnel: new xeogl.Fresnel({
           leftColor: [1.0, 1.0, 1.0],
           rightColor: [0.0, 0.0, 0.0],
           power: 4
       }),
       shininess: 80, // Default
       opacity: 1.0 // Default
   }),

   geometry: new xeogl.TorusGeometry()
});

Constructor

PhongMaterial

(
  • [scene]
  • [cfg]
)

Parameters:

  • [scene] Scene optional

    Parent Scene, creates this PhongMaterial within the default Scene when omitted

  • [cfg] optional

    The PhongMaterial configuration

    • [id] String optional

      Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

    • [meta=null] String:Object optional

      Metadata to attach to this PhongMaterial.

    • [ambient=[1.0, 1.0, 1.0 ]] Array of Number optional

      PhongMaterial ambient color.

    • [diffuse=[ 1.0, 1.0, 1.0 ]] Array of Number optional

      PhongMaterial diffuse color.

    • [specular=[ 1.0, 1.0, 1.0 ]] Array of Number optional

      PhongMaterial specular color.

    • [emissive=[ 0.0, 0.0, 0.0 ]] Array of Number optional

      PhongMaterial emissive color.

    • [opacity=1] Number optional

      Scalar in range 0-1 that controls opacity, where 0 is completely transparent and 1 is completely opaque. Only applies while Modes transparent equals true.

    • [shininess=80] Number optional

      Scalar in range 0-128 that determines the size and sharpness of specular highlights.

    • [reflectivity=1] Number optional

      Scalar in range 0-1 that controls how much CubeMap is reflected.

    • [lineWidth=1] Number optional

      Scalar that controls the width of lines for Geometry with primitive set to "lines".

    • [pointSize=1] Number optional

      Scalar that controls the size of points for Geometry with primitive set to "points".

    • [ambientMap=null] Texture optional

      A ambient map Texture, which will multiply by the diffuse property. Must be within the same Scene as this PhongMaterial.

    • [diffuseMap=null] Texture optional

      A diffuse map Texture, which will override the effect of the diffuse property. Must be within the same Scene as this PhongMaterial.

    • [specularMap=null] Texture optional

      A specular map Texture, which will override the effect of the specular property. Must be within the same Scene as this PhongMaterial.

    • [emissiveMap=undefined] Texture optional

      An emissive map Texture, which will override the effect of the emissive property. Must be within the same Scene as this PhongMaterial.

    • [normalMap=undefined] Texture optional

      A normal map Texture. Must be within the same Scene as this PhongMaterial.

    • [opacityMap=undefined] Texture optional

      An opacity map Texture, which will override the effect of the opacity property. Must be within the same Scene as this PhongMaterial.

    • [reflectivityMap=undefined] Texture optional

      A reflectivity control map Texture, which will override the effect of the reflectivity property. Must be within the same Scene as this PhongMaterial.

    • [occlusionMap=null] Texture optional

      An occlusion map Texture. Must be within the same Scene as this PhongMaterial.

    • [diffuseFresnel=undefined] Fresnel optional

      A diffuse Fresnel. Must be within the same Scene as this PhongMaterial.

    • [specularFresnel=undefined] Fresnel optional

      A specular Fresnel. Must be within the same Scene as this PhongMaterial.

    • [emissiveFresnel=undefined] Fresnel optional

      An emissive Fresnel. Must be within the same Scene as this PhongMaterial.

    • [opacityFresnel=undefined] Fresnel optional

      An opacity Fresnel. Must be within the same Scene as this PhongMaterial.

    • [reflectivityFresnel=undefined] Fresnel optional

      A reflectivity Fresnel. Must be within the same Scene as this PhongMaterial.

Methods

create

(
  • [cfg]
  • [instanceId]
)

Convenience method for creating a Component within this Component's Scene.

You would typically use this method to conveniently instantiate components that you'd want to share (ie. "instance") among your Entities.

The method is given a component type, configuration and optional instance ID, like so:

var material = myComponent.create(xeogl.PhongMaterial, {
     diffuse: [1,0,0],
     specular: [1,1,0]
}, "myMaterial");

The first time you call this method for the given type and instanceId, this method will create the PhongMaterial, passing the given attributes to the component's constructor.

If you call this method again, specifying the same type and instanceId, the method will return the same component instance that it returned the first time, and will ignore the configuration:

var material2 = component.create(xeogl.PhongMaterial, { specular: [1,1,0] }, "myMaterial");

So in this example, our PhongMaterial will continue to have the red specular and diffuse color that we specified the first time.

Each time you call this method with the same type and instanceId, the Scene will internally increment a reference count for the component instance. You can release the shared component instance with a call to Scene/putSharedComponent:method, and once you have released it as many times as you got it, the Scene will destroy the component.

Parameters:

  • [cfg] optional

    Configuration for the component instance - only used if this is the first time you are getting the component, ignored when reusing an existing instance.

  • [instanceId] String | Number optional

    Identifies the shared component instance. Note that this is not used as the ID of the component - you can specify the component ID in the cfg parameter.

Returns:

:

destroy

()

Destroys this component.

Fires a destroyed event on this Component.

Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.

TODO: describe effect with respect to #create

error

(
  • message
)

Logs an error for this component to the JavaScript console.

The console message will have this format: [ERROR] [<component type> =<component id>: <message>

Also fires the message as an error event on the parent Scene.

Parameters:

  • message String

    The message to log

fire

(
  • event
  • value
  • [forget=false]
)

Fires an event on this component.

Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.

Parameters:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

isType

(
  • type
)
Boolean

Tests if this component is of the given type, or is a subclass of the given type.

The type may be given as either a string or a component constructor.

This method works by walking up the inheritance type chain, which this component provides in property superTypes, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.

Examples:

var myRotate = new xeogl.Rotate({ ... });

myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Entity); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Entity

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

True if this component is of given type or is subclass of the given type.

log

(
  • message
)

Logs a console debugging message for this component.

The console message will have this format: [LOG] [<component type> <component id>: <message>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • handle
)

Cancels an event subscription that was previously made with on or once.

Parameters:

  • handle String

    Publication handle

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

Handle to the subscription, which may be used to unsubscribe with {@link #off}.

once

(
  • event
  • callback
  • [scope=this]
)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is handled.

This is equivalent to calling on, and then calling off inside the callback function.

Parameters:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

Properties

ambient

Float32Array

The PhongMaterial's ambient color.

Fires a ambient event on change.

Default: [0.3, 0.3, 0.3]

ambientMap

Texture

An ambient Texture attached to this PhongMaterial.

This property multiplies by ambient property.

Must be within the same Scene as this PhongMaterial.

Fires a ambientMap event on change.

Default: undefined

destroyed

Boolean

True as soon as this Component has been destroyed

diffuse

Float32Array

The PhongMaterial's diffuse color.

Multiplies by diffuseMap.

Fires a diffuse event on change.

Default: [1.0, 1.0, 1.0]

diffuseFresnel

Fresnel

A diffuse Fresnel attached to this PhongMaterial.

This property multiplies by diffuseFresnel when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a diffuseFresnel event on change.

Default: undefined

diffuseMap

Texture

A diffuse Texture attached to this PhongMaterial.

This property multiplies by diffuseMap when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a diffuseMap event on change.

Default: undefined

emissive

Float32Array

The PhongMaterial's emissive color.

Multiplies by emissiveMap.

Fires a emissive event on change.

Default: [0.0, 0.0, 0.0]

emissiveFresnel

Fresnel

An emissive Fresnel attached to this PhongMaterial.

This property multiplies by emissive when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires an emissiveFresnel event on change.

Default: undefined

emissiveMap

Texture

An emissive Texture attached to this PhongMaterial.

This property multiplies by emissive when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires an emissiveMap event on change.

Default: undefined

id

String final

Unique ID for this Component within its parent Scene.

isDefault

Boolean

Indicates whether this is one of the Scene's built-in Components.

json

JSON final

JSON object containing the state of this Component.

lineWidth

Number

The PhongMaterial's line width.

Fires a lineWidth event on change.

Default: 1.0

metadata

Object

Arbitrary, user-defined metadata on this component.

normalMap

Texture

A normal Texture attached to this PhongMaterial.

Must be within the same Scene as this PhongMaterial.

Fires a normalMap event on change.

Default: undefined

occlusionMap

Texture

An occlusion map Texture attached to this PhongMaterial. Must be within the same Scene as this PhongMaterial. Fires a occlusionMap event on change.

Default: undefined

opacity

Number

Factor in the range [0..1] indicating how transparent the PhongMaterial is.

A value of 0.0 indicates fully transparent, 1.0 is fully opaque.

Attached Entities will appear transparent only if they are also attached to Modes that have transparent set to true.

Multiplies by opacityMap.

Fires an opacity event on change.

Default: 1.0

opacityFresnel

Fresnel

An opacity Fresnel attached to this PhongMaterial.

This property multiplies by opacity when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires an opacityFresnel event on change.

Default: undefined

opacityMap

Texture

An opacity Texture attached to this PhongMaterial.

This property multiplies by opacity when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires an opacityMap event on change.

Default: undefined

pointSize

Number

The PhongMaterial's point size.

Fires a pointSize event on change.

Default: 1.0

reflection

Reflect

A reflection CubeMap attached to this PhongMaterial.

Must be within the same Scene as this PhongMaterial.

Fires a reflection event on change.

Default: undefined

reflectivity

Number

Scalar in range 0-1 that controls how much CubeMap is reflected by this PhongMaterial.

The surface will be non-reflective when this is 0, and completely mirror-like when it is 1.0.

Multiplies by reflectivityMap.

Fires a reflectivity event on change.

Default: 1.0

reflectivityFresnel

Fresnel

A reflectivity Fresnel attached to this PhongMaterial.

This property multiplies by reflectivity when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a reflectivityFresnel event on change.

Default: undefined

reflectivityMap

Texture

A reflectivity Texture attached to this PhongMaterial.

This property multiplies by reflectivity when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a reflectivityMap event on change.

Default: undefined

scene

Scene final

The parent Scene that contains this Component.

shininess

Number

A factor in range [0..128] that determines the size and sharpness of the specular highlights create by this PhongMaterial.

Larger values produce smaller, sharper highlights. A value of 0.0 gives very large highlights that are almost never desirable. Try values close to 10 for a larger, fuzzier highlight and values of 100 or more for a small, sharp highlight.

Fires a shininess event on change.

Default: 80.0

specular

Float32Array

The material's specular color.

Multiplies by specularMap.

Fires a specular event on change.

Default: [1.0, 1.0, 1.0]

specularFresnel

Fresnel

A specular Fresnel attached to this PhongMaterial.

This property multiplies by specular when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a specularFresnel event on change.

Default: undefined

specularMap

Texture

A specular Texture attached to this PhongMaterial.

This property multiplies by specular when not null or undefined.

Must be within the same Scene as this PhongMaterial.

Fires a specularMap event on change.

Default: undefined

string

String final

Inherited from Component but overwritten in src/component.js:1056

String containing the serialized JSON state of this Component.

superTypes

Array of String final

An array of strings that indicates the chain of super-types within this component's inheritance hierarchy.

For example, if this component is a Rotate, which extends Transform, which in turn extends Component, then this property will have the value:

["xeogl.Component", "xeogl.Transform"]
                    

Note that the chain is ordered downwards in the hierarchy, ie. from super-class down towards sub-class.

type

String final

JavaScript class name for this Component.

This is used when loading Scenes from JSON, and is included in the JSON representation of this Component, so that this class may be instantiated when loading it from the JSON representation.

For example: "xeogl.AmbientLight", "xeogl.ColorTarget", "xeogl.Lights" etc.

Events

ambient

Fired whenever this PhongMaterial's ambient property changes.

Event Payload:

  • value Float32Array

    The property's new value

ambientMap

Fired whenever this PhongMaterial's ambientMap property changes.

Event Payload:

  • value Object

    Number The property's new value

destroyed

Fired when this Component is destroyed.

diffuse

Fired whenever this PhongMaterial's diffuse property changes.

Event Payload:

  • value Float32Array

    The property's new value

diffuseFresnel

Fired whenever this PhongMaterial's diffuse property changes.

Event Payload:

  • value Object

    Number The property's new value

diffuseMap

Fired whenever this PhongMaterial's diffuseMap property changes.

Event Payload:

  • value Object

    Number The property's new value

emissive

Fired whenever this PhongMaterial's emissive property changes.

Event Payload:

  • value Float32Array

    The property's new value

emissiveFresnel

Fired whenever this PhongMaterial's emissiveFresnel property changes.

Event Payload:

  • value Object

    Number The property's new value

emissiveMap

Fired whenever this PhongMaterial's emissiveMap property changes.

Event Payload:

  • value Object

    Number The property's new value

lineWidth

Fired whenever this PhongMaterial's lineWidth property changes.

Event Payload:

  • value Array(Number)

    The property's new value

normalMap

Fired whenever this PhongMaterial's normalMap property changes.

Event Payload:

  • value Object

    Number The property's new value

occlusionMap

Fired whenever this PhongMaterial's occlusionMap property changes.

Event Payload:

  • value Object

    Number The property's new value

opacity

Fired whenever this PhongMaterial's opacity property changes.

Event Payload:

  • value Number

    The property's new value

opacityFresnel

Fired whenever this PhongMaterial's opacityFresnel property changes.

Event Payload:

  • value Object

    Number The property's new value

opacityMap

Fired whenever this PhongMaterial's opacityMap property changes.

Event Payload:

  • value Object

    Number The property's new value

pointSize

Fired whenever this PhongMaterial's pointSize property changes.

Event Payload:

  • value Array(Number)

    The property's new value

reflection

Fired whenever this PhongMaterial's reflectivityMap property changes.

Event Payload:

  • value Reflect

    The property's new value

reflectivity

Fired whenever this PhongMaterial's reflectivity property changes.

Event Payload:

  • value Object

    Number The property's new value

reflectivityFresnel

Fired whenever this PhongMaterial's reflectivityFresnel property changes.

Event Payload:

  • value Object

    Number The property's new value

reflectivityMap

Fired whenever this PhongMaterial's reflectivityMap property changes.

Event Payload:

  • value Object

    Number The property's new value

shininess

Fired whenever this PhongMaterial's shininess property changes.

Event Payload:

  • value Object

    Number The property's new value

specular

Fired whenever this PhongMaterial's specular property changes.

Event Payload:

  • value Float32Array

    The property's new value

specularFresnel

Fired whenever this PhongMaterial's specularFresnel property changes.

Event Payload:

  • value Object

    Number The property's new value

specularMap

Fired whenever this PhongMaterial's specularMap property changes.

Event Payload:

  • value Object

    Number The property's new value