WebGLRenderer - Руководство по Вердж3Д - Софт Эйт Софт
Description: Узнайте как использовать WebGLRenderer в интерактивных 3Д-веб-приложениях сделанных на Вердж3Д

# 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

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

- Если checkShaderErrors равно true, определяет, проверяются ли программы шейдеров материалов на наличие ошибок в процессе компиляции и компоновки. Может быть полезно отключить эту проверку во время разработки для повышения производительности. Настоятельно рекомендуется включать эти проверки во время разработки. Если шейдер не компилируется и не связывается — он не будет работать и связанный с ним материал не будет рендериться. По умолчанию `true`.
- disableCompiledShaderCache — выключает кеширование шейдеров посредством добавления случайной константы в код шейдера. По умолчанию `false`.

### # .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 (т.е. можно использовать текстуры в вершинном шейдере).

### # .domElement : HTMLCanvasElement

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

`document.body.appendChild(renderer.domElement);`

### # .extensions : Object

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

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

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

- `ANGLE_instanced_arrays`
- `EXT_blend_minmax`
- `EXT_color_buffer_float`
- `EXT_color_buffer_half_float`
- `EXT_disjoint_timer_query_webgl`
- `EXT_disjoint_timer_query_webgl2`
- `EXT_sRGB`
- `EXT_texture_compression_bptc`
- `EXT_texture_filter_anisotropic`
- `KHR_parallel_shader_compile`
- `OES_element_index_uint`
- `OES_standard_derivatives`
- `OES_texture_float`
- `OES_texture_float_linear`
- `OES_texture_half_float`
- `OES_texture_half_float_linear`
- `OES_vertex_array_object`
- `WEBGL_compressed_texture_etc`
- `WEBGL_compressed_texture_etc1`
- `WEBGL_compressed_texture_pvrtc`
- `WEBGL_compressed_texture_s3tc_srgb`
- `WEBGL_compressed_texture_s3tc`
- `WEBGL_debug_renderer_info`
- `WEBGL_depth_texture`
- `WEBGL_draw_buffers`
- `WEBGL_lose_context`
- `WEBGL_multisampled_render_to_texture`

### # .outputEncoding : Integer

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

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

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

### # .info : Object

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

- memory:
  - geometries
  - textures
  - textureSpecs
- render:
  - frame
  - calls
  - triangles
  - points
  - lines
  - customCounter
- programs
- numShaderCompiles

### # .localClippingEnabled : Boolean

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

### # .properties : Object

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

### # .renderLists : WebGLRenderLists

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

### # .shadowMap : WebGLShadowMap

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

- enabled: если `true`, данная карта теней используется на сцене. По умолчанию `false`.
- autoUpdate: включает автоматическое обновление теней в сцене. По умолчанию `true`. Если вам не требуется динамическое освещение/тени, вы можете установить значение `false` при инстанцировании рендерера.
- needsUpdate: если установлено значение `true`, карты теней в сцене будут обновлены в следующем вызове отрисовки. По умолчанию `false`. Если вы отключили автоматическое обновление карт теней (`shadowMap.autoUpdate = false`), вам нужно установить значение `true` и затем выполнить вызов рендеринга для обновления теней в вашей сцене.
- type: определяет тип карты теней. Варианты:
  - v3d.BasicShadowMap
  - v3d.BilinearShadowMap
  - v3d.PCFShadowMap (по умолчанию)
  - v3d.ESMShadowMap
  Смотрите подробности в разделе константы рендерера.

### # .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)

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

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

### # .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) — левый нижний угол области.

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

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