HDR video in Firefox for Windows tech retrospective – Mozilla Gfx Team Blog

Skip to content

Ashley Hale

Uncategorized

July 14, 2026

7 Minutes

HDR video is coming to Firefox for Windows users (and has been available for some time on macOS). This blog post explains how we developed the feature and gives a retrospective on the technical choices we made.

A primer on video playback for the web:

Video file demux and decode : A video stream generally consists of parallel image and audio streams, along with captions, HDR scene metadata, and the like. “Container” formats like MP4 or MKV specify how these streams are combined, or multiplexed, into a single byte stream for transmission. On receipt, Firefox needs to divide that byte stream back into the individual media streams; this is de-multiplexing or “demuxing”. Then Firefox must uncompress the data to get images, audio samples, and so on. Firefox’s media team provides the demuxers, and pulls in appropriate codecs to decode them. We prefer using hardware video decoders if they work reasonably well. Video decompression usually produces roughly a YUV 4:2:0 image in NV12 for SDR or P010 for HDR. (If you visit about:support in Firefox, and search for Codec Support Information (or one of the codec names like AV1 ), you can see a whole feature matrix of support details for which codecs are hardware and software on your system.)

Gecko displaylist building : Given a demultiplexed, uncompressed frame of video, Gecko displaylist building incorporates it into a video element in the displaylist being sent to WebRender. If the frame was decoded in hardware, it is generally represented by a texture in GPU memory. Or, if it was decoded in software, then it is represented by a memory mapping holding some raw pixel data in system memory shared with Firefox’s media decoder process.

WebRender : Given the video element in the displaylist, WebRender decides whether to promote it to a desktop compositor overlay, or whether it must instead be rendered using a pathway more like an ordinary HTML element. A compositor overlay is faster and uses less power; on Windows this uses DWM with the DirectComposition API, which manages a graph of visuals. But if complex CSS is involved (rounded corners, blur filters, or similar features), Firefox must use WebRender’s ordinary rendering pathway. Currently the latter is not HDR capable, so Firefox favors the desktop compositor overlay for animated elements such as video and canvas.

As we began designing Firefox’s HDR support, we had to lay out some assumptions and found many complications:

Initially, we had hoped that on a modern system, BT2100 HDR videos could be displayed on Windows by simply sending them to DirectComposition.

In theory, the Desktop Window Manager (DWM) honors the DXGISwapChain3::SetColorSpace1 method which should let us request either DXGI_COLOR_SPACE_YCBCR_STUDIO_G2084_LEFT_P2020 or DXGI_COLOR_SPACE_YCBCR_STUDIO_GHLG_LEFT_P2020. The former refers to SMPTE 2084, more commonly called PQ, the Perceptual Quantizer function and the latter is ARIB-STD-B67 also known as HLG, the Hybrid Log Gamma function, most commonly used on HDR TV broadcasts.

Unfortunately, this was a dead end. In testing with a mocked up compositor test app, calling SetColorSpace1 with this value seems to be ignored on P010 (at least in testing on AMD), so it incorrectly displays BT2100 PQ video as if it were BT709, which makes the video dull and muddy, since BT709 is a narrower gamut than BT2020, and the BT1886 transfer function used by BT709 is very different from PQ defined by BT2100. SetColorSpace1 may work on other vendors with P010, so it may be a valid optimization, but we were looking for a universal solution.

For the future, Windows 11 23H2 has added a new interface called IDCompositionTexture which may serve our purposes better; from what we have been told, it is universally supported for all formats and color spaces. We haven’t used it for video so far, but it’s an interesting future direction.

As noted above, HDR videos must use a desktop compositor overlay. HDR video uses the BT2100 PQ colorspace with an RGB10A2 format, while WebRender can only work with images in the sRGB colorspace (appropriate for standard-dynamic-range BT709 video).

Until HDR came along, Gecko and WebRender only used desktop compositor overlays as a power/performance optimization. With HDR, overlays become a necessity as the pixel format and color space differ from classic sRGB.

Fortunately, HDR videos tend to be shown without particularly fancy CSS rendering such as clip masks and rounded corners, which would require WebRender to perform further copies. Technically, DirectComposition does support all of those features, but Firefox doesn’t use that functionality much.

In the future, we expect to upgrade WebRender for HDR rendering, allowing us to deal with complex cases like clip masks or blur filters on video elements.

We considered whether we could use...