WebGLRenderer

WebGLRenderer отображает сцены с помощью технологии WebGL.

Конструктор

WebGLRenderer(parameters : Object)

parameters
Необязательный объект со свойствами, определяющими поведение рендерера. Конструктор также может не принимать никаких параметров. В случае, если какой-то параметр отсутствует, будет использоваться значение по умолчанию. Допустимые параметры:
canvas
Элемент canvas в который рендерер выводит результат. Соответствует приведенному ниже свойству domElement. Если не передать этот параметр, будет создан новый элемент canvas.
context
Может быть использован для присоединения рендерера к существующему контексту. По умолчанию null.
precision
Точность шейдера. Может быть "highp", "mediump" или "lowp". По умолчанию "highp", если данная точность поддерживается устройством.
alpha
Контролирует, какое значение будет содержаться в альфа-канале цвета очистки холста. Если true значение будет равно 0, иначе 1. По умолчанию 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 : Object

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

.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

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

.domElement : DOMElement

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

document.body.appendChild(renderer.domElement);

.extensions : Object

get(extensionName : String): Проверяет, поддерживается ли расширение extensionName и возвращает объект с параметрами этого расширения, в случае если оно поддерживается.

has(extensionName : String): Проверяет, поддерживается ли расширение extensionName.

Эти методы поддерживают следующие расширения:

.outputEncoding : Integer

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

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

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

.info : Object

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

.localClippingEnabled : Boolean

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

.properties : Object

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

.renderLists : WebGLRenderLists

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

.shadowMap : WebGLShadowMap

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

.sortObjects : Boolean

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

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

.state : Object

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

.toneMapping : Constant

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

.toneMappingExposure : Float

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

.xr : WebXRManager

Предоставляет доступ к WebXR-интерфейсу рендерера.

Методы

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

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

Все аргументы принимают по умолчанию значение true.

.clearColor()

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

.clearDepth()

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

.clearStencil()

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

.compile(scene : Object3D, camera : Camera)

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

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

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

.copyFramebufferToTexture(position : Vector2, texture : Texture, level : Integer)

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

.copyTextureToTexture(position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Integer)

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

.copyTextureToTexture3D(sourceBox : Box3, position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Integer)

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

.dispose()

Освобождает все связанные с GPU ресурсы, используемые экземпляром рендерера. Этот метод следует вызвать, если экзепляр рендерера больше не используется в приложении.

.forceContextLoss()

Имитирует потерю WebGL-контекста. Для этого требуется поддержка расширения WEBGL_lose_context.

.forceContextRestore()

Имитирует восстановление WebGL-контекста. Для этого требуется поддержка расширения WEBGL_lose_context.

.getClearAlpha() → Float

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

.getClearColor(target : Color) → Color

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

.getContext() → WebGLRenderingContext

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

.getContextAttributes() → WebGLContextAttributes

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

.getActiveCubeFace() → Integer

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

.getActiveMipmapLevel() → Integer

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

.getRenderTarget() → RenderTarget

Возвращает текущий рендер таргет, если он есть. В противном случае возвращает null.

.getCurrentViewport(target : Vector4) → Vector4

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

Возвращает текущий вьюпорт.

.getDrawingBufferSize(target : Vector2) → Vector2

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

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

.getPixelRatio() → Float

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

.getScissor(target : Vector4) → Vector4

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

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

.getScissorTest() → Boolean

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

.getSize(target : Vector2) → Vector2

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

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

.getViewport(target : Vector4) → Vector4

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

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

.initTexture(texture : Texture)

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

.resetGLState()

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

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

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

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

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

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

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

Считывает пиксельные данные из renderTarget в переданный вам буфер. Это асинхронная версия метода .readRenderTargetPixels с увеличенной производительностью.

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

.render(scene : Object3D, camera : Camera)

Рендерит сцену или другой объект с помощью камеры.

Рендеринг выполняется на ранее указанную renderTarget, установленную вызовом .setRenderTarget или на холст, как обычно.

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

.resetState()

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

.setAnimationLoop(callback : Function)

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

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

.setClearAlpha(alpha : Float)

Устанавливает значение альфа-канала цвета очистки. Допустимый диапазон параметра от 0.0 до 1.0.

.setClearColor(color : Color, alpha : Float)

Устанавливает цвет (и альфа-канал) очистки.

.setPixelRatio(value : number)

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

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

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

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

Задаёт параметры x, y, width, height области ножниц. Опционально можно подать 4-компонентный вектор, задающий те же параметры.

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

.setScissorTest(boolean : Boolean)

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

.setOpaqueSort(method : Function)

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

.setTransparentSort(method : Function)

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

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

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

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

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

Устанавливает область вьюпорта от (x, y) до (x + width, y + height), где (x, y) — левый нижний угол области.

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

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