Help understanding nanovg blending ops

Development
1

So, I’m looking at nvgGlobalCompositeBlendFunc (and related) as possibly a way to get nicer results in #d One : PanelTone (right now it just overwrites a potentially transparent color).

I’m a little confused why it says " The parameters should be one of NVGblendFactor."

If it’s actually restricted one value from the enumeration, then why is the enumeration defined like a bitmask? Or is it really a bitmask and ops can be combined?

nanovg docs are pretty useless – it says to look at opengl docs, but doesn’t provide any links or more specific references beyond that. I see it says that it’s emulating HTML5 canvas, but it’s missing more than half the compositing ops documented for that. Some of these appear to be a combination of others, which suggests that you can emulate the other ops by building on the base ops, but I’m new to this stuff, so unclear how to go about it.

Any hints? I appreciate it.

2

I asked Gemini:

In NanoVG, NVGblendFactor is an enumeration of constants used to define custom blending arithmetic between a “source” pixel (what you are currently drawing) and a “destination” pixel (what is already on the screen).

It is used primarily as an argument to two functions:

  1. nvgGlobalCompositeBlendFunc(ctx, sfactor, dfactor)
  2. nvgGlobalCompositeBlendFuncSeparate(ctx, srcRGB, dstRGB, srcAlpha, dstAlpha)

1. The Blending Equation

When you set these factors, NanoVG (and the underlying OpenGL backend) calculates the final pixel color using this general formula:

$$Result = (Source \times sfactor) + (Destination \times dfactor)$$

The values in NVGblendFactor determine what sfactor and dfactor are.

2. Available Blend Factors

Based on the header file, the available constants and their mathematical meanings are:

Constant Value Description
NVG_ZERO 0 Multiplies the color by 0 (removes it).
NVG_ONE 1 Multiplies the color by 1 (full intensity).
NVG_SRC_COLOR C_{src} Multiplies by the source color.
NVG_ONE_MINUS_SRC_COLOR 1 - C_{src} Multiplies by the inverse of the source color.
NVG_DST_COLOR C_{dst} Multiplies by the destination color.
NVG_ONE_MINUS_DST_COLOR 1 - C_{dst} Multiplies by the inverse of the destination color.
NVG_SRC_ALPHA A_{src} Multiplies by the source alpha.
NVG_ONE_MINUS_SRC_ALPHA 1 - A_{src} Multiplies by the inverse source alpha.
NVG_DST_ALPHA A_{dst} Multiplies by the destination alpha.
NVG_ONE_MINUS_DST_ALPHA 1 - A_{dst} Multiplies by the inverse destination alpha.

3. Common Use Cases

Standard Alpha Blending (Transparency)

This is the default mode where new shapes sit “on top” of the background based on their alpha value.

// Result = (Src * 1) + (Dst * (1 - SrcAlpha))
nvgGlobalCompositeBlendFunc(ctx, NVG_ONE, NVG_ONE_MINUS_SRC_ALPHA);

Note: NanoVG uses premultiplied alpha by default, which is why the source factor is NVG_ONE rather than NVG_SRC_ALPHA.

Additive Blending

Used for effects like glows, fire, or light beams where colors brighten as they overlap.

// Result = (Src * 1) + (Dst * 1)
nvgGlobalCompositeBlendFunc(ctx, NVG_ONE, NVG_ONE);

Multiplicative Blending

Used for “tinting” or shadow effects where the destination is darkened by the source.

// Result = (Src * 0) + (Dst * SrcColor)
// Effectively: New = Dst * Src
nvgGlobalCompositeBlendFunc(ctx, NVG_ZERO, NVG_SRC_COLOR);

4. Separate Blending

If you need the RGB channels to blend differently than the Alpha channel, use nvgGlobalCompositeBlendFuncSeparate. This is often used for advanced compositing where you want to preserve the destination’s alpha transparency regardless of the colors being drawn.

Summary of Usage

  • Context: These settings are part of the NVGcontext state.
  • State Management: If you change the blend mode for a specific shape, use nvgSave(ctx) before and nvgRestore(ctx) after to ensure you don’t accidentally affect subsequent drawing calls.
  • Comparison: If you’ve used OpenGL, these map directly to glBlendFunc. If you’ve used HTML5 Canvas, these are the low-level building blocks for globalCompositeOperation.
1 Like