dom/canvas/WebGLTypes.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef WEBGLTYPES_H_
   7 #define WEBGLTYPES_H_
   8
   9 #include "mozilla/TypedEnum.h"
  10
  11 // Most WebIDL typedefs are identical to their OpenGL counterparts.
  12 #include "GLTypes.h"
  13
  14 // Manual reflection of WebIDL typedefs that are different from their
  15 // OpenGL counterparts.
  16 typedef int64_t WebGLsizeiptr;
  17 typedef int64_t WebGLintptr;
  18 typedef bool WebGLboolean;
  19
  20 namespace mozilla {
  21
  22 /*
  23  * WebGLContextFakeBlackStatus and WebGLTextureFakeBlackStatus are enums to
  24  * track what needs to use a dummy 1x1 black texture, which we refer to as a
  25  * 'fake black' texture.
  26  *
  27  * There are generally two things that can cause us to use such 'fake black'
  28  * textures:
  29  *
  30  *   (1) OpenGL ES rules on sampling incomplete textures specify that they
  31  *       must be sampled as RGBA(0, 0, 0, 1) (opaque black). We have to implement these rules
  32  *       ourselves, if only because we do not always run on OpenGL ES, and also
  33  *       because this is dangerously close to the kind of case where we don't
  34  *       want to trust the driver with corner cases of texture memory accesses.
  35  *
  36  *   (2) OpenGL has cases where a renderbuffer, or a texture image, can contain
  37  *       uninitialized image data. See below the comment about WebGLImageDataStatus.
  38  *       WebGL must never have access to uninitialized image data. The WebGL 1 spec,
  39  *       section 4.1 'Resource Restrictions', specifies that in any such case, the
  40  *       uninitialized image data must be exposed to WebGL as if it were filled
  41  *       with zero bytes, which means it's either opaque or transparent black
  42  *       depending on whether the image format has alpha.
  43  *
  44  * Why are there _two_ separate enums there, WebGLContextFakeBlackStatus
  45  * and WebGLTextureFakeBlackStatus? That's because each texture must know the precise
  46  * reason why it needs to be faked (incomplete texture vs. uninitialized image data),
  47  * whereas the WebGL context can only know whether _any_ faking is currently needed at all.
  48  */
  49 MOZ_BEGIN_ENUM_CLASS(WebGLContextFakeBlackStatus, uint8_t)
  50   Unknown,
  51   NotNeeded,
  52   Needed
  53 MOZ_END_ENUM_CLASS(WebGLContextFakeBlackStatus)
  54
  55 MOZ_BEGIN_ENUM_CLASS(WebGLTextureFakeBlackStatus, uint8_t)
  56   Unknown,
  57   NotNeeded,
  58   IncompleteTexture,
  59   UninitializedImageData
  60 MOZ_END_ENUM_CLASS(WebGLTextureFakeBlackStatus)
  61
  62 /*
  63  * Implementing WebGL (or OpenGL ES 2.0) on top of desktop OpenGL requires
  64  * emulating the vertex attrib 0 array when it's not enabled. Indeed,
  65  * OpenGL ES 2.0 allows drawing without vertex attrib 0 array enabled, but
  66  * desktop OpenGL does not allow that.
  67  */
  68 MOZ_BEGIN_ENUM_CLASS(WebGLVertexAttrib0Status, uint8_t)
  69     Default, // default status - no emulation needed
  70     EmulatedUninitializedArray, // need an artificial attrib 0 array, but contents may be left uninitialized
  71     EmulatedInitializedArray // need an artificial attrib 0 array, and contents must be initialized
  72 MOZ_END_ENUM_CLASS(WebGLVertexAttrib0Status)
  73
  74 /*
  75  * Enum to track the status of image data (renderbuffer or texture image) presence
  76  * and initialization.
  77  *
  78  * - NoImageData is the initial state before any image data is allocated.
  79  * - InitializedImageData is the state after image data is allocated and initialized.
  80  * - UninitializedImageData is an intermediate state where data is allocated but not
  81  *   initialized. It is the state that renderbuffers are in after a renderbufferStorage call,
  82  *   and it is the state that texture images are in after a texImage2D call with null data.
  83  */
  84 MOZ_BEGIN_ENUM_CLASS(WebGLImageDataStatus, uint8_t)
  85     NoImageData,
  86     UninitializedImageData,
  87     InitializedImageData
  88 MOZ_END_ENUM_CLASS(WebGLImageDataStatus)
  89
  90 /*
  91  * The formats that may participate, either as source or destination formats,
  92  * in WebGL texture conversions. This includes:
  93  *  - all the formats accepted by WebGL.texImage2D, e.g. RGBA4444
  94  *  - additional formats provided by extensions, e.g. RGB32F
  95  *  - additional source formats, depending on browser details, used when uploading
  96  *    textures from DOM elements. See gfxImageSurface::Format().
  97  */
  98 MOZ_BEGIN_ENUM_CLASS(WebGLTexelFormat, uint8_t)
  99     // returned by SurfaceFromElementResultToImageSurface to indicate absence of image data
 100     None,
 101     // common value for formats for which format conversions are not supported
 102     FormatNotSupportingAnyConversion,
 103     // dummy pseudo-format meaning "use the other format".
 104     // For example, if SrcFormat=Auto and DstFormat=RGB8, then the source
 105     // is implicitly treated as being RGB8 itself.
 106     Auto,
 107     // 1-channel formats
 108     R8,
 109     A8,
 110     R16F, // OES_texture_half_float
 111     A16F, // OES_texture_half_float
 112     R32F, // OES_texture_float
 113     A32F, // OES_texture_float
 114     // 2-channel formats
 115     RA8,
 116     RA16F, // OES_texture_half_float
 117     RA32F, // OES_texture_float
 118     // 3-channel formats
 119     RGB8,
 120     BGRX8, // used for DOM elements. Source format only.
 121     RGB565,
 122     RGB16F, // OES_texture_half_float
 123     RGB32F, // OES_texture_float
 124     // 4-channel formats
 125     RGBA8,
 126     BGRA8, // used for DOM elements
 127     RGBA5551,
 128     RGBA4444,
 129     RGBA16F, // OES_texture_half_float
 130     RGBA32F // OES_texture_float
 131 MOZ_END_ENUM_CLASS(WebGLTexelFormat)
 132
 133 MOZ_BEGIN_ENUM_CLASS(WebGLTexImageFunc, uint8_t)
 134     TexImage,
 135     TexSubImage,
 136     CopyTexImage,
 137     CopyTexSubImage,
 138     CompTexImage,
 139     CompTexSubImage,
 140 MOZ_END_ENUM_CLASS(WebGLTexImageFunc)
 141
 142 MOZ_BEGIN_ENUM_CLASS(WebGLTexDimensions, uint8_t)
 143     Tex2D,
 144     Tex3D
 145 MOZ_END_ENUM_CLASS(WebGLTexDimensions)
 146
 147 // Please keep extensions in alphabetic order.
 148 MOZ_BEGIN_ENUM_CLASS(WebGLExtensionID, uint8_t)
 149     ANGLE_instanced_arrays,
 150     EXT_blend_minmax,
 151     EXT_color_buffer_half_float,
 152     EXT_frag_depth,
 153     EXT_sRGB,
 154     EXT_shader_texture_lod,
 155     EXT_texture_filter_anisotropic,
 156     OES_element_index_uint,
 157     OES_standard_derivatives,
 158     OES_texture_float,
 159     OES_texture_float_linear,
 160     OES_texture_half_float,
 161     OES_texture_half_float_linear,
 162     OES_vertex_array_object,
 163     WEBGL_color_buffer_float,
 164     WEBGL_compressed_texture_atc,
 165     WEBGL_compressed_texture_etc1,
 166     WEBGL_compressed_texture_pvrtc,
 167     WEBGL_compressed_texture_s3tc,
 168     WEBGL_debug_renderer_info,
 169     WEBGL_debug_shaders,
 170     WEBGL_depth_texture,
 171     WEBGL_draw_buffers,
 172     WEBGL_lose_context,
 173     Max,
 174     Unknown
 175 MOZ_END_ENUM_CLASS(WebGLExtensionID)
 176
 177 } // namespace mozilla
 178
 179 #endif