WebGLRenderer

WebGL-рендерер отображает ваши сцены, используя технологию WebGL.

Конструктор

WebGLRenderer(parameters : Object)

parameters
Необязательный объект со свойствами, определяющими поведение рендерера. Конструктор также может не принимать никаких параметров. В случае, если какой-то параметр отсутствует, будет использоваться значение по умолчанию. Допустимые параметры:
canvas
Элемент canvas в который рендерер выводит результат. Соответствует приведенному ниже свойству domElement. Если не передать этот параметр, будет создан новый элемент canvas.
context
Может быть использован для присоединения рендерера к существующему контексту. По умолчанию null.
precision
Точность шейдера. Может быть "highp", "mediump" или "lowp". По умолчанию "highp", если данная точность поддерживается устройством.
alpha
Содержит ли холст альфа-канал (прозрачность) или нет. По умолчанию false.
premultipliedAlpha
Будет ли рендерер считать, что цвета имеют премультиплицированный альфа-канал. По умолчанию true.
antialias
Выполнять ли сглаживание. По умолчанию false.
stencil
Будет ли иметь буфер отрисовки буфер шаблона с точностью 8 бит. По умолчанию true.
preserveDrawingBuffer
Сохранять ли буферы до тех пор, пока они не будут очищены вручную или перезаписаны. По умолчанию false.
powerPreference
Предоставляет браузеру пользователя подсказку, указывающую, какая конфигурация GPU подходит для данного контекста WebGL. Может быть "high-performance", "low-power" или "default". По умолчанию "default". Смотрите подробности в спецификации WebGL.
failIfMajorPerformanceCaveat
Будет ли создание рендерера прервано при обнаружении низкой производительности. По умолчанию false. Смотрите подробности в спецификации WebGL.
depth
Будет ли иметь буфер отрисовки буфер глубины с точностью минимум 16 бит. По умолчанию true.
logarithmicDepthBuffer
Использовать логарифмический буфер глубины. Может потребоваться при работе с большими различиями в масштабе сцены. Обратите внимание, что эта настройка использует gl_FragDepth, который отключает оптимизацию Early Fragment Test и может привести к снижению производительности. По умолчанию false.

Свойства

.autoClear : Boolean

Определяет, должен ли рендерер автоматически очищать свой вывод перед рендерингом кадра.

.autoClearColor : Boolean

Если autoClear равно true, определяет, должен ли рендерер очищать буфер цвета. По умолчанию true.

.autoClearDepth : Boolean

Если autoClear равно true, определяет, должен ли рендерер очищать буфер глубины. По умолчанию true.

.autoClearStencil : Boolean

Если autoClear равно true, определяет, должен ли рендерер очищать буфер стенсила. По умолчанию true.

.debug.checkShaderErrors : Boolean

Объект с параметрами отладки:

.capabilities : Object

Объект, содержащий подробную информацию о возможностях текущего RenderingContext.

floatFragmentTextures
Поддерживает ли контекст расширение OES_texture_float.
floatVertexTextures
true если floatFragmentTextures и vertexTextures оба true.
getMaxAnisotropy()
Возвращает максимальную доступную анизотропию.
getMaxPrecision()
Возвращает максимальную доступную точность для вершинных и фрагментных шейдеров.
isWebGL2
true если используемый контекст является объектом WebGL2RenderingContext.
logarithmicDepthBuffer
true если logarithmicDepthBuffer было установлено true в конструкторе и контекст поддерживает расширениеEXT_frag_depth.
maxAttributes
Значение gl.MAX_VERTEX_ATTRIBS.
maxCubemapSize
Значение gl.MAX_CUBE_MAP_TEXTURE_SIZE. Максимальная высота × ширина текстур карты куба, которые может использовать шейдер.
maxFragmentUniforms
Значение gl.MAX_FRAGMENT_UNIFORM_VECTORS. Количество юниформов, которые может использовать фрагментный шейдер.
maxSamples
Значение gl.MAX_SAMPLES. Максимальное количество семплов, используемых для мультисемплинга (MSAA).
maxTextureSize
Значение gl.MAX_TEXTURE_SIZE. Максимальная высота × ширина текстуры, которую использует шейдер.
maxTextures
Значение gl.MAX_TEXTURE_IMAGE_UNITS. Максимальное количество текстур, которое может быть использовано шейдером.
maxVaryings
Значение gl.MAX_VARYING_VECTORS. Количество изменяющихся векторов, которые могут использоваться шейдерами.
maxVertexTextures
Значение gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS. Количество текстур, которые могут быть использованы в вершинном шейдере.
maxVertexUniforms
Значение gl.MAX_VERTEX_UNIFORM_VECTORS. Максимальное количество юниформов, которое может быть использовано в вершинном шейдере.
precision
Точность шейдеров, используемая рендером.
vertexTextures
true если .maxVertexTextures : Integerбольше чем 0 (т.е. можно использовать вершинные текстуры).

.clippingPlanes : Array

Определяемые пользователем плоскости сечения, заданные как объекты v3d.Plane в мировом пространстве. Эти плоскости применяются глобально.Точки в пространстве, чье скалярное произведение с плоскостью отрицательно, отсекаются. По умолчанию [].

.domElement : DOMElement

canvas где рендерер рисует свой вывод.
Он автоматически создается рендерером в конструкторе (если он еще не создан); вам просто нужно добавить его на вашу страницу, как показано ниже:

document.body.appendChild(renderer.domElement);

.extensions : Object

Обертка для метода .extensions.get, используемого для проверки поддержки различных расширений WebGL.

.gammaFactor : Float

По умолчанию 2.

.outputEncoding : number

Определяет выходную кодировку рендерера. По умолчанию v3d.LinearEncoding.

Если цель рендеринга была установлена с помощью .setRenderTarget, то вместо нее будет использоваться renderTarget.texture.encoding.

Подробности о других форматах смотрите на странице texture constants.

.info : Object

Объект, содержащий ряд статистических сведений о памяти графической карты и процессе рендеринга. Полезен для отладки или просто как дополнительная информация. Объект содержит следующие поля:

.localClippingEnabled : Boolean

Определяет, соблюдает ли рендерер плоскости обтравки на уровне объекта. По умолчанию false.

.maxMorphTargets : Integer

По умолчанию 12. Максимальное количество целей MorphTargets, допустимое в шейдере. Следует помнить, что стандартные материалы допускают только 12 целей MorphTargets.

.maxMorphNormals : Integer

По умолчанию - 6. Максимальное количество MorphNormals, допустимое в шейдере. Следует помнить, что стандартные материалы допускают только 6 MorphNormals.

.physicallyCorrectLights : Boolean

Использовать ли режим физически корректного освещения. По умолчанию false.

.properties : Object

Используется внутри рендерера для отслеживания различных свойств саб-объектов.

.renderLists : WebGLRenderLists

Используется внутренне для обработки упорядочивания рендеринга объектов сцены.

.shadowMap : WebGLShadowMap

Содержит ссылку на карту теней, если она используется.

.shadowMap.enabled : Boolean

Если задано, используйте карты теней в сцене. По умолчанию false.

.shadowMap.autoUpdate : Boolean

Включает автоматическое обновление теней в сцене. По умолчанию true.

Если вам не требуется динамическое освещение/тени, вы можете установить значение false при инстанцировании рендерера.

.shadowMap.needsUpdate : Boolean

Если установлено значение true, карты теней в сцене будут обновлены в следующем вызове render. По умолчанию false.

Если вы отключили автоматическое обновление карт теней (shadowMap.autoUpdate = false), вам нужно установить значение true и затем выполнить вызов рендеринга для обновления теней в вашей сцене.

.shadowMap.type : Integer

Определяет тип карты теней (нефильтрованная, фильтрация с процентным приближением, фильтрация с процентным приближением с билинейной фильтрацией в шейдере, экспоненциальное отображение теней с гауссовым размытием).

Варианты: v3d.BasicShadowMap, v3d.PCFShadowMap (по умолчанию), v3d.PCFSoftShadowMap, v3d.ESMShadowMap, v3d.PCFShadowMapPoissonDisk. Подробности смотрите в Renderer constants.

.sortObjects : Boolean

Определяет, должен ли рендерер сортировать объекты. По умолчанию true.

Примечание: Сортировка используется для того, чтобы попытаться правильно отобразить объекты, имеющие некоторую степень прозрачности. По определению, сортировка объектов может работать не во всех случаях. В зависимости от потребностей приложения, может потребоваться отключить сортировку и использовать другие методы для работы с рендерингом прозрачности, например, вручную определять порядок рендеринга каждого объекта.

.state : Object

Содержит функции для установки различных свойств состояния WebGLRenderer.context.

.toneMapping : Constant

По умолчанию NoToneMapping. Другие варианты смотрите в Renderer constants.

.toneMappingExposure : Number

Уровень экспозиции тонального маппинга. По умолчанию 1.

.xr : WebXRManager

Предоставляет доступ к связанному с WebXR interface рендереру.

Методы

.clear(color : Boolean, depth : Boolean, stencil : Boolean) → null

Дает команду рендереру очистить буфер(ы) цвета, глубины или трафаретного рисунка. Этот метод инициализирует буфер цвета текущим значением clear color.
Аргументы по умолчанию имеют значение true.

.clearColor() → null

Очистить цветовой буфер. Эквивалентно вызову .clear(true, false, false).

.clearDepth() → null

Очистить буфер глубины. Эквивалентно вызову .clear(false, true, false).

.clearStencil() → null

Очистить буферы стенсилов. Эквивалентно вызову .clear(false, false, true).

.compile(scene : Object3D, camera : Camera) → null

Компилирует все материалы в сцене с камерой. Это полезно для предварительной компиляции шейдеров перед первым рендерингом.

.compileAsync(scene : Scene, camera : Camera, progressCb : Function) → null

Асинхронно компилирует все материалы в сцене с камерой. Это полезно для предварительной компиляции шейдеров перед первым рендерингом. Дополнительная функция progressCb получает параметр percentage.

.copyFramebufferToTexture(position : Vector2, texture : Texture, level : Number) → null

Копирует пиксели из текущего WebGLFramebuffer в 2D текстуру. Позволяет получить доступ к WebGLRenderingContext.copyTexImage2D.

.copyTextureToTexture(position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Number) → null

Копирует все пиксели текстуры в существующую текстуру, начиная с заданной позиции. Позволяет получить доступ к WebGLRenderingContext.texSubImage2D.

.dispose() → null

Удаление текущего контекста рендеринга.

.extensions.get(extensionName : String) → Object

Используется для проверки поддержки различных расширений и возвращает объект с подробной информацией о расширении, если оно доступно. Этот метод может проверить наличие следующих расширений:

- WEBGL_depth_texture
- EXT_texture_filter_anisotropic
- WEBGL_compressed_texture_s3tc
- WEBGL_compressed_texture_pvrtc
- WEBGL_compressed_texture_etc1

.forceContextLoss() → null

Имитация потери контекста WebGL. Для этого требуется поддержка расширения WEBGL_lose_context. Согласно WebGLStats, по состоянию на февраль 2016 года 90% устройств с поддержкой WebGL поддерживают его.

.getClearAlpha() → Float

Возвращает float с текущей чистой альфой. Диапазон от 0 до 1.

.getClearColor(target : Color) → Color

Возвращает экземпляр v3d.Color с текущим цветом прозрачности.

.getContext() → WebGLRenderingContext

Возвращает текущий контекст WebGL.

.getContextAttributes() → WebGLContextAttributes

Возвращает объект, описывающий атрибуты, установленные для контекста WebGL при его создании.

.getActiveCubeFace() → Integer

Возвращает текущую активную грань куба.

.getActiveMipmapLevel() → Integer

Возвращает текущий активный уровень mipmap.

.getRenderTarget() → RenderTarget

Возвращает текущую RenderTarget, если она есть; в противном случае возвращает null.

.getCurrentViewport(target : Vector4) → Vector4

target — результат будет скопирован в этот Vector4.

Возвращает текущий видовой экран.

.getDrawingBufferSize(target : Vector2) → Vector2

target — результат будет скопирован в этот Vector2.

Возвращает ширину и высоту буфера отрисовки рендерера, в пикселях.

.getPixelRatio() → number

Возвращает текущее используемое соотношение пикселей устройства.

.getScissor(target : Vector4) → Vector4

target — результат будет скопирован в этот Vector4.

Возвращает область ножниц.

.getScissorTest() → Boolean

Возвращает true, если тест ножниц включен; возвращает false в противном случае.

.getSize(target : Vector2) → Vector2

target — результат будет скопирован в этот Vector2.

Возвращает ширину и высоту выходного холста рендерера, в пикселях.

.getViewport(target : Vector4) → Vector4

target — результат будет скопирован в этот Vector4.

Возвращает область просмотра.

.initTexture(texture : Texture) → null

Инициализирует заданную текстуру. Полезно для предварительной загрузки текстуры вместо ожидания первого рендера (который может вызвать заметные задержки из-за накладных расходов на декодирование и загрузку GPU).

.resetGLState() → null

Сброс состояния GL на значение по умолчанию. Вызывается внутренне, если контекст WebGL потерян.

.readRenderTargetPixels(renderTarget : WebGLRenderTarget, x : Float, y : Float, width : Float, height : Float, buffer : TypedArray, activeCubeFaceIndex : Integer) → null

buffer - Uint8Array - единственный тип назначения, поддерживаемый во всех случаях, другие типы зависят от renderTarget и платформы. Подробности смотрите в WebGL spec.

Считывает пиксельные данные из renderTarget в переданный вам буфер. Это обертка вокруг WebGLRenderingContext.readPixels().

Для считывания WebGLCubeRenderTarget используйте необязательный параметр activeCubeFaceIndex, чтобы определить, какая грань должна быть считана.

.render(scene : Object3D, camera : Camera) → null

Рендеринг scene или другого типа object с помощью camera.
Рендеринг выполняется на ранее указанную renderTarget, установленную вызовом .setRenderTarget или на холст, как обычно.
По умолчанию буферы рендеринга очищаются перед рендерингом, но вы можете предотвратить это, установив свойство autoClear в false. Если вы хотите предотвратить очистку только определенных буферов, вы можете установить для свойств autoClearColor, autoClearStencil или autoClearDepth значение false. Чтобы принудительно очистить один или несколько буферов, вызовите .clear.

.renderBufferDirect(camera : Camera, fog : Fog, geometry : Geometry, material : Material, object : Object3D, group : Object) → null

Рендеринг группы геометрии буфера с использованием камеры и с указанным материалом.

.renderBufferImmediate(object : Object3D, program : WebGLProgram) → null

object - экземпляр Object3D
program - экземпляр WebGLProgram
Рендерит экземпляр ImmediateRenderObject. Вызывается функцией renderObjectImmediate().

.resetState() → null

Может использоваться для сброса внутреннего состояния WebGL. Этот метод наиболее актуален для приложений, которые используют один контекст WebGL в нескольких библиотеках WebGL.

.setAnimationLoop(callback : Function) → null

callback — Функция будет вызываться каждый доступный кадр. Если передано null, это остановит любую уже идущую анимацию.

Встроенная функция, которая может быть использована вместо requestAnimationFrame. Для проектов WebXR необходимо использовать эту функцию.

.setClearAlpha(alpha : Float) → null

Устанавливает прозрачную альфу. В качестве входного значения может быть использовано число в диапазоне от 0.0 до 1.0.

.setClearColor(color : Color, alpha : Float) → null

Устанавливает прозрачный цвет и непрозрачность.

.setFramebuffer(value : WebGLFramebuffer) → null

Устанавливает заданный WebGLFramebuffer. Этот метод можно использовать, только если цель рендеринга не установлена через .setRenderTarget().

.setPixelRatio(value : number) → null

Устанавливает соотношение пикселей устройства. Обычно используется для устройств с высоким разрешением, чтобы предотвратить смазывание холста при выводе.

.setRenderTarget(renderTarget : WebGLRenderTarget, activeCubeFace : Integer, activeMipmapLevel : Integer) → null

renderTarget — renderTarget, который должен быть активирован. Если задано значение null, то вместо него в качестве активной цели рендеринга устанавливается холст.
activeCubeFace — Указывает активную сторону куба (PX 0, NX 1, PY 2, NY 3, PZ 4, NZ 5) WebGLCubeRenderTarget (необязательно).
activeMipmapLevel — Указывает активный уровень mipmap (необязательно).

Этот метод устанавливает активный объект рендеринга.

.setScissor(x : Integer, y : Integer, width : Integer, height : Integer) → null
.setScissor(vector : Vector4) → null

Параметры x, y, ширины и высоты области ножниц.
Опционально, 4-компонентный вектор, определяющий параметры региона.

Устанавливает область ножниц от (x, y) до (x + ширина, y + высота).
(x, y) - левый нижний угол области ножниц.

.setScissorTest(boolean : Boolean) → null

Включите или отключите проверку ножниц. Если этот параметр включен, только пиксели в пределах определенной области будут затронуты дальнейшими действиями рендеринга.

.setOpaqueSort(method : Function) → null

Устанавливает пользовательскую функцию непрозрачной сортировки для WebGLRenderLists. Передайте null, чтобы использовать функцию по умолчанию painterSortStable.

.setTransparentSort(method : Function) → null

Устанавливает пользовательскую прозрачную функцию сортировки для WebGLRenderLists. Передайте null, чтобы использовать функцию по умолчанию reversePainterSortStable.

.setSize(width : Integer, height : Integer, updateStyle : Boolean) → null

Изменяет размер выводимого холста до (ширина, высота) с учетом соотношения пикселей устройства, а также устанавливает область просмотра в соответствии с этим размером, начиная с (0, 0). Установка updateStyle в false предотвращает любые изменения стиля выводимого холста.

.setViewport(x : Integer, y : Integer, width : Integer, height : Integer) → null
.setViewport(vector : Vector4) → null

Параметры x, y, ширины и высоты области просмотра.
Опционально, 4-компонентный вектор, задающий параметры видового экрана.

Устанавливает область просмотра для рендеринга из (x, y) в (x + ширина, y + высота).
(x, y) - левый нижний угол области.

Исходный файл

О том как получить исходный код этого модуля читайте тут.