Three.js

Основные элементы three.js

В этом разделе описаны основные классы библиотеки three.js.

      BufferAttribute

Данный класс сохраняет данные атрибута (такие как положения вершин, индексы граней, нормали, цвета, текстурные координаты (
объекта (X, Y, Z) и координатами на текстуре (U, V - эти буквы
обозначают оси двумерной текстуры, потому что «X», «Y» и «Z»
уже используются для обозначения осей 3D-объекта в пространстве
модели). Значения U и V обычно изменяются от 0 до 1.')" onmouseout="hide()">UV) и все атрибуты, установленные пользователем), связанного с BufferGeometry, который позволяет более эффективное прохождение всех этих данных к
блок графических вычислений или графический процессор
или попросту - процессор видеокарты')" onmouseout="hide()">GPU. Посмотрите эту страницу для дополнительных сведений и примеров использования.

Данные хранятся как векторы произвольной длины (определяемые itemSize), и вообще в методах, описанных ниже, если передаются с индексом, то он автоматически умножается на длину вектора.

Конструктор

BufferAttribute( array, itemSize, 
нормированный, т.е. приведенный к какой-то норме')" onmouseout="hide()">normalized )

Свойства

Методы

Исходники

BufferAttribute →

Типы BufferAttribute

В three.js имеются девять типов BufferAttribute. Они соответствуют типизированным массивам в JavaScript.

THREE.Float64BufferAttribute
THREE.Float32BufferAttribute
THREE.Uint32BufferAttribute
THREE.Int32BufferAttribute
THREE.Uint16BufferAttribute
THREE.Int16BufferAttribute
THREE.Uint8ClampedBufferAttribute
THREE.Uint8BufferAttribute
THREE.Int8BufferAttribute

Конструктор

Все вышеперечисленное вызывается одним и тем же способом.

TypedBufferAttribute( array, itemSize )

Свойства

Унаследованные свойства смотрите на странице BufferAttribute.

Методы

Унаследованные методы смотрите на странице BufferAttribute.

Исходники

      BufferGeometry

Данный класс является эффективной альтернативой Geometry, так как он сохраняет внутри буферов все данные, включая положения вершин, индексы граней, нормали, цвета, текстурные координаты (
объекта (X, Y, Z) и координатами на текстуре (U, V - эти буквы
обозначают оси двумерной текстуры, потому что «X», «Y» и «Z»
уже используются для обозначения осей 3D-объекта в пространстве
модели). Значения U и V обычно изменяются от 0 до 1.')" onmouseout="hide()">UV) и все атрибуты, установленные пользователем); это снижает затраты на прохождение всех этих данных к
блок графических вычислений или графический процессор
или попросту - процессор видеокарты')" onmouseout="hide()">GPU. При этом, работать с BufferGeometry сложнее, чем с Geometry; вместо того, чтобы обращаться к данным расположения как к объектам Vector3, а к данным о цвете как к объектам Color и так далее, нужно обращаться к необработанным данным (raw data) из соответствующего буфера атрибутов. Это делает BufferGeometry наиболее подходящим для статических объектов, где вам не нужно управлять геометрическими свойствами объекта после его создания.

Пример

var geometry = new THREE.BufferGeometry();
// create a simple square shape. We duplicate the bottom left and top right
// vertices because each vertex needs to appear once per triangle.
// создадим простую форму - квадрат. Нижняя левая и верхняя правая вершины
// повторяются, поскольку в обоих треугольниках есть каждая из этих вершин.
var vertices = new Float32Array( [
-1.0, -1.0,  1.0,
 1.0, -1.0,  1.0,
 1.0,  1.0,  1.0,

 1.0,  1.0,  1.0,
-1.0,  1.0,  1.0,
-1.0, -1.0,  1.0
] );

// itemSize = 3 because there are 3 values (components) per vertex
// itemSize = 3, потому что имеется 3 значения (компонента, т.е. составные части) на каждую вершину
geometry.addAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );
var material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
var mesh = new THREE.Mesh( geometry, material );

Другие примеры:

Complex mesh with non-indexed faces (сложная сетка с неиндексированными гранями),
Complex mesh with indexed faces (сложная сетка с индексированными гранями),
Lines (линии),
Indexed Lines (индексированные линии),
Particles (частицы), и
Raw Shaders (необработанные шейдеры).

Обращение к атрибутам Accessing attributes

WebGL хранит данные, связанные с отдельными вершинами геометрии в атрибутах. Примеры включают положение вершины, вектор нормали вершины, цвет вершины и т.д. При использовании Geometry, рендерер берет на себя заботу о переносе этой информации в буферы типизированного массива и отправлении этих данных в шейдер. В случае с BufferGeometry все эти данные хранятся в буферах, связанных с отдельными атрибутами. Это значит, что для получения данных о положении, связанных с вершиной (например), нужно вызвать метод .getAttribute для доступа к атрибуту position, затем обращаться к отдельным координатам x, y, и z этой позиции.

Различными элементами этого класса устанавливаются следующие атрибуты:
В дополнение к встроенным атрибутам, можно устанавливать свои собственные настраиваемые атрибуты при помощи метода addAttribute. При работе с Geometry, эти атрибуты установлены и хранятся в материале. В BufferGeometry эти атрибуты сохраняются вместе с самой геометрией. Обратите внимание, что по-прежнему нужно задавать сведения об атрибутах в материале, но значение каждого атрибута хранится в BufferGeometry.

Конструктор

BufferGeometry( )

Конструктор создает новый BufferGeometry, а также задает некоторым свойствам значение по умолчанию.

Свойства

Методы

В данном классе возможно применение методов EventDispatcher.

Исходники

      Clock

Объект для отслеживания времени. Он использует метод performance.now(), если такая возможность имеется, в противном случае он обращается к менее точному методу Date.now(). Вот описание методов performance.now() и Date.now() на русском языке.

Конструктор

Clock( autoStart )

Свойства

Методы

Исходники

      DirectGeometry

Данный класс используется внутри three.js для конвертирования из Geometry в BufferGeometry.

Конструктор

DirectGeometry()

Создает новую DirectGeometry.

Свойства

Методы

В данном классе возможно применение методов EventDispatcher.

Исходники

      EventDispatcher

События JavaScript для настраиваемых объектов.
EventDispatcher на Гитхабе.

Пример

// Adding events to a custom object
// Добавляем события в пользовательский объект
var Car = function () {
    this.start = function () {
        this.dispatchEvent( { type: 'start', message: 'vroom vroom!' } );
    };
};

// Mixin the EventDispatcher.prototype with the custom object prototype
// Объединяем EventDispatcher.prototype с прототипом пользовательского объекта
Object.assign( Car.prototype, EventDispatcher.prototype );

// Using events with the custom object
// Использование событий с пользовательским объектом
var car = new Car();
car.addEventListener( 'start', function ( event ) {
    alert( event.message );
} );

car.start();

Конструктор

EventDispatcher()

Создает объект EventDispatcher.

Методы

Исходники

      Face3

Треугольная грань, используемая в Geometry. Грани создаются автоматически для всех стандартных типов геометрии, однако, если строится нестандартная геометрия, их придется создавать вручную.

Пример

var material = new THREE.MeshStandardMaterial( { color : 0x00cc00 } );

// create a triangular geometry
// создадим геометрию треугольника
var geometry = new THREE.Geometry();
geometry.vertices.push( new THREE.Vector3( -50, -50, 0 ) );
geometry.vertices.push( new THREE.Vector3(  50, -50, 0 ) );
geometry.vertices.push( new THREE.Vector3(  50,  50, 0 ) );

// create a new face using vertices 0, 1, 2
// создаем новую грань, используя вершины 0, 1, 2
var normal = new THREE.Vector3( 0, 1, 0 ); // optional (необязательно)
var color = new THREE.Color( 0xffaa00 ); // optional (необязательно)
var materialIndex = 0; // optional (необязательно)
var face = new THREE.Face3( 0, 1, 2, normal, color, materialIndex );

// add the face to the geometry's faces array
// добавляем грань к массиву граней геометрии
geometry.faces.push( face );

// the face normals and vertex normals can be calculated automatically if not supplied above
// если выше не предоставлено, то нормали граней и вершин могут вычисляться автоматически
geometry.computeFaceNormals();
geometry.computeVertexNormals();

scene.add( new THREE.Mesh( geometry, material ) );

Другие примеры:

ubiquity / test
svg / sandbox
WebGL / exporter / obj
WebGL / shaders / vector

Конструктор

Face3( 
- ячейки сетки-арматуры, из которой состоят все грани геометрического элемента')" onmouseout="hide()">a, 
- ячейки сетки-арматуры, из которой состоят все грани геометрического элемента')" onmouseout="hide()">b, 
- ячейки сетки-арматуры, из которой состоят все грани геометрического элемента')" onmouseout="hide()">c, 
normal - нормаль')" onmouseout="hide()">normal, color, materialIndex )

Свойства

Методы

Исходники

      Geometry

Основной класс для всех геометрий (но не для BufferGeometries). Также его можно использовать напрямую для построения собственных и нестандартных геометрий.
С Geometry работать легче, чем с BufferGeometries, так как она хранит атрибуты, такие как вершины, грани, цвета и тому подобное непосредственно у себя (а не в буферах), хотя она, как правило, работает медленней.

Пример

var geometry = new THREE.Geometry();

geometry.vertices.push(
	new THREE.Vector3( -10,  10, 0 ),
	new THREE.Vector3( -10, -10, 0 ),
	new THREE.Vector3(  10, -10, 0 )
);

geometry.faces.push( new THREE.Face3( 0, 1, 2 ) );

geometry.computeBoundingSphere();

Другие примеры:

WebGL / geometry / minecraft,
WebGL / geometry / minecraft / ao,
WebGL / geometry / nurbs,
WebGL / geometry / spline / editor,
WebGL / interactive / cubes / gpu,
WebGL / interactive / lines,
WebGL / interactive / raycasting / points,
WebGL / interactive / voxelpainter,
WebGL / morphNormals.

Конструктор

Geometry()

Конструктор не принимает аргументов.

Свойства

Методы

В данном классе возможно применение методов EventDispatcher.

Исходники

BufferAttribute →

      InstancedBufferAttribute

В отличие от слова «создание», применяется не к объекту, а к классу.
То есть, говорят: (в виртуальной среде) создать экземпляр класса
или, другими словами, инстанцировать класс.')" onmouseout="hide()">Инстанцированная версия BufferAttribute (то есть, это экземпляр класса BufferAttribute). An instanced version of BufferAttribute.

Конструктор

InstancedBufferAttribute( array, itemSize, meshPerAttribute )

Свойства

Смотрите наследуемые свойства в описании BufferAttribute.

Методы

Смотрите наследуемые методы в описании BufferAttribute.

Исходники

BufferGeometry →

      InstancedBufferGeometry

В отличие от слова «создание», применяется не к объекту, а к классу.
То есть, говорят: (в виртуальной среде) создать экземпляр класса
или, другими словами, инстанцировать класс.')" onmouseout="hide()">Инстанцированная версия BufferGeometry (то есть, это экземпляр класса BufferGeometry).

Конструктор

InstancedBufferGeometry( )

Свойства

Смотрите наследуемые свойства в описании BufferGeometry.

Методы

Смотрите наследуемые методы в описании BufferGeometry.

Исходники

InterleavedBuffer →

      InstancedInterleavedBuffer

Инстанцированная версия InterleavedBuffer.

Конструктор

InstancedInterleavedBuffer( array, itemSize, meshPerAttribute )

Свойства

Смотрите наследуемые свойства в описании InterleavedBuffer.

Методы

Смотрите наследуемые методы в описании InterleavedBuffer.

Исходники

      InterleavedBuffer

Слово "Interleaved" (т.е. "с чередованием") в названии означает, что несколько атрибутов (возможно разных типов, например, position - положение, normal - нормаль, uv - UV-координаты, color - цвет) упаковываются в один-единственный буфер массива.
Введение в массивы с чередованием можно найти здесь: Interleaved array basics (Основы массива с чередованием).

Пример

webgl / buffergeometry / points / interleaved

Конструктор

InterleavedBuffer( array, stride )

Свойства

Методы

Исходники

      InterleavedBufferAttribute

Конструктор

InterleavedBufferAttribute( interleavedBuffer, itemSize, offset, normalized )

Свойства

Методы

Исходники

      Layers

Объект Layers назначает для Object3D 1 или больше (до 32) слоев, пронумерованных от 0 до 31 - внутренне слои хранятся в виде битовой маски (вот эта статья на русском), и по умолчанию все объекты Object3D имеют принадлежность к слою 0.
Это можно использовать для управления видимостью - чтобы быть видимым, при визуализации представления этой камеры, объект должен иметь общий слой с камерой.
Все классы, которые наследуют от Object3D имеют свойство layers, являющееся экземпляром данного класса.

Конструктор

Layers()

Создает новый объект Layers, принадлежность которого установлена изначально на слой 0.

Свойства

Методы

Исходники

      Object3D

Object3D является базовым классом для большинства объектов three.js и предоставляет набор свойств и методов для управления объектами в трехмерном пространстве.
Обратите внимание, что имеется возможность для группировки объектов с помощью метода .add( object ), который добавляет объект в качестве дочернего, но все же для этого лучше использовать класс Group.

Конструктор

Object3D()

Конструктор не принимает аргументов.

Свойства

Статические свойства

Статические свойства и методы устанавливаются для всего класса, а не для экземпляра этого класса. Это означает, что при изменении Object3D.DefaultUp или Object3D.DefaultMatrixAutoUpdate изменятся значения свойств up и matrixAutoUpdate каждого экземпляра Object3D (или производных от него), созданных после внесения изменений (объекты Object3D, уже созданные к этому моменту, не будут затронуты).

Методы

В данном классе возможно применение методов EventDispatcher.

Исходники

      Raycaster

Данный класс предназначен для оказания помощи с raycasting. Вот описание рейкастинга в Википедии на русском языке. Рейкастинг используется для выборки курсором мышки (вычисляет какие из объектов в трехмерном пространстве накрывает курсор мышки) среди других объектов. This class is designed to assist with raycasting. Raycasting is used for mouse picking (working out what objects in the 3d space the mouse is over) amongst other things. Этот класс упрощает рейкастинг. Рейкастинг используется для выбора и многого другого. This class makes raycasting easier. Raycasting is used for picking and more.

Пример

var raycaster = new THREE.Raycaster();
var mouse = new THREE.Vector2();

function onMouseMove( event ) {

  // calculate mouse position in normalized device coordinates
  // (-1 to +1) for both components
  // вычисляем положение курсора мышки в нормализованной
  // системе координат (от -1 до +1) для обоих компонентов

  mouse.x = ( event.clientX / window.innerWidth ) * 2 - 1;
  mouse.y = - ( event.clientY / window.innerHeight ) * 2 + 1;

}

function render() {

  // update the picking ray with the camera and mouse position
  // обновляем луч выборки с позиций камеры и курсора мышки
  raycaster.setFromCamera( mouse, camera );

  // calculate objects intersecting the picking ray
  // вычисляем объекты, пересекающие луч выборки
  var intersects = raycaster.intersectObjects( scene.children );

  for ( var i = 0; i < intersects.length; i++ ) {

    intersects[ i ].object.material.color.set( 0xff0000 );

  }

  renderer.render( scene, camera );

}

window.addEventListener( 'mousemove', onMouseMove, false );

window.requestAnimationFrame(render);

Больше примеров:

Raycasting to a Mesh,
Raycasting to a Mesh in using an OrthographicCamera,
Raycasting to a Mesh with BufferGeometry,
Raycasting to a Line,
Raycasting to Points,
Terrain raycasting,
Raycasting using an octree,
Raycasting to paint voxels,
Raycast to a Texture

Конструктор

Raycaster( 
от англ. слова origin - начало, источник')" onmouseout="hide()">origin, 
от англ. слова direction - направление')" onmouseout="hide()">direction, near, far ) {

Данный метод создает новый объект raycaster.

Свойства

Методы

Исходники

      Uniform

Uniform'ы являются глобальными переменными GLSL. Они передаются в шейдерные программы.

Пример

При объявлении uniform из ShaderMaterial, он объявляется по значению или по объекту.

uniforms: {
	time: { value: 1.0 },
	resolution: new THREE.Uniform(new THREE.Vector2())
}

Типы Uniform

Каждый uniform должен иметь свойство value. Тип этого value должен соответствовать типу переменной uniform в коде GLSL, как указано для примитивных типов GLSL в таблице ниже. The type of the value must correspond to the type of the uniform variable in the GLSL code as specified for the primitive GLSL types in the table below. Поддерживаются также структуры и массивы uniform. Массивы примитивных типов GLSL должны либо указываться как массивы соответствующих объектов THREE, либо как двумерный массив, содержащий данные всех объектов. Uniform structures and arrays are also supported. GLSL arrays of primitive type must either be specified as an array of the corresponding THREE objects or as a flat array containing the data of all the objects. Другими словами; примитивы GLSL в массивах не должны быть представлены массивами. Это правило не применяется транзитивно. In other words; GLSL primitives in arrays must not be represented by arrays. This rule does not apply transitively. Массив из массивов vec2, каждый из которых длиной в пять векторов, должен быть массивом массивов либо из пяти объектов Vector2, либо из десяти чисел. An array of vec2 arrays, each with a length of five vectors, must be an array of arrays, of either five Vector2 objects or ten numbers.
Типы Uniform

Типы GLSL	Типы JavaScript
int	Number
float	Number
bool	т.е. либо true, либо false')" onmouseout="hide()">Boolean
bool	Number
vec2	двумерный вектор')" onmouseout="hide()">THREE.Vector2
vec2	Float32Array (*)
vec2	Array (*)
vec3	трехмерный вектор')" onmouseout="hide()">THREE.Vector3
vec3	color - цвет')" onmouseout="hide()">THREE.Color
vec3	Float32Array (*)
vec3	Array (*)
vec4	четырехмерный вектор')" onmouseout="hide()">THREE.Vector4
vec4	кватернион')" onmouseout="hide()">THREE.Quaternion
vec4	Float32Array (*)
vec4	Array (*)
mat2	Float32Array (*)
mat2	Array (*)
mat3	матрица 3×3')" onmouseout="hide()">THREE.Matrix3
mat3	Float32Array (*)
mat3	Array (*)
mat4	матрица 4×4')" onmouseout="hide()">THREE.Matrix4
mat4	Float32Array (*)
mat4	Array (*)
ivec2, bvec2	Float32Array (*)
ivec2, bvec2	Array (*)
ivec3, bvec3	Int32Array (*)
ivec3, bvec3	Array (*)
ivec4, bvec4	Int32Array (*)
ivec4, bvec4	Array (*)
sampler2D	THREE.Texture
samplerCube	THREE.CubeTexture

(*) Same for an (innermost) array (dimension) of the same GLSL type, содержащего компоненты всех векторов или матриц в массиве.

Конструктор

Uniform( value )

Свойства

Методы

Исходники