-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
KHR_lights_punctual extension proposal #1223
Changes from 16 commits
31ca6c2
524fd6b
8cb0c17
bd8938e
07a8fec
2113228
e7ae552
0610717
72096c4
e495b9e
625b28e
dbc99db
8326130
26f376f
0a79dc7
6aff0cc
6e871f6
c605724
766ba65
b5dff39
8ae54ee
3dcdfb0
bd047d4
34ae110
382d3d6
be36985
2945499
08bc3c7
28d2bac
78a93ae
d9a6811
50050e6
66dfb38
1048d16
10ed0c6
d9313cf
fa6d985
2d240ec
93ae7df
e4989c1
03f63e0
f49c51e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||
---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,144 @@ | ||||||||
# KHR\_lights | ||||||||
|
||||||||
## Contributors | ||||||||
|
||||||||
* Norbert Nopper, UX3D, <mailto:nopper@ux3d.io> | ||||||||
* Thomas Kress, UX3D, <mailto:kress@ux3d.io> | ||||||||
* Mike Bond, Adobe, <mailto:mbond@adobe.com> | ||||||||
|
||||||||
## Status | ||||||||
|
||||||||
Draft (not ratified yet) | ||||||||
|
||||||||
## Dependencies | ||||||||
|
||||||||
Written against the glTF 2.0 spec. | ||||||||
|
||||||||
## Overview | ||||||||
|
||||||||
This extension defines a set of lights for use with glTF 2.0. | ||||||||
|
||||||||
Many 3D tools and engines support built-in implementations of light types. Using this extension, tools can export and engines can import these lights. | ||||||||
|
||||||||
This extension defines four light types: `ambient`, `directional`, `point` and `spot`. | ||||||||
|
||||||||
## Lights | ||||||||
|
||||||||
Lights define light sources within a scene. | ||||||||
|
||||||||
`ambient` lights are not transformable and, thus, can only be defined on the scene. All other lights are contained in nodes and inherit the translation and rotation of that node. Note that all lights ignore the scale of a node. | ||||||||
|
||||||||
A conforming implementation of this extension must be able to load light data defined in the asset and has to render the asset using those lights. | ||||||||
|
||||||||
### Defining Lights | ||||||||
|
||||||||
Lights are defined within a dictionary property in the glTF manifest file, by adding an `extensions` property to the top-level glTF 2.0 object and defining a `KHR_lights` property with a `lights` array inside it. | ||||||||
|
||||||||
Each light defines a mandatory `type` property that designates the type of light (`ambient`, `directional`, `point` or `spot`). The following example defines a white-colored directional light. | ||||||||
|
||||||||
```javascript | ||||||||
"extensions": { | ||||||||
"KHR_lights" : { | ||||||||
"lights": [ | ||||||||
{ | ||||||||
"color": [ | ||||||||
1.0, | ||||||||
1.0, | ||||||||
1.0 | ||||||||
], | ||||||||
"type": "directional" | ||||||||
} | ||||||||
] | ||||||||
} | ||||||||
} | ||||||||
``` | ||||||||
|
||||||||
### Adding Light Instances to Nodes | ||||||||
|
||||||||
Nodes can have lights attached to them, just like any other objects that have a transform. Only lights of types `directional`, `point`, and `spot` have position and/or orientation so only these light types are allowed. These lights are attached to a node by defining the `extensions.KHR_lights` property and, within that, an index into the `lights` array using the `light` property. | ||||||||
|
||||||||
```javascript | ||||||||
"nodes" : [ | ||||||||
{ | ||||||||
"extensions" : { | ||||||||
"KHR_lights" : { | ||||||||
"light" : 0 | ||||||||
} | ||||||||
} | ||||||||
} | ||||||||
] | ||||||||
``` | ||||||||
|
||||||||
For light types that have a position (`point` and `spot` lights), the light's position is defined as the node's world location. | ||||||||
For light types that have a direction (`directional` and `spot` lights), the light's direction is defined as the 3-vector `(0.0, 0.0, 1.0)` and the rotation of the node orients the light accordingly. | ||||||||
|
||||||||
### Adding Light Instances to Scenes | ||||||||
|
||||||||
Lights that have no transform information can be attached to scenes. `ambient` lights have no position or orientation and are therefore global and belong to a scene rather than a node. These lights are attached to the scene by defining the `extensions.KHR_lights` property and, within that, an index into the `lights` array using the `light` property. | ||||||||
|
||||||||
```javascript | ||||||||
"scenes" : [ | ||||||||
{ | ||||||||
"extensions" : { | ||||||||
"KHR_lights" : { | ||||||||
"light" : 0 | ||||||||
} | ||||||||
} | ||||||||
} | ||||||||
] | ||||||||
``` | ||||||||
|
||||||||
### Light Types | ||||||||
|
||||||||
All light types share the common set of properties listed below. | ||||||||
|
||||||||
#### Light Shared Properties | ||||||||
|
||||||||
| Property | Description | Required | | ||||||||
|:-----------------------|:------------------------------------------| :--------------------------| | ||||||||
| `name` | Name of the light. | No, Default: `""` | | ||||||||
| `color` | RGB value for light's color in linear space. | No, Default: `[1.0, 1.0, 1.0]` | | ||||||||
| `intensity` | Brightness of light in. The units that this is defined in depend on the type of light. `point` and `spot` lights use luminous intensity in candela (lm/sr) while `directional` and `ambient` lights use illuminance in lux (lm/m^2) | No, Default: `1.0` | | ||||||||
| `type` | Declares the type of the light. | :white_check_mark: Yes | | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The Within the range of the light, attenuation should follow the inverse square law as closely as possible, although some non-quadratic falloff near the edge of the range may be used to avoid a hard cutoff. A range of There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ^Suggested addition. I slightly prefer the term "range" to "radius", on the assumption that it may later apply to other light types, like area lights. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Lol, this has put a knot into my brain :-) But range with default 0.0 is fine for me know. |
||||||||
|
||||||||
#### Ambient | ||||||||
|
||||||||
Ambient lights define constant lighting throughout the scene. They are referenced only by a scene object and only 1 can be referenced per scene. It's intensity is defined in lumens per metre squared, or lux (lm/m^2). | ||||||||
|
||||||||
#### Directional | ||||||||
|
||||||||
Directional lights are light sources that act as though they are infinitely far away and emit light in the direction of the local +z axis. This light type inherits the orientation of the node that it belongs to but ignores position and scale. Because it is at an infinite distance, the light is not attenuated. It's intensity is defined in lumens per metre squared, or lux (lm/m^2). | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: s/It's/Its |
||||||||
|
||||||||
#### Point | ||||||||
|
||||||||
Point lights emit light in all directions from its position in space (and ignore rotation and scale). The brightness of the light attenuates in a physically correct manner as distance increases from the light's position (i.e. brightness goes like the inverse square of the distance). Point light intensity is defined in candela, which is lumens per square radian (lm/sr). | ||||||||
|
||||||||
#### Spot | ||||||||
|
||||||||
Spot lights emit light in a cone in the direction of the local +z axis. The angle and falloff of the cone is defined using two numbers, the `innerConeAngle` and `outerConeAngle`. As with point lights, the brightness also attenuates in a physically correct manner as distance increases from the light's position (i.e. brightness goes like the inverse square of the distance). Spot light intensity refers to the brightness inside the `innerConeAngle` and is defined in candela, which is lumens per square radian (lm/sr). Engines that don't support two angles for spotlights should use `outerConeAngle` as the spotlight angle (leaving `innerConeAngle` to implicitly be `0`). | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Just noticed this. Are we okay with this? I would think this will cause inconsistent behavior between clients. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I forget the reason for this... was there a key engine that doesn't support both? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hm I was looking at SpotLight in the scripting API suggesting it has both There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looks like that was just added in 2018.1 and is experimental (it doesn't exist in 2017 or older). |
||||||||
|
||||||||
| Property | Description | Required | | ||||||||
|:-----------------------|:------------------------------------------| :--------------------------| | ||||||||
| `innerConeAngle` | Angle, in radians, from centre of spotlight where falloff begins. Must be greater than or equal to `0` and less than `outerConeAngle`. | No, Default: `0` | | ||||||||
| `outerConeAngle` | Angle, in radians, from centre of spotlight where falloff ends. Must be greater than `innerConeAngle` and less than or equal to `PI / 2.0`. | No, Default: `PI / 4.0` | | ||||||||
|
||||||||
```javascript | ||||||||
"extensions": { | ||||||||
"KHR_lights" : { | ||||||||
"lights": [ | ||||||||
{ | ||||||||
"spot": { | ||||||||
"innerConeAngle": 0.785398163397448, | ||||||||
"outerConeAngle": 1.57079632679, | ||||||||
}, | ||||||||
"color": [ | ||||||||
1.0, | ||||||||
1.0, | ||||||||
1.0 | ||||||||
], | ||||||||
"type": "spot" | ||||||||
} | ||||||||
] | ||||||||
} | ||||||||
} | ||||||||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggested addition to second sentence: