xeogl / API Docs

API Docs for:

PhongMaterial

Extends Material
Defined in: /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:1
Module: materials
Parent Module: xeogl

A PhongMaterial is a Material that defines the surface appearance of attached Meshes 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 when more 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.
alpha 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 alpha.
specularMap Texture null sRGB Texture RGB components multiplying by specular. If the fourth component (A) is present, it multiplies by alpha.
emissiveMap Texture null linear Texture with RGB components multiplying by emissive.
alphaMap Texture null linear Texture with first component multiplying by alpha.
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.
alphaFresnel Fresnel null Fresnel term applied to alpha.
lineWidth Number [0..100] 1 Line width in pixels.
pointSize Number [0..100] 1 Point size in pixels.
alphaMode String "opaque", "blend", "mask" "blend" Alpha blend mode.
alphaCutoff Number [0..1] 0.5 Alpha cutoff value.
backfaces Boolean false Whether to render Geometry backfaces.
frontface String "ccw", "cw" "ccw" The winding order for Geometry frontfaces - "cw" for clockwise, or "ccw" for counter-clockwise.

Usage

In this example we have a Mesh with

var torus = new xeogl.Mesh({

   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
       alpha: 1.0 // Default
   }),

   geometry: new xeogl.TorusGeometry()
});

Transparency

Alpha Blending

Let's make our torus transparent. We'll update its PhongMaterial's alpha and alphaMode, causing it to blend 50% with the background:

torus.material.alpha = 0.5;
torus.material.alphaMode = "blend";

TODO: Screenshot

Alpha Masking

Now let's make holes in our torus instead. We'll give its PhongMaterial an alphaMap and configure alpha, alphaMode, and alphaCutoff to treat it as an alpha mask:

torus.material.alphaMap = new xeogl.Texture({
       src: "textures/diffuse/crossGridColorMap.jpg"
   });

torus.material.alpha = 1.0;
torus.material.alphaMode = "mask";
torus.material.alphaCutoff = 0.2;

TODO: Screenshot

Constructor

PhongMaterial

(
  • [owner]
  • [cfg]
  • [cfg.ambient=[1.0,
  • [cfg.diffuse=[
  • [cfg.specular=[
  • [cfg.emissive=[
)

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:1

Parameters:

  • [owner] Component optional

    Owner component. When destroyed, the owner will destroy this component as well. Creates this component 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.

    • [alpha=1] Number optional

      Scalar in range 0-1 that controls alpha, where 0 is completely transparent and 1 is completely opaque.

    • [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.

    • [alphaMap=undefined] Texture optional

      An alpha map Texture, which will override the effect of the alpha 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.

    • [alphaFresnel=undefined] Fresnel optional

      An alpha 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.

    • [alphaMode="opaque"] String optional

      The alpha blend mode - accepted values are "opaque", "blend" and "mask". See the alphaMode property for more info.

    • [alphaCutoff=0.5] Number optional

      The alpha cutoff value. See the alphaCutoff property for more info.

    • [backfaces=false] Boolean optional

      Whether to render Geometry backfaces.

    • [frontface="ccw"] Boolean optional

      The winding order for Geometry front faces - "cw" for clockwise, or "ccw" for counter-clockwise.

  • [cfg.ambient=[1.0, Array of Number

    1.0, 1.0 ]] PhongMaterial ambient color.

  • [cfg.diffuse=[ Array of Number

    1.0, 1.0, 1.0 ]] PhongMaterial diffuse color.

  • [cfg.specular=[ Array of Number

    1.0, 1.0, 1.0 ]] PhongMaterial specular color.

  • [cfg.emissive=[ Array of Number

    0.0, 0.0, 0.0 ]] PhongMaterial emissive color.

Methods

create

(
  • [cfg]
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:896

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

The method is given a component configuration, like so:

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

Parameters:

  • [cfg] optional

    Configuration for the component instance.

Returns:

:

destroy

()

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:1005

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
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:583

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]
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:407

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

hasSubs

(
  • event
)
Boolean

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:534

Returns true if there are any subscribers to the given event on this component.

Parameters:

  • event String

    The event

Returns:

Boolean:

True if there are any subscribers to the given event on this component.

isType

(
  • type
)
Boolean

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:371

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 Component/superTypes:property, 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.Mesh); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Mesh

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
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:545

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

(
  • subId
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:488

Cancels an event subscription that was previously made with Component#on() or Component#once().

Parameters:

  • subId String

    Publication subId

on

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

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:446

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]
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:513

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

This is equivalent to calling Component#on(), and then calling Component#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
)

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:566

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

alpha

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:463

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.

Multiplies by alphaMap.

Default: 1.0

alphaCutoff

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:773

The alpha cutoff value.

Specifies the cutoff threshold when alphaMode equals "mask". If the alpha is greater than or equal to this value then it is rendered as fully opaque, otherwise, it is rendered as fully transparent. A value greater than 1.0 will render the entire material as fully transparent. This value is ignored for other modes.

Alpha is the combined result of the alpha and alphaMap properties.

Default: 0.5

alphaFresnel

Fresnel final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:711

Alpha Fresnel.

Applies to alpha.

Default: undefined

alphaMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:628

Alpha map.

Multiplies by alpha.

Default: undefined

alphaMode

String

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:739

The alpha rendering mode.

This governs how alpha is treated. Alpha is the combined result of the alpha and alphaMap properties.

  • "opaque" - The alpha value is ignored and the rendered output is fully opaque.
  • "mask" - The rendered output is either fully opaque or fully transparent depending on the alpha value and the specified alpha cutoff value.
  • "blend" - The alpha value is used to composite the source and destination areas. The rendered output is combined with the background using the normal painting operation (i.e. the Porter and Duff over operator).

Default: "opaque"

ambient

Float32Array

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:337

The PhongMaterial's ambient color.

Default: [0.3, 0.3, 0.3]

ambientMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:571

Ambient map.

Multiplies by ambient.

Default: undefined

backfaces

Boolean

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:803

Whether backfaces are visible on attached Meshes.

The backfaces will belong to Geometry compoents that are also attached to the Meshes.

Default: false

destroyed

Boolean

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:316

True as soon as this Component has been destroyed

diffuse

Float32Array

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:367

The PhongMaterial's diffuse color.

Multiplies by diffuseMap.

Default: [1.0, 1.0, 1.0]

diffuseFresnel

Fresnel final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:669

Diffuse Fresnel.

Applies to diffuseFresnel.

Default: undefined

diffuseMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:585

Diffuse map.

Multiplies by diffuse.

Default: undefined

emissive

Float32Array

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:431

The PhongMaterial's emissive color.

Multiplies by emissiveMap.

Default: [0.0, 0.0, 0.0]

emissiveFresnel

Fresnel final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:697

Emissive Fresnel.

Applies to emissive.

Default: undefined

emissiveMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:614

Emissive map.

Multiplies by emissive.

Default: undefined

frontface

String

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:826

Indicates the winding direction of front faces on attached Meshes.

The faces will belong to Geometry components that are also attached to the Meshes.

Default: "ccw"

id

String final

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:307

Unique ID for this Component within its parent Scene.

lineWidth

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:507

The PhongMaterial's line width.

Default: 1.0

metadata

Object

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:299

Arbitrary, user-defined metadata on this component.

model

Model final

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:358

The Model which contains this Component, if any.

Will be null if this Component is not in a Model.

normalMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:559

Normal map.

Default: undefined

occlusionMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:656

Occlusion map.

Default: undefined

pointSize

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:523

The PhongMaterial's point size.

Default: 1.0

reflectivity

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:539

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.

Default: 1.0

reflectivityFresnel

Fresnel final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:725

Reflectivity Fresnel.

Applies to reflectivity.

Default: undefined

reflectivityMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:642

Reflectivity map.

Multiplies by reflectivity.

Default: undefined

scene

Scene final

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:250

The parent Scene that contains this Component.

shininess

Number

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:487

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.

Default: 80.0

specular

Float32Array

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:399

The material's specular color.

Multiplies by specularMap.

Default: [1.0, 1.0, 1.0]

specularFresnel

Fresnel final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:683

Specular Fresnel.

Applies to specular.

Default: undefined

specularMap

Texture final

Defined in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:599

Specular map.

Multiplies by specular.

Default: undefined

type

String final

Inherited from Component but overwritten in /home/lindsay/xeolabs/xeogl-next/xeogl/src/materials/phongMaterial.js:171

JavaScript class name for this Component.

For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.

Events

destroyed

Inherited from Component: /home/lindsay/xeolabs/xeogl-next/xeogl/src/component.js:1073

Fired when this Component is destroyed.