Chevron Down
Table of Contents
Chevron DownGetting Started
Chevron DownAPI Reference

getParameters, getParamter, setParameters, setParameter

luma.gl simplifies the usage of WebGL parameters by providing a unified API for setting and getting values. Any GL parameter can be queried or set using getParameters and setParameters (no need to keep track of what underlying WebGL calls are required), and luma.gl also provide setting names that allow the normal WebGL setter functions (like gl.blendEquation or gl.clearColor) to be specified as keys in a setParameters call.

In addition, state queries are done towards cached values and are thus much faster than working directly with the WebGL API, where synchronous WebGL queries can be a performance bottleneck.

The following functions are provided:

  • getParameter - Returns the value(s) of a GL context parameter
  • getParameters - Returns the values of some or all GL context parameters
  • setParameters - Sets a the value(s) of the specified GL context parameters

Usage

Get a global parameter value using a WebGL GLenum

const value = getParameter(gl, gl.DEPTH_TEST);

Set a global parameter value using a WebGL GLenum

const value = setParameters(gl, {
  [gl.DEPTH_TEST]: true
});

Set a global parameter value using a luma.gl setting function name

const value = setParameters(gl, {
  depthTest: true
});

Get all gl parameter values (values will be an object map keyed with parameter names)

const values = getParameters(gl);

Methods

getParameter

Gets the value(s) of a single gl context parameter.

getParameter(gl, pname)
  • gl {WebGLRenderingContext} - context
  • pname {GLenum} - parameter name, a GL parameter constant Returns {*} - value(s) of this parameter

getParameters

Gets the values of a gl context parameter.

getParameters(gl, values)
  • gl {WebGLRenderingContext} - context
  • values= {Object | GLenum[] | null} - parameters, either as keys in object or elements of array. Defaults to all parameters. Returns {Object} - object with keys and values corresponding to supplied parameter names and the current values of those parameters.

setParameters

Sets a number of parameters.

setParameters(gl, {key: value, ...})
  • gl {WebGLRenderingContext} - context
  • key {String} - parameter names, (, either )luma.gl setting name or a GL parameter constants
  • value {} - parameter value Returns {} - "normalized" parameter value after assignment

Note:

  • If both luma.gl setting names and GL parameter constants representing the same value are submitted the results are undefined.
  • value may be "normalized" (in case a short form is supported). In that case the normalized value is returned.

Parameters

Describes luma.gl setting names and values

Blending

Function styleSets parameter(s)
blendColorGL.BLEND_COLOR
blendEquation[GL.BLEND_EQUATION_RGB, GL.BLEND_EQUATION_ALPHA]
blendFunc[GL.BLEND_SRC_RGB, GL.BLEND_SRC_ALPHA]
blendFuncSeparate[GL.BLEND_SRC_RGB, GL.BLEND_SRC_ALPHA, GL.BLEND_DST_RGB, GL.BLEND_DST_ALPHA]
ParameterTypeDefaultDescription
GL.BLENDGLbooleanfalseBlending enabled
GL.BLEND_COLORFloat32Array(4)[0, 0, 0, 0]
GL.BLEND_EQUATION_RGBGLenumGL.FUNC_ADD
GL.BLEND_EQUATION_ALPHAGLenumGL.FUNC_ADD
GL.BLEND_SRC_RGBGLenumGL.ONEsrcRgb
GL.BLEND_SRC_ALPHAGLenumGL.ZEROsrcAlpha
GL.BLEND_DST_RGBGLenumGL.ONEdstRgb
GL.BLEND_DST_ALPHAGLenumGL.ZEROdstAlpha

Clear Color

FunctionSets parameters
clearColorGL.COLORCLEARVALUE
ParameterTypeDefaultDescription
GL.COLOR_CLEAR_VALUEnew Float32Array(4)[0, 0, 0, 0].

Color Mask

FunctionSets parameters
colorMaskGL.COLOR_WRITEMASK
ParameterTypeDefaultDescription
GL.COLOR_WRITEMASK[GLboolean, GLboolean, GLboolean, GLboolean][true, true, true, true].

Depth Test

Function styleSets parameters
clearDepthGL.DEPTH_CLEAR_VALUE
depthFuncGL.DEPTH_FUNC
depthRangeGL.DEPTH_RANGE
depthMaskGL.DEPTH_WRITEMASK
ParameterTypeDefaultDescription
GL.DEPTH_TESTGLbooleanfalse
GL.DEPTH_CLEAR_VALUEGLfloattrue
GL.DEPTH_FUNCGLenumnull
GL.DEPTH_RANGEFloat32Array(2)[null, null] // TBD
GL.DEPTH_WRITEMASKGLbooleannull

Derivative Hints (WebGL2 or extension)

Requires WebGL2 or OES_standard_derivatives.

ParameterTypeDefaultDescription
GL.FRAGMENT_SHADER_DERIVATIVE_HINTGLenumGL.DONT_CAREAccuracy of derivates in built-in GLSL functions

Hints

ValueDescription
GL.FASTESTThe most efficient behavior should be used
GL.NICESTThe most correct or the highest quality option should be used
GL.DONT_CAREThere is no preference for this behavior

Dithering

ParameterTypeDefaultDescription
GL.DITHERGLbooleantrueEnable dithering of color components before they get written to the color buffer
  • Note: Dithering is driver dependent and typically has a stronger effect when the color components have a lower number of bits.

Face Culling

FunctionSets parameters
cullFaceGL.CULL_FACE_MODE
frontFaceGL.FRONT_FACE
ParameterTypeDefaultDescription
GL.CULL_FACEGLbooleanfalseEnable face culling
GL.CULL_FACE_MODEGLenumGL.BACKWhich face to cull
GL.FRONT_FACEGLenumGL.CCWWhich face is front

Cull Face Modes

ValueDescription
GL.FRONTClock wise
GL.BACKCounter clock wise
GL.FRONT_AND_BACKNo polygons are drawn (but LINES and POINTS are)

Face orientation

ValueDescription
GL.CWClock wise
GL.CCWCounter clock wise

MipmapHint

Hint for quality of images generated with glGenerateMipmap

ParameterTypeDefaultDescription
GL.GENERATE_MIPMAP_HINTGLenumGL.DONT_CARE.

Mipmap Hints

ValueDescription
GL.FASTESTThe most efficient behavior should be used
GL.NICESTThe most correct or the highest quality option should be used
GL.DONT_CAREThere is no preference for this behavior

LineWidth

Line widths are between 1 and GL.ALIASEDLINEWIDTH_RANGE.

FunctionSets parameters
lineWidthGL.LINE_WIDTH
ParameterTypeDefaultDescription
GL.LINE_WIDTHGLfloat1.

Example:

// Set viewport to maximum supported size
const lineWidthRange = getLimits(gl)[GL.ALIASED_LINE_WIDTH_RANGE];
setState(gl, {
  lineWidth: lineWidthRange[1]
});
  • Note: Line widths will be clamped to [1, GL.ALIASED_LINE_WIDTH_RANGE]. This is different from gl.lineWidth which generates errors on lineWidth 0.
  • Caution: line aliasing is driver dependent and GL.LINES may not give desired results.

PolygonOffset

Add small offset to fragment depth values (by factor × DZ + r × units) Useful for rendering hidden-line images, for applying decals to surfaces, and for rendering solids with highlighted edges.

FunctionSets parameters
polygonOffset[GL.POLYGONOFFSETFACTOR, GL.POLYGONOFFSETUNITS]
ParameterTypeDefaultDescription
GL.POLYGON_OFFSET_FILLGLbooleanfalse.
GL.POLYGON_OFFSET_FACTORGLfloat0.
GL.POLYGON_OFFSET_UNITSGLfloat0.
  • Note: The semantics of polygon offsets are loosely specified by the WebGL standard and results can thus be driver dependent.

Rasterization (WebGL2)

Primitives are discarded immediately before the rasterization stage, but after the optional transform feedback stage. gl.clear() commands are ignored.

ParameterTypeDefaultDescription
GL.RASTERIZER_DISCARDGLbooleanfalseDisable rasterization

Sampling

Specify multisample coverage parameters

FunctionSets parameters
sampleCoverage[GL.SAMPLE_COVERAGE_VALUE, GL.SAMPLE_COVERAGE_INVERT]
ParameterTypeDefaultDescription
GL_SAMPLE_COVERAGEGLbooleanfalseActivates the computation of a temporary coverage value determined by the alpha value.
GL_SAMPLE_ALPHA_TO_COVERAGEGLbooleanfalseActivates ANDing the fragment's coverage with the temporary coverage value
GL.SAMPLE_COVERAGE_VALUEGLfloat1.0
GL.SAMPLE_COVERAGE_INVERTGLbooleanfalse

Scissor Test

Settings for scissor test and scissor box.

FunctionSets parameters
scissorGL.SCISSOR_BOX
scissorTestGL.SCISSOR_TEST
ParameterTypeDefaultDescription
GL.SCISSOR_TESTGLbooleanfalse
GL.SCISSOR_BOXInt32Array(4)[null, null, null, null]), // TBD

Stencil Test

Setting any value will enable stencil testing (i.e. enable GL.STENCIL_TEST).

FunctionParameters Set
clearStencilGL.STENCIL_CLEAR_VALUE
stencilMask[GL.STENCIL_WRITEMASK]
stencilMaskSeparate[GL.STENCIL_WRITEMASK, GL.STENCIL_BACK_WRITEMASK]
stencilFunc[GL.STENCIL_FUNC, GL.STENCIL_REF, GL.STENCIL_VALUE_MASK]
stencilFuncSeparate[GL.STENCIL_FUNC, GL.STENCIL_REF, GL.STENCIL_VALUE_MASK, GL.STENCIL_BACK_FUNC, GL.STENCIL_BACK_REF, GL.STENCIL_BACK_VALUE_MASK ]
stencilOp[GL.STENCIL_FAIL, GL.STENCIL_FAIL_DEPTH_FAIL, GL.STENCIL_FAIL_DEPTH_PASS]
stencilOpSeparate[GL.STENCIL_FAIL, GL.STENCIL_FAIL_DEPTH_FAIL, GL.STENCIL_FAIL_DEPTH_PASS, GL.STENCIL_BACK_FAIL, GL.STENCIL_BACK_FAIL_DEPTH_FAIL, GL.STENCIL_BACK_FAIL_DEPTH_PASS]
ParameterTypeDefaultDescription
GL.STENCIL_TESTGLbooleanfalseEnables stencil testing
GL.STENCIL_CLEAR_VALUEGLint0Sets index used when stencil buffer is cleared.
GL.STENCIL_WRITEMASKGLuint0xFFFFFFFFSets bit mask enabling writing of individual bits in the stencil planes
GL.STENCIL_BACK_WRITEMASKGLuint0xFFFFFFFFSets bit mask enabling writing of individual bits in the stencil planes
GL.STENCIL_FUNCGLenumGL.ALWAYS
GL.STENCIL_REFGLint0
GL.STENCIL_VALUE_MASKGLuint0xFFFFFFFFSets bit mask
GL.STENCIL_BACK_FUNCGLenumGL.ALWAYS
GL.STENCIL_BACK_REFGLint0
GL.STENCIL_BACK_VALUE_MASKGLuint0xFFFFFFFFSets bit mask enabling writing of individual bits in the stencil planes
GL.STENCIL_FAILGLenumGL.KEEPstencil test fail action
GL.STENCIL_PASS_DEPTH_FAILGLenumGL.KEEPdepth test fail action
GL.STENCIL_PASS_DEPTH_PASSGLenumGL.KEEPdepth test pass action
GL.STENCIL_BACK_FAILGLenumGL.KEEPstencil test fail action, back
GL.STENCIL_BACK_PASS_DEPTH_FAILGLenumGL.KEEPdepth test fail action, back
GL.STENCIL_BACK_PASS_DEPTH_PASSGLenumGL.KEEPdepth test pass action, back

Stencil Test Functions

Values for GL.STENCIL_TEST

ValueDescription
GL.NEVERNever pass
GL.LESSPass if (ref & mask) < (stencil & mask)
GL.EQUALPass if (ref & mask) = (stencil & mask)
GL.LEQUALPass if (ref & mask) <= (stencil & mask)
GL.GREATERPass if (ref & mask) > (stencil & mask)
GL.NOTEQUALPass if (ref & mask) != (stencil & mask)
GL.GEQUALPass if (ref & mask) >= (stencil & mask)
GL.ALWAYSAlways pass

Stencil Operations

ValueDescription
GL.KEEPKeeps the current value
GL.ZEROSets the stencil buffer value to 0
GL.REPLACESets the stencil buffer value to the reference value as specified by stencilFunc
GL.INCRIncrements the current stencil buffer value. Clamps to the maximum representable unsigned value
GL.INCR_WRAPIncrements the current stencil buffer value. Wraps to zero when incrementing the maximum representable unsigned value
GL.DECRDecrements current stencil buffer value. Clamps to 0
GL.DECR_WRAPDecrements current stencil buffer value, wraps to maximum unsigned value when decrementing 0
GL.INVERTInverts the current stencil buffer value bitwise

Action when the stencil test fails, front and back.

  • stencil test fail action,
  • depth test fail action,
  • pass action

Viewport

Specifies the transformation from normalized device coordinates to window/framebuffer coordinates. The maximum supported value, is defined by the GL.MAX_VIEWPORT_DIMS limit.

FunctionParameters
viewportGL.VIEWPORT
ParameterTypeDefaultDescription
GL.VIEWPORTInt32Array(4)[...] TBDViewport

Example:

// Set viewport to maximum supported size
const maxViewport = getLimits(gl)[GL.MAX_VIEWPORT_DIMS];
setState(gl, {
  viewport: [0, 0, maxViewport[0], maxViewport[1]]
});

Pixel Pack/Unpack Modes

Specifies how bitmaps are written to and read from memory

ParameterTypeDefaultDescription
GL.PACK_ALIGNMENTGLint4Byte alignment of pixel row data in memory (1,2,4,8 bytes) when storing data
GL.UNPACK_ALIGNMENTGLint4Byte alignment of pixel row data in memory (1,2,4,8 bytes) when reading data
GL.UNPACK_FLIP_Y_WEBGLGLbooleanfalseFlip source data along its vertical axis
GL.UNPACK_PREMULTIPLY_ALPHA_WEBGLGLbooleanfalseMultiplies the alpha channel into the other color channels
GL.UNPACK_COLORSPACE_CONVERSION_WEBGLGLenumGL.BROWSER_DEFAULT_WEBGLUse default or no color space conversion.

Pixel Pack/Unpack Modes WebGL2

Specifies how bitmaps are written to and read from memory

ParameterTypeDefaultDescription
GL.PACK_ROW_LENGTHGLint0Number of pixels in a row
GL.PACK_SKIP_PIXELSGLint0Number of pixels skipped before the first pixel is written into memory
GL.PACK_SKIP_ROWSGLint0Number of rows of pixels skipped before first pixel is written to memory
GL.UNPACK_ROW_LENGTHGLint0Number of pixels in a row.
GL.UNPACK_IMAGE_HEIGHTGLint0Image height used for reading pixel data from memory
GL.UNPACK_SKIP_PIXELSGLint0Number of pixel images skipped before first pixel is read from memory
GL.UNPACK_SKIP_ROWSGLint0Number of rows of pixels skipped before first pixel is read from memory
GL.UNPACK_SKIP_IMAGESGLint0Number of pixel images skipped before first pixel is read from memory

Remarks

WebGL State Management can be quite complicated.

  • A large part of the WebGL API is devoted to parameters. When reading, querying individual values using GL constants is the norm, and when writing, special purpose functions are provided for most parameters. luma.gl supports both forms for both reading and writing parameters.
  • Reading values from WebGL can be very slow if it requires a GPU roundtrip. To get around this, luma.gl reads values once, caches them and tracks them as they are changed through luma functions. The cached values can get out of sync if the context is shared outside of luma.gl.
  • luma.gl's state management enables "conflict-free" programming, so that even when setting global state, one part of the code does not need to worry about whether other parts are changing the global state.
  • Note that to fully support the conflict-free model and detect changes done e.g. in other WebGL libraries, luma.gl needs to hook into the WebGL context to track state changes.