# Graphic configuration

Color and alpha blending, depth, stencil and culling are controlled by the
`GraphicConfig` node.

`nope.gl` is aligned with the traditional blending mode concepts from graphics
APIs. For example, color and alpha blending involves source and destination
factors for color channels or alpha, and a blending operation (addition,
subtraction, etc). This document will assume you are familiar with these
concepts.

For color and alpha blending, you will be particularly interested in the
`GraphicConfig.blend*` parameters. Similarly, depth and stencil configuration
can be respectively found in `GraphicConfig` parameters prefixed by `depth` and
`stencil`.


## Defaults

By default, `nope.gl` aligns its defaults with the sane ones from OpenGL:

- Blending: *disabled*
- Blending source factor: `1`
- Blending destination factor: `0`
- Blending source factor alpha: `1`
- Blending destination factor alpha: `0`
- Blending operation: *addition*
- Blending operation alpha: *addition*
- Color write mask: *red*, *green*, *blue*, *alpha*
- Depth test: *disabled*
- Depth write mask: `1`
- Depth Function: *less than*
- Stencil test: *disabled*
- Stencil write mask: `0xff`
- Stencil function: *always*
- Stencil reference: `0`
- Stencil read mask: `0xff`
- Stencil fail: *keep*
- Stencil depth fail: *keep*
- Stencil depth pass: *keep*
- Cull mode: *none*


## Inheritance

In a graph, a `GraphicConfig` will inherit the parameters from its parent(s),
or from the previously mentioned defaults if it has none. Every parameter that
is **not set** (or set to `None`/`NULL`) will be **inherited from its
ancestor(s)**.

Sibling branches do not share graphic state except from their common ancestor:
the parenthood is not expressed by the tree visiting sequence at draw time but
by the graph structure itself. Said differently, when the drawing cursor goes
out of a branch (because it has been drawn), it will reset the graphic state to
what it was before entering that branch, and then move into the sibling branch.

While sibling branches do not share the graphic state, it is important to keep
in mind that they do share the same color buffer: the current blending
*destination* represents what was drawn by previous sibling branches, or the
initial frame buffer color if nothing was rendered yet.


## Future directions / improvements

### Grouping settings

While the inheritance mechanism makes sense for categories of settings, it is a
source of confusion within a given scope. For example, while it makes sense to
inherit from the stencil and depth parameters when changing the color blending
(because they are conceptually independent from each other), it doesn't make
much sense to inherit from the alpha blending factors from the ancestors when
setting the color blending factors.

Some solutions involve splitting `GraphicConfig` into several nodes, or have an
internal mechanism such as "if at least one setting of a given group is set,
reset to the defaults the unset settings of that group".


### Undesired inheritance

Even if explicitly set to `None`/`NULL`, the parameters will **not** be reset
to their default values but still inherited from the parent(s). There are
multiple ways we could address this issue:

1. implementing the settings grouping mechanism (as mentioned in the previous
   section), which workarounds the issue by removing the need for a reset
2. adding specific `reset` constants to `GraphicConfig` parameters
3. introducing a dedicated node with the reset-to-defaults purpose

### Blocking down inheritance automatically

In some circumstances, it may be relevant to automatically reset the graphic
state in a sub-tree. The main contender here would be the `RenderToTexture`
node.